Filtros para pesquisa de palavra-chave no Pesquisa de IA do Azure 

Um filtro fornece critérios baseados em valor para incluir ou excluir conteúdo antes da execução da consulta para pesquisa de palavra-chave ou antes ou depois da execução da consulta para pesquisa de vetor. Os filtros são aplicados a campos não vetoriais, mas podem ser usados na pesquisa de vetor se os documentos incluem campos não vetoriais. Por exemplo, para índices organizados em torno de conteúdo segmentado, você pode ter campos de nível superior ou campos de metadados que podem ser filtrados.

Este artigo explica a filtragem da pesquisa de palavras-chave. Para obter mais informações sobre vetores, consulte Adicionar um filtro em uma consulta de vetor.

Um filtro é especificado usando a sintaxe de expressão de filtro OData. Em contraste com a palavra-chave e a pesquisa de vetor, um filtro só terá êxito se a correspondência for exata.

Quando usar um filtro

Os filtros são fundamentais para várias experiências de pesquisa, incluindo pesquisa geoespacial "localizar perto de mim", navegação facetada e filtros de segurança que mostram apenas os documentos que um usuário tem permissão para ver. Se você implementar qualquer uma dessas experiências, um filtro será necessário. É o filtro anexado à consulta de pesquisa que fornece as coordenadas de localização geográfica, a categoria de faceta selecionada pelo usuário ou a ID de segurança do solicitante.

Cenários comuns incluem:

• Segmentar os resultados da pesquisa com base no conteúdo no índice. Considerando um esquema com localização de hotel, categorias e comodidades, você pode criar um filtro para corresponder explicitamente aos critérios (em Seattle, à beira d'água, com vista).

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

  • A navegação facetada utiliza um filtro para transmitir a categoria de faceta selecionada pelo usuário.
  • A pesquisa geoespacial usa um filtro para passar as coordenadas da localização atual em aplicativos e funções "encontrar perto de mim" que correspondem dentro de uma área ou por distância.
  • Filtros de segurança utilizam identificadores de segurança como critérios de filtro, onde uma correspondência no índice serve como um proxy para os direitos de acesso ao documento.

• Faça uma "pesquisa de números". Os campos numéricos são recuperáveis e podem aparecer nos resultados da pesquisa, mas não são pesquisáveis (sujeitos à pesquisa de texto completo) individualmente. Se você precisar de critérios de seleção com base em dados numéricos, use um filtro.

Como os filtros são executados

No momento da consulta, um analisador de filtro aceita critérios como entrada, converte a expressão em expressões boolianas atômicas representadas como uma árvore e, em seguida, avalia a árvore de filtro sobre campos filtrados em um índice.

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

Como os filtros são definidos

Os filtros se aplicam ao conteúdo de texto e numérico (não vetor) em campos que são atribuídos como filterable.

Os filtros são expressões OData, articuladas na sintaxe filtro compatíveis com Pesquisa de IA do Azure .

Você pode especificar um filtro para cada operação de pesquisa , mas o próprio filtro pode incluir vários campos, vários critérios e, se você usar uma ismatch função, várias expressões de pesquisa de texto completo. Em uma expressão de filtro de várias partes, você pode especificar predicados em qualquer ordem (sujeitos às regras de precedência do operador). Não haverá ganho appreciável no desempenho se você tentar reorganizar predicados em uma sequência específica.

Um dos limites em uma expressão de filtro é o limite de tamanho máximo da solicitação. A solicitação inteira, inclusive do filtro, pode ser no máximo 16 MB para POST ou 8 KB para GET. Também há um limite no número de cláusulas em sua expressão de filtro. Uma boa regra geral é que, se você tiver centenas de cláusulas, correrá o risco de atingir o limite. Recomendamos projetar seu aplicativo de forma que ele não gere filtros de tamanho ilimitado.

Os exemplos a seguir representam definições de filtro prototípico 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 a seguir ilustram vários padrões de uso para cenários de filtro. Para obter mais ideias, consulte exemplos de sintaxe > de expressão OData.

• $filter autônomo, sem uma cadeia de consulta, útil quando a expressão de filtro puder qualificar totalmente documentos de interesse. Sem uma cadeia de caracteres de consulta, não há nenhuma análise lexical ou linguística, nenhuma pontuação e nenhuma classificação. Observe que a cadeia de caracteres 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 caracteres de consulta e $filter, em que o filtro cria o subconjunto e a cadeia de caracteres de consulta fornece as entradas de termo para pesquisa de texto completo sobre o subconjunto filtrado. A adição de termos (percorrendo teatros de distância) apresenta as pontuações de pesquisa nos resultados, onde os documentos que melhor correspondam aos termos são classificados como mais altos. Usar um filtro com uma cadeia de caracteres 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 composta, separadas por "or", cada uma com seus próprios critérios de filtro (por exemplo, “beagles" em "dog" ou "siamese" em "cat"). Expressões combinadas com or são avaliadas individualmente, com a União de documentos que correspondem a cada expressão enviada de volta na resposta. Esse padrão de uso é alcançado por meio da search.ismatchscoring função. Você 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 por meio de search.ismatchscoring com filtros usando and em vez de or, mas isso é funcionalmente equivalente ao uso dos parâmetros search e $filter em uma solicitação de pesquisa. Por exemplo, as duas consultas a seguir 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, a filtragem está ativada por padrão para campos simples. Campos filtrados aumentam o tamanho do índice; certifique-se de definir "filterable": false para campos que você não planeja realmente usar em um filtro. Para obter mais informações sobre as configurações para definições de campo, consulte Criar Índice.

No SDKs do Azure, a filtragem é off por padrão. Você pode tornar um campo filtreável definindo a propriedade IsFilterable do objeto SearchField correspondente como true. No exemplo a seguir, o atributo é definido na propriedade Rating de uma classe de modelo que é mapeada para a definição de índice.

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

Tornando um campo existente filtrável

Não é possível modificar os campos existentes para torná-los filtrados. Em vez disso, você precisa adicionar um novo campo ou recompilar o índice. Para obter mais informações sobre como recriar um índice ou repovoar campos, consulte Como recriar um índice Pesquisa de IA do Azure .

Conceitos básicos do filtro de texto

Os filtros de texto comparam campos de texto a textos literais que você fornece no filtro: $filter=Category eq 'Resort and Spa'

Ao contrário da pesquisa de texto completo, não há análise lexical ou quebra de palavras para filtros de texto, portanto, as comparações são apenas para correspondências exatas. Por exemplo, suponha que um campo f contenha "dia ensolarado", $filter=f eq 'sunny' não corresponde, mas $filter=f eq 'sunny day' irá.

As cadeias de caracteres de texto diferenciam maiúsculas de minúsculas, o que significa que os filtros de texto também diferenciam por padrão. Por exemplo, $filter=f eq 'Sunny day' não encontrará "dia ensolarado". No entanto, você pode usar um normalizador para tornar a filtragem não sensível a maiúsculas e minúsculas.

Abordagens para filtragem no texto

Conceitos básicos do filtro numérico

Os campos numéricos não fazem parte do contexto da pesquisa de texto completo. Somente cadeias de caracteres estão sujeitas à pesquisa de texto completo. Por exemplo, se você inserir 99,99 como um termo de pesquisa, não receberá itens de volta com preço de US$ 99,99. Em vez disso, você veria itens que têm o número 99 em campos de cadeia de caracteres do documento. Portanto, se você tiver dados numéricos, a suposição é que você os usará para filtros, incluindo intervalos, facetas, grupos e assim por diante.

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

Próximas etapas

Primeiro, tente Search Explorer no portal Azure para enviar consultas com parâmetros $filter. O índice de exemplo de imóveis fornece resultados interessantes para as seguintes consultas filtradas quando você as cola 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, consulte exemplos de sintaxe > de expressão de filtro OData.

Consulte também

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