Interactive beanquery manual based on marimo notebook

[Chary Ev2geny]

Dear all,

I wanted to experiment with marimo notebooks (thanks to  Brian Lalor  for pointing to marimo).

But somehow I ended up creating the Interactive beanquery manual (which I wanted to create long time already, but Jupyter does not have a good mechanism to do this)

You can check it here:

https://github.com/Ev2geny/beanquery-interactive-manual

Interactive beanquery manual

This is an interactive manual and tutorial for beanquery — a customizable, extensible, lightweight SQL-like query tool for Beancount ledger data.

This document is intended as a follow-up to the Beancount v2 Beancount Query Language document.

It was created with the following goals in mind:

• to cover the latest features of beanquery
• to include many real examples using actual ledgers
• to be self-documenting: all query outputs are computed by running beanquery as part of the notebook execution
• to be interactive: when run as a marimo notebook, readers can experiment by changing the default ledgers and/or queries, with outputs updating automatically

Current state: work is ongoing

it is created based on the original Beancount Query Language document, posts in this group (especially from Daniel, especially for new features), and my personal experience on usage of beanquery.

It is still very much work in progress, yet I think it already covers 95% of the original document plus much more.

As I have a feeling I may not be having much time coming period, I decided to announce it in its current state.

https://github.com/Ev2geny/beanquery-interactive-manual

Comments, feedback and PRs are more then welcome!

And, once again, I would like to thank Daniel for his ongoing work on beanquery as well as his answers in this group.

Note, that I still have quite a lot of questions about the beanquery, I often put these questions directly in the document. Like this:

E.g.: ?? Why do we need this.

[Stefano Zacchiroli]

On Wed, Apr 15, 2026 at 02:05:42PM -0700, Chary Ev2geny wrote:
> You can check it here:
>
> https://github.com/Ev2geny/beanquery-interactive-manual

> [ direct link: https://ev2geny.github.io/beanquery-interactive-manual/ ]

This is AMAZING, thank you!

Since the new-ish syntax in BQL I have been struggling with finding the info I need between the (old) doc and interactive help.
Your interactive manual is great, because it can be used both as a reference, easily searchable with Ctrl+f and the like, and as a playground.

@Daniele: would you consider linking this resource from the main Beanquery repo, to make it more easily findable?

Cheers
--
Stefano Zacchiroli - https://upsilon.cc/zack
Full professor of Computer Science, Polytechnic Institute of Paris
Co-founder & CSO Software Heritage

[Martin Blais]

I've add it to the contribs list.

Thank you!

--
You received this message because you are subscribed to the Google Groups "Beancount" group.
To unsubscribe from this group and stop receiving emails from it, send an email to beancount+...@googlegroups.com.
To view this discussion visit https://groups.google.com/d/msgid/beancount/fmywchqeaajlvcmrcflypawg2h2y4jwry5bigrmlihcuyhoxdm%40w5a76ucnpehu.

[Chary Ev2geny]

On Thursday, April 16, 2026 at 9:21:42 AM UTC+2 Stefano Zacchiroli wrote:

This is AMAZING, thank you!

Stefano, 

thank you for your feedback. I really hope that people will submit PRs to the document and we can turn perhaps turn it into a community maintained manual / tutorial / reference / knowledge base about beanquery.

E.g. would be nice to receive contributions to the section 18. Example queries for typical situations

 

[Justus Pendleton]

This looks pretty impressive!

I haven't finished the whole thing but on the transaction id, one thing I've actually used it for other than debugging purposes is when I want to exclude a specific transaction from a query: usually because it is some outlier than throws off things. Yes, you can usually accomplish the same thing with clever and prescient usage of sub-accounts but I'm not always that clever. If I want to know, say, the average tax I paid (to forecast future tax) -- but also want to exclude that one-off tax from selling a house -- I can exclude just that transaction by throwing in an "AND id != xyz"

[Chary Ev2geny]

On Friday, April 17, 2026 at 8:20:28 AM UTC+2 just...@gmail.com wrote:

This looks pretty impressive!

Thanks for the feedback!

 

I haven't finished the whole thing but on the transaction id, one thing I've actually used it for other than debugging purposes is when I want to exclude a specific transaction from a query: usually because it is some outlier than throws off things. Yes, you can usually accomplish the same thing with clever and prescient usage of sub-accounts but I'm not always that clever. If I want to know, say, the average tax I paid (to forecast future tax) -- but also want to exclude that one-off tax from selling a house -- I can exclude just that transaction by throwing in an "AND id != xyz"

I will note to add this. But please also feel free to send me a PR