使用 database/sql 查询

Go SDK 通过标准库

database/sql
database/sql
执行查询和 DML。本文介绍 DSN 参数、查询与写入、参数绑定、SQL 参数设置、超时与取消,以及以 Arrow 格式读取结果。安装和第一个查询程序见 Go SDK 简介。

连接字符串(DSN)

<username>:<password>@<protocol>(<service>)/<schema>?virtualCluster=<vcluster>&workspace=<workspace>&instance=<instance>[&<参数>=<值>...]

参数是否必填说明
username
username
是登录用户名
password
password
是登录密码。使用
magic_token
magic_token
认证时可以不填
protocol
protocol
否
https
https
或
http
http
。主版本从
v0.0.20
v0.0.20
开始可以省略,默认
https
https
,例如
<username>:<password>@(<service>)/...
<username>:<password>@(<service>)/...
。
⚠️
v0.0.19
v0.0.19
及更早版本中省略协议时,请求会失败并返回
unsupported protocol scheme ""
unsupported protocol scheme ""
。使用这些版本或兼容版本时请显式填写
service
service
是Lakehouse 服务地址,例如
cn-shanghai-alicloud.api.clickzetta.com
cn-shanghai-alicloud.api.clickzetta.com
;DSN 中不要重复填写
https://
https://
。所有地域见 云服务和地域
schema
schema
否默认 SCHEMA;不填写时使用
public
public
virtualCluster
virtualCluster
是默认计算集群名称,也可以写作
vc
vc
workspace
workspace
是工作空间名称
instance
instance
是Lakehouse 服务实例名称

可选参数:

参数默认值说明
magic_token
magic_token
无使用已有的 token 认证,跳过用户名密码登录。也可以写作
token
token
sdk.query.max.retries
sdk.query.max.retries
10
10
提交作业和获取结果时的最大重试次数
separate_params
separate_params
false
false
为
true
true
时,
INSERT
INSERT
的批量参数以 Arrow 二进制格式单独发送,不拼接进 SQL 文本。适合大批量参数写入
cz.sql.string.literal.escape.mode
cz.sql.string.literal.escape.mode
backslash
backslash
驱动拼接字符串参数时的转义方式,见 字符串转义

参数值需要进行 URL 编码。

前置准备

本文以及 批量写入数据(Bulkload)、使用 GORM 中的示例共用以下表和数据。在 DSN 指定的 SCHEMA 中执行:

CREATE TABLE doc_go_orders ( id BIGINT NOT NULL, name STRING, amount INT, cost DECIMAL(10, 2) ); CREATE TABLE doc_go_orders_archive ( id BIGINT NOT NULL, name STRING, amount INT, cost DECIMAL(10, 2) ); CREATE TABLE doc_go_tags ( id BIGINT, tags ARRAY<INT> ); INSERT INTO doc_go_orders VALUES (1, 'Alice', 120, 18.00), (2, 'Bob', 80, 12.50), (3, 'Carol', 260, 39.00);

SELECT * FROM doc_go_orders ORDER BY id
SELECT * FROM doc_go_orders ORDER BY id
的结果:

idnameamountcost
1Alice12018.00
2Bob8012.50
3Carol26039.00

示例中的

db
db
是
sql.Open("clickzetta", dsn)
sql.Open("clickzetta", dsn)
返回的
*sql.DB
*sql.DB
,
ctx
ctx
是
context.Context
context.Context
。

查询与写入

rows, err := db.QueryContext(ctx, "SELECT id, name FROM doc_go_orders WHERE amount > ? ORDER BY id LIMIT 10", 100) if err != nil { log.Fatal(err) } defer rows.Close() for rows.Next() { var id int64 var name string if err := rows.Scan(&id, &name); err != nil { log.Fatal(err) } fmt.Println(id, name) } if err := rows.Err(); err != nil { log.Fatal(err) } _, err = db.ExecContext(ctx, "INSERT INTO doc_go_orders (id, name, amount) VALUES (?, ?, ?)", 4, "O'Brien", 200) if err != nil { log.Fatal(err) }

查询输出

amount
amount
大于 100 的订单:

1 Alice 3 Carol

INSERT
INSERT
执行后,
SELECT * FROM doc_go_orders WHERE id = 4
SELECT * FROM doc_go_orders WHERE id = 4
的结果如下。未写入的
cost
cost
列为 NULL,
'
'
按原样写入:

idnameamountcost
4O'Brien200NULL

参数绑定

SQL 中的

?
?
占位符由驱动替换为对应参数的字面量后再提交。驱动按以下规则生成字面量:

Go 类型生成的 SQL
整数、浮点数数值字面量。
NaN
NaN
和无穷大会返回错误
string
string
加引号并转义的字符串。必须是合法的 UTF-8,否则返回错误;二进制数据请使用
[]byte
[]byte
[]byte
[]byte
十六进制 BINARY 字面量
X'...'
X'...'
time.Time
time.Time
timestamp 'YYYY-MM-DD HH:MM:SS[.ffffff]±HH:MM'
timestamp 'YYYY-MM-DD HH:MM:SS[.ffffff]±HH:MM'
,带时区偏移,精度最高到微秒
nil
nil
、
sql.NullString
sql.NullString
等
值为空时生成
NULL
NULL
goclickzetta.RawSQLValue
goclickzetta.RawSQLValue
原样拼接,用于 ARRAY、MAP、STRUCT 等复杂类型
  • 写入
    TIMESTAMP
    TIMESTAMP
    (即
    TIMESTAMP_LTZ
    TIMESTAMP_LTZ
    )列时,服务端按字面量中的时区偏移确定时间点;
    TIMESTAMP_NTZ
    TIMESTAMP_NTZ
    列忽略偏移,保留字面量中的本地时间。需要按特定时区写入时,先调用
    In()
    In()
    转换,例如
    ts.In(time.UTC)
    ts.In(time.UTC)
    。
  • 字符串字面量、带引号的标识符和注释中的
    ?
    ?
    不会被当作占位符。参数个数多于占位符时返回
    too many bindings for placeholders
    too many bindings for placeholders
    。

复杂类型使用

RawSQLValue
RawSQLValue
传入:

_, err := db.ExecContext(ctx, "INSERT INTO doc_go_tags VALUES (?, ?)", 1, goclickzetta.RawSQLValue("array(1,2,3)"))

执行

SELECT id, tags FROM doc_go_tags
SELECT id, tags FROM doc_go_tags
,把两列扫描到
any
any
类型的变量后用
fmt.Println
fmt.Println
打印:

1 [1 2 3]

字符串转义

字符串默认按

backslash
backslash
方式转义:
'
'
转为
\'
\'
,
\
\
转为
\\
\\
。驱动会把所用的转义方式作为 SQL 参数告知服务端。

可以把

cz.sql.string.literal.escape.mode
cz.sql.string.literal.escape.mode
设为
quote
quote
,改为
quote
quote
方式(
'
'
转为
''
''
)。该参数只能通过 DSN 或
WithDriverFlags
WithDriverFlags
设置。写在 SQL 前面不起作用:驱动会用 DSN 或 context 中的值覆盖它。

验证方法:通过 context 设置

quote
quote
后执行
SELECT 'O''Brien'
SELECT 'O''Brien'
。返回
O'Brien
O'Brien
说明服务端支持;返回
OBrien
OBrien
说明不支持,请继续使用默认的
backslash
backslash
方式。

qctx := goclickzetta.WithDriverFlags(ctx, goclickzetta.DriverFlags{ "cz.sql.string.literal.escape.mode": "quote", }) var s string if err := db.QueryRowContext(qctx, "SELECT 'O''Brien'").Scan(&s); err != nil { log.Fatal(err) } fmt.Println(s)

在不支持

quote
quote
的服务端上,输出为:

OBrien

设置 SQL 参数

在 JDBC 中通过

set
set
命令设置的 SQL 参数,在 Go SDK 中有两种传递方式。支持的参数请参考 参数管理。

写在 SQL 前面:用

<参数>=<值>;
<参数>=<值>;
的形式写在语句前,不需要
set
set
关键字。可以写多个参数,最后一条是要执行的语句:

var ts time.Time err := db.QueryRowContext(ctx, "cz.sql.timezone=Asia/Shanghai;SELECT current_timestamp()").Scan(&ts)

ts
ts
是一个时间点,打印时时区为 UTC,例如
2026-11-16 12:38:57.555467 +0000 UTC
2026-11-16 12:38:57.555467 +0000 UTC
。需要按特定时区显示时调用
ts.In()
ts.In()
转换。

通过 context 传递:适合给一组语句统一设置参数:

ctx := goclickzetta.WithDriverFlags(context.Background(), goclickzetta.DriverFlags{ "cz.sql.timezone": "Asia/Shanghai", }) rows, err := db.QueryContext(ctx, "SELECT id, name, amount FROM doc_go_orders ORDER BY id LIMIT 10")

通过 context 还可以临时切换

schema
schema
、
catalog
catalog
和
virtualCluster
virtualCluster
,只对这次调用生效。

超时与取消

方式作用
context.WithTimeout
context.WithTimeout
只控制客户端等待结果的时间。超时后 SDK 停止等待并返回错误,服务端作业继续运行。
⚠️
v0.0.20
v0.0.20
及更早版本和兼容版本中,小于 30 秒的超时不生效,约 30 秒后才返回
sdk.job.timeout
sdk.job.timeout
作业超过指定秒数仍未结束时,SDK 取消服务端作业并返回错误
Cancel
Cancel
、
CancelJob
CancelJob
主动取消服务端作业

sdk.job.timeout
sdk.job.timeout
是 SDK 自身的参数,单位为秒,写在 SQL 前面传递,不会发送给服务端。从
v0.0.21
v0.0.21
开始,计时从提交作业时算起,作业在设置的秒数后被取消。例如设置为
5
5
时,长时间运行的作业约在 5 秒后被取消,
ExecContext
ExecContext
返回
job timeout, jobid: <作业 ID>
job timeout, jobid: <作业 ID>
。

以下语句为归档作业设置 600 秒的时限:

_, err := db.ExecContext(ctx, "sdk.job.timeout=600;INSERT INTO doc_go_orders_archive SELECT * FROM doc_go_orders")

作业在时限内完成,

err
err
为
nil
nil
,
doc_go_orders_archive
doc_go_orders_archive
中写入了
doc_go_orders
doc_go_orders
的全部行。

*goclickzetta.ClickzettaConn
*goclickzetta.ClickzettaConn
提供两个取消方法,参数
userAgent
userAgent
用于标识取消的来源,传空字符串时使用默认值:

  • Cancel(userAgent string) error
    Cancel(userAgent string) error
    :取消该连接上正在执行的作业。
  • CancelJob(jobID string, userAgent string) error
    CancelJob(jobID string, userAgent string) error
    :按作业 ID 取消作业。

database/sql
database/sql
在执行语句期间会锁定连接,此时在另一个 goroutine 中调用
conn.Raw
conn.Raw
会一直等到语句结束,无法取消正在执行的作业。因此需要在
Raw
Raw
回调中通过驱动连接执行语句,并在定时器或其他 goroutine 中调用
Cancel
Cancel
:

conn, err := db.Conn(ctx) if err != nil { log.Fatal(err) } defer conn.Close() err = conn.Raw(func(dc any) error { cz := dc.(*goclickzetta.ClickzettaConn) // 5 秒后取消该连接上正在执行的作业 timer := time.AfterFunc(5*time.Second, func() { if err := cz.Cancel("my-app"); err != nil { log.Println("cancel:", err) } }) defer timer.Stop() // 一个需要较长时间的查询:4 × 1010 行的笛卡尔积 _, err := cz.ExecContext(ctx, "SELECT sum(a*b) FROM (SELECT explode(sequence(1,200000)) a) x CROSS JOIN (SELECT explode(sequence(1,200000)) b) y", nil) return err }) fmt.Println(err)

约 5 秒后输出:

job cancelled, jobid: <作业 ID>

作业被取消后,

ExecContext
ExecContext
返回上述错误,连接仍可继续使用。作业在取消前已经结束时,
Cancel
Cancel
不起作用,
ExecContext
ExecContext
正常返回。已知作业 ID 时,也可以在任意连接上调用
CancelJob
CancelJob
取消该作业。

读取 Arrow 格式结果

需要直接处理列式数据时,可以用

QueryArrowStream
QueryArrowStream
获取 Arrow RecordReader,避免逐行转换的开销:

conn, err := db.Conn(ctx) if err != nil { log.Fatal(err) } defer conn.Close() err = conn.Raw(func(dc any) error { reader, err := dc.(*goclickzetta.ClickzettaConn).QueryArrowStream(ctx, "SELECT * FROM doc_go_orders", nil) if err != nil { return err } defer reader.Release() for reader.Next() { record := reader.Record() fmt.Println(record.NumRows()) } return reader.Err() })

每次

reader.Next()
reader.Next()
返回一批数据,输出该批的行数。批次的划分由服务端决定,各批行数之和等于结果的总行数。

返回值类型为

github.com/apache/arrow-go/v18/arrow/array.RecordReader
github.com/apache/arrow-go/v18/arrow/array.RecordReader
。该接口只在主版本中提供。

作业来源信息

从

v0.0.19
v0.0.19
(Arrow v12 兼容版
v0.0.20-arrow12
v0.0.20-arrow12
,无 Arrow 版
v0.0.12-csv
v0.0.12-csv
)开始,SDK 提交的每个 SQL 作业都会携带客户端信息,便于在作业历史中区分来源和排查问题:

  • SQL 参数
    cz.sql.sdk.info
    cz.sql.sdk.info
    :SDK 名称和版本,格式为
    goclickzetta:<版本号>
    goclickzetta:<版本号>
    ,例如
    goclickzetta:0.0.19
    goclickzetta:0.0.19
    。通过 commit 或分支依赖 SDK 时会附加 commit,例如
    goclickzetta:0.0.19-0.20261112093000-abcdef123456:abcdef123456
    goclickzetta:0.0.19-0.20261112093000-abcdef123456:abcdef123456
    。版本号来自应用编译时记录的依赖信息;使用
    replace
    replace
    指向本地目录时为
    goclickzetta:unknown
    goclickzetta:unknown
    。
  • 作业的 user agent:客户端访问服务端所用的本机 IP 地址。
联系我们
预约咨询
微信咨询
电话咨询
邮件咨询