ALTER STAGE¶

TYPE = CSV¶

COMPRESSION = AUTO | GZIP | BZ2 | BROTLI | ZSTD | DEFLATE | RAW_DEFLATE | NONE

使用:

数据加载、数据卸载和外部表

定义:

• 加载数据时，指定数据文件的当前压缩算法。Snowflake 使用此选项来检测 已压缩 的数据文件是如何压缩的，以便提取文件中的压缩数据进行加载。

• 卸载数据时，使用指定的压缩算法压缩数据文件。

值:

支持的值	备注
AUTO	加载数据时，压缩算法会自动检测，但使用 Brotli 的压缩文件除外，目前无法自动检测。卸载数据时，文件会使用默认格式 gzip 自动压缩。
GZIP
BZ2
BROTLI	加载/卸载 Brotli 压缩文件时必须进行指定。
ZSTD	支持 Zstandard v0.8（及更高版本）。
DEFLATE	使用 Deflate 压缩的文件（带有 zlib 标头、RFC1950）。
RAW_DEFLATE	使用 Raw Deflate 压缩的文件（无标头、RFC1951）。
NONE	在加载数据时，表示文件尚未压缩。在卸载数据时，指定卸载的未压缩文件。

默认值:

AUTO

RECORD_DELIMITER = 'string' | NONE

使用:

数据加载、数据卸载和外部表

定义:

一个或多个单字节或多字节字符，用于分隔输入文件（数据加载）或卸载文件（数据卸载）中的记录。接受常见的转义序列或以下单字节或多字节字符：

单字节字符:

八进制值（以 \\ 为前缀）或十六进制值（以 0x 或 \x 为前缀）。例如，对于由重音符号 (^) 字符分隔的记录，请指定八进制 (\\136) 或十六进制 (0x5e) 值。

多字节字符:

十六进制值（前缀为 \x）。例如，对于由分 (¢) 字符分隔的记录，请指定十六进制 (\xC2\xA2) 值。

RECORD_DELIMITER 或 FIELD_DELIMITER 分隔符不能是其他文件格式选项（例如 FIELD_DELIMITER = 'aa' RECORD_DELIMITER = 'aabb'）的分隔符的子字符串。

指定的分隔符必须是有效的 UTF-8 字符，而不是随机的字节序列。另请注意，分隔符限制为最多 20 个字符。

也接受 NONE 的值。

默认值:

数据加载:

换行符。请注意，“换行符”是合乎逻辑的，因而 \r\n 可以理解为 Windows 平台上文件的换行符。

数据卸载:

换行符 (\n)。

FIELD_DELIMITER = 'string' | NONE

使用:

数据加载、数据卸载和外部表

定义:

一个或多个单字节或多字节字符，用于分隔输入文件（数据加载）或卸载文件（数据卸载）中的字段。接受常见的转义序列或以下单字节或多字节字符：

单字节字符:

八进制值（以 \\ 为前缀）或十六进制值（以 0x 或 \x 为前缀）。例如，对于由重音符号 (^) 字符分隔的记录，请指定八进制 (\\136) 或十六进制 (0x5e) 值。

多字节字符:

十六进制值（前缀为 \x）。例如，对于由分 (¢) 字符分隔的记录，请指定十六进制 (\xC2\xA2) 值。

RECORD_DELIMITER 或 FIELD_DELIMITER 分隔符不能是其他文件格式选项（例如 FIELD_DELIMITER = 'aa' RECORD_DELIMITER = 'aabb'）的分隔符的子字符串。

备注

对于非 ASCII 字符，必须使用十六进制字节序列值来获取确定性行为。

指定的分隔符必须是有效的 UTF-8 字符，而不是随机的字节序列。另请注意，分隔符限制为最多 20 个字符。

也接受 NONE 的值。

默认值:

逗号 (,)

MULTI_LINE = TRUE | FALSE

使用:

数据加载和外部表

定义:

布尔值，指定是否允许多行。如果将 MULTI_LINE 设置为 FALSE，并且指定记录分隔符存在于 CSV 字段中，则包含该字段的记录将被解析为错误。

默认值:

TRUE

备注

如果您正在加载符合 RFC4180 规范的大型未压缩的 CSV 文件（大于 128MB），则当 MULTI_LINE 设置为 FALSE、COMPRESSION 设置为 NONE，并且 ON_ERROR 设置为 ABORT_STATEMENT 或 CONTINUE 时，Snowflake 支持对这些 CSV 文件进行并行扫描。

FILE_EXTENSION = 'string' | NONE

使用:

仅数据卸载

定义:

指定卸载到暂存区的文件的扩展名。接受任何扩展名。用户负责指定可由任何所需软件或服务读取的文件扩展名。

默认值:

null 表示文件扩展名由格式类型 .csv[compression] 确定，其中 compression 是由压缩方法添加的扩展名（如果已设置 COMPRESSION）。

备注

如果 SINGLE 复制选项为 TRUE，则默认情况下，COPY 命令会卸载没有文件扩展名的文件。要指定文件扩展名，请在 internal_location 或 external_location 路径中提供文件名和扩展名（例如 copy into @stage/data.csv）。

PARSE_HEADER = TRUE | FALSE

使用:

仅加载数据

定义:

布尔，指定是否使用数据文件中的第一行标题来确定列名称。

此文件格式选项仅适用于以下操作：

• 使用 INFER_SCHEMA 函数自动检测列定义。

• 使用 INFER_SCHEMA 函数和 MATCH_BY_COLUMN_NAME 复制选项将 CSV 数据加载到单独的列中。

如果该选项设置为 TRUE，则第一行标题将用于确定列名称。默认值 FALSE 将返回 c* 形式的列名称，其中 * 是列的位置。

备注

• 此选项不支持外部表。

• 如果设置了 PARSE_HEADER = TRUE，则不支持 SKIP_HEADER 选项。

默认值:

FALSE

SKIP_HEADER = integer

使用:

数据加载和外部表

定义:

要跳过的文件开头的行数。

注意，SKIP_HEADER 不使用 RECORD_DELIMITER 或 FIELD_DELIMITER 值来决定标头行；相反，它会直接跳过文件中指定数量的以 CRLF（回车符、换行）分隔的行。然后，使用 RECORD_DELIMITER 和 FIELD_DELIMITER 确定要加载的数据行。

默认值:

0

SKIP_BLANK_LINES = TRUE | FALSE

使用:

数据加载和外部表

定义:

布尔，指定是否跳过数据文件中遇到的任何空行；否则，空行将产生记录结束错误（默认行为）。

默认值:

FALSE

DATE_FORMAT = 'string' | AUTO

使用:

数据加载和卸载

定义:

定义数据文件（数据加载）或表（数据卸载）中日期值的格式。如果未指定值或为 AUTO，则使用 :ref:`label-DATE_INPUT_FORMAT`（数据加载）或 :ref:`label-DATE_OUTPUT_FORMAT`（数据卸载）参数的值。

默认值:

AUTO

TIME_FORMAT = 'string' | AUTO

使用:

数据加载和卸载

定义:

定义数据文件（数据加载）或表（数据卸载）中时间值的格式。如果未指定值或为 AUTO，则使用 :ref:`label-TIME_INPUT_FORMAT`（数据加载）或 :ref:`label-TIME_OUTPUT_FORMAT`（数据卸载）参数的值。

默认值:

AUTO

TIMESTAMP_FORMAT = string' | AUTO

使用:

数据加载和卸载

定义:

定义数据文件（数据加载）或表（数据卸载）中时间戳值的格式。如果未指定值或为 AUTO，则使用 :ref:`label-TIMESTAMP_INPUT_FORMAT`（数据加载）或 :ref:`label-TIMESTAMP_OUTPUT_FORMAT`（数据卸载）参数的值。

默认值:

AUTO

BINARY_FORMAT = HEX | BASE64 | UTF8

使用:

数据加载和卸载

定义:

定义二进制输入或输出的编码格式。在表中的二进制列中加载数据或从二进制列中卸载数据时，可以使用该选项。

默认值:

HEX

ESCAPE = 'character' | NONE

使用:

数据加载和卸载

定义:

用作封闭或未封闭字段值的转义字符的单字节字符串。转义字符对字符序列中的后续字符调用替代解释。您可以使用 ESCAPE 字符将数据中 FIELD_OPTIONALLY_ENCLOSED_BY 字符的实例解释为字面量。

接受常见的转义序列、八进制值或十六进制值。

加载数据:

仅指定封闭字段的转义字符。通过设置 FIELD_OPTIONALLY_ENCLOSED_BY 指定用于包围字段的字符。

备注

此文件格式选项仅支持单字节字符。请注意，UTF-8 字符编码将高阶 ASCII 字符表示为多字节字符。如果数据文件使用 UTF-8 字符集进行编码，则不能将高阶 ASCII 字符指定为选项值。

此外，如果指定高阶 ASCII 字符，建议将文件格式选项设置为 ENCODING = 'string' 数据文件的字符编码，以确保正确解释该字符。

卸载数据:

如果设置此选项，它将替换 ESCAPE_UNENCLOSED_FIELD 的转义字符集。

默认值:

NONE

ESCAPE_UNENCLOSED_FIELD = 'character' | NONE

使用:

数据加载、数据卸载和外部表

定义:

仅用作未封闭字段值的转义字符的单字节字符串。转义字符对字符序列中的后续字符调用替代解释。您可以使用 ESCAPE 字符将数据中 FIELD_DELIMITER 或 RECORD_DELIMITER 字符的实例解释为字面量。转义字符还可用于对数据中自身的实例进行转义。

接受常见的转义序列、八进制值或十六进制值。

加载数据:

仅指定未封闭字段的转义字符。

备注

• 默认值为 \\。如果数据文件中的行以反斜杠 (\) 字符结尾，则此字符将转义为 RECORD_DELIMITER 文件格式选项指定的换行符或回车符。因此，加载操作会将此行和下一行视为单行数据。若要避免此问题，请将值设置为 NONE。

• 此文件格式选项仅支持单字节字符。请注意，UTF-8 字符编码将高阶 ASCII 字符表示为多字节字符。如果数据文件使用 UTF-8 字符集进行编码，则不能将高阶 ASCII 字符指定为选项值。

  此外，如果指定高阶 ASCII 字符，建议将文件格式选项设置为 ENCODING = 'string' 数据文件的字符编码，以确保正确解释该字符。

卸载数据:

如果设置了 ESCAPE，该文件格式选项的转义字符集将替换此选项。

默认值:

反斜杠 (\\)

TRIM_SPACE = TRUE | FALSE

使用:

数据加载和外部表

定义:

布尔，指定是否从字段中移除空格。

例如，如果您的外部数据库软件将字段放在引号中，但插入了前导空格，则 Snowflake 会读取前导空格而不是左引号字符作为字段的开头（即引号被解释为字段数据字符串的一部分）。可将选项设置为 TRUE，在数据加载期间移除不需要的空格。

再举一个例子，如果字符串两边的引号两边有前导空格或尾随空格，则可以使用此选项移除周围的空格，并使用 FIELD_OPTIONALLY_ENCLOSED_BY 选项移除引号字符。请注意，引号 内 的任何空格都将保留。例如，假设 FIELD_DELIMITER = '|' 和 FIELD_OPTIONALLY_ENCLOSED_BY = '"'：

|"Hello world"|    /* loads as */  >Hello world<
|" Hello world "|  /* loads as */  > Hello world <
| "Hello world" |  /* loads as */  >Hello world<

Copy

（此示例中的括号未加载；它们用于分隔加载字符串的开头和结尾）

默认值:

FALSE

FIELD_OPTIONALLY_ENCLOSED_BY = 'character' | NONE

使用:

数据加载、数据卸载和外部表

定义:

用于包围字符串的字符。值可以是 NONE、单引号字符 (') 或双引号字符 (")。要使用单引号字符，请使用八进制或十六进制表示形式 (0x27) 或双单引号转义 ('')。

仅数据卸载:

源表中的字段包含此字符时，Snowflake 使用相同的字符对其进行转义以进行卸载。例如，如果值是双引号字符，且字段包含字符串 A "B" C，则 Snowflake 会按如下方式对双引号进行转义以进行卸载：

A ""B"" C

默认值:

NONE

NULL_IF = ( 'string1' [ , 'string2' , ... ] )

使用:

数据加载、数据卸载和外部表

定义:

用于与 SQL NULL 相互转换的字符串：

• 加载数据时，Snowflake 会将数据加载源中的这些值替换为 SQL NULL。若要指定多个字符串，请将字符串列表放在括号中，并使用逗号分隔每个值。

  请注意，无论数据类型如何，Snowflake 都会将该值的所有实例转换为 NULL。例如，如果 2 指定为值，则转换为字符串或数字的所有 2 实例。

  例如：

  NULL_IF = ('\N', 'NULL', 'NUL', '')

  请注意，此选项可以包含空字符串。

• 卸载数据时：Snowflake 会将 SQL NULL 值转换为列表中的第一个值。

默认值:

\N``（即 NULL，假设 :code:`ESCAPE_UNENCLOSED_FIELD` 值为 ``\\）

ERROR_ON_COLUMN_COUNT_MISMATCH = TRUE | FALSE

使用:

仅加载数据

定义:

布尔，指定在输入文件中的分隔列数（即字段）与相应表中的列数不匹配时是否生成解析错误。

如果设置为 FALSE，则不会生成错误，并且加载将继续。如果文件已成功加载：

• 如果输入文件包含的记录字段数多于表中的列数，则匹配的字段将按文件中的出现顺序加载，其余字段将不加载。

• 如果输入文件包含的记录字段数少于表中的列数，则表中不匹配的列将加载 NULL 值。

此选项假定输入文件中的所有记录都具有相同的长度（即无论为此参数指定的值如何，包含不同长度记录的文件都会返回错误）。

默认值:

TRUE

备注

:doc:`在加载期间转换数据时 </user-guide/data-load-transform>`（即使用查询作为 COPY 命令的源），此选项将被忽略。您的数据文件不需要与目标表具有相同的列数和顺序。

REPLACE_INVALID_CHARACTERS = TRUE | FALSE

使用:

仅加载数据

定义:

布尔，指定是否将无效的 UTF-8 字符替换为 Unicode 替换字符 (�)。

如果设置为 TRUE，Snowflake 会将无效的 UTF-8 字符替换为 Unicode 替换字符。

如果设置为 FALSE，则加载操作在检测到无效的 UTF-8 字符编码时产生错误。

默认值:

FALSE

EMPTY_FIELD_AS_NULL = TRUE | FALSE

使用:

数据加载、数据卸载和外部表

定义:

• 加载数据时，指定是否为输入文件中的空字段插入 SQL NULL，空字段由两个连续的分隔符（例如 ,,）表示。

  如果设置为 FALSE，Snowflake 会尝试将空字段转换为相应列类型。空字符串会插入到类型为 STRING 的列中。对于其他列类型，COPY 命令将引发错误。

• 卸载数据时，此选项与 FIELD_OPTIONALLY_ENCLOSED_BY 结合使用。FIELD_OPTIONALLY_ENCLOSED_BY = NONE 时，设置 EMPTY_FIELD_AS_NULL = FALSE 指定将表中的空字符串卸载为空字符串值，而不用将字段值放在引号内。

  如果设置为 TRUE，FIELD_OPTIONALLY_ENCLOSED_BY 必须指定一个字符来包围字符串。

默认值:

TRUE

SKIP_BYTE_ORDER_MARK = TRUE | FALSE

使用:

仅加载数据

定义:

布尔，指定如果数据文件中存在 BOM（字节顺序标记），是否跳过。BOM 是数据文件开头的字符代码，用于定义字节顺序和编码形式。

如果设置为 FALSE，Snowflake 会识别数据文件中的任何 BOM，这可能会导致 BOM 错误或合并到表中的第一列中。

默认值:

TRUE

ENCODING = 'string'

使用:

数据加载和外部表

定义:

字符串（常量），指定将数据加载到表中时源数据的字符集。

字符 集	ENCODING 值	支持的语言	备注
Big5	BIG5	繁体中文
EUC-JP	EUCJP	日语
EUC-KR	EUCKR	韩语
GB18030	GB18030	中文
IBM420	IBM420	阿拉伯语
IBM424	IBM424	希伯来语
IBM949	IBM949	韩语
ISO-2022-CN	ISO2022CN	简体中文
ISO-2022-JP	ISO2022JP	日语
ISO-2022-KR	ISO2022KR	韩语
ISO-8859-1	ISO88591	丹麦语、荷兰语、英语、法语、德语、意大利语、挪威语、葡萄牙语、瑞典语
ISO-8859-2	ISO88592	捷克语、匈牙利语、波兰语、罗马尼亚语
ISO-8859-5	ISO88595	俄语
ISO-8859-6	ISO88596	阿拉伯语
ISO-8859-7	ISO88597	希腊语
ISO-8859-8	ISO88598	希伯来语
ISO-8859-9	ISO88599	土耳其语
ISO-8859-15	ISO885915	丹麦语、荷兰语、英语、法语、德语、意大利语、挪威语、葡萄牙语、瑞典语	与 ISO-8859-1 相同，但 8 个字符除外，包括欧元货币符号。
KOI8-R	KOI8R	俄语
Shift_JIS	SHIFTJIS	日语
UTF-8	UTF8	所有语言	要从分隔文件（CSV、TSV 等）加载数据，默认为 UTF-8。. . 要从所有其他支持的文件格式（JSON、Avro 等）加载数据以及卸载数据，UTF-8 是唯一支持的字符集。
UTF-16	UTF16	所有语言
UTF-16BE	UTF16BE	所有语言
UTF-16LE	UTF16LE	所有语言
UTF-32	UTF32	所有语言
UTF-32BE	UTF32BE	所有语言
UTF-32LE	UTF32LE	所有语言
windows-874	WINDOWS874	泰语
windows-949	WINDOWS949	韩语
windows-1250	WINDOWS1250	捷克语、匈牙利语、波兰语、罗马尼亚语
windows-1251	WINDOWS1251	俄语
windows-1252	WINDOWS1252	丹麦语、荷兰语、英语、法语、德语、意大利语、挪威语、葡萄牙语、瑞典语
windows-1253	WINDOWS1253	希腊语
windows-1254	WINDOWS1254	土耳其语
windows-1255	WINDOWS1255	希伯来语
windows-1256	WINDOWS1256	阿拉伯语

默认值:

UTF8

备注

Snowflake 将所有数据存储在 UTF-8 字符集中。数据在加载到 Snowflake 之前将转换为 UTF-8。

TYPE = JSON¶

COMPRESSION = AUTO | GZIP | BZ2 | BROTLI | ZSTD | DEFLATE | RAW_DEFLATE | NONE

使用:

数据加载和外部表

定义:

• 加载数据时，指定数据文件的当前压缩算法。Snowflake 使用此选项来检测 已压缩 的数据文件是如何压缩的，以便提取文件中的压缩数据进行加载。

• 卸载数据时，使用指定的压缩算法压缩数据文件。

值:

支持的值	备注
AUTO	加载数据时，压缩算法会自动检测，但使用 Brotli 的压缩文件除外，目前无法自动检测。卸载数据时，文件会使用默认格式 gzip 自动压缩。
GZIP
BZ2
BROTLI	如果加载/卸载 Brotli 压缩文件，则必须进行指定。
ZSTD	支持 Zstandard v0.8（及更高版本）。
DEFLATE	使用 Deflate 压缩的文件（带有 zlib 标头、RFC1950）。
RAW_DEFLATE	使用 Raw Deflate 压缩的文件（无标头、RFC1951）。
NONE	在加载数据时，表示文件尚未压缩。在卸载数据时，指定卸载的未压缩文件。

默认值:

AUTO

DATE_FORMAT = 'string' | AUTO

使用:

仅加载数据

定义:

定义数据文件中日期字符串值的格式。如果未指定值或值为 AUTO，则使用 DATE_INPUT_FORMAT 参数的值。

此文件格式选项仅适用于以下操作：

• 使用 MATCH_BY_COLUMN_NAME 复制选项将 JSON 数据加载到单独的列中。

• 通过在 COPY 语句中指定查询（即 COPY 转换），将 JSON 数据加载到单独的列中。

默认值:

AUTO

TIME_FORMAT = 'string' | AUTO

使用:

仅加载数据

定义:

定义数据文件中时间字符串值的格式。如果未指定值或值为 AUTO，则使用 TIME_INPUT_FORMAT 参数的值。

此文件格式选项仅适用于以下操作：

• 使用 MATCH_BY_COLUMN_NAME 复制选项将 JSON 数据加载到单独的列中。

• 通过在 COPY 语句中指定查询（即 COPY 转换），将 JSON 数据加载到单独的列中。

默认值:

AUTO

TIMESTAMP_FORMAT = string' | AUTO

使用:

仅加载数据

定义:

定义数据文件中时间戳字符串值的格式。如果未指定值或值为 AUTO，则使用 TIMESTAMP_INPUT_FORMAT 参数的值。

此文件格式选项仅适用于以下操作：

• 使用 MATCH_BY_COLUMN_NAME 复制选项将 JSON 数据加载到单独的列中。

• 通过在 COPY 语句中指定查询（即 COPY 转换），将 JSON 数据加载到单独的列中。

默认值:

AUTO

BINARY_FORMAT = HEX | BASE64 | UTF8

使用:

仅加载数据

定义:

定义数据文件中二进制字符串值的编码格式。将数据加载到表中的二进制列时可以使用该选项。

此文件格式选项仅适用于以下操作：

• 使用 MATCH_BY_COLUMN_NAME 复制选项将 JSON 数据加载到单独的列中。

• 通过在 COPY 语句中指定查询（即 COPY 转换），将 JSON 数据加载到单独的列中。

默认值:

HEX

TRIM_SPACE = TRUE | FALSE

使用:

仅加载数据

定义:

布尔，指定是否从字符串中移除前导和尾随空格。

例如，如果您的外部数据库软件将字段放在引号中，但插入了前导空格，则 Snowflake 会读取前导空格而不是左引号字符作为字段的开头（即引号被解释为字段数据字符串的一部分）。可将选项设置为 TRUE，在数据加载期间移除不需要的空格。

仅当使用 MATCH_BY_COLUMN_NAME 复制选项将 JSON 数据加载到单独的列中时，此文件格式选项才应用于以下操作。

默认值:

FALSE

MULTI_LINE = TRUE | FALSE

使用：数据加载和外部表

定义:

布尔值，指定是否允许多行。如果将 MULTI_LINE 设置为 FALSE，并且 JSON 记录中存在新行，则包含新行的记录将被解析为错误。

默认值:

TRUE

NULL_IF = ( 'string1' [ , 'string2' , ... ] )

使用:

仅加载数据

定义:

用于与 SQL NULL 相互转换的字符串。Snowflake 会将数据加载源中的这些字符串替换为 SQL NULL。若要指定多个字符串，请将字符串列表放在括号中，并使用逗号分隔每个值。

仅当使用 MATCH_BY_COLUMN_NAME 复制选项将 JSON 数据加载到单独的列中时，此文件格式选项才应用于以下操作。

请注意，无论数据类型如何，Snowflake 都会将该值的所有实例转换为 NULL。例如，如果 2 指定为值，则转换为字符串或数字的所有 2 实例。

例如：

NULL_IF = ('\N', 'NULL', 'NUL', '')

请注意，此选项可以包含空字符串。

默认值:

``N``（即，NULL）

FILE_EXTENSION = 'string' | NONE

使用:

仅数据卸载

定义:

指定卸载到暂存区的文件的扩展名。接受任何扩展名。用户负责指定可由任何所需软件或服务读取的文件扩展名。

默认值:

null 表示文件扩展名由格式类型 .json[compression] 确定，其中 compression 是由压缩方法添加的扩展名（如果已设置 COMPRESSION）。

ENABLE_OCTAL = TRUE | FALSE

使用:

仅加载数据

定义:

布尔，支持解析八进制数。

默认值:

FALSE

ALLOW_DUPLICATE = TRUE | FALSE

使用:

数据加载和外部表

定义:

布尔，指定允许重复对象字段名称（仅保留最后一个）。

默认值:

FALSE

STRIP_OUTER_ARRAY = TRUE | FALSE

使用:

数据加载和外部表

定义:

布尔，指示 JSON 解析器移除外括号（即 [ ]）。

默认值:

FALSE

STRIP_NULL_VALUES = TRUE | FALSE

使用:

数据加载和外部表

定义:

布尔，指示 JSON 解析器移除包含 null 值的对象字段或数组元素。例如，当设置为 TRUE 时，会发生以下变化：

之前	之后
[null]	[]
[null,null,3]	[,,3]
{"a":null,"b":null,"c":123}	{"c":123}
{"a":[1,null,2],"b":{"x":null,"y":88}}	{"a":[1,,2],"b":{"y":88}}

默认值:

FALSE

REPLACE_INVALID_CHARACTERS = TRUE | FALSE

使用:

数据加载和外部表

定义:

布尔，指定是否将无效的 UTF-8 字符替换为 Unicode 替换字符 (�)。此选项执行一对一的字符替换。

值:

如果设置为 TRUE，Snowflake 会将无效的 UTF-8 字符替换为 Unicode 替换字符。

如果设置为 FALSE，则加载操作在检测到无效的 UTF-8 字符编码时产生错误。

默认值:

FALSE

IGNORE_UTF8_ERRORS = TRUE | FALSE

使用:

数据加载和外部表

定义:

布尔，指定 UTF-8 编码错误是否产生错误条件。它是 REPLACE_INVALID_CHARACTERS 的替代语法。

值:

如果设置为 TRUE，则任何无效 UTF-8 的序列都将以静默方式替换为 Unicode 字符 U+FFFD （即“替换字符”）。

如果设置为 FALSE，则加载操作在检测到无效的 UTF-8 字符编码时产生错误。

默认值:

FALSE

SKIP_BYTE_ORDER_MARK = TRUE | FALSE

使用:

仅加载数据

定义:

布尔，指定如果数据文件中存在 BOM（字节顺序标记），是否跳过。BOM 是数据文件开头的字符代码，用于定义字节顺序和编码形式。

如果设置为 FALSE，Snowflake 会识别数据文件中的任何 BOM，这可能会导致 BOM 错误或合并到表中的第一列中。

默认值:

TRUE

TYPE = AVRO¶

COMPRESSION = AUTO | GZIP | BROTLI | ZSTD | DEFLATE | RAW_DEFLATE | NONE

使用:

仅加载数据

定义:

• 加载数据时，指定数据文件的当前压缩算法。Snowflake 使用此选项来检测 已压缩 的数据文件是如何压缩的，以便提取文件中的压缩数据进行加载。

• 卸载数据时，使用指定的压缩算法压缩数据文件。

值:

支持的值	备注
AUTO	加载数据时，压缩算法会自动检测，但使用 Brotli 的压缩文件除外，目前无法自动检测。卸载数据时，文件会使用默认格式 gzip 自动压缩。
GZIP
BROTLI	如果加载/卸载 Brotli 压缩文件，则必须进行指定。
ZSTD	支持 Zstandard v0.8（及更高版本）。
DEFLATE	使用 Deflate 压缩的文件（带有 zlib 标头、RFC1950）。
RAW_DEFLATE	使用 Raw Deflate 压缩的文件（无标头、RFC1951）。
NONE	在加载数据时，表示文件尚未压缩。在卸载数据时，指定卸载的未压缩文件。

默认值:

AUTO。

TRIM_SPACE = TRUE | FALSE

使用:

仅加载数据

定义:

布尔，指定是否从字符串中移除前导和尾随空格。

例如，如果您的外部数据库软件将字段放在引号中，但插入了前导空格，则 Snowflake 会读取前导空格而不是左引号字符作为字段的开头（即引号被解释为字段数据字符串的一部分）。可将选项设置为 TRUE，在数据加载期间移除不需要的空格。

仅当使用 MATCH_BY_COLUMN_NAME 复制选项将 Avro 数据加载到单独的列中时，此文件格式选项才应用于以下操作。

默认值:

FALSE

REPLACE_INVALID_CHARACTERS = TRUE | FALSE

使用:

数据加载和外部表

定义:

布尔，指定是否将无效的 UTF-8 字符替换为 Unicode 替换字符 (�)。此选项执行一对一的字符替换。

值:

如果设置为 TRUE，Snowflake 会将无效的 UTF-8 字符替换为 Unicode 替换字符。

如果设置为 FALSE，则加载操作在检测到无效的 UTF-8 字符编码时产生错误。

默认值:

FALSE

NULL_IF = ( 'string1' [ , 'string2' , ... ] )

使用:

仅加载数据

定义:

用于与 SQL NULL 相互转换的字符串。Snowflake 会将数据加载源中的这些字符串替换为 SQL NULL。若要指定多个字符串，请将字符串列表放在括号中，并使用逗号分隔每个值。

仅当使用 MATCH_BY_COLUMN_NAME 复制选项将 Avro 数据加载到单独的列中时，此文件格式选项才应用于以下操作。

请注意，无论数据类型如何，Snowflake 都会将该值的所有实例转换为 NULL。例如，如果 2 指定为值，则转换为字符串或数字的所有 2 实例。

例如：

NULL_IF = ('\N', 'NULL', 'NUL', '')

请注意，此选项可以包含空字符串。

默认值:

``N``（即，NULL）

TYPE = ORC¶

TRIM_SPACE = TRUE | FALSE

使用:

数据加载和外部表

定义:

布尔，指定是否从字符串中移除前导和尾随空格。

例如，如果您的外部数据库软件将字段放在引号中，但插入了前导空格，则 Snowflake 会读取前导空格而不是左引号字符作为字段的开头（即引号被解释为字段数据字符串的一部分）。可将选项设置为 TRUE，在数据加载期间移除不需要的空格。

仅当使用 MATCH_BY_COLUMN_NAME 复制选项将 Orc 数据加载到单独的列中时，此文件格式选项才应用于以下操作。

默认值:

FALSE

REPLACE_INVALID_CHARACTERS = TRUE | FALSE

使用:

数据加载和外部表

定义:

布尔，指定是否将无效的 UTF-8 字符替换为 Unicode 替换字符 (�)。此选项执行一对一的字符替换。

值:

如果设置为 TRUE，Snowflake 会将无效的 UTF-8 字符替换为 Unicode 替换字符。

如果设置为 FALSE，则加载操作在检测到无效的 UTF-8 字符编码时产生错误。

默认值:

FALSE

NULL_IF = ( 'string1' [ , 'string2' , ... ] )

使用:

数据加载和外部表

定义:

用于与 SQL NULL 相互转换的字符串。Snowflake 会将数据加载源中的这些字符串替换为 SQL NULL。若要指定多个字符串，请将字符串列表放在括号中，并使用逗号分隔每个值。

仅当使用 MATCH_BY_COLUMN_NAME 复制选项将 Orc 数据加载到单独的列中时，此文件格式选项才应用于以下操作。

请注意，无论数据类型如何，Snowflake 都会将该值的所有实例转换为 NULL。例如，如果 2 指定为值，则转换为字符串或数字的所有 2 实例。

例如：

NULL_IF = ('\N', 'NULL', 'NUL', '')

请注意，此选项可以包含空字符串。

默认值:

``N``（即，NULL）

TYPE = PARQUET¶

COMPRESSION = AUTO | LZO | SNAPPY | NONE

使用:

数据卸载和外部表

定义:

• 卸载数据时，指定 Parquet 文件中列的压缩算法。

值:

支持的值	备注
AUTO	加载数据时，会自动检测压缩算法。支持以下压缩算法：Brotli、gzip、Lempel-Ziv-Oberhumer (LZO)、LZ4、Snappy 或 Zstandard v0.8（及更高版本）。. 卸载数据时，默认情况下使用 ` Snappy <https://google.github.io/snappy/ (https://google.github.io/snappy/)>`_ 压缩算法压缩卸载的文件。
LZO	卸载数据时，默认情况下使用 Snappy 算法压缩文件。如果将数据卸载到 LZO 压缩文件，请指定此值。
SNAPPY	卸载数据时，默认情况下使用 Snappy 算法压缩文件。您可以选择指定此值。
NONE	在加载数据时，表示文件尚未压缩。在卸载数据时，指定卸载的未压缩文件。

默认值:

AUTO

SNAPPY_COMPRESSION = TRUE | FALSE

使用:

仅数据卸载

支持的值	备注
AUTO	对于卸载的文件，默认情况下使用 ` Snappy <https://google.github.io/snappy/ (https://google.github.io/snappy/)>`_ 压缩算法进行压缩。
SNAPPY	如果卸载 Snappy 压缩文件，则可以指定。
NONE	在加载数据时，表示文件尚未压缩。在卸载数据时，指定卸载的未压缩文件。

定义:

布尔，指定是否使用 SNAPPY 算法压缩卸载文件。

备注

已弃用。`请改用 :samp:`COMPRESSION = SNAPPY。

限制:

仅支持数据卸载操作。

默认值:

TRUE

BINARY_AS_TEXT = TRUE | FALSE

使用:

数据加载和外部表

定义:

布尔，指定是否将未定义逻辑数据类型的列解释为 UTF-8 文本。当设置为 FALSE 时，Snowflake 会将这些列解释为二进制数据。

默认值:

TRUE

备注

Snowflake 建议您将 BINARY_AS_TEXT 设置为 FALSE 以避免任何潜在的转换问题。

TRIM_SPACE = TRUE | FALSE

使用:

仅加载数据

定义:

布尔，指定是否从字符串中移除前导和尾随空格。

例如，如果您的外部数据库软件将字段放在引号中，但插入了前导空格，则 Snowflake 会读取前导空格而不是左引号字符作为字段的开头（即引号被解释为字段数据字符串的一部分）。可将选项设置为 TRUE，在数据加载期间移除不需要的空格。

仅当使用 MATCH_BY_COLUMN_NAME 复制选项将 Parquet 数据加载到单独的列中时，此文件格式选项才应用于以下操作。

默认值:

FALSE

USE_LOGICAL_TYPE = TRUE | FALSE

使用:

数据加载、暂存文件中的数据查询和架构检测。

定义:

布尔，指定是否使用 Parquet 逻辑类型。使用此文件格式选项，Snowflake 可以在数据加载期间解释 Parquet 逻辑类型。有关更多信息，请参阅 ` Parquet 逻辑类型定义 <https://github.com/apache/parquet-format/blob/master/LogicalTypes.md (https://github.com/apache/parquet-format/blob/master/LogicalTypes.md)>`_。创建新文件格式选项时，若要启用 Parquet 逻辑类型，请将 USE_LOGICAL_TYPE 设置为 TRUE。

限制:

不支持数据卸载。

USE_VECTORIZED_SCANNER = TRUE | FALSE

使用:

暂存文件中的数据加载和数据查询

定义:

指定是否使用矢量化扫描程序加载 Parquet 文件的布尔值。

默认值:

FALSE。在未来的 BCR 中，默认值将为 TRUE。

使用矢量化扫描程序可以显著减少加载 Parquet 文件的延迟，因为该扫描器非常适合 Parquet (https://parquet.apache.org/docs/file-format/) 文件的列式格式。该扫描程序只会将 Parquet 文件的相关部分下载到内存中，如选定列的子集。

如果 USE_VECTORIZED_SCANNER 设置为 TRUE，则矢量化扫描程序具有以下行为：

• BINARY_AS_TEXT 选项始终被视为 FALSE，USE_LOGICAL_TYPE 选项始终被视为 TRUE，无论实际设置的值是什么。

• 矢量化扫描程序支持 Parquet 映射类型。扫描映射类型的输出如下：

  "my_map":
    {
     "k1": "v1",
     "k2": "v2"
    }
  

  Copy

• 矢量化扫描程序在输出中显示 NULL 值，如以下示例所示：

  "person":
   {
    "name": "Adam",
    "nickname": null,
    "age": 34,
    "phone_numbers":
    [
      "1234567890",
      "0987654321",
      null,
      "6781234590"
    ]
    }
  

  Copy

• 矢量化扫描程序按以下方式处理 Time 和 Timestamp：

  Parquet	Snowflake 矢量化扫描程序
  TimeType(isAdjustedToUtc=True/False, unit=MILLIS/MICROS/NANOS)	TIME
  TimestampType(isAdjustedToUtc=True, unit=MILLIS/MICROS/NANOS)	TIMESTAMP_LTZ
  TimestampType(isAdjustedToUtc=False, unit=MILLIS/MICROS/NANOS)	TIMESTAMP_NTZ
  INT96	TIMESTAMP_LTZ

如果 USE_VECTORIZED_SCANNER 设置为 FALSE，扫描程序具有以下行为：

• 此选项不支持 Parquet 映射。 扫描映射类型的输出如下：

  "my_map":
   {
    "key_value":
    [
     {
            "key": "k1",
            "value": "v1"
        },
        {
            "key": "k2",
            "value": "v2"
        }
      ]
    }
  

  Copy

• 此选项不会在扫描输出中明确显示 NULL 值，如以下示例所示：

  "person":
   {
    "name": "Adam",
    "age": 34
    "phone_numbers":
    [
     "1234567890",
     "0987654321",
     "6781234590"
    ]
   }
  

  Copy

• 此选项按以下方式处理 Time 和 Timestamp：

  Parquet	当 USE_LOGICAL_TYPE = TRUE 时	当 USE_LOGICAL_TYPE = FALSE 时
  TimeType(isAdjustedToUtc=True/False, unit=MILLIS/MICROS)	TIME	TIME（如果 ConvertedType 存在） INTEGER（如果 ConvertedType 不存在）
  TimeType(isAdjustedToUtc=True/False, unit=NANOS)	TIME	INTEGER
  TimestampType（isAdjustedToUtc=True，unit=MILLIS/MICROS）	TIMESTAMP_LTZ	TIMESTAMP_NTZ
  TimestampType（isAdjustedToUtc=True，unit=NANOS）	TIMESTAMP_LTZ	INTEGER
  TimestampType(isAdjustedToUtc=False, unit=MILLIS/MICROS)	TIMESTAMP_NTZ	TIMESTAMP_LTZ（如果 ConvertedType 存在） INTEGER（如果 ConvertedType 不存在）
  TimestampType(isAdjustedToUtc=False, unit=NANOS)	TIMESTAMP_NTZ	INTEGER
  INT96	TIMESTAMP_NTZ	TIMESTAMP_NTZ

REPLACE_INVALID_CHARACTERS = TRUE | FALSE

使用:

数据加载和外部表

定义:

布尔，指定是否将无效的 UTF-8 字符替换为 Unicode 替换字符 (�)。此选项执行一对一的字符替换。

值:

如果设置为 TRUE，Snowflake 会将无效的 UTF-8 字符替换为 Unicode 替换字符。

如果设置为 FALSE，则加载操作在检测到无效的 UTF-8 字符编码时产生错误。

默认值:

FALSE

NULL_IF = ( 'string1' [ , 'string2' , ... ] )

使用:

仅加载数据

定义:

用于与 SQL NULL 相互转换的字符串。Snowflake 会将数据加载源中的这些字符串替换为 SQL NULL。若要指定多个字符串，请将字符串列表放在括号中，并使用逗号分隔每个值。

仅当使用 MATCH_BY_COLUMN_NAME 复制选项将 Parquet 数据加载到单独的列中时，此文件格式选项才应用于以下操作。

请注意，无论数据类型如何，Snowflake 都会将该值的所有实例转换为 NULL。例如，如果 2 指定为值，则转换为字符串或数字的所有 2 实例。

例如：

NULL_IF = ('\N', 'NULL', 'NUL', '')

请注意，此选项可以包含空字符串。

默认值:

``N``（即，NULL）

TYPE = XML¶

COMPRESSION = AUTO | GZIP | BZ2 | BROTLI | ZSTD | DEFLATE | RAW_DEFLATE | NONE

使用:

仅加载数据

定义:

• 加载数据时，指定数据文件的当前压缩算法。Snowflake 使用此选项来检测 已压缩 的数据文件是如何压缩的，以便提取文件中的压缩数据进行加载。

• 卸载数据时，使用指定的压缩算法压缩数据文件。

值:

支持的值	备注
AUTO	加载数据时，压缩算法会自动检测，但使用 Brotli 的压缩文件除外，目前无法自动检测。卸载数据时，文件会使用默认格式 gzip 自动压缩。
GZIP
BZ2
BROTLI	如果加载/卸载 Brotli 压缩文件，则必须进行指定。
ZSTD	支持 Zstandard v0.8（及更高版本）。
DEFLATE	使用 Deflate 压缩的文件（带有 zlib 标头、RFC1950）。
RAW_DEFLATE	使用 Raw Deflate 压缩的文件（无标头、RFC1951）。
NONE	在加载数据时，表示文件尚未压缩。在卸载数据时，指定卸载的未压缩文件。

默认值:

AUTO

IGNORE_UTF8_ERRORS = TRUE | FALSE

使用:

数据加载和外部表

定义:

布尔，指定 UTF-8 编码错误是否产生错误条件。它是 REPLACE_INVALID_CHARACTERS 的替代语法。

值:

如果设置为 TRUE，则任何无效 UTF-8 的序列都将以静默方式替换为 Unicode 字符 U+FFFD （即“替换字符”）。

如果设置为 FALSE，则加载操作在检测到无效的 UTF-8 字符编码时产生错误。

默认值:

FALSE

PRESERVE_SPACE = TRUE | FALSE

使用:

仅加载数据

定义:

布尔，指定 XML 分析器是否在元素内容中保留前导空格和尾随空格。

默认值:

FALSE

STRIP_OUTER_ELEMENT = TRUE | FALSE

使用:

仅加载数据

定义:

布尔，指定 XML 解析器是否剥离外部 XML 元素，将第 2 级元素公开为单独的文档。

默认值:

FALSE

DISABLE_AUTO_CONVERT = TRUE | FALSE

使用:

仅加载数据

定义:

布尔，指定 XML 分析器是否禁用数值和布尔值从文本到原生表示形式的自动转换。

默认值:

FALSE

REPLACE_INVALID_CHARACTERS = TRUE | FALSE

使用:

数据加载和外部表

定义:

布尔，指定是否将无效的 UTF-8 字符替换为 Unicode 替换字符 (�)。此选项执行一对一的字符替换。

值:

如果设置为 TRUE，Snowflake 会将无效的 UTF-8 字符替换为 Unicode 替换字符。

如果设置为 FALSE，则加载操作在检测到无效的 UTF-8 字符编码时产生错误。

默认值:

FALSE

SKIP_BYTE_ORDER_MARK = TRUE | FALSE

使用:

仅加载数据

定义:

布尔，指定是否跳过输入文件中存在的任何 BOM（字节顺序标记）。BOM 是数据文件开头的字符代码，用于定义字节顺序和编码形式。

如果设置为 FALSE，Snowflake 会识别数据文件中的任何 BOM，这可能会导致 BOM 错误或合并到表中的第一列中。

默认值:

TRUE