Access Hologres Data in MaxCompute via External Tables - DataWorks

The Hologres metadata mapping feature in DataWorks lets you query Hologres data directly from MaxCompute without importing data. DataWorks creates external tables or external schemas in MaxCompute that map to Hologres tables or schemas, so you can run MaxCompute SQL on Hologres data while keeping storage costs low and avoiding data duplication.

Use this feature when:

You need ad hoc or exploratory queries on Hologres data from MaxCompute
You want to avoid ETL pipelines or data duplication between the two systems
You need the governance and compute capabilities of MaxCompute with data that lives in Hologres

Two mapping levels are available:

Schema-level mapping: Maps an entire Hologres schema to a MaxCompute external schema. Backed by MaxCompute external schemas.
Table-level mapping: Maps a single Hologres table to a MaxCompute external table. Backed by the MaxCompute external table feature.

Prerequisites

Instances and data catalog

Before you begin, make sure you have:

A MaxCompute project activated. See Create a MaxCompute project.
A Hologres instance purchased. See Purchase a Hologres instance.
The Hologres instance added to the DATA CATALOG pane in DataWorks Data Studio. See Data Catalog.

For schema-level mapping only

A foreign server of the Hologres type created in MaxCompute. See Step 1: Create a Hologres foreign server.

Important
When creating the foreign server, follow these constraints: - Set Host to a classic network hostname. Virtual Private Cloud (VPC) hostnames are not supported. - Set Authentication Method to RAMRole. ExecuteWithUserAuth is not supported. - Set DBNAME to the name of the Hologres database you want to map.

Roles and permissions

The access identity is added to the MaxCompute project.
The access identity has read permissions on MaxCompute external tables.
Only users assigned the O&M (operations and maintenance) or Workspace Administrator role can select data sources added in the production environment.

Limitations

Only data in Hologres internal databases can be mapped to MaxCompute.
The Hologres foreign server must use a classic network hostname. VPC hostnames are not supported.
The Authentication Method for the foreign server must be RAMRole. ExecuteWithUserAuth is not supported.
MaxCompute and Hologres support different data types. Unsupported type mappings are silently skipped. Review Data type mappings between MaxCompute and Hologres before mapping to confirm your data types are supported.
For other limits on Hologres external tables in MaxCompute, see Hologres external tables.

Access control

DataWorks determines the access identity based on how the MaxCompute project is added:

MaxCompute project source	Access identity	Required Hologres permissions
Added as a data source in DataWorks	The identity specified for that data source. To map Hologres metadata to a production-environment project, your account must have the O&M or Workspace Administrator role.	If using dual-signature mode: read and write permissions on Hologres tables. If using STS mode: the RAM role must have read and write permissions on Hologres tables.
A project on which you have direct access permissions	Your current Alibaba Cloud account	Same as above.

Open the metadata mapping configuration

Go to the Workspaces page in the DataWorks console. In the top navigation bar, select a region. Find the target workspace and choose Shortcuts > Data Studio in the Actions column.
In the left-side navigation pane of the Data Studio page, click the icon to open the DATA CATALOG pane.
In the Hologres directory, find the schema or table to map. Right-click its name and select Metadata Mapping to MaxCompute.

Map a schema

Schema-level mapping creates an external schema in MaxCompute that mirrors all tables in a Hologres schema. The external schema syncs metadata from a Hologres foreign server.

Before mapping, read User guide for Data Lakehouse Solution 2.0 to understand MaxCompute foreign servers and external schemas. The target MaxCompute project must be an internal project with the schema feature enabled.

Setup overview: Prepare a foreign server → configure mapping parameters → run.

Step 1: Prepare a Hologres foreign server in MaxCompute

Schema-level mapping works by creating an external schema in the MaxCompute project, which syncs Hologres metadata through a foreign server. Add a MaxCompute external data source in DataWorks that points to the target Hologres database, then mount it to the MaxCompute project to link the external schema to the Hologres database.

For setup instructions, see Create and use a Hologres federation.

Set Host to a classic network hostname (VPC is not supported) and set DBNAME to the Hologres database name you want to use for mapping.

Step 2: Configure schema-level mapping

Open the metadata mapping configuration.
In the Hologres directory, right-click the schema and select Metadata Mapping to MaxCompute.

On the Metadata Mapping to MaxCompute tab, configure the parameters.

Hologres (Source)

Parameter	Description
Source object type	Fixed as `Hologres Schema`.
Source object name	The Hologres schema to map, in `<Hologres database>.<Hologres schema>` format. The value is pre-filled based on the schema you selected. The Hologres database in this value must match the DBNAME you set when creating the foreign server.

MaxCompute (Destination)

Parameter	Description
Instance search method	How to select the target MaxCompute project. From DataWorks data sources: select from MaxCompute data sources associated with the workspace. I am authorized: select from MaxCompute projects you have access to within your Alibaba Cloud account.
Data source	(Required when Instance search method is From DataWorks data sources) The MaxCompute data source to use.
Project name	(Required when Instance search method is I am authorized) The MaxCompute project to use.
External schema name	The name of the MaxCompute external schema to create.
External data source	The foreign server connected to the Hologres database. See Step 1: Create a Hologres foreign server. The Host:port, Auth, and Database fields are populated automatically based on the server you select.

Click Run in the top toolbar to complete the mapping.

Map a table

Table-level mapping creates a single MaxCompute external table that maps to a specific Hologres table. Unlike schema-level mapping, the external table is a one-time snapshot—metadata is not automatically refreshed. To update the mapping, delete the external table and create a new mapping.

Setup overview: Select the source Hologres table → configure the target external table parameters → run.

Configure table-level mapping

Open the metadata mapping configuration.
In the Hologres directory, right-click the table and select Metadata Mapping to MaxCompute.

On the Metadata Mapping to MaxCompute tab, configure the parameters.

Hologres (Source)

Parameter	Description
Source object type	Fixed as `Hologres Table`.
Source object name	The Hologres table to map. The value is pre-filled based on the table you selected.

MaxCompute (Destination)

Parameter	Description
Instance search method	How to select the target MaxCompute project. From DataWorks data sources: select from MaxCompute data sources associated with the workspace. Also configure Data source and External table. The data source identity must have read and write permissions on both the Hologres table and the MaxCompute project. I am authorized: select from MaxCompute projects you have access to. Also configure External table. Your account must have read and write permissions on both the Hologres table and the MaxCompute project.
Data source	(Required when Instance search method is From DataWorks data sources) The MaxCompute data source to use.
Project name	(Required when Instance search method is I am authorized) The MaxCompute project to use.
Schema	The MaxCompute external schema where the external table will be created.
External table	The name of the external table to create. The Hologres table metadata maps to this table.
Permissions to access MaxCompute external table	The authentication method for accessing the external table after mapping. Dual-signature: a joint authentication protocol developed by MaxCompute and Hologres. Use the same account in both systems to access the external table without additional configuration. See Dual-signature authentication. RamRole: authentication uses Security Token Service (STS). See RamRole authentication.
RoleARN	(Required when Permissions to access MaxCompute external table is RamRole) The ARN of the RAM role to use. Create a RAM role first. See Create a Hologres external table (STS mode).
Location	The mapping address between the Hologres table and the MaxCompute table. Generated automatically—do not modify.
Lifecycle	The lifecycle setting for the MaxCompute external table.
Field	The MaxCompute table fields and their data types for this mapping. Adjust based on your requirements. Unsupported data type mappings are skipped. See Data type mappings between MaxCompute and Hologres.

Click Run in the top toolbar to complete the mapping.

What's next

After mapping completes:

In the MaxCompute directory of the DATA CATALOG pane, view the external schema or external table that the Hologres metadata is mapped to.
Create a MaxCompute SQL node in Data Studio and use it to query data in the Hologres external table.