Compartilhar via

Pesquisar documentos (API REST da Pesquisa de IA do Azure)

  • Artigo

Uma solicitação de consulta tem como destino a coleção de documentos de um único índice em um serviço de pesquisa. Ele inclui parâmetros que definem os critérios de correspondência e parâmetros que moldam a resposta. A partir da versão 2021-04-30-Preview da API, você também pode usar um alias de índice para direcionar um índice específico em vez de usar o próprio nome de índice.

Você pode usar GET ou POST. Os parâmetros de consulta são especificados na cadeia de caracteres de consulta para solicitações GET e no corpo da solicitação para solicitações POST.

GET https://[service name].search.windows.net/indexes/[index name]/docs?[query parameters] 
  Content-Type: application/json   
  api-key: [admin or query key]

Se você estiver usando POST, adicione a ação "search" como um parâmetro de URI.

POST https://[service name].search.windows.net/indexes/[index name]/docs/search?api-version=[api-version]  
  Content-Type: application/json  
  api-key: [admin or query key]

Quando chamado com GET, o comprimento da URL de solicitação não pode exceder 8 KB. Esse comprimento geralmente é suficiente para a maioria dos aplicativos. No entanto, alguns aplicativos produzem consultas grandes, especificamente quando expressões de filtro OData são usadas. Para esses aplicativos, HTTP POST é uma opção melhor porque permite filtros maiores que GET.

Com o POST, o número de cláusulas em um filtro é o fator limitante, não o tamanho da cadeia de caracteres de filtro não processada, uma vez que o limite de tamanho da solicitação POST é quase 16 MB. Embora o limite de tamanho da solicitação POST seja grande, as expressões de filtro não podem ser arbitrariamente complexas. Para obter mais informações sobre limitações de complexidade de filtro, consulte Sintaxe de expressão OData para Azure AI Search.

Parâmetros de URI

Parâmetro Descrição
[nome do serviço] Obrigatórios. Defina isso como o nome exclusivo definido pelo usuário do serviço de pesquisa.
[nome do índice]/docs Obrigatórios. Especifica a coleção de documentos de um índice nomeado.
[parâmetros de consulta] Os parâmetros de consulta são especificados no URI para solicitações GET e no corpo da solicitação para solicitações POST.
api-version Obrigatórios. A versão estável atual é api-version=2020-06-30. Consulte Versões de API para obter mais versões. Para consultas, a versão da api sempre é especificada como um parâmetro de URI para GET e POST.

Recomendações de codificação de URL

Lembre-se de codificar url parâmetros de consulta específicos ao chamar diretamente a API REST GET. Para uma operação pesquisar documentos , a codificação de URL pode ser necessária para os seguintes parâmetros de consulta:

  • pequisa
  • $filter
  • facet
  • highlightPreTag
  • highlightPostTag

A codificação de URL só é recomendada para parâmetros individuais. Se você usar a codificação de URL inadvertidamente para a cadeia de caracteres de consulta inteira (tudo após o ?), as solicitações são interrompidas.

Além disso, a codificação de URL só é necessária ao se chamar a API REST diretamente usando GET. Nenhuma codificação de URL é necessária ao usar POST ou ao usar a biblioteca de clientes .NET da Pesquisa de IA do Azure, que manipula a codificação para você.

Cabeçalhos de solicitação

A tabela a seguir descreve os cabeçalhos de solicitação necessários e opcionais

Campos Descrição
Tipo de conteúdo Obrigatórios. Defina isso como "application/json"
chave de API Opcional se você estiver usando funções do Azure e um token de portador for fornecido na solicitação, caso contrário, uma chave será necessária. Uma chave de api é uma cadeia de caracteres exclusiva gerada pelo sistema que autentica a solicitação para o serviço de pesquisa. As solicitações de consulta na coleção de documentos podem especificar uma chave de administrador ou chave de consulta como a chave de API. A chave de consulta é usada para operações somente leitura na coleção de documentos. Confira Conectar-se ao Azure AI Search usando a autenticação de chave para obter detalhes.

Corpo da solicitação

Para GET: Nenhum.

Para POST:

{  
     "count": true | false (default),  
     "facets": [ "facet_expression_1", "facet_expression_2", ... ],  
     "filter": "odata_filter_expression",  
     "highlight": "highlight_field_1, highlight_field_2, ...",  
     "highlightPreTag": "pre_tag",  
     "highlightPostTag": "post_tag",  
     "minimumCoverage": # (% of index that must be covered to declare query successful; default 100),  
     "orderby": "orderby_expression",  
     "queryType": "simple" (default) | "full",
     "scoringParameters": [ "scoring_parameter_1", "scoring_parameter_2", ... ],  
     "scoringProfile": "scoring_profile_name",  
     "scoringStatistics" : "local" | "global",
     "search": "simple_query_expression",  
     "searchFields": "field_name_1, field_name_2, ...",  
     "searchMode": "any" (default) | "all",  
     "select": "field_name_1, field_name_2, ...",  
     "sessionId" : "session_id",
     "skip": # (default 0),  
     "top": #  
   }

Continuação de respostas de pesquisa parciais

Às vezes, o Azure AI Search não pode retornar todos os resultados solicitados em uma única resposta de Pesquisa. Isso pode ocorrer por diferentes motivos, como quando a consulta solicita muitos documentos não especificando $top ou especificando um valor grande demais para $top. Nesses casos, o Azure AI Search inclui a @odata.nextLink anotação no corpo da resposta e também @search.nextPageParameters se era uma solicitação POST. Você pode usar os valores dessas anotações para formular outra solicitação Pesquisar para obter a próxima parte da resposta da pesquisa. Isso é chamado de continuação da solicitação Pesquisar original e as anotações geralmente são chamadas de tokens de continuação. Consulte o exemplo em Resposta abaixo para obter detalhes sobre a sintaxe dessas anotações e onde elas aparecem no corpo da resposta.

Os motivos pelos quais o Azure AI Search pode retornar tokens de continuação são específicos da implementação e estão sujeitos a alterações. Clientes robustos devem sempre estar prontos para lidar com casos em que são retornados menos documentos do que o esperado e um token de continuação é incluído para continuar recuperando os documentos. Observe também que você deve usar o mesmo método HTTP que a solicitação original para continuar. Por exemplo, se você tiver enviado uma solicitação GET, quaisquer solicitações de continuação que você enviar também deverão usar GET (e da mesma forma para POST).

Observação

A finalidade de @odata.nextLink e @search.nextPageParameters é proteger o serviço contra consultas que solicitam muitos resultados, não para fornecer um mecanismo geral para paginação. Se você quiser analisar os resultados, use $top e $skip juntos. Por exemplo, se você quiser páginas do tamanho 10, sua primeira solicitação deverá ter $top=10 e $skip=0, a segunda solicitação deve ter $top=10 e $skip=10, a terceira solicitação deve ter $top=10 e $skip=20e assim por diante.

Parâmetros de consulta

Uma consulta aceita vários parâmetros na URL quando chamada com GET e como propriedades JSON no corpo da solicitação quando chamada com POST. A sintaxe para alguns parâmetros é ligeiramente diferente entre GET e POST. Essas diferenças são indicadas conforme aplicável abaixo.

Nome Tipo Descrição
api-version string Obrigatórios. Versão da API REST usada para a solicitação. Para obter uma lista de versões com suporte, consulte Versões da API. Para essa operação, a versão da api é especificada como um parâmetro de URI, independentemente de você chamar Pesquisar Documentos com GET ou POST.
$count booleano Opcional. Os valores válidos são "true" ou "false". O padrão é "false". Quando chamado com POST, esse parâmetro é nomeado count em vez de $count. Especifica se deve buscar a contagem total de resultados. Essa é a contagem de todos os documentos que correspondem aos parâmetros de pesquisa e $filter, ignorando $top e $skip. Definir esse valor como "true" pode prejudicar o desempenho. A contagem será precisa se o índice estiver estável, mas sub-relatará ou relatará em excesso todos os documentos adicionados, atualizados ou excluídos ativamente. Se você quiser obter apenas a contagem sem documentos, poderá usar $top=0.
facetas ou facetas string Opcional. Um campo para facetar por, em que o campo é atribuído como "facetável". Quando chamado com GET, facet é um campo (facet: field1). Quando chamado com POST, esse parâmetro é nomeado facets em vez de facet e é especificado como uma matriz (facets: [field1, field2, field3]). A cadeia de caracteres pode conter parâmetros para personalizar a faceta, expressa como pares nome-valor separados por vírgulas.

Os parâmetros válidos são "count", "sort", "values", "interval" e "timeoffset".

"count" é o número máximo de termos de faceta; o padrão é 10. Não há limite superior no número de termos, mas valores mais altos degradam o desempenho, especialmente se o campo facetado contiver um grande número de termos exclusivos. Por exemplo, "facet=category,count:5" obtém as cinco principais categorias em resultados de faceta. Se o parâmetro count for menor que o número de termos exclusivos, os resultados poderão não ser precisos. Isso ocorre devido à maneira como as consultas de facetamento são distribuídas entre fragmentos. Você pode definir a contagem como zero ou como um valor maior ou igual ao número de valores exclusivos no campo de faceta para obter uma contagem precisa em todos os fragmentos. A compensação é maior latência.

"sort" pode ser definido como "count", "-count", "value", "-value". Use count para classificar decrescente por contagem. Use -count para classificar em ordem crescente por contagem. Use o valor para classificar em ordem crescente por valor. Use -value para classificar decrescente por valor (por exemplo, "facet=category,count:3,sort:count" obtém as três principais categorias em facetas resulta em ordem decrescente pelo número de documentos com cada nome da cidade). Se as três principais categorias são Orçamento, Motel e Luxo, e Orçamento tem 5 acertos, Motel tem 6, e Luxury tem 4, então os buckets estão no pedido Motel, Orçamento, Luxo. Para -value, "facet=rating,sort:-value" produz buckets para todas as classificações possíveis, em ordem decrescente por valor (por exemplo, se as classificações forem de 1 a 5, os buckets serão ordenados 5, 4, 3, 2, 1, independentemente de quantos documentos correspondem a cada classificação).

"valores" podem ser definidos como valores numéricos delimitados por pipe ou Edm.DateTimeOffset especificando um conjunto dinâmico de valores de entrada de faceta (por exemplo, "facet=baseRate,values:10 | 20" produz três buckets: um para a taxa base 0 até, mas não incluindo 10, um para 10 até, mas não incluindo 20, e outro para 20 e superior). Uma cadeia de caracteres "facet=lastRenovationDate,values:2010-02-01T00:00:00Z" produz dois buckets: um para hotéis renovados antes de fevereiro de 2010 e outro para hotéis renovados em 1º de fevereiro de 2010 ou posterior. Os valores devem ser listados em ordem sequencial e crescente para obter os resultados esperados.

"interval" é um intervalo inteiro maior que 0 para números, ou minuto, hora, dia, semana, mês, trimestre, ano para valores de data/hora. Por exemplo, "facet=baseRate,interval:100" produz buckets com base em intervalos de taxa base de tamanho 100. Se as taxas de base forem todas entre US$ 60 e US$ 600, há buckets para 0 a 100, 100 a 200, 300 a 200, 300 a 400, 400 a 500 e 500 a 600. A cadeia de caracteres "facet=lastRenovationDate,interval:year" produz um bucket para cada ano quando os hotéis foram renovados.

"timeoffset" pode ser definido como ([+-]hh:mm, [+-]hhmm ou [+-]hh). Se usado, o parâmetro timeoffset deve ser combinado com a opção de intervalo e somente quando aplicado a um campo do tipo Edm.DateTimeOffset. O valor especifica o deslocamento de hora em relação ao UTC para compensar ao definir limites de tempo. Por exemplo: "facet=lastRenovationDate,interval:day,timeoffset:-01:00" usa o limite de dia que começa às 01:00:00 UTC (meia-noite no fuso horário de destino).

count e sort podem ser combinados na mesma especificação de faceta, mas não podem ser combinados com intervalo ou valores, e intervalo e valores não podem ser combinados juntos.

As facetas de intervalo na hora da data são calculadas com base na hora UTC se o timeoffset não for especificado. Por exemplo: para "facet=lastRenovationDate,interval:day", o limite do dia começa em 00:00:00 UTC.
$filter string Opcional. Uma expressão de pesquisa estruturada na sintaxe do OData padrão. Somente campos filtreáveis podem ser usados em um filtro. Ao chamar com POST, esse parâmetro é nomeado filtro em vez de $filter. Consulte Sintaxe de expressão OData para Azure AI Search para obter detalhes sobre o subconjunto da gramática de expressão OData compatível com o Azure AI Search.
highlight string Opcional. Um conjunto de nomes de campos separados por vírgulas usado para realçar a ocorrência. Somente campos pesquisáveis podem ser usados para realce de clique. Por padrão, o Azure AI Search retorna até 5 realces por campo. O limite é configurável por campo acrescentando "-<max # de realces>" após o nome do campo. Por exemplo, "highlight=title-3,description-10" retorna até 3 ocorrências realçadas do campo de título e até 10 ocorrências do campo de descrição. O número máximo de realces deve ser um inteiro entre 1 e 1000 inclusive.
highlightPostTag string Opcional. Assume o padrão de "</em>". Uma marca de cadeia de caracteres que acrescenta ao termo realçado. Deve ser definido com highlightPreTag. Caracteres reservados na URL devem ser codificados por percentual (por exemplo, %23, em vez de #).
highlightPreTag string Opcional. Assume o padrão de "</em>". Uma marca de cadeia de caracteres que acrescenta ao termo realçado. Deve ser definido com highlightPostTag. Caracteres reservados na URL devem ser codificados por percentual (por exemplo, %23, em vez de #).
minimumCoverage inteiro Opcional. Os valores válidos são um número entre 0 e 100, indicando a porcentagem do índice que deve estar disponível para atender à consulta antes que ela possa ser relatada como um sucesso. O padrão é "100".

Uma cobertura de cem por cento significa que todos os fragmentos responderam à solicitação (nem problemas de integridade do serviço nem atividades de manutenção reduziram a cobertura). Na configuração padrão, menos de cobertura completa retorna o código http status 503.

A redução de minimumCoverage poderá ser útil se 503 erros estiverem ocorrendo e você quiser aumentar a probabilidade de sucesso da consulta, especialmente para serviços configurados para um réplica. Se você definir minimumCoverage e Search for bem-sucedido, ele retornará HTTP 200 e incluirá um @search.coverage valor na resposta indicando o percentual do índice incluído na consulta. Nesse cenário, nem todos os documentos correspondentes têm a garantia de estar presentes nos resultados da pesquisa, mas se a disponibilidade da pesquisa for mais importante do que o recall, a redução da cobertura poderá ser uma estratégia de mitigação viável.
$orderby string Opcional. Uma lista de expressões separadas por vírgulas para classificar os resultados. Quando chamado com POST, esse parâmetro é nomeado orderby em vez de $orderby. Cada expressão pode ser um nome de campo ou uma chamada para a função geo.distance(). Cada expressão pode ser seguida por "asc" para indicar crescente e "desc" para indicar decrescente. Se houver valores nulos no campo de classificação, os nulos aparecerão primeiro em ordem crescente e por último em ordem decrescente. O padrão é a ordem crescente. Os empates serão resolvidos pelas pontuações de correspondência de documentos. Se nenhuma $orderby for especificada, a ordem de classificação padrão será decrescente por pontuação de correspondência do documento. Há um limite de 32 cláusulas para $orderby.
queryType string Opcional. Os valores válidos são "simples" ou "completo". Usa como padrão "simples".

"simple" interpreta cadeias de caracteres de consulta usando a sintaxe de consulta simples que permite símbolos como +e *"". As consultas são avaliadas em todos os campos pesquisáveis (ou campos indicados em searchFields) em cada documento por padrão.

"full" interpreta as cadeias de caracteres de consulta usando a sintaxe de consulta Lucene completa que permite pesquisas específicas e ponderadas do campo. Não há suporte para a pesquisa de intervalo na linguagem de consulta Lucene em favor de $filter, que oferece funcionalidade semelhante.
scoreParameter string Opcional. Indica os valores de cada parâmetro definido em uma função de pontuação (como referencePointParameter) usando o formato "name-value1,value2,..." Quando chamado com POST, esse parâmetro é nomeado scoreParameters em vez de scoreParameter. Além disso, especifique-o como uma matriz JSON de cadeias de caracteres em que cada cadeia de caracteres é um par de nomes-valores separados.

Para perfis de pontuação que incluem uma função, separe a função de sua lista de entrada com um - caractere. Por exemplo, uma função chamada "mylocation" seria "&scoringParameter=mylocation--122.2,44.8". O primeiro traço separa o nome da função da lista de valores, enquanto o segundo traço faz parte do primeiro valor (longitude neste exemplo).

Para parâmetros de pontuação, como para aumento de marca que pode conter vírgulas, você pode escapar de todos esses valores na lista usando aspas simples. Se os próprios valores contiverem aspas simples, você poderá liberá-las ao duplicar. Suponha que você tenha um parâmetro de aumento de marca chamado "mytag" e queira aumentar os valores de marca "Hello, O'Brien" e "Smith", a opção de cadeia de caracteres de consulta seria "&scoringParameter=mytag-'Hello, O''Brien',Smith". Aspas são necessárias apenas para valores que contêm vírgulas.
scoringProfile string Opcional. O nome de um perfil de pontuação para avaliar as pontuações correspondentes para corresponder documentos para classificar os resultados.
scoringStatistics string Opcional. Os valores válidos são "local" ou "global". O padrão é "local". Especifique se as estatísticas de pontuação devem ser calculadas, como frequência do documento, globalmente (em todos os fragmentos) para pontuação mais consistente ou localmente (no fragmento atual) para menor latência. Confira Estatísticas de Pontuação no Azure AI Search. As estatísticas de pontuação sempre serão calculadas localmente para termos que usam pesquisa difusa ('~').
pequisa string Opcional. O texto a ser pesquisado. Todos os campos pesquisáveis são pesquisados por padrão, a menos que searchFields seja especificado. No índice, o texto em um campo pesquisável é tokenizado, portanto, vários termos podem ser separados por espaço em branco (por exemplo: 'search=hello world'). Para corresponder a qualquer termo, use * (isso pode ser útil para consultas de filtros boolianos). A omissão desse parâmetro tem o mesmo efeito que sua definição como *. Confira Sintaxe de consulta simples para obter detalhes na sintaxe de pesquisa.

Às vezes, os resultados podem ser surpreendentes ao consultar campos pesquisáveis. O tokenizer inclui lógica para lidar com casos comuns para texto em inglês como apóstrofes, vírgulas nos números e assim por diante. Por exemplo, 'search=123.456' corresponderá a um único termo '123.456' em vez dos termos individuais '123' e '456', uma vez que as vírgulas são usadas como separadores de milhar para números grandes em inglês. Por esse motivo, é recomendável usar espaço em branco em vez de pontuação para separar termos no parâmetro de pesquisa.
searchMode string Opcional. Os valores válidos são "any" ou "all" Padrões para "any". Especifica se algum ou todos os termos de pesquisa devem ser iguais para considerar o documento uma correspondência.
searchFields string Opcional. A lista de nomes de campos separados por vírgula para procurar o texto especificado. Os campos de destino devem ser marcados como pesquisáveis no esquema de índice.
$select string Opcional. Uma lista de campos separados por vírgulas a serem incluídos no conjunto de resultados. Somente campos marcados como recuperáveis podem ser incluídos nesta cláusula. Se não for especificado ou se for definido como *, todos os campos marcados como recuperáveis no esquema serão incluídos na projeção. Quando chamado com POST, esse parâmetro é nomeado select em vez de $select.
sessionID string Opcional. O uso de sessionId ajuda a melhorar a consistência da pontuação de relevância para serviços de pesquisa com várias réplicas. Em configurações de várias réplica, pode haver pequenas diferenças entre pontuações de relevância de documentos individuais para a mesma consulta. Quando uma ID de sessão é fornecida, o serviço faz o melhor esforço para rotear uma determinada solicitação para o mesmo réplica para essa sessão. Tenha cuidado para que a reutilização dos mesmos valores de ID de sessão repetidamente possa interferir no balanceamento de carga das solicitações entre réplicas e afetar negativamente o desempenho do serviço de pesquisa. O valor usado como sessionId não pode começar com um caractere '_'. Se um serviço não tiver nenhuma réplica, esse parâmetro não terá efeito sobre o desempenho ou a consistência da pontuação.
$skip inteiro Opcional. O número de resultados de pesquisa a ser ignorado. Quando chamado com POST, esse parâmetro é chamado skip em vez de $skip. Esse valor não pode ser maior que 100.000. Se você precisar examinar documentos em sequência, mas não puder usar $skip devido a essa limitação, considere usar $orderby em um campo que tenha valores exclusivos para cada documento no índice (como a chave do documento, por exemplo) e $filter com uma consulta de intervalo.
$top inteiro Opcional. O número de resultados de pesquisa a ser recuperado. O padrão é 50. Quando chamado com POST, esse parâmetro é nomeado top em vez de $top. Se você especificar um valor maior que 1000 e houver mais de 1000 resultados, somente os primeiros 1000 resultados serão retornados, juntamente com um link para a próxima página de resultados (consulte @odata.nextLink o exemplo abaixo).

O Azure AI Search usa paginação do lado do servidor para impedir que consultas recuperem muitos documentos ao mesmo tempo. O tamanho de página padrão é 50, enquanto o tamanho máximo da página é 1000. Isso significa que, por padrão , Os Documentos de Pesquisa retornarão no máximo 50 resultados se você não especificar $top. Se houver mais de 50 resultados, a resposta incluirá informações para recuperar a próxima página de no máximo 50 resultados (confira "@odata.nextLink" e "@search.nextPageParameters" nos Exemplos abaixo. Da mesma forma, se você especificar um valor maior que 1000 para $top e houver mais de 1000 resultados, somente os primeiros 1000 resultados serão retornados, juntamente com informações para recuperar a próxima página de no máximo 1000 resultados.

Resposta

Código de status: 200 OK é retornado para uma resposta bem-sucedida.

  {
    "@odata.count": # (if `$count`=true was provided in the query),
    "@search.coverage": # (if minimumCoverage was provided in the query),
    "@search.facets": { (if faceting was specified in the query)
      "facet_field": [
        {
          "value": facet_entry_value (for non-range facets),
          "from": facet_entry_value (for range facets),
          "to": facet_entry_value (for range facets),
          "count": number_of_documents
        }
      ],
      ...
    },
    "@search.nextPageParameters": { (request body to fetch the next page of results if not all results could be returned in this response and Search was called with POST)
      "count": ... (value from request body if present),
      "facets": ... (value from request body if present),
      "filter": ... (value from request body if present),
      "highlight": ... (value from request body if present),
      "highlightPreTag": ... (value from request body if present),
      "highlightPostTag": ... (value from request body if present),
      "minimumCoverage": ... (value from request body if present),
      "orderby": ... (value from request body if present),
      "scoringParameters": ... (value from request body if present),
      "scoringProfile": ... (value from request body if present),
      "scoringStatistics": ... (value from request body if present),
      "search": ... (value from request body if present),
      "searchFields": ... (value from request body if present),
      "searchMode": ... (value from request body if present),
      "select": ... (value from request body if present),
      "sessionId" : ... (value from request body if present),
      "skip": ... (page size plus value from request body if present),
      "top": ... (value from request body if present minus page size),
    },
    "value": [
      {
        "@search.score": document_score (if a text query was provided),
        "@search.highlights": {
          field_name: [ subset of text, ... ],
          ...
        },
        "@search.features": {
          "field_name": {
            "uniqueTokenMatches": feature_score,
            "similarityScore": feature_score,
            "termFrequency": feature_score,
          },
          ...
        },
        key_field_name: document_key,
        field_name: field_value (retrievable fields or specified projection),
        ...
      },
      ...
    ],
    "@odata.nextLink": (URL to fetch the next page of results if not all results could be returned in this response; Applies to both GET and POST)
  }

Exemplos

Você pode encontrar mais exemplos na Sintaxe de Expressão OData para o Azure AI Search.

  1. Pesquise o índice classificado em ordem decrescente por data:

    GET /indexes/hotels/docs?search=*&$orderby=LastRenovationDate desc&api-version=2020-06-30

    POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "*",  
      "orderby": "LastRenovationDate desc"
    }

  2. Em uma pesquisa facetada, pesquise o índice e recupere facetas para categorias, classificações, marcas e itens com baseRate em intervalos específicos.

    GET /indexes/hotels/docs?search=*&facet=Category&facet=Rating&facet=Tags&facet=Rooms/BaseRate,values:80|150|220&api-version=2020-06-30

    POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "test",  
      "facets": [ "Category", "Rating", "Tags", "Rooms/BaseRate,values:80|150|220" ]  
    }

    Observe que a última faceta está em um subcampo. As facetas contam o documento pai (Hotéis) e não os subdocumentos intermediários (Salas), portanto, a resposta determina o número de hotéis que têm quartos em cada bucket de preço.

  3. Usando um filtro, restrinja o resultado da consulta facetada anterior depois que o usuário selecionar Classificação 3 e a categoria "Motel".

    GET /indexes/hotels/docs?search=*&facet=tags&facet=Rooms/BaseRate,values:80|150|220&$filter=Rating eq 3 and Category eq 'Motel'&api-version=2020-06-30

    POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "test",  
      "facets": [ "tags", "Rooms/BaseRate,values:80|150|220" ],  
      "filter": "Rating eq 3 and Category eq 'Motel'"  
    }

  4. Em uma pesquisa facetada, definir um limite superior para termos exclusivos retornados em uma consulta. O padrão é 10, mas é possível aumentar ou diminuir esse valor usando o parâmetro de contagem no atributo da faceta. Esse exemplo retorna facetas para cidade, limitadas a 5.

    GET /indexes/hotels/docs?search=*&facet=Address/City,count:5&api-version=2020-06-30

    POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "test",  
      "facets": [ "Address/City,count:5" ]  
    }

  5. Pesquise o índice de campos específicos (por exemplo, um campo de idioma):

    GET /indexes/hotels/docs?search=hôtel&searchFields=Description_fr&api-version=2020-06-30

    POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "hôtel",  
      "searchFields": "Description_fr"
    }

  6. Pesquisar o índice em vários campos. Por exemplo, você pode armazenar e consultar campos pesquisáveis em vários idiomas, todos no mesmo índice. Se as descrições em inglês e francês coexistirem no mesmo documento, você poderá retornar qualquer um ou todos nos resultados da consulta:

    GET /indexes/hotels/docs?search=hotel&searchFields=Description,Description_fr&api-version=2020-06-30

    POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "hotel",  
      "searchFields": "Description, Description_fr"
    }

    Você só pode consultar o índice por vez. Não crie vários índices para cada idioma, a menos que você planeje consultar um de cada vez.

  7. Paginação – Obter a primeira página de itens (o tamanho da página é 10):

    GET /indexes/hotels/docs?search=*&$skip=0&$top=10&api-version=2020-06-30

    POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "*",  
      "skip": 0,  
      "top": 10  
    }

  8. Paginação – Obter a segunda página de itens (o tamanho da página é 10):

    GET /indexes/hotels/docs?search=*&$skip=10&$top=10&api-version=2020-06-30

    POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "*",  
      "skip": 10,  
      "top": 10  
    }

  9. Recuperar um conjunto específico de campos:

    GET /indexes/hotels/docs?search=*&$select=HotelName,Description&api-version=2020-06-30

    POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "*",  
      "select": "HotelName, Description"
    }

  10. Recupere documentos que correspondem a uma expressão de filtro específica:

    GET /indexes/hotels/docs?$filter=(Rooms/BaseRate ge 60 and Rooms/BaseRate lt 300) or HotelName eq 'Fancy Stay'&api-version=2020-06-30

    POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "filter": "(Rooms/BaseRate ge 60 and Rooms/BaseRate lt 300) or HotelName eq 'Fancy Stay'"  
    }

  11. Pesquise o índice e retorne fragmentos com realces de ocorrências:

    GET /indexes/hotels/docs?search=something&highlight=Description&api-version=2020-06-30

    POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "something",  
      "highlight": "Description"  
    }

  12. Pesquise o índice e retorne documentos classificados do local mais próximo ao mais longe de uma referência:

    GET /indexes/hotels/docs?search=something&$orderby=geo.distance(Location, geography'POINT(-122.12315 47.88121)')&api-version=2020-06-30

    POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "something",  
      "orderby": "geo.distance(Location, geography'POINT(-122.12315 47.88121)')"
    }

  13. Pesquise o índice supondo que haja um perfil de pontuação chamado "geo" com duas funções de pontuação de distância, uma definindo um parâmetro chamado "currentLocation" e outra definindo um parâmetro chamado "lastLocation". No exemplo a seguir, "currentLocation" tem um delimitador de um único traço (-). Ele é seguido por coordenadas de longitude e latitude, em que longitude é um valor negativo.

    GET /indexes/hotels/docs?search=something&scoringProfile=geo&scoringParameter=currentLocation--122.123,44.77233&scoringParameter=lastLocation--121.499,44.2113&api-version=2020-06-30

    POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "something",  
      "scoringProfile": "geo",  
      "scoringParameters": [ "currentLocation--122.123,44.77233", "lastLocation--121.499,44.2113" ]  
    }

  14. Localize documentos no índice usando a sintaxe de consulta simples. Esta consulta retorna hotéis em que os campos de pesquisa contêm os termos "conforto" e "local", mas não "motel":

    Get /indexes/hotels/docs?search=comfort +location –motel&searchMode=all&api-version=22020-06-30

    POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "comfort +location -motel",  
      "searchMode": "all"  
    }

    Dica

    O uso de searchMode=all substitui o padrão de searchMode=any, garantindo que -motel significa "AND NOT" em vez de "OR NOT". Sem searchMode=all, você obtém "OU NÃO", que expande em vez de restringir os resultados de pesquisa, e isso pode ser contraintuitivo para alguns usuários.

  15. Encontre documentos no índice usando a sintaxe de consulta Lucene). Essa consulta retorna hotéis onde o campo de categoria contém o termo "orçamento" e todos os campos pesquisáveis com a frase "renovado recentemente". Os documentos com a frase "renovado recentemente" apresentam uma classificação superior como um resultado do valor de aumento de termo (3)

    GET /indexes/hotels/docs?search=Category:budget AND \"recently renovated\"^3&searchMode=all&api-version=2020-06-30&querytype=full` 

    POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
     "search": "Category:budget AND \"recently renovated\"^3",  
      "queryType": "full",  
      "searchMode": "all"  
}

  16. Encontre documentos no índice, favorecendo a pontuação consistente em relação à latência mais baixa. Essa consulta calcula as frequências do documento em todo o índice e faz um melhor esforço para direcionar o mesmo réplica para todas as consultas dentro da mesma "sessão", o que ajuda a gerar uma classificação estável e reproduzível.

    GET /indexes/hotels/docs?search=hotel&sessionId=mySessionId&scoringStatistics=global&api-version=2020-06-30

    POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "hotel",  
      "sessionId": "mySessionId",
      "scoringStatistics" :"global"
    }

Confira também