创建作业规范文件
作业配置文件指示 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": "bigquery",
"name": "persons",
"query": "SELECT person_tmdbId, name, bornIn, born, died FROM team-connectors-dev.movies.persons"
},
{
"type": "bigquery",
"name": "movies",
"query": "SELECT movieId, title, imdbRating, year FROM team-connectors-dev.movies.movies"
},
{
"type": "bigquery",
"name": "directed",
"query": "SELECT movieId, person_tmdbId FROM team-connectors-dev.movies.directed"
},
{
"type": "bigquery",
"name": "acted_in",
"query": "SELECT movieId, person_tmdbId, role FROM team-connectors-dev.movies.acted_in"
}
],
"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",
"write_mode": "merge",
"node_match_mode": "match",
"type": "DIRECTED",
"start_node_reference": "Persons",
"end_node_reference": "Movies"
},
{
"source": "acted_in",
"name": "Acted_in",
"write_mode": "merge",
"node_match_mode": "match",
"type": "ACTED_IN",
"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": "bigquery",
"name": "<sourceName>",
"query": "<bigQuerySqlQuery>",
"query_temp_project": "<projectName>",
"query_temp_dataset": "<datasetName>"
}
-
type
(string) —bigquery
。 -
name
(string) — 源的人性化标签(在所有名称中必须唯一;不能包含空格)。您将使用此名称在规范文件的其他部分引用该源。 -
query
(string) — 要从 BigQuery 中提取的数据集,以 SQL 查询形式表示。请注意:-
源表可以包含比您在查询中选择的更多列;
-
多个目标可以使用同一个源,并可能过滤出不同的列子集。
-
-
query_temp_project
(string, optional) 用于存储临时查询结果的 Google Cloud 项目(默认为当前项目)。 -
query_temp_dataset
(string, optional) 用于存储临时查询结果的 BigQuery 数据集(默认为新的临时数据集)。
在您仅对源所在的 Google Cloud 项目/数据集具有读取权限的情况下,指定临时项目和/或数据集会很有帮助。 如果设置了 |
不支持 BIGNUMERIC , GEOGRAPHY , JSON , INTERVAL 和 STRUCT 类型的列。 |
目标
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
。每种属性类型(除了 byte_array)也支持其 "_array" 形式(例如 date_array, string_array 等),用于 BigQuery 的 "repeated" 列类型。 -
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 列的值不能为 null,否则会与节点键约束冲突。如果源数据在这方面不干净,请考虑在相关的 source.query 字段中预先清洗数据,排除所有不满足约束条件的行(例如 WHERE person_tmbdId IS NOT NULL )。或者,在源转换中使用 where 属性。 |
选项 key_constraints 和 existence_constraints 需要 Neo4j/Aura 企业版,在 Neo4j 社区版安装上运行时无效。 |
配置
{
...
"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
。每种属性类型(除了 byte_array)也支持其 "_array" 形式(例如 date_array, string_array 等),用于 BigQuery 的 "repeated" 列类型。
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 列的值不能为 null,否则会与关系键约束冲突。如果源数据在这方面不干净,请考虑在相关的 source.query 字段中预先清洗数据,排除所有不满足约束条件的行(例如 WHERE person_tmbdId IS NOT NULL )。或者,在源转换中使用 where 属性。 |
选项 key_constraints 和 existence_constraints 需要 Neo4j/Aura 企业版,在 Neo4j 社区版安装上运行时无效。 |
配置
{
...
"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 查询;请改用actions。一次性查询,特别是非幂等查询,不适合在自定义查询目标中使用。原因是目标中的查询是分批运行的,因此自定义查询可能会根据从源中提取的 $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) — 要使aggregations
/where
生效,必须设置为true
。 -
aggregations
(list of objects) — 聚合在expression
属性中指定为 SQL 查询,结果以field_name
中指定的名称作为源列可用。 -
limit
(int) — 限制用于导入的源行数(默认为无限制,编码为-1
)。 -
where
(string) — 在导入之前过滤源数据(使用 SQLWHERE
子句格式)。 -
order_by
(list of objects) — 强制对源进行排序。
示例
{
"enable_grouping": true,
"aggregations": [
{
"expression": "SUM(unit_price*quantity)",
"field_name": "total_amount_sold"
},
{
"expression": "SUM(quantity)",
"field_name": "total_quantity_sold"
}
],
"limit": 50,
"where": "sourceId IS NOT NULL"
}
默认情况下,源仅处理一次;然后其数据扇出到其目标。但是,具有源转换的目标会触发新的数据获取,因为生成的源查询与默认查询不同。因此,源会为不带转换的目标处理一次,然后根据定义转换的目标数量再处理多次。因此,原始源查询必须是确定性的,否则不同的目标可能会接收到不同的数据。 |
操作
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())"
}