Filtragem de metadados

nota

O Amazon S3 Vectors está na versão prévia para o Amazon Simple Storage Service e está sujeito a alterações.

A filtragem de metadados permite que você filtre os resultados da consulta com base em atributos específicos associados aos seus vetores. Você pode usar filtros de metadados com operações de consulta para encontrar vetores que correspondam tanto aos critérios de similaridade quanto às condições específicas de metadados.

O S3 Vectors aceita dois tipos de metadados: metadados filtráveis e metadados não filtráveis. A principal diferença é que os metadados filtráveis podem ser usados em filtros de consulta, mas têm limitações de tamanho mais rígidas, enquanto os metadados não filtráveis não podem ser usados em filtros, mas podem armazenar grandes quantidades de dados de acordo om os respectivos limites de tamanho. Para ter mais informações sobre limites de metadados, como limites de tamanho por vetor e número máximo de chaves de metadados por vetor, consulte Limitações e restrições.

Metadados filtráveis

Os metadados filtráveis permitem que você filtre os resultados da consulta com base em valores de metadados específicos. Por padrão, todos os campos de metadados podem ser filtrados em uma consulta de similaridade, a menos que sejam explicitamente especificados como não filtráveis durante a criação do índice de vetores. O S3 Vectors permite os tipos de metadados de string, número, booliano e lista com um limite de tamanho por vetor. O tipo de metadados é ideal para atributos que você deseja filtrar, como categorias, carimbos de data/hora ou valores de status.

Se o tamanho dos metadados ultrapassar esses limites permitidos, a operação de API PutVectors exibirá o erro 400 Bad Request. Para ter mais informações sobre o limite de tamanho de metadados filtráveis por vetor, consulte Limitações e restrições.

As operações a seguir podem ser usadas com metadados filtráveis.

Operador	Tipos de entrada válidos	Descrição
$eq	String, número, booliano	Comparação de correspondência exata para valores únicos. Ao realizar a comparação com um valor de metadados da matriz, retorna verdadeiro se o valor de entrada corresponder a qualquer elemento na matriz. Por exemplo, {"category": {"$eq": "documentary"}} corresponderia a um vetor com metadados "category": ["documentary", "romance"].
$ne	String, número, booliano	Comparação não igual a
$gt	telefone	Maior que a comparação
$gte	telefone	Comparação maior ou igual a
$lt	telefone	Menor que a comparação
$lte	telefone	Comparação menor ou igual a
$in	Matriz não vazia de primitivos	Tenta encontrar correspondência com qualquer valor na matriz
$nin	Matriz não vazia de primitivos	Não encontra correspondência com nenhum dos valores na matriz
$exists	Booleano	Verifique se o campo existe
$and	Matriz não vazia de filtros	AND lógico de várias condições
$or	Matriz não vazia de filtros	OR lógico de várias condições

Exemplos de metadados filtráveis válidos

Igualdade simples

{"genre": "documentary"}

Esse filtro tenta encontrar correspondências com vetores em que a chave de metadados do gênero é igual a “documentário”. Quando você não especifica um operador, o S3 Vectors usa automaticamente o operador $eq.

Igualdade explícita

// Example: Exact match
{"genre": {"$eq": "documentary"}}

// Example: Not equal to
{"genre": {"$ne": "drama"}}

Comparação numérica

{"year": {"$gt": 2019}}

{"year": {"$gte": 2020}}

{"year": {"$lt": 2020}}

{"year": {"$lte": 2020}}

Operadores de matriz

{"genre": {"$in": ["comedy", "documentary"]}}

{"genre": {"$nin": ["comedy", "documentary"]}}

Verificação de existência

{"genre": {"$exists": true}}

O filtro $exists tenta encontrar correspondência com vetores que têm uma chave de metadados de “gênero”, independentemente do valor armazenado para essa chave de metadados.

Operadores lógicos

{"$and": [{"genre": {"$eq": "drama"}}, {"year": {"$gte": 2020}}]}

{"$or": [{"genre": {"$eq": "drama"}}, {"year": {"$gte": 2020}}]}

Faixa de preço (várias condições no mesmo campo)

{"price": {"$gte": 10, "$lte": 50}}

Para ter mais informações sobre como consultar vetores com filtragem de metadados, consulte Filtragem de metadados.

Metadados não filtráveis

Os metadados não filtráveis não podem ser usados em filtros de consulta, mas podem armazenar quantidades maiores de dados contextuais do que os metadados filtráveis. Eles são ideais para armazenar grandes fragmentos de texto, descrições detalhadas ou outras informações contextuais que não precisam ser pesquisáveis, mas podem ser exibidas com os resultados da consulta. Por exemplo, você pode armazenar o texto completo de um documento, descrições de imagens ou especificações detalhadas de um produto como metadados não filtráveis.

As chaves de metadados não filtráveis devem ser configuradas explicitamente durante a criação do índice de vetores. Depois que uma chave de metadados é designada como não filtrável durante a criação do índice, posteriormente ela não pode ser alterada para filtrável. Você pode configurar várias chaves de metadados como não filtráveis por índice de vetores, e cada nome de chave de metadados deve ter no máximo 63 caracteres. Para ter mais informações sobre o número máximo de chaves de metadados não filtráveis permitidas por índice de vetores, consulte Limitações e restrições.

Embora não seja possível filtrar metadados não filtráveis, você pode recuperá-los com os resultados da consulta usando o parâmetro return-metadata. Você pode usar metadados não filtráveis para alguns casos de uso da seguinte maneira:

• Use-os para fornecer contexto para sua aplicação sem analisar fontes de dados separadas.

• Armazene fragmentos de texto maiores que podem exceder os limites de tamanho de metadados filtráveis.

• Inclua-os nas exportações de vetores usando a operação de API ListVectors.

Para ter mais informações sobre como configurar metadados não filtráveis, consulte Criar um índice de vetores em um bucket de vetores.