Synchroniser les données BigQuery avec AlloyDB

Cette page vous explique comment synchroniser des tables depuis BigQuery vers votre instance AlloyDB pour PostgreSQL.

En synchronisant les données analytiques de BigQuery dans 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 dans le stockage AlloyDB pour des performances maximales.

AlloyDB propose les méthodes suivantes pour transférer des données BigQuery dans votre instance :

  • La synchronisation unique crée une copie indépendante et modifiable de votre table BigQuery.

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

Considérations sur les performances et le fonctionnement

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

  • Utilisation des ressources : le transfert de données consomme du processeur et de la mémoire. Pour les très grandes tables, envisagez de planifier les synchronisations pendant les heures creuses 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 exécutées pendant l'importation affichent initialement une table vide, puis les nouvelles données 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 et les mappages de colonnes BigQuery, car l'extension alloydb_sync utilise bigquery_fdw pour se connecter à BigQuery.
  2. Connectez-vous à votre compte Google Cloud . 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. Pour confirmer le nom du projet que vous allez modifier, à l'étape Confirmer le projet, cliquez sur Suivant.

  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 projet Google Cloud 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ésidant dans un autre projet Google Cloud .

  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 à l'ensemble de données BigQuery l'accès au compte de service du cluster AlloyDB, vous devez disposer 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 permet 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 tâche 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 requêtes.

Configurer l'extension

Avant de synchroniser des tables depuis BigQuery, activez l'extension requise et configurez la connexion à BigQuery. Si vous utilisez la console Google Cloud , AlloyDB effectue ces étapes automatiquement.

  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 base de données ou utilisateur IAM accédant à 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 unique

Vous pouvez synchroniser une table BigQuery pour une exportation unique à l'aide de la consoleGoogle Cloud ou de psql.

Utiliser la console Google Cloud

Pour synchroniser une table BigQuery avec AlloyDB à l'aide de la consoleGoogle Cloud  :

  1. Ouvrez la page BigQuery dans la console Google Cloud .

    Accéder à la page "BigQuery"

  2. Dans le volet de gauche, cliquez sur Explorateur :

    Si le volet de gauche ne s'affiche pas, cliquez sur Développer le volet de gauche pour l'ouvrir.

  3. Dans le volet Explorateur, développez votre projet, cliquez sur Ensembles de données, puis sur votre ensemble de données.

  4. Cliquez sur Présentation > Tables, puis sélectionnez un tableau.

  5. Dans le volet d'informations, cliquez sur Importer Exporter / Synchroniser > AlloyDB (exporter une fois ou synchroniser).

  6. Sous Choisir un cluster cible, sélectionnez l'une des options suivantes :

    • Sélectionnez Utiliser un cluster existant pour exporter la table BigQuery vers un cluster AlloyDB existant. Ensuite, procédez comme suit :

      1. Sélectionnez le cluster AlloyDB principal.

      2. Sélectionnez la base de données AlloyDB de destination.

      3. Sélectionnez le schéma de votre table AlloyDB de destination.

      4. Spécifiez un nom pour votre table AlloyDB de destination.

      5. Pour la fréquence de synchronisation, sélectionnez Une seule fois pour créer une copie de la table BigQuery.

      6. Cliquez sur Configurer l'exportation.

      Une fois la configuration de la synchronisation terminée, vous pouvez utiliser les instructions SQL fournies pour suivre le job d'importation et interroger les tables importées. Cliquez sur Requête pour accéder à votre table importée dans AlloyDB Studio.

    • Sélectionnez Créer un cluster pour exporter la table BigQuery vers un nouveau cluster AlloyDB. Ensuite, procédez comme suit :

      1. Cliquez sur Configurer l'exportation.

      2. Dans la boîte de dialogue Rediriger vers AlloyDB, sélectionnez Rediriger.

      3. Sélectionnez un type de cluster : Cluster d'essai sans frais ou Cluster provisionné.

      4. Cliquez sur Continuer.

      5. Dans Configuration de la synchronisation, sélectionnez la base de données AlloyDB de destination postgres par défaut, le schéma public par défaut pour votre table AlloyDB de destination, puis spécifiez un nom pour votre table AlloyDB de destination.

        Pour la fréquence de synchronisation, sélectionnez Une seule fois pour créer une copie de la table BigQuery.

      6. Cliquez sur Continuer.

      7. Configurez votre cluster. Pour en savoir plus sur chaque champ, consultez Créer un cluster et une instance principale.

      8. Cliquez sur Créer un cluster.

      Une fois la configuration de la synchronisation terminée, accédez à AlloyDB Studio pour interroger vos tables importées.

Synchroniser une table BigQuery une seule fois à l'aide de psql

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

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 à créer dans la base de données AlloyDB 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 à partir 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 la façon dont 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 de nouvelles données issues de BigQuery.
Compatibilité avec les clés primaires

Si vous fournissez le paramètre facultatif primary_key sous forme de 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 l'exporter régulièrement à l'aide de la consoleGoogle Cloud ou de psql.

Utiliser la console Google Cloud

Pour synchroniser une table BigQuery avec AlloyDB à l'aide de la consoleGoogle Cloud  :

  1. Ouvrez la page BigQuery dans la console Google Cloud .

    Accéder à la page "BigQuery"

  2. Dans le volet de gauche, cliquez sur Explorateur :

    Bouton du volet Explorateur mis en évidence.

    Si le volet de gauche ne s'affiche pas, cliquez sur Développer le volet de gauche pour l'ouvrir.

  3. Dans le volet Explorateur, développez votre projet, cliquez sur Ensembles de données, puis sur votre ensemble de données.

  4. Cliquez sur Présentation > Tables, puis sélectionnez un tableau.

  5. Dans le volet d'informations, cliquez sur Importer Exporter / Synchroniser > AlloyDB (exporter une fois ou synchroniser).

  6. Sous Choisir un cluster cible, sélectionnez l'une des options suivantes :

    • Sélectionnez Utiliser un cluster existant pour exporter la table BigQuery vers un cluster AlloyDB existant. Ensuite, procédez comme suit :

      1. Sélectionnez le cluster AlloyDB principal.

      2. Sélectionnez la base de données AlloyDB de destination.

      3. Sélectionnez le schéma de votre table AlloyDB de destination.

      4. Spécifiez un nom pour votre table AlloyDB de destination.

      5. Pour Fréquence de synchronisation, sélectionnez une période pour créer une synchronisation périodique de la table BigQuery (par exemple, Toutes les heures ou Toutes les six heures).

      6. Cliquez sur Configurer l'exportation.

      Une fois la configuration de la synchronisation terminée, vous pouvez utiliser les instructions SQL fournies pour suivre le job d'importation et interroger la table importée. Cliquez sur Requête pour accéder à votre table importée dans AlloyDB Studio.

    • Sélectionnez Créer un cluster pour exporter la table BigQuery vers un nouveau cluster AlloyDB. Ensuite, procédez comme suit :

      1. Cliquez sur Configurer l'exportation.

      2. Dans la boîte de dialogue Rediriger vers AlloyDB, sélectionnez Rediriger.

      3. Sélectionnez un type de cluster : Cluster d'essai sans frais ou Cluster provisionné.

      4. Cliquez sur Continuer.

      5. Dans Configuration de la synchronisation, sélectionnez la base de données AlloyDB de destination postgres par défaut, le schéma public par défaut pour votre table AlloyDB de destination, puis spécifiez un nom pour votre table AlloyDB de destination.

        Pour la fréquence de synchronisation, sélectionnez Une seule fois pour créer une copie de la table BigQuery.

      6. Cliquez sur Continuer.

      7. Configurez votre cluster. Pour en savoir plus sur chaque champ, consultez Créer un cluster et une instance principale.

      8. Cliquez sur Créer un cluster.

      Une fois la configuration de la synchronisation terminée, accédez à AlloyDB Studio pour interroger vos tables importées.

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 de la base de données AlloyDB dans laquelle créer et synchroniser les données.
  • REFRESH_INTERVAL : intervalle auquel AlloyDB actualise régulièrement 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 la synchronisation lancée, vous pouvez suivre sa progression et gérer les tâches.

Vérifier l'état d'une tâche

Les synchronisations volumineuses peuvent prendre du temps. Vous pouvez suivre la progression, y compris les enregistrements traités et le temps estimé avant la fin de l'opération, 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');

Mappages des types de données

Lorsque vous synchronisez ou importez des données de BigQuery vers AlloyDB à l'aide de l'extension alloydb_sync, AlloyDB mappe les types de données BigQuery aux types de données PostgreSQL correspondants dans votre table cible.

Vérifiez que les colonnes de votre table BigQuery source utilisent les types de données compatibles suivants.

Le tableau suivant liste les mappages des types de données entre BigQuery et AlloyDB.

Types de données des table BigQuery Types de données recommandés pour les tables externes PostgreSQL

BOOLEAN

BOOLEAN

INTEGER (INT64)

BIGINT

FLOAT (FLOAT64)

DOUBLE PRECISION

STRING

VARCHAR

NUMERIC

NUMERIC(38, 9)

NUMERIC(P[, S])

NUMERIC(P, S)

BIGNUMERIC

NUMERIC(77, 38)

BIGNUMERIC(P[, S])

NUMERIC(P, S)

DATE

DATE

TIMESTAMP

TIMESTAMPTZ

TIME

TIME

JSON

JSONB

BYTES

BYTEA

GEOGRAPHY

GEOGRAPHY(POINT), ...

Pour en savoir plus, consultez PostGIS_Geography.

DATETIME

TIMESTAMP

ARRAY

VECTOR(N)

N correspond à la dimension du vecteur. Vous devez définir l'option bigquery_fdw.enable_vector_downcasting dans la session. Étant donné que le type VECTOR dans AlloyDB utilise le type float4, vous risquez de perdre en précision lors de cette conversion.

Pour en savoir plus, consultez l'extension pgvector.

Limites

Les limites suivantes s'appliquent lors de la synchronisation des tables depuis 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 recréer l'extension.
  • 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 risquent de s'écraser mutuellement.
  • Si une interruption se produit lors de l'importation en arrière-plan initiale d'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 les types de données BigQuery et les 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 actualiser les données de manière sécurisée.
  • 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 pendant l'exécution d'une importation, les métadonnées peuvent rester bloquées à l'état RUNNING, ce qui bloque les importations futures. Vous devez exécuter manuellement UPDATE alloydb_sync.import_job_status SET status = 'FAILED' WHERE status = 'RUNNING'; pour le débloquer.

Tarifs

Lorsque vous synchronisez des données de BigQuery vers AlloyDB, la facturation est basée sur les tarifs de BigQuery pour les lectures en flux continu (API Storage Read).

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

Étapes suivantes