Créer et gérer des ressources dans le catalogue du runtime Lakehouse

Lakehouse pour Apache Iceberg est compatible avec la gestion des ressources via le catalogue d'environnements d'exécution Lakehouse.

Ce catalogue partagé élimine la nécessité de gérer plusieurs catalogues pour les charges de travail Open Source sur différents moteurs de traitement des données. Les opérations compatibles incluent la création, l'affichage, la modification et la suppression de ressources telles que les espaces de noms et les tables.

Avant de commencer

  1. Vérifiez que la facturation est activée pour votre projet Google Cloud .

  2. Activez les API BigQuery, BigQuery Storage et Managed Service pour Apache Spark.

    Rôles requis pour activer les API

    Pour activer les API, vous avez besoin du rôle IAM Administrateur Service Usage (roles/serviceusage.serviceUsageAdmin), qui contient l'autorisation serviceusage.services.enable. Découvrez comment attribuer des rôles.

    Activer les API

Rôles requis

Pour obtenir les autorisations nécessaires pour gérer les ressources Apache Iceberg dans le catalogue du runtime Lakehouse, demandez à votre administrateur de vous accorder les rôles IAM suivants sur votre projet :

Pour en savoir plus sur l'attribution de rôles, consultez Gérer l'accès aux projets, aux dossiers et aux organisations.

Vous pouvez également obtenir les autorisations requises avec des rôles personnalisés ou d'autres rôles prédéfinis.

Créer des ressources de catalogue

Les sections suivantes expliquent comment créer des ressources dans le catalogue du runtime Lakehouse.

Créer des espaces de noms

Sélectionnez l'une des options suivantes :

API

Utilisez la méthode datasets.insert et spécifiez le champ ExternalCatalogDatasetOptions dans la ressource d'ensemble de données que vous transmettez.

{
  "datasetReference": {
    "projectId": "PROJECT_ID",
    "datasetId": "DATASET_ID"
  },
  "externalCatalogDatasetOptions": {
    "defaultStorageLocationUri": "URI",
    "parameters": {
      ...
    }
  },
  "location": "LOCATION"
}

Remplacez les éléments suivants :

  • PROJECT_ID : ID du projet contenant votre ensemble de données cible.
  • DATASET_ID : ID de votre ensemble de données cible.
  • URI : URI Cloud Storage de toutes les tables de l'ensemble de données.
  • LOCATION : emplacement BigQuery dans lequel vous souhaitez créer l'ensemble de données.

Apache Spark SQL 

CREATE NAMESPACE SPARK_CATALOG.NAMESPACE;

Remplacez les éléments suivants :

  • SPARK_CATALOG : nom de votre catalogue Apache Spark.
  • NAMESPACE : nom de votre nouvel espace de noms

Terraform 

provider "google" {
  project = "PROJECT_ID"
}

resource "google_bigquery_dataset" "default" {
  dataset_id = "DATASET_ID"
  location   = "LOCATION"

  external_catalog_dataset_options {
    default_storage_location_uri = "URI"
    parameters = {
      ...
    }
  }
}

Remplacez les éléments suivants :

  • PROJECT_ID : ID du projet contenant votre ensemble de données cible.
  • DATASET_ID : ID de votre ensemble de données cible.
  • LOCATION : emplacement BigQuery dans lequel vous souhaitez créer l'ensemble de données.
  • URI : URI Cloud Storage de toutes les tables de l'ensemble de données.

Créer des tables Apache Iceberg

Sélectionnez l'une des options suivantes :

API

Utilisez la méthode tables.insert et spécifiez le champ ExternalCatalogTableOptions dans la ressource de table que vous transmettez.

{
  "tableReference": {
    "projectId": "PROJECT_ID",
    "datasetId": "DATASET_ID",
    "tableId": "TABLE_ID"
  },
  "externalCatalogTableOptions": {
    "parameters": {
      "table_type": "iceberg",
      "metadata_location": "METADATA_URI"
    },
    "connection_id": "CONNECTION_ID"
  }
}

Remplacez les éléments suivants :

  • PROJECT_ID : ID du projet contenant votre table cible.
  • DATASET_ID : ID de l'ensemble de données contenant votre table cible.
  • TABLE_ID : ID de votre table cible.
  • METADATA_URI : URI Cloud Storage du dernier fichier de métadonnées Apache Iceberg. Exemple : gs://mybucket/mytable/metadata/1234.metadata.json.
  • CONNECTION_ID : ID de votre connexion à Cloud Storage.

Apache Spark SQL 

CREATE TABLE SPARK_CATALOG.NAMESPACE.TABLE
  (id bigint, data string) USING iceberg;

Remplacez les éléments suivants :

  • SPARK_CATALOG : nom de votre catalogue Apache Spark.
  • NAMESPACE : nom de votre espace de noms
  • TABLE : nom de votre nouvelle table.

Terraform 

resource "google_bigquery_table" "default" {
  deletion_protection = false
  dataset_id          = google_bigquery_dataset.default.dataset_id
  table_id            = "TABLE"

  external_catalog_table_options {
    storage_descriptor {
      location_uri  = "STORAGE_URI"
      input_format  = "org.apache.hadoop.mapred.FileInputFormat"
      output_format = "org.apache.hadoop.mapred.FileOutputFormat"
    }
    parameters = {
      "table_type"        = "iceberg"
      "metadata_location" = "METADATA_URI"
      "write.parquet.compression-codec" : "zstd"
      "EXTERNAL" : "TRUE"
    }
  }
}

Remplacez les éléments suivants :

  • TABLE : nom de la table cible.
  • STORAGE_URI : URI Cloud Storage où sont stockées les données de la table, commençant par gs://.
  • METADATA_URI : URI Cloud Storage du dernier fichier de métadonnées Apache Iceberg. Exemple : gs://mybucket/mytable/metadata/1234.metadata.json.

Afficher les ressources du catalogue

Les sections suivantes décrivent comment afficher les ressources dans le catalogue du runtime Lakehouse.

Afficher les espaces de noms

Sélectionnez l'une des options suivantes :

API

Utilisez la méthode datasets.list pour afficher tous les espaces de noms ou la méthode datasets.get pour afficher des informations sur un espace de noms défini.

Apache Spark SQL

Pour afficher tous les espaces de noms d'un catalogue, utilisez l'instruction suivante :

SHOW { DATABASES | NAMESPACES } IN SPARK_CATALOG;

Remplacez SPARK_CATALOG par le nom de votre catalogue Apache Spark.

Pour afficher des informations sur un espace de noms défini, utilisez l'instruction suivante :

DESCRIBE { DATABASE | NAMESPACE } [EXTENDED]
SPARK_CATALOG.NAMESPACE;

Remplacez les éléments suivants :

  • SPARK_CATALOG : nom de votre catalogue Apache Spark.
  • NAMESPACE : nom de votre espace de noms

Afficher des tables

Sélectionnez l'une des options suivantes :

API

Utilisez la méthode tables.list pour afficher toutes les tables d'un espace de noms ou la méthode tables.get pour afficher des informations sur une table définie.

Apache Spark SQL

Pour afficher toutes les tables d'un espace de noms, utilisez l'instruction suivante :

SHOW TABLES IN SPARK_CATALOG.NAMESPACE;

Remplacez les éléments suivants :

  • SPARK_CATALOG : nom de votre catalogue Apache Spark.
  • NAMESPACE : nom de votre espace de noms

Pour afficher des informations sur une table définie, utilisez l'instruction suivante :

DESCRIBE TABLE [EXTENDED]
SPARK_CATALOG.NAMESPACE.TABLE;

Remplacez les éléments suivants :

  • SPARK_CATALOG : nom de votre catalogue Apache Spark.
  • NAMESPACE : nom de votre espace de noms
  • TABLE : nom de votre table.

Modifier les ressources de catalogue

Les sections suivantes expliquent comment modifier les ressources dans le catalogue du runtime Lakehouse.

Mettre à jour les espaces de noms

Sélectionnez l'une des options suivantes :

API

Utilisez la méthode datasets.patch et mettez à jour le champ ExternalCatalogDatasetOptions dans la ressource d'ensemble de données. La méthode datasets.update n'est pas recommandée, car elle remplace l'intégralité de la ressource d'ensemble de données.

Apache Spark SQL

Utilisez l'instruction ALTER DATABASE.

Mettre à jour les tables Apache Iceberg

Sélectionnez l'une des options suivantes :

API

Utilisez la méthode tables.patch et mettez à jour le champ ExternalCatalogTableOptions dans la ressource de table. La méthode tables.update n'est pas recommandée, car elle remplace l'intégralité de la ressource de table.

Pour mettre à jour le schéma ou le fichier de métadonnées, utilisez la méthode tables.patch et définissez la propriété autodetect_schema sur "true" :

PATCH https://bigquery.googleapis.com/bigquery/v2/projects/PROJECT_ID/datasets/DATASET_ID/tables/TABLE_ID?autodetect_schema=true

Remplacez les éléments suivants :

  • PROJECT_ID : ID du projet contenant la table que vous souhaitez mettre à jour.
  • DATASET_ID : ID de l'ensemble de données contenant la table que vous souhaitez mettre à jour.
  • TABLE_ID : ID de la table que vous souhaitez mettre à jour.

Dans le corps de la requête, spécifiez la valeur mise à jour pour chaque champ. Par exemple, pour mettre à jour l'emplacement des métadonnées de la table Apache Iceberg, spécifiez la valeur mise à jour pour le champ metadata_location :

{
  "externalCatalogTableOptions": {
    "parameters": {"metadata_location": "METADATA_URI"}
  },
  "schema": null
}'

Remplacez METADATA_URI par l'URI Cloud Storage du dernier fichier de métadonnées Apache Iceberg. Exemple : gs://mybucket/mytable/metadata/1234.metadata.json.

Apache Spark SQL

Utilisez l'instruction ALTER TABLE.

Supprimer des ressources de catalogue

Les sections suivantes décrivent comment supprimer des ressources dans le catalogue du runtime Lakehouse.

Supprimer des espaces de noms

Sélectionnez l'une des options suivantes :

API

Exécutez la méthode datasets.delete. Définissez le paramètre deleteContents sur "true" pour supprimer les tables de votre espace de noms.

Apache Spark SQL 

DROP NAMESPACE SPARK_CATALOG.NAMESPACE;

Remplacez les éléments suivants :

  • SPARK_CATALOG : nom de votre catalogue Apache Spark.
  • NAMESPACE : nom de votre espace de noms

Supprimer des tables

Sélectionnez l'une des options suivantes :

API

Utilisez la méthode tables.delete et spécifiez le nom de la table. Cette méthode ne supprime pas les fichiers associés dans Cloud Storage.

Apache Spark SQL

Pour n'abandonner que la table, utilisez l'instruction suivante:

DROP TABLE SPARK_CATALOG.NAMESPACE.TABLE;

Remplacez les éléments suivants :

  • SPARK_CATALOG : nom de votre catalogue Apache Spark.
  • NAMESPACE : nom de votre espace de noms
  • TABLE : nom de la table à supprimer.

Pour abandonner la table et supprimer les fichiers associés dans Cloud Storage, utilisez l'instruction suivante :

DROP TABLE SPARK_CATALOG.NAMESPACE.TABLE PURGE;

Remplacez les éléments suivants :

  • SPARK_CATALOG : nom de votre catalogue Apache Spark.
  • NAMESPACE : nom de votre espace de noms
  • TABLE : nom de la table à supprimer.

Étapes suivantes