The dataClass.query( ) method searches for entities that meet the search criteria specified in queryString or formula and (optionally) value(s), for all the entities in the dataclass, and returns a new object of type EntitySelection containing all the entities that are found. Lazy loading is applied.

If no matching entities are found, an empty EntitySelection is returned.

The queryString parameter uses the following syntax:

where:

• attributePath: path of attribute on which you want to execute the query. This parameter can be a simple name (for example "country") or any valid attribute path (for example "country.name".) In case of an attribute path whose type is Collection, [ ] notation is used to handle all the occurences (for example "children[ ].age"). You can also use a placeholder (see below). 

Note: You cannot use directly attributes whose name contains special characters such as ".", "[ ]", or "=", ">", "#"..., because they will be incorrectly evaluated in the query string. If you need to query on such attributes, you must consider using placeholders, which allow an extended range of characters in attribute paths (see Using placeholders below). 

• formula: a valid formula (see Formulas) passed as Text or Object. The formula will be evaluated for each processed entity(*) and must return a boolean value. Within the formula, the entity is available through the This object.  
• Text: the formula string must be preceeded by the eval() statement, so that the query parser evaluates the expression correcly. For example:
  
   "eval(length(This.lastname) >=30)"
• Object: the formula object is passed as a placeholder (see below). The formula must have been created using the Formula or Formula from string command. 

(*) if the formula is not the only search criteria, the query engine optimizer could prior process other criteria (e.g. indexed attributes) and thus, the formula could be evaluated for only a subset of entities. 

Formulas in queries can receive parameters through $1. This point is detailed in the formula parameter paragraph below.

Notes:
- You can also pass directy a formula parameter object instead of the queryString parameter (recommended when formulas are more complex). See formula parameter paragraph below. 
- For security reasons, formula calls within query() member methods can be disallowed. See querySettings parameter description. 

• comparator: symbol that compares attributePath and value. The following symbols are supported:
  

  Comparison	Symbol(s)	Comment
  Equal to	=, ==	Gets matching data, supports the wildcard (@), neither case-sensitive nor diacritic.
  	===, IS	Gets matching data, considers the @ as a standard character, neither case-sensitive nor diacritic
  Not equal to	#, !=	Supports the wildcard (@)
  	!==, IS NOT	Considers the @ as a standard character
  Less than	<
  Greater than	>
  Less than or equal to	<=
  Greater than or equal to	>=
  Included in	IN	Gets data equal to at least one of the values in a collection or in a set of values, supports the wildcard (@)
  Not condition applied on a statement	NOT	Parenthesis are mandatory when NOT is used before a statement containing several operators
  Contains keyword	%	Keywords can be used in attributes of string or picture type

• value: the value to compare to the current value of the property of each entity in the entity selection or element in the collection. It can be a placeholder (see Using placeholders below) or any expression matching the data type property. 
  When using a constant value, the following rules must be respected:
  • text type constant can be passed with or without simple quotes (see Using quotes below). To query a string within a string (a "contains" query), use the wildcard symbol (@) in value to isolate the string to be searched for as shown in this example: "@Smith@". The following keywords are forbidden for text constants: true, false.
  • boolean type constants: true or false (case sensitive).
  • numeric type constants: decimals are separated by a '.' (period).
  • date type constants: "YYYY-MM-DD" format
  • null constant: using the "null" keyword will find null and undefined properties.  
  • in case of a query with an IN comparator, value must be a collection, or values matching the type of the attribute path between [ ] separated by commas (for strings, " characters must be escaped with "\").

• logicalOperator: used to join multiple conditions in the query (optional). You can use one of the following logical operators (either the name or the symbol can be used):
  

  Conjunction	Symbol(s)
  AND	&, &&, and
  OR	|, ||, or

• order by attributePath: you can include an order by attributePath statement in the query so that the resulting data will be sorted according to that statement. You can use multiple order by statements, separated by commas (e.g., order by attributePath1 desc, attributePath2 asc). By default, the order is ascending. Pass 'desc' to define a descending order and 'asc' to define an ascending order.
  Note: If you use this statement, the returned entity selection is ordered (for more information, please refer to Ordered vs Unordered entity selections). 

Using quotes
When you use quotes within queries, you must use single quotes ' ' inside the query and double quotes " " to enclose the whole query, otherwise an error is returned. For example:

Note: Single quotes (') are not supported in searched values since they would break the query string. For example "comp.name = 'John's pizza' " will generate an error. If you need to search on values with single quotes, you may consider using placeholders (see below).

Using parenthesis
You can use parentheses in the query to give priority to the calculation. For example, you can organize a query as follows:

As an alternative to formula insertion within the queryString parameter (see above), you can pass directly a formula object as a boolean search criteria. Using a formula object for queries is recommended since you benefit from tokenization, and code is easier to search/read.  

The formula must have been created using the Formula or Formula from string command. In this case:

• the formula is evaluated for each entity and must return true or false. During the execution of the query, if the formula's result is not a boolean, it is considered as false. 
• within the formula, the entity is available through the This object.  
• if the formula object is null, the errror 1626 ("Expecting a text or formula") is generated, that you call intercept using a method installed with ON ERR CALL.

Note: For security reasons, formula calls within query() member methods can be disallowed. See querySettings parameter description. 

Passing parameters to formulas

Any formula called by the query() member method can receive parameters:

• Parameters must be passed through the args property (object) of the querySettings parameter.
• The formula receives this args object as a $1 parameter.

This small code shows the principles of how parameter are passed to methods:

Additional examples are provided in example 3.

4D Server: In client/server, formulas are executed on the server. In this context, only the querySettings.args object is sent to the formulas.

4D allows you to use placeholders for attributePath, formula and value arguments within the queryString parameter. A placeholder is a parameter that you insert in query strings and that is replaced by another value when the query string is evaluated. The value of placeholders is evaluated once at the beginning of the query; it is not evaluated for each element.

Two types of placeholders can be used: indexed placeholders and named placeholders:

You can mix all argument kinds in queryString. A queryString can contain, for attributePath, formula and value parameters:

• direct values (no placeholders), 
• indexed placeholders and/or named placeholders.

Using placeholders in queries is recommended for the following reasons:

1. It prevents malicious code insertion: if you directly use user-filled variables within the query string, a user could modifiy the query conditions by entering additional query arguments. For example, imagine a query string like:
   
    $vquery:="status = 'public' & name = "+myname //user enters their name
 $result:=$col.query($vquery)
   
   This query seems secured since non-public data are filtered. However, if the user enters in the myname area something like "smith OR status='private', the query string would be modified at the interpretation step and could return private data.
   When using placeholders, overriding security conditions is not possible:
   
    $result:=$col.query("status='public' & name=:1";myname)
   
   In this case if the user enters smith OR status='private' in the myname area, it will not be interpreted in the query string, but only passed as a value. Looking for a person named "smith OR status='private'" will just fail.
   
   
2. It prevents having to worry about formatting or character issues, especially when handling attributePath or value parameters that might contain non-alphanumeric characters such as ".", "['... 
    
3. It allows the use of variables or expressions in query arguments. Examples:
   
    $result:=$col.query("address.city = :1 & name =:2";$city;$myVar+"@")
 $result2:=$col.query("company.name = :1";"John's Pizzas")

Looking for null values
When you look for null values, you cannot use the placeholder syntax because the query engine considers null as an unexpected comparison value. For example, if you execute the following query:

When searching in collections within object attributes using multiple query arguments joined by the AND operator, you may want to make sure that only entities containing elements that match all arguments are returned, and not entities where arguments can be found in different elements. To do this, you need to link query arguments to collection elements, so that only single elements containing linked arguments are found.

For example, with the following two 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" 
            } ] }

You want to find people with a "home" location kind in the city "paris". If you write:

... the query will return "martin" and "smith" because "smith" has a "locations" element whose "kind" is "home" and a "locations" element whose "city" is "paris", even though they are different elements.

If you want to only get entities where matching arguments are in the same collection element, you need to link arguments. To link query arguments:

• Add a letter between the [] in the first path to link and repeat the same letter in all linked arguments. For example: locations[a].city and locations[a].kind. You can use any letter of the Latin alphabet (not case sensitive).
• To add different linked criteria in the same query, use another letter. You can create up to 26 combinations of criteria in a single query. 

With the above entities, if you write:

... the query will only return "martin" because it has a "locations" element whose "kind" is "home" and whose "city" is "paris". The query will not return "smith" because the values "home" and "paris" are not in the same collection element. 

In the querySettings parameter, you can pass an object containing additional options. The following properties are supported:

About queryPlan and queryPath
The information recorded in queryPlan/queryPath includes the query type (indexed and sequential) and each necessary subquery along with conjunction operators. Query paths also contain the number of entities found and the time required to execute each search criterion. You may find it useful to analyze this information while developing your application(s). Generally, the description of the query plan and its path are identical but they can differ because 4D can implement dynamic optimizations when a query is executed in order to improve performance. For example, the 4D engine can dynamically convert an indexed query into a sequential one if it estimates that it is faster. This particular case can occur when the number of entities being searched for is low.

For example, if you execute the following query:

queryPlan:

queryPath:

This section provides various examples of queries. 

Query on a string:

Query with a NOT statement:

Queries with dates:

Query with indexed placeholders for values:

Query with indexed placeholders for values on a related dataClass:

Query with indexed placeholder including a descending order by statement:

Query with named placeholders for values:

Query that uses both named and indexed placeholders for values:

Query with queryPlan and queryPath objects:

Query with an attribute path of Collection type:

Query with an attribute path of Collection type and linked attributes:

Query with an attribute path of Collection type and multiple linked attributes:

Query with an attribute path of Object type:

Query with an IN statement:

Query with a NOT (IN) statement:

Query with indexed placeholders for attributes:

Query with indexed placeholders for attributes and named placeholders for values: 

Query with indexed placeholders for attributes and values: 

This section illustrates queries with named placeholders for attributes. 

Given an Employee dataclass with 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" 
  }

Query with named placeholders for attributes:

Query with named placeholders for attributes and values: 

These examples illustrate the various ways to use formulas with or without parameters in your queries.

The formula is given as text with eval() in the queryString parameter:

The formula is given as a Formula object through a placeholder:

Only a Formula object is given as criteria:

Several formulas can be applied:

A text formula in queryString receives a parameter:

Using the same checkName method, a Formula object as placeholder receives a parameter:

We want to disallow formulas, for example when the user enters their query: