Use o recurso Auto Load para carregar dados do MaxCompute e OSS automaticamente sob demanda ou integralmente - Hologres: Central de Documentação do Alibaba Cloud

Escolha um modo de carregamento

	Carregamento sob demanda	Carregamento completo
Funcionamento	Cria a tabela externa na primeira consulta a uma tabela do MaxCompute ou do OSS	Cria antecipadamente tabelas externas para todas as tabelas de uma fonte de dados; sincroniza novas tabelas periodicamente
Cenário ideal	Poucas tabelas que exigem consultas aceleradas	Muitas tabelas ou múltiplas fontes de dados que exigem consultas aceleradas
Valor do parâmetro	`query` (padrão)	`period`

Comportamento do carregamento sob demanda:

Se já existirem um schema e uma tabela do Hologres com o mesmo nome, o Auto Load não será acionado. A consulta utilizará a tabela interna existente.
A conta que executa a consulta precisa ter permissão para criar e excluir schemas e tabelas no banco de dados, mas apenas na primeira consulta. As consultas subsequentes exigem somente permissão de consulta.
As tabelas são criadas apenas no momento da consulta, não seguindo uma programação.

Comportamento do carregamento completo:

Todas as tabelas da fonte de dados são criadas como tabelas externas do Hologres após a configuração inicial.
Novas tabelas adicionadas à fonte de dados são carregadas automaticamente como tabelas externas após o próximo intervalo de verificação (padrão: 30 minutos).
Não ative o carregamento completo para fontes de dados com mais de 1.000 tabelas.
Defina o intervalo de verificação para 600 segundos (10 minutos) ou mais.

Limitações

Os parâmetros de mapeamento para fontes de dados do MaxCompute e do OSS não podem começar com hg_ ou holo_, pois esses prefixos são reservados no Hologres.
Uma única consulta pode carregar automaticamente no máximo 6 tabelas. Se a consulta envolver mais de 6 tabelas, o processo de carregamento automático falhará. Execute a consulta novamente para carregar as tabelas externas restantes.
Caso uma tabela do MaxCompute contenha tipos de dados incompatíveis com tabelas externas do Hologres, a criação automática da tabela externa não será possível. Utilize CREATE FOREIGN TABLE para criá-la manualmente, selecionando apenas os campos compatíveis.
Para usar o Auto Load com dados do OSS por meio do Data Lake Formation (DLF), execute CREATE USER MAPPING para especificar o AccessKey ID e o AccessKey secret da conta que acessa o DLF e o OSS.
Quando tabelas de várias fontes de dados externas são carregadas no mesmo schema do Hologres, uma nova tabela externa sobrescreve qualquer tabela externa existente com o mesmo nome. Associe diferentes fontes de dados a diferentes schemas do Hologres para evitar esse problema.
A criação automática de um schema inexistente no Hologres requer permissões de db_admin.
A evolução de schema (adição de colunas, exclusão de colunas, modificação de nomes e ordem das colunas) é compatível com tabelas externas do MaxCompute (V2.2.1+), mas não com tabelas externas do OSS.

Requisitos de versão

Versão	Novidades
V1.1.43+	Auto Load para tabelas externas do MaxCompute (apenas modelo de duas camadas)
V1.3.28+	Intervalo de verificação padrão alterado de 5 minutos para 30 minutos
V2.2.1+	Parâmetro `hg_experimental_load_foreign_table_mode`; suporte ao modelo de três camadas do MaxCompute; evolução de schema para tabelas externas do MaxCompute; carregamento de metadados do DLF para consultas ao OSS

Nota

Se sua instância for V2.1 ou anterior e você precisar dos recursos da V2.2.1+, entre em contato com o suporte técnico do Hologres para fazer o upgrade.

Ative o Auto Load para tabelas externas

A configuração exige quatro etapas. A etapa 2 aplica-se apenas ao Hologres V2.2.1 e versões posteriores.

Ativar o carregamento automático
(V2.2.1+, opcional) Definir o modo de carregamento
Configurar mapeamentos de schema
Consultar dados e verificar a configuração

Pré-requisitos

Antes de começar, certifique-se de ter:

Uma instância do Hologres executando a V1.1.43 ou posterior
Permissões de db_admin no banco de dados do Hologres
(Para fontes DLF/OSS) Um servidor externo criado com DLF_FDW e um mapeamento de usuário configurado — consulte Acelerar consultas em dados de um data lake baseado em OSS usando DLF

Etapa 1: Ativar o carregamento automático

ALTER DATABASE <database_name> SET hg_experimental_enable_auto_load_foreign_table = on;

Substitua <database_name> pelo nome do seu banco de dados do Hologres.

Etapa 2: Definir o modo de carregamento

Esta etapa aplica-se ao Hologres V2.2.1 e versões posteriores. Ignore-a para versões anteriores — o carregamento sob demanda (query) é usado por padrão.

O modo deve ser definido no nível do banco de dados.

-- On-demand loading (default)
ALTER DATABASE <database_name> SET hg_experimental_load_foreign_table_mode = 'query';

-- Full loading
ALTER DATABASE <database_name> SET hg_experimental_load_foreign_table_mode = 'period';

Etapa 3: Configurar mapeamentos de schema

Mapeie cada schema do Hologres para a fonte de dados externa correspondente.

Mapeamentos do MaxCompute (V2.2.1+)

-- Three-layer model project
ALTER DATABASE <database_name> SET hg_experimental_auto_load_foreign_schema_mapping = '<hologres_schema>:<odps_foreign_server>.<mc_project>.<mc_schema>, [...]';

-- Two-layer model project
ALTER DATABASE <database_name> SET hg_experimental_auto_load_foreign_schema_mapping = '<hologres_schema>:<odps_foreign_server>.<mc_project>, [...]';

Mapeamentos do MaxCompute (anteriores à V2.2.1)

ALTER DATABASE <database_name> SET hg_experimental_default_odps_project_list='<odps_project_name_1>,<odps_project_name_2>...';

Mapeamentos do DLF (V2.2.1+)

-- Default catalog
ALTER DATABASE <database_name> SET hg_experimental_auto_load_foreign_schema_mapping = '<hologres_schema>:<dlf_foreign_server>.<dlf_database> [...]';

-- Custom catalog
ALTER DATABASE <database_name> SET hg_experimental_auto_load_foreign_schema_mapping = '<hologres_schema>:<dlf_foreign_server>.<dlf_catalog>.<dlf_database>, [...]';

Parâmetros

Parâmetro	Descrição	Padrão
`database_name`	Nome do banco de dados do Hologres	—
`hologres_schema`	Nome do schema do Hologres	—
`odps_foreign_server`	Valor fixo: `odps_server`	`odps_server`
`mc_project`	Nome do projeto do MaxCompute. Encontre-o no console do MaxCompute em Workspace > Project Management	—
`mc_schema`	Nome do schema do MaxCompute. Necessário apenas para projetos de modelo de três camadas. Consulte Operações de schema	—
`odps_project_name`	(Apenas versões anteriores à V2.2.1) Nome do projeto do MaxCompute. Separe vários nomes com vírgulas.	vazio (nenhum projeto carregado periodicamente)
`dlf_foreign_server`	Servidor externo criado com DLF_FDW. Execute `SELECT * FROM pg_foreign_server;` para obter o nome. Consulte Acelerar consultas em dados de um data lake baseado em OSS usando DLF	—
`dlf_catalog`	Nome do catálogo de dados do DLF. Encontre-o no console do Data Lake Formation na aba Metadata > Metadata Management > Data Catalog	—
`dlf_database`	Nome do banco de dados do DLF. Encontre-o no console do Data Lake Formation na aba Metadata > Metadata Management > Database	—

Etapa 4: Consultar dados e verifique a configuração

Execute uma consulta no schema mapeado. O Auto Load cria a tabela externa no primeiro acesso (modo sob demanda) ou confirma que as tabelas já foram carregadas (modo completo).

-- Query a MaxCompute table
SELECT * FROM <hologres_schema>.<mc_table>;

-- Query a DLF table
SELECT * FROM <hologres_schema>.<dlf_table>;

Para confirme quais fontes de dados estão configuradas, execute:

-- V2.2.1 and later
SHOW hg_experimental_auto_load_foreign_schema_mapping;

-- Earlier than V2.2.1
SHOW hg_experimental_default_odps_project_list;

Mais operações

Desativar o carregamento automático

ALTER DATABASE <database_name> SET hg_experimental_enable_auto_load_foreign_table = off;

Após a desativação, o Hologres interrompe a sincronização de metadados das fontes de dados externas e a criação de novas tabelas externas. As tabelas externas existentes permanecem disponíveis para consulta. Para adicionar mais tabelas externas manualmente, utilize IMPORT FOREIGN SCHEMA.

Defina o intervalo de verificação para carregamento completo

No modo de carregamento completo, configure a frequência com que o Hologres verifica se há novas tabelas na fonte de dados. Quando uma nova tabela é detectada, ela é carregada automaticamente como tabela externa na próxima consulta após o término do intervalo.

-- Set the check interval to 600 seconds (10 minutes)
ALTER DATABASE <database_name> SET hg_experimental_load_all_foreign_table_interval_time = 600;

Padrão: 1800 segundos (30 minutos). Mínimo: 600 segundos (10 minutos).

Ative a evolução de schema para tabelas externas do MaxCompute

Quando o schema de uma fonte de dados do MaxCompute mudar — colunas adicionadas, excluídas ou renomeadas — ative este parâmetro GUC (Grand Unified Configuration) no nível da sessão para atualize os metadados da tabela externa automaticamente durante a consulta.

SET hg_experimental_enable_auto_load_check_schema_evolution = on;

Importante

Ative este parâmetro apenas no nível da sessão. Ativá-lo no nível do banco de dados gera um grande volume de tarefas de verificação de evolução de schema e aumenta a carga do sistema.

Nota

A evolução de schema não é compatível com tabelas externas do OSS.

Exclua uma tabela externa

Para parar de acelerar consultas em uma tabela externa, remova-a com a instrução DROP. Consulte DROP FOREIGN TABLE.

Exemplos

Exemplo 1: Carregamento sob demanda de um projeto do MaxCompute

Este exemplo demonstra o carregamento sob demanda para projetos do MaxCompute nos modelos de duas e três camadas.

	Modelo de duas camadas	Modelo de três camadas
Projeto	`mc_project`	`mc_3_layer_project`
Schema	—	`mc_schema`
Tabela	`mc_table`	`mc_table`

Modelo de duas camadas

-- Step 1: Enable automatic loading
ALTER DATABASE holo_demo SET hg_experimental_enable_auto_load_foreign_table = on;

-- Step 2: Configure the mapping
-- V2.2.1 and later
ALTER DATABASE holo_demo SET hg_experimental_auto_load_foreign_schema_mapping = 'hologres_schema:odps_server.mc_project';
-- Earlier than V2.2.1
ALTER DATABASE holo_demo SET hg_experimental_default_odps_project_list='mc_project';

-- Step 3: Query the table (the foreign table is created on first query)
SELECT * FROM hologres_schema.mc_table;

Modelo de três camadas

-- Step 1: Enable automatic loading
ALTER DATABASE holo_demo SET hg_experimental_enable_auto_load_foreign_table = on;

-- Step 2: Configure the mapping
ALTER DATABASE holo_demo SET hg_experimental_auto_load_foreign_schema_mapping = 'holo_schema_3layer:odps_server.mc_3_layer_project.mc_schema';

-- Step 3: Query the table
SELECT * FROM holo_schema_3layer.mc_table;

Exemplo 2: Carregamento completo de uma fonte de dados do DLF

Este exemplo ilustra o carregamento completo para um banco de dados do DLF, tanto do catálogo padrão quanto de um catálogo personalizado.

Catálogo padrão do DLF

Todas as tabelas em dlf_db são carregadas como tabelas externas do Hologres. O sistema verifica periodicamente se há novas tabelas com base no intervalo configurado.

-- Step 1: Create the DLF foreign server
CREATE SERVER IF NOT EXISTS dlf_server FOREIGN DATA WRAPPER dlf_fdw OPTIONS (
    dlf_endpoint 'dlf-share.cn-beijing.aliyuncs.com',
    oss_endpoint 'oss-cn-beijing-internal.aliyuncs.com'
);

-- Step 2: Create a user mapping with credentials for DLF and OSS
CREATE USER MAPPING FOR <account_uid> SERVER <server_name> OPTIONS (
    dlf_access_id 'accessid',
    dlf_access_key 'accesskey',
    oss_access_id 'accessid',
    oss_access_key 'accesskey'
);

-- Step 3: Enable automatic loading
ALTER DATABASE holo_demo SET hg_experimental_enable_auto_load_foreign_table = on;

-- Step 4: Configure the mapping and set full loading mode
SET hg_experimental_auto_load_foreign_schema_mapping = 'holo_schema:dlf_server.dlf_db';
SET hg_experimental_load_foreign_table_mode = 'period';
SET hg_experimental_load_all_foreign_table_interval_time = 600;

-- Step 5: Query a table
SELECT * FROM holo_schema.dlf_table;

Catálogo personalizado do DLF

-- Step 1: Create the DLF foreign server
CREATE SERVER IF NOT EXISTS DLF_server FOREIGN DATA WRAPPER dlf_fdw OPTIONS (
    dlf_endpoint 'dlf-share.cn-beijing.aliyuncs.com',
    oss_endpoint 'oss-cn-beijing-internal.aliyuncs.com'
);

-- Step 2: Create a user mapping
CREATE USER MAPPING FOR <account_uid> SERVER <server_name> OPTIONS (
    dlf_access_id 'accessid',
    dlf_access_key 'accesskey',
    oss_access_id 'accessid',
    oss_access_key 'accesskey'
);

-- Step 3: Enable automatic loading
ALTER DATABASE holo_demo SET hg_experimental_enable_auto_load_foreign_table = on;

-- Step 4: Configure the mapping, loading mode, and check interval
SET hg_experimental_auto_load_foreign_schema_mapping = 'holo_schema:DLF_server.dlf_catalog.dlf_db';
SET hg_experimental_load_foreign_table_mode = 'period';
SET hg_experimental_load_all_foreign_table_interval_time = 600;

-- Step 5: Query a table
SELECT * FROM holo_schema.dlf_table;

Próximos passos

IMPORT FOREIGN SCHEMA — importe tabelas externas manualmente quando o Auto Load estiver desativado
DROP FOREIGN TABLE — remova tabelas externas que não são mais necessárias
Acelerar consultas em dados de um data lake baseado em OSS usando DLF — configure servidores externos do DLF e mapeamentos de usuários
Operações de schema — entenda os schemas do modelo de três camadas do MaxCompute