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' ...]);

参数说明

参数说明
schema_name可选参数，指定表所在的模式。若省略，系统使用当前会话的默认模式
table_name要设置属性的表名
schema_name要设置属性的模式名
workspace_name要设置属性的工作空间名
property_key属性键名，需用单引号括起
property_value属性值，需用单引号括起

使用示例

-- 为表设置压缩和自动刷新属性
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');

表支持的参数

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

参数名称描述取值范围
data_lifecycle数据生命周期大于0的正整数值，取值为-1代表未开启生命周期
data_retention_days设置Time Travel保留期限，Time Travel保留期限决定了您可以访问多久以前的数据，包括使用UNDROP、TABLE STREAM、RESTORE访问历史数据和恢复历史数据您可以为每个表设置不同的数据保留周期，以满足不同的业务需求。num的设置范围为0-90，Lakehoue将单独对Time Travel收取存储费用
cz.storage.write.max.string.bytesSTRING 类型用于存储长度大于或等于 0 的字符序列，最大可支持 16MB 的文本数据。在批量或实时导入数据时，系统会对字段长度进行校验。若导入数据超出 16MB，可通过修改表属性调整字符串长度限制，例如将 STRING 长度设置为 32MB：ALTER TABLE table_name SET PROPERTIES("cz.storage.write.max.string.bytes"="33554432");大于0的整数
cz.storage.write.max.binary.bytesbinray 类型用于存储长度最大可支持 16MB 的数据。在批量或实时导入数据时，系统会对字段长度进行校验。若导入数据超出 16MB，可通过修改表属性调整binary长度限制，例如将 binray 长度设置为 32MB：ALTER TABLE table_name SET PROPERTIES("cz.storage.write.max.binray.bytes"="33554432");大于0的整数
cz.storage.write.max.json.bytesjson 类型用于存储长度大于或等于 0 的字符序列，最大可支持 16MB 的文本数据。在批量或实时导入数据时，系统会对字段长度进行校验。若导入数据超出 16MB，可通过修改表属性调整json字符串长度限制，例如将 json 长度设置为 32MB：ALTER TABLE table_name SET PROPERTIES("cz.storage.write.max.json.bytes"="33554432");大于0的整数

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 ...]);

参数说明

参数说明
schema_name可选参数，指定表所在的模式。若省略，系统使用当前会话的默认模式
table_name要移除属性的表名
schema_name要移除属性的模式名
workspace_name要移除属性的工作空间名
property_key要移除的属性键名

使用示例

-- 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;

参数说明

参数说明
schema_name可选参数，指定表所在的模式。若省略，系统使用当前会话的默认模式
table_name要查看属性的表名
schema_name要查看属性的模式名
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         |
+---------------+---------------+

支持的对象类型

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

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

执行行为说明

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

  1. 静默处理：如果尝试移除不存在的属性，命令会静默成功，不会抛出错误。
  2. 批量操作：可在一个命令中设置或移除多个属性，提高操作效率。
  3. 权限要求：需要对应对象的 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客户端会话中设置参数。以下是当前支持的参数列表：

参数名称取值范围默认值描述
query_tag字符串类型无用于标记查询的SQL
schedule_job_queue_priority0-90提交SQL时设置作业优先级，数值范围从0到9，数值越大，表示优先级越高
cz.sql.group.by.having.use.alias.firsttrue/falsefalse指定group by和having语句是否优先使用列的别名，而非从From语句里寻找列的名字。
cz.sql.double.quoted.identifierstrue/falsefalse分隔符标示符
cz.sql.cast.modetolerant/stricttolerant类型转化采用的模式，默认tolerant
cz.optimizer.enable.mv.rewritetrue/falsefalse提交SQL时是否开启Materialized View查询改写功能
cz.sql.string.literal.escape.modebackslashquote:引号，backslash:反斜线，quote_backslash:同时支持引号和反斜线字符串转译字符。默认时使用backslash反斜线进行转移等。
cz.sql.arithmetic.modetolerantstrict/tolerant控制算数运算出错是不是抛异常。例如运算精度溢出，默认不抛出异常
cz.sql.timezoneutc+08您可以指定时区名称例如：America/Los_Angeles、Europe/London、UTC或Etc/GMT设置sql时区
cz.sql.remote.udf.lookup.policyschema_only：强制要求UDF带Schema前缀builtin_first：优先调用内置函数，udf_first：优先调用UDF，schema_only：默认策略，强制要求UDF带Schema前缀动态切换 UDF 与内置函数的解析优先级
cz.sql.translation.mode无支持postgres,mysql,starrocks,hive,prestoLakehouse 提供 SQL 方言兼容层，支持将主流数据库方言自动转换为原生 SQL 语法。本功能基于  SQLGlot 实现如果遇到不兼容的语法设置完该参数后会自动转化语法，会将对应语言的SQL自动转化为Lakehouse可执行的语法。需要注意的是并非支持了全部的语法，只是部分语法可以转化

会话参数使用方法

  1. 在Lakehouse Studio编辑器中，您需要选中要执行的查询并执行它们。例如，要设置query_tag参数并执行一个简单的查询，请参考以下步骤： 执行以下命令设置query_tag参数：
set query_tag='test';
select 1+2;
  1. 如果在客户端或者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='xxx-api.clickzetta.com',
               instance='jnsxwfyr',
               workspace='xx',
               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进行分组。否则，将会报错找不到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://clickzetta.api.clickzetta.com/default?schema=public&query_tag=test
  • python代码中设置query_tag 
    # 建立连接 
conn = connect(username='',
 password='', 
service='api.clickzetta.com', 
instance='jnsxwfyr',
 workspace='', schema='public', vcluster='default') 
# 执行 SQL 
cursor = conn.cursor() 
my_param["hints"]["query_tag"] ="test"
cursor.execute('select 1;', parameters=my_param)

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

Image

借助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';

Image

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;此案例中我们想返回lakehouse字符串。但是由于SQL写的不规范，nvl中是一个int类型，then中是一个string类型。按照类型优先级转化规则推测会认为整体应该返回一个int类型。上面是一个true会直接进入到true的输出中，由于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)：

    案例 1：在字符串中包含单引号

    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。注意，这里使用了两个单引号 '' 来表示一个单独的单引号。

    案例 2：字符串常量的自动拼接

    SET cz.sql.string.literal.escape.mode = QUOTE;
SELECT 'foo'
'bar' as res;
+--------+
|  res   |
+--------+
| foobar |
+--------+

    案例 3：无效的字符串拼接

    --这个查询是无效的，因为两个字符串常量之间没有用逗号分隔，也没有换行，所以  不会将它们拼接。
SET cz.sql.string.literal.escape.mode = QUOTE;
SELECT 'foo' 'bar';
+--------+
|  res   |
+--------+
| foobar |
+--------+

  • 同时支持引号和反斜线模式（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 或者一个溢出的值，而不是抛出异常。

  • 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 模式下不允许算数运算除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() 函数将返回当前的日期和时间，根据 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() 函数将返回当前的日期和时间，根据UTC时区进行调整。

cz.sql.remote.udf.lookup.policy

参数说明：动态切换 UDF 与内置函数的解析优先级 案例 默认行为，使用UDF时必须带SCHEMA前缀

--创建函数
CREATE FUNCTION public.lower()
RETURNS STRING
AS 'Hello World!';
--使用函数，必须写SCHMA否则会报错函数找不到
SELECT public.lower();
-- 策略1：优先调用内置函数,可以不用写SCHMA。如果和内置函数同名优先使用内置函数
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);
对象标识符
常用的DDL语句
Yunqi © 2024 Yunqi, Inc. All Rights Reserved.

联系我们
预约咨询
微信咨询
电话咨询