Quando chama o método Index.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 estrutura SearchOptions como argumento para Search para alterar estas opções.
A estrutura SearchOptions 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 usando expressões de campos (campos com valores derivados de outros campos no documento).
Além das opções de consulta, a estrutura `SearchOptions` também pode incluir uma instância da estrutura SortOptions. As opções de ordenação permitem-lhe alterar a ordem de ordenação e ordenar os resultados por várias chaves.
SearchOptions
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 |
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 deslocamento são abordados na página de referência da pesquisa Go. | Nulo. Os resultados contêm todos os documentos correspondentes (até ao limite). | - |
Sort |
Defina uma estrutura 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 |
|---|---|---|
IDsOnly |
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). |
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). |
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 |
SortOptions
As propriedades de SortOptions controlam a ordenação e a pontuação dos resultados da pesquisa.
| Propriedade | Descrição | Predefinição |
|---|---|---|
Expressions |
Uma fatia de SortExpressions que representa uma ordenação multidimensional de documentos. |
Nenhum |
Scorer |
Um Scorer 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. 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 |
|---|---|---|
Expr |
Uma expressão a ser avaliada ao ordenar os resultados de cada documento correspondente. | Nenhum |
Reverse |
Se true inverter a ordem dos resultados da pesquisa para que apareçam por ordem ascendente (em vez da ordem descendente predefinida). |
false |
Default |
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 campo (que são definidas no
SearchOptions) e expressões de ordenação, que são
definidas no 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 Scorer 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.