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")
Look up collections#
You can look up collections found in the server by using the list_collections
method, which returns a list of string collection names. Additionally,
you can use the starts_with
parameter to filter the results to include only collections
that begin with the provided prefix. Omitting the starts_with
parameter will return
all available collections from the server.
conn = btrdb.connect()
collections = conn.list_collections(starts_with="NORTHWEST")
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 |