tsdb-cli 的 import 命令把 TSDB 共享版导出的 CSV 数据导入 TSDB 专享版，无需理解导出格式或自行编写转换脚本。导入分为两个独立步骤：先用 import analyze 分析完整输入并生成结构文件，确认目标表结构后再用 import 写入数据。

该能力需要 tsdb-cli 3.2.0 或更高版本，安装与升级见下载与安装。

准备输入数据

TSDB 共享版的手动导出和自动导出都把数据写入用户自己的 BOS Bucket，文件格式为 CSV，数据量较大时会拆分为多个文件。导出操作见共享版文档的数据管理。

导入支持三类输入，通过 -f（即 --file）指定：

本地目录和 BOS 前缀只处理后缀为小写 .csv 的普通文件或对象，符号链接、非 CSV 和空文件打印告警后跳过。本地目录中没有可处理的 CSV 时命令失败；BOS 前缀没有匹配到任何对象时命令失败。

建议在导入前创建目标数据库并设置保留期，见管理 Database 与 Retention。

导入本地 CSV

以目录为例：

1# 分析完整输入并生成结构文件
2tsdb-cli import analyze -f ./tsdb-export/ --output schema.json
3
4# 确认结构文件后执行导入
5tsdb-cli import -d mydb -f ./tsdb-export/ --schema-file schema.json

单个 CSV 文件使用相同的两步流程：

1tsdb-cli import analyze -f ./tsdb-export/weather-0.csv --output schema.json
2tsdb-cli import -d mydb -f ./tsdb-export/weather-0.csv --schema-file schema.json

从 BOS 前缀导入

读取 BOS 需要访问密钥和 region 级 endpoint。凭证由您在执行导入时提供，TSDB 专享版服务端不接触也不保存您的 BOS 凭证。

1export BOS_ACCESS_KEY_ID='<AK>'
2export BOS_SECRET_ACCESS_KEY='<SK>'
3export BOS_ENDPOINT='bj.bcebos.com'
4
5tsdb-cli import analyze -f bos://my-bucket/tsdb-export/ --output schema.json
6tsdb-cli import -d mydb -f bos://my-bucket/tsdb-export/ --schema-file schema.json

BOS 前缀按对象名字典序分页流式读取，不需要先把全部对象下载到本地。凭证、权限、网络连接和响应超时错误都会结束命令，并给出对应类别的提示。

请优先使用环境变量传递凭证。通过 --bos-secret-access-key 在命令行传入时，密钥会保留在 Shell 历史和进程参数中，可能被本机的其他用户读取。

参数

共同参数：

import analyze 参数：

正式 import 参数：

CSV 与目标表的对应关系

CSV 至少包含一个 Field 列。表头、表名、列名、timestamp、类型或字段值无法解析，以及同一张表的同名 Field 同时出现 int64 和 float64 时，命令报告对应的输入项和 CSV 行号并中止。

一个 CSV 可以包含多个 metric，每个 metric 导入为一张独立的表；同名 Field 在不同表中的类型互不影响。例如下面的输入会导入 temperature 和 pm25 两张表，value 分别为 int64 和 float64：

1metric,timestamp,value:Number,city,zip_code,latitude,longitude
2temperature,1420070400000,21,beijing,100000,39.9,116.4
3pm25,1420070400000,85.5,beijing,100000,39.9,116.4

结构文件

import analyze 读取完整输入，分析成功后一次性写出结构文件，目标数据库保持原状。文件记录每张目标表的完整 Tag 与 Field 集合，其中 series_key 的数组顺序就是该表的 series key 顺序，由分析步骤按各 Tag 的估算区分度推荐。series key 顺序在建表时确定，之后不可调整；Tag 顺序对查询的影响见数据模型与权限。

1{
2  "version": 1,
3  "format": "iot-tsdb",
4  "tables": [
5    {
6      "name": "temperature",
7      "series_key": ["latitude", "longitude", "zip_code", "city"],
8      "fields": [
9        { "name": "value", "type": "int64" }
10      ]
11    },
12    {
13      "name": "pm25",
14      "series_key": ["latitude", "longitude", "zip_code", "city"],
15      "fields": [
16        { "name": "value", "type": "float64" }
17      ]
18    }
19  ]
20}

结构文件是分析步骤的产物，请原样传给正式导入，不要手工修改。文件内容会直接决定目标表结构，修改后可能建出与预期不同的表，也可能因为与输入冲突导致导入失败。如果已经按错误的结构文件建表，需要删除目标表，再用重新分析得到的文件导入。

结构文件只描述表结构。目标数据库仍由 -d 指定，输入位置和 BOS 凭证仍由命令参数或环境变量提供。

重复导入与结构冲突

正式导入在确认第一个有效输入后准备目标表：

• 目标表不存在时，按结构文件创建。
• 目标表已存在且结构一致时，继续导入，既有表的保留期不变。
• 目标表已存在但结构不一致时，命令在写入任何数据前中止，并给出数据库名、表名和第一个结构差异。

导入过程中发生枚举、读取或写入错误时，已经成功写入的批次会保留。修正输入或结构冲突后重新执行分析和导入。

导入后验证

1# 确认目标表已创建
2tsdb-cli query -d mydb 'SHOW TABLES'
3
4# 按时间范围抽查数据
5tsdb-cli query -d mydb \
6  "SELECT * FROM temperature WHERE time >= '2015-01-01T00:00:00Z' AND time < '2015-01-02T00:00:00Z' ORDER BY time LIMIT 10"

刚完成大批量导入时，请按时间范围和返回行数抽查，不要对整张表执行没有过滤条件的全量扫描查询。

能力边界

• 导入不改变共享版的导出格式，也不提供从专享版反向导出到共享版的能力。
• 导入前的数据清洗、去重和跨库聚合不在导入命令的范围内，请在导出侧或导入完成后另行处理。
• 输入存在但全部为空或全部被跳过时，分析步骤报告没有可分析的数据并保留原结构文件，正式导入的成功结果为 0 条。