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

ダイナミックフィールド

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",    // Not in schema
  "category": "books"  // Not in schema
}

動的フィールド機能が有効になっている場合、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​

ダイナミックフィールド機能を使用するには、コレクションスキーマ作成時に enable_dynamic_field=True を設定します：

from pymilvus import MilvusClient, DataType

# Initialize client
client = MilvusClient(uri="YOUR_CLUSTER_ENDPOINT")

# Create schema with dynamic field enabled
schema = client.create_schema(
    auto_id=False,
    enable_dynamic_field=True,
)

# Add explicitly defined fields
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)

# Create the collection
client.create_collection(
    collection_name="my_collection",
    schema=schema
)

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

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

entities = [
    {
        "my_id": 1, # Explicitly defined primary field
        "my_vector": [0.1, 0.2, 0.3, 0.4, 0.5], # Explicitly defined vector field
        "overview": "Great product",       # Scalar key not defined in schema
        "words": 150,                      # Scalar key not defined in schema
        "dynamic_json": {                  # JSON key not defined in schema
            "varchar": "some text",
            "nested": {
                "value": 42.5
            },
            "string_price": "99.99"        # Number stored as string
        }
    }
]

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

動的フィールド内のキーのインデックス作成​

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

📘Notes

動的フィールドのキーに対するインデックス作成は任意です。インデックスなしでも動的フィールドのキーでクエリやフィルタリングが可能ですが、ブルートフォース検索による遅延が発生する可能性があります。

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 a simple string key
index_params.add_index(
    field_name="overview",  # Key name in the dynamic field
    index_type="AUTOINDEX", # Must be set to AUTOINDEX for JSON path indexing
    index_name="overview_index",  # Unique index name
    params={
        "json_cast_type": "varchar",   # Data type that Zilliz Cloud uses when indexing the values
        "json_path": "overview"        # JSON path to the key
    }
)

# Index a simple numeric key
index_params.add_index(
    field_name="words",  # Key name in the dynamic field
    index_type="AUTOINDEX", # Must be set to AUTOINDEX for JSON path indexing
    index_name="words_index",  # Unique index name
    params={
        "json_cast_type": "double",  # Data type that Zilliz Cloud uses when indexing the values
        "json_path": "words" # JSON path to the key
    }
)

# Index a nested key within a JSON object
index_params.add_index(
    field_name="dynamic_json", # JSON key name in the dynamic field
    index_type="AUTOINDEX", # Must be set to AUTOINDEX for JSON path indexing
    index_name="json_varchar_index", # Unique index name
    params={
        "json_cast_type": "varchar", # Data type that Zilliz Cloud uses when indexing the values
        "json_path": "dynamic_json['varchar']" # JSON path to the nested key
    }
)

# Index a deeply nested key
index_params.add_index(
    field_name="dynamic_json",
    index_type="AUTOINDEX", # Must be set to AUTOINDEX for JSON path indexing
    index_name="json_nested_index", # Unique index name
    params={
        "json_cast_type": "double",
        "json_path": "dynamic_json['nested']['value']"
    }
)

型変換に JSON キャスト関数を使用する​

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

# Convert a string to double before indexing
index_params.add_index(
    field_name="dynamic_json", # JSON key name
    index_type="AUTOINDEX",
    index_name="json_string_price_index",
    params={
        "json_path": "dynamic_json['string_price']",
        "json_cast_type": "double", # Must be the output type of the cast function
        "json_cast_function": "STRING_TO_DOUBLE" # Case insensitive; convert string to double
    }
)
📘Notes

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

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

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

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

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

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

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

  • JSON以外のキー（例：文字列、数値、ブール値）の場合、キー名を直接参照できます。

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

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

filter = 'overview == "Great product"'                # Non-JSON key
filter = 'words >= 100'                               # Non-JSON key
filter = 'dynamic_json["nested"]["value"] < 50'       # JSON object key

動的フィールドキーの取得: 検索またはクエリ結果に動的フィールドキーを返すには、フィルタリング時と同じJSONパス構文を使用して、output_fieldsパラメータで明示的に指定する必要があります。

# Example: Include dynamic field keys in search results
results = client.search(
    collection_name="my_collection",
    data=[[0.1, 0.2, 0.3, 0.4, 0.5]],
    filter=filter,                         # Filter expression defined earlier
    limit=10,
    output_fields=[
        "overview",                        # Simple dynamic field key
        "dynamic_json"          # Nested JSON key
    ]
)
📘Notes

動的フィールドのキーはデフォルトで結果に含まれず、明示的にリクエストする必要があります。

サポートされている演算子およびフィルター式の完全な一覧については、Filtered Search を参照してください。

すべてをまとめる​

ここまでで、スキーマに定義されていないキーを柔軟に保存・インデックスするために動的フィールドを使用する方法を学びました。動的フィールドのキーが一度挿入されれば、特別な構文は不要で、フィルター式内で他のフィールドと同様に使用できます。

実際のアプリケーションでこのワークフローを完了するには、以下の手順も必要です。

FAQ​

スキーマ内でフィールドを明示的に定義すべきタイミングは？動的フィールドキーを使うべきではないのはいつ？​

動的フィールドキーではなく、スキーマ内でフィールドを明示的に定義すべきケースは以下の通りです。

  • そのフィールドが頻繁に output_fields に含まれる場合: output_fields 経由で効率的に取得できることが保証されているのは、明示的に定義されたフィールドのみです。動的フィールドキーは高頻度での取得に最適化されておらず、パフォーマンスオーバーヘッドが発生する可能性があります。

  • そのフィールドが頻繁にアクセスまたはフィルターされる場合: 動的フィールドキーにインデックスを作成すれば、固定スキーマフィールドと同程度のフィルタリング性能が得られますが、明示的に定義されたフィールドの方が構造が明確で保守性が高くなります。

  • フィールドの動作を完全に制御したい場合: 明示的なフィールドでは、スキーマレベルでの制約、バリデーション、明確な型指定が可能であり、データの整合性と一貫性を管理するのに役立ちます。

  • インデックスの不整合を避けたい場合: 動的フィールドキー内のデータは、型や構造において不整合が生じやすい傾向があります。固定スキーマを使用することでデータ品質を確保しやすくなり、特にインデックスやキャストを利用する予定がある場合は重要です。

同じ動的フィールドキーに対して、異なるデータ型で複数のインデックスを作成できますか？​

いいえ、1つのJSONパスにつき1つのインデックスしか作成できません。たとえ動的フィールドキーに複数の型の値（例：一部が文字列、一部が数値）が混在していたとしても、そのパスのインデックス作成時には単一の json_cast_type を選択する必要があります。現時点では、同じキーに対して異なる型で複数のインデックスを作成することはサポートされていません。

動的フィールドキーのインデックス作成時にデータのキャストに失敗した場合はどうなりますか？​

動的フィールドキーに対してインデックスを作成しており、データのキャストに失敗した場合（例：double 型へのキャストが想定されていた値が "abc" のような非数値文字列だった場合）、該当する値はインデックス作成中に静かにスキップされます。これらの値はインデックスに含まれないため、インデックスに依存するフィルターに基づく検索やクエリの結果にも表示されません。

これにはいくつか重要な影響があります。

  • フルスキャンへのフォールバックなし: 多くのエンティティが正常にインデックスされた場合、フィルタリングクエリは完全にインデックスに依存します。キャストに失敗したエンティティは、フィルター条件に論理的に一致していても結果セットから除外されます。

  • 検索精度のリスク: データ品質が一貫していない大規模なデータセット（特に動的フィールドキー内）では、この動作により予期しない検索漏れが発生する可能性があります。インデックス作成前に、データのフォーマットが一貫しており有効であることを確認することが極めて重要です。

  • キャスト関数の慎重な使用: インデックス作成時に json_cast_function を使って文字列を数値に変換する場合、その文字列値が確実に変換可能であることを保証してください。json_cast_type と実際に変換された型との間に不一致があると、エラーが発生するか、エントリがスキップされます。

クエリで使用するデータ型が、インデックス作成時のキャスト型と異なる場合はどうなりますか？​

クエリで動的フィールドキーを異なるデータ型で比較する場合（例：インデックスが double 型にキャストされているにもかかわらず、文字列として比較するクエリを実行する場合）、システムはインデックスを使用せず、可能な場合にのみフルスキャンにフォールバックします。最高のパフォーマンスと精度を得るには、クエリのデータ型がインデックス作成時に指定した json_cast_type と一致していることを確認してください。