Lakehouse 参数控制

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

数据对象参数

Workspace 属性

要修改 Workspace 属性，请使用以下语法：

ALTER WORKSPACE wbname SET PROPERTIES ('key'='value')

要查看 Workspace 属性，请使用以下语法：

SHOW PROPERTIES IN WORKSPACE <workspace_name>

Schema 属性

要修改 Schema 属性，请使用以下语法：

ALTER SCHEMA scname SET PROPERTIES ('key'='value')

要查看 Schema 属性，请使用以下语法：

SHOW PROPERTIES IN SCHEMA scname

Table 属性

要修改 Table 属性，请使用以下语法：

ALTER TABLE tbname SET PROPERTIES ('key'='value')

要查看 Table 属性，请使用以下语法：

SHOW PROPERTIES IN TABLE tbname

表支持的参数

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

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

会话参数

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

如何使用会话参数

在 JDBC 中设置参数后，这些参数将在整个当前 JDBC 连接中生效。例如，要设置

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

set cz.sql.group.by.having.use.alias.first=true;

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

query_tag

1. 运行以下命令设置

   query_tag

   query_tag
   参数：

set query_tag='test';

2. 执行查询：

select 1;

python sdk 设置参数 通过 JDBC 中 set 命令设置的 SQL hints 可以通过

parameters

from clickzetta import connect # 建立连接 conn = connect(username='', password='', service='xxx-api.singdata.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

query_tag

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

set query_tag='aa'; select 1;

• 在 JDBC URL 中添加

  query_tag

  query_tag
  ，使每个提交的 SQL 都携带

  query_tag

  query_tag
  以标识来源，可在页面上进行过滤。

  jdbc:clickzetta://xxx.api.singdata.com/default?schema=public&query_tag=test

• 在 python 代码中设置 query_tag

# 建立连接 conn = connect(username='', password='', service='api.singdata.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 的作业历史中，仅过滤精确匹配

预览

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

• 在 ANSI/ISO SQL 标准中，双引号内的标识符（分隔标识符）允许用户使用特殊字符或关键字。Singdata 也可以兼容此行为。
• 启用后，双引号充当标识符的分隔符。设置

  cz.sql.double.quoted.identifiers=true

  cz.sql.double.quoted.identifiers=true
  目前仅支持会话级别启用。需要注意的是，如果将双引号启用为标识符的分隔符，Singdata 将不再把双引号内的数据视为字符串类型。

cz.sql.cast.mode

• 当启用 cast strict 模式时，尝试转换不兼容的类型将导致错误。您可以使用

  try_cast

  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

  nvl
  中包含 int 类型，而

  then

  then
  中包含字符串类型。根据类型优先级转换规则，推断整体返回类型应为 int。由于条件为 true，直接进入 true 输出。因为 'lakehouse' 是字符串被转换为 int，系统的默认行为将直接使用

  try_cast

  try_cast
  ，将 'lakehouse' 转换为 int 会得到 null，导致意外结果。在 strict 模式下，系统不会自动使用

  try_cast

  try_cast
  ，而是抛出异常，告知用户此 SQL 不是标准行为。如果确认逻辑是正确的，在启用 ANSI 模式时添加

  try_cast

  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 = {priority value};

• 其中，{priority value} 为 0 到 9 之间的整数。 示例

set schedule_job_queue_priority=2; select current_timestamp();

cz.sql.string.literal.escape.mode

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

\

示例：

• 默认模式（backslash）：

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

• Quote 模式（quote）：

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

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

此查询将返回字符串

It's a beautiful day

''

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

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

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

--此查询无效，因为两个字符串字面量之间没有用逗号或换行符分隔，因此不会被拼接。 SET cz.sql.string.literal.escape.mode = QUOTE; SELECT 'foo' 'bar';

• 同时支持 quote 和 backslash 模式（quote_backslash）：

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

cz.sql.arithmetic.mode

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

tolerant

示例：

• tolerant 模式（默认）：

  SELECT 2/0 res;

在此示例中，除以 0 返回

NULL

• strict 模式：

  SET cz.sql.arithmetic.mode = strict; SELECT 2/0 res;

在此示例中，将抛出异常，因为在

strict

cz.sql.timezone

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

示例：

• 将时区设置为 UTC+08：

  SET cz.sql.timezone = 'Asia/Shanghai'; SELECT NOW() AS res;

• 在此示例中，

  NOW()

  NOW()
  函数将返回当前日期和时间，调整为

  Asia/Shanghai

  Asia/Shanghai
  时区（UTC+08）。

• 将时区设置为 UTC：

  SET cz.sql.timezone = 'UTC'; SELECT NOW() AS res_utc;

在此示例中，

NOW()

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.patible.target 引擎兼容模式，以设置与 MySQL 或 PostgreSQL 兼容的原始语义。

-- 兼容 MySQL DATE_FORMAT 函数的原生语义 set cz.sql.compatible.target=mysql; select DATE_FORMAT(CURRENT_DATE(), '%x-%v %a %W'); -- 兼容 PostgreSQL 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);