Una cadena de consulta contiene caracteres Unicode. La longitud máxima de una cadena de consulta es de 2000 caracteres. Todas las cadenas de consulta contienen al menos un valor de campo. Se recomienda escribir los valores de los campos en minúsculas, ya que las búsquedas en los campos atom, text y HTML no distinguen entre mayúsculas y minúsculas. Además, una cadena de consulta también puede contener los operadores booleanos AND, OR y NOT, que se reconocen si se escriben en mayúsculas.
Una coma solo puede aparecer en una cadena de consulta si se usa para separar los argumentos de una función (distance(home, geopoint(35.2, 40.5)) > 100) o si forma parte de una cadena entre comillas.
Una cadena de consulta puede adoptar muchas formas. Hay dos formas principales de crear una consulta: con y sin nombres de campo. Una búsqueda global usa una cadena de consulta que contiene solo valores de campo:
String query = "blue";
String query = "NOT white";
String query = "blue OR red";
String query = "blue guitar";
Una búsqueda de campos usa una cadena de consulta que contiene una o varias expresiones que especifican nombres y valores de campos:
String query = "model:gibson date < 1965-01-01";
String query = "title:\"Harry Potter\" AND pages<500";
String query = "beverage:wine color:(red OR white) NOT country:france";
En este documento se describe cómo crear cadenas de consulta para búsquedas globales y de campos, y cómo funciona la lógica de búsqueda en cada caso.
Te recomendamos que registres las cadenas de consulta en tu aplicación si quieres mantener un registro de las consultas que se han ejecutado.
Búsqueda global
La búsqueda global te permite buscar documentos especificando valores que pueden aparecer en cualquier campo del documento. Para realizar una búsqueda global, escribe una cadena de consulta que contenga uno o varios valores de campo. El algoritmo de búsqueda reconoce el tipo de cada valor y busca en todos los campos del documento que puedan contener ese valor.
Consultas de un valor
Las búsquedas con una cadena de consulta que contiene un solo valor se gestionan según estas reglas:
Si la cadena de consulta es una palabra (red) o una cadena entre comillas ("red rose"), search
recupera todos los documentos de un índice que tengan lo siguiente:
- Un campo de texto o HTML que contiene esa palabra o cadena entre comillas (no se distingue entre mayúsculas y minúsculas).
- Un campo de átomo con un valor que coincide con la palabra o la cadena entre comillas (no se 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 tengan lo siguiente:
- Un campo de texto o HTML que contiene un token que coincide con el número tal como aparece en la consulta (el campo de texto "he took 5 minutes" coincidirá con la consulta "5", pero no con "5.0").
- Un campo de átomo que coincide literalmente con el número tal como aparece en la consulta.
Si la cadena de consulta es una fecha con el formato aaaa-mm-dd, la búsqueda recupera todos los documentos que tengan:
- Un campo de fecha cuyo valor sea igual a esa fecha (los ceros iniciales de la cadena de consulta son opcionales; "2012-07-04" y "2012-7-4" son la misma fecha).
- Campo de texto o HTML que contiene un token que coincide literalmente con la fecha tal como aparece en la consulta.
- Un campo de átomo que coincide literalmente con la fecha tal como aparece en la consulta.
Puedes añadir el operador booleano NOT (en mayúsculas) delante de una consulta de una palabra. El resultado es una lista de documentos que no tienen ningún campo que coincida con el valor de la consulta, según las mismas reglas. Por lo tanto, la consulta NOT red devolverá todos los documentos que no tengan campos de texto o HTML que contengan "rojo" ni campos de tipo atom con el valor red.
Puede que hayas observado que no hemos mencionado los campos de geopunto. Por el momento, no puedes especificar un valor de geopunto sin formato como una cadena, por lo que los geopuntos no pueden aparecer en búsquedas globales.
Consultas con varios valores
Puede especificar varios valores (separados por espacios) en una cadena de búsqueda global. Los espacios en blanco entre palabras, cadenas entre comillas, números y fechas se tratan como un operador AND implícito. Las dos cadenas de búsqueda que se muestran a continuación son casi idénticas. La diferencia radica en cómo trata la búsqueda global los campos de átomo, tal como se explica a continuación:
query = "small red"
query = "small AND red"
Cuando se realiza una búsqueda global con varios valores, la coincidencia de campos se lleva a cabo de forma independiente en cada valor de la cadena, y la coincidencia de campos atómicos se gestiona de forma diferente. En concreto:
- Los valores de consulta pueden aparecer en cualquier orden en un campo de texto o HTML.
- Pueden aparecer diferentes valores en distintos campos.
- Los campos Atom solo se buscan cuando la cadena de consulta no contiene ningún operador booleano (
AND,OR,NOT). Toda la cadena de consulta debe coincidir con un campo Atom.
Ten en cuenta la tercera regla, que trata sobre los campos de átomo. La cadena de consulta "red small" no contiene el booleano AND (aunque esté implícito), por lo que la búsqueda intentará encontrar campos de átomo coincidentes. La cadena "red AND small" contiene un operador booleano, por lo que la búsqueda no intentará hacer coincidir la cadena de consulta con los campos de átomo.
En el siguiente ejemplo se muestran cuatro documentos que se han obtenido mediante la cadena de consulta "rose bud". Cada documento tiene dos campos de texto y un campo de átomo. En la columna de comentarios se explica por qué cada documento cumple la consulta.
| ID de documento | Campo de texto 1 | Campo de texto 2 | Campo Atom | Comentario |
|---|---|---|---|---|
| 1 | poderoso como una rosa | un botón para controlarlos a todos | arbusto espinoso | Los valores coincidentes pueden aparecer en campos diferentes |
| 2 | ancho como un río | como un en una rosa | tumble weed | Los valores coincidentes pueden aparecer en cualquier orden en el mismo campo de texto o HTML, con texto intermedio |
| 3 | profundo como el océano | los chicos de Rosebud | gorro azul | Los valores coincidentes pueden aparecer en cualquier orden en el mismo campo de texto o HTML |
| 4 | alto como una montaña | el hermoso jardín | de rosa | El campo Atom coincide porque su valor es el mismo que toda la cadena de consulta |
Tenga en cuenta que si invirtiera los valores en la consulta y buscara "bud rose", se devolverían los documentos 1, 2 y 3, pero no el 4. Para buscar una cadena de caracteres exacta en los campos atom, text y HTML, incluye la cadena entre comillas en la cadena de consulta. Si buscas "rose bud", solo se devolverán los documentos 3 y 4 del ejemplo.
Operadores booleanos
Puedes especificar una búsqueda global más compleja usando el operador booleano NOT
antes de un valor y los operadores AND y OR entre valores. Ten en cuenta que estos operadores deben escribirse en mayúsculas. Si aparecen en una cadena entre comillas, se tratan como parte del valor del campo, no como operadores. Puedes usar paréntesis en una cadena de consulta para que la lógica sea clara.
La precedencia de los operadores booleanos, de mayor a menor, es la siguiente: NOT, OR y 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
Procesamiento por lexemas
Para buscar variaciones comunes de una palabra, como formas en plural y terminaciones verbales, usa el ~ operador de raíz (el carácter de tilde). Se trata de un operador de prefijo que debe preceder a un valor sin espacios intermedios. El valor ~cat coincidirá con "gato" o "gatos", y ~dog coincidirá con "perro" o "perros". El algoritmo de derivación no es infalible. El valor ~care coincidirá con "care" y "caring", pero no con "cares" ni "cared". La derivación solo se usa cuando se buscan campos de texto y HTML.
Tokenización
Cuando se indexa un documento, sus campos se tokenizan. Del mismo modo, los valores de una cadena de consulta también se tokenizan. Esto significa que lo que podría parecer una consulta de un solo valor se trata como una consulta de varios valores. Por ejemplo:
"real-time" --> "real time"
"2001-12-15" --> "2001 12 15"
"1.5" --> "1 5"
Búsqueda de campos
Una búsqueda de campos busca valores en campos de documentos específicos por nombre de campo. Una cadena de consulta de búsqueda de campos se compone de una o varias 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 usar en todos los tipos de campos. Estas son algunas cadenas de consulta de campos 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 con las cadenas de consulta de búsqueda global, el valor de un campo de texto, HTML o Atom se puede incluir entre comillas para especificar una cadena, y se puede negar una expresión de un valor de campo añadiendo una NOT en mayúsculas al principio.
Consultas en campos de Atom
El valor de un campo de átomo es una cadena de caracteres. En las consultas de campos atom no se distingue entre mayúsculas y minúsculas. Si en tu consulta se especifica un valor de campo con espacios en blanco o signos de puntuación, asegúrate de incluir el valor entre comillas en la cadena de consulta. El único operador relacional válido para los campos de átomos es el operador de igualdad. El contenido completo de un campo de átomo debe coincidir con el valor de la consulta, incluidos los caracteres de combinación o acentuados de Unicode del campo. No se admite la derivación de palabras en los campos de átomos.
| Cadena de consulta | Comentarios |
|---|---|
"weather=stormy"
|
Cualquiera de las dos formas del operador de igualdad es válida. Obtiene los documentos con un campo de tiempo que sea igual a "tormentoso". |
"Title: \"Tom&Jerry\""
|
Si buscas un campo de átomo que contenga espacios en blanco o caracteres especiales, incluye el valor entre comillas. |
"Color = (red OR blue)"
|
Puede usar paréntesis y el operador lógico OR para especificar una lista de valores de campo alternativos. |
Consultas en 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 derivación para buscar variantes de una palabra. También puede usar los operadores OR y AND para especificar expresiones booleanas complejas para el valor del campo. Si aparece un operador booleano en una cadena entre comillas, no se trata de forma especial, sino que es solo otra parte de la cadena de caracteres que se debe buscar. Recuerde que, al buscar en campos HTML, se ignora el texto que se encuentra dentro de las etiquetas de marcado HTML. Las consultas en campos de texto y HTML no distinguen entre mayúsculas y minúsculas. Cuando se indexan estos campos, los caracteres de combinación Unicode y los caracteres acentuados que contengan se "normalizan" a sus equivalentes sin acento. Los caracteres combinados y los acentos también se normalizan en las cadenas de consulta de estos campos, por lo que una consulta puede incluir las formas acentuadas o no, y coincidirá con los campos en ambos casos.
| Cadena de consulta | Comentarios |
|---|---|
"Comment = great" |
Cualquiera de las dos formas del operador de igualdad es válida. Obtiene los documentos con un campo de comentario que contiene al menos una instancia de la palabra "great" en el campo Comment. |
"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 obtiene documentos con un campo Comment que incluye las tres palabras en cualquier orden con cualquier número de otras palabras entre ellas. El espacio entre palabras implica un operador AND lógico. La segunda forma lo hace explícito. |
"Comment = \"insanely great\""
|
Para buscar una cadena de texto específica, escribe la cadena entre comillas. Esta consulta devolverá los documentos cuyo campo Comment contenga la frase "insanely great" (y también "insanely-great", que se tokeniza de la misma forma). |
"pet = ~dog"
|
El operador de derivación coincidirá con las variantes de la palabra "perro" en el campo de mascota. |
"Color = (red OR blue)" |
Para buscar una coincidencia en una lista de alternativas, incluye la lista entre paréntesis con la palabra clave OR entre las alternativas. Esta consulta obtiene los documentos cuyo campo Color incluye "rojo", "azul" o ambos. |
"weather = ((rain OR snow) AND cold)" |
Puede usar los operadores lógicos OR y AND, junto con paréntesis, para especificar un valor de campo más complejo. |
"weather = \"rain OR shine\"" |
Como la operación lógica OR está insertada en una cadena entre comillas, no se trata como un operador relacional. Esta cadena de consulta obtiene documentos con un campo de tiempo que contiene la cadena "rain or shine" |
Consultas en campos de número
El valor de un campo de número se puede escribir como un número entero, un decimal o un exponencial.
Los operadores relacionales válidos para los campos de número son los operadores de igualdad, así como los operadores menor que y mayor que (<, <=, > y >=). Ten en cuenta que no hay ningún operador de desigualdad (!=). Aquí tienes algunos ejemplos de cadenas de consulta
para campos de número:
"quantity = 10000"
"size: 4"
"price < 9.99"
"theta > 1.5E-2"
Consultas en campos de fecha
El valor de un 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, así como los operadores menor que y mayor que (<, <=, > y >=). Ten en cuenta que no hay ningún operador de desigualdad. Puedes añadir el operador NOT delante de una expresión para negarla. A continuación se muestran algunas cadenas de consulta de ejemplo para campos de fecha:
"start_date: 2012-05-20"
"end_date: 2013-5-1"
"birthday >= 2000-12-31"
"NOT birthday = 2000-12-25"
Consultas en campos de geopunto
No hay operadores relacionales que funcionen con campos de geopuntos, por lo que los campos de geopuntos no se pueden nombrar directamente en una cadena de consulta. La API Search proporciona dos funciones especiales que se pueden usar en consultas que incluyan campos de geopuntos:
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 geopunto o una invocación de la función de geopunto. Ten en cuenta que no puedes proporcionar dos nombres de campo como argumentos de esta función. Al menos uno de los argumentos debe ser una constante.
Estas funciones se pueden usar para crear consultas que recuperen ubicaciones relativas a una posición constante. En los siguientes ejemplos se presupone que el índice contiene documentos con campos de geopuntos llamados "survey_marker" y "home".
| Cadena de consulta | Comentarios |
|---|---|
"distance(survey_marker, geopoint(35.2, 40.5)) < 100" |
Busca marcadores que estén a menos de 100 metros de un geopunto determinado. |
"distance(home, geopoint(35.2, 40.5)) > 100" |
Buscar casas a más de 100 metros de un punto geográfico determinado. |
Las aplicaciones que usan la geolocalización suelen recibir información del navegador. Si el usuario lo permite, la ubicación se puede inferir a partir de su dirección IP o puede introducir un código postal. La ubicación también puede proceder de otras APIs, como la API Geolocation de Google Maps.
Consultas en varios campos
Puedes combinar varias expresiones de consulta de campo en una consulta enumerándolas en secuencia y separándolas con espacios en blanco. Esto coloca un AND implícito entre cada expresión, por lo que todas ellas deben cumplirse para recuperar un documento. Puedes añadir explícitamente los operadores AND y OR entre expresiones, así como usar paréntesis para que la lógica sea clara.
| Cadena de consulta | Comentarios |
|---|---|
"product=piano manufacturer=steinway""product=piano AND manufacturer=steinway"
|
Estas consultas obtienen todos los pianos Steinway. El espacio entre los términos implica un operador AND lógico. La segunda forma lo explicita. |
"product=piano AND NOT manufacturer=steinway"
|
Obtiene todos los pianos que no son Steinway. |
"product=piano AND price<2000" |
Esta consulta obtiene pianos baratos. |
Combinar búsquedas globales y de campos
Una cadena de consulta puede contener cualquier número de expresiones de búsqueda global y expresiones de búsqueda de campos. 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 gestionará de acuerdo con las reglas asociadas a ese tipo de término.
| Cadena de consulta | Comentarios |
|---|---|
"keyboard great price<5000"
|
Obtiene los documentos en los que las palabras "great" y "keyboard" aparecen en cualquier campo de texto, HTML o Atom, y hay un campo de precio inferior a 5000.
El AND está implícito, por lo que la segunda forma es equivalente.
|
"keyboard OR product=piano" |
Recupera documentos con un campo de producto que contenga piano o documentos con cualquier campo de texto, HTML o Atom que contenga keyboard. |