Leer tablas de Unity Catalog

Para ejecutar consultas analíticas sobre tablas de Databricks desde tu aplicación de AppKit, necesitas un SQL warehouse (el compute de SQL de Databricks). El Analytics plugin conecta tu handler con uno: los archivos SQL van en config/queries/, el warehouse los ejecuta y devuelve filas tipadas. Tu handler no verifica permisos.

Las tablas que consulta el warehouse se rigen por Unity Catalog (UC). UC controla el espacio de nombres de tres niveles (catalog.schema.object) y aplica grants, filtros de filas, máscaras de columnas y políticas ABAC (control de acceso basado en atributos) en cada acceso. Además de las tablas, UC también gobierna vistas, vistas materializadas, volúmenes, modelos, índices de vector search y funciones registradas.

Requisitos previos

• Databricks CLI v1.0.0+ con un perfil autenticado.
• Una aplicación de AppKit en ejecución. Consulta la guía de inicio rápido de Apps.
• Un SQL warehouse declarado como recurso de la aplicación en databricks.yml. El service principal de tu aplicación obtiene CAN_USE automáticamente al vincular el recurso. Los permisos de los usuarios finales se explican más adelante.

Qué lee el Analytics plugin

Todos los objetos de UC residen en un espacio de nombres catalog.schema.object. Estos son los objetos que consulta el plugin:

• Tablas (Delta e Iceberg).
• Vistas y vistas materializadas.
• Tablas de streaming.
• Funciones invocadas como SELECT my_catalog.my_schema.my_function(...).

Los demás objetos de UC se usan con otros plugins. Los volúmenes (almacenamiento de archivos) se manejan a través del plugin Files. La lista completa de objetos de UC está en Securable objects.

Conecta el Analytics plugin

Registra el Analytics plugin en createApp. Expone endpoints de Analytics y lee las consultas de config/queries/ ejecutándolas en el SQL warehouse que vincules en app.yaml.

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

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

Vincula el SQL warehouse en app.yaml para que la plataforma defina DATABRICKS_WAREHOUSE_ID al iniciar:

env:
  - name: DATABRICKS_WAREHOUSE_ID
    valueFrom: sql-warehouse

El recurso correspondiente se define en databricks.yml. Consulta Configuración de la app para ver la lista completa de recursos y las claves valueFrom.

Escribe los archivos SQL

Coloca los archivos .sql en config/queries/. El nombre del archivo sin .sql pasa a ser la clave de la consulta.

-- @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;

El contexto de ejecución se define según el nombre del archivo:

• spend_summary.sql se ejecuta como el service principal de la app. La caché se comparte entre todos los usuarios.
• spend_summary.obo.sql se ejecuta como el usuario que inició sesión. La caché es por usuario. Unity Catalog aplica los permisos, los filtros de fila, las máscaras de columna y las políticas ABAC de ese usuario.

Para ver la API completa del plugin, incluidos los tipos de parámetros y el streaming con Arrow, consulta la referencia del Analytics plugin.

Renderizar en React con 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>
  );
}

De dónde vienen los errores 403

El nombre del archivo determina la identidad asociada a cada consulta:

• Las consultas con service principal (*.sql) usan el service principal de la app. El SP necesita SELECT sobre las tablas subyacentes. Los errores de permisos devuelven 403 desde el warehouse.
• Las consultas on-behalf-of-user (*.obo.sql) usan la identidad del usuario que inició sesión. UC aplica sus permisos automáticamente. Si el usuario no tiene SELECT, o si un filtro de filas o una máscara de columnas oculta los datos, la llamada devuelve un 403 o menos filas. No tienes que escribir la comprobación de permisos.

Lakehouse Federation

Lakehouse Federation hace que las fuentes externas (Snowflake, BigQuery, Oracle, Redshift) se muestren como catálogos de UC. Una vez registradas, el Analytics plugin las trata como cualquier otra tabla de UC: la misma referencia catalog.schema.table, el mismo archivo SQL, el mismo OBO. El warehouse delega (pushdown) filtros y agregaciones a la fuente externa siempre que es posible, y lee los datos restantes en el momento de la consulta sin persistirlos en UC. Consulta Lakehouse Federation para ver la lista de fuentes, la configuración y la cobertura de pushdown de cada fuente.

Consultas en lenguaje natural

Para preguntas y respuestas en lenguaje natural sobre tablas de UC (conjuntos de datos curados, más un almacén de conocimiento y un sistema de IA compuesto que convierte las preguntas en SQL), usa Genie. Para ver una configuración funcional, consulta la plantilla Genie Conversational Analytics. El plugin de Genie está en la sección de Agent Bricks porque es una integración de agentes, no de SQL.

Qué sigue

Prueba Configurar Unity Catalog con almacenamiento externo para aprovisionar un catálogo, o Volume File Manager para añadir volúmenes de UC a tu aplicación. Después, explora Lakeflow Jobs para disparar tareas, o Canalizaciones y actualidad de los datos para obtener señales de «última actualización».