批量写入数据(Bulkload)
Bulkload 是 Go SDK 的高吞吐批量写入接口,适合把 Go 内存中的大量结构化数据写入 Lakehouse 表。
本文介绍主版本的接口。Arrow v12 兼容版的接口略有不同,见 兼容版本的接口 ;无 Arrow 版不支持 Bulkload。
概述
Bulkload 的写入流程是:Go 应用通过 Writer 写入 Row,SDK 在本地把数据写成 Parquet 文件并上传;调用
BulkloadStream.Close()BulkloadStream.Close()
时,SDK 关闭所有 Writer、上传剩余数据并提交,数据才会加载到目标表。
写入方式 适用场景 数据可见性 Bulkload 大批量导入、历史数据回灌 Close()Close()
成功返回后可见ExecContextExecContext
执行 DML低频小批量 DML SQL 执行成功后可见 COPY INTOCOPY INTO
数据已在对象存储 SQL 执行成功后可见
⚠️ 注意 :
BulkloadStream.Close()BulkloadStream.Close()
才会刷新、上传并提交数据,必须检查其返回的错误。Go SDK 的提交方式与 Java SDK 不同,不需要单独调用提交接口。
写入数据
示例写入 前置准备 中创建的
doc_go_ordersdoc_go_orders
表(
id BIGINT NOT NULLid BIGINT NOT NULL
、
name STRINGname STRING
、
amount INTamount INT
、
cost DECIMAL(10, 2)cost DECIMAL(10, 2)
)。
CreateBulkloadStreamCreateBulkloadStream
是
*goclickzetta.ClickzettaConn*goclickzetta.ClickzettaConn
的方法。通过
database/sqldatabase/sql
使用时,先用
db.Conndb.Conn
取得专用连接,再用
RawRaw
访问驱动连接:
import (
"context"
"database/sql"
"fmt"
"github.com/clickzetta/goclickzetta"
"github.com/shopspring/decimal"
)
func writeOrders(ctx context.Context, db *sql.DB) error {
conn, err := db.Conn(ctx)
if err != nil {
return err
}
defer conn.Close()
return conn.Raw(func(dc any) error {
cz := dc.(*goclickzetta.ClickzettaConn)
stream, err := cz.CreateBulkloadStream(goclickzetta.BulkloadOptions{
Table: "doc_go_orders",
Operation: goclickzetta.APPEND,
})
if err != nil {
return err
}
writer, err := stream.CreateWriter(0)
if err != nil {
stream.Abort()
return err
}
for i := 1000; i < 2000; i++ {
row := writer.CreateRow()
// Set* 出错时该列不会被赋值,必须检查错误并放弃写入
if err := row.SetBigint("id", int64(i)); err != nil {
stream.Abort()
return err
}
if err := row.SetString("name", fmt.Sprintf("order_%d", i)); err != nil {
stream.Abort()
return err
}
if err := row.SetDecimal("cost", decimal.NewFromFloat(float64(i-1000)*1.5)); err != nil {
stream.Abort()
return err
}
if err := writer.WriteRow(row); err != nil {
stream.Abort()
return err
}
}
// Close 关闭所有 Writer、上传剩余数据并提交
return stream.Close()
})
}
Close()Close()
成功后,执行
SELECT count(*), min(id), max(id), sum(cost) FROM doc_go_orders WHERE id >= 1000SELECT count(*), min(id), max(id), sum(cost) FROM doc_go_orders WHERE id >= 1000
的结果:
count(*) min(id) max(id) sum(cost) 1000 1000 1999 749250.00
示例没有设置
amountamount
列,
SELECT * FROM doc_go_orders WHERE id IN (1000, 1001, 1999) ORDER BY idSELECT * FROM doc_go_orders WHERE id IN (1000, 1001, 1999) ORDER BY id
的结果:
id name amount cost 1000 order_1000 NULL 0.00 1001 order_1001 NULL 1.50 1999 order_1999 NULL 1498.50
未设置的列写入 NULL,向
Set*Set*
方法传入
nilnil
也写入 NULL。空字符串按空字符串写入,不会转为 NULL。
以下情况会返回错误:
Set*Set*
方法设置了目标表中不存在的列,或传入的值与列类型不匹配:Set*Set*
返回错误,例如 table doc_go_orders has no column "nmae"table doc_go_orders has no column "nmae"
。
NOT NULLNOT NULL
列未设置值或设置为 nilnil
:WriteRowWriteRow
返回错误,例如 column "id" of table doc_go_orders is NOT NULL but has no valuecolumn "id" of table doc_go_orders is NOT NULL but has no value
,该行不会写入。
⚠️ 注意 :
Set*Set*
返回错误时,该列没有被赋值,但这一行仍然可以写入。如果忽略错误继续调用
WriteRowWriteRow
,该列会被写成 NULL,并且不会返回任何错误。请像上面的示例一样检查每次
Set*Set*
调用的错误。
⚠️ 注意 :
v0.0.18v0.0.18
及更早版本中,有列未设置时
stream.Close()stream.Close()
会使程序崩溃(panic),并且无法写入 NULL。请使用
v0.0.19v0.0.19
或更高版本;Arrow v12 兼容版请使用
v0.0.20-arrow12v0.0.20-arrow12
或更高版本。
写入失败时调用
stream.Abort()stream.Abort()
放弃本次写入,SDK 会清理本地和已上传的临时文件,数据不会提交。
写入模式
OperationOperation
说明 APPENDAPPEND
追加写入,默认模式 OVERWRITEOVERWRITE
覆盖写入,清空目标表中原有数据 UPSERTUPSERT
按记录键更新已有行并插入新行
⚠️ 注意 :使用
UPSERTUPSERT
时必须通过
RecordKeysRecordKeys
指定记录键。
stream, err := cz.CreateBulkloadStream(goclickzetta.BulkloadOptions{
Table: "doc_go_orders",
Operation: goclickzetta.UPSERT,
RecordKeys: []string{"id"},
})
用这个 stream 写入一行
id=1, name="Alice", amount=150id=1, name="Alice", amount=150
(不设置
costcost
)后,
SELECT * FROM doc_go_orders WHERE id = 1SELECT * FROM doc_go_orders WHERE id = 1
的结果:
id name amount cost 1 Alice 150 NULL
id=1id=1
的行被整行更新,未设置的
costcost
由
18.0018.00
变为 NULL。只想更新部分列时,通过
PartialUpdateColumnsPartialUpdateColumns
指定要更新的列。例如设置
PartialUpdateColumns: []string{"id", "amount"}PartialUpdateColumns: []string{"id", "amount"}
后写入
id=2, amount=99id=2, amount=99
,结果为
2, Bob, 99, 12.502, Bob, 99, 12.50
,未列出的
namename
和
costcost
保持原值。
写入选项
字段 说明 TableTable
目标表名 OperationOperation
写入模式 PartitionSpecPartitionSpec
写入指定分区,例如 dt=20261113dt=20261113
RecordKeysRecordKeys
UPSERTUPSERT
模式的记录键PartialUpdateColumnsPartialUpdateColumns
UPSERTUPSERT
模式只更新这些列;留空时更新所有列LoadUriLoadUri
本地临时 Parquet 文件的目录,默认使用系统临时目录 MaxRowsPerFileMaxRowsPerFile
单个文件的最大行数,默认 100 万 MaxBytesPerFileMaxBytesPerFile
单个文件的最大字节数,默认 64MB
设置列值
RowRow
按列名设置值:
方法 对应的列类型 SetTinyIntSetTinyInt
、SetSmallIntSetSmallInt
、SetIntSetInt
、SetBigintSetBigint
TINYINTTINYINT
、SMALLINTSMALLINT
、INTINT
、BIGINTBIGINT
SetFloatSetFloat
、SetDoubleSetDouble
FLOATFLOAT
、DOUBLEDOUBLE
SetDecimalSetDecimal
DECIMALDECIMAL
,值为 github.com/shopspring/decimalgithub.com/shopspring/decimal
的 decimal.Decimaldecimal.Decimal
SetBooleanSetBoolean
BOOLEANBOOLEAN
SetStringSetString
STRINGSTRING
SetDateSetDate
DATEDATE
,值为字符串,例如 2026-01-012026-01-01
SetTimestampSetTimestamp
TIMESTAMPTIMESTAMP
,值为字符串,例如 2026-01-01 00:00:002026-01-01 00:00:00
兼容版本的接口
Arrow v12 兼容版(
-arrow12-arrow12
)用
OpenWriterOpenWriter
创建 Writer,并且需要先关闭 Writer 再关闭 stream:
writer, err := stream.OpenWriter(0)
if err != nil {
stream.Abort()
return err
}
row := writer.CreateRow()
if err := row.SetBigint("id", int64(1)); err != nil {
stream.Abort()
return err
}
if err := writer.WriteRow(row); err != nil {
stream.Abort()
return err
}
// 先关闭 Writer 上传数据,再关闭 stream 提交
if err := writer.Close(); err != nil {
stream.Abort()
return err
}
return stream.Close()
v0.0.20-arrow12v0.0.20-arrow12
写入这一行后,
doc_go_ordersdoc_go_orders
中
idid
为 1 的行的
namename
、
amountamount
、
costcost
均为 NULL。
无 Arrow 版(
-csv-csv
)不支持 Bulkload。从
v0.0.12-csvv0.0.12-csv
开始,调用时返回以下错误,不会写入任何数据:
goclickzetta: BulkLoad is not supported in the text-result-only (-csv) build because it has no Arrow dependency; use INSERT statements or the main version