数据导入工具

sdbimprt 是 SequoiaDB 巨杉数据库的数据导入工具，用于将 JSON 或 CSV 格式的数据导入到 SequoiaDB 数据库中。

JSON

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

CSV

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

分隔符

Note:

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

CSV类型

Note:

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

CSV类型自动判断

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

CSV类型转换

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

Note:

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

命令选项

通用选项

输入选项

Note:

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

JSON选项

CSV选项

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'
• 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"

导入选项

示例

• 数据文件 test.csv 存在如下记录：

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

  将数据通过协调节点导入至集合 sample.employee 中

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

• 数据文件 test.csv 存在以下记录：

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

  将数据导入到本地数据库 11810 中的集合 sample.employee

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

• 数据文件 test.csv 存在以下记录，其中文件第一行是字段定义，需要跳过：

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

  将数据导入到本地数据库 11810 中的集合 sample.employee

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

• 将目录 ../data 中的所有文件以 csv 格式导入至集合 sample.employee

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

• 将目录 ../data 中的所有文件以及 ./sample_employee_data.csv 以 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

• 通过管道从其它工具 other 获取数据，并以 json 格式导入至集合 sample.employee 中

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

• 导入多种时间戳格式，以系统时区是东八区为例，如下是导入文件的内容：

  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

  将导入文件以 csv 格式导入至集合 sample.employee 中

  $ 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")'

  Note:

  • time1没有指定时区，因此都用系统的时区。
  • time2指定时区字符Z，如果数据没有时区信息，则用系统的时区；如果数据有Z字符，则作为 UTC 时间。
  • 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"
     }
  }