Next: , Previous: File format, Up: Running Ledger


2.8 Some typical queries

A query such as the following shows all expenses since last October, sorted by total:

     ledger -b "last oct" -s -S T bal ^expenses

From left to right the options mean: Show entries since October, 2003; show all sub-accounts; sort by the absolute value of the total; and report the balance for all expenses.

2.8.1 Reporting monthly expenses

The following query makes it easy to see monthly expenses, with each month's expenses sorted by the amount:

     ledger -M --period-sort t reg ^expenses

Now, you might wonder where the money came from to pay for these things. To see that report, add -r, which shows the “related account” transactions:

     ledger -M --period-sort t -r reg ^expenses

But maybe this prints too much information. You might just want to see how much you're spending with your MasterCard. That kind of query requires the use of a display predicate, since the transactions calculated must match ‘^expenses’, while the transactions displayed must match ‘mastercard’. The command would be:

     ledger -M -r -d /mastercard/ reg ^expenses

This query says: Report monthly subtotals; report the “related account” transactions; display only related transactions whose account matches ‘mastercard’, and base the calculation on transactions matching ‘^expenses’.

This works just as well for report the overall total, too:

     ledger -s -r -d /mastercard/ reg ^expenses

The -s option subtotals all transactions, just as -M subtotaled by the month. The running total in both cases is off, however, since a display expression is being used.

2.8.2 Visualizing with Gnuplot

If you have Gnuplot installed, you can graph any of the above register reports. The script to do this is included in the ledger distribution, and is named scripts/report. Install report anywhere along your PATH, and then use report instead of ledger when doing a register report. The only thing to keep in mind is that you must specify -j or -J to indicate whether Gnuplot should plot the amount, or the running total. For example, this command plots total monthly expenses made on your MasterCard.

     report -j -M -r -d /mastercard/ reg ^expenses

The report script is a very simple Bourne shell script, that passes a set of scripted commands to Gnuplot. Feel free to modify the script to your liking, since you may prefer histograms to line plots, for example.

2.8.2.1 Typical plots

Here are some useful plots:

     report -j -M reg ^expenses         # monthly expenses
     report -J reg checking             # checking account balance
     report -J reg ^income ^expenses    # cash flow report
     
     # net worth report, ignoring non-$ transactions
     
     report -J -l "Ua>={\$0.01}" reg ^assets ^liab
     
     # net worth report starting last February.  the use of a display
     # predicate (-d) is needed, otherwise the balance will start at
     # zero, and thus the y-axis will not reflect the true balance
     
     report -J -l "Ua>={\$0.01}" -d "d>=[last feb]" reg ^assets ^liab

The last report uses both a calculation predicate (-l) and a display predicate (-d). The calculation predicates limits the report to transactions whose amount is greater than $1 (which can only happen if the transaction amount is in dollars). The display predicate limits the entries displayed to just those since last February, even those entries from before then will be computed as part of the balance.