Una string de consulta contiene caracteres Unicode. La longitud máxima es de 2,000 caracteres. Todas incluyen al menos un valor de campo. Se recomienda escribir los valores de campo en minúsculas porque las búsquedas en campos atómicos, de texto y HTML no distinguen entre mayúsculas y minúsculas, y las string de consulta también pueden incluir los operadores booleanos AND, OR y NOT, que se reconocen porque se escriben en mayúsculas.
Una coma puede aparecer en una string de consulta solo si se usa para separar los argumentos de una función: distance(home, geopoint(35.2, 40.5)) > 100 o es parte de una string entre comillas.
Las strings de consulta pueden ser de muchas formas. Las consultas se construyen principalmente de dos maneras: con y sin nombres de campo. La búsqueda global utiliza una cadena de consulta que solo contiene valores de campo:
query = "blue"
query = "NOT white"
query = "blue OR red"
query = "blue guitar"
La búsqueda de campo utiliza una cadena de consulta que contiene una o más expresiones para especificar nombres de campo y valores de campo:
query = "model:gibson date < 1965-01-01"
query = "title:\"Harry Potter\" AND pages<500"
query = "beverage:wine color:(red OR white) NOT country:france"
En este documento se describe cómo construir cadenas de consulta para búsquedas globales y de campo, y cómo funciona la lógica de búsqueda en cada caso.
Te recomendamos registrar las strings de consulta en tu aplicación si deseas mantener un registro de las consultas que se ejecutaron.
Búsqueda global
La búsqueda global ofrece la capacidad de buscar documentos especificando valores que puedan aparecer en cualquier campo del documento. Para realizar una búsqueda global, hay que escribir una cadena de consulta que contenga uno o más valores de campo. El algoritmo de búsqueda reconoce el tipo de cada valor y busca en todos los campos del documento que podrían incluir ese valor.
Consultas de un valor
Las búsquedas con una string de consulta que contiene un solo valor se controlan de acuerdo con estas reglas:
Si la string de consulta es una palabra (red) o una string entre comillas ("red rose"), la búsqueda recupera todos los documentos de un índice que tengan los siguientes campos:
- un campo de texto o HTML con la palabra o string entre comillas (la coincidencia no distingue entre mayúsculas y minúsculas);
- un campo atómico con un valor que coincide con la palabra o string entre comillas (la coincidencia no distingue entre mayúsculas y minúsculas).
Si la cadena de consulta es un número ("3.14159"), la búsqueda recupera todos los documentos que tienen:
- un campo numérico con un valor igual al número de la consulta (un campo numérico de valor 5 coincidirá con la consulta "5" y "5.0");
- un campo de texto o HTML con un token que coincide con el número tal como aparece en la consulta (el campo de texto "tardó 5 minutos" coincidirá con la consulta "5", pero no con "5.0");
- un campo atómico que coincide literalmente con el número que aparece en la consulta.
Si la cadena de consulta es una fecha en formato aaaa-mm-dd, la búsqueda recupera todos los documentos que tienen:
- un campo de fecha con un valor igual a la fecha que aparece en la consulta (los ceros iniciales de la cadena de consulta son opcionales, "2012-07-04" y "2012-7-4" son la misma fecha);
- un campo de texto o HTML con un token que coincide literalmente con la fecha tal como aparece en la consulta;
- un campo atómico que coincide literalmente con la fecha tal como aparece en la consulta.
En consultas de una palabra, se puede anteponer el operador booleano NOT (en mayúsculas). El resultado es una lista de documentos sin campos que coinciden con el valor de la consulta, de acuerdo con las mismas reglas. Por lo tanto, la consulta NOT red recuperará todos los documentos que no tengan campos de texto o HTML que contengan “red” o cualquier campo atómico con el valor red.
Es probable que hayas notado que no se mencionaron los campos de puntos geográficos. En este momento, no es posible especificar un valor de punto geográfico bruto como string, por lo que los puntos geográficos no pueden aparecer en las búsquedas globales.
Consultas de valores múltiples
En una string de búsqueda global, se pueden especificar varios valores (separados por espacios). El espacio entre palabras, strings entre comillas, números y fechas se trata como un operador AND implícito. Las dos strings de búsqueda a continuación son casi iguales, pero varían en cuanto a la forma en que las búsquedas globales tratan los campos atómicos, que se explica seguidamente:
query = "small red"
query = "small AND red"
Cuando se hace una búsqueda global con varios valores, las correspondencias de campos se establecen de forma independiente considerando cada valor de la string, y las correspondencias de campos atómicos se manejan de otra manera, en particular:
- Los valores de consulta pueden aparecer en cualquier orden en un campo de texto o HTML.
- Pueden aparecer valores distintos en campos diferentes.
- Los campos atómicos se buscan solo cuando la string de consulta no contiene ningún operador booleano (
AND,OR,NOT). La string de consulta completa debe coincidir con un campo atómico.
Ten en cuenta la tercera regla con respecto a los campos atómicos. La string de consulta “red small” no contiene el operador booleano AND (aunque esté implícito), por lo que la búsqueda intentará encontrar campos atómicos que coincidan. La string “red AND small” contiene un operador booleano, por lo que la búsqueda no intentará establecer coincidencias entre la string de consulta y los campos atómicos.
En el siguiente ejemplo, se muestran cuatro documentos que se recuperaron mediante la string de consulta “rose bud”. Cada documento tiene dos campos de texto y un campo atómico. En la columna “Comentario” se explica la razón por la que cada documento satisface la consulta.
| ID del documento | Campo de texto 1 | Campo de texto 2 | Campo atómico | Comentario |
|---|---|---|---|---|
| 1 | mighty like a rose | one bud to bind them all | thorn bush | Los valores coincidentes pueden aparecer en campos distintos. |
| 2 | wide like a river | like a bud on a rose | tumble weed | Los valores coincidentes pueden aparecer en cualquier orden en el mismo campo de texto o HTML, con texto intermedio. |
| 3 | deep like the ocean | the rose bud boys | blue bonnet | Los valores coincidentes pueden aparecer en cualquier orden en el mismo campo de texto o HTML. |
| 4 | tall like a mountain | the beautiful garden | rose bud | Coincidencia con el campo atómico porque su valor es el mismo que el de toda la cadena de consulta. |
Ten en cuenta que si invirtieras los valores de la consulta y buscaras, en cambio, "bud rose", se seguirían mostrando los documentos 1, 2 y 3, pero el 4 no. Para buscar una string de caracteres exacta en campos atómicos, de texto y HTML, escribe la string entre comillas en la string de consulta. Una búsqueda de "rose bud" mostraría solo los documentos 3 y 4 en el ejemplo.
Operadores booleanos
Puedes definir una búsqueda global más compleja con el operador booleano NOT antepuesto a un valor y los operadores AND y OR entre valores. Ten en cuenta que estos operadores se deben escribir en mayúsculas. Si aparecen dentro de una string entre comillas, se tratan como parte del valor del campo y no como operadores. Puedes usar paréntesis en una string de consulta para que la lógica resulte clara.
El orden en que se evalúan los operadores booleanos, del de mayor prioridad al de menor prioridad, es NOT, OR, AND:
NOT cat AND dogs OR horses --> (NOT cat) AND (dogs OR horses)
NOT cat OR dogs AND horses --> ((NOT cat) OR dogs) AND horses
Lematización
Para buscar variaciones comunes de una palabra, como plurales y terminaciones verbales, se usa el operador de lemas ~ (la tilde de la ñ). Este es un operador de prefijo que debe preceder a un valor sin espacio intermedio. El valor ~cat coincidirá con “cat” o “cats” y, de igual manera, ~dog coincidirá con “dog” o “dogs”. El algoritmo de lematización no es infalible. El valor ~care coincidirá con “care” y “caring”, pero no con “cares” o “cared”. La lematización solo se usa cuando se buscan campos de texto y HTML.
Asignación de token
Cuando se indexa un documento, se asignan tokens a sus campos. Del mismo modo, se asignan tokens a los valores de una cadena de consulta. Esto significa que lo que podría parecer una consulta de un solo valor se trata en realidad como una consulta de valores múltiples. Por ejemplo:
"real-time" --> "real time"
"2001-12-15" --> "2001 12 15"
"1.5" --> "1 5"
Búsqueda por campo
En la búsqueda por campo se buscan valores, por nombre de campo, en campos específicos de los documentos. En las búsquedas por campo, las cadenas de consulta están compuestas por una o más expresiones que especifican un nombre de campo, un operador relacional y un valor de campo. Los operadores relacionales disponibles dependen del tipo de campo. El operador de igualdad, representado por dos puntos o el signo igual, se puede utilizar para todos los tipos de campo. A continuación se incluyen algunas cadenas de consulta por campo para diferentes tipos de campos:
query = "pet = dog"
query = "author = \"Ray Bradbury\""
query = "color:red"
query = "NOT color:red"
query = "price < 500"
query = "birthday>=2011-05-10"
Ten en cuenta que el uso de espacios en blanco a ambos lados del operador relacional es opcional. Al igual que en el caso de cadenas de consulta de búsquedas globales, el valor de un campo de texto, HTML o atómico puede encerrarse entre comillas para especificar una string, y es posible negar una expresión de un valor de campo anteponiendo un NOT en mayúsculas.
Consultas sobre campos atómicos
El valor de un campo atómico es una string de caracteres. Las consultas sobre campos atómicos no distinguen entre mayúsculas y minúsculas. Si la consulta especifica un valor de campo con espacios o puntuación, asegúrate de encerrar el valor entre comillas dentro de la cadena de consulta. El único operador relacional válido para los campos atómicos es el operador de igualdad. El contenido completo de un campo atómico debe coincidir con el valor de la consulta; esto incluye los caracteres acentuados o caracteres de combinación Unicode que haya en el campo. La lematización no es compatible con los campos atómicos.
| String de consulta | Comentarios |
|---|---|
"weather=stormy"
|
Es válida cualquiera de las formas del operador de igualdad. Recupera documentos con un campo "weather" igual al valor "stormy". |
"Title: \"Tom&Jerry\""
|
Si haces la búsqueda en un campo atómico que contiene espacios o caracteres especiales, debes encerrar el valor entre comillas. |
"Color = (red OR blue)"
|
Puedes usar paréntesis y el operador lógico OR para especificar una lista de valores de campo alternativos. |
Consultas sobre campos de texto y HTML
El único operador relacional válido para los campos de texto y HTML es el de igualdad. En este caso, el operador significa “el campo incluye el valor”, no “el campo es igual al valor”. Puedes usar el operador de lematización para buscar variantes en una palabra. También puedes usar los operadores OR y AND a fin de especificar expresiones booleanas complejas para el valor del campo. Si aparece un operador booleano dentro de una string entre comillas, no se lo trata de forma especial; es solo otro elemento de la string de caracteres con el que deben buscarse coincidencias. Recuerda que cuando se hacen búsquedas sobre campos HTML, el texto dentro de las etiquetas de marcado de HTML se ignora. Las consultas sobre campos de texto y HTML no distinguen entre mayúsculas y minúsculas. Cuando se indexan estos campos, los caracteres acentuados o caracteres de combinación Unicode que haya en ellos se "normalizan", es decir, se reemplazan por sus equivalentes no acentuados. Los caracteres acentuados y de combinación también se normalizan en las cadenas de consulta sobre estos campos, por lo que una consulta puede o no incluir las formas acentuadas, y la coincidencia se establecerá en cualquiera de los casos.
| String de consulta | Comentarios |
|---|---|
"Comment = great" |
Es válida cualquiera de las formas del operador de igualdad. Recupera documentos con un campo "Comment" que contenga al menos una vez la palabra "great". |
"Comment = (great big ball)"
|
Para buscar dos o más palabras en un campo, en cualquier orden, escribe las palabras entre paréntesis. Esta cadena de consulta recupera documentos con un campo "Comment" que incluya las tres palabras en cualquier orden y con cualquier cantidad de palabras entre ellas. El espacio entre las palabras implica un operador AND; en la segunda forma el operador es explícito. |
"Comment = \"insanely great\""
|
Para buscar una string de texto específica, enciérrala entre comillas. Esta consulta recupera documentos cuyo campo "Comment" contenga la frase "insanely great" (y también "insanely-great", a la que se asigna un token con el mismo valor). |
"pet = ~dog"
|
El operador de lema buscará coincidencias de variantes de la palabra "dog" en el campo "pet". |
"Color = (red OR blue)" |
Para buscar una coincidencia entre una lista de alternativas, escribe la lista entre paréntesis con la palabra clave OR entre las alternativas. Esta consulta recupera documentos cuyo campo "Color" incluya los valores "red", "blue" o ambos. |
"weather = ((rain OR snow) AND cold)" |
Puedes usar los operadores lógicos OR y AND, junto con paréntesis, para definir un valor de campo más complejo. |
"weather = \"rain OR shine\"" |
Como el operador lógico OR está incorporado en una string entre comillas, no se lo trata como un operador relacional. Esta cadena de consulta recupera documentos con un campo "weather" que contenga la string "rain or shine" |
Consultas sobre campos numéricos
El valor de un campo numérico se puede escribir como un número entero, decimal o exponencial.
Los operadores relacionales válidos para los campos numéricos son los operadores de igualdad, junto con los operadores menores que o mayores que (<, <=, >, >=). Ten en cuenta que no hay operador de desigualdad (!=). A continuación, se incluyen algunos ejemplos de strings de consulta para campos numéricos:
"quantity = 10000"
"size: 4"
"price < 9.99"
"theta > 1.5E-2"
Consultas sobre campos de fecha
Un valor de campo de fecha debe escribirse en yyyy-mm-dd form. Los ceros iniciales son opcionales para los meses y los días de un solo dígito. Los operadores relacionales válidos para los campos de fecha son los operadores de igualdad, junto con los operadores menores que o mayores que (<, <=, >, >=). Ten en cuenta que no hay operador de desigualdad. Se puede anteponer el operador NOT a una expresión para negarla. A continuación, se incluyen algunos ejemplos de strings de consulta para campos de fecha:
"start_date: 2012-05-20"
"end_date: 2013-5-1"
"birthday >= 2000-12-31"
"NOT birthday = 2000-12-25"
Consultas sobre campos de puntos geográficos
No hay operadores relacionales que funcionen con los campos de puntos geográficos; por eso, estos campos no pueden nombrarse de forma directa en una cadena de consulta. La API de búsqueda proporciona dos funciones especiales que se pueden usar para realizar consultas sobre campos de puntos geográficos:
geopoint(lat,long)- Define un punto geográfico a partir de una latitud y una longitud.
distance(point1, point2)- Calcula la distancia en metros entre dos puntos geográficos. Cada punto se puede especificar mediante el nombre de un campo de punto geográfico o mediante una invocación a la función "geopoint". Ten en cuenta que no se pueden usar dos nombres de campo como argumentos en esta función. Al menos uno de los argumentos debe ser una constante.
Estas funciones se pueden usar para crear consultas que devuelvan ubicaciones relativas a una posición constante. En los ejemplos que siguen se parte del supuesto de que el índice contiene documentos con campos de punto geográfico llamados "survey_marker" y "home".
| String de consulta | Comentarios |
|---|---|
"distance(survey_marker, geopoint(35.2, 40.5)) < 100" |
Busca marcadores a menos de 100 metros de un punto geográfico determinado. |
"distance(home, geopoint(35.2, 40.5)) > 100" |
Busca direcciones particulares a más de 100 metros de un punto geográfico determinado. |
Por lo general, las aplicaciones que utilizan la ubicación geográfica reciben información del navegador. Si el usuario lo permite, se puede deducir la ubicación de su dirección IP, o bien es posible ingresar un código postal. La ubicación también se puede obtener a partir de otras API, como la API de ubicación geográfica de Google Maps.
Consultas sobre campos múltiples
Se pueden combinar expresiones de consulta de varios campos en una sola consulta si se las enumera en orden y separadas por espacios en blanco. Esto coloca un AND implícito entre expresión y expresión, por lo que todas las condiciones se deben cumplir para que se recupere un documento. Puedes agregar operadores AND y OR de manera explícita entre las expresiones y usar paréntesis para que la lógica resulte clara.
| String de consulta | Comentarios |
|---|---|
"product=piano manufacturer=steinway""product=piano AND manufacturer=steinway"
|
Estas consultas recuperan todos los pianos Steinway. El espacio entre los términos implica un operador lógico AND; en a segunda forma el operador es explícito. |
"product=piano AND NOT manufacturer=steinway"
|
Recupera todos los pianos que no son Steinway |
"product=piano AND price<2000" |
Esta consulta recupera pianos de bajo costo. |
Cómo mezclar búsquedas por campo y globales
Las cadenas de consulta pueden contener cualquier cantidad de expresiones de búsqueda global y por campo. Los espacios entre expresiones se tratan como AND. También puedes usar OR y AND de forma explícita, junto con paréntesis. Cada expresión se maneja de acuerdo con las reglas asociadas a ese tipo de término.
| String de consulta | Comentarios |
|---|---|
"keyboard great price<5000"
|
Recupera documentos en los que las palabras “great” y “keyboard” aparecen en cualquier campo de texto, HTML o atómico, y que incluyen un campo “price” con un valor menor que 5,000.
El operador AND es implícito; la segunda forma es equivalente.
|
"keyboard OR product=piano" |
Recupera documentos con un campo “product” que contenga el valor “piano” o documentos con campos de texto, HTML o atómicos que contengan el valor “keyboard”. |