Felder zu einer bestehenden Sammlung hinzufügenCompatible with Milvus 2.6.x

Milvus ermöglicht es Ihnen, dynamisch neue Felder zu bestehenden Sammlungen hinzuzufügen, so dass Sie Ihr Datenschema leicht weiterentwickeln können, wenn sich Ihre Anwendungsanforderungen ändern. Dieser Leitfaden zeigt Ihnen anhand von praktischen Beispielen, wie Sie Felder in verschiedenen Szenarien hinzufügen können.

Überlegungen

Bevor Sie Felder zu Ihrer Sammlung hinzufügen, sollten Sie diese wichtigen Punkte beachten:

• Sie können skalare Felder hinzufügen (INT64, VARCHAR, FLOAT, DOUBLE, usw.). Vektorfelder können nicht zu bestehenden Sammlungen hinzugefügt werden.

• Neue Felder müssen löschbar sein (nullable=True), damit vorhandene Entitäten, die keine Werte für das neue Feld haben, berücksichtigt werden können.

• Das Hinzufügen von Feldern zu geladenen Sammlungen erhöht den Speicherverbrauch.

• Es gibt eine Höchstgrenze für die Anzahl der Felder pro Sammlung. Für Details, siehe Milvus Limits.

• Feldnamen müssen unter statischen Feldern eindeutig sein.

• Sie können kein $meta Feld hinzufügen, um die dynamische Feldfunktionalität für Sammlungen zu aktivieren, die ursprünglich nicht mit enable_dynamic_field=True erstellt wurden.

Voraussetzungen

Diese Anleitung setzt voraus, dass Sie Folgendes haben

• Eine laufende Milvus-Instanz

• Milvus SDK installiert

• Eine bestehende Sammlung

Grundlegende Verwendung

from pymilvus import MilvusClient, DataType

# Connect to your Milvus server
client = MilvusClient(
    uri="http://localhost:19530"  # Replace with your Milvus server URI
)

import io.milvus.v2.client.MilvusClientV2;
import io.milvus.v2.client.ConnectConfig;

ConnectConfig config = ConnectConfig.builder()
        .uri("http://localhost:19530")
        .build();
MilvusClientV2 client = new MilvusClientV2(config);

import { MilvusClient } from '@zilliz/milvus2-sdk-node';

const milvusClient = new MilvusClient({
    address: 'localhost:19530'
});

// go

# restful
export CLUSTER_ENDPOINT="localhost:19530"

Szenario 1: Schnelles Hinzufügen von löschbaren Feldern

Der einfachste Weg, Ihre Sammlung zu erweitern, ist das Hinzufügen von löschbaren Feldern. Dies ist ideal, wenn Sie schnell neue Attribute zu Ihren Daten hinzufügen möchten.

# Add a nullable field to an existing collection
# This operation:
# - Returns almost immediately (non-blocking)
# - Makes the field available for use with minimal delay
# - Sets NULL for all existing entities
client.add_collection_field(
    collection_name="product_catalog",
    field_name="created_timestamp",  # Name of the new field to add
    data_type=DataType.INT64,        # Data type must be a scalar type
    nullable=True                    # Must be True for added fields
    # Allows NULL values for existing entities
)

import io.milvus.v2.service.collection.request.AddCollectionFieldReq;

client.addCollectionField(AddCollectionFieldReq.builder()
        .collectionName("product_catalog")
        .fieldName("created_timestamp")
        .dataType(DataType.Int64)
        .isNullable(true)
        .build());

await client.addCollectionField({
    collection_name: 'product_catalog',
    field: {
        name: 'created_timestamp',
        dataType: 'Int64',
        nullable: true
     }
});

// go

# restful
curl -X POST "http://localhost:19530/v2/vectordb/collections/fields/add" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "collectionName": "product_catalog",
    "schema": {
      "fieldName": "created_timestamp",
      "dataType": "Int64",
      "nullable": true
    }
  }'

Erwartetes Verhalten:

• Vorhandene Entitäten werden NULL für das neue Feld haben

• Neue Entitäten können entweder NULL oder aktuelle Werte haben

• Feldverfügbarkeit erfolgt fast sofort mit minimaler Verzögerung aufgrund der internen Schemasynchronisation

• Sofort nach der kurzen Synchronisationszeitabfragbar

# Example query result
{
    'id': 1, 
    'created_timestamp': None  # New field shows NULL for existing entities
}

// java

// nodejs
{
    'id': 1, 
    'created_timestamp': None  # New field shows NULL for existing entities
}

// go

# restful
{
  "code": 0,
  "data": {},
  "cost": 0
}

Szenario 2: Hinzufügen von Feldern mit Standardwerten

Wenn Sie möchten, dass vorhandene Entitäten einen sinnvollen Anfangswert anstelle von NULL haben, geben Sie Standardwerte an.

# Add a field with default value
# This operation:
# - Sets the default value for all existing entities
# - Makes the field available with minimal delay
# - Maintains data consistency with the default value
client.add_collection_field(
    collection_name="product_catalog",
    field_name="priority_level",     # Name of the new field
    data_type=DataType.VARCHAR,      # String type field
    max_length=20,                   # Maximum string length
    nullable=True,                   # Required for added fields
    default_value="standard"         # Value assigned to existing entities
    # Also used for new entities if no value provided
)

client.addCollectionField(AddCollectionFieldReq.builder()
        .collectionName("product_catalog")
        .fieldName("priority_level")
        .dataType(DataType.VarChar)
        .maxLength(20)
        .isNullable(true)
        .build());

await client.addCollectionField({
    collection_name: 'product_catalog',
    field: {
        name: 'priority_level',
        dataType: 'VarChar',
        nullable: true,
        default_value: 'standard',
     }
});

// go

# restful
curl -X POST "http://localhost:19530/v2/vectordb/collections/fields/add" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "collectionName": "product_catalog",
    "schema": {
      "fieldName": "priority_level",
      "dataType": "VarChar",
      "nullable": true,
      "defaultValue": "standard",
      "elementTypeParams": {
        "max_length": "20"
      }
    }
  }'

Erwartetes Verhalten:

• Bestehende Entitäten werden den Standardwert ("standard") für das neu hinzugefügte Feld haben.

• Neue Entitäten können den Standardwert außer Kraft setzen oder ihn verwenden, wenn kein Wert angegeben wird

• Feldverfügbarkeit erfolgt fast sofort mit minimaler Verzögerung

• Sofort nach der kurzen Synchronisationszeitabfragbar

# Example query result
{
    'id': 1,
    'priority_level': 'standard'  # Shows default value for existing entities
}

// java

{
    'id': 1,
    'priority_level': 'standard'  # Shows default value for existing entities
}

// go

# restful
{
    'id': 1,
    'priority_level': 'standard'  # Shows default value for existing entities
}

FAQ

Kann ich dynamische Schemafunktionen aktivieren, indem ich ein $meta Feld hinzufüge?

Nein, Sie können nicht add_collection_field verwenden, um ein $meta Feld hinzuzufügen, um dynamische Feldfunktionen zu aktivieren. Der nachstehende Code funktioniert zum Beispiel nicht:

# ❌ This is NOT supported
client.add_collection_field(
    collection_name="existing_collection",
    field_name="$meta",
    data_type=DataType.JSON  # This operation will fail
)

// ❌ This is NOT supported
client.addCollectionField(AddCollectionFieldReq.builder()
        .collectionName("existing_collection")
        .fieldName("$meta")
        .dataType(DataType.JSON)
        .build());

// ❌ This is NOT supported
await client.addCollectionField({
    collection_name: 'product_catalog',
    field: {
        name: '$meta',
        dataType: 'JSON',
     }
});

// go

# restful
# ❌ This is NOT supported
curl -X POST "http://localhost:19530/v2/vectordb/collections/fields/add" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "collectionName": "existing_collection",
    "schema": {
      "fieldName": "$meta",
      "dataType": "JSON",
      "nullable": true
    }
  }'

So aktivieren Sie die dynamische Schemafunktionalität:

• Neue Sammlung: Setzen Sie enable_dynamic_field auf True, wenn Sie die Sammlung erstellen. Einzelheiten finden Sie unter Sammlung erstellen

• Vorhandene Sammlung: Setzen Sie die Eigenschaft auf Sammlungsebene dynamicfield.enabled auf True. Weitere Informationen finden Sie unter Ändern einer Sammlung.

Was passiert, wenn ich ein Feld mit demselben Namen wie ein dynamischer Feldschlüssel hinzufüge?

Wenn in Ihrer Sammlung ein dynamisches Feld aktiviert ist ($meta existiert), können Sie statische Felder hinzufügen, die denselben Namen wie die vorhandenen dynamischen Feldschlüssel haben. Das neue statische Feld maskiert den Schlüssel des dynamischen Feldes, aber die ursprünglichen dynamischen Daten bleiben erhalten.

Um mögliche Konflikte bei den Feldnamen zu vermeiden, sollten Sie sich den Namen des hinzuzufügenden Feldes überlegen, indem Sie auf vorhandene Felder und dynamische Feldschlüssel verweisen, bevor Sie es tatsächlich hinzufügen.

Beispielszenario:

# Original collection with dynamic field enabled
# Insert data with dynamic field keys
data = [{
    "id": 1,
    "my_vector": [0.1, 0.2, ...],
    "extra_info": "this is a dynamic field key",  # Dynamic field key as string
    "score": 99.5                                 # Another dynamic field key
}]
client.insert(collection_name="product_catalog", data=data)

# Add static field with same name as existing dynamic field key
client.add_collection_field(
    collection_name="product_catalog",
    field_name="extra_info",         # Same name as dynamic field key
    data_type=DataType.INT64,        # Data type can differ from dynamic field key
    nullable=True                    # Must be True for added fields
)

# Insert new data after adding static field
new_data = [{
    "id": 2,
    "my_vector": [0.3, 0.4, ...],
    "extra_info": 100,               # Now must use INT64 type (static field)
    "score": 88.0                    # Still a dynamic field key
}]
client.insert(collection_name="product_catalog", data=new_data)

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

Gson gson = new Gson();
JsonObject row = new JsonObject();
row.addProperty("id", 1);
row.add("my_vector", gson.toJsonTree(new float[]{0.1f, 0.2f, ...}));
row.addProperty("extra_info", "this is a dynamic field key");
row.addProperty("score", 99.5);

InsertResp insertR = client.insert(InsertReq.builder()
        .collectionName("product_catalog")
        .data(Collections.singletonList(row))
        .build());
        
client.addCollectionField(AddCollectionFieldReq.builder()
        .collectionName("product_catalog")
        .fieldName("extra_info")
        .dataType(DataType.Int64)
        .isNullable(true)
        .build());
        
JsonObject newRow = new JsonObject();
newRow.addProperty("id", 2);
newRow.add("my_vector", gson.toJsonTree(new float[]{0.3f, 0.4f, ...}));
newRow.addProperty("extra_info", 100);
newRow.addProperty("score", 88.0);

insertR = client.insert(InsertReq.builder()
        .collectionName("product_catalog")
        .data(Collections.singletonList(newRow))
        .build());

// Original collection with dynamic field enabled
// Insert data with dynamic field keys
const data = [{
    "id": 1,
    "my_vector": [0.1, 0.2, ...],
    "extra_info": "this is a dynamic field key",  // Dynamic field key as string
    "score": 99.5                                 // Another dynamic field key
}]
await client.insert({
    collection_name: "product_catalog", 
    data: data
});

// Add static field with same name as existing dynamic field key
await client.add_collection_field({
    collection_name: "product_catalog",
    field_name: "extra_info",         // Same name as dynamic field key
    data_type: DataType.INT64,        // Data type can differ from dynamic field key
    nullable: true                   // Must be True for added fields
});

// Insert new data after adding static field
const new_data = [{
    "id": 2,
    "my_vector": [0.3, 0.4, ...],
    "extra_info": 100,               # Now must use INT64 type (static field)
    "score": 88.0                    # Still a dynamic field key
}];

await client.insert({
    collection_name:"product_catalog", 
    data: new_data
});

// go

# restful
#!/bin/bash

export MILVUS_HOST="localhost:19530"
export AUTH_TOKEN="your_token_here"
export COLLECTION_NAME="product_catalog"

echo "Step 1: Insert initial data with dynamic fields..."
curl -X POST "http://${MILVUS_HOST}/v2/vectordb/entities/insert" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${AUTH_TOKEN}" \
  -d "{
    \"collectionName\": \"${COLLECTION_NAME}\",
    \"data\": [{
      \"id\": 1,
      \"my_vector\": [0.1, 0.2, 0.3, 0.4, 0.5],
      \"extra_info\": \"this is a dynamic field key\",
      \"score\": 99.5
    }]
  }"

echo -e "\n\nStep 2: Add static field with same name as dynamic field..."
curl -X POST "http://${MILVUS_HOST}/v2/vectordb/collections/fields/add" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${AUTH_TOKEN}" \
  -d "{
    \"collectionName\": \"${COLLECTION_NAME}\",
    \"schema\": {
      \"fieldName\": \"extra_info\",
      \"dataType\": \"Int64\",
      \"nullable\": true
    }
  }"

echo -e "\n\nStep 3: Insert new data after adding static field..."
curl -X POST "http://${MILVUS_HOST}/v2/vectordb/entities/insert" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${AUTH_TOKEN}" \
  -d "{
    \"collectionName\": \"${COLLECTION_NAME}\",
    \"data\": [{
      \"id\": 2,
      \"my_vector\": [0.3, 0.4, 0.5, 0.6, 0.7],
      \"extra_info\": 100,
      \"score\": 88.0
    }]
  }"

Erwartetes Verhalten:

• Vorhandene Entitäten werden NULL für das neue statische Feld haben extra_info

• Neue Entitäten müssen den Datentyp des statischen Feldes verwenden (INT64)

• Dieursprünglichen Schlüsselwerte des dynamischen Feldes bleiben erhalten und sind über die Syntax $meta zugänglich.

• Das statische Feld maskiert den Schlüssel des dynamischen Feldes in normalen Abfragen.

Zugriff auf sowohl statische als auch dynamische Werte:

# 1. Query static field only (dynamic field key is masked)
results = client.query(
    collection_name="product_catalog",
    filter="id == 1",
    output_fields=["extra_info"]
)
# Returns: {"id": 1, "extra_info": None}  # NULL for existing entity

# 2. Query both static and original dynamic values
results = client.query(
    collection_name="product_catalog", 
    filter="id == 1",
    output_fields=["extra_info", "$meta['extra_info']"]
)
# Returns: {
#     "id": 1,
#     "extra_info": None,                           # Static field value (NULL)
#     "$meta['extra_info']": "this is a dynamic field key"  # Original dynamic value
# }

# 3. Query new entity with static field value
results = client.query(
    collection_name="product_catalog",
    filter="id == 2", 
    output_fields=["extra_info"]
)
# Returns: {"id": 2, "extra_info": 100}  # Static field value

// java

// 1. Query static field only (dynamic field key is masked)
let results = client.query({
    collection_name: "product_catalog",
    filter: "id == 1",
    output_fields: ["extra_info"]
})
// Returns: {"id": 1, "extra_info": None}  # NULL for existing entity

// 2. Query both static and original dynamic values
results = client.query({
    collection_name:"product_catalog", 
    filter: "id == 1",
    output_fields: ["extra_info", "$meta['extra_info']"]
});
// Returns: {
//     "id": 1,
//     "extra_info": None,                           # Static field value (NULL)
//     "$meta['extra_info']": "this is a dynamic field key"  # Original dynamic value
// }

// 3. Query new entity with static field value
results = client.query({
    collection_name: "product_catalog",
    filter: "id == 2", 
    output_fields: ["extra_info"]
})
// Returns: {"id": 2, "extra_info": 100}  # Static field value

// go

# restful
#!/bin/bash

export MILVUS_HOST="localhost:19530"
export AUTH_TOKEN="your_token_here"
export COLLECTION_NAME="product_catalog"

echo "Query 1: Static field only (dynamic field masked)..."
curl -X POST "http://${MILVUS_HOST}/v2/vectordb/entities/query" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${AUTH_TOKEN}" \
  -d "{
    \"collectionName\": \"${COLLECTION_NAME}\",
    \"filter\": \"id == 1\",
    \"outputFields\": [\"extra_info\"]
  }"

echo -e "\n\nQuery 2: Both static and original dynamic values..."
curl -X POST "http://${MILVUS_HOST}/v2/vectordb/entities/query" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${AUTH_TOKEN}" \
  -d "{
    \"collectionName\": \"${COLLECTION_NAME}\",
    \"filter\": \"id == 1\",
    \"outputFields\": [\"extra_info\", \"\$meta['extra_info']\"]
  }"

echo -e "\n\nQuery 3: New entity with static field value..."
curl -X POST "http://${MILVUS_HOST}/v2/vectordb/entities/query" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${AUTH_TOKEN}" \
  -d "{
    \"collectionName\": \"${COLLECTION_NAME}\",
    \"filter\": \"id == 2\",
    \"outputFields\": [\"extra_info\"]
  }"

Wie lange dauert es, bis ein neues Feld verfügbar ist?

Hinzugefügte Felder werden fast sofort verfügbar, aber es kann eine kurze Verzögerung aufgrund der internen Schemaänderung geben, die im Milvus-Cluster übertragen wird. Durch diese Synchronisierung wird sichergestellt, dass alle Knoten von der Schemaaktualisierung Kenntnis haben, bevor Abfragen mit dem neuen Feld verarbeitet werden.