MaxCompute:Tabelas externas do Hologres

Considerações

Sintaxe

Ao criar uma tabela externa, especifique o StorageHandler na instrução DDL CREATE TABLE, configure a autorização por função do RAM ou por função vinculada a service e forneça a URL de conexão JDBC para acessar a fonte de dados do Hologres.

CREATE EXTERNAL TABLE [IF NOT EXISTS] <table_name>(
  <col1_name> <data_type>,
  <col2_name> <data_type>,
  ......
)
stored BY 'com.aliyun.odps.jdbc.JdbcStorageHandler'
WITH serdeproperties (
  'odps.properties.rolearn'='<role_arn>')
location 'jdbc:postgresql://<endpoint>:<port>/<database>?
  ApplicationName=MaxCompute&[currentSchema=<schema>&]
  [useSSL={true|false}&]table=<holo_table_name>/' 
tblproperties (
  'mcfed.mapreduce.jdbc.driver.class'='org.postgresql.Driver', 
  'odps.federation.jdbc.target.db.type'='holo',
-- When Hologres and MaxCompute column names differ, add the odps.federation.jdbc.colmapping parameter to map columns. 
-- This parameter can be omitted if column names are identical.
  ['odps.federation.jdbc.colmapping'='<table_column1>:<source_column1>, 
                                     <table_column2>:<source_column2>,...']
);

-- Create an external table
CREATE EXTERNAL TABLE [IF NOT EXISTS]  <table_name>(
  <col1_name> <data_type>,
  <col2_name> <data_type>,
  ......
)
STORED BY 'com.aliyun.odps.jdbc.JdbcStorageHandler'
LOCATION 'jdbc:postgresql://<endpoint>:<port>/<database>?
  ApplicationName=MaxCompute&[currentSchema=<schema>&]
  [useSSL={true|false}&]table=<holo_table_name>/' 
tblproperties (
  'mcfed.mapreduce.jdbc.driver.class'='org.postgresql.Driver', 
  'odps.federation.jdbc.target.db.type'='holo',
-- When Hologres and MaxCompute column names differ, add the odps.federation.jdbc.colmapping parameter to map columns. 
-- This parameter can be omitted if column names are identical.
   ['odps.federation.jdbc.colmapping'='<table_column1>:<source_column1>, 
                                      <table_column2>:<source_column2>,...']
);

Parâmetros

Etapa 1: Preparar dados do Hologres

Pule esta etapa se você já possui um banco de dados, uma tabela e dados de teste no Hologres.

Etapa 2: Criar uma tabela externa do Hologres

Limitações

Ao ativar o modo de leitura direta para o Hologres, aplicam-se as seguintes limitações. Se essas condições não forem atendidas, a consulta retornará ao modo JDBC.

1. Requisitos de versão

   Sua instância do Hologres deve ser V1.3.34 ou posterior. O recurso de leitura direta não é suportado em versões anteriores.

2. Restrições de tipo de tabela

   • O modo de leitura direta não é suportado para tabelas de armazenamento frio do Hologres.

   • O modo de leitura direta não é suportado para tabelas orientadas a linhas do Hologres.

3. Limitações de mapeamento de tipos de dados

   Ao usar o modo de leitura direta, o mapeamento de um tipo Timestamp With Time Zone no Hologres para um tipo TIMESTAMP no MaxCompute pode causar pequenas discrepâncias de horário. As diferenças são as seguintes:

   • Discrepância de valor de tempo

     • Para timestamps anteriores a 1900-12-31 15:54:15, o horário retornado pelo MaxCompute estará adiantado em 5 minutos e 44 segundos.

     • Para timestamps entre 1900-12-31 15:54:16 e 1969-12-31 23:59:58, o horário retornado pelo MaxCompute estará adiantado em 1 segundo.

     • Para timestamps posteriores a 1969-12-31 23:59:59, os horários no Hologres e no MaxCompute serão idênticos.

   • Deslocamento de fuso horário

     • Por exemplo, se o fuso horário do MaxCompute for UTC+8 e uma coluna Timestamp With Time Zone no Hologres for 2000-01-01 00:00:00, o MaxCompute retornará 2000-01-01 08:00:00.

     • Por exemplo, se o fuso horário do MaxCompute for UTC+8 e uma coluna Timestamp With Time Zone no Hologres for 1969-01-01 00:00:00, o MaxCompute retornará 1969-01-01 08:00:01.

4. Restrição de mesma região

   Devido a restrições de conectividade de rede, o MaxCompute pode acessar apenas instâncias do Hologres na mesma região. O acesso entre regiões falha com o seguinte erro: FAILED: ODPS-0010000:System internal error - fuxi job failed, caused by: Pangu request failed with error code 3.

5. Se sua instância do Hologres usar uma arquitetura primária/secundária, você poderá especificar apenas a instância primária na URL de conexão, e não uma instância secundária.

6. Limitação adicional para o modo Foreign Server: Você deve ativar a chave de sintaxe no nível de schema para o projeto do MaxCompute.

Ativar modo de leitura direta

Para ativar o modo de leitura direta na sua sessão, adicione o seguinte comando antes da sua consulta SQL no MaxCompute:

SET odps.table.api.enable.holo.table=true;

Você também pode ativar ou desativar o modo de leitura direta no nível do projeto.

-- You can enable direct read and disable JDBC fallback at the project level.
-- Enable direct read at the project level: 
setproject odps.table.api.enable.holo.table=true; -- Set to true to enable, false to disable.
-- Disable the default fallback to JDBC: 
setproject odps.table.api.allow.fallback.jdbc=false; -- Set to true to allow fallback, false to prevent it.

Verificar modo de leitura direta

Para verificar se uma consulta utilizou o modo de leitura direta, verifique os logs no Logview. Para mais informações sobre como usar o Logview, consulte Usar o Logview 2.0 para visualizar informações de execução de jobs.

Na aba Summary do Logview, localize o campo external holo tables. O formato é o seguinte:

<project_name>.<table_name>:<access mode>[<(fallback reason)>]

Parâmetros:

Parâmetro	Descrição
project_name	Nome do projeto.
table_name	Nome da tabela.
access mode	Modo de acesso à tabela externa. Valores válidos: Optimized: Indica que o modo de leitura direta foi utilizado. Segue um exemplo do Logview. Optimized: Indica que o modo de otimização de leitura direta está ativado. Na seção Summary do Logview, é exibido external holo tables: <project_name>.<table_name>:Optimized, o que indica que a tabela externa Holo utilizou o caminho de otimização de leitura direta. Fallback: Indica que o sistema reverteu para o modo JDBC. Segue um exemplo do Logview. Na aba Summary, se a seção external holo tables exibir uma mensagem de Fallback, como aliorc_test.holo_lineitem:Fallback (Column type map error Column name l_orderkey Odps type 3 Holo type 4), isso indica que o modo de leitura direta não foi usado. Em vez disso, o sistema reverteu para o modo Fallback devido a um erro de mapeamento de tipo de coluna. Para detalhes sobre o motivo do fallback, consulte Fallback exibido no modo de leitura direta.

Quando um job que utiliza o modo de leitura direta encontra uma limitação, ele reverte automaticamente para o modo JDBC. Sob cargas de trabalho pesadas, esse fallback pode consumir recursos significativos do pool de conexões do Hologres, e a transferência de dados no modo JDBC é muito menos eficiente do que no modo de leitura direta. Consequentemente, esses recursos podem ser liberados lentamente, aumentando a carga na sua instância do Hologres.

Em casos extremos, fallbacks frequentes podem impactar outros services críticos para o negócio que dependem da mesma instância do Hologres. Para evitar isso, desative o mecanismo de fallback automático adicionando o parâmetro set odps.table.api.allow.fallback.jdbc=false; aos seus jobs. Isso faz com que os jobs falhem em vez de reverter silenciosamente, prevenindo degradação inesperada de desempenho.

Predicate pushdown para tabelas externas do Hologres

Ao acessar tabelas externas do Hologres, o MaxCompute pode enviar condições de filtro de consulta para execução no Hologres (predicate pushdown). Os dados são filtrados previamente no lado do Hologres, o que reduz a transferência de dados e melhora o desempenho da consulta. Os seguintes cenários são suportados:

• PPD de Snapshot do Hologres: A expressão de filtro é convertida em uma cláusula SQL WHERE e passada ao servidor Hologres através do parâmetro filter de holo_create_table_snapshot().

• PPD JDBC do Hologres: A condição WHERE é anexada à instrução SQL JDBC, e o Hologres filtra os dados na camada SQL.

• Filtragem no nível de coluna de grupo de linhas ORC: Filtragem no nível de arquivo no lado do MaxCompute. Para cada arquivo ORC, um SearchArgument é construído e passado ao leitor ORC, que usa estatísticas de coluna (min/max/count) para pular grupos de linhas que não correspondem.

Os seguintes cenários serão suportados no futuro:

• Poda de partições: Para tabelas particionadas físicas do Hologres, a expressão de filtro é avaliada em relação a cada valor de partição antes da criação de um snapshot. Partições que não correspondem são ignoradas, e nenhum snapshot é criado para elas.

• Filtragem por segment key: Após o retorno do snapshot do Hologres, o MaxCompute analisa a segment key min/max nos metadados de cada arquivo e compara o intervalo com a expressão de filtro. Se o intervalo da segment key de um arquivo não se sobrepor ao filtro, o arquivo será ignorado.

• Filtragem por Distribution ID: Suportado apenas para Liquid Tables. Cada arquivo pode conter linhas com múltiplos distribution IDs. Após a leitura de um RecordBatch, as linhas são filtradas pelo intervalo de distribution ID.

Uso

Cenário 1: PPD de Snapshot do Hologres

Em cenários de leitura direta do Hologres, expressões de filtro são convertidas em cláusulas SQL WHERE para tabelas de partição lógica e enviadas ao servidor Hologres como o parâmetro filter de holo_create_table_snapshot(). Isso permite que o Hologres filtre arquivos não correspondentes no lado do servidor durante a criação do snapshot, reduzindo o número de arquivos retornados ao MaxCompute e minimizando a transferência de dados.

Cenário	Suporte a PPD em cenários de leitura direta do Hologres
Parâmetro principal	Valores válidos para o parâmetro predicate_pushdown_mode: off: Desativa o predicate pushdown e lê todos os dados. Use esta configuração para depuração e comparação em um ambiente de desenvolvimento. on: Ativa o predicate pushdown para criar apenas snapshots filtrados. Recomendado para ambientes de produção. Debug: Cria dois snapshots para comparar o desempenho. Pode ser usado para testes de desempenho e solução de problemas. Exemplo de sintaxe: set odps.external.holo.read.table.rules="{predicate_pushdown_mode:on}";
Tipos suportados	INT、BIGINT、STRING、DATE、TIMESTAMP、BINARY
Limitações	O predicate pushdown não suporta o seguinte: Funções definidas pelo usuário (UDFs) ou funções integradas. Expressões CAST durante conversão implícita. O tipo de dados jsonb. Tabelas com chave primária do Hologres.
Cenários aplicáveis	Instâncias do Hologres que suportam PPD; a versão da instância deve atender a um dos seguintes requisitos. >=3.1.36 >=3.2.18 >=4.0.7

Cenário 2: PPD JDBC do Hologres

Quando a leitura direta do Hologres está desativada (odps.table.api.enable.holo.table=false), as consultas são executadas pelo caminho JDBC. Nesse caso, o PPD funciona anexando a cláusula WHERE à SQL JDBC enviada ao Hologres, e o Hologres realiza a filtragem no nível SQL. Isso difere do PPD em cenários de leitura direta do Hologres:

• PPD de leitura direta: filtra arquivos no nível de snapshot

• PPD JDBC: filtra linhas no nível de consulta SQL

Cenário	Suporte a PPD em cenários de leitura JDBC do Hologres
Parâmetro principal	Valores do parâmetro odps.external.hive.scan.ppd.enabled: true: ativa o predicate pushdown. false: desativa o predicate pushdown. Exemplo de sintaxe do parâmetro: set odps.external.hive.scan.ppd.enabled=true;
Tipos suportados	INT、BIGINT、DOUBLE、FLOAT、STRING、DATE、TIMESTAMP、TIMESTAMP_NTZ
Limitações	O predicate pushdown não suporta o seguinte: Funções definidas pelo usuário (UDFs) ou funções integradas. Expressões CAST. O tipo de dados jsonb. Tabelas com chave primária do Hologres.
Cenários aplicáveis	Serve como solução de fallback para cenários de leitura direta do Hologres. O PPD não é suportado atualmente nesta instância do Hologres.

Cenário 3: Filtragem no nível de coluna de grupo de linhas ORC

Filtragem no nível de arquivo no lado do MaxCompute. Para cada arquivo ORC, um SearchArgument é construído e passado ao leitor ORC. O leitor ORC usa as estatísticas de coluna (min/max/count) de cada stripe/grupo de linhas para determinar se todo o grupo de linhas pode ser ignorado.

• A poda no nível de arquivo é realizada no lado do MaxCompute

• Depende se o parâmetro PPD está ativado no lado do Hologres.

• Tabelas não particionadas, tabelas particionadas físicas e tabelas particionadas lógicas são todas suportadas.

Cenário	Filtragem no nível de coluna de grupo de linhas ORC
Parâmetro principal	odps.external.holo.use.predicate.pushdown true：Ativa a filtragem. false：Desativa a filtragem. Este é o valor padrão.
Tipos suportados	BOOLEAN、INT、BIGINT、FLOAT、DOUBLE、DECIMAL、STRING、DATE、TIMESTAMP

Exemplos

PPD de Snapshot do Hologres

1. Prepare os dados. Na sua instância do Hologres, crie uma tabela de teste e insira dados.

   CREATE TABLE test_multi_type_ppd (
     c_id INT NOT NULL,
     c_boolean BOOLEAN,
     c_int INT,
     c_bigint BIGINT,
     c_double DOUBLE precision,
     c_float REAL,
     c_string TEXT,
     c_date DATE,
     c_timestamp_tz TIMESTAMPTZ,
     c_timestamp_ntz TIMESTAMP
   )
   WITH (SEGMENT_KEY = 'c_id');
   -- Insert 10 rows of data.
   INSERT INTO test_multi_type_ppd VALUES
   (1,  true,   10,  1000,   1.25,  1.5,  'alpha',   '2023-01-01', '2023-01-01 10:00:00+08', '2023-01-01 02:00:00'),
   (2,  false,  20,  2000,  -2.50,  2.5,  'beta',    '2023-01-02', '2023-01-02 10:00:00+08', '2023-01-02 02:00:00'),
   (3,  true,   30,  3000,   3.75, -3.5,  'gamma',   '2023-01-03', '2023-01-03 10:00:00+08', '2023-01-03 02:00:00'),
   (4,  false,  40,  4000,   4.00,  4.5,  'delta',   '2023-01-04', '2023-01-04 10:00:00+08', '2023-01-04 02:00:00'),
   (5,  true,   50,  5000,   5.50,  5.5,  'epsilon', '2023-01-05', '2023-01-05 10:00:00+08', '2023-01-05 02:00:00'),
   (6,  false,  60,  6000,   6.60,  6.0,  'zeta',    '2023-01-06', '2023-01-06 10:00:00+08', '2023-01-06 02:00:00'),
   (7,  true,   70,  7000,   7.70, -7.0,  'eta',     '2023-01-07', '2023-01-07 10:00:00+08', '2023-01-07 02:00:00'),
   (8,  false,  80,  8000,   8.80,  8.0,  'theta',   '2023-01-08', '2023-01-08 10:00:00+08', '2023-01-08 02:00:00'),
   (9,  true,   90,  9000,  -9.90,  9.0,  'iota',    '2023-01-09', '2023-01-09 10:00:00+08', '2023-01-09 02:00:00'),
   (10, false, 100, 10000,  10.10, 10.0,  'kappa',   '2023-01-10', '2023-01-10 10:00:00+08', '2023-01-10 02:00:00');
   SELECT * FROM test_multi_type_ppd;

2. Crie uma tabela externa do Hologres no MaxCompute.

   CREATE EXTERNAL TABLE test_multi_type_ppd
   (
     c_id int,
     c_boolean boolean,
     c_int int,
     c_bigint bigint,
     c_double double,
     c_float float,
     c_string string,
     c_date date,
     c_timestamp_tz timestamp,
     c_timestamp_ntz timestamp_ntz
   )
   STORED BY 'com.aliyun.odps.jdbc.JdbcStorageHandler'
   WITH serdeproperties ('odps.properties.rolearn'='acs:ram::139****:role/<role name>')
   LOCATION 'jdbc:postgresql://<holo-endpoint>/<db>?currentSchema=public&table=test_multi_type_ppd'
   TBLPROPERTIES (
     'mcfed.mapreduce.jdbc.driver.class'='org.postgresql.Driver',
     'odps.federation.jdbc.target.db.type'='holo'
   );

3. Consulte a tabela externa.

   -- Enable Hologres direct read.
   SET odps.table.api.enable.holo.table=true;
   -- Set the PPD mode (off, on, or debug).
   SET odps.external.holo.read.table.rules="{predicate_pushdown_mode:on}";
   -- Configure the type system.
   SET odps.sql.type.system.odps2=true;
   SET odps.sql.decimal.odps2=true;
   -- Allow expressions to be pushed down to TableScan. This is typically enabled by default.
   SET odps.use.builtin.function.input.range=true;
   -- set odps.mcqa.disable=true;
   SELECT * FROM test_multi_type_ppd WHERE c_id = 3;
   -- The query returns the following result.
   +------+-----------+-------+------------+------------+---------+----------+--------+----------------+-----------------+
   | c_id | c_boolean | c_int | c_bigint   | c_double   | c_float | c_string | c_date | c_timestamp_tz | c_timestamp_ntz |
   +------+-----------+-------+------------+------------+---------+----------+--------+----------------+-----------------+
   | 3    | true      | 30    | 3000       | 3.75       | -3.5    | gamma    | 2023-01-03 | 2023-01-03 10:00:00 | 2023-01-03 02:00:00 |
   +------+-----------+-------+------------+------------+---------+----------+--------+----------------+-----------------+
   -- Check the Summary section in Logview. The following information is displayed:
   external holo tables:
   	**.default.test_multi_type_ppd:Optimized
     Holo-side PPD enabled -->   Filter pushdown applied successfully
     Snapshot Id: 56-1-100***
     With-filter file count: 2
     With-filter create snapshot duration: 19ms

PPD JDBC do Hologres

1. Prepare os dados. Na sua instância do Hologres, crie uma tabela de teste e insira dados.

   CREATE TABLE test_multi_type_ppd (
     c_id INT NOT NULL,
     c_boolean BOOLEAN,
     c_int INT,
     c_bigint BIGINT,
     c_double DOUBLE precision,
     c_float REAL,
     c_string TEXT,
     c_date DATE,
     c_timestamp_tz TIMESTAMPTZ,
     c_timestamp_ntz TIMESTAMP
   )
   WITH (SEGMENT_KEY = 'c_id');
   -- Insert 10 rows of data.
   INSERT INTO test_multi_type_ppd VALUES
   (1,  true,   10,  1000,   1.25,  1.5,  'alpha',   '2023-01-01', '2023-01-01 10:00:00+08', '2023-01-01 02:00:00'),
   (2,  false,  20,  2000,  -2.50,  2.5,  'beta',    '2023-01-02', '2023-01-02 10:00:00+08', '2023-01-02 02:00:00'),
   (3,  true,   30,  3000,   3.75, -3.5,  'gamma',   '2023-01-03', '2023-01-03 10:00:00+08', '2023-01-03 02:00:00'),
   (4,  false,  40,  4000,   4.00,  4.5,  'delta',   '2023-01-04', '2023-01-04 10:00:00+08', '2023-01-04 02:00:00'),
   (5,  true,   50,  5000,   5.50,  5.5,  'epsilon', '2023-01-05', '2023-01-05 10:00:00+08', '2023-01-05 02:00:00'),
   (6,  false,  60,  6000,   6.60,  6.0,  'zeta',    '2023-01-06', '2023-01-06 10:00:00+08', '2023-01-06 02:00:00'),
   (7,  true,   70,  7000,   7.70, -7.0,  'eta',     '2023-01-07', '2023-01-07 10:00:00+08', '2023-01-07 02:00:00'),
   (8,  false,  80,  8000,   8.80,  8.0,  'theta',   '2023-01-08', '2023-01-08 10:00:00+08', '2023-01-08 02:00:00'),
   (9,  true,   90,  9000,  -9.90,  9.0,  'iota',    '2023-01-09', '2023-01-09 10:00:00+08', '2023-01-09 02:00:00'),
   (10, false, 100, 10000,  10.10, 10.0,  'kappa',   '2023-01-10', '2023-01-10 10:00:00+08', '2023-01-10 02:00:00');
   SELECT * FROM test_multi_type_ppd;

2. Crie uma tabela externa do Hologres no MaxCompute.

   CREATE EXTERNAL TABLE test_multi_type_ppd
   (
     c_id int,
     c_boolean boolean,
     c_int int,
     c_bigint bigint,
     c_double double,
     c_float float,
     c_string string,
     c_date date,
     c_timestamp_tz timestamp,
     c_timestamp_ntz timestamp_ntz
   )
   STORED BY 'com.aliyun.odps.jdbc.JdbcStorageHandler'
   WITH serdeproperties (
     'odps.properties.rolearn'='acs:ram::122**79014:role/<role name>')
   LOCATION 'jdbc:postgresql://hgprecn-cn-oew210ut****-cn-hangzhou-internal.hologres.aliyuncs.com:80/<holo database name>?ApplicationName=MaxCompute&currentSchema=public&useSSL=true&table=<table name>/'
   TBLPROPERTIES (
     'mcfed.mapreduce.jdbc.driver.class'='org.postgresql.Driver',
     'odps.federation.jdbc.target.db.type'='holo'
   );

3. Consulte a tabela externa.

   -- Disable Hologres direct read and use the JDBC path.
   SET odps.table.api.enable.holo.table=false;
   SET odps.table.api.enable.holo.table.auto.fallback=false;
   
   -- Enable JDBC PPD.
   SET odps.external.hive.scan.ppd.enabled=true;
   
   -- Allow expressions to be pushed down to TableScan. 
   -- This is enabled by default in most cases.
   SET odps.use.builtin.function.input.range=true;
   
   -- Enable common table.
   SET odps.sql.common.table.planner.ext.hive.bridge=true;
   SET odps.sql.common.table.planner.ext.hive.bridge.v2=true;
   
   -- After PPD is enabled, TableScan reads only one record.
   SELECT * FROM test_multi_type_ppd WHERE c_id = 3;
   
   -- The query result is as follows:
   +------+-----------+-------+------------+------------+---------+----------+--------+----------------+-----------------+
   | c_id | c_boolean | c_int | c_bigint   | c_double   | c_float | c_string | c_date | c_timestamp_tz | c_timestamp_ntz |
   +------+-----------+-------+------------+------------+---------+----------+--------+----------------+-----------------+
   | 3    | true      | 30    | 3000       | 3.75       | -3.5    | gamma    | 2023-01-03 | 2023-01-03 10:00:00 | 2023-01-03 02:00:00 |
   +------+-----------+-------+------------+------------+---------+----------+--------+----------------+-----------------+
   
   -- Check the stdout details of the instance in Logview. The following messages are displayed:
   [2026-07-22 10:02:41] Volcano instance executor [MainThreadID: 222960]
   Jdbc HoloRecordReader query conditions: (c_id = 3)
   JDBC HoloRecordReader: Query predicate pushdown succeeded.
   JdbcShardRecordReader getSelectQuery: SELECT c_id, c_boolean, c_int, c_bigint, c_double, c_float, c_string, c_date, c_timestamp_tz, c_timestamp_ntz FROM test_multi_type_ppd0721 AS test_multi_type_ppd0721 WHERE ( hg_shard_id = 9) AND ((c_id = 3))

Filtragem no nível de coluna de grupo de linhas ORC

Este método aplica-se a cenários com grandes volumes de dados. Cada grupo de linhas no ORC contém 10.000 linhas, portanto, o efeito de filtragem não é evidente quando o volume de dados é muito pequeno.

1. Prepare os dados. Crie uma tabela de teste na instância do Hologres.

   DROP TABLE IF EXISTS test_2m_data;
   
   BEGIN;
   CREATE TABLE test_2m_data (
       id   INT    NOT NULL,
       name TEXT   NOT NULL
   );
   
   -- Set a distribution key to avoid data skew and improve batch write performance.
   CALL set_table_property('test_2m_data', 'distribution_key', 'id');
   COMMIT;
   
   INSERT INTO test_2m_data (id, name)
   SELECT 
       g AS id,
       'user_' || g AS name
   FROM generate_series(1, 2000000) AS g;
   
   SELECT COUNT(*) FROM test_2m_data;

2. Crie uma tabela externa do Hologres no MaxCompute.

   CREATE EXTERNAL TABLE ext_holo_test_2m_data
   (
       id          INT  ,
       name        STRING 
   )
   STORED BY 'com.aliyun.odps.jdbc.JdbcStorageHandler'
   WITH serdeproperties (
     'odps.properties.rolearn'='acs:ram::*****:role/<role_name>')
   LOCATION 'jdbc:postgresql://hgpostcn-cn-2bj4lnv16008-cn-<region>-internal.hologres.aliyuncs.com:80/<holo_database>?currentSchema=public&table=test_2m_data'
   TBLPROPERTIES (
     'mcfed.mapreduce.jdbc.driver.class'='org.postgresql.Driver',
     'odps.federation.jdbc.target.db.type'='holo'
   );

3. Consulte dados da tabela externa

   -- Enable Hologres direct read
   SET odps.table.api.enable.holo.table=true;
   -- Enable PPD
   SET odps.external.holo.use.predicate.pushdown=true;
   -- Set the PPD mode
   SET odps.external.holo.read.table.rules="{predicate_pushdown_mode:on}";
   SELECT * FROM ext_holo_test_2m_data where id>100 and id<100000;

   Verifique os detalhes stdout da instância no LogView. A filtragem terá sucesso se ocorrer o seguinte:

   • IOCount e IOLatencyPercentiles aparecem em TableScan1.

   • ReadRowCount é menor que RequestedRowCount em TableScan1.

   37  Filter1                                          99899           0                99998998
       {"PMS":{"S":24584}}
   38  GlobalInit                                       0               769              0
       {"CallBack":{"T":1},"CodeGenDCE":{"T":6393},"CodeGenMajorPass":{"T":13954},"CreateCursor":{"T":41350},
       "CreateOperator":{"T":309351},"JitFunction":{"T":13027},"LoadAndParseIR":{"T":38273},"OpenShuffleRW":{"T":30},
       "parseTableScanInfo":{"T":4551}}
   39  TableScan1                                       163840          1634             100269
       {"PMS":{"S":20480},"actualSplitFileCount":0,"actualSplitFileStats":{"avg":0,"max":0,"min":9223372036854775807},
       "plannedSplitFileCount":0,"plannedSplitFileStats":{"avg":0,"max":0,"min":9223372036854775807}}
       {"DecodingCount":320,"DecodingInBytes":147068,"DecodingLatencyUs":1224,"DecodingOutBytes":1310720,
       "DeltaFileInclusiveLatencyUs":76,"IOBlockingLatencyUs":424255,"IOCount":60,"IOLatencyPercentiles":
       "{\"Count\":\"60\",\"Percentiles\":\"[[0,2835], [0.5,6183], [0.9,6183], [0.95,6183], [0.99,6183], [0.999,6752], [1,
       15206]]\",\"Total\":\"495889\"}","IOReadBytes":27988440,"MaxMemoryUsageBytes":1936240,"ReadRawSize":2346495,
       "ReadRowCount":163840,"ReaderCount":1,"ReaderInclusiveLatencyUs":447950,"RequestedRowCount":2000000,
       "StringDirectReadOutBytes":169113,"Type":"OrcReader","VectorBatchConversionLatencyUs":1636}
   40  TableScan1@CommonTableReader                     0               0                nan
       {"PMS":{"S":19456}}
   41  fuxi                                             0               0                nan
       {"PMS":{"S":0}}
   42  inst                                             0               0                nan
       {"APMS":{"S":0},"PMFM":{"S":1073741824},"PMS":{"S":3246003}}

   Na saída anterior, o operador TableScan1 contém os campos IOCount e IOLatencyPercentiles, e ReadRowCount (163840) é menor que RequestedRowCount (2000000), o que indica que a filtragem por predicate pushdown teve sucesso.

Importação e exportação de dados do Hologres

• Para importar dados do Hologres para uma tabela ou partição do MaxCompute, use LOAD.

• Para exportar dados de um projeto do MaxCompute para o Hologres para uso por outros mecanismos de computação, use UNLOAD.

Tipos de dados suportados

• Limitações do tipo Decimal

  Para tabelas externas do Hologres criadas no MaxCompute, o tipo de dados DECIMAL é fixo em decimal(38,18) e não pode ser modificado. Se a tabela de origem tiver menos casas decimais, defina a coluna como tipo STRING na tabela externa do MaxCompute e depois use a função CAST para converter explicitamente os dados ao utilizá-los.

• Limitações de tipos complexos

  Tabelas externas do Hologres criadas no MaxCompute não suportam tipos de dados complexos como Array, Map ou Struct.

• Outros tipos incompatíveis

  Tipos de dados no Hologres, como MONEY, não são suportados porque não existem tipos de dados correspondentes no MaxCompute.

A tabela a seguir lista os mapeamentos de tipos de dados entre Hologres e MaxCompute.

Tipo Hologres	Tipo MaxCompute	Leitura JDBC	Escrita JDBC	Leitura direta (odps.table.api.enable.holo.table=true)	Descrição
INTEGER (alias: INT ou INT4)	INT	Suportado	Suportado	Suportado	Um inteiro assinado de 32 bits.
TEXT	STRING, VARCHAR	Suportado	Suportado	Suportado	Um tipo string com limite de comprimento de 8 MB.
SMALLINT	SMALLINT	Suportado	Suportado	Suportado	Um inteiro assinado de 16 bits.
INT2	SMALLINT	Suportado	Suportado	Suportado	Um inteiro assinado de 16 bits.
BIGINT (alias: INT8)	BIGINT	Suportado	Suportado	Suportado	Um inteiro assinado de 64 bits.
BYTEA	BINARY	Suportado	Suportado	Suportado	O tipo de dados binário tem atualmente um limite de comprimento de 8 MB. O tipo de dados BINARY do Hologres tem tamanho máximo de 1 GB.
REAL (alias: FLOAT4)	FLOAT	Suportado	Suportado	Suportado	Um número de ponto flutuante binário de 32 bits.
DOUBLE PRECISION (alias: FLOAT8)	DOUBLE	Suportado	Suportado	Suportado	Um número de ponto flutuante binário de 64 bits.
BOOLEAN (alias: BOOL)	BOOLEAN	Suportado	Suportado	Suportado	Um tipo BOOLEAN.
TIMESTAMP	TIMESTAMP_NTZ	Suportado	Não suportado	Suportado	O tipo TIMESTAMP do Hologres tem precisão de microssegundos e sem fuso horário. Ele é mapeado para o TIMESTAMP_NTZ do MaxCompute, que tem precisão de nanossegundos. A diferença de precisão pode causar discrepâncias.
TIMESTAMP WITH TIME ZONE (alias: TIMESTAMPTZ)	TIMESTAMP	Suportado	Não suportado	Suportado	O tipo de dados timestamp tem precisão de nanossegundos e usa o formato yyyy-mm-dd hh:mm:ss.xxxxxxxxx. A conversão de precisão subjacente é tratada automaticamente.
DECIMAL (alias: NUMERIC)	DECIMAL(precision,scale)	Suportado	Suportado	Suportado	Um tipo numérico exato de base 10. precision: Especifica o número máximo de dígitos. Faixa de valores: 1 <= precision <= 38. scale: Especifica o número de casas decimais. Faixa de valores: 0 <= scale <= 18. No MaxCompute, o tipo de dados DECIMAL assume o padrão (38,18) se nenhuma precisão for especificada. Ao criar uma tabela usando a instrução IMPORT FOREIGN SCHEMA, o sistema converte automaticamente a precisão.
CHAR(n)	CHAR(n)	Suportado	Suportado	Suportado	No MaxCompute, CHAR(n) é um tipo de caractere de comprimento fixo. n especifica o comprimento. O comprimento máximo é 255. Strings mais curtas são preenchidas com espaços. O tamanho máximo do tipo de dados CHAR(n) no Hologres é 1 GB.
VARCHAR(n)	VARCHAR(n)	Suportado	Suportado	Suportado	O tipo de dados VARCHAR(n) no MaxCompute é um tipo de caractere de comprimento variável. O parâmetro n especifica o comprimento, que varia de 1 a 65535. No Hologres, o tamanho máximo para VARCHAR(n) é 1 GB.
DATE	DATE	Suportado	Suportado	Suportado	O tipo de dados é data no formato yyyy-mm-dd.
INT4[]	ARRAY<INT>	Suportado	Não suportado	Suportado	Arrays do Hologres são mapeados para os tipos ARRAY correspondentes do MaxCompute. Note que a escrita de arrays no Hologres não é suportada via JDBC.
INT8[]	ARRAY<BIGINT>	Suportado	Não suportado	Suportado
FLOAT4[]	ARRAY<FLOAT>	Suportado	Não suportado	Suportado
FLOAT8[]	ARRAY<DOUBLE>	Suportado	Não suportado	Suportado
BOOLEAN[]	ARRAY<BOOLEAN>	Suportado	Não suportado	Suportado
TEXT[]	ARRAY<STRING>	Suportado	Não suportado	Suportado
JSONB	JSON	Não suportado	Não suportado	Suportado	O JSONB do Hologres é mapeado para o tipo JSON do MaxCompute. Este mapeamento é suportado apenas no modo de leitura direta.
JSON	STRING	Suportado	Não suportado	Não suportado	Ao usar JDBC, o tipo JSON do Hologres é mapeado para o tipo STRING do MaxCompute, o que limita o tamanho a 8 MB.
SERIAL (auto-increment)	INT	Suportado	Não suportado	Suportado	O MaxCompute lê campos SERIAL do Hologres como valores INT. O comportamento de incremento automático não é suportado em escritas.
RoaringBitmap	Não suportado	Não suportado	Não suportado	Não suportado	Não existe tipo correspondente no MaxCompute.
RoaringBitmap64	Não suportado	Não suportado	Não suportado	Não suportado	Não existe tipo correspondente no MaxCompute.
BIT(n)	Não suportado	Não suportado	Não suportado	Não suportado	Não existe tipo correspondente no MaxCompute.
VARBIT(n)	Não suportado	Não suportado	Não suportado	Não suportado	Não existe tipo correspondente no MaxCompute.
INTERVAL	Não suportado	Não suportado	Não suportado	Não suportado	Não existe tipo correspondente no MaxCompute.
TIMETZ	Não suportado	Não suportado	Não suportado	Não suportado	Não existe tipo correspondente no MaxCompute.
TIME	Não suportado	Não suportado	Não suportado	Não suportado	Não existe tipo correspondente no MaxCompute.
INET	Não suportado	Não suportado	Não suportado	Não suportado	Não existe tipo correspondente no MaxCompute.
MONEY	Não suportado	Não suportado	Não suportado	Não suportado	Não existe tipo correspondente no MaxCompute.
OID	Não suportado	Não suportado	Não suportado	Não suportado	Não existe tipo correspondente no MaxCompute.
UUID	Não suportado	Não suportado	Não suportado	Não suportado	Não existe tipo correspondente no MaxCompute.

FAQ

Erro ODPS-0130071 ao ler dados do Hologres diretamente

• Problema

  Ao ler dados do Hologres no modo de leitura direta, o job falha com um erro semelhante a ODPS-0130071 Failed to split to equal size...max count: 7777. Por exemplo:

  ODPS-0130071:[0,0] Semantic analysis exception - physical plan generation failed: storage/table/src/input_splits_builder.cpp(195): StorageException: Failed to split to equal size, total size: 2143570729934, min size: 268435456, max size: 272629760, max count: 7777, split size: 275629513, split count: 7777

• Causa

  Quando o MaxCompute lê dados do Hologres, sua estratégia padrão de divisão de dados pode fazer com que o número de instâncias de mapper exceda o limite de concorrência de 7.777.

  Nota

  Esse limite impede a execução de jobs com um número excessivo de mappers, protegendo a estabilidade dos arquivos e das conexões de rede do Hologres.

• Solução

  Resolva este erro definindo os seguintes parâmetros.

  SET odps.external.holo.mapper.instances=10000; -- Increase the concurrency limit. The maximum value is 10,000.
  SET odps.sql.mapper.split.size=512; -- Adjust the job concurrency. The maximum value is 512 MB.

Jobs SQL lentos em tabelas externas do Hologres

• Problema

  O desempenho é lento ao usar o SDK para buscar dados em uma tabela externa do MaxCompute.

• Solução

  Tabelas externas têm desempenho lento porque suportam apenas varreduras completas de tabela. Para melhor desempenho, use uma tabela interna do MaxCompute.

Erro quando o nome da coluna é uma palavra-chave

• Problema

  Se o nome de uma coluna na sua tabela do Hologres for uma palavra-chave, as consultas podem falhar com os seguintes erros sem configuração especial:

  ODPS-0123131:User defined function exception - SQLException in nextKeyValue

  Caused by: org.postgresql.util.PSQLException: ERROR: syntax error at or near ","

• Solução

  Adicione o parâmetro odps.federation.jdbc.colmapping para mapear as colunas da tabela de origem do Hologres para as colunas da tabela externa do Hologres.

  Por exemplo, se a tabela de origem do Hologres contiver a palavra-chave "offset" como nome de coluna, adicione o parâmetro 'odps.federation.jdbc.colmapping'='offset:"offset"' ao criar a tabela externa do Hologres.

Erro password authentication failed for user "mcslr$STS.**" no modo de função vinculada a service

• Problema

  Quando um usuário do RAM ou função do RAM lê uma tabela externa do Hologres usando o modo de autorização por função vinculada a service, o job pode falhar com o erro password authentication failed for user "mcslr$STS.******". Veja abaixo um exemplo de mensagem de erro:

  Caused by: java.lang.RuntimeException: java.lang.RuntimeException: org.postgresql.util.PSQLException: 
    ERROR: pooler: c0a981a2413b5: password authentication failed for user "*******$V2#****#TMP.3KvMuCpXhuMbeZsbpaE****m738WfEw73rze
    ohJUeXxhsKza1khCxdKSJQAU5CFac*****qDCA#STS.NZFkZ3TbJNmAjS2TKLdUHHdiW#**.*.*.***"
  	at org.apache.hadoop.mapreduce.lib.db.DBInputFormat.setConf(DBInputFormat.java:171)
  	at com.aliyun.odps.jdbc.wrapper.InputFormatWrapper.checkAndInitDbInputFormat(InputFormatWrapper.java:48)
  	... 45 more
  Caused by: java.lang.RuntimeException: org.postgresql.util.PSQLException: ERROR: pooler: c0a981a2413b5: 
    password authentication failed for user "*******$V2#****#TMP.3KvMuCpXhuMbeZsbpaE****m738WfEw73rzeohJUeXxhsKza1khCxdKSJQAU
    5CFac*****qDCA#STS.NZFkZ3TbJNmAjS2TKLdUHHdiW#**.*.*.***"
  	at org.apache.hadoop.mapreduce.lib.db.DBInputFormat.createConnection(DBInputFormat.java:205)
  	at com.aliyun.odps.jdbc.impl.JdbcDBInputFormat.superCreateConnection(JdbcDBInputFormat.java:69)
  	at com.aliyun.odps.jdbc.impl.JdbcDBInputFormat.createConnection(JdbcDBInputFormat.java:56)
  	at org.apache.hadoop.mapreduce.lib.db.DBInputFormat.setConf(DBInputFormat.java:164)

• Causa

  Falha no modo de autorização por função vinculada a service.

• Solução

  Adicione o parâmetro set odps.external.holo.enable.slr = force; antes da instrução SQL para forçar a ativação do modo de autorização por função vinculada a service.

Erro Holo-side PPD disabled --> The Holo snapshot PPD mode is enabled, but FAILED to push down the filter into Holo no modo de leitura direta

• Mensagem de erro

  Holo-side PPD disabled --> The Holo snapshot PPD mode is enabled, 
  but FAILED to push down the filter into Holo, 
  errorMsg[storage/table/src/holo/snapshot.cpp(319): 
  StorageException: Create/Get snapshot failed for table: test_multi_type_ppd partition:  
  Query:select holo_create_table_snapshot('public.test_multi_type_ppd', 259200, filter=>$$c_id = 3$$) with error ERROR:  
  internal error: Failed to build fragment dag desc: node type 65 is not supported

• Solução

  Certifique-se de que sua tabela interna do Hologres atenda aos requisitos nas Notas de uso.

Fallback Exibido no Modo de Leitura Direta

Na aba Summary do Logview, se informações de Fallback aparecerem na seção external holo tables, isso indica que o modo de leitura direta não foi utilizado e o sistema reverteu para o modo JDBC. Erros comuns e causas estão listados abaixo:

Detalhes do erro	Causa raiz	Resolução
Column name <col> Odps type <X> Holo type <Y>, manifestado especificamente como: Column name created_at Odps type DATETIME Holo type TIMESTAMP Column name create_date Odps type STRING Holo type TIMESTAMP Column name create_time Odps type STRING Holo type TIMESTAMP_NTZ Column name manual_enabled Odps type INT Holo type BIGINT Column name cpa_bid Odps type DECIMAL(38,18) Holo type DECIMAL(38,10) Column name details Odps type STRING Holo type JSON Column name history_score_median Odps type STRING Holo type DOUBLE Column name l_orderkey Odps type 3 Holo type 4	Erro de mapeamento de tipo de coluna	Os tipos de coluna dos campos da tabela externa do Hologres não correspondem aos da tabela de origem. Modifique o tipo de dados da tabela externa de acordo com o mapeamento de tipos de dados para ativar o modo de leitura direta.
Odps table schema invalid	Erro de generalização: Consulte os Error Logs no Logview para detalhes.	Possível causa 1: Erro de configuração de Column Mapping — formato de texto inválido, múltiplas colunas mapeadas para a mesma coluna do Hologres, apontando para uma coluna inexistente, ou Mapping não configurado quando o nome da coluna não existe no Hologres. Possível causa 2: Colunas ausentes — verifique se os DDLs da tabela externa do Hologres e da tabela de origem correspondem.
Holo connection error	Exceção de Conexão da Instância Hologres	Informações de permissão incorretas ou status anormal da instância Hologres. Verifique se o usuário atual tem permissão para acessar o banco de dados Hologres correspondente, ou verifique se a instância Hologres está atualmente em estado operacional.
Select hg_version error/Hologres version check error/Fetch hg_version data error	Versão da instância Hologres incorreta	Atualize a instância Hologres para V1.3.34 ou posterior. Para detalhes sobre como atualizar a versão da instância, consulte Atualizar uma instância。

Referências

Para mais informações sobre problemas comuns com tabelas externas do Hologres, consulte FAQ sobre Lakehouse e Tabelas Externas.