# Search term

A search term allows you to specify one search restriction. The result search expression, which contains more than one search term, will be the applications of all restrictions.

A search term can be one of the following (the first three term are collectively called *search literals*):

A metadata-based search, by specifying the name of a metadata key, followed by a search operator, followed by an optional search value.

All zettel containing the given metadata key with a allowed value (depending on the search operator) are selected.

If no search value is given, then all zettel containing the given metadata key are selected (or ignored, for a negated search operator).

An optional search operator, followed by a search value.

This specifies a full-text search for the given search value.

**Note:**the search value will be normalized according to Unicode NKFD, ignoring everything except letters and numbers. Therefore, the following search expression are essentially the same:`"search syntax"`and`search syntax`. The first is a search expression with one search value, which is normalized to two strings to be searched for. The second is a search expression containing two search values, giving two string to be searched for.A metadata key followed by

or`?`

.`!?`Is true, if zettel metadata contains / does not contain the given key.

The string

`OR`signals that following search literals may occur alternatively in the result.Since search literals may be negated, it is possible to form any boolean search expression. Any search expression will be in a disjunctive normal form.

It has no effect on the following search terms initiated with a special uppercase word.

The string

`PICK`, followed by a non-empty sequence of spaces and a number greater zero (calledN

).This will pick randomly N elements of the result list. A zero value of N will produce the same result as if nothing was specified. If specified multiple times, the lower value takes precedence.

Example:

`PICK 5 PICK 3`will be interpreted as`PICK 3`.The string

`ORDER`, followed by a non-empty sequence of spaces and the name of a metadata key, will specify an ordering of the result list. If you include the string`REVERSE`after`ORDER`but before the metadata key, the ordering will be reversed.Example:

`ORDER published`will order the resulting list based on the publishing data, while`ORDER REVERSED published`will return a reversed result order.An explicit order field will take precedence over the random order described below.

If no random order is effective, a

`ORDER REVERSE id`

will be added. This makes the sort stable.Example:

`ORDER created`

will be interpreted as`ORDER created ORDER REVERSE id`

.Any ordering by zettel identifier will make following order terms to be ignored.

Example:

`ORDER id ORDER created`

will be interpreted as`ORDER id`

.The string

`RANDOM`will provide a random order of the resulting list.Currently, only the first term specifying the order of the resulting list will be used. Other ordering terms will be ignored.

A random order specification will be ignored, if there is an explicit ordering given or if the specification contains a valid

`PICK`.Example:

`RANDOM ORDER published`will be interpreted as`ORDER published`,`PICK 3 RANDOM`will be interpreted as`PICK 3`.The string

`OFFSET`, followed by a non-empty sequence of spaces and a number greater zero (calledN

).This will ignore the first N elements of the result list, based on the specified sort order. A zero value of N will produce the same result as if nothing was specified. If specified multiple times, the higher value takes precedence.

Example:

`OFFSET 4 OFFSET 8`will be interpreted as`OFFSET 8`.The string

`LIMIT`, followed by a non-empty sequence of spaces and a number greater zero (calledN

).This will limit the result list to the first N elements, based on the specified sort order. A zero value of N will produce the same result as if nothing was specified. If specified multiple times, the lower value takes precedence.

Example:

`LIMIT 4 LIMIT 8`will be interpreted as`LIMIT 4`.

You may have noted that the specifications of first two items overlap somehow. This is resolved by the following rule:

- A search term containing no search operator character is treated as a full-text search.
- The first search operator character found in a search term divides the term into two pieces. If the first piece, from the beginning of the search term to the search operator character, is syntactically a metadata key, the search term is treated as a metadata-based search.
- Otherwise, the search term is treated as a full-text search.

If a term like `PICK`, `ORDER`, `ORDER REVERSE`, `OFFSET`, or `LIMIT` is not followed by an appropriate value, it is interpreted as a search value for a full-text search. For example, `ORDER 123` will search for a zettel conatining the strings ORDER

(case-insensitive) and 123

.

A specification `RANDOM LIMIT n` (with some valid value of `n`) will be interpreted as `PICK n`. Similar, a specification `PICK n`, where `n` is greater or equal to the length of the result list, will be interpreted as `RANDOM`. A specification `LIMIT n`, where `n` is greater or equal to the length of the result list, will be ignored effectively.