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.


Path Expression

Similar to a path, but with character '*' allowed to express a set of paths.

  • 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.


Selector

A string which is the conjunction of an path expression identifying a set of paths 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.

  • 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.

By default zenoh is able to transport and store any format of data as long as it’s serializable as a bytes buffer. But for advanced features such as content filtering (using selector) or to automatically deserialize the data into a concrete type in the client APIs, zenoh require a description of the data encoding.

The current version of zenoh supports the following encodings for filtering and automatic deserialization:

  • Raw: the value is a bytes buffer
  • StringUTF8: the value is an UTF-8 string
  • Json: the value is a JSON string
  • Properties: the value is a string representing a list of keys/values separated by ';' (e.g. "k1=v1;k2=v2...")
  • Integer: the value is an integer
  • Float: the value is a float
  • Custom: the value is a bytes buffer with a free string allowing for instance to describe its encoding

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.