Cube.
js — Cours Complet | Guide Pratique 2026
[Link]
Cours Complet & Guide Pratique
Semantic Layer • Analytics • BI Headless
Version 1.6.x | Mai 2026
Page 1
[Link] — Cours Complet | Guide Pratique 2026
1. Introduction à [Link]
1.1 Qu'est-ce que [Link] ?
[Link] (ou Cube) est une plateforme open-source de couche sémantique (Semantic Layer)
conçue pour simplifier l'accès aux données analytiques. Il s'intercale entre vos bases de
données et vos outils de visualisation ou d'IA pour centraliser la logique métier de vos données.
💡 Définition clé
[Link] est un outil headless BI (Business Intelligence sans interface graphique imposée). Il expose
vos données via des API REST, GraphQL et SQL, que vous connectez ensuite à n'importe quel
frontend, tableau de bord ou agent IA.
1.2 Pourquoi utiliser [Link] ?
Les problèmes classiques que [Link] résout :
▸ Duplication de logique SQL dans plusieurs outils (dashboards, rapports, APIs)
▸ Requêtes analytiques lentes sans cache ni pré-agrégations
▸ Absence de gouvernance des données entre équipes
▸ Difficulté à exposer les données aux LLMs et agents IA
1.3 Architecture générale
[Link] repose sur 3 couches distinctes :
Composant Rôle Technologie
Cube Core (Backend) Modélisation, cache, pré- [Link] / Rust
agrégations, APIs
Cube Store Moteur de stockage columaire Rust
rapide
Cube SDK (Frontend) Client JS pour React, Vue, JavaScript / TypeScript
Angular
Page 2
[Link] — Cours Complet | Guide Pratique 2026
2. Installation
2.1 Prérequis
▸ [Link] ≥ 16.x (pour la méthode npm)
▸ Docker (pour la méthode conteneurisée — recommandée)
▸ Une base de données : PostgreSQL, MySQL, BigQuery, Snowflake, etc.
2.2 Méthode Docker (recommandée)
Créez un dossier de projet et lancez la commande suivante :
mkdir mon-projet-cube && cd mon-projet-cube
docker run -p 4000:4000 \
-p 15432:15432 \
-v ${PWD}:/cube/conf \
-e CUBEJS_DEV_MODE=true \
cubejs/cube
Ouvrez ensuite [Link] dans votre navigateur pour accéder au Developer
Playground.
2.3 Méthode npm
# Installer le CLI [Link] globalement
npm install -g cubejs-cli
# Créer un nouveau projet (ici avec PostgreSQL)
cubejs create mon-backend -d postgres
# Démarrer en mode développement
cd mon-backend
npm run dev
2.4 Configuration (.env)
Editez le fichier .env à la racine du projet pour configurer la connexion à votre base :
Page 3
[Link] — Cours Complet | Guide Pratique 2026
CUBEJS_API_SECRET=mon_secret_super_securise
CUBEJS_DB_TYPE=postgres
CUBEJS_DB_HOST=localhost
CUBEJS_DB_PORT=5432
CUBEJS_DB_NAME=ma_base
CUBEJS_DB_USER=mon_user
CUBEJS_DB_PASS=mon_mot_de_passe
CUBEJS_DEV_MODE=true
💡 Bases de données supportées
PostgreSQL, MySQL, MariaDB, MS SQL Server, BigQuery, Snowflake, Databricks, Amazon
Redshift, ClickHouse, MongoDB (via BI Connector), et bien d'autres.
3. Modélisation des Données (Schema)
3.1 Concepts fondamentaux
Le schéma de données est le cœur de [Link]. Il définit comment vos tables SQL sont
exposées comme des objets métier compréhensibles.
Concept Description Exemple
Cube Représente une table ou vue Commandes, Utilisateurs
SQL
Measure Donnée quantitative agrégeable Nombre de ventes, Revenu
total
Dimension Donnée catégorielle ou Statut, Région, Date
temporelle
Join Relation entre deux cubes Commandes → Utilisateurs
Segment Filtre réutilisable prédéfini Commandes actives
uniquement
3.2 Exemple de schéma complet
Fichier : schema/[Link]
cube(`Commandes`, {
sql: `SELECT * FROM orders`,
Page 4
[Link] — Cours Complet | Guide Pratique 2026
joins: {
Utilisateurs: {
sql: `${CUBE}.user_id = ${Utilisateurs}.id`,
relationship: `many_to_one`,
},
},
measures: {
count: {
type: `count`,
drillMembers: [id, createdAt],
},
totalRevenu: {
sql: `amount`,
type: `sum`,
format: `currency`,
},
revenuMoyen: {
sql: `${totalRevenu} / ${count}`,
type: `number`,
format: `currency`,
},
},
dimensions: {
id: {
sql: `id`,
type: `number`,
primaryKey: true,
},
statut: {
sql: `status`,
type: `string`,
},
createdAt: {
sql: `created_at`,
type: `time`,
},
},
segments: {
commandesTerminees: {
sql: `${CUBE}.status = 'completed'`,
},
},
});
3.3 Types de Measures
Type Usage
Page 5
[Link] — Cours Complet | Guide Pratique 2026
count Nombre de lignes
countDistinct Valeurs distinctes
sum Somme d'une colonne
avg Moyenne d'une colonne
min / max Valeur min ou max
number Calcul personnalisé (formule)
boolean Condition vraie ou fausse
4. Les APIs de [Link]
4.1 REST API
L'API REST est l'interface principale pour interroger [Link]. Les requêtes sont envoyées en
JSON.
POST /cubejs-api/v1/load
Authorization: Bearer <CUBEJS_API_TOKEN>
{
"query": {
"measures": ["[Link]", "[Link]"],
"dimensions": ["[Link]"],
"timeDimensions": [{
"dimension": "[Link]",
"granularity": "month",
"dateRange": "last 6 months"
}],
"order": { "[Link]": "asc" }
}
}
4.2 SQL API
[Link] expose une interface SQL compatible PostgreSQL (port 15432). Idéale pour les outils
BI classiques (Tableau, Metabase, DBeaver).
-- Connexion via psql
psql -h localhost -p 15432 -U cube
Page 6
[Link] — Cours Complet | Guide Pratique 2026
-- Requête SQL standard
SELECT
"[Link]",
"[Link]",
"[Link]"
FROM Commandes
WHERE "[Link]" >= '2025-01-01'
GROUP BY 1;
4.3 GraphQL API
L'API GraphQL est disponible sur /cubejs-api/v1/graphql. Elle permet une introspection typée du
modèle de données.
query {
cube {
commandes(
where: { statut: { equals: "completed" } }
orderBy: { createdAt: asc }
) {
count
totalRevenu
createdAt { month }
}
}
}
5. Cache et Pré-agrégations
5.1 Deux niveaux de cache
▸ Cache en mémoire : In-memory cache
◦ Actif par défaut en mode développement
◦ Durée de vie configurable via refreshKey
▸ Pré-agrégations : Cube Store (pré-agrégations)
◦ Résultats précalculés stockés dans Cube Store (moteur Rust columaire)
◦ Temps de réponse sub-seconde pour des millions de lignes
Page 7
[Link] — Cours Complet | Guide Pratique 2026
5.2 Définir une pré-agrégation
cube(`Commandes`, {
// ...
preAggregations: {
commandesParMois: {
measures: [[Link], [Link]],
dimensions: [[Link]],
timeDimension: [Link],
granularity: `month`,
refreshKey: {
every: `1 hour`,
},
},
},
});
💡 Performance
Les pré-agrégations peuvent réduire les temps de requête de plusieurs secondes à quelques
millisecondes, même sur des datasets de plusieurs milliards de lignes.
6. Intégration Frontend (React)
6.1 Installation du SDK
npm install --save @cubejs-client/core @cubejs-client/react recharts
6.2 Initialiser le client
import cubejs from '@cubejs-client/core';
const cubejsApi = cubejs(
[Link].REACT_APP_CUBEJS_TOKEN,
{ apiUrl: '[Link] }
);
6.3 Composant de graphique
import { QueryRenderer } from '@cubejs-client/react';
Page 8
[Link] — Cours Complet | Guide Pratique 2026
import { BarChart, Bar, XAxis, YAxis, Tooltip } from 'recharts';
const MonGraphique = () => (
<QueryRenderer
query={{
measures: ['[Link]'],
timeDimensions: [{
dimension: '[Link]',
granularity: 'month',
dateRange: 'last 6 months'
}]
}}
cubejsApi={cubejsApi}
render={({ resultSet }) => {
if (!resultSet) return <div>Chargement...</div>;
return (
<BarChart data={[Link]()}>
<XAxis dataKey='x' />
<YAxis />
<Tooltip />
<Bar dataKey='[Link]' fill='#2E86DE' />
</BarChart>
);
}}
/>
);
7. Sécurité et Authentification
7.1 Tokens JWT
[Link] utilise des tokens JWT pour authentifier les requêtes API. En production, générez des
tokens avec votre CUBEJS_API_SECRET.
const jwt = require('jsonwebtoken');
const token = [Link](
{
// Contexte de sécurité (filtrage par tenant)
userId: 42,
companyId: 'acme-corp',
},
[Link].CUBEJS_API_SECRET,
{ expiresIn: '7d' }
);
Page 9
[Link] — Cours Complet | Guide Pratique 2026
7.2 Row-Level Security (multi-tenant)
Utilisez le contexte de sécurité dans vos schémas pour filtrer automatiquement les données par
utilisateur ou organisation :
cube(`Commandes`, {
sql: `SELECT * FROM orders
WHERE company_id = '${SECURITY_CONTEXT.companyId}'`,
// Le SQL est automatiquement filtré
// selon le token JWT de l'utilisateur
});
8. Récapitulatif et Bonnes Pratiques
8.1 Flux de travail typique
▸ Connecter [Link] à votre base de données via .env
▸ Modéliser les données dans /schema avec cubes, measures, dimensions
▸ Tester les requêtes dans le Developer Playground (localhost:4000)
▸ Ajouter des pré-agrégations pour les requêtes fréquentes
▸ Exposer via REST, SQL ou GraphQL à vos outils et dashboards
▸ Sécuriser avec JWT + Row-Level Security en production
8.2 Bonnes pratiques
▸ Toujours définir une primaryKey dans chaque cube
▸ Utiliser des pré-agrégations pour toute requête > 1M de lignes
▸ Séparer les cubes par domaine métier (ventes, utilisateurs, produits...)
▸ Versionner vos schémas dans Git
▸ Ne jamais mettre CUBEJS_DEV_MODE=true en production
8.3 Comparaison des méthodes de déploiement
Méthode Avantage Inconvénient Cas d'usage
Docker Simple, isolé Moins flexible Dev & staging
npm/[Link] Intégration code Plus de config Projets existants
Page 10
[Link] — Cours Complet | Guide Pratique 2026
Cube Cloud Managé, scalable Payant Production enterprise
Kubernetes Haute dispo Complexe Large scale
Fin du cours — [Link] v1.6.x
Documentation officielle : [Link]
Page 11