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:
Zenoh uses paths as keys. In all zenoh documentations, “key” and “path” are synonym.
A set of strings separated by
'/' , as in a filesystem path. A Path cannot contain any
Examples of paths:
A path can be absolute (i.e. starting with a
'/') or relative to a workspace.
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
"**"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.
/s1/s2/.../sn?x>1&y<2&...&z=4(p1=v1;p2=v2;...;pn=vn)#a;b;x;y;...;z | | | | | | | | |-- expr ---| |--- filter --| |---- properties ---| |--fragment-|
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 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.
A user provided data item along with its 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
- 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
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.
See Zenoh backends chapter for details and for the list of supported backends in the current version.
An entity storing keys/values on a specific backend.
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.
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.
The abstraction that give you access to zenoh primitives.
The administration space of zenoh allowing to administrate a zenoh router and its plugins.
It is accessible via regular get/put on zenoh, under the
/@/router/<router-id> path prefix, where
<router-id> is is the UUID of a zenoh router.
For instance, the following paths can be used:
Returns a JSON with the status informations about the router.
On get, returns the properties of the backend with the specified ID.
On put, make the router to dynamically load a backend library with the properties specified as the value.
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.
When using the REST API, you can replace the
<router-id> with the
meaning the operation addresses the zenoh router the HTTP client is connected to.