Observação: o Python 2.7 chegou ao fim do suporte em 31 de janeiro de 2024. Os aplicativos Python 2.7 atuais continuarão a ser executados e a receber tráfego. No entanto, o App Engine pode bloquear a reimplantação de aplicativos que usam ambientes de execução após o término da data de suporte. Recomendamos que você migre para a versão compatível mais recente do Python.

Strings de consulta

Uma string de consulta contém caracteres Unicode. O comprimento máximo desse tipo de string é de 2.000 caracteres. Todas elas contêm pelo menos um valor de campo. É recomendável escrever valores de campo em minúsculas, já que as pesquisas em campos atômicos, de texto e HTML são indiferentes a maiúsculas. Além disso, uma string de consulta também pode conter os operadores booleanos AND, OR e NOT, reconhecidos pela grafia em maiúsculas.

Uma vírgula poderá aparecer em uma string de consulta somente se for usada para separar os argumentos de uma função: distance(home, geopoint(35.2, 40.5)) > 100 ou como parte de uma string entre aspas.

Uma string de consulta pode assumir várias formas. Há duas maneiras principais de criar uma consulta: com e sem nomes de campo. Uma pesquisa global usa uma string de consulta que contém apenas valores de campo:

query = "blue"
query = "NOT white"
query = "blue OR red"
query = "blue guitar"

Uma pesquisa de campo usa uma string de consulta contendo uma ou mais expressões que especificam nomes e 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"

Neste documento, descrevemos como criar strings de consulta para pesquisas globais e de campo e como funciona a lógica de pesquisa em cada caso.

Recomendamos que você registre strings de consulta no aplicativo se quiser manter um registro das consultas que foram executadas.

Pesquisa global

A pesquisa global oferece a capacidade de procurar documentos especificando valores que podem aparecer em qualquer campo de documento. Para executar uma pesquisa global, escreva 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 do documento que podem conter esse valor.

Consultas de valor único

As pesquisas com uma string de consulta que contém um único valor são processadas de acordo com as regras a seguir.

Se a string de consulta for uma palavra (red) ou uma string entre aspas ("red rose"), a pesquisa irá recuperar todos os documentos em um índice com:

um texto ou campo HTML que contenha essa palavra ou string entre aspas (a correspondência é indiferente a maiúsculas);
um campo atômico com um valor que corresponda à palavra ou à string entre aspas (a correspondência é indiferente a maiúsculas).

Se a string de consulta for um número ("3,14159"), a pesquisa recuperará todos os documentos que tenham:

um campo de texto ou HTML contendo um token que corresponda ao número que aparece na consulta (o campo de texto "ele demorou 5 minutos" corresponderá à consulta "5", mas não à "5,0");
um campo atômico que corresponda literalmente ao número que aparece na consulta.

Se a string de consulta for uma data no formato aaaa-mm-dd, a pesquisa recuperará todos os documentos que tenham:

um campo de data com o valor igual a essa data (os zeros iniciais na string de consulta são opcionais, "2012-07-04" e "2012-7-4" são a mesma data);
um campo de texto ou HTML contendo um token que corresponda literalmente à data tal como aparece na consulta;
um campo atômico que corresponda literalmente à data tal como aparece na consulta.

É possível adicionar o operador booleano NOT (em maiúsculas) a uma consulta de uma palavra. O resultado será uma lista de documentos que não têm nenhum campo correspondente ao valor da consulta, de acordo com as mesmas regras. Portanto, a consulta NOT red vai recuperar todos os documentos que não tenham campos de texto ou HTML que contenham "red" ou quaisquer campos atômicos com o valor red.

Talvez você tenha percebido que os campos de geopoint não foram mencionados. No momento, não é possível especificar um valor bruto de geopoint como uma string. Portanto, os geopoints não podem aparecer nas pesquisas globais.

Consultas com múltiplos valores

É possível especificar múltiplos valores (separados por espaços) em uma string de pesquisa global. O espaço em branco entre as 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. Elas diferem na maneira como a pesquisa global trata os campos atômicos, conforme explicaremos abaixo:

query = "small red"
query = "small AND red"

Ao executar uma pesquisa global com múltiplos valores, a correspondência de campos é feita de maneira independente em cada valor na string. Já na correspondência de campos atômicos, ela é processada de maneira diferente, mais especificamente da maneira a seguir:

Os valores da consulta podem aparecer em qualquer ordem em um campo de texto ou HTML.
Valores diferentes podem aparecer em campos diferentes.
Os campos atômicos são pesquisados somente quando a string de consulta não contém nenhum operador booleano (AND, OR, NOT). A string de consulta inteira precisa corresponder a um campo atômico.

Observe a terceira regra relacionada aos campos atômicos. A string de consulta "red small" não contém o valor booleano AND, mesmo que ele esteja implícito. Por isso, a pesquisa tentará encontrar campos atômicos correspondentes. A string "red AND small" contém um operador booleano. Por isso, a pesquisa não tentará corresponder a string de consulta aos campos atômicos.

O exemplo a seguir mostra quatro documentos que foram recuperados usando a string de consulta "rose bud". Cada documento tem dois campos de texto e um campo atômico. A coluna de comentários explica por que cada documento satisfaz a consulta.

Código do documento	Campo de texto 1	Campo de texto 2	Campo atômico	Comentário
1	mighty like a rose	one bud to bind them all	thorn bush	Os valores de correspondência podem aparecer em diferentes campos
2	wide like a river	like a bud on a rose	tumble weed	Os valores de correspondência podem aparecer em qualquer ordem no mesmo campo de texto ou HTML, com texto entre eles
3	deep like the ocean	the rose bud boys	blue bonnet	Os valores de correspondência podem aparecer em qualquer ordem no mesmo campo de texto ou HTML
4	tall like a mountain	the beautiful garden	rose bud	O campo atômico coincide porque o valor é igual a toda a string de consulta

Observe que, se você invertesse os valores na consulta e pesquisasse por "bud rose", os documentos 1, 2 e 3 ainda seriam retornados, mas o documento 4 não. Para pesquisar uma string exata em campos atômicos, de texto e HTML, basta citá-la na string de consulta. Uma pesquisa por "rose bud" retornaria apenas os documentos 3 e 4 no exemplo.

Operadores booleanos

É possível especificar uma pesquisa global mais complexa usando o operador booleano NOT antes de um valor e os operadores AND e OR entre os valores. Observe que esses operadores precisam ser escritos em maiúsculas. Se aparecerem dentro de uma string entre parênteses, eles serão tratados como parte do valor do campo, não como operadores. Use parênteses em uma string de consulta para que a lógica seja clara.

A ordem de prioridade dos operadores booleanos, do mais alto ao 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 procurar variações comuns de uma palavra, como formas plurais e terminações verbais, use o operador de derivação ~~ (o caractere til). Esse é um operador de prefixo que precisa preceder um valor sem espaço intermediário. O valor ~cat corresponderá a "cat" ou "cats" e ~dog corresponderá a "dog" ou "dogs". O algoritmo de derivação não é à prova de erros. O valor ~care corresponderá a "care" e "caring", mas não a "cares" ou "cared". A derivação é usada somente ao pesquisar campos de texto e HTML.

Tokenização

Quando um documento é indexado, os campos são tokenizados. Da mesma maneira, os valores em uma string de consulta também são tokenizados. Assim, o que pode parecer uma consulta de valor único, na verdade, é processado como uma consulta de múltiplos valores. Por exemplo:

"real-time" --> "real time"
"2001-12-15" --> "2001 12 15"
"1.5" --> "1 5"

Pesquisa de campo

Uma pesquisa de campo procura valores em campos de documentos específicos, por nome de campo. Uma string de consulta de pesquisa de campo é composta por uma ou mais expressões que especificam um nome de campo, um operador relacional e um valor de campo. Os operadores relacionais disponíveis dependem do tipo do campo. O operador de igualdade, representado por dois pontos ou o sinal de igual, pode ser usado para todos os tipos de campo. Veja algumas strings de consulta 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"

Observe que o uso de espaços em branco em ambos os lados do operador relacional é opcional. Assim como acontece com as strings de consulta de pesquisa global, o valor de um campo atômico, de texto ou HTML pode ser incluído entre aspas para especificar uma string, e uma expressão para um valor de campo pode ser negada com a adição do operador NOT, em maiúsculas.

Consultas em campos atômicos

O valor de um campo atômico é uma string de caracteres. As consultas em campos atômicos são indiferentes a maiúsculas. Se a consulta especificar um valor de campo com espaços em branco ou pontuação, inclua o valor entre aspas na string de consulta. O único operador relacional válido para campos atômicos é o de igualdade. O conteúdo completo de um campo atômico precisa corresponder ao valor da consulta. Isso inclui todos os caracteres de combinação Unicode ou caracteres acentuados no campo. A derivação não é compatível com campos atômicos.

String de consulta	Comentários
`"weather=stormy" "weather: stormy"`	Qualquer uma das formas do operador de igualdade é válida. Recupera documentos com um campo "weather" igual a "stormy".
`"Title: \"Tom&Jerry\"" "Couple: \"Fred and Ethel\"" "Version = \"1HCP(21.3)\""`	Se você estiver pesquisando um campo atômico que contenha espaços em branco ou caracteres especiais, coloque o valor entre aspas.
`"Color = (red OR blue)" "Color = (\"dark red\" OR \"bright blue\")"`	É possível usar parênteses e o operador lógico OR para especificar uma lista de valores de campo alternativos.

Consultas em campos de texto e HTML

O único operador relacional válido para campos de texto e HTML é o de igualdade. Nesse caso, o operador significa "campo inclui valor" e não "campo igual ao valor". Você pode usar o operador de derivação para procurar variantes de uma palavra. Você 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 dentro de uma string entre aspas, ele não será considerado à parte, e sim como mais um elemento da string a ser correspondida. Lembre-se de que, na pesquisa de campos HTML, o texto nas tags de marcação HTML é ignorado. As consultas em campos de texto e HTML são indiferentes a maiúsculas. Quando esses campos são indexados, os caracteres acentuados e de combinação Unicode presentes são substituídos por equivalentes não acentuados. Caracteres e acentos também são substituídos em strings de consulta nesses campos. Portanto, uma consulta pode incluir as formas acentuadas ou não e, assim, combinar os campos em ambos os casos.

String de consulta	Comentários
`"Comment = great" "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 "great" no campo "Comment".
`"Comment = (great big ball)" "Comment = (great AND big AND ball)"`	Para procurar duas ou mais palavras em um campo, em qualquer ordem, coloque as palavras entre parênteses. Essa string de consulta recupera documentos com um campo "Comment" contendo todas as três palavras em qualquer ordem, com qualquer número de outras palavras entre elas. Com o espaço entre os termos, o AND fica implícito na pesquisa, e a segunda forma o torna explícito.
`"Comment = \"insanely great\""`	Para pesquisar uma string específica de texto, coloque a string entre aspas. Essa consulta recuperará documentos em que o campo "Comment" contenha a frase "insanely great" e também "insanely-great", a versão tokenizada.
`"pet = ~dog"`	O operador de derivação buscará as variantes da palavra "dog" no campo "pet".
`"Color = (red OR blue)"`	Para pesquisar uma correspondência de uma lista de alternativas, coloque a lista entre parênteses com a palavra-chave OR entre as alternativas. Essa consulta recupera documentos em que o campo "Color" inclui "red" ou "blue" ou ambos.
`"weather = ((rain OR snow) AND cold)"`	É possível usar os operadores lógicos OR e AND, juntamente com parênteses, para especificar um valor de campo mais complexo.
`"weather = \"rain OR shine\""`	Como o OR lógico está incorporado em uma string entre aspas, ele não é tratado como um operador relacional. Essa string de consulta recupera documentos com um campo "weather" que contenha a string "rain or shine".

Consultas em campos numéricos

O 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, junto com os operadores menor que/maior que (<, <=, >, >=). Não há operador de desigualdade (!=). Veja algumas strings de consulta de exemplo 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 precisa ser escrito em yyyy-mm-dd form. Os zeros iniciais são opcionais para meses e dias de um dígito. Os operadores relacionais válidos para campos de data são os de igualdade e os operadores menor que/maior que (<, <=, >, >=). Não há operador de desigualdade. Para negar uma expressão, basta adicionar o operador NOT antes dela. Veja algumas strings de consulta de exemplo 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 pontos geográficos

Nenhum operador relacional funciona com os campos de pontos geográficos. Portanto, eles não podem ser nomeados diretamente em uma string de consulta. A API Search fornece duas funções especiais que podem ser usadas para consultas envolvendo campos de pontos geográficos:

geopoint(lat,long): Define um ponto geográfico considerando latitude e longitude.
distance(point1, point2): Calcula a distância em metros entre dois pontos geográficos. Cada ponto pode ser especificado com o nome de um campo de ponto geográfico ou uma chamada à função correspondente. Não é possível fornecer dois nomes de campo como argumentos nessa função. Pelo menos um argumento precisa ser uma constante.

Essas funções podem ser usadas para criar consultas que recuperam locais em relação a uma posição constante. Nos exemplos a seguir, supomos que o índice contém documentos com campos de pontos geográficos denominados "survey_marker" e "home".

String de consulta	Comentários
`"distance(survey_marker, geopoint(35.2, 40.5)) < 100"`	Pesquisa marcadores a menos de 100 metros de um determinado geopoint.
`"distance(home, geopoint(35.2, 40.5)) > 100"`	Pesquisa casas a mais de 100 metros de um determinado geopoint.

Os aplicativos que usam geolocalização geralmente recebem informações do navegador. Se o usuário permitir, a localização poderá ser inferida a partir do endereço IP ou ele poderá inserir um CEP. A localização também pode vir de outras APIs, como a API Google Maps Geolocation.

Consultas em vários campos

É possível combinar várias expressões de consulta de campos em uma consulta. Para isso, basta listá-las em sequência separadas por espaços em branco. Com isso, haverá um AND implícito entre cada expressão, e todas elas precisarão ser atendidas para que um documento seja recuperado. Você pode adicionar explicitamente os operadores AND e OR entre as 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"`	Essas consultas recuperam todos os pianos Steinway. Com o espaço entre os termos, o AND fica implícito na pesquisa, e a segunda forma o torna explícito.
`"product=piano AND NOT manufacturer=steinway"`	Recupera todos os pianos que não sejam Steinway.
`"product=piano AND price<2000"`	Esta consulta recupera pianos baratos.

Como misturar pesquisas globais e de campo

Uma string de consulta pode conter infinitas expressões de pesquisa global e de campo. Os espaços entre as expressões são tratados como AND. Também é possível usar OR e AND explicitamente com parênteses. Cada expressão será processada de acordo com as regras associadas ao tipo de termo.

String de consulta	Comentários
`"keyboard great price<5000" "keyboard AND great AND price<5000"`	Recupera os documentos em que as palavras "great" e "keyboard" aparecem em qualquer campo atômico, de texto ou HTML e que tenham um campo de preço inferior a 5.000. O `AND` está implícito, e a segunda forma é equivalente.
`"keyboard OR product=piano"`	Recupera documentos com um campo de produto que contenha "piano" ou documentos com qualquer campo atômico, de texto ou HTML que contenha "keyboard".