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

プライマリフィールド & AutoID

Zilliz Cloudのすべてのコレクションには、各エンティティを一意に識別するためのプライマリフィールドが必要です。このフィールドにより、すべてのエンティティが曖昧性なく挿入、更新、クエリ、削除できます。

使用ケースに応じて、Zilliz CloudがIDを自動生成する（AutoID）か、自分でIDを手動で割り当てるかを選択できます。

プライマリフィールドとは？​

プライマリフィールドは、コレクション内の各エンティティの一意のキーとして機能し、従来のデータベースのプライマリキーに似ています。Zilliz Cloudは、挿入、アップサート、削除、クエリ操作中にエンティティを管理するためにプライマリフィールドを使用します。

主要な要件:

  • 各コレクションには正確に1つのプライマリフィールドが必要です。

  • プライマリフィールドの値はnullにできません。

  • データ型は作成時に指定され、後で変更することはできません。

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

プライマリフィールドは、エンティティを一意に識別できるサポートされているスカラーデータ型を使用する必要があります。

データ型

説明

INT64

64ビット整数型。通常AutoIDで使用されます。これはほとんどの使用ケースにおすすめのオプションです。

VARCHAR

可変長文字列型。エンティティ識別子が外部システム（たとえば、商品コードやユーザーID）から来る場合に使用します。max_lengthプロパティが必要で、値ごとに許可される最大バイト数を定義します。

AutoIDと手動IDの選択​

Zilliz Cloudは、プライマリキー値の割り当てに2つのモードをサポートしています。

モード

説明

推奨対象

AutoID

Zilliz Cloudが挿入またはインポートされたエンティティに一意の識別子を自動生成します。

IDを手動で管理する必要がないほとんどのシナリオ。

手動ID

データを挿入またはインポートする際に自分で一意のIDを提供します。

外部システムや既存のデータセットとIDを合わせる必要がある場合。

📘注釈

どのモードを選択するかわからない場合は、AutoIDで始めることをおすすめします。これにより、より簡単なデータインジェストと一意性の保証を実現できます。

クイックスタート: AutoIDの使用​

Zilliz CloudにID生成を自動で任せることができます。

ステップ1: AutoID付きコレクションの作成​

プライマリフィールド定義でauto_id=Trueを有効にします。Zilliz CloudがID生成を自動で処理します。

from pymilvus import MilvusClient, DataType

client = MilvusClient(uri="YOUR_CLUSTER_ENDPOINT")

schema = client.create_schema()

# AutoID有効化されたプライマリフィールドを定義
schema.add_field(
    field_name="id", # プライマリフィールド名
    is_primary=True,
    auto_id=True,  # MilvusがIDを自動生成; デフォルトはFalse
    datatype=DataType.INT64
)

# 他のフィールドを定義
schema.add_field(field_name="embedding", datatype=DataType.FLOAT_VECTOR, dim=4) # ベクトルフィールド
schema.add_field(field_name="category", datatype=DataType.VARCHAR, max_length=1000) # VARCHAR型のスカラーフィールド

# コレクションを作成
if client.has_collection("demo_autoid"):
    client.drop_collection("demo_autoid")
client.create_collection(collection_name="demo_autoid", schema=schema)

ステップ2: データ挿入​

重要: プライマリフィールド列をデータに含めないでください。Zilliz CloudがIDを自動生成します。

data = [
    {"embedding": [0.1, 0.2, 0.3, 0.4], "category": "book"},
    {"embedding": [0.2, 0.3, 0.4, 0.5], "category": "toy"},
]

res = client.insert(collection_name="demo_autoid", data=data)
print("生成されたID:", res.get("ids"))

# 出力例:
# 生成されたID: [461526052788333649, 461526052788333650]
📘注釈

既存のエンティティで作業する際は、重複IDエラーを避けるためにinsert()の代わりにupsert()を使用してください。

手動IDの使用​

IDを手動で制御する必要がある場合は、AutoIDを無効にして、自分で値を提供します。

ステップ1: AutoIDなしコレクションの作成​

from pymilvus import MilvusClient, DataType

client = MilvusClient(uri="YOUR_CLUSTER_ENDPOINT")

schema = client.create_schema()

# AutoIDなしでプライマリフィールドを定義
schema.add_field(
    field_name="product_id",
    is_primary=True,
    auto_id=False,  # データインジェスト時にIDを手動で提供
    datatype=DataType.VARCHAR,
    max_length=100 # datatypeがVARCHARの場合に必要
)

# 他のフィールドを定義
schema.add_field(field_name="embedding", datatype=DataType.FLOAT_VECTOR, dim=4) # ベクトルフィールド
schema.add_field(field_name="category", datatype=DataType.VARCHAR, max_length=1000) # VARCHAR型のスカラーフィールド

# コレクションを作成
if client.has_collection("demo_manual_ids"):
    client.drop_collection("demo_manual_ids")
client.create_collection(collection_name="demo_manual_ids", schema=schema)

ステップ2: ID付きデータの挿入​

すべての挿入操作でプライマリフィールド列を含める必要があります。

# 各エンティティはプライマリフィールド`product_id`を含む必要があります
data = [
    {"product_id": "PROD-001", "embedding": [0.1, 0.2, 0.3, 0.4], "category": "book"},
    {"product_id": "PROD-002", "embedding": [0.2, 0.3, 0.4, 0.5], "category": "toy"},
]

res = client.insert(collection_name="demo_manual_ids", data=data)
print("生成されたID:", res.get("ids"))

# 出力例:
# 生成されたID: ['PROD-001', 'PROD-002']

あなたの責任:

  • すべてのIDがすべてのエンティティ間で一意であることを保証すること

  • すべての挿入/インポート操作にプライマリフィールドを含めること

  • IDの競合と重複検出を自分で処理すること