Source: https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/variable-definition/file-variable/
Documentation version: v5.3.2

# 文件变量

文件变量用于定义基于文件的数据源和数据目的地。它们主要用于数据的[导入](https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/in-out/import/)或[导出](https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/in-out/export/)操作，可处理多种文件格式，包括 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`可以是常规标识符或使用反引号(```)包围的分隔标识符。有关标识符的更多信息，请参见[标识符命名规则](https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/overview/keywords-identifiers/#_3)。

### `column_definitions`

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

### `column_name`

文件中列的名称。`column_name`必须是一个标识符。更多信息，请参见[标识符命名规则](https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/overview/keywords-identifiers/#_3)。

### `value_type`

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

- [数值](https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/data-types/numeric-type/)，如`INT`、`UINT`、`FLOAT`、`DOUBLE`和`DECIMAL`。
- [字符串](https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/data-types/c-string-type/)
- [布尔](https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/data-types/boolean-type/)
- [日期和时间](https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/data-types/temporal-type/)，如`DATE`、`LOCAL TIME`、`ZONED TIME`、`LOCAL DATETIME`和`ZONED DATETIME`。
- [向量](https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/data-types/vector-type/)
- [列表](https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/data-types/list-type/)
- [集合](https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/data-types/set-type/)
- [映射](https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/data-types/map-type/)
- [地理空间](https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/data-types/geo-type/)

更多信息，请参见[数据类型](https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/data-types/)。

### `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](https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/variable-definition/file-variable/#additional_options)。 

## 示例

以下示例基于[示例数据集](https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/overview/example-dataset/)。

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

````
'''
// 使用文件变量定义输出文件
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
'''

````

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

更多信息，请参见[从文件/文件变量导入数据](https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/in-out/import/#from_files)。