AI検索フィルタリングガイド

このページでは、AI Search クエリのフィルター式構文について説明します。標準エンドポイントとストレージ最適化エンドポイントとで、フィルター構文が異なります。

• 標準のエンドポイント はPythonディクショナリを使用し、キーは列名と演算子の両方をエンコードします（例：{"price <": 200} ）。
• ストレージに最適化されたエンドポイント は、SQLのWHERE句に似たフィルタ文字列（たとえば、"price < 200"）を使用します。

サポートされている演算子と、クエリ API でフィルターを見つける場所の完全なリファレンスについては、クエリでフィルターを使用するを参照してください。ノートブックの例については、「ノートブックの例」を参照してください。

標準エンドポイント

標準のエンドポイントは、filtersパラメーターを介してsimilarity_search()に渡されるPython辞書を受け入れます。キーは、列名と演算子の両方をエンコードします（例：{"price >": 40000}）、同じディクショナリ内の複数のキーはANDロジックと組み合わされます。このセクションでは、サポートされている演算子と既知の制限事項の概要を説明します。

クイック リファレンス

文字列列

オペレーター	構文	例
完全一致	{"col": "val"}	{"make": "Toyota"}
否定	{"col NOT": "val"}	{"make NOT": "Ford"}
または (複数の値)	{"col": ["v1","v2"]}	{"make": ["Toyota","Honda"]}
トークンベースの LIKE	{"col LIKE": "token"}	{"color LIKE": "red"}
ハイフン付きの値	{"col": "F-150"}	{"model": "F-150"}
JSONパターン LIKE	[{"col LIKE": "%pattern%"}, {"col2 op": n}]	[{"specs LIKE": '%"drivetrain":"AWD"%'}, {"price <": 50000}]

数値列（INT、DOUBLE）

オペレーター	構文	例
超	{"col >": n}	{"price >": 40000}
以下	{"col <=": n}	{"price <=": 55000}
以上	{"col >=": n}	{"rating >=": 4.5}
整数マッチ	{"col": n}	{"year": 2024}
範囲	辞書に2つのキー	{"price >=": 30000, "price <=": 55000}

ブーリアン列

オペレーター	構文	例
真に一致します。	{"col": true}	{"in_stock": true}
一致はフォールスです	{"col": false}	{"in_stock": false}

配列列

標準エンドポイントはプリミティブなARRAY型に対応しています：ARRAY<STRING>、ARRAY<INT>、ARRAY<BIGINT>、ARRAY<SMALLINT>、ARRAY<TINYINT>、ARRAY<FLOAT>、ARRAY<DOUBLE>、ARRAY<BOOLEAN>、ARRAY<DATE>、ARRAY<TIMESTAMP>。ARRAY<STRUCT> はサポートされていません。

オペレーター	構文	例
値が含まれています	{"col": "val"}	{"body_type": "sedan"}
任意の値が含まれています (OR)	{"col": ["v1","v2"]}	{"body_type": ["hybrid","electric"]}
ANDと別の列	{"col": ["v1","v2"], "col2": "val"}	{"body_type": ["hybrid", "electric"], "make": "BMW"}

タイムスタンプ列（ネイティブ TIMESTAMP または DATE）

オペレーター	構文	例
後	{"col >": "ISO8601Z"}	{"listed_at >": "2024-01-01T00:00:00Z"}
タイムスタンプの完全一致	{"col": "ISO8601Z"}	{"listed_at": "2024-01-10T09:15:00Z"}
否定	{"col NOT": "ISO8601Z"}	{"listed_at NOT": "2024-01-10T09:15:00Z"}
範囲	辞書に2つのキー	{"listed_at >=": "2024-01-01T00:00:00Z", "listed_at <": "2024-04-01T00:00:00Z"}

組み合わせフィルター

1つのdict内の複数のキーは、ANDロジックで結合されます。ORの{"col1 OR col2 op": [v1, v2]}構文を異なるフィールドで使用してください。

パターン	構文	例
文字列と数値	複数のキー	{"make": "BMW", "price >": 60000}
数値+数値	複数のキー	{"price >": 50000, "rating >=": 4.7}
文字列+数値+配列	複数のキー	{"make": ["Tesla", "Toyota"], "price <=": 55000, "body_type": "electric"}
文字列、配列、数値	複数のキー	{"body_type": ["hybrid", "electric"], "price <": 70000, "year": 2024}
文字列と数値とタイムスタンプ	複数のキー	{"make": "Toyota", "price <=": 40000, "listed_at >=": "2024-01-01T00:00:00Z"}
OR フィールドごとの	結合キー	{"make OR price <=": ["Tesla", 30000]}
JSON LIKE + 数値	ディクショナリのリスト	[{"specs LIKE": '%"drivetrain":"AWD"%'}, {"price <": 50000}]
AND 同じフィールドで	ディクショナリのリスト	[{"make_model_year LIKE": "%Tesla%"}, {"make_model_year LIKE": "%2024%"}]

制限事項：

制限事項	詳細	回避策
ARRAY<struct> サポートされていない	ARRAY<struct>列でインデックスを作成するとBadRequest: Invalid column type in schema.が発生します。サポートされているフィールドタイプは、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、およびarray<int>です。	インデックス付けとフィルタリングのために、構造体を文字列列に非平坦化します。
LIKE トークンベースのみです	空白で区切られたトークン全体に一致しますが、SQLワイルドカードパターン（%、_）には一致しません。	ワイルドカード LIKE には、ストレージ最適化エンドポイントを使用してください。
STRING 日付列はサポートされていません。	STRING列で>、<、>=、または<=を使用すると、BadRequest: Please use a numeric valueが発生します。	TIMESTAMP 列を ISO 8601 の値とともにお使いいただくか、日付をエポックミリ秒として格納してください。
BETWEEN サポートされていない	BETWEEN演算子はありません。	辞書内で2つのキーを使用してください。たとえば、{"price >=": 30000, "price <=": 55000}。
フィルター内にSQL関数はありません。	to_timestamp() のような関数は辞書フィルターではサポートされていません。	SQLフィルタ文字列を備えたストレージ最適化エンドポイントを使用してください。タイムスタンプは、エポック ミリ秒として保存してください。
JSON数値フィルタはサポートされていません	標準エンドポイントでは、ネストされたJSON値を抽出したりキャストしたりすることはできません（例：specs.hp >、CAST()、またはget_json_object()）。	JSON文字列にLIKEパターンを使用するか、値を事前に抽出し、最上位のINT列にしてください。
重複する辞書キーは警告なしに破棄されます	Pythonでは、辞書内の重複キーに対しては、最後の値のみが保持されます。たとえば、{"make_model_year LIKE": "%Tesla%", "make_model_year LIKE": "%2024%"} は2番目のフィルターのみが適用されます。	辞書のリストを使用してください: [{"make_model_year LIKE": "%Tesla%"}, {"make_model_year LIKE": "%2024%"}]。

ストレージ最適化エンドポイント

ストレージに最適化されたエンドポイントは、filtersパラメーターを介してsimilarity_search()に渡されるSQLのようなフィルタ文字列を受け入れます。このセクションでは、サポートされている演算子と既知の制限事項の概要を説明します。

クイック リファレンス

文字列列

オペレーター	構文	例
完全一致	col = 'val'	make = 'Toyota'
否定	col != 'val'	make != 'Ford'
または (複数の値)	col IN ('v1','v2')	make IN ('Toyota','Honda')
ワイルドカードパターン	col LIKE 'pat%'	color LIKE 'bl%'
ハイフン付きの値	col = 'val-ue'	model = 'F-150'
JSON 部分文字列一致	col LIKE '%"k":v%'	specs LIKE '%"hp":4%'

数値列（INT、DOUBLE）

オペレーター	構文	例
超	col > n	price > 40000
以下	col <= n	price <= 25000
以上	col >= n	rating >= 4.7
整数マッチ	col = n	year = 2024
範囲	col >= a AND col <= b	price >= 30000 AND price <= 55000

ブーリアン列

オペレーター	構文	例
ブーリアン 真	col IS TRUE	in_stock IS TRUE

配列列

配列フィルタリングは、ストレージ最適化エンドポイントではサポートされていません。ARRAY_CONTAINS が BadRequest: Syntax error を発生します。回避策として、配列の値を文字列列に連結し、LIKEを使用してください。例えば：

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

タイムスタンプ列（ネイティブ TIMESTAMP）

オペレーター	構文	例
日付以降	col > TO_TIMESTAMP('ISO8601')	listed_at > TO_TIMESTAMP('2024-03-01T00:00:00')
範囲	と結合します AND	listed_at >= TO_TIMESTAMP('2024-01-01T00:00:00') AND listed_at < TO_TIMESTAMP('2024-04-01T00:00:00')

組み合わせフィルター

パターン	構文	例
文字列と数値	A AND B	make = 'BMW' AND price > 60000
数値+数値	A AND B	price > 50000 AND rating >= 4.7
文字列+数値+ IN	A AND B AND C	make IN ('Tesla', 'Toyota') AND price <= 55000 AND year >= 2022
OR フィールドごとの	A OR (B AND C)	make = 'Tesla' OR (make = 'BMW' AND price > 60000)
タイムスタンプ + 数値 + 文字列	A AND B AND C	listed_at >= TO_TIMESTAMP('2024-01-01T00:00:00') AND price < 40000 AND make = 'Toyota'

制限事項：

制限事項	詳細	回避策
ARRAY<struct> サポートされていない	ARRAY<struct>列でインデックスを作成するとBadRequest: Invalid column type in schema.が発生します。サポートされているフィールドタイプは、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、およびarray<int>です。	インデックス付けとフィルタリングのために、構造体を文字列列に非平坦化します。
ARRAY_CONTAINS サポートされていない	ARRAY_CONTAINS(col, 'val') BadRequest: Syntax errorが発生します。配列フィルタリングはストレージ最適化されたフィルター文字列ではサポートされていません。	配列の値を文字列の列に連結し、LIKEを使用します。
BETWEEN サポートされていない	BETWEENを使用すると、BadRequest: no viable alternative at input 'priceBETWEEN'が発生します。	price >= a AND price <= bを使用してください。
生のタイムスタンプ文字列により、型が一致しません。	listed_at > '2024-03-01T00:00:00' BadRequest: Cannot compare timestamp[us] with STRING_LITERALが発生します。	値を TO_TIMESTAMP() で囲みます（例：listed_at > TO_TIMESTAMP('2024-03-01T00:00:00')）。列はネイティブなTIMESTAMPタイプである必要があります。
JSON数値フィルタはサポートされていません	CAST(get_json_object(specs, '$.hp') AS INT) > 300 SQL 関数は BadRequest: Syntax error を発生させます。ストレージ最適化されたフィルター文字列では、式ベースのフィルターはサポートされていません。	インデックス作成時にJSONフィールドを事前にトップレベルの列に抽出し、あるいは、LIKE のパターンマッチングを使用します (たとえば、400～599 のHP値に近似するために specs LIKE '%"hp":4%' OR specs LIKE '%"hp":5%' を使用します)。
後処理フィルタリング（過剰取得）	結果はまず関連性でランク付けされ、その後フィルターされます。ほとんどのケースは自動的に処理されますが、まれなシナリオ（主に、LIKE '%...%'フィルターが40を超えるインデックスに適用され、num_resultsが低い場合）では、関連度が低い一致ドキュメントは、フィルター条件を満たしていても表示されない可能性があります。	候補者プールを広げるには、num_results を増やします。

「ノートブックの例」

標準エンドポイント設定およびフィルタリング用ノートブック

ノートブックを新しいタブで開く

ストレージ最適化エンドポイントのセットアップとフィルタリングノートブック

ノートブックを新しいタブで開く