文件变量

文件变量用于定义基于文件的数据源和数据目的地。它们主要用于数据的导入或导出操作，可处理多种文件格式，包括 CSV、Parquet 和 ORC。每个文件变量可以对应一个或多个文件。

语法

语法图源码

file_variable_definition

column_definitions

file_options

file_path

file_variable_definition ::=
    'FILE' file_variable '{' (column_definitions) ( ',' (column_definitions))* '}' '=' 'DATAFILE' '{' file_options '}'

column_definitions ::=
    column_name value_type

file_options ::=
    ('PATH' ':' file_path) ',' ('FORMAT' ':' ('"' 'CSV' '"'|'"' 'PARQUET' '"'|'"' 'ORC' '"')(',' additional_options)* )

file_path ::=
      '"' 'file://' path '"'
    | '"' 'hdfs://' hostname ':' port '/' path '"' 
    | '"' 's3://' (access_key ':' secret_key '@')? bucket '/' path ( '?' ( parameter_name '=' parameter_value) ('&' ( parameter_name '=' parameter_value))* )? '"'
    | '"' 'gs://' ((access_key ':' secret_key) | 'anonymous') '@' bucket '/' path ( '?' ( parameter_name '=' parameter_value) ('&' ( parameter_name '=' parameter_value))* )? '"'            

参数

file_variable

要定义的文件变量的名称。file_variable可以是常规标识符或使用反引号(`)包围的分隔标识符。有关标识符的更多信息，请参见标识符命名规则。

column_definitions

文件中列和数据类型的结构定义。每个定义由column_name和value_type组成，多个定义之间用逗号分隔。例如：{id INT, name STRING}。

column_name

文件中列的名称。column_name必须是一个标识符。更多信息，请参见标识符命名规则。

value_type

列所存储值的数据类型。支持的数据类型包括：

• 数值，如INT、UINT、FLOAT、DOUBLE和DECIMAL。
• 字符串
• 布尔
• 日期和时间，如DATE、LOCAL TIME、ZONED TIME、LOCAL DATETIME和ZONED DATETIME。
• 向量
• 列表
• 集合
• 映射
• 地理空间

更多信息，请参见数据类型。

file_options

文件配置项，包括PATH、FORMAT以及特定格式的配置项。PATH和FORMAT必填；其他所有配置项都是可选的。配置项可以以任意顺序出现。

支持的文件格式包括：CSV、PARQUET和ORC。

有关可选配置项，请参见下方的参数additional_options。

additional_options

用于配置文件读取、解析、转换和写入的额外配置项。这些配置项根据文件格式的不同而有所差异。支持的配置项包括：

文件类型	类别	配置项名称	数据类型	默认值	说明
CSV	读取	SKIP_ROWS	Int32	0	读取列前跳过的表头行数。
	读取	SKIP_ROWS_AFTER_NAMES	Int32	0	读取列后跳过的行数。
	读取	COLUMN_NAMES	Vector	[]	表的显式列。默认，系统自动从文件的第一行读取列名。
	读取	AUTOGENERATE_COLUMN_NAMES	Bool	false	当未提供列名时，是否自动生成列名（例如f0、f1）。
	解析	DELIMITER	Char	','	列的分隔符字符。
	解析	QUOTING	Bool	true	是否启用引号。
	解析	QUOTE_CHAR	Char	'"'	值的引用字符。
	解析	DOUBLE_QUOTE	Bool	true	值内部的引号是否由双引号表示。
	解析	ESCAPING	Bool	false	是否启用转义。
	解析	ESCAPE_CHAR	Char	'\'	特殊字符的转义字符。
	解析	NEWLINES_IN_VALUES	Bool	false	值中是否可能包含换行符。
	解析	IGNORE_EMPTY_LINES	Bool	true	是否忽略空行。
	转换	CHECK_UTF8	Bool	true	是否验证字符串列的 UTF-8 编码。
	转换	NULL_VALUES	Vector	"", "#N/A", "#N/A N/A", "#NA", "-1.#IND", "-1.#QNAN", "-NaN", "-nan", "1.#IND", "1.#QNAN", "N/A", "NA", "NULL", "NaN", "n/a", "nan", "null"	被解释为 Null 值的字符串。
	转换	TRUE_VALUES	Vector	{"1", "True", "TRUE", "true"}	被解释为布尔值true的字符串。
	转换	FALSE_VALUES	Vector	{"0", "False", "FALSE", "false"}	被解释为布尔值false的字符串。
	转换	STRINGS_CAN_BE_NULL	Bool	true	字符串/二进制列是否可能包含 Null 值。
	转换	QUOTED_STRINGS_CAN_BE_NULL	Bool	false	引用的字符串值是否可被视为 Null。
	转换	INCLUDE_COLUMNS	Vector	[]	输出中包含的列；未列出的列将被忽略。默认包含所有列。
	转换	INCLUDE_MISSING_COLUMNS	Bool	false	是否为INCLUDE_COLUMNS中列出但缺失的列创建 Null 值。
	写入	INCLUDE_HEADER	Bool	true	是否写入包含列的表头行。
	写入	BATCH_SIZE	Int32	1024	每次写入批次处理的最大行数。
	写入	DELIMITER	Char	','	输出中的列的分隔符字符。
	写入	NULL_STRING	String	""	Null 值的字符串表示形式。默认，Null 值被替换为空字符串。
	写入	EOL	String	"\n"	行结束字符序列。
	写入	MAX_ROWS_PER_FILE	Int64	100000000	每个输出文件的最大行数。
Parquet	读取	BATCH_SIZE	Int64	1024	读取时每个记录批次的最大行数。
	写入	MAX_ROWS_PER_FILE	Int64	100000000	每个输出文件的最大行数。
	写入	WRITE_BATCH_SIZE	Int64	1024	将 Arrow 值写入 Parquet 的批次大小。
	写入	VERSION	String	PARQUET_1_0	Parquet 文件格式版本。
	写入	DATA_PAGE_VERSION	String	1	数据页格式版本。
	写入	CREATED_BY	String	Arrow 构建标识符	创建文件的应用程序标识符。
ORC	写入	COMPRESSION	String	SNAPPY	压缩编解码器（例如SNAPPY、GZIP）。
	写入	MAX_ROWS_PER_FILE	Int64	100000000	每个输出文件的最大行数。

file_path

文件输出的路径。支持本地存储路径或云存储路径，例如 Amazon S3 和 Google Cloud Storage (GCS)。

此参数必填。

path

写入或读取文件的绝对路径。

• 当从文件变量导入数据时，该路径可指向文件或目录。目录中的所有文件都须对应相同的点类型或边类型。
• 当导出数据至文件变量时，该路径被解析为目录，系统将在该目录下自动创建写入文件。文件数量由配置项query_concurrency决定。

hostname和port

存储服务的主机名或 IP 地址及端口，用于写入或读取文件。

access_key和secret_key

用于访问云存储服务的 Access Key 和 Secret Key。

在访问 Amazon S3 时，也支持将 Access Key 和 Secret Key 指定为输出路径中的参数（parameter_name）。

在访问 GCS 时，也支持省略 Access Key 和 Secret Key，而是指定anonymous来访问公共存储桶。

bucket

往云存储服务中写入或从中读取文件的存储桶名称。

parameter_name和parameter_value

往云存储服务中写入或从中读取文件时指定的参数。

在访问 Amazon S3 时，支持指定以下参数：

• access_key：用于访问 S3 存储桶的 Access Key。
• secret_key：用于访问 S3 存储桶的 Secret Key。
• region：S3 存储桶所在的区域。
• scheme：访问 S3 存储桶的协议，例如http或https。
• endpoint_override：用于覆盖默认 S3 端点的自定义端点。
• allow_bucket_creation：是否允许在存储桶不存在时创建存储桶。
• allow_bucket_deletion：是否允许在存储桶已存在时删除存储桶。

在访问 GCS 时，支持指定以下参数：

• scheme：访问 GCS 存储桶的协议，例如http或https。
• endpoint_override：用于覆盖默认 GCS 端点的自定义端点。
• retry_limit_seconds：写入文件失败时，重试的最大时间（以秒为单位）。若超过此时间仍未成功，则返回错误。

性能调优建议

为了最大化数据加载和处理性能，建议根据具体的硬件配置、数据格式和工作负载，对以下配置项进行调优：

• 块大小：为 CSV 文件配置BLOCK_SIZE；较大的块大小可提升大文件的 I/O 性能。
• 多线程：启用USE_THREADS以实现并行处理（适用于 CSV 和 Parquet 格式）。
• 批次大小：根据内存限制优化BATCH_SIZE和WRITE_BATCH_SIZE。
• 缓冲：对于网络存储或高延迟文件系统，使用BUFFER_SIZE和PRE_BUFFER。
• 目录加载：从目录读取文件时，确保所有文件具有相同的表结构。
• 网络数据源：对于远程文件源，需考虑网络延迟和带宽；相应地调整BUFFER_SIZE。
• 压缩：对于 ORC 文件，选择合适的COMPRESSION压缩编解码器（如SNAPPY、GZIP），以在文件大小和处理速度之间取得平衡。

关于更多的性能调优的配置项，请参见上文的 additional_options。

示例

以下示例基于示例数据集。

使用文件变量将查询数据导出到文件

'''
// 使用文件变量定义输出文件
FILE output_file {id INT64, firstName STRING} = DATAFILE {
   PATH: "file:///tmp/output.csv",
   FORMAT: "CSV",
   INCLUDE_HEADER: true
}

// 将查询数据导出到输出文件
USE movie
MATCH (v:Person)
EXPORT v.id, v.name INTO output_file
'''

使用文件变量从文件导入数据

更多信息，请参见从文件/文件变量导入数据。