Compartilhar via

Funções de pesquisa de texto completo do OData no Azure AI Search – search.ismatch e search.ismatchscoring

O Azure AI Search dá suporte para pesquisa de texto completo no contexto de expressões de filtro do OData por meio das funções search.ismatch e search.ismatchscoring. Essas funções permitem combinar a pesquisa de texto completo com filtragem booliana estrita de maneiras que não são possíveis apenas usando o parâmetro de nível search superior da API de Pesquisa.

Observação

As funções search.ismatch e search.ismatchscoring têm suporte apenas em filtros na API de Pesquisa. Não há suporte para elas nas APIs De sugestão ou preenchimento automático .

Sintaxe

O seguinte EBNF (Formulário Estendido Backus-Naur) define a gramática das funções search.ismatch e search.ismatchscoring:

search_is_match_call ::=
    'search.ismatch'('scoring')?'(' search_is_match_parameters ')'

search_is_match_parameters ::=
    string_literal(',' string_literal(',' query_type ',' search_mode)?)?

query_type ::= "'full'" | "'simple'"

search_mode ::= "'any'" | "'all'"

Um diagrama de sintaxe interativa também está disponível:

Diagrama de sintaxe OData para Azure AI Search

Observação

Confira Referência de sintaxe de expressão OData para Azure AI Search para ver a EBNF completa.

search.ismatch

A função search.ismatch avalia a consulta de pesquisa de texto completo como parte de uma expressão de filtro. Documentos correspondentes são retornados no conjunto de resultados. As seguintes sobrecargas desta função estão disponíveis:

  • search.ismatch(search)
  • search.ismatch(search, searchFields)
  • search.ismatch(search, searchFields, queryType, searchMode)

A tabela abaixo contém os parâmetros:

Nome do parâmetro Tipo Descrição
search Edm.String A consulta de pesquisa (em sintaxe de consulta Lucerne simples ou completa).
searchFields Edm.String Lista separada por vírgulas de campos pesquisáveis, assume como padrão todos os campos pesquisáveis no índice. Quando você usa a searchpesquisa em campo no parâmetro, os especificadores de campo na consulta Lucene substituem todos os campos especificados neste parâmetro.
queryType Edm.String 'simple' ou 'full'; padrão é 'simple'. Especifica qual idioma de consulta foi usado no parâmetro search.
searchMode Edm.String 'any' ou 'all', padrão é 'any'. Indica se deve haver uma correspondência com alguns ou todos os termos de pesquisa no parâmetro search para contar o documento como uma correspondência. Quando você usa os operadores boolianos Lucene no search parâmetro, eles têm precedência sobre esse parâmetro.

Todos os parâmetros acima são equivalentes aos respectivos parâmetros de solicitação de pesquisa na API de Pesquisa.

A search.ismatch função retorna um valor de tipo Edm.Boolean, que permite compor com outras subexpressões de filtro usando os operadores lógicos boolianos.

Observação

O Azure AI Search não dá suporte ao uso search.ismatch ou search.ismatchscoring dentro de expressões lambda. Isso significa que não é possível gravar filtros em coleções de objetos que podem correlacionar correspondências de pesquisa de texto completo com correspondências de filtro estritas no mesmo objeto. Para obter mais informações sobre essa limitação, bem como exemplos, consulte Solucionar problemas de filtros de coleção no Azure AI Search. Veja informações mais detalhadas sobre o motivo dessa limitação em Noções básicas sobre filtros de coleta no Azure AI Search.

search.ismatchscoring

A função search.ismatchscoring, como a função search.ismatch, retorna true para documentos que correspondem à consulta de pesquisa de texto completo passada como um parâmetro. A diferença entre eles é que a pontuação de relevância dos documentos correspondentes à search.ismatchscoring consulta contribui para a pontuação geral do documento, enquanto que, para search.ismatch, a pontuação do documento não é alterada. As seguintes sobrecargas dessa função estão disponíveis com parâmetros idênticos aos de search.ismatch:

  • search.ismatchscoring(search)
  • search.ismatchscoring(search, searchFields)
  • search.ismatchscoring(search, searchFields, queryType, searchMode)

As funções search.ismatch e search.ismatchscoring podem ser usadas na mesma expressão de filtro.

Exemplos

Localizar documentos com as palavras "orla marítima". Essa consulta de filtro é idêntica a uma solicitação de pesquisa com search=waterfront.

    search.ismatchscoring('waterfront')

Aqui está a sintaxe de consulta completa para essa solicitação, que você pode executar no Gerenciador de Pesquisa no portal do Azure. A saída consiste em correspondências na orla, na água e na frente.

{
  "search": "*",
  "select": "HotelId, HotelName, Description",
  "searchMode": "all",
  "queryType": "simple",
  "count": true,
  "filter": "search.ismatchscoring('waterfront')"
}

Encontre documentos com a palavra "pool" e classificação maior ou igual a 4 ou documentos com a palavra "motel" e igual a 3,2. Observe que essa solicitação não pôde ser expressa sem a search.ismatchscoring função.

    search.ismatchscoring('pool') and Rating ge 4 or search.ismatchscoring('motel') and Rating eq 3.2

Aqui está a sintaxe de consulta completa para esta solicitação para o Gerenciador de Pesquisa. A saída consiste em correspondências em hotéis com pools com uma classificação maior que 4 ou motéis com uma classificação igual a 3,2.

{
  "search": "*",
  "select": "HotelId, HotelName, Description, Tags, Rating",
  "searchMode": "all",
  "queryType": "simple",
  "count": true,
  "filter": "search.ismatchscoring('pool') and Rating ge 4 or search.ismatchscoring('motel') and Rating eq 3.2"
}

Localizar documentos sem a palavra "luxo".

    not search.ismatch('luxury')

Aqui está a sintaxe de consulta completa para esta solicitação. A saída consiste em correspondências no termo luxo.

{
  "search": "*",
  "select": "HotelId, HotelName, Description, Tags, Rating",
  "searchMode": "all",
  "queryType": "simple",
  "count": true,
  "filter": "not search.ismatch('luxury')"
}

Encontre documentos com a frase "oceano" ou classificação igual a 3,2. A search.ismatchscoring consulta é executada somente em campos HotelName e Description.

Aqui está a sintaxe de consulta completa para esta solicitação. Documentos que correspondem apenas à segunda cláusula da disjunção também são retornados (especificamente, hotéis com Rating igual a 3.2). Para deixar claro que esses documentos não correspondem a nenhuma das partes pontuadas da expressão, eles são retornados com pontuação igual a zero.

{
  "search": "*",
  "select": "HotelId, HotelName, Description, Rating",
  "searchMode": "all",
  "queryType": "full",
  "count": true,
  "filter": "search.ismatchscoring('ocean', 'Description,HotelName') or Rating eq 3.2"
}

A saída consiste em 4 correspondências: hotéis que mencionam "oceano" na Descrição ou Nome do Hotel ou hotéis com uma classificação de 3.2. Observe a pontuação de pesquisa de zero para correspondências na segunda cláusula.

{
  "@odata.count": 4,
  "value": [
    {
      "@search.score": 1.6076145,
      "HotelId": "18",
      "HotelName": "Ocean Water Resort & Spa",
      "Description": "New Luxury Hotel for the vacation of a lifetime. Bay views from every room, location near the pier, rooftop pool, waterfront dining & more.",
      "Rating": 4.2
    },
    {
      "@search.score": 1.0594962,
      "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.",
      "Rating": 3.5
    },
    {
      "@search.score": 0,
      "HotelId": "40",
      "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.",
      "Rating": 3.2
    },
    {
      "@search.score": 0,
      "HotelId": "26",
      "HotelName": "Planetary Plaza & Suites",
      "Description": "Extend Your Stay. Affordable home away from home, with amenities like free Wi-Fi, full kitchen, and convenient laundry service.",
      "Rating": 3.2
    }
  ]
}

Encontre documentos onde os termos "hotel" e "aeroporto" estão dentro de 5 palavras um do outro na descrição do hotel, e onde fumar não é permitido em pelo menos alguns dos quartos.

    search.ismatch('"hotel airport"~5', 'Description', 'full', 'any') and Rooms/any(room: not room/SmokingAllowed)

Aqui está a sintaxe de consulta completa. Para ser executado no Gerenciador de Pesquisa, escape das aspas internas com um caractere de barra invertida.

{
  "search": "*",
  "select": "HotelId, HotelName, Description, Tags, Rating",
  "searchMode": "all",
  "queryType": "simple",
  "count": true,
  "filter": "search.ismatch('\"hotel airport\"~5', 'Description', 'full', 'any') and Rooms/any(room: not room/SmokingAllowed)"
}

A saída consiste em um único documento em que os termos "hotel" e "aeroporto" estão a uma distância de 5 palavras. Fumar é permitido para vários quartos na maioria dos hotéis, incluindo o deste resultado da pesquisa.

{
  "@odata.count": 1,
  "value": [
    {
      "@search.score": 1,
      "HotelId": "40",
      "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.",
      "Tags": [
        "bar",
        "free wifi",
        "restaurant"
      ],
      "Rating": 3.2
    }
  ]
}

Encontre documentos que tenham uma palavra que comece com as letras "lux" no campo Descrição. Essa consulta usa a pesquisa de prefixo em combinação com search.ismatch.

    search.ismatch('lux*', 'Description')

Aqui está uma consulta completa:

{
  "search": "*",
  "select": "HotelId, HotelName, Description, Tags, Rating",
  "searchMode": "all",
  "queryType": "simple",
  "count": true,
  "filter": "search.ismatch('lux*', 'Description')"
}

A saída consiste nas correspondências a seguir.

{
  "@odata.count": 4,
  "value": [
    {
      "@search.score": 1,
      "HotelId": "18",
      "HotelName": "Ocean Water Resort & Spa",
      "Description": "New Luxury Hotel for the vacation of a lifetime. Bay views from every room, location near the pier, rooftop pool, waterfront dining & more.",
      "Tags": [
        "view",
        "pool",
        "restaurant"
      ],
      "Rating": 4.2
    },
    {
      "@search.score": 1,
      "HotelId": "13",
      "HotelName": "Luxury Lion Resort",
      "Description": "Unmatched Luxury. Visit our downtown hotel to indulge in luxury accommodations. Moments from the stadium and transportation hubs, we feature the best in convenience and comfort.",
      "Tags": [
        "bar",
        "concierge",
        "restaurant"
      ],
      "Rating": 4.1
    },
    {
      "@search.score": 1,
      "HotelId": "16",
      "HotelName": "Double Sanctuary Resort",
      "Description": "5 star Luxury Hotel - Biggest Rooms in the city. #1 Hotel in the area listed by Traveler magazine. Free WiFi, Flexible check in/out, Fitness Center & espresso in room.",
      "Tags": [
        "view",
        "pool",
        "restaurant",
        "bar",
        "continental breakfast"
      ],
      "Rating": 4.2
    },
    {
      "@search.score": 1,
      "HotelId": "14",
      "HotelName": "Twin Vortex Hotel",
      "Description": "New experience in the making. Be the first to experience the luxury of the Twin Vortex. Reserve one of our newly-renovated guest rooms today.",
      "Tags": [
        "bar",
        "restaurant",
        "concierge"
      ],
      "Rating": 4.4
    }
  ]
}

Próximas etapas