Synchroniser les données BigQuery avec AlloyDB

Cette page explique comment synchroniser des tables de BigQuery avec votre instance AlloyDB pour PostgreSQL.

En synchronisant les données analytiques de BigQuery avec AlloyDB, vous pouvez créer des systèmes opérationnels qui bénéficient d'un accès transactionnel à faible latence à votre lac de données. Contrairement à un wrapper de données externes (FDW) qui interroge les données sur place, la table de synchronisation déplace les données vers le stockage AlloyDB pour des performances maximales.

AlloyDB propose les méthodes suivantes pour déplacer les données BigQuery vers votre instance :

  • Synchronisation ponctuelle : crée une copie indépendante et accessible en écriture de votre table BigQuery.

  • Synchronisation périodique (mise en miroir) : crée une table locale en lecture seule qui s'actualise automatiquement selon une planification, par exemple toutes les six heures ou tous les jours.

Considérations relatives aux performances et au fonctionnement

Lorsque vous utilisez des tables de synchronisation BigQuery, tenez compte des points suivants :

  • Utilisation des ressources : le déplacement des données consomme du processeur et de la mémoire. Pour les tables très volumineuses, envisagez de planifier les synchronisations en dehors des heures de pointe afin d'éviter d'affecter votre charge de travail transactionnelle principale.
  • Visibilité des données : lors d'une opération de remplacement, la table cible existante est supprimée et recréée à l'avance. Les requêtes effectuées pendant l'importation voient initialement une table vide, puis les données nouvellement importées apparaissent progressivement à mesure que les transactions par lot sont validées.

Avant de commencer

  1. Familiarisez-vous avec la façon dont bigquery_fdw gère les types de données BigQuery et les mappages de colonnes, car l'extension alloydb_sync utilise bigquery_fdw pour se connecter à BigQuery.
  2. Connectez-vous à votre Google Cloud compte. Si vous débutez sur Google Cloud, créez un compte pour évaluer les performances de nos produits en conditions réelles. Les nouveaux clients bénéficient également de 300 $ de crédits sans frais pour exécuter, tester et déployer des charges de travail.

  3. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  4. Verify that billing is enabled for your Google Cloud project.

  5. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  6. Verify that billing is enabled for your Google Cloud project.

  7. Activez les APIs Cloud nécessaires pour créer une instance AlloyDB et vous y connecter.

    Activer les API

  8. À l'étape Confirmer le projet , cliquez sur Suivant pour confirmer le nom du projet que vous allez modifier.

  9. À l'étape Activer les API, cliquez sur Activer pour activer les éléments suivants :

    • API AlloyDB
    • API Compute Engine
    • API Cloud Resource Manager
    • API Service Networking
    • API BigQuery Storage

    L'API Service Networking est requise si vous prévoyez de configurer la connectivité réseau à AlloyDB à l'aide d'un réseau VPC qui réside dans le même Google Cloud projet qu'AlloyDB.

    Les API Compute Engine et Cloud Resource Manager sont requises si vous prévoyez de configurer la connectivité réseau à AlloyDB à l'aide d'un réseau VPC réseau qui réside dans un autre Google Cloud projet.

  10. Assurez-vous de disposer d'une table BigQuery existante à partir de laquelle synchroniser les données. Pour en savoir plus, consultez Créer et utiliser des tables BigQuery.

Rôles requis

Pour accorder au compte de service du cluster AlloyDB l'accès à l'ensemble de données BigQuery, vous avez besoin des autorisations suivantes :

  • Lecteur de données BigQuery (roles/bigquery.dataViewer) ou tout rôle personnalisé disposant des autorisations bigquery.tables.get et bigquery.tables.getData. Lorsqu'il est accordé à un compte de service, ce rôle fournit des autorisations permettant de lire les données et les métadonnées de la table ou de la vue.
  • Utilisateur de sessions de lecture BigQuery (roles/bigquery.readSessionUser) ou tout rôle personnalisé disposant des autorisations bigquery.readsessions.create et bigquery.readsessions.getData. Permet de créer et d'utiliser des sessions de lecture.
  • Utilisateur de job BigQuery (roles/bigquery.jobUser) ou tout rôle personnalisé disposant des autorisations bigquery.jobs.create. Permet de créer et d'exécuter des jobs, y compris des jobs de requête.

Configurer l'extension

Avant de synchroniser les tables de BigQuery, activez l'extension requise et configurez la connexion à BigQuery.

  1. Créez l'extension.

    1. Connectez-vous à l'instance AlloyDB à l'aide du client psql en suivant les instructions de la section Connecter un client psql à une instance.

    2. Exécutez la commande suivante :

      CREATE EXTENSION IF NOT EXISTS alloydb_sync;

  2. Pour permettre à AlloyDB de s'authentifier auprès de BigQuery, créez le mappage utilisateur.

    CREATE EXTENSION IF NOT EXISTS bigquery_fdw;
CREATE SERVER IF NOT EXISTS BIGQUERY_SERVER_NAME FOREIGN DATA WRAPPER bigquery_fdw;
CREATE USER MAPPING IF NOT EXISTS FOR USER SERVER BIGQUERY_SERVER_NAME;

    Remplacez les éléments suivants :

    • USER: nom d'utilisateur de la base de données ou utilisateur IAM qui accède à la table BigQuery.
    • BIGQUERY_SERVER_NAME: identifiant unique du serveur BigQuery. Définissez-le une seule fois dans une base de données donnée. Vous pouvez remplacer BIGQUERY_SERVER_NAME par le nom de votre serveur.

Synchroniser une table BigQuery pour une exportation ponctuelle

Vous pouvez synchroniser une table BigQuery pour une exportation ponctuelle à l'aide de psql.

Synchroniser une table BigQuery ponctuellement à l'aide de psql

Pour créer une copie modifiable des données BigQuery, utilisez psql pour exécuter la alloydb_sync.import_bq_table fonction.

SELECT alloydb_sync.import_bq_table(
  'PROJECT_ID.DATASET_ID.TABLE_ID',
  'ALLOYDB_DESTINATION_TABLE_NAME',
  'ON_EXISTS',
  ARRAY['PRIMARY_KEY_COLUMN']
);

Remplacez les éléments suivants :

  • PROJECT_ID: ID du projet dans lequel réside l'ensemble de données BigQuery.
  • DATASET_ID: nom de l'ensemble de données BigQuery pour la table. Pour les tables Iceberg avec un nom en quatre parties, il s'agit de Catalog.Namespace.
  • TABLE_ID: nom de la table ou de la vue BigQuery.
  • ALLOYDB_DESTINATION_TABLE_NAME: nom de la table locale dans la base de données AlloyDB à créer et dans laquelle importer les données. Vous pouvez inclure le nom du schéma, par exemple public.local_sales.
  • ON_EXISTS: stratégie à utiliser si la table de destination existe déjà.
  • PRIMARY_KEY_COLUMN: liste facultative de noms de colonnes à utiliser comme clé primaire.

Exemple

L'exemple suivant montre comment synchroniser une table nommée transactions d'un ensemble de données BigQuery dans une nouvelle table AlloyDB nommée public.local_sales :

SELECT alloydb_sync.import_bq_table(
    'my-gcp-project.sales_data.transactions',
    'public.local_sales',
    'replace'
);
Paramètre on_exists

Le paramètre on_exists détermine comment la fonction gère la synchronisation si la table de destination existe déjà dans AlloyDB :

  • error : option par défaut. Arrête la synchronisation si la table de destination existe déjà.
  • skip : ignore la synchronisation si la table de destination existe déjà.
  • replace: remplace la table locale existante par des données actualisées de BigQuery.
Compatibilité avec les clés primaires

Si vous fournissez le paramètre facultatif primary_key en tant que tableau de texte, AlloyDB crée la table avec les colonnes spécifiées comme clé primaire.

SELECT alloydb_sync.import_bq_table(
    'my-gcp-project.sales_data.transactions',
    'public.local_sales',
    ARRAY['transaction_id']
);

Synchroniser une table BigQuery pour une exportation périodique

Vous pouvez synchroniser une table BigQuery pour une exportation périodique à l'aide de psql.

Créer une synchronisation périodique

Pour conserver une table en lecture seule qui reste synchronisée avec les données BigQuery, utilisez psql pour exécuter la fonction alloydb_sync.create_bq_sync_table.

SELECT alloydb_sync.create_bq_sync_table(
    'PROJECT_ID.DATASET_ID.TABLE_ID',
    'ALLOYDB_DESTINATION_TABLE_NAME',
    'REFRESH_INTERVAL',
    'ON_EXISTS',
    ARRAY['PRIMARY_KEY_COLUMN']
);

Remplacez les éléments suivants :

  • PROJECT_ID.DATASET_ID.TABLE_ID : nom complet de la table ou de la vue BigQuery, y compris l'ID du projet, l'ID de l'ensemble de données et l'ID de la table, séparés par des points. Pour les tables Iceberg avec un nom en quatre parties, DATASET_ID est représenté par Catalog.Namespace. Par exemple, my-gcp-project.sales_data.transactions.
  • ALLOYDB_DESTINATION_TABLE_NAME: nom de la table locale dans la base de données AlloyDB à créer et dans laquelle synchroniser les données.
  • REFRESH_INTERVAL: intervalle auquel AlloyDB actualise périodiquement les données de BigQuery, par exemple 12 hours.
  • ON_EXISTS: stratégie à utiliser si la table de destination existe déjà.
  • PRIMARY_KEY_COLUMN: liste facultative de noms de colonnes à utiliser comme clé primaire.

Exemple

L'exemple suivant montre comment créer un miroir de profil client qui s'actualise toutes les 12 heures :

SELECT alloydb_sync.create_bq_sync_table(
    'my-gcp-project.crm_data.profiles',
    'public.customer_mirror',
    '12 hours',
    'replace'
);

Surveiller et gérer les jobs

Une fois que vous avez lancé une synchronisation, vous pouvez suivre sa progression et gérer les jobs.

Vérifier l'état d'un job

Les synchronisations volumineuses peuvent prendre du temps. Vous pouvez suivre la progression, y compris les enregistrements traités et le temps d'exécution estimé, en interrogeant la vue job_status :

SELECT
    import_id,
    status,
    records_processed,
    total_records,
    error
FROM alloydb_sync.job_status;

Par exemple, pour annuler le job, exécutez la commande suivante :

SELECT alloydb_sync.cancel_import_job('85bb5dfa-dfb9-4017-9153-738f55abe4b1');

Arrêter et supprimer un job de synchronisation

Pour arrêter la mise en miroir d'une table BigQuery et supprimer la table locale, utilisez la fonction alloydb_sync.delete_bq_sync_table :

SELECT alloydb_sync.delete_bq_sync_table('public.customer_mirror');

Limites

Les limites suivantes s'appliquent lors de la synchronisation de tables à partir de BigQuery :

  • Cette fonctionnalité n'est compatible qu'avec PostgreSQL version 18.
  • Si vous DROP l'extension alloydb_sync, vous devez redémarrer l'instance avant de la recréer.
  • Les synchronisations s'exécutent dans une transaction. Si le job d'importation est interrompu ou échoue, le système restaure les données importées.
  • Si deux utilisateurs lancent des jobs de synchronisation en même temps avec les mêmes tables cibles, les tables peuvent s'écraser mutuellement.
  • Si une interruption se produit lors de l'importation initiale en arrière-plan pour une table de synchronisation nouvellement enregistrée, la table reste incomplète jusqu'à son prochain intervalle d'actualisation planifié. Pour résoudre ce problème, vous pouvez supprimer la table de synchronisation à l'aide de la fonction alloydb_sync.delete_bq_sync_table() et la recréer.
  • Les types BigQuery complexes tels que ARRAY, BYTES, VECTOR et GEOGRAPHY ne sont pas compatibles avec la synchronisation. Pour obtenir la liste complète, consultez Types de données BigQuery et mappages de colonnes compatibles.
  • Ne supprimez pas manuellement une table répliquée. Utilisez la fonction d'API alloydb_sync.delete_bq_sync_table() pour supprimer la table et les actualisations en toute sécurité.
  • Pour supprimer une base de données qui utilise l'extension alloydb_sync, vous devez utiliser DROP DATABASE ... WITH (FORCE).
  • Si la base de données Postgres plante lors de l'exécution d'une importation, les métadonnées peuvent rester bloquées à l'état RUNNING, ce qui bloque les futures importations. Vous devez exécuter manuellement UPDATE alloydb_sync.import_job_status SET status = 'FAILED' WHERE status = 'RUNNING'; pour les débloquer.

Tarifs

Lorsque vous synchronisez des données de BigQuery vers AlloyDB, vous êtes facturé selon la tarification des calculs de capacité BigQuery.

Une fois les données exportées, leur stockage dans AlloyDB vous est facturé. Pour en savoir plus, consultez Tarifs d'AlloyDB pour PostgreSQL.

Étape suivante