Source: https://dev-docs.yueshu.com.cn/v5.3.2/utilities/exchange/import-data/template-import/
Documentation version: v5.3.2

# 基于 GQL 模板导入

悦数数据迁移支持通过自定义 GQL 模板将数据导入悦数图数据库开发版。与[导入数据](https://dev-docs.yueshu.com.cn/v5.3.2/utilities/exchange/import-data/)中的标准导入方式不同，用户可直接编写 GQL 语句模板，由系统逐行读取数据源、填充模板中的占位符后发送至悦数图数据库开发版执行。

## 与标准导入方式的区别

 |  | 标准导入 | 基于 GQL 模板导入
 | 任务类型（`taskType`） | `import` | `gqlTemplate`
 | 写入模式 | 从七种预设模式中选择（`INSERT`、`INSERT IGNORE`、`INSERT REPLACE`、`INSERT UPDATE`、`UPDATE`、`DELETE`、`DETACH DELETE`） | 用户自行编写任意 GQL 语句
 | 点边映射 | 通过`nodetypes` / `edgetypes`配置点边映射 | 不使用`nodetypes` / `edgetypes`，通过 GQL 模板直接定义写入逻辑。

## 前提条件

- 已[部署悦数数据迁移](https://dev-docs.yueshu.com.cn/v5.3.2/utilities/exchange/deploy-exchange/)。
- 目标悦数图数据库开发版实例已启动且可访问。
- 目标图及其图类型已创建，或通过[`nebula.preHooks`](https://dev-docs.yueshu.com.cn/v5.3.2/utilities/exchange/config/#_5)配置在导入前自动创建。
- 数据源文件已准备就绪。

## 快速开始

以下是一个完整的自定义 GQL 模板导入配置示例，从本地 CSV 文件读取人员数据并插入点。

1. 

准备源文件和配置文件。

CSV 文件`/tmp/person.csv`：

````
id,name,age
1,Alice,30
2,Bob,25
3,Charlie,35

````

配置文件：

将`<current-password>`替换为登录账号的当前密码。若已修改密码，请使用修改后的密码。

````
{
  # 任务类型：指定为 gqlTemplate
  taskType: gqlTemplate

  # 目标悦数图数据库开发版实例的连接信息
  nebula: {
    graphAddr: "127.0.0.1:9669"
    graphName: "demo_graph"
    user: "root"
    passwd: "<current-password>"
    preHooks:[
        """
        CREATE GRAPH TYPE IF NOT EXISTS demo_graph_type AS {
            NODE Person (LABEL Person {id INT PRIMARY KEY, name STRING, age INT}),
            EDGE Follow (Person)-[LABEL Follow {degree INT, MULTIEDGE KEY()}]->(Person)
        }
        """,
        "CREATE GRAPH IF NOT EXISTS movie TYPED movie_type"
        ]
  }

  # 错误处理：执行失败的记录写入此目录
  error: {
    path: "/tmp/errors"
    maxRecords: 100
  }

  # 断点续传配置：
  checkPoint: {
    path: "/tmp/checkpoint"
    resume: true
  }

  # 数据源全局配置：所有模板共享的默认数据源参数
  sourcesCommon: {
    type: "local"
    format: "csv"
    header: true
    separator: ","
  }

  # GQL 模板列表：每个元素定义一个模板任务
  gqlTemplates: [
    {
      name: "insert_person"
      template: "USE demo_graph INSERT (@Person{id: $${id}, name: '$${name}', age: $${age}})"
      source: {
        path: "file:///tmp/person.csv"
      }
    }
  ]
}

````

系统逐行读取 CSV 文件，将`$${字段名}`占位符替换为实际值后执行。例如第一行数据生成如下 GQL 语句：

````
USE demo_graph INSERT (@Person{id: 1, name: "Alice", age: 30})

````

2. 

执行导入命令。

````
java -jar cli-5.3.0.jar -f <path_of_config_file> -n 5 -p 2

````

关于命令详情，请参见[使用悦数数据迁移导入数据](https://dev-docs.yueshu.com.cn/v5.3.2/utilities/exchange/import-data/)。

## 配置说明

gqlTemplate 的配置文件结构如下：

````
{
    taskType: gqlTemplate

    nebula: {}

    error: {}

    checkPoint: {}

    sourcesCommon: {}

    gqlTemplates: []
}

````

其中`nebula`、`error`、`checkPoint`、`sourcesCommon`的配置项与标准导入方式相同，详情参见[数据导入配置](https://dev-docs.yueshu.com.cn/v5.3.2/utilities/exchange/config/)中的对应章节：

- `nebula`：参见悦数图数据库开发版配置。
- `error`：参见错误配置。
- `checkPoint`：参见 Checkpoint 文件配置。
- `sourcesCommon`：参见通用源配置。 

Note

`gqlTemplate`模式不使用`writeCommon`和`sources`配置段。

### GQL 模板配置（`gqlTemplates`）

`gqlTemplates`是一个数组，每个元素定义一个 GQL 模板任务。

 | 参数 | 类型 | 是否必填 | 说明
 | name | String | 是 | 模板名称，用于标识任务和错误日志目录。
 | template | String | 是 | GQL 语句模板。使用`$${字段名}`作为占位符引用数据源中的字段值。
 | source | Object | 否 | 该模板的数据源配置，可覆盖`sourcesCommon`中的同名字段。不同数据源类型支持的字段及格式，请参见各个数据源类型的[数据源配置](https://dev-docs.yueshu.com.cn/v5.3.2/utilities/exchange/config/sources/)。

占位符使用说明

- 占位符格式为`$${字段名}`（双美元符号），而非`${字段名}`。
- 模板填充后的语句直接发送至悦数图数据库开发版执行，因此模板中可以使用任何悦数图数据库开发版支持的 GQL 语句。

### `sourcesCommon`与`gqlTemplates[].source`的优先级

数据源通过`sourcesCommon`和各模板的`gqlTemplates[].source`两种方式进行配置。`sourcesCommon`定义全局默认值，各模板的`gqlTemplates[].source`可覆盖同名字段。字段解析优先级为：`gqlTemplates[].source` > `sourcesCommon` > 系统默认值。

## 示例

以下示例基于如下图类型和图。如果目标实例中尚未创建，可通过`nebula.preHooks`在导入前自动执行创建语句。

````
"""
-- 图类型
CREATE GRAPH TYPE IF NOT EXISTS demo_graph_type AS {
    NODE Person (LABEL Person {id INT PRIMARY KEY, name STRING, age INT}),
    EDGE Follow (Person)-[LABEL Follow {degree INT, MULTIEDGE KEY()}]->(Person)
}
"""

"""
-- 图
CREATE GRAPH IF NOT EXISTS demo_graph TYPED demo_graph_type
"""

````

### 导入点数据

以下示例从 CSV 文件读取人员数据，通过 GQL 模板插入点。

CSV 文件`/tmp/person.csv`：

````
id,name,age
1,Alice,30
2,Bob,25
3,Charlie,35

````

配置文件：

````
{
  taskType: gqlTemplate

  nebula: {
    graphAddr: "127.0.0.1:9669"
    graphName: "demo_graph"
    user: "root"
    passwd: "<current-password>"
  }

  sourcesCommon: {
    type: "local"
    format: "csv"
    header: true
    separator: ","
  }

  gqlTemplates: [
    {
      name: "insert_person"
      template: "USE demo_graph INSERT (@Person{id: $${id}, name: '$${name}', age: $${age}})"
      source: {
        path: "file:///tmp/person.csv"
      }
    }
  ]
}

````

### 导入边数据

以下示例从 CSV 文件读取关系数据，通过 GQL 模板插入边。

CSV 文件`/tmp/follow.csv`：

````
src,dst,degree
1,2,90
2,3,80
3,1,85

````

配置文件：

````
{
  taskType: gqlTemplate

  nebula: {
    graphAddr: "127.0.0.1:9669"
    graphName: "demo_graph"
    user: "root"
    passwd: "<current-password>"
  }

  sourcesCommon: {
    type: "local"
    format: "csv"
    header: true
    separator: ","
  }

  gqlTemplates: [
    {
      name: "insert_follow"
      template: "USE demo_graph MATCH (s@Person), (t@Person) WHERE s.id = $${src} AND t.id = $${dst} INSERT (s)-[@Follow{degree: $${degree}}]->(t)"
      source: {
        path: "file:///tmp/follow.csv"
      }
    }
  ]
}

````

### 多模板组合导入

以下示例在同一个配置文件中定义多个模板，同时导入点和边数据。

````
{
  taskType: gqlTemplate

  nebula: {
    graphAddr: "127.0.0.1:9669"
    graphName: "demo_graph"
    user: "root"
    passwd: "<current-password>"
  }

  sourcesCommon: {
    type: "local"
    format: "csv"
    header: true
    separator: ","
  }

  gqlTemplates: [
    {
      name: "insert_person"
      template: "USE demo_graph INSERT (@Person{id: $${id}, name: '$${name}', age: $${age}})"
      source: {
        path: "file:///tmp/person.csv"
      }
    },
    {
      name: "insert_follow"
      template: "USE demo_graph MATCH (s@Person), (t@Person) WHERE s.id = $${src} AND t.id = $${dst} INSERT (s)-[@Follow{degree: $${degree}}]->(t)"
      source: {
        path: "file:///tmp/follow.csv"
      }
    }
  ]
}

````