Filtros em consultas de texto

  • Artigo

Um filtro fornece critérios baseados em valor para incluir ou excluir conteúdo antes da execução da consulta. Por exemplo, incluir ou excluir documentos com base em datas, locais ou idioma. Os filtros são especificados em campos individuais. Uma definição de campo deve ser atribuída como "filtrável" se você quiser usá-la em expressões de filtro.

Um filtro é especificado usando a sintaxe de expressão de filtro OData. Em contraste com a pesquisa de texto completo, um filtro só é bem-sucedido 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 "encontrar 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 geolocalização, a categoria de faceta selecionada pelo usuário ou o ID de segurança do solicitante.

Cenários comuns incluem:

  • Fatie os resultados da pesquisa 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 aos critérios (em Seattle, na água, com uma vista).

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

    • A navegação facetada usa um filtro para passar de volta 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 de "encontrar perto de mim" que correspondem dentro de 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 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 baseados 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 incluir no processamento a jusante 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 recuperação da operação de pesquisa subsequente. Quando usado sozinho (por exemplo, quando a cadeia de caracteres de consulta está vazia onde search=*), o critério de filtro é a única entrada.

Definição de filtros

Os filtros são expressões OData, articuladas na sintaxe de filtro suportada pelo Azure AI Search.

Você pode especificar um filtro para cada operação de pesquisa , mas o filtro em si 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 (sujeito às regras de precedência do operador). Não há ganho apreciável de desempenho se você tentar reorganizar predicados em uma sequência específica.

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

Os exemplos a seguir representam definições de filtro prototípicas em várias APIs.

POST https://[service name].search.windows.net/indexes/hotels/docs/search?api-version=2020-06-30
{
    "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 caracteres de consulta, útil quando a expressão de filtro é capaz de qualificar totalmente documentos de interesse. Sem uma seqüência de caracteres de consulta, não há análise lexical ou linguística, nenhuma pontuação e nenhuma classificação. Observe que a string 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, onde o filtro cria o subconjunto e a cadeia de caracteres de consulta fornece as entradas de termos para pesquisa de texto completo sobre o subconjunto filtrado. A adição de termos (teatros a uma curta distância) introduz pontuações de pesquisa nos resultados, onde os documentos que melhor correspondem aos termos são classificados 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 compostas, separadas por "ou", cada uma com 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 de documentos correspondentes a cada expressão enviada de volta na resposta. Este padrão de uso é alcançado através 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 via search.ismatchscoring com filtros usando and em vez de , mas isso é funcionalmente equivalente a usar os search parâmetros e $filter em uma solicitação de orpesquisa. 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á ativado por padrão para campos simples. Os campos filtráveis 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 configurações para definições de campo, consulte Criar índice.

No SDK do .NET, o filtrável está desativado por padrão. Você pode tornar um campo filtrável definindo a propriedade IsFilterable do objeto SearchField correspondente como true. No próximo exemplo, o atributo é definido na Rating propriedade de uma classe de modelo que mapeia 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 campos existentes para torná-los filtráveis. Em vez disso, você precisa adicionar um novo campo ou reconstruir o índice. Para obter mais informações sobre como recriar um índice ou repreencher campos, consulte Como reconstruir um índice do Azure AI Search.

Fundamentos do filtro de texto

Os filtros de texto correspondem aos campos de cadeia de caracteres com as cadeias de caracteres literais fornecidas 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 contém "dia ensolarado", $filter=f eq 'sunny' não corresponde, mas $filter=f eq 'sunny day' irá.

As cadeias de texto diferenciam maiúsculas de minúsculas, o que significa que os filtros de texto diferenciam maiúsculas de minúsculas por padrão. Por exemplo, $filter=f eq 'Sunny day' não vai encontrar "dia ensolarado". No entanto, você pode usar um normalizador para que a filtragem não diferencie maiúsculas de minúsculas.

Abordagens para filtragem de texto

Abordagem Description Quando utilizar o
search.in Uma função que corresponde a um campo em relação a uma lista delimitada de cadeias de caracteres. Recomendado para filtros de segurança e para quaisquer filtros em que muitos valores de texto bruto precisem ser correspondidos com um campo de cadeia de caracteres. A função search.in é projetada para velocidade e é muito mais rápida do que comparar explicitamente o campo contra cada string usando eq e or.
search.ismatch Uma função que permite misturar operações de pesquisa de texto completo com operações de filtro estritamente booleanas na mesma expressão de filtro. Use search.ismatch (ou seu equivalente de pontuação, search.ismatchscoring) quando quiser várias combinações de filtro de pesquisa em uma solicitação. Você também pode usá-lo para um filtro contains para filtrar em uma cadeia de caracteres parcial dentro de uma cadeia de caracteres maior.
$filter=field operator string Uma expressão definida pelo usuário composta de campos, operadores e valores. Use isso quando quiser encontrar correspondências exatas entre um campo de cadeia de caracteres e um valor de cadeia de caracteres.

Fundamentos do filtro numérico

Os campos numéricos não searchable estão no contexto da pesquisa de texto completo. Apenas as 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á de volta itens com preço de US$ 99,99. Em vez disso, você veria itens com o número 99 em campos de cadeia de caracteres do documento. Assim, se você tiver dados numéricos, a suposição é que você os usará para filtros, incluindo intervalos, facetas, grupos e assim por diante.

Os 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 campos numéricos.

Próximos passos

Primeiro, tente o explorador de pesquisa no portal para enviar consultas com parâmetros $filter . O índice de amostra 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