Uma string de consulta contém carateres Unicode. O comprimento máximo de uma string de consulta é de 2000 carateres. Todas as strings de consulta contêm, pelo menos, um valor de campo. Recomendamos que escreva os valores dos campos em letras minúsculas, porque as pesquisas em campos atom, text e HTML não são sensíveis a maiúsculas e minúsculas, e uma string de consulta também pode conter os operadores booleanos AND, OR e NOT, que são reconhecidos se forem escritos em letras maiúsculas.
Uma vírgula só pode aparecer numa string de consulta se for usada para separar os argumentos de uma função: distance(home, geopoint(35.2, 40.5)) > 100 ou se fizer parte de uma string entre aspas.
Uma string de consulta pode assumir várias formas. Existem duas formas principais de criar uma consulta: com e sem nomes de campos. Uma pesquisa global usa uma string de consulta que contém apenas valores de campos:
String query = "blue";
String query = "NOT white";
String query = "blue OR red";
String query = "blue guitar";
Uma pesquisa de campos usa uma string de consulta que contém uma ou mais expressões que especificam nomes de campos e 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";
Este documento descreve como criar strings de consulta para pesquisas globais e de campos, e como funciona a lógica de pesquisa em cada caso.
Recomendamos que registe as strings de consulta na sua aplicação se quiser manter um registo das consultas que foram executadas.
Pesquisa global
A pesquisa global oferece a capacidade de pesquisar documentos especificando valores que podem aparecer em qualquer campo de documento. Para fazer uma pesquisa global, escreve uma string de consulta que contenha um ou mais valores de campo. O algoritmo de pesquisa reconhece o tipo de cada valor e pesquisa todos os campos de documentos que podem conter esse valor.
Consultas com um valor
Uma pesquisa com uma string de consulta que contém um único valor é processada de acordo com estas regras:
Se a string de consulta for uma palavra (red) ou uma string entre aspas ("red rose"), a pesquisa
obtém todos os documentos num índice que tenham:
- Um campo de texto ou HTML que contém essa palavra ou string entre aspas (a correspondência não é sensível a maiúsculas e minúsculas).
- Um campo atom com um valor que corresponde à palavra ou à string entre aspas (a correspondência não é sensível a maiúsculas e minúsculas).
Se a string de consulta for um número ("3,14159"), a pesquisa obtém todos os documentos que têm:
- Um campo de texto ou HTML que contém um token que corresponde ao número tal como aparece na consulta (o campo de texto "demorou 5 minutos" corresponde à consulta "5", mas não a "5,0").
- Um campo atom que corresponde literalmente ao número tal como aparece na consulta.
Se a string de consulta for uma data no formato aaaa-mm-dd, a pesquisa devolve todos os documentos que tenham:
- Um campo de data cujo valor é igual a essa data (os zeros à esquerda na string de consulta são opcionais, "2012-07-04" e "2012-7-4" representam a mesma data).
- Um campo de texto ou HTML que contém um token que corresponde literalmente à data tal como aparece na consulta.
- Um campo atom que corresponde literalmente à data tal como aparece na consulta.
Pode antepor o operador booleano NOT (em maiúsculas) a uma consulta de uma palavra. O resultado é uma lista de documentos que não têm campos que correspondam ao valor da consulta, de acordo com as mesmas regras. Assim, a consulta NOT red vai obter todos os documentos que não têm campos de texto ou HTML que contenham "red" ou campos de átomos com o valor red.
Pode ter reparado que os campos de geoponto não foram mencionados. Neste momento, não pode especificar um valor de geoponto bruto como uma string, pelo que os geopontos não podem aparecer em pesquisas globais.
Consultas com vários valores
Pode especificar vários valores (separados por espaços) numa string de pesquisa global. O espaço em branco entre palavras, strings entre aspas, números e datas é tratado como um operador AND implícito. As duas strings de pesquisa abaixo são quase iguais; diferem na forma como a pesquisa global trata os campos de átomos, o que é explicado abaixo:
query = "small red"
query = "small AND red"
Quando faz uma pesquisa global com vários valores, a correspondência de campos é feita de forma independente em cada valor na string, e a correspondência de campos de átomos é processada de forma diferente, em particular:
- Os valores de consulta podem aparecer em qualquer ordem num campo de texto ou HTML.
- Podem aparecer valores diferentes em campos diferentes.
- Os campos Atom são pesquisados apenas quando a string de consulta não contém operadores booleanos (
AND,OR,NOT). Toda a string de consulta tem de corresponder a um campo Atom.
Tenha em atenção a terceira regra relativa aos campos atom. A string de consulta "red small" não contém o booleano AND (apesar de estar implícito), pelo que a pesquisa vai tentar encontrar campos de átomos correspondentes. A string "red AND small" contém um operador booleano, pelo que a pesquisa não tenta fazer corresponder a string de consulta a campos de átomos.
O exemplo seguinte mostra quatro documentos que foram obtidos através da string de consulta "rose bud". Cada documento tem dois campos de texto e um campo de átomo. A coluna de comentários explica por que motivo cada documento satisfaz a consulta.
| ID do documento | Campo de texto 1 | Campo de texto 2 | Campo Atom | Comentário |
|---|---|---|---|---|
| 1 | poderosa como uma rosa | Um auricular para os unir a todos | arbusto espinhoso | Os valores correspondentes podem aparecer em campos diferentes |
| 2 | largo como um rio | como um botão numa rosa | erva-rolante | Os valores correspondentes podem aparecer em qualquer ordem no mesmo campo de texto ou HTML, com texto intercalado |
| 3 | profundo como o oceano | os rapazes rose bud | blue bonnet | Os valores correspondentes podem aparecer em qualquer ordem no mesmo campo de texto ou HTML |
| 4 | alto como uma montanha | o belo jardim | botão de rosa | O campo Atom corresponde porque o respetivo valor é igual a toda a string de consulta |
Tenha em atenção que, se invertesse os valores na consulta e pesquisasse "bud rose", os documentos 1, 2 e 3 seriam devolvidos, mas o documento 4 não seria. Para pesquisar uma string de carateres exata nos campos atom, text e HTML,
coloque a string entre aspas na string de consulta. Uma pesquisa por "rose bud" devolveria apenas os documentos 3 e 4 no exemplo.
Operadores booleanos
Pode especificar uma pesquisa global mais complexa usando o operador booleano NOT
antes de um valor e os operadores AND e OR entre valores. Tenha em atenção que estes operadores têm de ser escritos em letras maiúsculas. Se aparecerem numa string entre aspas, são tratados como parte do valor do campo e não como operadores. Pode usar parênteses numa string de consulta para tornar a lógica clara.
A precedência dos operadores booleanos, do mais alto para o mais baixo, é: 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
Derivação
Para pesquisar variações comuns de uma palavra, como formas no plural e terminações verbais, use o operador de ~ tema (o caráter til). Este é um operador de prefixo que tem de preceder um valor sem espaço entre eles. O valor ~cat corresponde a "cat" ou "cats" e, da mesma forma, ~dog corresponde a "dog" ou "dogs". O algoritmo de flexão não é infalível. O valor ~care corresponde a "care" e "caring", mas não a "cares" nem "cared". A flexão só é usada quando se pesquisam campos de texto e HTML.
Conversão em tokens
Quando um documento é indexado, os respetivos campos são divididos em tokens. Da mesma forma, os valores numa string de consulta também são convertidos em tokens. Isto significa que o que pode parecer uma consulta de valor único é, na verdade, tratado como uma consulta de vários valores. Por exemplo:
"real-time" --> "real time"
"2001-12-15" --> "2001 12 15"
"1.5" --> "1 5"
Pesquisa de campo
Uma pesquisa de campos procura valores em campos de documentos específicos, por nome do campo. Uma string de consulta de pesquisa de campo é composta por uma ou mais expressões que especificam um nome do campo, um operador relacional e um valor do campo. Os operadores relacionais disponíveis dependem do tipo de campo. O operador de igualdade, representado por dois pontos ou o sinal de igual, pode ser usado para todos os tipos de campos. Seguem-se algumas strings 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"
Tenha em atenção que a utilização de espaços em branco de qualquer lado do operador relacional é opcional. Tal como acontece com as strings de consulta de pesquisa global, o valor de um campo de texto, HTML ou atom pode ser incluído entre aspas para especificar uma string, e uma expressão para um valor de campo pode ser negada antepondo um NOT em maiúsculas.
Consultas em campos Atom
O valor de um campo de átomo é uma string de carateres. As consultas em campos atom não são sensíveis a maiúsculas e minúsculas. Se a sua consulta especificar um valor de campo com espaços ou pontuação, certifique-se de que coloca o valor entre aspas na string de consulta. O único operador relacional válido para campos de átomos é o operador de igualdade. O conteúdo completo de um campo atom tem de corresponder ao valor da consulta, incluindo quaisquer carateres combinados Unicode ou carateres acentuados no campo. A flexão não é suportada para campos de átomos.
| String de consulta | Comentários |
|---|---|
"weather=stormy"
|
Qualquer uma das formas do operador de igualdade é válida. Recupera documentos com um campo de tempo que seja igual a "tempestuoso". |
"Title: \"Tom&Jerry\""
|
Se estiver a pesquisar um campo atom que contenha espaços em branco ou carateres especiais, coloque o valor entre aspas. |
"Color = (red OR blue)"
|
Pode usar parênteses e o operador lógico OU para especificar uma lista de valores de campos alternativos. |
Consultas em campos de texto e HTML
O único operador relacional válido para campos de texto e HTML é a igualdade. Neste caso, o operador significa "o campo inclui o valor" e não "o campo é igual ao valor". Pode usar o operador de flexão para pesquisar variantes de uma palavra. Também pode usar os operadores OR e AND para especificar expressões booleanas complexas para o valor do campo. Se um operador booleano aparecer numa string entre aspas, não é tratado de forma especial. É apenas outra parte da string de carateres a ser correspondida. Lembre-se de que, quando pesquisa campos HTML, o texto nas etiquetas de marcação HTML é ignorado. As consultas em campos de texto e HTML não são sensíveis a maiúsculas e minúsculas. Quando estes campos são indexados, todos os carateres combinados Unicode e os carateres acentuados nos mesmos são "normalizados" para os respetivos equivalentes sem acento. Os carateres e os acentos combinados também são normalizados nas strings de consulta nestes campos, pelo que uma consulta pode incluir ou não as formas com acento e vai corresponder aos campos em qualquer dos casos.
| String de consulta | Comentários |
|---|---|
"Comment = great" |
Qualquer uma das formas do operador de igualdade é válida. Recupera documentos com um campo de comentário que contém, pelo menos, uma ocorrência da palavra "ótimo" no campo de comentário. |
"Comment = (great big ball)"
|
Para pesquisar duas ou mais palavras num campo, em qualquer ordem, coloque as palavras entre parênteses. Esta string de consulta obtém documentos com um campo Comment que inclui as três palavras por qualquer ordem com qualquer número de outras palavras entre elas. O espaço entre palavras implica um E lógico; a segunda forma torna isto explícito. |
"Comment = \"insanely great\""
|
Para pesquisar uma string de texto específica, coloque a string entre aspas. Esta consulta vai obter documentos cujo campo Comment contém a expressão "insanely great" (e também "insanely-great", que é tokenizada para a mesma coisa). |
"pet = ~dog"
|
O operador de flexão vai corresponder a variantes da palavra "cão" no campo de animal de estimação. |
"Color = (red OR blue)" |
Para pesquisar uma correspondência numa lista de alternativas, coloque a lista entre parênteses com a palavra-chave OU entre as alternativas. Esta consulta obtém documentos cujo campo Color inclui "red" ou "blue" ou ambos. |
"weather = ((rain OR snow) AND cold)" |
Pode usar os operadores lógicos OR e AND, juntamente com parênteses, para especificar um valor de campo mais complexo. |
"weather = \"rain OR shine\"" |
Uma vez que o OR lógico está incorporado numa string entre aspas, não é tratado como um operador relacional. Esta string de consulta obtém documentos com um campo de tempo que contém a string "rain or shine" (faça chuva ou faça sol) |
Consultas em campos numéricos
Um valor de campo numérico pode ser escrito como um número inteiro, um decimal ou um exponencial.
Os operadores relacionais válidos para campos numéricos são os operadores de igualdade, juntamente com os operadores inferior a/superior a (<, <=, >, >=). Tenha em atenção que não existe um operador de desigualdade (!=). Seguem-se alguns exemplos de strings de consulta
para campos numéricos:
"quantity = 10000"
"size: 4"
"price < 9.99"
"theta > 1.5E-2"
Consultas em campos de data
Um valor de campo de data tem de ser escrito no formato yyyy-mm-dd form. Os zeros iniciais são opcionais para meses e dias com um dígito. Os operadores relacionais válidos para campos de data são os operadores de igualdade, juntamente com os operadores inferior a/superior a (<, <=, >, >=). Tenha em atenção que não existe um operador de desigualdade. Pode
adicionar o operador NOT a uma expressão para a negar. Seguem-se alguns exemplos de strings de consulta para campos de data:
"start_date: 2012-05-20"
"end_date: 2013-5-1"
"birthday >= 2000-12-31"
"NOT birthday = 2000-12-25"
Consultas em campos de geoponto
Não existem operadores relacionais que funcionem com campos de geoponto, pelo que os campos de geoponto não podem ser nomeados diretamente numa string de consulta. A API Search oferece duas funções especiais que podem ser usadas para consultas que envolvem campos de geoponto:
geopoint(lat,long)- Define um geoponto com base numa latitude e longitude.
distance(point1, point2)- Calcula a distância em metros entre dois geopontos. Cada ponto pode ser especificado através do nome de um campo de geoponto ou de uma invocação da função geoponto. Tenha em atenção que não pode fornecer dois nomes de campos como argumentos para esta função. Pelo menos um argumento tem de ser uma constante.
Estas funções podem ser usadas para criar consultas que obtenham localizações relativas a uma posição constante. Os exemplos seguintes pressupõem que o índice contém documentos com campos de geoponto denominados "survey_marker" e "home".
| String de consulta | Comentários |
|---|---|
"distance(survey_marker, geopoint(35.2, 40.5)) < 100" |
Pesquise marcadores a menos de 100 metros de um determinado geoponto. |
"distance(home, geopoint(35.2, 40.5)) > 100" |
Pesquise casas a mais de 100 metros de um determinado geoponto. |
As aplicações que usam a geolocalização recebem normalmente informações do navegador. Se o utilizador permitir, a localização pode ser inferida a partir do respetivo endereço IP ou pode introduzir um código postal. A localização também pode ser proveniente de outras APIs, como a API Google Maps Geolocation.
Consultas em vários campos
Pode combinar várias expressões de consulta de campos numa única consulta listando-as em sequência separadas por espaços. Isto coloca um AND implícito entre cada expressão, pelo que todas têm de ser satisfeitas para obter um documento. Pode adicionar explicitamente operadores AND e OR entre expressões e usar parênteses para tornar a lógica clara.
| String de consulta | Comentários |
|---|---|
"product=piano manufacturer=steinway""product=piano AND manufacturer=steinway"
|
Estas consultas obtêm todos os pianos Steinway. O espaço entre os termos implica um E lógico; a segunda forma torna isto explícito. |
"product=piano AND NOT manufacturer=steinway"
|
Obtém todos os pianos que não são Steinway. |
"product=piano AND price<2000" |
Esta consulta obtém pianos baratos. |
Misturar pesquisas globais e de campos
Uma string de consulta pode conter qualquer número de expressões de pesquisa global e expressões de pesquisa de campo. Os espaços entre expressões são tratados como AND. Também pode usar OR e AND explicitamente, juntamente com parênteses. Cada expressão é processada de acordo com as regras associadas a esse tipo de termo.
| String de consulta | Comentários |
|---|---|
"keyboard great price<5000"
|
Recupera documentos em que as palavras "great" e "keyboard" aparecem em quaisquer campos de texto, HTML ou atom, e existe um campo de preço inferior a 5000.
O AND está implícito, a segunda forma é equivalente.
|
"keyboard OR product=piano" |
Obtém documentos com um campo de produto que contém piano ou documentos com qualquer campo de texto, HTML ou atom que contenha teclado. |