构建 Paimon Global Index - 数据湖构建

Global Index（全局索引）可减少查询 Paimon 表时的数据扫描量，并支持向量搜索和混合检索。本文介绍如何为新建或已有的 Paimon Append 表开启 Global Index，并查看索引构建情况。

功能介绍

Global Index 支持以下索引类型：

B-tree 索引：加速等值查询和范围查询，例如查询指定时间范围内的数据。
向量索引：根据图片、文本等数据的向量查找相似内容。
Bitmap 索引：加速标量字段的等值过滤，例如查询 time_of_day = 'night' 的记录。
多值索引：加速数组元素包含条件的过滤，例如查询 detected_objects 中包含指定对象类别的记录。
全文索引：用于在文本字段中执行全文检索。具体操作，请参见DLF Paimon 表全文检索。

Global Index 还支持混合检索，例如先使用 B-tree 索引筛选数据，再通过 IVF-PQ 向量索引进行向量召回。

前提条件

表类型：使用由 DLF 管理的 Paimon Append 表。具体操作，请参见Paimon Append 表和Paimon Table。
表配置：创建 Paimon 表时已开启行级追踪和数据演化，即将 row-tracking.enabled 和 data-evolution.enabled 设置为 true。具体操作，请参见数据演化与行级追踪。已有表不满足要求时，需要重新建表并迁移数据。
向量字段：向量字段必须为 ARRAY<FLOAT>，同一字段中的向量维度必须一致。

开启 Global Index

创建新表并开启 Global Index

本节介绍如何在同一张 Paimon 表中创建 B-tree、Bitmap、多值和 IVF-PQ 向量索引。

以下 SQL 中的 my_db 和 my_table 为示例名称，请替换为实际的数据库名和表名。

本示例使用自动驾驶图片检索场景，将图片、结构化信息和图片向量存储在同一张 Paimon 表中：

使用 BLOB 保存 JPEG 图片原始数据。
为 weather 创建 B-tree 索引。
为 time_of_day 创建 Bitmap 索引。
为 detected_objects 创建多值索引。
为 image_embedding 创建 IVF-PQ 向量索引。
图片向量维度为 768。

CREATE TABLE my_db.my_table (
    image_id STRING COMMENT '图片 ID',
    video_id STRING COMMENT '图片所属视频 ID',
    event_time TIMESTAMP(3) COMMENT '驾驶场景采集时间',
    file_name STRING COMMENT '原始 JPEG 文件名',
    weather STRING COMMENT '天气，例如 clear、rainy、overcast',
    time_of_day STRING COMMENT '时间段，例如 daytime、night',
    road_scene STRING COMMENT '道路场景，例如 city_street、highway',
    detected_objects ARRAY<STRING> COMMENT '检测到的对象类别',
    file_size BIGINT COMMENT '图片大小，单位为字节',
    image BLOB COMMENT 'JPEG 图片原始数据',
    image_embedding ARRAY<FLOAT> COMMENT '图片向量'
)
WITH (
    'write-only' = 'true',
    'row-tracking.enabled' = 'true',
    'data-evolution.enabled' = 'true',
    'reassign' = 'true',
    'blob-field' = 'image',
    'morax.btree-index.enabled' = 'true',
    'global-index.btree.index-column' = 'weather',
    'morax.bitmap-index.enabled' = 'true',
    'global-index.bitmap.index-columns' = 'time_of_day',
    'morax.multivalue-index.enabled' = 'true',
    'global-index.multivalue.index-columns' = 'detected_objects',
    'morax.paimon-vector-index.enabled' = 'true',
    'global-index.ivf-pq.index-columns' = 'image_embedding',
    'ivf-pq.dimension' = '768'
);

说明

数据写入后，DLF 会异步为存量数据和新增数据构建索引。索引构建完成后，查询引擎才能使用对应索引。

参数说明

表配置

参数	是否必选	说明	示例值
`write-only`	是	必须设置为 `true`，由 DLF 执行表维护和索引构建任务。	`true`
`row-tracking.enabled`	是	必须设置为 `true`，开启行级追踪。	`true`
`data-evolution.enabled`	是	必须设置为 `true`，开启数据演化。	`true`
`reassign`	否	允许在整理数据时重新分配行号并维护索引。	`true`
`blob-field`	否	使用 BLOB 字段时，指定保存图片等大对象数据的字段。	`image`

B-tree 索引

参数	说明	示例值
`morax.btree-index.enabled`	开启 B-tree 索引的自动构建。	`true`
`global-index.btree.index-column`	指定建立 B-tree 索引的字段。	`weather`

Bitmap 索引

参数	说明	示例值
`morax.bitmap-index.enabled`	开启 Bitmap 索引的自动构建。	`true`
`global-index.bitmap.index-columns`	指定建立 Bitmap 索引的字段。多个字段用英文逗号分隔，每个字段分别构建索引。	`time_of_day`

多值索引

参数	说明	示例值
`morax.multivalue-index.enabled`	开启多值索引的自动构建。	`true`
`global-index.multivalue.index-columns`	指定建立多值索引的数组字段。多个字段用英文逗号分隔，每个字段分别构建索引。	`detected_objects`

IVF-PQ 向量索引

参数	说明	示例值
`morax.paimon-vector-index.enabled`	开启 Paimon 向量索引的自动构建。	`true`
`global-index.ivf-pq.index-columns`	指定建立 IVF-PQ 索引的向量字段。	`image_embedding`
`ivf-pq.dimension`	指定向量维度，必须与实际数据一致。	`768`

以上仅说明建表示例中使用的参数。IVF-PQ 构建参数、查询参数及调优方法，请参见IVF-PQ 向量索引构建和查询参数。

为已有表开启 Global Index

如果已有由 DLF 管理的 Paimon Append 表已开启行级追踪（row-tracking.enabled）和数据演化（data-evolution.enabled），可以通过 ALTER TABLE 为表中的现有字段开启 Global Index。以下示例分别为 weather 创建 B-tree 索引、为 time_of_day 创建 Bitmap 索引、为 detected_objects 创建多值索引，以及为 image_embedding 创建 IVF-PQ 向量索引：

ALTER TABLE my_db.my_table SET (
    'morax.btree-index.enabled' = 'true',
    'global-index.btree.index-column' = 'weather',
    'morax.bitmap-index.enabled' = 'true',
    'global-index.bitmap.index-columns' = 'time_of_day',
    'morax.multivalue-index.enabled' = 'true',
    'global-index.multivalue.index-columns' = 'detected_objects',
    'morax.paimon-vector-index.enabled' = 'true',
    'global-index.ivf-pq.index-columns' = 'image_embedding',
    'ivf-pq.dimension' = '768'
);

设置完成后，DLF 会逐步为存量数据和新增数据构建索引。

后续可以按照查看索引构建情况确认索引是否就绪，并根据后续步骤选择计算引擎执行查询。

查看索引构建情况

Global Index 采用异步构建方式。创建表、开启或修改索引后，可以根据使用的计算引擎查询 Paimon table_indexes 系统表，查看已经提交的索引文件。

说明

将示例中的 <catalog_name>、my_db 和 my_table 分别替换为实际的 Paimon Catalog 名称、数据库名和表名。

DLF 数据探查

执行 SQL 前，在 DLF 数据探查中选择实际使用的 Paimon Catalog，并将 my_db 和 my_table 替换为实际的数据库名和表名。

SELECT
    index_type,
    index_field_name,
    row_count
FROM `my_db`.`my_table$table_indexes`
WHERE index_type IN ('btree', 'ivf-pq', 'bitmap', 'multivalue')
ORDER BY index_type, index_field_name;

Spark

执行 SQL 前，在 SparkSQL 编辑器中选择实际使用的 Paimon Catalog。

SELECT
    index_type,
    index_field_name,
    COUNT(*) AS index_file_count,
    SUM(row_count) AS indexed_rows
FROM `my_db`.`my_table$table_indexes`
WHERE index_type IN ('btree', 'ivf-pq', 'bitmap', 'multivalue')
GROUP BY index_type, index_field_name;

Flink

SELECT
    ti.`index_type`,
    ti.`index_field_name`,
    COUNT(*) AS index_file_count,
    SUM(ti.`row_count`) AS indexed_rows
FROM `<catalog_name>`.`my_db`.`my_table$table_indexes` AS ti
WHERE ti.`index_type` IN ('btree', 'ivf-pq', 'bitmap', 'multivalue')
GROUP BY ti.`index_type`, ti.`index_field_name`;

StarRocks

SELECT
    index_type,
    index_field_name,
    COUNT(*) AS index_file_count,
    SUM(row_count) AS indexed_rows
FROM `<catalog_name>`.`my_db`.`my_table$table_indexes`
WHERE index_type IN ('btree', 'ivf-pq', 'bitmap', 'multivalue')
GROUP BY index_type, index_field_name
ORDER BY index_type, index_field_name;

根据查询结果判断：

返回 btree、weather：B-tree 索引已经生成并提交。
返回 ivf-pq、image_embedding：IVF-PQ 索引已经生成并提交。
返回 bitmap、time_of_day：该字段的 Bitmap 索引已经生成并提交。
返回 multivalue、detected_objects：该字段的多值索引已经生成并提交。
没有返回对应记录：索引尚未生成或尚未提交，请稍后重新查询。
表持续写入数据时，可以观察 indexed_rows 是否继续增加，判断新增数据是否已进入索引。

table_indexes 仅展示已经提交的索引文件，不展示正在运行的构建任务进度。

后续步骤

索引构建完成后，可以根据使用的计算引擎查询 Paimon 表：

DLF 数据探查：请参见使用 DLF 数据探查体验 Paimon Global Index。
Flink：请参见使用 Flink 查询 Paimon Global Index。
Spark：请参见使用 Spark 查询 Paimon Global Index。
StarRocks：请参见使用 StarRocks 查询 Paimon Global Index。