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

Dynamic Field

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に格納されたキーの値に適用されます。

サポートされる型は以下の通りです：

  • String（VARCHAR）

  • Integer（INT8、INT32、INT64）

  • Floating point（FLOAT、DOUBLE）

  • Boolean（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",       # スキーマで定義されていないスカラー
        "words": 150,                      # スキーマで定義されていないスカラー
        "dynamic_json": {                  # スキーマで定義されていないJSON
            "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 Fieldを参照してください。

コレクションへのインデックスの適用​

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

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

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

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

  • JSONでないキー（文字列、数値、ブール値など）については、キー名で直接参照できます。

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

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

filter = 'overview == "Great product"'                # 非JSONキー
filter = 'words >= 100'                               # 非JSONキー
filter = 'dynamic_json["nested"]["value"] < 50'       # JSONオブジェクトキー

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

# 例: 動的フィールドキーを検索結果に含める
results = client.search(
    collection_name="my_collection",
    data=[[0.1, 0.2, 0.3, 0.4, 0.5]],
    filter=filter,                         # 以前に定義したフィルター式
    limit=10,
    output_fields=[
        "overview",                        # 単純な動的フィールドキー
        'dynamic_json["varchar"]'          # ネストされたJSONキー
    ]
)
📘注意

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

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

すべてをまとめましょう​

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

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

  • ベクトルフィールドにインデックスを作成（各コレクションに必須）

    Index Vector Fieldsを参照してください

  • コレクションをロード

    Load & Releaseを参照してください

  • JSONパスフィルターを使用して検索またはクエリ

    Filtered SearchおよびJSON Operatorsを参照してください

よくある質問​

スキーマで明示的にフィールドを定義する代わりに動的フィールドキーを使用すべき場面は？​

動的フィールドキーを使用する代わりに、スキーマでフィールドを明示的に定義すべきなのは以下のときです：

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

  • フィールドが頻繁にアクセスまたはフィルターされる場合: 動的フィールドキーにインデックスを作成すれば固定スキーマフィールドと同様のフィルタリングパフォーマンスを提供できますが、明示的に定義されたフィールドはより明確な構造と保守性を提供します。

  • フィールドの動作を完全に制御する必要がある場合: 明示的なフィールドはスキーマレベルの制約、検証、およびより明確な型付けをサポートし、データの整合性と一貫性を管理するのに役立ちます。

  • インデックスの不整合を避ける場合: 動的フィールドキーのデータは型や構造の不整合が起こりやすいです。固定スキーマを使用すると、特にインデックスやキャストを計画している場合、データの品質を確保するのに役立ちます。

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

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

動的フィールドキーをインデックス化するときに、データキャストが失敗した場合どうなりますか？​

動的フィールドキーにインデックスを作成し、データキャストが失敗した場合—たとえば、doubleに変換しようとした値が"abc"のような非数値文字列だった場合—それらの特定の値はインデックス作成中に黙ってスキップされます。インデックスに含まれず、したがってインデックスに依存するフィルター検索やクエリ結果では返されません。

これにはいくつか重要な意味合いがあります：

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

  • 検索精度のリスク: データ品質が一貫していない大規模データセット（特に動的フィールドキー）では、この動作により予期しない結果の欠落が生じる可能性があります。インデックス作成前に一貫した有効なデータ形式を確保することが重要です。

  • キャスト関数は慎重に使用: インデックス作成中に文字列から数値への変換にjson_cast_functionを使用する場合、文字列値が確実に変換可能であることを確認してください。json_cast_typeと実際に変換された型の不一致はエラーまたはスキップされたエントリを引き起こします。

クエリがインデックスで使用されたキャスト型とは異なるデータ型を使用している場合どうなりますか？​

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