Linguagem de Consulta Beancount - Consultas Financeiras Semelhantes a SQL

O Beancount possui uma poderosa Linguagem de Consulta (BQL) semelhante a SQL que permite segmentar, detalhar e analisar seus dados financeiros com precisão. Seja para gerar um relatório rápido, depurar uma entrada ou realizar análises complexas, dominar a BQL é fundamental para desbloquear todo o potencial do seu livro razão de contabilidade em texto simples. Este guia irá guiá-lo através de sua estrutura, funções e melhores práticas. 🔍

---

Estrutura e Execução de Consultas

O núcleo da BQL é sua sintaxe familiar, inspirada no SQL. As consultas são executadas usando a ferramenta de linha de comando bean-query, que processa seu arquivo de razão e retorna os resultados diretamente em seu terminal.

Formato Básico de Consulta

Uma consulta BQL é composta por três cláusulas principais: SELECT, FROM e WHERE.

SELECT <alvo1>, <alvo2>, ...
FROM <expressão-de-filtro-de-entrada>
WHERE <expressão-de-filtro-de-lançamento>;

• SELECT: Especifica quais colunas de dados você deseja recuperar.
• FROM: Filtra transações inteiras antes de serem processadas.
• WHERE: Filtra as linhas de lançamento individuais após a transação ter sido selecionada.

Sistema de Filtragem de Dois Níveis

Compreender a diferença entre as cláusulas FROM e WHERE é crucial para escrever consultas precisas. BQL usa um processo de filtragem de dois níveis.

1. Nível de Transação (FROM) Esta cláusula atua em transações inteiras. Se uma transação corresponder à condição FROM, a transação inteira (incluindo todos os seus lançamentos) é passada para a próxima etapa. Esta é a principal forma de filtrar dados, pois preserva a integridade do sistema de contabilidade de partidas dobradas. Por exemplo, filtrar FROM ano = 2024 seleciona todas as transações que ocorreram em 2024.

2. Nível de Lançamento (WHERE) Esta cláusula filtra os lançamentos individuais dentro das transações selecionadas pela cláusula FROM. Isso é útil para apresentação e para focar em partes específicas de uma transação. No entanto, esteja ciente de que a filtragem neste nível pode "quebrar" a integridade de uma transação na saída, pois você pode ver apenas um lado de uma entrada. Por exemplo, você pode selecionar todos os lançamentos para sua conta Despesas:Supermercado.

---

Modelo de Dados

Para consultar seus dados de forma eficaz, você precisa entender como o Beancount os estrutura. Um razão é uma lista de diretivas, mas o BQL se concentra principalmente nas entradas de Transaction.

Estrutura da Transação

Cada Transaction é um contêiner com atributos de nível superior e uma lista de objetos Posting.

Transação
├── data
├── sinalizador
├── beneficiário
├── narração
├── etiquetas
├── links
└── Lançamentos[]
    ├── conta
    ├── unidades
    ├── custo
    ├── preço
    └── metadados

Tipos de Coluna Disponíveis

Você pode SELECT qualquer um dos atributos da transação ou de seus lançamentos.

1. Atributos da Transação Estas colunas são as mesmas para cada lançamento dentro de uma única transação.

   SELECT
       data,        -- A data da transação (datetime.date)
       ano,        -- O ano da transação (int)
       mês,       -- O mês da transação (int)
       dia,         -- O dia da transação (int)
       sinalizador,        -- O sinalizador da transação, por exemplo, "*" ou "!" (str)
       beneficiário,       -- O beneficiário (str)
       narração,   -- A descrição ou memorando (str)
       etiquetas,        -- Um conjunto de etiquetas, por exemplo, #viagem-2024 (set[str])
       links        -- Um conjunto de links, por exemplo, ^relatório-de-despesas (set[str])

2. Atributos do Lançamento Estas colunas são específicas para cada linha de lançamento individual.

   SELECT
       conta,     -- O nome da conta (str)
       posição,    -- O valor total, incluindo unidades e custo (Position)
       unidades,       -- O número e a moeda do lançamento (Amount)
       custo,        -- A base de custo do lançamento (Cost)
       preço,       -- O preço usado no lançamento (Amount)
       peso,      -- A posição convertida para sua base de custo (Amount)
       saldo      -- O total acumulado de unidades na conta (Inventory)

---

Funções de Consulta

BQL inclui um conjunto de funções para agregação e transformação de dados, muito parecido com SQL.

Funções de Agregação

As funções de agregação resumem dados em várias linhas. Quando usadas com GROUP BY, elas fornecem resumos agrupados.

-- Contar o número de lançamentos
SELECT COUNT(*)

-- Somar o valor de todos os lançamentos (convertido para uma moeda comum)
SELECT SUM(posição)

-- Encontrar a data da primeira e da última transação
SELECT FIRST(data), LAST(data)

-- Encontrar os valores mínimo e máximo de posição
SELECT MIN(posição), MAX(posição)

-- Agrupar por conta para obter uma soma para cada
SELECT conta, SUM(posição) GROUP BY conta

Funções de Posição/Inventário

A coluna posição é um objeto composto. Estas funções permitem extrair partes específicas dele ou calcular seu valor de mercado.

-- Extrair apenas o número e a moeda de uma posição
SELECT UNITS(posição)

-- Mostrar o custo total de uma posição
SELECT COST(posição)

-- Mostrar a posição convertida para sua base de custo (útil para investimentos)
SELECT WEIGHT(posição)

-- Calcular o valor de mercado usando os dados de preço mais recentes
SELECT VALUE(posição)

Você pode combinar estes para relatórios poderosos. Por exemplo, para ver o custo total e o valor de mercado atual de sua carteira de investimentos:

SELECT
    conta,
    COST(SUM(posição)) AS custo_total,
    VALUE(SUM(posição)) AS valor_de_mercado
FROM
    conta ~ "Ativos:Investimentos"
GROUP BY
    conta

---

Recursos Avançados

Além das instruções SELECT básicas, o BQL oferece comandos especializados para relatórios financeiros comuns.

Relatórios de Balanço

A instrução BALANCES gera um balanço patrimonial ou uma demonstração do resultado para um período específico.

-- Gerar um balanço patrimonial simples a partir do início de 2024
BALANCES FROM close ON 2024-01-01
WHERE conta ~ "^Ativos|^Passivos"

-- Gerar uma demonstração do resultado para o ano fiscal de 2024
BALANCES FROM
    OPEN ON 2024-01-01
    CLOSE ON 2024-12-31
WHERE conta ~ "^Receitas|^Despesas"

Relatórios de Diário

A instrução JOURNAL mostra a atividade detalhada para uma ou mais contas, semelhante a uma visualização de razão tradicional.

-- Mostrar toda a atividade em sua conta corrente a seu custo original
JOURNAL "Ativos:Corrente" AT COST

-- Mostrar todas as transações 401k, exibindo apenas as unidades (ações)
JOURNAL "Ativos:.*:401k" AT UNITS

Imprimir Operações

A instrução PRINT é uma ferramenta de depuração que produz transações completas e correspondentes em seu formato de arquivo Beancount original.

-- Imprimir todas as transações relacionadas a investimentos de 2024
PRINT FROM ano = 2024
WHERE conta ~ "Ativos:Investimentos"

-- Encontrar uma transação por seu ID exclusivo (gerado por algumas ferramentas)
PRINT FROM id = "8e7c47250d040ae2b85de580dd4f5c2a"

Expressões de Filtragem

Você pode construir filtros sofisticados usando operadores lógicos (AND, OR), expressões regulares (~) e comparações.

-- Encontrar todas as despesas de viagem do segundo semestre de 2024
SELECT * FROM
    ano = 2024 AND mês >= 6
WHERE conta ~ "Despesas:Viagem"

-- Encontrar todas as transações relacionadas a férias ou negócios
SELECT * FROM
    "férias-2024" IN etiquetas OR
    "viagem-de-negócios" IN links

---

Considerações de Desempenho ⚙️

bean-query é projetado para eficiência, mas entender seu fluxo operacional pode ajudá-lo a escrever consultas mais rápidas em grandes razões.

1. Carregamento de Dados: O Beancount primeiro analisa todo o seu arquivo de razão e classifica todas as transações cronologicamente. Este conjunto de dados inteiro é mantido na memória.
2. Otimização de Consulta: O mecanismo de consulta aplica filtros em uma ordem específica para máxima eficiência: FROM (transações) -> WHERE (lançamentos) -> Agregações. Filtrar no nível FROM é mais rápido porque reduz o conjunto de dados no início.
3. Uso de Memória: Todas as operações acontecem na memória. Objetos Position e agregações Inventory são otimizados, mas conjuntos de resultados muito grandes podem consumir RAM significativa. BQL não usa armazenamento temporário baseado em disco.

---

Melhores Práticas

Siga estas dicas para escrever consultas limpas, eficazes e sustentáveis.

1. Organização de Consulta Formate suas consultas para legibilidade, especialmente as complexas. Use quebras de linha e indentação para separar as cláusulas.

   -- Uma consulta limpa e legível para todas as despesas de 2024
   SELECT
       data,
       conta,
       posição
   FROM
       ano = 2024
   WHERE
       conta ~ "Despesas"
   ORDER BY
       data DESC;

2. Depuração Se uma consulta não estiver funcionando como esperado, use EXPLAIN para ver como o Beancount a analisa. Para testar um filtro, use SELECT DISTINCT para ver quais valores exclusivos ele corresponde.

   -- Ver o plano de consulta
   EXPLAIN SELECT data, conta, posição;
   
   -- Testar quais contas correspondem a uma expressão regular
   SELECT DISTINCT conta
   WHERE conta ~ "^Ativos:.*";

3. Afirmações de Saldo Você pode usar BQL para verificar as afirmações de balance em seu razão. Esta consulta deve retornar o valor exato especificado em sua última verificação de saldo para essa conta.

   -- Verificar o saldo final de sua conta corrente
   SELECT conta, sum(posição)
   FROM close ON 2025-01-01 -- Use a data de sua diretiva de saldo
   WHERE conta = "Ativos:Corrente";