Querying and Managing Streams

With BTrDB, you can easily create, delete, and query for streams using simple method calls. Simple examples are included below but please review the API docs for further options.

Create a Stream

Creating a stream requires only a UUID, collection, and dictionary for the initial tags.

conn = btrdb.connect()

stream = conn.create(
    uuid=uuid.uuid4(),
    collection="NORTHWEST/90001",
    tags={"name": "L1MAG", "unit": "volts"}
)

Delete a Stream

Deleting a stream can be performed by calling the obliterate method on the stream object. If the stream could not be found than an error is raised.

conn = btrdb.connect()
stream = conn.stream_from_uuid("66466a91-dcfe-42ea-9e88-87c51f847944")
stream.obliterate()

Find by UUID

To retrieve your stream from the server at a later date, you can easily query for it by using the UUID it was created with. As a convenience, you can provide either a UUID object or a string of the UUID value. If a stream matching the supplied UUID cannot be found then None will be returned.

conn = btrdb.connect()
stream = conn.stream_from_uuid("71466a91-dcfe-42ea-9e88-87c51f847942")

Finding by collection

You can also search for multiple streams by collection using the server object’s streams_in_collection method which will return a simple list of Stream instances. Aside from the collection name, you can provide more information such as tags and annotations. Please see the API docs for more detail.

conn = btrdb.connect()
streams = conn.streams_in_collection("NORTHEAST/NH")

Querying Metadata

Finally, you can query for metadata using standard SQL although at the moment, only the streams table is available. SQL queries can be submitted using the query method which accepts both a stmt and params argument. The stmt should contain the SQL you’d like executed with parameter placeholders such as $1 or $2 as shown below.

conn = btrdb.connect()
stmt = "select uuid from streams where name = $1 or name = $2"
params = ["Boston_1", "Boston_2"]

for row in conn.query(stmt, params):
  print(row)

The SQL query results are returned as a list of dictionaries where each key matches a column from your SQL projection. You can choose your columns from the schema of the streams table as follows.

Column	Type	Nullable
uuid	uuid	not null
collection	character varying(256)	not null
name	character varying(256)	not null
unit	character varying(256)	not null
ingress	character varying(256)	not null
property_version	bigint	not null
annotations	hstore