メインコンテンツまでスキップ
バージョン: User Guides (Cloud)

JSONインデックス

JSONフィールドは、Zilliz Cloud で構造化されたメタデータを柔軟に格納する方法を提供します。インデックスを作成しない場合、JSONフィールドに対するクエリはコレクション全体のスキャンを必要とし、データセットが大きくなるにつれて遅くなります。JSONインデックスを作成することで、JSONデータ内の特定の値に対して高速な検索が可能になります。

JSONインデックスは、以下の用途に最適です：

  • 一貫性があり、キーが事前にわかっている構造化スキーマ
  • 特定のJSONパスに対する等価および範囲クエリ
  • インデックス対象のキーを正確に制御したいシナリオ
  • 対象を絞ったクエリをストレージ効率よく高速化したい場合
📘Notes

多様なクエリパターンを持つ複雑なJSONドキュメントの場合は、代わりにJSON Shreddingを検討してください。

JSONインデックス構文​

JSONインデックスを作成する際には、以下の情報を指定します：

  • JSONパス：インデックスを作成したいデータの正確な位置
  • データキャストタイプ：インデックス対象の値をどのように解釈・格納するか
  • オプションの型変換：必要に応じて、インデックス作成時にデータを変換する方法

以下は、JSONフィールドにインデックスを作成するための構文です：

# Prepare index params
index_params = MilvusClient.prepare_index_params()

index_params.add_index(
    field_name="<json_field_name>",  # Name of the JSON field
    index_type="AUTOINDEX",  # Must be AUTOINDEX
    index_name="<unique_index_name>",  # Index name
    params={
        "json_path": "<path_to_json_key>",  # Specific key to be indexed within JSON data
        "json_cast_type": "<data_type>",  # Data type to use when interpreting and indexing the value
        # "json_cast_function": "<cast_function>"  # Optional: convert key values into a target type at index time
    }
)

パラメータ

説明

値 / 例

field_name

コレクションスキーマ内のJSONフィールドの名前。

"metadata"

index_type

JSONインデックスでは必ず"AUTOINDEX"を指定する必要があります。

"AUTOINDEX"

index_name

このインデックスの一意な識別子。

"category_index"

json_path

JSONオブジェクト内でインデックスを作成したいキーへのパス。

  • トップレベルのキー: 'metadata["category"]'

  • ネストされたキー: 'metadata["supplier"]["contact"]["email"]'

  • JSONオブジェクト全体: "metadata"

  • サブオブジェクト: 'metadata["supplier"]'

json_cast_type

値を解釈およびインデックス作成する際に使用するデータ型。キーの実際のデータ型と一致している必要があります。

利用可能なキャストタイプの一覧については、サポートされているキャストタイプ を参照してください。

"VARCHAR"

json_cast_function

（任意） インデックス作成時に元のキー値をターゲット型に変換します。この設定は、キー値が誤った形式で保存されており、インデックス作成中にデータ型を変換したい場合にのみ必要です。

利用可能なキャスト関数の一覧については、サポートされているキャスト関数を参照してください。

"STRING_TO_DOUBLE"

サポートされているキャストタイプ​

Zilliz Cloudは、インデックス作成時に以下のデータ型によるキャストをサポートしています。これらの型により、データが効率的なフィルタリングのために正しく解釈されます。

キャストタイプ

説明

JSON値の例

BOOL / bool

真偽値をインデックス作成するために使用され、true/false条件に基づくクエリを可能にします。

true, false

DOUBLE / double

整数および浮動小数点数を含む数値に使用されます。>、<、==などの範囲や等価性に基づくフィルタリングを可能にします。

42, 99.99

VARCHAR / varchar

文字列値をインデックス作成するために使用され、名前、カテゴリ、IDなどのテキストベースのデータに一般的です。

"electronics", "BrandA"

ARRAY_BOOL / array_bool

真偽値の配列をインデックス作成するために使用されます。

[true, false, true]

ARRAY_DOUBLE / array_double

数値の配列をインデックス作成するために使用されます。

[1.2, 3.14, 42]

ARRAY_VARCHAR / array_varchar

文字列の配列をインデックス作成するために使用され、タグやキーワードのリストに最適です。

["tag1", "tag2", "tag3"]

JSON / json

自動型推論とフラット化による、JSONオブジェクト全体またはサブオブジェクト。

JSONオブジェクト全体をインデックス作成すると、インデックスサイズが増加します。多数のキーがあるシナリオでは、JSON Shreddingを検討してください。

任意のJSONオブジェクト

📘Notes

配列は、最適なインデックス作成のために同じ型の要素を含む必要があります。詳細については、配列 Fieldを参照してください。

サポートされているキャスト関数​

JSONフィールドキーに誤った形式の値が含まれている場合（例：数値が文字列として保存されているなど）、json_cast_function引数にキャスト関数を渡すことで、インデックス作成時にこれらの値を変換できます。

キャスト関数は大文字・小文字を区別しません。以下の関数がサポートされています：

キャスト関数

変換元 → 変換先

ユースケース

STRING_TO_DOUBLE / string_to_double

文字列 → 数値（double）

"99.99"を99.99に変換

📘Notes

変換に失敗した場合（例：非数値文字列）、その値はスキップされ、インデックス作成されません。

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インデックスを作成する前に、インデックスパラメータを準備してください。

# Prepare index params
index_params = MilvusClient.prepare_index_params()

例 1: シンプルな JSON キーのインデックス作成​

category フィールドにインデックスを作成して、商品カテゴリによる高速なフィルタリングを有効化します。

index_params.add_index(
    field_name="metadata",
    index_type="AUTOINDEX", # Must be set to AUTOINDEX for JSON path indexing
    index_name="category_index",  # Unique index name
    params={
        "json_path": 'metadata["category"]', # Path to the JSON key
        "json_cast_type": "varchar" # Data cast type
    }
)

例 2: ネストされたキーのインデックス作成​

サプライヤーの連絡先検索用に、深くネストされた email フィールドに対してインデックスを作成します。

# Index the nested key
index_params.add_index(
    field_name="metadata",
    index_type="AUTOINDEX", # Must be set to AUTOINDEX for JSON path indexing
    index_name="email_index", # Unique index name
    params={
        "json_path": 'metadata["supplier"]["contact"]["email"]', # Path to the nested JSON key
        "json_cast_type": "varchar" # Data cast type
    }
)

例 3: インデックス作成時にデータ型を変換する​

数値データが誤って文字列として保存されている場合があります。STRING_TO_DOUBLE キャスト関数を使用して、適切に変換およびインデックス作成します。

# Convert string numbers to double for indexing
index_params.add_index(
    field_name="metadata",
    index_type="AUTOINDEX", # Must be set to AUTOINDEX for JSON path indexing
    index_name="string_to_double_index", # Unique index name
    params={
        "json_path": 'metadata["string_price"]', # Path to the JSON key to be indexed
        "json_cast_type": "double", # Data cast type
        "json_cast_function": "STRING_TO_DOUBLE" # Cast function; case insensitive
    }
)

重要: いずれかのドキュメント（例: "invalid" のような数値でない文字列）の変換が失敗した場合、そのドキュメントの値はインデックスから除外され、フィルタリング結果に表示されません。

例4: オブジェクト全体をインデックスする​

完全なJSONオブジェクトをインデックスして、その内部の任意のフィールドに対してクエリを実行できるようにします。json_cast_type="JSON" を使用すると、システムは自動的に以下の処理を行います：

  • JSON構造をフラット化する: ネストされたオブジェクトは、効率的なインデックス作成のためにフラットなパスに変換されます

  • データ型を推論する: 各値は、その内容に基づいて自動的に数値、文字列、真偽値、日付のいずれかに分類されます

  • 包括的なカバレッジを作成する: オブジェクト内のすべてのキーおよびネストされたパスが検索可能になります

上記のサンプルJSON構造に対して、metadata オブジェクト全体をインデックスします：

# Index the entire JSON object
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 a sub-object
index_params.add_index(
    field_name="metadata",
    index_type="AUTOINDEX", 
    index_name="supplier_index",
    params={
        "json_path": 'metadata["supplier"]',
        "json_cast_type": "JSON"
    }
)

インデックス設定の適用​

すべてのインデックスパラメータを定義したら、それらをコレクションに適用します。

# Apply all index configurations to the collection
MilvusClient.create_index(
    collection_name="your_collection_name",
    index_params=index_params
)

インデックス作成が完了すると、JSONフィールドに対するクエリは自動的にこれらのインデックスを使用し、パフォーマンスが向上します。

FAQ​

クエリのフィルター式で、インデックスのキャスト型とは異なる型を使用した場合、どうなりますか？​

フィルター式でインデックスの 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オブジェクト全体に対してインデックスを作成しつつ、そのオブジェクト内のネストされたキーに対しても別途インデックスを作成することは可能です。