MaxCompute:Tables externes Hologres

Mode rôle RAM

Pour un exemple de code complet, consultez la section Créer une table externe Hologres (mode d'autorisation par rôle RAM).

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

Mode rôle lié au service

Pour un exemple de code complet, consultez la section Créer une table externe Hologres (mode d'autorisation par rôle lié au service).

Le mode d'autorisation par rôle lié au service permet au même utilisateur RAM d'accéder aux tables autorisées dans MaxCompute et Hologres sans autorisation manuelle. Ce mode prend également en charge la fonctionnalité de liste blanche d'adresses IP 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>,...']
);

Rôle RAM

Dans ce mode, le créateur de la table externe intègre un rôle RAM disposant des autorisations d'accès aux données Hologres dans la définition de la table externe. D'autres utilisateurs MaxCompute peuvent ensuite recevoir des autorisations sur cette table externe. Lorsqu'un utilisateur accède à la table externe, le système utilise le rôle RAM lié pour accéder aux données de la table Hologres mappée.

Hologres ne prend pas en charge l'ajout d'un rôle RAM inter-comptes à une instance de base de données. Par conséquent, Hologres en mode rôle RAM ne prend en charge que les rôles RAM du même compte. De même, lorsque MaxCompute accède à Hologres via une table externe ou un schéma externe, seuls les rôles RAM du même compte sont pris en charge.

Rôle lié au service

Dans ce mode, vous devez créer un rôle lié au service pour accéder aux données Hologres. Afin de prévenir tout accès non autorisé, ce mode transmet l'identité de l'utilisateur à Hologres pour authentification ; l'utilisateur doit donc disposer d'autorisations à la fois sur la table externe et sur la table Hologres sous-jacente.

Scénario 1 : Hologres Snatshot PPD

Dans les scénarios de lecture directe Hologres, les expressions de filtre sont converties en clauses SQL WHERE pour les tables de partition logique et envoyées au serveur Hologres en tant que paramètre filter de la fonction holo_create_table_snapshot(). Cela permet à Hologres de filtrer les fichiers non correspondants côté serveur lors de la création du snapshot, réduisant ainsi le nombre de fichiers renvoyés à MaxCompute et minimisant les transferts de données.

Scénario 2 : Hologres JDBC PPD

Lorsque la lecture directe Hologres est désactivée (odps.table.api.enable.holo.table=false), les requêtes sont exécutées via le chemin JDBC. Dans ce cas, le PPD fonctionne en ajoutant la clause WHERE à l'instruction SQL JDBC envoyée à Hologres, et Hologres effectue le filtrage au niveau SQL. Cela diffère du PPD dans les scénarios de lecture directe Hologres :

• PPD en lecture directe : filtre les fichiers au niveau du snapshot

• PPD JDBC : filtre les lignes au niveau de la requête SQL

Scénario 3 : Filtrage au niveau des colonnes des groupes de lignes ORC

Filtrage au niveau des fichiers côté MaxCompute. Pour chaque fichier ORC, un SearchArgument est construit et transmis au lecteur ORC. Le lecteur ORC utilise les statistiques de colonne (min/max/count) de chaque stripe/groupe de lignes pour déterminer si le groupe de lignes entier peut être ignoré.

• L'élimination au niveau des fichiers est effectuée côté MaxCompute

• Dépend de l'activation ou non du paramètre PPD côté Hologres.

• Les tables non partitionnées, les tables partitionnées physiquement et les tables partitionnées logiquement sont toutes prises en charge.

Hologres Snapshot PPD

1. Préparez les données. Dans votre instance Hologres, créez une table de test et insérez des données.

   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. Créez une table externe Hologres dans 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. Interrogez la table externe.

   -- 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. Préparez les données. Dans votre instance Hologres, créez une table de test et insérez des données.

   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. Créez une table externe Hologres dans 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. Interrogez la table externe.

   -- 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))

Filtrage au niveau des colonnes des groupes de lignes ORC

Cette méthode s'applique aux scénarios impliquant de grands volumes de données. Chaque groupe de lignes dans ORC contient 10 000 lignes, de sorte que l'effet du filtrage n'est pas évident lorsque le volume de données est trop faible.

1. Préparez les données. Créez une table de test dans l'instance 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. Créez une table externe Hologres dans 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. Interrogez les données de la table externe.

   -- 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;

   Vérifiez les détails stdout de l'instance dans LogView. Le filtrage réussit si les conditions suivantes sont remplies :

   • IOCount et IOLatencyPercentiles apparaissent dans TableScan1.

   • ReadRowCount est inférieur à RequestedRowCount dans 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}}

   Dans la sortie précédente, l'opérateur TableScan1 contient les champs IOCount et IOLatencyPercentiles, et ReadRowCount (163840) est inférieur à RequestedRowCount (2000000), ce qui indique que le filtrage par pushdown de prédicats a réussi.