slaesvuo/hledger
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

;doc: queries: cleanups (#1625)

Browse Source
This commit is contained in:
Simon Michael 2021-07-27 22:16:24 -10:00
parent a4d8072393
commit 6a92953111
1 changed files with 123 additions and 78 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

201
hledger/hledger.m4.md
View File

@ -691,105 +691,150 @@ This flag has the same effect as a `depth:` query argument
# QUERIES # QUERIES
One of hledger's strengths is being able to quickly report on precise subsets of your data. One of hledger's strengths is being able to quickly report on a precise subset of your data.
Most commands accept an optional query expression, written as arguments after the command name, Most hledger commands accept an optional query to restrict their scope.
to filter the data by date, account name or other criteria. The syntax is as follows:
The syntax is similar to a web search:
one or more space-separated search terms,
quotes to enclose whitespace,
prefixes to match specific fields,
a not: prefix to negate the match.
We do not yet support arbitrary boolean combinations of search terms; - Zero or more space-separated query terms.
instead most commands show transactions/postings/accounts which match (or negatively match): These are most often [account name](#account-names) substrings:
`utilities food:groceries`
- Terms with spaces or other [special characters](#special-characters) should be enclosed in quotes:
`"personal care"`
- [Regular expressions](#regular-expressions) are also supported:
`"^expenses\b" "accounts (payable|receivable)"`
- Add a query type prefix to match other parts of the data:
`date:202012- desc:amazon cur:USD amt:">100" status:`
- Add a `not:` prefix to negate a term:
`not:cur:USD`
## Query types
Here are the types of query term available.
Remember these can also be prefixed with **`not:`** to convert them into a negative match.
**`acct:REGEX`, `REGEX`**\
Match account names containing this (case insensitive) [regular expression].
This is the default query type when there is no prefix,
and regular expression syntax is typically not needed,
so usually we just write an account name substring, like `expenses` or `food`.
**`amt:N, amt:<N, amt:<=N, amt:>N, amt:>=N`**\
Match postings with a single-commodity amount equal to, less than, or greater than N.
(Postings with multi-commodity amounts are not tested and will always match.)
The comparison has two modes:
if N is preceded by a + or - sign (or is 0), the two signed numbers are compared.
Otherwise, the absolute magnitudes are compared, ignoring sign.
**`code:REGEX`**\
Match by transaction code (eg check number).
**`cur:REGEX`**\
Match postings or transactions including any amounts whose
currency/commodity symbol is fully matched by REGEX. (For a partial
match, use `.*REGEX.*`).
Note, to match [special characters](#special-characters) which are regex-significant, you need to escape them with `\`.
And for characters which are significant to your shell you may need one more level of escaping.
So eg to match the dollar sign:\
`hledger print cur:\\$`.
**`desc:REGEX`**\
Match transaction descriptions.
**`date:PERIODEXPR`**\
Match dates (or with the `--date2` flag, [secondary dates](#secondary-dates))
within the specified period.
PERIODEXPR is a [period expression](#period-expressions) with no report interval.
Examples:\
`date:2016`, `date:thismonth`, `date:2/1-2/15`, `date:2021-07-27..nextquarter`.
**`date2:PERIODEXPR`**\
Match secondary dates within the specified period (independent of the `--date2` flag).
**`depth:N`**\
Match (or display, depending on command) accounts at or above this depth.
**`note:REGEX`**\
Match transaction [notes](#payee-and-note)
(the part of the description right of `|`, or the whole description if there's no `|`).
**`payee:REGEX`**\
Match transaction [payee/payer names](#payee-and-note)
(the part of the description left of `|`, or the whole description if there's no `|`).
**`real:, real:0`**\
Match real or virtual postings respectively.
**`status:, status:!, status:*`**\
Match unmarked, pending, or cleared transactions respectively.
**`tag:REGEX[=REGEX]`**\
Match by tag name, and optionally also by tag value.
(To match only by value, use `tag:.=REGEX`.)
Note that postings also inherit tags from their transaction,
and transactions also acquire tags from their postings,
when querying.
(**`inacct:ACCTNAME`**\
A special query term used automatically in hledger-web only:
tells hledger-web to show the transaction register for an account.)
## Combining query terms
Most commands select things which match:
- any of the description terms AND - any of the description terms AND
- any of the account terms AND - any of the account terms AND
- any of the status terms AND - any of the status terms AND
- all the other terms. - all the other terms.
The [print](#print) command instead shows transactions which: while the [print](#print) command shows transactions which:
- match any of the description terms AND - match any of the description terms AND
- have any postings matching any of the positive account terms AND - have any postings matching any of the positive account terms AND
- have no postings matching any of the negative account terms AND - have no postings matching any of the negative account terms AND
- match all the other terms. - match all the other terms.
The following kinds of search terms can be used. You can do more powerful queries (such as AND-ing two like terms)
Remember these can also be prefixed with **`not:`**, eg to exclude a particular subaccount. by running a first query with `print`,
and piping the result into a second hledger command.
Eg: how much of food expenses was paid with cash ?
**`REGEX`, `acct:REGEX`** ```shell
: match account names by this [regular expression]. $ hledger print assets:cash | hledger f- -I balance expenses:food
(With no prefix, `acct:` is assumed.) ```
: same as above If you are interested in full boolean expressions for queries,
see [#203](https://github.com/simonmichael/hledger/issues/203).
**`amt:N, amt:<N, amt:<=N, amt:>N, amt:>=N`** ## Queries and command options
: match postings with a single-commodity amount that is equal to, less
than, or greater than N. (Multi-commodity amounts are not tested, and
will always match.) The comparison has two modes: if N is preceded by
a + or - sign (or is 0), the two signed numbers are
compared. Otherwise, the absolute magnitudes are compared, ignoring
sign.
**`code:REGEX`** Some queries can also be expressed as command-line options:
: match by transaction code (eg check number) `depth:2` is equivalent to `--depth 2`,
`date:2020` is equivalent to `-p 2020`, etc.
When you mix command options and query arguments,
generally the resulting query is their intersection.
**`cur:REGEX`** ## Queries and account aliases
: match postings or transactions including any amounts whose
currency/commodity symbol is fully matched by REGEX. (For a partial
match, use `.*REGEX.*`). Note, to match characters which are
regex-significant, like the dollar sign (`$`), you need to prepend `\`.
And when using the command line you need to add one more level of
quoting to hide it from the shell, so eg do: `hledger print cur:'\$'`
or `hledger print cur:\\$`.
**`desc:REGEX`** When account names are [rewritten](rewriting-accounts) with `--alias` or `alias`,
: match transaction descriptions. `acct:` will match either the old or the new account name.
**`date:PERIODEXPR`** ## Queries and valuation
: match dates within the specified period.
PERIODEXPR is a [period expression](#period-expressions) (with no report interval).
Examples: `date:2016`, `date:thismonth`, `date:2000/2/1-2/15`, `date:lastweek-`.
If the `--date2` command line flag is present, this matches [secondary dates](#secondary-dates) instead.
([Report intervals](#report-intervals) will adjust [start/end dates](report-start--end-date)
to preceding/following subperiod boundaries.)
**`date2:PERIODEXPR`** When amounts are converted to other commodities in [cost](#costing) or [value](#valuation) reports,
: match secondary dates within the specified period. `cur:` and `amt:` match the old commodity symbol and the old amount quantity,
not the new ones
**`depth:N`** (except in hledger 1.22.0 where it's reversed, see [#1625](https://github.com/simonmichael/hledger/issues/1625)).
: match (or display, depending on command) accounts at or above this depth
**`note:REGEX`**
: match transaction [notes](#payee-and-note)
(part of description right of `|`, or whole description when there's no `|`)
**`payee:REGEX`**
: match transaction [payee/payer names](#payee-and-note)
(part of description left of `|`, or whole description when there's no `|`)
**`real:, real:0`**
: match real or virtual postings respectively
**`status:, status:!, status:*`**
: match unmarked, pending, or cleared transactions respectively
**`tag:REGEX[=REGEX]`**
: match by tag name, and optionally also by tag value. Note a
tag: query is considered to match a transaction if it matches any of
the postings. Also remember that postings inherit the tags of their
parent transaction.
The following special search term is used automatically in hledger-web, only:
**`inacct:ACCTNAME`**
: tells hledger-web to show the transaction register for this account.
Can be filtered further with `acct` etc.
Some of these can also be expressed as command-line options (eg `depth:2` is equivalent to `--depth 2`).
Generally you can mix options and query arguments, and the resulting query will be their intersection
(perhaps excluding the `-p/--period` option).
## Querying with account aliases ## Querying with account aliases