Beancount Query Language - Finančné dotazy podobné SQL

Beancount obsahuje výkonný Query Language (BQL) podobný SQL, ktorý vám umožňuje s presnosťou triediť, analyzovať a rozoberať vaše finančné dáta. Či už chcete generovať rýchlu správu, ladiť záznam alebo vykonávať komplexnú analýzu, ovládanie BQL je kľúčové pre odomknutie plného potenciálu vašej účtovnej knihy v prostom texte. Táto príručka vás prevedie jeho štruktúrou, funkciami a osvedčenými postupmi. 🔍

---

Štruktúra a vykonávanie dotazu

Jadrom BQL je jeho známa syntax inšpirovaná jazykom SQL. Dotazy sa vykonávajú pomocou nástroja príkazového riadku bean-query, ktorý spracováva váš účtovný súbor a vracia výsledky priamo do vášho terminálu.

Základný formát dotazu

Dotaz BQL sa skladá z troch hlavných klauzúl: SELECT, FROM a WHERE.

SELECT <cieľ1>, <cieľ2>, ...
FROM <výraz-filtra-záznamov>
WHERE <výraz-filtra-účtovných-položiek>;

• SELECT: Určuje, ktoré stĺpce dát chcete načítať.
• FROM: Filtruje celé transakcie predtým, ako sa spracujú.
• WHERE: Filtruje jednotlivé riadky účtovných položiek po výbere transakcie.

Dvojúrovňový systém filtrovania

Pochopenie rozdielu medzi klauzulami FROM a WHERE je rozhodujúce pre písanie presných dotazov. BQL používa dvojúrovňový proces filtrovania.

1. Úroveň transakcie (FROM) Táto klauzula pôsobí na celé transakcie. Ak transakcia zodpovedá podmienke FROM, celá transakcia (vrátane všetkých jej účtovných položiek) sa prenesie do ďalšej fázy. Toto je primárny spôsob filtrovania dát, pretože zachováva integritu systému podvojného účtovníctva. Napríklad filtrovanie FROM year = 2024 vyberie všetky transakcie, ktoré sa uskutočnili v roku 2024.

2. Úroveň účtovnej položky (WHERE) Táto klauzula filtruje jednotlivé účtovné položky v rámci transakcií vybratých klauzulou FROM. Toto je užitočné na prezentáciu a na zameranie sa na špecifické časti transakcie. Buďte si však vedomí, že filtrovanie na tejto úrovni môže "narušiť" integritu transakcie vo výstupe, pretože môžete vidieť iba jednu stranu záznamu. Napríklad by ste mohli vybrať všetky účtovné položky do vášho účtu Expenses:Groceries.

---

Dátový model

Ak chcete efektívne dotazovať svoje dáta, musíte pochopiť, ako ich Beancount štruktúruje. Účtovná kniha je zoznam direktív, ale BQL sa primárne zameriava na záznamy Transaction.

Štruktúra transakcie

Každá Transaction je kontajner s atribútmi najvyššej úrovne a zoznamom objektov Posting.

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

Dostupné typy stĺpcov

Môžete SELECT ľubovoľný z atribútov z transakcie alebo jej účtovných položiek.

1. Atribúty transakcie Tieto stĺpce sú rovnaké pre každú účtovnú položku v rámci jednej transakcie.

   SELECT
       date,        -- Dátum transakcie (datetime.date)
       year,        -- Rok transakcie (int)
       month,       -- Mesiac transakcie (int)
       day,         -- Deň transakcie (int)
       flag,        -- Príznak transakcie, napr. "*" alebo "!" (str)
       payee,       -- Príjemca (str)
       narration,   -- Popis alebo poznámka (str)
       tags,        -- Množina značiek, napr. #trip-2024 (set[str])
       links        -- Množina odkazov, napr. ^expense-report (set[str])

2. Atribúty účtovnej položky Tieto stĺpce sú špecifické pre každý jednotlivý riadok účtovnej položky.

   SELECT
       account,     -- Názov účtu (str)
       position,    -- Celková suma, vrátane jednotiek a nákladov (Position)
       units,       -- Počet a mena účtovnej položky (Amount)
       cost,        -- Nákladová základňa účtovnej položky (Cost)
       price,       -- Cena použitá v účtovnej položke (Amount)
       weight,      -- Pozícia prepočítaná na jej nákladovú základňu (Amount)
       balance      -- Kumulatívny súčet jednotiek na účte (Inventory)

---

Funkcie dotazu

BQL obsahuje sadu funkcií pre agregáciu a transformáciu dát, podobne ako SQL.

Agregačné funkcie

Agregačné funkcie sumarizujú dáta naprieč viacerými riadkami. Keď sa používajú s GROUP BY, poskytujú zoskupené súhrny.

-- Spočítajte počet účtovných položiek
SELECT COUNT(*)

-- Súčet hodnoty všetkých účtovných položiek (prepočítané na spoločnú menu)
SELECT SUM(position)

-- Nájdite dátum prvej a poslednej transakcie
SELECT FIRST(date), LAST(date)

-- Nájdite minimálne a maximálne hodnoty pozície
SELECT MIN(position), MAX(position)

-- Zoskupte podľa účtu, aby ste získali súčet pre každý
SELECT account, SUM(position) GROUP BY account

Funkcie pozície/inventára

Stĺpec position je zložený objekt. Tieto funkcie vám umožňujú extrahovať špecifické časti z neho alebo vypočítať jeho trhovú hodnotu.

-- Extrahujte iba číslo a menu z pozície
SELECT UNITS(position)

-- Zobrazte celkové náklady na pozíciu
SELECT COST(position)

-- Zobrazte pozíciu prepočítanú na jej nákladovú základňu (užitočné pre investície)
SELECT WEIGHT(position)

-- Vypočítajte trhovú hodnotu pomocou najnovších údajov o cene
SELECT VALUE(position)

Môžete ich kombinovať pre výkonné správy. Napríklad, ak chcete zobraziť celkové náklady a aktuálnu trhovú hodnotu vášho investičného portfólia:

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

---

Pokročilé funkcie

Okrem základných príkazov SELECT ponúka BQL špecializované príkazy pre bežné finančné správy.

Súvaha

Príkaz BALANCES generuje súvahu alebo výkaz ziskov a strát za špecifické obdobie.

-- Vygenerujte jednoduchú súvahu k začiatku roka 2024
BALANCES FROM close ON 2024-01-01
WHERE account ~ "^Assets|^Liabilities"

-- Vygenerujte výkaz ziskov a strát za fiškálny rok 2024
BALANCES FROM
    OPEN ON 2024-01-01
    CLOSE ON 2024-12-31
WHERE account ~ "^Income|^Expenses"

Denník

Príkaz JOURNAL zobrazuje podrobnú aktivitu pre jeden alebo viac účtov, podobne ako tradičný pohľad do knihy.

-- Zobrazte všetku aktivitu na vašom bežnom účte v jeho pôvodnej cene
JOURNAL "Assets:Checking" AT COST

-- Zobrazte všetky transakcie 401k, zobrazujúce iba jednotky (akcie)
JOURNAL "Assets:.*:401k" AT UNITS

Operácie tlače

Príkaz PRINT je ladiaci nástroj, ktorý vypisuje celé, zodpovedajúce transakcie v ich pôvodnom formáte súboru Beancount.

-- Vytlačte všetky transakcie súvisiace s investíciami z roku 2024
PRINT FROM year = 2024
WHERE account ~ "Assets:Investments"

-- Nájdite transakciu podľa jej jedinečného ID (generovaného niektorými nástrojmi)
PRINT FROM id = "8e7c47250d040ae2b85de580dd4f5c2a"

Filtrovacie výrazy

Môžete vytvárať sofistikované filtre pomocou logických operátorov (AND, OR), regulárnych výrazov (~) a porovnaní.

-- Nájdite všetky cestovné výdavky z druhej polovice roka 2024
SELECT * FROM
    year = 2024 AND month >= 6
WHERE account ~ "Expenses:Travel"

-- Nájdite všetky transakcie súvisiace s dovolenkou alebo podnikaním
SELECT * FROM
    "vacation-2024" IN tags OR
    "business-trip" IN links

---

Úvahy o výkone ⚙️

bean-query je navrhnutý pre efektívnosť, ale pochopenie jeho prevádzkového toku vám môže pomôcť písať rýchlejšie dotazy na rozsiahlych účtovných knihách.

1. Načítanie dát: Beancount najprv analyzuje celý váš účtovný súbor a zoradí všetky transakcie chronologicky. Celá táto dátová sada je uložená v pamäti.
2. Optimalizácia dotazu: Dotazovací engine aplikuje filtre v špecifickom poradí pre maximálnu efektivitu: FROM (transakcie) -> WHERE (účtovné položky) -> Agregácie. Filtrovanie na úrovni FROM je najrýchlejšie, pretože znižuje dátovú sadu skoro.
3. Využitie pamäte: Všetky operácie sa dejú v pamäti. Objekty Position a agregácie Inventory sú optimalizované, ale veľmi rozsiahle množiny výsledkov môžu spotrebovať značné množstvo RAM. BQL nepoužíva dočasné úložisko založené na disku.

---

Osvedčené postupy

Postupujte podľa týchto tipov na písanie čistých, efektívnych a udržiavateľných dotazov.

1. Organizácia dotazu Formátujte svoje dotazy pre čitateľnosť, najmä komplexné. Používajte zalomenia riadkov a odsadenie na oddelenie klauzúl.

   -- Čistý, čitateľný dotaz pre všetky výdavky z roku 2024
   SELECT
       date,
       account,
       position
   FROM
       year = 2024
   WHERE
       account ~ "Expenses"
   ORDER BY
       date DESC;

2. Ladenie Ak dotaz nefunguje podľa očakávaní, použite EXPLAIN na zistenie, ako ho Beancount analyzuje. Ak chcete otestovať filter, použite SELECT DISTINCT na zistenie, ktoré jedinečné hodnoty zodpovedajú.

   -- Zobrazte plán dotazu
   EXPLAIN SELECT date, account, position;
   
   -- Otestujte, ktoré účty zodpovedajú regulárnemu výrazu
   SELECT DISTINCT account
   WHERE account ~ "^Assets:.*";

3. Kontrola zostatkov Pomocou BQL môžete dvakrát skontrolovať tvrdenia balance vo vašej účtovnej knihe. Tento dotaz by mal vrátiť presnú sumu uvedenú v poslednej kontrole zostatku pre daný účet.

   -- Overte konečný zostatok vášho bežného účtu
   SELECT account, sum(position)
   FROM close ON 2025-01-01 -- Použite dátum z vašej smernice o zostatku
   WHERE account = "Assets:Checking";