O Python 2.7 atingiu o fim do suporte e vai ser descontinuado a 31 de janeiro de 2026. Após a descontinuação, não vai poder implementar aplicações Python 2.7, mesmo que a sua organização tenha usado anteriormente uma política organizacional para reativar as implementações de runtimes antigos. As suas aplicações Python 2.7 existentes vão continuar a ser executadas e a receber tráfego após a data de descontinuação. Recomendamos que migre para a versão suportada mais recente do Python.

Esta página foi traduzida pela API Cloud Translation.

Opções de consulta e ordenação

Quando chama o método search() usando apenas uma string de consulta, os resultados são devolvidos de acordo com as opções de consulta predefinidas:

Os documentos são devolvidos ordenados por ordem descendente da classificação
Os documentos são devolvidos em grupos de 20 de cada vez
Os documentos obtidos contêm todos os respetivos campos originais

Pode usar uma instância da classe Query como argumento para search() para alterar estas opções.

A classe Query permite-lhe especificar quantos documentos devolver de cada vez. Também lhe permite personalizar o conteúdo dos documentos obtidos. Pode pedir apenas identificadores de documentos ou solicitar que os documentos contenham apenas um subconjunto dos respetivos campos. Também pode criar campos personalizados nos documentos obtidos: fragmentos (fragmentos de campos de texto que mostram o texto que envolve 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 pode incluir uma instância da classe SortOptions. As opções de ordenação permitem-lhe alterar a ordem de ordenação e ordenar os resultados por várias chaves.

Pesquisar com a classe Query

Quando pesquisa com uma instância da classe Query, tem de criar uma instância da classe em vários passos. Esta é a ordem geral:

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

Os construtores QueryOptions e SortOptions usam argumentos com nome, 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

Estas propriedades controlam quantos resultados são devolvidos e em que ordem. As opções de deslocamento e cursor, que são mutuamente exclusivas, suportam a paginação. Especificam que documentos selecionados devem ser devolvidos nos resultados.

Propriedade	Descrição	Predefinição	Máximo
`limit`	O número máximo de documentos a devolver nos resultados.	20	1000
`number_found_accuracy`	Esta propriedade determina a precisão do resultado devolvido por `SearchResults.number_found()`. Define um limite para o número de correspondências que são efetivamente contabilizadas, parando a pesquisa quando o limite é atingido. Se o número de correspondências no índice for inferior ou igual ao limite, a contagem devolvida é exata. Caso contrário, a contagem é uma estimativa baseada nas correspondências encontradas e no tamanho e na estrutura do índice. Tenha em atenção que definir um valor elevado para esta propriedade pode afetar a complexidade da operação de pesquisa e pode causar tempos limite.	Se não for especificado ou for definido como `None`, a precisão é definida com o mesmo valor que `limit`	25000
`offset`	O deslocamento do primeiro documento nos resultados a devolver.	0. Os resultados contêm todos os documentos correspondentes (até ao limite).	1000
`cursor`	Pode usar um cursor em vez de um deslocamento para obter grupos de documentos por ordem alfabética. Um cursor é atualizado à medida que é transmitido para dentro e para fora de consultas consecutivas, o que permite que cada nova pesquisa seja continuada a partir do final da anterior. O cursor e o desvio são abordados na página Processar resultados.	Nulo. Os resultados contêm todos os documentos correspondentes (até ao limite).	-
`sort_options`	Defina um objeto `SortOptions` para controlar a ordenação dos resultados da pesquisa. Uma instância de `SortOptions` tem o seu próprio conjunto de propriedades, que são descritas abaixo.	Nulo. Ordenar por diminuição da classificação do documento.	-

Estas propriedades controlam os campos de documentos que aparecem nos resultados.

Propriedade	Descrição	Predefinição
`ids_only`	Definido como `True` ou `False`. Quando `True`, os documentos devolvidos nos resultados contêm apenas IDs e não campos.	`False` (devolve todos os campos).
`returned_fields`	Especifica os campos de documentos a incluir nos resultados. Não é possível especificar mais de 100 campos.	Devolver todos os campos do documento (até 100 campos).
`returned_expressions`	Expressões de campo que descrevem campos calculados adicionados a cada documento devolvido nos resultados da pesquisa. Estes campos são adicionados à propriedade expressions do documento. O valor do campo é especificado escrevendo uma expressão que pode incluir um ou mais campos de documentos.	Nenhum
`snippeted_fields`	Uma lista de nomes de campos de texto. É gerado um fragmento para cada campo. Este é um campo calculado que é adicionado à propriedade expressions dos documentos nos resultados da pesquisa. O campo do fragmento tem o mesmo nome que o campo de origem. Esta opção usa implicitamente a função de fragmento com apenas dois argumentos, criando um fragmento com, no máximo, uma string correspondente, com base na mesma string de consulta que a pesquisa usou para obter os resultados: `snippet("query-string", field-name)`. Também pode criar fragmentos personalizados com a opção `returned_expressions` adicionando uma expressão de campo que chama explicitamente a função de fragmento.	Nenhum

SortOptions

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

Propriedade	Descrição	Predefinição
`expressions`	Uma lista de `SortExpressions` que representa uma ordenação multidimensional de documentos.	Nenhum
`match_scorer`	Um objeto `MatchScorer` opcional. Quando presente, isto faz com que os documentos sejam classificados de acordo com a frequência do termo de pesquisa. A pontuação vai estar disponível como o campo `_score`. A atribuição de pontuações a documentos pode ser dispendiosa (em termos de operações faturáveis e tempo de execução) e pode tornar as suas pesquisas mais lentas. Use a pontuação com moderação.	Nenhum
`limit`	Número máximo de objetos a classificar e/ou ordenar. Não pode ser superior a 10 000.	1000

Ordenar por várias chaves

Pode ordenar os resultados da pesquisa por várias chaves de ordenação. Cada chave pode ser um nome de campo simples ou um valor calculado a partir de vários campos. Tenha em atenção que o termo "expressão" é usado com vários significados quando se fala sobre opções de ordenação: o SortOption em si tem um atributo expressions. Este atributo é uma lista de SortExpression objetos que correspondem a chaves de ordenação. Por último, cada objeto SortExpression contém um atributo expression que especifica como calcular o valor da chave de ordenação. Esta expressão é criada de acordo com as regras na secção seguinte.

Um SortExpression também define a direção da ordenação e um valor principal predefinido a usar se a expressão não puder ser calculada para um documento. Segue-se a lista completa de propriedades:

Propriedade	Descrição	Predefinição
`expression`	Uma expressão a ser avaliada ao ordenar os resultados de cada documento correspondente.	Nenhum
`direction`	A direção para ordenar os resultados da pesquisa, `ASCENDING` ou `DESCENDING`.	`DESCENDING`
`default_value`	O valor predefinido da expressão, se não estiver presente nenhum campo e não for possível calcular para um documento. Tem de ser especificado um valor de texto para as ordenações de texto. Tem de ser especificado um valor numérico para as ordenações numéricas.	Nenhum

Ordenar campos com vários valores

Quando ordena por um campo com vários valores de um tipo específico, apenas é usado o primeiro valor atribuído ao campo. Por exemplo, considere dois documentos, DocA e DocB, que têm ambos um campo de texto denominado "cor". São atribuídos dois valores ao campo "cor" do DocA pela ordem (vermelho, azul) e dois valores ao DocB pela ordem (verde, vermelho). Quando faz uma ordenação que especifica o campo de texto "cor", o DocA é ordenado pelo valor "vermelho" e o DocB pelo valor "verde". Os outros valores dos campos não são usados na ordenação.

Ordenar ou não ordenar

Se não especificar nenhuma opção de ordenação, os resultados da pesquisa são devolvidos automaticamente ordenados por classificação descendente. Neste caso, não existe limite para o número de documentos devolvidos. Se especificar opções de ordenação, a ordenação é realizada depois de todos os documentos correspondentes terem sido selecionados. Existe uma propriedade explícita, `SortOptions.limit`, que controla o tamanho da ordenação. Nunca pode ordenar mais de 10 000 documentos. O valor predefinido é 1000. Se existirem mais documentos correspondentes do que o número especificado por `SortOptions.limit`, a pesquisa só obtém, ordena e devolve esse número limitado. Seleciona os documentos a ordenar a partir da lista de todos os documentos correspondentes, que está por ordem descendente de classificação. É possível que uma consulta selecione mais documentos correspondentes do que os que pode ordenar. Se estiver a usar opções de ordenação e for importante obter todos os documentos correspondentes, deve tentar garantir que a sua consulta não devolve mais documentos do que os que pode ordenar.

Escrever expressões

As expressões são usadas para definir expressões de campos (que são definidas em `QueryOptions` ) e expressões de ordenação, que são definidas em SortOptions. 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 podem usar os operadores aritméticos (+, -, *, /) e as funções numéricas incorporadas indicadas abaixo. As expressões que envolvem campos de geopontos podem usar as funções de geopontos e distância. As expressões para campos de texto e HTML podem usar a função de fragmento.

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

Vigência	Descrição
`_rank`	A propriedade rank de um documento. Pode ser usado em expressões de campo e expressões de ordenação.
`_score`	A pontuação atribuída a um documento quando inclui um `MatchScorer` no `SortOptions`. Este termo só pode aparecer em expressões de ordenação. 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 estas funções incorporadas. Os argumentos têm de ser números, nomes de campos ou expressões que usem números e nomes de campos.

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

Funções de geoponto

É possível usar estas funções para expressões que envolvem campos de geoponto.

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

Fragmentos

Um fragmento é um fragmento de um campo de texto que corresponde a uma string de consulta e inclui o texto circundante. Os fragmentos são criados chamando a função snippet:

snippet(query, body, [max_chars])

query: Uma string de consulta entre aspas que especifica o texto a encontrar no campo.
body: O nome de um campo de texto, HTML ou atom.
max_chars: O número máximo de carateres a devolver no fragmento. Este argumento é opcional; a predefinição é de 160 carateres.

A função devolve uma string HTML. A string contém um fragmento do valor do campo do corpo, com o texto que correspondeu à consulta em negrito.