El método dataClass.query( ) busca entidades que cumplan los criterios de búsqueda especificados en cadenaBusq o formula y (opcionalmente) valor, para todas las entidades de la clase de datos o de la selección de entidades y devuelve un nuevo objeto de tipo EntitySelection que contiene todas las entidades de la clase de datos que fueron encontradas. Se aplica carga diferida.

Si no se encuentran entidades coincidentes, se devuelve una EntitySelection vacía.

El parámetro cadenaBusq utiliza la siguiente sintaxis:

donde:

• rutaAtributo: ruta del atributo en el que desea ejecutar la búsqueda. Este parámetro puede contener un nombre simple (por ejemplo "país"). En el caso de una ruta de atributo tipo Collection, la notación [] se utiliza para manejar todas las ocurrencias (por ejemplo "children[ ].age"). También puede utilizar un texto de ejemplo (placeholder) (ver abajo).

Nota: no puede utilizar directamente los atributos cuyo nombre contenga caracteres especiales como ".", "[ ]", o "=", ">", "#"..., porque se evaluarán incorrectamente en la cadena de búsqueda. Si necesita buscar dichos atributos, debe considerar el uso de marcadores de posición, que permiten un rango extendido de caracteres en las rutas de atributos (ver Parámetro valor (y placeholders) a continuación).

• formula: una fórmula válida (ver Fórmulas) pasada como Texto u Objeto. La fórmula se evaluará para cada entidad procesada (*) y debe devolver un valor booleano. Dentro de la fórmula, la entidad está disponible vía el objeto This .  
  • Texto: la cadena de fórmula debe ir precedida por la declaración eval(), de modo que el analizador de consultas evalúe la expresión correctamente. Por ejemplo:
    
     "eval(length(This.lastname) >=30)"
  • Objeto: el objeto fórmula se pasa como un marcador de posición (ver abajo). La fórmula debe haberse creado con el comando Formula o Formula from string. 

(*) Si la fórmula no es el único criterio de búsqueda, el sistema de optimización de búsquedas podría priorizar otros criterios (por ejemplo, atributos indexados) y, por lo tanto, la fórmula podría evaluarse solo para un subconjunto de entidades.

Las fórmulas en las consultas pueden recibir parámetros vía $1. Este punto se detalla en el párrafo Parámetro fórmula abajo.

Notas:
- También puede pasar directamente un parámetro formula en lugar del parámetro cadenaBusq (recomendado cuando las fórmulas son más complejas). Ver el párrafo Parámetro fórmula abajo. 
- Por razones de seguridad, es posible desactivar las llamadas de fórmulas dentro de los métodos miembros query(). Ver la descripción del parámetro cadenaBusq.

• comparador: símbolo que compara rutaAtributo y valor. Los siguientes símbolos son soportados:

• valor: el valor a comparar con el valor actual de la propiedad de cada elemento en la colección o selección de entidades. Puede ser cualquier expresión del mismo tipo de datos que la propiedad o un separador de posición (ver Parámetro valor (y placeholders) abajo) o toda expresión que corresponda con la propiedad del tipo de datos. 
  Cuando se utiliza un valor constante, se deben respetar las siguientes reglas:
  • las constantes de tipo texto pueden pasarse con o sin comillas sencillas (ver Uso de comillas abajo). Para buscar una cadena dentro de una cadena (una búsqueda "contiene"), utilice el símbolo comodín (@) en valor para aislar la cadena que se va a buscar como se muestra en este ejemplo: "@Smith@". Las siguientes palabras claves están prohibidas para las constantes: true, false.
  • constantes tipo booleano: true o false (sensible a mayúsculas y minúsculas).
  • constantes tipo numérico: los decimales son separados por un '.' (punto).
  • constantes tipo fecha: formato "AAAA-MM-DD"
  • constante null: utilizando la palabra clave "null" encontrará propiedades null y undefined.
  • En el caso de una búsqueda con un comparador IN, valor debe ser una colección, o valores que coincidan con el tipo de la ruta del atributo entre [ ] separados por comas (para cadenas, "los caracteres se deben escapar con "\").  

• operadorLogico: utilizado para unir múltiples condiciones en la búsqueda (opcional). Puede usar uno de los siguientes operadores lógicos (puede pasar el nombre o el símbolo):
  

  Conjunción	Símbolo(s)
  AND	&, &&, and
  OR	|, ||, or

Como alternativa a la inserción de fórmulas dentro del parámetro cadenaBusq (ver arriba), puede pasar directamente un objeto formula como un criterio de búsqueda booleano. Se recomienda utilizar un objeto fórmula para consultas, ya que se beneficia de la tokenización y el código es más fácil de buscar/leer.

La fórmula debe haberse creado con el comando Formula o Formula from string. En este caso:

• formula se evalúa para cada entidad y debe devolver verdadero o falso. Durante la ejecución de la consulta, si el resultado de la fórmula no es booleano, se considera falso.
• dentro de formula, la entidad está disponible a través del objeto This .  
• si el objeto formula es null, se genera el error 1626 ("Esperando un texto o una fórmula"), que llama intercepción utilizando un método instalado con ON ERR CALL.

Nota: por razones de seguridad, las llamadas de fórmula dentro de los métodos query() pueden ser rechazadas. Ver la descripción del parámetro cadenaBusq.

Pasando parámetros a fórmulas

Toda formula llamada por el método miembro query() puede recibir parámetros:

• Los parámetros se deben pasar a través de la propiedad args (objeto) del parámetro cadenaBusq.
• La fórmula recibe este objeto args como un parámetro $1.

Este pequeño código muestra los principios de cómo se pasan los parámetros a los métodos:

Se presentan ejemplos adicionales en el ejemplo 3.

4D Server: en cliente/servidor, las fórmulas se ejecutan en el servidor. En este contexto, solo el objeto querySettings.args se envía a las fórmulas.

4D le permite utilizar marcadores de posición para los argumentos rutaAtributo, formula y valor dentro del parámetro params. Un marcador de posición es un parámetro que se inserta en las cadenas de búsqueda y que se reemplaza por otro valor cuando se evalúa la cadena de búsqueda. El valor de los marcadores de posición se evalúa una vez al comienzo de la consulta; No se evalúa para cada elemento.

Se pueden utilizar dos tipos de marcadores de posición: marcadores de posición indexados y marcadores de posición con nombre:

Puede combinar todos los tipos de argumentos en cadenaBusq. Una cadenaBusq puede contener, en términos de parámetros rutaAtributo, formula y valor:

• valores directos (sin marcadores de posición),
• marcadores de posición indexados y/o marcadores de posición nombrados.

Se recomienda utilizar marcadores de posición en las búsquedas por los siguientes motivos:

1. Evita la inserción de código malicioso: si utiliza en la cadena de búsqueda variables llenadas directamente por usuarios, un usuario podría modificar las condiciones de consulta al ingresar argumentos de consulta adicionales. Por ejemplo, imagine una cadena de consulta como:
   
    $vquery:="status = 'public' & name = "+myname //el usuario introduce su nombre
 $result:=$col.query($vquery)
   
   Esta consulta parece segura ya que los datos no públicos se filtran. Sin embargo, si el usuario introduce en el área $myname algo así como smith OR status='private', la cadena de consulta se modificaría en el paso de interpretación y podría devolver datos privados.
   Al utilizar marcadores de posición, no es posible prevalecer sobre las condiciones de seguridad:
   
    $result:=$col.query("status='public' & name=:1";$myvar)
   
   En este caso, si el usuario introduce OR status='private' en el área $myvar, no se interpretará en la cadena de consulta, sino que solo se pasará como un valor. Buscar una persona llamada "OR status='private'" simplemente fallará.
2. Evita tener que preocuparse por problemas de formato o caracteres, especialmente al manejar parámetros rutaAtributo o valor que podrían contener caracteres no alfa numéricos tales como ".", "['... 
3. Permite el uso de variables o expresiones en argumentos de consulta. Ejemplos:
   
    $result:=$col.query("address.city = :1 & name =:2";$city;$myVar+"@")
 $result2:=$col.query("company.name = :1";"John's Pizzas")

Búsqueda de valores null
Cuando busca valores null, no puede utilizar la sintaxis de marcador de posición porque el motor de consulta considera null como un valor de comparación invalido. Por ejemplo, si ejecuta la siguiente búsqueda:

Al realizar búsquedas en colecciones dentro de atributos de objetos utilizando múltiples argumentos de consulta unidos por el operador AND, es posible que desee asegurarse de que sólo se devuelvan entidades que contengan elementos que coincidan con todos los argumentos, y no entidades en las que se puedan encontrar argumentos en diferentes elementos. Para ello, debe vincular los argumentos de consulta a los elementos de la colección, de forma que sólo se encuentren elementos individuales que contengan argumentos vinculados.

Por ejemplo, con las siguientes dos entidades:

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

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

Quiere encontrar gente con un tipo de ubicación "home" en la ciudad "paris". Si escribe: 

... ... la consulta devolverá "martin" y "smith" porque "smith" tiene un elemento "locations" cuya "kind" es "home" y un elemento "locations" cuya "city" es "paris", aunque son elementos diferentes.

Si quiere obtener sólo entidades donde los argumentos coincidentes estén en el mismo elemento colección, necesita enlazar los argumentos. Para enlazar los argumentos de búsqueda:

• Añada una letra entre el [] en la primera ruta a enlazar y repita la misma letra en todos los argumentos enlazados. Por ejemplo: locations[a].city y locations[a].kind. Puede utilizar cualquier letra del alfabeto latino (no se distingue entre mayúsculas y minúsculas).
• Para añadir diferentes criterios de enlace en la misma consulta, utilice otra letra. Puede crear hasta 26 combinaciones de criterios en una sola consulta.

Con las entidades anteriores, si escribe:

... la búsqueda sólo devolverá "martin" porque tiene un elemento "locations" cuya "kind" es "home" y cuya "city" es "paris". La consulta no devolverá "smith" porque los valores "home" y "paris" no están en el mismo elemento de colección.

En el parámetro params, puede pasar un objeto que contenga opciones adicionales. Las siguientes propiedades son soportadas:

Acerca de queryPlan y queryPath
La información registrada en queryPlan/queryPath incluye el tipo de consulta (indexada y secuencial) y cada subconsulta necesaria junto con los operadores de conjunción. Las rutas de búsqueda también contienen la cantidad de entidades encontradas y el tiempo requerido para ejecutar cada criterio de búsqueda. Puede resultarle útil analizar esta información mientras desarrolla sus aplicaciones. En general, la descripción del plan de búsqueda y su ruta son idénticos, pero pueden diferir porque 4D puede implementar optimizaciones dinámicas cuando se ejecuta una búsqueda para mejorar el rendimiento. Por ejemplo, el motor 4D puede convertir dinámicamente una búsqueda indexada en una secuencial si estima que es más rápida. Este caso particular puede ocurrir cuando el número de entidades que se buscan es bajo.

Por ejemplo, si ejecuta la siguiente búsqueda:

queryPlan:

queryPath:

Aquí hay varios ejemplos de consultas válidas.

Consulta estándar con marcadores de posición:

Consulta estándar sin marcadores de posición:

Consulta con un dataClass relacionado:

Consulta con un marcador de posición indexado incluyendo un orden descendente por sentencia:

Consulta con marcadores de posición nombrados para valores:

Consulta que utiliza marcadores de posición nombrados e indexados para valores:

Consulta con objetos queryPlan y queryPath:

Consulta con marcadores de posición y valores dados como una colección:

Consulta con una declaración NOT:

Consulta con una ruta de atributo de tipo Collection:

Consulta con una ruta de atributo de tipo Collection y atributos vinculados:

Consulta con una ruta de atributo de tipo Collection y múltiples atributos vinculados:

Consulta con una ruta de atributo de tipo Object:

Consulta con una declaración IN:

Consulta con una instrucción NOT (IN):

Consulta con marcadores indexados para los atributos:

Consulta con marcadores indexados para los atributos y con los placeholders nombrados para los valores: 

Consulta con marcadores indexados para los atributos y los valores: 

Esta sección ilustra las búsquedas con los marcadores de posición con nombre para los atributos.

Dada una dataclass Employee con 2 entidades:

• 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" 
  }

Búsqueda con los marcadores de posición con nombre para los atributos:

Búsqueda con los marcadores de posición con nombre para los atributos y los valores:

Estos ejemplos ilustran las diferentes formas de utilizar fórmulas con o sin parámetros en sus búsquedas.

La fórmula se da como texto con eval() en el parámetro cadenaBusq:

La fórmula se da como un objeto Fórmula a través de un marcador de posición:

Sólo un objeto Fórmula se da como criterio:

Se pueden aplicar varias fórmulas:

Una fórmula texto en cadenaBusq recibe un parámetro:

Utilizando el mismo método checkName, un objeto Fórmula como marcador de posición recibe un parámetro:

Queremos no permitir fórmulas, por ejemplo, cuando el usuario introduce su búsqueda: