API: Select zettel based on their metadata

00001012051810 · Info · (manual) · #api #manual #zettelstore

Every query parameter that does not begin with the low line character (_, U+005F) is treated as the name of a metadata key. According to the type of a metadata key, zettel are possibly selected. All supported metadata keys have a well-defined type. User-defined keys have the type e (string, possibly empty).

For example, if you want to retrieve all zettel that contain the string API in its title, your request will be:

# curl 'http://127.0.0.1:23123/j?title=API'
{"query":"title MATCH API","list":[{"id":"00001012921000","meta":{"title":"API: JSON structure of an access token","tags":"#api #manual #reference #zettelstore","syntax":"zmk","role":"manual"}},{"id":"00001012920500","meta":{"title":"Formats available by the API","tags":"#api #manual #reference #zettelstore","syntax":"zmk","role":"manual"}},{"id":"00001012920000","meta":{"title":"Endpoints used by the API","tags":"#api #manual #reference #zettelstore","syntax":"zmk","role":"manual"}}, ...

However, if you want all zettel that does not match a given value, you must prefix the value with the exclamation mark character (!, U+0021). For example, if you want to retrieve all zettel that do not contain the string API in their title, your request will be:

# curl 'http://127.0.0.1:23123/j?title=!API'
{"query":"title NOT MATCH API","list":[{"id":"00010000000000","meta":{"back":"00001003000000 00001005090000","backward":"00001003000000 00001005090000","copyright":"(c) 2020-2021 by Detlef Stern <ds@zettelstore.de>","forward":"00000000000001 00000000000003 00000000000096 00000000000100","lang":"en","license":"EUPL-1.2-or-later","role":"zettel","syntax":"zmk","title":"Home"}},{"id":"00001014000000","meta":{"back":"00001000000000 00001004020000 00001012920510","backward":"00001000000000 00001004020000 00001012000000 00001012920510","copyright":"(c) 2020-2021 by Detlef Stern <ds@zettelstore.de>","forward":"00001012000000","lang":"en","license":"EUPL-1.2-or-later","published":"00001014000000","role":"manual","syntax":"zmk","tags":"#manual #webui #zettelstore","title":"Web user interface"}},
...

In both cases, an implicit precondition is that the zettel must contain the given metadata key. For a metadata key like title, which has a default value, this precondition should always be true. But the situation is different for a key like url. Both curl 'http://localhost:23123/j?url=' and curl 'http://localhost:23123/j?url=!' may result in an empty list.

The empty query parameter values matches all zettel that contain the given metadata key. Similar, if you specify just the exclamation mark character as a query parameter value, only those zettel match that does not contain the given metadata key. This is in contrast to above rule that the metadata value must exist before a match is done. For example curl 'http://localhost:23123/j?back=!&backward=' returns all zettel that are reachable via other zettel, but also references these zettel.

As stated above, the exact rule for comparison depends on the type of the specified metadata key. By using a simple search syntax, you are able to specify other comparison operations.1

Above example shows that all sub-expressions of a select specification must be true so that no zettel is rejected from the final list.

If you specify the query parameter _negate, either with or without a value, the whole selection will be negated. Because of the precondition described above, curl 'http://127.0.0.1:23123/j?url=!com' and curl 'http://127.0.0.1:23123/j?url=com&_negate' may produce different lists. The first query produces a zettel list, where each zettel does have a url metadata value, which does not contain the characters com. The second query produces a zettel list, that excludes any zettel containing a url metadata value that contains the characters com; this also includes all zettel that do not contain the metadata key url.

Alternatively, you also can use the endpoint /z for a simpler result format. The first example translates to:

# curl 'http://127.0.0.1:23123/z?title=API'
00001012921000 API: JSON structure of an access token
00001012920500 Formats available by the API
00001012920000 Endpoints used by the API
...
  1. One is the already mentioned exclamation mark character. ↩︎