Observação: o Go 1.11 chegou ao fim do suporte em 30 de janeiro de 2024. Os aplicativos Go 1.11 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 Go.

Opções de consulta e classificação

Quando você chama o método Index.Search usando apenas uma string de consulta, os resultados são retornados de acordo com as opções de consulta padrão:

Os documentos são retornados classificados na ordem decrescente.
Os documentos são retornados em grupos de 20 por vez.
Os documentos recuperados contêm todos os campos originais.

Use uma instância da estrutura SearchOptions como argumento para Search para alterar essas opções.

A estrutura SearchOptions permite especificar quantos documentos retornar por vez. além de personalizar o conteúdo dos documentos recuperados. É possível solicitar apenas identificadores de documento ou que os documentos contenham somente um subconjunto dos campos. Crie também campos personalizados nos documentos recuperados usando expressões de campo (campos com valores derivados de outros campos no documento).

Além das opções de consulta, a estrutura "SearchOptions" pode incluir uma instância da estrutura SortOptions. Com as opções de classificação, é possível alterar a ordem de classificação e agrupar os resultados em várias chaves.

SearchOptions

Essas propriedades controlam a quantidade e a ordem dos resultados retornados. As opções de deslocamento e cursor, mutuamente exclusivas, são compatíveis com a paginação. Elas especificam quais documentos selecionados são retornados nos resultados.

Propriedade	Descrição	Padrão	Máximo
`Limit`	O número máximo de documentos a serem retornados nos resultados.	20	1000
`Offset`	O deslocamento do primeiro documento nos resultados a serem retornados.	0. Os resultados incluirão todos os documentos correspondentes (até o limite).	1.000
`Cursor`	Um cursor pode ser usado no lugar de um deslocamento para recuperar grupos de documentos em ordem classificada. Um cursor é atualizado à medida que é passado para dentro e fora de consultas consecutivas, permitindo que cada nova pesquisa continue a partir do fim da anterior. O cursor e o deslocamento são abordados na página de referência de pesquisa do Go.	Nulo. Os resultados incluirão todos os documentos correspondentes (até o limite).	-
`Sort`	Defina uma estrutura `SortOptions` para controlar a ordem dos resultados da pesquisa. Uma instância de `SortOptions` tem seu próprio conjunto de propriedades descritas abaixo.	Nulo. Classificar diminuindo a classificação do documento.	-

Essas propriedades controlam quais campos do documento são exibidos nos resultados.

Propriedade	Descrição	Padrão
`IDsOnly`	Defina como `true` ou `false`. Quando `true`, os documentos retornados nos resultados conterão apenas IDs, sem campos.	`false` (retorna todos os campos).
`Fields`	Especifica quais campos do documento precisam ser incluídos nos resultados. Não é possível especificar mais de 100 campos.	Retornar todos os campos do documento (até 100 campos).
`Expressions`	Expressões de campo que descrevem campos processados adicionados a cada documento retornado nos resultados da pesquisa. Esses campos são adicionados à propriedade "expressions" do documento. O valor do campo é especificado escrevendo uma expressão que pode incluir um ou mais campos do documento.	Nenhum

SortOptions

As propriedades de SortOptions controlam a ordem e a pontuação dos resultados da pesquisa.

Propriedade	Descrição	Padrão
`Expressions`	Um trecho de `SortExpressions` que representa uma classificação multidimensional de documentos.	Nenhum
`Scorer`	um `Scorer` (em inglês) opcional; Quando presente, fará os documentos serem pontuados de acordo com a frequência do termo de pesquisa. A pontuação estará disponível como o campo `_score`. A pontuação de documentos pode ser cara, tanto em termos de operações faturáveis quanto de tempo de execução, e pode deixar as pesquisas lentas. Use a pontuação com moderação.	Nenhum
`Limit`	Número máximo de objetos para pontuar e/ou classificar. Não pode ser mais que 10.000.	1.000

Como classificar várias chaves

É possível ordenar os resultados da pesquisa em várias chaves de classificação. Cada chave é um nome de campo simples ou um valor calculado com base em vários campos. Essa expressão é construída de acordo com as regras na próxima seção.

Um SortExpression também define a direção da classificação e um valor de chave padrão a ser usado, caso a expressão não seja calculada para um documento. Veja a seguir a lista completa de propriedades:

Propriedade	Descrição	Padrão
`Expr`	Uma expressão a ser avaliada durante a classificação de resultados para cada documento correspondente.	Nenhum
`Reverse`	Se `true`, inverta a ordem dos resultados da pesquisa. Desse modo, eles serão exibidos em ordem crescente, e não no padrão decrescente.	`false`
`Default`	O valor padrão da expressão, se nenhum campo estiver presente e não puder ser calculado para um documento. Um valor de texto precisa ser especificado para classificações de texto. Um valor numérico precisa ser especificado para classificações numéricas.	Nenhum

Como classificar campos com vários valores

Quando você classifica um campo com vários valores de um determinado tipo, somente o primeiro valor atribuído ao campo é usado. Por exemplo, considere dois documentos, DocA e DocB, que têm um campo de texto chamado "cor". Dois valores são atribuídos ao campo "cor" de DocA na ordem (vermelho, azul), e dois valores ao DocB na ordem (verde, vermelho). Quando você executa uma classificação especificando o campo de texto "cor", o DocA é classificado no valor "vermelho" e o DocB no valor "verde". Os outros valores de campo não são usados na classificação.

Classificar ou não classificar

Caso nenhuma opção de classificação seja especificada, os resultados da pesquisa serão retornados automaticamente na classificação decrescente. Não há limite para o número de documentos retornados nesse caso. Por outro lado, ao especificar qualquer opção de classificação, ela será realizada depois que todos os documentos correspondentes forem selecionados. Há uma propriedade explícita, SortOptions.Limit, que controla o tamanho da classificação. Não é possível classificar mais de 10.000 documentos. O padrão é 1.000. Quando o número de documentos correspondentes é maior do que o número especificado por SortOptions.Limit, a pesquisa apenas recupera, classifica e retorna esse número limitado. Ela seleciona os documentos para classificação na lista de todos os documentos correspondentes, que está em ordem decrescente. Talvez o número de documentos correspondentes selecionados por uma consulta seja maior do que é possível classificar. Quando você utilizar as opções de classificação e for importante recuperar todos os documentos correspondentes, tente garantir que sua consulta não retorne mais documentos do que é possível para o processo.

Como escrever expressões

As expressões são usadas para definir expressões de campo (que são definidas no SearchOptions) e expressões de classificação, que são definidas no SortOptions. Elas são escritas como strings:

"price * quantity"
"(men + women)/2"
"min(daily_use, 10) * rate"
"snippet('rose', flower, 120)"

As expressões que envolvem campos numéricos usam os operadores aritméticos (+, -, *, /) e as funções numéricas integradas listadas abaixo. As expressões que envolvem campos de geoponto usam as funções de geoponto e distância. As expressões para campos de texto e HTML podem usar a função de snippet.

As expressões também podem incluir estes termos especiais:

Termo	Descrição
`_rank`	Propriedade rank de um documento. Pode ser usada em expressões de campo e de classificação.
`_score`	A pontuação atribuída a um documento quando você inclui um `Scorer` no `SortOptions`. Esse termo só pode ser exibido em expressões de classificação. Ele não pode ser usado em expressões de campo.

Funções numéricas

As expressões para definir valores numéricos para FieldExpressions e SortExpressions podem usar essas funções incorporadas. Os argumentos precisam ser números, nomes de campo ou expressões que usam números e nomes de campo.

Função	Descrição	Exemplo
`max`	Retorna o maior dos argumentos.	`max(recommended_retail_price, discount_price, wholesale_price)`
`min`	Retorna o menor dos argumentos.	`min(height, width, length)`
`log`	Retorna o logaritmo natural.	`log(x)`
`abs`	Retorna o valor absoluto.	`abs(x)`
`pow`	Utiliza dois argumentos numéricos. A chamada pow(x, y) calcula o valor de x elevado à potência y.	`pow(x, 2)`
`count`	Utiliza um nome de campo como argumento. Retorna o número de campos no documento com esse nome. Lembre-se de que um documento pode conter vários campos de tipos diferentes com o mesmo nome. Observação: `count` só pode ser usado em `FieldExpressions`. Ele não pode aparecer em `SortExpressions`.	`count(user)`

Funções de geoponto

Essas funções podem ser usadas em expressões que envolvem campos de geoponto.

Função	Descrição	Exemplo
`geopoint`	Define um geoponto considerando latitude e longitude.	`geopoint(-31.3, 151.4)`
`distance`	Calcula a distância em metros entre dois geopontos. Qualquer um dos dois argumentos pode ser o nome de um campo de geoponto ou uma invocação da função de geoponto. No entanto, somente um argumento pode ser o nome de um campo.	`distance(geopoint(23, 134), store_location)`

Snippets

Snippet é um fragmento de um campo de texto que corresponde a uma string de consulta e inclui o texto próximo. Os snippets são criados chamando a função snippet:

snippet(query, body, [max_chars])

query: Uma string de consulta entre aspas especificando o texto a ser localizado no campo.
body: O nome de um campo de texto, HTML ou Atom.
max_chars: O número máximo de caracteres a serem retornados no snippet. Esse argumento é opcional. O padrão é de 160 caracteres.

A função retorna uma string HTML. A string contém um snippet do valor do campo de corpo, com o texto correspondente à consulta em negrito.