版本: 最新版本-3.5

FILES

定义远程存储中的数据文件。它可以用于

从远程存储系统加载或查询数据
将数据卸载到远程存储系统

目前，FILES() 函数支持以下数据源和文件格式

数据源
- HDFS
- AWS S3
- Google Cloud Storage
- 其他 S3 兼容存储系统
- Microsoft Azure Blob Storage
- NFS(NAS)
文件格式
- Parquet
- ORC（从 v3.3 开始支持）
- CSV（从 v3.3 开始支持）
- Avro（从 v3.4.4 开始支持，仅用于加载）

从 v3.2 开始，除了基本数据类型之外，FILES() 还支持复杂数据类型，包括 ARRAY、JSON、MAP 和 STRUCT。

用于加载的 FILES()

从 v3.1.0 开始，StarRocks 支持使用表函数 FILES() 定义远程存储中的只读文件。它可以访问文件的路径相关属性的远程存储，推断文件中数据的表模式，并返回数据行。您可以使用 SELECT 直接查询数据行，使用 INSERT 将数据行加载到现有表中，或者使用 CREATE TABLE AS SELECT 创建新表并将数据行加载到其中。从 v3.3.4 开始，您还可以使用带有 DESC 的 FILES() 查看数据文件的模式。

语法

FILES( data_location , [data_format] [, schema_detect ] [, StorageCredentialParams ] [, columns_from_path ] [, list_files_only ] [, list_recursively])

参数

所有参数均为 "key" = "value" 对。

data_location

用于访问文件的 URI。

您可以指定路径或文件。例如，您可以将此参数指定为 "hdfs://<hdfs_host>:<hdfs_port>/user/data/tablename/20210411" 以从 HDFS 服务器上的路径 /user/data/tablename 加载名为 20210411 的数据文件。

您还可以使用通配符 ?、*、[]、{} 或 ^ 将此参数指定为多个数据文件的保存路径。例如，您可以将此参数指定为 "hdfs://<hdfs_host>:<hdfs_port>/user/data/tablename/*/*" 或 "hdfs://<hdfs_host>:<hdfs_port>/user/data/tablename/dt=202104*/*" 以从 HDFS 服务器上 /user/data/tablename 路径中的所有分区或仅 202104 分区加载数据文件。

注意

通配符还可用于指定中间路径。

要访问 HDFS，您需要将此参数指定为

"path" = "hdfs://<hdfs_host>:<hdfs_port>/<hdfs_path>"
-- Example: "path" = "hdfs://127.0.0.1:9000/path/file.parquet"

要访问 AWS S3

如果使用 S3 协议，则需要将此参数指定为

"path" = "s3://<s3_path>"
-- Example: "path" = "s3://path/file.parquet"

如果使用 S3A 协议，则需要将此参数指定为

"path" = "s3a://<s3_path>"
-- Example: "path" = "s3a://path/file.parquet"

要访问 Google Cloud Storage，您需要将此参数指定为

"path" = "s3a://<gcs_path>"
-- Example: "path" = "s3a://path/file.parquet"

要访问 Azure Blob Storage

如果您的存储帐户允许通过 HTTP 访问，您需要将此参数指定为

"path" = "wasb://<container>@<storage_account>.blob.core.windows.net/<blob_path>"
-- Example: "path" = "wasb://testcontainer@testaccount.blob.core.windows.net/path/file.parquet"

如果您的存储帐户允许通过 HTTPS 访问，您需要将此参数指定为

"path" = "wasbs://<container>@<storage_account>.blob.core.windows.net/<blob_path>"
-- Example: "path" = "wasbs://testcontainer@testaccount.blob.core.windows.net/path/file.parquet"

要访问 NFS(NAS)
```
"path" = "file:///<absolute_path>"
-- Example: "path" = "file:///home/ubuntu/parquetfile/file.parquet"
```
注意
要通过 file:// 协议访问 NFS 中的文件，您需要在每个 BE 或 CN 节点的同一目录下挂载 NAS 设备作为 NFS。

data_format

数据文件的格式。有效值

parquet
orc（从 v3.3 开始支持）
csv（从 v3.3 开始支持）
avro（从 v3.4.4 开始支持，仅用于加载）

您必须为特定的数据文件格式设置详细选项。

当 list_files_only 设置为 true 时，您不需要指定 data_format。

Parquet

Parquet 格式的示例

"format"="parquet",
"parquet.use_legacy_encoding" = "true"   -- for unloading only

parquet.use_legacy_encoding

控制用于 DATETIME 和 DECIMAL 数据类型的编码技术。有效值：true 和 false（默认值）。此属性仅支持数据卸载。

如果此项设置为 true

对于 DATETIME 类型，系统使用 INT96 编码。
对于 DECIMAL 类型，系统使用 fixed_len_byte_array 编码。

如果此项设置为 false

对于 DATETIME 类型，系统使用 INT64 编码。
对于 DECIMAL 类型，系统使用 INT32 或 INT64 编码。

注意

对于 DECIMAL 128 数据类型，只有 fixed_len_byte_array 编码可用。 parquet.use_legacy_encoding 不生效。

CSV

CSV 格式的示例

"format"="csv",
"csv.column_separator"="\\t",
"csv.enclose"='"',
"csv.skip_header"="1",
"csv.escape"="\\"

csv.column_separator

指定当数据文件为 CSV 格式时使用的列分隔符。如果您未指定此参数，则此参数默认为 \\t，表示制表符。您使用此参数指定的列分隔符必须与数据文件中实际使用的列分隔符相同。否则，由于数据质量不足，加载作业将失败。

使用 Files() 的任务是根据 MySQL 协议提交的。 StarRocks 和 MySQL 都转义加载请求中的字符。因此，如果列分隔符是不可见字符（例如制表符），则必须在列分隔符前面添加反斜杠 (\)。例如，如果列分隔符是 \t，则必须输入 \\t，如果列分隔符是 \n，则必须输入 \\n。 Apache Hive™ 文件使用 \x01 作为其列分隔符，因此如果数据文件来自 Hive，则必须输入 \\x01。

注意

对于 CSV 数据，您可以使用 UTF-8 字符串，例如逗号 (,)、制表符或管道 (|)，其长度不超过 50 个字节作为文本分隔符。

Null 值用 \N 表示。例如，数据文件由三列组成，并且来自该数据文件的记录在第一列和第三列中包含数据，但在第二列中没有数据。在这种情况下，您需要在第二列中使用 \N 来表示 null 值。这意味着记录必须编译为 a,\N,b 而不是 a,,b。 a,,b 表示记录的第二列包含空字符串。

csv.enclose

指定当数据文件为 CSV 格式时，用于根据 RFC4180 包装数据文件中字段值的字符。类型：单字节字符。默认值：NONE。最常见的字符是单引号 (') 和双引号 (")。

使用 enclose 指定的字符包装的所有特殊字符（包括行分隔符和列分隔符）都被视为普通符号。 StarRocks 可以比 RFC4180 做更多的事情，因为它允许您指定任何单字节字符作为 enclose 指定的字符。

如果字段值包含 enclose 指定的字符，您可以使用相同的字符来转义该 enclose 指定的字符。例如，您将 enclose 设置为 "，并且字段值为 a "quoted" c。在这种情况下，您可以将字段值作为 "a ""quoted"" c" 输入到数据文件中。

csv.skip_header

指定在 CSV 格式的数据中要跳过的标题行数。类型：INTEGER。默认值：0。

在某些 CSV 格式的数据文件中，使用许多标题行来定义元数据，例如列名和列数据类型。通过设置 skip_header 参数，您可以使 StarRocks 跳过这些标题行。例如，如果您将此参数设置为 1，则 StarRocks 在数据加载期间会跳过数据文件的第一行。

数据文件中的标题行必须使用您在加载语句中指定的行分隔符分隔。

csv.escape

指定用于转义各种特殊字符（例如行分隔符、列分隔符、转义字符和 enclose 指定的字符）的字符，这些字符随后被 StarRocks 视为公共字符并解析为它们所在的字段值的一部分。类型：单字节字符。默认值：NONE。最常见的字符是斜杠 (\)，必须在 SQL 语句中写成双斜杠 (\\)。

注意

escape 指定的字符同时应用于每对 enclose 指定的字符的内部和外部。以下是两个示例

当您将 enclose 设置为 " 并将 escape 设置为 \ 时，StarRocks 会将 "say \"Hello world\"" 解析为 say "Hello world"。

假设列分隔符是逗号 (,)。当您将 escape 设置为 \ 时，StarRocks 会将 a, b\, c 解析为两个单独的字段值：a 和 b, c。

schema_detect

从 v3.2 开始，FILES() 支持自动模式检测和同一批数据文件的联合。 StarRocks 首先通过对批处理中随机数据文件的某些数据行进行采样来检测数据的模式。然后，StarRocks 联合批处理中所有数据文件中的列。

您可以使用以下参数配置采样规则

auto_detect_sample_files：每个批处理中要采样的随机数据文件数。范围：[0, + ∞]。默认值：1。
auto_detect_sample_rows：每个采样数据文件中要扫描的数据行数。范围：[0, + ∞]。默认值：500。

采样后，StarRocks 根据这些规则联合来自所有数据文件的列

对于列名或索引不同的列，每个列都被标识为一个单独的列，并且最终返回所有单独列的联合。
对于列名相同但数据类型不同的列，它们被标识为同一列，但在相对精细的粒度级别上具有通用数据类型。例如，如果文件 A 中的列 col1 是 INT，但文件 B 中的列是 DECIMAL，则返回的列中使用 DOUBLE。
- 所有整数列将在整体粗粒度级别上联合为整数类型。
- 整数列与 FLOAT 类型列一起将联合为 DECIMAL 类型。
- 字符串类型用于联合其他类型。
通常，STRING 类型可用于联合所有数据类型。

您可以参考示例 5。

如果 StarRocks 未能联合所有列，则它会生成一个模式错误报告，其中包含错误信息和所有文件模式。

注意

单个批处理中的所有数据文件必须具有相同的文件格式。

下推目标表模式检查

从 v3.4.0 开始，系统支持将目标表模式检查下推到 FILES() 的 Scan 阶段。

FILES() 的模式检测并非完全严格。例如，当函数读取文件时，CSV 文件中的任何整数列都会被推断并检查为 BIGINT 类型。在这种情况下，如果目标表中的对应列是 TINYINT 类型，则不会过滤超出 BIGINT 类型的 CSV 数据记录。相反，它们将被隐式填充为 NULL。

为了解决这个问题，系统引入了动态 FE 配置项 files_enable_insert_push_down_schema，以控制是否将目标表模式检查下推到 FILES() 的 Scan 阶段。通过将 files_enable_insert_push_down_schema 设置为 true，系统将在文件读取时过滤掉未通过目标表模式检查的数据记录。

联合具有不同模式的文件

从 v3.4.0 开始，系统支持联合具有不同模式的文件，默认情况下，如果存在不存在的列，将返回错误。通过将属性 fill_mismatch_column_with 设置为 null，您可以允许系统为不存在的列分配 NULL 值，而不是返回错误。

fill_mismatch_column_with：系统在联合具有不同模式的文件时检测到不存在的列后的行为。有效值

none：如果检测到不存在的列，将返回错误。
null：NULL 值将被分配给不存在的列。

例如，要读取的文件来自 Hive 表的不同分区，并且已对较新的分区执行了模式更改。在读取新旧分区时，您可以将 fill_mismatch_column_with 设置为 null，系统将联合新旧分区文件的模式，并将 NULL 值分配给不存在的列。

系统基于列名联合 Parquet 和 ORC 文件的模式，并基于列的位置（顺序）联合 CSV 文件的模式。

从 Parquet 推断 STRUCT 类型

从 v3.4.0 开始，FILES() 支持从 Parquet 文件推断 STRUCT 类型数据。

StorageCredentialParams

StarRocks 用于访问您的存储系统的身份验证信息。

StarRocks 目前支持使用简单身份验证访问 HDFS，使用基于 IAM 用户的身份验证访问 AWS S3 和 GCS，并使用共享密钥、SAS 令牌、托管身份和服务主体访问 Azure Blob Storage。

HDFS

使用简单身份验证访问 HDFS

"hadoop.security.authentication" = "simple",
"username" = "xxxxxxxxxx",
"password" = "yyyyyyyyyy"

键	必需	描述
hadoop.security.authentication	否	身份验证方法。有效值：`simple`（默认值）。 `simple` 表示简单身份验证，意味着没有身份验证。
username	是	您要用于访问 HDFS 集群的 NameNode 的帐户的用户名。
password	是	您要用于访问 HDFS 集群的 NameNode 的帐户的密码。

使用 Kerberos 身份验证访问 HDFS

目前，FILES() 仅通过放置在 fe/conf、be/conf 和 cn/conf 目录下的配置文件 hdfs-site.xml 支持使用 Kerberos 身份验证访问 HDFS。

此外，您需要在每个 FE 配置文件 fe.conf、BE 配置文件 be.conf 和 CN 配置文件 cn.conf 中的配置项 JAVA_OPTS 中附加以下选项
```
# Specify the local path to which the Kerberos configuration file is stored.
-Djava.security.krb5.conf=<path_to_kerberos_conf_file>
```
示例
```
JAVA_OPTS="-Xlog:gc*:${LOG_DIR}/be.gc.log.$DATE:time -XX:ErrorFile=${LOG_DIR}/hs_err_pid%p.log -Djava.security.krb5.conf=/etc/krb5.conf"
```
您还需要在每个 FE、BE 和 CN 节点上运行 kinit 命令，以从密钥分发中心 (KDC) 获取票证授予票证 (TGT)。
```
kinit -kt <path_to_keytab_file> <principal>
```
要运行此命令，您使用的主体必须具有对您的 HDFS 集群的写入访问权限。此外，您需要为命令设置一个 crontab，以按特定时间间隔调度任务，从而防止身份验证过期。

示例
```
# Renew TGT every 6 hours.
0 */6 * * * kinit -kt sr.keytab sr/test.starrocks.com@STARROCKS.COM > /tmp/kinit.log
```
在启用 HA 模式的情况下访问 HDFS

目前，FILES() 仅通过放置在 fe/conf、be/conf 和 cn/conf 目录下的配置文件 hdfs-site.xml 支持访问启用 HA 模式的 HDFS。

AWS S3

如果您选择 AWS S3 作为您的存储系统，请执行以下操作之一

要选择基于实例配置文件的身份验证方法，请按如下方式配置 StorageCredentialParams
```
"aws.s3.use_instance_profile" = "true",
"aws.s3.region" = "<aws_s3_region>"
```

要选择基于假设角色的身份验证方法，请按如下方式配置 StorageCredentialParams

"aws.s3.use_instance_profile" = "true",
"aws.s3.iam_role_arn" = "<iam_role_arn>",
"aws.s3.region" = "<aws_s3_region>"

要选择基于 IAM 用户的身份验证方法，请按如下方式配置 StorageCredentialParams

"aws.s3.use_instance_profile" = "false",
"aws.s3.access_key" = "<iam_user_access_key>",
"aws.s3.secret_key" = "<iam_user_secret_key>",
"aws.s3.region" = "<aws_s3_region>"

下表描述了需要在 StorageCredentialParams 中配置的参数。

参数	必需	描述
aws.s3.use_instance_profile	是	指定是否启用凭据方法实例配置文件和承担角色。有效值：`true` 和 `false`。默认值：`false`。
aws.s3.iam_role_arn	否	具有您的 AWS S3 存储桶权限的 IAM 角色的 ARN。如果您选择承担角色作为访问 AWS S3 的凭据方法，则必须指定此参数。
aws.s3.region	是	您的 AWS S3 bucket 所在的区域。示例：`us-west-1`。
aws.s3.access_key	否	您的 IAM 用户的访问密钥。如果您选择 IAM 用户作为访问 AWS S3 的凭据方法，则必须指定此参数。
aws.s3.secret_key	否	您的 IAM 用户的密钥。如果您选择 IAM 用户作为访问 AWS S3 的凭据方法，则必须指定此参数。

有关如何选择访问 AWS S3 的身份验证方法以及如何在 AWS IAM 控制台中配置访问控制策略的信息，请参阅用于访问 AWS S3 的身份验证参数。

Google GCS

如果您选择 Google GCS 作为您的存储系统，请执行以下操作之一

要选择基于 VM 的身份验证方法，请按如下方式配置 StorageCredentialParams
```
"gcp.gcs.use_compute_engine_service_account" = "true"
```
下表描述了需要在 StorageCredentialParams 中配置的参数。

参数 默认值 值示例描述
gcp.gcs.use_compute_engine_service_account false true 指定是否直接使用绑定到您的 Compute Engine 的服务帐户。

要选择基于服务帐户的身份验证方法，请按如下方式配置 StorageCredentialParams

"gcp.gcs.service_account_email" = "<google_service_account_email>",
"gcp.gcs.service_account_private_key_id" = "<google_service_private_key_id>",
"gcp.gcs.service_account_private_key" = "<google_service_private_key>"

下表描述了需要在 StorageCredentialParams 中配置的参数。

参数	默认值	值示例	描述
gcp.gcs.service_account_email	""	`"user@hello.iam.gserviceaccount.com"`	在创建服务帐户时生成的 JSON 文件中的电子邮件地址。
gcp.gcs.service_account_private_key_id	""	"61d257bd8479547cb3e04f0b9b6b9ca07af3b7ea"	在创建服务帐户时生成的 JSON 文件中的私钥 ID。
gcp.gcs.service_account_private_key	""	"-----BEGIN PRIVATE KEY----xxxx-----END PRIVATE KEY-----\n"	在创建服务帐户时生成的 JSON 文件中的私钥。

要选择基于模拟的身份验证方法，请按如下方式配置 StorageCredentialParams

使 VM 实例模拟服务帐户

"gcp.gcs.use_compute_engine_service_account" = "true",
"gcp.gcs.impersonation_service_account" = "<assumed_google_service_account_email>"

下表描述了需要在 StorageCredentialParams 中配置的参数。

参数	默认值	值示例	描述
gcp.gcs.use_compute_engine_service_account	false	true	指定是否直接使用绑定到您的 Compute Engine 的服务帐户。
gcp.gcs.impersonation_service_account	""	"hello"	您要模拟的服务帐户。

使服务帐户（命名为元服务帐户）模拟另一个服务帐户（命名为数据服务帐户）

"gcp.gcs.service_account_email" = "<google_service_account_email>",
"gcp.gcs.service_account_private_key_id" = "<meta_google_service_account_email>",
"gcp.gcs.service_account_private_key" = "<meta_google_service_account_email>",
"gcp.gcs.impersonation_service_account" = "<data_google_service_account_email>"

下表描述了需要在 StorageCredentialParams 中配置的参数。

参数	默认值	值示例	描述
gcp.gcs.service_account_email	""	`"user@hello.iam.gserviceaccount.com"`	在创建元服务帐户时生成的 JSON 文件中的电子邮件地址。
gcp.gcs.service_account_private_key_id	""	"61d257bd8479547cb3e04f0b9b6b9ca07af3b7ea"	在创建元服务帐户时生成的 JSON 文件中的私钥 ID。
gcp.gcs.service_account_private_key	""	"-----BEGIN PRIVATE KEY----xxxx-----END PRIVATE KEY-----\n"	在创建元服务帐户时生成的 JSON 文件中的私钥。
gcp.gcs.impersonation_service_account	""	"hello"	您要模拟的数据服务帐户。

Azure Blob Storage

使用共享密钥访问 Azure Blob Storage
```
"azure.blob.shared_key" = "<shared_key>"
```
键必需描述
azure.blob.shared_key 是您可以用来访问 Azure Blob Storage 帐户的共享密钥。
使用 SAS 令牌访问 Azure Blob Storage
```
"azure.blob.sas_token" = "<storage_account_SAS_token>"
```
键必需描述
azure.blob.sas_token 是您可以用来访问 Azure Blob Storage 帐户的 SAS 令牌。

键	必需	描述
azure.blob.shared_key	是	您可以用来访问 Azure Blob Storage 帐户的共享密钥。

键	必需	描述
azure.blob.sas_token	是	您可以用来访问 Azure Blob Storage 帐户的 SAS 令牌。

使用托管身份访问 Azure Blob Storage（从 v3.4.4 开始支持）

注意

仅支持具有客户端 ID 凭据的用户分配的托管身份。
FE 动态配置 azure_use_native_sdk（默认值：true）控制是否允许系统使用托管身份和服务主体的身份验证。

"azure.blob.oauth2_use_managed_identity" = "true",
"azure.blob.oauth2_client_id" = "<oauth2_client_id>"

键	必需	描述
azure.blob.oauth2_use_managed_identity	是	是否使用托管身份访问 Azure Blob Storage 帐户。将其设置为 `true`。
azure.blob.oauth2_client_id	是	您可以用来访问 Azure Blob Storage 帐户的托管身份的客户端 ID。

使用服务主体访问 Azure Blob Storage（从 v3.4.4 开始支持）

注意

仅支持客户端密钥凭据。
FE 动态配置 azure_use_native_sdk（默认值：true）控制是否允许系统使用托管身份和服务主体的身份验证。

"azure.blob.oauth2_client_id" = "<oauth2_client_id>",
"azure.blob.oauth2_client_secret" = "<oauth2_client_secret>",
"azure.blob.oauth2_tenant_id" = "<oauth2_tenant_id>"

键	必需	描述
azure.blob.oauth2_client_id	是	您可以用来访问 Azure Blob Storage 帐户的服务主体的客户端 ID。
azure.blob.oauth2_client_secret	是	您可以用来访问 Azure Blob Storage 帐户的服务主体的客户端密钥。
azure.blob.oauth2_tenant_id	是	您可以用来访问 Azure Blob Storage 帐户的服务主体的租户 ID。

Azure Data Lake Storage Gen2

如果您选择 Data Lake Storage Gen2 作为您的存储系统，请执行以下操作之一

要选择托管标识身份验证方法，请按如下方式配置 StorageCredentialParams

"azure.adls2.oauth2_use_managed_identity" = "true",
"azure.adls2.oauth2_tenant_id" = "<service_principal_tenant_id>",
"azure.adls2.oauth2_client_id" = "<service_client_id>"

下表描述了需要在 StorageCredentialParams 中配置的参数。

参数	必需	描述
azure.adls2.oauth2_use_managed_identity	是	指定是否启用托管标识身份验证方法。将值设置为 `true`。
azure.adls2.oauth2_tenant_id	是	您要访问其数据的租户的 ID。
azure.adls2.oauth2_client_id	是	托管标识的客户端（应用程序）ID。

要选择共享密钥身份验证方法，请按如下方式配置 StorageCredentialParams
```
"azure.adls2.storage_account" = "<storage_account_name>",
"azure.adls2.shared_key" = "<storage_account_shared_key>"
```
下表描述了需要在 StorageCredentialParams 中配置的参数。

参数必需描述
azure.adls2.storage_account 是您的 Data Lake Storage Gen2 存储帐户的用户名。
azure.adls2.shared_key 是您的 Data Lake Storage Gen2 存储帐户的共享密钥。

参数	必需	描述
azure.adls2.storage_account	是	您的 Data Lake Storage Gen2 存储帐户的用户名。
azure.adls2.shared_key	是	您的 Data Lake Storage Gen2 存储帐户的共享密钥。

要选择服务主体身份验证方法，请按如下方式配置 StorageCredentialParams

"azure.adls2.oauth2_client_id" = "<service_client_id>",
"azure.adls2.oauth2_client_secret" = "<service_principal_client_secret>",
"azure.adls2.oauth2_client_endpoint" = "<service_principal_client_endpoint>"

下表描述了您需要在 StorageCredentialParams 中配置的参数。

参数	必需	描述
azure.adls2.oauth2_client_id	是	服务主体的客户端（应用程序）ID。
azure.adls2.oauth2_client_secret	是	创建的新客户端（应用程序）密钥的值。
azure.adls2.oauth2_client_endpoint	是	服务主体或应用程序的 OAuth 2.0 令牌端点 (v1)。

Azure Data Lake Storage Gen1

如果您选择 Data Lake Storage Gen1 作为您的存储系统，请执行以下操作之一

要选择托管服务标识身份验证方法，请按如下方式配置 StorageCredentialParams
```
"azure.adls1.use_managed_service_identity" = "true"
```
下表描述了需要在 StorageCredentialParams 中配置的参数。

参数必需描述
azure.adls1.use_managed_service_identity 是指定是否启用托管服务标识身份验证方法。将值设置为 true。

参数	必需	描述
azure.adls1.use_managed_service_identity	是	指定是否启用托管服务标识身份验证方法。将值设置为 `true`。

要选择服务主体身份验证方法，请按如下方式配置 StorageCredentialParams

"azure.adls1.oauth2_client_id" = "<application_client_id>",
"azure.adls1.oauth2_credential" = "<application_client_credential>",
"azure.adls1.oauth2_endpoint" = "<OAuth_2.0_authorization_endpoint_v2>"

下表描述了需要在 StorageCredentialParams 中配置的参数。

参数	必需	描述
azure.adls1.oauth2_client_id	是	的客户端（应用程序）ID。
azure.adls1.oauth2_credential	是	创建的新客户端（应用程序）密钥的值。
azure.adls1.oauth2_endpoint	是	服务主体或应用程序的 OAuth 2.0 令牌端点 (v1)。

其他 S3 兼容存储系统

如果您选择其他 S3 兼容存储系统（例如 MinIO），请按如下方式配置 StorageCredentialParams

"aws.s3.enable_ssl" = "false",
"aws.s3.enable_path_style_access" = "true",
"aws.s3.endpoint" = "<s3_endpoint>",
"aws.s3.access_key" = "<iam_user_access_key>",
"aws.s3.secret_key" = "<iam_user_secret_key>"

下表描述了需要在 StorageCredentialParams 中配置的参数。

参数	必需	描述
aws.s3.enable_ssl	是	指定是否启用 SSL 连接。有效值：`true` 和 `false`。默认值：`true`。
aws.s3.enable_path_style_access	是	指定是否启用路径样式 URL 访问。有效值：`true` 和 `false`。默认值：`false`。对于 MinIO，您必须将值设置为 `true`。
aws.s3.endpoint	是	用于连接到您的 S3 兼容存储系统而不是 AWS S3 的端点。
aws.s3.access_key	是	您的 IAM 用户的访问密钥。
aws.s3.secret_key	是	您的 IAM 用户的密钥。

columns_from_path

从 v3.2 开始，StarRocks 可以从文件路径中提取键/值对的值作为列的值。

"columns_from_path" = "<column_name> [, ...]"

假设数据文件 file1 存储在格式为 /geo/country=US/city=LA/ 的路径下。您可以将 columns_from_path 参数指定为 "columns_from_path" = "country, city"，以提取文件路径中的地理信息作为返回的列的值。有关更多说明，请参阅示例 4。

list_files_only

从 v3.4.0 开始，FILES() 支持在读取文件时仅列出文件。

"list_files_only" = "true"

请注意，当 list_files_only 设置为 true 时，您不需要指定 data_format。

有关更多信息，请参阅返回。

list_recursively

StarRocks 还支持 list_recursively 以递归方式列出文件和目录。 list_recursively 仅在 list_files_only 设置为 true 时才生效。默认值为 false。

"list_files_only" = "true",
"list_recursively" = "true"

当 list_files_only 和 list_recursively 都设置为 true 时，StarRocks 将执行以下操作

如果指定的 path 是一个文件（无论是专门指定还是用通配符表示），StarRocks 将显示该文件的信息。
如果指定的 path 是一个目录（无论是专门指定还是用通配符表示，以及是否以 / 结尾），StarRocks 将显示此目录下的所有文件和子目录。

有关更多信息，请参阅返回。

SELECT FROM FILES()

与 SELECT 一起使用时，FILES() 将文件中的数据作为表返回。

查询 CSV 文件时，您可以使用 $1、$2 ... 表示 SELECT 语句中的每一列，或者指定 * 以从所有列获取数据。

SELECT * FROM FILES(
    "path" = "s3://inserttest/csv/file1.csv",
    "format" = "csv",
    "csv.column_separator"=",",
    "csv.row_delimiter"="\n",
    "csv.enclose"='"',
    "csv.skip_header"="1",
    "aws.s3.access_key" = "AAAAAAAAAAAAAAAAAAAA",
    "aws.s3.secret_key" = "BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB",
    "aws.s3.region" = "us-west-2"
)
WHERE $1 > 5;
+------+---------+------------+
| $1   | $2      | $3         |
+------+---------+------------+
|    6 | 0.34413 | 2017-11-25 |
|    7 | 0.40055 | 2017-11-26 |
|    8 | 0.42437 | 2017-11-27 |
|    9 | 0.67935 | 2017-11-27 |
|   10 | 0.22783 | 2017-11-29 |
+------+---------+------------+
5 rows in set (0.30 sec)

SELECT $1, $2 FROM FILES(
    "path" = "s3://inserttest/csv/file1.csv",
    "format" = "csv",
    "csv.column_separator"=",",
    "csv.row_delimiter"="\n",
    "csv.enclose"='"',
    "csv.skip_header"="1",
    "aws.s3.access_key" = "AAAAAAAAAAAAAAAAAAAA",
    "aws.s3.secret_key" = "BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB",
    "aws.s3.region" = "us-west-2"
);
+------+---------+
| $1   | $2      |
+------+---------+
|    1 | 0.71173 |
|    2 | 0.16145 |
|    3 | 0.80524 |
|    4 | 0.91852 |
|    5 | 0.37766 |
|    6 | 0.34413 |
|    7 | 0.40055 |
|    8 | 0.42437 |
|    9 | 0.67935 |
|   10 | 0.22783 |
+------+---------+
10 rows in set (0.38 sec)

查询 Parquet 或 ORC 文件时，您可以直接在 SELECT 语句中指定所需列的名称，或者指定 * 以从所有列获取数据。

SELECT * FROM FILES(
    "path" = "s3://inserttest/parquet/file2.parquet",
    "format" = "parquet",
    "aws.s3.access_key" = "AAAAAAAAAAAAAAAAAAAA",
    "aws.s3.secret_key" = "BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB",
    "aws.s3.region" = "us-west-2"
)
WHERE c1 IN (101,105);
+------+------+---------------------+
| c1   | c2   | c3                  |
+------+------+---------------------+
|  101 |    9 | 2018-05-15T18:30:00 |
|  105 |    6 | 2018-05-15T18:30:00 |
+------+------+---------------------+
2 rows in set (0.29 sec)

SELECT c1, c3 FROM FILES(
    "path" = "s3://inserttest/parquet/file2.parquet",
    "format" = "parquet",
    "aws.s3.access_key" = "AAAAAAAAAAAAAAAAAAAA",
    "aws.s3.secret_key" = "BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB",
    "aws.s3.region" = "us-west-2"
);
+------+---------------------+
| c1   | c3                  |
+------+---------------------+
|  101 | 2018-05-15T18:30:00 |
|  102 | 2018-05-15T18:30:00 |
|  103 | 2018-05-15T18:30:00 |
|  104 | 2018-05-15T18:30:00 |
|  105 | 2018-05-15T18:30:00 |
|  106 | 2018-05-15T18:30:00 |
|  107 | 2018-05-15T18:30:00 |
|  108 | 2018-05-15T18:30:00 |
|  109 | 2018-05-15T18:30:00 |
|  110 | 2018-05-15T18:30:00 |
+------+---------------------+
10 rows in set (0.55 sec)

当您查询 list_files_only 设置为 true 的文件时，系统将返回 PATH、SIZE、IS_DIR（给定的路径是否为目录）和 MODIFICATION_TIME。

SELECT * FROM FILES(
    "path" = "s3://bucket/*.parquet",
    "aws.s3.access_key" = "AAAAAAAAAAAAAAAAAAAA",
    "aws.s3.secret_key" = "BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB",
    "list_files_only" = "true"
);
+-----------------------+------+--------+---------------------+
| PATH                  | SIZE | IS_DIR | MODIFICATION_TIME   |
+-----------------------+------+--------+---------------------+
| s3://bucket/1.parquet | 5221 |      0 | 2024-08-15 20:47:02 |
| s3://bucket/2.parquet | 5222 |      0 | 2024-08-15 20:54:57 |
| s3://bucket/3.parquet | 5223 |      0 | 2024-08-20 15:21:00 |
| s3://bucket/4.parquet | 5224 |      0 | 2024-08-15 11:32:14 |
+-----------------------+------+--------+---------------------+
4 rows in set (0.03 sec)

当您查询 list_files_only 和 list_recursively 设置为 true 的文件时，系统将递归地列出文件和目录。

假设路径 s3://bucket/list/ 包含以下文件和子目录

s3://bucket/list/
├── basic1.csv
├── basic2.csv
├── orc0
│   └── orc1
│       └── basic_type.orc
├── orc1
│   └── basic_type.orc
└── parquet
    └── basic_type.parquet

递归地列出文件和目录

SELECT * FROM FILES(
    "path"="s3://bucket/list/",
    "aws.s3.access_key" = "AAAAAAAAAAAAAAAAAAAA",
    "aws.s3.secret_key" = "BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB",
    "list_files_only" = "true", 
    "list_recursively" = "true"
);
+---------------------------------------------+------+--------+---------------------+
| PATH                                        | SIZE | IS_DIR | MODIFICATION_TIME   |
+---------------------------------------------+------+--------+---------------------+
| s3://bucket/list                            |    0 |      1 | 2024-12-24 22:15:59 |
| s3://bucket/list/basic1.csv                 |   52 |      0 | 2024-12-24 11:35:53 |
| s3://bucket/list/basic2.csv                 |   34 |      0 | 2024-12-24 11:35:53 |
| s3://bucket/list/orc0                       |    0 |      1 | 2024-12-24 11:35:53 |
| s3://bucket/list/orc0/orc1                  |    0 |      1 | 2024-12-24 11:35:53 |
| s3://bucket/list/orc0/orc1/basic_type.orc   | 1027 |      0 | 2024-12-24 11:35:53 |
| s3://bucket/list/orc1                       |    0 |      1 | 2024-12-24 22:16:00 |
| s3://bucket/list/orc1/basic_type.orc        | 1027 |      0 | 2024-12-24 22:16:00 |
| s3://bucket/list/parquet                    |    0 |      1 | 2024-12-24 11:35:53 |
| s3://bucket/list/parquet/basic_type.parquet | 2281 |      0 | 2024-12-24 11:35:53 |
+---------------------------------------------+------+--------+---------------------+
10 rows in set (0.04 sec)

以非递归方式列出此路径中与 orc* 匹配的文件和目录

SELECT * FROM FILES(
    "path"="s3://bucket/list/orc*", 
    "list_files_only" = "true", 
    "list_recursively" = "false"
);
+--------------------------------------+------+--------+---------------------+
| PATH                                 | SIZE | IS_DIR | MODIFICATION_TIME   |
+--------------------------------------+------+--------+---------------------+
| s3://bucket/list/orc0/orc1           |    0 |      1 | 2024-12-24 11:35:53 |
| s3://bucket/list/orc1/basic_type.orc | 1027 |      0 | 2024-12-24 22:16:00 |
+--------------------------------------+------+--------+---------------------+
2 rows in set (0.03 sec)

DESC FILES()

与 DESC 一起使用时，FILES() 返回文件的模式。

DESC FILES(
    "path" = "s3://inserttest/lineorder.parquet",
    "format" = "parquet",
    "aws.s3.access_key" = "AAAAAAAAAAAAAAAAAAAA",
    "aws.s3.secret_key" = "BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB",
    "aws.s3.region" = "us-west-2"
);

+------------------+------------------+------+
| Field            | Type             | Null |
+------------------+------------------+------+
| lo_orderkey      | int              | YES  |
| lo_linenumber    | int              | YES  |
| lo_custkey       | int              | YES  |
| lo_partkey       | int              | YES  |
| lo_suppkey       | int              | YES  |
| lo_orderdate     | int              | YES  |
| lo_orderpriority | varchar(1048576) | YES  |
| lo_shippriority  | int              | YES  |
| lo_quantity      | int              | YES  |
| lo_extendedprice | int              | YES  |
| lo_ordtotalprice | int              | YES  |
| lo_discount      | int              | YES  |
| lo_revenue       | int              | YES  |
| lo_supplycost    | int              | YES  |
| lo_tax           | int              | YES  |
| lo_commitdate    | int              | YES  |
| lo_shipmode      | varchar(1048576) | YES  |
+------------------+------------------+------+
17 rows in set (0.05 sec)

当您查看 list_files_only 设置为 true 的文件时，系统将返回 PATH、SIZE、IS_DIR（给定的路径是否为目录）和 MODIFICATION_TIME 的 Type 和 Null 属性。

DESC FILES(
    "path" = "s3://bucket/*.parquet",
    "aws.s3.access_key" = "AAAAAAAAAAAAAAAAAAAA",
    "aws.s3.secret_key" = "BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB",
    "list_files_only" = "true"
);
+-------------------+------------------+------+
| Field             | Type             | Null |
+-------------------+------------------+------+
| PATH              | varchar(1048576) | YES  |
| SIZE              | bigint           | YES  |
| IS_DIR            | boolean          | YES  |
| MODIFICATION_TIME | datetime         | YES  |
+-------------------+------------------+------+
4 rows in set (0.00 sec)

用于卸载的 FILES()

从 v3.2.0 开始，FILES() 支持将数据写入远程存储中的文件。您可以使用 INSERT INTO FILES() 将数据从 StarRocks 卸载到远程存储。

语法

FILES( data_location , data_format [, StorageCredentialParams ] , unload_data_param )

参数

所有参数均为 "key" = "value" 对。

unload_data_param

unload_data_param ::=
    "compression" = { "uncompressed" | "gzip" | "snappy" | "zstd | "lz4" },
    "partition_by" = "<column_name> [, ...]",
    "single" = { "true" | "false" } ,
    "target_max_file_size" = "<int>"

键	必需	描述
compression	是	卸载数据时要使用的压缩方法。有效值 `uncompressed`：不使用压缩算法。 `gzip`：使用 gzip 压缩算法。 `snappy`：使用 SNAPPY 压缩算法。 `zstd`：使用 Zstd 压缩算法。 `lz4`：使用 LZ4 压缩算法。注意卸载到 CSV 文件不支持数据压缩。您必须将此项设置为 `uncompressed`。
partition_by	否	用于将数据文件分区到不同存储路径的列的列表。多个列用逗号 (,) 分隔。 FILES() 提取指定列的键/值信息，并将数据文件存储在具有提取的键/值对的存储路径下。有关更多说明，请参阅示例 7。
single	否	是否将数据卸载到单个文件中。有效值 `true`：数据存储在单个数据文件中。 `false`（默认值）：如果要卸载的数据量超过 512 MB，则数据存储在多个文件中。
target_max_file_size	否	要卸载的批次中每个文件的尽力最大大小。单位：字节。默认值：1073741824 (1 GB)。当要卸载的数据大小超过此值时，数据将被分成多个文件，并且每个文件的大小不会显着超过此值。在 v3.2.7 中引入。

示例

示例 1：从文件查询数据

查询 AWS S3 存储桶 inserttest 中 Parquet 文件 parquet/par-dup.parquet 中的数据

SELECT * FROM FILES(
     "path" = "s3://inserttest/parquet/par-dup.parquet",
     "format" = "parquet",
     "aws.s3.access_key" = "AAAAAAAAAAAAAAAAAAAA",
     "aws.s3.secret_key" = "BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB",
     "aws.s3.region" = "us-west-2"
);
+------+---------------------------------------------------------+
| c1   | c2                                                      |
+------+---------------------------------------------------------+
|    1 | {"1": "key", "1": "1", "111": "1111", "111": "aaaa"}    |
|    2 | {"2": "key", "2": "NULL", "222": "2222", "222": "bbbb"} |
+------+---------------------------------------------------------+
2 rows in set (22.335 sec)

查询 NFS(NAS) 中 Parquet 文件的数据

SELECT * FROM FILES(
  'path' = 'file:///home/ubuntu/parquetfile/*.parquet', 
  'format' = 'parquet'
);

示例 2：从文件插入数据行

将 AWS S3 存储桶 inserttest 中 Parquet 文件 parquet/insert_wiki_edit_append.parquet 中的数据行插入到表 insert_wiki_edit 中

INSERT INTO insert_wiki_edit
    SELECT * FROM FILES(
        "path" = "s3://inserttest/parquet/insert_wiki_edit_append.parquet",
        "format" = "parquet",
        "aws.s3.access_key" = "AAAAAAAAAAAAAAAAAAAA",
        "aws.s3.secret_key" = "BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB",
        "aws.s3.region" = "us-west-2"
);
Query OK, 2 rows affected (23.03 sec)
{'label':'insert_d8d4b2ee-ac5c-11ed-a2cf-4e1110a8f63b', 'status':'VISIBLE', 'txnId':'2440'}

将 NFS(NAS) 中 CSV 文件的数据行插入到表 insert_wiki_edit 中

INSERT INTO insert_wiki_edit
  SELECT * FROM FILES(
    'path' = 'file:///home/ubuntu/csvfile/*.csv', 
    'format' = 'csv', 
    'csv.column_separator' = ',', 
    'csv.row_delimiter' = '\n'
  );

示例 3：使用来自文件的数据行的 CTAS

创建一个名为 ctas_wiki_edit 的表，并将 AWS S3 存储桶 inserttest 中 Parquet 文件 parquet/insert_wiki_edit_append.parquet 中的数据行插入到表中

CREATE TABLE ctas_wiki_edit AS
    SELECT * FROM FILES(
        "path" = "s3://inserttest/parquet/insert_wiki_edit_append.parquet",
        "format" = "parquet",
        "aws.s3.access_key" = "AAAAAAAAAAAAAAAAAAAA",
        "aws.s3.secret_key" = "BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB",
        "aws.s3.region" = "us-west-2"
);
Query OK, 2 rows affected (22.09 sec)
{'label':'insert_1a217d70-2f52-11ee-9e4a-7a563fb695da', 'status':'VISIBLE', 'txnId':'3248'}

示例 4：从文件查询数据并提取其路径中的键/值信息

查询 Parquet 文件 /geo/country=US/city=LA/file1.parquet（仅包含两列 -id 和 user）中的数据，并提取其路径中的键/值信息作为返回的列。

SELECT * FROM FILES(
    "path" = "hdfs://xxx.xx.xxx.xx:9000/geo/country=US/city=LA/file1.parquet",
    "format" = "parquet",
    "hadoop.security.authentication" = "simple",
    "username" = "xxxxx",
    "password" = "xxxxx",
    "columns_from_path" = "country, city"
);
+------+---------+---------+------+
| id   | user    | country | city |
+------+---------+---------+------+
|    1 | richard | US      | LA   |
|    2 | amber   | US      | LA   |
+------+---------+---------+------+
2 rows in set (3.84 sec)

示例 5：自动模式检测和联合

以下示例基于 S3 存储桶中的两个 Parquet 文件

文件 1 包含三列 - INT 列 c1、FLOAT 列 c2 和 DATE 列 c3。

c1,c2,c3
1,0.71173,2017-11-20
2,0.16145,2017-11-21
3,0.80524,2017-11-22
4,0.91852,2017-11-23
5,0.37766,2017-11-24
6,0.34413,2017-11-25
7,0.40055,2017-11-26
8,0.42437,2017-11-27
9,0.67935,2017-11-27
10,0.22783,2017-11-29

文件 2 包含三列 - INT 列 c1、INT 列 c2 和 DATETIME 列 c3。

c1,c2,c3
101,9,2018-05-15T18:30:00
102,3,2018-05-15T18:30:00
103,2,2018-05-15T18:30:00
104,3,2018-05-15T18:30:00
105,6,2018-05-15T18:30:00
106,1,2018-05-15T18:30:00
107,8,2018-05-15T18:30:00
108,5,2018-05-15T18:30:00
109,6,2018-05-15T18:30:00
110,8,2018-05-15T18:30:00

使用 CTAS 语句创建一个名为 test_ctas_parquet 的表，并将两个 Parquet 文件中的数据行插入到表中

CREATE TABLE test_ctas_parquet AS
SELECT * FROM FILES(
    "path" = "s3://inserttest/parquet/*",
    "format" = "parquet",
    "aws.s3.access_key" = "AAAAAAAAAAAAAAAAAAAA",
    "aws.s3.secret_key" = "BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB",
    "aws.s3.region" = "us-west-2"
);

查看 test_ctas_parquet 的表模式

SHOW CREATE TABLE test_ctas_parquet\G

*************************** 1. row ***************************
       Table: test_ctas_parquet
Create Table: CREATE TABLE `test_ctas_parquet` (
  `c1` bigint(20) NULL COMMENT "",
  `c2` decimal(38, 9) NULL COMMENT "",
  `c3` varchar(1048576) NULL COMMENT ""
) ENGINE=OLAP 
DUPLICATE KEY(`c1`, `c2`)
COMMENT "OLAP"
DISTRIBUTED BY RANDOM
PROPERTIES (
"bucket_size" = "4294967296",
"compression" = "LZ4",
"replication_num" = "3"
);

结果表明，包含 FLOAT 和 INT 数据的 c2 列被合并为 DECIMAL 列，包含 DATE 和 DATETIME 数据的 c3 列被合并为 VARCHAR 列。

当 Parquet 文件更改为包含相同数据的 CSV 文件时，上述结果保持不变

CREATE TABLE test_ctas_csv AS
  SELECT * FROM FILES(
    "path" = "s3://inserttest/csv/*",
    "format" = "csv",
    "csv.column_separator"=",",
    "csv.row_delimiter"="\n",
    "csv.enclose"='"',
    "csv.skip_header"="1",
    "aws.s3.access_key" = "AAAAAAAAAAAAAAAAAAAA",
    "aws.s3.secret_key" = "BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB",
    "aws.s3.region" = "us-west-2"
);
Query OK, 0 rows affected (30.90 sec)

SHOW CREATE TABLE test_ctas_csv\G
*************************** 1. row ***************************
       Table: test_ctas_csv
Create Table: CREATE TABLE `test_ctas_csv` (
  `c1` bigint(20) NULL COMMENT "",
  `c2` decimal(38, 9) NULL COMMENT "",
  `c3` varchar(1048576) NULL COMMENT ""
) ENGINE=OLAP 
DUPLICATE KEY(`c1`, `c2`)
COMMENT "OLAP"
DISTRIBUTED BY RANDOM
PROPERTIES (
"bucket_size" = "4294967296",
"compression" = "LZ4",
"replication_num" = "3"
);
1 row in set (0.27 sec)

通过将 fill_mismatch_column_with 设置为 null，统一 Parquet 文件的模式并允许系统为不存在的列分配 NULL 值

SELECT * FROM FILES(
  "path" = "s3://inserttest/basic_type.parquet,s3://inserttest/basic_type_k2k5k7.parquet",
  "format" = "parquet",
  "aws.s3.access_key" = "AAAAAAAAAAAAAAAAAAAA",
  "aws.s3.secret_key" = "BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB",
  "aws.s3.region" = "us-west-2",
  "fill_mismatch_column_with" = "null"
);
+------+------+------+-------+------------+---------------------+------+------+
| k1   | k2   | k3   | k4    | k5         | k6                  | k7   | k8   |
+------+------+------+-------+------------+---------------------+------+------+
| NULL |   21 | NULL |  NULL | 2024-10-03 | NULL                | c    | NULL |
|    0 |    1 |    2 |  3.20 | 2024-10-01 | 2024-10-01 12:12:12 | a    |  4.3 |
|    1 |   11 |   12 | 13.20 | 2024-10-02 | 2024-10-02 13:13:13 | b    | 14.3 |
+------+------+------+-------+------------+---------------------+------+------+
3 rows in set (0.03 sec)

示例 6：查看文件的 Schema

使用 DESC 查看存储在 AWS S3 中的 Parquet 文件 lineorder 的 schema。

DESC FILES(
    "path" = "s3://inserttest/lineorder.parquet",
    "format" = "parquet",
    "aws.s3.access_key" = "AAAAAAAAAAAAAAAAAAAA",
    "aws.s3.secret_key" = "BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB",
    "aws.s3.region" = "us-west-2"
);

+------------------+------------------+------+
| Field            | Type             | Null |
+------------------+------------------+------+
| lo_orderkey      | int              | YES  |
| lo_linenumber    | int              | YES  |
| lo_custkey       | int              | YES  |
| lo_partkey       | int              | YES  |
| lo_suppkey       | int              | YES  |
| lo_orderdate     | int              | YES  |
| lo_orderpriority | varchar(1048576) | YES  |
| lo_shippriority  | int              | YES  |
| lo_quantity      | int              | YES  |
| lo_extendedprice | int              | YES  |
| lo_ordtotalprice | int              | YES  |
| lo_discount      | int              | YES  |
| lo_revenue       | int              | YES  |
| lo_supplycost    | int              | YES  |
| lo_tax           | int              | YES  |
| lo_commitdate    | int              | YES  |
| lo_shipmode      | varchar(1048576) | YES  |
+------------------+------------------+------+
17 rows in set (0.05 sec)

示例 7：卸载数据

将 sales_records 中的所有数据行卸载为 HDFS 集群中路径 /unload/partitioned/ 下的多个 Parquet 文件。这些文件存储在不同的子路径中，这些子路径由 sales_time 列中的值区分。

INSERT INTO FILES(
    "path" = "hdfs://xxx.xx.xxx.xx:9000/unload/partitioned/",
    "format" = "parquet",
    "hadoop.security.authentication" = "simple",
    "username" = "xxxxx",
    "password" = "xxxxx",
    "compression" = "lz4",
    "partition_by" = "sales_time"
)
SELECT * FROM sales_records;

将查询结果卸载到 NFS(NAS) 中的 CSV 和 Parquet 文件中

-- CSV
INSERT INTO FILES(
    'path' = 'file:///home/ubuntu/csvfile/', 
    'format' = 'csv', 
    'csv.column_separator' = ',', 
    'csv.row_delimitor' = '\n'
)
SELECT * FROM sales_records;

-- Parquet
INSERT INTO FILES(
    'path' = 'file:///home/ubuntu/parquetfile/',
    'format' = 'parquet'
)
SELECT * FROM sales_records;

示例 8：Avro 文件

加载 Avro 文件

INSERT INTO avro_tbl
  SELECT * FROM FILES(
    "path" = "hdfs://xxx.xx.xx.x:yyyy/avro/primitive.avro", 
    "format" = "avro"
);

查询 Avro 文件中的数据

SELECT * FROM FILES("path" = "hdfs://xxx.xx.xx.x:yyyy/avro/complex.avro", "format" = "avro")\G
*************************** 1. row ***************************
record_field: {"id":1,"name":"avro"}
  enum_field: HEARTS
 array_field: ["one","two","three"]
   map_field: {"a":1,"b":2}
 union_field: 100
 fixed_field: 0x61626162616261626162616261626162
1 row in set (0.05 sec)

查看 Avro 文件的 schema

DESC FILES("path" = "hdfs://xxx.xx.xx.x:yyyy/avro/logical.avro", "format" = "avro");
+------------------------+------------------+------+
| Field                  | Type             | Null |
+------------------------+------------------+------+
| decimal_bytes          | decimal(10,2)    | YES  |
| decimal_fixed          | decimal(10,2)    | YES  |
| uuid_string            | varchar(1048576) | YES  |
| date                   | date             | YES  |
| time_millis            | int              | YES  |
| time_micros            | bigint           | YES  |
| timestamp_millis       | datetime         | YES  |
| timestamp_micros       | datetime         | YES  |
| local_timestamp_millis | bigint           | YES  |
| local_timestamp_micros | bigint           | YES  |
| duration               | varbinary(12)    | YES  |
+------------------------+------------------+------+

示例 9：使用托管身份和服务主体访问 Azure Blob Storage

-- Managed Identity
SELECT * FROM FILES(
    "path" = "wasbs://storage-container@storage-account.blob.core.windows.net/ssb_1g/customer/*",
    "format" = "parquet",
    "azure.blob.oauth2_use_managed_identity" = "true",
    "azure.blob.oauth2_client_id" = "1d6bfdec-dd34-4260-b8fd-aaaaaaaaaaaa"
);
-- Service Principal
SELECT * FROM FILES(
    "path" = "wasbs://storage-container@storage-account.blob.core.windows.net/ssb_1g/customer/*",
    "format" = "parquet",
    "azure.blob.oauth2_client_id" = "1d6bfdec-dd34-4260-b8fd-bbbbbbbbbbbb",
    "azure.blob.oauth2_client_secret" = "C2M8Q~ZXXXXXX_5XsbDCeL2dqP7hIR60xxxxxxxx",
    "azure.blob.oauth2_tenant_id" = "540e19cc-386b-4a44-a7b8-cccccccccccc"
);

示例 10：CSV 文件

查询 CSV 文件中的数据

SELECT * FROM FILES(                                                                                                                                                     "path" = "s3://test-bucket/file1.csv",
    "format" = "csv",
    "csv.column_separator"=",",
    "csv.row_delimiter"="\r\n",
    "csv.enclose"='"',
    "csv.skip_header"="1",
    "aws.s3.access_key" = "AAAAAAAAAAAAAAAAAAAA",
    "aws.s3.secret_key" = "BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB",
    "aws.s3.region" = "us-west-2"
);
+------+---------+--------------+
| $1   | $2      | $3           |
+------+---------+--------------+
|    1 | 0.71173 | 2017-11-20   |
|    2 | 0.16145 | 2017-11-21   |
|    3 | 0.80524 | 2017-11-22   |
|    4 | 0.91852 | 2017-11-23   |
|    5 | 0.37766 | 2017-11-24   |
|    6 | 0.34413 | 2017-11-25   |
|    7 | 0.40055 | 2017-11-26   |
|    8 | 0.42437 | 2017-11-27   |
|    9 | 0.67935 | 2017-11-27   |
|   10 | 0.22783 | 2017-11-29   |
+------+---------+--------------+
10 rows in set (0.33 sec)

加载 CSV 文件

INSERT INTO csv_tbl
  SELECT * FROM FILES(
    "path" = "s3://test-bucket/file1.csv",
    "format" = "csv",
    "csv.column_separator"=",",
    "csv.row_delimiter"="\r\n",
    "csv.enclose"='"',
    "csv.skip_header"="1",
    "aws.s3.access_key" = "AAAAAAAAAAAAAAAAAAAA",
    "aws.s3.secret_key" = "BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB",
    "aws.s3.region" = "us-west-2"
);

用于加载的 FILES()​

语法​

参数​

data_location​

data_format​

Parquet​

parquet.use_legacy_encoding​

CSV​

csv.column_separator​

csv.enclose​

csv.skip_header​

csv.escape​

schema_detect​

下推目标表模式检查​

联合具有不同模式的文件​

从 Parquet 推断 STRUCT 类型​

StorageCredentialParams​

HDFS​

AWS S3​

Google GCS​

Azure Blob Storage​

Azure Data Lake Storage Gen2​

Azure Data Lake Storage Gen1​

其他 S3 兼容存储系统​

columns_from_path​

list_files_only​

list_recursively​

返回​

SELECT FROM FILES()​

DESC FILES()​

用于卸载的 FILES()​

语法​

参数​

data_location​

data_format​

StorageCredentialParams​

unload_data_param​

示例​

示例 1：从文件查询数据​

示例 2：从文件插入数据行​

示例 3：使用来自文件的数据行的 CTAS​

示例 4：从文件查询数据并提取其路径中的键/值信息​

示例 5：自动模式检测和联合​

示例 6：查看文件的 Schema​

示例 7：卸载数据​

示例 8：Avro 文件​

示例 9：使用托管身份和服务主体访问 Azure Blob Storage​

示例 10：CSV 文件​

您觉得这篇文档怎么样？

用于加载的 FILES()

语法

参数

data_location

data_format

Parquet

parquet.use_legacy_encoding

CSV

csv.column_separator

csv.enclose

csv.skip_header

csv.escape

schema_detect

下推目标表模式检查

联合具有不同模式的文件

从 Parquet 推断 STRUCT 类型

StorageCredentialParams

HDFS

AWS S3

Google GCS

Azure Blob Storage

Azure Data Lake Storage Gen2

Azure Data Lake Storage Gen1

其他 S3 兼容存储系统

columns_from_path

list_files_only

list_recursively

返回

SELECT FROM FILES()

DESC FILES()

用于卸载的 FILES()

语法

参数

data_location

data_format

StorageCredentialParams

unload_data_param

示例

示例 1：从文件查询数据

示例 2：从文件插入数据行

示例 3：使用来自文件的数据行的 CTAS

示例 4：从文件查询数据并提取其路径中的键/值信息

示例 5：自动模式检测和联合

示例 6：查看文件的 Schema

示例 7：卸载数据

示例 8：Avro 文件

示例 9：使用托管身份和服务主体访问 Azure Blob Storage

示例 10：CSV 文件