Esta página foi traduzida pela API Cloud Translation.

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.

É possível usar uma instância da , da classe Query como argumento para search() para alterar essas opções.

O struct classe Query permitem especificar quantos documentos retornar por vez. Com ela, também é possível 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, o também pode incluir uma instância SortOptions da classe. 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.

Os construtores QueryOptions e SortOptions usam argumentos nomeados, conforme mostrado neste exemplo:

def query_options():
    index = search.Index('products')
    query_string = "product: piano AND price < 5000"

    # Create sort options to sort on price and brand.
    sort_price = search.SortExpression(
        expression='price',
        direction=search.SortExpression.DESCENDING,
        default_value=0)
    sort_brand = search.SortExpression(
        expression='brand',
        direction=search.SortExpression.DESCENDING,
        default_value="")
    sort_options = search.SortOptions(expressions=[sort_price, sort_brand])

    # Create field expressions to add new fields to the scored documents.
    price_per_note_expression = search.FieldExpression(
        name='price_per_note', expression='price/88')
    ivory_expression = search.FieldExpression(
        name='ivory', expression='snippet("ivory", summary, 120)')

    # Create query options using the sort options and expressions created
    # above.
    query_options = search.QueryOptions(
        limit=25,
        returned_fields=['model', 'price', 'description'],
        returned_expressions=[price_per_note_expression, ivory_expression],
        sort_options=sort_options)

    # Build the Query and run the search
    query = search.Query(query_string=query_string, options=query_options)
    results = index.search(query)
    for scored_document in results:
        print(scored_document)

QueryOptions

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 `number_found_accuracy`
`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 abordados na página Como processar resultados .	Nulo. Os resultados incluirão todos os documentos correspondentes (até o limite).	-
`sort_options`	Defina um `SortOptions` objeto 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
`ids_only`	Defina como `True` ou `False`. Quando `True`, os documentos retornados nos resultados conterão apenas IDs, sem campos.	`False` (retorna todos os campos).
`returned_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).
`returned_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
`snippeted_fields`	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 `returned_expressions` 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.

Propriedade	Descrição	Padrão
`expressions`	Uma partes de `SortExpressions` que representa uma classificação multidimensional de documentos.	Nenhum
`match_scorer`	An optional `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`. 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
limite	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 em a 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 será `ASCENDING` ou `DESCENDING`.
`default_value`	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, garanta 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 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 integradas. 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.