Ler tabelas do Unity Catalog

Para executar consultas analíticas em tabelas no Databricks a partir do seu app AppKit, você precisa de um SQL warehouse (o compute SQL do Databricks). O Analytics plugin conecta seu handler a um: os arquivos SQL ficam em config/queries/, o warehouse os executa e as linhas tipadas são retornadas. Seu handler não verifica permissões.

As tabelas consultadas pelo warehouse são governadas pelo Unity Catalog (UC). O UC controla o namespace de três níveis (catalog.schema.object) e aplica grants, filtros de linha, máscaras de coluna e políticas ABAC (controle de acesso baseado em atributos) a cada acesso. Além das tabelas, o UC também governa views, visualizações materializadas, volumes, modelos, índices de vector search e funções registradas.

Pré-requisitos

• Databricks CLI v1.0.0+ com um perfil autenticado.
• Um app AppKit em execução. Consulte o guia rápido de Apps.
• Um SQL warehouse declarado como recurso do app no databricks.yml. O service principal do seu app recebe CAN_USE automaticamente ao vincular o recurso. As permissões de usuário final são tratadas abaixo.

O que o Analytics plugin lê

Todos os objetos do UC ficam em um namespace catalog.schema.object. Os objetos consultados por este plugin são:

• Tabelas (Delta e Iceberg).
• Views e visualizações materializadas.
• Streaming tables.
• Funções chamadas como SELECT my_catalog.my_schema.my_function(...).

Os demais objetos do UC utilizam outros plugins. Volumes (armazenamento de arquivos) passam pelo plugin Files. A lista completa de objetos do UC está em Securable objects.

Conecte o Analytics plugin

Registre o plugin em createApp. Ele expõe os endpoints do Analytics e lê as consultas de config/queries/, executando-as no SQL warehouse vinculado em app.yaml.

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

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

Vincule o SQL warehouse no app.yaml para que a plataforma defina DATABRICKS_WAREHOUSE_ID na inicialização:

env:
  - name: DATABRICKS_WAREHOUSE_ID
    valueFrom: sql-warehouse

O recurso correspondente fica em databricks.yml. Consulte Configuração do app para ver a lista completa de recursos e as chaves valueFrom.

Escreva os arquivos SQL

Coloque os arquivos .sql em config/queries/. O nome do arquivo sem a extensão .sql se torna a chave da 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;

O contexto de execução é definido pelo nome do arquivo:

• spend_summary.sql é executado como o service principal do app. O cache é compartilhado entre os usuários.
• spend_summary.obo.sql é executado como o usuário autenticado. O cache é individual por usuário. O Unity Catalog aplica os grants, os filtros de linha, as máscaras de coluna e as políticas ABAC desse usuário.

Para conhecer a API completa do plugin, incluindo tipos de parâmetros e streaming Arrow, consulte a referência do Analytics plugin.

Renderizar em React com 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 onde vêm os erros 403

A identidade associada a cada consulta é definida pelo nome do arquivo:

• Consultas com service principal (*.sql) usam o service principal do app. O SP precisa de SELECT nas tabelas subjacentes. Erros de permissão retornam 403 do warehouse.
• Consultas on-behalf-of-user (*.obo.sql) usam o usuário autenticado. O UC aplica os grants desse usuário automaticamente. Se o usuário não tiver SELECT, ou se um filtro de linha ou uma máscara de coluna ocultar os dados, a chamada retorna 403 ou devolve menos linhas. Você não precisa escrever a verificação de permissão.

Lakehouse Federation

O Lakehouse Federation faz com que fontes externas (Snowflake, BigQuery, Oracle, Redshift) apareçam como catálogos do UC. Depois de registradas, elas são tratadas como qualquer outra tabela do UC pelo Analytics plugin: mesma referência catalog.schema.table, mesmo arquivo SQL, mesmo OBO. O warehouse aplica filtros e agregações diretamente na fonte externa (pushdown) sempre que possível e lê os dados restantes no momento da consulta, sem persisti-los no UC. Consulte Lakehouse Federation para ver a lista de fontes, a configuração e a cobertura de pushdown por fonte.

Consultas em linguagem natural

Para perguntas e respostas em linguagem natural sobre tabelas do UC (conjuntos de dados curados, além de um repositório de conhecimento e de um sistema de IA composto que converte perguntas em SQL), use o Genie. Para ver uma configuração funcional, consulte o template Genie Conversational Analytics. O plugin do Genie está na seção Agent Bricks porque se trata de uma integração de agente, e não de SQL.

Próximos passos

Experimente Set Up Unity Catalog with External Storage para provisionar um catálogo ou Volume File Manager para adicionar UC Volumes ao seu app. Depois, explore Lakeflow Jobs para disparar execuções ou Pipelines and freshness para obter sinais de «última atualização».