Guia de filtragem de Pesquisa de IA

Esta página descreve a sintaxe da expressão de filtro para queries da Pesquisa de AI. A sintaxe do filtro é diferente para endpoints padrão e otimizados para armazenamento.

• Endpoints padrão usam um dicionário Python, em que a chave codifica o nome da coluna e o operador (por exemplo, {"price <": 200}).
• Endpoints otimizados para armazenamento usam uma string de filtro semelhante a uma WHERE cláusula (por"price < 200" exemplo,).

Para uma referência completa de operadores compatíveis e onde encontrar filtros na API de consulta, consulte Usar filtros em consultas. Para Notebooks de exemplo, consulte Notebooks de exemplo.

Endpoints padrão

Endpoints padrão aceitam um dicionário Python passado para similarity_search() por meio do parâmetro filters. A chave codifica tanto o nome da coluna quanto o operador (por exemplo, {"price >": 40000}), e várias chaves no mesmo dicionário são combinadas com a lógica AND. Esta seção resume os operadores compatíveis e as limitações conhecidas.

Referência rápida

Colunas de strings

Operador	Sintaxe	Exemplo
Correspondência exata	{"col": "val"}	{"make": "Toyota"}
Negação	{"col NOT": "val"}	{"make NOT": "Ford"}
OU (vários valores)	{"col": ["v1","v2"]}	{"make": ["Toyota","Honda"]}
Baseado em token LIKE	{"col LIKE": "token"}	{"color LIKE": "red"}
Valores hifenizados	{"col": "F-150"}	{"model": "F-150"}
Padrão JSON LIKE	[{"col LIKE": "%pattern%"}, {"col2 op": n}]	[{"specs LIKE": '%"drivetrain":"AWD"%'}, {"price <": 50000}]

Colunas numéricas (INT, DOUBLE)

Operador	Sintaxe	Exemplo
Maior que	{"col >": n}	{"price >": 40000}
Menor ou igual a	{"col <=": n}	{"price <=": 55000}
Maior ou igual a	{"col >=": n}	{"rating >=": 4.5}
Correspondência de inteiros	{"col": n}	{"year": 2024}
Intervalo	Duas chaves em um dicionário	{"price >=": 30000, "price <=": 55000}

Colunas Booleanas

Operador	Sintaxe	Exemplo
Corresponder ao verdadeiro	{"col": true}	{"in_stock": true}
Corresponder a Falso	{"col": false}	{"in_stock": false}

Colunas de matrizes

Endpoints padrão suportam tipos primitivos de ARRAY: ARRAY<STRING>, ARRAY<INT>, ARRAY<BIGINT>, ARRAY<SMALLINT>, ARRAY<TINYINT>, ARRAY<FLOAT>, ARRAY<DOUBLE>, ARRAY<BOOLEAN>, ARRAY<DATE> e ARRAY<TIMESTAMP>. ARRAY<STRUCT> não é compatível com.

Operador	Sintaxe	Exemplo
Contém um valor	{"col": "val"}	{"body_type": "sedan"}
Contém qualquer valor (OU)	{"col": ["v1","v2"]}	{"body_type": ["hybrid","electric"]}
E com outra coluna	{"col": ["v1","v2"], "col2": "val"}	{"body_type": ["hybrid", "electric"], "make": "BMW"}

Colunas de timestamp (nativas TIMESTAMP ou DATE)

Operador	Sintaxe	Exemplo
Depois	{"col >": "ISO8601Z"}	{"listed_at >": "2024-01-01T00:00:00Z"}
Correspondência exata de carimbo de data/hora	{"col": "ISO8601Z"}	{"listed_at": "2024-01-10T09:15:00Z"}
Negação	{"col NOT": "ISO8601Z"}	{"listed_at NOT": "2024-01-10T09:15:00Z"}
Intervalo	Duas chaves em um dicionário	{"listed_at >=": "2024-01-01T00:00:00Z", "listed_at <": "2024-04-01T00:00:00Z"}

Filtros combinados

Múltiplas chaves em um único dicionário são combinadas com AND lógica. Use a sintaxe {"col1 OR col2 op": [v1, v2]} para OR em diferentes campos.

Padrão	Sintaxe	Exemplo
string + numérico	Múltiplas chaves	{"make": "BMW", "price >": 60000}
Numérico + numérico	Múltiplas chaves	{"price >": 50000, "rating >=": 4.7}
String + numérico + array	Múltiplas chaves	{"make": ["Tesla", "Toyota"], "price <=": 55000, "body_type": "electric"}
String + array + numérico	Múltiplas chaves	{"body_type": ["hybrid", "electric"], "price <": 70000, "year": 2024}
strings, numérico e marca de tempo	Múltiplas chaves	{"make": "Toyota", "price <=": 40000, "listed_at >=": "2024-01-01T00:00:00Z"}
OR em todos os campos	Chave combinada	{"make OR price <=": ["Tesla", 30000]}
JSON LIKE + numérico	Lista de dicionários	[{"specs LIKE": '%"drivetrain":"AWD"%'}, {"price <": 50000}]
AND no mesmo campo	Lista de dicionários	[{"make_model_year LIKE": "%Tesla%"}, {"make_model_year LIKE": "%2024%"}]

Limitações

Limitação	Detalhe	Solução alternativa
ARRAY<struct> Não suportado	A criação de um índice com ARRAY<struct> colunas gera BadRequest: Invalid column type in schema.. Os tipos de campo suportados incluem array<float>, array<tinyint>, array<double>, timestamp, tinyint, float, smallint, array<date>, string, array<boolean>, array<smallint>, double, boolean, date, int, array<string>, array<bigint>, array<timestamp>, bigint e array<int>.	Desachatar a estrutura em uma coluna de strings para indexação e filtragem.
LIKE é baseado em tokens apenas	Corresponde a tokens inteiros separados por espaço em branco, e não padrões curinga SQL (%, _).	Utilize um endpoint otimizado para armazenamento para caractere curinga LIKE.
STRING Colunas de data não são suportadas	Usar >, <, >= ou <= em colunas STRING gera BadRequest: Please use a numeric value.	Use uma coluna TIMESTAMP nativa com valores ISO 8601, ou armazene as datas em milissegundos epoch.
BETWEEN Não suportado	Não há BETWEEN operador.	Use duas chaves no dicionário, por exemplo {"price >=": 30000, "price <=": 55000}.
Sem funções SQL em filtros	Funções como to_timestamp() não são compatíveis em filtros de dicionário.	Use um endpoint otimizado para armazenamento com uma string de filtro SQL. Para registros de data/hora, devem ser armazenados como milissegundos desde a época.
Filtragem numérica de JSON não é compatível	Endpoints padrão não podem extrair ou converter valores JSON aninhados (por exemplo, specs.hp >, CAST() ou get_json_object()).	Usar padrões LIKE na string JSON, ou pré-extrair o valor como uma coluna de nível superior INT.
Chaves de dicionário duplicadas descartadas silenciosamente	Python mantém apenas o último valor para chaves duplicadas em um dicionário. Por exemplo, {"make_model_year LIKE": "%Tesla%", "make_model_year LIKE": "%2024%"} apenas aplica o segundo filtro.	Use uma lista de dicionários: [{"make_model_year LIKE": "%Tesla%"}, {"make_model_year LIKE": "%2024%"}].

Endpoints otimizados para armazenamento

Endpoints otimizados para armazenamento aceitam uma string de filtro semelhante a SQL passada para similarity_search() através do parâmetro filters. Esta seção resume os operadores compatíveis e as limitações conhecidas.

Referência rápida

Colunas de strings

Operador	Sintaxe	Exemplo
Correspondência exata	col = 'val'	make = 'Toyota'
Negação	col != 'val'	make != 'Ford'
OU (vários valores)	col IN ('v1','v2')	make IN ('Toyota','Honda')
Padrão de caractere universal	col LIKE 'pat%'	color LIKE 'bl%'
Valores hifenizados	col = 'val-ue'	model = 'F-150'
Correspondência de substring JSON	col LIKE '%"k":v%'	specs LIKE '%"hp":4%'

Colunas numéricas (INT, DOUBLE)

Operador	Sintaxe	Exemplo
Maior que	col > n	price > 40000
Menor ou igual a	col <= n	price <= 25000
Maior ou igual a	col >= n	rating >= 4.7
Correspondência de inteiros	col = n	year = 2024
Intervalo	col >= a AND col <= b	price >= 30000 AND price <= 55000

Colunas Booleanas

Operador	Sintaxe	Exemplo
Boolean verdadeiro	col IS TRUE	in_stock IS TRUE

Colunas de matrizes

A filtragem de arrays não é suportada em endpoints otimizados para armazenamento. ARRAY_CONTAINS gera um BadRequest: Syntax error. Como alternativa, concatene valores de array em uma coluna de string e use LIKE. Por exemplo:

• "body_type LIKE '%sedan%'"
• "body_type LIKE '%hybrid%' OR body_type LIKE '%electric%'"

Colunas de timestamp (nativas TIMESTAMP)

Operador	Sintaxe	Exemplo
Após a data	col > TO_TIMESTAMP('ISO8601')	listed_at > TO_TIMESTAMP('2024-03-01T00:00:00')
Intervalo	Combinar com AND	listed_at >= TO_TIMESTAMP('2024-01-01T00:00:00') AND listed_at < TO_TIMESTAMP('2024-04-01T00:00:00')

Filtros combinados

Padrão	Sintaxe	Exemplo
string + numérico	A AND B	make = 'BMW' AND price > 60000
Numérico + numérico	A AND B	price > 50000 AND rating >= 4.7
String + numérico + IN	A AND B AND C	make IN ('Tesla', 'Toyota') AND price <= 55000 AND year >= 2022
OR em todos os campos	A OR (B AND C)	make = 'Tesla' OR (make = 'BMW' AND price > 60000)
Timestamp + numérico + string	A AND B AND C	listed_at >= TO_TIMESTAMP('2024-01-01T00:00:00') AND price < 40000 AND make = 'Toyota'

Limitações

Limitação	Detalhe	Solução alternativa
ARRAY<struct> Não suportado	A criação de um índice com ARRAY<struct> colunas gera BadRequest: Invalid column type in schema.. Os tipos de campo suportados incluem array<float>, array<tinyint>, array<double>, timestamp, tinyint, float, smallint, array<date>, string, array<boolean>, array<smallint>, double, boolean, date, int, array<string>, array<bigint>, array<timestamp>, bigint e array<int>.	Desachatar a estrutura em uma coluna de strings para indexação e filtragem.
ARRAY_CONTAINS Não suportado	ARRAY_CONTAINS(col, 'val') Gera BadRequest: Syntax error. A filtragem de arrays não é compatível em strings de filtro otimizadas para armazenamento.	Concatenar valores de matriz em uma coluna de strings e use LIKE.
BETWEEN Não suportado	Usando BETWEEN causa BadRequest: no viable alternative at input 'priceBETWEEN'.	Use price >= a AND price <= b.
Strings de timestamp não formatadas causam incompatibilidade de tipos.	listed_at > '2024-03-01T00:00:00' gera BadRequest: Cannot compare timestamp[us] with STRING_LITERAL.	Envolva o valor com TO_TIMESTAMP(), por exemplo, listed_at > TO_TIMESTAMP('2024-03-01T00:00:00'). A coluna deve ser do tipo nativo TIMESTAMP.
Filtragem numérica de JSON não é compatível	Funções SQL como CAST(get_json_object(specs, '$.hp') AS INT) > 300 geram BadRequest: Syntax error. Filtros baseados em expressão não são suportados em strings de filtro otimizadas para armazenamento.	Pré-extrair campos JSON em colunas de nível superior no momento da criação do índice, ou usar correspondência de padrões LIKE (por exemplo, specs LIKE '%"hp":4%' OR specs LIKE '%"hp":5%' para aproximar valores de HP de 400–599).
Pós-filtragem (overfetch)	Os resultados são classificados primeiro por relevância, depois filtrados. A maioria dos casos é tratada automaticamente, mas, em cenários raros—principalmente LIKE '%...%' filtros em mais de 40 índices com baixo num_results—documentos correspondentes com pontuações de relevância baixas podem não aparecer, mesmo que atendam ao filtro.	Aumentar num_results para ampliar o pool de candidatos.

Notebooks de exemplo

Notebook de configuração padrão de endpoint e filtragem

Abrir notebook em uma nova aba

Notebook de configuração e filtragem de endpoint otimizado para armazenamento

Abrir notebook em uma nova aba