الحقل الأساسي والمعرف التلقائي

يجب أن تحتوي كل مجموعة في ميلفوس على حقل أساسي لتعريف كل كيان بشكل فريد. يضمن هذا الحقل إمكانية إدراج كل كيان أو تحديثه أو الاستعلام عنه أو حذفه دون غموض.

اعتمادًا على حالة الاستخدام الخاصة بك، يمكنك إما السماح ل Milvus بإنشاء معرّفات تلقائيًا (AutoID) أو تعيين معرّفاتك الخاصة يدويًا.

ما هو الحقل الأساسي؟

يعمل الحقل الأساسي كمفتاح فريد لكل كيان في مجموعة، على غرار المفتاح الأساسي في قاعدة البيانات التقليدية. يستخدم Milvus الحقل الأساسي لإدارة الكيانات أثناء عمليات الإدراج والإضافة والحذف والاستعلام.

متطلبات المفتاح:

• يجب أن تحتوي كل مجموعة على حقل أساسي واحد فقط.

• لا يمكن أن تكون قيم الحقل الأساسي فارغة.

• يجب تحديد نوع البيانات عند الإنشاء ولا يمكن تغييره لاحقًا.

أنواع البيانات المعتمدة

يجب أن يستخدم الحقل الأساسي نوع بيانات قياسي مدعوم يمكنه تحديد الكيانات بشكل فريد.

نوع البيانات	الوصف
INT64	نوع عدد صحيح 64 بت، يستخدم عادةً مع المعرف التلقائي. هذا هو الخيار الموصى به لمعظم حالات الاستخدام.
VARCHAR	نوع سلسلة متغيرة الطول. يُستخدم هذا النوع عندما تأتي معرّفات الكيانات من أنظمة خارجية (على سبيل المثال، رموز المنتجات أو معرّفات المستخدمين). يتطلب الخاصية max_length لتحديد الحد الأقصى لعدد البايت المسموح به لكل قيمة.

اختر بين المعرف التلقائي والمعرفات اليدوية

يدعم Milvus وضعين لتعيين قيم المفاتيح الأساسية.

الوضع	الوصف	موصى به ل
المعرف التلقائي	يقوم Milvus تلقائياً بإنشاء معرفات فريدة للكيانات المدرجة أو المستوردة.	معظم السيناريوهات التي لا تحتاج فيها إلى إدارة المعرفات يدوياً.
المعرف اليدوي	يمكنك توفير معرفات فريدة بنفسك عند إدراج البيانات أو استيرادها.	عندما يجب أن تتوافق المعرفات مع الأنظمة الخارجية أو مجموعات البيانات الموجودة مسبقاً.

البدء السريع: استخدام المعرف التلقائي

يمكنك السماح لـ Milvus بالتعامل مع إنشاء المعرف تلقائيًا.

الخطوة 1: إنشاء مجموعة باستخدام المعرف التلقائي

قم بتمكين auto_id=True في تعريف الحقل الأساسي الخاص بك. سيتعامل Milvus مع إنشاء المعرف تلقائيًا.

from pymilvus import MilvusClient, DataType

client = MilvusClient(uri="http://localhost:19530")

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)

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("http://localhost:19530")
        .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);

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

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

// Define schema fields
const schema = [
  {
    name: "id",
    description: "Primary field",
    data_type: DataType.Int64,
    is_primary_key: true,
    autoID: true, // Milvus generates IDs automatically
  },
  {
    name: "embedding",
    description: "Vector field",
    data_type: DataType.FloatVector,
    dim: 4,
  },
  {
    name: "category",
    description: "Scalar field",
    data_type: DataType.VarChar,
    max_length: 1000,
  },
];

// Create the collection
await client.createCollection({
  collection_name: "demo_autoid",
  fields: schema,
});

// go

# 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 'http://localhost:19530/v2/vectordb/collections/create' \
-H 'Content-Type: application/json' \
-d "{
    \"collectionName\": \"demo_autoid\",
    \"schema\": $SCHEMA
}"

الخطوة 2: إدراج البيانات

مهم: لا تقم بتضمين عمود الحقل الأساسي في بياناتك. يقوم Milvus بإنشاء المعرفات تلقائيًا.

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]

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());

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

# 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 'http://localhost:19530/v2/vectordb/entities/insert' \
-H 'Content-Type: application/json' \
-d "{
    \"collectionName\": \"demo_autoid\",
    \"data\": $INSERT_DATA
}"

استخدم المعرفات اليدوية

إذا كنت بحاجة إلى التحكم في المعرفات يدويًا، فقم بتعطيل المعرف التلقائي وقدم قيمك الخاصة.

الخطوة 1: إنشاء مجموعة بدون معرف تلقائي

from pymilvus import MilvusClient, DataType

client = MilvusClient(uri="http://localhost:19530")

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)

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("http://localhost:19530")
        .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);

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

const client = new MilvusClient({
  address: "localhost:19530",
  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

# 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 'http://localhost:19530/v2/vectordb/collections/create' \
-H 'Content-Type: application/json' \
-d "{
    \"collectionName\": \"demo_manual_ids\",
    \"schema\": $SCHEMA
}"

الخطوة 2: أدخل البيانات بمعرّفاتك الخاصة

يجب عليك تضمين عمود الحقل الأساسي في كل عملية إدراج.

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

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());

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

# 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 'http://localhost:19530/v2/vectordb/entities/insert' \
-H 'Content-Type: application/json' \
-d "{
    \"collectionName\": \"demo_manual_ids\",
    \"data\": $INSERT_DATA
}"

مسؤولياتك:

• تأكد من أن جميع المعرفات فريدة في جميع الكيانات

• قم بتضمين الحقل الأساسي في كل عملية إدراج/استيراد

• تعامل مع تعارضات المعرفات واكتشاف التكرار بنفسك

الاستخدام المتقدم

ترحيل البيانات باستخدام المعرفات التلقائية الموجودة

للحفاظ على المعرفات الموجودة أثناء ترحيل البيانات، قم بتمكين الخاصية allow_insert_auto_id عن طريق إجراء الاستدعاء alter_collection_properties. عند التعيين على صواب، يقبل Milvus المعرفات المقدمة من المستخدم حتى إذا تم تمكين المعرف التلقائي.

للحصول على تفاصيل التكوين، راجع تعديل المجموعة.

ضمان تفرد المعرف التلقائي العام عبر المجموعات

عند تشغيل مجموعات Milvus متعددة، قم بتكوين معرف مجموعة فريد لكل منها لضمان عدم تداخل المعرفات التلقائية أبدًا.

التهيئة: قم بتحرير التكوين common.clusterID في milvus.yaml قبل تهيئة مجموعتك:

common:
  clusterID: 3   # Must be unique across all clusters (Range: 0-7)

في هذا التكوين، clusterID يحدد المعرف الفريد المستخدم في إنشاء المعرف التلقائي، الذي يتراوح من 0 إلى 7 (يدعم ما يصل إلى ثماني مجموعات).

مرجع: كيف يعمل المعرف التلقائي

يمكن أن يساعدك فهم كيفية قيام AutoID بإنشاء معرّفات فريدة داخليًا في تكوين معرّفات المجموعات بشكل صحيح واستكشاف المشكلات المتعلقة بالمعرّفات وإصلاحها.

يستخدم المعرف التلقائي تنسيقًا منظمًا 64 بت لضمان التفرد:

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

الجزء	الوصف
sign_bit	محجوز للاستخدام الداخلي
cluster_id	يحدد المجموعة التي قامت بإنشاء المعرف (نطاق القيمة: 0-7)
physical_ts	الطابع الزمني بالمللي ثانية عندما تم إنشاء المعرف بالمللي ثانية
logical_ts	عداد لتمييز المعرفات التي تم إنشاؤها في نفس المللي ثانية