btrdb.conn#

Connection related objects for the BTrDB library

class btrdb.conn.BTrDB(endpoint)#

The primary server connection object for communicating with a BTrDB server.

Methods

`collection_metadata`(prefix[, auto_retry, ...])	Gives statistics about metadata for collections that match a prefix.
`create`(uuid, collection[, tags, ...])	Tells BTrDB to create a new stream with UUID uuid in collection with specified tags and annotations.
`info`()	Returns information about the connected BTrDB server.
`list_collections`([starts_with])	Returns a list of collection paths using the starts_with argument for filtering.
`list_unique_annotations`([collection])	Returns a list of annotation keys used in a given collection prefix.
`list_unique_names`([collection])	Returns a list of names used in a given collection prefix.
`list_unique_units`([collection])	Returns a list of units used in a given collection prefix.
`query`(stmt[, params, auto_retry, retries, ...])	Performs a SQL query on the database metadata and returns a list of dictionaries from the resulting cursor.
`stream_from_uuid`(uuid)	Creates a stream handle to the BTrDB stream with the UUID uuid.
`streams`(*identifiers[, versions, ...])	Returns a StreamSet object with BTrDB streams from the supplied identifiers.
`streams_in_collection`(*collection[, ...])	Search for streams matching given parameters

collection_metadata(prefix, auto_retry=False, retries=5, retry_delay=3, retry_backoff=4)#

Gives statistics about metadata for collections that match a prefix.

Parameters:

prefix (str, required) – A prefix of the collection names to look at
auto_retry (bool, default: False) – Whether to retry this request in the event of an error
retries (int, default: 5) – Number of times to retry this request if there is an error. Will be ignored if auto_retry is False
retry_delay (int, default: 3) – initial time to wait before retrying function call if there is an error. Will be ignored if auto_retry is False
retry_backoff (int, default: 4) – Exponential factor by which the backoff increases between retries. Will be ignored if auto_retry is False

Returns:

A tuple of dictionaries containing metadata on the streams in the provided collection.

Return type:

tuple

create(uuid, collection, tags=None, annotations=None, auto_retry=False, retries=5, retry_delay=3, retry_backoff=4)#

Tells BTrDB to create a new stream with UUID uuid in collection with specified tags and annotations.

Parameters:

uuid (UUID, required) – The uuid of the requested stream.
collection (str, required) – The collection string prefix that the stream will belong to.
tags (dict, required) – The tags-level immutable metadata key:value pairs.
annotations (dict, optional) – The mutable metadata of the stream, key:value pairs
auto_retry (bool, default: False) – Whether to retry this request in the event of an error
retries (int, default: 5) – Number of times to retry this request if there is an error. Will be ignored if auto_retry is False
retry_delay (int, default: 3) – initial time to wait before retrying function call if there is an error. Will be ignored if auto_retry is False
retry_backoff (int, default: 4) – Exponential factor by which the backoff increases between retries. Will be ignored if auto_retry is False

Returns:

instance of Stream class

Return type:

Stream

info()#

Returns information about the connected BTrDB server.

Returns:: server connection and status information
Return type:: dict

list_collections(starts_with='')#

Returns a list of collection paths using the starts_with argument for filtering.

Parameters:: starts_with (str, optional, default = '') – Filter collections that start with the string provided, if none passed, will list all collections.
Returns:: collections
Return type:: List[str]

list_unique_annotations(collection=None)#

Returns a list of annotation keys used in a given collection prefix.

Parameters:: collection (str) – Prefix of the collection to filter.
Returns:: annotations
Return type:: list[str]

list_unique_names(collection=None)#

Returns a list of names used in a given collection prefix.

Parameters:: collection (str) – Prefix of the collection to filter.
Returns:: names
Return type:: list[str]

list_unique_units(collection=None)#

Returns a list of units used in a given collection prefix.

Parameters:: collection (str) – Prefix of the collection to filter.
Returns:: units
Return type:: list[str]

query(stmt, params=None, auto_retry=False, retries=5, retry_delay=3, retry_backoff=4)#

Performs a SQL query on the database metadata and returns a list of dictionaries from the resulting cursor.

Parameters:

stmt (str) – a SQL statement to be executed on the BTrDB metadata. Available tables are noted below. To sanitize inputs use a $1 style parameter such as select * from streams where name = $1 or name = $2.
params (list or tuple) – a list of parameter values to be sanitized and interpolated into the SQL statement. Using parameters forces value/type checking and is considered a best practice at the very least.
auto_retry (bool, default: False) – Whether to retry this request in the event of an error
retries (int, default: 5) – Number of times to retry this request if there is an error. Will be ignored if auto_retry is False
retry_delay (int, default: 3) – initial time to wait before retrying function call if there is an error. Will be ignored if auto_retry is False
retry_backoff (int, default: 4) – Exponential factor by which the backoff increases between retries. Will be ignored if auto_retry is False

Returns:

a list of dictionary object representing the cursor results.

Return type:

list

Notes

Parameters will be inserted into the SQL statement as noted by the paramter number such as $1, $2, or $3. The streams table is available for SELECT statements only.

See https://btrdb.readthedocs.io/en/latest/ for more info.

stream_from_uuid(uuid)#

Creates a stream handle to the BTrDB stream with the UUID uuid. This method does not check whether a stream with the specified UUID exists. It is always good form to check whether the stream existed using stream.exists().

Parameters:: uuid (UUID) – The uuid of the requested stream.
Returns:: instance of Stream class or None
Return type:: Stream

streams(*identifiers, versions=None, is_collection_prefix=False)#

Returns a StreamSet object with BTrDB streams from the supplied identifiers. If any streams cannot be found matching the identifier than StreamNotFoundError will be returned.

Parameters:

identifiers (str or UUID) – a single item or iterable of items which can be used to query for streams. identiers are expected to be UUID as string, UUID as UUID, or collection/name string.
versions (list[int]) – a single or iterable of version numbers to match the identifiers

streams_in_collection(*collection, is_collection_prefix=True, tags=None, annotations=None, auto_retry=False, retries=5, retry_delay=3, retry_backoff=4)#

Search for streams matching given parameters

This function allows for searching

Parameters:

collection (str) – collections to use when searching for streams, case sensitive.
is_collection_prefix (bool) – Whether the collection is a prefix.
tags (Dict[str, str]) – The tags to identify the stream.
annotations (Dict[str, str]) – The annotations to identify the stream.
auto_retry (bool, default: False) – Whether to retry this request in the event of an error
retries (int, default: 5) – Number of times to retry this request if there is an error. Will be ignored if auto_retry is False
retry_delay (int, default: 3) – initial time to wait before retrying function call if there is an error. Will be ignored if auto_retry is False
retry_backoff (int, default: 4) – Exponential factor by which the backoff increases between retries. Will be ignored if auto_retry is False

Returns:

A list of stream objects found with the provided search arguments.

Return type:

list