6 Guia do analista de dados do colibri

Este guia cobre o ritual de conexão ao lakehouse do Colibri para visualização, download de tabelas e consultas em SQL, R ou Python. Assume que você já seguiu o Guia de instalação e tem a credencial de visualizador (colibri-token-visualizador) configurada em .segredos.yml.

6.1 Sincronizar o catálogo local

Antes do primeiro uso (e sempre que quiser garantir que está vendo os dados mais recentes), baixe o catálogo meta.ducklake e os manifestos para a raiz do projeto:

colibri sincronizar

6.2 Explorar o catálogo pela interface gráfica

colibri lake ui

Abre a DuckDB UI local, conectada ao catálogo do Colibri — uma interface em estilo notebook, onde é possível rodar fragmentos de SQL um de cada vez, ver o resultado imediatamente, e inspecionar tipo de dado e percentual de valores faltantes por coluna. Os cadernos ficam salvos localmente para acessos futuros.

6.3 Explorar e consultar pela linha de comando

colibri lake tables                     # tabelas/views no catálogo, com contagem de linhas/parquets
colibri lake years <tabela>             # contagem de linhas por ano de uma tabela
colibri lake download <tabela>          # exporta uma tabela para parquet local
colibri lake query "<sql>"              # roda uma consulta SQL livre

Nota

O comando correto é colibri lake query, não colibri lake q — essa abreviação aparece por engano em alguns exemplos mais antigos.

Exemplo de validação, comparando a tabela mrt_pncp_comprasgov__resumo_anual com os totais publicados no painel “PNCP em Números”:

colibri lake query "SELECT * FROM lake.main_marts.mrt_pncp_comprasgov__resumo_anual ORDER BY ano_compra"

6.4 Tabelas disponíveis hoje

Tabela	Fonte	Atualização
`ncm_prefixos`	Portal Único Siscomex	Full replace quando há mudança
`int_pncp_comprasgov__compras`	comprasGOV (diário/mensal/anual)	Incremental, histórico versionado (SCD2) por `cod_compra`
`int_pncp_comprasgov__itens`	comprasGOV (diário/mensal/anual)	Incremental, histórico versionado (SCD2) por `id_compra_item`
`int_pncp_comprasgov__resultados`	comprasGOV (diário/mensal/anual)	Incremental, histórico versionado (SCD2) por `(id_compra_item, sequencial_resultado)`
`mrt_pncp_comprasgov__resumo_anual`	agregação de `int_pncp_comprasgov__compras`	Recalculada a cada execução

Use colibri docs para ver a documentação completa de todas as tabelas e colunas geradas pelos modelos dbt:

colibri docs                # gera e abre a documentação dos modelos dbt
colibri docs --sem-servidor # apenas gera, sem subir o servidor local

6.5 Conexão direta via R

library(DBI)
library(duckdb)

con <- dbConnect(duckdb())
dbExecute(con, "INSTALL httpfs; LOAD httpfs;")
dbExecute(con, "INSTALL ducklake; LOAD ducklake;")

dbExecute(con, "
  CREATE SECRET (
    TYPE s3,
    KEY_ID '<SUA ACCESS KEY>',
    SECRET '<SUA SECRET KEY>',
    ENDPOINT '<ACCOUNTID>.r2.cloudflarestorage.com',
    REGION 'auto',
    URL_STYLE 'path'
  );
")

dbExecute(con, "ATTACH 'ducklake:meta.ducklake' AS lake (DATA_PATH 's3://<BUCKET LAKE>/lake/');")

resultado <- dbGetQuery(con, "
  SELECT * FROM lake.main_marts.mrt_pncp_comprasgov__resumo_anual
  ORDER BY ano_compra
")

dbDisconnect(con, shutdown = TRUE)

6.6 Conexão direta via Python

import duckdb

con = duckdb.connect()
con.execute("INSTALL httpfs; LOAD httpfs;")
con.execute("INSTALL ducklake; LOAD ducklake;")

con.execute("""
    CREATE SECRET (
        TYPE s3,
        KEY_ID '<SUA ACCESS KEY>',
        SECRET '<SUA SECRET KEY>',
        ENDPOINT '<ACCOUNTID>.r2.cloudflarestorage.com',
        REGION 'auto',
        URL_STYLE 'path'
    );
""")

con.execute("ATTACH 'ducklake:meta.ducklake' AS lake (DATA_PATH 's3://<BUCKET LAKE>/lake/');")

df = con.execute("""
    SELECT * FROM lake.main_marts.mrt_pncp_comprasgov__resumo_anual
    ORDER BY ano_compra
""").df()

Também é possível usar o pacote pyducklake, que simplifica esses mesmos passos de ATTACH. As credenciais (endpoint, access_key, secret_key, bucket_lake) são as mesmas configuradas em .segredos.yml — veja o Guia de instalação.

6.7 Baixar tabelas para análise local

Se preferir trabalhar totalmente offline, baixe a tabela inteira em Parquet e leia-a com a ferramenta de sua preferência (pandas, arrow, data.table etc.):

colibri lake download mrt_pncp_comprasgov__resumo_anual