Ingestion-time partitioned tables - MaxCompute - Centre de documentation Alibaba Cloud

Les tables partitionnées par heure d'ingestion assignent automatiquement les lignes entrantes aux partitions en fonction du moment où elles sont écrites dans MaxCompute. Au lieu de spécifier manuellement une clé de partition, vous déclarez une pseudo-colonne _partitiontime et une expression TRUNC_TIME. MaxCompute capture l'horodatage d'écriture, le tronque à la granularité choisie (heure, jour, mois ou année) et génère pour vous la colonne de clé de partition.

Par exemple, si vous créez une table partitionnée par heure et écrivez des lignes aux moments suivants :

Heure d'ingestion des données (UTC+8)	Valeur _partitiontime générée (TIMESTAMP)	Clé de partition générée (STRING)
2025-06-18 17:22:00	2025-06-18 17:00:00	2025-06-18 09:00:00
2025-06-18 17:40:00	2025-06-18 17:00:00	2025-06-18 09:00:00
2025-06-18 18:31:00	2025-06-18 18:00:00	2025-06-18 10:00:00

La fonction TRUNC_TIME convertit l'horodatage local en UTC avant de procéder à la troncature, de sorte que la clé de partition STRING reflète l'heure UTC. Consultez la section Comportement des fuseaux horaires pour plus de détails.

Pour un aperçu de tous les types de tables partitionnées dans MaxCompute, consultez la rubrique Aperçu des tables partitionnées.

Limitations

Une seule colonne de partition est prise en charge. Le partitionnement multiniveau n'est pas pris en charge.
La colonne de partition est toujours de type de données STRING. Cette configuration ne peut pas être modifiée.
Le partitionnement automatique basé sur l'heure d'ingestion fonctionne uniquement pour les écritures via MaxCompute SQL. D'autres méthodes d'ingestion, telles que le connecteur Flink, ne sont pas prises en charge.
Seule la fonction TRUNC_TIME est prise en charge dans l'expression AUTO PARTITIONED BY.

Comportement des fuseaux horaires

La fonction TRUNC_TIME convertit l'horodatage d'ingestion du fuseau horaire local du projet vers l'UTC avant d'effectuer la troncature. La valeur de la clé de partition STRING est toujours exprimée en UTC, même si votre projet s'exécute dans un autre fuseau horaire.

Important

Définissez le fuseau horaire de votre projet sur UTC afin d'éviter des valeurs inattendues pour les clés de partition : Si votre projet utilise un fuseau horaire autre que l'UTC (par exemple, Asia/Shanghai, UTC+8), la valeur UTC tronquée diffère de l'heure locale selon le décalage UTC. Les exemples de requêtes présentés dans cette rubrique utilisent Asia/Shanghai pour illustrer cet effet — c'est pourquoi _partitiontime et la colonne de clé de partition affichent une différence de 8 heures dans les résultats.

SET odps.sql.timezone=UTC;

Créer une table partitionnée par heure d'ingestion

Syntaxe

CREATE [OR REPLACE] TABLE [IF NOT EXISTS] <table_name>
  (_partitiontime <data_type>, <col_name> <data_type> [, ...])
  [COMMENT <table_comment>]
AUTO PARTITIONED BY (<auto_partition_expression> [AS <auto_partition_column_name>])
TBLPROPERTIES('ingestion_time_partition'='true');

Paramètres

Paramètre	Obligatoire	Description
`table_name`	Oui	Nom de la table à créer.
`_partitiontime`	Oui	Pseudo-colonne qui stocke l'horodatage d'ingestion tronqué. Le nom de la colonne est fixe et ne peut pas être modifié. Types de données pris en charge : `TIMESTAMP` et `TIMESTAMP_NTZ`.
`col_name`	Oui	Nom d'une colonne standard.
`data_type`	Oui	Type de données de la colonne.
`table_comment`	Non	Commentaire associé à la table.
`TBLPROPERTIES('ingestion_time_partition'='true')`	Oui	Identifie la table comme étant partitionnée par heure d'ingestion.
`auto_partition_expression`	Oui	Expression permettant de dériver la clé de partition. Seule la fonction TRUNC_TIME est prise en charge. MaxCompute capture automatiquement l'heure d'ingestion et la transmet à `TRUNC_TIME` pour générer la valeur de la clé de partition.
`auto_partition_column_name`	Non	Nom attribué à la colonne de partition générée. La valeur par défaut est `_pt_col_0_`. Si ce nom est déjà utilisé, le système utilise `_pt_col_1_`, `_pt_col_2_`, et ainsi de suite. La colonne générée est de type STRING et ne peut pas être modifiée directement.

Exemples

Exemple 1 : Partitionnement par heure

L'instruction suivante crée la table ingestion_sale_detail_hourly. Lors de l'écriture des données, MaxCompute tronque l'heure d'ingestion à l'heure, remplit la colonne _partitiontime et stocke le résultat UTC en tant que colonne de partition sale_time.

-- The system captures the write time, truncates it to the hour,
-- and stores the UTC value as the sale_time partition key.
CREATE TABLE IF NOT EXISTS ingestion_sale_detail_hourly (
  shop_name    STRING,
  total_price  DOUBLE,
  _partitiontime TIMESTAMP
)
AUTO PARTITIONED BY (TRUNC_TIME(_partitiontime, 'hour') AS sale_time)
TBLPROPERTIES('ingestion_time_partition'='true');

Exécutez DESC ingestion_sale_detail_hourly; pour inspecter la table. La sortie indique que sale_time est une colonne de partition de type STRING :

+------------------------------------------------------------------------------------+
| Owner:                    ALIYUN$test****                                          |
| Project:                   xxxxxxx                                                 |
| Schema:                    default                                                 |
| TableComment:                                                                      |
+------------------------------------------------------------------------------------+
| CreateTime:               2025-06-16 14:59:40                                      |
| LastDDLTime:              2025-06-16 14:59:40                                      |
| LastModifiedTime:         2025-06-16 14:59:40                                      |
+------------------------------------------------------------------------------------+
| InternalTable: YES      | Size: 0                                                  |
+------------------------------------------------------------------------------------+
| Native Columns:                                                                    |
+------------------------------------------------------------------------------------+
| Field           | Type       | Label | Comment                                     |
+------------------------------------------------------------------------------------+
| shop_name       | string     |       |                                             |
| total_price     | double     |       |                                             |
| _partitiontime  | timestamp  |       |                                             |
+------------------------------------------------------------------------------------+
| Partition Columns:                                                                 |
+------------------------------------------------------------------------------------+
| sale_time       | string     |                                                     |
+------------------------------------------------------------------------------------+

Exemple 2 : Partitionnement par jour

Lorsque la granularité est définie sur day, MaxCompute génère également une pseudo-colonne _partitiondate de type DATE, en plus de _partitiontime.

CREATE TABLE IF NOT EXISTS ingestion_sale_detail_daily (
  shop_name    STRING,
  total_price  DOUBLE,
  _partitiontime TIMESTAMP
)
AUTO PARTITIONED BY (TRUNC_TIME(_partitiontime, 'day') AS sale_date)
TBLPROPERTIES('ingestion_time_partition'='true');

Pour afficher _partitiondate , incluez-la explicitement dans la requête : SELECT *, _partitiondate FROM ingestion_sale_detail_daily; Pour inspecter la logique de génération des partitions, utilisez l'instruction SHOW CREATE TABLE .

Écrire des données dans une table partitionnée par heure d'ingestion

Tous les exemples ci-dessous écrivent des données dans les tables ingestion_sale_detail_hourly et ingestion_sale_detail_daily créées dans la section Créer une table partitionnée par heure d'ingestion.

Si vous omettez _partitiontime de l'instruction INSERT, MaxCompute utilise l'heure d'écriture actuelle. Si vous fournissez une valeur, elle doit être tronquée à la même granularité que celle définie dans l'instruction CREATE TABLE.

Exemple 1 : Laisser le système attribuer la partition

Omettez _partitiontime. MaxCompute utilise l'horodatage d'écriture actuel et le tronque à l'heure.

INSERT INTO ingestion_sale_detail_hourly (shop_name, total_price)
VALUES
  ('shanghai_shop', 10001.1),
  ('chongqin_shop', 20002.2),
  ('hangzhou_shop', 30003.3),
  ('shenzhen_shop', 40004.4);

Exemple 2 : Spécifier explicitement l'heure d'ingestion

La valeur doit être tronquée à la granularité déclarée (horaire dans ce cas).

Valide — 2025-06-15 14:00:00 correspond à une limite horaire exacte :

INSERT INTO ingestion_sale_detail_hourly (shop_name, total_price, _partitiontime)
VALUES
  ('beijing_shop', 50005.5, TIMESTAMP '2025-06-15 14:00:00'),
  ('chengdu_shop', 60006.6, TIMESTAMP '2025-06-14 05:00:00');

Invalide — 2025-06-15 14:30:00 ne correspond pas à une limite horaire exacte :

INSERT INTO ingestion_sale_detail_hourly (shop_name, total_price, _partitiontime)
VALUES ('beijing_shop', 50005.5, TIMESTAMP '2025-06-15 14:30:00');

Erreur renvoyée :

FAILED: ODPS-0130071:[0,0] Semantic analysis exception - physical plan generation failed:
SQL Runtime Unretryable Error: ODPS-0121095:Invalid argument - illegal ingestion time: 2025-06-15 14:30:00

Exemple 3 : Table partitionnée par jour — spécifier uniquement _partitiontime

Pour les tables partitionnées par jour, fournissez uniquement _partitiontime. Il n'est pas possible de spécifier _partitiondate dans une instruction INSERT.

Valide — 2025-06-18 00:00:00 correspond au début de la journée :

INSERT INTO ingestion_sale_detail_daily (shop_name, total_price, _partitiontime)
VALUES ('beijing_shop', 50005.5, TIMESTAMP '2025-06-18 00:00:00');

Invalide — 2025-06-18 14:00:00 ne correspond pas au début de la journée :

INSERT INTO ingestion_sale_detail_daily (shop_name, total_price, _partitiontime)
VALUES ('beijing_shop', 50005.5, TIMESTAMP '2025-06-18 14:00:00');

Erreur renvoyée :

FAILED: ODPS-0130071:[0,0] Semantic analysis exception - physical plan generation failed:
SQL Runtime Unretryable Error: ODPS-0121095:Invalid argument - illegal ingestion time: 2025-06-18 14:00:00

Invalide — spécification directe de _partitiondate :

INSERT INTO ingestion_sale_detail_daily (shop_name, total_price, _partitiondate)
VALUES ('beijing_shop', 50005.5, DATE '2025-06-15');

Erreur renvoyée :

FAILED: ODPS-0130071:[1,64] Semantic analysis exception - column _partitiondate cannot be resolved;
Did you mean _partitiontime ?

Interroger une table partitionnée par heure d'ingestion

Tous les exemples ci-dessous interrogent les tables créées dans la section Créer une table partitionnée par heure d'ingestion.

Deux comportements importants à garder à l'esprit :

L'instruction SELECT * ne renvoie not _partitiontime, _partitiondate ni la colonne de partition générée. Vous devez les spécifier explicitement pour les inclure dans le résultat.

Utilisez _partitiontime dans les clauses WHERE pour activer l'élimination des partitions. Les expressions de filtre suivantes déclenchent l'élimination des partitions sur les tables partitionnées par heure d'ingestion : Pour la liste complète des expressions d'élimination prises en charge, consultez la rubrique Tables autopartitionnées basées sur des fonctions temporelles.

Granularité	Exemple de filtre
Heure	`WHERE _partitiontime >= TIMESTAMP '2025-06-18 07:00:00' AND _partitiontime < TIMESTAMP '2025-06-18 08:00:00'`
Mois	`WHERE _partitiontime >= TIMESTAMP '2025-06-01 00:00:00' AND _partitiontime < TIMESTAMP '2025-07-01 00:00:00'`
Année	`WHERE _partitiontime >= TIMESTAMP '2025-01-01 00:00:00' AND _partitiontime < TIMESTAMP '2026-01-01 00:00:00'`

Exemple 1 : SELECT de base — les pseudo-colonnes sont masquées par défaut

SELECT * FROM ingestion_sale_detail_hourly;

-- Result:
+---------------+-------------+
| shop_name     | total_price |
+---------------+-------------+
| shanghai_shop | 10001.1     |
| chongqin_shop | 20002.2     |
| hangzhou_shop | 30003.3     |
| shenzhen_shop | 40004.4     |
| chengdu_shop  | 60006.6     |
| beijing_shop  | 50005.5     |
+---------------+-------------+

Exemple 2 : Inclure explicitement les pseudo-colonnes et les colonnes de partition

Le fuseau horaire du projet est défini sur Asia/Shanghai (UTC+8). Étant donné que TRUNC_TIME convertit l'heure en UTC avant la troncature, sale_time (la clé de partition) accuse un retard de 8 heures par rapport à _partitiontime.

Interrogez la table partitionnée par heure :

SELECT *, _partitiontime, sale_time FROM ingestion_sale_detail_hourly;

-- Result:
+---------------+-------------+---------------------+---------------------+
| shop_name     | total_price | _partitiontime      | sale_time           |
+---------------+-------------+---------------------+---------------------+
| shanghai_shop | 10001.1     | 2025-06-18 15:00:00 | 2025-06-18 07:00:00 |
| chongqin_shop | 20002.2     | 2025-06-18 15:00:00 | 2025-06-18 07:00:00 |
| hangzhou_shop | 30003.3     | 2025-06-18 15:00:00 | 2025-06-18 07:00:00 |
| shenzhen_shop | 40004.4     | 2025-06-18 15:00:00 | 2025-06-18 07:00:00 |
| beijing_shop  | 50005.5     | 2025-06-15 14:00:00 | 2025-06-15 06:00:00 |
| chengdu_shop  | 60006.6     | 2025-06-14 05:00:00 | 2025-06-13 21:00:00 |
+---------------+-------------+---------------------+---------------------+

Interrogez la table partitionnée par jour :

SELECT *, _partitiontime, _partitiondate, sale_date FROM ingestion_sale_detail_daily;

-- Result:
+--------------+-------------+---------------------+----------------+-----------+
| shop_name    | total_price | _partitiontime      | _partitiondate | sale_date |
+--------------+-------------+---------------------+----------------+-----------+
| beijing_shop | 50005.5     | 2025-06-18 00:00:00 | 2025-06-18     | 2025-06-18|
+--------------+-------------+---------------------+----------------+-----------+

Voir aussi

Tables autopartitionnées basées sur des fonctions temporelles — règles d'élimination des partitions et expressions de filtre prises en charge
Référence de la fonction TRUNC_TIME — granularités prises en charge et détails sur la conversion UTC
Aperçu des tables partitionnées — comparaison entre les tables partitionnées par heure d'ingestion, les tables standard et les tables autopartitionnées
SHOW CREATE TABLE — inspection de la logique de génération des partitions pour toute table partitionnée par heure d'ingestion