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

主フィールドと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の競合や重複検出を自分で処理すること