版本: 最新版本-3.5

MaxCompute Catalog

Beta 功能

Beta 功能使用建议

StarRocks 从 v3.3 版本开始支持阿里云 MaxCompute（原 ODPS）Catalog。

MaxCompute Catalog 是一种外部 Catalog，可以让您无需导入数据即可查询 MaxCompute 中的数据。

借助 MaxCompute Catalog，您还可以使用 INSERT INTO 直接转换和加载来自 MaxCompute 的数据。

使用说明

您只能使用 MaxCompute Catalog 查询 MaxCompute 中的数据。您不能使用 MaxCompute Catalog 来删除或插入数据到您的 MaxCompute 集群中。

集成准备

在创建 MaxCompute Catalog 之前，请确保您的 StarRocks 集群可以正确访问您的 MaxCompute 服务。

创建 MaxCompute Catalog

语法

CREATE EXTERNAL CATALOG <catalog_name>
[COMMENT <comment>]
PROPERTIES
(
    "type" = "odps",
    CatalogParams,
    ScanParams,
    CachingMetaParams
)

参数

catalog_name

MaxCompute Catalog 的名称。命名规范如下：

该名称可以包含字母、数字 (0-9) 和下划线 (_)。它必须以字母开头。
该名称区分大小写，长度不能超过 1023 个字符。

comment

MaxCompute Catalog 的描述。此参数是可选的。

type

数据源的类型。设置为 odps。

CatalogParams

一组关于 StarRocks 如何访问 MaxCompute 集群元数据的参数。

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

参数	必需	描述
odps.endpoint	是	MaxCompute 服务的连接地址（即 endpoint）。您需要根据创建 MaxCompute 项目时选择的区域以及网络连接模式配置 endpoint。有关不同区域和网络连接模式下使用的 endpoint 的详细信息，请参见 Endpoint。请注意，目前仅支持阿里云的两种网络连接模式以提供最佳体验：VPC 和经典网络。
odps.project	是	您要访问的 MaxCompute 项目的名称。如果您已创建标准模式工作空间，请注意在配置此参数时生产环境和开发环境 (_dev) 的项目名称之间的差异。您可以登录到 MaxCompute 控制台，并在工作空间 > 项目管理页面上获取 MaxCompute 项目名称。
odps.access.id	是	阿里云账户或 RAM 用户的 AccessKey ID。您可以进入 AccessKey 管理页面获取 AccessKey ID。
odps.access.key	是	与 AccessKey ID 匹配的 AccessKey Secret。您可以进入 AccessKey 管理页面获取 AccessKey Secret。
odps.tunnel.endpoint	否	Tunnel 服务的公网访问链接。如果您尚未配置 Tunnel endpoint，Tunnel 将自动路由到与 MaxCompute 服务所在的网络匹配的 Tunnel endpoint。如果您已配置 Tunnel endpoint，则将按配置使用，不会自动路由。
odps.tunnel.quota	是	用于访问 MaxCompute 的配额名称。MaxCompute 为数据传输提供两种类型的资源：MaxCompute Tunnel 独占资源组（订阅）和存储 API（按需付费）。您可以执行以下操作来获取基于资源类型的配额名称。 MaxCompute Tunnel 独占资源组：登录到 MaxCompute 控制台。在顶部导航栏中，选择一个区域。在左侧导航窗格中，选择工作空间 > 配额以查看可用配额。有关更多信息，请参见在 MaxCompute 控制台中管理计算资源配额。存储 API：登录到 MaxCompute 控制台。在左侧导航窗格中，选择租户 > 租户属性。在租户页面上，打开存储 API 开关。有关更多信息，请参见使用存储 API（按需付费）。存储 API 的默认名称是 "pay-as-you-go"。

ScanParams

一组关于 StarRocks 如何访问存储在 MaxCompute 集群中的文件的参数。此参数集是可选的。

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

参数	必需	描述
odps.split.policy	否	数据扫描时使用的分片策略。有效值：`size`（按数据大小分片）和 `row_offset`（按行数分片）。默认值：`size`。
odps.split.row.count	否	当 `odps.split.policy` 设置为 `row_offset` 时，每个分片的最大行数。默认值：`4 * 1024 * 1024 = 4194304`。

CachingMetaParams

一组关于 StarRocks 如何缓存 Hive 元数据的参数。此参数集是可选的。

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

参数	必需	描述
odps.cache.table.enable	否	指定 StarRocks 是否缓存 MaxCompute 表的元数据。有效值：`true` 和 `false`。默认值：`true`。值 `true` 启用缓存，值 `false` 禁用缓存。
odps.cache.table.expire	否	StarRocks 自动驱逐 MaxCompute 表或分区的缓存元数据的时间间隔，以秒为单位。默认值：`86400`（24 小时）。
odps.cache.table.size	否	StarRocks 缓存的 MaxCompute 表元数据条目的数量。默认值：`1000`。
odps.cache.partition.enable	否	指定 StarRocks 是否缓存 MaxCompute 表的所有分区的元数据。有效值：`true` 和 `false`。默认值：`true`。值 `true` 启用缓存，值 `false` 禁用缓存。
odps.cache.partition.expire	否	StarRocks 自动驱逐 MaxCompute 表的所有分区的缓存元数据的时间间隔，以秒为单位。默认值：`86400`（24 小时）。
odps.cache.partition.size	否	StarRocks 为其缓存所有分区元数据的 MaxCompute 表的数量。默认值：`1000`。
odps.cache.table-name.enable	否	指定 StarRocks 是否缓存来自 MaxCompute 项目的表的信息。有效值：`true` 和 `false`。默认值：`false`。值 `true` 启用缓存，值 `false` 禁用缓存。
odps.cache.table-name.expire	否	StarRocks 自动驱逐来自 MaxCompute 项目的表的缓存信息的时间间隔，以秒为单位。默认值：`86400`（24 小时）。
odps.cache.table-name.size	否	StarRocks 缓存的 MaxCompute 项目的数量。默认值：`1000`。

示例

以下示例创建了一个名为 odps_catalog 的 MaxCompute Catalog，它使用 odps_project 作为仓库项目。

CREATE EXTERNAL CATALOG odps_catalog 
PROPERTIES (
   "type"="odps",
   "odps.access.id"="<maxcompute_user_access_id>",
   "odps.access.key"="<maxcompute_user_access_key>",
   "odps.endpoint"="<maxcompute_server_endpoint>",
   "odps.project"="odps_project"
);

查看 MaxCompute Catalog

您可以使用 SHOW CATALOGS 查询当前 StarRocks 集群中的所有 Catalog

SHOW CATALOGS;

您还可以使用 SHOW CREATE CATALOG 查询外部 Catalog 的创建语句。以下示例查询名为 odps_catalog 的 MaxCompute Catalog 的创建语句。

SHOW CREATE CATALOG odps_catalog;

删除 MaxCompute Catalog

您可以使用 DROP CATALOG 删除外部 Catalog。

以下示例删除了名为 odps_catalog 的 MaxCompute Catalog。

DROP CATALOG odps_catalog;

查看 MaxCompute 表的 Schema

您可以使用以下语法之一来查看 MaxCompute 表的 Schema

查看 Schema

DESC[RIBE] <catalog_name>.<database_name>.<table_name>;

从 CREATE 语句中查看 Schema 和 Location

SHOW CREATE TABLE <catalog_name>.<database_name>.<table_name>;

查询 MaxCompute 表

使用 SHOW DATABASES 查看 MaxCompute 集群中的数据库
```
SHOW DATABASES FROM <catalog_name>;
```
使用 SET CATALOG 切换到当前会话中的目标 Catalog
```
SET CATALOG <catalog_name>;
```
然后，使用 USE 指定当前会话中的活动数据库
```
USE <db_name>;
```
或者，您可以使用 USE 直接指定目标 Catalog 中的活动数据库
```
USE <catalog_name>.<db_name>;
```

使用 SELECT 查询指定数据库中的目标表

SELECT count(*) FROM <table_name> LIMIT 10;

从 MaxCompute 加载数据

假设您的 StarRocks 集群中有一个名为 olap_tbl 的 OLAP 表，并且您的 MaxCompute 集群中有一个名为 mc_table 的表。您可以像下面这样将 MaxCompute 表 mc_table 中的数据转换并加载到 StarRocks 表 olap_tbl 中

INSERT INTO default_catalog.olap_db.olap_tbl SELECT * FROM mc_table;

数据类型映射

MaxCompute Catalog 将 MaxCompute 数据类型映射到 StarRocks 数据类型。下表显示了 MaxCompute 数据类型到 StarRocks 数据类型之间的映射。

MaxCompute 数据类型	StarRocks 数据类型
BOOLEAN	BOOLEAN
TINYINT	TINYINT
SMALLINT	SMALLINT
INT	INT
BIGINT	BIGINT
FLOAT	FLOAT
DOUBLE	DOUBLE
DECIMAL(p, s)	DECIMAL(p, s)
STRING	VARCHAR(1073741824)
VARCHAR(n)	VARCHAR(n)
CHAR(n)	CHAR(n)
JSON	VARCHAR(1073741824)
BINARY	VARBINARY
DATE	DATE
DATETIME	DATETIME
TIMESTAMP	DATETIME
ARRAY	ARRAY
MAP	MAP
STRUCT	STRUCT

注意

由于 StarRocks 中的类型转换，TIMESTAMP 类型将失去精度。

收集 CBO 统计信息

在当前版本中，MaxCompute Catalog 无法自动收集 MaxCompute 表的 CBO 统计信息，因此优化器可能无法生成最佳查询计划。因此，手动扫描 MaxCompute 表的 CBO 统计信息并将其导入到 StarRocks 中可以有效地加快查询速度。

假设您的 MaxCompute 集群中有一个名为 mc_table 的 MaxCompute 表。您可以使用 ANALYZE TABLE 创建手动收集 CBO 统计信息的任务

ANALYZE TABLE mc_table;

手动更新元数据缓存

默认情况下，StarRocks 缓存 MaxCompute 的元数据以提高查询性能。因此，在对 MaxCompute 表进行 Schema 更改或其他更新后，您可以使用 REFRESH EXTERNAL TABLE 手动更新表的元数据，从而确保 StarRocks 可以及时获取最新的元数据

REFRESH EXTERNAL TABLE <table_name> [PARTITION ('partition_name', ...)]

使用说明​

集成准备​

创建 MaxCompute Catalog​

语法​

参数​

catalog_name​

comment​

type​

CatalogParams​

ScanParams​

CachingMetaParams​

示例​

查看 MaxCompute Catalog​

删除 MaxCompute Catalog​

查看 MaxCompute 表的 Schema​

查询 MaxCompute 表​

从 MaxCompute 加载数据​

数据类型映射​

收集 CBO 统计信息​

手动更新元数据缓存​

您觉得这篇文档怎么样？