Abstractions

Zenoh is a distributed service to define, manage and operate on key/value spaces.

The key abstractions at the core of zenoh are the following:

Key

Zenoh uses paths as keys. In all zenoh documentations, “key” and “path” are synonym.


Path

A set of strings separated by '/' , as in a filesystem path. A Path cannot contain any '*' character.
Examples of paths: /demo/example/test , /com/adlink/building/fr/floor/1/office/2

A path can be absolute (i.e. starting with a '/') or relative to a workspace.


Selector

A string which is the conjunction of an path expression identifying a set of keys and some optional parts allowing to refine the set of paths and associated values.
Structure of a selector:

/s1/s2/.../sn?x>1&y<2&...&z=4(p1=v1;p2=v2;...;pn=vn)#a;b;x;y;...;z
|           | |             | |                   |  |           |
|-- expr ---| |--- filter --| |---- properties ---|  |--fragment-|

where:

  • expr: is a path expression. I.e. a string similar to a path but with character '*' allowed.
    A single '*' matches any set of characters in a path, except '/'.
    While "**" matches any set of characters in a path, including '/'.
    A path expression can be absolute (i.e. starting with a '/') or relative to a workspace.

  • filter: a list of predicates separated by '&' allowing to perform filtering on the values associated with the matching keys.
    Each predicate has the form field``operator value where:

    • field is the name of a field in the value (is applicable and is existing. otherwise the predicate is false)
    • operator is one of a comparison operators: < , > , <= , >= , = , !=
    • value is the the value to compare the field's value with
  • fragment: a list of fields names allowing to return a sub-part of each value.
    This feature only applies to structured values using a “self-describing” encoding, such as JSON or XML. It allows to select only some fields within the structure. A new structure with only the selected fields will be used in place of the original value.

NOTE: the filters and fragments are not yet supported in current zenoh version.


Value

A user provided data item along with its encoding.


Encoding

A description of the value format, allowing zenoh to know how to encode/decode the value to/from a bytes buffer.

The current version of zenoh supports the following encodings:

  • RAW: the value is a bytes buffer
  • string: the value is a string
  • JSON: the value is a JSON string
  • Properties: the value is a string representing a list of keys/values separated by ;: k1=v1;k2=v2...

Timestamp

When a value is put into zenoh, the first zenoh router receiving this value automatically associates it with a timestamp.
This timestamp is made of 2 items:

  • A time generated by a Hybrid Logical Clock (HLC). This time is a 64-bit time with a similar structure than a NTP timestamp (but with a different epoch):

    • the higher 32-bit part is the number of seconds since midnight, January 1, 1970 UTC (implying a roll over in 2106).
    • the lower 32-bit part is a fraction of second, but with the 8 last bits replaced by a counter.

    This time gives a theoritical resolution of 2^-32 seconds (60 nanoseconds), and guarantees that the same time cannot be generated twice and that the happened-before relationship is preserved.

  • The UUID of the zenoh router that generated the time.

Such a timestamp allows zenoh to guarantee that each value introduced into the system has a unique timestamp, and that those timestamps (and therefore the values) can be ordered in the same way at any point of the system, without the need of any consensus algorithm.


Backend

A storage technology, such as DBMS, Main Memory, time-series database, etc.

See zenoh backends for the list of supported backends in the current version.


Storage

An entity storing tuples on a specific backend.

A storage is associated at its creation to a selector. Storages can be created by applications and take responsibility for storing all keys/values whose path matches the storage selector.


Subscriber

An entity registering interest for being notified whenever a key/value with a path matchings the subscriber selector is put, updated or removed on zenoh.


Eval

A computation registered at a specific path.

This computation can be triggered by a get operation on a selector matching this path. The computation function will receive the selector's properties as parameter.


Workspace

The abstraction that give you access to zenoh primitives.

A workspace is associated to a path at creation. This path will be used as a prefix for any relative path or selector used with this workspace.


Admin space

The administration space of zenoh. It is accessible via regular get/put on zenoh, under the /@/router/<zenoh-id> path prefix. The following paths can be used:

  • /@/router/<zenoh-id>/plugin/storages (read-only):
    Returns a JSON with the overview of the full storages (and their parent backends) configuration.
  • /@/router/<zenoh-id>/plugin/storages/backend/<backend-id> (read/write):
    On get, returns the properties of the backend with the specified ID.
    On put, adds a backend with the properties specified as the value.
  • /@/router/<zenoh-id>/plugin/storages/backend/<backend-id>/storage/<storage-id> (read/write):
    On get, returns the properties of the storage with the specified ID.
    On put, adds a storage in the parent backend with the properties specified as the value.
    On remove, removes the storage.

In all those paths, the <zenoh-id> is the UUID of a zenoh router.

Note that the zenoh client APIs provide an Admin interface that facilitate the addition/removal of backends and storage. Underneath, this interface calls put/remove/get operations on those paths. By default, this interface knows the <zenoh-id> of the zenoh router it's connected to and automatically use it in paths, if no alternative <zenoh-id> is provided.

When using the REST API, the user can replace the <zenoh-id> with the local keyword, meaning the operation addresses the zenoh router the HTTP client is connected to.

Next up: Zenoh backends