Observação: o Java 8 chegou ao fim do suporte em 31 de janeiro de 2024. Os aplicativos Java 8 atuais continuarão a ser executados e recebendo 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 Java.

Opções de consulta e classificação

Quando você chama o método 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 classe Query como argumento de search() para alterar essas opções.

Com a classe Query, você especifica quantos documentos retornar por vez, além de personalizar o conteúdo dos documentos recuperados. É possível apenas solicitar identificadores de documento ou que os documentos contenham somente um subconjunto dos campos. Além disso, é possível criar campos personalizados nos documentos recuperados: snippets (fragmentos de campos de texto que mostram o texto em torno de uma string correspondente) e expressões de campo (campos com valores derivados de outros campos no documento).

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

Pesquisar com a classe Query

Ao pesquisar com uma instância da classe Query, você precisa construir uma instância da classe em várias etapas. Esta é a ordem geral:

Criar uma string de consulta.
Criar SortOptions se necessário.
Criar QueryOptions.
Criar um objeto Query que inclua a string de consulta e o QueryOptions (opcional).
Chamar o método de pesquisa no objeto Query.

As várias opções de consulta e classificação são especificadas chamando métodos setter em instâncias das classes QueryOptions.Builder e SortOptions.Builder, como neste exemplo:

try {
  // Build the SortOptions with 2 sort keys
  SortOptions sortOptions =
      SortOptions.newBuilder()
          .addSortExpression(
              SortExpression.newBuilder()
                  .setExpression("price")
                  .setDirection(SortExpression.SortDirection.DESCENDING)
                  .setDefaultValueNumeric(0))
          .addSortExpression(
              SortExpression.newBuilder()
                  .setExpression("brand")
                  .setDirection(SortExpression.SortDirection.DESCENDING)
                  .setDefaultValue(""))
          .setLimit(1000)
          .build();

  // Build the QueryOptions
  QueryOptions options =
      QueryOptions.newBuilder()
          .setLimit(25)
          .setFieldsToReturn("model", "price", "description")
          .setSortOptions(sortOptions)
          .build();

  // A query string
  String queryString = "product: coffee roaster AND price < 500";

  //  Build the Query and run the search
  Query query = Query.newBuilder().setOptions(options).build(queryString);
  IndexSpec indexSpec = IndexSpec.newBuilder().setName(indexName).build();
  Index index = SearchServiceFactory.getSearchService().getIndex(indexSpec);
  Results<ScoredDocument> result = index.search(query);
  return result;
} catch (SearchException e) {
  // handle exception...
}

QueryOptions

É necessário usar o QueryOptions.Builder para definir as opções de consulta. Você não tem acesso a essas propriedades diretamente.

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
`NumberFoundAccuracy`	Essa propriedade determina a precisão do resultado retornado por `Results.getNumberFound()`. Estabelece um limite de quantas correspondências são realmente contadas, interrompendo a pesquisa quando o limite é atingido. Se o número de correspondências no índice é menor ou igual ao limite, a contagem retornada é exata. Caso contrário, a contagem é uma estimativa baseada nas correspondências encontradas e no tamanho e na estrutura do índice. Observe que definir um valor alto para essa propriedade pode afetar a complexidade da operação de pesquisa e causar esgotamento de tempo limite.	Se precisão indeterminada estiver definida com o mesmo valor que `Limit`	25.000
`Offset`	O deslocamento do primeiro documento nos resultados a retornar.	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 final da anterior. O cursor e o deslocamento são discutidos na página Como processar os resultados.	Nulo. Os resultados incluirão todos os documentos correspondentes (até o limite).	-
`SortOptions`	Defina um objeto `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
`ReturningIdsOnly`	Defina como `True` ou `False`. Quando `True`, os documentos retornados nos resultados conterão apenas IDs, sem campos.	`False` (retorna todos os campos).
`FieldsToReturn`	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).
`ExpressionsToReturn`	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
`FieldsToSnippet`	Uma lista de nomes de campos de texto. Um snippet é gerado para cada campo. É um campo calculado adicionado à propriedade de expressões dos documentos nos resultados da pesquisa. O campo do snippet tem o mesmo nome do campo de origem. Essa opção usa implicitamente a função de snippet com apenas dois argumentos, criando um snippet com no máximo uma string correspondente, com base na mesma string de consulta usada para recuperar os resultados: `snippet("query-string", field-name)`. Também é possível criar snippets personalizados com a opção `ExpressionsToReturn` adicionando uma expressão de campo que chame explicitamente a função de snippet.	Nenhum

SortOptions

As propriedades de SortOptions controlam a ordem e a pontuação dos resultados da pesquisa. É necessário usar o SortOptions.Builder para definir as opções de classificação. Você não tem acesso a essas propriedades diretamente.

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

Propriedade	Descrição	Padrão
`SortExpressions`	Uma lista de `SortExpressions` que representa uma classificação multidimensional de documentos.	Nenhum
`MatchScorer`	Um objeto `MatchScorer` 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`. Os documentos de pontuação podem ser caros, tanto em termos de operações faturáveis quanto de tempo de execução, e podem 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. O termo "expressão" é usado com vários significados quando se fala sobre opções de classificação: o próprio SortOption tem um atributo de expressões. Esse atributo é uma lista de objetos SortExpression que correspondem a chaves de classificação. Por fim, cada objeto SortExpression contém um atributo de expressão que especifica como calcular o valor da chave de classificação. 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
`Expression`	Uma expressão a ser avaliada durante a classificação de resultados para cada documento correspondente.	Nenhum
`Direction`	A direção de classificação dos resultados da pesquisa, `ASCENDING` ou `DESCENDING`.	`DESCENDING`
`DefaultValue` `DefaultValueDate` `DefaultValueNumber`	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 as expressões de campo, que são configuradas em `QueryOptions`, e as expressões de classificação, que são configuradas em 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 `MatchScorer` 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.