# Beancount Query Language (BQL): interroga il tuo ledger

Beancount dispone di un potente Query Language (BQL) simile a SQL che ti permette di suddividere, analizzare e studiare i tuoi dati finanziari con precisione. Che tu voglia generare un report rapido, fare il debug di una scrittura o [eseguire analisi complesse](https://beancount.io/it/docs/Solutions/analytics), padroneggiare BQL è la chiave per sbloccare il pieno potenziale del tuo registro contabile in plaintext. Questa guida ti accompagnerà attraverso la sua struttura, le funzioni e le best practice. 🔍

![beancount.io BQL query editor running SQL-like queries against a Beancount ledger in the browser](/img/ledger/query-bql-example.webp)

*[Explore the live ledger →](https://beancount.io/ledger/open_ledger/example/query)*


---

## Struttura ed Esecuzione delle Query

Il cuore di BQL è la sua familiare sintassi ispirata a SQL. Esegui le query con `bea query`: `bea --file <ledger> query "SELECT …"` stampa la tabella nel tuo terminale, e `bea query` senza argomenti apre la shell interattiva. Ogni query in questa guida è stata eseguita con Beancount 3.2.3 con beanquery 0.2.0.

### Struttura Base di una Query

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

```sql
SELECT <target1>, <target2>, ...
FROM <entry-filter-expression>
WHERE <posting-filter-expression>;
```

- **`SELECT`**: Specifica quali colonne di dati vuoi recuperare.
- **`FROM`**: Filtra intere transazioni _prima_ che vengano elaborate.
- **`WHERE`**: Filtra le singole righe di posting _dopo_ che la transazione è stata selezionata.

### Sistema di Filtraggio su Due Livelli

Comprendere la differenza tra le clausole `FROM` e `WHERE` è cruciale per scrivere query accurate. BQL utilizza un processo di filtraggio a due livelli.

1. **Livello transazione (`FROM`)**
   Questa clausola agisce su intere transazioni. Se una transazione corrisponde alla condizione `FROM`, l'_intera transazione_ (incluse tutte le sue scritture) viene passata alla fase successiva. Questo è il modo principale per filtrare i dati, poiché preserva l'integrità del sistema di partita doppia. Ad esempio, filtrando `FROM year = 2024` si selezionano tutte le transazioni avvenute nel 2024.

2. **Livello posting (`WHERE`)**
   Questa clausola filtra le singole scritture _all'interno_ delle transazioni selezionate dalla clausola `FROM`. Questo è utile per la presentazione e per concentrarsi su specifiche parti di una transazione. Tuttavia, tieni presente che filtrare a questo livello può "rompere" l'integrità di una transazione nell'output, poiché potresti vedere solo un lato di una scrittura. Ad esempio, potresti selezionare tutte le scritture sul tuo conto `Expenses:Groceries`.

Concretamente, `PRINT FROM year = 2024` restituisce le transazioni complete (entrambi i lati di ogni scrittura), mentre `SELECT date, narration, account, position FROM year = 2024 WHERE account ~ "Assets:Broker"` restituisce una riga per ogni posting corrispondente. Su un registro con due acquisti tramite broker, la prima restituisce le scritture complete e la seconda restituisce esattamente le due righe del broker.

---

## Modello dei Dati

Per interrogare i tuoi dati in modo efficace, devi capire come Beancount li struttura. Un registro è una lista di direttive, ma BQL si concentra principalmente sulle scritture `Transaction`.

### Struttura della Transazione

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

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

### Tipi di Colonne Disponibili

Puoi usare `SELECT` su qualsiasi attributo della transazione o delle sue scritture.

1. **Attributi della transazione**
   Queste colonne sono identiche per ogni posting all'interno di una singola transazione.

   ```sql
   SELECT
       date,        -- The date of the transaction (datetime.date)
       year,        -- The year of the transaction (int)
       month,       -- The month of the transaction (int)
       day,         -- The day of the transaction (int)
       flag,        -- The transaction flag, e.g., "*" or "!" (str)
       payee,       -- The payee (str)
       narration,   -- The description or memo (str)
       tags,        -- A set of tags, e.g., #trip-2024 (set[str])
       links        -- A set of links, e.g., ^expense-report (set[str])
   ```

2. **Attributi del posting**
   Queste colonne sono specifiche di ogni singola riga di scrittura.

   ```sql
   SELECT
       account,           -- The account name (str)
       position,          -- The full amount, including units and cost (Position)
       units(position),   -- The number and currency of the posting (Amount)
       cost(position),    -- The cost basis of the posting (Amount)
       price,             -- The price used in the posting (Amount)
       weight,            -- The position converted to its cost basis (Amount)
       balance            -- The running total of units in the account (Inventory)
   ```
   `units` e `cost` sono funzioni che accettano `position`. `price`, `weight` e `balance` sono colonne semplici.

---

## Funzioni di Query

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

### Funzioni di Aggregazione

Le funzioni di aggregazione riassumono i dati su più righe. Se utilizzate con `GROUP BY`, forniscono riepiloghi raggruppati.

```sql
-- Count the number of postings
SELECT COUNT(*)

-- Sum all postings into one Inventory; currencies and lots are kept, not converted
SELECT SUM(position)
-- one row, e.g. (-2300.00 USD, 10 HOOL {150.00 USD, 2024-09-05}, 5 HOOL {160.00 USD, 2024-11-02})

-- Total one account in a single currency explicitly (positions without a price keep their currency)
SELECT SUM(CONVERT(position, 'USD')) WHERE account ~ "Assets:Checking"
-- one row, e.g. (2580.00 USD)

-- Find the date of the first and last transaction
SELECT FIRST(date), LAST(date)

-- Find the minimum and maximum position values
SELECT MIN(position), MAX(position)

-- Group by account to get a sum for each
SELECT account, SUM(position) GROUP BY account
```

### Funzioni di Posizione/Inventario

La colonna `position` è un oggetto composito. Queste funzioni ti permettono di estrarne parti specifiche o di calcolarne il valore di mercato.

```sql
-- Extract just the number and currency from a position
SELECT UNITS(position)

-- Show the total cost of a position
SELECT COST(position)

-- Show each posting at its cost value (a column; there is no WEIGHT() function)
SELECT account, weight WHERE account ~ "Assets:Investments"

-- Calculate the market value using the latest price data
-- (needs a price directive for the holding; otherwise the position is returned unchanged)
SELECT VALUE(position)
```

Puoi combinarle per creare report potenti. Ad esempio, per vedere il costo totale e il valore di mercato corrente del tuo portafoglio di investimenti. Il valore di mercato necessita di una direttiva `price` per ogni holding (ad esempio `2024-12-01 price HOOL 175.00 USD`). Entrambe le aggregazioni restituiscono un Inventory per conto, quindi ogni valuta è ancora elencata separatamente.

```sql
SELECT
    account,
    COST(SUM(position)) AS total_cost,
    VALUE(SUM(position)) AS market_value
FROM
    account ~ "Assets:Investments"
GROUP BY
    account
-- one row per account, e.g. Assets:Broker:HOOL | (2300.00 USD) | (2625.00 USD)
```

---

Le direttive price utilizzate dalle query sul valore di mercato possono provenire da voci manuali, da un fetcher locale di quotazioni o da [Live Prices](https://beancount.io/it/docs/live-prices) in un loader compatibile. I feed gestiti non cambiano la sintassi delle query. Gli strumenti upstream locali necessitano di file di prezzi locali, e le query storiche richiedono comunque prezzi alla data richiesta o precedenti.

## Funzionalità Avanzate

Oltre alle istruzioni `SELECT` di base, BQL offre comandi specializzati per i report finanziari più comuni.

### Report di Bilancio

L'istruzione `BALANCES` genera uno stato patrimoniale o un conto economico per un periodo specifico.

```sql
-- Generate a simple balance sheet as of the start of 2024
BALANCES FROM close ON 2024-01-01
WHERE account ~ "^Assets|^Liabilities"

-- Generate an income statement for the 2024 fiscal year
BALANCES FROM
    OPEN ON 2024-01-01
    CLOSE ON 2024-12-31
WHERE account ~ "^Income|^Expenses"
```

### Report di Giornale

L'istruzione `JOURNAL` mostra l'attività dettagliata di uno o più conti, in modo simile a una tradizionale vista di registro.

```sql
-- Show all activity in your checking account at its original cost
JOURNAL "Assets:Checking" AT COST

-- Show all 401k transactions, displaying only the units (shares)
JOURNAL "Assets:.*:401k" AT UNITS
```

### Operazioni di Stampa

L'istruzione `PRINT` è uno strumento di debug che produce transazioni complete e corrispondenti nel loro formato originale di file Beancount. Accetta solo un filtro sulle scritture. Una clausola `WHERE` qui è un errore di sintassi. Per restringere l'output a un lato di ogni scrittura, usa `SELECT` con un filtro sui posting. Restituisce una riga per ogni posting corrispondente.

```sql
-- Print all 2024 transactions in full (every posting of each matching entry)
PRINT FROM year = 2024

-- Show only the investment postings of 2024 transactions
SELECT date, narration, account, position
FROM year = 2024
WHERE account ~ "Assets:Investments"

-- Find a transaction by its unique ID (generated by some tools)
-- Returns the matching entry, or no rows when nothing carries that ID
PRINT FROM id = "8e7c47250d040ae2b85de580dd4f5c2a"
```

### Espressioni di Filtraggio

Puoi [costruire filtri sofisticati](https://beancount.io/it/docs/Tips/filtering-and-searching) usando operatori logici (`AND`, `OR`), espressioni regolari (`~`) e confronti.

I letterali stringa usano virgolette singole. Le virgolette doppie delimitano l'espressione regolare dopo `~`.

```sql
-- Find all travel expenses from the second half of 2024
-- SELECT * returns date, flag, payee, narration and position per matching posting
SELECT * FROM
    year = 2024 AND month >= 6
WHERE account ~ "Expenses:Travel"

-- Find all transactions related to a vacation or business
SELECT * FROM
    'vacation-2024' IN tags OR
    'business-trip' IN links
```

---

## Considerazioni sulle Prestazioni

`bea query` è progettato per l'efficienza, ma comprendere il suo flusso operativo può aiutarti a scrivere query più veloci su [registri di grandi dimensioni](https://beancount.io/it/docs/Tips/multi-file-support).

1. **Caricamento dei dati**: Beancount prima analizza l'intero file del tuo registro e ordina tutte le transazioni cronologicamente. L'intero dataset è mantenuto in memoria.
2. **Ottimizzazione della query**: Il motore di query applica i filtri in un ordine specifico per la massima efficienza: `FROM` (transazioni) -\> `WHERE` (postings) -\> Aggregazioni. Filtrare a livello `FROM` è più veloce perché riduce il dataset in anticipo.
3. **Utilizzo della memoria**: Tutte le operazioni avvengono in memoria. Gli oggetti `Position` e le aggregazioni `Inventory` sono ottimizzati, ma set di risultati molto grandi possono consumare RAM significativa. BQL non utilizza archiviazione temporanea su disco.

---

## Migliori Pratiche

Segui questi consigli per scrivere query pulite, efficaci e manutenibili.

1. **Organizzazione delle query**
   Formatta le tue query per la leggibilità, specialmente quelle complesse. Usa interruzioni di riga e indentazione per separare le clausole.

   ```sql
   -- A clean, readable query for all 2024 expenses
   SELECT
       date,
       account,
       position
   FROM
       year = 2024
   WHERE
       account ~ "Expenses"
   ORDER BY
       date DESC;
   ```

2. **Debugging**
   Se una query non funziona come previsto, esegui prima un piccolo campione con `LIMIT`. Per testare un filtro, usa `SELECT DISTINCT` per vedere quali valori unici corrisponde.

   ```sql
   -- Preview the first rows while iterating
   SELECT date, account, position LIMIT 5;

   -- Test which accounts match a regular expression
   SELECT DISTINCT account
   WHERE account ~ "^Assets:.*";
   ```

3. **Assertion di saldo**
   Puoi usare BQL per ricontrollare le assertion di `balance` nel tuo registro. Questa query dovrebbe restituire l'importo esatto specificato nel tuo ultimo controllo di saldo per quel conto.

   ```sql
   -- Verify the final balance of your checking account
   SELECT account, sum(position)
   FROM close ON 2025-01-01 -- Use the date from your balance directive
   WHERE account = "Assets:Checking";
   ```
