数据导入工具

sdbimprt 是 SequoiaDB 数据导入工具，可以将 JSON 格式或 CSV 格式的数据导入到 SequoiaDB 数据库中。

JSON

JSON格式的记录必须符合JSON的定义，以左右花括号作为记录的分界符，并且字符串类型的数据必须包含在两个双引号之间，转义字符为反斜杠“\”。

CSV

CSV（Comma Separated Value）格式以逗号分隔数值。默认情况下记录以换行符分隔，字段以逗号分隔。用户能够指定字符串分隔符、字段分隔符以及记录分隔符。

分隔符

类型	默认值
字符串分隔符	"（双引号）
字段分隔符	,（逗号）
记录分隔符	'\n'（换行符）

Note:

• 分隔符可以使用 ASCII 码中的不可见字符，通过转义字符“\”输入 ASCII 码的十进制数值（0 ~ 127），例如“\30”。回车符、换行符、制表符、转义字符“\”可以直接使用“\r”，“\n”，“\t”，“\\”。
• 可以使用 UTF-8 字符作为分隔符。
• 可以使用多个字符作为分隔符。

CSV类型

类型	别名	说明
int	integer	十进制整型，取值范围为 -2147483648 ~ 2147483647
long		十进制长整型，取值范围 -9223372036854775808 ~ 9223372036854775807
double		双精度浮点型，取值范围为 1.79E +/- 308 (15 位)
decimal		高精度数，范围为小数点前最高 131072 位;小数点后最高 16383 位。 可以指定精度，如 decimal(18, 6)
number		数值类型，自动判断数值的具体类型（int，long，double，decimal）
bool	boolean	布尔型，取值可以为 true，false，t，f，yes，no，y 或 n，不区分大小写
string		字符串。 可以指定长度，如 string(5, 30)
null		空值
oid		OID 类型，长度必须为 24 个字符，不支持类型自动判断
date		日期类型，取值范围为 0000-01-01 ~ 9999-12-31，不支持类型自动判断
autodate		日期类型，取值范围为 0000-01-01 ~ 9999-12-31，不支持类型自动判断
timestamp		时间戳类型，取值范围为 1902-01-01-00.00.00.000000 ~ 2037-12-31-23.59.59.999999，不支持类型自动判断。 可以指定格式，如timestamp("YYYY-MM-DD HH:mm:ss")
autotimestamp		时间戳类型，取值范围为 1902-01-01-00.00.00.000000 ~ 2037-12-31-23.59.59.999999，不支持类型自动判断
binary		二进制类型，使用 base64 编码，不支持类型自动判断
regex		正则表达式类型，不支持类型自动判断
skip		忽略指定的列，该列的数据不导入到数据库

Note:

• int、long、double 支持以‘#’开头的数字，例如“#123.456”。
• double 支持科学计数法，例如“1.23e-4”，“-1.23E+4”。
• double 支持忽略小数点前的“0”，例如“.123”。
• 在自动判断类型时，整数超过 long 的范围，浮点数超过 double 的范围，以及浮点数总位数超过 15 位或小数位超过 6 位时，类型判断为 decimal。
• autodate 类型支持使用整数，表示自 1970-01-01-00.00.00.000000 以来的毫秒数, 取值范围为 long 类型的范围。
• autotimestamp 类型支持使用整数，表示自 1970-01-01-00.00.00.000000 以来的毫秒数，取值范围为 -2147414400000 ~ 2147443199000。

CSV类型自动判断

在不指定 CSV 字段类型时，导入工具会自动判断类型。其中 oid、date、timestamp、binary、regex 不支持自动类型判断，会被识别为 string 类型。整数超过 long 的范围，浮点数超过 double 的范围，以及浮点数总位数超过 15 位或小数位超过 6 位时，类型判断为 decimal。

例如：

CSV 数据	判断类型	实际数据
123	int	123
123.	int	123
+123	int	123
-123	int	-123
0123	int	123
#-123.	int	-123
2147483648	long	2147483648
123.1	double	123.1
.123	double	0.123
9223372036854775808	decimal	9223372036854775808
true	bool	true
false	bool	false
"123"	string	"123"
123a	string	"123a"
"true"	string	"true"
"false"	string	"false"
"null"	string	"null"
null	null	null

CSV类型转换

在指定 CSV 字段类型时，导入工具会将字段转换为指定的类型。如果字段的实际类型不是指定的类型，则转换可能失败。具体参考下表，最左边一列是指定的类型，Y 表示可以转换，N 表示不能转换。

指定类型 \ 实际类型	int	long	double	decimal	bool	string	null	oid	date	timestamp	binary	regex
int	Y	可能溢出	可能丢失精度	可能丢失精度	Y	支持数值字符串	Y	N	N	N	N	N
long	Y	Y	可能丢失精度	可能丢失精度	Y	支持数值字符串	Y	N	N	N	N	N
double	Y	Y	Y	可能丢失精度	N	支持数值字符串	Y	N	N	N	N	N
decimal	Y	Y	Y	Y	N	支持数值字符串	Y	N	N	N	N	N
number	Y	Y	Y	Y	Y	支持数值字符串	Y	N	N	N	N	N
bool	Y	Y	N	N	Y	支持 bool 字符串	Y	N	N	N	N	N
string	Y	Y	Y	Y	Y	Y	Y	Y	Y	Y	Y	Y
null	Y	Y	Y	Y	Y	Y	Y	Y	Y	Y	Y	Y
oid	N	N	N	N	N	支持 OID 字符串	N	Y	N	N	N	N
date	Y	Y	N	N	N	支持 date 字符串	Y	N	Y	Y	N	N
timestamp	Y	Y	N	N	N	支持 timestamp 字符串	Y	N	Y	Y	N	N
binary	N	N	N	N	N	支持 binary 字符串	N	N	N	N	Y	N
regex	N	N	N	N	N	支持 regex 字符串	N	N	N	N	N	Y

Note:

• 指定类型为 bool，实际类型为 int、long 时，0 值转为 false，非 0 值转为 true。
• 指定类型为 int、long，实际类型为 bool 时，true、t、yes 或 y 转为 1，false、f、no 或 n 转为 0。
• 参数 --cast 可以指定数值转换时是否允许精度损失或数值溢出。

命令选项

通用选项

选项	缩写	说明
--help	-h	显示帮助信息
--version	-V	显示版本号
--hosts		指定主机地址（hostname:svcname），用“,”分隔多个地址，默认值为 localhost:11810
--user	-u	指定数据库用户名
--password	-w	指定数据库用户密码，如果不使用该参数指定密码，工具会通过交互式界面提示用户输入密码
--cipher		是否使用密文模式输入密码，默认为 false，不使用密文模式输入密码。关于密文模式的介绍，详细可参考密码管理
--token		指定加密令牌
--cipherfile		指定密文文件路径，默认值为 ~/sequoiadb/passwd
--csname	-c	指定集合空间的名字
--clname	-l	指定集合的名字
--errorstop		如果遇到解析错误就停止，默认值为 false，解析错误后不停止
--ssl		使用 SSL 连接，默认值为 false，不使用 SSL 连接
--verbose	-v	显示详细的执行信息

输入选项

选项	缩写	说明
--file		要导入的数据文件的名称，使用“,”分隔多个文件或目录。 如果 --file 和 --exec 都没有指定，则从标准输入读取数据
--exec		执行外部程序来获取数据，外部程序必须将数据输出到标准输出
--type		导入数据格式，可以是 csv 或 json，默认为 csv
--linepriority		指定分隔符的优先级，默认 auto。 auto：当 type 为 csv 时，记录分隔符最高优先级；当 type 为 json 时，字符串分隔符最高优先级。 true：记录分隔符 > 字符串分隔符 > 字段分隔符。 false：字符串分隔符 > 记录分隔符 > 字段分隔符。
--delrecord	-r	指定记录分隔符，默认值为换行符'\n'
--force		如果数据中有非 UTF-8 的字符，强制导入数据，默认为 false，不强制导入

Note:

• --linepriority 参数需要被特别关注，如果设置不当，可能会导入数据失败。当记录中包含记录分隔符，并且 --linepriority 为 true 时，工具会优先按照记录分隔符解析，而导致导入失败。例如：如果记录为 {"name": "Mike\n"}，应当设置 --linepriority 为 false。
• 使用 --file 参数指定文件或目录时，重复出现的文件会被忽略。
• 使用 --hosts 指定地址时，重复出现的地址会被忽略。

导入选项

选项	缩写	说明
--insertnum	-n	指定每次导入的记录数，取值范围为 1 ~ 100000，默认值为 1000。
--jobs	-j	指定导入连接数（每个连接一个线程），取值范围为 1 ~ 1000，默认值为 4。
--parsers		指定解析任务数（每个任务一个线程），取值范围为 1 ~ 1000，默认值为 4。
--coord		指定是否自动查找协调节点，默认值为 true，自动查找协调节点。
--sharding		指定是否按分区信息重新打包记录，默认值为 true，按照分区信息重新打包信息。
--transaction		指定导入数据时是否开启事务，默认为 false，不开启事务。 注意：此功能需要服务端开启事务。
--allowkeydup		指定是否允许唯一索引的键出现重复时忽略错误继续导入，默认值为 true，忽略错误继续导入。
--replacekeydup		指定唯一索引键重复时替换记录，默认值为 false。

Note:
不能同时设置 --allowkeydup 参数和 --replacekeydup 参数为 true。
--replacekeydup 参数指定 true 时，--allowkeydup 参数默认为 false。

JSON选项

选项	缩写	说明
--unicode		是否转义 Unicode 字符编码（\uXXXX），默认为 true，自动转移 Unicode 字符编码
--decimalto		decimal 类型强制转换，默认 ""。 ""：不转换，保留 decimal 类型。 double：强制转换成 double 类型，可能会发生精度丢失。 string：强制转换成 string 类型。

CSV选项

选项	缩写	说明
--delchar	-a	指定字符串分隔符，默认值为双引号'"'
--delfield	-e	指定字段分隔符,默认值为逗号','
--fields		指定导入数据的字段名、类型、默认值
--datefmt		指定日期格式，默认为 YYYY-MM-DD
--timestampfmt		指定时间戳格式，默认为 YYYY-MM-DD-HH.mm.ss.ffffff
--trim		删除字符串左右两侧的空格（包括 ASCII 空格和 UTF-8 全角空格）， 取值可以是 no、right、left 或 both， 默认值为 no
--headerline		指定导入数据首行是否作为字段名。默认值为 false，导入数据首行不作为字段名
--sparse		指定导入数据中，数据的列数比字段的列数多，是否自动添加字段名。默认值为 true，字段名按 filed1、field2 顺序增加
--extra		指定导入数据中，字段的列数比数据的列数多，是否自动添加 null 值。默认值为 false，不自动添加
--cast		指定是否允许数值类型转换时丢失精度或数值溢出。默认值为 false，不允许丢失精度或者数值溢出
--strictfieldnum		指定是否严格限制记录的字段数与定义的字段数一致，默认值为 false，不严格限制
--checkdelimeter		是否严格校验分隔符，默认为 true。 true：禁止字符分隔符、字段分隔符、记录分隔符互相包含； false：允许字符分隔符、字段分隔符、记录分隔符互相包含。

Note:

• fields 语法：fieldName [type [default <value>], ...]
  • type 支持所有的 CSV 类型
  • type 可不写，由导入工具自动判断
  • 指定字段可以用命令行指定，也可以在导入文件的首行指定。如果在命令行指定了 --fields，并且 --headerline 设为 true，导入工具将会优先使用命令行指定字段并且跳过导入文件的首行
  • 字段名不能以“$”开头，中间不能有“.”，不能有不可见字符，包含空格时需要将字段名包含在单引号或双引号中
  • decimal 类型可以指定精度，如 decimal(18, 6)
  • 例如：--fields='name string default "Jack", age int default 18, phone'
• string 字符串，可以指定最小长度和最大长度，最大长度如果为 0，表示不设限制，语法：string([min length,][max length[,STRICT]])
  • 指定最大长度：当值超过最大长度则截断。如：string(128) 指定最大长度为 128 个字符，超出则截断。
    当指定 STRICT 则不截断并输出到 rec 文件，如：string(32,STRICT)
  • 指定最小长度：当值的长度不满足最小长度时，使用默认值代替；如果没有默认值，则用 null 代替。如：string(10, 0) 指定最小长度为 10 个字符，少于 10 个字符的字段用 null 代替。
    当指定 STRICT 则使用默认值代替；如果没有默认值，则不导入记录并输出到 rec 文件，如：string(10,0,STRICT)
  • 指定最大长度和最小长度：如：string(10, 128) 指定最小长度为10个字符，最大长度为128个字符
  • 默认值长度不可以小于最小长度；如果默认值长度大于最大长度，则会根据最大长度截断。如：key string(2, 4) default address 指定最大长度为 4 个字符，默认值 address 会截断为 addr
• datefmt 格式包括年、月、日、通配符以及特定字符
  • 年：YYYY
  • 月：MM
  • 日：DD
  • 通配符：*
  • 特定字符：任意 UTF-8 字符
  • 其中年、月、日必须是整数，并且符合日期类型的范围
  • 指定通配符时，日期字段上对应的位置可以为任意字符
  • 指定特定字符时，日期字段上对应的位置必须为该指定字符
  • 例如需要导入的数据中日期格式为“3/15, 2015”，则设置 --datefmt="MM/DD, YYYY" 与该格式匹配
• timestamp 格式包括年、月、日、时、分、秒、微秒或毫秒、通配符以及特定字符
  • 年：YYYY
  • 月：MM
  • 日：DD
  • 时：HH
  • 分：mm
  • 秒：ss
  • 微秒：ffffff
  • 毫秒：SSS
  • 时区：Z
  • 通配符：*
  • 特定字符：任意 UTF-8 字符
  • 其中年、月、日、时、分、秒、微秒、毫秒必须是整数，并且符合时间戳类型的范围
  • 微秒和毫秒不能同时出现，只能出现其中一个
  • 指定通配符时，时间戳字段上对应的位置可以为任意字符
  • 指定特定字符时，时间戳字段上对应的位置必须为该指定字符
  • 例如需要导入的数据中时间戳格式为“3/15/2015 T 12.30.123”，则设置 --timestampfmt="MM/DD/YYYY T mm.ss.SSS" 与该格式匹配
  • 例如指定带时区的时间戳：--timestampfmt="YYYY-MM-DD HH.mm.ssZ"
  • 例如指定东八区时间戳： --timestampfmt="YYYY-MM-DD HH.mm.ss+0800"

示例

• 将数据导入到本地数据库 11810 中集合空间 sample 的集合 employee，导入格式是 csv，数据文件为test.csv，第一行为字段定义：

  以下是导入文件的内容：

  name string default "Anonymous", age int, country
  "Jack",18,"China"
  "Mike",20,"USA"

  $ sdbimprt --hosts=localhost:11810 --type=csv --file=test.csv -c sample -l employee --headerline=true

• 导入格式是 csv，文件名是test.csv，导入至集合空间 sample 的集合 employee 中

  以下是导入文件的内容：

  "Jack",18,"China"
  "Mike",20,"USA"

  导入命令：

  $ sdbimprt --hosts=localhost:11810 --type=csv --file=test.csv -c sample -l employee --fields='name string default "Anonymous", age int, country'

• 导入格式是 csv，文件名是test.csv，导入至集合空间 sample 的集合 employee 中

  以下是导入文件的内容，其中文件第一行是字段定义，需要跳过：

  name, age, country
  "Jack",18,"China"
  "Mike",20,"USA"

  导入命令：

  $ sdbimprt --hosts=localhost:11810 --type=csv --file=test.csv -c sample -l employee --fields='name string default "Anonymous", age int, country' --headerline=true

• 导入格式是 csv，导入文件是目录../data中的所有文件，导入至集合空间 sample 的集合 employee 中

  $ sdbimprt --hosts=localhost:11810 --type=csv --file=../data -c sample -l employee --fields='name string default "Anonymous", age int, country'

• 导入格式是 csv，导入文件是目录../data中的所有文件以及./sample_employee_data.csv，导入至集合空间 sample 的集合 employee 中，有 11810 和 11910 两个协调节点，记录中时间戳类型的数据类似于“2015-10-01 T 12.31.15.123 T”，使用两个连接同时导入

  $ sdbimprt --type=csv --file=../data,./sample_employee_data.csv --fields='name, time timestamp' -c sample -l employee --timestampfmt="YYYY-MM-DD T HH.mm.ss.SSS T" --hosts=localhost:11810,localhost:11910 -j 2

• 导入格式是 json，通过管道从其它工具 other 获取数据，导入至集合空间 sample 的集合 employee 中

  $ other | sdbimprt --hosts=localhost:11810 --type=json -c sample -l employee 

• 导入格式是 csv，导入多种时间戳格式

  例子的系统时区是东八区

  以下是导入文件的内容：

  2014-01-01, 2001/01/01, 1990-01-01
  2014-01-01Z, 2001/01/01Z, 1990-01-01Z
  2014-01-01+0200, 2001/01/01+0200, 1990-01-01+0200

  导入命令：

  $ sdbimprt --hosts=localhost:11810 --type=csv --file=test.csv -c sample -l employee --fields='time1 timestamp("YYYY-MM-DD"), time2 timestamp("YYYY/MM/DDZ"), time3 timestamp("YYYY-MM-DD+0600")'

  1. time1没有指定时区，因此都用系统的时区
  2. time2指定时区字符Z，如果数据没有时区信息，则用系统的时区；如果数据有Z字符，则作为UTC时间
  3. time3指定+0600时区，如果数据没有时区信息，则用字段指定的+0600时区；如果数据有Z字符，则作为UTC时间

  查询结果：

  > db.sample.employee.find()
  {
    "_id": {
       "$oid": "5ad5565f13f513e620000000"
    },
    "time1": {
       "$timestamp": "2014-01-01-00.00.00.000000"
    },
    "time2": {
       "$timestamp": "2001-01-01-00.00.00.000000"
    },
    "time3": {
       "$timestamp": "1990-01-01-02.00.00.000000"
    }
  }
  {
    "_id": {
       "$oid": "5ad5565f13f513e620000001"
    },
    "time1": {
       "$timestamp": "2014-01-01-00.00.00.000000"
    },
    "time2": {
       "$timestamp": "2001-01-01-08.00.00.000000"
    },
    "time3": {
       "$timestamp": "1990-01-01-08.00.00.000000"
    }
  }
  {
    "_id": {
       "$oid": "5ad5565f13f513e620000002"
    },
    "time1": {
       "$timestamp": "2014-01-01-00.00.00.000000"
    },
    "time2": {
       "$timestamp": "2001-01-01-06.00.00.000000"
    },
    "time3": {
       "$timestamp": "1990-01-01-06.00.00.000000"
    }
  }