[説明] このページは機械翻訳された日本語版です。内容に誤りがございましたら、報告していただけると助かります。

主フィールドと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生成を自動的に処理します。

Python

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)

Java

import io.milvus.v2.client.ConnectConfig;
import io.milvus.v2.client.MilvusClientV2;
import io.milvus.v2.service.collection.request.AddFieldReq;
import io.milvus.v2.service.collection.request.CreateCollectionReq;
import io.milvus.v2.service.collection.request.DropCollectionReq;

MilvusClientV2 client = new MilvusClientV2(ConnectConfig.builder()
        .uri("YOUR_CLUSTER_ENDPOINT")
        .build());

CreateCollectionReq.CollectionSchema collectionSchema = CreateCollectionReq.CollectionSchema.builder()
        .build();
collectionSchema.addField(AddFieldReq.builder()
        .fieldName("id")
        .dataType(DataType.Int64)
        .isPrimaryKey(true)
        .autoID(true)
        .build());
collectionSchema.addField(AddFieldReq.builder()
        .fieldName("embedding")
        .dataType(DataType.FloatVector)
        .dimension(4)
        .build());
collectionSchema.addField(AddFieldReq.builder()
        .fieldName("category")
        .dataType(DataType.VarChar)
        .maxLength(1000)
        .build());

client.dropCollection(DropCollectionReq.builder()
        .collectionName("demo_autoid")
        .build());

CreateCollectionReq requestCreate = CreateCollectionReq.builder()
        .collectionName("demo_autoid")
        .collectionSchema(collectionSchema)
        .build();
client.createCollection(requestCreate);

NodeJS

import { MilvusClient, DataType } from "@zilliz/milvus2-sdk-node";

const client = new MilvusClient({
  address: "YOUR_CLUSTER_ENDPOINT",
});

// スキーマフィールドを定義
const schema = [
  {
    name: "id",
    description: "主フィールド",
    data_type: DataType.Int64,
    is_primary_key: true,
    autoID: true, // MilvusがIDを自動生成
  },
  {
    name: "embedding",
    description: "ベクトルフィールド",
    data_type: DataType.FloatVector,
    dim: 4,
  },
  {
    name: "category",
    description: "スカラーフィールド",
    data_type: DataType.VarChar,
    max_length: 1000,
  },
];

// コレクションを作成
await client.createCollection({
  collection_name: "demo_autoid",
  fields: schema,
});

Go

// go

cURL

# restful
export SCHEMA='{
    "autoID": true,
    "fields": [
        {
            "fieldName": "id",
            "dataType": "Int64",
            "isPrimary": true,
            "elementTypeParams": {}
        },
        {
            "fieldName": "embedding",
            "dataType": "FloatVector",
            "isPrimary": false,
            "elementTypeParams": {
                "dim": "4"
            }
        },
        {
            "fieldName": "category",
            "dataType": "VarChar",
            "isPrimary": false,
            "elementTypeParams": {
                "max_length": "1000"
            }
        }
    ]
}'

curl -X POST 'YOUR_CLUSTER_ENDPOINT/v2/vectordb/collections/create' \
-H 'Content-Type: application/json' \
-d "{
    \"collectionName\": \"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"))

# 出力例:
# Generated IDs: [461526052788333649, 461526052788333650]

Java

import com.google.gson.*;
import io.milvus.v2.service.vector.request.InsertReq;
import io.milvus.v2.service.vector.response.InsertResp;

List<JsonObject> rows = new ArrayList<>();
Gson gson = new Gson();
JsonObject row1 = new JsonObject();
row1.add("embedding", gson.toJsonTree(new float[]{0.1f, 0.2f, 0.3f, 0.4f}));
row1.addProperty("category", "book");
rows.add(row1);

JsonObject row2 = new JsonObject();
row2.add("embedding", gson.toJsonTree(new float[]{0.2f, 0.3f, 0.4f, 0.5f}));
row2.addProperty("category", "toy");
rows.add(row2);

InsertResp insertR = client.insert(InsertReq.builder()
        .collectionName("demo_autoid")
        .data(rows)
        .build());
System.out.printf("Generated IDs: %s\n", insertR.getPrimaryKeys());

NodeJS

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

const res = await client.insert({
    collection_name: "demo_autoid",
    fields_data: data,
});

console.log(res);

Go

// go

cURL

# restful
export INSERT_DATA='[
    {
        "embedding": [0.1, 0.2, 0.3, 0.4],
        "category": "book"
    },
    {
        "embedding": [0.2, 0.3, 0.4, 0.5],
        "category": "toy"
    }
]'

curl -X POST 'YOUR_CLUSTER_ENDPOINT/v2/vectordb/entities/insert' \
-H 'Content-Type: application/json' \
-d "{
    \"collectionName\": \"demo_autoid\",
    \"data\": $INSERT_DATA
}"

📘ノート

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

手動IDの使用

IDを手動で管理する必要がある場合は、AutoIDを無効にして独自の値を提供してください。

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

Python

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)

Java

import io.milvus.v2.client.ConnectConfig;
import io.milvus.v2.client.MilvusClientV2;
import io.milvus.v2.service.collection.request.AddFieldReq;
import io.milvus.v2.service.collection.request.CreateCollectionReq;
import io.milvus.v2.service.collection.request.DropCollectionReq;

MilvusClientV2 client = new MilvusClientV2(ConnectConfig.builder()
        .uri("YOUR_CLUSTER_ENDPOINT")
        .build());

CreateCollectionReq.CollectionSchema collectionSchema = CreateCollectionReq.CollectionSchema.builder()
        .build();
collectionSchema.addField(AddFieldReq.builder()
        .fieldName("product_id")
        .dataType(DataType.VarChar)
        .isPrimaryKey(true)
        .autoID(false)
        .maxLength(100)
        .build());
collectionSchema.addField(AddFieldReq.builder()
        .fieldName("embedding")
        .dataType(DataType.FloatVector)
        .dimension(4)
        .build());
collectionSchema.addField(AddFieldReq.builder()
        .fieldName("category")
        .dataType(DataType.VarChar)
        .maxLength(1000)
        .build());

client.dropCollection(DropCollectionReq.builder()
        .collectionName("demo_manual_ids")
        .build());

CreateCollectionReq requestCreate = CreateCollectionReq.builder()
        .collectionName("demo_manual_ids")
        .collectionSchema(collectionSchema)
        .build();
client.createCollection(requestCreate);

NodeJS

import { MilvusClient, DataType } from "@zilliz/milvus2-sdk-node";

const client = new MilvusClient({
  address: "YOUR_CLUSTER_ENDPOINT",
  username: "username",
  password: "Aa12345!!",
});

const schema = [
  {
    name: "product_id",
    data_type: DataType.VARCHAR,
    is_primary_key: true,
    autoID: false,
  },
  {
    name: "embedding",
    data_type: DataType.FLOAT_VECTOR,
    dim: 4,
  },
  {
    name: "category",
    data_type: DataType.VARCHAR,
    max_length: 1000,
  },
];

const res = await client.createCollection({
  collection_name: "demo_autoid",
  schema: schema,
});

Go

// go

cURL

# restful
export SCHEMA='{
    "autoID": false,
    "fields": [
        {
            "fieldName": "product_id",
            "dataType": "VarChar",
            "isPrimary": true,
            "elementTypeParams": {
                "max_length": "100"
            }
        },
        {
            "fieldName": "embedding",
            "dataType": "FloatVector",
            "isPrimary": false,
            "elementTypeParams": {
                "dim": "4"
            }
        },
        {
            "fieldName": "category",
            "dataType": "VarChar",
            "isPrimary": false,
            "elementTypeParams": {
                "max_length": "1000"
            }
        }
    ]
}'

curl -X POST 'YOUR_CLUSTER_ENDPOINT/v2/vectordb/collections/create' \
-H 'Content-Type: application/json' \
-d "{
    \"collectionName\": \"demo_manual_ids\",
    \"schema\": $SCHEMA
}"

ステップ2: IDでデータを挿入

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

Python

# 各エンティティには主フィールド`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"))

# 出力例:
# Generated IDs: ['PROD-001', 'PROD-002']

Java

import com.google.gson.*;
import io.milvus.v2.service.vector.request.InsertReq;
import io.milvus.v2.service.vector.response.InsertResp;

List<JsonObject> rows = new ArrayList<>();
Gson gson = new Gson();
JsonObject row1 = new JsonObject();
row1.addProperty("product_id", "PROD-001");
row1.add("embedding", gson.toJsonTree(new float[]{0.1f, 0.2f, 0.3f, 0.4f}));
row1.addProperty("category", "book");
rows.add(row1);

JsonObject row2 = new JsonObject();
row2.addProperty("product_id", "PROD-002");
row2.add("embedding", gson.toJsonTree(new float[]{0.2f, 0.3f, 0.4f, 0.5f}));
row2.addProperty("category", "toy");
rows.add(row2);

InsertResp insertR = client.insert(InsertReq.builder()
        .collectionName("demo_manual_ids")
        .data(rows)
        .build());
System.out.printf("Generated IDs: %s\n", insertR.getPrimaryKeys());

NodeJS

const 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"},
];

const insert = await client.insert({
    collection_name: "demo_autoid",
    fields_data: data,
});

console.log(insert);

Go

// go

cURL

# restful
export INSERT_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"
    }
]'

# データを挿入
curl -X POST 'YOUR_CLUSTER_ENDPOINT/v2/vectordb/entities/insert' \
-H 'Content-Type: application/json' \
-d "{
    \"collectionName\": \"demo_manual_ids\",
    \"data\": $INSERT_DATA
}"

あなたの責任:

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

• すべての挿入/インポート操作で主フィールドを含める

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