Accéder aux données Iceberg depuis AlloyDB

Preview — Accès direct à Iceberg

Cette fonctionnalité est soumise aux "Conditions des offres de pré-DG" de la section "Conditions générales du service" des Conditions spécifiques du service. Les fonctionnalités pré-DG sont disponibles "en l'état" et peuvent avoir une prise en charge limitée. Pour en savoir plus, consultez les descriptions des étapes de lancement.

L'accès direct à Iceberg dans AlloyDB pour PostgreSQL vous permet d'interroger des données stockées au format de table Apache Iceberg dans Cloud Storage à partir de votre instance AlloyDB. Vous pouvez accéder aux ensembles de données Iceberg à l'aide des URI de bucket Cloud Storage ou du catalogue d'exécution Lakehouse. Pour accélérer les charges de travail analytiques, AlloyDB fournit un moteur de données en colonnes intégré qui optimise les analyses, les jointures et les agrégations. En s'intégrant au moteur de données en colonnes, l'accès direct à Iceberg vous permet d'exécuter des requêtes analytiques hautes performances sur votre data lakehouse sans avoir à créer, gérer ni maintenir des pipelines de données ETL (extraction, transformation et chargement) complexes.

Vous pouvez interroger des tables Iceberg à l'aide de commandes SQL standard, joindre des ensembles de données Iceberg à des tables opérationnelles dans AlloyDB et insérer des tables Iceberg dans le moteur de données en colonnes en mémoire pour accélérer les performances des requêtes.

Avantages

L'accès direct à Iceberg offre les avantages suivants :

• Accès au lakehouse sans ETL : interrogez des ensembles de données Iceberg externes sur place sans copier ni déplacer les données vers des systèmes d'analyse distincts.
• Requêtes transactionnelles et analytiques unifiées : joignez des données opérationnelles en temps réel stockées dans des tables de tas AlloyDB à des données historiques volumineuses stockées dans des tables Iceberg sur Cloud Storage.
• Intégration flexible du catalogue : accédez aux métadonnées des tables Iceberg à partir des chemins d'accès aux bucket Cloud Storage ou via le catalogue d'environnements d'exécution Lakehouse.
• Accélération des requêtes en colonnes : mettez en cache et renseignez les tables Iceberg dans la mémoire du moteur de données en colonnes AlloyDB pour un traitement analytique en moins d'une seconde.
• Interface SQL standard : utilisez la syntaxe PostgreSQL que vous connaissez pour interroger et analyser des tables Iceberg.

Fonctionnement de l'accès direct à Iceberg

L'accès direct à Iceberg utilise l'interface TAM (PostgreSQL Table Access Method) (USING iceberg) et s'intègre au planificateur et au framework d'exécution du moteur de données en colonnes AlloyDB.

Lorsque vous interrogez une table Iceberg, AlloyDB fonctionne dans l'un des modes suivants :

• Analyse directe (pour les lectures en flux continu) : AlloyDB lit les métadonnées et les fichiers de données les plus récents directement depuis Cloud Storage. Le moteur de colonnes traite les données en flux continu.
• Accélération du moteur de données en colonnes (pour les lectures mises en cache en mémoire) : lorsque vous renseignez une table Iceberg dans le moteur de données en colonnes AlloyDB à l'aide de la fonction google_columnar_engine_add(), la table est chargée dans le store orienté colonnes en mémoire. Les requêtes suivantes lisent à partir de la mémoire du moteur de stockage en colonnes, ce qui maximise le débit des requêtes et minimise la latence.

Diffusion d'instantanés et actualisation du cache

L'instantané de table Iceberg interrogé par AlloyDB dépend du mode de lecture :

• Analyse directe : AlloyDB exécute des requêtes sur le dernier instantané Iceberg. Lorsqu'une requête démarre, AlloyDB détermine le dernier instantané de table Iceberg disponible et lit les données de cet instantané, même dans une transaction REPEATABLE READ ou SERIALIZABLE. AlloyDB n'est pas compatible avec l'épinglage d'instantanés ni les requêtes à un moment précis entre les transactions.

  Par exemple, lorsque vous interrogez une table à l'aide d'une analyse directe, chaque instruction d'une transaction lit à partir du dernier instantané disponible :

  BEGIN TRANSACTION ISOLATION LEVEL SERIALIZABLE;
  SELECT * FROM customer_orders;
  -- If an external process commits a new Iceberg snapshot:
  SELECT * FROM customer_orders; -- Returns results from the new snapshot.
  COMMIT;
  

• Accélération du moteur de données en colonnes : AlloyDB exécute les requêtes sur l'instantané renseigné dans le moteur de données en colonnes. Si AlloyDB écrit de nouvelles données dans la table Iceberg sous-jacente dans Cloud Storage après le remplissage, les requêtes peuvent renvoyer des données obsolètes. Pour obtenir des données à jour après des opérations LMD sur la table sous-jacente, actualisez le cache à l'aide de la fonction google_columnar_engine_refresh().

Types de données acceptés

Lorsque vous définissez une table Iceberg dans AlloyDB, les noms de colonnes et les types de données de votre instruction LDD doivent correspondre aux types du schéma Iceberg sous-jacent.

L'accès direct à Iceberg est compatible avec les types de données Apache Iceberg suivants et leurs types AlloyDB correspondants :

Type de données Apache Iceberg	Type de données AlloyDB	Description
boolean	BOOLEAN	Conversion vectorisée au format compressé en octets
int	INT/INTEGER	Entier signé 32 bits
long	BIGINT	Entier signé de 64 bits
float	REAL/FLOAT4	Valeur à virgule flottante 32 bits à simple précision
double	DOUBLE PRECISION/FLOAT8	Valeur à virgule flottante 64 bits à double précision
decimal(P, S)	NUMERIC(P, S)/DECIMAL(P, S)	Valeur numérique à virgule fixe avec une précision de P et une échelle de S
string	TEXT/VARCHAR	Valeurs de chaîne UTF-8
date	DATE	Date du calendrier (année, mois, jour)
timestamp	TIMESTAMP	Code temporel sans fuseau horaire
timestamptz	TIMESTAMPTZ	Code temporel avec fuseau horaire

Limites

L'accès direct à Iceberg présente les limites suivantes :

• Disponibilité des versions de PostgreSQL : AlloyDB est compatible avec l'accès direct à Iceberg sur PostgreSQL 18 et versions ultérieures.
• Autorisations utilisateur : seuls les utilisateurs de base de données disposant du rôle alloydbsuperuser peuvent créer des tables Iceberg. Une fois la table créée, vous pouvez accorder des autorisations SELECT à d'autres utilisateurs pour qu'ils puissent interroger la table Iceberg.
• Opérations en lecture seule : AlloyDB n'accepte que les requêtes SELECT (DQL) sur les tables Iceberg. Il n'est pas compatible avec les opérations d'écriture (INSERT, UPDATE, DELETE, TRUNCATE).
• Version de la spécification Apache Iceberg : AlloyDB n'est pas compatible avec les fichiers de suppression Iceberg v2 (suppressions positionnelles et d'égalité) ni avec les vecteurs de suppression Iceberg v3.
• Compatibilité avec les formats de fichiers : l'accès direct à Iceberg est compatible avec les fichiers de données Parquet, ainsi qu'avec les fichiers de métadonnées JSON et Avro. Il n'est pas compatible avec les fichiers de données ORC.
• Gestion des versions des instantanés : les requêtes d'analyse directe s'exécutent sur le dernier instantané de la table Iceberg, et les requêtes accélérées par colonnes s'exécutent sur l'instantané renseigné. AlloyDB n'est pas compatible avec les requêtes à un moment précis.
• Évolution du schéma : AlloyDB n'accepte pas les opérations ALTER TABLE sur les tables Iceberg. La table Iceberg sous-jacente ne doit pas avoir subi de migration de schéma.
• Compatibilité avec les catalogues de métadonnées : l'accès direct à Iceberg est compatible avec les chemins d'accès directs aux bucket Cloud Storage (gs://) et les chemins d'accès au catalogue d'environnements d'exécution Lakehouse (bl://). Pour le catalogue d'environnements d'exécution Lakehouse, AlloyDB n'est compatible qu'avec le mode d'identifiants de l'utilisateur final. Il n'est pas compatible avec le mode de distribution des identifiants ni avec les autres catalogues REST.
• Buckets avec paiements du demandeur : AlloyDB n'est pas compatible avec les buckets Cloud Storage qui utilisent les paiements du demandeur.
• Contrainte de remplissage complet : AlloyDB n'est pas compatible avec le remplissage partiel des colonnes pour les tables Iceberg. Les tables doivent tenir dans la mémoire du moteur de stockage en colonnes ou dans l'espace SSD.
• Mémoire de tas de remplissage : le remplissage d'une table Iceberg contenant de grands groupes de lignes Parquet peut dépasser la limite de mémoire de tas de remplissage par nœud de calcul, en particulier sur les instances comportant moins de processeurs virtuels. Pour résoudre ce problème, consultez Le tas de mémoire du moteur de données en colonnes est plein.

Avant de commencer

Avant de créer et d'interroger des tables Iceberg, assurez-vous d'effectuer les opérations suivantes :

1. Créez un cluster AlloyDB exécutant PostgreSQL 18 ou une version ultérieure sur Google Cloud. Pour en savoir plus, consultez Créer un cluster.
2. Hébergez une table Apache Iceberg dans Cloud Storage ou enregistrée dans le catalogue d'environnements d'exécution Lakehouse :
   • Pour les chemins d'accès Cloud Storage, la structure de répertoires du bucket doit suivre la mise en page Apache Iceberg standard contenant les sous-répertoires data/ et metadata/, y compris les fichiers JSON de métadonnées et version-hint.text. Pour en savoir plus, consultez Créer un bucket.
   • Pour le catalogue d'environnements d'exécution Lakehouse, créez et enregistrez votre catalogue Iceberg en mode d'identifiants de l'utilisateur final. Pour en savoir plus, consultez Configurer le point de terminaison du catalogue REST Apache Iceberg.
3. Configurez les identifiants de base de données pour un utilisateur disposant du rôle alloydbsuperuser. Pour en savoir plus, consultez Rôle du groupe alloydbsuperuser.

Rôles requis

Pour permettre à AlloyDB de lire les données et les métadonnées Iceberg, vous devez accorder les rôles IAM requis au compte de service du cluster AlloyDB :

• Accès à Cloud Storage : attribuez le rôle de lecteur des objets de l'espace de stockage (roles/storage.objectViewer) sur le bucket Cloud Storage contenant vos données et métadonnées Iceberg.
• Accès BigLake (si vous utilisez le catalogue d'environnements d'exécution Lakehouse) : accordez le rôle Lecteur BigLake (roles/biglake.viewer) sur le projet hébergeant votre catalogue BigLake.

Pour trouver le compte de service du cluster, exécutez la commande gcloud beta alloydb clusters describe :

gcloud beta alloydb clusters describe CLUSTER_ID --region=REGION_ID

Remplacez les éléments suivants :

• CLUSTER_ID : ID du cluster AlloyDB.
• REGION_ID : emplacement du cluster AlloyDB. Exemple :us-east1 Pour obtenir la liste complète des régions, consultez Emplacements AlloyDB.

Le résultat contient un champ serviceAccountEmail, qui correspond au compte de service de ce cluster. Dans la console Google Cloud , vous trouverez le compte de service sur la page Présentation du cluster.

Pour attribuer le rôle "Lecteur des objets Storage" à l'aide de la gcloud CLI, exécutez la commande suivante :

gcloud storage buckets add-iam-policy-binding \
    gs://BUCKET_NAME \
    --member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \
    --role="roles/storage.objectViewer"

Si vous utilisez le catalogue d'environnements d'exécution Lakehouse, accordez le rôle Lecteur BigLake :

gcloud projects add-iam-policy-binding LAKEHOUSE_PROJECT_ID \
    --member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \
    --role="roles/biglake.viewer"

Remplacez les éléments suivants :

• BUCKET_NAME : nom du bucket Cloud Storage.
• LAKEHOUSE_PROJECT_ID : ID du projet Google Cloud dans lequel votre catalogue d'environnements d'exécution Lakehouse est hébergé.
• SERVICE_ACCOUNT_EMAIL : adresse e-mail du compte de service du cluster que vous avez trouvée dans le champ serviceAccountEmail.

Configurer des indicateurs de base de données

Pour activer le moteur de données en colonnes et l'accès direct à Iceberg, vous pouvez configurer des indicateurs de base de données sur votre instance AlloyDB. Définissez les indicateurs de base de données suivants sur votre instance :

Indicateur de base de données	Valeur	Description
google_columnar_engine.enabled	on	Active le moteur de données en colonnes AlloyDB.
google_columnar_engine.enable_iceberg_reads	on	Active l'accès direct à Iceberg. Leur activation nécessite le redémarrage de l'instance.
google_columnar_engine.memory_size_in_mb	SIZE_IN_MB	(Facultatif) Alloue de la mémoire au moteur de données en colonnes. Recommandé si vous prévoyez de remplir les tables Iceberg en mémoire.

Pour configurer ces options à l'aide de gcloud CLI, exécutez la commande gcloud alloydb instances update :

gcloud alloydb instances update INSTANCE_ID \
    --cluster=CLUSTER_ID \
    --region=REGION_ID \
    --database-flags=google_columnar_engine.enabled=on,google_columnar_engine.enable_iceberg_reads=on

Remplacez les éléments suivants :

• INSTANCE_ID : ID de votre instance AlloyDB.
• CLUSTER_ID : ID de votre cluster AlloyDB.
• REGION_ID : identifiant de la région de votre cluster AlloyDB.

Créer une table Iceberg dans AlloyDB

Pour exposer un ensemble de données Apache Iceberg dans AlloyDB, connectez-vous en tant qu'utilisateur disposant des droits alloydbsuperuser. Ensuite, créez une table à l'aide de la méthode d'accès à la table USING iceberg.

CREATE TABLE TABLE_NAME (
    COLUMN_NAME DATA_TYPE [, ...]
)
USING iceberg
WITH (
    uri = 'LOCATION_URI'
);

Remplacez les éléments suivants :

• TABLE_NAME : nom de la table à créer dans AlloyDB.
• COLUMN_NAME et DATA_TYPE : définitions des colonnes. Les noms et les types de colonnes doivent correspondre au schéma de la table Iceberg sous-jacente.
• LOCATION_URI : emplacement des métadonnées de la table Iceberg. Spécifiez l'un des formats suivants :
  • Chemin d'accès Cloud Storage direct : gs://BUCKET_NAME/PATH_TO_ICEBERG_TABLE
  • URI du catalogue d'environnements d'exécution Lakehouse : bl://projects/PROJECT_ID/catalogs/CATALOG_NAME/databases/DATABASE_NAME/tables/TABLE_NAME

Exemples

Les exemples suivants vous montrent comment créer des tables Iceberg dans AlloyDB.

Créer une table à partir d'un chemin d'accès Cloud Storage

L'exemple suivant crée une table nommée customer_orders, basée sur un ensemble de données Iceberg situé dans un bucket Cloud Storage :

CREATE TABLE customer_orders (
    order_id BIGINT,
    customer_id INT,
    order_status TEXT,
    total_amount DOUBLE PRECISION,
    order_date DATE,
    is_completed BOOLEAN
)
USING iceberg
WITH (
    uri = 'gs://my-iceberg-analytics-bucket/datasets/sales/customer_orders'
);

Créer une table à partir du catalogue d'environnements d'exécution Lakehouse

L'exemple suivant crée une table référençant une table Iceberg gérée par le catalogue d'environnements d'exécution Lakehouse :

CREATE TABLE customer_orders (
    order_id BIGINT,
    customer_id INT,
    order_status TEXT,
    total_amount DOUBLE PRECISION,
    order_date DATE,
    is_completed BOOLEAN
)
USING iceberg
WITH (
    uri = 'bl://projects/my-analytics-project/catalogs/sales_catalog/databases/retail_db/tables/customer_orders'
);

Interroger des données Iceberg

Une fois la table créée dans AlloyDB, vous pouvez l'interroger à l'aide d'instructions SQL standard SELECT avec des droits alloydbsuperuser. Vous pouvez éventuellement accorder des autorisations de lecture à un utilisateur sans droits alloydbsuperuser à l'aide de l'instruction GRANT. Par exemple, GRANT SELECT ON customer_orders TO normal_user.

Interroger les données

L'exemple suivant montre comment exécuter une requête :

SELECT
    customer_id,
    COUNT(order_id) AS total_orders,
    SUM(total_amount) AS total_spent
FROM customer_orders
WHERE is_completed = true
  AND order_date >= '2026-01-01'
GROUP BY customer_id
ORDER BY total_spent DESC
LIMIT 10;

Interroger des données Iceberg jointes avec des données opérationnelles

Vous pouvez combiner des données opérationnelles en temps réel résidant dans AlloyDB avec des données historiques résidant dans Iceberg :

SELECT
    c.customer_name,
    c.account_tier,
    COUNT(o.order_id) AS total_orders,
    SUM(o.total_amount) AS historical_spend
FROM customer_orders o
JOIN customers c ON o.customer_id = c.customer_id
WHERE o.is_completed = true
GROUP BY c.customer_name, c.account_tier
ORDER BY historical_spend DESC;

Importer des données dans une table locale

Pour créer une copie indépendante et accessible en écriture des données Iceberg dans l'espace de stockage AlloyDB local, exécutez CREATE TABLE ... AS SELECT, comme illustré dans l'exemple suivant :

CREATE TABLE local_customer_orders AS
SELECT * FROM customer_orders
WHERE order_date >= '2026-01-01';

Accélérer les requêtes à l'aide du moteur de données en colonnes

Pour les charges de travail analytiques nécessitant une latence ultra-faible, vous pouvez insérer la table Iceberg directement dans la mémoire du moteur de données en colonnes AlloyDB.

Remplir la table Iceberg dans le store orienté colonnes

Pour insérer toutes les colonnes d'une table Iceberg dans le moteur de données en colonnes AlloyDB, utilisez la fonction google_columnar_engine_add(). Exemple :

SELECT google_columnar_engine_add('customer_orders');

Pour ne renseigner que des colonnes spécifiques utilisées par vos requêtes, transmettez une liste de noms de colonnes séparés par une virgule comme deuxième argument. Exemple :

SELECT google_columnar_engine_add('customer_orders', 'customer_id,order_status');

Pour en savoir plus, consultez Ajouter des colonnes à l'aide de fonctions SQL.

Actualiser les données renseignées

Si vous écrivez de nouveaux instantanés dans l'ensemble de données Iceberg sous-jacent, actualisez la table pour recharger les dernières données dans le moteur de données en colonnes afin que les requêtes renvoient des résultats à jour :

SELECT google_columnar_engine_refresh('customer_orders');

Supprimer une table du magasin de données en colonnes

Pour supprimer une table Iceberg du magasin de colonnes et revenir à l'analyse directe :

SELECT google_columnar_engine_drop('customer_orders');

Surveiller et vérifier l'exécution des requêtes

Vous pouvez surveiller la façon dont AlloyDB exécute les requêtes sur les tables Iceberg et vérifier si les requêtes utilisent le moteur de données en colonnes en mémoire. Utilisez les vues système pour vérifier l'état de remplissage du cache et EXPLAIN pour inspecter les plans d'exécution des requêtes.

Vérifier l'état de la mise en cache colonnaire

Pour vérifier si une table Iceberg est renseignée dans le moteur de données en colonnes, interrogez la vue système g_columnar_relations :

SELECT relation_name, status
FROM g_columnar_relations
WHERE relation_name = 'customer_orders';

Une valeur status de USABLE confirme que la table est mise en cache dans la mémoire du moteur de données en colonnes.

Inspecter les plans d'exécution des requêtes avec EXPLAIN

Pour vérifier si une requête exploite le moteur de données en colonnes, utilisez l'instruction EXPLAIN :

EXPLAIN (ANALYZE, COSTS OFF)
SELECT SUM(total_amount)
FROM customer_orders
WHERE is_completed = true;

Le résultat indique l'exécution en colonnes via un nœud Custom Scan (ColumnarScan) sur la table :

Custom Scan (ColumnarScan) on customer_orders
  Filter: (is_completed = true)

Dépannage

Cette section explique comment résoudre les problèmes courants que vous pouvez rencontrer lorsque vous configurez et interrogez des tables Iceberg dans AlloyDB.

L'option google_columnar_engine.enable_iceberg_reads est désactivée

Cause : l'option de base de données pour l'accès direct à Iceberg est désactivée.

Correction recommandée : définissez les indicateurs de base de données google_columnar_engine.enabled=on et google_columnar_engine.enable_iceberg_reads=on dans votre instance, puis redémarrez l'instance.

Autorisation d'accès à Cloud Storage refusée

Cause : le compte de service du cluster AlloyDB ne dispose pas d'un accès en lecture au bucket Cloud Storage.

Correction recommandée : attribuez le rôle roles/storage.objectViewer au compte de service du cluster sur le bucket.

Autorisation d'accès au catalogue d'environnements d'exécution Lakehouse refusée

Cause : Le compte de service du cluster AlloyDB ne dispose pas d'un accès en lecture au catalogue d'environnements d'exécution Lakehouse.

Correction recommandée : attribuez le rôle roles/biglake.viewer au compte de service du cluster sur le projet Google Cloud hébergeant le catalogue d'environnements d'exécution Lakehouse.

Échec de la population en colonnes

Cause : La taille de la table Iceberg dépasse la mémoire et l'espace SSD disponibles dans le moteur de données en colonnes.

Correction recommandée : augmentez l'allocation de mémoire allouée au moteur de données en colonnes à l'aide du flag google_columnar_engine.memory_size_in_mb sur votre instance, ou augmentez la taille du cache de stockage du moteur de données en colonnes à l'aide du flag google_columnar_engine.storage_cache_size. Pour en savoir plus, consultez Configurer le cache de stockage pour le moteur de données en colonnes.

Le tas de population du moteur de données en colonnes est plein

Message d'erreur :

ERROR: Columnar engine population heap is full during population. Set
google_columnar_engine.population_heap_size_in_mb to a bigger value.

Cause : La mémoire requise pour remplir un grand groupe de lignes Parquet dépasse la limite de tas de population par nœud de calcul.

Correction recommandée : réduisez le nombre de nœuds de calcul de population parallèles afin que le processus de population puisse utiliser un tas plus important. Dans la session SQL où vous remplissez la table, définissez l'option google_job_scheduler.max_parallel_workers_per_job sur 0 avant d'appeler la fonction google_columnar_engine_add() :

SET google_job_scheduler.max_parallel_workers_per_job = 0;
SELECT google_columnar_engine_add('TABLE_NAME');

Remplacez TABLE_NAME par le nom de la table Iceberg dans AlloyDB.

Étapes suivantes

• En savoir plus sur le moteur de données en colonnes AlloyDB
• Découvrez comment configurer le moteur de données en colonnes.
• Choisissez comment accéder aux données BigQuery depuis AlloyDB.