Lakehouse参数控制

Lakehouse支持通过参数来控制包括数据对象以及当前连接会话的使用行为。本文将详细介绍如何通过修改Workspace、Schema和Table的属性来添加或修改参数，以及如何在JDBC客户端会话中设置会话参数。

数据对象参数

SET PROPERTIES

命令用途

SET PROPERTIES

语法格式

-- 为表设置属性 ALTER TABLE [schema_name.]table_name SET PROPERTIES ('property_key1'='property_value1' [, 'property_key2'='property_value2' ...]); -- 为schema设置属性 ALTER SCHEMA schema_name SET PROPERTIES ('property_key1'='property_value1' [, 'property_key2'='property_value2' ...]); -- 为Workspace设置属性 ALTER WORKSPACE workspace_name SET PROPERTIES ('property_key1'='property_value1' [, 'property_key2'='property_value2' ...]);

参数说明

使用示例

-- 为表设置压缩和自动刷新属性 ALTER TABLE sales_records SET PROPERTIES ('compression'='zstd', 'auto_refresh'='true'); -- 为模式设置数据保留期属性 ALTER SCHEMA reporting SET PROPERTIES ('data_retention_days'='90'); -- 为Workspace设置属性 ALTER WORKSPACE analytics_ws SET PROPERTIES ('aa'='bb');

表支持的参数

以下表格列出了系统属性及其描述和取值范围：

STRING

STRING

ALTER TABLE table_name SET PROPERTIES("cz.storage.write.max.string.bytes"="33554432");

binary

binary

ALTER TABLE table_name SET PROPERTIES("cz.storage.write.max.binary.bytes"="33554432");

json

json

ALTER TABLE table_name SET PROPERTIES("cz.storage.write.max.json.bytes"="33554432");

UNSET PROPERTIES

命令用途

UNSET PROPERTIES

语法格式

-- 移除表的属性 ALTER TABLE [schema_name.]table_name UNSET PROPERTIES (property_key1 [, property_key2 ...]); -- 移除模式的属性 ALTER SCHEMA schema_name UNSET PROPERTIES (property_key1 [, property_key2 ...]); -- 移除Workspace的属性 ALTER WORKSPACE workspace_name UNSET PROPERTIES (property_key1 [, property_key2 ...]);

参数说明

使用示例

-- a) 移除表的单个属性 ALTER TABLE sales_records UNSET PROPERTIES ('xxx'); -- b) 同时移除表的多个属性 ALTER TABLE customer_feedback UNSET PROPERTIES ('auto_refresh', 'xxxx'); -- c) 移除模式的属性 ALTER SCHEMA reporting_data UNSET PROPERTIES ('default_table_format'); -- d) 移除Workspace的属性 ALTER WORKSPACE data_science UNSET PROPERTIES ('xxx');

SHOW PROPERTIES

命令用途

SHOW PROPERTIES

语法格式

-- 查看表的属性 SHOW PROPERTIES IN TABLE [schema_name.]table_name; -- 查看模式的属性 SHOW PROPERTIES IN SCHEMA schema_name; -- 查看Workspace的属性 SHOW PROPERTIES IN WORKSPACE workspace_name;

参数说明

使用示例

-- 查看表的所有属性 SHOW PROPERTIES IN TABLE sales_data; -- 查看特定模式中表的属性 SHOW PROPERTIES IN TABLE analytics.customer_metrics; -- 查看模式的所有属性 SHOW PROPERTIES IN SCHEMA reporting; -- 查看Workspace的所有属性 SHOW PROPERTIES IN WORKSPACE data_science;

输出说明

SHOW PROPERTIES

+---------------+---------------+ | property_key | property_value| +---------------+---------------+ | compression | zstd | | auto_refresh | true | +---------------+---------------+

支持的对象类型

当前，Lakehouse 支持为以下三种主要对象类型管理属性：

1. Workspace 属性：作用于整个工作空间，影响其中的所有模式和表。通常包括资源限制、安全设置等全局配置。
2. Schema 属性：作用于特定模式，影响该模式下的所有表。常用于设置模式级别的默认行为。
3. Table 属性：作用于特定表，仅影响该表的行为和性能特性。这是最细粒度的属性设置。

执行行为说明

使用属性管理命令时，应注意以下行为特性：

1. 静默处理：如果尝试移除不存在的属性，命令会静默成功，不会抛出错误。
2. 批量操作：可在一个命令中设置或移除多个属性，提高操作效率。
3. 权限要求：需要对应对象的

   ALTER

   ALTER
   权限才能修改其属性。
4. Workspace 属性生效时间：Workspace 级别的属性修改通常在约 1 分钟后生效。

应用场景

环境迁移与配置管理

在开发、测试和生产环境之间迁移数据应用时，属性管理非常重要。

-- 生产环境设置更严格的属性 ALTER TABLE customer_data SET PROPERTIES ('encryption'='true', 'backup_schedule'='daily'); -- 移除仅适用于测试环境的属性 ALTER TABLE customer_data UNSET PROPERTIES (debug_mode, test_flag);

清理过时配置

-- 查找具有过时属性的表 SHOW PROPERTIES IN TABLE legacy_system_data; -- 移除过时的兼容性属性 ALTER TABLE legacy_system_data UNSET PROPERTIES (compatibility_mode, legacy_format);

属性变更验证

执行属性变更后，可通过以下方式验证操作是否成功：

-- 使用SHOW PROPERTIES命令直接查看 SHOW PROPERTIES IN TABLE modified_table; -- 或使用DESC命令查看详细信息 DESC TABLE EXTENDED modified_table;

会话参数

Lakehouse支持在JDBC客户端会话中设置参数。以下是当前支持的参数列表：

FROM_UNIXTIME

null

会话参数使用方法

1. 在 Lakehouse Studio 编辑器中，您需要选中要执行的查询并执行它们。例如，要设置

   query_tag

   query_tag
   参数并执行一个简单的查询，请参考以下步骤： 执行以下命令设置

   query_tag

   query_tag
   参数：

set query_tag='test'; select 1+2;

2. 如果在客户端或者 JDBC 运行会话参数，则会在整个会话期间生效。

set query_tag='test'; select 1+2;

上面的query_tag仍然会生效

select 1+4;

Python SDK 设置参数 在 JDBC 中通过 SET 命令设置的 SQL hints 可以通过

parameters

from clickzetta import connect # 建立连接 conn = connect(username='', password='', service='region_id.api.clickzetta.com', instance='demo_instance', workspace='demo_workspace', schema='public', vcluster='default') my_param = { 'hints': { 'cz.sql.timezone': 'UTC+00' } } cursor = conn.cursor() cursor.execute("select current_timestamp();",my_param) # 获取查询结果 results = cursor.fetchall() for row in results: print(row) # 关闭连接 cursor.close() conn.close()

会话参数说明

cz.sql.group.by.having.use.alias.first

此参数指定group by和having语句是否优先使用列的别名，而非从From语句里寻找列的名字。例如，考虑以下查询：

select count(*) from (select col1 as c1 from table1) t group by c1;

如果启用此参数，查询将使用别名

c1

query_tag

设置query_tag后，会话中的查询作业历史将自动在作业历史的query_tag字段中添加自定义标签内容。可以通过set query_tag命令方式设置，也可以在jdbc URL中设置query_tag。例如：

set query_tag='aa'; select 1;

• 在jdbc url中添加query_tag,这样提交的每条SQL都会带上query_tag用来标识来源，可以在页面中进行过滤

  jdbc:clickzetta://demo_instance.cn-shanghai-alicloud.api.clickzetta.com/default?schema=public&query_tag=test

• python代码中设置query_tag

  # 建立连接 conn = connect(username='', password='', service='cn-shanghai-alicloud.api.clickzetta.com', instance='demo_instance', workspace='', schema='public', vcluster='default') # 执行 SQL cursor = conn.cursor() my_param["hints"]["query_tag"] ="test" cursor.execute('select 1;', parameters=my_param)

在 Studio 的作业历史中过滤，当前只支持精确匹配。

预览

借助query_tag参数，您可以对作业进行分类和检索。在Lakehouse 的information_schema查询过滤作业：

select * from information_schema.job_history where query_tag='aa';

在show jobs中可以过滤：

show jobs where query_tag='aa' limit 100 ;

desc jobs中也可以展示设置的query tag

desc job '202311281613333434l4r2v3c8ni0';

预览

cz.sql.double.quoted.identifiers

• 在 SQL 的 ANSI/ISO 标准中，双引号中的标识符（分隔标识符）允许用户可以写特殊字符或者关键字。Lakehouse也可以兼容此行为。
• 开启后双引号为分隔符标识符，SET cz.sql.double.quoted.identifiers=true 当前只支持会话级别开启。需要特别注意的是，如果开启双引号为分隔符标识符后，Lakehouse 将不再把双引号括起来的数据认为是一个字符串类型。

cz.sql.cast.mode

• 开启cast strict模式后，显式转换无法转换的类型会报错，可以使用try_cast函数
• 隐式转换行为无法转换的会报错。案例：比如

  select case when true then 'lakehouse' else nvl(null,-99) end;

  select case when true then 'lakehouse' else nvl(null,-99) end;
  此案例中我们想返回 lakehouse 字符串。但是由于SQL写的不规范，nvl中是一个int类型，then中是一个string类型。按照类型优先级转换规则推测会认为整体应该返回一个int类型。上面是一个true会直接进入到true的输出中，由于

  lakehouse

  lakehouse
  是一个字符串转换成int，系统默认行为会直接走try_cast，lakehouse转换成int时则会变成null，会导致一些结果超出预期。如果严格模式，系统则不会自动走try_cast会将异常抛出，告知用户这个SQL不是规范行为，如果确认逻辑正确，在开启ansi模式下添加try_cast函数

select case when true then cast('lakehouse' as int) else nvl(null,-99) end; select case when true then try_cast('123' as int) else nvl(null,-99) end;

schedule_job_queue_priority

作业优先级 用户提交的SQL作业会附带一个优先级设置，该设置决定了作业在队列中的执行顺序。系统会根据这些设置来确定哪些作业应该优先执行，并优先将它们下发到虚拟集群（VCLUSTER）进行处理。对于GP和AP类型的VCLUSTER，优先级设置决定了哪个作业首先被下发到VCLUSTER。在计算集群中有大量作业排队等待处理时，设置作业优先级尤为有效。

作业优先级划分

• 定义：作业优先级是一个数值，用于标识作业的执行顺序。
• 对应数字：数值范围从0到9，数值越大，表示优先级越高。

作业优先级设置

• SQL支持：用户可以在当前临时会话中修改作业的优先级，以便在提交作业时指定优先级。
• 设置语法：使用以下命令来设置作业优先级：

SET schedule_job_queue_priority = {优先级数值};

• 其中，{优先级数值}是一个介于0到9之间的整数。

案例

set schedule_job_queue_priority=2; select current_timestamp();

以下是针对您提到的几个参数的案例：

cz.sql.string.literal.escape.mode

参数说明：此参数用于控制字符串字面量的转义字符。默认使用反斜线（

\

案例：

• 默认模式（backslash）：

  SELECT 'Hello \n World!' AS res; +---------+ | res | +---------+ | Hello World! | +---------+ SELECT 'It''s a beautiful day' as res; +---------------------+ | res | +---------------------+ | Its a beautiful day | +---------------------+

• 引号模式(quote)：

  SET cz.sql.string.literal.escape.mode = QUOTE; SELECT 'It''s a beautiful day'; +----------------------+ | res | +----------------------+ | It's a beautiful day | +----------------------+

  这个查询将返回字符串

  It's a beautiful day

  It's a beautiful day
  。注意，这里使用了两个单引号

  ''

  ''
  来表示一个单独的单引号。

• 同时支持引号和反斜线模式（quote_backslash）：

  SET cz.sql.string.literal.escape.mode = quote_backslash; SELECT 'Hello \n World!' AS res,'It''s a beautiful day' as res2; +---------+---------------------+ | res | res2 | +---------+---------------------+ | Hello World! | Its a beautiful day | +---------+---------------------+

  在这个例子中，既可以使用反斜线转义特殊字符，也可以使用双引号来包含引号。

cz.sql.arithmetic.mode

参数说明：此参数控制算术运算出错时是否抛出异常。默认为

tolerant

案例：

• tolerant模式（默认）：

  SELECT 2/0 res; +------+ | res | +------+ | null | +------+

  在这个例子中，除以 0 返回一个

  NULL

  NULL
  或者一个溢出的值，而不是抛出异常。

• strict模式：

  SET cz.sql.arithmetic.mode = strict; SELECT 2/0 res; CZLH-22012:arithmetic divide by zero. Detail taskId 0, vertex name=stg0, vertexId=2024121311314772461pl5i9617d2_94570-V0 (state=,code=0)

  在这个例子中，将会抛出一个异常，因为

  strict

  strict
  模式下不允许算术运算除以 0。

cz.sql.timezone

参数说明：此参数用于设置 SQL 会话的时区。

案例：

• 设置时区为UTC+08：

  SET cz.sql.timezone = Asia/Shanghai; SELECT NOW() AS res; +---------------------------+ | res | +---------------------------+ | 2024-12-13 07:43:28.275429| +---------------------------+

• 在这个例子中，

  NOW()

  NOW()
  函数将返回当前的日期和时间，根据

  Asia/Shanghai

  Asia/Shanghai
  时区（UTC+08）进行调整。

• 设置时区为UTC：

  SET cz.sql.timezone = UTC; SELECT NOW() AS res_utc; +----------------------------+ | res_utc | +----------------------------+ | 2024-12-13 07:43:46.791785 | +----------------------------+

  在这个例子中，

  NOW()

  NOW()
  函数将返回当前的日期和时间，根据UTC时区进行调整。

cz.sql.remote.udf.lookup.policy

参数说明：动态切换 UDF 与内置函数的解析优先级。

案例：

默认行为，使用UDF时必须带SCHEMA前缀

--创建函数 CREATE FUNCTION public.lower() RETURNS STRING AS 'Hello World!'; --使用函数，必须写SCHEMA否则会报错函数找不到 SELECT public.lower(); -- 策略1：优先调用内置函数，可以不用写SCHEMA。如果和内置函数同名优先使用内置函数 SET cz.sql.remote.udf.lookup.policy = builtin_first; SELECT lower(); -- 策略2：优先调用UDF（适配MC/Spark作业场景）。如果和内置函数同名优先使用udf SET cz.sql.remote.udf.lookup.policy = udf_first; SELECT lower();

cz.sql.translation.mode 【预览发布】本功能当前处于公开预览发布阶段。

参数说明：通过设置此参数，Lakehouse 可将指定 SQL 方言的语法自动转换为原生可执行语法，实现多方言兼容查询。本功能基于改进版 SQLGlot 实现，支持将常见数据库语法透明转换为 Lakehouse 原生语法，降低业务迁移成本。需要注意的是，并非支持全部的语法转换，只是部分语法可以转换。目前支持 PostgreSQL、MySQL、Doris、Hive、Presto。

案例：

设置Doris转化

--设置Doris转化 set cz.sql.translation.mode=doris; SELECT DATE_ADD(CURRENT_TIMESTAMP(), INTERVAL 1 HOUR);

DATE_FORMAT 和 AES_DECRYPT 函数需要指定 cz.sql.compatible.target 引擎兼容模式，以设置兼容 MySQL 或 PostgreSQL 的原始语义。

--兼容 mysql DATE_FORMAT 函数的原生语义 set cz.sql.compatible.target=mysql; select DATE_FORMAT(CURRENT_DATE(), '%x-%v %a %W'); --兼容 pg DATE_FORMAT 函数的原生语义 set cz.sql.compatible.target=pg; SELECT DATE_FORMAT(CURRENT_TIMESTAMP(), 'yyyy-"Q"Q') --兼容 mysql AES_DECRYPT 函数的原生语义 set cz.sql.compatible.target=mysql; SELECT CAST(AES_DECRYPT(UNBASE64('fOltPBoMXnbhu54SSxaaAQ=='), 'namePURPMEF4uI2mQSbrWOhpAvu6OGbE4U') AS STRING);

cz.sql.type.conversion

默认值：无 取值为 hive 时：兼容 Hive 的类型转换规则。

用于兼容 Hive 的类型转换。由于 Lakehouse 和 Hive 的默认类型转换规则存在差异，设置此参数可使类型转换逻辑与 Hive 保持一致。详细的类型转换优先级规则可参考类型转化。

cz.sql.function.from.unixtime.trim.to.second

默认值：false

控制

FROM_UNIXTIME

cz.sql.time.parser.strict.mode

默认值：false

启用时间解析的严格模式。若时间格式与指定的格式模式不匹配，系统将抛出错误；禁用时则返回

null

示例：

SET cz.sql.time.parser.strict.mode=true; SELECT TO_TIMESTAMP('2025-08-01','yyyy-MM-dd HH'); 执行结果: ❌ 错误发生 SET cz.sql.time.parser.strict.mode=false; SELECT TO_TIMESTAMP('2025-08-01','yyyy-MM-dd HH'); 执行结果: NULL

cz.sql.cast.string.to.integer.allow.truncate

默认值：false

控制字符串转整数时是否允许截断小数位。启用时，转换过程中的小数部分将被直接丢弃，与 Hive 的行为保持一致。

示例：

SELECT CAST('11.4' AS INT); 执行结果: NULL SET cz.sql.cast.string.to.integer.allow.truncate=true; SELECT CAST('11.4' AS INT) ; 执行结果:11