# Lance on Aura DDL语法说明 #### 使用限制 Lance表不支持创建partition和bucket列。 #### 创建Lance表 用户使用CREATE TABLE语法创建Lance表，需指定STORE AS Lance。具体语法，请参见[CREATE TABLE](https://support.huaweicloud.com/sqlref-aura-aidatalake/aidatalake_061_0219.html)。用户创建的Lance表元数据存储于LakeFormation中，主要包含表名、表路径、表当前版本号和表参数，Lance表实际数据文件存储于OBS桶中。 示例： ``` CREATE TABLE lance_tbl( col1 int, col2 array, col3 bytea ) TABLEPROPERTIES ( 'enable.blob.col3'='true', 'arrow.fixed-size-list.col2' = '128' ) STORE AS Lance; ``` TABLEPROPERTIES支持配置的表参数： 表1 | 参数 | 类型 | 说明 | |:---|:---|:---| | enable.blob.col_name | 布尔值 | 指定col_name列为BLOB列，仅支持bytea类型列，Lance中对于BLOB的介绍请参见：[Lance BLOB格式介绍](https://lance.org/guide/blob/) 。 | | arrow.fixed-size-list.col_name | 整型值 | 范围为1\~2147483647，指定col_name使用Arrow中的FixedSizeList存储为定长向量，仅支持浮点数类型的一维数组。 | | max.rows.per.file | 整型值 | 范围为1\~9223372036854775807，默认值为1048576，指定单个文件写入最大行数。 | | max.bytes.per.file | 整型值 | 范围为1\~9223372036854775807，默认值为90GiB，指定单个文件写入最大字节数。 | | lance.encoding.compression | 整型值 | 字符串，可指定为zstd、lz4、fsst三种压缩算法，其中zstd支持配置压缩等级，取值范围为0-22，如果未指定压缩等级则默认压缩等级为3，默认不启用压缩。三种压缩方式的介绍，请参见[Lance支持压缩方式介绍](https://lance.org/format/file/encoding/?h=compression#compression-configuration)。 | | lance.batch.readahead | 整型值 | 范围为1\~9223372036854775807，默认值为4，指定预读的Batch数目。 | | lance.fragment.readahead | 整型值 | 范围为1\~9223372036854775807，默认值为32，指定预读的Fragment数目。 | | lance.storage.version | 字符串 | 可取值为0.1、2.0、2.1、2.2，指定存储的Lance格式版本，默认值为2.2。 | | lance.block.size | 整型值 | 范围为1\~34359738368，指定向存储层发起单次I/O请求的最小字节数，默认值为1MB。 | | metadata.cache.size | 整型值 | 范围为1\~34359738368，指定元数据缓存大小字节数，默认值为1GiB。 | | io.buffer.size | 整型值 | 范围为1\~34359738368，指定I/O缓冲区大小字节数，默认值为2GiB。 | | index.cache.size | 整型值 | 范围为1\~34359738368，指定索引缓存大小字节数，默认值为6GiB。 | #### 清空Lance表 通过TRUNCATE TABLE语法清空表中的数据。具体语法，请参见[TRUNCATE](https://support.huaweicloud.com/sqlref-aura-aidatalake/aidatalake_061_0229.html)。 示例： ``` TRUNCATE TABLE lance_tbl; ``` #### 清理Lance表历史版本 通过VACUUM TABLE语法清理Lance表的历史版本及不再被引用的数据文件、事务文件、索引文件，回收OBS存储空间。Lance表在执行INSERT/UPDATE/DELETE/INSERT OVERWRITE/ALTER INDEX OPTIMIZE等操作后会产生新版本，旧版本及其引用的文件会持续保留，可通过VACUUM TABLE清理。 支持的清理选项： - older_than_seconds：整型值，范围为1\~31536000，仅清理产生时间超过该秒数的旧版本。省略时Lance内核使用默认值（14 天）。 - delete_rate_limit：整型值，范围为1\~2147483647，删除操作的限速（次/秒），用于避免触发OBS限流。 VACUUM TABLE返回一行清理统计结果，包含6个字段： 表2字段说明 | 字段 | 类型 | 说明 | |:---|:---|:---| | bytes_removed | bigint | 清理释放的字节数。 | | old_versions | integer | 清理的旧版本数。 | | data_files_removed | integer | 清理的数据文件数。 | | transaction_files_removed | integer | 清理的事务文件数。 | | index_files_removed | integer | 清理的索引文件数。 | | deletion_files_removed | integer | 清理的删除标记文件数量。 | 示例： 清理2秒前产生的旧版本： ``` VACUUM TABLE lance_tbl WITH (older_than_seconds = 2); ``` 使用默认参数（Lance内核默认清理14天前的旧版本）： ``` VACUUM TABLE lance_tbl; ``` #### Lance表数据压缩 通过Compaction操作对Lance表进行数据重写（Rewrite Data），将多个小Fragment合并为较大的Fragment，并按配置重新组织Fragment内部的Row Group，从而减少Fragment数量、降低元数据开销并优化查询性能。Lance表在多次执行 INSERT、DELETE 等操作后会产生多个Fragment以及删除标记文件（Deletion File），通过Compaction可以合并小Fragment，并根据配置选择是否物化删除（Materialize Deletions）已标记删除的数据。 支持的Compaction选项如下表所示： 表3参数说明 | 字段 | 类型 | 取值范围 | 默认值 | 说明 | |:---|:---|:---|:---|:---| | target_rows_per_fragment | bigint | \[1, int32) | 1048576（约100万行） | Compaction会以该值作为目标 Fragment行数，对满足条件的 Fragment进行重写，使生成的新 Fragment 的行数尽可能接近该值（并非严格等于，也并非所有小于该值的Fragment都一定会被单独合并）。 | | max_rows_per_group | bigint | \[1, int32) | 1024 | 每个Fragment内部Row Group（Arrow RecordBatch）的最大行数。当Fragment的行数超过该值时，会被划分为多个Row Group。 | | max_bytes_per_file | bigint | \[1, int64) | write_dataset默认值 | 单个.lance文件允许的最大字节大小。 | | materialize_deletions | boolean | true/false | true | 是否在Compaction时物化删除（Materialize Deletions）已标记删除的数据。 - 设置为true时，会将删除的数据从新的Fragment中移除。 - 设置为false时，会保留删除标记文件（Deletion File）并继续引用原有 Fragment。 | | materialize_deletions_threshold | real | \[0.0, 1.0\] | 0.1 (10%) | 当materialize_deletions=true 时，仅删除比例超过该阈值的Fragment会执行物化删除。删除比例 = 已删除行数 / Fragment总行数 | | num_threads | bigint | \[0, int32) | CPU核心数 | compaction执行时使用的线程数（控制CPU并行度）。当设置为0或未指定时，将自动使用当前机器的CPU Core数。 | | batch_size | bigint | \[0, int32) | scanner默认值 | Scanner每次读取的数据Batch大小（影响内存占用和处理速度）。 | | defer_index_remap | boolean | true/false | false | 是否延迟执行索引重映射（Index Remapping）。设置为 true 时，Compaction不会立即更新关联索引，而是记录Fragment的映射关系，由后续操作完成索引重映射，可减少 Compaction 的执行时间 | | max_source_fragments | bigint | \[0, int32) | 无限制 | 单个Compaction Task最多允许参与合并的源Fragment数量，用于限制一次重写的数据规模。 | 示例： 基本用法： ``` OPTIMIZE lance_table REWRITE DATA; ``` 指定目标Fragment数： ``` OPTIMIZE lance_table REWRITE DATA WITH OPTIONS ('target_rows_per_fragment' = '10000'); ``` 多参数配置： ``` OPTIMIZE lance_table REWRITE DATA WITH OPTIONS ( 'target_rows_per_fragment' = '10000', 'materialize_deletions' = 'true', 'materialize_deletions_threshold' = '0.2', 'max_source_fragments' = '50'); ``` #### 删除Lance表 通过DROP TABLE语法删除Lance表，会同时删除表的元数据及数据（Managed表删除后可以从LakeFormation控制台恢复表的元数据及数据）。具体语法，请参见[DROP TABLE](https://support.huaweicloud.com/sqlref-aura-aidatalake/aidatalake_061_0223.html)。 示例： ``` DROP TABLE lance_tbl; ``` #### 修改表中的列 - 添加列： 向一个指定表中添加一列或者多列，需要指定列名和数据类型，添加的列会追加到表的当前列后面。 ``` ALTER TABLE tbl_name ADD COLUMN col1 typ1, col2 typ2, ....; ``` - 删除列： 删除一个指定表的一列或者多列，不能删除一个表的所有列。 ``` ALTER TABLE tbl_name DROP COLUMNS (col1, col2,...); ``` - 重命名列： 重命名一个指定的列名，不能同时重命名多列。 ``` ALTER TABLE tbl_name RENAME COLUMN old_name TO new_name; ``` - 更改列类型： 更改一个或多个指定列的数据类型为另一个类型。 ``` ALTER TABLE tbl_name ALTER COLUMN a TYPE new_type, b TYPE new_type, ...; ``` 当前仅支持从低精度类型更新到高精度类型，不支持以下范围之外的类型转换： - 整数类型：从smallint更新到int或者bigint，从int更新到bigint。 - 浮点类型：从float4更新到float8。 - numeric类型：从低精度（precision）更新到高精度（precision），不支持更新小数位数（scale）。 - 字符串类型：varchar或者char的长度变长。 #### 修改表参数 - 添加或修改参数： 仅支持max.rows.per.file、max.bytes.per.file、lance.encoding.compression三个参数。 ``` ALTER TABLE tbl_name SET TABLEPROPERTIES('max.rows.per.file'='1024', 'max.bytes.per.file'='2048', 'lance.encoding.compression'='zstd'); ``` - 移除表参数： 仅支持max.rows.per.file、max.bytes.per.file、lance.encoding.compression三个参数。 ``` ALTER TABLE tbl_name UNSET TABLEPROPERTIES('max.rows.per.file', 'max.bytes.per.file', 'lance.encoding.compression'); ```