Managing Stream Metadata#
BTrDB has multiple options for storing stream metadata including
collection, tags, annotations, and others. Most metadata is returned as a
string
, or specialized object such as the UUID. Tags and annotations
are returned as dict
objects.
There is also the concept of the “property version” which is a version counter
that applies only to the metadata and is separate from the version incremented
with changes to the data. See the API docs for Stream.annotations
or
Stream.update
for more information.
Viewing Metadata#
Viewing the metadata for a Stream is as simple as calling the appropriate property or method. In cases where the data is not expected to change quickly, a Stream instance will provide you with cached values unless you force it to refresh with the server.
UUID#
The uuid
property of a Stream
is read-only and will return an
instance of class UUID
.
stream.uuid
>> UUID('07d28a44-4991-492d-b9c5-2d8cec5aa6d4')
Annotations#
Similar to tags, annotations are key/value pairs that are available for your use
to store extra information about the Stream
.
Because annotations may change more often than tags, a metadata version number is also returned when asking for annotations. This version number is incremented whenever metadata (tags, annotations, collection, etc.) are updated but not when making changes to the underlying time series data.
By default the method will attempt to provide a cached copy of the annotations however you can request the latest version from the server using the refresh argument. As with tags, annotations values also have a 255 character limit.
stream.annotations(refresh=True)
>> ({'owner': 'Salvatore McFesterson', 'state': 'NH'}, 44)
Name and Collection#
The name
and collection
properties of a Stream are read-only and
will return instances of str
. Note that the name
property is
just a convenience as this value can also be found within the tags.
stream.collection
>> 'NORTHEAST/VERMONT/Burlington'
stream.name
>> 'L1MAG'
Updating Metadata#
An update
method is available if you would like to make changes to
the tags, annotations, or collection. By default, all updates are implemented
as an UPSERT operation and a single change could result in multiple increments
to the property version (the version of the metadata).
Upon calling this method, the library will first verify that the local property version of your stream object matches the version found on the server. If the two versions do not match then you will not be allowed to perform an update as this implies that the data has already been changed by another user or process.
collection = 'NORTHEAST/VERMONT'
annotations = {
'owner': 'Salvatore McFesterson',
'state': 'VT',
'created': '2018-01-01 12:42:03 -0500'
}
property_version = stream.update(
collection=collection,
annotations=annotations
)
If you would like to remove any keys from your annotations you must use the replace=True
keyword argument. This will ensure that the annotations dictionary you provide completely replaces the existing values rather than perform an UPSERT operation. The example below shows how you could remove an existing key from the annotations dictionary.
annotations, _ = stream.anotations()
del annotations["key_to_delete"]
stream.update(annotations=annotations, replace=True)