跳到主要内容

创建 Scalar Index

Zilliz Cloud 支持对标量字段（非向量字段）建立索引，以显著加速过滤和搜索性能，特别是在大型数据集上。

📘说明

对标量字段建立索引是可选操作，推荐您对经常在过滤条件中使用的字段建立索引。

可以索引的内容​

Zilliz Cloud 支持对以下字段类型使用 AUTOINDEX：

字段类型

描述

VARCHAR

字符串

INT8, INT32, INT64

整数

FLOAT, DOUBLE

浮点数

BOOL

布尔值

ARRAY

标量值的同质数组

JSON

Schema 定义的或 dynamic field（具有特定路径目标）

📘说明

不支持对整个 JSON 对象建立索引。您必须指定 JSON 字段内标量值的路径。更多信息请参考 JSON 类型。

定义 collection schema​

在创建索引之前，定义一个包含向量字段和标量字段的 collection。Zilliz Cloud 要求每个 collection 都有一个向量字段。

在此示例中，我们为产品目录定义一个 schema，包括标量字段、JSON 类型的 metadata 字段和必需的向量字段，并启用 dynamic field 功能：

from pymilvus import MilvusClient, DataType

client = MilvusClient(uri="YOUR_CLUSTER_ENDPOINT") # 替换为您的集群端点

# 定义支持 dynamic field 的 schema
schema = client.create_schema(
    auto_id=False,
    # highlight-next-line
    enable_dynamic_field=True # 启用 dynamic field
)

# 必需字段
schema.add_field(field_name="product_id", datatype=DataType.INT64, is_primary=True)
schema.add_field(field_name="vector", datatype=DataType.FLOAT_VECTOR, dim=5)

# 标量字段和 JSON 字段
# highlight-start
schema.add_field(field_name="price", datatype=DataType.DOUBLE)
schema.add_field(field_name="metadata", datatype=DataType.JSON, nullable=True)
# highlight-end

# 创建 collection
client.create_collection(
    collection_name="product_catalog",
    schema=schema
)
📘说明

有关如何使用 JSON 字段和 dynamic field 的更多信息，请参考 Dynamic Field

为非 JSON 字段建立索引​

您可以使用 AUTOINDEX 为任何非 JSON 标量字段创建索引。无需额外的索引参数。

index_params = client.prepare_index_params() # 准备一个空的 IndexParams 对象，无需指定任何索引参数

index_params.add_index(
    field_name="price", # 要索引的标量字段名称
    # highlight-next-line
    index_type="AUTOINDEX", # 要创建的索引类型
    index_name="price_index" # 要创建的索引名称
)

为 JSON 字段建立索引​

Zilliz Cloud 支持使用 JSON 路径索引为 JSON 字段建立索引。这允许您按 JSON 对象内的键或嵌套值进行过滤，而无需扫描整个字段。

示例 JSON 字段​

考虑一个在 schema 中定义的 metadata 字段：

{
  "metadata": {
    "category": "electronics",
    "brand": "BrandA",
    "in_stock": true,
    "tags": ["clearance", "summer_sale"],
    "string_price": "99.99"
  }
}

您可以为以下路径创建索引：

  • metadata["category"]

  • metadata["tags"]

  • metadata["string_price"] → 使用转换函数将字符串数字转换为 double

JSON 路径索引语法​

要创建 JSON 路径索引，请指定：

  • JSON 路径（json_path）：您要索引的 JSON 对象内键或嵌套字段的路径。

    • 示例：metadata["category"]

      这定义了索引引擎在 JSON 结构内查找的位置。

  • JSON 转换类型（json_cast_type）：Zilliz Cloud 在解释和索引指定路径处的值时应使用的数据类型。

# 将 category 字段作为字符串索引
index_params.add_index(
    field_name="metadata",
    # highlight-next-line
    index_type="AUTOINDEX", # 对于 JSON 路径索引必须设置为 AUTOINDEX
    index_name="category_index",
    # highlight-start
    params={
        "json_path": "metadata[\"category\"]",
        "json_cast_type": "varchar"
    }
    # highlight-end
)

# 将 tags 数组作为字符串数组索引
index_params.add_index(
    field_name="metadata",
    # highlight-next-line
    index_type="AUTOINDEX", # 对于 JSON 路径索引必须设置为 AUTOINDEX
    index_name="tags_array_index", 
    # highlight-start
    params={
        "json_path": "metadata[\"tags\"]",
        "json_cast_type": "array_varchar"
    }
    # highlight-end
)

使用 JSON 转换函数进行类型转换​

当您的 JSON 包含格式不正确的值（例如，以字符串形式存储的数字）时，您可以使用转换函数在索引期间转换值。

# 将字符串数字转换为 double 用于索引
index_params.add_index(
    field_name="metadata",
    # highlight-next-line
    index_type="AUTOINDEX", # 对于 JSON 路径索引必须设置为 AUTOINDEX
    index_name="string_to_double_index",
    # highlight-start
    params={
        "json_path": "metadata[\"string_price\"]",
        "json_cast_type": "double", # 必须是转换函数的输出类型
        "json_cast_function": "STRING_TO_DOUBLE" # 不区分大小写
    }
    # highlight-end
)
📘说明

  • 如果类型转换失败（例如值 "not_a_number" 无法转换为数字），该值将被跳过且不会被索引。

  • 有关转换函数参数的详细信息，请参考 JSON 类型。

为 dynamic field 中的键建立索引​

如果您启用了 dynamic field，可以为未在 schema 中明确定义的特定标量键建立索引。这些键存储在隐藏的 JSON 字段中，在索引目的上被视为与其他标量字段相同。

📘说明

有关 dynamic field 的详细信息，请参考 Dynamic Field。

# 为动态键建立索引（例如，已插入但未在 schema 中定义）
index_params.add_index(
    field_name="overview",  # dynamic field 中的键名
    index_type="AUTOINDEX",
    index_name="overview_index",
    # highlight-start
    params={
        "json_path": "overview", # dynamic field 中的键名
        "json_cast_type": "varchar" # Zilliz Cloud 在索引值时使用的数据类型
    }
    # highlight-end
)

将索引参数应用到 collection​

定义索引参数后，您可以使用 create_index() 将它们应用到 collection：

client.create_index(
    collection_name="product_catalog",
    index_params=index_params
)

常见问题​

什么时候应该为标量字段创建索引？​

创建标量索引是可选的——但当字段经常在过滤条件中使用时强烈建议创建。没有索引时，Zilliz Cloud 在过滤期间会执行全 collection 扫描，这可能会显著影响大型数据集的性能。为这些字段建立索引可以使用标量索引实现更快的过滤。

我可以在同一个 JSON 字段上创建多个索引吗？​

是的，您可以为同一个 JSON 字段内的不同路径建立索引，但每个唯一路径只允许一个索引。

为特定 JSON 路径建立索引时，如果某些行中不存在该 JSON 路径会怎样？​

这些行在索引期间会被静默跳过。不会引发错误。

为 JSON 字段建立索引时，转换函数失败会发生什么？​

Zilliz Cloud 会静默忽略无法转换的值，例如无法解析为数字的字符串。

我可以索引特定的数组元素吗？​

是的，您可以索引特定的数组位置，如 metadata["tags"][0] 用于数组的第一个元素。

如果 JSON 字段中的某些值无法转换为索引类型会怎样？​

它们会在索引期间被静默跳过，并从依赖索引的查询结果中排除。如果您的数据有不一致的类型，这可能会导致部分结果。

我可以用不同类型多次索引同一个 JSON 字段路径吗？​

不可以，单个 JSON 路径或 dynamic field 键一次只支持一个索引。您必须为索引选择一个 json_cast_type。

在哪里可以找到有关索引 JSON 字段或 dynamic field 的完整详细信息？​

请参考 JSON 类型 和 Dynamic Field 章节获取更多信息。