Filtros no Azure Cognitive Search

  • Artigo

Um filtro fornece critérios baseados em valores para incluir ou excluir conteúdo antes da execução da consulta. Por exemplo, incluindo ou excluindo documentos com base em datas, localizações ou idioma. Os filtros são especificados em campos individuais. Uma definição de campo tem de ser atribuída como "filtráveis" se quiser utilizá-la em expressões de filtro.

É especificado um filtro com a sintaxe da expressão do filtro OData. Em contraste com a pesquisa em texto completo, um filtro só é bem-sucedido se a correspondência for exata.

Quando utilizar um filtro

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

Os cenários comuns incluem o seguinte:

  • Segmente os resultados da pesquisa com base no conteúdo no índice. Tendo em conta um esquema com localização de hotel, categorias e comodidades, pode criar um filtro para corresponder explicitamente aos critérios (em Seattle, na água, com vista).

  • Implementar uma experiência de pesquisa inclui uma dependência de filtro:

    • A navegação por facetas utiliza um filtro para transmitir a categoria de facetas selecionada pelo utilizador.
    • A pesquisa geoespacial utiliza um filtro para transmitir coordenadas da localização atual em aplicações e funções "localizar perto de mim" que correspondem dentro de uma área ou por distância.
    • Os filtros de segurança transmitem 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.

  • Efetue 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 a pesquisa em texto completo) individualmente. Se precisar de critérios de seleção com base em dados numéricos, utilize 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, em seguida, avalia a árvore de filtros em campos filtráveis num índice.

A filtragem ocorre em conjunto com a pesquisa, qualificando os documentos a incluir no processamento a jusante para obtenção de documentos e classificação por relevância. Quando emparelhado com uma cadeia de pesquisa, o filtro reduz eficazmente o conjunto de recuperação da operação de pesquisa subsequente. Quando utilizado apenas (por exemplo, quando a cadeia de consulta está vazia em que search=*), os critérios de filtro são a única entrada.

Definir filtros

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

Pode especificar um filtro para cada operação de pesquisa , mas o filtro em si pode incluir vários campos, múltiplos critérios e, se utilizar uma função ismatch , várias expressões de pesquisa de texto completo. Numa expressão de filtro de várias partes, pode especificar predicados por qualquer ordem (sujeito às regras de precedência do operador). Não haverá ganhos apreciáveis no desempenho se tentar reorganizar predicados numa sequência específica.

Um dos limites de uma expressão de filtro é o limite de tamanho máximo do pedido. O pedido completo, incluindo o filtro, pode ser um máximo de 16 MB para POST ou 8 KB para GET. Também existe um limite para o número de cláusulas na expressão de filtro. Uma boa regra é que, se tiver centenas de cláusulas, corre o risco de chegar ao limite. Recomendamos que crie a sua aplicação de forma a não gerar filtros de tamanho não vinculado.

Os exemplos seguintes representam definições de filtros prototípicos 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"
}

    parameters =
        new SearchParameters()
        {
            Filter = "Rooms/any(room: room/BaseRate lt 150.0)",
            Select = new[] { "HotelId", "HotelName", "Rooms/Description" ,"Rooms/BaseRate"}
        };

    var results = searchIndexClient.Documents.Search("*", parameters);

Padrões de filtro

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

  • A $filter autónoma, sem uma cadeia de consulta, é útil quando a expressão de filtro é capaz de qualificar completamente documentos de interesse. Sem uma cadeia de consulta, não há análise lexical ou linguística, nem classificação nem classificação. Repare que a cadeia de pesquisa é apenas um asterisco, o 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 o termo entradas para pesquisa de texto completo sobre o subconjunto filtrado. A adição de termos (salas de distância a pé) introduz pontuações de pesquisa nos resultados, onde os documentos que melhor correspondem aos termos estão classificados mais alto. Utilizar um filtro com uma cadeia de consulta é o padrão de utilização 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 "siamese" 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 utilização é alcançado através da search.ismatchscoring função . Também pode utilizar a versão sem classificaçã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 em texto completo através search.ismatchscoring de filtros em and vez de or, mas isto é funcionalmente equivalente à utilização dos search parâmetros e $filter num pedido de pesquisa. Por exemplo, as duas consultas seguintes 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 opção filtráveis está ativada por predefinição para campos simples. Os campos filtráveis aumentam o tamanho do índice; certifique-se de que define "filterable": false para campos que não planeia utilizar num filtro. Para obter mais informações sobre as definições de campos, veja Criar Índice.

No SDK .NET, o filtráveis está desativado por predefinição. Pode tornar um campo filtráveis ao definir a propriedade IsFilterable do objeto SearchField correspondente como true. No exemplo abaixo, o atributo é definido na BaseRate propriedade de uma classe de modelo que mapeia para a definição de índice.

[IsFilterable, IsSortable, IsFacetable]
public double? BaseRate { get; set; }

Tornar um campo existente filtráveis

Não pode modificar campos existentes para os tornar filtráveis. Em vez disso, tem de adicionar um novo campo ou reconstruir o índice. Para obter mais informações sobre como reconstruir um índice ou repovoar campos, veja Como reconstruir um índice de Azure Cognitive Search.

Noções básicas do filtro de texto

Os filtros de texto correspondem aos campos de cadeias de carateres literais fornecidos no filtro: $filter=Category eq 'Resort and Spa'

Ao contrário da pesquisa em texto completo, não há análise lexical ou quebra de palavras para filtros de texto, pelo que 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 são sensíveis às maiúsculas e minúsculas, o que significa que os filtros de texto são sensíveis às maiúsculas e minúsculas por predefinição. Por exemplo, $filter=f eq 'Sunny day' não encontrará "dia ensolarado". No entanto, pode utilizar um normalizador para torná-lo para que a filtragem não seja sensível às maiúsculas e minúsculas.

Abordagens para filtrar texto

Abordagem Descrição Quando utilizar
search.in Uma função que corresponde a um campo com uma lista delimitada de cadeias. Recomendado para filtros de segurança e para quaisquer filtros em que muitos valores de texto não processados precisem de ser correspondidos com um campo de cadeia. A função search.in foi concebida para a velocidade e é muito mais rápida do que comparar explicitamente o campo com cada cadeia com eq e or.
search.ismatch Uma função que lhe permite misturar operações de pesquisa em texto completo com operações de filtro estritamente booleanas na mesma expressão de filtro. Utilize search.ismatch (ou o equivalente à classificação, search.ismatchscoring) quando quiser múltiplas combinações de filtro de pesquisa num pedido. Também pode utilizá-lo para um filtro contém para filtrar uma cadeia parcial dentro de uma cadeia maior.
$filter=field operator string Uma expressão definida pelo utilizador composta por campos, operadores e valores. Utilize esta opção quando quiser encontrar correspondências exatas entre um campo de cadeia e um valor de cadeia.

Noções básicas do filtro numérico

Os campos numéricos não searchable estão no contexto da pesquisa em texto completo. Apenas as cadeias de carateres estão sujeitas a pesquisa em texto completo. Por exemplo, se introduzir 99,99 como um termo de pesquisa, não receberá itens com um preço de 99,99 $. Em vez disso, veria os itens que têm o número 99 nos campos de cadeia do documento. Assim, se tiver dados numéricos, a suposição é que os utilizará para filtros, incluindo intervalos, facetas, grupos, etc.

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 como retrievable. O ponto aqui é que a pesquisa de texto completo em si não é aplicável a tipos de campo numéricos.

Passos seguintes

Primeiro, experimente o Explorador de pesquisa no portal para submeter consultas com $filter parâmetros. O índice real-estate-sample fornece resultados interessantes para as seguintes consultas filtradas ao colá-las 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ão de Filtro OData.

Ver também