Databricks Data Discovery: encontre dados com Genie antes de escrever SQL

ANÁLISE EDITORIAL

Encontrar a tabela certa costuma consumir mais tempo do que escrever a consulta. Em um workspace grande, nomes parecidos, catálogos diferentes e regras de acesso tornam perigoso adivinhar o caminho. Databricks Data Discovery orienta o agente a começar pelo Genie One para localizar dados, responder perguntas em linguagem natural e gerar SQL fundamentado no contexto governado do Databricks.

A Skill é mantida oficialmente pela Databricks no repositório databricks/databricks-agent-skills. A curadoria fixou o commit ca92a6cf4e0071c8d31dcaedfc1647e1e4f39a78, no qual o SKILL.md declara a versão 0.1.0. A API pública do GitHub mostrava 288 estrelas em 29 de agosto de 2026. A inclusão é uma exceção ao piso de mil estrelas por ser um projeto oficial, ativo, documentado e com licença que trata redistribuição. O número não é apresentado como sinal de popularidade.

Ilustração editorial exclusiva: a capa mostra camadas abstratas de dados atravessando um portal de governança e convergindo para um núcleo luminoso. Não é captura de tela, painel do Databricks, resultado de consulta, logotipo, prova de acesso ou selo de precisão.

O que esta Skill faz de verdade

A instrução funciona como roteador. Se o pedido é localizar tabelas, entender onde um dado vive, responder uma pergunta sobre os dados ou produzir uma primeira consulta SQL, ela direciona o trabalho ao Genie One. Para editar arquivos, criar jobs, alterar pipelines, executar DDL ou mexer em infraestrutura, devolve o trabalho ao agente de código e às Skills específicas do produto.

O fluxo principal usa databricks genie ask com uma etiqueta de sessão. O Genie pesquisa o que a identidade autenticada pode ver, consulta metadados e contexto semântico e pode executar SQL para fundamentar a resposta. A documentação oficial do Genie One MCP descreve a mesma família de capacidade em um servidor MCP gerenciado. A Skill oferece a rota pelo CLI, sem exigir que esse MCP esteja configurado.

Ela não concede acesso, não ignora Unity Catalog, não valida a qualidade de todos os dados e não garante que uma resposta esteja correta. O resultado depende da identidade, das permissões, do catálogo, da semântica disponível e da revisão da pergunta e do SQL.

Para quem serve

Serve a analistas, engenheiros de dados, equipes de produto e desenvolvedores que trabalham em workspaces Databricks e precisam descobrir a fonte correta antes de escrever consultas ou aplicações. É especialmente útil quando o usuário conhece o conceito de negócio, mas não sabe qual catálogo, esquema, tabela ou métrica o representa.

Também ajuda agentes que recebem pedidos como “onde estão as vendas aprovadas?”, “qual tabela contém o identificador do cliente?” ou “escreva SQL para a receita por destino”. Em vez de inventar nomes, a Skill preserva uma etapa de descoberta baseada no ambiente autorizado.

Não é uma Skill genérica de pesquisa na web nem uma ferramenta para analisar arquivos locais. Sem conta, workspace, CLI e permissão de leitura, ela continua sendo apenas documentação.

Compatibilidade e pré-requisitos

O módulo é Markdown para clientes compatíveis com Agent Skills. O frontmatter declara Databricks CLI 1.9.0 ou superior para o comando estável databricks genie ask. Em versões anteriores, a própria Skill indica o alias depreciado databricks experimental genie ask. Confirme a versão instalada e o --help antes de tratar o comando como disponível.

O fluxo exige um workspace Databricks, identidade autorizada e perfil autenticado. A documentação oficial de autenticação do CLI recomenda OAuth quando possível e explica perfis de usuário ou de principal de serviço. A página de perfis de configuração mostra como separar ambientes e testar cada perfil.

A Skill é filha de databricks-core. O pacote do Bastidores preserva somente este SKILL.md, LICENSE, NOTICE e ORIGEM.md. Portanto, a instalação funcional deve obter a Skill pai na origem oficial e revisar seu escopo. O ZIP não inclui CLI, plugin, servidor MCP, executáveis, scripts, dependências, credenciais ou dados.

Instalação recomendada

Comece pelo README fixado no commit auditado. Escolha a distribuição compatível com o seu cliente e instale primeiro em um projeto de teste. Preserve as pastas databricks-core e databricks-data-discovery, pois o módulo de descoberta depende da orientação de autenticação e do fallback manual da Skill pai.

Não copie o repositório inteiro para um ambiente sensível sem revisar o conjunto. Ele reúne muitas Skills e artefatos para diferentes produtos. Instale apenas os módulos necessários, compare o commit e leia o diff antes de atualizar.

O download local do Bastidores é documental e auditável. Ele não substitui a origem oficial nem constitui um instalador. A Databricks License limita o uso dos materiais à conexão com os Serviços Databricks e impõe condições de redistribuição. Leia LICENSE e NOTICE no ZIP antes de prosseguir.

Configuração antes do primeiro uso

Liste e valide os perfis sem exibir segredos. Escolha explicitamente workspace e ambiente, de preferência com nomes como desenvolvimento, homologação e produção. Evite depender silenciosamente do perfil padrão quando houver mais de um destino.

Use identidade de menor privilégio e comece com leitura. Tokens, client secrets e saídas sensíveis não devem entrar no prompt, em screenshots ou em logs. O guia oficial para autorizar acesso a recursos Databricks separa contas de usuário, principais de serviço e APIs de conta ou workspace. A documentação também informa que OAuth interativo usa armazenamento seguro do sistema operacional em ambientes compatíveis. Personal access tokens são opção legada e exigem cuidado adicional.

Defina o objetivo da pergunta, o período, a unidade e os filtros de negócio. “Receita por cliente” pode variar por moeda, status, devolução e data de reconhecimento. O agente precisa registrar essas escolhas, mesmo quando o Genie encontra as tabelas.

Primeiro uso seguro

Comece com uma pergunta não sensível e uma etiqueta de sessão clara. A Skill recomenda reutilizar a mesma etiqueta nos desdobramentos, pois isso preserva o contexto da conversa. Use uma etiqueta nova apenas quando quiser separar deliberadamente outro assunto.

databricks genie ask -s catalogo-teste "Quais tabelas públicas de demonstração descrevem viagens?"
databricks genie ask -s catalogo-teste "Mostre as colunas relevantes para destino e valor"
databricks genie ask -s catalogo-teste "Escreva uma consulta de exemplo, sem alterar dados" --include-sql

Revise o SQL antes de executar fora do fluxo controlado. Confirme catálogo, esquema, joins, filtros, período e volume. O primeiro resultado esperado é uma rota reproduzível para a fonte e uma consulta pequena, não uma extração ampla.

Como decidir entre Genie e o agente de código

Use Genie para localizar dados, responder perguntas sobre seu conteúdo, traçar tendências e gerar uma primeira consulta. Use o agente de código para gravar o arquivo SQL, editar notebook, criar dashboard, definir pipeline, versionar mudanças ou implementar uma aplicação.

DDL e operações de escrita ficam fora deste primeiro fluxo. Pedidos de CREATE, INSERT, UPDATE ou DELETE exigem autorização separada, plano de reversão e revisão humana. Uma pergunta de descoberta não deve se transformar silenciosamente em alteração.

Se o Genie não estiver disponível, confirme primeiro os comandos de ajuda. Só então use o fallback manual documentado pela Skill pai, com buscas em information_schema e consultas pequenas. Não adivinhe nomes de tabela por semelhança.

Resultado esperado

Um bom primeiro resultado registra perfil, workspace, pergunta, etiqueta de sessão, fontes encontradas, SQL produzido, limitações e horário. Quando a resposta cita dados, preserve o caminho de volta ao catálogo e a consulta executada.

Uma não resposta também é válida. Se a identidade não vê dados relevantes ou o Genie não encontra contexto suficiente, pare e relate o limite. Não repita a pergunta em variações até obter uma resposta conveniente.

O resultado não é prova de verdade de negócio. Valide amostras, definições e proprietários antes de publicar métricas ou decisões.

Permissões, privacidade e riscos

O Genie opera com os acessos da identidade autenticada. Isso reduz o risco de consultar fora da autorização, mas não elimina exposição indevida dentro do escopo concedido. Aplique menor privilégio, segregação por ambiente e revisão periódica das permissões.

Perguntas e resultados podem conter nomes de tabelas, métricas, clientes ou informações sensíveis. Não copie respostas completas para tickets públicos, prompts externos ou repositórios. Minimize dados e use exemplos sintéticos em testes.

O CLI e os Serviços Databricks têm seus próprios termos e telemetria. A licença do repositório não transfere direitos sobre dados do workspace. O ZIP próprio é documental e não contém credenciais nem dados.

Erros comuns

Usar o perfil errado. Informe o perfil e valide host e identidade antes de perguntar. Tratar acesso negado como dado inexistente. A ausência pode ser permissão, catálogo ou contexto, não prova de que a tabela não existe.

Executar SQL sem revisão. Mesmo uma consulta somente leitura pode varrer volume alto ou usar join incorreto. Limite amostra e período. Confundir Genie One com Genie Agent. A Skill trata descoberta ampla. Agentes Genie curados por domínio têm fluxo diferente.

Instalar somente a filha. Sem databricks-core, faltam autenticação, perfis e fallback manual. Apresentar 288 estrelas como adoção comprovada. A exceção editorial existe porque o mantenedor é oficial, não porque o número indica popularidade.

Versão, licença e origem verificadas

O snapshot auditado usa o commit ca92a6cf4e0071c8d31dcaedfc1647e1e4f39a78, ativo em 29/08/2026. A Skill declara versão 0.1.0 e compatibilidade com CLI 1.9.0 ou superior para o comando estável. Versões, nomes e disponibilidade podem mudar, por isso o commit permanece fixado.

A Databricks License permite redistribuição e sublicenciamento sob condições, mas restringe o uso dos materiais à utilização ou conexão com os Serviços Databricks, exige fornecer a licença e preservar avisos. O pacote inclui LICENSE e NOTICE sem alteração.

O ZIP documental tem SHA-256 39e4300bdf0d51973052d5ecc4ebad88ace9cd6d2bdc0ba282fb50d8731a23e1. Compare esse valor depois do download. Para atualizações, volte ao repositório oficial e repita a auditoria.

Checklist antes de automatizar

• Fixe commit, versão da Skill e versão do CLI.
• Instale também a Skill pai databricks-core.
• Confirme workspace, perfil, identidade e menor privilégio.
• Comece com pergunta não sensível e consulta pequena.
• Reveja catálogo, esquema, joins, filtros, período e volume.
• Separe descoberta de arquivos, DDL e qualquer escrita.
• Registre fontes, SQL, limitações e horário.
• Leia LICENSE e NOTICE antes de redistribuir ou usar.

Consulte também o catálogo de Skills do Bastidores da IA para módulos de banco de dados, qualidade e governança com finalidades diferentes.