创建作业规范文件
作业配置文件指示 Dataflow 如何运行导入(数据源位置、如何映射到 Neo4j 等)。它由一个包含四个部分的 JSON 对象组成。
{
"version": "1",
"config": { ... }, (1)
"sources": [ (2)
{ ... }
],
"targets": [ (3)
{ ... }
],
"actions": [ (4)
{ ... }
]
}
| 1 | config — 影响导入执行方式的全局标志(可选) |
| 2 | sources — 数据源定义(关系型) |
| 3 | targets — 数据目标定义(图:节点/关系/Cypher 查询) |
| 4 | actions — 一次性操作(可选) |
从高层次来看,作业从 sources 获取数据,并将其转换/导入到 targets。
一个有效的规范文件至少包含一个源对象和一个目标对象。
完整示例
下面是一个示例作业规范文件,可以直接用于导入公开可用的 movies 数据集。
该数据集包含实体 Person 和 Movie,通过 DIRECTED 和 ACTED_IN 关系连接。换句话说,每个 Person 可能 DIRECTED 和/或 ACTED_IN 一部 Movie。实体和关系都附加了额外的详细信息。数据源自以下文件:persons.csv、movies.csv、acted_in.csv、directed.csv。
接下来的部分将对其进行细分,并为每个部分提供上下文信息。我们建议您将本指南与作业规范示例对照阅读。
{
"version": "1",
"config": {
"reset_db": true
},
"sources": [
{
"type": "text",
"name": "persons",
"urls": ["gs://neo4j-examples/persons.csv"],
"format": "excel",
"header": ["person_tmdbId","bio","born","bornIn","died","person_imdbId","name","person_poster","person_url"]
},
{
"type": "text",
"name": "movies",
"urls": ["gs://neo4j-examples/movies.csv"],
"format": "excel",
"header": ["movieId","title","budget","countries","movie_imdbId","imdbRating","imdbVotes","languages","plot","movie_poster","released","revenue","runtime","movie_tmdbId","movie_url","year","genres"]
},
{
"type": "text",
"name": "directed",
"urls": ["gs://neo4j-examples/directed.csv"],
"format": "excel",
"header": ["movieId","person_tmdbId"]
},
{
"type": "text",
"name": "acted_in",
"urls": ["gs://neo4j-examples/acted_in.csv"],
"format": "excel",
"header": ["movieId","person_tmdbId","role"]
}
],
"targets": {
"nodes": [
{
"source": "persons",
"name": "Persons",
"write_mode": "merge",
"labels": [ "Person" ],
"properties": [
{
"source_field": "person_tmdbId",
"target_property": "id",
"target_property_type": "string"
},
{
"source_field": "name",
"target_property": "name",
"target_property_type": "string"
},
{
"source_field": "bornIn",
"target_property": "bornLocation",
"target_property_type": "string"
},
{
"source_field": "born",
"target_property": "bornDate",
"target_property_type": "date"
},
{
"source_field": "died",
"target_property": "diedDate",
"target_property_type": "date"
}
],
"schema": {
"key_constraints": [
{
"name": "personIdKey",
"label": "Person",
"properties": ["id"]
}
],
"unique_constraints": [
{
"name": "personNameUnique",
"label": "Person",
"properties": ["name"]
}
]
}
},
{
"source": "movies",
"name": "Movies",
"write_mode": "merge",
"labels": [ "Movie" ],
"properties": [
{
"source_field": "movieId",
"target_property": "id",
"target_property_type": "string"
},
{
"source_field": "title",
"target_property": "title",
"target_property_type": "string"
},
{
"source_field": "year",
"target_property": "releaseYear",
"target_property_type": "string"
},
{
"source_field": "imdbRating",
"target_property": "imdbRating",
"target_property_type": "float"
}
],
"schema": {
"key_constraints": [
{
"name": "movieIdKey",
"label": "Movie",
"properties": ["id"]
}
],
"unique_constraints": [
{
"name": "movieTitleUnique",
"label": "Movie",
"properties": ["title"]
}
]
}
}
],
"relationships": [
{
"source": "directed",
"name": "Directed",
"type": "DIRECTED",
"write_mode": "merge",
"node_match_mode": "match",
"start_node_reference": "Persons",
"end_node_reference": "Movies"
},
{
"source": "acted_in",
"name": "Acted_in",
"type": "ACTED_IN",
"write_mode": "merge",
"node_match_mode": "match",
"start_node_reference": "Persons",
"end_node_reference": "Movies",
"properties": [
{
"source_field": "role",
"target_property": "role",
"target_property_type": "string"
}
]
}
]
}
}
配置
config 对象包含导入作业的全局配置。所有设置都有默认值,除非您想更改它们,否则无需指定。
"config": {
"reset_db": false,
"index_all_properties": false,
"node_target_batch_size": 5000,
"relationship_target_batch_size": 1000,
"query_target_batch_size": 1000,
"node_target_parallelism": 10,
"relationship_target_parallelism": 1,
"query_target_parallelism": 1
}
-
reset_db(bool) — 是否在导入前清除目标数据库。删除数据、索引和约束。 -
index_all_properties(bool) — 是否为所有属性创建索引。参见Cypher® → 搜索性能索引。 -
node_target_batch_size(int) — 每个节点目标的导入事务要处理的行数。 -
relationship_target_batch_size(int) — 每个关系目标的事务要处理的行数。 -
query_target_batch_size(int) — 每个自定义查询的事务要处理的行数。 -
node_target_parallelism(int) — 每个 worker 处理节点目标的最大并发事务数。 -
relationship_target_parallelism(int) — 每个 worker 处理关系目标的最大并发事务数。大于1的值应谨慎设置,因为它们可能导致死锁。 -
query_target_parallelism(int) — 每个 worker 处理 Cypher 查询目标的最大并发事务数。大于1的值应谨慎设置,因为它们可能导致死锁。
源
sources 部分包含数据源的定义,为一个列表。大致来说,您可以理解为 一个表 <=> 一个源。导入器将利用源提供的数据,并将其提供给目标,最终将其映射到 Neo4j 中。
源对象至少必须指定属性 type、name、urls 和 header。默认的列分隔符和行分隔符根据指定的 format 设置,遵循 Apache 的 CSVFormat。
{
"type": "text",
"name": "<sourceName>",
"urls": [ "<csvPath1>", "<csvPath2>", ... ],
"format": "default",
"column_delimiter": "",
"line_separator": "",
"header": "<colName1>,<colName2>,..."
}
-
type(string) —text。 -
name(string) — 一个易于理解的源标签(在所有名称中唯一)。您将使用它在规范文件的其他部分引用该源。 -
urls(list of strings) — CSV 文件的 Google Storage 位置(例如gs://neo4j-datasets/movies.csv)。如何检索文件的 Google Storage 位置?
要检索 Cloud 存储桶中文件的 Google Storage 位置,展开右侧的三个点,选择
Copy gsutil URI。
-
format(string) — 提供的 CSV 文件格式。
有效值包括:default、excel、informix、mongo、mongo_tsv、mysql、oracle、postgres、postgresql_csv、rfc4180。
格式行为与 Apache 的CSVFormat一致。 -
column_delimiter(string) — CSV 字段分隔符。 -
line_separator(string) — CSV 行分隔符。 -
header(string) — CSV 文件包含的字段名称完整列表,按顺序排列。另外,列表可以仅限于前几列。此处指定的列名控制目标将从中映射的行字段名称。
|
字段 给定一个包含列
|
有效示例 |
|
有效示例 |
|
有效示例 |
|
无效示例 |
|
无效示例 |
|
目标
targets 部分包含导入后生成的图实体定义。
您必须指定至少一个目标对象。
Neo4j 使用节点(例如 movies、people)表示对象,并使用关系(例如 ACTED_IN、DIRECTED)连接它们。targets 部分中的每个对象都将从源中提取数据,并在 Neo4j 中生成相应的实体(节点或关系)。也可以运行自定义 Cypher 查询。
"targets": {
"nodes": [ ... ],
"relationships": [ ... ],
"queries": [ ... ]
}
默认情况下,您无需考虑节点和关系之间的依赖关系。关系目标总是在其起始节点和结束节点对应的目标处理后进行处理。但是,可以将其他目标添加为依赖项。
节点对象
节点实体必须在 targets 对象内以 nodes 为键的列表中进行分组。
"targets": {
"nodes": [
{ <nodeSpec1> },
{ <nodeSpec2> },
...
]
}
必填字段
每个节点对象至少必须具有属性 source、name、labels 和 properties。
{
"source": "<sourceName>",
"name": "<targetName>",
"labels": ["<label1>", "<label2>", ...],
"properties": [
{
"source_field": "<bigQueryColumnName>",
"target_field": "<neo4jPropertyName>",
"target_property_type": "<neo4jPropertyType>"
},
{ <propertyObj2> },
...
],
"write_mode": "merge"
}
-
source(string) — 此目标应从中提取数据的源名称。应与sources对象中的某个名称匹配。 -
name(string) — 一个易于理解的目标名称(在所有名称中唯一)。 -
labels(list of strings) — 用于标记节点的标签。 -
properties(list of objects) — 源列与节点属性之间的映射。target_property_type的有效值包括:boolean、byte_array(假定 base64 编码)、date、duration、float、integer、local_date、local_datetime、local_time、point、string、zoned_datetime、zoned_time。 -
write_mode(string) — Neo4j 中的创建模式。可以是create或merge。有关 Cypher 子句行为的信息,请参见CREATE和MERGE。
Schema 定义
如果全局配置 index_all_properties 设置为 true,所有属性将使用范围索引进行索引。 |
{
...
"schema": {
"enable_type_constraints": true,
"key_constraints": [
{
"name": "<constraintName>",
"label": "<label>",
"properties": ["<neo4jPropertyName1>", "<neo4jPropertyName2>", ...],
"options": {}
}
],
"unique_constraints": [
{
"name": "<constraintName>",
"label": "<label>",
"properties": ["<neo4jPropertyName1>", "<neo4jPropertyName2>", ...],
"options": {}
}
],
"existence_constraints": [
{
"name": "<constraintName>",
"label": "<label>",
"property": "<neo4jPropertyName>"
}
],
"range_indexes": [
{
"name": "<indexName>",
"label": "<label>",
"properties": ["<neo4jPropertyName1>", "<neo4jPropertyName2>", ...],
}
],
"text_indexes": [
{
"name": "<indexName>",
"label": "<label>",
"property": "<neo4jPropertyName>",
"options": {}
}
],
"point_indexes": [
{
"name": "<indexName>",
"label": "<label>",
"property": "<neo4jPropertyName>",
"options": {}
}
],
"fulltext_indexes": [
{
"name": "<indexName>",
"labels": ["label1", "label2", ...],
"properties": ["<neo4jPropertyName1>", "<neo4jPropertyName2>", ...],
"options": {}
}
],
"vector_indexes": [
{
"name": "<indexName>",
"label": "<label>",
"property": "<neo4jPropertyName>",
"options": {}
}
]
}
}
其中每个对象的属性为
源数据的 key_constraints 列不能包含空值,否则会与节点键约束冲突。如果源数据在这方面不干净,请考虑提前在相关的 source.query 字段中通过排除所有不满足约束的行来清洗数据(例如 WHERE person_tmbdId IS NOT NULL)。或者,使用源转换中的 where 属性。 |
选项 key_constraints 和 existence_constraints 需要 Neo4j/Aura Enterprise Edition,并且在针对 Neo4j Community Edition 安装运行时无效。 |
配置
{
...
"active": true,
"source_transformations": {
"enable_grouping": true
},
"depends_on": ["<dependencyTargetName1>", "<dependencyTargetName2>", ...]
}
-
active(bool) — 是否应将此目标包含在导入中(默认值:true)。 -
source_transformations(object) — 如果enable_grouping设置为true,导入将在key_constraints和properties中指定的所有字段上附加 SQL 子句GROUP BY。如果设置为false,源中的任何重复数据都将被推入 Neo4j,可能引发约束错误或降低插入效率。该对象还可以包含聚合函数和其他字段,参见源转换。 -
depends_on(list of strings) — 应在当前目标之前执行的目标的name。
示例
Person 节点的节点对象示例{
"source": "persons",
"name": "Persons",
"labels": [ "Person" ],
"properties": [
{
"source_field": "person_tmdbId",
"target_field": "id",
"target_property_type": "string"
},
{
"source_field": "name",
"target_field": "name",
"target_property_type": "string"
},
{
"source_field": "bornIn",
"target_field": "bornLocation",
"target_property_type": "string"
},
{
"source_field": "born",
"target_field": "bornDate",
"target_property_type": "local_date"
},
{
"source_field": "died",
"target_field": "diedDate",
"target_property_type": "local_date"
}
],
"schema": {
"key_constraints": [
{
"name": "personIdKey",
"label": "Person",
"properties": ["id"]
}
],
"unique_constraints": [
{
"name": "personNameUnique",
"label": "Person",
"properties": ["name"]
}
]
}
}
关系对象
关系实体必须在 targets 对象内以 relationships 为键的列表中进行分组。
"targets": {
...
"relationships": [
{ <relationshipSpec1> },
{ <relationshipSpec2> },
...
]
}
必填字段
每个关系对象至少必须具有属性 source、name 和 type。
它还必须包含关系连接哪些节点目标的信息。您通过 start_node_reference 和 end_node_reference 提供此信息。
{
"source": "<sourceName>",
"name": "<targetName>",
"type": "<relationshipType>",
"start_node_reference": "<nodeTargetName>",
"end_node_reference": "<nodeTargetName>",
"node_match_mode": "<match/merge>",
"write_mode": "<create/merge>"
}
-
source(string) — 此目标应从中提取数据的源名称。应与sources对象中的某个名称匹配。 -
name(string) — 一个易于理解的目标名称(在所有名称中唯一)。 -
type(string) — 要分配给关系的类型。 -
start_node_reference(string) — 作为关系起点的节点目标的名称。 -
end_node_reference(string) — 作为关系终点的节点目标的名称。 -
node_match_mode(string) — 在创建关系之前用于获取起点/终点节点的 Cypher 子句。有效值为match或merge,分别对应 Cypher 子句MATCH和MERGE。 -
write_mode(string) — Neo4j 中的创建模式。可以是create或merge。有关 Cypher 子句行为的信息,请参见CREATE和MERGE。
属性
关系也可以将源列映射为属性。
{
...
"properties": [
{
"source_field": "<bigQueryColumnName>",
"target_field": "<neo4jPropertyName>",
"target_property_type": "<neo4jPropertyType>"
},
{ <propertyObj2> },
...
]
}
-
properties(list of objects) — 源列与关系属性之间的映射。target_property_type的有效值包括:boolean、byte_array(假定 base64 编码)、date、duration、float、integer、local_date、local_datetime、local_time、point、string、zoned_datetime、zoned_time。
Schema 定义
如果全局配置 index_all_properties 设置为 true,所有属性将使用范围索引进行索引。 |
{
...
"schema": {
"enable_type_constraints": true,
"key_constraints": [
{
"name": "<constraintName>",
"type": "<relationshipType>",
"properties": ["<neo4jPropertyName1>", "<neo4jPropertyName2>", ...],
"options": {}
}
],
"unique_constraints": [
{
"name": "<constraintName>",
"type": "<relationshipType>",
"properties": ["<neo4jPropertyName1>", "<neo4jPropertyName2>", ...],
"options": {}
}
],
"existence_constraints": [
{
"name": "<constraintName>",
"type": "<relationshipType>",
"property": "<neo4jPropertyName>"
}
],
"range_indexes": [
{
"name": "<indexName>",
"type": "<relationshipType>",
"properties": ["<neo4jPropertyName1>", "<neo4jPropertyName2>", ...],
}
],
"text_indexes": [
{
"name": "<indexName>",
"type": "<relationshipType>",
"property": "<neo4jPropertyName>",
"options": {}
}
],
"point_indexes": [
{
"name": "<indexName>",
"type": "<relationshipType>",
"property": "<neo4jPropertyName>",
"options": {}
}
],
"fulltext_indexes": [
{
"name": "<indexName>",
"types": ["<relationshipType1>", "<relationshipType2>", ...],
"properties": ["<neo4jPropertyName1>", "<neo4jPropertyName2>", ...],
"options": {}
}
],
"vector_indexes": [
{
"name": "<indexName>",
"type": "<relationshipType>",
"property": "<neo4jPropertyName>",
"options": {}
}
]
}
}
其中每个对象的属性为
源数据的 key_constraints 列不能包含空值,否则会与关系键约束冲突。如果源数据在这方面不干净,请考虑提前在相关的 source.query 字段中通过排除所有不满足约束的行来清洗数据(例如 WHERE person_tmbdId IS NOT NULL)。或者,使用源转换中的 where 属性。 |
选项 key_constraints 和 existence_constraints 需要 Neo4j/Aura Enterprise Edition,并且在针对 Neo4j Community Edition 安装运行时无效。 |
配置
{
...
"active": true,
"source_transformations": {
"enable_grouping": true
},
"depends_on": ["<dependencyTargetName1>", "<dependencyTargetName2>", ...]
}
-
active(bool) — 是否应将此目标包含在导入中。 -
source_transformations(object) — 如果enable_grouping设置为true,导入将在key_constraints和properties中指定的所有字段上执行 SQLGROUP BY。如果设置为false,源中的任何重复数据都将被推入 Neo4j,可能引发约束错误或降低插入效率。该对象还可以包含聚合函数和其他字段,参见源转换。 -
depends_on(list of strings) — 应在当前目标之前执行的目标的name。
示例
ACTED_IN 关系的关系对象示例{
"source": "acted_in",
"name": "Acted_in",
"type": "ACTED_IN",
"write_mode": "merge",
"node_match_mode": "match",
"start_node_reference": "Persons",
"end_node_reference": "Movies",
"properties": [
{
"source_field": "role",
"target_field": "role",
"target_property_type": "string"
}
]
}
自定义查询目标
当导入需要一个不方便放入节点/关系目标格式的复杂查询时,自定义查询目标很有用。查询目标通过变量 $rows 接收成批的行。
自定义查询必须在 targets 对象内以 queries 为键的列表中进行分组。
"targets": {
...
"queries": [
{ <querySpec1> },
{ <querySpec2> },
...
]
}
不要使用自定义查询运行不直接依赖于源的 Cypher 查询;应使用操作代替。一次性查询,特别是如果不是幂等的查询,不适合在自定义查询目标中使用。原因在于目标中的查询是分批运行的,因此自定义查询可能会根据从源中提取的 $rows 批次数而多次运行。 |
必填字段
每个查询目标至少必须具有属性 source、name 和 query。
{
"source": "<sourceName>",
"name": "<targetName>",
"query": "<cypherQuery>"
}
-
source(string) — 此目标应从中提取数据的源名称。应与sources对象中的某个名称匹配。 -
name(string) — 一个易于理解的目标名称(在所有名称中唯一)。 -
query(string) — 一个 Cypher 查询。源数据作为列表在参数$rows中可用。
配置
{
...
"active": true,
"depends_on": ["<dependencyTargetName1>", "<dependencyTargetName2>", ...]
}
-
active(bool) — 是否应将此目标包含在导入中。 -
depends_on(list of strings) — 应在当前目标之前执行的目标的name。
示例
Person 节点并在创建时设置日期的查询对象示例{
"custom_query": {
"name": "Person nodes",
"source": "persons",
"query": "UNWIND $rows AS row WHERE row.person_tmdbId IS NOT NULL MERGE (p:Person {id: row.person_tmdbId, name: row.name, born_in: row.bornIn, born: date(row.born), died: date(row.died)}) ON CREATE SET p.created_time=datetime()"
}
}
源转换
每个节点和关系目标都可以选择具有包含聚合函数的 source_transformation 属性。这对于从更细粒度的源中提取更高级别的维度很有用。聚合会生成额外的字段,这些字段可用于属性映射。
"source_transformations": {
"enable_grouping": true,
"aggregations": [ {
"expression": "",
"field_name": ""
},
{ aggregationObj2 }, ...
],
"limit": -1,
"where": "",
"order_by": [
{
"expression": "column_name",
"order": "<asc/desc>"
},
{ orderObj2 }, ...
],
}
-
enable_grouping(bool) — 必须设置为true,aggregations/where才能工作。 -
aggregations(list of objects) — 聚合在expression属性中指定为 SQL 查询,结果在源中以field_name指定的名称作为列提供。 -
limit(int) — 限制考虑导入的源行数(默认为无限制,编码为-1)。 -
where(string) — 在导入前过滤源数据(采用 SQLWHERE子句格式)。 -
order_by(list of objects) — 对源强制执行排序。
操作
actions 部分包含可在导入过程特定步骤之前或之后运行的命令。每个步骤称为一个 stage。例如,您可以在步骤完成后提交 HTTP 请求,在源上执行 SQL 查询,或在 Neo4j 目标实例上运行 Cypher 语句。
...
"actions": [
{ <actionSpec1> },
{ <actionSpec2> },
...
]
每个操作对象至少必须具有属性 name、type 和 stage。其他属性取决于操作类型。
{
"type": "http",
"name": "<actionName>",
"stage": "<stageName>",
"method": "<get/post>",
"url": "<targetUrl>",
"headers": {}
}
-
type(string) — 操作类型。 -
name(string) — 一个易于理解的操作名称(在所有名称中唯一)。 -
stage(string) — 操作应在导入过程的哪个阶段运行。有效值包括:start、post_sources、pre_nodes、post_nodes、pre_relationships、post_relationships、pre_queries、post_queries、end。 -
method(string) — HTTP 方法;可以是get或post。 -
url(string) — HTTP 请求的目标 URL。 -
headers(object, optional) — 请求头。
GET 请求的操作示例{
"type": "http",
"name": "Post load ping",
"stage": "end",
"method": "get",
"url": "https://neo4j.ac.cn/success",
"headers": {
"secret": "314159",
"moreSecret": "17320"
}
}
{
"type": "cypher",
"name": "<actionName>",
"stage": "<stageName>",
"query": "<cypherQuery>",
"execution_mode": "<transaction/autocommit>"
}
-
type(string) — 操作类型。 -
name(string) — 一个易于理解的操作名称(在所有名称中唯一)。 -
stage(string) — 操作应在导入过程的哪个阶段运行。有效值包括:start、post_sources、pre_nodes、post_nodes、pre_relationships、post_relationships、pre_queries、post_queries、end。 -
query(string) — 要运行的 Cypher 查询。 -
execution_mode(string, optional) — 查询应在哪种模式下执行。有效值包括transaction、autocommit(默认值:transaction)。
importJob 节点的操作示例{
"type": "cypher",
"name": "Post load log",
"stage": "end",
"query": "MERGE (:importJob {date: datetime()})"
}
{
"type": "bigquery",
"name": "<actionName>",
"stage": "<stageName>",
"sql": "<sqlQuery>"
}
-
type(string) — 操作类型。 -
name(string) — 一个易于理解的操作名称(在所有名称中唯一)。 -
stage(string) — 操作应在导入过程的哪个阶段运行。有效值包括:start、post_sources、pre_nodes、post_nodes、pre_relationships、post_relationships、pre_queries、post_queries、end。 -
sql(string) — 要运行的 SQL 查询。
GET 请求的操作示例{
"type": "bigquery",
"name": "Post load log",
"stage": "end",
"sql": "INSERT INTO logs.imports (time) VALUES (NOW())"
}