Filtros para pesquisa por palavras-chave no Pesquisa de IA do Azure

Um filtro fornece critérios baseados em valores para incluir ou excluir conteúdo antes da execução da consulta para pesquisa por palavras-chave, ou antes ou depois da execução da consulta para pesquisa vetorial. Os filtros são aplicados a campos não vetoriais, mas podem ser usados na pesquisa vetorial se os documentos incluírem campos não vetoriais. Por exemplo, para indexações baseadas em conteúdos fragmentados, pode ter campos de nível superior ou campos de metadados que podem ser alvo de filtragem.

Este artigo explica o filtragem para pesquisa por palavras-chave. Para mais informações sobre vetores, veja Adicionar um filtro numa consulta vetorial.

Um filtro é especificado usando a sintaxe de expressão do filtro OData. Em contraste com a pesquisa por palavras-chave e a pesquisa vetorial, um filtro só funciona se houver uma correspondência exata.

Quando usar um filtro

Os filtros são fundamentais para várias experiências de pesquisa, incluindo a pesquisa geoespacial "encontrar perto de mim", navegação facetada e filtros de segurança que mostram apenas os documentos que o utilizador pode ver. Se implementares qualquer uma destas experiências, é necessário um filtro. É o filtro associado à consulta de pesquisa que fornece as coordenadas de geolocalização, a categoria de faceta selecionada pelo utilizador ou o ID de segurança do requerente.

Cenários comuns incluem:

• Corte ou divida os resultados da pesquisa com base no conteúdo do índice. Dado um esquema com localização do hotel, categorias e comodidades, pode criar um filtro para corresponder explicitamente a critérios (em Seattle, junto à água, com vista).

• Implemente uma experiência de pesquisa que venha com uma dependência de filtro:

  • A navegação facetada utiliza um filtro para devolver a categoria facetada selecionada pelo utilizador.
  • A pesquisa geoespacial utiliza um filtro para passar coordenadas da localização atual em aplicações e funções "encontrar perto de mim" que correspondem a uma área ou por distância.
  • Os filtros de segurança passam identificadores de segurança como critérios de filtro, onde uma correspondência no índice serve como proxy para os direitos de acesso ao documento.

• Realiza uma "pesquisa de números". Os campos numéricos são recuperáveis e podem aparecer nos resultados de pesquisa, mas não são pesquisáveis (sujeitos a pesquisa em texto completo) individualmente. Se precisares de critérios de seleção baseados em dados numéricos, usa um filtro.

Como os filtros são executados

No momento da consulta, um analisador de filtros aceita critérios como entrada, converte a expressão em expressões booleanas atómicas representadas como uma árvore e depois avalia a árvore de filtros sobre campos filtráveis num índice.

A filtragem ocorre em conjunto com a pesquisa, qualificando quais os documentos a incluir no processamento posterior para recuperação de documentos e pontuação de relevância. Quando emparelhado com uma cadeia de pesquisa, o filtro reduz efetivamente o conjunto de recordação da operação de pesquisa subsequente. Quando usado isoladamente (por exemplo, quando a cadeia de consulta está vazia onde search=*), o critério do filtro é a única entrada.

Como são definidos os filtros

Filtros aplicam-se a texto e conteúdo numérico (não vetorial) em campos atribuídos como filterable.

Os filtros são expressões OData, articuladas na sintaxe filtro suportada por Pesquisa de IA do Azure.

Pode especificar um filtro para cada operação de pesquisa , mas o filtro pode incluir vários campos, múltiplos critérios e, se usar uma ismatch função, múltiplas expressões de pesquisa em texto completo. Numa expressão de filtro multiparte, pode especificar predicados em qualquer ordem (sujeito às regras de precedência do operador). Não há ganho apreciável de desempenho se tentares rearranjar predicados numa sequência específica.

Um dos limites numa expressão de filtro é o limite máximo de tamanho do pedido. O pedido completo, incluindo o filtro, pode ter um máximo de 16 MB para POST, ou 8 KB para GET. Há também um limite no número de cláusulas na tua expressão do filtro. Uma boa regra prática é que, se tiver centenas de cláusulas, corre o risco de atingir o limite. Recomendamos que desenhe a sua aplicação de forma a não gerar filtros de tamanho ilimitado.

Os exemplos seguintes representam definições prototípicas de filtros em várias APIs.

POST https://[service name].search.windows.net/indexes/hotels/docs/search?api-version=2026-04-01
{
    "search": "*",
    "filter": "Rooms/any(room: room/BaseRate lt 150.0)",
    "select": "HotelId, HotelName, Rooms/Description, Rooms/BaseRate"
}

options = new SearchOptions()
{
    Filter = "Rating gt 4",
    OrderBy = { "Rating desc" }
};

Padrões de filtro

Os exemplos seguintes ilustram vários padrões de utilização para cenários de filtros. Para mais ideias, veja Exemplos de sintaxe > de expressão OData.

• $filter independente, sem uma cadeia de consulta, útil quando a expressão de filtro consegue qualificar totalmente documentos de interesse. Sem uma sequência de consulta, não há análise lexical ou linguística, nem pontuação, nem classificação. Repare que a cadeia de pesquisa é apenas um asterisco, que significa "corresponder a todos os documentos".

  {
    "search": "*",
    "filter": "Rooms/any(room: room/BaseRate ge 60 and room/BaseRate lt 300) and Address/City eq 'Honolulu"
  }
  

• Combinação de cadeia de consulta e $filter, onde o filtro cria o subconjunto e a cadeia de consulta fornece as entradas de termos para pesquisa de texto completo sobre o subconjunto filtrado. A adição de termos (teatros a uma distância de caminhada) introduz pontuações de pesquisa nos resultados, onde os documentos que melhor correspondem aos termos são classificados mais altos. Usar um filtro com uma cadeia de consulta é o padrão de uso mais comum.

  {
    "search": "walking distance theaters",
    "filter": "Rooms/any(room: room/BaseRate ge 60 and room/BaseRate lt 300) and Address/City eq 'Seattle'"
  }
  
  

• Consultas compostas, separadas por "ou", cada uma com os seus próprios critérios de filtro (por exemplo, 'beagles' em 'cão' ou 'siamês' em 'gato'). As expressões combinadas com or são avaliadas individualmente, com a união dos documentos que correspondem a cada expressão incluída na resposta. Este padrão de utilização é alcançado através da search.ismatchscoring função. Também pode usar a versão sem pontuação, search.ismatch.

  # Match on hostels rated higher than 4 OR 5-star motels.
  $filter=search.ismatchscoring('hostel') and Rating ge 4 or search.ismatchscoring('motel') and Rating eq 5
  
  # Match on 'luxury' or 'high-end' in the description field OR on category exactly equal to 'Luxury'.
  $filter=search.ismatchscoring('luxury | high-end', 'Description') or Category eq 'Luxury'&$count=true
  

  Também é possível combinar a pesquisa de texto completo via search.ismatchscoring com filtros usando and em vez de or, mas isto é funcionalmente equivalente a usar os search parâmetros e $filter num pedido de pesquisa. Por exemplo, as seguintes duas consultas produzem o mesmo resultado:

  $filter=search.ismatchscoring('pool') and Rating ge 4
  
  search=pool&$filter=Rating ge 4
  

Requisitos de campo para filtragem

Na API REST, o filtro está ativado por defeito para campos simples. Campos filtráveis aumentam o tamanho do índice; Certifica-te de definir "filterable": false campos que não planeias realmente usar num filtro. Para mais informações sobre definições de campos, consulte Criar Índice.

Nos SDKs do Azure, o filtrável está desligado por padrão. Pode tornar um campo filtrável definindo a propriedade IsFilterable do objeto SearchField correspondente para true. No exemplo seguinte, o atributo é definido na Rating propriedade de uma classe de modelo que corresponde à definição do índice.

[SearchField(IsFilterable = true, IsSortable = true, IsFacetable = true)]
public double? Rating { get; set; }

Tornar um campo existente filtrável

Não podes modificar campos existentes para os tornar filtráveis. Em vez disso, precisa de adicionar um novo campo ou reconstruir o índice. Para mais informações sobre reconstrução de um índice ou repovoamento de campos, consulte Como reconstruir um índice Pesquisa de IA do Azure.

Fundamentos do filtro de texto

Os filtros de texto comparam campos de strings com strings literais que forneces no filtro: $filter=Category eq 'Resort and Spa'

Ao contrário da pesquisa de texto completo, não há análise lexical nem quebra de palavras para filtros de texto, por isso as comparações são apenas para correspondências exatas. Por exemplo, suponha que um campo f contém "dia de sol", $filter=f eq 'sunny' não corresponderá, mas $filter=f eq 'sunny day' corresponderá.

As cadeias de texto são sensíveis a maiúsculas e minúsculas, o que significa que os filtros de texto são sensíveis a maiúsculas e minúsculas por padrão. Por exemplo, $filter=f eq 'Sunny day' não encontra "dia de sol". No entanto, podes usar um normalizador para que a filtragem não seja sensível a maiúsculas e minúsculas.

Abordagens para filtragem no texto

Fundamentos do filtro numérico

Os campos numéricos não são searchable no contexto da pesquisa por texto completo. Apenas as strings estão sujeitas a pesquisa em texto completo. Por exemplo, se introduzir 99,99 como termo de pesquisa, não receberá itens com preço de $99,99. Em vez disso, verias itens com o número 99 nos campos de string do documento. Assim, se tiver dados numéricos, assume-se que os usará para filtros, incluindo alcances, facetas, grupos, e assim por diante.

Documentos que contêm campos numéricos (preço, tamanho, SKU, ID) fornecem esses valores nos resultados de pesquisa se o campo estiver marcado retrievable. O ponto aqui é que a pesquisa em texto completo em si não é aplicável a tipos numéricos de campo.

Próximos passos

Primeiro, tente explorador de pesquisa no portal Azure para submeter consultas com parâmetros $filter. O índice de exemplos imobiliários fornece resultados interessantes para as seguintes consultas filtradas quando as insere na barra de pesquisa:

# Geo-filter returning documents within 5 kilometers of Redmond, Washington state
# Use $count=true to get a number of hits returned by the query
# Use $select to trim results, showing values for named fields only
# Use search=* for an empty query string. The filter is the sole input

search=*&$count=true&$select=description,city,postCode&$filter=geo.distance(location,geography'POINT(-122.121513 47.673988)') le 5

# Numeric filters use comparison like greater than (gt), less than (lt), not equal (ne)
# Include "and" to filter on multiple fields (baths and bed)
# Full text search is on John Leclerc, matching on John or Leclerc

search=John Leclerc&$count=true&$select=source,city,postCode,baths,beds&$filter=baths gt 3 and beds gt 4

# Text filters can also use comparison operators
# Wrap text in single or double quotes and use the correct case
# Full text search is on John Leclerc, matching on John or Leclerc

search=John Leclerc&$count=true&$select=source,city,postCode,baths,beds&$filter=city gt 'Seattle'

Para trabalhar com mais exemplos, veja Exemplos de Sintaxe > de Expressões do Filtro OData.

Ver também

• Como funciona a pesquisa de texto completo em Pesquisa de IA do Azure
• API REST de Pesquisa de Documentos
• Sintaxe simples de consulta
• Sintaxe de consulta Lucene
• Tipos de dados suportados