Preskočiť na hlavný obsah

Beancount Query Language (BQL): dotazujte sa na svoj ledger

Dotazujte sa na svoj Beancount ledger pomocou BQL, jazyka podobného SQL: syntax SELECT, stĺpce, agregačné a inventárne funkcie a reporty spúšťané príkazom bea query.

Beancount disponuje výkonným dotazovacím jazykom (BQL) podobným SQL, ktorý vám umožňuje presne vyberať, kombinovať a analyzovať vaše finančné údaje. Či už chcete vygenerovať rýchly prehľad, odladiť záznam alebo vykonať komplexnú analýzu, zvládnutie BQL je kľúčom k odomknutiu plného potenciálu vašej plaintextovej účtovnej knihy. Táto príručka vás prevedie jej štruktúrou, funkciami a osvedčenými postupmi. 🔍

beancount.io BQL query editor running SQL-like queries against a Beancount ledger in the browser

Preskúmajte živú účtovnú knihu →

Struktura in izvedba poizvedbe​

Jadrom BQL je jeho známa syntax inšpirovaná SQL. Dotazy spúšťajte pomocou bea query: bea --file <ledger> query "SELECT …" vypíše tabuľku vo vašom termináli a bea query bez argumentu otvorí interaktívny shell. Každý dotaz v tejto príručke bol spustený proti Beancount 3.2.3 s beanquery 0.2.0.

Osnovni format poizvedbe​

Dotaz BQL sa skladá z troch hlavných častí: SELECT, FROM a WHERE.

SELECT <target1>, <target2>, ...
FROM <entry-filter-expression>
WHERE <posting-filter-expression>;
  • SELECT: Určuje, ktoré stĺpce údajov chcete získať.
  • FROM: Filtruje celé transakcie predtým, než sú spracované.
  • WHERE: Filtruje jednotlivé položky po výbere transakcie.

Dvonivojski sistem filtriranja​

Pochopenie rozdielu medzi časťami FROM a WHERE je kľúčové pre písanie presných dotazov. BQL používa dvojúrovňový proces filtrovania.

  1. Úroveň transakcie (FROM) Táto časť pôsobí na celé transakcie. Ak transakcia spĺňa podmienku FROM, celá transakcia (vrátane všetkých jej položiek) je odovzdaná do ďalšej fázy. Toto je hlavný spôsob filtrovania údajov, pretože zachováva integritu systému podvojného účtovníctva. Napríklad filter FROM year = 2024 vyberie všetky transakcie, ktoré sa uskutočnili v roku 2024.

  2. Úroveň položky (WHERE) Táto časť filtruje jednotlivé položky v rámci transakcií vybraných časťou FROM. Je užitočná na prezentáciu a zameranie sa na konkrétne časti transakcie. Majte však na pamäti, že filtrovanie na tejto úrovni môže „narušiť“ integritu transakcie vo výstupe, pretože môžete vidieť len jednu stranu záznamu. Napríklad môžete vybrať všetky položky na váš účet Expenses:Groceries.

Konkrétne, PRINT FROM year = 2024 vráti celé transakcie (obe strany každého záznamu), zatiaľ čo SELECT date, narration, account, position FROM year = 2024 WHERE account ~ "Assets:Broker" vráti jeden riadok na každú zodpovedajúcu položku. Na účtovnej knihe s dvoma nákupmi u brokera prvý dotaz vráti celé záznamy a druhý vráti presne dva riadky brokera.

Podatkovni model​

Aby ste mohli efektívne dotazovať svoje údaje, musíte pochopiť, ako Beancount štruktúruje údaje. Účtovná kniha je zoznam direktív, ale BQL sa zameriava predovšetkým na záznamy Transaction.

Struktura transakcije​

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

Razpoložljive vrste stolpcev​

Môžete SELECT-ovať ktorýkoľvek z atribútov transakcie alebo jej položiek.

  1. Atribúty transakcie Tieto stĺpce sú rovnaké pre každú 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 platby (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 položky Tieto stĺpce sú špecifické pre každý jednotlivý riadok položky.

    SELECT
    account,           -- Názov účtu (str)
    position,          -- Celková suma vrátane jednotiek a nákladov (Position)
    units(position),   -- Počet a mena položky (Amount)
    cost(position),    -- Nákladová základňa položky (Amount)
    price,             -- Cena použitá v položke (Amount)
    weight,            -- Položka prevedená na svoju nákladovú základňu (Amount)
    balance            -- Priebežný súčet jednotiek na účte (Inventory)

    units a cost sú funkcie, ktoré berú position. price, weight a balance sú obyčajné stĺpce.

Funkcije poizvedbe​

BQL obsahuje sadu funkcií na agregáciu a transformáciu údajov, podobne ako SQL.

Agregacijske funkcije​

Agregačné funkcie sumarizujú údaje naprieč viacerými riadkami. Pri použití s GROUP BY poskytujú zoskupené súhrny.

-- Spočítať počet položiek
SELECT COUNT(*)
 
-- Sčítať všetky položky do jedného Inventory; meny a loty sa zachovajú, nekonvertujú sa
SELECT SUM(position)
-- jeden riadok, napr. (-2300.00 USD, 10 HOOL {150.00 USD, 2024-09-05}, 5 HOOL {160.00 USD, 2024-11-02})
 
-- Sčítať jeden účet v jednej mene explicitne (položky bez ceny si zachovajú svoju menu)
SELECT SUM(CONVERT(position, 'USD')) WHERE account ~ "Assets:Checking"
-- jeden riadok, napr. (2580.00 USD)
 
-- Nájsť dátum prvej a poslednej transakcie
SELECT FIRST(date), LAST(date)
 
-- Nájsť minimálnu a maximálnu hodnotu položky
SELECT MIN(position), MAX(position)
 
-- Zoskupiť podľa účtu, aby ste získali súčet pre každý
SELECT account, SUM(position) GROUP BY account

Funkcije pozicije/inventarja​

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

-- Extrahovať iba číslo a menu z položky
SELECT UNITS(position)
 
-- Zobraziť celkové náklady položky
SELECT COST(position)
 
-- Zobraziť každú položku v jej nákladovej hodnote (stĺpec; neexistuje funkcia WEIGHT())
SELECT account, weight WHERE account ~ "Assets:Investments"
 
-- Vypočítať trhovú hodnotu pomocou najnovších cenových údajov
-- (vyžaduje cenovú direktívu pre držaný majetok; inak sa položka vráti nezmenená)
SELECT VALUE(position)

Môžete ich kombinovať pre výkonné prehľady. Napríklad na zobrazenie celkových nákladov a aktuálnej trhovej hodnoty vášho investičného portfólia. Trhová hodnota vyžaduje direktívu price pre každý držaný majetok (napríklad 2024-12-01 price HOOL 175.00 USD). Oba agregáty vracajú Inventory na účet, takže každá mena je stále uvedená samostatne.

SELECT
    account,
    COST(SUM(position)) AS total_cost,
    VALUE(SUM(position)) AS market_value
FROM
    account ~ "Assets:Investments"
GROUP BY
    account
-- jeden riadok na účet, napr. Assets:Broker:HOOL | (2300.00 USD) | (2625.00 USD)

Cenové direktívy používané dotazmi na trhovú hodnotu môžu pochádzať z manuálnych záznamov, lokálneho nástroja na získavanie kotácií alebo Live Prices v kompatibilnom načítavacom nástroji. Spravované kanály nemenia syntax dotazu. Lokálne upstream nástroje potrebujú lokálne cenové súbory a historické dotazy stále potrebujú ceny k požadovanému dátumu alebo pred ním.

Napredne funkcije​

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

Poročila o stanju​

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

-- Vygenerovať jednoduchú súvahu k začiatku roka 2024
BALANCES FROM close ON 2024-01-01
WHERE account ~ "^Assets|^Liabilities"
 
-- Vygenerovať výkaz ziskov a strát pre fiškálny rok 2024
BALANCES FROM
    OPEN ON 2024-01-01
    CLOSE ON 2024-12-31
WHERE account ~ "^Income|^Expenses"

Dnevniška poročila​

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

-- Zobraziť všetku aktivitu na vašom bežnom účte v pôvodných nákladoch
JOURNAL "Assets:Checking" AT COST
 
-- Zobraziť všetky transakcie 401k, pričom sa zobrazia iba jednotky (podielové listy)
JOURNAL "Assets:.*:401k" AT UNITS

Operacije tiskanja​

Príkaz PRINT je nástroj na ladenie, ktorý vypisuje úplné, zodpovedajúce transakcie v ich pôvodnom formáte súboru Beancount. Akceptuje iba filter záznamov. Časť WHERE je tu syntaktickou chybou. Ak chcete výstup zúžiť na jednu stranu každého záznamu, použite namiesto toho SELECT s filtrom položiek. Vracia jeden riadok na každú zodpovedajúcu položku.

-- Vypísať všetky transakcie z roku 2024 v úplnosti (každú položku každého zodpovedajúceho záznamu)
PRINT FROM year = 2024
 
-- Zobraziť iba investičné položky transakcií z roku 2024
SELECT date, narration, account, position
FROM year = 2024
WHERE account ~ "Assets:Investments"
 
-- Nájsť transakciu podľa jej jedinečného ID (generovaného niektorými nástrojmi)
-- Vracia zodpovedajúci záznam alebo žiadne riadky, ak nič nemá toto ID
PRINT FROM id = "8e7c47250d040ae2b85de580dd4f5c2a"

Filtrirni izrazi​

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

Reťazcové literály používajú jednoduché úvodzovky. Dvojité úvodzovky oddeľujú regulárny výraz za ~.

-- Nájsť všetky cestovné výdavky z druhej polovice roka 2024
-- SELECT * vracia date, flag, payee, narration a position na každú zodpovedajúcu položku
SELECT * FROM
    year = 2024 AND month >= 6
WHERE account ~ "Expenses:Travel"
 
-- Nájsť všetky transakcie súvisiace s dovolenkou alebo pracovnou cestou
SELECT * FROM
    'vacation-2024' IN tags OR
    'business-trip' IN links

Premišljanja o zmogljivosti ⚙️​

bea query je navrhnutý pre efektivitu, ale pochopenie jeho prevádzkového toku vám môže pomôcť písať rýchlejšie dotazy na veľkých účtovných knihách.

  1. Načítanie údajov: Beancount najprv spracuje celý súbor vašej účtovnej knihy a zoradí všetky transakcie chronologicky. Celý tento súbor údajov je držaný v pamäti.
  2. Optimalizácia dotazu: Dotazovací engine aplikuje filtre v konkrétnom poradí pre maximálnu efektivitu: FROM (transakcie) -> WHERE (položky) -> Agregácie. Filtrovanie na úrovni FROM je najrýchlejšie, pretože včas zmenšuje súbor údajov.
  3. Využitie pamäte: Všetky operácie prebiehajú v pamäti. Objekty Position a agregácie Inventory sú optimalizované, ale veľmi veľké množiny výsledkov môžu spotrebovať značné množstvo RAM. BQL nepoužíva dočasné úložisko na disku.

Najboljše prakse​

Pri písaní čistých, efektívnych a udržiavateľných dotazov postupujte podľa týchto rád.

  1. Organizácia dotazu Formátujte svoje dotazy pre čitateľnosť, najmä tie zložité. Používajte zalomenie riadkov a odsadenie na oddelenie častí.

    -- Čistý, čitateľný dotaz na 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ávania, najprv spustite malú vzorku s LIMIT. Na otestovanie filtra použite SELECT DISTINCT, aby ste videli, aké jedinečné hodnoty zodpovedajú.

    -- Zobraziť náhľad prvých riadkov počas iterácie
SELECT date, account, position LIMIT 5;
 
-- Otestovať, ktoré účty zodpovedajú regulárnemu výrazu
SELECT DISTINCT account
WHERE account ~ "^Assets:.*";

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

    -- Overiť 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 direktívy balance
WHERE account = "Assets:Checking";

Zdieľať túto stránku

Zdieľať na FacebookZdieľať na TelegramZdieľať na XZdieľať na LinkedInZdieľať na WhatsApp

Bola táto stránka užitočná?

Beancount Query Language (BQL): dotazujte sa na svoj ledger

Zdroj: https://beancount.io/sk/docs/Basics/beancount-query-language