vesoft/nebula-importer

Nebula Importer 镜像文档

概述

Nebula Importer是专为https://github.com/vesoft-inc/nebula%E8%AE%BE%E8%AE%A1%E7%9A%84CSV%E6%95%B0%E6%8D%AE%E5%AF%BC%E5%85%A5%E5%B7%A5%E5%85%B7%E3%80%82%E5%AE%83%E8%83%BD%E5%A4%9F%E8%AF%BB%E5%8F%96%E6%9C%AC%E5%9C%B0CSV%E6%96%87%E4%BB%B6%E4%B8%AD%E7%9A%84%E6%95%B0%E6%8D%AE%EF%BC%8C%E5%B9%B6%E6%89%B9%E9%87%8F%E5%AF%BC%E5%85%A5%E5%88%B0Nebula Graph数据库中。

使用前需确保：

• Nebula Graph已部署（推荐通过https://github.com/vesoft-inc/nebula-docker-compose%E5%BF%AB%E9%80%9F%E9%83%A8%E7%BD%B2%EF%BC%89
• 已创建包含space、tag和edge type的schema

核心功能和特性

• CSV文件支持：读取本地CSV文件，支持带表头和不带表头的格式
• 批量导入：支持批量插入数据，可配置批量大小（batchSize）
• 失败数据处理：自动记录导入失败的数据至指定目录，便于重试
• 灵活配置：通过YAML配置文件定义导入规则，支持顶点（vertex）和边（edge）导入
• 连接优化：可配置重试次数、并发连接数、缓存队列大小等参数
• 版本兼容：master和v3分支仅支持Nebula Graph 3.x，需注意版本匹配

使用场景

• Nebula Graph数据库的数据迁移
• 批量数据导入（如初始化数据库、定期数据更新）
• 从CSV格式数据源向Nebula Graph导入顶点和边数据

使用方法

Docker部署

无需本地安装Go环境，直接拉取镜像并挂载配置文件和CSV数据目录即可使用。

基本命令

bash
docker run --rm -ti \
    --network=host \
    -v {本地配置文件绝对路径}:{容器内配置文件路径} \
    -v {本地CSV数据目录绝对路径}:{容器内CSV数据目录路径} \
    vesoft/nebula-importer:{镜像版本} \
    --config {容器内配置文件路径}

参数说明

• --network=host：使用主机网络，确保容器能访问Nebula Graph服务
• -v {本地配置文件}:{容器内配置文件}：挂载本地YAML配置文件到容器
• -v {本地CSV数据目录}:{容器内CSV数据目录}：挂载本地CSV数据目录到容器
• {镜像版本}：指定镜像版本，如v3（对应Nebula Graph 3.x）
• --config：指定容器内配置文件路径

示例

假设本地配置文件路径为/data/nebula/importer/config.yaml，CSV数据目录为/data/nebula/csv，使用v3版本镜像：

bash
docker run --rm -ti \
    --network=host \
    -v /data/nebula/importer/config.yaml:/config.yaml \
    -v /data/nebula/csv:/csv \
    vesoft/nebula-importer:v3 \
    --config /config.yaml

注意：配置文件中files.path建议使用相对路径，若使用绝对路径需确保与容器内挂载路径一致。

配置说明

Nebula Importer通过YAML配置文件定义导入规则，包含全局设置、Nebula Graph连接信息、CSV文件信息和数据schema等。

配置文件结构

yaml
version: v2
description: 示例配置
removeTempFiles: false
clientSettings:
  # Nebula Graph客户端配置
files:
  # CSV文件列表配置

全局配置

clientSettings（Nebula Graph客户端配置）

yaml
clientSettings:
  retry: 3                  # 失败重试次数
  concurrency: 10           # 并发连接数
  channelBufferSize: 128    # 每个客户端的缓存队列大小
  space: test               # 目标space名称
  connection:
    user: user              # 用户名
    password: password      # 密码
    address: 192.168.8.1:9669,192.168.8.2:9669  # Nebula Graph地址列表
  postStart:                # 连接后、导入前执行的命令
    commands: |
      UPDATE CONFIGS storage:wal_ttl=3600;
    afterPeriod: 8s         # 命令执行后等待时间
  preStop:                  # 断开连接前执行的命令
    commands: |
      UPDATE CONFIGS storage:wal_ttl=86400;

files（CSV文件配置）

yaml
workingDir: ./data/         # 工作目录，用于拼接相对路径
logPath: ./err/test.log     # 日志路径
files:
  - path: ./student.csv     # CSV文件路径（支持通配符，如./follower-*.csv）
    failDataPath: ./err/student  # 失败数据存储目录
    batchSize: 128          # 批量插入大小
    limit: 10               # 最大读取行数限制
    inOrder: false          # 是否按文件顺序导入
    type: csv               # 文件类型（仅支持csv）
    csv:
      withHeader: false     # 是否带表头
      withLabel: false      # 是否带标签（+/-表示插入/删除）
      delimiter: ","        # 分隔符（仅支持单个字符）
      lazyQuotes: false     # 是否允许非标准引号

schema（数据schema配置）

必填，描述CSV文件的数据结构，分为顶点（vertex）和边（edge）两种类型。

顶点配置示例

yaml
schema:
  type: vertex
  vertex:
    vid:
      index: 1               # CSV列索引（从0开始）
      function: hash         # VID生成函数（仅支持hash）
      prefix: abc            # VID前缀
    tags:
      - name: student        # tag名称
        props:
          - name: age        # 属性名
            type: int        # 属性类型
            index: 2         # CSV列索引
          - name: name
            type: string
            index: 1
          - name: gender
            type: string
            defaultValue: "male"  # 默认值
          - name: phone
            type: string
            nullable: true        # 是否允许为NULL
          - name: email
            type: string
            nullable: true
            nullValue: "__NULL__" # NULL值标识
          - name: address
            type: string
            nullable: true
            alternativeIndices: [7, 8]  # 备选列索引

边配置示例

yaml
schema:
  type: edge
  edge:
    name: choose             # edge type名称
    srcVID:                  # 源顶点VID配置
      index: 0
      function: hash
    dstVID:                  # 目标顶点VID配置
      index: 1
      function: hash
    rank:                    # 边的rank配置
      index: 2
    props:                   # 边属性配置
      - name: grade
        type: int
        index: 3

VID配置参数

属性配置参数

CSV文件格式说明

不带表头（withHeader: false）

顶点文件示例（tag: course）

csv
101,Math,3,No5
102,English,6,No11

• 第1列：顶点ID
• 后续列：按配置文件vertex.tags.props顺序排列的属性

边文件示例（edge type: choose）

csv
200,101,5
200,102,3

• 第1列：源顶点ID
• 第2列：目标顶点ID
• 第3列：边属性（如有rank，需放在属性前）

带表头（withHeader: true）

表头格式：<tag/edge名称>.<属性名>:<类型>，支持特殊关键字：

• :VID：顶点ID
• :SRC_VID：源顶点ID
• :DST_VID：目标顶点ID
• :RANK：边的rank
• :IGNORE：忽略该列
• :LABEL：操作标签（+插入/-删除）

顶点文件示例

csv
:LABEL,:VID,course.name,building.name:string,:IGNORE,course.credits:int
+,"hash(""Math"")",Math,No5,1,3
+,"hash(""English"")",English,"No11 B\",2,6

边文件示例

csv
:DST_VID,follow.likeness:double,:SRC_VID,:RANK
201,92.5,200,0
200,85.6,201,1

注意：带表头时，配置文件中的props会被忽略，以表头定义为准。