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

動的フィールド

Zilliz Cloudでは、動的フィールドと呼ばれる特別な機能を通じて、柔軟で進化する構造を持つエンティティを挿入できます。このフィールドは#metaという名前の非表示のJSONフィールドとして実装され、コレクションスキーマで明示的に定義されていないデータ内のすべてのフィールドを自動的に格納します。

動作方法​

動的フィールドが有効になっている場合、Zilliz Cloudは各エンティティに非表示の#metaフィールドを追加します。このフィールドはJSON型であり、任意のJSON互換データ構造を格納でき、JSONパス構文を使用してインデックス化できます。

データ挿入時、スキーマで宣言されていないすべてのフィールドは、自動的にこの動的フィールド内にキーと値のペアとして格納されます。

#metaを手動で管理する必要はありません。Zilliz Cloudが透過的に処理します。

たとえば、コレクションスキーマがidとvectorのみを定義しており、次のエンティティを挿入する場合を考えてみましょう。

{
  "id": 1,
  "vector": [0.1, 0.2, 0.3],
  "name": "Item A",    // スキーマにありません
  "category": "books"  // スキーマにありません
}

動的フィールド機能が有効になっている場合、Zilliz Cloudは内部的に次のように格納します。

{
  "id": 1,
  "vector": [0.1, 0.2, 0.3],
  "$meta": {
    "name": "Item A",
    "category": "books"
  }
}

これにより、スキーマを変更せずにデータ構造を進化させることができます。

一般的な使用例は次のとおりです。

  • オプションまたは頻繁には取得されないフィールドの格納

  • エンティティごとに異なるメタデータの取得

  • 特定の動的フィールドキーにインデックスを設定した柔軟なフィルタリングのサポート

サポートされているデータ型​

動的フィールドは、Zilliz Cloudが提供するすべてのスカラーデータ型をサポートしており、単純な値と複雑な値の両方を含みます。これらのデータ型は、$metaに格納されるキーの値に適用されます。

サポートされている型は次のとおりです。

  • 文字列 (VARCHAR)

  • 整数 (INT8, INT32, INT64)

  • 浮動小数点 (FLOAT, DOUBLE)

  • 真偽値 (BOOL)

  • スカラー値の配列 (ARRAY)

  • JSONオブジェクト (JSON)

例:

{
  "brand": "Acme",
  "price": 29.99,
  "in_stock": true,
  "tags": ["new", "hot"],
  "specs": {
    "weight": "1.2kg",
    "dimensions": { "width": 10, "height": 20 }
  }
}

上記のすべてのキーと値は#metaフィールド内に格納されます。

動的フィールドの有効化​

動的フィールド機能を使用するには、コレクションスキーマ作成時にenable_dynamic_field=Trueを設定します。

from pymilvus import MilvusClient, DataType

# クライアントを初期化
client = MilvusClient(uri="YOUR_CLUSTER_ENDPOINT")

# 動的フィールドを有効にしてスキーマを作成
schema = client.create_schema(
    auto_id=False,
    enable_dynamic_field=True,
)

# 明示的に定義されたフィールドを追加
schema.add_field(field_name="my_id", datatype=DataType.INT64, is_primary=True)
schema.add_field(field_name="my_vector", datatype=DataType.FLOAT_VECTOR, dim=5)

# コレクションを作成
client.create_collection(
    collection_name="my_collection",
    schema=schema
)

コレクションへのエンティティ挿入​

動的フィールドにより、スキーマで定義されていない追加フィールドを挿入できます。これらのフィールドは自動的に#metaに格納されます。

entities = [
    {
        "my_id": 1, # 明示的に定義された主フィールド
        "my_vector": [0.1, 0.2, 0.3, 0.4, 0.5], # 明示的に定義されたベクトルフィールド
        "overview": "Great product",       # スキーマで定義されていないスカラーkey
        "words": 150,                      # スキーマで定義されていないスカラーkey
        "dynamic_json": {                  # スキーマで定義されていないJSON key
            "varchar": "some text",
            "nested": {
                "value": 42.5
            },
            "string_price": "99.99"        # 文字列として格納された数値
        }
    }
]

client.insert(collection_name="my_collection", data=entities)

動的フィールドのキーにインデックスを設定​

Zilliz Cloudでは、JSONパスインデックスを使用して、動的フィールド内の特定のキーにインデックスを作成できます。スカラー値またはJSONオブジェクト内のネストされた値に使用できます。

📘ノート

動的フィールドキーのインデックス設定はオプションです。インデックスなしで動的フィールドキーによるクエリやフィルタリングは可能ですが、ブルートフォース検索になるためパフォーマンスが低下する可能性があります。

JSONパスインデックス構文​

JSONパスインデックスを作成するには、以下を指定します。

  • JSONパス (json_path): インデックスを作成するJSONオブジェクト内のキーまたはネストされたフィールドのパス。

    • 例: metadata["category"]

      これにより、インデックス作成エンジンがJSON構造内で検索する場所が定義されます。

  • JSONキャスト型 (json_cast_type): Zilliz Cloudが指定されたパスの値を解釈してインデックス化する際に使用するデータ型。

    • この型は、インデックス対象のフィールドの実際のデータ型と一致する必要があります。

    • 完全なリストについては、サポートされているJSONキャスト型を参照してください。

JSONパスを使用して動的フィールドキーにインデックスを設定​

動的フィールドはJSONフィールドであるため、JSONパス構文を使用して内部の任意のキーにインデックスを設定できます。単純なスカラー値と複雑なネスト構造の両方に使用できます。

JSONパスの例:

  • 単純なキー: overview, words

  • ネストされたキー: dynamic_json['varchar'], dynamic_json['nested']['value']

index_params = client.prepare_index_params()

# 単純な文字列キーにインデックスを設定
index_params.add_index(
    field_name="overview",  # 動的フィールド内のキー名
    index_type="AUTOINDEX", # JSONパスインデックスではAUTOINDEXに設定する必要があります
    index_name="overview_index",  # ユニークなインデックス名
    params={
        "json_cast_type": "varchar",   # Zilliz Cloudが値をインデックス化する際に使用するデータ型
        "json_path": "overview"        # キーへのJSONパス
    }
)

# 単純な数値キーにインデックスを設定
index_params.add_index(
    field_name="words",  # 動的フィールド内のキー名
    index_type="AUTOINDEX", # JSONパスインデックスではAUTOINDEXに設定する必要があります
    index_name="words_index",  # ユニークなインデックス名
    params={
        "json_cast_type": "double",  # Zilliz Cloudが値をインデックス化する際に使用するデータ型
        "json_path": "words" # キーへのJSONパス
    }
)

# JSONオブジェクト内のネストされたキーにインデックスを設定
index_params.add_index(
    field_name="dynamic_json", # 動的フィールド内のJSONキー名
    index_type="AUTOINDEX", # JSONパスインデックスではAUTOINDEXに設定する必要があります
    index_name="json_varchar_index", # ユニークなインデックス名
    params={
        "json_cast_type": "varchar", # Zilliz Cloudが値をインデックス化する際に使用するデータ型
        "json_path": "dynamic_json['varchar']" # ネストされたキーへのJSONパス
    }
)

# 深くネストされたキーにインデックスを設定
index_params.add_index(
    field_name="dynamic_json",
    index_type="AUTOINDEX", # JSONパスインデックスではAUTOINDEXに設定する必要があります
    index_name="json_nested_index", # ユニークなインデックス名
    params={
        "json_cast_type": "double",
        "json_path": "dynamic_json['nested']['value']"
    }
)

型変換のためのJSONキャスト関数を使用​

動的フィールドキーが不正な形式の値を含んでいる場合（例：文字列として格納された数値）、キャスト関数を使用して変換できます。

# インデックス化前に文字列をdoubleに変換
index_params.add_index(
    field_name="dynamic_json", # JSONキー名
    index_type="AUTOINDEX",
    index_name="json_string_price_index",
    params={
        "json_path": "dynamic_json['string_price']",
        "json_cast_type": "double", # キャスト関数の出力型にする必要があります
        "json_cast_function": "STRING_TO_DOUBLE" # 大文字小文字を区別しない; 文字列をdoubleに変換
    }
)
📘ノート

  • 型変換に失敗した場合（例：値"not_a_number"は数値に変換できません）、値はスキップされインデックス化されません。

  • キャスト関数のパラメータの詳細については、JSONフィールドを参照してください。

コレクションにインデックスを適用​

インデックスパラメータを定義した後、create_index()を使用してコレクションに適用できます。

client.create_index(
    collection_name="my_collection",
    index_params=index_params
)

動的フィールドキーによるフィルタリング​

動的フィールドキーを持つエンティティを挿入した後、標準のフィルター式を使用してそれらをフィルターできます。

  • JSONでないキー（例：文字列、数値、真偽値）については、キー名を直接参照できます。

  • JSONオブジェクトを格納するキーについては、JSONパス構文を使用してネストされた値にアクセスします。

前のセクションの例のエンティティに基づき、有効なフィルター式は次のとおりです。

# 動的フィールドキーによるクエリ
results = client.query(
    collection_name="my_collection",
    filter="overview == 'Great product'",
    output_fields=["my_id", "overview", "words"]
)

# ネストされたJSON値によるクエリ
results = client.query(
    collection_name="my_collection",
    filter="dynamic_json['nested']['value'] > 40",
    output_fields=["my_id", "dynamic_json"]
)

# 数値によるクエリ
results = client.query(
    collection_name="my_collection",
    filter="words >= 100",
    output_fields=["my_id", "words"]
)

検索における動的フィールドの使用​

動的フィールドは、ベクトル検索を強化するためのメタデータを格納する場合にも便利です。検索時にoutput_fieldsパラメータに動的フィールドキーを含めることで、検索結果にこの追加データを取得できます。

# 動的フィールドキーを含むベクトル検索
results = client.search(
    collection_name="my_collection",
    data=[[0.1, 0.2, 0.3, 0.4, 0.5]],  # クエリベクトル
    limit=5,
    output_fields=["my_id", "overview", "words", "dynamic_json"]
)

# 結果の例:
# [
#   {
#     "id": 1,
#     "distance": 0.123,
#     "entity": {
#       "my_id": 1,
#       "overview": "Great product",
#       "words": 150,
#       "dynamic_json": {
#         "varchar": "some text",
#         "nested": {
#           "value": 42.5
#         },
#         "string_price": "99.99"
#       }
#     }
#   }
# ]

制限事項​

  • 動的フィールドは、JSON型であるため、明示的なスカラーフィールドよりもパフォーマンスが低下する可能性があります。

  • 動的フィールドキーにインデックスを設定していない場合、フィルタリングは全検索になり、パフォーマンスが低下する可能性があります。

  • Zilliz Cloud v2.4.0以降では、動的フィールドに格納されるデータはスキーマ検証を通過する必要があります。無効なデータは挿入時に拒否されます。

  • クエリや検索結果から動的フィールドデータを取得するには、output_fieldsに*または$metaを含める必要があります。

  • 動的フィールドは、アップサート操作ではサポートされていません。