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.

  However, the operators “less” and “greater” are not supported, they are internally translated into the “match” operators. Similar, “not less” and “not greater” are translated into “not match”. It simply does not make sense to search the content of all zettel for words less than a specific word, for example.

  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 (called “N”).

  This will pick randomly N elements of the result list, preserving the order of that 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 REVERSE 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.

  Example: RANDOM ORDER published will be interpreted as ORDER published.

• The string OFFSET, followed by a non-empty sequence of spaces and a number greater zero (called “N”).

  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 (called “N”).

  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 containing the strings “ORDER” (case-insensitive) and “123”.