Quarto Para Paper Duck

O que é quarto para paper duck e como ele funciona na prática

O termo quarto para paper duck se refere a um conjunto de técnicas e ferramentas voltadas para manipulação e otimização de arquivos DuckPond em ambiente Quarto. Basicamente, é um fluxo de trabalho que combina geração de documentos reprodutíveis com manipulação de datasets estruturados no formato DuckDB. Se você já tentou rodar múltiplas análises em paralelo e se deparou com erros de concorrência ou conflitos de memória, provavelmente já encontrou esse problema de maneira indireta. Para começar, você precisa ter o Quarto instalado. A versão mínima recomendada é a 1.4, pois as versões anteriores têm bugs conhecidos na manipulação de conexões DuckDB em contextos de múltiplos filhos. Rode quarto --version para verificar. Depois, instale o pacote duckdb no seu ambiente R ou Python, dependendo da stack que você vai usar. A configuração do arquivo _quarto.yml merece atenção. O campo execute-dir precisa estar definido como project, senão os caminhos relativos para os arquivos temporários do DuckDB ficam errados e o pipeline quebra silenciosamente. Eu já perdi meio dia caçando um bug assim porque o Quarto resolvia os caminhos antes de trocar de diretório de execução. O arquivo fica mais ou menos assim:

_quarto.yml project:   type: manuscript

execute:   freeze: auto   execute-dir: project

Isso garante que os arquivos temporários sejam criados sempre no mesmo lugar, o que evita conflitos entre células que compartilham o mesmo banco DuckDB.

O fluxo de trabalho na prática

O ponto central do quarto para paper duck é usar uma única instância de DuckDB como banco centralizado enquanto múltiplas células ou arquivos geram visualizações e tabelas diferentes. A ideia é evitar repetir carregamento de dados. Em vez de abrir o mesmo CSV cinco vezes, você abre uma vez, cria views ou tabelas temporárias, e todas as células compartilham a mesma conexão. O problema é que o Quarto, por padrão, executa cada célula em um contexto isolado em certos modos de renderização. Isso significa que o objeto de conexão que você criou na célula 1 não existe na célula 4. A solução mais simples é usar o parâmetro .duckdb_connection como variável de sessão ou, alternativamente, definir o modo de execução como cache: persistent no YAML. Com cache persistente, o estado do interpretador é mantido entre as células e a conexão sobrevive. Um caso específico que eu encontrei: estava processando um dataset de 4 gigabytes com colunas de texto não normalizado. A conexão DuckDB criava arquivos WAL (write-ahead log) em /tmp e, em servidores com restrição de espaço em tmpfs, o processo travava sem mensagem de erro clara. O Quarto simplesmente parava de responder. A solução foi forçar o diretório de work mem com PRAGMA work_mem = '512MB' e redirecionar o para um path em disco físico, usando PRAGMA temp_directory = '/var/tmp/duckdb_work'. Isso resolveu em cinco minutos.

Pegadinhas avançadas que ninguém conta

O primeiro problema que iniciantes sempre encontram é a serialização de conexões DuckDB entre notebooks. Se você tentar salvar o estado da sessão com quarto preview e depois renderizar com quarto render, a conexão pode ser perdida porque o modo preview mantém o interpretador vivo e o modo render reconstrói o ambiente. Sempre teste a renderização final antes de confiar nos resultados do preview. O segundo detalhe é sobre tipos de dados. O DuckDB é rigoroso com tipagem. Se uma coluna no seu CSV parece numérica mas tem valores NaN representados como strings vazias, o DuckDB pode inferir o tipo como VARCHAR em vez de DOUBLE e quebrar operações matemáticas silenciosamente. Use CAST(col AS DOUBLE) explicitamente nas suas views ou force o schema na leitura com read_csv_auto e columns especificado. Outro ponto: performance. O quarto para paper duck brilha quando você tem múltiplas visualizações sobre os mesmos dados. Se seu fluxo tem apenas uma ou duas células, o overhead de inicializar o DuckDB pode ser maior do que simplesmente carregar o arquivo com read.csv ou pandas.read_csv. O ganho real aparece a partir de três ou quatro análises interligadas que compartilham transforms.

Limitações e quando não usar

Esse fluxo não é adequada para datasets que cabem facilmente na memória RAM e não exigem repetição de leitura. Nestes casos, a simplicidade do pandas ou data.table é suficiente. Também não recomendo para ambientes onde você precisa de isolamento total entre células, como em fluxos de aprovação ou validação independente de cada etapa. O compartilhamento de estado é uma faca de dois gumes: economiza tempo, mas dificulta o debug quando algo sai errado. Se o seu projeto depende de transações complexas ou de rollback, considere usar PostgreSQL ao invés de DuckDB. O DuckDB é projetado para análise, não para operações transacionais do dia a dia. Para instalar as dependências principais:

No R: install.packages(c("duckdb", "arrow")) No Python: pip install duckdb pandas pyarrow E para renderizar um documento que use quarto para paper duck, o comando básico é quarto render. Adicione --execute se quiser garantir que todas as células sejam executadas mesmo que estejam congeladas.