Consultando no Azure Pesquisa CognitivaQuerying in Azure Cognitive Search

O Azure Pesquisa Cognitiva oferece uma linguagem de consulta avançada para dar suporte a uma ampla gama de cenários, da pesquisa de texto livre, a padrões de consulta altamente especificados.Azure Cognitive Search offers a rich query language to support a broad range of scenarios, from free text search, to highly-specified query patterns. Este artigo descreve as solicitações de consulta e os tipos de consultas que você pode criar.This article describes query requests, and what kinds of queries you can create.

No Pesquisa Cognitiva, uma consulta é uma especificação completa de uma operação de viagem de ida e search volta, com parâmetros que informam a execução da consulta e moldam a resposta que retorna.In Cognitive Search, a query is a full specification of a round-trip search operation, with parameters that both inform query execution and shape the response coming back. Os parâmetros e os analisadores determinam o tipo de solicitação de consulta.Parameters and parsers determine the type of query request. O exemplo de consulta a seguir é uma consulta de texto livre com um operador booliano, usando os documentos de pesquisa (API REST), direcionando a coleção de documentos Hotéis-Sample-index .The following query example is a free text query with a boolean operator, using the Search Documents (REST API), targeting the hotels-sample-index documents collection.

POST https://[service name].search.windows.net/indexes/hotels-sample-index/docs/search?api-version=2020-06-30
{
    "queryType": "simple",
    "searchMode": "all",
    "search": "restaurant +view",
    "searchFields": "HotelName, Description, Address/City, Address/StateProvince, Tags",
    "select": "HotelName, Description, Address/City, Address/StateProvince, Tags",
    "top": "10",
    "count": "true",
    "orderby": "Rating desc"
}

Os parâmetros usados durante a execução da consulta incluem:Parameters used during query execution include:

  • queryType define o analisador, que é o analisador de consulta simples padrão (ideal para pesquisa de texto completo) ou o analisador de consulta Lucene completo usado para constructos de consulta avançada, como expressões regulares, pesquisa de proximidade, pesquisa difusa e de curinga, para citar alguns.queryType sets the parser, which is either the default simple query parser (optimal for full text search), or the full Lucene query parser used for advanced query constructs like regular expressions, proximity search, fuzzy and wildcard search, to name a few.

  • searchMode Especifica se as correspondências se baseiam em critérios "todos" ou em "qualquer" na expressão.searchMode specifies whether matches are based on "all" criteria or "any" criteria in the expression. O padrão é Any.The default is any.

  • search fornece os critérios de correspondência, geralmente os termos ou frases inteiras, com ou sem operadores.search provides the match criteria, usually whole terms or phrases, with or without operators. Qualquer campo atribuído como pesquisável no esquema de índice é um candidato para esse parâmetro.Any field that is attributed as searchable in the index schema is a candidate for this parameter.

  • searchFields restringe a execução da consulta a campos pesquisáveis específicos.searchFields constrains query execution to specific searchable fields. Durante o desenvolvimento, é útil usar a mesma lista de campos para Select e Search.During development, it's helpful to use the same field list for select and search. Caso contrário, uma correspondência pode ser baseada em valores de campo que você não pode ver nos resultados, criando incertezas sobre por que o documento foi retornado.Otherwise a match might be based on field values that you can't see in the results, creating uncertainty as to why the document was returned.

Parâmetros usados para formatar a resposta:Parameters used to shape the response:

  • select Especifica quais campos retornar na resposta.select specifies which fields to return in the response. Somente os campos marcados como recuperáveis no índice podem ser usados em uma instrução SELECT.Only fields marked as retrievable in the index can be used in a select statement.

  • top Retorna o número especificado de documentos de melhor correspondência.top returns the specified number of best-matching documents. Neste exemplo, apenas 10 ocorrências são retornadas.In this example, only 10 hits are returned. Você pode usar top e Skip (não mostrado) para paginar os resultados.You can use top and skip (not shown) to page the results.

  • count informa quantos documentos em todo o índice correspondem em geral, o que pode ser maior que o retornado.count tells you how many documents in the entire index match overall, which can be more than what are returned.

  • orderby será usado se você quiser classificar os resultados por um valor, como uma classificação ou um local.orderby is used if you want to sort results by a value, such as a rating or location. Caso contrário, o padrão é usar a pontuação de relevância para classificar os resultados.Otherwise, the default is to use the relevance score to rank results. Um campo deve ser atribuído como classificável para ser um candidato para esse parâmetro.A field must be attributed as sortable to be a candidate for this parameter.

A lista acima é representativa, mas não exaustiva.The above list is representative but not exhaustive. Para obter a lista completa de parâmetros em uma solicitação de consulta, consulte Pesquisar documentos (API REST).For the full list of parameters on a query request, see Search Documents (REST API).

Tipos de consultasTypes of queries

Com algumas exceções notáveis, uma solicitação de consulta itera em índices invertidos que são estruturados para verificações rápidas, em que uma correspondência pode ser encontrada em potencialmente qualquer campo, dentro de qualquer número de documentos de pesquisa.With a few notable exceptions, a query request iterates over inverted indexes that are structured for fast scans, where a match can be found in potentially any field, within any number of search documents. Em Pesquisa Cognitiva, a principal metodologia para localizar correspondências é a pesquisa de texto completo ou filtros, mas você também pode implementar outras experiências de pesquisa conhecidas como preenchimento automático ou pesquisa de localização geográfica.In Cognitive Search, the primary methodology for finding matches is either full text search or filters, but you can also implement other well-known search experiences like autocomplete, or geo-location search. O restante deste artigo resume as consultas no Pesquisa Cognitiva e fornece links para mais informações e exemplos.The rest of this article summarizes queries in Cognitive Search and provides links to more information and examples.

Se o seu aplicativo de pesquisa incluir uma caixa de pesquisa que coleta entradas de termo, a pesquisa de texto completo provavelmente será a operação de consulta que está fazendo o backup dessa experiência.If your search app includes a search box that collects term inputs, then full text search is probably the query operation backing that experience. A pesquisa de texto completo aceita termos ou frases passados em um search parâmetro em todos os campos pesquisáveis no índice.Full text search accepts terms or phrases passed in a search parameter in all searchable fields in your index. Operadores boolianos opcionais na cadeia de caracteres de consulta podem especificar critérios de inclusão ou exclusão.Optional boolean operators in the query string can specify inclusion or exclusion criteria. O analisador simples e o analisador completo dão suporte à pesquisa de texto completo.Both the simple parser and full parser support full text search.

No Pesquisa Cognitiva, a pesquisa de texto completo é criada no mecanismo de consulta do Apache Lucene.In Cognitive Search, full text search is built on the Apache Lucene query engine. As cadeias de caracteres de consulta na pesquisa de texto completo passam por análise lexical para tornar as verificações mais eficientes.Query strings in full text search undergo lexical analysis to make scans more efficient. A análise inclui todos os termos de maiúsculas e minúsculas, removendo palavras de parada como "a" e reduzindo os termos para formulários raiz primitivos.Analysis includes lower-casing all terms, removing stop words like "the", and reducing terms to primitive root forms. O analisador padrão é o Lucene padrão.The default analyzer is Standard Lucene.

Quando termos correspondentes são encontrados, o mecanismo de consulta reconstitui um documento de pesquisa que contém a correspondência usando a chave ou ID do documento para montar valores de campo, classifica os documentos em ordem de relevância e retorna os 50 principais (por padrão) na resposta ou em um número diferente, se você tiver especificado top .When matching terms are found, the query engine reconstitutes a search document containing the match using the document key or ID to assemble field values, ranks the documents in order of relevance, and returns the top 50 (by default) in the response or a different number if you specified top.

Se você estiver implementando a pesquisa de texto completo, entender como o conteúdo é indexado ajudará você a depurar quaisquer anomalias de consulta.If you're implementing full text search, understanding how your content is tokenized will help you debug any query anomalies. As consultas em cadeias de caracteres hifenizadas ou especiais podem precisar usar um analisador diferente do padrão Lucene padrão para garantir que o índice contenha os tokens corretos.Queries over hyphenated strings or special characters could necessitate using an analyzer other than the default standard Lucene to ensure the index contains the right tokens. Você pode substituir o padrão por analisadores de linguagem ou analisadores especializados que modificam a análise léxica.You can override the default with language analyzers or specialized analyzers that modify lexical analysis. Um exemplo é a palavra-chave que trata todo o conteúdo de um campo como um único token.One example is keyword that treats the entire contents of a field as a single token. É útil para dados como códigos postais, IDs e alguns nomes de produtos.This is useful for data like zip codes, IDs, and some product names. Para obter mais informações, consulte pesquisa de termo parcial e padrões com caracteres especiais.For more information, see Partial term search and patterns with special characters.

Se você antecipar o uso intensivo de operadores boolianos, o que é mais provável em índices que contêm blocos de texto Grandes (um campo de conteúdo ou descrições longas), certifique-se de testar as consultas com o searchMode=Any|All parâmetro para avaliar o impacto dessa configuração na pesquisa booleana.If you anticipate heavy use of Boolean operators, which is more likely in indexes that contain large text blocks (a content field or long descriptions), be sure to test queries with the searchMode=Any|All parameter to evaluate the impact of that setting on boolean search.

Preenchimento automático e consultas sugeridasAutocomplete and suggested queries

Os resultados de preenchimento automático ou sugerido são alternativas ao que disparam search solicitações de consulta sucessivas com base em entradas de cadeias de caracteres parciais (depois de cada caractere) em uma experiência de pesquisa conforme o tipo.Autocomplete or suggested results are alternatives to search that fire successive query requests based on partial string inputs (after each character) in a search-as-you-type experience. Você pode usar autocomplete suggestions o e oparâmetro juntos ou separadamente, conforme descrito neste tutorial, mas não pode usá-los com o search .You can use autocomplete and suggestions parameter together or separately, as described in this tutorial, but you cannot use them with search. Os termos concluídos e as consultas sugeridas são derivados do conteúdo do índice.Both completed terms and suggested queries are derived from index contents. O mecanismo nunca retornará uma cadeia de caracteres ou sugestão que não existe em seu índice.The engine will never return a string or suggestion that is non-existent in your index. Para obter mais informações, consulte preenchimento automático (API REST) e sugestões (API REST).For more information, see Autocomplete (REST API) and Suggestions (REST API).

Os filtros são amplamente usados em aplicativos que incluem Pesquisa Cognitiva.Filters are widely used in apps that include Cognitive Search. Em páginas de aplicativo, os filtros são geralmente visualizados como facetas em estruturas de navegação de link para filtragem direcionada pelo usuário.On application pages, filters are often visualized as facets in link navigation structures for user-directed filtering. Os filtros também são usados internamente para expor fatias de conteúdo indexado.Filters are also used internally to expose slices of indexed content. Por exemplo, você pode inicializar uma página de pesquisa usando um filtro em uma categoria de produto ou um idioma se um índice contiver campos em inglês e em francês.For example, you might initialize a search page using a filter on a product category, or a language if an index contains fields in both English and French.

Você também pode precisar de filtros para invocar um formulário de consulta especializado, conforme descrito na tabela a seguir.You might also need filters to invoke a specialized query form, as described in the following table. Você pode usar um filtro com uma pesquisa não especificada ( search=* ) ou com uma cadeia de caracteres de consulta que inclua termos, frases, operadores e padrões.You can use a filter with an unspecified search (search=*) or with a query string that includes terms, phrases, operators, and patterns.

Cenário de filtroFilter scenario DescriçãoDescription
filtros de intervaloRange filters No Pesquisa Cognitiva do Azure, as consultas de intervalo são criadas usando o parâmetro de filtro.In Azure Cognitive Search, range queries are built using the filter parameter. Para obter mais informações e exemplos, consulte exemplo de filtro de intervalo.For more information and examples, see Range filter example.
Pesquisa de localização geográficaGeo-location search Se um campo pesquisável for do tipo EDM. GeographyPoint, você poderá criar uma expressão de filtro para "localizar perto de mim" ou controles de pesquisa baseados em mapa.If a searchable field is of Edm.GeographyPoint type, you can create a filter expression for "find near me" or map-based search controls. Os campos que orientam a pesquisa geográfica contêm coordenadas.Fields that drive geo-search contain coordinates. Para obter mais informações e um exemplo, consulte exemplo de pesquisa geográfica.For more information and an example, see Geo-search example.
Navegação facetadaFaceted navigation Uma estrutura de navegação de faceta se torna fundamental na navegação orientada pelo usuário quando você invoca um filtro em resposta a um onclick evento em uma faceta.A facet navigation structure becomes instrumental in user-directed navigation when you invoke a filter in response to an onclick event on a facet. Assim, as facetas e os filtros são disponibilizados em mãos.As such, facets and filters go hand-in-hand. Se você adicionar navegação de faceta, precisará de filtros para concluir a experiência.If you add facet navigation, you will need filters to complete the experience. Para obter mais informações, consulte como criar um filtro de faceta.For more information, see How to build a facet filter.

Observação

O texto usado em uma expressão de filtro não é analisado durante o processamento da consulta.Text that's used in a filter expression is not analyzed during query processing. Presume-se que a entrada de texto seja um padrão de caracteres textualmente sensível a maiúsculas e minúsculas que seja bem-sucedida ou falhe na correspondência.The text input is presumed to be a verbatim case-sensitive character pattern that either succeeds or fails on the match. As expressões de filtro são construídas usando a sintaxe do OData e passadas em um filter parâmetro em todos os campos filtráveis no índice.Filter expressions are constructed using OData syntax and passed in a filter parameter in all filterable fields in your index. Para obter mais informações, consulte filtros no Azure pesquisa cognitiva.For more information, see Filters in Azure Cognitive Search.

Pesquisa de documentosDocument look-up

Em contraste com os formulários de consulta descritos anteriormente, este recupera um único documento de pesquisa por ID, sem nenhuma pesquisa de índice ou verificação correspondente.In contrast with the previously described query forms, this one retrieves a single search document by ID, with no corresponding index search or scan. Apenas um documento é solicitado e retornado.Only the one document is requested and returned. Quando um usuário seleciona um item nos resultados da pesquisa, recuperando o documento e preenchendo uma página de detalhes com campos é uma resposta típica e uma pesquisa de documento é a operação que dá suporte a ela.When a user selects an item in search results, retrieving the document and populating a details page with fields is a typical response, and a document look-up is the operation that supports it.

Pesquisa avançada: difusa, curinga, proximidade, RegexAdvanced search: fuzzy, wildcard, proximity, regex

Um formulário de consulta avançada depende do analisador de Lucene completo e dos operadores que disparam um comportamento de consulta específico.An advanced query form depends on the Full Lucene parser and operators that trigger a specific query behavior.

Tipo de consultaQuery type UsoUsage Obter mais informações e exemplosExamples and more information
Pesquisa em campoFielded search search meter queryType=fullsearch parameter, queryType=full Crie uma expressão de consulta composta visando um único campo.Build a composite query expression targeting a single field.
Exemplo de pesquisa em campoFielded search example
pesquisa difusafuzzy search search meter queryType=fullsearch parameter, queryType=full Corresponde a termos com construção ou ortografia semelhantes.Matches on terms having a similar construction or spelling.
Exemplo de pesquisa difusaFuzzy search example
pesquisa por proximidadeproximity search search meter queryType=fullsearch parameter, queryType=full Descobre condições que estão próximos uns dos outros em um documento.Finds terms that are near each other in a document.
Exemplo de pesquisa por proximidadeProximity search example
aumento de termoterm boosting search meter queryType=fullsearch parameter, queryType=full Classifica um documento mais alto se ele contiver o termo potencializado, em relação a outros que não contêm.Ranks a document higher if it contains the boosted term, relative to others that don't.
Exemplo de aumento de termoTerm boosting example
pesquisa de expressão regularregular expression search search meter queryType=fullsearch parameter, queryType=full Correspondências com base no conteúdo de uma expressão regular.Matches based on the contents of a regular expression.
Exemplo de expressão regularRegular expression example
pesquisa de curinga ou prefixowildcard or prefix search search parâmetro com * ~ ou ? , queryType=fullsearch parameter with *~ or ?, queryType=full Correspondências baseadas em um prefixo e til (~) ou caractere único (?).Matches based on a prefix and tilde (~) or single character (?).
Exemplo de pesquisa de curingaWildcard search example

Próximas etapasNext steps

Para uma análise mais detalhada da implementação da consulta, examine os exemplos de cada sintaxe.For a closer look at query implementation, review the examples for each syntax. Se você for novo na pesquisa de texto completo, uma análise mais detalhada do que o mecanismo de consulta pode ser uma opção igualmente boa.If you are new to full text search, a closer look at what the query engine does might be an equally good choice.