Exemplos de sintaxe de pesquisa em Lucene completas (consultas avançadas)

  • Artigo

Ao construir consultas para o Azure AI Search, você pode substituir o padrão analisador de consulta simples pelo mais expansivo analisador de consulta Lucene, para formular expressões de consulta especializadas e avançadas.

O analisador Lucene suporta formatos de consulta complexas, como consultas com escopo de campo, pesquisa difusa, caractere curinga prefixo, sufixo e radical, pesquisa de proximidade, reforço de termos e pesquisa de expressão regular. A energia adicional vem com mais requisitos de processamento, portanto, você deve esperar um tempo de execução um pouco mais longo. Neste artigo, você pode percorrer exemplos que demonstram operações de consulta com base na sintaxe completa.

Observação

Muitas construções de consulta especializadas habilitadas por meio da sintaxe de consulta Lucene completa não são texto analisado, o que pode ser surpreendente caso espera-se a lematização. A análise lexical é realizada somente em termos completos (uma consulta de termo ou de frase). Tipos de consulta com termos incompletos (consulta de prefixo, consulta de curinga, consulta de regex, consulta difusa) são adicionados diretamente à árvore de consulta, ignorando o estágio de análise. A única transformação realizada em termos de consulta parcial é colocá-los em letras minúsculas.

Índice do exemplo de hotéis

As consultas a seguir são baseadas em hotels-sample-index, que você pode criar seguindo as instruções neste guia de início rápido.

Exemplos de consultas são articuladas usando a API REST e solicitações POST. Você pode colá-los e executá-los em um cliente REST. Ou então, use a exibição JSON do Gerenciador de Pesquisa no portal do Azure. Na 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
Content-Type aplicativo/json
api-key <your-search-service-api-key>, uma consulta ou chave de administração

Os parâmetros de URI devem incluir o ponto de extremidade do serviço de pesquisa com o nome do índice, as coleções de docs, o comando de pesquisa e a 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 da solicitação deve ser formado como um JSON válido:

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

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

  • queryType definido como completo invoca o analisador de consulta Lucene completo e é necessário para essa sintaxe.

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

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

Escopos de pesquisa em campo individuais, expressões de pesquisa inseridas em um campo específico. Este exemplo procura nomes de hotéis com o termo hotel neles, mas não motel. Você pode especificar vários campos usando AND.

Ao usar essa sintaxe de consulta, você pode omitir o parâmetro searchFields, quando os campos que você deseja consultar estão na expressão de pesquisa propriamente dita. Se você incluir searchFields na pesquisa de campo, o fieldName:searchExpression sempre terá precedência sobre searchFields.

POST /indexes/hotel-samples-index/docs/search?api-version=2024-07-01
{
    "search": "HotelName:(hotel NOT motel) AND Category:'Boutique'",
    "queryType": "full",
    "select": "HotelName, Category",
    "count": true
}

A resposta para essa consulta deve ser semelhante ao exemplo a seguir, filtrado em Resort e Spa, retornando hotéis que incluem hotel no nome, excluindo os resultados que incluem pousadas no nome.

{
  "@odata.count": 5,
  "value": [
    {
      "@search.score": 2.2289815,
      "HotelName": "Stay-Kay City Hotel",
      "Category": "Boutique"
    },
    {
      "@search.score": 1.3862944,
      "HotelName": "City Skyline Antiquity Hotel",
      "Category": "Boutique"
    },
    {
      "@search.score": 1.355046,
      "HotelName": "Old Century Hotel",
      "Category": "Boutique"
    },
    {
      "@search.score": 1.355046,
      "HotelName": "Sublime Palace Hotel",
      "Category": "Boutique"
    },
    {
      "@search.score": 1.355046,
      "HotelName": "Red Tide Hotel",
      "Category": "Boutique"
    }
  ]
}

A expressão de pesquisa pode ser um único termo, uma frase, ou uma expressão mais complexa entre parênteses, opcionalmente com operadores boolianos. Alguns exemplos incluem o seguinte:

  • HotelName:(hotel NOT motel)
  • Address/StateProvince:("WA" OR "CA")
  • Tags:("free wifi" NOT "free parking") AND "coffee in lobby"

Certifique-se de colocar uma frase entre aspas se desejar que ambas as cadeias de caracteres sejam avaliadas como uma única entidade, como neste caso, procurando por dois locais distintos no campo Address/StateProvince. Dependendo do cliente, talvez seja necessário escapar das (\) as aspas.

O campo especificado em fieldName:searchExpression deve ser um campo pesquisável. Para saber como as definições de campo são atribuídas, consulte Criar Índice (API REST).

Correspondências de pesquisa difusa em termos semelhantes, incluindo palavras incorretas. Para fazer uma pesquisa difusa, acrescente o símbolo til ~ ao final de uma única palavra com um parâmetro opcional, um valor entre 0 e 2, que especifica a distância de edição. Por exemplo, blue~ ou blue~1 retornariam mar, amar e maré.

POST /indexes/hotel-samples-index/docs/search?api-version=2024-07-01
{
    "search": "Tags:conserge~",
    "queryType": "full",
    "select": "HotelName, Category, Tags",
    "searchFields": "HotelName, Category, Tags",
    "count": true
}

A resposta dessa consulta é resolvida como concierge nos documentos correspondentes, cortados para fins de brevidade:

{
  "@odata.count": 9,
  "value": [
    {
      "@search.score": 1.4947624,
      "HotelName": "Twin Vortex Hotel",
      "Category": "Luxury",
      "Tags": [
        "bar",
        "restaurant",
        "concierge"
      ]
    },
    {
      "@search.score": 1.1685618,
      "HotelName": "Stay-Kay City Hotel",
      "Category": "Boutique",
      "Tags": [
        "view",
        "air conditioning",
        "concierge"
      ]
    },
    {
      "@search.score": 1.1465473,
      "HotelName": "Old Century Hotel",
      "Category": "Boutique",
      "Tags": [
        "pool",
        "free wifi",
        "concierge"
      ]
    },
. . .
  ]
}

Não há suporte diretamente para frases, mas você pode especificar uma correspondência difusa em cada termo de uma frase de várias partes, como search=Tags:landy~ AND sevic~. Essa expressão de consulta encontra 15 correspondências em serviço de lavanderia.

Observação

As consultas difusas não são analisadas. Tipos de consulta com termos incompletos (consulta de prefixo, consulta de curinga, consulta de regex, consulta difusa) são adicionados diretamente à árvore de consulta, ignorando o estágio de análise. A única transformação realizada em termos de consulta parcial é colocá-los em letras minúsculas.

A pesquisa por proximidade encontra termos próximos em um documento. Insira um símbolo til ~ no final de uma frase seguida pelo número de palavras que criam o limite de proximidade.

Esta consulta procura os termos hotel e aeroporto dentro de cinco palavras um do outro em um documento. As aspas são escapadas (\") para preservar a frase:

POST /indexes/hotel-samples-index/docs/search?api-version=2024-07-01
{
    "search": "Description: \"hotel airport\"~5",
    "queryType": "full",
    "select": "HotelName, Description",
    "searchFields": "HotelName, Description",
    "count": true
}

A resposta para essa consulta deve ser semelhante ao exemplo a seguir:

{
  "@odata.count": 1,
  "value": [
    {
      "@search.score": 0.69167054,
      "HotelName": "Trails End Motel",
      "Description": "Only 8 miles from Downtown. On-site bar/restaurant, Free hot breakfast buffet, Free wireless internet, All non-smoking hotel. Only 15 miles from airport."
    }
  ]
}

Exemplo 4: aumento de termos

O aumento de termos refere-se ao aumento da classificação de um documento caso contenha o termo aumentado, em relação aos documentos que não contêm o termo. Para aumentar um termo, use o símbolo circunflexo, ^, com um fator de aumento (um número) no final do termo que você está pesquisando. O padrão do fator de aumento é 1 e, embora ele deva ser positivo, ele pode ser menor que 1 (por exemplo, 0,2). O aumento de termos difere dos perfis de pontuação, em que os perfis de pontuação aumentam determinados campos, em vez de termos específicos.

Nessa anterior, pesquise acesso à praia e observe que há sete documentos que corresponderão em um ou em ambos os termos.

POST /indexes/hotel-samples-index/docs/search?api-version=2024-07-01
{
    "search": "beach access",
    "queryType": "full",
    "select": "HotelName, Description, Tags",
    "searchFields": "HotelName, Description, Tags",
    "count": true
}

Na verdade, apenas dois documentos correspondem a acesso. A primeira instância está na segunda posição, mesmo que o documento não tenha o termo praia.

{
  "@odata.count": 6,
  "value": [
    {
      "@search.score": 1.068669,
      "HotelName": "Johnson's Family Resort",
      "Description": "Family oriented resort located in the heart of the northland. Operated since 1962 by the Smith family, we have grown into one of the largest family resorts in the state. The home of excellent Smallmouth Bass fishing with 10 small cabins, we're a home not only to fishermen but their families as well. Rebuilt in the early 2000's, all of our cabins have all the comforts of home. Sporting a huge **beach** with multiple water toys for those sunny summer days and a Lodge full of games for when you just can't swim anymore, there's always something for the family to do. A full marina offers watercraft rentals, boat launch, powered dock slips, canoes (free to use), & fish cleaning facility. Rent pontoons, 14' fishing boats, 16' fishing rigs or jet ski's for a fun day or week on the water. Pets are accepted in the lakeside cottages.",
      "Tags": [
        "24-hour front desk service",
        "pool",
        "coffee in lobby"
      ]
    },
    {
      "@search.score": 1.0162708,
      "HotelName": "Campus Commander Hotel",
      "Description": "Easy **access** to campus and steps away from the best shopping corridor in the city. From meetings in town or gameday, enjoy our prime location between the union and proximity to the university stadium.",
      "Tags": [
        "free parking",
        "coffee in lobby",
        "24-hour front desk service"
      ]
    },
    {
      "@search.score": 0.9050383,
      "HotelName": "Lakeside B & B",
      "Description": "Nature is Home on the **beach**. Explore the shore by day, and then come home to our shared living space to relax around a stone fireplace, sip something warm, and explore the library by night. Save up to 30 percent. Valid Now through the end of the year. Restrictions and blackouts may apply.",
      "Tags": [
        "laundry service",
        "concierge",
        "free parking"
      ]
    },
    {
      "@search.score": 0.8955848,
      "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.",
      "Tags": [
        "pool",
        "air conditioning",
        "bar"
      ]
    },
    {
      "@search.score": 0.83636594,
      "HotelName": "Happy Lake Resort & Restaurant",
      "Description": "The largest year-round resort in the area offering more of everything for your vacation – at the best value! What can you enjoy while at the resort, aside from the mile-long sandy **beaches** of the lake? Check out our activities sure to excite both young and young-at-heart guests. We have it all, including being named “Property of the Year” and a “Top Ten Resort” by top publications.",
      "Tags": [
        "pool",
        "bar",
        "restaurant"
      ]
    },
    {
      "@search.score": 0.7808502,
      "HotelName": "Swirling Currents Hotel",
      "Description": "Spacious rooms, glamorous suites and residences, rooftop pool, walking **access** to shopping, dining, entertainment and the city center. Each room comes equipped with a microwave, a coffee maker and a minifridge. In-room entertainment includes complimentary W-Fi and flat-screen TVs. ",
      "Tags": [
        "air conditioning",
        "laundry service",
        "24-hour front desk service"
      ]
    }
  ]
}

Na consulta após, repita a pesquisa, desta vez aumentando os resultados com o termo praia em vez do termo acesso. Uma versão da consulta legível para humanos é search=Description:beach^2 access. De acordo com seu cliente, você pode ter que expressar ^2 como %5E2.

POST /indexes/hotel-samples-index/docs/search?api-version=2024-07-01
{
    "search": "Description:beach^2 access",
    "queryType": "full",
    "select": "HotelName, Description, Tags",
    "searchFields": "HotelName, Description, Tags",
    "count": true
}

Depois de impulsionar o termo praia, a partida no Campus Commander Hotel passa para o quinto lugar.

{
  "@odata.count": 6,
  "value": [
    {
      "@search.score": 2.137338,
      "HotelName": "Johnson's Family Resort",
      "Description": "Family oriented resort located in the heart of the northland. Operated since 1962 by the Smith family, we have grown into one of the largest family resorts in the state. The home of excellent Smallmouth Bass fishing with 10 small cabins, we're a home not only to fishermen but their families as well. Rebuilt in the early 2000's, all of our cabins have all the comforts of home. Sporting a huge beach with multiple water toys for those sunny summer days and a Lodge full of games for when you just can't swim anymore, there's always something for the family to do. A full marina offers watercraft rentals, boat launch, powered dock slips, canoes (free to use), & fish cleaning facility. Rent pontoons, 14' fishing boats, 16' fishing rigs or jet ski's for a fun day or week on the water. Pets are accepted in the lakeside cottages.",
      "Tags": [
        "24-hour front desk service",
        "pool",
        "coffee in lobby"
      ]
    },
    {
      "@search.score": 1.8100766,
      "HotelName": "Lakeside B & B",
      "Description": "Nature is Home on the beach. Explore the shore by day, and then come home to our shared living space to relax around a stone fireplace, sip something warm, and explore the library by night. Save up to 30 percent. Valid Now through the end of the year. Restrictions and blackouts may apply.",
      "Tags": [
        "laundry service",
        "concierge",
        "free parking"
      ]
    },
    {
      "@search.score": 1.7911696,
      "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.",
      "Tags": [
        "pool",
        "air conditioning",
        "bar"
      ]
    },
    {
      "@search.score": 1.6727319,
      "HotelName": "Happy Lake Resort & Restaurant",
      "Description": "The largest year-round resort in the area offering more of everything for your vacation – at the best value! What can you enjoy while at the resort, aside from the mile-long sandy beaches of the lake? Check out our activities sure to excite both young and young-at-heart guests. We have it all, including being named “Property of the Year” and a “Top Ten Resort” by top publications.",
      "Tags": [
        "pool",
        "bar",
        "restaurant"
      ]
    },
    {
      "@search.score": 1.0162708,
      "HotelName": "Campus Commander Hotel",
      "Description": "Easy access to campus and steps away from the best shopping corridor in the city. From meetings in town or gameday, enjoy our prime location between the union and proximity to the university stadium.",
      "Tags": [
        "free parking",
        "coffee in lobby",
        "24-hour front desk service"
      ]
    },
    {
      "@search.score": 0.7808502,
      "HotelName": "Swirling Currents Hotel",
      "Description": "Spacious rooms, glamorous suites and residences, rooftop pool, walking access to shopping, dining, entertainment and the city center. Each room comes equipped with a microwave, a coffee maker and a minifridge. In-room entertainment includes complimentary W-Fi and flat-screen TVs. ",
      "Tags": [
        "air conditioning",
        "laundry service",
        "24-hour front desk service"
      ]
    }
  ]
}

Exemplo 5: Regex

Uma pesquisa de expressão regular localiza uma correspondência com base no conteúdo entre barras de encaminhamento /, conforme documentado na classe RegExp.

POST /indexes/hotel-samples-index/docs/search?api-version=2024-07-01
{
    "search": "HotelName:/(Mo|Ho)tel/",
    "queryType": "full",
    "select": "HotelName",
    "count": true
}

A resposta para esta consulta deve ser semelhante ao exemplo a seguir, encurtado para brevidade:

{
  "@odata.count": 25,
  "value": [
    {
      "@search.score": 1,
      "HotelName": "Country Residence Hotel"
    },
    {
      "@search.score": 1,
      "HotelName": "Downtown Mix Hotel"
    },
    {
      "@search.score": 1,
      "HotelName": "Gastronomic Landscape Hotel"
    },
    . . . 
    {
      "@search.score": 1,
      "HotelName": "Trails End Motel"
    },
    {
      "@search.score": 1,
      "HotelName": "Nordick's Valley Motel"
    },
    {
      "@search.score": 1,
      "HotelName": "King's Cellar Hotel"
    }
  ]
}

Observação

Consultas Regex não são analisadas. A única transformação realizada em termos de consulta parcial é colocá-los em letras minúsculas.

Você pode usar a sintaxe geralmente reconhecida para pesquisas com vários caracteres curinga (*) ou um caractere curinga (?). O analisador de consulta Lucene dá suporte ao uso desses símbolos com um único termo e não a uma frase.

Nesta consulta, pesquise nomes de hotéis que contenham o prefixo sc. Você não pode usar um símbolo * ou ? como o primeiro caractere de uma pesquisa.

POST /indexes/hotel-samples-index/docs/search?api-version=2024-07-01
{
    "search": "HotelName:sc*",
    "queryType": "full",
    "select": "HotelName",
    "count": true
}

A resposta para essa consulta deve ser semelhante ao exemplo a seguir:

{
  "@odata.count": 1,
  "value": [
    {
      "@search.score": 1,
      "HotelName": "Waterfront Scottish Inn"
    }
  ]
}

Observação

Consultas com curingas não são analisadas. A única transformação realizada em termos de consulta parcial é colocá-los em letras minúsculas.

Conteúdo relacionado

Experimente especificar as consultas no código. O link a seguir explica como configurar consultas de pesquisa usando SDKs do Azure.

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