JSONインデクシング
JSONフィールドは、Zilliz Cloudで構造化メタデータを柔軟に保存する方法を提供します。インデクシングがないと、JSONフィールドのクエリにはコレクション全体をスキャンする必要があり、データセットが大きくなると遅くなります。JSONインデクシングは、JSONデータ内にインデックスを作成することで高速ルックアップを可能にします。
JSONインデクシングは以下に最適です：
-
一貫した既知のキーを持つ構造化スキーマ
-
特定のJSONパスでの等価性および範囲クエリ
-
どのキーにインデックスを付けるかを正確に制御する必要があるシナリオ
-
ターゲットクエリのストレージ効率の良い高速化
多様なクエリパターンを持つ複雑なJSONドキュメントの場合、代替としてJSONシャレディングを検討してください。
JSONインデクシング構文
JSONインデックスを作成する際には、以下を指定します。
-
JSONパス：インデックスを作成するデータの正確な位置
-
データキャスト型：インデックスされた値を解釈および保存する方法
-
オプションの型変換：必要に応じてインデックス作成時にデータを変換
JSONフィールドにインデックスを作成する構文は以下の通りです。
# インデックスパラメータを準備
index_params = MilvusClient.prepare_index_params()
index_params.add_index(
field_name="<json_field_name>", # JSONフィールドの名前
index_type="AUTOINDEX", # AUTOINDEXでなければならない
index_name="<unique_index_name>", # インデックス名
params={
"json_path": "<path_to_json_key>", # JSONデータ内でインデックスされる特定のキー
"json_cast_type": "<data_type>", # 値を解釈およびインデックスする際に使用するデータ型
# "json_cast_function": "<cast_function>" # オプション：インデックス作成時にキー値をターゲット型に変換
}
)
パラメータ | 説明 | 値/例 |
|---|---|---|
| コレクションスキーマ内のJSONフィールドの名前。 |
|
| JSONインデクシングでは |
|
| このインデックスのユニーク識別子。 |
|
| JSONオブジェクト内でインデックスするキーへのパス。 |
|
| 値を解釈およびインデックスする際に使用するデータ型。キーの実際のデータ型と一致しなければならない。 利用可能なキャスト型のリストについては、以下でサポートされるキャスト型を参照。 |
|
| （オプション）インデックス作成時に元のキー値をターゲット型に変換。この構成は、キー値が誤った形式で保存されており、インデックス作成中にデータ型を変換したい場合にのみ必要。 利用可能なキャスト関数のリストについては、以下のサポートされるキャスト関数を参照。 |
|
サポートされるキャスト型
Zilliz Cloudは、インデックス作成時にキャストするための以下のデータ型をサポートしています。これらの型により、データが効率的なフィルタリングのために正しく解釈されます。
キャスト型 | 説明 | JSON値の例 |
|---|---|---|
| ブール値をインデックス化するために使用され、true/false条件でのフィルタリングクエリを可能にします。 |
|
| 整数および浮動小数点数を含む数値に使用されます。範囲や等価性（例： |
|
| 文字列値をインデックス化するために使用され、名前、カテゴリ、IDなどのテキストベースのデータに一般的です。 |
|
| ブール値の配列をインデックス化するために使用されます。 |
|
| 数値の配列をインデックス化するために使用されます。 |
|
| 文字列の配列をインデックス化するために使用され、タグやキーワードのリストに理想的です。 |
|
| 自動型推論とフラット化による完全なJSONオブジェクトまたはサブオブジェクト。 完全なJSONオブジェクトにインデックスを付けるとインデックスサイズが増加します。多くのキーがあるシナリオではJSONシャレディングを検討してください。 | 任意のJSONオブジェクト |
最適なインデクシングのために配列には同じ型の要素を含めるべきです。詳細は配列フィールドを参照してください。
サポートされるキャスト関数
JSONフィールドキーに誤った形式の値（例：文字列として保存された数値）が含まれている場合、json_cast_function引数にキャスト関数を渡してインデックス作成時にこれらの値を変換できます。
キャスト関数は大文字小文字を区別しません。以下の関数がサポートされています。
キャスト関数 | 変換元 → 変換先 | 使用例 |
|---|---|---|
| 文字列 → 数値（倍精度） |
|
変換に失敗した場合（例：数値でない文字列）、値はスキップされインデックスに含まれません。
JSONインデックスの作成
このセクションでは、実際の例を使用して異なる型のJSONデータにインデックスを作成する方法を示します。すべての例では、以下に示すサンプルJSON構造を使用し、適切に定義されたコレクションスキーマを持つMilvusClientへの接続を確立済みであると想定しています。
サンプルJSON構造
{
"metadata": {
"category": "electronics",
"brand": "BrandA",
"in_stock": true,
"price": 99.99,
"string_price": "99.99",
"tags": ["clearance", "summer_sale"],
"supplier": {
"name": "SupplierX",
"country": "USA",
"contact": {
"email": "support@supplierx.com",
"phone": "+1-800-555-0199"
}
}
}
}
基本的な設定
JSONインデックスを作成する前に、インデックスパラメータを準備してください。
# インデックスパラメータを準備
index_params = MilvusClient.prepare_index_params()
例1：単純なJSONキーにインデックスを作成
製品カテゴリによる高速フィルタリングを可能にするためにcategoryフィールドにインデックスを作成します。
index_params.add_index(
field_name="metadata",
index_type="AUTOINDEX", # JSONパスインデクシングではAUTOINDEXに設定する必要があります
index_name="category_index", # ユニークなインデックス名
params={
"json_path": 'metadata["category"]', # JSONキーへのパス
"json_cast_type": "varchar" # データキャスト型
}
)
例2：ネストされたキーにインデックスを作成
サプライヤーの連絡先検索のために深くネストされたemailフィールドにインデックスを作成します。
# ネストされたキーにインデックスを作成
index_params.add_index(
field_name="metadata",
index_type="AUTOINDEX", # JSONパスインデクシングではAUTOINDEXに設定する必要があります
index_name="email_index", # ユニークなインデックス名
params={
"json_path": 'metadata["supplier"]["contact"]["email"]', # ネストされたJSONキーへのパス
"json_cast_type": "varchar" # データキャスト型
}
)
例3：インデックス作成時にデータ型を変換
場合によっては数値データが誤って文字列として保存されることがあります。STRING_TO_DOUBLEキャスト関数を使用して変換および適切にインデックスを作成します。
# インデックス作成時に文字列数値を倍精度に変換
index_params.add_index(
field_name="metadata",
index_type="AUTOINDEX", # JSONパスインデクシングではAUTOINDEXに設定する必要があります
index_name="string_to_double_index", # ユニークなインデックス名
params={
"json_path": 'metadata["string_price"]', # インデックスされるJSONキーへのパス
"json_cast_type": "double", # データキャスト型
"json_cast_function": "STRING_TO_DOUBLE" # キャスト関数；大文字小文字を区別しない
}
)
重要：変換がいずれかのドキュメントで失敗した場合（例："invalid"のような数値でない文字列）、そのドキュメントの値はインデックスから除外され、フィルター結果には表示されません。
例4：完全なオブジェクトにインデックスを作成
その中の任意のフィールドに対するクエリを可能にするために完全なJSONオブジェクトにインデックスを作成します。json_cast_type="JSON"を使用すると、システムは自動的に：
-
JSON構造をフラット化：ネストされたオブジェクトは効率的なインデクシングのためにフラットなパスに変換されます
-
データ型を推測：各値はその内容に基づいて数値、文字列、ブール値、または日付として自動的に分類されます
-
包括的なカバレッジを作成：オブジェクト内のすべてのキーおよびネストされたパスが検索可能になります
上記のサンプルJSON構造について、完全なmetadataオブジェクトにインデックスを作成します。
# 完全なJSONオブジェクトにインデックスを作成
index_params.add_index(
field_name="metadata",
index_type="AUTOINDEX",
index_name="metadata_full_index",
params={
"json_path": "metadata",
"json_cast_type": "JSON"
}
)
JSON構造の一部にのみインデックスを作成することもできます。例：すべてのsupplier情報。
# サブオブジェクトにインデックスを作成
index_params.add_index(
field_name="metadata",
index_type="AUTOINDEX",
index_name="supplier_index",
params={
"json_path": 'metadata["supplier"]',
"json_cast_type": "JSON"
}
)
インデックス構成の適用
すべてのインデックスパラメータを定義したら、コレクションに適用します。
# すべてのインデックス構成をコレクションに適用
MilvusClient.create_index(
collection_name="your_collection_name",
index_params=index_params
)
インデクシングが完了すると、JSONフィールドクエリはこれらのインデックスを自動的に使用してパフォーマンスが高速化されます。
よくある質問
クエリのフィルター式がインデックスされたキャスト型とは異なる型を使用している場合、どうなりますか？
フィルター式がインデックスのjson_cast_typeとは異なる型を使用している場合、Zilliz Cloudはインデックスを使用せず、データが許可する場合に遅いブルートフォーススキャンに移行する可能性があります。最適なパフォーマンスのために、フィルター式は常にインデックスのキャスト型と一致させてください。たとえば、json_cast_type="double"で数値インデックスが作成された場合、数値フィルター条件のみがインデックスを活用します。
JSONインデックスを作成する際、JSONキーが異なるエンティティ間でデータ型が一貫していない場合、どうなりますか？
型の一貫性がない場合、部分的なインデクシングが発生する可能性があります。たとえば、metadata["price"]フィールドが数値（99.99）および文字列（"99.99"）の両方として保存され、json_cast_type="double"でインデックスが作成された場合、数値のみがインデックスに含まれます。文字列形式のエントリはスキップされ、フィルター結果には表示されません。
同じJSONキーに複数のインデックスを作成できますか？
いいえ、各JSONキーは1つのインデックスのみをサポートします。データに一致する単一のjson_cast_typeを選択する必要があります。ただし、完全なJSONオブジェクトとそのオブジェクト内のネストされたキーにそれぞれインデックスを作成することはできます。