导入

neo4j-admin database import 以最快速度将 CSV 数据写入 Neo4j 的原生文件格式。
它还提供对 Parquet 文件格式的支持。

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

  • 由于拥有大量数据（数百万/数十亿个实体），导入性能至关重要。

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

  • 数据库不存在或为空，并且您需要执行初始数据加载。

  • 您需要使用大量数据更新图数据库。在这种情况下，增量导入数据可能比事务性插入更具性能优势。

    增量导入可以在单个命令中完成，也可以分阶段完成。有关详细信息，请参阅 单个命令增量导入 和 分阶段增量导入。

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

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

变更数据捕获（Change Data Capture）不会捕获任何因使用 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 选项。

从 2026.03 版本开始，您可以查看 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]]
                                 [--dry-run[=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]] [--profile[=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>] [--path-pattern-style=regex|glob|none]
                                 [--profile-results-path=<path>] [--property-shard-count=<propertyShardCount>]
                                 [--quote=<char>] [--read-buffer-size=<size>] [--report-file=<path>] [--schema=<path>]
                                 [--target-format=<format>] [--target-location=<path>] [--temp-path=<path>]
                                 [--threads=<num>] [--vector-delimiter=<char>] [--nodes=[<label>[:<label>]...=]
                                 <files>...]... [--relationships=[<type>=]<files>...]...
                                 [--multiline-fields=true|false|<path>[,<path>] [--multiline-fields-format=v1|v2]]
                                 <database>

描述

将无故障的 CSV 数据高速初始导入到不存在或为空的数据库中。

参数

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

<database>

要导入的数据库名称。如果导入的目标数据库在导入前不存在，您随后必须使用 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=<file>[1]

包含额外配置的配置文件。

--array-delimiter=<char>

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

  • 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=<num>

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

-1 2025.12 中变更

--delimiter=<char>

CSV 数据中值之间的分隔符。也接受 TAB 和使用 Unicode 指定的字符（例如 U+002A）。请注意，分隔符必须是 UTF-8 中的单字节字符。

  • 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。

,

--dry-run[=true|false][2]

2026.02 中引入该标志用于指示应执行干运行（dry run），即不会实际导入任何数据，仅执行参数验证和导入大小估算，并报告结果。

false

--expand-commands

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

--format=<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=<character-set>

输入数据的字符编码集。

UTF-8

--input-type=csv|parquet

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

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

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

false

--max-off-heap-memory=<size>

命令可用于页缓存和各种缓存数据结构以提高性能的最大内存。值可以是普通数字（如 10000000），也可以是大小单位（如 20G），或百分比（如 70%，表示机器当前可用内存的 70%）。

90%

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

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

null

--multiline-fields-format=v1|v2

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

null

--nodes=[<label>[:<label>]…​=]<files>…​

节点 CSV 标题和数据。

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

  • 第一行必须包含标题。

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

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

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

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

--normalize-types[=true|false]

当为 true 时，非数组属性值将转换为对应的 Cypher 类型。例如，所有整数值将转换为 64 位长整数。

true

--overwrite-destination[=true|false]

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

false

--path-pattern-style=regex|glob|none[3]

2026.01 中引入用于匹配 --nodes 和 --relationships 文件的模式样式。

可能的值为：

  • glob — 允许编写如 /some/**/deep/**/nested/structure.* 的模式。

  • regex — 允许编写正则表达式，即 /some/nested/structure.*。

  • none — 必须精确列出所有文件路径，即 /some/content/structure1.csv,/some/content/structure2.csv。

regex

--profile[=true|false]

2026.02 中引入捕获整个导入过程的 Java Flight Recording。

false

--profile-results-path=<path>

2026.02 中引入提供存储使用 --profile 选项捕获的 Java Flight Recording 的路径。需要设置 --profile 或 --profile=true 才能生效。

--property-shard-count=<propertyShardCount>[4]

2025.12 中引入企业版 将要创建的属性数据分片数量，每个分片将是一个独立的数据库。当此值为 0 时，等同于仅运行 FULL 导入。

0

--quote=<char> [5]

用于 CSV 数据中值的引用字符。

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

不能使用 \ 进行转义。

"

--read-buffer-size=<size>

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

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

4194304

--relationships=[<type>=]<files>…​

关系 CSV 标题和数据。

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

  • 第一行必须包含标题。

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

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

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

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

--report-file=<path>

存储 csv-import 报告的文件。

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

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

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

import.report

--schema=<path>

企业版 包含用于在数据导入过程中创建索引和约束的 Cypher 命令的文件路径。可以使用适当的 URI 作为路径，从 AWS S3 存储桶、Google Cloud 存储桶和 Azure 存储桶加载命令。

--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

--target-format=<format>[4]

2025.12 中引入企业版 目标格式可以是纯数据库目录/文件结构 (database) 或备份制品 (backup)。使用 --temp-path 位置保存任何中间状态。

database

--target-location=<path>[4]

2025.12 中引入企业版 目标备份制品数据的位置。与 --target-format=backup 一起使用。

--temp-path=<path>

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

--threads=<num>

(高级) 导入器使用的最大工作线程数。默认为 JVM 报告的可用处理器数。出于某种原因需要最少数量的线程，因此该值没有下限。为获得最佳性能，此值不应大于可用处理器的数量。

--trim-strings[=true|false]

字符串是否应修剪空格。

false

--vector-delimiter=<char>

2025.10 中引入 CSV 数据中值内向量坐标之间的分隔符。也接受 TAB 以及使用 Unicode 指定的字符（例如 U+20AC）。

;

--verbose

启用详细输出。

1. 详细信息请参阅 Neo4j Admin 和 Neo4j CLI → 配置。
2. 详细信息请参阅 在导入数据前执行干运行。
3. 详细信息请参阅 使用模式样式匹配 --nodes 和 --relationships 文件。
4. 详细信息请参阅 属性分片 → 数据摄取。
5. 要转义 CSV 数据中的引号，应双写配置的字符。
导入的堆大小

您需要将最大堆大小设置为适合导入的值。这是通过在启动导入之前定义 HEAP_SIZE 环境变量来完成的。例如，2G 是小型导入的适当值。

如果导入规模在 1000 亿个实体左右，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 → 变量参数选项和位置参数 官方文档。

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

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

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

从云存储导入

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

示例

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

假设您按照 CSV 标题格式 格式化了数据，并将其存放在六个不同的文件中：

  1. movies_header.csv

  2. movies.csv

  3. actors_header.csv

  4. actors.csv

  5. roles_header.csv

  6. roles.csv

在导入数据前执行干运行
2026.02 中引入

在进行实际导入之前，您可以运行干运行以验证输入文件并估算导入规模。该命令不会向数据库写入任何数据。

bin/neo4j-admin database import full --dry-run=true --nodes import/movies_header.csv,import/movies.csv \
--nodes import/actors_header.csv,import/actors.csv \
--relationships import/roles_header.csv,import/roles.csv
输出示例
Neo4j version: 2026.03.1
Checking the contents of the following files:
Nodes:
  /path/to/neo4j-enterprise-2026.03.1/import/movies_header.csv
  /path/to/neo4j-enterprise-2026.03.1/import/movies.csv
  /path/to/neo4j-enterprise-2026.03.1/import/actors_header.csv
  /path/to/neo4j-enterprise-2026.03.1/import/actors.csv

Relationships:
  null:
  /path/to/neo4j-enterprise-2026.03.1/import/roles_header.csv
  /path/to/neo4j-enterprise-2026.03.1/import/roles.csv


Available resources:
  Total machine memory: 32.00GiB
  Free machine memory: 81.34MiB
  Max heap memory : 7.111GiB
  Max worker threads: 10
  Configured max memory: 88.11MiB
  High parallel IO: true

Cypher type normalization is enabled (disable with --normalize-types=false):
  Property type of 'year' normalized from 'int' --> 'long' in /path/to/neo4j-enterprise-2026.03.1/import/movies_header.csv
Estimated entity counts / sizes:
  Nodes: 6
    Labels: 8
    Total property count: 15
    Total properties size: 237B
  Relationships: 9
    Total property count: 9
    Total properties size: 108B

从多个 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.endpointUrls3、aws.endpointUrlS3 或 aws.endpointUrl，或环境变量 AWS_ENDPOINT_URL_S3 或 AWS_ENDPOINT_URL 来覆盖端点，以便 AWS SDK 可以与 Ceph、Minio 或 LocalStack 等替代存储系统通信。

  1. 按照 AWS 官方文档中的说明安装 AWS CLI — 安装 AWS CLI 版本 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 官方文档 — 使用 AWS CLI 使用 Amazon S3 和 使用 AWS CLI 的高级 (s3) 命令。

  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 命令设置您的 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]] [--dry-run
                                        [=true|false]] [--ignore-empty-strings[=true|false]] [--ignore-extra-columns
                                        [=true|false]] [--legacy-style-quoting[=true|false]] [--normalize-types
                                        [=true|false]] [--profile[=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>]
                                        [--path-pattern-style=regex|glob|none] [--profile-results-path=<path>]
                                        [--property-shard-count=<propertyShardCount>] [--quote=<char>]
                                        [--read-buffer-size=<size>] [--report-file=<path>] [--schema=<path>]
                                        [--stage=all|prepare|build|merge] [--target-format=<format>]
                                        [--target-location=<path>] [--temp-path=<path>] [--threads=<num>]
                                        [--vector-delimiter=<char>] [--nodes=[<label>[:<label>]...=]<files>...]...
                                        [--relationships=[<type>=]<files>...]... [--multiline-fields=true|false|<path>[,
                                        <path>] [--multiline-fields-format=v1|v2]] <database>

描述

对现有数据库进行增量导入。

用法和限制

导入器在独立服务器上工作良好。

要在集群环境中安全地执行增量导入，请遵循以下步骤：

  1. 在集群中的单台服务器上运行增量导入命令。此服务器随后可用作 指定种子节点，其他集群成员可以从中复制数据库。

  2. 通过运行 dbms.recreateDatabase() 过程，将数据库拓扑重新配置为单个主节点。

  3. 然后使用 STOP DATABASE 停止数据库。

  4. 在托管数据库的服务器上执行增量导入。

  5. 然后使用 START DATABASE 启动数据库。

  6. 最后，使用 ALTER DATABASE 恢复所需的数据库拓扑。

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

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

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

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

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

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

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

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

  • 删除现有节点和关系。

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

参数

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

<database>

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

neo4j

选项

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

--additional-config=<file>[6]

包含额外配置的配置文件。

--array-delimiter=<char>

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

  • 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=<num>

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

-1 2025.12 中变更

--delimiter=<char>

CSV 数据中值之间的分隔符。也接受 TAB 和使用 Unicode 指定的字符（例如 U+002A）。请注意，分隔符必须是 UTF-8 中的单字节字符。

  • 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。

,

--dry-run[=true|false][7]

2026.02 中引入该标志用于指示应执行干运行（dry run），即不会实际导入任何数据，仅执行参数验证和导入大小估算，并报告结果。

false

--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=<character-set>

输入数据的字符编码集。

UTF-8

--input-type=csv|parquet

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

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

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

false

--max-off-heap-memory=<size>

命令可用于页缓存和各种缓存数据结构以提高性能的最大内存。值可以是普通数字（如 10000000），也可以是大小单位（如 20G），或百分比（如 70%，表示机器当前可用内存的 70%）。

90%

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

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

null

--multiline-fields-format=v1|v2

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

null

--nodes=[<label>[:<label>]…​=]<files>…​

节点 CSV 标题和数据。

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

  • 第一行必须包含标题。

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

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

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

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

--normalize-types[=true|false]

当为 true 时，非数组属性值将转换为对应的 Cypher 类型。例如，所有整数值将转换为 64 位长整数。

true

--path-pattern-style=regex|glob|none[8]

2026.01 中引入用于匹配 --nodes 和 --relationships 文件的模式样式。

可能的值为：

  • glob — 允许编写如 /some/**/deep/**/nested/structure.* 的模式。

  • regex — 允许编写正则表达式，即 /some/nested/structure.*。

  • none — 必须精确列出所有文件路径，即 /some/content/structure1.csv,/some/content/structure2.csv。

regex

--profile[=true|false]

2026.02 中引入捕获整个导入过程的 Java Flight Recording。

false

--profile-results-path=<path>

2026.02 中引入提供存储使用 --profile 选项捕获的 Java Flight Recording 的路径。需要设置 --profile 或 --profile=true 才能生效。

--property-shard-count=<propertyShardCount>[9]

2025.12 中引入 企业版 (高级) 将要创建的属性数据分片数量，每个分片将是一个独立的数据库。通常无需设置此选项，因为分片数量已在初始导入时确定。

0

--quote=<char> [10]

用于 CSV 数据中值的引用字符。

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

不能使用 \ 进行转义。

"

--read-buffer-size=<size>

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

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

4194304

--relationships=[<type>=]<files>…​

关系 CSV 标题和数据。

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

  • 第一行必须包含标题。

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

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

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

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

--report-file=<path>

存储 csv-import 报告的文件。

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

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

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

import.report

--schema=<path>

2025.02 起可用 包含用于在数据导入过程中创建索引和约束的 Cypher 命令的文件路径。可以使用适当的 URI 作为路径，从 AWS S3 存储桶、Google Cloud 存储桶和 Azure 存储桶加载命令。

--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

--target-format=<format>[9]

2025.12 中引入企业版 目标格式可以是纯数据库目录/文件结构 (database) 或备份制品 (backup)。使用 --temp-path 位置保存任何中间状态。

database

--target-location=<path>[9]

2025.12 中引入企业版 目标备份制品数据的位置。与 --target-format=backup 一起使用。

--temp-path=<path>

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

--threads=<num>

(高级) 导入器使用的最大工作线程数。默认为 JVM 报告的可用处理器数。出于某种原因需要最少数量的线程，因此该值没有下限。为获得最佳性能，此值不应大于可用处理器的数量。

--trim-strings[=true|false]

字符串是否应修剪空格。

false

--vector-delimiter=<char>

2025.10 中引入 CSV 数据中值内向量坐标之间的分隔符。也接受 TAB 以及使用 Unicode 指定的字符（例如 U+20AC）。

;

--update-all-matching-relationships

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

false

--verbose

启用详细输出。

6. 详细信息请参阅 Neo4j Admin 和 Neo4j CLI → 配置。
7. 详细信息请参阅 在导入数据前执行干运行。
8. 详细信息请参阅 使用模式样式匹配 --nodes 和 --relationships 文件。
9. 详细信息请参阅 属性分片 → 数据摄取。
10. 要转义 CSV 数据中的引号，应双写配置的字符。
同时使用多值选项和位置参数

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

这是底层库 Picocli 的限制，并非 Neo4j Admin 特有。有关更多信息，请参阅 Picocli → 变量参数选项和位置参数 官方文档。

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

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

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

示例

在导入数据前执行干运行
2026.02 中引入

在进行实际导入之前，您可以运行干运行以验证输入文件并估算导入规模。该命令不会向数据库写入任何数据。

neo4j@system> STOP DATABASE neo4j WAIT;
...
bin/neo4j-admin database import incremental --dry-run=true --nodes=N1=../../raw-data/incremental-import/nodes.csv --relationships=R1=../../raw-data/incremental-import/relationships.csv neo4j
输出示例
Neo4j version: 2026.03.1
Checking the contents of the following files:
Nodes:
  /path/to/neo4j-enterprise-2026.03.1/raw-data/incremental-import/nodes.csv
Relationships:
  /path/to/neo4j-enterprise-2026.03.1/raw-data/incremental-import/relationships.csv

Available resources:
  Total machine memory: 64.00GiB
  Free machine memory: 9.997GiB
  Max heap memory : 14.22GiB
  Max worker threads: 10
  Configured max memory: 40.00GiB
  High parallel IO: true

Schema commands:
  Indexes to be created: 3
  Indexes to be dropped: 1
  Constraints to be created: 2
  Constraints to be dropped: 3

Estimated entity counts / sizes:
  Nodes: 2702496410
    Includes updates: true
    Labels: 2702496410
    Property count: 16348903762
    Property size: 253.6GiB
  Relationships: 18094004256
    Includes updates: false
    Property count: 6076138797
    Property size: 96.14GiB

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

单个命令增量导入

如果不需要担心停机时间，可以运行带有 --stage=all 选项的单个命令。此选项要求数据库处于停止状态。 

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

分阶段增量导入

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

  1. prepare（准备）阶段

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

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

      STOP DATABASE neo4j WAIT

    2. 运行带有 --stage=prepare 选项的增量导入命令。

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

  2. build（构建）阶段

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

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

      ALTER DATABASE neo4j SET ACCESS READ ONLY

    2. 运行带有 --stage=build 选项的增量导入命令。

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

  3. merge（合并）阶段

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

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

      STOP DATABASE neo4j WAIT

    2. 运行带有 --stage=merge 选项的增量导入命令。

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

CSV 标题格式

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

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

增量导入

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

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

Parquet 的扩展标题支持
2025.04 中引入

除了 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 保存在一个属性中，该属性的名称由字段定义 <name>:ID 的 <name> 部分定义。如果未定义此类属性 name，则唯一 ID 将用于导入，但以后不可用于引用。如果未指定 ID，节点仍会被导入，但在导入期间不会连接到其他节点。当提供属性 name 时，该属性类型可以通过 --id-type 选项进行全局配置（类似于 属性数据类型）。您可以使用标题中的 id-type 选项为节点组中的节点属性指定要存储的不同值 ID 类型，例如：id:ID(MyGroup){label:MyLabel, id-type: int}。标题中的此 ID 类型覆盖全局 --id-type 选项。例如，全局 id-type 可以是字符串，但节点会将 ID 存储为 int 类型。有关更多信息，请参阅 在组中为 ID 存储不同的值类型。节点标题还可以包含多个 ID 列，其中关系数据引用所有这些列的复合值。这也暗示使用 string 作为 id-type。对于每个 ID 列，您可以指定将其值存储为不同的节点属性。但是，复合值不能存储为节点属性。有关更多信息，请参阅 使用多个节点 ID。

LABEL

从此字段读取一个或多个标签。与数组值一样，多个标签由 ; 或由 --array-delimiter 指定的字符分隔。块格式的标签名称最大长度为 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

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

START_ID

此关系的起始节点的 ID。

END_ID

此关系的结束节点的 ID。

START_ID 和 END_ID 引用在其中一个节点数据源中定义的唯一节点 ID，如前一节所述。这些都不采用名称，例如如果定义了 <name>:START_ID 或 <name>:END_ID，则 <name> 部分将被忽略。它们也不采用 <field_type>，例如如果定义了 :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

属性数据类型

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

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

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

要定义数组类型，请在类型后附加 []。默认情况下，数组值由 ; 分隔。可以使用 --array-delimiter 指定不同的分隔符。数组不受 --normalize-types 标志的影响。例如，如果您希望将字节数组存储为 Cypher 长整数数组，则必须将该属性显式声明为 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{crs: 'WGS-84'}。以这种方式指定标题允许您在数据文件中的值位置具有不完整的映射。或者，数据文件中的值可以覆盖标题中的默认值。

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

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

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

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

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

  • 第一个城市的位置使用 latitude 和 longitude 定义，正如使用标题中定义的坐标系时预期的那样。

  • 第二个城市使用 x 和 y。这通常会产生一个使用 cartesian 坐标系的点。由于标题定义了 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]

2025.10 引入的向量数据类型的特殊注意事项

向量使用 Cypher 映射语法指定。映射必须指定向量的 coordinateType 和 dimensions。coordinateType 可以是 byte, short, int, long, float 或 double 之一。dimensions 必须在 1 到 4096 之间（包含）。

默认情况下，向量值由 ; 分隔。可以使用 --vector-delimiter 指定不同的分隔符。

数据中每个向量的维度必须与标题中指定的内容匹配。

标题中的向量例如可以看起来像这样： 

:ID,"vector1:vector{coordinateType:byte,dimensions:4096}"

请注意，引号是必需的，否则映射中的 , 将被解释为列分隔符。

使用 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 列。

从 2025.07 开始，关系数据必须使用匹配数量的 START_ID / END_ID 列作为对这些 ID 列复合值的引用。这暗示使用 string 作为 id-type。

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

增量导入不支持使用多个节点标识符。此功能仅在全量导入时可用。

定义多个 ID 作为节点属性

  1. 在节点标题中定义多个 ID 列。

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

  2. 定义两个已建立节点之间的关系。

    从 2025.07 开始，您可以在定义关系时使用匹配数量的 START_ID 和 END_ID 列。但是，不要混用引用复合 ID 的方式。要么所有引用都必须使用单个 START_ID 和 END_ID 列，要么所有引用都必须使用匹配数量的列。

    relationships_header.csv
    :START_ID,:START_ID,:TYPE,:END_ID,:END_ID
    relationships.csv
    aa,11,WORKS_WITH,bb,22

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

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

定义存储在 ID 空间中的多个 ID

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

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

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

    从 2025.07 开始，您必须在定义关系时使用匹配数量的 START_ID 和 END_ID 列：

    relationships_header.csv
    :START_ID(MyGroup),:START_ID(MyGroup),:TYPE,:END_ID(MyGroup),:END_ID(MyGroup)
    relationships.csv
    aa,11,WORKS_WITH,bb,22
    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 存储为 ID 属性中的 long 类型。

示例 7. 导入具有不同 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 是字符串。

使用模式样式匹配 --nodes 和 --relationships 文件
2026.01 中引入

导入工具支持三种不同的模式样式，用于通过导入命令的 --path-pattern-style 参数匹配 --nodes 和 --relationships 文件。模式样式为 glob, regex 和 none。默认模式样式为 regex。

glob

当您有大量数据组织成更嵌套的文件夹结构时，使用 glob 样式模式匹配，例如按年份分组的数据： 

/data/invoices/2024/invoices_jan.csv
...
/data/invoices/2024/invoices_dec.csv
/data/invoices/2025/invoices_jan.csv
...
/data/invoices/2025/invoices_dec.csv
/data/invoices/2026/invoices_jan.csv

它允许您通过类似 /data/invoices/**/invoices_{jan,feb,mar,apr,may,jun,jul,aug,sep,oct,nov,dec}.csv 的方式导入所有文件。

regex

当您有大量数据组织在一个文件夹内时，使用 regex 样式模式匹配。例如： 

/data/invoices/invoices_2024_1.csv
/data/invoices/invoices_2024_2.csv
...
/data/invoices/invoices_2026_1.csv

它允许您通过类似 /data/invoices/invoices_\d+_\d.csv 的方式导入所有文件。

none

当您了解文件并希望避免模式匹配时使用 none。例如，这在您的文件位于云中时特别有用，使用其他两个选项可能会产生不必要的性能和财务成本。

通过 CSV 文件应用数据更改
2025.01.0 中引入

您可以使用 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"

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

更新现有标签

您可以通过在标题中 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 可能会严重降低导入器的性能。因此，请谨慎使用，特别是在大数据量导入时。

或者，您可以通过设置 --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 前面必须加上 :。

示例 8. 跳过一列

在此示例中，您对节点文件第三列中的数据不感兴趣，希望跳过它。请注意，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 压缩的文件。每个压缩文件必须包含单个文件。

示例 9. 使用压缩文件执行导入
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 选项在全量和增量导入期间创建并填充索引/约束，方法是提供包含 CREATE INDEX|CONSTRAINT 命令的 Cypher 脚本。在增量导入期间，如果 Cypher 脚本包含 DROP INDEX|CONSTRAINT 命令，您也可以使用相同的选项来删除索引/约束。

--schema 选项仅适用于 block 存储格式。对于增量导入，创建和删除索引和约束从 2025.02 开始提供。

导入工具支持以下索引和约束：

  • RANGE

  • LOOKUP

  • POINT

  • TEXT

  • FULL-TEXT

  • VECTOR

在全量导入期间创建索引和约束

您可以使用 --schema 选项在全量导入期间创建并填充索引/约束，方法是提供包含 CREATE INDEX|CONSTRAINT 命令的 Cypher 脚本以进行解析和执行。

全量导入不支持删除索引和约束。

例如：

schema.cypher 脚本
CREATE INDEX PersonNameIndex IF NOT EXISTS FOR (p:Person) ON (p.name);
CREATE CONSTRAINT PersonAgeConstraint IF NOT EXISTS FOR (c:Person) REQUIRE c.age IS :: INTEGER;

此文件使用 ';' 作为分隔符。

然后使用以下示例命令运行导入： 

bin/neo4j-admin database import full neo4j --nodes=import/movies.csv --nodes=import/actors.csv --relationships=import/roles.csv --schema=import/schema.cypher

在增量导入期间创建和删除索引和约束
2025.02 中引入

您可以使用 --schema 选项在增量导入期间创建并填充、以及删除索引/约束，方法是提供包含 CREATE INDEX|CONSTRAINT 和 DROP INDEX|CONSTRAINT 命令的 Cypher 脚本以进行解析和执行。请注意，您不能删除作为约束后盾的索引。您必须删除约束本身，这也会删除底层的索引。

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

例如：

schema.cypher 脚本
DROP INDEX PersonNameIndex IF EXISTS;
CREATE CONSTRAINT person_name IF NOT EXISTS FOR (p:Person) REQUIRE p.name IS UNIQUE;
DROP CONSTRAINT PersonAgeConstraint IF EXISTS;
CREATE CONSTRAINT movie_title IF NOT EXISTS FOR (m:Movie) REQUIRE m.title IS UNIQUE;

此文件使用 ';' 作为分隔符。

然后使用以下示例命令运行导入： 

bin/neo4j-admin database import incremental --stage=all --nodes=import/movies.csv --nodes=import/actors.csv --relationships=import/roles.csv --schema=import/schema.cypher

恢复已停止或取消的导入
企业版

已停止或在完成前失败的导入可以从停止点附近恢复。导入可以从以下几点恢复：

  • 关系的链接

  • 后处理

使用 Java Flight Recorder (JFR) 诊断性能问题
2026.02 中引入

--profile 选项在整个导入期间运行 JFR 记录，并捕获 JVM 性能数据以供分析。此选项对于长时间运行和资源密集型导入特别有用。

要使用此选项，请将 --profile 或 --profile=true 添加到您的导入命令中。例如：

运行带有 JFR 记录的全量导入 
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 \
--profile=true

或者，您可以使用 --profile-results-path 选项指定存储生成的 Java Flight Recording 的路径。如果未指定，记录将存储在 logs 文件夹中。

导入进度报告
在 2026.03 中引入

从 2026.03 开始，neo4j-admin database import 命令具有一个上下文目录，用于捕获有关导入过程的信息。

启动导入时，将创建一个格式为 server/data/imports/dbname-yyyy-MM-dd.HH.mm.ss 的新目录。

它包含详细日志记录、详细进度、错误收集器信息（请参阅 --bad-tolerance 选项）以及性能分析（如果已启用 Java Flight Recording）。如果提供了 --profile-results-path 选项，则该路径将改为用于 Java Flight 记录。

目录在导入作业结束时被删除，除非出现以下情况：

  • 启用了性能分析或详细模式。

  • 导入失败并出现错误。

  • 违规由错误收集器报告，即导入成功但检测到数据问题。

详细报告进度位于 progress.json.log 中，每个快照每行是一个 JSON 对象条目。

违规报告为 JSON 对象条目，每行一个，位于 report.json.log 中。

导入 CLI 支持 --report-file 选项来覆盖默认输出路径。提供后，违规将以相同的 JSON 格式写入指定位置。

每个 JSON 条目都包含一个等同于 2026.03 之前格式的 message 字段，以及提供更详细信息的其他字段。