Como criar um catálogo de metadados para tabelas Delta em Lakehouse

João Barros 14 de August de 2026 4 min de leitura

Este tutorial mostra como criar um catálogo de metadados simples para organizar tabelas Delta no Lakehouse. Ter um catálogo ajuda a documentar, descobrir tabelas e garantir que as equipas utilizam esquemas e permissões corretos.

Pré-requisitos

Conta no Microsoft Fabric com permissões para criar Lakehouse e executar SQL e scripts.
Um Lakehouse com pelo menos uma tabela Delta existente.
Conhecimentos básicos de SQL e noções de PowerShell (opcional para automatização).

Passo 1: Definir o modelo de metadados

Antes de criar tabelas, pense quais campos são úteis: nome da tabela, localização (path), esquema (colunas), responsável, etiquetas e última actualização. Um modelo simples evita divergências e permite pesquisa.

-- Exemplo de esquema para a tabela de catálogo
CREATE TABLE IF NOT EXISTS metadata.catalog (
  table_name STRING,
  lakehouse_path STRING,
  schema_json STRING,
  owner STRING,
  tags ARRAY,
  last_updated TIMESTAMP
)
USING DELTA;

Passo 2: Criar a tabela de catálogo no Lakehouse

Use o endpoint SQL do Lakehouse (ou cadernos SQL) para criar a tabela Delta que guardará os metadados. Isto centraliza a informação e beneficia das características ACID da Delta.

-- Executar no notebook SQL ou no endpoint SQL
CREATE TABLE IF NOT EXISTS metadata.catalog (
  table_name STRING,
  lakehouse_path STRING,
  schema_json STRING,
  owner STRING,
  tags ARRAY,
  last_updated TIMESTAMP
)
USING DELTA;

Passo 3: Popular o catálogo com uma entrada manual

Adicione manualmente uma entrada para uma tabela Delta existente. Guarde o esquema em JSON para facilitar a utilização por ferramentas que consumam o catálogo.

INSERT INTO metadata.catalog VALUES (
  'sales_raw',
  '/lakehouse/finance/sales_raw',
  '{"columns":[{"name":"sale_id","type":"INT"},{"name":"amount","type":"DOUBLE"}] }',
  'joana.silva',
  array('finance','raw'),
  current_timestamp()
);

Passo 4: Automatizar a captura do esquema com SQL

Para evitar inserções manuais, extraia o esquema da tabela Delta e guarde-o em JSON. Este exemplo usa funções SQL para construir o JSON do esquema (exemplo genérico — adapte conforme o endpoint SQL disponível).

-- Exemplo: gerar esquema a partir de DESCRIBE TABLE e inserir no catálogo
-- 1) Obter descrição e transformar em JSON (pseudocódigo adaptável)
CREATE OR REPLACE TEMP VIEW v_schema AS
SELECT concat('{"name":"', col_name, '","type":"', data_type, '"}') as item
FROM (DESCRIBE TABLE sales_raw);

-- 2) Agregar em array/json e inserir
INSERT INTO metadata.catalog (table_name,lakehouse_path,schema_json,owner,tags,last_updated)
SELECT
 'sales_raw',
 '/lakehouse/finance/sales_raw',
 concat('[', string_join(collect_list(item), ','), ']'),
 'joana.silva',
 array('finance','raw'),
 current_timestamp()
FROM v_schema;

Passo 5: Actualizar entradas com MERGE (upsert)

Use MERGE para manter o catálogo sincronizado quando a tabela for alterada ou recriada. Assim evita duplicados e mantém last_updated correcto.

MERGE INTO metadata.catalog AS target
USING (SELECT 'sales_raw' AS table_name, '/lakehouse/finance/sales_raw' AS lakehouse_path,
              '[{"name":"sale_id","type":"INT"},{"name":"amount","type":"DOUBLE"}]' AS schema_json,
              'joana.silva' AS owner, array('finance','raw') AS tags, current_timestamp() AS last_updated) AS src
ON target.table_name = src.table_name
WHEN MATCHED THEN UPDATE SET
  lakehouse_path = src.lakehouse_path,
  schema_json = src.schema_json,
  owner = src.owner,
  tags = src.tags,
  last_updated = src.last_updated
WHEN NOT MATCHED THEN INSERT *;

Passo 6: Automatizar com PowerShell (opcional)

Para executar actualizações regulares, escreva um script PowerShell que chame o endpoint SQL e actualize o catálogo — útil para pipelines ETL/ELT.

# PowerShell: exemplo mínimo para chamar um endpoint SQL (pseudocódigo)
$endpointUrl = 'https://sqlendpoint.fabric...'  # adaptar
$query = "MERGE INTO metadata.catalog ..."  # colocar MERGE preparado
Invoke-RestMethod -Method Post -Uri $endpointUrl -Body @{query=$query} -Headers @{Authorization='Bearer TOKEN'}

Verificar o resultado

Confirme que a tabela metadata.catalog contém entradas e que schema_json corresponde ao esquema real. Execute consultas simples e compare com DESCRIBE TABLE.

SELECT * FROM metadata.catalog WHERE table_name = 'sales_raw';
DESCRIBE TABLE sales_raw;

Conclusão

Com um catálogo de metadados no Lakehouse fica mais fácil descobrir tabelas Delta, garantir consistência de esquemas e automatizar documentação. Próximos passos: expandir campos (linhas de responsabilidade, SLAs), integrar com Power BI para pesquisa ou ligar alertas quando o esquema muda. Dica: comece com entradas manuais e automatize quando o padrão estiver definido — que metadados considera mais úteis na sua organização?