Lire des tables Unity Catalog

Pour exécuter des requêtes analytiques sur des tables Databricks depuis votre application AppKit, vous avez besoin d'un SQL warehouse (le compute SQL de Databricks). L'plugin Analytics y relie votre handler : les fichiers SQL sont placés dans config/queries/, le warehouse les exécute et renvoie des lignes typées. Votre handler, lui, ne vérifie pas les permissions.

Les tables interrogées par le warehouse sont régies par Unity Catalog (UC). UC gère l'espace de noms à trois niveaux (catalog.schema.object) et applique à chaque accès les grants, les filtres de lignes, les masques de colonnes et les politiques ABAC (contrôle d'accès basé sur les attributs). Au-delà des tables, UC régit également les vues, les vues matérialisées, les volumes, les modèles, les index de recherche vectorielle et les fonctions enregistrées.

Prérequis

• Databricks CLI v1.0.0+ avec un profil authentifié.
• Une application AppKit en cours d'exécution. Voir Démarrage rapide des Apps.
• Un SQL warehouse déclaré comme ressource d'application dans databricks.yml. Le service principal de votre application se voit automatiquement attribuer CAN_USE lorsque vous liez la ressource. Les permissions des utilisateurs finaux sont traitées ci-dessous.

Ce que lit le plugin Analytics

Tous les objets UC résident dans un espace de noms catalog.schema.object. Les objets interrogés par ce plugin :

• Tables (Delta et Iceberg).
• Vues et vues matérialisées.
• Tables de streaming.
• Fonctions appelées avec SELECT my_catalog.my_schema.my_function(...).

Les autres objets UC relèvent d'autres plugins. Les volumes (stockage de fichiers) passent par le plugin Files. La liste complète des objets UC figure dans Securable objects.

Brancher le plugin Analytics

Enregistrez le plugin dans createApp. Il expose les endpoints Analytics et lit les requêtes depuis config/queries/ pour les exécuter sur le SQL warehouse que vous associez dans app.yaml.

import { analytics, createApp, server } from "@databricks/appkit";

await createApp({
  plugins: [server(), analytics({})],
});

Associez le SQL warehouse dans app.yaml afin que la plateforme définisse DATABRICKS_WAREHOUSE_ID au démarrage :

env:
  - name: DATABRICKS_WAREHOUSE_ID
    valueFrom: sql-warehouse

La ressource correspondante est déclarée dans databricks.yml. Consultez Configuration de l'application pour la liste complète des ressources et les clés valueFrom.

Rédiger les fichiers SQL

Placez vos fichiers .sql dans config/queries/. Le nom du fichier, sans l'extension .sql, devient la clé de la requête.

-- @param startDate DATE
-- @param endDate DATE
SELECT date_trunc('day', usage_date) AS day, SUM(usage_quantity) AS qty
FROM system.billing.usage
WHERE usage_date BETWEEN :startDate AND :endDate
GROUP BY 1
ORDER BY 1;

Le contexte d'exécution est déterminé par le nom du fichier :

• spend_summary.sql s'exécute sous l'identité du service principal de l'application. Le cache est partagé entre les utilisateurs.
• spend_summary.obo.sql s'exécute sous l'identité de l'utilisateur connecté. Le cache est propre à chaque utilisateur. Unity Catalog applique les grants, les filtres de lignes, les masques de colonnes et les politiques ABAC de cet utilisateur.

Pour l'API complète du plugin, y compris les types de paramètres et le streaming Arrow, consultez la référence du plugin Analytics.

Afficher les données dans React avec useAnalyticsQuery

import { useMemo } from "react";
import { sql } from "@databricks/appkit-ui/js";
import { useAnalyticsQuery } from "@databricks/appkit-ui/react";

export function SpendTable() {
  const params = useMemo(
    () => ({
      startDate: sql.date("2025-01-01"),
      endDate: sql.date("2025-12-31"),
    }),
    [],
  );

  const { data, loading, error } = useAnalyticsQuery("spend_summary", params);

  if (loading) return <p>Loading...</p>;
  if (error) return <p>{error}</p>;
  return (
    <ul>
      {data?.map((row) => (
        <li key={row.day}>
          {row.day}: {row.qty}
        </li>
      ))}
    </ul>
  );
}

D'où viennent les erreurs 403

L'identité associée à chaque requête est déterminée par le nom du fichier :

• Les requêtes du service principal (*.sql) utilisent le service principal de l'application. Le SP doit disposer du privilège SELECT sur les tables sous-jacentes. Les erreurs de permission renvoient un 403 depuis le warehouse.
• Les requêtes on-behalf-of-user (*.obo.sql) s'exécutent sous l'identité de l'utilisateur connecté. UC applique automatiquement ses grants. Si l'utilisateur ne dispose pas du privilège SELECT, ou si un filtre de lignes ou un masque de colonnes masque les données, l'appel renvoie un 403 ou moins de lignes. Vous n'avez pas à écrire la vérification des permissions.

Lakehouse Federation

Lakehouse Federation fait apparaître les sources externes (Snowflake, BigQuery, Oracle, Redshift) comme des catalogues UC. Une fois enregistrées, elles se comportent, pour le plugin Analytics, comme n'importe quelle autre table UC : même référence catalog.schema.table, même fichier SQL, même OBO. Le warehouse délègue autant que possible les filtres et les agrégations à la source externe, puis lit les données restantes au moment de la requête, sans les conserver dans UC. Consultez Lakehouse Federation pour la liste des sources, la configuration et la couverture du pushdown par source.

Requêtes en langage naturel

Pour les questions-réponses en langage naturel sur les tables UC (jeux de données curés, base de connaissances et système d'IA composite qui transforme les questions en SQL), utilisez Genie. Pour un exemple de configuration fonctionnelle, consultez le modèle Genie Conversational Analytics. Le plugin Genie figure dans la section Agent Bricks, car il s'agit d'une intégration d'agent et non d'une intégration SQL.

Et ensuite

Essayez Set Up Unity Catalog with External Storage pour provisionner un catalogue, ou Volume File Manager pour ajouter des UC Volumes à votre application. Explorez ensuite Lakeflow Jobs pour déclencher des traitements, ou Pipelines and freshness pour les indicateurs de « dernière mise à jour ».