KingbaseES数据导入导出与CSV交换实践及常见问题

引言

上一篇文章关注的是数据库运行状态：当 SQL 卡住、事务未提交、锁等待出现时，我们如何定位问题。本文换一个方向，讨论数据库和外部文件之间的数据交换。

在实际工作中，数据导入导出非常常见：

把商品清单导入数据库
把订单报表导出给业务人员
把查询结果保存为 CSV
把测试数据批量装入表

本文会基于 kb_shop 演示 CSV 导出和导入。相比手工一条条写 INSERT，文件导入导出更适合批量数据处理。

在数据库迁移和日常运维中，CSV 是最常见的交换格式之一。它结构简单，便于人工查看，也容易被脚本、表格工具和其他系统读取。电科金仓 KingbaseES 提供 COPY 和客户端侧 \copy 能力，既可以服务端读写文件，也可以通过 ksql 在客户端机器上完成文件交换。本文选择 \copy，更贴近 Windows 本地实操场景。

需要强调的是，CSV 交换不等同于完整迁移方案。它适合小批量数据、报表导出、测试数据准备和临时核对；如果是完整业务系统迁移，还要结合迁移评估、数据校验、对象兼容和应用改造等工作。本文把 CSV 作为入门场景，是为了先掌握最基础、最容易复现的数据进出能力。

COPY 和 \copy 的区别

在 ksql 中，经常会看到两个相似命令：

本文使用 Windows 本地环境，数据库和客户端都在同一台机器上，但仍推荐初学者优先使用 \copy。因为它更符合“我在当前 Windows 命令行里读写本机文件”的直觉。

这个差异对排错很关键。如果使用服务端 COPY，文件路径必须是数据库服务端能访问的路径；如果使用 \copy，路径则由当前 ksql 客户端访问。很多“文件找不到”的问题，本质上都是没有分清命令执行位置。截图中导出的文件位于 Windows 本机目录，正好对应 \copy 的客户端路径语义。

一、准备导出目录

建议准备一个专门目录保存 CSV：

D:\Tools\Kingbase\data

如果目录不存在，可以在 Windows 命令行创建：

mkdir D:\Tools\Kingbase\data

然后连接数据库：

cd /d D:\Tools\Kingbase\ES\Server\bin
ksql -U system -d kb_shop -h localhost -p 54321

二、导出商品数据到 CSV

咱们先去查一下商品表里面的数据：

SELECT product_code,
       product_name,
       category,
       unit_price,
       stock_qty,
       status
FROM inventory.product
ORDER BY product_id;

等确认里面确实是有数据的，接着咱们就可以把它导出来了：

\copy (SELECT product_code, product_name, category, unit_price, stock_qty, status FROM inventory.product ORDER BY product_id) TO 'D:/Tools/Kingbase/data/product_export.csv' WITH CSV HEADER ENCODING 'UTF8';

这块有两个小细节你得留意一下：

• \copy 这东西，它其实是 ksql 客户端的元命令，也就是说它根本不是普通的 SQL。那么你在执行的时候，必须得把整条 \copy ... 命令全放在同一行里输进去。千万别像写 SELECT 那样换行粘贴，不然的话很容易出问题。出啥问题呢？往往会报 \copy: parse error at end of line 这种错，或者给你报在 ) 附近有语法错误。
• 路径里面咱们用的是正斜杠，为啥这么搞呢？其实就是为了少惹点麻烦，避免 Windows 那个反斜杠给你带来转义上的问题。

导出弄完之后，你可以打开 PowerShell，用 UTF-8 的编码去看一下：

Get-Content -Encoding UTF8 D:\Tools\Kingbase\data\product_export.csv

那如果你用的是老式的 cmd 窗口，敲 type 命令去看的话，中文往往仅仅只是会显示成乱码。那为什么会这样呢？原因就在于控制台默认的代码页它不是 UTF-8。那你得先切换一下代码页，接着再看：

chcp 65001
type D:\Tools\Kingbase\data\product_export.csv

这里出现乱码的情况，通常来说仅仅是命令行显示编码不对导致的。这可不代表你导出的 CSV 文件内容就坏了。后续你要是用 \copy ... FROM ... ENCODING 'UTF8' 再导进去的话，只要文件本身是 UTF-8 的，导进去是没问题的。

所以啊，你光看到 COPY 5 这种提示还不算完，还得去确认文件是不是真能被正确读出来。同样的道理，看到命令行乱码，你也别立马就觉得导出失败了。你得搞清楚，文件编码和控制台显示编码这俩它不是一回事，得区分开。

三、创建导入测试表

为了不把咱们正式的商品表给搞坏了，那么咱们就建一张专门用来测试导入的表：

CREATE TABLE IF NOT EXISTS inventory.product_import_stage (
    product_code VARCHAR(40),
    product_name VARCHAR(120),
    category VARCHAR(50),
    unit_price NUMERIC(12,2),
    stock_qty INT,
    status VARCHAR(20)
);

建完之后，把旧数据清一下：

TRUNCATE TABLE inventory.product_import_stage;

这个表名叫 stage，其实也就是暂存表的意思。在实际做项目的情况里，你导入外面的数据，通常来说都不会直接往正式的业务表里写。为啥呢？一般都是先进暂存表，等你校验没问题了，然后再往正式表里合并。

四、从 CSV 导入数据

\copy inventory.product_import_stage (product_code, product_name, category, unit_price, stock_qty, status) FROM 'D:/Tools/Kingbase/data/product_export.csv' WITH CSV HEADER ENCODING 'UTF8';

导进去之后，咱们查一下看看：

SELECT product_code,
       product_name,
       category,
       unit_price,
       stock_qty,
       status
FROM inventory.product_import_stage
ORDER BY product_code;

要是能查到商品数据，那就说明 CSV 导入这事儿成了。

咱们这里导进去的，其实就是前面刚导出来的商品数据。也就是说，结果按理说得跟源表一模一样才对。不过在真实的项目里面，导完之后你还得再核对一些东西。比如行数对不对啊，主键或者业务编码有没有缺啊，金额字段对不对啊，还有中文字段有没有乱码啊。你看截图里面，商品名称啊、分类啊、价格还有库存这些都能正常显示，这就说明咱们从导出到导入的这根线，其实已经跑通了。

五、导出订单报表

视图这东西，其实拿来做导出的数据源是非常合适的。比如咱们要导出订单列表：

\copy (SELECT order_no, customer_name, order_status_name, total_amount, created_at FROM report.v_order_list ORDER BY created_at DESC) TO 'D:/Tools/Kingbase/data/order_report.csv' WITH CSV HEADER ENCODING 'UTF8';

这条命令刚好就能体现出前面咱们搞视图的价值了。啥价值呢？就是导出报表的时候，你根本不需要再去重新写那些复杂的 JOIN，直接查视图就行了，多省事。

把视图当成导出源的话，其实还有个好处。那就是导出文件里面的字段口径，它就更加稳定了。看报表的人，他不需要去懂底层的四张表是怎么连起来的，只要用 report.v_order_list，就能拿到整理好的订单列表。这其实也就呼应了咱们第九篇讲的视图封装：数据库对象你设计得越清楚，后面做数据交换往往仅仅只是越简单而已。

六、导入前的数据校验

导入暂存表后，先做校验：

SELECT COUNT(*) AS total_rows
FROM inventory.product_import_stage;

检查价格和库存：

SELECT *
FROM inventory.product_import_stage
WHERE unit_price < 0
   OR stock_qty < 0;

检查商品编码是否为空：

SELECT *
FROM inventory.product_import_stage
WHERE product_code IS NULL
   OR product_code = '';

这些校验能避免脏数据直接进入正式业务表。

七、导入导出中的数据治理思路

导入导出不是简单地把文件读进来或写出去，它同样涉及数据治理。尤其是外部 CSV 文件，来源可能是人工编辑、第三方系统导出或历史数据整理，质量不一定可靠。

比较稳妥的流程是：

外部 CSV 文件
  -> 暂存表
  -> 数据校验
  -> 异常数据修正
  -> 写入正式表
  -> 抽样核对

本文创建的 product_import_stage 就是暂存表思路。暂存表的好处是可以先接住外部数据，不直接污染正式业务表。导入后通过 SQL 检查价格、库存、编码是否异常，再决定是否进入正式表。

如果要把暂存数据合并到正式商品表，可以先查询差异：

SELECT s.product_code,
       s.product_name,
       s.unit_price,
       s.stock_qty
FROM inventory.product_import_stage s
LEFT JOIN inventory.product p
  ON s.product_code = p.product_code
WHERE p.product_code IS NULL;

这条 SQL 可以找出暂存表中存在、正式商品表中不存在的新商品。真实项目中，通常会把新增、更新、异常数据分开处理，而不是一条 SQL 全部写入。

因此，CSV 导入导出章节不能只看命令是否成功，还要看数据进入数据库后的治理流程。暂存表、校验 SQL、异常数据处理和正式表合并，才构成一个更稳妥的数据交换闭环。本文虽然使用小样例，但流程和思路可以迁移到更大的业务数据导入场景。

八、常见问题排查

问题 1：\copy 报 parse error 或语法错误

如果把 \copy ( 单独放在一行执行，可能会看到类似错误：

\copy: parse error at end of line
ERROR: 语法错误 在 ")" 或附近的

原因是 \copy 是 ksql 客户端命令，不是数据库服务端 SQL。它不会像普通 SELECT 那样等待多行补齐。处理方法是：把整条 \copy 命令写成一行后再执行。

正确写法示例：

\copy (SELECT product_code, product_name, category, unit_price, stock_qty, status FROM inventory.product ORDER BY product_id) TO 'D:/Tools/Kingbase/data/product_export.csv' WITH CSV HEADER ENCODING 'UTF8';

问题 2：文件路径找不到

确认路径存在：

dir D:\Tools\Kingbase\data

在 \copy 中建议使用：

D:/Tools/Kingbase/data/product_export.csv

问题 3：中文乱码

如果 type D:\Tools\Kingbase\data\product_export.csv 打印出来是乱码，先不要判断为导出失败。常见原因是 CSV 文件按 UTF-8 导出，但当前 Windows cmd 代码页不是 UTF-8。

可以改用 PowerShell 查看：

Get-Content -Encoding UTF8 D:\Tools\Kingbase\data\product_export.csv

或者在 cmd 中先执行：

chcp 65001
type D:\Tools\Kingbase\data\product_export.csv

导出导入命令中仍建议指定：

ENCODING 'UTF8'

同时检查 CSV 文件打开工具是否按 UTF-8 识别。乱码发生在“查看文件”的环节时，不等于文件内容或 \copy 导出格式有问题。

问题 4：导入时报字段数量不匹配

确认 CSV 表头和导入字段顺序一致。WITH CSV HEADER 表示第一行是表头，不作为数据导入。

九、本文小结

本文承接第十二篇运行诊断，进入数据交换实践。我们使用 \copy 完成商品数据导出、暂存表导入、订单报表导出和导入前校验。

本文掌握了：

\copy TO
\copy FROM
CSV HEADER
ENCODING UTF8
暂存表 stage
导入前校验
视图导出报表

下一篇会继续进入数据保护方向，讲逻辑备份和恢复。导入导出解决的是数据交换，备份恢复解决的是数据安全，两者都是数据库日常管理中不可缺少的能力。

参考依据

• 电科金仓 KingbaseES 工具参考手册：提供命令行工具和数据装载相关能力说明。
• 电科金仓 KingbaseES 数据库参考手册：支持 COPY、CSV、查询导出和表数据导入。

总结 

到此这篇关于KingbaseES数据导入导出与CSV交换实践及常见问题的文章就介绍到这了,更多相关KingbaseES导入导出与CSV交换内容请搜索脚本之家以前的文章或继续浏览下面的相关文章希望大家以后多多支持脚本之家！

最新评论