Milvus
Zilliz
Estrela44.3KMarcar uma demonstraçãoComeçar
Home
  • Home
  • Docs

  • Guia do utilizador

  • Esquema e campos de dados

  • Adicionar campos a uma coleção existente

Adicionar campos a uma coleção existenteCompatible with Milvus 2.6.x

Milvus permite-lhe adicionar dinamicamente novos campos a colecções existentes, facilitando a evolução do seu esquema de dados à medida que as necessidades da sua aplicação mudam. Este guia mostra como adicionar campos em diferentes cenários usando exemplos práticos.

Considerações

Antes de adicionar campos à sua coleção, tenha em conta estes pontos importantes:

  • Pode adicionar campos escalares (INT64, VARCHAR, FLOAT, DOUBLE, etc.). Os campos vectoriais não podem ser adicionados a colecções existentes.

  • Novos campos devem ser anuláveis (nullable=True) para acomodar entidades existentes que não têm valores para o novo campo.

  • A adição de campos a colecções carregadas aumenta a utilização de memória.

  • Há um limite máximo para o total de campos por coleção. Para obter detalhes, consulte Limites do Milvus.

  • Os nomes dos campos devem ser exclusivos entre os campos estáticos.

  • Não é possível adicionar um campo $meta para ativar a funcionalidade de campo dinâmico para coleções que não foram originalmente criadas com enable_dynamic_field=True.

Pré-requisitos

Este guia pressupõe que você tenha:

  • Uma instância do Milvus em execução

  • Milvus SDK instalado

  • Uma coleção existente

Consulte o nosso Criar coleção para a criação de colecções e operações básicas.

Utilização básica

Python Java NodeJS Go cURL
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"

Cenário 1: adicionar rapidamente campos anuláveis

A maneira mais simples de estender sua coleção é adicionando campos anuláveis. Isso é perfeito quando você precisa adicionar rapidamente novos atributos aos seus dados.

Python Java NodeJS Go cURL
# 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
    }
  }'

Comportamento esperado:

  • Entidades existentes terão NULL para o novo campo

  • Novas entidades podem ter NULL ou valores reais

  • A disponibilidade do campo ocorre quase imediatamente com um atraso mínimo devido à sincronização do esquema interno

  • Pode ser consultado imediatamente após o breve período de sincronização

Python Java NodeJS Go cURL
# 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
}

Cenário 2: Adicionar campos com valores padrão

Quando quiser que as entidades existentes tenham um valor inicial significativo em vez de NULL, especifique valores predefinidos.

Python Java NodeJS Go cURL
# 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"
      }
    }
  }'

Comportamento esperado:

  • As entidades existentes terão o valor padrão ("standard") para o campo recém-adicionado

  • Novas entidades podem substituir o valor padrão ou usá-lo se nenhum valor for fornecido

  • A disponibilidade do campo ocorre quase imediatamente com um atraso mínimo

  • Pode ser consultado imediatamente após o breve período de sincronização

Python Java NodeJS Go cURL
# 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
}

PERGUNTAS FREQUENTES

Posso ativar a funcionalidade de esquema dinâmico adicionando um campo $meta?

Não, você não pode usar add_collection_field para adicionar um campo $meta para habilitar a funcionalidade de campo dinâmico. Por exemplo, o código abaixo não funcionará:

Python Java NodeJS Go cURL
# ❌ 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
    }
  }'

Para ativar a funcionalidade de esquema dinâmico:

  • Nova coleção: Defina enable_dynamic_field como True ao criar a coleção. Para obter detalhes, consulte Criar coleção

  • Coleção existente: Defina a propriedade de nível de coleção dynamicfield.enabled como True. Para obter detalhes, consulte Modificar coleção.

O que acontece quando eu adiciono um campo com o mesmo nome de uma chave de campo dinâmico?

Quando a sua coleção tem o campo dinâmico ativado ($meta existe), pode adicionar campos estáticos com o mesmo nome que as chaves de campo dinâmico existentes. O novo campo estático irá mascarar a chave do campo dinâmico, mas os dados dinâmicos originais são preservados.

Para evitar possíveis conflitos nos nomes dos campos, considere o nome do campo a adicionar, consultando os campos existentes e as chaves de campo dinâmicas antes de o adicionar efetivamente.

Exemplo de cenário:

Python Java NodeJS Go cURL
# 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
    }]
  }"

Comportamento esperado:

  • As entidades existentes terão NULL para o novo campo estático extra_info

  • Novas entidades devem usar o tipo de dados do campo estático (INT64)

  • Os valores originais da chave do campo dinâmico são preservados e acessíveis através da sintaxe $meta

  • O campo estático mascara a chave do campo dinâmico em consultas normais

Acesso a valores estáticos e dinâmicos:

Python Java NodeJS Go cURL
# 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\"]
  }"

Quanto tempo leva para um novo campo ficar disponível?

Os campos adicionados ficam disponíveis quase imediatamente, mas pode haver um breve atraso devido à transmissão interna de alterações de esquema no cluster Milvus. Esta sincronização garante que todos os nós estão cientes da atualização do esquema antes de processar as consultas que envolvem o novo campo.

Tabela de conteúdos

Try Managed Milvus for Free

Zilliz Cloud is hassle-free, powered by Milvus and 10x faster.

Get Started
Feedback

Esta página foi útil?