メインコンテンツまでスキップ

Primary Field と AutoID

Zilliz Cloud のすべての collection には、各 entity を一意に識別するための primary field が必要です。このフィールドにより、すべての entity を曖昧さなく挿入、更新、クエリ、削除できます。

ユースケースに応じて、Zilliz Cloud に ID を自動生成させる（AutoID）ことも、自分で ID を手動で割り当てることもできます。

primary field とは何ですか？​

primary field は、従来のデータベースにおける主キーのように、collection 内の各 entity の一意キーとして機能します。Zilliz Cloud は、挿入、upsert、削除、クエリの各操作で entity を管理するために primary field を使用します。

主な要件:

  • 各 collection には ちょうど 1 つ の primary field が必要です。

  • primary field の値を null にすることはできません。

  • データ型は作成時に指定する必要があり、後から変更することはできません。

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

primary field には、entity を一意に識別できる、サポート対象の scalar データ型を使用する必要があります。

Data Type説明
INT6464-bit integer 型で、AutoID とよく使われます。ほとんどのユースケースで推奨されるオプションです。
VARCHAR可変長文字列型です。entity 識別子が外部システム由来である場合（たとえば、製品コードやユーザー ID）に使用します。各値に許可される最大バイト数を定義するために max_length プロパティが必要です。

AutoID と Manual IDs の選び方​

Zilliz Cloud は、primary key の値を割り当てるための 2 つのモードをサポートしています。

Mode説明推奨される用途
AutoIDZilliz Cloud が、挿入またはインポートされた entity に対して一意の識別子を自動生成します。ID を手動で管理する必要がないほとんどのシナリオ。
Manual IDデータの挿入またはインポート時に、自分で一意の ID を指定します。ID を外部システムや既存データセットに合わせる必要がある場合。
📘注意

  • どちらのモードを選ぶべきか迷う場合は、よりシンプルな取り込みと一意性の保証のために、AutoID から始めてください。

  • primary key を手動設定することに利点がある場合を除き、すべてのケースで autoId を利用することを推奨します。

クイックスタート: AutoID を使う​

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

ステップ 1: AutoID を有効にして collection を作成する​

primary field の定義で auto_id=True を有効にします。Zilliz Cloud が自動的に ID 生成を処理します。

python
from pymilvus import MilvusClient, DataType

client = MilvusClient(uri="YOUR_CLUSTER_ENDPOINT")

schema = client.create_schema()

# Define primary field with AutoID enabled
schema.add_field(
    field_name="id", # Primary field name
    is_primary=True,
    auto_id=True,  # Milvus generates IDs automatically; Defaults to False
    datatype=DataType.INT64
)

# Define the other fields
schema.add_field(field_name="embedding", datatype=DataType.FLOAT_VECTOR, dim=4) # Vector field
schema.add_field(field_name="category", datatype=DataType.VARCHAR, max_length=1000) # Scalar field of the VARCHAR type

# Create the collection
if client.has_collection("demo_autoid"):
    client.drop_collection("demo_autoid")
client.create_collection(collection_name="demo_autoid", schema=schema)

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

重要: データに primary field 列を含めないでください。Zilliz Cloud が自動的に ID を生成します。

python
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("Generated IDs:", res.get("ids"))

# Output example:
# Generated IDs: [461526052788333649, 461526052788333650]
📘注意

既存の entity を扱う場合は、重複 ID エラーを避けるために insert() ではなく upsert() を使用してください。

Manual IDs を使う​

ID を手動で制御する必要がある場合は、AutoID を無効にして独自の値を指定します。

ステップ 1: AutoID を使わずに collection を作成する​

python
from pymilvus import MilvusClient, DataType

client = MilvusClient(uri="YOUR_CLUSTER_ENDPOINT")

schema = client.create_schema()

# Define the primary field without AutoID
schema.add_field(
    field_name="product_id",
    is_primary=True,
    auto_id=False,  # You'll provide IDs manually at data ingestion
    datatype=DataType.VARCHAR,
    max_length=100 # Required when datatype is VARCHAR
)

# Define the other fields
schema.add_field(field_name="embedding", datatype=DataType.FLOAT_VECTOR, dim=4) # Vector field
schema.add_field(field_name="category", datatype=DataType.VARCHAR, max_length=1000) # Scalar field of the VARCHAR type

# Create the collection
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 でデータを挿入する​

すべての挿入操作で、primary field の列を含める必要があります。

python
# Each entity must contain the primary field `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("Generated IDs:", res.get("ids"))

# Output example:
# Generated IDs: ['PROD-001', 'PROD-002']

あなたの責務:

  • すべての entity 間で各 ID が一意であることを保証する

  • すべての insert/import 操作に primary field を含める

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

Ctrl I