StarRocks Connector

背景信息

StarRocks是新一代极速全场景MPP (Massively Parallel Processing) 数据库，可以满足企业级用户的多种分析需求，包括OLAP (Online Analytical Processing) 多维分析、定制报表、实时数据分析和Ad-hoc数据分析等。关于StarRocks详情，请参见StarRocks简介。StarRocks支持Catalog（数据目录）功能，实现在一套系统内同时维护内、外部数据，方便您轻松访问并查询存储在各类外部源的数据，详情请参见Catalog概述。

前提条件

已部署V3.2.3及以上版本StarRocks集群，且确保StarRocks集群能够正常访问MaxCompute服务。关于如何部署StarRocks集群操作，详情请参见使用Docker Compose部署StarRocks存算一体集群。

使用限制

• 支持读取分区表、聚簇表、物化视图，不支持读取MaxCompute的Delta Table、外部表、逻辑视图。

• 不支持读JSON数据类型。

• 仅支持未开启Schema的MaxCompute项目。关于Schema详情，请参见Schema操作。

创建MaxCompute Catalog

登录StarRocks并在StarRocks中创建MaxCompute Catalog。关于External Catalog详情，请参见Create External Catalog。

语法

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

参数说明

• 公共参数

  参数	是否必填	说明
  catalog_name	是	MaxCompute Catalog的名称。命名规则如下： 必须由字母 (a~z 或 A~Z)、数字 (0~9) 或下划线 (_) 组成，且只能以字母开头。 总长度不能超过1023个字符。 Catalog名称大小写敏感。
  type	是	数据源的类型，需设置为odps。
  comment	否	MaxCompute Catalog的描述。
  CatalogParams	是	StarRocks访问MaxCompute的相关参数。
  ScanParams	否	StarRocks访问MaxCompute文件存储的相关参数。
  CachingMetaParams	否	指定缓存元数据缓存策略的相关参数。

• CatalogParams相关参数

  参数	是否必填	说明
  odps.endpoint	是	MaxCompute服务的连接地址。您需要根据创建MaxCompute项目时选择的地域以及网络连接方式配置Endpoint。各地域及网络对应的Endpoint值，请参见Endpoint。 说明 当前仅支持使用阿里云VPC网络。
  odps.project	是	MaxCompute项目名称。您可以登录MaxCompute控制台，在工作区 > 项目管理页面获取MaxCompute项目名称。 说明 如果您创建了标准模式的工作空间，在配置此参数时，请注意区分生产环境与开发环境（_dev）的项目名称。
  odps.access.id	是	阿里云账号或RAM用户的AccessKey ID。您可以进入AccessKey管理页面获取AccessKey ID。
  odps.access.key	是	AccessKey ID对应的AccessKey Secret。
  odps.tunnel.quota	是	访问MaxCompute使用的Quota名称。访问MaxCompute支持独享数据传输服务资源组（包年包月）和开放存储（按量计费）两种资源，获取Quota名称的方式分别如下： 独享数据传输服务资源组：登录MaxCompute控制台，左上角切换地域后，在左侧导航栏选择工作区>配额（Quota）管理，查看可使用的Quota列表。具体操作，请参见计算资源-Quota管理。 开放存储：登录MaxCompute控制台，在左侧导航栏选择租户管理>租户属性，开启开放存储并进行授权操作。具体操作，请参见使用开放存储（按量付费）。 开放存储资源名称默认为pay-as-you-go。

• ScanParams相关参数

  参数	是否必填	说明
  odps.split.policy	否	扫描数据时所使用的分片策略。取值说明如下： size（默认值）：按数据大小进行分片，默认值：256MB。 row_offset：按行数进行分片。 说明 分片策略对计算引擎的数据扫描并发度有重要影响，如果默认策略不满足需求，可选择row_offset策略结合odps.split.row.count参数自行调整。
  odps.split.row.count	否	每个分片的最大行数，默认值：4194304，取值范围：大于0。 说明 仅当odps.split.policy参数为row_offset时需配置此参数。

• CachingMetaParams相关参数

  参数	是否必填	说明
  odps.cache.table.enable	否	是否缓存表的元数据。取值说明如下： true（默认值）：开启缓存表的元数据，有助于提升元数据的检索和更新速度，适用于频繁进行DDL操作、大型多用户环境以及需要进行复杂查询优化的场景。 false：关闭缓存表的元数据，由于缓存资源有限，且过度依赖缓存可能导致内存资源过度消耗，对于非高频查询或表元数据经常变化的场景可关闭缓存。
  odps.cache.table.expire	否	自动淘汰缓存的表元数据的时间间隔，单位：秒（s）。默认值：86400，即24小时，取值范围：大于等于0。
  odps.cache.table.size	否	缓存表元数据的数量。默认值：1000。
  odps.cache.partition.enable	否	是否缓存目标表下所有分区的元数据。取值说明如下： true（默认值）：开启缓存目标表下所有分区的元数据。 false：关闭缓存，所有分区的元数据均不缓存。 说明 若非分区表配置odps.cache.partition.enable参数将不生效。
  odps.cache.partition.expire	否	自动淘汰缓存所有分区元数据的时间间隔，单位：秒（s）。默认值：86400，即24小时，取值范围：大于等于0。
  odps.cache.partition.size	否	可缓存的分区表的数量。默认值：1000。
  odps.cache.table-name.enable	否	是否缓存MaxCompute项目下所有表名称。取值说明如下： true：开启缓存MaxCompute项目下所有表名称。 false（默认值）：关闭缓存，不进行MaxCompute项目下所有表名称的缓存。
  odps.cache.table-name.expire	否	自动淘汰缓存MaxCompute项目中表信息数据的时间间隔，单位：秒（s）。默认值：86400，即24小时，取值范围：大于等于0。

示例

以下示例演示创建一个名为odps_catalog的MaxCompute Catalog，其中以MaxCompute项目mf_mc_bj为例。

-- 创建catalog
CREATE EXTERNAL CATALOG odps_catalog PROPERTIES(
    "type"="odps",
    "odps.access.id"="LTAI5tRzd4W8cTyLZKT****",
    "odps.access.key"="gJwKaF3hK9MDAQgbO0zsHCz****",
    "odps.endpoint"="http://service.cn-beijing.maxcompute.aliyun.com/api",
    "odps.tunnel.quota"="pay-as-you-go",
    "odps.project"="mf_mc_bj"
);

访问MaxCompute

1. 切换到目标Catalog和MaxCompute项目。本文以odps_catalog和mf_mc_bj为例。

   • 语法

     • 方式一

       --指定Catalog
       SET CATALOG <catalog_name>;
       --指定MaxCompute项目
       USE <project_name>;

     • 方式二

       USE <catalog_name>.<project_name>;

   • 示例

     SET CATALOG odps_catalog;
     USE mf_mc_bj;

2. 查询数据。本文以src表为例。

SELECT COUNT(*) FROM src LIMIT 10;

返回结果如下。

+------+-------+
| key  | value |
+------+-------+
| 1    | 1     |
| 3    | 3     |
| 2    | 2     |
| 4    | 100   |
| 5    | 200   |
| 6    | 300   |
| 3    | 400   |
+------+-------+

其他操作

查看MaxCompute Catalog

• 查询当前所在StarRocks集群中所有Catalog。

  SHOW CATALOGS;

  返回结果如下。

  +-----------------+----------+------------------------------------------------------------------+
  | Catalog         | Type     | Comment                                                          |
  +-----------------+----------+------------------------------------------------------------------+
  | default_catalog | Internal | An internal catalog contains this cluster‘s self-managed tables. |
  | odps_catalog    | Odps     | NULL                                                             |
  +-----------------+----------+------------------------------------------------------------------+

• 查询指定Catalog对应的创建语句。

  SHOW CREATE CATALOG odps_catalog;

  返回结果如下。

  +--------------+--------------------------------------------------------------------------+
  | Catalog      | Create Catalog                                                           |
  +--------------+--------------------------------------------------------------------------+
  | odps_catalog | CREATE EXTERNAL CATALOG `odps_catalog`
                   PROPERTIES ("odps.endpoint"  =  "http://service.cn-beijing.maxcompute.aliyun.com/api",
                   "odps.access.id"  =  "LT******Kb",
                   "odps.access.key"  =  "gJ******CB",
                   "odps.project"  =  "odps_project",
                   "type"  =  "odps"
                  )|
  +-----------------------------------------------------------------------------------------+

查看MaxCompute表结构

• 查询MaxCompute表结构。

  • 语法

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

  • 参数说明

    • catalog_name：必填，Catalog名称。

    • database_name：必填，目标Catalog下的MaxCompute项目名称。

    • table_name：必填，目标MaxCompute项目下的表名称。

  • 示例

    DESC odps_catalog.mf_mc_bj.src;

    返回结果如下。

    +-------+------+------+-------+---------+-------+
    | Field | Type | Null | Key   | Default | Extra |
    +-------+------+------+-------+---------+-------+
    | id    | INT  | Yes  | false | NULL    |       |
    | a     | INT  | Yes  | false | NULL    |       |
    +-------+------+------+-------+---------+-------+

• 查询MaxCompute表结构和对应的建表语句。

  • 语法

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

  • 参数说明

    • catalog_name：必填，Catalog名称。

    • database_name：必填，目标Catalog下的MaxCompute项目名称。

    • table_name：必填，目标MaxCompute项目下的表名称。

  • 示例

    SHOW CREATE TABLE odps_catalog.mf_mc_bj.src;

    返回结果如下。

    +-------+--------------------------------------------------------------------------------+
    | Table | Create Table                                                                   |
    +-------+--------------------------------------------------------------------------------+
    | src   | CREATE TABLE `src` (
      `id` int(11) DEFAULT NULL,
      `a` int(11) DEFAULT NULL
    ) |
    +-------+--------------------------------------------------------------------------------+

删除 MaxCompute Catalog

您可通过如下命令，删除MaxCompute Catalog。

DROP CATALOG odps_catalog;

CBO（Cost-Based Optimizer）统计信息采集

StarRocks当前版本暂不支持自动采集MaxCompute表的统计信息，您可以通过以下命令，手动创建采集任务，进行统计信息采集。

--<table_name>替换为MaxCompute表名称
ANALYZE TABLE <table_name>;

手动更新元数据缓存

默认情况下，StarRocks会缓存MaxCompute的元数据，从而提高查询性能。当对表做了表结构变更或表数据更新后，您也可以手动更新该表的元数据，从而确保StarRocks第一时间获取到新的元数据缓存。

--<table_name>替换为MaxCompute表名称
REFRESH EXTERNAL TABLE <table_name>;

常见问题

读取报错：Your slot quota is exceeded.

• 问题分析

  当读取数据超过数据传输服务限额时，会触发该报错。在读取数据时，StarRocks会将表切分成若干分片，分发给BE，由BE通过线程池并发读取。因此，在读取过程中占用的Slot数量通常为：Max(分片数量，BE数量*BE线程池并发数)。

• 解决方案

  • 购买高并发数的独享数据传输服务资源。具体操作，请参见购买与使用独享数据传输服务资源组。

  • 通过配置ScanParams参数，调整分片数量。如采用row_offset分片策略，还需提高odps.split.row.count参数。

  • 修改Starrocks BE线程池数量scanner_thread_pool_queue_size、scanner_thread_pool_thread_num。修改方式详情，请参见StarRocks简介。

附录：类型映射