Die Methode dataClass.query() sucht für alle Entities in der DataClass nach Entities, welche die in queryString oder formula und (optional) value angegebenen Suchkriterien erfüllen, und gibt ein neues Objekt vom Typ EntitySelection zurück, das alle gefundenen Entities der DataClass enthält. Lazy loading wird angewendet.

Werden keine passenden Entities gefunden, wird eine leere EntitySelection zurückgegeben.

Der Parameter queryString verwendet folgende Syntax:

Definitionen:

• attributePath: Name des Dataclass Attributs, in dem Sie die Suche ausführen wollen. Das kann ein einfacher Name, z.B. "country" oder ein gültiger Attributspfad sein, z.B. "country.name". Bei einem Attributspfad vom Typ Collection verwenden Sie eckige Klammern [ ] zum Verwalten aller Vorkommen, z.B. "children[ ].age". Sie können auch einen Platzhalter verwenden (siehe unten)
  
  Hinweis: Sie können nicht nach Attributen suchen, die im Namen Sonderzeichen, wie "." "[ ]" oder "=", ">", "#" enthalten, da sie im Such-String nicht korrekt gewertet werden. Für solche Fälle müssen Sie Platzhalter verwenden. Weitere Informationen dazu finden Sie im unteren Abschnitt Platzhalter verwenden. 
  
  
• formula: Eine gültige Formel (siehe Formel), als Text oder Objekt übergeben. Die Formel wird für jede bearbeitete Entity(*) gewertet und muss einen boolean Wert zurückgeben. Innerhalb der Formel ist die Entity über das Objekt This verfügbar.  
• Text: Der Formel als String muss die Anweisung eval() vorangestellt werden, damit der Suchlauf den Ausdruck korrekt bewertet. Zum Beispiel: 
  
   "eval(length(This.lastname) >=30)"
• Objekt: Die Formel als Objekt wird als Platzhalter übergeben (siehe unten). Die Formel muss mit dem Befehl Formula oder Formula from string erstellt worden sein. 

(*) Ist die Formel nicht das einzige Suchkriterium, priorisiert der Optimierer der Such-Engine u.U. andere Kriterien, wie z.B. indizierte Attribute, so dass die Formel nur für eine Teilmenge der Entities gewertet wird.

Formeln in Suchen können Parameter über $1 empfangen. Weitere Informationen dazu finden Sie im unteren Abschnitt Parameter formula.

Hinweise: 
- Sie können anstelle des Parameters queryString auch direkt den Parameter formula übergeben (wird bei komplexeren Formeln empfohlen). Siehe unteren Abschnitt Parameter formula. 
- Aus Sicherheitsgründen können Formelaufrufe innerhalb von Member-Methods query() nicht erlaubt sein. Weitere Informationen dazu finden Sie unter dem Parameter querySettings. 

• comparator: Symbol zum Vergleichen von attributePath und value. Es gibt folgende Symbole:
  

  Vergleich	Symbol(e)	Kommentar
  Ist gleich	=, ==	Erhält passende Daten, unterstützt den Joker @, berücksichtigt weder Groß- und Kleinschreibung noch diakritische Zeichen.
  	===, IS	Erhält passende Daten, bewertet @ als Standardzeichen, berücksichtigt weder Groß- und Kleinschreibung noch diakritische Zeichen.
  Ungleich zu	#, !=	unterstützt den Joker (@)
  	!==, IS NOT	bewertet @ als Standardzeichen
  Kleiner als	<
  Größer als	>
  Kleiner als oder gleich	<=
  Größer als oder gleich	>=
  Enthalten in	IN	Erhält Daten, die mit mindestens einem Wert in einer Collection bzw. einem Satz Werte übereinstimmen, unterstützt den Joker (@)
  Nicht enthalten in einer Anweisung	NOT	Klammern sind zwingend, wenn NOT vor einer Anweisung mit mehreren Operatoren verwendet wird
  Enthält Schlüsselwort	%	Schlüsselwörter lassen sich in Attributen vom Typ String oder Bild verwenden

• value: Wert zum Vergleichen mit dem aktuellen Wert der Eigenschaft jeder Entity in der Entity-Selection oder Element in der Collection. Das kann ein Platzhalter (siehe Absatz unten Platzhalter verwenden) oder jeder Ausdruck vom gleichen Datentyp wie die Eigenschaft sein. Bei Werten von Konstanten gelten folgende Regeln:
  
  • Konstanten vom Typ Text können mit oder ohne einfache Anführungszeichen übergeben werden (siehe unten Anführungszeichen verwenden). Für eine Suche innerhalb eines anderen String (eine Suche "Enthalten in") verwenden Sie den Joker (@) in value, um den zu suchenden String zu isolieren, zum Beispiel: "@Smith@". Die Schlüsselwörter true, false sind verboten.
  • Konstanten vom Typ Boolean: true oder false (unterscheiden zwischen Groß- und Kleinschreibung).
  • Konstanten vom Typ Zahl: der Punkt dient als Dezimaltrenner.
  • Konstanten vom Typ Datum: Es gilt das Format YYYY-MM-DD
  • Null Konstante: Die Suche mit dem Schlüsselwort "null" findet die Eigenschaften null und undefined.  
  • Bei einer Suche mit einem IN Vergleichsoperator muss value eine Collection sein bzw. Werte, die zum Typ des Attributspfads zwischen eckigen Klammern [] passen, getrennt durch Kommas (bei Strings müssen Anführungszeichen " mit "\" abschließen)

• logicalOperator: verbindet mehrere Bedingungen in der Suche (optional). Es gibt folgende logische Operatoren (Sie können Name oder Symbol übergeben):
  

  Konjunktion	Symbol(e)
  AND	&, &&, and
  OR	|, ||, or

  
  
  
• order by attributePath: Sie können eine Anweisung order by attributePath in der Suche hinzufügen, so dass die Ergebniswerte sortiert werden. Sie können mehrere Sortieranweisungen, durch Komma getrennt, verwenden, (z.B. order by attributePath1 desc, attributePath2 asc). Die Sortierung ist standardmäßig aufsteigend. Übergeben Sie 'desc' für absteigende Reihenfolge und 'asc' für aufsteigende Reihenfolge.
  Hinweis: Mit dieser Anweisung wird die zurückgegebene Entity Selection sortiert. Weitere Informationen dazu finden Sie im Abschnitt Sortierte vs unsortierte Entity-Selections). 

Anführungszeichen verwenden
Innerhalb der Suche müssen Sie einfache Anführungszeichen ' ' setzen, doppelte Anführungszeichen " " verwenden Sie zum Umrahmen der gesamten Suche. Andernfalls wird ein Fehler generiert. Zum Beispiel:

Hinweis: Einzelne Anführungszeichen, z.B. ein Apostroph, werden in gesuchten Werten nicht unterstützt, da sie den Suchstring unterbrechen. So erzeugt die Suche "comp.name = 'John's pizza' " einen Fehler. Für solche Fälle sollten Sie Platzhalter verwenden (siehe unten).

Klammern verwenden
Mit Klammern in einer Suche können Sie Prioritäten beim Berechnen setzen. Zum Beispiel:

Alternativ zum Einfügen einer Formel im Parameter queryString (siehe oben) können Sie ein Objekt formula direkt als boolean Suchkriterium übergeben. Wir empfehlen für Suchen das Objekt formula, da sie tokenisiert ist und Code leichter zu suchen/lesen ist. 

Die Formel muss mit dem Befehl Formula oder Formula from string erstellt werden. In diesem Fall:

• Wird formula für jede Entity bewertet und muss wahr oder falsch zurückgeben. Ist das Ergebnis der Formel während dem Suchlauf kein boolean, wird es als falsch gewertet.
• Die Entity in formula ist über das Objekt This verfügbar.  
• Ist das Objekt formula null, wird der Fehler 1626 generiert ("Text oder Formel wird erwartet"). Sie können den Fehler mit einer Methode abfangen, installiert mit dem Befehl ON ERR CALL.

Hinweis: Aus Sicherheitsgründen können innerhalb von Member-Methods query() Formelaufrufe nicht erlaubt sein. Weitere Informationen dazu finden Sie unter dem Parameter querySettings

Parameter an Formeln übergeben

Jede von der Member-Method query() aufgerufene formula kann Parameter empfangen:

• Parameter müssen über die Eigenschaft (Objekt) args des Parameters querySettings übergeben werden.
• Die Formel empfängt dieses Objekt args als Parameter $1.

Dieser kurze Code zeigt, wie Parameter an Methoden übergeben werden:

Weitere Anwendungen finden Sie unter Beispiel 3.

4D Server: In der Client/Server-Architektur werden Formeln auf dem Server ausgeführt. In diesem Kontext wird nur das Objekt querySettings.args an die Formeln gesendet.

Sie können im Parameter queryString Platzhalter für die Argumente attributePath, formula und value verwenden. Platzhalter sind Tags, die Sie in Suchstrings einfügen und die beim Bewerten durch einen anderen Wert ersetzt werden. Der Wert von Platzhaltern wird einmal am Anfang bewertet; er wird nicht für jedes Element bewertet.

Es gibt zwei Arten von Platzhaltern: Platzhalter als Index und Platzhalter als Name:

Sie können in queryString alle Argumentarten miteinander mischen. queryString kann für die Parameter attributePath, formula und value folgendes enthalten:

• direkte Werte (keine Platzhalter), 
• Platzhalter als Index bzw. Platzhalter als Name

Platzhalter in Suchen werden aus folgenden Gründen empfohlen:

1. Verhindert Einfügen von böswilligem Code: Verwenden Sie direkt von Benutzern gefüllte Variablen im Suchstring, könnte ein Benutzer die Suchbedingungen durch Einfügen zusätzlicher Suchargumente verändern. Nehmen wir beispielsweise folgenden Suchstring:
   
    $vquery:="status = 'public' & name = "+myname //Benutzer gibt Namen ein
 $result:=$col.query($vquery)
   
   Diese Suche scheint abgesichert, da nicht-öffentliche Daten gefiltert werden. Gibt der Benutzer jedoch im Bereich myname etwas ein wie OR status='private', wäre der Suchstring beim Interpretieren verändert und könnte private Daten zurückgeben.
   Mit Platzhaltern ist ein Überschreiben der Sicherheitsbedingungen nicht möglich:
   
    $result:=$col.query("status='public' & name=:1";$myname)
   
   Gibt der Benutzer hier OR status='private' im Bereich myname ein, wird das im Suchstring nicht interpretiert, sondern nur als Wert übergeben. Die Suche nach einer Person mit Namen "smith OR status='private'" schlägt einfach fehl.
   
   
2. Sie müssen sich nicht um Probleme mit Formatierung oder Zeichen kümmern, insbesondere wenn die Parameter attributePath und value nicht-alphanumerische Zeichen wie ".", "[' enthalten.
   
   
3. Sie können Variablen oder Ausdrücke in Suchargumenten verwenden. Beispiele:
   
    $result:=$col.query("address.city = :1 & name =:2";$city;$myVar+"@")
 $result2:=$col.query("company.name = :1";"John's Pizzas")

Nach Nullwerten suchen
Beim Suchen nach Nullwerten können Sie keine Syntax mit Platzhaltern verwenden, da die Such-Engine Null als einen unerwarteten Vergleichswert betrachtet. Führen Sie beispielsweise folgende Suche aus:

Bei der Suche in Collections in Objektattributen mit mehreren per UND Operator verbundenen Suchkriterien wollen Sie sicherstellen, dass nur Entities mit Elementen zurückgegeben werden, auf die alle Kriterien passen und keine Entities mit Kriterien in verschiedenen Elementen. Dazu müssen Sie die Suchkriterien mit Collection-Elementen verknüpfen, damit nur solche Elemente mit verknüpften Kriterien gefunden werden.

Nehmen wir z.B. folgende Entities: 

Entity 1:
ds.People.name: "martin"
ds.People.places: 
    { "locations" : [ {
                "kind":"home",
                "city":"paris" 
            } ] }

Entity 2:
ds.People.name: "smith"
ds.People.places: 
    { "locations" : [ {
                "kind":"home",
                "city":"lyon" 
            } , {
                "kind":"office",
                "city":"paris" 
            } ] }

Sie wollen Personen mit dem Element locations "home" in der Stadt "paris" finden.  Schreiben Sie:

... gibt die Suche "martin" und "smith" zurück, da in der Entity "smith" das Element locations "kind" den Wert "home" und das Element locations "city" den Wert "paris" hat, auch wenn es unterschiedliche Elemente sind.

Wollen Sie nur Entities mit den passende Kriterien im gleichen Element der Collection erhalten, müssen Sie Kriterien verknüpfen. Dazu machen Sie folgendes:

• Sie fügen im ersten Pfad zum Verknüpfen einen Buchstaben in die [] ein und wiederholen diesen in allen verknüpften Kriterien, also locations[a].city und locations[a].kind. Sie können jeden Buchstaben des lateinischen Alphabets verwenden (keine Unterscheidung zwischen Groß- und Kleinschreibung).
• Für ein anderes verknüpftes Kriterium in derselben Suche verwenden Sie einen anderen Buchstaben. Sie können in einer Suche bis zu 26 Kombinationen von Kriterien verwenden. 

Schreiben Sie jetzt:

... gibt die Suche nur "martin" zurück, denn hier hat im Element locations "kind" den Wert "home" und "city" den Wert "paris". Die Suche gibt dagegen nicht "smith" zurück, da die Werte "home" und "paris" nicht im gleichen Element der Collection sind.

Im Parameter querySettings können Sie ein Objekt mit zusätzlichen Optionen übergeben. Es gibt folgende Eigenschaften:

Über queryPlan und queryPath
Die in queryPlan/queryPath gespeicherten Angaben enthalten den Suchtyp (indiziert und sequentiell) und jede notwendige Untersuche zusammen mit den Verbindungsoperatoren. Suchpfade enthalten auch die Anzahl der gefundenen Entities und die erforderliche Zeit zum Ausführen jedes Suchkriteriums. Das sind nützliche Informationen, die Sie beim Entwickeln Ihrer Anwendung analysieren können. Die Beschreibung des Suchplans und seines Pfads sind im allgemeinen identisch. Sie können u.U. unterschiedlich sein, da 4D beim Ausführen der Suche dynamische Optimierungen zum Verbessern der Performance einfügen kann. Die 4D Engine kann z.B. dynamisch eine indizierte Suche in eine sequentielle umwandeln, wenn sie diese für schneller hält. Das kann bei geringer Anzahl der gesuchten Entities der Fall sein.

Führen Sie beispielsweise folgende Suche aus:

queryPlan:

queryPath:

Hier sehen Sie verschiedene Beispiele für Suchen.

Suche nach String:

Suche mit einer Anweisung NOT:

Suche mit einem Datum:

Suche mit Platzhaltern als Index für Werte:

Suche mit Platzhaltern als Index für Werte in einer verknüpften dataClass:

Suche mit Platzhaltern als Index mit Werten in absteigender Reihenfolge:

Suche mit Platzhaltern als Name für Werte:

Suche mit Platzhaltern als Name und als Index für Werte:

Suche mit queryPlan und queryPath Objekten:

Suche mit einem Attributspfad vom Typ Collection:

Suche mit einem Attributspfad vom Typ Collection und verknüpften Attributen:

Suche mit einem Attributspfad vom Typ Collection und mehreren verknüpften Attributen:

Suche mit einem Attributspfad vom Typ Object:

Suche mit einer Anweisung IN:

Suche mit einer Anweisung NOT (IN):

Suche mit Platzhaltern als Index für Attribute:

Suche mit Platzhaltern als Index für Attribute und Platzhaltern als Name für Werte: 

Suche mit Platzhaltern als Index für Attribute und Werte: 

Dieses Beispiel zeigt Suchen mit Platzhaltern mit Namen für Attribute. 

Vorgegeben ist eine Dataclass Employee mit 2 Entities:

• Entity 1:
  name: "Marie"
  number: 46
  softwares:{
  "Word 10.2": "Installed",
  "Excel 11.3": "To be upgraded",
  "Powerpoint 12.4": "Not installed"
  }
• Entity 2
  name: "Sophie"
  number: 47
  softwares:{
  "Word 10.2": "Not installed",
  "Excel 11.3": "To be upgraded",
  "Powerpoint 12.4": "Not installed" 
  }

Suche mit Platzhaltern mit Namen für Attribute:

Suche mit Platzhaltern mit Namen für Attribute und Werte: 

Diese Beispiele zeigen verschiedene Wege, um Formeln mit oder ohne Parameter in Ihren Suchen zu verwenden:

Die Formel ist als Text mit eval() im Parameter queryString vorgegeben:

Die Formel ist als Objekt über Platzhalter vorgegeben:

Nur ein Objekt Formula ist als Kriterium vorgegeben:

Es lassen sich mehrere Formeln anwenden:

Eine Formel als Text in queryString empfängt einen Parameter:

Ein Objekt Formula als Platzhalter empfängt mit derselben Methode checkName einen Parameter:

Keine Formeln zulassen, z.B. wenn der Benutzer eine Suche eingibt: