批量写入数据(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()
成功返回后可见
ExecContext
ExecContext
执行 DML
低频小批量 DMLSQL 执行成功后可见
COPY INTO
COPY INTO
数据已在对象存储SQL 执行成功后可见

写入数据

示例写入 前置准备 中创建的

doc_go_orders
doc_go_orders
表(
id BIGINT NOT NULL
id BIGINT NOT NULL
、
name STRING
name STRING
、
amount INT
amount INT
、
cost DECIMAL(10, 2)
cost DECIMAL(10, 2)
)。

CreateBulkloadStream
CreateBulkloadStream
是
*goclickzetta.ClickzettaConn
*goclickzetta.ClickzettaConn
的方法。通过
database/sql
database/sql
使用时,先用
db.Conn
db.Conn
取得专用连接,再用
Raw
Raw
访问驱动连接:

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 >= 1000
SELECT count(*), min(id), max(id), sum(cost) FROM doc_go_orders WHERE id >= 1000
的结果:

count(*)min(id)max(id)sum(cost)
100010001999749250.00

示例没有设置

amount
amount
列,
SELECT * FROM doc_go_orders WHERE id IN (1000, 1001, 1999) ORDER BY id
SELECT * FROM doc_go_orders WHERE id IN (1000, 1001, 1999) ORDER BY id
的结果:

idnameamountcost
1000order_1000NULL0.00
1001order_1001NULL1.50
1999order_1999NULL1498.50

未设置的列写入 NULL,向

Set*
Set*
方法传入
nil
nil
也写入 NULL。空字符串按空字符串写入,不会转为 NULL。

以下情况会返回错误:

  • Set*
    Set*
    方法设置了目标表中不存在的列,或传入的值与列类型不匹配:
    Set*
    Set*
    返回错误,例如
    table doc_go_orders has no column "nmae"
    table doc_go_orders has no column "nmae"
    。
  • NOT NULL
    NOT NULL
    列未设置值或设置为
    nil
    nil
    :
    WriteRow
    WriteRow
    返回错误,例如
    column "id" of table doc_go_orders is NOT NULL but has no value
    column "id" of table doc_go_orders is NOT NULL but has no value
    ,该行不会写入。

写入失败时调用

stream.Abort()
stream.Abort()
放弃本次写入,SDK 会清理本地和已上传的临时文件,数据不会提交。

写入模式

Operation
Operation
说明
APPEND
APPEND
追加写入,默认模式
OVERWRITE
OVERWRITE
覆盖写入,清空目标表中原有数据
UPSERT
UPSERT
按记录键更新已有行并插入新行

stream, err := cz.CreateBulkloadStream(goclickzetta.BulkloadOptions{ Table: "doc_go_orders", Operation: goclickzetta.UPSERT, RecordKeys: []string{"id"}, })

用这个 stream 写入一行

id=1, name="Alice", amount=150
id=1, name="Alice", amount=150
(不设置
cost
cost
)后,
SELECT * FROM doc_go_orders WHERE id = 1
SELECT * FROM doc_go_orders WHERE id = 1
的结果:

idnameamountcost
1Alice150NULL

id=1
id=1
的行被整行更新,未设置的
cost
cost
由
18.00
18.00
变为 NULL。只想更新部分列时,通过
PartialUpdateColumns
PartialUpdateColumns
指定要更新的列。例如设置
PartialUpdateColumns: []string{"id", "amount"}
PartialUpdateColumns: []string{"id", "amount"}
后写入
id=2, amount=99
id=2, amount=99
,结果为
2, Bob, 99, 12.50
2, Bob, 99, 12.50
,未列出的
name
name
和
cost
cost
保持原值。

写入选项

字段说明
Table
Table
目标表名
Operation
Operation
写入模式
PartitionSpec
PartitionSpec
写入指定分区,例如
dt=20261113
dt=20261113
RecordKeys
RecordKeys
UPSERT
UPSERT
模式的记录键
PartialUpdateColumns
PartialUpdateColumns
UPSERT
UPSERT
模式只更新这些列;留空时更新所有列
LoadUri
LoadUri
本地临时 Parquet 文件的目录,默认使用系统临时目录
MaxRowsPerFile
MaxRowsPerFile
单个文件的最大行数,默认 100 万
MaxBytesPerFile
MaxBytesPerFile
单个文件的最大字节数,默认 64MB

设置列值

Row
Row
按列名设置值:

方法对应的列类型
SetTinyInt
SetTinyInt
、
SetSmallInt
SetSmallInt
、
SetInt
SetInt
、
SetBigint
SetBigint
TINYINT
TINYINT
、
SMALLINT
SMALLINT
、
INT
INT
、
BIGINT
BIGINT
SetFloat
SetFloat
、
SetDouble
SetDouble
FLOAT
FLOAT
、
DOUBLE
DOUBLE
SetDecimal
SetDecimal
DECIMAL
DECIMAL
,值为
github.com/shopspring/decimal
github.com/shopspring/decimal
的
decimal.Decimal
decimal.Decimal
SetBoolean
SetBoolean
BOOLEAN
BOOLEAN
SetString
SetString
STRING
STRING
SetDate
SetDate
DATE
DATE
,值为字符串,例如
2026-01-01
2026-01-01
SetTimestamp
SetTimestamp
TIMESTAMP
TIMESTAMP
,值为字符串,例如
2026-01-01 00:00:00
2026-01-01 00:00:00

兼容版本的接口

Arrow v12 兼容版(

-arrow12
-arrow12
)用
OpenWriter
OpenWriter
创建 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-arrow12
v0.0.20-arrow12
写入这一行后,
doc_go_orders
doc_go_orders
中
id
id
为 1 的行的
name
name
、
amount
amount
、
cost
cost
均为 NULL。

无 Arrow 版(

-csv
-csv
)不支持 Bulkload。从
v0.0.12-csv
v0.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

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