lnbits-exts/castle
1
0
Fork 0
Code Issues 2 Pull requests Projects Releases 2 Packages Wiki Activity Actions

Document BQL limitations and add reference comments

Browse source 
Added detailed comments to BQL methods explaining:
- Current limitation: cannot access posting metadata (sats-equivalent)
- BQL only queries position amounts (EUR/USD)
- Manual aggregation with caching remains the recommended approach
- Future consideration if ledger format changes

Changes:
- query_bql(): Added limitation warning and future consideration note
- get_user_balance_bql(): Added "NOT CURRENTLY USED" warning
- get_all_user_balances_bql(): Added "NOT CURRENTLY USED" warning

All methods kept as reference code for future architectural changes.

See: misc-docs/BQL-BALANCE-QUERIES.md for complete analysis.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
padreug 2025-11-10 23:36:42 +01:00
parent d8e3b79755
commit 89710a37a3
1 changed files with 38 additions and 8 deletions
Download patch file Download diff file Expand all files Collapse all files

46
fava_client.py
View file

@ -498,6 +498,15 @@ class FavaClient:
This is a general-purpose method for executing BQL queries against Fava/Beancount.
Use this for efficient aggregations, filtering, and data retrieval.
⚠️ LIMITATION: BQL can only query position amounts and transaction-level data.
It CANNOT access posting metadata (like 'sats-equivalent'). For Castle's current
ledger format where SATS are stored in metadata, manual aggregation is required.
See: misc-docs/BQL-BALANCE-QUERIES.md for detailed analysis and test results.
FUTURE CONSIDERATION: If Castle's ledger format changes to use SATS as position
amounts (instead of metadata), BQL could provide significant performance benefits.
Args:
query_string: BQL query (e.g., "SELECT account, sum(position) WHERE account ~ 'User-abc'")
@ -550,22 +559,33 @@ class FavaClient:
"""
Get user balance using BQL (efficient, replaces 115-line manual aggregation).
⚠️ NOT CURRENTLY USED: This method cannot access SATS balances stored in posting
metadata. It only queries position amounts (EUR/USD). For Castle's current ledger
format, use get_user_balance() instead (manual aggregation with caching).
This method uses Beancount Query Language for server-side filtering and aggregation,
resulting in 5-10x performance improvement over manual aggregation.
which would provide 5-10x performance improvement IF SATS were stored as position
amounts instead of metadata.
FUTURE CONSIDERATION: If Castle's ledger format changes to store SATS as position
amounts (e.g., "100000 SATS {100.00 EUR}"), this method would become feasible and
provide significant performance benefits.
See: misc-docs/BQL-BALANCE-QUERIES.md for detailed test results and analysis.
Args:
user_id: User ID
Returns:
{
"balance": int (sats),
"fiat_balances": {"EUR": Decimal("100.50"), ...},
"balance": int (sats), # Currently returns 0 (cannot access metadata)
"fiat_balances": {"EUR": Decimal("100.50"), ...}, # Works correctly
"accounts": [{"account": "...", "sats": 150000}, ...]
}
Example:
balance = await fava.get_user_balance_bql("af983632")
print(f"Balance: {balance['balance']} sats")
print(f"Balance: {balance['balance']} sats") # Will be 0 with current ledger format
"""
from decimal import Decimal
import re
@ -647,15 +667,25 @@ class FavaClient:
"""
Get balances for all users using BQL (efficient admin view).
⚠️ NOT CURRENTLY USED: This method cannot access SATS balances stored in posting
metadata. It only queries position amounts (EUR/USD). For Castle's current ledger
format, use get_all_user_balances() instead (manual aggregation with caching).
This method uses Beancount Query Language to query all user balances
in a single efficient query, instead of fetching all entries and manually aggregating.
in a single efficient query, which would be faster than fetching all entries IF
SATS were stored as position amounts instead of metadata.
FUTURE CONSIDERATION: If Castle's ledger format changes to store SATS as position
amounts, this method would provide significant performance benefits for admin views.
See: misc-docs/BQL-BALANCE-QUERIES.md for detailed test results and analysis.
Returns:
[
{
"user_id": "abc123",
"balance": 100000,
"fiat_balances": {"EUR": Decimal("100.50")},
"balance": 100000, # Currently 0 (cannot access metadata)
"fiat_balances": {"EUR": Decimal("100.50")}, # Works correctly
"accounts": [{"account": "...", "sats": 150000}, ...]
},
...
@ -664,7 +694,7 @@ class FavaClient:
Example:
all_balances = await fava.get_all_user_balances_bql()
for user in all_balances:
print(f"{user['user_id']}: {user['balance']} sats")
print(f"{user['user_id']}: {user['balance']} sats") # Will be 0 with current format
"""
from decimal import Decimal
import re