关于 Milvus
开始使用
概念
用户指南
- 数据库
- Collections
- Schema与数据字段
  - Schema详解
  - 主字段与自动标识符
  - 稠密向量
  - 二进制向量
  - 稀疏向量
  - VarChar 字段
  - 文本框
  - 数字字段
  - JSON 字段
  - 数组字段
  - StructArray
  - 几何领域
  - TIMESTAMPTZ 字段
  - Dynamic Field
  - 可为空字段
  - 默认值
  - 分析仪
  - 修改Collection字段
  - 修改Collection Schema
  - 修改外部Collection Schema
  - 最佳实践
- 插入与删除
- 索引
- 搜索
- 函数与模型推断
- 存储优化
- 快照
数据导入
AI 工具
管理指南
工具
集成
教程
常见问题解答
API Reference

首页
文档
用户指南
Schema与数据字段
可为空字段

可为空字段

Milvus 支持可为空字段，允许字段值为空或显式设置为 NULL。可为空性在 Schema 级别定义，并在数据摄入、索引、搜索和查询操作中始终如一地应用。

在以下情况下使用可空字段：

从允许缺失值的外部系统摄取数据时。
部分元数据为可选，或仅在数据集的部分数据中可用。
向量Embeddings是异步生成的，并在稍后插入。

限制

允许 NULL 值的向量字段不支持 `IS NULL ` 或 `IS NOT NULL ` 过滤表达式。您无法根据向量字段值是否为 NULL 来显式过滤实体。
从 Milvus 3.0.0 开始，父级StructArray字段可以是可为空的。请在父级 StructArray 字段上设置 `nullable=True `，而非在单个子字段上设置。NULL 适用于整个 StructArray 字段，而非单个 Struct 元素，且 Milvus 会在内部将父级字段的可为空性传播至其子字段。添加到现有 Collection 中的 StructArray 字段必须为可空，以便现有实体能够为该新字段返回 NULL。详情请参阅《StructArray 限制》。
可空属性在字段创建时定义，此后无法修改。您无法对现有字段启用或禁用可空性。
标记为可空的字段不能用作Partition Key。Partition Key字段必须始终包含有效的、非空的值。有关更多信息，请参阅《使用Partition Key》。

什么是可空字段？

在 Milvus 中，字段是否允许存储 NULL 值由一个名为 `nullable` 的 Schema 级字段属性控制。

当字段被定义为nullable=True 时，Milvus 允许在数据摄入过程中该字段值缺失。实际上，Milvus 将以下两种输入视为等效，并将字段值存储为 NULL：

输入实体中省略了该字段。
该字段被显式设置为 NULL（例如，在 Python 中使用 `None `）。

如果字段未定义为可为空（默认行为），则每个实体都必须为该字段提供有效值。省略该字段或显式赋值为 NULL 都会导致插入或导入操作失败。

Schema 模式中的标量字段和向量字段均支持 nullable 属性。从 Milvus 3.0.0 开始，父级 StructArray 字段也支持该属性。请勿单独将 Struct 子字段配置为可为空；应在 StructArray 父级上定义可为空性，Milvus 会内部将该设置传播到其子字段。

可空性决定字段值是否可以为空；它并不定义字段为空时使用的具体值。

如果配置了可空字段但未指定默认值，则省略该字段时，系统将存储 NULL 值。
如果配置了默认值，Milvus 可能会存储该默认值。有关详细信息，请参阅“默认值”。

在Collection Schema中定义可空字段

要使用可空字段，您必须在定义 Collection Schema 时启用 nullable 属性。

在此示例中，Collection Schema定义了一个名为embedding 的向量字段，其nullable=True 。这允许Collection中的实体在数据摄入过程中省略向量值，或将其显式设置为NULL。

Python Java NodeJS Go cURL

from pymilvus import MilvusClient, DataType

client = MilvusClient(
    uri="http://localhost:19530",
    token="root:Milvus"
)

# Define schema fields
schema = client.create_schema()
schema.add_field("id", DataType.INT64, is_primary=True)  # Primary field
schema.add_field(
    field_name="embedding",
    datatype=DataType.FLOAT_VECTOR,
    dim=4,
    nullable=True,  # Enable the nullable attribute; defaults to False
)

client.create_collection(
    collection_name="my_collection",
    schema=schema,
)

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

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

CreateCollectionReq.CollectionSchema schema = CreateCollectionReq.CollectionSchema.builder()
        .build();

schema.addField(AddFieldReq.builder()
        .fieldName("id")
        .dataType(DataType.Int64)
        .isPrimaryKey(true)
        .build());
schema.addField(AddFieldReq.builder()
        .fieldName("embedding")
        .dataType(DataType.FloatVector)
        .dimension(4)
        .isNullable(true)
        .build());

client.createCollection(CreateCollectionReq.builder()
        .collectionName("my_collection")
        .collectionSchema(schema)
        .build());

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

const client = new MilvusClient({
  address: "http://localhost:19530",
  token: "root:Milvus",
});

await client.createCollection({
  collection_name: "my_collection",
  fields: [
    {
      name: "id",
      data_type: DataType.Int64,
      is_primary_key: true,
      autoID: false,
    },
    {
      name: "embedding",
      data_type: DataType.FloatVector,
      dim: 4,
      nullable: true,
    },
  ],
});

import (
    "context"
    "fmt"

    "github.com/milvus-io/milvus/client/v2/entity"
    "github.com/milvus-io/milvus/client/v2/milvusclient"
)

ctx, cancel := context.WithCancel(context.Background())
defer cancel()

client, err := milvusclient.New(ctx, &milvusclient.ClientConfig{
    Address: "localhost:19530",
})
if err != nil {
    fmt.Println(err.Error())
    // handle error
}
defer client.Close(ctx)

schema := entity.NewSchema()
schema.WithField(entity.NewField().
    WithName("id").
    WithDataType(entity.FieldTypeInt64).
    WithIsPrimaryKey(true),
).WithField(entity.NewField().
    WithName("embedding").
    WithDataType(entity.FieldTypeFloatVector).
    WithDim(4).
    WithNullable(true),
)

err = client.CreateCollection(ctx,
    milvusclient.NewCreateCollectionOption("my_collection", schema))
if err != nil {
    fmt.Println(err.Error())
    // handle error
}

export TOKEN="root:Milvus"
export CLUSTER_ENDPOINT="http://localhost:19530"

export pkField='{
  "fieldName": "id",
  "dataType": "Int64",
  "isPrimary": true
}'

export embeddingField='{
  "fieldName": "embedding",
  "dataType": "FloatVector",
  "typeParams": {"dim": "4"},
  "nullable": true
}'

curl --request POST \
  --url "${CLUSTER_ENDPOINT}/v2/vectordb/collections/create" \
  --header "Authorization: Bearer ${TOKEN}" \
  --header "Content-Type: application/json" \
  --header "Request-Timeout: 10" \
  -d "{
    \"collectionName\": \"my_collection\",
    \"schema\": {
      \"fields\": [
        $pkField,
        $embeddingField
      ]
    }
  }"

在此Schema中：

embedding 字段被显式标记为可为空。
实体在插入时可以省略embedding 字段，或将其赋值为 NULL。
是否允许 NULL 值的决定在 Collection 创建时即已确定。

为清晰起见，以下示例将重点放在可为空的向量字段（embedding ）上。定义可为空的标量字段是可选的，且无需遵循本指南的其余内容。

可选：定义可空标量字段

标量字段也可以使用相同的 `nullable ` 属性定义为可为空，并在数据摄入过程中遵循相同的规则。例如：

Python Java NodeJS Go cURL

schema.add_field(
    field_name="age",
    datatype=DataType.INT64,
    nullable=True,
)

schema.addField(AddFieldReq.builder()
        .fieldName("age")
        .dataType(DataType.Int64)
        .isNullable(true)
        .build());

// Add to the fields array when calling createCollection:
// { name: "age", data_type: DataType.Int64, nullable: true },

schema.WithField(entity.NewField().
    WithName("age").
    WithDataType(entity.FieldTypeInt64).
    WithNullable(true),
)

# Add another field object to the schema "fields" array, for example:
# { "fieldName": "age", "dataType": "Int64", "nullable": true }

存在缺失值或 NULL 值时的插入行为

一旦在 Schema 中将字段定义为可空，Milvus 便允许在数据摄入过程中该字段值为缺失或显式设置为 NULL。

下面的示例将三个实体插入到“在Schema中定义可为空字段”中创建的Collection中，演示了这些不同情况。

Python Java NodeJS Go cURL

data = [
    {
        "id": 1,
        "embedding": [0.1, 0.2, 0.3, 0.4],
    },
    {
        "id": 2,
        "embedding": None,  # Explicitly set to NULL
    },
    {
        "id": 3,  # Field omitted → stored as NULL
    },
]

client.insert(
    collection_name="my_collection",
    data=data,
)

import com.google.gson.Gson;
import com.google.gson.JsonNull;
import com.google.gson.JsonObject;
import io.milvus.v2.service.vector.request.InsertReq;

import java.util.Arrays;
import java.util.List;

Gson gson = new Gson();

JsonObject row1 = new JsonObject();
row1.addProperty("id", 1);
row1.add("embedding", gson.toJsonTree(Arrays.asList(0.1f, 0.2f, 0.3f, 0.4f)));

JsonObject row2 = new JsonObject();
row2.addProperty("id", 2);
row2.add("embedding", JsonNull.INSTANCE); // Explicitly set to NULL

JsonObject row3 = new JsonObject();
row3.addProperty("id", 3); // Field omitted; stored as NULL

List<JsonObject> data = Arrays.asList(row1, row2, row3);

client.insert(InsertReq.builder()
        .collectionName("my_collection")
        .data(data)
        .build());

const data = [
  { id: 1, embedding: [0.1, 0.2, 0.3, 0.4] },
  { id: 2, embedding: null },
  { id: 3 },
];

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

import (
    "context"
    "fmt"

    "github.com/milvus-io/milvus/client/v2/milvusclient"
)

// Assumes `client` is the Milvus client from the Go schema example above.
ctx := context.Background()

rows := []any{
    map[string]any{"id": int64(1), "embedding": []float32{0.1, 0.2, 0.3, 0.4}},
    map[string]any{"id": int64(2), "embedding": nil},
    map[string]any{"id": int64(3)},
}

_, err := client.Insert(ctx, milvusclient.NewRowBasedInsertOption("my_collection", rows...))
if err != nil {
    fmt.Println(err.Error())
}

curl --request POST \
  --url "${CLUSTER_ENDPOINT}/v2/vectordb/entities/insert" \
  --header "Authorization: Bearer ${TOKEN}" \
  --header "Content-Type: application/json" \
  --header "Request-Timeout: 10" \
  -d '{
    "collectionName": "my_collection",
    "data": [
      {"id": 1, "embedding": [0.1, 0.2, 0.3, 0.4]},
      {"id": 2, "embedding": null},
      {"id": 3}
    ]
  }'

在此示例中：

实体id = 1提供了有效的向量值。
实体id = 2将 NULL 值显式赋值给 `embedding ` 字段。
实体id = 3完全省略了 `embedding ` 字段；Milvus 将其存储为 NULL。