Llenguatge de consulta de Beancount - Consultes financeres semblants a SQL

Beancount inclou un potent llenguatge de consulta semblant a SQL (BQL) que et permet segmentar, analitzar i examinar les teves dades financeres amb precisió. Tant si vols generar un informe ràpid, depurar una entrada o realitzar una anàlisi complexa, dominar BQL és clau per alliberar tot el potencial del teu llibre de comptabilitat en text pla. Aquesta guia et guiarà a través de la seva estructura, funcions i bones pràctiques. 🔍

---

Estructura i execució de la consulta

El nucli de BQL és la seva sintaxi familiar, inspirada en SQL. Les consultes s'executen mitjançant l'eina de línia d'ordres bean-query, que processa el teu fitxer de llibre i retorna els resultats directament al teu terminal.

Format bàsic de la consulta

Una consulta BQL es compon de tres clàusules principals: SELECT, FROM i WHERE.

SELECT <objectiu1>, <objectiu2>, ...
FROM <expressió-filtre-entrada>
WHERE <expressió-filtre-apunt>;

• SELECT: Especifica quines columnes de dades vols recuperar.
• FROM: Filtra transaccions senceres abans de ser processades.
• WHERE: Filtra les línies d'apunt individuals després que la transacció hagi estat seleccionada.

Sistema de filtratge de dos nivells

Comprendre la diferència entre les clàusules FROM i WHERE és crucial per escriure consultes precises. BQL utilitza un procés de filtratge de dos nivells.

1. Nivell de transacció (FROM) Aquesta clàusula actua sobre transaccions senceres. Si una transacció compleix la condició FROM, la transacció sencera (incloent-hi tots els seus apunts) es passa a la següent etapa. Aquesta és la principal manera de filtrar dades, ja que preserva la integritat del sistema de comptabilitat per partida doble. Per exemple, filtrar FROM year = 2024 selecciona totes les transaccions que van ocórrer el 2024.

2. Nivell d'apunt (WHERE) Aquesta clàusula filtra els apunts individuals dins de les transaccions seleccionades per la clàusula FROM. Això és útil per a la presentació i per centrar-se en branques específiques d'una transacció. No obstant això, tingues en compte que filtrar a aquest nivell pot "trencar" la integritat d'una transacció a la sortida, ja que pot ser que només vegis un costat d'una entrada. Per exemple, pots seleccionar tots els apunts al teu compte Expenses:Groceries.

---

Model de dades

Per consultar les teves dades de manera efectiva, has d'entendre com Beancount les estructura. Un llibre és una llista de directives, però BQL se centra principalment en les entrades Transaction.

Estructura de la transacció

Cada Transaction és un contenidor amb atributs de nivell superior i una llista d'objectes Posting.

Transaction
├── date
├── flag
├── payee
├── narration
├── tags
├── links
└── Postings[]
    ├── account
    ├── units
    ├── cost
    ├── price
    └── metadata

Tipus de columna disponibles

Pots fer SELECT de qualsevol dels atributs de la transacció o dels seus apunts.

1. Atributs de la transacció Aquestes columnes són les mateixes per a cada apunt dins d'una sola transacció.

   SELECT
       date,        -- La data de la transacció (datetime.date)
       year,        -- L'any de la transacció (int)
       month,       -- El mes de la transacció (int)
       day,         -- El dia de la transacció (int)
       flag,        -- El senyalitzador de la transacció, per exemple, "*" o "!" (str)
       payee,       -- El beneficiari (str)
       narration,   -- La descripció o el memo (str)
       tags,        -- Un conjunt d'etiquetes, per exemple, #trip-2024 (set[str])
       links        -- Un conjunt d'enllaços, per exemple, ^expense-report (set[str])

2. Atributs de l'apunt Aquestes columnes són específiques de cada línia d'apunt individual.

   SELECT
       account,     -- El nom del compte (str)
       position,    -- L'import total, incloent-hi les unitats i el cost (Position)
       units,       -- El nombre i la moneda de l'apunt (Amount)
       cost,        -- La base del cost de l'apunt (Cost)
       price,       -- El preu utilitzat en l'apunt (Amount)
       weight,      -- La posició convertida a la seva base de cost (Amount)
       balance      -- El total acumulat d'unitats al compte (Inventory)

---

Funcions de consulta

BQL inclou un conjunt de funcions per a l'agregació i la transformació de dades, de manera molt semblant a SQL.

Funcions d'agregació

Les funcions d'agregació resumeixen les dades a través de múltiples files. Quan s'utilitzen amb GROUP BY, proporcionen resums agrupats.

-- Compta el nombre d'apunts
SELECT COUNT(*)

-- Suma el valor de tots els apunts (convertit a una moneda comuna)
SELECT SUM(position)

-- Troba la data de la primera i l'última transacció
SELECT FIRST(date), LAST(date)

-- Troba els valors de posició mínim i màxim
SELECT MIN(position), MAX(position)

-- Agrupa per compte per obtenir una suma per a cadascun
SELECT account, SUM(position) GROUP BY account

Funcions de posició/inventari

La columna position és un objecte compost. Aquestes funcions et permeten extreure parts específiques o calcular el seu valor de mercat.

-- Extreu només el nombre i la moneda d'una posició
SELECT UNITS(position)

-- Mostra el cost total d'una posició
SELECT COST(position)

-- Mostra la posició convertida a la seva base de cost (útil per a inversions)
SELECT WEIGHT(position)

-- Calcula el valor de mercat utilitzant les dades de preu més recents
SELECT VALUE(position)

Pots combinar-les per obtenir informes potents. Per exemple, per veure el cost total i el valor de mercat actual de la teva cartera d'inversions:

SELECT
    account,
    COST(SUM(position)) AS total_cost,
    VALUE(SUM(position)) AS market_value
FROM
    account ~ "Assets:Investments"
GROUP BY
    account

---

Característiques avançades

Més enllà de les declaracions SELECT bàsiques, BQL ofereix ordres especialitzades per a informes financers comuns.

Informes de balanç

La declaració BALANCES genera un balanç o un compte de resultats per a un període específic.

-- Genera un balanç simple a partir de l'inici de 2024
BALANCES FROM close ON 2024-01-01
WHERE account ~ "^Assets|^Liabilities"

-- Genera un compte de resultats per a l'exercici fiscal 2024
BALANCES FROM
    OPEN ON 2024-01-01
    CLOSE ON 2024-12-31
WHERE account ~ "^Income|^Expenses"

Informes de diari

La declaració JOURNAL mostra l'activitat detallada d'un o més comptes, de manera similar a una vista de llibre tradicional.

-- Mostra tota l'activitat del teu compte corrent al seu cost original
JOURNAL "Assets:Checking" AT COST

-- Mostra totes les transaccions de 401k, mostrant només les unitats (accions)
JOURNAL "Assets:.*:401k" AT UNITS

Operacions d'impressió

La declaració PRINT és una eina de depuració que genera transaccions coincidents completes en el seu format de fitxer Beancount original.

-- Imprimeix totes les transaccions relacionades amb la inversió de 2024
PRINT FROM year = 2024
WHERE account ~ "Assets:Investments"

-- Troba una transacció pel seu ID únic (generat per algunes eines)
PRINT FROM id = "8e7c47250d040ae2b85de580dd4f5c2a"

Expressions de filtratge

Pots construir filtres sofisticats utilitzant operadors lògics (AND, OR), expressions regulars (~) i comparacions.

-- Troba totes les despeses de viatge de la segona meitat de 2024
SELECT * FROM
    year = 2024 AND month >= 6
WHERE account ~ "Expenses:Travel"

-- Troba totes les transaccions relacionades amb unes vacances o negocis
SELECT * FROM
    "vacation-2024" IN tags OR
    "business-trip" IN links

---

Consideracions de rendiment ⚙️

bean-query està dissenyat per a l'eficiència, però comprendre el seu flux operatiu et pot ajudar a escriure consultes més ràpides en llibres grans.

1. Càrrega de dades: Beancount primer analitza tot el teu fitxer de llibre i ordena totes les transaccions cronològicament. Tot aquest conjunt de dades es manté a la memòria.
2. Optimització de consultes: El motor de consulta aplica filtres en un ordre específic per a la màxima eficiència: FROM (transaccions) -> WHERE (apunts) -> Agregacions. Filtrar al nivell FROM és més ràpid perquè redueix el conjunt de dades aviat.
3. Ús de la memòria: Totes les operacions tenen lloc a la memòria. Els objectes Position i les agregacions Inventory estan optimitzats, però conjunts de resultats molt grans poden consumir una quantitat significativa de RAM. BQL no utilitza emmagatzematge temporal basat en disc.

---

Bones pràctiques

Segueix aquests consells per escriure consultes netes, efectives i mantenibles.

1. Organització de la consulta Formata les teves consultes per a la llegibilitat, especialment les complexes. Utilitza salts de línia i sagnat per separar les clàusules.

   -- Una consulta neta i llegible per a totes les despeses de 2024
   SELECT
       date,
       account,
       position
   FROM
       year = 2024
   WHERE
       account ~ "Expenses"
   ORDER BY
       date DESC;

2. Depuració Si una consulta no funciona com s'esperava, utilitza EXPLAIN per veure com Beancount l'analitza. Per provar un filtre, utilitza SELECT DISTINCT per veure quins valors únics coincideix.

   -- Veure el pla de consulta
   EXPLAIN SELECT date, account, position;
   
   -- Prova quins comptes coincideixen amb una expressió regular
   SELECT DISTINCT account
   WHERE account ~ "^Assets:.*";

3. Asegurances de saldo Pots utilitzar BQL per comprovar doblement les assegurances de balance al teu llibre. Aquesta consulta ha de retornar la quantitat exacta especificada a la teva última comprovació de saldo per a aquest compte.

   -- Verifica el saldo final del teu compte corrent
   SELECT account, sum(position)
   FROM close ON 2025-01-01 -- Utilitza la data de la teva directiva de saldo
   WHERE account = "Assets:Checking";