版本: 最新版本-3.5

File 外部表

文件外部表是一种特殊的外部表。它允许您直接查询外部存储系统中的 Parquet 和 ORC 数据文件，而无需将数据加载到 StarRocks 中。此外，文件外部表不依赖于 Metastore。在当前版本中，StarRocks 支持以下外部存储系统：HDFS、Amazon S3 和其他 S3 兼容的存储系统。

此功能自 StarRocks v2.5 起支持。

注意

从 v3.1 开始，StarRocks 支持使用 INSERT 命令和 FILES 函数直接从云存储上的文件加载数据，因此您无需先创建外部 Catalog 或文件外部表。此外，FILES() 可以自动推断文件的表 Schema，大大简化了数据加载过程。
文件外部表功能旨在帮助将数据加载到 StarRocks 中，而不是作为一种常规操作来针对外部系统执行高效的查询。更高效的解决方案是将数据加载到 StarRocks 中。

限制

文件外部表必须在 default_catalog 中的数据库中创建。您可以运行 SHOW CATALOGS 来查询集群中创建的 Catalog。
仅支持 Parquet、ORC、Avro、RCFile 和 SequenceFile 数据文件。
您只能使用文件外部表来查询目标数据文件中的数据。不支持诸如 INSERT、DELETE 和 DROP 等数据写入操作。

前提条件

在创建文件外部表之前，您必须配置 StarRocks 集群，以便 StarRocks 可以访问存储目标数据文件的外部存储系统。文件外部表所需的配置与 Hive Catalog 所需的配置相同，只是您无需配置 Metastore。有关配置的更多信息，请参见 Hive Catalog - 集成准备。

创建数据库（可选）

连接到 StarRocks 集群后，您可以在现有数据库中创建文件外部表，也可以创建一个新数据库来管理文件外部表。要查询集群中的现有数据库，请运行 SHOW DATABASES。然后，您可以运行 USE <db_name> 以切换到目标数据库。

创建数据库的语法如下。

CREATE DATABASE [IF NOT EXISTS] <db_name>

创建文件外部表

访问目标数据库后，您可以在此数据库中创建文件外部表。

语法

CREATE EXTERNAL TABLE <table_name>
(
    <col_name> <col_type> [NULL | NOT NULL] [COMMENT "<comment>"]
) 
ENGINE=file
COMMENT ["comment"]
PROPERTIES
(
    FileLayoutParams,
    StorageCredentialParams
)

参数

参数	必需	描述
table_name	是	文件外部表的名称。命名约定如下该名称可以包含字母、数字 (0-9) 和下划线 (_)。它必须以字母开头。名称的长度不能超过 64 个字符。
col_name	是	文件外部表中的列名。文件外部表中的列名必须与目标数据文件中的列名相同，但不区分大小写。文件外部表中的列的顺序可以与目标数据文件中的顺序不同。
col_type	是	文件外部表中的列类型。您需要根据目标数据文件中的列类型指定此参数。有关更多信息，请参见列类型映射。
NULL \| NOT NULL	否	是否允许文件外部表中的列为 NULL。 NULL：允许 NULL。 NOT NULL：不允许 NULL。您必须根据以下规则指定此修饰符如果未为目标数据文件中的列指定此参数，则您可以选择不为文件外部表中的列指定它，或者为文件外部表中的列指定 NULL。如果为目标数据文件中的列指定了 NULL，则您可以选择不为文件外部表中的列指定此参数，或者为文件外部表中的列指定 NULL。如果为目标数据文件中的列指定了 NOT NULL，则您还必须为文件外部表中的列指定 NOT NULL。
comment	否	文件外部表中列的注释。
ENGINE	是	引擎的类型。将值设置为 file。
comment	否	文件外部表的描述。
PROPERTIES	是	`FileLayoutParams`：指定目标文件的路径和格式。此属性是必需的。 `StorageCredentialParams`：指定访问对象存储系统所需的身份验证信息。此属性仅对于 AWS S3 和其他 S3 兼容的存储系统是必需的。

FileLayoutParams

用于访问目标数据文件的一组参数。

"path" = "<file_path>",
"format" = "<file_format>"
"enable_recursive_listing" = "{ true | false }"
"enable_wildcards" = "{ true | false }"

参数	必需	描述
path	是	数据文件的路径。如果数据文件存储在 HDFS 中，则路径格式为 `hdfs://<HDFS 的 IP 地址>:<端口号>/<路径>`。默认端口号为 8020。如果您使用默认端口，则无需指定它。如果数据文件存储在 AWS S3 或其他 S3 兼容的存储系统中，则路径格式为 `s3://<存储桶名称>/<文件夹>/`。输入路径时请注意以下规则如果要访问路径中的所有文件，请使用斜杠 (`/`) 结束此参数，例如 `hdfs://x.x.x.x/user/hive/warehouse/array2d_parq/data/`。当您运行查询时，StarRocks 会遍历路径下的所有数据文件。它不使用递归来遍历数据文件。如果要访问单个文件，请输入直接指向此文件的路径，例如 `hdfs://x.x.x.x/user/hive/warehouse/array2d_parq/data`。当您运行查询时，StarRocks 仅扫描此数据文件。
format	是	数据文件的格式。有效值：`parquet`、`orc`、`avro`、`rctext` 或 `rcbinary` 和 `sequence`。
enable_recursive_listing	否	指定是否递归遍历当前路径下的所有文件。默认值：`true`。值 `true` 指定递归列出子目录，值 `false` 指定忽略子目录。
enable_wildcards	否	是否支持在 `path` 中使用通配符 (``)。默认值：`false`。例如，`2024-07-` 是匹配所有具有 `2024-07-` 前缀的文件。此参数自 v3.1.9 起受支持。

StorageCredentialParams（可选）

一组关于 StarRocks 如何与目标存储系统集成的参数。此参数集是可选的。

仅当目标存储系统是 AWS S3 或其他 S3 兼容的存储时，才需要配置 StorageCredentialParams。

对于其他存储系统，您可以忽略 StorageCredentialParams。

AWS S3

如果您需要访问存储在 AWS S3 中的数据文件，请在 StorageCredentialParams 中配置以下身份验证参数。

如果您选择基于实例配置文件的身份验证方法，请按如下方式配置 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" = "<ARN of your assumed role>",
"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>"

参数名	必需	描述
aws.s3.use_instance_profile	是	指定访问 AWS S3 时是否启用基于实例配置文件的身份验证方法和基于承担角色的身份验证方法。有效值：`true` 和 `false`。默认值：`false`。
aws.s3.iam_role_arn	是	具有您的 AWS S3 存储桶权限的 IAM 角色的 ARN。如果您使用基于承担角色的身份验证方法来访问 AWS S3，则必须指定此参数。然后，StarRocks 在访问目标数据文件时将承担此角色。
aws.s3.region	是	您的 AWS S3 存储桶所在的区域。示例：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 的身份验证参数。

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	是	指定是否启用 path-style 访问。有效值：`true` 和 `false`。默认值：`false`。对于 MinIO，您必须将值设置为 `true`。路径样式的 URL 使用以下格式：`https://s3.<region_code>.amazonaws.com/<bucket_name>/<key_name>`。例如，如果您在美国西部（俄勒冈）区域中创建一个名为 `DOC-EXAMPLE-BUCKET1` 的存储桶，并且想要访问该存储桶中的 `alice.jpg` 对象，则可以使用以下路径样式的 URL：`https://s3.us-west-2.amazonaws.com/DOC-EXAMPLE-BUCKET1/alice.jpg`。
aws.s3.endpoint	是	用于连接到 S3 兼容的存储系统而不是 AWS S3 的端点。
aws.s3.access_key	是	您的 IAM 用户的访问密钥。
aws.s3.secret_key	是	您的 IAM 用户的密钥。

列类型映射

下表提供了目标数据文件和文件外部表之间的列类型映射。

数据文件	File 外部表
INT/INTEGER	INT
BIGINT	BIGINT
TIMESTAMP	DATETIME。请注意，TIMESTAMP 根据当前会话的时区设置转换为不带时区的 DATETIME，并且会损失一些精度。
STRING	STRING
VARCHAR	VARCHAR
CHAR	CHAR
DOUBLE	DOUBLE
FLOAT	FLOAT
DECIMAL	DECIMAL
BOOLEAN	BOOLEAN
ARRAY	ARRAY
MAP	MAP
STRUCT	STRUCT

示例

HDFS

创建一个名为 t0 的文件外部表，以查询存储在 HDFS 路径中的 Parquet 数据文件。

USE db_example;

CREATE EXTERNAL TABLE t0
(
    name string, 
    id int
) 
ENGINE=file
PROPERTIES 
(
    "path"="hdfs://x.x.x.x:8020/user/hive/warehouse/person_parq/", 
    "format"="parquet"
);

AWS S3

示例 1：创建一个文件外部表，并使用实例配置文件访问 AWS S3 中的单个 Parquet 文件。

USE db_example;

CREATE EXTERNAL TABLE table_1
(
    name string, 
    id int
) 
ENGINE=file
PROPERTIES 
(
    "path" = "s3://bucket-test/folder1/raw_0.parquet", 
    "format" = "parquet",
    "aws.s3.use_instance_profile" = "true",
    "aws.s3.region" = "us-west-2" 
);

示例 2：创建一个文件外部表，并使用承担角色访问 AWS S3 中目标文件路径下的所有 ORC 文件。

USE db_example;

CREATE EXTERNAL TABLE table_1
(
    name string, 
    id int
) 
ENGINE=file
PROPERTIES 
(
    "path" = "s3://bucket-test/folder1/", 
    "format" = "orc",
    "aws.s3.use_instance_profile" = "true",
    "aws.s3.iam_role_arn" = "arn:aws:iam::51234343412:role/role_name_in_aws_iam",
    "aws.s3.region" = "us-west-2" 
);

示例 3：创建一个文件外部表，并使用 IAM 用户访问 AWS S3 中文件路径下的所有 ORC 文件。

USE db_example;

CREATE EXTERNAL TABLE table_1
(
    name string, 
    id int
) 
ENGINE=file
PROPERTIES 
(
    "path" = "s3://bucket-test/folder1/", 
    "format" = "orc",
    "aws.s3.use_instance_profile" = "false",
    "aws.s3.access_key" = "<iam_user_access_key>",
    "aws.s3.secret_key" = "<iam_user_access_key>",
    "aws.s3.region" = "us-west-2" 
);

查询文件外部表

语法

SELECT <clause> FROM <file_external_table>

例如，要从示例 - HDFS 中创建的文件外部表 t0 中查询数据，请运行以下命令

SELECT * FROM t0;

+--------+------+
| name   | id   |
+--------+------+
| jack   |    2 |
| lily   |    1 |
+--------+------+
2 rows in set (0.08 sec)

管理文件外部表

您可以使用 DESC 查看表的 Schema，或使用 DROP TABLE 删除表。

限制​

前提条件​

创建数据库（可选）​

创建文件外部表​

语法​

参数​

FileLayoutParams​

StorageCredentialParams（可选）​

AWS S3​

S3 兼容的存储​

列类型映射​

示例​

HDFS​

AWS S3​

查询文件外部表​

管理文件外部表​

您觉得这篇文档怎么样？

限制

前提条件

创建数据库（可选）

创建文件外部表

语法

参数

FileLayoutParams

StorageCredentialParams（可选）

AWS S3

S3 兼容的存储

列类型映射

示例

HDFS

AWS S3

查询文件外部表

管理文件外部表