External databases let you query data in MaxCompute and data lake sources directly from Hologres — without migrating any data. This feature is available in Hologres V3.0 and later.
When to use external databases
Use external databases when you need to:
Run federated queries — join Hologres internal tables with MaxCompute tables or data lake tables in a single SQL query.
Manage metadata centrally — load metadata from external sources into Hologres without physically moving the data, supporting a unified lakehouse architecture.
Query data lakes — access Apache Paimon, Hudi, and Delta Lake data managed through Data Lake Formation (DLF) and Object Storage Service (OSS), with high-performance reads and writes from Hologres Query Engine (HQE).
If your goal is simply to read or write MaxCompute data at high speed, Hologres's native MaxCompute integration handles that directly. External databases are the right choice when you need cross-source queries or centralized metadata management across multiple data sources.
How it works
Hologres treats MaxCompute and DLF as external databases. Once an external database is created, it is globally visible — you can reference its tables from any Hologres database using the three-part format:
ext_db.ext_schema.ext_tableYou can also connect directly to an external database to run SQL statements and configure Grand Unified Configuration (GUC) parameters.
Permissions on external databases are managed by the external data sources (MaxCompute or DLF), not by Hologres. Hologres passes your identity to the external source on each request.
Prerequisites
Before you begin, ensure that you have:
Hologres V3.0 or later
An Alibaba Cloud account or a RAM user with the required permissions
Access to the external data source (MaxCompute project or DLF catalog)
Set up access permissions
The identity Hologres passes to the external data source depends on how you configure access.
| Identity type | How to configure |
|---|---|
| Service-linked role (default) | Grant the Hologres service-linked role the required permissions in MaxCompute or DLF. Use your Alibaba Cloud account or a RAM user with the required permissions to complete this grant. See Hologres service-linked role. |
| RAM role | Assign a Resource Access Management (RAM) role to customize access policies for the external data source. See RAM role overview. |
| BASIC account | If you use a BASIC account (not an Alibaba Cloud account or RAM user), run CREATE USER MAPPING to associate the account with the external data source. See CREATE USER MAPPING. |
Create an external database
After permissions are configured, create an external database with the CREATE EXTERNAL DATABASE statement. For the full syntax and examples, see CREATE EXTERNAL DATABASE.
Query external data
Reference a table in the external database using the three-part format:
SELECT * FROM ext_db.ext_schema.ext_table;Limitations and considerations
Global visibility: External databases are globally visible once created.
No data migration: The external database feature loads metadata only. Data stays in the source system (MaxCompute or DLF).
Permission model: Permissions on external databases are managed by the external data sources (MaxCompute or DLF). Hologres only passes identities to external data sources. Grant access at the source before users query through Hologres.
Storage classes: Standard storage and Infrequent Access (IA) storage classes apply to Hologres internal data only. External data remains in MaxCompute or DLF under its own storage model.
Next steps
CREATE EXTERNAL DATABASE — full syntax reference
CREATE USER MAPPING — account association for BASIC accounts
Hologres service-linked role — configure the default identity pass-through