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

JSONフィールド

JSONフィールドは、キーと値のペアでベクトルの埋め込みとともに追加情報を格納するスカラーフィールドです。以下は、データがJSON形式で格納される例です。

{
  "metadata": {
    "product_info": {
      "category": "electronics",
      "brand": "BrandA"
    },
    "price": 99.99,
    "in_stock": true,
    "tags": ["summer_sale", "clearance"]
  }
}

限界​

  • フィールドサイズ: JSONフィールドの体格は65,536バイトに制限されています。

  • ネストされたディクショナリ: JSONフィールド値内のネストされたディクショナリは、ストレージ用のプレーン文字列として扱われます。

  • デフォルト値: JSONフィールドはデフォルト値をサポートしていません。ただし、null属性をTrueに設定してnull値を許可することができます。詳細については、「Nullableデフォルト」を参照してください。

  • タイプの一致: JSONフィールドのキー値が整数または浮動小数点数の場合、同じタイプの別の数値キーと（式フィルターを介して）比較することができます。

  • 命名: JSONキーに名前を付ける場合は、文字、数字、アンダースコアのみを使用することをお勧めします。他の文字を使用すると、フィルタリングや検索時に問題が発生する可能性があります。

  • 文字列の処理: Milvusは、セマンティック変換なしでJSONフィールドに入力された文字列値を保存します。例えば:

    • 'a"b',"a'b",'a\'b'と"a\"b"はそのまま保存されます。

    • 'a'b'と"a"b"は無効と見なされます。

  • JSONインデックス作成: JSONフィールドのインデックス作成時に、フィルタリングを高速化するためにJSONフィールドに1つ以上のパスを指定できます。追加のパスごとにインデックス作成のオーバーヘッドが増加するため、インデックス作成戦略を注意深く計画してください。JSONフィールドのインデックス作成に関する詳細な考慮事項については、「JSONインデックス作成に関する考慮事項」を参照してください。

JSONフィールドを追加する​

このJSONフィールドメタデータをコレクションスキーマに追加するには、DataType. JSONを使用します。以下の例では、null値を許可するJSONフィールドメタデータを定義しています。

# Import necessary libraries
from pymilvus import MilvusClient, DataType

# Define server address
SERVER_ADDR = "YOUR_CLUSTER_ENDPOINT"

# Create a MilvusClient instance
client = MilvusClient(uri=SERVER_ADDR)

# Define the collection schema
schema = client.create_schema(
    auto_id=False,
    enable_dynamic_fields=True,
)

# Add a JSON field that supports null values
schema.add_field(field_name="metadata", datatype=DataType.JSON, nullable=True)
schema.add_field(field_name="pk", datatype=DataType.INT64, is_primary=True)
schema.add_field(field_name="embedding", datatype=DataType.FLOAT_VECTOR, dim=3)

この例では、メタデータというJSONフィールドを追加して、商品カテゴリ、価格、ブランド情報などのベクトルデータに関連する追加のメタデータを格納します。

📘ノート

将来、追加の未定義フィールドを挿入する必要がある場合は enable_dynamic_fields=Trueを設定してください。

JSONオブジェクトが欠落しているかnullである場合は、nullable=Trueを使用してください。

インデックスパラメータの設定​

インデックス作成Zilliz Cloud大量のデータを素早くフィルタリングまたは検索します。Zilliz Cloudインデックス化とは:

  • ベクトルフィールドには必須です(類似検索を効率的に実行するため)。

  • 特定のJSONパスのスカラーフィルターを高速化するためのJSONフィールドのオプション。

JSONフィールドのインデックス​

デフォルトでは、JSONフィールドはインデックス化されないため、フィルタークエリ(例:metadata["price"]<100)はすべての行をスキャンする必要があります。metadataフィールド内の特定のパスでクエリを加速したい場合は、関心のある各パスに反転インデックスを作成できます。

この例では、JSONフィールドmetadata内の異なるパスに2つのインデックスを作成します：

index_params = client.prepare_index_params()

# Example 1: Index the 'category' key inside 'product_info' as a string
index_params.add_index(
    field_name="metadata", # JSON field name to index
    index_type="INVERTED", # Index type. Set to INVERTED
    index_name="json_index_1", # Index name
    params={
        "json_path": "metadata[\"product_info\"][\"category\"]", # Path in JSON field to index
        "json_cast_type": "varchar" # Data type that the extracted JSON values will be cast to
    }
)

# Example 2: Index 'price' as a numeric type (double)
index_params.add_index(
    field_name="metadata",
    index_type="INVERTED",
    index_name="json_index_2",
    params={
        "json_path": "metadata[\"price\"]",
        "json_cast_type": "double"
    }
)

パラメータ

説明

例の値

field_name

スキーマ内のJSONフィールドの名前。

"metadata"

index_type

作成するインデックスタイプ。現在、JSONパスインデックスにはINVERTEDのみがサポートされています。

"INVERTED"

index_name

（オプション）カスタムインデックス名。同じJSONフィールドに複数のインデックスを作成する場合は、異なる名前を指定してください。

"json_index_1"

params.json_path

インデックスを作成するJSONパスを指定します。ネストされたキー、配列の位置、または両方をターゲットにすることができます（例:metadata["product_info"]["category"]またはmetadata["tags"][0]）。 パスがない場合、または特定の行に配列要素が存在しない場合、インデックス作成中にその行は単にスキップされ、エラーはスローされません。

"metadata["product_info"]["category"]"

params.json_cast_type

ああ、データ型Zilliz Cloudインデックスを構築する際に、抽出されたJSON値をキャストします。有効な値:

  • "bool"または"BOOL"
  • "double"または"double"
  • "varchar"または"VARCHAR"注意:整数値の場合、Zilliz Cloud内部的にはインデックスにdoubleを使用します。2^53を超える大きな整数は精度を失います。型キャストが失敗した場合(型の不一致によるもの)、エラーはスローされず、その行の値はインデックスされません。

"varchar"

JSONインデックスに関する考慮事項​

  • フィルタリングロジック:

    • double型インデックス（json_cast_type="double"）を作成する場合、数値型のフィルタ条件のみがインデックスを使用できます。フィルタがdouble型インデックスと非数値型の条件を比較する場合、Zilliz Cloudブルートフォース検索に戻ります。

    • varchar型インデックス(json_cast_type="varchar")を作成した場合、文字列型のフィルタ条件のみがインデックスを使用できます。それ以外の場合は、Zilliz Cloudブルートフォースに戻る。

    • ブールインデックスはvarchar-typeと同様に動作します。

  • 用語の表現:

    • [value 1, value 2,...]でjson["field"]を使用することができます。ただし、インデックスはそのパスに格納されたスカラー値に対してのみ機能します。json["field"]が配列の場合、クエリはブルートフォースにフォールバックされます（配列型インデックスはまだサポートされていません）。

  • 数値の精度:

    • 内部的に、Zilliz Cloudすべての数値フィールドをdoubleとしてインデックス化します。数値が2^53を超えると精度が低下し、範囲外の値に対するクエリは完全に一致しない可能性があります。

  • データの整合性:

    • Zilliz Cloud指定されたキャストを超えてJSONキーを解析または変換しません。ソースデータが一貫性がない場合(例えば、一部の行はキー"k"の文字列を格納し、他の行は数値を格納します)、一部の行はインデックス化されません。

ベクトル場のインデックス​

次の例では、AUTOINDEXインデックスタイプを使用してベクトル場のembeddingにインデックスを作成します。このタイプでは、Zilliz Cloudデータ型に基づいて最適なインデックスを自動的に選択します。

# Set index params

index_params = client.prepare_index_params()

# Index `embedding` with AUTOINDEX and specify similarity metric type
index_params.add_index(
    field_name="embedding",
    index_name="vector_index",
    index_type="AUTOINDEX",  # Use automatic indexing to simplify complex index settings
    metric_type="COSINE"  # Specify similarity metric type, options include L2, COSINE, or IP
)

コレクションを作成​

スキーマとインデックスが定義されたら、文字列フィールドを含むコレクションを作成してください。

client.create_collection(
    collection_name="my_collection",
    schema=schema,
    index_params=index_params
)

データの挿入​

コレクションを作成した後、スキーマに一致するエンティティを挿入してください。

# Sample data
data = [
    {
        "metadata": {
            "product_info": {"category": "electronics", "brand": "BrandA"},
            "price": 99.99,
            "in_stock": True,
            "tags": ["summer_sale"]
        },
        "pk": 1,
        "embedding": [0.12, 0.34, 0.56]
    },
    {
        "metadata": None,  # Entire JSON object is null
        "pk": 2,
        "embedding": [0.56, 0.78, 0.90]
    },
    {
        # JSON field is completely missing
        "pk": 3,
        "embedding": [0.91, 0.18, 0.23]
    },
    {
        # Some sub-keys are null
        "metadata": {
            "product_info": {"category": None, "brand": "BrandB"},
            "price": 59.99,
            "in_stock": None
        },
        "pk": 4,
        "embedding": [0.56, 0.38, 0.21]
    }
]

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

フィルタ式を使用したクエリ​

エンティティを挿入した後、queryメソッドを使用して、指定したフィルター式に一致するエンティティを取得します。

📘ノート

null値を許可するJSONフィールドの場合、JSONオブジェクト全体が欠落しているか、Noneに設定されている場合、フィールドはnullとして扱われます。詳細については、Null値を持つJSONフィールドを参照してください。

metadataがnullでないエンティティを取得するには:

# Query to filter out records with null metadata

filter = 'metadata is not null'

res = client.query(
    collection_name="my_collection",
    filter=filter,
    output_fields=["metadata", "pk"]
)

# Expected result:
# Rows with pk=1 and pk=4 have valid, non-null metadata.
# Rows with pk=2 (metadata=None) and pk=3 (no metadata key) are excluded.

print(res)

# Output:
# data: [
#     "{'metadata': {'product_info': {'category': 'electronics', 'brand': 'BrandA'}, 'price': 99.99, 'in_stock': True, 'tags': ['summer_sale']}, 'pk': 1}",
#     "{'metadata': {'product_info': {'category': None, 'brand': 'BrandB'}, 'price': 59.99, 'in_stock': None}, 'pk': 4}"
# ]

metadata["product_info"]["category"]が"electronics"であるエンティティを取得するには:

filter = 'metadata["product_info"]["category"] == "electronics"'

res = client.query(
    collection_name="my_collection",
    filter=filter,
    output_fields=["metadata", "pk"]
)

# Expected result:
# - Only pk=1 has "category": "electronics".
# - pk=4 has "category": None, so it doesn't match.
# - pk=2 and pk=3 have no valid metadata.

print(res)

# Output:
# data: [
#     "{'pk': 1, 'metadata': {'product_info': {'category': 'electronics', 'brand': 'BrandA'}, 'price': 99.99, 'in_stock': True, 'tags': ['summer_sale']}}"
# ]

フィルタ式を用いたベクトル検索​

基本的なスカラー場フィルタリングに加えて、ベクトル類似検索をスカラー場フィルターと組み合わせることができます。例えば、次のコードはベクトル検索にスカラー場フィルターを追加する方法を示しています。

filter = 'metadata["product_info"]["brand"] == "BrandA"'

res = client.search(
    collection_name="my_collection",
    data=[[0.3, -0.6, 0.1]],
    limit=5,
    search_params={"params": {"nprobe": 10}},
    output_fields=["metadata"],
    filter=filter
)

# Expected result:
# - Only pk=1 has "brand": "BrandA" in metadata["product_info"].
# - pk=4 has "brand": "BrandB".
# - pk=2 and pk=3 have no valid metadata.
# Hence, only pk=1 matches the filter.

print(res)

# Output:
# data: [
#     "[{'id': 1, 'distance': -0.2479381263256073, 'entity': {'metadata': {'product_info': {'category': 'electronics', 'brand': 'BrandA'}, 'price': 99.99, 'in_stock': True, 'tags': ['summer_sale']}}}]"
# ]

さらに、Zilliz CloudJSON_CONTAINS、JSON_CONTAINS_ALL、JSON_CONTAINS_ANYなどの高度なJSONフィルタリング演算子をサポートし、クエリ機能をさらに強化できます。詳細については、「JSON演算子」を参照してください。