Connection related objects for the BTrDB library

class btrdb.conn.BTrDB(endpoint)

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


Gives statistics about metadata for collections that match a prefix.

Parameters:prefix (str) – A prefix of the collection names to look at
Returns:A tuple of dictionaries containing metadata on the streams in the provided collection.
Return type:tuple
create(uuid, collection, tags=None, annotations=None)

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

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

Returns information about the connected BTrDB srerver.

Returns:server connection and status information
Return type:dict

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

Returns:collection paths
Return type:list[str]
query(stmt, params=[])

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

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

a list of dictionary object representing the cursor results.

Return type:



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 for more info.


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.

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

Search for streams matching given parameters

This function allows for searching

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

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

Return type: