Exemplos de consultas de pesquisa simples no Azure AI Search

  • Artigo

No Azure AI Search, a sintaxe de consulta simples invoca o analisador de consulta padrão para pesquisa de texto completo. O analisador é rápido e lida com cenários comuns, incluindo pesquisa de texto completo, pesquisa filtrada e facetada e pesquisa de prefixo. Este artigo usa exemplos para ilustrar o uso simples de sintaxe em uma solicitação de documentos de pesquisa (API REST).

Nota

Uma sintaxe de consulta alternativa é Lucene, que suporta estruturas de consulta mais complexas, como pesquisa difusa e curinga. Para obter mais informações, consulte Exemplos de sintaxe de pesquisa Lucene completa .

Índice de amostra de hotéis

As consultas a seguir são baseadas no hotels-sample-index, que você pode criar seguindo as instruções em Guia de início rápido: crie um índice de pesquisa no portal do Azure.

Consultas de exemplo são articuladas usando a API REST e solicitações POST. Você pode colá-los e executá-los em um cliente REST. Ou use o modo de exibição JSON do explorador de Pesquisa no portal do Azure. No modo de exibição JSON, você pode colar nos exemplos de consulta mostrados aqui neste artigo.

Os cabeçalhos de solicitação devem ter os seguintes valores:

Key valor
Tipo de Conteúdo application/json
Chave API <your-search-service-api-key>, chave de consulta ou de administrador

Os parâmetros de URI devem incluir o ponto de extremidade do serviço de pesquisa com o nome do índice, coleções de documentos, comando de pesquisa e versão da API, semelhante ao exemplo a seguir:

https://{{service-name}}.search.windows.net/indexes/hotels-sample-index/docs/search?api-version=2024-07-01

O corpo do pedido deve ser formado como JSON válido:

{
    "search": "*",
    "queryType": "simple",
    "select": "HotelId, HotelName, Category, Tags, Description",
    "count": true
}

  • search definido como * é uma consulta não especificada, equivalente a pesquisa nula ou vazia. Não é especialmente útil, mas é a pesquisa mais simples que você pode fazer e mostra todos os campos recuperáveis no índice, com todos os valores.

  • queryType Definir como simples é o padrão e pode ser omitido, mas é incluído para enfatizar que os exemplos de consulta neste artigo são expressos na sintaxe simples.

  • select definido como uma lista delimitada por vírgulas de campos é usado para a composição dos resultados da pesquisa, incluindo apenas os campos que são úteis no contexto dos resultados da pesquisa.

  • count Devolve o número de documentos que correspondem aos critérios de pesquisa. Em uma cadeia de pesquisa vazia, a contagem é de todos os documentos no índice (50 no hotels-sample-index).

Exemplo 1: Pesquisa de texto completo

A pesquisa de texto completo pode ser qualquer número de termos independentes ou frases entre aspas, com ou sem operadores booleanos.

POST /indexes/hotel-samples-index/docs/search?api-version=2024-07-01
{
    "search": "pool spa +airport",
    "searchMode": "any",
    "queryType": "simple",
    "select": "HotelId, HotelName, Category, Description",
    "count": true
}

Uma pesquisa por palavra-chave composta por termos ou frases importantes tende a funcionar melhor. Os campos de cadeia de caracteres passam por análise de texto durante a indexação e consulta, descartando palavras não essenciais como o, e, ele. Para ver como uma cadeia de caracteres de consulta é tokenizada no índice, passe a cadeia de caracteres em uma chamada Analisar Texto para o índice.

O searchMode parâmetro controla a precisão e a recordação. Se você quiser mais recuperação, use o valor padrão any , que retorna um resultado se qualquer parte da cadeia de caracteres de consulta for correspondida. Se você preferir a precisão, onde todas as partes da cadeia de caracteres devem ser correspondidas, mude searchMode para todas. Experimente a consulta anterior de ambas as maneiras para ver como searchMode altera o resultado.

A resposta para a consulta spa piscina + aeroporto deve ser semelhante ao exemplo a seguir.

"@odata.count": 4,
"value": [
{
    "@search.score": 6.090657,
    "HotelId": "12",
    "HotelName": "Winter Panorama Resort",
    "Description": "Plenty of great skiing, outdoor ice skating, sleigh rides, tubing and snow biking. Yoga, group exercise classes and outdoor hockey are available year-round, plus numerous options for shopping as well as great spa services. Newly-renovated with large rooms, free 24-hr airport shuttle & a new restaurant. Rooms/suites offer mini-fridges & 49-inch HDTVs.",
    "Category": "Resort and Spa"
},
{
    "@search.score": 4.314683,
    "HotelId": "21",
    "HotelName": "Good Business Hotel",
    "Description": "1 Mile from the airport. Free WiFi, Outdoor Pool, Complimentary Airport Shuttle, 6 miles from Lake Lanier & 10 miles from downtown. Our business center includes printers, a copy machine, fax, and a work area.",
    "Category": "Suite"
},
{
    "@search.score": 3.575948,
    "HotelId": "27",
    "HotelName": "Starlight Suites",
    "Description": "Complimentary Airport Shuttle & WiFi. Book Now and save - Spacious All Suite Hotel, Indoor Outdoor Pool, Fitness Center, Florida Green certified, Complimentary Coffee, HDTV",
    "Category": "Suite"
},
{
    "@search.score": 2.6926985,
    "HotelId": "25",
    "HotelName": "Waterfront Scottish Inn",
    "Description": "Newly Redesigned Rooms & airport shuttle. Minutes from the airport, enjoy lakeside amenities, a resort-style pool & stylish new guestrooms with Internet TVs.",
    "Category": "Suite"
}
]

Observe a pontuação da pesquisa na resposta. Este é o placar de relevância da partida. Por padrão, um serviço de pesquisa retorna as 50 melhores correspondências com base nessa pontuação.

Pontuações uniformes de 1,0 ocorrem quando não há classificação, seja porque a pesquisa não foi pesquisa de texto completo, ou porque nenhum critério foi fornecido. Por exemplo, em uma pesquisa vazia (search=*), as linhas voltam em ordem arbitrária. Ao incluir critérios reais, você verá as pontuações de pesquisa evoluirem para valores significativos.

Exemplo 2: Procurar por ID

Depois que os resultados da pesquisa são retornados, uma próxima etapa lógica é fornecer uma página de detalhes que inclua mais campos do documento. Este exemplo mostra como retornar um único documento usando Get Document passando a ID do documento.

GET /indexes/hotels-sample-index/docs/41?api-version=2024-07-01

Todos os documentos têm um identificador único. Se você estiver usando o portal, selecione o índice na guia Índices e, em seguida, examine as definições de campo para determinar qual campo é a chave. Na API REST, a chamada GET Index retorna a definição de índice no corpo da resposta.

A resposta para a consulta anterior consiste no documento cuja chave é 41. Qualquer campo marcado como recuperável na definição de índice pode ser retornado nos resultados da pesquisa e renderizado em seu aplicativo.

{
    "HotelId": "41",
    "HotelName": "Windy Ocean Motel",
    "Description": "Oceanfront hotel overlooking the beach features rooms with a private balcony and 2 indoor and outdoor pools. Inspired by the natural beauty of the island, each room includes an original painting of local scenes by the owner. Rooms include a mini fridge, Keurig coffee maker, and flatscreen TV. Various shops and art entertainment are on the boardwalk, just steps away.",
    "Description_fr": "Cet hôtel en bord de mer donnant sur la plage propose des chambres dotées d'un balcon privé et de 2 piscines intérieure et extérieure. Inspiré par la beauté naturelle de l'île, chaque chambre comprend une peinture originale de scènes locales par le propriétaire. Les chambres comprennent un mini-réfrigérateur, une cafetière Keurig et une télévision à écran plat. Divers magasins et divertissements artistiques se trouvent sur la promenade, à quelques pas.",
    "Category": "Suite",
    "Tags": [
    "pool",
    "air conditioning",
    "bar"
    ],
    "ParkingIncluded": true,
    "LastRenovationDate": "2021-05-10T00:00:00Z",
    "Rating": 3.5,
    "Location": {
    "type": "Point",
    "coordinates": [
        -157.846817,
        21.295841
    ],
    "crs": {
        "type": "name",
        "properties": {
        "name": "EPSG:4326"
        }
    }
    },
    "Address": {
    "StreetAddress": "1450 Ala Moana Blvd 2238 Ala Moana Ctr",
    "City": "Honolulu",
    "StateProvince": "HI",
    "PostalCode": "96814",
    "Country": "USA"
    }
}

Exemplo 3: Filtrar texto

A sintaxe de filtro é uma expressão OData que você pode usar sozinha ou com search. Quando usado em conjunto na mesma solicitação, filter é aplicado primeiro a todo o índice e, em seguida, o search é executado nos resultados do filtro. Por conseguinte, os filtros podem ser uma técnica útil para melhorar o desempenho de consultas, uma vez que reduzem o conjunto de documentos necessários à consulta de pesquisa para processamento.

Os filtros podem ser definidos em qualquer campo marcado como filterable na definição do índice. Para hotels-sample-index, os campos filtráveis incluem Categoria, Tags, EstacionamentoIncluído, Classificação e a maioria dos campos Endereço .

POST /indexes/hotels-sample-index/docs/search?api-version=2024-07-01
{
    "search": "art tours",
    "queryType": "simple",
    "filter": "Category eq 'Boutique'",
    "searchFields": "HotelName,Description,Category",
    "select": "HotelId,HotelName,Description,Category",
    "count": true
}

A resposta para a consulta anterior tem como escopo apenas os hotéis categorizados como Boutique e que incluem os termos arte ou passeios. Neste caso, há apenas uma correspondência.

"value": [
{
    "@search.score": 1.2814453,
    "HotelId": "2",
    "HotelName": "Old Century Hotel",
    "Description": "The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts. The hotel also regularly hosts events like wine tastings, beer dinners, and live music.",
    "Category": "Boutique"
}
]

Exemplo 4: Funções de filtro

As expressões de filtro podem incluir as funções search.ismatch e search.ismatchscoreing, permitindo que você crie uma consulta de pesquisa dentro do filtro. Esta expressão de filtro usa um curinga gratuito para selecionar comodidades, incluindo Wi-Fi gratuito, estacionamento gratuito e assim por diante.

POST /indexes/hotels-sample-index/docs/search?api-version=2024-07-01
  {
    "search": "",
    "filter": "search.ismatch('free*', 'Tags', 'full', 'any')",
    "select": "HotelName, Tags, Description",
    "count": true
  }

A resposta para a consulta anterior corresponde a 27 hotéis que oferecem comodidades gratuitas. Observe que a pontuação da pesquisa é um 1 uniforme ao longo dos resultados. Isso ocorre porque a expressão de pesquisa é nula ou vazia, resultando em correspondências de filtro literais, mas nenhuma pesquisa de texto completo. As pontuações de relevância só são devolvidas na pesquisa de texto completo. Se estiver a utilizar filtros sem searcho , certifique-se de que tem campos classificáveis suficientes para poder controlar a classificação da pesquisa.

  "@odata.count": 27,
  "value": [
    {
      "@search.score": 1,
      "HotelName": "Country Residence Hotel",
      "Description": "All of the suites feature full-sized kitchens stocked with cookware, separate living and sleeping areas and sofa beds. Some of the larger rooms have fireplaces and patios or balconies. Experience real country hospitality in the heart of bustling Nashville. The most vibrant music scene in the world is just outside your front door.",
      "Tags": [
        "laundry service",
        "restaurant",
        "free parking"
      ]
    },
    {
      "@search.score": 1,
      "HotelName": "Downtown Mix Hotel",
      "Description": "Mix and mingle in the heart of the city. Shop and dine, mix and mingle in the heart of downtown, where fab lake views unite with a cheeky design.",
      "Tags": [
        "air conditioning",
        "laundry service",
        "free wifi"
      ]
    },
    {
      "@search.score": 1,
      "HotelName": "Starlight Suites",
      "Description": "Complimentary Airport Shuttle & WiFi. Book Now and save - Spacious All Suite Hotel, Indoor Outdoor Pool, Fitness Center, Florida Green certified, Complimentary Coffee, HDTV",
      "Tags": [
        "pool",
        "coffee in lobby",
        "free wifi"
      ]
    },
. . .

Exemplo 5: Filtros de intervalo

A filtragem de intervalo é suportada através de expressões de filtros para qualquer tipo de dados. Os exemplos a seguir ilustram intervalos numéricos e de cadeia de caracteres. Os tipos de dados são importantes em filtros de intervalo e funcionam melhor quando os dados numéricos estão em campos numéricos e os dados de cadeia de caracteres em campos de cadeia de caracteres. Os dados numéricos em campos de cadeia de caracteres não são adequados para intervalos porque as cadeias numéricas não são comparáveis.

A consulta a seguir é um intervalo numérico. Em hotels-sample-index, o único campo numérico filtrável é Rating.

POST /indexes/hotels-sample-index/docs/search?api-version=2024-07-01
{
    "search": "*",
    "filter": "Rating ge 2 and Rating lt 4",
    "select": "HotelId, HotelName, Rating",
    "orderby": "Rating desc",
    "count": true
}

A resposta para esta consulta deve ser semelhante ao exemplo a seguir, cortado para brevidade.

"@odata.count": 27,
"value": [
{
    "@search.score": 1,
    "HotelId": "22",
    "HotelName": "Lion's Den Inn",
    "Rating": 3.9
},
{
    "@search.score": 1,
    "HotelId": "25",
    "HotelName": "Waterfront Scottish Inn",
    "Rating": 3.8
},
{
    "@search.score": 1,
    "HotelId": "2",
    "HotelName": "Old Century Hotel",
    "Rating": 3.6
},
...

A próxima consulta é um filtro de intervalo sobre um campo de cadeia de caracteres (Address/StateProvince):

POST /indexes/hotels-sample-index/docs/search?api-version=2024-07-01
{
    "search": "*",
    "filter": "Address/StateProvince ge 'A*' and Address/StateProvince lt 'D*'",
    "select": "HotelId, HotelName, Address/StateProvince",
    "count": true
}

A resposta para esta consulta deve ser semelhante ao exemplo a seguir, cortado para brevidade. Neste exemplo, não é possível classificar por StateProvince porque o campo não é atribuído como classificável na definição de índice.

{
  "@odata.count": 9,
  "value": [
    {
      "@search.score": 1,
      "HotelId": "39",
      "HotelName": "White Mountain Lodge & Suites",
      "Address": {
        "StateProvince": "CO"
      }
    },
    {
      "@search.score": 1,
      "HotelId": "9",
      "HotelName": "Smile Up Hotel",
      "Address": {
        "StateProvince": "CA "
      }
    },
    {
      "@search.score": 1,
      "HotelId": "7",
      "HotelName": "Roach Motel",
      "Address": {
        "StateProvince": "CA "
      }
    },
    {
      "@search.score": 1,
      "HotelId": "34",
      "HotelName": "Lakefront Captain Inn",
      "Address": {
        "StateProvince": "CT"
      }
    },
    {
      "@search.score": 1,
      "HotelId": "37",
      "HotelName": "Campus Commander Hotel",
      "Address": {
        "StateProvince": "CA "
      }
    },
. . .

O índice de amostra de hotéis inclui um campo Localização com coordenadas de latitude e longitude. Este exemplo usa a função geo.distance que filtra documentos dentro da circunferência de um ponto de partida, até uma distância arbitrária (em quilômetros) que você fornece. Você pode ajustar o último valor na consulta (10) para reduzir ou ampliar a área de superfície da consulta.

POST /indexes/v/docs/search?api-version=2024-07-01
{
    "search": "*",
    "filter": "geo.distance(Location, geography'POINT(-122.335114 47.612839)') le 10",
    "select": "HotelId, HotelName, Address/City, Address/StateProvince",
    "count": true
}

A resposta a esta consulta devolve todos os hotéis a uma distância de 10 quilómetros das coordenadas fornecidas:

{
  "@odata.count": 3,
  "value": [
    {
      "@search.score": 1,
      "HotelId": "45",
      "HotelName": "Happy Lake Resort & Restaurant",
      "Address": {
        "City": "Seattle",
        "StateProvince": "WA"
      }
    },
    {
      "@search.score": 1,
      "HotelId": "24",
      "HotelName": "Uptown Chic Hotel",
      "Address": {
        "City": "Seattle",
        "StateProvince": "WA"
      }
    },
    {
      "@search.score": 1,
      "HotelId": "16",
      "HotelName": "Double Sanctuary Resort",
      "Address": {
        "City": "Seattle",
        "StateProvince": "WA"
      }
    }
  ]
}

Exemplo 7: Booleanos com searchMode

A sintaxe simples suporta operadores booleanos na forma de caracteres (+, -, |) para suportar a lógica de consulta E, OU e NÃO. A pesquisa booleana se comporta como você poderia esperar, com algumas exceções dignas de nota.

Em uma pesquisa booleana, considere adicionar o parâmetro como um mecanismo para influenciar a searchMode precisão e a recordação. Os valores válidos incluem "searchMode": "any" o favorecimento do recall (um documento que satisfaça qualquer um dos critérios é considerado uma correspondência) e "searchMode": "all" o favorecimento da precisão (todos os critérios devem ser correspondidos em um documento).

No contexto de uma pesquisa booleana, o padrão "searchMode": "any" pode ser confuso se você estiver empilhando uma consulta com vários operadores e obtendo resultados mais amplos em vez de mais restritos. Isto é particularmente verdade no caso do NOT, em que os resultados incluem todos os documentos que não contêm um termo ou frase específicos.

O exemplo a seguir fornece uma ilustração. A consulta procura correspondências no restaurante que excluam a frase ar condicionado. Se você executar a seguinte consulta com searchMode (qualquer), 43 documentos serão retornados: aqueles que contêm o termo restaurante, além de todos os documentos que não têm a frase *ar condicionado.

Observe que não há espaço entre o operador booleano (-) e a frase ar condicionado. As aspas são escapadas (\").

POST /indexes/hotels-sample-index/docs/search?api-version=2024-07-01
{
    "search": "restaurant -\"air conditioning\"",
    "searchMode": "any",
    "searchFields": "Tags",
    "select": "HotelId, HotelName, Tags",
    "count": true
}

Mudar para "searchMode": "all" impor um efeito cumulativo sobre os critérios e retorna um conjunto de resultados menor (sete correspondências) composto por documentos contendo o termo restaurante, menos aqueles que contêm a frase ar condicionado.

A resposta para esta consulta agora seria semelhante ao exemplo a seguir, cortado para brevidade.

{
  "@odata.count": 14,
  "value": [
    {
      "@search.score": 3.1383743,
      "HotelId": "18",
      "HotelName": "Ocean Water Resort & Spa",
      "Tags": [
        "view",
        "pool",
        "restaurant"
      ]
    },
    {
      "@search.score": 2.028083,
      "HotelId": "22",
      "HotelName": "Lion's Den Inn",
      "Tags": [
        "laundry service",
        "free wifi",
        "restaurant"
      ]
    },
    {
      "@search.score": 2.028083,
      "HotelId": "34",
      "HotelName": "Lakefront Captain Inn",
      "Tags": [
        "restaurant",
        "laundry service",
        "coffee in lobby"
      ]
    },
...

Exemplo 8: Resultados de paginação

Em exemplos anteriores, você aprendeu sobre parâmetros que afetam a composição dos resultados da pesquisa, incluindo select que determina quais campos estão em um resultado, ordens de classificação e como incluir uma contagem de todas as correspondências. Este exemplo é uma continuação da composição de resultados de pesquisa na forma de parâmetros de paginação que permitem agrupar o número de resultados que aparecem em qualquer página.

Por padrão, um serviço de pesquisa retorna as 50 principais correspondências. Para controlar o número de correspondências em cada página, use top para definir o tamanho do lote e, em seguida, use skip para pegar lotes subsequentes.

O exemplo a seguir usa um filtro e uma ordem de classificação no Rating campo (A classificação é filtrável e classificável) porque é mais fácil ver os efeitos da paginação nos resultados classificados. Em uma consulta de pesquisa completa regular, as principais correspondências são classificadas e paginadas por @search.score.

POST /indexes/hotels-sample-index/docs/search?api-version=2024-07-01
{
    "search": "*",
    "filter": "Rating gt 4",
    "select": "HotelName, Rating",
    "orderby": "Rating desc",
    "top": 5,
    "count": true
}

A consulta encontra 21 documentos correspondentes, mas como você especificou top, a resposta retorna apenas as cinco melhores correspondências, com classificações começando em 4,9 e terminando em 4,7 com Lakeside B & B.

Para obter os próximos cinco, pule o primeiro lote:

POST /indexes/hotels-sample-index/docs/search?api-version=2024-07-01
{
    "search": "*",
    "filter": "Rating gt 4",
    "select": "HotelName, Rating",
    "orderby": "Rating desc",
    "top": 5,
    "skip": 5,
    "count": true
}

A resposta para o segundo lote pula as cinco primeiras partidas, retornando as cinco seguintes, começando com o Pull'r Inn Motel. Para continuar com mais lotes, você manteria top em cinco e, em seguida, incrementaria skip em cinco em cada nova solicitação (skip=5, skip=10, skip=15 e assim por diante).

{
  "@odata.count": 21,
  "value": [
    {
      "@search.score": 1,
      "HotelName": "Head Wind Resort",
      "Rating": 4.7
    },
    {
      "@search.score": 1,
      "HotelName": "Sublime Palace Hotel",
      "Rating": 4.6
    },
    {
      "@search.score": 1,
      "HotelName": "City Skyline Antiquity Hotel",
      "Rating": 4.5
    },
    {
      "@search.score": 1,
      "HotelName": "Nordick's Valley Motel",
      "Rating": 4.5
    },
    {
      "@search.score": 1,
      "HotelName": "Winter Panorama Resort",
      "Rating": 4.5
    }
  ]
}

Conteúdos relacionados

Agora que você tem alguma prática com a sintaxe de consulta básica, tente especificar consultas no código. O link a seguir aborda como configurar consultas de pesquisa usando os SDKs do Azure.

Mais referência de sintaxe, arquitetura de consulta e exemplos podem ser encontrados nos seguintes links: