Intégrer Gravitino à DLF - Data Lake Formation - Centre de documentation Alibaba Cloud

Connectez un catalogue Alibaba Cloud Data Lake Formation (DLF) à Apache Gravitino via le protocole REST Paimon pour gérer l'intégralité du cycle de vie des métadonnées de catalogue, de schéma et de table.

Prérequis

DLF est activé et un catalogue DLF existe. Consultez Créer un catalogue DLF.
Vous disposez d'une paire AccessKey RAM avec des autorisations d'écriture sur le catalogue. Consultez Configurer les permissions et Créer une AccessKey.
Apache Gravitino version 1.2.0 ou ultérieure est déployé. Il s'agit de la version minimale prenant en charge le catalogue REST Paimon.
L'instance (conteneur ou ECS) exécutant Gravitino se trouve dans la même région que DLF, et son VPC figure dans la liste d'autorisation VPC de DLF (Configuration VPC de confiance).

Remarque

Par défaut, DLF ne prend pas en charge l'accès via le réseau public. Pour accéder à DLF par Internet, consultez Connecter Gravitino à DLF via le réseau public.

Enregistrer un catalogue DLF dans Gravitino

Étape 1 : Créer un Metalake

Un Metalake constitue l'espace de noms de niveau supérieur dans Gravitino. Exécutez la commande suivante pour en créer un.

curl -X POST -H "Content-Type: application/json" \
  -d '{
    "name": "lakehouse",
    "comment": "Gravitino lakehouse for DLF Paimon integration",
    "properties": {}
  }' \
  http://localhost:8090/api/metalakes

Exemple de réponse :

{"code":0,"metalake":{"name":"lakehouse","comment":"...","properties":{"in-use":"true"},"audit":{...}}}

Étape 2 : Enregistrer le catalogue DLF Paimon

Enregistrez un catalogue DLF dans le Metalake en exécutant la commande suivante. Remplacez les espaces réservés des paramètres par vos valeurs réelles.

curl -X POST -H "Content-Type: application/json" \
  -d '{
    "name": "dlf_paimon",
    "type": "RELATIONAL",
    "provider": "lakehouse-paimon",
    "comment": "DLF Paimon catalog via REST",
    "properties": {
      "catalog-backend": "rest",
      "token-provider": "dlf",
      "dlf-region": "<your-region-id>",
      "dlf-access-key-id": "<your-access-key-id>",
      "dlf-access-key-secret": "<your-access-key-secret>",
      "warehouse": "<your-dlf-catalog-name>",
      "uri": "https://<your-region-id>-vpc.dlf.aliyuncs.com"
    }
  }' \
  http://localhost:8090/api/metalakes/lakehouse/catalogs

Paramètres requis

Paramètre

Description

Exemple

catalog-backend

Valeur fixe : rest

rest

token-provider

Valeur fixe : dlf

dlf

uri

<!--@p {"id":"i52c0ognqb6gi"}--br>Endpoint DLF. Utilisez l'endpoint VPC pour un accès interne ou l'endpoint public pour un accès via le réseau public. Consultez Endpoints et accès par réseau public

https://cn-hangzhou-vpc.dlf.aliyuncs.com

warehouse

Nom du catalogue DLF

demo_catalog

dlf-region

ID de la région où DLF est déployé. Consultez Endpoints et accès par réseau public

cn-hangzhou

dlf-access-key-id

Votre ID AccessKey

LTAI***

dlf-access-key-secret

Votre secret AccessKey

***

Vérifier la connexion au catalogue

Exécutez la commande suivante pour vérifier la connexion au catalogue. Un schéma Gravitino correspond à une base de données DLF.

curl http://localhost:8090/api/metalakes/lakehouse/catalogs/dlf_paimon/schemas

Exemple de réponse :

{
  "code": 0,
  "identifiers": [
    {"namespace":["lakehouse","dlf_paimon"],"name":"default"},
    {"namespace":["lakehouse","dlf_paimon"],"name":"system"}
  ]
}

Connecter Gravitino à DLF via le réseau public

Étape 1 : Activer l'accès par réseau public pour DLF

Activez l'accès par réseau public dans la console DLF. Consultez Endpoints et accès par réseau public.

Étape 2 : Mettre à jour la dépendance Paimon

Gravitino est fourni par défaut avec le JAR Paimon 1.2.0, qui ne prend en charge que l'ancien protocole de signature DLF et ne peut pas passer la vérification de signature requise par l'endpoint public. Vous devez mettre à jour la dépendance Paimon vers la version 1.4.1 ou ultérieure.

Deux méthodes de mise à jour sont disponibles, selon le mode de déploiement de Gravitino.

Méthode 1 : Remplacement à chaud dans un conteneur Docker

Utilisez cette méthode si Gravitino s'exécute en tant qu'image officielle ou dans un environnement conteneurisé (image de conteneur apache/gravitino:1.2.0).

# 1) Download the 6 paimon-* 1.4.1 JARs on the host
for f in paimon-api paimon-core paimon-common paimon-format paimon-codegen-loader paimon-hive-catalog; do
  curl -sLO "https://repo1.maven.org/maven2/org/apache/paimon/${f}/1.4.1/${f}-1.4.1.jar"
done

# 2) Back up the existing 1.2.0 JARs inside the container
for f in paimon-api paimon-core paimon-common paimon-format paimon-codegen-loader paimon-hive-catalog; do
  docker exec gravitino \
    mv /root/gravitino/catalogs/lakehouse-paimon/libs/${f}-1.2.0.jar \
       /root/gravitino/catalogs/lakehouse-paimon/libs/${f}-1.2.0.jar.bak
done

# 3) Copy the new JARs into the container
for f in paimon-api paimon-core paimon-common paimon-format paimon-codegen-loader paimon-hive-catalog; do
  docker cp ${f}-1.4.1.jar \
    gravitino:/root/gravitino/catalogs/lakehouse-paimon/libs/
done

# 4) Restart Gravitino to load the new classpath
docker restart gravitino

Remarque

Remarque Pour revenir en arrière, supprimez les fichiers -1.4.1.jar, renommez -1.2.0.jar.bak en *-1.2.0.jar et exécutez docker restart gravitino.

Méthode 2 : Compilation depuis les sources pour un déploiement autonome

Utilisez cette méthode pour le développement local, les environnements sans Docker ou le débogage au niveau du code source. Le serveur Gravitino s'exécute directement sur l'hôte en tant que processus bin/gravitino.sh.

Prérequis : JDK 17 ou version ultérieure.

# 1) Build the distribution from source (about 10-15 minutes for the first build)
cd /path/to/gravitino
./gradlew compileDistribution -PskipWeb=true -x test

# 2) Navigate to the output directory
cd distribution/package

# 3) Download and replace the 6 paimon-* 1.4.1 JARs
cd catalogs/lakehouse-paimon/libs
for f in paimon-api paimon-core paimon-common paimon-format paimon-codegen-loader paimon-hive-catalog; do
  mv ${f}-1.2.0.jar ${f}-1.2.0.jar.bak
  curl -sLO "https://repo1.maven.org/maven2/org/apache/paimon/${f}/1.4.1/${f}-1.4.1.jar"
done
cd ../../../   # Return to distribution/package

# 4) (Optional) Change the port if 8090 is already in use
sed -i '' 's/httpPort = 8090/httpPort = 8091/' conf/gravitino.conf   # macOS
# sed -i      's/httpPort = 8090/httpPort = 8091/' conf/gravitino.conf   # Linux

# 5) Start with JDK 17
./bin/gravitino.sh start

# Verify
curl -sf http://localhost:8091/api/version

Commandes de maintenance courantes : ./bin/gravitino.sh start | stop | restart | status. Les journaux se trouvent dans distribution/package/logs/gravitino-server.log.

Étape 3 : Configurer l'endpoint public

Après avoir mis à jour Paimon, définissez uri sur l'endpoint public lorsque vous enregistrez le catalogue DLF Paimon :

"uri": "https://dlfnext.<region>.aliyuncs.com"

Opérations sur les métadonnées

Opérations sur les schémas

Créer un schéma

curl -X POST -H "Content-Type: application/json" \
  -d '{"name":"demo_db","comment":"Demo database for Paimon tables","properties":{}}' \
  http://localhost:8090/api/metalakes/lakehouse/catalogs/dlf_paimon/schemas

Obtenir les détails d'un schéma

curl http://localhost:8090/api/metalakes/lakehouse/catalogs/dlf_paimon/schemas/demo_db

La réponse inclut des propriétés injectées par DLF, telles que location (chemin OSS), owner, createdAt et updatedAt.

Lister les schémas

curl http://localhost:8090/api/metalakes/lakehouse/catalogs/dlf_paimon/schemas

Supprimer un schéma

# cascade=true drops all tables under this schema
curl -X DELETE \
  "http://localhost:8090/api/metalakes/lakehouse/catalogs/dlf_paimon/schemas/demo_db?cascade=true"

Créer une table

Paimon prend en charge plusieurs types de tables, notamment les tables Append, les tables à clé primaire (PK) et les tables partitionnées.

Table Append

Les tables Append conviennent aux charges de travail en ajout seul, telles que les journaux d'événements et les flux CDC.

curl -X POST -H "Content-Type: application/json" \
  -d '{
    "name": "event_log",
    "comment": "Event log table (append-only)",
    "columns": [
      {"name":"event_id","type":"string","nullable":false,"comment":"Event ID"},
      {"name":"event_type","type":"string","nullable":false,"comment":"Event type"},
      {"name":"payload","type":"string","nullable":true,"comment":"Event payload"},
      {"name":"created_at","type":"timestamp","nullable":false,"comment":"Creation time"}
    ]
  }' \
  http://localhost:8090/api/metalakes/lakehouse/catalogs/dlf_paimon/schemas/demo_db/tables

Table à clé primaire (PK)

Les tables PK conviennent aux tables de dimension et aux tables d'état nécessitant des opérations d'upsert.

curl -X POST -H "Content-Type: application/json" \
  -d '{
    "name": "user_info",
    "comment": "User information table",
    "columns": [
      {"name":"user_id","type":"integer","nullable":false},
      {"name":"username","type":"string","nullable":false},
      {"name":"email","type":"string","nullable":true},
      {"name":"updated_at","type":"timestamp","nullable":true}
    ],
    "indexes": [
      {"indexType":"PRIMARY_KEY","name":"pk_user_id","fieldNames":[["user_id"]]}
    ]
  }' \
  http://localhost:8090/api/metalakes/lakehouse/catalogs/dlf_paimon/schemas/demo_db/tables

Table partitionnée

Les tables partitionnées conviennent aux tables de faits partitionnées par des champs métier tels que la date.

curl -X POST -H "Content-Type: application/json" \
  -d '{
    "name": "order_data",
    "comment": "Order data table (partitioned by date)",
    "columns": [
      {"name":"order_id","type":"string","nullable":false},
      {"name":"user_id","type":"integer","nullable":false},
      {"name":"amount","type":"double","nullable":true},
      {"name":"dt","type":"string","nullable":false}
    ],
    "partitioning": [
      {"strategy":"identity","fieldName":["dt"]}
    ],
    "indexes": [
      {"indexType":"PRIMARY_KEY","name":"pk_order","fieldNames":[["order_id"],["dt"]]}
    ]
  }' \
  http://localhost:8090/api/metalakes/lakehouse/catalogs/dlf_paimon/schemas/demo_db/tables

Interroger des tables

# List all tables in a schema
curl http://localhost:8090/api/metalakes/lakehouse/catalogs/dlf_paimon/schemas/demo_db/tables

# Get table details (column definitions, partitions, primary keys, Paimon internal properties)
curl http://localhost:8090/api/metalakes/lakehouse/catalogs/dlf_paimon/schemas/demo_db/tables/user_info

Modifier une table

Les exemples ci-dessous modifient la table user_info pour illustrer les opérations sur les colonnes.

BASE=http://localhost:8090/api/metalakes/lakehouse/catalogs/dlf_paimon/schemas/demo_db/tables/user_info

Ajouter une colonne

Trois options de position sont disponibles.

Ajouter à la fin : Définissez position sur "default".

curl -X PUT -H "Content-Type: application/json" \
  -d '{"updates":[{"@type":"addColumn","fieldName":["phone"],"type":"string","comment":"phone","position":"default","nullable":true}]}' \
  $BASE

Ajouter au début : Définissez position sur "first".

curl -X PUT -H "Content-Type: application/json" \
  -d '{"updates":[{"@type":"addColumn","fieldName":["row_id"],"type":"long","comment":"row id","position":"first","nullable":true}]}' \
  $BASE

Ajouter après une colonne spécifique : Définissez position sur {"after":"<colName>"}.

curl -X PUT -H "Content-Type: application/json" \
  -d '{"updates":[{"@type":"addColumn","fieldName":["nickname"],"type":"string","comment":"nick","position":{"after":"username"},"nullable":true}]}' \
  $BASE

Renommer une colonne

curl -X PUT -H "Content-Type: application/json" \
  -d '{"updates":[{"@type":"renameColumn","oldFieldName":["phone"],"newFieldName":"mobile"}]}' \
  $BASE

Supprimer une colonne

curl -X PUT -H "Content-Type: application/json" \
  -d '{"updates":[{"@type":"deleteColumn","fieldName":["mobile"],"ifExists":true}]}' \
  $BASE

Autres opérations de modification

Opération

Description

rename

Renommer une table

updateComment

Mettre à jour le commentaire de la table

setProperty / removeProperty

Définir ou supprimer une propriété de table

updateColumnType

Modifier le type d'une colonne

updateColumnComment

Mettre à jour le commentaire d'une colonne

updateColumnNullability

Modifier la possibilité de valeur nulle d'une colonne

updateColumnPosition

Réorganiser les colonnes

updateColumnDefaultValue

Modifier la valeur par défaut d'une colonne

Supprimer une table

Le protocole REST Paimon nécessite purge=true, ce qui supprime à la fois les métadonnées et les fichiers de données OSS.

curl -X DELETE \
  "http://localhost:8090/api/metalakes/lakehouse/catalogs/dlf_paimon/schemas/demo_db/tables/event_log?purge=true"