Salta al contenuto principale
Beancount.io LogoBeancount.io
219
Query con SQL

Query con SQL

Padroneggia il Beancount Query Language (BQL) per analisi avanzate di dati finanziari. Impara la sintassi simile a SQL per interrogare e analizzare i tuoi dati contabili.

Beancount dispone di un potente linguaggio di query simile a SQL (BQL) che ti consente di analizzare, suddividere e esaminare i tuoi dati finanziari con precisione. Che tu voglia generare un report rapido, eseguire il debug di una registrazione o effettuare analisi complesse, padroneggiare BQL è la chiave per sbloccare tutto il potenziale del tuo libro mastro contabile in testo semplice. Questa guida ti condurrà attraverso la sua struttura, le funzioni e le migliori pratiche. 🔍

editor di query BQL di beancount.io che esegue query simili a SQL su un libro mastro Beancount nel browser

Esplora il libro mastro live →

Struttura ed Esecuzione delle Query​

Il cuore di BQL è la sua familiarità con la sintassi SQL. Le query vengono eseguite usando il strumento da riga di comando bean-query, che processa il tuo file di libro mastro e restituisce i risultati direttamente nel tuo terminale.

Formato Base della Query​

Una query BQL è composta da tre clausole principali: SELECT, FROM e WHERE.

SELECT <target1>, <target2>, ...
FROM <espressione-filtro-transazione>
WHERE <espressione-filtro-registrazione>;
  • SELECT: Specifica quali colonne di dati vuoi recuperare.
  • FROM: Filtra le intere transazioni prima che vengano processate.
  • WHERE: Filtra le singole righe di registrazione dopo che la transazione è stata selezionata.

Sistema di Filtraggio a Due Livelli​

La comprensione della differenza tra le clausole FROM e WHERE è cruciale per scrivere query accurate. BQL utilizza un processo di filtraggio a due livelli.

  1. Livello di Transazione (FROM) Questa clausola agisce su intere transazioni. Se una transazione corrisponde alla condizione FROM, l'intera transazione (inclusi tutti i suoi post) viene trasferita alla fase successiva. Questo è il modo principale per filtrare i dati, poiché preserva l'integrità del sistema di contabilità a partita doppia. Ad esempio, filtrare FROM anno = 2024 seleziona tutte le transazioni verificatesi nel 2024.

  2. Livello di Registrazione (WHERE) Questa clausola filtra i singoli movimenti all'interno delle transazioni selezionate dalla clausola FROM. Questo è utile per la presentazione e per concentrarsi su aspetti specifici di una transazione. Tuttavia, bisogna essere consapevoli che filtrare a questo livello può "rompere" l'integrità di una transazione nell'output, poiché potrebbe visualizzare solo un lato di una registrazione. Ad esempio, potresti selezionare tutti i movimenti verso il tuo conto Spese:Alimentari.

Modello Dati​

Per interrogare efficacemente i tuoi dati, devi comprendere come Beancount struttura la tua contabilità. Un libro mastro è un elenco di direttive, ma BQL si concentra principalmente sulle registrazioni di Transaction.

Struttura delle Transazioni​

Ogni Transaction è un contenitore con attributi di primo livello e una lista di oggetti Posting.

Transaction
├── data
├── flag
├── beneficiario
├── descrizione
├── tag
├── link
└── Posting[]
    ├── conto
    ├── unità
    ├── costo
    ├── prezzo
    └── metadati

Tipi di Colonne Disponibili​

Puoi selezionare (SELECT) qualsiasi attributo della transazione o dei suoi movimenti.

  1. Attributi delle Transazioni Queste colonne sono le stesse per ogni movimento all'interno di una singola transazione.

    SELECT
    data,          -- La data della transazione (datetime.date)
    anno,          -- L'anno della transazione (int)
    mese,          -- Il mese della transazione (int)
    giorno,        -- Il giorno della transazione (int)
    flag,          -- Il flag della transazione, es. "*" o "!" (str)
    beneficiario,  -- Il beneficiario (str)
    narrativa,     -- La descrizione o nota (str)
    tag,           -- Un set di tag, es. #viaggio-2024 (set[str])
    link           -- Un set di link, es. ^report-spese (set[str])

  2. Attributi delle Registrazioni Queste colonne sono specifiche di ogni singolo movimento.

    SELECT
    conto,          -- Il nome del conto (str)
    posizione,      -- L'importo completo, incluse unità e costo (Posizione)
    unità,          -- Il numero e la valuta della registrazione (Importo)
    costo,          -- La base costo della registrazione (Costo)
    prezzo,         -- Il prezzo utilizzato nella registrazione (Importo)
    peso,           -- La posizione convertita alla sua base costo (Importo)
    saldo           -- Il totale progressivo delle unità nel conto (Inventario)

Funzioni di Query​

..include una suite di funzioni per aggregazione e trasformazione dei dati, proprio come ... SQL.

Funzioni di Aggregazione​

Le funzioni di aggregazione riassumono i dati su più righe. Quando utilizzate con GROUP BY, forniscono sommari raggruppati.

-- Conta il numero di registrazioni
SELECT COUNT(*)
 
-- Somma il valore di tutte le registrazioni (convertito in una valuta comune)
SELECT SUM(posizione)
 
-- Trova la data della prima e dell'ultima transazione
SELECT FIRST(data), LAST(data)
 
-- Trova i valori minimi e massimi delle posizioni
SELECT MIN(posizione), MAX(posizione)
 
-- Raggruppa per conto di ottenere un totale per ciascuno
SELECT conto, SUM(posizione) GROUP BY conto

Funzioni Posizione/Inventario​

La colonna posizione è un oggetto composito. Queste funzioni permettono di estrarre specifiche parti di essa o calcolarne il valore di mercato.

-- Estrai solo il numero e la valuta da una posizione
SELECT UNITS(posizione)
 
-- Mostra il costo totale di una posizione
SELECT COST(posizione)
 
-- Mostra la posizione convertita alla sua base (utile per gli investimenti)
SELECT WEIGHT(posizione)
 
-- Calcola il valore di mercato usando i dati di prezzo più recenti
SELECT VALUE(posizione)

Puoi combinarle per creare report potenti. Ad esempio, per vedere il costo totale e il valore di mercato attuale del tuo portafoglio di investimenti:

SELECT
    conto,
    COST(SUM(posizione)) AS costo_totale,
    VALUE(SUM(posizione)) AS valore_mercato
FROM
    conto ~ "Attività:Investimenti"
GROUP BY
    conto

Funzionalità Avanzate​

Oltre alle semplici istruzioni SELECT, BQL offre comandi specializzati per report finanziari comuni.

Report di Bilancio​

L'istruzione BALANCES genera un bilancio o un conto economico per un periodo specifico.

-- Genera un semplice bilancio patrimoniale alla fine del 1 gennaio 2024
BALANCES FROM chiusura IL 2024-01-01
WHERE conto ~ "^Attività|^Passività"
 
-- Genera un conto economico per l'anno fiscale 2024
BALANCES FROM
    APERTURA IL 2024-01-01
    CHIUSURA IL 2024-12-31
WHERE conto ~ "^Ricavi|^Spese"

Report di Journal​

L'istruzione JOURNAL mostra l'attività dettagliata per uno o più conti, simile alla visualizzazione tradizionale di un libro mastro.

-- Mostra tutte le operazioni sul tuo conto corrente al costo originale
JOURNAL "Attività:Cassa" AL COSTO
 
-- Mostra tutte le transazioni 401k, visualizzando solo le unità (azioni)
JOURNAL "Attività:.*:401k" AD UNITÀ

Operazioni di Stampa​

L'istruzione PRINT è uno strumento di debug che output delle transazioni complete e corrispondenti nel formato originale dei file Beancount.

-- Stampa tutte le transazioni relative agli investimenti del 2024
PRINT FROM anno = 2024
WHERE conto ~ "Attività:Investimenti"
 
-- Trova una transazione tramite il suo ID univoco (generato da alcuni strumenti)
PRINT FROM id = "8e7c47250d040ae2b85de580dd4f5c2a"

Espressioni di Filtraggio​

È possibile costruire filtri sofisticati utilizzando operatori logici (AND, OR), espressioni regolari (~) e confronti.

-- Trova tutti le spese di viaggio nella seconda metà del 2024
SELECT * FROM
    anno = 2024 AND mese >= 6
WHERE conto ~ "Spese:Viaggio"
 
-- Trova tutte le transazioni relative a una vacanza o affari
SELECT * FROM
    "vacanza-2024" IN tag OR
    "viaggio-affari" IN link

Considerazioni di performance ⚙️​

bean-query è progettato per essere efficiente, ma comprendere il suo funzionamento può aiutarti a scrivere query più veloci su libri mastri di grandi dimensioni.

  1. Caricamento Dati: Beancount prima di tutto analizza interamente il tuo file di libro mastro e ordina tutte le transazioni in ordine cronologico. Questo intero dataset viene tenuto in memoria.
  2. Ottimizzazione delle Query: Il motore applica i filtri in un ordine specifico per massima efficienza: FROM (transazioni) → WHERE (registrazioni) → aggregazioni. Filtrare al livello FROM è più veloce perché riduce anticipatamente il dataset.
  3. Uso della memoria: Timerariamente, tutti i processi sono in memoria. Gli oggetti Posizione e le aggregazioni Inventario sono ottimizzati, ma set di risultati di grandi dimensioni possono consumare una notevole quantità di RAM. BQL non utilizza memorizzazione temporanea su disco.

Best Practices​

Segui questi suggerimenti per scrivere eccentriche, efficaci ed essenziali.

  1. Organizzazione Formatta le tue query per renderle leggibili, specialmente quelleHannooggle complesse. - Usoo interruzioni di riga e indentazione per separare le clausole.

    -- Una query pulita e leggibile per tutte le spese del 2024
SELECT
    data,
    conto,
    posizione
FROM
    anno = 2024
WHERE
    conto ~ "Spese"
ORDER BY
        data DESC;

  2. Debugging Se una query non produce i risultati nuovi, usa EXPLAIN per vedere me Beancount la parole. Il tanto, usa SELECT DISTINCT per verificare quali valori unici corrispondono alla filter.

    -- Vedere il piano di esecuzione
EXPLAIN SELECT data, conto, posizione;
 
-- Testare quali conti corrispondono a un'espressione regolare
SELECT DISTINCT conto
WHERE conto ~ "^Attività:.*";

  3. Bilanci di verifica Puoi usare BQL per verificare le ```balance` nel tuo ledger. Questa query deve restituire l'importo esatto indicato nella tua ultima verifica di saldo per quel conto.

    -- Verificare il saldo finale del tuo conto corrente
SELECT conto, SUM(posizione)
FROM chiusura IL 2025-01-01 -- Usa la data dalla tua direttiva di saldo
WHERE conto = "Attività:ContoCorrente";
PrecedenteInventoriesSuccessivoUi Features