Guide de filtrage de la recherche IA

Les expressions de filtre de recherche IA affinent les résultats de la query par valeur de colonne. La syntaxe diffère selon le type d'endpoint : les endpoints standard utilisent un dictionnaire Python, et les endpoints optimisés pour le stockage utilisent une chaîne de filtre de type SQL.

• **Endpoint standard** utilisent un dictionnaire Python, où la clé encode à la fois le nom de la colonne et l'opérateur (par{"price <": 200} exemple,).
• Les endpoints optimisés pour le stockage utilisent une chaîne de filtre de type SQL similaire à une clause WHERE (par exemple, "price < 200").

Pour une référence complète des opérateurs pris en charge et où trouver des filtres dans l'API de query, consultez Utiliser des filtres sur les queries. Pour des Notebooks d'exemple, voir Notebooks d'exemple.

Endpoints standards

Les endpoints standards acceptent un dictionnaire Python transmis à similarity_search() via le parameter filters. La clé encode à la fois le nom de la colonne et l'opérateur (par exemple, {"price >": 40000}), et plusieurs clés dans le même dictionnaire sont combinées avec la logique AND. Cette section résume les opérateurs pris en charge et les limitations connues.

Référence rapide

Colonnes de chaînes

Opérateur	Syntaxe	Exemple
Correspondance exacte	{"col": "val"}	{"make": "Toyota"}
Négation	{"col NOT": "val"}	{"make NOT": "Ford"}
OU (plusieurs valeurs)	{"col": ["v1","v2"]}	{"make": ["Toyota","Honda"]}
Basé sur les jetons LIKE	{"col LIKE": "token"}	{"color LIKE": "red"}
Valeurs avec trait d'union	{"col": "F-150"}	{"model": "F-150"}
Modèle JSON LIKE	[{"col LIKE": "%pattern%"}, {"col2 op": n}]	[{"specs LIKE": '%"drivetrain":"AWD"%'}, {"price <": 50000}]

Opérateur	Syntaxe	Exemple
Correspondance exacte	{"col": "val"}	{"make": "Toyota"}
Négation	{"col NOT": "val"}	{"make NOT": "Ford"}
OU (plusieurs valeurs)	{"col": ["v1","v2"]}	{"make": ["Toyota","Honda"]}
Basé sur les jetons LIKE	{"col LIKE": "token"}	{"color LIKE": "red"}
Valeurs avec trait d'union	{"col": "F-150"}	{"model": "F-150"}
Modèle JSON LIKE	[{"col LIKE": "%pattern%"}, {"col2 op": n}]	[{"specs LIKE": '%"drivetrain":"AWD"%'}, {"price <": 50000}]

Colonnes numériques (INT, DOUBLE)

Opérateur	Syntaxe	Exemple
Supérieur à	{"col >": n}	{"price >": 40000}
Inférieur ou égal à	{"col <=": n}	{"price <=": 55000}
Supérieur ou égal à	{"col >=": n}	{"rating >=": 4.5}
Correspondance d'entiers.	{"col": n}	{"year": 2024}
Plage	Deux clés dans le dictionnaire.	{"price >=": 30000, "price <=": 55000}

Opérateur	Syntaxe	Exemple
Supérieur à	{"col >": n}	{"price >": 40000}
Inférieur ou égal à	{"col <=": n}	{"price <=": 55000}
Supérieur ou égal à	{"col >=": n}	{"rating >=": 4.5}
Correspondance d'entiers.	{"col": n}	{"year": 2024}
Plage	Deux clés dans le dictionnaire.	{"price >=": 30000, "price <=": 55000}

Colonnes booléennes

Opérateur	Syntaxe	Exemple
Correspondre à vrai	{"col": true}	{"in_stock": true}
Faux	{"col": false}	{"in_stock": false}

Opérateur	Syntaxe	Exemple
Correspondre à vrai	{"col": true}	{"in_stock": true}
Faux	{"col": false}	{"in_stock": false}

Colonnes de tableaux

Les Endpoint standard prennent en charge les types primitifs ARRAY : ARRAY<STRING>, ARRAY<INT>, ARRAY<BIGINT>, ARRAY<SMALLINT>, ARRAY<TINYINT>, ARRAY<FLOAT>, ARRAY<DOUBLE>, ARRAY<BOOLEAN>, ARRAY<DATE> et ARRAY<TIMESTAMP>. ARRAY<STRUCT> n'est pas pris en charge.

Opérateur	Syntaxe	Exemple
Contient une valeur	{"col": "val"}	{"body_type": "sedan"}
Contient toute valeur (OU)	{"col": ["v1","v2"]}	{"body_type": ["hybrid","electric"]}
ET avec une autre colonne	{"col": ["v1","v2"], "col2": "val"}	{"body_type": ["hybrid", "electric"], "make": "BMW"}

Opérateur	Syntaxe	Exemple
Contient une valeur	{"col": "val"}	{"body_type": "sedan"}
Contient toute valeur (OU)	{"col": ["v1","v2"]}	{"body_type": ["hybrid","electric"]}
ET avec une autre colonne	{"col": ["v1","v2"], "col2": "val"}	{"body_type": ["hybrid", "electric"], "make": "BMW"}

Colonnes Timestamp (natives TIMESTAMP ou DATE)

Opérateur	Syntaxe	Exemple
Après	{"col >": "ISO8601Z"}	{"listed_at >": "2024-01-01T00:00:00Z"}
Correspondance exacte du timestamp	{"col": "ISO8601Z"}	{"listed_at": "2024-01-10T09:15:00Z"}
Négation	{"col NOT": "ISO8601Z"}	{"listed_at NOT": "2024-01-10T09:15:00Z"}
Plage	Deux clés dans le dictionnaire.	{"listed_at >=": "2024-01-01T00:00:00Z", "listed_at <": "2024-04-01T00:00:00Z"}

Opérateur	Syntaxe	Exemple
Après	{"col >": "ISO8601Z"}	{"listed_at >": "2024-01-01T00:00:00Z"}
Correspondance exacte du timestamp	{"col": "ISO8601Z"}	{"listed_at": "2024-01-10T09:15:00Z"}
Négation	{"col NOT": "ISO8601Z"}	{"listed_at NOT": "2024-01-10T09:15:00Z"}
Plage	Deux clés dans le dictionnaire.	{"listed_at >=": "2024-01-01T00:00:00Z", "listed_at <": "2024-04-01T00:00:00Z"}

Filtres combinés

Plusieurs clés dans un seul dictionnaire sont combinées avec la logique AND. Utilisez la syntaxe {"col1 OR col2 op": [v1, v2]} pour OR à travers différents champs.

Modèle	Syntaxe	Exemple
Chaîne + numérique	Plusieurs clés	{"make": "BMW", "price >": 60000}
Numérique + numérique	Plusieurs clés	{"price >": 50000, "rating >=": 4.7}
Chaîne + numérique + tableau	Plusieurs clés	{"make": ["Tesla", "Toyota"], "price <=": 55000, "body_type": "electric"}
Chaîne + tableau + numérique	Plusieurs clés	{"body_type": ["hybrid", "electric"], "price <": 70000, "year": 2024}
Chaîne + numérique + Timestamp	Plusieurs clés	{"make": "Toyota", "price <=": 40000, "listed_at >=": "2024-01-01T00:00:00Z"}
OR à travers les champs	Clé combinée	{"make OR price <=": ["Tesla", 30000]}
JSON LIKE + numérique	Liste de dictionnaires	[{"specs LIKE": '%"drivetrain":"AWD"%'}, {"price <": 50000}]
AND sur le même champ	Liste de dictionnaires	[{"make_model_year LIKE": "%Tesla%"}, {"make_model_year LIKE": "%2024%"}]

Modèle	Syntaxe	Exemple
Chaîne + numérique	Plusieurs clés	{"make": "BMW", "price >": 60000}
Numérique + numérique	Plusieurs clés	{"price >": 50000, "rating >=": 4.7}
Chaîne + numérique + tableau	Plusieurs clés	{"make": ["Tesla", "Toyota"], "price <=": 55000, "body_type": "electric"}
Chaîne + tableau + numérique	Plusieurs clés	{"body_type": ["hybrid", "electric"], "price <": 70000, "year": 2024}
Chaîne + numérique + Timestamp	Plusieurs clés	{"make": "Toyota", "price <=": 40000, "listed_at >=": "2024-01-01T00:00:00Z"}
OR à travers les champs	Clé combinée	{"make OR price <=": ["Tesla", 30000]}
JSON LIKE + numérique	Liste de dictionnaires	[{"specs LIKE": '%"drivetrain":"AWD"%'}, {"price <": 50000}]
AND sur le même champ	Liste de dictionnaires	[{"make_model_year LIKE": "%Tesla%"}, {"make_model_year LIKE": "%2024%"}]

Limitations

Limitation	Détail	Solution de contournement
ARRAY<struct> non pris en charge	La création d’un index avec ARRAY<struct> colonnes déclenche BadRequest: Invalid column type in schema. Les types de champs pris en charge incluent 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 et array<int>.	Aplatir la structure en une colonne de chaîne pour l'indexation et le filtrage.
LIKE est basé sur des jetons uniquement	Correspond à des jetons entiers séparés par des espaces, et non à des modèles de caractères génériques SQL (%, _).	Utilisez un endpoint optimisé pour le stockage pour les caractères génériques LIKE.
STRING Colonnes de date non prises en charge	L'utilisation de >, <, >= ou <= sur STRING colonnes génère BadRequest: Please use a numeric value.	Utilisez une colonne native TIMESTAMP avec des valeurs ISO 8601, ou stockez les dates en tant que millisecondes epoch.
BETWEEN non pris en charge	Il n'y a pas d'opérateur BETWEEN.	Utilisez deux clés dans le dict, par exemple {"price >=": 30000, "price <=": 55000}.
Aucune fonction SQL dans les filtres	Les fonctions comme to_timestamp() ne sont pas prises en charge dans les filtres de dictionnaire.	Utilisez un Endpoint optimisé pour le stockage avec une chaîne de filtre SQL. Pour les Timestamp, stocker en millisecondes d'époque.
Le filtrage numérique JSON n'est pas pris en charge.	Les endpoints standard ne peuvent pas extraire ou caster des valeurs JSON imbriquées (par exemple, specs.hp >, CAST() ou get_json_object()).	Utilisez des modèles LIKE sur la chaîne JSON, ou pré-extrayez la valeur comme colonne INT de niveau supérieur.
Les clés de dictionnaire en double sont supprimées silencieusement	Python ne conserve que la dernière valeur pour les clés en double dans un dict. Par exemple, {"make_model_year LIKE": "%Tesla%", "make_model_year LIKE": "%2024%"} n'applique que le deuxième filtre.	Utilisez une liste de dictionnaires : [{"make_model_year LIKE": "%Tesla%"}, {"make_model_year LIKE": "%2024%"}].

Limitation	Détail	Solution de contournement
ARRAY<struct> non pris en charge	La création d’un index avec ARRAY<struct> colonnes déclenche BadRequest: Invalid column type in schema. Les types de champs pris en charge incluent 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 et array<int>.	Aplatir la structure en une colonne de chaîne pour l'indexation et le filtrage.
LIKE est basé sur des jetons uniquement	Correspond à des jetons entiers séparés par des espaces, et non à des modèles de caractères génériques SQL (%, _).	Utilisez un endpoint optimisé pour le stockage pour les caractères génériques LIKE.
STRING Colonnes de date non prises en charge	L'utilisation de >, <, >= ou <= sur STRING colonnes génère BadRequest: Please use a numeric value.	Utilisez une colonne native TIMESTAMP avec des valeurs ISO 8601, ou stockez les dates en tant que millisecondes epoch.
BETWEEN non pris en charge	Il n'y a pas d'opérateur BETWEEN.	Utilisez deux clés dans le dict, par exemple {"price >=": 30000, "price <=": 55000}.
Aucune fonction SQL dans les filtres	Les fonctions comme to_timestamp() ne sont pas prises en charge dans les filtres de dictionnaire.	Utilisez un Endpoint optimisé pour le stockage avec une chaîne de filtre SQL. Pour les Timestamp, stocker en millisecondes d'époque.
Le filtrage numérique JSON n'est pas pris en charge.	Les endpoints standard ne peuvent pas extraire ou caster des valeurs JSON imbriquées (par exemple, specs.hp >, CAST() ou get_json_object()).	Utilisez des modèles LIKE sur la chaîne JSON, ou pré-extrayez la valeur comme colonne INT de niveau supérieur.
Les clés de dictionnaire en double sont supprimées silencieusement	Python ne conserve que la dernière valeur pour les clés en double dans un dict. Par exemple, {"make_model_year LIKE": "%Tesla%", "make_model_year LIKE": "%2024%"} n'applique que le deuxième filtre.	Utilisez une liste de dictionnaires : [{"make_model_year LIKE": "%Tesla%"}, {"make_model_year LIKE": "%2024%"}].

Endpoints optimisés pour le stockage

Les Endpoint optimisés pour le stockage acceptent une chaîne de filtre de type SQL transmise à similarity_search() via le parameter filters. Cette section résume les opérateurs pris en charge et les limitations connues.

Référence rapide

Colonnes de chaînes

Opérateur	Syntaxe	Exemple
Correspondance exacte	col = 'val'	make = 'Toyota'
Négation	col != 'val'	make != 'Ford'
OU (plusieurs valeurs)	col IN ('v1','v2')	make IN ('Toyota','Honda')
Modèle générique	col LIKE 'pat%'	color LIKE 'bl%'
Valeurs avec trait d'union	col = 'val-ue'	model = 'F-150'
Correspondance de sous-chaîne JSON	col LIKE '%"k":v%'	specs LIKE '%"hp":4%'

Opérateur	Syntaxe	Exemple
Correspondance exacte	col = 'val'	make = 'Toyota'
Négation	col != 'val'	make != 'Ford'
OU (plusieurs valeurs)	col IN ('v1','v2')	make IN ('Toyota','Honda')
Modèle générique	col LIKE 'pat%'	color LIKE 'bl%'
Valeurs avec trait d'union	col = 'val-ue'	model = 'F-150'
Correspondance de sous-chaîne JSON	col LIKE '%"k":v%'	specs LIKE '%"hp":4%'

Colonnes numériques (INT, DOUBLE)

Opérateur	Syntaxe	Exemple
Supérieur à	col > n	price > 40000
Inférieur ou égal à	col <= n	price <= 25000
Supérieur ou égal à	col >= n	rating >= 4.7
Correspondance d'entiers.	col = n	year = 2024
Plage	col >= a AND col <= b	price >= 30000 AND price <= 55000

Opérateur	Syntaxe	Exemple
Supérieur à	col > n	price > 40000
Inférieur ou égal à	col <= n	price <= 25000
Supérieur ou égal à	col >= n	rating >= 4.7
Correspondance d'entiers.	col = n	year = 2024
Plage	col >= a AND col <= b	price >= 30000 AND price <= 55000

Colonnes booléennes

Opérateur	Syntaxe	Exemple
Booléen vrai	col IS TRUE	in_stock IS TRUE

Opérateur	Syntaxe	Exemple
Booléen vrai	col IS TRUE	in_stock IS TRUE

Colonnes de tableaux

Le filtrage de tableau n’est pas pris en charge sur les Endpoint optimisés pour le stockage. ARRAY_CONTAINS soulève un BadRequest: Syntax error. Comme solution de contournement, concaténez les valeurs du tableau dans une colonne de type chaîne et utilisez LIKE. Par exemple :

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

Colonnes de timestamp (natives TIMESTAMP)

Opérateur	Syntaxe	Exemple
Après la date	col > TO_TIMESTAMP('ISO8601')	listed_at > TO_TIMESTAMP('2024-03-01T00:00:00')
Plage	Combiner avec AND	listed_at >= TO_TIMESTAMP('2024-01-01T00:00:00') AND listed_at < TO_TIMESTAMP('2024-04-01T00:00:00')

Opérateur	Syntaxe	Exemple
Après la date	col > TO_TIMESTAMP('ISO8601')	listed_at > TO_TIMESTAMP('2024-03-01T00:00:00')
Plage	Combiner avec AND	listed_at >= TO_TIMESTAMP('2024-01-01T00:00:00') AND listed_at < TO_TIMESTAMP('2024-04-01T00:00:00')

Filtres combinés

Modèle	Syntaxe	Exemple
Chaîne + numérique	A AND B	make = 'BMW' AND price > 60000
Numérique + numérique	A AND B	price > 50000 AND rating >= 4.7
Chaîne + numérique + IN	A AND B AND C	make IN ('Tesla', 'Toyota') AND price <= 55000 AND year >= 2022
OR à travers les champs	A OR (B AND C)	make = 'Tesla' OR (make = 'BMW' AND price > 60000)
Timestamp + numérique + chaîne	A AND B AND C	listed_at >= TO_TIMESTAMP('2024-01-01T00:00:00') AND price < 40000 AND make = 'Toyota'

Modèle	Syntaxe	Exemple
Chaîne + numérique	A AND B	make = 'BMW' AND price > 60000
Numérique + numérique	A AND B	price > 50000 AND rating >= 4.7
Chaîne + numérique + IN	A AND B AND C	make IN ('Tesla', 'Toyota') AND price <= 55000 AND year >= 2022
OR à travers les champs	A OR (B AND C)	make = 'Tesla' OR (make = 'BMW' AND price > 60000)
Timestamp + numérique + chaîne	A AND B AND C	listed_at >= TO_TIMESTAMP('2024-01-01T00:00:00') AND price < 40000 AND make = 'Toyota'

Limitations

Limitation	Détail	Solution de contournement
ARRAY<struct> non pris en charge	La création d’un index avec ARRAY<struct> colonnes déclenche BadRequest: Invalid column type in schema. Les types de champs pris en charge incluent 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 et array<int>.	Aplatir la structure en une colonne de chaîne pour l'indexation et le filtrage.
ARRAY_CONTAINS non pris en charge	ARRAY_CONTAINS(col, 'val') s'élève à BadRequest: Syntax error. Le filtrage des tableaux n'est pas pris en charge dans les chaînes de filtre optimisées pour le stockage.	Concaténez les valeurs du tableau dans une colonne de chaîne et utilisez LIKE.
BETWEEN non pris en charge	L'utilisation de BETWEEN provoque BadRequest: no viable alternative at input 'priceBETWEEN'.	Utilisez price >= a AND price <= b.
Les chaînes de caractères de Timestamp brutes provoquent une incompatibilité de type	listed_at > '2024-03-01T00:00:00' lève BadRequest: Cannot compare timestamp[us] with STRING_LITERAL.	Entourez la valeur avec TO_TIMESTAMP(), par exemple listed_at > TO_TIMESTAMP('2024-03-01T00:00:00'). La colonne doit être un type natif TIMESTAMP.
Le filtrage numérique JSON n'est pas pris en charge.	Les fonctions SQL comme CAST(get_json_object(specs, '$.hp') AS INT) > 300 déclenchent BadRequest: Syntax error. Les filtres basés sur des expressions ne sont pas pris en charge dans les chaînes de filtre optimisées pour le stockage.	Pré-extrayez les champs JSON dans les colonnes de niveau supérieur au moment de la création de l'index, ou utilisez la correspondance de modèles LIKE (par exemple, specs LIKE '%"hp":4%' OR specs LIKE '%"hp":5%' pour approximer les valeurs HP de 400 à 599).
Post-filtrage (sur-récupération)	Les résultats sont classés par pertinence d'abord, puis filtrés. La plupart des cas sont gérés automatiquement, mais dans de rares scénarios (principalement LIKE '%...%' filtres sur plus de 40 index avec un faible num_results), les documents correspondants avec de faibles scores de pertinence pourraient ne pas apparaître même s'ils satisfont le filtre.	Augmentez num_results pour élargir le pool de candidats.

Limitation	Détail	Solution de contournement
ARRAY<struct> non pris en charge	La création d’un index avec ARRAY<struct> colonnes déclenche BadRequest: Invalid column type in schema. Les types de champs pris en charge incluent 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 et array<int>.	Aplatir la structure en une colonne de chaîne pour l'indexation et le filtrage.
ARRAY_CONTAINS non pris en charge	ARRAY_CONTAINS(col, 'val') s'élève à BadRequest: Syntax error. Le filtrage des tableaux n'est pas pris en charge dans les chaînes de filtre optimisées pour le stockage.	Concaténez les valeurs du tableau dans une colonne de chaîne et utilisez LIKE.
BETWEEN non pris en charge	L'utilisation de BETWEEN provoque BadRequest: no viable alternative at input 'priceBETWEEN'.	Utilisez price >= a AND price <= b.
Les chaînes de caractères de Timestamp brutes provoquent une incompatibilité de type	listed_at > '2024-03-01T00:00:00' lève BadRequest: Cannot compare timestamp[us] with STRING_LITERAL.	Entourez la valeur avec TO_TIMESTAMP(), par exemple listed_at > TO_TIMESTAMP('2024-03-01T00:00:00'). La colonne doit être un type natif TIMESTAMP.
Le filtrage numérique JSON n'est pas pris en charge.	Les fonctions SQL comme CAST(get_json_object(specs, '$.hp') AS INT) > 300 déclenchent BadRequest: Syntax error. Les filtres basés sur des expressions ne sont pas pris en charge dans les chaînes de filtre optimisées pour le stockage.	Pré-extrayez les champs JSON dans les colonnes de niveau supérieur au moment de la création de l'index, ou utilisez la correspondance de modèles LIKE (par exemple, specs LIKE '%"hp":4%' OR specs LIKE '%"hp":5%' pour approximer les valeurs HP de 400 à 599).
Post-filtrage (sur-récupération)	Les résultats sont classés par pertinence d'abord, puis filtrés. La plupart des cas sont gérés automatiquement, mais dans de rares scénarios (principalement LIKE '%...%' filtres sur plus de 40 index avec un faible num_results), les documents correspondants avec de faibles scores de pertinence pourraient ne pas apparaître même s'ils satisfont le filtre.	Augmentez num_results pour élargir le pool de candidats.

Exemples de Notebooks

Notebook de configuration et de filtrage d'endpoint standard

Ouvrir le notebook dans un nouvel ongletOuvrir dans Databricks

Notebook de configuration et de filtrage d'Endpoint optimisé pour le stockage

Ouvrir le notebook dans un nouvel ongletOuvrir dans Databricks