MaxCompute:Tabelas externas do Hologres

Modo de função RAM

Para obter um exemplo de código completo, consulte Create a Hologres external table (RAM role authorization mode).

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>,...']
);

Modo de service-linked role

Para obter um exemplo de código completo, consulte Create a Hologres external table (service-linked role authorization mode).

O modo de autorização por service-linked role permite que o mesmo usuário RAM acesse tabelas autorizadas tanto no MaxCompute quanto no Hologres sem autorização manual. Esse modo também oferece suporte ao recurso de lista de permissões de IP do Hologres.

-- 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>,...']
);

RAM role

Neste modo, o criador da tabela externa incorpora uma função RAM com permissões de acesso aos dados do Hologres na definição da tabela externa. Outros usuários do MaxCompute podem então receber permissões sobre essa tabela externa. Ao acessar a tabela externa, o sistema utiliza a função RAM vinculada para acessar os dados na tabela mapeada do Hologres.

O Hologres não oferece suporte à adição de uma função RAM entre contas a uma instância de banco de dados. Portanto, o Hologres no modo de função RAM suporta apenas funções RAM da mesma conta. Da mesma forma, quando o MaxCompute acessa o Hologres por meio de uma tabela externa ou schema externo, apenas funções RAM da mesma conta são suportadas.

Service-linked role

Neste modo, é necessário criar uma função vinculada ao service para acessar os dados do Hologres. Para evitar acessos não autorizados, esse modo encaminha a identidade do usuário ao Hologres para autenticação. Assim, o usuário precisa ter permissões tanto na tabela externa quanto na tabela subjacente do Hologres.

Cenário 1: PPD de Snapshot do Hologres

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

Cenário 2: PPD via 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 adicionando a cláusula WHERE à instrução SQL JDBC enviada ao Hologres, que realiza a filtragem na camada SQL. Essa abordagem difere do PPD em cenários de leitura direta do Hologres:

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

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

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

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

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

• Depende de o parâmetro de PPD estar ativado no lado do Hologres.

• Tabelas não particionadas, tabelas fisicamente particionadas e tabelas logicamente particionadas são todas suportadas.

Hologres Snapshot PPD

1. Prepare os dados. Na sua instância 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 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

Hologres JDBC PPD

1. Prepare os dados. Na sua instância 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 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))

ORC row group column-level filtering

Este método é indicado para cenários com grandes volumes de dados. Cada row group no ORC contém 10.000 linhas, portanto o efeito da filtragem não é perceptível quando o volume de dados é muito pequeno.

1. Prepare os dados. Crie uma tabela de teste na instância 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 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 os 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 de stdout da instância no LogView. A filtragem foi bem-sucedida se as seguintes condições forem atendidas:

   • Os campos IOCount e IOLatencyPercentiles aparecem no TableScan1.

   • O valor de ReadRowCount é menor que o de RequestedRowCount no 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 acima, o operador TableScan1 contém os campos IOCount e IOLatencyPercentiles, e o valor de ReadRowCount (163840) é menor que o de RequestedRowCount (2000000). Isso indica que a filtragem por predicate pushdown foi bem-sucedida.