transaction.find

Find splits with the criteria of GnuCash's Find Transaction dialog.

Finds splits with the criteria of GnuCash's Find Transaction dialog and returns each match as a {transaction, split, account} triple. A query is an object with one key: a criterion (description, notes, memo, num, action, datePosted, value, amount, reconcile, void, accounts, and more) or all, any or not of other queries. Text matches ignore case unless matchCase is set; limit keeps the last n matches.

The result lists splits, not transactions, so a two-split transaction that matches on its description appears twice. Regular expressions (matchesRegex) are Rust's regex syntax, close to GnuCash's POSIX extended; text ties in the sort go by code point instead of locale.

Examples

Example: with a copy of the reports/test-data example book open as book.gnucash.

JSON-RPC

Request:

{"jsonrpc":"2.0","id":1,"method":"transaction.find","params":{"query":{"all":[{"description":{"text":"$22 expense"}},{"datePosted":{"op":"before","date":"1978-03-01"}}]}}}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "matches": [
      {
        "transaction": "c000000000000000000000000000000d",
        "split": "…",
        "account": "…"
      },
      {
        "transaction": "c000000000000000000000000000000d",
        "…": "…"
      },
      {
        "transaction": "c0000000000000000000000000000011",
        "…": "…"
      },
      {
        "transaction": "c0000000000000000000000000000011",
        "…": "…"
      }
    ]
  }
}

Command line

red-ale exec --book book.gnucash transaction.find '{"query":{"all":[{"description":{"text":"$22 expense"}},{"datePosted":{"op":"before","date":"1978-03-01"}}]}}'

It prints:

{
  "matches": [
    {
      "transaction": "c000000000000000000000000000000d",
      "split": "…",
      "account": "…"
    },
    {
      "transaction": "c000000000000000000000000000000d",
      "…": "…"
    },
    {
      "transaction": "c0000000000000000000000000000011",
      "…": "…"
    },
    {
      "transaction": "c0000000000000000000000000000011",
      "…": "…"
    }
  ]
}

MCP tool call

Tool call:

{"name":"transaction.find","arguments":{"query":{"all":[{"description":{"text":"$22 expense"}},{"datePosted":{"op":"before","date":"1978-03-01"}}]}}}

Result:

{
  "structuredContent": {
    "matches": [
      {
        "transaction": "c000000000000000000000000000000d",
        "split": "…",
        "account": "…"
      },
      {
        "transaction": "c000000000000000000000000000000d",
        "…": "…"
      },
      {
        "transaction": "c0000000000000000000000000000011",
        "…": "…"
      },
      {
        "transaction": "c0000000000000000000000000000011",
        "…": "…"
      }
    ]
  }
}

Effect: read.

Params

Params of transaction.find.

query (FindQuery, required): The query.
limit (integer (uint) or null): Keep only the last this many matches, as GnuCash keeps them when a limit applies.

Result

The result of transaction.find.

matches (array of Match, required): The splits found, in GnuCash's split order (xaccSplitOrder): by transaction (posted date, num, date entered, description), then memo, action, reconcile state, amount, value.