Filtros na pesquisa de palavra-chave

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 em partes, você pode ter campos de nível pai 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, confira Adicionar um filtro em uma consulta de vetor.

Um filtro é especificado usando a sintaxe de expressão de filtro OData. Diferente da pesquisa de palavra-chave e busca em vetores, um filtro só terá êxito se houver uma combinação exata.

Quando usar um filtro

Os filtros são fundamentais para as várias experiências de pesquisa, incluindo pesquisa geoespacial do tipo "Localizar próximo a mim", navegação facetada e filtros de segurança que mostram somente 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 identificação de segurança do solicitante.

Cenários comuns incluem:

• Resultados da pesquisa de fatia com base no conteúdo do índice. Dado um esquema com localização, categorias e comodidades do hotel, você pode criar um filtro para corresponder explicitamente nos critérios (em Seattle, na água, com uma exibição).

• A implementação de uma experiência de pesquisa vem com uma dependência de filtro:

  • A navegação facetada usa um filtro para devolver a categoria de faceta selecionada pelo usuário.
  • A pesquisa geoespacial usa um filtro para passar coordenadas da localização atual em aplicativos e funções "localizar perto de mim" que corresponderem em uma área ou por distância.
  • Os filtros de segurança passam identificadores de segurança como critérios de filtro, em que uma correspondência no índice serve como um proxy para 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 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 booleanas atômicas representadas como uma árvore e, em seguida, avalia a árvore de filtro sobre campos filtráveis em um índice.

A filtragem ocorre em conjunto com a pesquisa, qualificando quais documentos devem ser incluídos no processamento de downstream para recuperação de documentos e a 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 estiver vazio em search=*), os critérios de filtro são a única entrada.

Como os filtros são definidos

Os filtros se aplicam ao conteúdo alfanumérico em campos que são atribuídos como filterable.

Filtros são expressões do OData, articuladas na sintaxe de filtro com suporte da IA do Azure Search.

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 função ismatch, 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 (sujeito às regras de precedência de operador). Não há nenhum ganho significativo no desempenho caso você tente reorganizar predicados em uma determinada sequência.

Um dos limites em uma expressão de filtro é o limite de tamanho máximo da solicitação. Toda a solicitação, incluindo o filtro, pode ter um máximo de 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 prática é que, se você tiver centenas de cláusulas, você correrá o risco de atingir o limite. É recomendável criar o aplicativo de forma que ele não gere filtros de tamanho ilimitado.

Os exemplos a seguir representam as definições de filtro de um modelo em várias APIs.

POST https://[service name].search.windows.net/indexes/hotels/docs/search?api-version=2024-07-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" }
};

Filtrar padrões

Os exemplos a seguir ilustram vários padrões de uso para cenários de filtro. Para obter mais ideias, confira Sintaxe de expressão do OData > Exemplos.

• $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 existe análise linguística, lexical, pontuação e nem classificação. Observe que a cadeia de caracteres de pesquisa é apenas um asterisco, o que significa "corresponder todos os documentos".

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

• A 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 do termo de pesquisa de texto completo no 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. O uso de 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 função search.ismatchscoring. 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 tem uma funcionalidade equivalente a usar os 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, filtrável está habilitado por padrão para campos simples. Campos que podem ser filtrados aumentam o tamanho do índice. Certifique-se de definir "filterable": false para os campos que não planeja usar em um filtro. Para obter mais informações sobre como configurar definições de campo, consulte Criar índice.

Nos SDKs do Azure, a filtragem está desativada por padrão. Você pode tornar um campo filtrá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

Você não pode modificar os campos existentes para torná-los filtráveis. Em vez disso, você precisa adicionar um novo campo ou recompilar o índice. Para obter mais informações sobre como recompilar um índice ou repopular os campos, consulte Como recompilar um índice da IA do Azure Search.

Conceitos básicos do filtro de texto

Os filtros de texto correspondem aos campos de cadeia de caracteres em cadeias literais que você fornece no filtro: $filter=Category eq 'Resort and Spa'

Ao contrário da pesquisa de texto completo, não há nenhuma separação de palavras ou análise lexical em filtros de texto, portanto, as comparações servem somente para correspondências exatas. Por exemplo, considere que um campo f contém "dia ensolarado", $filter=f eq 'sunny' não corresponde, mas $filter=f eq 'sunny day' corresponderá.

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 fazer com que a filtragem não diferencie maiúsculas de minúsculas.

Abordagens para filtragem de texto

Conceitos básicos do filtro numérico

Campos numéricos não são searchable no 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, você não receberá itens com preços de $ 99,99. Em vez disso, você verá os itens que têm o número 99 nos campos de cadeia de caracteres do documento. Assim, se você tiver dados numéricos, supõe-se 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 como retrievable. A questão aqui é que a pesquisa de texto completo em si não é aplicável a tipos de campos numéricos.

Próximas etapas

Primeiro, tente o Search Explorer no portal para enviar consultas com parâmetros $filter. O índice real-estate-sample fornece resultados interessantes para as seguintes consultas filtradas quando você o 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, confira Sintaxe de expressão de filtro OData > Exemplos.

Confira também

• Como funciona a pesquisa de texto completo na IA do Azure Search
• API REST para pesquisar documentos
• Sintaxe de consulta simples
• Sintaxe de consulta Lucene
• Tipos de dados com suporte