Definition von Suchabfragen

Suchabfragen werden in Sciformation ELN durch Name-Wert-Paare beschrieben, wie sie in HTTP-Requests oder auch in Maps beschrieben werden können. Die HTTP-Requests können wahlweise durch ein HTML-Formular oder direkt als URL-Aufruf an das Servlet performSearch ausgelöst werden.

Pflichtparameter ist der Name der Entity-Klasse, die als Parameter table angeben wird, z.B. CdbContainer.

Werden keine weiteren Parameter angegeben, so werden alle für den aktiven Nutzer sichtbaren Datensätze ausgegeben, sofern diese nicht als deaktiviert (disabled) markiert sind. Um (auch) die deaktivierten Einträge zu erhalten, muß der Parameter disabled_filter entweder auf DISABLED_ONLY = 1 (nur deaktivierte Datensätze) oder DISABLED_ANY = 2 (alles) gesetzt werden. Möchte man nur Einträge erhalten, die der Nutzer durch Häkchen selektiert hat, dann kann man selected_only auf 1 oder true setzen.

Die Filterkriterien werden durch positive Ganzzahlen indiziert, der Parameter query beschreibt deren Verknüpfung in einem Boole'schen Ausdruck, z.B. "[0] AND ([1] OR [2]) AND NOT [4]". Fehlende runde Klammern werden am Rand angefügt, um nach Möglichkeit einen gültigen Ausdruck zu erhalten. Ein Filterkriterium # besteht mindestens aus dem Feldnamen (im Java-Objekt) crit# und einem Vergleichswert val#, z.B. sucht

nach allen Benutzern, deren Vorname "Felix" enthält. Ungültige Kriterien (z.B. auf nicht existierende Felder) werden verworfen und aus query entfernt, wobei die verbleibenden Suchkriterien möglichst wenig beeinflußt werden. Man kann auch mit crit# auf Felder verweisen, die erst über JOINs erreichbar sind (z.B. cdbMolecule.casNr oder cdbMoleculeNamesCollection.name). In diesem Fall werden automatisch möglichst kurze Ketten von Tabellenverknüpfungen erzeugt und für spätere Nutzung zwischengespeichert. Zeichenketten werden für die SQL-Abfrage automatisch mit Anführungszeichen maskiert, numerische Werte auf den Zahlencharakter geprüft. Kriterien mit leeren Werten werden ignoriert, sofern nicht der Parameter allowempty auf 1 oder true gesetzt ist oder der Operator keinen Wert benötigt (z.B. OP_IS_NULL oder OP_IS_TRUE).

Für eine genauere Kontrolle über die Suchergebnisse kann man noch einen der nachfolgend aufgeführten Operatoren als op# angeben:

Paßt der angegebene Operator nicht zum Datentyp des Felds, so wird der jew. Standardoperator (jeweils fett gedruckt) für den betr. Datentyp verwendet.

Verknüpfung mit anderen (vorherigen) Ergebnislisten

Eine Suchanfrage (B) kann durch Angabe des Parameters list_op mit Ergebnislisten früherer Suchanfragen (A) verknüpft werden:

Auf die gewünschte Ergebnisliste wird verwiesen, indem der Parameter ref_cache_id deren cache_id angibt.

Sortierung (durch Datenbank) und Limit

Um eine Sortierung der Suchergebnisse durch die Datenbank zu veranlassen, kann der Parameter orderBy angegeben werden. Dabei sind SQL-Spaltennamen getrennte durch Kommata anzugeben, also nicht Java-Feldnamen. Die Angabe von DESC kehrt die Sortierreihenfolge für das betreffende Feld um. Ist keine Sortierreihenfolge angegeben, so versucht das System, Treffer mit besserer Übereinstimmung mit den Suchbegriffen nach vorne zu sortieren. Dieses Verhalten kann deaktiviert werden, indem man den Parameter qualityConditionsMode auf 1 setzt, während der Wert 2 die Ordnung nach Qualität gegenüber anderen Ordnungskriterien bevorzugt.

Durch Angabe von limit kann die maximale Anzahl Suchergebnisse beschränkt werden, z.B. zur Leistungssteigerung. Mit dem Parameter skip=n können bei Zugriffen über die Abfrage-API die ersten n Ergebnisse übersprungen werden, sofern benötigt.

Unterabfragen

Um beispielsweise alle Experimente (Tabelle ElnReaction) zu suchen, bei denen die Eigenschaft (Tabelle ElnReactionProperty) "temperature" zwischen 40-60 liegt, ist eine Unterabfrage erforderlich. Diese ermittelt zunächst alle Eigenschaftseinträge, die den geforderten Teilbedingungen genügen und bindet die Ergebnisliste in die Hauptabfrage ein:

Sollen Benutzereingaben in einem Feld für mehrere Parameter verwendet werden, so kann z.B. über einen Parameter map_val0 mit dem Wert "val1" val0 immer auf den Wert von val1 verwiesen werden.

Suche in Reaktionsgleichungen

Für die Suche in Reaktionsgleichungen stehen zwei Modi zur Verfügung:

  1. Im einfachen wird als val# einfach ein RXNFile übergeben, und Sciformation ELN liefert alle Experimente, in deren Reaktionsgleichung dieses RXNFile als Substruktur enthalten ist.
  2. Um Suchergebnisse genauer einzugrenzen, kann eine Tabelle mit Einzelkomponenten angegeben werden, wobei jede Zeile durch eine eindeutige ID gekennzeichnet ist. Die Auflistung dieser IDs kann entweder durch URLs im Stil ..&uuid0=xyz&uuid0=abc&... übergeben werden oder als kommagetrennte Liste bzw. direkt als Collection. Die Bedingungen an die einzelnen Komponenten werden durch [uuid]_query, [uuid]_crit0, [uuid]_val0, etc. beschrieben, so daß es z.B. auch möglich ist, nach Experimenten zu suchen, bei denen eine eingegrenzte Menge einer Substanz verwendet wurde. In der Regel dürfte es am einfachsten sein, einen RowRenderer vom Typ webclient.list.ElnReactionComponentSearchRenderer zu verwenden, der die entsprechenden Parameter korrekt setzt.

Suche nach ähnlichen Signalmustern

Bei der Verarbeitung von Analytikdaten versuchen die Python-Datenkonverter, aus Signalen geeignete Peaklisten zu erzeugen. Diese können dann zur Suche genutzt werden, entweder durch Vergleich mit dem Signal hochgeladener Analytikdaten, einem bestehenden Datensatz oder händisch eingegebenen Werten. Der Parameter mode# gibt an, in welcher Form das Referenzmuster bereitgestellt wird:

Prozentuale Toleranzen für die Retentionszeit, den X-, Y- und Z-Wert können durch die Parameter tolT#, tolX#, tolY# und tolZ# festgelegt werden. So kann z.B. den unterschiedlichen Charakteristika von Schwingungsspektroskopie und Massenspektrometrie Rechnung getragen werden. Für den Z-Wert kann auch ein absoluter Toleranzbereich über den Parameter tolZabs# festgelegt werden, der zur prozentualen Toleranz addiert wird. Darüber hinaus kann die Bewertung der Übereinstimmung über die Parameter minX#, maxX#, minY#, maxY#, minZ# und maxZ# auf ein bestimmtes Fenster eingegrenzt werden.

Der Parameter minHitPerc# gibt an, für wieviel Prozent der angegebenen Signale - im Rahmen der gegebenen Toleranzen - ein passendes Signal gefunden werden muß, damit ein Eintrag in die Ergebnisliste aufgenommen wird. Durch maxMiss# kann eingestellt werden, ab welcher Zahl nicht auffindbarer Signale ein Eintrag aus der Ergebnisliste entfernt wird. Analog dazu kann mittels minHit# auch eine absolute Zahl zuordenbarer Signale gefordert werden.

Ausgabeformat

Um das Ausgabeformat zu steuern, setzen Sie den Parameter format auf:

*) nur für bestimmte Objekttypen geeignet

Query definition

Search queries in Sciformation ELN are described by name-value-paris, as they can easily be created using HTTP requests or Maps. The HTTP requests can either originate from an HTML form or directly as URL call of the servlet performSearch.

The only mandatory parameter is table, giving the name of the entity class, e.g. CdbContainer.

If no further parameters are given, all data sets visible for the currently active user will be listed, unless they are deactivated (marked as disabled). To(also) display the deactivated entries, the parameter disabled_filter can be set to either DISABLED_ONLY = 1 (show deactivated entries only) or DISABLED_ANY = 2 (everything). If the parameter selected_only is set to 1 or true, only data sets selected by the current user - by clicking the checkbox of the entry line - will be listed.

The filter criteria are indexed using positive integers, the parameter query describes their combination in a Boolean expression like "[0] AND ([1] OR [2]) AND NOT [4]". Missing parentheses will be added to either side, to end up with a valid expression. A filter criterion # compromises at least of a (Java) field name crit# and a value to compare with val#. For instance, the parameters

search for all users whose first name contains "Felix". Invalid criteria (e.g. pointing to nonexisting fields) will be discarded and removed from query, trying to avoid any influence on the remaining criteria. It is also possible to let crit# refer to fields which are accessible only via JOINs (e.g. cdbMolecule.casNr or cdbMoleculeNamesCollection.name). In this case, Sciformation ELN will try to find short ways to the joined tables and store these for future use. Strings will automatically quoted, numeric values checked or NULLed. Criteria with empty values will be ignored, unless the parameter allowempty is set to 1 or true, or if the operator does not require a value (e.g. OP_IS_NULL or OP_IS_TRUE).

The following operators can be provided as parameter op# to better control the search results returned:

If the chosen operator does not match the field type, the respective default operator (in bold) is used.

Combinations with other (previous) result lists

A query (B) can be combined with result lists of previous queries (A) using the parameter list_op:

To refer to a specific result list, you must set the parameter ref_cache_id to its cache_id.

Sorting (at database level) and limit

You can set the parameter orderBy to obtain sorted result lists from the database. You must use comma-separated SQL column names, Java field names will not work. Adding DESC will reverse the sort order for the respective field. If no sort order is defined, the system will try to display better matches first. This behavior can be disabled by setting the parameter qualityConditionsMode to 1, while a value of 2 gives the quality higher priority than other ordering criteria.

The parameter limit can help to increase performance by limiting the maximum number of results. When performing API queries, the parameter skip=n allows to skip the first n results, if required.

Subqueries

A subquery is required to - for example - find all experiments (table ElnReaction) where the property (table ElnReactionProperty) "temperature" is between 40-60. The subquery will first find all matching property entries, which will become part of the main query then:

To use data entered by the user for multiple parameters, e.g. let val0 always refer to the value of val1, a parameter map_val0 with the value "val1" can be used.

Searching within reaction equations

Two modes can be used to search within reaction equations:

  1. In the simple case, a RXNFile is passed as val#, Sciformation ELN will list all experiments containing the given equation as substructure.
  2. To control the search criteria more precisely, a table of individual components can be provided, where every line has a unique identifier. These unique identifiers can be passed as URLs ..&uuid0=xyz&uuid0=abc&..., as comma separated list or directly as Collection. Each component's conditions are described by[uuid]_query, [uuid]_crit0, [uuid]_val0, etc., allowing to search also for certain substance amounts. Normally, using a RowRenderer of type webclient.list.ElnReactionComponentSearchRenderer should be a conventient and reliable option to define such queries.

Searching for similar peak patterns

When processing analytical raw data, the Python data converters try to extract reasonable peak lists. These lists can be used for searching, either by comparing to the signal of uploaded data, or an existing data set or peak data entered manually. The parameter mode# defines how the reference pattern is provided:

Relative tolerances for retention time, X, Y and Z value can be defined by parameters tolT#, tolX#, tolY# and tolZ#. By this, different charakteristics of e.g. vibrational spectroscopy and mass spectrometry can be addressed. For the Z value, an absolute tolerance range can also be defined, using the parameter tolZabs#. If both tolZ# and tolZabs# are set, the tolerances will be added. The parameters minX#, maxX#, minY#, maxY#, minZ# and maxZ# allow to limit the peak matching to a certain value range.

The parameter minHitPerc# defines, for which percentage of the query signals a matching signal must be found - with the given tolerance levels - to accept a potential result. If for a candidate, more than maxMiss# signals cannot be assigned, it will be removed from the result list. In the same way, minHit# allows to set a number of signals which must at least be assigned.

Output format

To control the format of the data, set the parameter format to:

*) only suitable for selected object types