湖仓一体2.0使用指南

步骤一：授权

步骤二：创建DLF+OSS外部数据源

1. 登录MaxCompute控制台，在左上角选择地域。

2. 在左侧导航栏，选择租户管理>外部数据源。

3. 在外部数据源页面，单击创建外部数据源。

4. 在新增外部数据源对话框，根据界面提示配置相关参数。参数说明如下：

   参数	说明
   外部数据源类型	选择DLF+OSS。
   外部数据源名称	可自定义命名。命名规则如下： 以字母开头，且只能包含小写字母、下划线和数字。 不能超过128个字符。
   外部数据源描述	根据需要填写。
   地域	默认为当前地域。
   DLF Endpoint	默认为当前地域的DLF Endpoint。
   OSS Endpoint	默认为当前地域的OSS Endpoint。
   RoleARN	RAM角色的ARN信息。此角色需要包含能够同时访问DLF和OSS服务的权限。 您可以登录RAM访问控制台，在左侧导航栏选择身份管理>角色，单击对应的RAM角色名称，即可在基本信息区域获取ARN信息。 示例：acs:ram::124****:role/aliyunodpsdefaultrole。
   外部数据源补充属性	为外部数据源特殊声明的属性，指定后，使用此外部数据源的任务可以按照参数定义的行为访问源系统。 说明 支持的具体参数请关注后续官网文档更新说明，具体参数将随产品能力演进逐步放开。

5. 单击确定，完成外部数据源的创建。

步骤三：创建外部Schema

外部Schema是项目内的对象，可以使用SQL进行操作。若您当前账号没有打开过租户级别Schema语法开关，需要在SQL前增加SET odps.namespace.schema=true;语句，以方便后续执行Schema相关命令。

引用了DLF+OSS类型外部数据源的外部Schema创建命令如下：

CREATE EXTERNAL SCHEMA IF NOT EXISTS <external_schema_name>
with <dlfoss_foreign_server_name>
ON '<dlf_calaog_id>.<database_name>';

参数说明如下：

• external_schema_name：外部Schema名称。

• dlfoss_foreign_server_name：上述已创建的外部数据源名称，外部Schema归属的项目必须与外部数据源处于同一地域。

• dlf_calaog_id：DLF数据目录ID。数据目录创建方法请参见新建数据目录（Catalog）。

• database_name：DLF中指定数据目录下的数据库名称。详情请参见创建数据库。

步骤四：使用SQL访问数据源系统

• 命令格式：列出DLF和OSS的表名称。

  • 方式1：

    SHOW tables IN <external_schema_name>; --external_schema_name为外部Schema名称。

  • 方式2：

    use <external_schema_name>; --external_schema_name为外部Schema名称。
    SHOW tables;

• 使用示例：

  1. 查询名称为es_dlf的外部Schema下的所有表名。

     SHOW tables IN es_dlf;

     返回结果示例：

     ALIYUN$xxx@test.aliyunid.com:hellocsv
     ALIYUN$xxx@test.aliyunid.com:t1
     ALIYUN$xxx@test.aliyunid.com:t2
     ALIYUN$xxx@test.aliyunid.com:t3

  2. 查询lakehouse47_3项目中es_dlfSchema的hellocsv表数据。

     SELECT * FROM lakehouse47_3.es_dlf.hellocsv;

     返回结果示例：

     +------------+------------+------------+------------+
     | col1       | col2       | col3       | col4       |
     +------------+------------+------------+------------+
     | 1          | hello      | test       | world      |
     +------------+------------+------------+------------+

  3. 从数据源将联邦外表hellocsv的数据复制入数仓。

     -- 将联邦外表的数据复制到数仓中
     CREATE TABLE hellocsv_copy AS SELECT * FROM lakehouse47_3.es_dlf.hellocsv;
     
     -- 查询数仓中已复制的表数据
     SELECT * FROM hellocsv_copy;

     返回结果示例：

     +------------+------------+------------+------------+
     | col1       | col2       | col3       | col4       |
     +------------+------------+------------+------------+
     | 1          | hello      | test       | world      |
     +------------+------------+------------+------------+

步骤一：创建Hive+HDFS外部数据源

1. 登录MaxCompute控制台，在左上角选择地域。

2. 在左侧导航栏，选择租户管理>外部数据源。

3. 在外部数据源页面，单击创建外部数据源。

4. 在新增外部数据源对话框，根据界面提示配置相关参数。参数说明如下：

   参数	说明
   外部数据源类型	选择Hive+HDFS。
   外部数据源名称	可自定义命名。命名规则如下： 以字母开头，且只能包含小写字母、下划线和数字。 不能超过128个字符。
   外部数据源描述	根据需要填写。
   网络连接对象	网络连接名称，选择或创建MaxCompute到阿里云E-MapReduce或Hadoop VPC网络的连接。参数详情请参见访问VPC方案（专线直连）中的创建MaxCompute与目标VPC网络间的网络连接步骤。 说明 网络连接基本概念请参见Networklink。 VPC必须与MaxCompute外部数据源及外部数据源挂载的项目处于同一地域。
   集群名称	在Hadoop集群高可用环境下用于指代NameNode的名称。在构建Hadoop集群场景下，您可以通过hdfs-site.xml文件中的dfs.nameservices配置参数获取集群名称。
   NameNode 地址	目标Hadoop集群的Active和Standby NameNode服务地址和端口号（端口号通常是8020）。您可联系Hadoop集群管理员获取。
   HMS 服务地址	目标Hadoop集群的Active和Standby NameNode的Hive元数据服务地址和端口号（端口号通常是9083）。您可联系Hadoop集群管理员获取。
   认证类型	暂时仅支持无认证方式。
   外部数据源补充属性	为外部数据源特殊声明的属性，指定后，使用此外部数据源的任务可以按照参数定义的行为访问源系统。 说明 支持的具体参数请关注后续官网文档更新说明，具体参数将随产品能力演进逐步放开。

5. 单击确定，完成外部数据源的创建。

步骤二：创建外部Schema

外部Schema是项目内的对象，可以使用SQL进行操作。若您当前账号没有打开过租户级别Schema语法开关，需要在SQL前增加SET odps.namespace.schema=true;语句，以方便后续执行Schema相关命令。

引用了Hive+HDFS类型的外部数据源的外部Schema创建命令如下：

CREATE EXTERNAL SCHEMA IF NOT EXISTS <external_schema_name>
WITH  <hive_foreign_server_name>
ON '<database_name>' ;

参数说明如下：

• external_schema_name：外部Schema名称。

• hive_foreign_server_name：已创建的外部数据源名称。

• database_name：Hive数据库名称。

步骤三：使用SQL访问数据源系统

• 命令格式：列出Hive的表名称。

  • 方式1：

    SHOW tables IN <external_schema_name>; --external_schema_name为外部Schema名称。

  • 方式2：

    use <external_schema_name>; --external_schema_name为外部Schema名称。
    SHOW tables;

• 使用示例：

  1. 查询名称为es_hive3的外部Schema下的所有表名。

     SHOW tables IN es_hive3;

     返回结果示例：

     ALIYUN$xxx@test.aliyunid.com:t1

  2. 查询lakehouse47_3项目中es_hive3Schema的t1表数据。

     SELECT * FROM lakehouse47_3.es_hive3.t1;

     返回结果示例：

     +------------+
     | id         |
     +------------+
     | 1          |
     +------------+

  3. 从数据源将联邦外表hellocsv的数据复制入数仓。

     -- 将联邦外表的数据复制到数仓中
     CREATE TABLE t1_copy AS SELECT * FROM lakehouse47_3.es_hive3.t1;
     
     -- 查询数仓中已复制的表数据
     SELECT * FROM t1_copy;

     返回结果示例：

     +------------+
     | id         |
     +------------+
     | 1          |
     +------------+

步骤一：创建Hologres外部数据源

1. 登录MaxCompute控制台，在左上角选择地域。

2. 在左侧导航栏，选择租户管理>外部数据源。

3. 在外部数据源页面，单击创建外部数据源。

4. 在新增外部数据源对话框，根据界面提示配置相关参数。参数说明如下：

   参数	说明
   外部数据源类型	选择Hologres。
   外部数据源名称	可自定义命名。命名规则如下： 以字母开头，且只能包含小写字母、下划线和数字。 不能超过128个字符。
   外部数据源描述	根据需要填写。
   连接方式	目前只支持云产品互联网络连接方式。
   Host	Hologres实例的Host信息。 您可以登录Hologres管理控制台，在左侧导航栏选择实例列表，并单击对应的实例ID，即可在实例详情页面的网络信息区域获取Host。 示例：hgpostcn-cn-3m***-cn-shanghai-internal.hologres.aliyuncs.com。
   Port	Hologres实例的端口信息。 您可以登录Hologres管理控制台，在左侧导航栏选择实例列表，并单击对应的实例ID，即可在实例详情页面的网络信息区域获取端口。端口一般为80。
   DBNAME	Hologres实例的数据库名称。
   认证方式	RAMRole：使用RAM角色扮演认证鉴权方式，支持跨主账号的方式访问Hologres。联邦外表暂时只支持RAMRole方式。RoleARN填写示例：acs:ram::uid:role/aliyunodpsholorole。aliyunodpsholorole角色配置及授权，详情请参见创建Hologres外部表（STS模式）。 ExecuteWithUserAuth：MaxCompute和Hologres之间的用户身份互认模式，允许MaxCompute和Hologres基于相同的账号，当前用户以自身的身份可以在两个系统中看到有权访问的表和数据，可以直接通过CALL EXEC_EXTERNAL_QUERY函数执行命令，不需要额外设置认证信息。 重要 ExecuteWithUserAuth模式暂不支持联邦外表使用方式。
   RoleARN	RAM角色的ARN信息，此角色需要包含能够访问Hologres服务的权限。认证方式选择RAMRole时需要填写该参数。 您可以登录RAM访问控制台，在左侧导航栏选择身份管理>角色，单击对应的RAM角色名称，即可在基本信息区域获取ARN信息。
   外部数据源补充属性	为外部数据源特殊声明的属性，指定后，使用此外部数据源的任务可以按照参数定义的行为访问源系统。 说明 支持的具体参数请关注后续官网文档更新说明，具体参数将随产品能力演进逐步放开。

5. 单击确定，完成外部数据源的创建。

步骤二：创建外部Schema

外部Schema是项目内的对象，可以使用SQL进行操作。若您当前账号没有打开过租户级别Schema语法开关，需要在SQL前增加SET odps.namespace.schema=true;语句，以方便后续执行Schema相关命令。

引用了Hologres类型外部数据源的外部Schema创建命令如下：

CREATE EXTERNAL SCHEMA IF NOT EXISTS <external_schema_name>
with  <holo_foreign_server_name>
ON '<holoschema_name>' ;

参数说明如下：

• external_schema_name：外部Schema名称。

• holo_foreign_server_name：已创建的外部数据源名称。

• holoschema_name：Hologres需要映射的Schema名称。

步骤三：使用SQL访问数据源系统

• 命令格式：列出Hologres Schema中的表名称。

  • 方式1：

    SHOW tables IN <external_schema_name>; --external_schema_name为外部Schema名称。

  • 方式2：

    use <external_schema_name>; --external_schema_name为外部Schema名称。
    SHOW tables;

• 使用示例：

  1. 查询名称为es_holo_rolearn_nonl的外部Schema下的所有表名：

     SHOW tables IN es_holo_rolearn_nonl;

     返回结果示例：

     ALIYUN$xxx@test.aliyunid.com:mc_holo_external

  2. 查询lakehouse47_3项目中es_holo_rolearn_nonlSchema的mc_holo_external表数据。

     SELECT * FROM lakehouse47_3.es_holo_rolearn_nonl.mc_holo_external;

     返回结果示例：

     +------------+------------+------------+------------+
     | col1       | col2       | col3       | col4       |
     +------------+------------+------------+------------+
     | 1          | hello      | test       | world      |
     +------------+------------+------------+------------+

  3. 向表中插入数据。

     INSERT INTO lakehouse47_3.es_holo_rolearn_nonl.mc_holo_external VALUES(2,'hello','test','holo');
     
     SELECT * FROM lakehouse47_3.es_holo_rolearn_nonl.mc_holo_external;

     返回结果示例：

     +------------+------------+------------+------------+
     | col1       | col2       | col3       | col4       |
     +------------+------------+------------+------------+
     | 1          | hello      | test       | world      |
     | 2          | hello      | test       | holo       |
     +------------+------------+------------+------------+

  4. 从数据源将联邦外表hellocsv的数据复制入数仓。

     -- 将联邦外表的数据复制到数仓中
     CREATE TABLE mc_holo_external_copy AS SELECT * FROM lakehouse47_3.es_holo_rolearn_nonl.mc_holo_external;
     
     -- 查询数仓中已复制的表数据
     SELECT * FROM mc_holo_external_copy;

     返回结果示例：

     +------------+------------+------------+------------+
     | col1       | col2       | col3       | col4       |
     +------------+------------+------------+------------+
     | 1          | hello      | test       | world      |
     | 2          | hello      | test       | holo       |
     +------------+------------+------------+------------+

基于当前用户身份向Hologres提交执行命令

MaxCompute支持使用CALL命令，运行EXEC_EXTERNAL_QUERY函数，向Hologres侧提交可执行的SQL命令。

• 命令语法

  CALL EXEC_EXTERNAL_QUERY (
    '<holo_ExecuteWithUserAuth_foreign_server_name>',
    r"###(
      <holo_query>)###");

  • holo_ExecuteWithUserAuth_foreign_server_name：即上文中以ExecuteWithUserAuth模式创建的Hologres外部数据源名称。

  • r：表示即将执行的命令。

  • holo_query：是在边界符中填写的具体Hologres SQL命令。

  说明

  函数参考C++的Raw String方式，用""和()加delimiter的边界符方式，避免前后边界符与holo_query中的特殊字符发生冲突。 delimiter字符串可以修改，注意"[delimiter]( )[delimiter]"一定要前后成对。边界符不包括<>，建议的边界符为"###(<holo_query>)###"。

• 使用示例

  • 示例1：在MaxCompute中提交一条向Hologres内部表public.current_user_test进行INSERT OVERWRITE操作的SQL，数据来源是Hologres查询当前用户UID的Query：SELECT current_user;

    1. 在MaxCompute中执行如下SQL。

       CALL EXEC_EXTERNAL_QUERY (
         'fs_holo_ExecuteWithUserAuth_nonl_y',
         r"###(
           CALL hg_insert_overwrite(
             'public.current_user_test',
             $$SELECT current_user$$
       );)###");

    2. 在Hologres中查询内部表public.current_user_test的数据。

       SELECT * FROM current_user_test;

       返回结果：返回当前MaxCompute侧与Hologres侧相同用户身份的UID，如1117xxxxxx519。

  • 示例2：在MaxCompute中提交一条向Hologres内部表public.hologres_parent_insert1，分区子表是2020，进行INSERT OVERWRITE操作的SQL，数据来源是Hologres内部的一张基于MaxCompute表的外部表：SELECT * FROM mc_external_table WHERE a='2020';

    1. 在MaxCompute中执行如下SQL。

       CALL EXEC_EXTERNAL_QUERY (
         'fs_holo_ExecuteWithUserAuth_nonl_y',
         r"###(
           CALL hg_insert_overwrite(
             'public.hologres_parent_insert1',
             '2020',
             $$SELECT * FROM mc_external_table WHERE a='2020'$$
       );)###");

    2. 在Hologres中查询内部表public.hologres_parent_insert1的数据。

       -- hologres查表，会多一条数据
       SELECT * FROM hologres_parent_insert1;

       返回结果：

       a			b	c														d
       2020	1	2024-06-19 10:27:46.201636	a