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

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

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

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

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

プライマリフィールドは、従来のデータベースの主キーと同様に、コレクション内の各エンティティの一意キーとして機能します。Zilliz Cloud は、挿入、upsert、削除、クエリの各操作でプライマリフィールドを使用してエンティティを管理します。

主な要件：

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

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

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

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

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

データ型

説明

INT64

64 ビット整数型で、AutoID でよく使用されます。ほとんどのユースケースで推奨されるオプションです。

VARCHAR

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

AutoID と手動 ID のどちらかを選択する​

Zilliz Cloud では、主キー値を割り当てる 2 つのモードをサポートしています。

モード

説明

推奨用途

AutoID

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

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

手動 ID

データを挿入またはインポートするときに、一意の ID を自分で指定します。

ID を外部システムまたは既存のデータセットと一致させる必要がある場合。

📘Notes

  • どのモードを選択すべきかわからない場合は、よりシンプルな取り込みと一意性の保証のために AutoID から始める ことをお勧めします。

  • 主キーを手動で設定することが有益でない限り、すべての場合で autoId に依存することをお勧めします。

クイックスタート：AutoID を使用する​

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

ステップ 1: AutoID を使用してコレクションを作成する​

プライマリフィールドの定義で 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,  # Zilliz Cloud 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: データを挿入する​

重要： データにプライマリフィールドの列を含めないでください。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]
📘Notes

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

手動 ID を使用する​

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

ステップ 1: AutoID を使用せずにコレクションを作成する​

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 を使用してデータを挿入する​

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

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']

お客様の責任：

  • すべてのエンティティで ID が一意であることを確認してください。

  • すべての挿入/import 操作にプライマリフィールドを含めてください。

  • ID の競合と重複の検出はご自身で処理してください。

高度な使用方法​

既存の AutoID を含むデータを移行する​

データ移行中に既存の ID を保持するには、alter_collection_properties 呼び出しを実行して allow_insert_auto_id プロパティを有効にします。true に設定すると、AutoID が有効であっても、Zilliz Cloud はユーザーが指定した ID を受け入れます。

構成の詳細については、Modify コレクション を参照してください。

リファレンス：AutoID の仕組み​

AutoID は、一意性を保証するために構造化された 64 ビット形式を使用します：

plaintext
[sign_bit][cluster_id][physical_ts][logical_ts]

セグメント

説明

sign_bit

内部使用のために予約されています。

cluster_id

ID を生成したクラスターを識別します（値の範囲：0-7）。

physical_ts

ID が生成された時点のタイムスタンプをミリ秒単位で示します。

logical_ts

同じミリ秒内に作成された ID を区別するためのカウンターです。

📘Notes

VARCHAR をデータ型として AutoID を有効にした場合でも、Zilliz Cloud は数値 ID を生成します。これらの ID は、最大 20 文字の数値文字列として保存されます（uint64 の範囲）。

このページは役に立ちましたか？
Ctrl I