Connexion d'un entrepôt BigQuery

Ce guide vous accompagne dans la connexion d’un dataset Google BigQuery à Saiku Cloud. Quinze minutes si vous avez déjà un compte de service ; trente si vous devez également en créer un dans IAM.

Impact niveau : chaque niveau Saiku Cloud prend en charge BYOC BigQuery.

Pilote : Saiku Cloud embarque le pilote JDBC officiel BigQuery de Google (Apache 2.0, ~56 Mo shaded). L’authentification se fait via une clé JSON de compte de service — il n’existe pas de chemin d’authentification par mot de passe.

Ce dont vous aurez besoin

• Un projet Google Cloud avec BigQuery activé.
• Un dataset au sein de ce projet où résident vos données analytiques.
• La permission IAM Propriétaire ou équivalente pour créer un compte de service.

Étape 1 — Accès réseau (bonne nouvelle)

L’API BigQuery est un service géré par Google, joignable depuis tout hôte connecté à Internet. Aucune allowlist de pare-feu requise. L’IP de sortie de Saiku Cloud (87.99.153.244) est l’une des nombreuses qui frapperont l’API BigQuery ; l’edge de Google gère le routage de manière transparente.

Passez à l’étape 2.

Étape 2 — Créer un compte de service en lecture seule

Saiku Cloud a besoin de BigQuery Data Viewer (pour SELECT) + BigQuery Job User (pour l’exécution des requêtes).

Dans la console Google Cloud :

1. IAM & Admin → Service Accounts → Créer un compte de service.

2. Nom : saiku-read. Description : Accès en lecture seule Saiku Cloud.

3. Accordez les rôles :

   • BigQuery Data Viewer — limitez-le à des datasets spécifiques si vous voulez un accès plus strict (Data Viewer au niveau projet lit tous les datasets ; au niveau dataset, seulement celui-ci).
   • BigQuery Job User — doit être au niveau projet (BigQuery ne prend pas en charge Job User limité à un dataset).

4. Cliquez sur le compte de service créé → Clés → Ajouter une clé → Créer une nouvelle clé → JSON. Le navigateur télécharge un fichier <project>-<id>.json.

5. C’est l’identifiant — enregistrez-le dans votre gestionnaire de mots de passe. Il contient la clé privée.

Étape 3 — Construire l’URL JDBC

La forme (séparée par des points-virgules, PAS en querystring) :

jdbc:bigquery://https://www.googleapis.com/bigquery/v2:443;ProjectId=<PROJECT>;OAuthType=0;OAuthServiceAcctEmail=<SA_EMAIL>;OAuthPvtKey=<INLINE_PEM>;DefaultDataset=<DATASET>

Exemple concret avec PEM inline :

jdbc:bigquery://https://www.googleapis.com/bigquery/v2:443;ProjectId=my-analytics-prod;OAuthType=0;OAuthServiceAcctEmail=saiku-read@my-analytics-prod.iam.gserviceaccount.com;OAuthPvtKey=-----BEGIN PRIVATE KEY-----\nMIIEvQIBADANBgkqhkiG9w0BAQEF...-----END PRIVATE KEY-----;DefaultDataset=analytics

Carte des paramètres :

• https://www.googleapis.com/bigquery/v2:443 — l’endpoint API. Toujours celui-ci pour le service BigQuery public. Les endpoints Private Service Connect ont une forme différente (voir Enterprise : réseau privé).
• ProjectId= — votre ID de projet Google Cloud (l’alphanumérique de l’URL de console, pas le nom de projet).
• OAuthType=0 — auth par clé de compte de service. Autres valeurs : 1 (OAuth utilisateur — non pris en charge dans Saiku), 3 (Application Default Credentials — ne fonctionne que si le moteur a accès à ADC, ce qui n’est généralement pas vrai dans le déploiement Saiku Cloud hébergé).
• OAuthServiceAcctEmail= — l’e-mail du compte de service, copié depuis l’étape 2 sous-étape 4. Format : <saname>@<project>.iam.gserviceaccount.com.
• OAuthPvtKeyPath= OU OAuthPvtKey= — l’un ou l’autre.
  • OAuthPvtKeyPath=/path/to/key.json — le pilote lit le fichier à l’exécution. Ne fonctionne pas sur Saiku Cloud hébergé car vous ne pouvez pas déposer de fichiers sur le système de fichiers du conteneur du moteur.
  • OAuthPvtKey=<inline PEM> — le contenu littéral -----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY----- du champ private_key de la clé JSON, avec des \n littéraux entre les lignes. Utilisez ceci pour l’hébergement cloud.
• DefaultDataset= — le dataset BigQuery (le deuxième segment de project.dataset.table). Permet aux schemas de référencer des noms de table non qualifiés comme <Table name='sales'/> au lieu de qualifier complètement chaque référence. Requis pour que les schemas BYOC se chargent via Mondrian de Saiku Cloud (l’API de métadonnées du pilote ne résout les tables non qualifiées que lorsque ceci est défini).

Côté création de cube : propriétés schema/catalog pour l’introspection des métadonnées

Lorsque vous téléversez un XML de schema Mondrian via Saiku Cloud qui référence des tables BigQuery non qualifiées (par ex. <Table name='salary'/> plutôt que <Table name='salary' schema='analytics'/>), Saiku Cloud doit aussi connaître le dataset et le projet pour l’introspection des métadonnées JDBC. Ceux-ci sont passés comme propriétés de chaîne de connexion au niveau du wrapper Mondrian, en plus de l’URL ci-dessus :

• JdbcSchema=<dataset> — même valeur que DefaultDataset= dans l’URL.
• JdbcCatalog=<project> — même valeur que ProjectId= dans l’URL.

L’assistant de connexion de Saiku Cloud les dérive automatiquement des paramètres ProjectId= + DefaultDataset= de l’URL lorsque vous enregistrez la connexion, donc la plupart des clients ne les voient jamais. Mentionnés ici car la forme .sds du moteur sur disque les inclut, et ils apparaissent dans les journaux d’audit :

jdbc:mondrian:Jdbc='jdbc:bigquery://https://www.googleapis.com/bigquery/v2:443;ProjectId=my-analytics-prod;OAuthType=0;OAuthServiceAcctEmail=...;OAuthPvtKey=...;DefaultDataset=analytics';Catalog=file:/var/lib/saiku/data/<your-schema>.xml;JdbcDrivers=com.google.cloud.bigquery.jdbc.BigQueryDriver;JdbcSchema=analytics;JdbcCatalog=my-analytics-prod

Attention

Deux détails importants de forme si vous devez écrire ce .sds à la main (par ex. pour tester sur le moteur OSS) :

1. Encadrez l’URL JDBC interne par des apostrophes. Le parseur de chaîne de connexion de Mondrian utilise ; comme séparateur de propriété de premier niveau — le même séparateur que celui utilisé par le pilote BigQuery À L’INTÉRIEUR de son URL. Les apostrophes indiquent à Mondrian de préserver les ; internes au lieu de les découper. Sans elles, vous obtenez IllegalStateException: Invalid Auth type specified: -1 car Mondrian retire les paramètres côté BigQuery avant de passer l’URL au pilote.
2. JdbcSchema= et JdbcCatalog= vont À L’EXTÉRIEUR de l’URL entre apostrophes, au niveau des propriétés Mondrian (à côté de Catalog=, JdbcDrivers=). À l’intérieur de l’URL, ils seraient analysés par le pilote BigQuery et ignorés — ils n’importent qu’à la couche d’introspection des métadonnées de Mondrian.

Ces deux exigences sont documentées en détail dans les notes BigQuery-Mondrian avec le catalogue des modes de défaillance.

Extraire la clé privée du JSON

Le JSON téléchargé à l’étape 2 ressemble à :

{
  "type": "service_account",
  "project_id": "...",
  "private_key_id": "...",
  "private_key": "-----BEGIN PRIVATE KEY-----\nMIIEvQ...\n-----END PRIVATE KEY-----\n",
  "client_email": "...",
  ...
}

Extrayez la valeur de private_key, retirez les guillemets englobants, et voilà ce qui va dans OAuthPvtKey= (les échappements \n sont littéraux — gardez-les comme chaînes backslash-n, PAS comme des sauts de ligne réels).

Étape 4 — Connectez-vous via l’assistant Saiku Cloud

1. Connectez-vous à https://cloud.saiku.bi/.

2. Naviguez vers Connexions dans la barre latérale gauche.

3. Sous 1. Choisir le type d’entrepôt, cliquez sur la tuile BigQuery.

4. Renseignez :

   • URL JDBC — l’URL de l’étape 3.
   • Nom d’utilisateur — n’importe quoi (par ex. bigquery). Le pilote ignore ce champ ; l’auth est dans l’URL.
   • Mot de passe — n’importe quoi de non vide (par ex. unused-key-in-url). Également ignoré.

5. Cliquez sur Tester la connexion.

Attendez-vous à une bannière de résultat verte : ✓ Connection successful plus la version BigQuery détectée (quelque chose comme BigQuery 2.0). La première connexion BigQuery prend 5 à 10 secondes (échange de jeton + listing des datasets).

Étape 5 — Enregistrer la connexion

Même forme que tout autre dialecte — ressaisissez le placeholder du mot de passe, donnez-lui un libellé, enregistrez.

Attention

Stockage de la clé de compte de service. Saiku Cloud stocke le PEM inline dans l’enregistrement chiffré de la connexion à côté de l’URL JDBC. Vault Transit chiffre l’ensemble de l’identifiant au repos. La clé vit toujours dans la chaîne URL au moment du déchiffrement, mais jamais dans les variables d’environnement, jamais dans les logs, jamais dans les réponses des listes de connexion. Un chemin futur plus propre — extraire la clé dans Vault comme sa propre ressource et templatiser l’URL JDBC avec une référence résolue par Vault — est sur la feuille de route ; les clients arrivant aujourd’hui via le chemin inline pourront migrer de manière transparente quand cela arrivera.

Dépannage

✗ Connection failed (AUTH_FAILED)

• Formatage OAuthPvtKey — cause la plus courante. Le PEM doit inclure des \n littéraux entre les lignes (PAS de sauts de ligne réels). Vérifiez : la valeur doit commencer par -----BEGIN PRIVATE KEY-----\nMIIE... (backslash-n, pas un saut de ligne).
• Le compte de service n’a pas BigQuery Job User au niveau projet — même avec Data Viewer sur le dataset, BigQuery rejette les requêtes de comptes sans Job User au niveau projet.
• Compte de service désactivé ou supprimé — vérifiez la console IAM.

✗ Connection failed (DATABASE_NOT_FOUND)

ProjectId= est incorrect, ou le compte de service n’a aucun dataset visible dans ce projet. Vérifiez que l’ID de projet correspond à ce qui apparaît dans l’URL de la console Google Cloud.

✗ Connection failed (HOST_UNREACHABLE) ou (TIMEOUT)

L’API BigQuery est rarement injoignable ; consultez la page de statut GCP. Si GCP est en bonne santé, le segment d’URL https://www.googleapis.com/bigquery/v2:443 est probablement mal saisi — il doit être exact.

✗ Connection failed with "OAuthType=1 requires interactive OAuth"

Vous avez défini OAuthType=1 (OAuth utilisateur) au lieu de OAuthType=0 (compte de service). Basculez vers OAuthType=0 et fournissez une clé de compte de service.

Le cube s’affiche mais sans données

Le compte de service a BigQuery Job User (donc les requêtes réussissent) mais pas BigQuery Data Viewer sur le dataset (donc les requêtes renvoient des résultats vides). Ajoutez Data Viewer au niveau du dataset.

Toute autre chose

Faites une capture d’écran de l’assistant avec la bannière de résultat rouge visible (en particulier la ligne Kind: ...) et envoyez-la à support@saiku.bi.

Enterprise : réseau privé {#enterprise-private-network}

Pour les clients Enterprise, BigQuery prend en charge Private Service Connect — le trafic API BigQuery de votre tenant reste dans un réseau privé. L’endpoint URL JDBC passe de https://www.googleapis.com/bigquery/v2:443 à votre endpoint PSC. Contactez votre équipe de compte pour provisionner le peering.

Essayer avec FoodMart

Vous voulez tester Saiku Cloud avec ce dialecte avant de connecter vos propres données ? Téléchargez le jeu de données d’exemple FoodMart packagé pour BigQuery :

Jeu de données d’exemple FoodMart pour BigQuery