导入

neo4j-admin database import 尽可能快地将 CSV 数据写入 Neo4j 的原生文件格式。
它还支持 Parquet 文件格式。

您应该在以下情况使用此工具：

  • 导入性能很重要，因为您有大量数据（数百万/数十亿实体）。

  • 数据库可以离线，并且您可以直接访问托管 Neo4j DBMS 的其中一台服务器。

  • 数据库为空，或者自上次增量导入以来其内容未发生更改。

  • CSV 数据干净/无故障（节点未重复，关系起点和终点节点存在）。此工具可以处理数据故障，但性能未优化。如果您的数据存在大量故障，建议在导入前使用专用工具进行清理。

其他将数据导入 Neo4j 的方法可能更适合非管理员用户

数据变更捕获 **不** 捕获使用 neo4j-admin database import 所产生的任何数据更改。更多信息请参见 数据变更捕获 → 关键注意事项。

概述

neo4j-admin database import 命令有两种模式，都用于初始数据导入

  • full — 用于将数据导入到不存在的空数据库中。

  • incremental — 当无法通过一次 full 导入完成时使用，允许导入分解为一系列较小的导入。

运行 neo4j-admin database import 的用户必须对 server.directories.data 和 server.directories.log 具有 WRITE 权限。

本节描述 neo4j-admin database import 选项。

有关 LOAD CSV 的信息，请参见 Cypher 手册 → LOAD CSV。有关使用 neo4j-admin database import 命令的深入示例，请参阅 教程 → 导入数据。

创建输入文件时需要牢记以下几点：

  • 字段默认以逗号分隔，但可以指定不同的分隔符。

  • 所有文件必须使用相同的分隔符。

  • 节点和关系都可以使用多个数据源。

  • 数据源可以选择通过多个文件提供。

  • 一个包含数据字段信息的独立头部文件必须是每个数据源的第一个指定文件。

  • 头部文件中没有对应信息的字段将不被读取。

  • 使用 UTF-8 编码。

  • 默认情况下，导入工具会删除字符串开头和结尾的额外空白字符。引用您的数据以保留前导和尾随空白字符。

索引和约束

索引和约束在导入期间不会创建。相反，您必须在之后添加它们（参见 Cypher 手册 → 索引）。

您可以使用 --schema 选项在导入过程中创建和填充索引及约束。该选项在企业版中可用，并且仅适用于 block 格式。更多信息请参见 导入期间提供索引和约束。

完整导入

语法

导入一组 CSV 文件的语法是

neo4j-admin database import full [-h] [--expand-commands] [--verbose] [--auto-skip-subsequent-headers[=true|false]]
                                 [--ignore-empty-strings[=true|false]] [--ignore-extra-columns[=true|false]]
                                 [--legacy-style-quoting[=true|false]] [--normalize-types[=true|false]]
                                 [--overwrite-destination[=true|false]] [--skip-bad-entries-logging[=true|false]]
                                 [--skip-bad-relationships[=true|false]] [--skip-duplicate-nodes[=true|false]] [--strict
                                 [=true|false]] [--trim-strings[=true|false]] [--additional-config=<file>]
                                 [--array-delimiter=<char>] [--bad-tolerance=<num>] [--delimiter=<char>]
                                 [--format=<format>] [--high-parallel-io=on|off|auto] [--id-type=string|integer|actual]
                                 [--input-encoding=<character-set>] [--input-type=csv|parquet]
                                 [--max-off-heap-memory=<size>] [--quote=<char>] [--read-buffer-size=<size>]
                                 [--report-file=<path>] [--schema=<path>] [--temp-path=<path>] [--threads=<num>]
                                 --nodes=[<label>[:<label>]...=]<files>... [--nodes=[<label>[:<label>]...=]<files>...]...
                                 [--relationships=[<type>=]<files>...]... [--multiline-fields=true|false|<path>[,
                                 <path>] [--multiline-fields-format=v1|v2]] <database>

描述

将数据首次导入到不存在的空数据库中。

参数

表 1. neo4j-admin database import full 参数
参数 描述 默认值

<数据库>

要导入的数据库名称。如果导入前数据库不存在，您必须随后使用 CREATE DATABASE 创建它。

neo4j

以下某些选项被标记为“高级”。这些选项不应用于实验。

更多信息，请联系 Neo4j 专业服务。

选项

neo4j-admin import 也支持 Parquet 文件格式。您可以使用参数 --input-type=csv|parquet 明确指定导入工具使用 CSV 还是 Parquet。如果未定义，则默认为 CSV。CSV 的示例也可以与 Parquet 一起使用。

表 2. neo4j-admin database import full 选项
选项 描述 默认值 CSV Parquet

--additional-config=<文件>[1]

包含附加配置的配置文件。

--array-delimiter=<字符>

CSV 数据中值内数组元素之间的分隔符。也接受 TAB 和例如 U+20AC 用于指定 Unicode 字符。

  • ASCII 字符 — 例如 --array-delimiter=";"。

  • \ID — 带 ID 的 Unicode 字符，例如 --array-delimiter="\59"。

  • U+XXXX — 用 4 个十六进制字符指定的 Unicode 字符，例如 --array-delimiter="U+20AC"。

  • \t — 水平制表符 (HT)，例如 --array-delimiter="\t"。

对于水平制表符 (HT)，使用 \t 或 Unicode 字符 ID \9。

如果以 \ 开头，可以使用 Unicode 字符 ID。

;

--auto-skip-subsequent-headers[=true|false]

在包含多个文件的文件组中，自动跳过后续文件中意外的头部行。

false

--bad-tolerance=<数字>

在导入中止之前允许的错误条目数量。导入过程针对无错误数据进行了优化。因此，强烈建议在导入之前清理数据。如果在导入过程中遇到任何错误条目，您可以将错误条目数量设置为适合您需求的值。但是，设置较高的值可能会影响工具的性能。

1000

--delimiter=<字符>

CSV 数据中值之间的分隔符。也接受 TAB 和例如 U+20AC 用于指定 Unicode 字符。

  • ASCII 字符 — 例如 --delimiter=","。

  • \ID — 带 ID 的 Unicode 字符，例如 --delimiter="\44"。

  • U+XXXX — 用 4 个十六进制字符指定的 Unicode 字符，例如 --delimiter="U+20AC"。

  • \t — 水平制表符 (HT)，例如 --delimiter="\t"。

对于水平制表符 (HT)，使用 \t 或 Unicode 字符 ID \9。

如果以 \ 开头，可以使用 Unicode 字符 ID。

,

--expand-commands

允许在配置值评估中进行命令扩展。

--format=<格式>

数据库格式名称。导入的数据库将以指定格式创建，或使用配置中设置的格式。有效格式包括 standard、aligned、high_limit 和 block。

-h, --help

显示此帮助信息并退出。

--high-parallel-io=on|off|auto

忽略基于环境的启发式算法，并指示目标存储子系统是否支持高吞吐量的并行 IO 或自动检测。通常，对于 SSD、大型 RAID 阵列和网络附加存储，此选项为 on。

auto

--id-type=string|integer|actual

每个节点都必须提供一个唯一的 ID。这用于在创建关系时查找正确的节点。

可能的值为：

  • string — 用于标识节点的任意字符串。

  • integer — 用于标识节点的任意整数值。

  • actual — （高级）实际节点 ID。

string

--ignore-empty-strings[=true|false]

是否忽略输入源中的空字符串字段（即 ""），即将其视为 null。

false

--ignore-extra-columns[=true|false]

导入期间是否应忽略未指定的列。

false

--input-encoding=<字符集>

输入数据的编码字符集。

UTF-8

--input-type=csv|parquet

要导入的文件类型。可以是 csv 或 parquet。默认为 csv。

--legacy-style-quoting[=true|false]

反斜杠转义的引号（例如 \"）是否被解释为内部引号。

false

--max-off-heap-memory=<大小>

neo4j-admin 可用于各种数据结构和缓存以提高性能的最大内存。

值可以是普通数字，例如 10000000，或 20G 表示 20 GB。也可以指定为可用内存的百分比，例如 70%。

90%

--multiline-fields=true|false|<路径>[,<路径>]

在 v1 中，输入源中的字段是否可以跨越多行，即包含换行符。设置 --multiline-fields=true 可能会严重降低导入工具的性能。因此，请谨慎使用，特别是对于大型导入。在 v2 中，此选项将指定包含多行字段的文件列表。文件也可以使用正则表达式指定。

null

--multiline-fields-format=v1|v2

控制可跨越多行（即包含换行符）的输入源的解析。当设置为 v1 时，--multiline-fields 的值只能是 true 或 false。当设置为 v2 时，--multiline-fields 的值应该是包含多行字段的文件列表。

null

--nodes=[<标签>[:<标签>]…​=]<文件>…​

节点 CSV 头部和数据。

  • 从导入工具的角度来看，多个文件在逻辑上被视为一个大文件。

  • 第一行必须包含头部。

  • 在一次导入中可以指定多个这样的数据源，每个数据源都有自己的头部。

  • 文件也可以使用正则表达式指定。

可以使用适当的 URI 作为路径从 AWS S3 存储桶、Google Cloud 存储桶和 Azure 存储桶导入文件。

有关示例，请参见 使用正则表达式从 CSV 文件导入数据。

--normalize-types[=true|false]

当设置为 true 时，非数组属性值将转换为等效的 Cypher 类型。例如，所有整数值都将转换为 64 位长整数。

true

--overwrite-destination[=true|false]

在导入之前删除任何现有的数据库文件。

false

--quote=<字符>

CSV 数据中用作引号字符的字符。

引号可以按照 RFC 4180 的规定通过双写来转义，例如 "" 将被解释为字面量 "。

您不能使用 \ 进行转义。

"

--read-buffer-size=<大小>

读取输入数据每个缓冲区的大小。

它必须至少足够大以容纳输入数据中最大的单个值。该值可以是普通数字或字节单位字符串，例如 128k, 1m。

4194304

--relationships=[<类型>=]<文件>…​

关系 CSV 头部和数据。

  • 从导入工具的角度来看，多个文件在逻辑上被视为一个大文件。

  • 第一行必须包含头部。

  • 在一次导入中可以指定多个这样的数据源，每个数据源都有自己的头部。

  • 文件也可以使用正则表达式指定。

可以使用适当的 URI 作为路径从 AWS S3 存储桶、Google Cloud 存储桶和 Azure 存储桶导入文件。

有关示例，请参见 使用正则表达式从 CSV 文件导入数据。

--report-file=<路径>

存储 CSV 导入报告的文件。

导入日志文件的位置可以通过 --report-file 选项控制。如果您运行大量低数据质量的 CSV 文件导入，导入日志文件可能会变得非常大。例如，包含重复节点 ID 或尝试在不存在的节点之间创建关系的 CSV 文件可能被归类为数据质量低下。在这种情况下，您可能希望将输出导向可以处理大型日志文件的位置。

如果您在类 UNIX 系统上运行且不关心输出，可以通过将报告文件导向 /dev/null 完全消除它。

如果您需要调试导入，收集堆栈跟踪可能会很有用。这可以通过使用 --verbose 选项来完成。

import.report

--schema=<路径>

企业版 包含用于在数据导入期间创建索引和约束的 Cypher 命令的文件路径。

--skip-bad-entries-logging[=true|false]

当设置为 true 时，错误条目的详细信息不会写入日志。当数据包含大量故障时，禁用日志记录可以提高性能。强烈建议在导入之前清理数据，因为即使没有日志记录，故障也会显著影响工具的性能。

false

--skip-bad-relationships[=true|false]

是否跳过导入引用缺失节点 ID 的关系，即起始或结束节点 ID/组引用节点输入数据中未指定的节点。

如果跳过的关系在 --bad-tolerance 指定的实体限制内且 --skip-bad-entries-logging 选项被禁用，则会记录这些关系。

false

--skip-duplicate-nodes[=true|false]

是否跳过导入具有相同 ID/组的节点。

如果同一组中有多个节点具有相同的 ID，则遇到的第一个节点将被导入，而连续的此类节点将被跳过。

如果跳过的节点在 --bad-tolerance 指定的实体限制内且 --skip-bad-entries-logging 选项被禁用，则会记录这些节点。

false

--strict[=true|false]

是否需要严格检查关系中引用的节点的查找。如果禁用，大多数但并非所有引用不存在节点的关系都将被检测到。如果启用，所有这些关系都将被找到，但代价是性能降低。

false

--temp-path=<路径> 2025.04 引入

提供一个路径，用于存储在导入过程中创建和删除的临时文件。如果未明确提供，默认临时路径将在导入数据库的数据库目录中创建。

--threads=<数字>

（高级）导入工具使用的最大工作线程数。默认为 JVM 报告的可用处理器数量。由于需要一定数量的最小线程，因此该值没有下限。为获得最佳性能，此值不应大于可用处理器的数量。

20

--trim-strings[=true|false]

字符串是否应去除空白字符。

false

--verbose

启用详细输出。

1. 详情请参见 Neo4j Admin 和 Neo4j CLI → 配置。
导入的堆大小

您需要为导入设置一个相关的最大堆大小。这通过在开始导入前定义 HEAP_SIZE 环境变量来完成。例如，对于较小的导入，2G 是一个合适的值。

如果进行数千亿实体量级的导入，20G 将是一个合适的值。
记录格式

如果您的导入数据生成的图大于 340 亿节点、340 亿关系或 680 亿属性，您需要将导入工具配置为使用 block 格式。这可以通过使用导入命令的 format 选项并将值设置为 block 来实现。

bin/neo4j-admin database import full --format=block

block 格式仅在企业版中可用。
在文件中提供参数

所有选项都可以在文件中提供，并使用 @ 前缀传递给命令。当命令行过长难以管理时，这非常有用。例如，以下命令：

bin/neo4j-admin database import full @/path/to/your/<args-filename> mydb

更多信息，请参见 Picocli → AtFiles 官方文档。
同时使用多值选项和位置参数

当同时使用多值选项（例如 --nodes 和 --relationships）和位置参数时（例如在 --additional-config neo4j.properties --nodes 0-nodes.csv mydatabase 中），--nodes 选项会“贪婪”地行动，下一个选项（在本例中为 mydatabase）会通过节点转换器被引入。

这是底层库 Picocli 的一个限制，并非 Neo4j Admin 特有。更多信息，请参见 Picocli → Variable Arity Options and Positional Parameters 官方文档。

要解决此问题，请使用以下解决方案之一：

  • 将位置参数放在前面。例如，mydatabase --nodes 0-nodes.csv。

  • 将位置参数放在最后，在 -- 和最后一个多值选项的最终值之后。例如，nodes 0-nodes.csv — mydatabase。
从云存储导入

--nodes 和 --relationships 选项还可以从 AWS S3 存储桶、Google Cloud 存储桶和 Azure 存储桶导入文件。更多信息，请参见 从云存储导入文件。

示例

如果导入到之前未明确创建的数据库中，则必须在导入后创建该数据库才能使用。

从 CSV 文件导入数据

假设您已按照 CSV 头部格式 格式化了数据，使其存在于六个不同的文件中：

  1. movies_header.csv

  2. movies.csv

  3. actors_header.csv

  4. actors.csv

  5. roles_header.csv

  6. roles.csv

以下命令导入这三个数据集：

bin/neo4j-admin database import full --nodes import/movies_header.csv,import/movies.csv \
--nodes import/actors_header.csv,import/actors.csv \
--relationships import/roles_header.csv,import/roles.csv

使用正则表达式从 CSV 文件导入数据

假设您想要包含一个头部，然后是多个匹配特定模式（例如包含数字）的文件。在这种情况下，可以使用正则表达式。数字组保证按数字顺序排序，而不是按字典顺序排序。

例如

bin/neo4j-admin database import full --nodes import/node_header.csv,import/node_data_\d+\.csv

使用更复杂的正则表达式从 CSV 文件导入数据

对于包含逗号的正则表达式模式（逗号也是组中文件之间的分隔符），可以将模式用引号括起来以保留模式。

例如

bin/neo4j-admin database import full --nodes import/node_header.csv,'import/node_data_\d{1,5}.csv' databasename

从云存储导入文件

在 Neo4j 2025.03 中，引入了新的云集成设置，以更好地支持云生态系统中的部署和管理。详情请参阅 配置设置 → 云存储集成设置。

以下示例展示了如何使用 --nodes 和 --relationships 选项导入存储在云存储桶中的数据。

Neo4j 使用 AWS SDK v2 通过 AWS URL 调用 AWS 上的 API。另外，您可以覆盖端点，以便 AWS SDK 可以使用系统变量 aws.endpointUrls3、aws.endpointUrlS3 或 aws.endpointUrl，或环境变量 AWS_ENDPOINT_URL_S3 或 AWS_ENDPOINT_URL 与替代存储系统（如 Ceph、Minio 或 LocalStack）通信。

  1. 按照 AWS 官方文档中的说明安装 AWS CLI — 安装 AWS CLI version 2。

  2. 使用 AWS CLI 创建 S3 存储桶和用于存储备份文件的目录

    aws s3 mb --region=us-east-1 s3://myBucket
aws s3api put-object --bucket myBucket --key myDirectory/

    有关如何创建存储桶和使用 AWS CLI 的更多信息，请参见 AWS 官方文档 — 将 Amazon S3 与 AWS CLI 结合使用 和 将高级 (s3) 命令与 AWS CLI 结合使用。

  3. 通过运行以下命令验证 ~/.aws/config 文件是否正确

    cat ~/.aws/config

    输出应如下所示

    [default]
region=us-east-1

  4. 通过在 ~/.aws/credentials 文件中设置 aws_access_key_id 和 aws_secret_access_key 来配置对 AWS S3 存储桶的访问，如果需要，还可以使用存储桶策略。例如：

    1. 使用 aws configure set aws_access_key_id aws_secret_access_key 命令设置您的 AWS IAM 凭据，并验证 ~/.aws/credentials 是否正确

      cat ~/.aws/credentials

      输出应如下所示

      [default]
aws_access_key_id=this.is.secret
aws_secret_access_key=this.is.super.secret

    2. 此外，您可以使用基于资源的策略来授予对 S3 存储桶及其对象的访问权限。创建一个包含以下内容的策略文档并将其附加到存储桶。请注意，这两个资源条目对于能够下载和上传文件都很重要。

      {
    "Version": "2012-10-17",
    "Id": "Neo4jBackupAggregatePolicy",
    "Statement": [
        {
            "Sid": "Neo4jBackupAggregateStatement",
            "Effect": "Allow",
            "Action": [
                "s3:ListBucket",
                "s3:GetObject",
                "s3:PutObject",
                "s3:DeleteObject"
            ],
            "Resource": [
                "arn:aws:s3:::myBucket/*",
                "arn:aws:s3:::myBucket"
            ]
        }
    ]
}

  5. 运行 neo4j-admin database import 命令，从您的 AWS S3 存储桶导入数据。此示例假设您的数据存储在存储桶中的 myBucket/data 文件夹中。

    bin/neo4j-admin database import full --nodes s3://myBucket/data/nodes.csv --relationships s3://myBucket/data/relationships.csv newdb

  1. 确保您拥有 Google 帐户并在 Google Cloud Platform (GCP) 中创建了项目。

    1. 按照 Google 官方文档中的说明安装 gcloud CLI — 安装 gcloud CLI。

    2. 使用 Google 官方文档创建服务帐号和服务帐号密钥 — 创建服务帐号 和 创建和管理服务帐号密钥。

    3. 下载服务帐号的 JSON 密钥文件。

    4. 将 GOOGLE_APPLICATION_CREDENTIALS 和 GOOGLE_CLOUD_PROJECT 环境变量分别设置为 JSON 密钥文件的路径和项目 ID

      export GOOGLE_APPLICATION_CREDENTIALS="/path/to/keyfile.json"
export GOOGLE_CLOUD_PROJECT=YOUR_PROJECT_ID

    5. 使用您创建的服务帐号的电子邮件地址、JSON 密钥文件的路径和项目 ID 对 gcloud CLI 进行身份验证

      gcloud auth activate-service-account service-account@example.com --key-file=$GOOGLE_APPLICATION_CREDENTIALS --project=$GOOGLE_CLOUD_PROJECT

      更多信息，请参见 Google 官方文档 — gcloud auth activate-service-account。

    6. 使用 Google 官方文档在 Google Cloud Storage 中创建存储桶 — 创建存储桶。

    7. 通过运行以下命令验证存储桶是否已创建

      gcloud storage ls

      输出应列出已创建的存储桶。

  2. 运行 neo4j-admin database import 命令，从您的 Google 存储桶导入数据。此示例假设您的数据存储在存储桶中的 myBucket/data 文件夹中。

    bin/neo4j-admin database import full --nodes gs://myBucket/data/nodes.csv --relationships gs://myBucket/data/relationships.csv newdb

  1. 确保您拥有 Azure 帐户、Azure 存储帐户和 Blob 容器。

    1. 您可以使用 Azure 门户创建存储帐户。
      更多信息，请参见 Azure 官方文档中的 创建存储帐户。

    2. 在 Azure 门户中创建 Blob 容器。
      更多信息，请参见 Azure 官方文档中的 快速入门：使用 Azure 门户上传、下载和列出 Blob。

  2. 按照 Azure 官方文档中的说明安装 Azure CLI — Azure 官方文档。

  3. 使用默认 Azure 凭据对 Azure 进行 neo4j 或 neo4j-admin 进程的身份验证。
    更多信息，请参见 Azure 官方文档中的 默认 Azure 凭据。

    az login

    然后您应该可以在 neo4j 或 neo4j-admin 中使用 Azure URL。

  4. 要验证您是否使用登录凭据访问容器，请运行以下命令

    # Upload a file:
az storage blob upload --file someLocalFile  --account-name accountName - --container someContainer --name remoteFileName  --auth-mode login

# Download the file
az storage blob download  --account-name accountName --container someContainer --name remoteFileName --file downloadedFile --auth-mode login

# List container files
az storage blob list  --account-name someContainer --container someContainer  --auth-mode login

  5. 运行 neo4j-admin database import 命令，从您的 Azure Blob 存储容器导入数据。此示例假设您的数据存储在容器中的 myStorageAccount/myContainer/data 文件夹中。

    bin/neo4j-admin database import full --nodes azb://myStorageAccount/myContainer/data/nodes.csv --relationships azb://myStorageAccount/myContainer/data/relationships.csv newdb

增量导入

增量导入支持 block 格式。

增量导入允许您分批将大量数据合并到图中。当无法通过一次完整导入完成时，您可以将此操作作为初始数据加载的一部分运行。此外，您可以通过增量导入更新图，这比事务性插入此类数据性能更高。

增量导入需要使用 --force 选项，并且只能在现有数据库上运行。

如果您想在一个命令中执行增量导入，必须停止数据库。

如果您无法承受数据库完全停机，请将操作拆分为几个阶段：

  • prepare 阶段（离线）

  • build 阶段（离线或只读）

  • merge 阶段（离线）

prepare 和 merge 阶段必须停止数据库。在 build 阶段，数据库可以保持在线但置于只读模式。有关详细示例，请参见 分阶段增量导入。

强烈建议在运行增量导入之前备份数据库，因为如果 merge 阶段失败、中止或崩溃，可能会损坏数据库。

语法

增量导入一组 CSV 文件的语法是

neo4j-admin database import incremental [-h] [--expand-commands] --force [--update-all-matching-relationships]
                                        [--verbose] [--auto-skip-subsequent-headers[=true|false]]
                                        [--ignore-empty-strings[=true|false]] [--ignore-extra-columns[=true|false]]
                                        [--legacy-style-quoting[=true|false]] [--normalize-types[=true|false]]
                                        [--skip-bad-entries-logging[=true|false]] [--skip-bad-relationships
                                        [=true|false]] [--skip-duplicate-nodes[=true|false]] [--strict[=true|false]]
                                        [--trim-strings[=true|false]] [--additional-config=<file>]
                                        [--array-delimiter=<char>] [--bad-tolerance=<num>] [--delimiter=<char>]
                                        [--high-parallel-io=on|off|auto] [--id-type=string|integer|actual]
                                        [--input-encoding=<character-set>] [--input-type=csv|parquet]
                                        [--max-off-heap-memory=<size>] [--quote=<char>] [--read-buffer-size=<size>]
                                        [--report-file=<path>] [--schema=<path>] [--stage=all|prepare|build|merge]
                                        [--temp-path=<path>] [--threads=<num>] --nodes=[<label>[:<label>]...=]<files>...
                                        [--nodes=[<label>[: <label>]...=]<files>...]... [--relationships=[<type>=]<files>...]...
                                        [--multiline-fields=true|false|<path>[,<path>]
                                        [--multiline-fields-format=v1|v2]] <database>

描述

增量导入到现有数据库。

用法和限制

导入工具在独立服务器上运行良好。

在数据库有多个副本的集群环境中，更新后的数据库必须用作重新播种其余数据库副本的源。您可以使用 dbms.recreateDatabase() 过程。详情请参见 重新创建数据库。

在增量导入后未重新播种或在单个服务器上执行增量导入而数据库在其他集群成员上仍保持在线状态的情况下启动集群数据库，可能会导致不可预测的后果，包括集群成员之间的数据不一致。

增量导入命令可用于添加：

  • 具有标签和属性的新节点。

    请注意，您必须为构成主键或唯一可识别节点的属性键和标签组合设置节点属性唯一性约束。否则，该命令将抛出错误并退出。更多信息请参见 CSV 头部格式。

  • 现有节点或新节点之间的新关系。

从 2025.01 开始，增量导入命令还可以用于：

  • 向现有节点或关系添加新属性。

  • 更新或删除节点或关系中的属性。

  • 更新或删除节点中的标签。

  • 删除现有节点和关系。

这仅受 block 格式支持。更多信息请参见 通过 CSV 文件应用数据更改。

参数

表 3. neo4j-admin database import incremental 参数
参数 描述 默认值

<数据库>

要导入的数据库名称。如果导入前数据库不存在，您必须随后使用 CREATE DATABASE 创建它。

neo4j

选项

表 4. neo4j-admin database import incremental 选项
选项 描述 默认值 CSV Parquet

--additional-config=<文件>[2]

包含附加配置的配置文件。

--array-delimiter=<字符>

CSV 数据中值内数组元素之间的分隔符。也接受 TAB 和例如 U+20AC 用于指定 Unicode 字符。

  • ASCII 字符 — 例如 --array-delimiter=";"。

  • \ID — 带 ID 的 Unicode 字符，例如 --array-delimiter="\59"。

  • U+XXXX — 用 4 个十六进制字符指定的 Unicode 字符，例如 --array-delimiter="U+20AC"。

  • \t — 水平制表符 (HT)，例如 --array-delimiter="\t"。

对于水平制表符 (HT)，使用 \t 或 Unicode 字符 ID \9。

如果以 \ 开头，可以使用 Unicode 字符 ID。

;

--auto-skip-subsequent-headers[=true|false]

在包含多个文件的文件组中，自动跳过后续文件中意外的头部行。

false

--bad-tolerance=<数字>

在导入中止之前允许的错误条目数量。导入过程针对无错误数据进行了优化。因此，强烈建议在导入之前清理数据。如果在导入过程中遇到任何错误条目，您可以将错误条目数量设置为适合您需求的值。但是，设置较高的值可能会影响工具的性能。

1000

--delimiter=<字符>

CSV 数据中值之间的分隔符。也接受 TAB 和例如 U+20AC 用于指定 Unicode 字符。

  • ASCII 字符 — 例如 --delimiter=","。

  • \ID — 带 ID 的 Unicode 字符，例如 --delimiter="\44"。

  • U+XXXX — 用 4 个十六进制字符指定的 Unicode 字符，例如 --delimiter="U+20AC"。

  • \t — 水平制表符 (HT)，例如 --delimiter="\t"。

对于水平制表符 (HT)，使用 \t 或 Unicode 字符 ID \9。

如果以 \ 开头，可以使用 Unicode 字符 ID。

,

--expand-commands

允许在配置值评估中进行命令扩展。

--force

通过设置此标志确认增量导入。

-h, --help

显示此帮助信息并退出。

--high-parallel-io=on|off|auto

忽略基于环境的启发式算法，并指示目标存储子系统是否支持高吞吐量的并行 IO 或自动检测。通常，对于 SSD、大型 RAID 阵列和网络附加存储，此选项为 on。

auto

--id-type=string|integer|actual

每个节点都必须提供一个唯一的 ID。这用于在创建关系时查找正确的节点。

可能的值为：

  • string — 用于标识节点的任意字符串。

  • integer — 用于标识节点的任意整数值。

  • actual — （高级）实际节点 ID。

string

--ignore-empty-strings[=true|false]

是否忽略输入源中的空字符串字段（即 ""），即将其视为 null。

false

--ignore-extra-columns[=true|false]

导入期间是否应忽略未指定的列。

false

--input-encoding=<字符集>

输入数据的编码字符集。

UTF-8

--input-type=csv|parquet

要导入的文件类型。可以是 csv 或 parquet。默认为 csv。

--legacy-style-quoting[=true|false]

反斜杠转义的引号（例如 \"）是否被解释为内部引号。

false

--max-off-heap-memory=<大小>

neo4j-admin 可用于各种数据结构和缓存以提高性能的最大内存。

值可以是普通数字，例如 10000000，或 20G 表示 20 GB。也可以指定为可用内存的百分比，例如 70%。

90%

--multiline-fields=true|false|<路径>[,<路径>]

在 v1 中，输入源中的字段是否可以跨越多行，即包含换行符。设置 --multiline-fields=true 可能会严重降低导入工具的性能。因此，请谨慎使用，特别是对于大型导入。在 v2 中，此选项将指定包含多行字段的文件列表。文件也可以使用正则表达式指定。

null

--multiline-fields-format=v1|v2

控制可跨越多行（即包含换行符）的输入源的解析。当设置为 v1 时，--multiline-fields 的值只能是 true 或 false。当设置为 v2 时，--multiline-fields 的值应该是包含多行字段的文件列表。

null

--nodes=[<标签>[:<标签>]…​=]<文件>…​

节点 CSV 头部和数据。

  • 从导入工具的角度来看，多个文件在逻辑上被视为一个大文件。

  • 第一行必须包含头部。

  • 在一次导入中可以指定多个这样的数据源，每个数据源都有自己的头部。

  • 文件也可以使用正则表达式指定。

可以使用适当的 URI 作为路径从 AWS S3 存储桶、Google Cloud 存储桶和 Azure 存储桶导入文件。

有关示例，请参见 使用正则表达式从 CSV 文件导入数据。

--normalize-types[=true|false]

当设置为 true 时，非数组属性值将转换为等效的 Cypher 类型。例如，所有整数值都将转换为 64 位长整数。

true

--quote=<字符>

CSV 数据中用作引号字符的字符。

引号可以按照 RFC 4180 的规定通过双写来转义，例如 "" 将被解释为字面量 "。

您不能使用 \ 进行转义。

"

--read-buffer-size=<大小>

读取输入数据每个缓冲区的大小。

它必须至少足够大以容纳输入数据中最大的单个值。该值可以是普通数字或字节单位字符串，例如 128k, 1m。

4194304

--relationships=[<类型>=]<文件>…​

关系 CSV 头部和数据。

  • 从导入工具的角度来看，多个文件在逻辑上被视为一个大文件。

  • 第一行必须包含头部。

  • 在一次导入中可以指定多个这样的数据源，每个数据源都有自己的头部。

  • 文件也可以使用正则表达式指定。

可以使用适当的 URI 作为路径从 AWS S3 存储桶、Google Cloud 存储桶和 Azure 存储桶导入文件。

有关示例，请参见 使用正则表达式从 CSV 文件导入数据。

--report-file=<路径>

存储 CSV 导入报告的文件。

导入日志文件的位置可以通过 --report-file 选项控制。如果您运行大量低数据质量的 CSV 文件导入，导入日志文件可能会变得非常大。例如，包含重复节点 ID 或尝试在不存在的节点之间创建关系的 CSV 文件可能被归类为数据质量低下。在这种情况下，您可能希望将输出导向可以处理大型日志文件的位置。

如果您在类 UNIX 系统上运行且不关心输出，可以通过将报告文件导向 /dev/null 完全消除它。

如果您需要调试导入，收集堆栈跟踪可能会很有用。这可以通过使用 --verbose 选项来完成。

import.report

--schema=<路径> 从 2025.02 开始可用

包含用于在数据导入期间创建索引和约束的 Cypher 命令的文件路径。

--skip-bad-entries-logging[=true|false]

当设置为 true 时，错误条目的详细信息不会写入日志。当数据包含大量故障时，禁用日志记录可以提高性能。强烈建议在导入之前清理数据，因为即使没有日志记录，故障也会显著影响工具的性能。

false

--skip-bad-relationships[=true|false]

是否跳过导入引用缺失节点 ID 的关系，即起始或结束节点 ID/组引用节点输入数据中未指定的节点。

如果跳过的关系在 --bad-tolerance 指定的实体限制内且 --skip-bad-entries-logging 选项被禁用，则会记录这些关系。

false

--skip-duplicate-nodes[=true|false]

是否跳过导入具有相同 ID/组的节点。

如果同一组中有多个节点具有相同的 ID，则遇到的第一个节点将被导入，而连续的此类节点将被跳过。

如果跳过的节点在 --bad-tolerance 指定的实体限制内且 --skip-bad-entries-logging 选项被禁用，则会记录这些节点。

false

--stage=all|prepare|build|merge

增量导入阶段。

对于增量导入到现有数据库，使用 all（这需要停止数据库）。

对于半在线增量导入，先运行 prepare（在已停止的数据库上），然后是 build（在可能运行的数据库上），最后是 merge（在已停止的数据库上）。

all

--strict[=true|false]

是否需要严格检查关系中引用的节点的查找。如果禁用，大多数但并非所有引用不存在节点的关系都将被检测到。如果启用，所有这些关系都将被找到，但代价是性能降低。

false

--temp-path=<路径> 2025.04 引入

提供一个路径，用于存储在导入过程中创建和删除的临时文件。如果未明确提供，默认临时路径将在导入数据库的数据库目录中创建。

--threads=<数字>

（高级）导入工具使用的最大工作线程数。默认为 JVM 报告的可用处理器数量。由于需要一定数量的最小线程，因此该值没有下限。为获得最佳性能，此值不应大于可用处理器的数量。

20

--trim-strings[=true|false]

字符串是否应去除空白字符。

false

--update-all-matching-relationships

2025.01 引入 是否更新所有与关系数据条目匹配的现有关系。如果禁用，当关系数据条目在 --bad-tolerance 指定的实体限制内且 --skip-bad-entries-logging 选项禁用时，将记录该关系数据条目。

false

--verbose

启用详细输出。

2. 详情请参见 Neo4j Admin 和 Neo4j CLI → 配置。
同时使用多值选项和位置参数

当同时使用多值选项（例如 --nodes 和 --relationships）和位置参数时（例如在 --additional-config neo4j.properties --nodes 0-nodes.csv mydatabase 中），--nodes 选项会“贪婪”地行动，下一个选项（在本例中为 mydatabase）会通过节点转换器被引入。

这是底层库 Picocli 的一个限制，并非 Neo4j Admin 特有。更多信息，请参见 Picocli → Variable Arity Options and Positional Parameters 官方文档。

要解决此问题，请使用以下解决方案之一：

  • 将位置参数放在前面。例如，mydatabase --nodes 0-nodes.csv。

  • 将位置参数放在最后，在 -- 和最后一个多值选项的最终值之后。例如，nodes 0-nodes.csv — mydatabase。

示例

有两种增量导入数据的方式。

单命令增量导入

如果停机时间不是问题，您可以使用 --stage=all 选项运行单个命令。此选项要求数据库停止。

neo4j@system> STOP DATABASE db1 WAIT;
...
bin/neo4j-admin database import incremental --stage=all --nodes=N1=../../raw-data/incremental-import/b.csv db1

分阶段增量导入

如果您无法承受数据库的完全停机，可以将导入分为三个阶段运行。

  1. prepare 阶段

    在此阶段，导入工具会分析 CSV 头部并将相关数据复制到新的增量数据库路径。导入命令使用 --stage=prepare 选项运行，并且数据库必须停止。

    1. 使用 system 数据库，通过 WAIT 选项停止数据库 db1，以确保在运行增量导入命令之前发生检查点。数据库必须停止才能运行 --stage=prepare。

      STOP DATABASE db1 WAIT

    2. 使用 --stage=prepare 选项运行增量导入命令

      bin/neo4j-admin database import incremental --stage=prepare --nodes=N1=../../raw-data/incremental-import/c.csv db1

  2. build 阶段

    在此阶段，导入工具将数据导入、去重并在新的增量数据库路径中验证。这是最长的阶段，您可以将数据库置于只读模式以允许读取访问。导入命令使用 --stage=build 选项运行。

    1. 将数据库置于只读模式

      ALTER DATABASE db1 SET ACCESS READ ONLY

    2. 使用 --stage=build 选项运行增量导入命令

      bin/neo4j-admin database import incremental --stage=build --nodes=N1=../../raw-data/incremental-import/c.csv db1

  3. merge 阶段

    在此阶段，导入工具将新数据与数据库中的现有数据合并。它还会更新受影响的索引并维护受影响的属性唯一性约束和属性存在性约束。导入命令使用 --stage=merge 选项运行，并且数据库必须停止。在使用 --stage=merge 时，不需要包含 --nodes 或 --relationships 选项。

    1. 使用 system 数据库，通过 WAIT 选项停止数据库 db1，以确保在运行增量导入命令之前发生检查点。

      STOP DATABASE db1 WAIT

    2. 使用 --stage=merge 选项运行增量导入命令

      bin/neo4j-admin database import incremental --stage=merge db1

CSV 头部格式

每个数据源的头部文件指定数据字段应如何解释。您必须为头部文件和数据文件使用相同的分隔符。

头部包含每个字段的信息，格式为 <名称>:<字段类型>。 <名称> 用于属性和节点 ID。在所有其他情况下，字段的 <名称> 部分将被忽略。

增量导入

使用增量导入时，您必须为构成主键或唯一可识别节点的属性键和标签组合设置节点属性唯一性约束。例如，导入具有 Person 标签且由 uuid 属性键唯一标识的节点时，头部格式应为 uuid:ID{label:Person}。

在使用多个组时也是如此。例如，您可以使用 uuid:ID(Person){label:Person}，其中关系 CSV 数据可以引用其 :START_ID 和 :END_ID 的不同组，就像完整导入方法一样。

Parquet 的扩展头部支持

除了 CSV 导入支持的头部格式外，Parquet 导入还支持名称映射头部文件。这些文件包含两行条目，其中第一行表示名称（包括可选类型、ID 组等），第二行引用数据文件中原始列的名称。

movie_header.csv
movieId:ID,title,year:int,:LABEL
id,movie_title,year,label

如果为一组标签或关系类型提供了头部文件，导入工具将忽略头部中未提及的列。

节点文件

包含节点数据的文件可以包含 ID 字段、LABEL 字段和属性。

ID

如果节点要通过导入中创建的任何关系连接，则每个节点都必须具有唯一的 ID。Neo4j 使用 ID 在创建关系时找到正确的节点。请注意，无论标签如何，ID 在组内的所有节点中都必须是唯一的。唯一 ID 将持久化在一个属性中，该属性的名称由字段定义 <名称>:ID 的 <名称> 部分定义。如果未定义此类属性名称，则唯一 ID 将用于导入，但稍后无法引用。如果未指定 ID，则节点将被导入，但在导入期间不会与其他节点连接。如果提供了属性名称，则该属性类型可以通过 --id-type 选项全局配置（如同属性数据类型）。
您可以使用头部中的 id-type 选项为其组中的节点属性指定要存储的不同值 ID 类型，例如：id:ID(MyGroup){label:MyLabel, id-type: int}。此 ID 类型会覆盖全局 --id-type 选项。例如，全局 id-type 可以是字符串，但节点将以 int 类型存储其 ID 属性中的 ID。更多信息，请参见在组中存储不同值类型的 ID。
节点头部也可以包含多个 ID 列，其中关系数据引用所有这些列的复合值。这也意味着使用 string 作为 id-type。对于每个 ID 列，您可以指定将其值存储为不同的节点属性。但是，复合值不能存储为节点属性。更多信息，请参见使用多个节点 ID。

LABEL

从此字段读取一个或多个标签。与数组值一样，多个标签通过 ; 分隔，或者通过 --array-delimiter 指定的字符分隔。block 格式的标签名称最大长度为 16,383 个字符。

示例 1. 定义节点文件

您在 movies_header.csv 文件中定义电影的头部。电影具有 movieId、year 和 title 属性。您还为标签指定了一个字段。

movieId:ID,title,year:int,:LABEL

您在 movies.csv 文件中定义了三部电影。它们包含头部文件中定义的所有属性。所有电影都赋予了 Movie 标签。其中两部还赋予了 Sequel 标签。

tt0133093,"The Matrix",1999,Movie
tt0234215,"The Matrix Reloaded",2003,Movie;Sequel
tt0242653,"The Matrix Revolutions",2003,Movie;Sequel

类似地，您还在 actors_header.csv 和 actors.csv 文件中定义了三位演员。他们都具有 personId 和 name 属性，以及 Actor 标签。

personId:ID,name,:LABEL
keanu,"Keanu Reeves",Actor
laurence,"Laurence Fishburne",Actor
carrieanne,"Carrie-Anne Moss",Actor

关系文件

包含关系数据的文件有三个必填字段，并且还可以有属性。必填字段是：

TYPE

用于此关系的类型。block 格式的关系类型名称最大长度为 16,383 个字符。

START_ID

此关系的起始节点 ID。

END_ID

此关系的结束节点 ID。

START_ID 和 END_ID 引用前面部分解释的节点数据源中定义的唯一节点 ID。这些都不带名称，例如如果定义了 <名称>:START_ID 或 <名称>:END_ID，则 <名称> 部分将被忽略。它们也不带 <字段类型>，例如如果定义了 :START_ID:int 或 :END_ID:int，则 :int 部分在类型信息的上下文中没有任何意义。

示例 2. 定义关系文件

在此示例中，假设您将使用前面示例中的两个节点文件以及以下关系文件。

您在 roles_header.csv 和 roles.csv 文件中定义演员与电影之间的关系。每行将起始节点和结束节点通过 ACTED_IN 关系类型连接起来。请注意，您如何使用上述节点文件中的唯一标识符 personId 和 movieId。演员在此电影中扮演的角色的名称作为 role 属性存储在关系上。

:START_ID,role,:END_ID,:TYPE
keanu,"Neo",tt0133093,ACTED_IN
keanu,"Neo",tt0234215,ACTED_IN
keanu,"Neo",tt0242653,ACTED_IN
laurence,"Morpheus",tt0133093,ACTED_IN
laurence,"Morpheus",tt0234215,ACTED_IN
laurence,"Morpheus",tt0242653,ACTED_IN
carrieanne,"Trinity",tt0133093,ACTED_IN
carrieanne,"Trinity",tt0234215,ACTED_IN
carrieanne,"Trinity",tt0242653,ACTED_IN

属性数据类型

对于属性，字段的 <名称> 部分指定属性键，而 <字段类型> 部分分配数据类型。节点数据文件和关系数据文件中都可以包含属性。block 格式的属性键最大长度为 16,383 个字符。

使用 int、long、float、double、boolean、byte、short、char、string、point、date、localtime、time、localdatetime、datetime 和 duration 之一来指定属性的数据类型。默认情况下，类型（数组除外）将转换为 Cypher 类型。请参见 Cypher 手册 → 属性、结构和构造值。

此行为可以使用选项 --normalize-types=false 禁用。规范化类型可能需要更多磁盘空间，但可以避免 Cypher 在查询期间进行类型转换。如果没有给出数据类型，则默认为 string。

要定义数组类型，请在类型后附加 []。默认情况下，数组值以 ; 分隔。可以使用 --array-delimiter 指定不同的分隔符。数组不受 --normalize-types 标志的影响。例如，如果您希望将字节数组存储为 Cypher long 数组，则必须将属性明确声明为 long[]。

基于 CSV 的导入不导入空数组，因为它们无法与设置为 null 的数组区分开来。但是，Parquet 导入能够区分它们，并将空数组导入为空数组，将 null 导入为 null。

布尔值在与文本 true 完全匹配时为 true。所有其他值均为 false。包含分隔符的字段需要用双引号括起来进行转义，或者使用 --delimiter 选项指定不同的分隔符。

示例 3. 包含数据类型的头部格式

此示例演示了 CSV 头部中指定的几种不同数据类型。

:ID,name,joined:date,active:boolean,points:int
user01,Joe Soap,2017-05-05,true,10
user02,Jane Doe,2017-08-21,true,15
user03,Moe Know,2018-02-17,false,7
point 数据类型的特殊考量

点使用 Cypher 映射语法指定。该映射允许与 Cypher 手册 → Point 函数的输入相同的键。头部中的 point 数据类型可以附带一个用于该列所有值的默认值映射，例如 point{crs: 'WGS-84'}。以这种方式指定头部允许您在数据文件的值位置拥有不完整的映射。可选地，数据文件中的值可以覆盖头部中的默认值。

示例 4. point 数据类型的属性格式

此示例演示了在导入头部和数据文件中使用 point 数据类型的各种方法。

您将导入城市的名称和位置坐标。首先，您将头部定义为：

:ID,name,location:point{crs:WGS-84}

然后您在数据文件中定义城市。

  • 第一个城市的位置使用 latitude 和 longitude 定义，这在使用头部中定义的坐标系时是预期的。

  • 第二个城市改用 x 和 y。这通常会导致使用笛卡尔坐标系的点的生成。由于头部定义了 crs:WGS-84，因此将使用该坐标系。

  • 第三个城市覆盖了头部中定义的坐标参考系统，并将其明确设置为 WGS-84-3D。

:ID,name,location:point{crs:WGS-84}
city01,"Malmö","{latitude:55.6121514, longitude:12.9950357}"
city02,"London","{y:51.507222, x:-0.1275}"
city03,"San Mateo","{latitude:37.554167, longitude:-122.313056, height: 100, crs:'WGS-84-3D'}"

请注意，所有点映射都包含在双引号 " 中，以防止其中包含的 , 字符被解释为列分隔符。另一种方法是使用 --delimiter='\t' 并使用制表符分隔符重新格式化文件，在这种情况下不需要 " 字符。

:ID name    location:point{crs:WGS-84}
city01  Malmö   {latitude:55.6121514, longitude:12.9950357}
city02  London  {y:51.507222, x:-0.1275}
city03  San Mateo   {latitude:37.554167, longitude:-122.313056, height: 100, crs:'WGS-84-3D'}
时间数据类型的特殊考量

所有时间数据类型的格式必须按照 Cypher 手册 → 时间瞬间语法 和 Cypher 手册 → 持续时间语法 中所述进行定义。其中两种时间类型，Time 和 DateTime，接受一个时区参数，该参数可能在数据文件中的所有值或许多值之间是通用的。因此，可以在头部中为 Time 和 DateTime 值指定默认时区，例如：time{timezone:+02:00} 和：datetime{timezone:Europe/Stockholm}。如果未指定默认时区，则默认时区由 db.temporal.timezone 配置设置确定。默认时区可以在数据文件中的值中明确覆盖。

示例 5. 时间数据类型的属性格式

此示例演示了在导入头部和数据文件中使用 datetime 数据类型的各种方法。

首先，您定义包含两个 DateTime 列的头部。第一个定义了时区，而第二个没有：

:ID,date1:datetime{timezone:Europe/Stockholm},date2:datetime

然后您在数据文件中定义日期。

  • 第一行有两个未指定明确时区的值。date1 的值将使用头部中为该字段指定的 Europe/Stockholm 时区。date2 的值将使用数据库配置的默认时区。

  • 在第二行中，date1 和 date2 都明确将时区设置为 Europe/Berlin。这会覆盖 date1 的头部定义以及数据库配置的默认时区。

1,2018-05-10T10:30,2018-05-10T12:30
2,2018-05-10T10:30[Europe/Berlin],2018-05-10T12:30[Europe/Berlin]

使用 ID 空间

默认情况下，导入工具假设节点标识符在所有节点文件中是唯一的。在许多情况下，ID 仅在每个实体文件中是唯一的，例如，当您的 CSV 文件包含从关系数据库中提取的数据并且 ID 字段是从相应表中的主键列中提取时。为了处理这种情况，您可以定义 ID 空间。ID 空间在节点文件的 ID 字段中使用语法 ID(<ID 空间标识符>) 定义。要在关系文件中引用 ID 空间的 ID，您可以使用语法 START_ID(<ID 空间标识符>) 和 END_ID(<ID 空间标识符>)。

示例 6. 定义和使用 ID 空间

在 movies_header.csv 文件中定义一个 Movie-ID ID 空间。

movieId:ID(Movie-ID),title,year:int,:LABEL
1,"The Matrix",1999,Movie
2,"The Matrix Reloaded",2003,Movie;Sequel
3,"The Matrix Revolutions",2003,Movie;Sequel

在 actors_header.csv 文件的头部中定义一个 Actor-ID ID 空间。

personId:ID(Actor-ID),name,:LABEL
1,"Keanu Reeves",Actor
2,"Laurence Fishburne",Actor
3,"Carrie-Anne Moss",Actor

现在，在将演员连接到电影时使用之前定义的 ID 空间。

:START_ID(Actor-ID),role,:END_ID(Movie-ID),:TYPE
1,"Neo",1,ACTED_IN
1,"Neo",2,ACTED_IN
1,"Neo",3,ACTED_IN
2,"Morpheus",1,ACTED_IN
2,"Morpheus",2,ACTED_IN
2,"Morpheus",3,ACTED_IN
3,"Trinity",1,ACTED_IN
3,"Trinity",2,ACTED_IN
3,"Trinity",3,ACTED_IN

使用多个节点 ID

节点头部也可以包含多个 ID 列，其中关系数据引用所有这些列的复合值。这也意味着使用 string 作为 id-type。

对于每个 ID 列，您可以指定将其值存储为不同的节点属性。但是，复合值不能存储为节点属性。

增量导入不支持使用多个节点标识符。此功能仅在完整导入中可用。
示例 7. 将多个 ID 定义为节点属性

您可以在节点头部中定义多个 ID 列。例如，您可以定义一个包含两个 ID 列的节点头部。

nodes_header.csv
:ID,:ID,name
nodes.csv
aa,11,John
bb,22,Paul

现在，在定义关系时使用这两个 ID：

relationships_header.csv
:START_ID,:TYPE,:END_ID
relationships.csv
aa11,WORKS_WITH,bb22
示例 8. 定义存储在 ID 空间中的多个 ID

在 nodes_header.csv 文件中定义一个 MyGroup ID 空间。

nodes_header.csv
personId:ID(MyGroup),memberId:ID(MyGroup),name
nodes.csv
aa,11,John
bb,22,Paul

现在，在连接 John 和 Paul 时使用定义的 ID 空间，并在关系中使用两个 ID。

relationships_header.csv
:START_ID(MyGroup),:TYPE,:END_ID(MyGroup)
relationships.csv
aa11,WORKS_WITH,bb22

在组中存储不同值类型的 ID

您可以通过在头部中定义 id-type 选项来控制将存储的节点属性的 ID 类型，例如 :ID{id-type:long}。头部中的 id-type 选项会覆盖提供给命令的全局 --id-type 值。这样，您可以为不同组的节点拥有不同类型的属性值。例如，全局 id-type 可以是字符串，但某些节点可以将它们的 ID 存储为 long 类型在其 ID 属性中。

示例 9. 导入具有不同 ID 值类型的节点
persons_header.csv
id:ID(GroupOne){id-type:long},name,:LABEL
persons.csv
123,P1,Person
456,P2,Person
games_header.csv
id:ID(GroupTwo),name,:LABEL
games.csv
ABC,G1,Game
DEF,G2,Game
导入节点
neo4j_home$ --nodes persons.csv --nodes games.csv --id-type string

persons 组中节点的 id 属性将存储为 long 类型，而 games 组中节点的 id 属性将存储为 string 类型，因为全局 id-type 是字符串。

通过 CSV 文件应用数据更改

您可以在增量导入期间使用 CSV 文件更新现有节点、关系、标签或属性。

此功能仅受 block 格式支持。

为每行设置显式操作

您可以通过在头部文件中使用 :ACTION 关键字为 CSV 文件中的每一行设置显式操作。如果未指定操作，导入工具将像在完整导入模式下一样工作，创建新数据。

支持以下操作：

  • empty = CREATE (默认)

  • C, CREATE - 创建新节点和关系，带或不带属性，以及标签。

  • U, UPDATE - 更新现有节点、关系、标签和属性。

  • D, DELETE - 删除现有节点或关系。删除节点也会删除其关系（DETACH DELETE）。

在 CSV 文件中使用操作更新节点
:ACTION,uid:ID(label:Person),name,:LABEL
CREATE,person1,"Keanu Reeves",Actor
UPDATE,person2,"Laurence Fishburne",Actor
DELETE,person4,,

节点通过其键/标签组合的唯一属性值进行识别，该组合由标题指定。

在 CSV 文件中使用操作更新关系
:ACTION,:START_ID,:END_ID,:TYPE,role
CREATE,person1,movie1,ACTED_IN,"Neo"
UPDATE,person2,movie1,ACTED_IN,"Morpheus"
DELETE,person3,movie1,ACTED_IN

关系通过其起点和终点节点 ID 及其类型进行非唯一识别。

为了进一步缩小选择范围，您可以将属性列标记为标识符，以帮助唯一（或至少更唯一）地选择关系。

在 CSV 文件中使用操作更新带标识符属性的关系
:ACTION,:START_ID,:TYPE,:END_ID,p1{identifier:true},name,p4
U,person1,KNOWS,person2,abc,"Keanu Reeves","Hello Morpheus"
U,person2,KNOWS,person1,def,"Laurence Fishburne","Hello Neo"

如果存在多个 1,KNOWS,2，这些关系中 p1 列的数据有助于“更唯一地”选择关系。标题中还可以定义多个标识符属性。标识符属性匹配选定的关系，并且不会在已经拥有这些属性的关系上设置。

更新现有标签

您可以通过在标题中的 LABEL 子句前加上 +（默认）或 - 来添加或删除现有节点的一个或多个标签。

  • :+LABEL - 为现有节点添加一个或多个标签。

  • :-LABEL - 从现有节点中删除一个或多个标签（如果存在）。

例如，文件可以具有以下格式

uid:ID(label:Person),:+LABEL,:-LABEL,name,age
person1,Actor,Producer,"Keanu Reeves",55
person2,Actor;Director,,"Laurence Fishburne",60

在这种情况下，第二列中的所有标签都会被添加，而第三列中的所有标签都会被删除（如果存在）。

移除现有属性

您可以通过标题中的 :-PROPERTY 列从现有节点或关系中移除属性。在该字段的内容中，您可以添加零个或多个属性名称以从实体中移除。例如

移除节点的属性
:ACTION,uid:ID(label:Person),:-PROPERTY
U,person1,age;hometown

属性 age 和 hometown 将从 uid:ID 为 person1 的节点中移除。

移除关系的属性
:ACTION,:START_ID,:END_ID,:TYPE,:-PROPERTY
U,person1,movie1,ACTED_IN,role;description

属性 role 和 description 将从 :START_ID 为 person1、:END_ID 为 movie1、:TYPE 为 ACTED_IN 的关系中移除。

在 CSV 文件中使用操作更新标签和属性
:ACTION,uid:ID(label:Person),:LABEL,:-LABEL,:-PROPERTY,name,height:int
U,person1,Actor,Producer,age;hometown,Henry",185

一个 CSV 条目可以同时指定对一个实体的所有类型的更新。在此示例中，节点 person1 将更新为

  • 添加了 Actor 标签

  • 移除了 Producer 标签

  • 移除了 age 和 hometown 属性

  • 设置了 name="Henry" 属性

  • 设置了 height=185 属性

导入跨多行的数据

--multiline-fields 选项允许输入源中的字段跨越多行，即包含换行符。例如

bin/neo4j-admin database import full --nodes import/node_header.csv,import/node_data.csv --multiline-fields=true databasename

其中 import/node_data.csv 包含多行字段，例如

id,name,birthDate,birthYear,birthLocation,description
1,John,October 1st,2000,New York,This is a multiline
description

将 --multiline-fields=true 设置为 true 会严重降低导入器的性能。因此，请谨慎使用，尤其是对于大型导入。

您可以选择通过设置 --multiline-fields-format 选项来指定 --multiline-fields 的格式，以控制输入源的解析。可能的值为

  • v1 - 默认格式，使用当前处理多行字段的方法。

  • v2 - 一种更高效的处理方法，要求文本字段带引号。对于 v2，--multiline-fields 选项必须设置为包含多行字段的文件列表（允许使用正则表达式）。

两种格式都有一个限制，即每一行的全部内容都必须能够容纳到缓冲区中（默认为 4m）。--multiline-fields-format 选项在 full 和 incremental 导入模式下可用。

例如

bin/neo4j-admin database import full --nodes import/node_header.csv,import/node_data.csv --multiline-fields=true --multiline-fields-format=v1 databasename

其中 import/node_data.csv 包含多行字段，例如

id,name,birthDate,birthYear,birthLocation,description
1,John,October 1st,2000,New York,This is a multiline
description
bin/neo4j-admin database import full --nodes import/node_header.csv,import/node_data.csv --multiline-fields=import/node_data.csv --multiline-fields-format=v2 databasename

其中 import/node_data.csv 包含多行字段，例如

id,name,birthDate,birthYear,birthLocation,description
1,"John","October 1st",2000,"New York","This is a multiline
description"

跳过列

IGNORE

如果数据中有您希望完全忽略的字段，可以使用标题文件中的 IGNORE 关键字来完成。IGNORE 必须以 : 开头。

示例 10. 跳过一列

在此示例中，您对节点文件第三列中的数据不感兴趣，并希望跳过它。请注意，IGNORE 关键字前有一个 :。

personId:ID,name,:IGNORE,:LABEL
keanu,"Keanu Reeves","male",Actor
laurence,"Laurence Fishburne","male",Actor
carrieanne,"Carrie-Anne Moss","female",Actor

如果您所有多余的数据都放在您希望导入的所有列的右侧，您可以改用命令行选项 --ignore-extra-columns。

导入压缩文件

导入工具可以处理用 zip 或 gzip 压缩的文件。每个压缩文件必须只包含一个文件。

示例 11. 使用压缩文件执行导入
neo4j_home$ ls import
actors-header.csv  actors.csv.zip  movies-header.csv  movies.csv.gz  roles-header.csv  roles.csv.gz
bin/neo4j-admin database import --nodes import/movies-header.csv,import/movies.csv.gz --nodes import/actors-header.csv,import/actors.csv.zip --relationships import/roles-header.csv,import/roles.csv.gz

在导入期间提供索引和约束

您可以使用 --schema 选项在导入过程中创建和填充索引/约束。它适用于块格式以及完整和增量导入。对于增量导入，此功能从 2025.02 版本开始可用。

您应该有一个仅包含 CREATE INDEX|CONSTRAINT 命令的 Cypher 脚本，以便进行解析和执行。此文件使用 ';' 作为分隔符。

例如

CREATE INDEX PersonNameIndex FOR (i:Person) ON (i.name);
CREATE CONSTRAINT PersonAgeConstraint FOR (c:Person) REQUIRE c.age IS :: INTEGER

导入工具可以创建的支持索引和约束列表

  • 范围（RANGE）

  • 查找（LOOKUP）

  • 点（POINT）

  • 文本（TEXT）

  • 全文（FULL-TEXT）

  • 向量（VECTOR）

例如

在完整导入期间创建索引和约束
bin/neo4j-admin database import full neo4j --nodes=import/movies.csv --nodes=import/actors.csv --relationships=import/roles.csv --schema=import/schema.cypher
在增量导入期间创建索引和约束
bin/neo4j-admin database import incremental --stage=all --nodes=import/movies.csv --nodes=import/actors.csv --relationships=import/roles.csv --schema=import/schema.cypher

如果您想在一个命令中执行增量导入，必须停止您的数据库。如果您无法承受数据库的完全停机，请将操作分成几个阶段。有关详细信息，请参阅分阶段增量导入。

恢复已停止或取消的导入

已停止或在完成前失败的导入可以从更接近其停止点的某个点恢复。导入可以从以下点恢复

  • 关系链接

  • 后处理

© . All rights reserved.