btrdb4
index
/home/filip/pyt/btrdb4-python/btrdb4/__init__.py

The 'btrdb4' module provides Python bindings to interact with BTrDB.

 
Package Contents
       
btrdb_pb2
btrdb_pb2_grpc
endpoint
utils

 
Classes
       
__builtin__.object
BTrDB
Connection
Stream

 
class BTrDB(__builtin__.object)
     Methods defined here:
__init__(self, endpoint)
alignedWindowsToCSV(self, csvFile, start, end, depth, includeVersions, *streams)
Writes aligned windows streams to a csv file using the
provided configuration.
 
Parameters
----------
csvFile: File
    The csv file where rows will be written
start: int
    The start time in nanoseconds for the queries
end: int
    The end time in nanoseconds
depth: int
    The depth of the queries
includeVersions: bool
    Include the stream versions in the header labels
streams: *Tuple[int, str, UUID]
    The version, label and uuid for the streams to be queried.
create(self, uu, collection, tags=None, annotations=None)
Tells BTrDB to create a new stream with UUID `uu` in `collection` with specified `tags` and `annotations`.
 
Parameters
----------
uu: UUID
    The uuid of the requested stream.
 
Returns
-------
Stream
    a Stream class object
getMetadataUsage(self, prefix)
Gives statistics about metadata for collections that match a
prefix.
 
Parameters
----------
prefix: str
    A prefix of the collection names to look at
info(self)
Returns information about the connected BTrDB srerver.
lookupStreams(self, collection, isCollectionPrefix, tags=None, annotations=None)
Search for streams matching given parameters
 
This function allows for searching
 
Parameters
----------
collection: str
    The name of the collection to be found, case sensitive.
isCollectionPrefix: 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.
 
Yields
------
Stream Generator
    A stream generator that iterates over the search results.
rawValuesToCSV(self, csvFile, start, end, width, depth, includeVersions, *streams)
Writes raw values streams to a csv file using the provided
configuration.
 
Parameters
----------
csvFile: File
    The csv file where rows will be written
start: int
    The start time in nanoseconds for the queries
end: int
    The end time in nanoseconds
width: int
    The width of the stat points
depth: int
    The depth of the queries
includeVersions: bool
    Include the stream versions in the header labels
streams: *Tuple[int, str, UUID]
    The version, label and uuid for the streams to be queried.
streamFromUUID(self, uu)
Creates a stream handle to the BTrDB stream with the UUID `uu`.
 
Creates a stream handle to the BTrDB stream with the UUID `uu`. 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
----------
uu: UUID
    The uuid of the requested stream.
 
Returns
-------
Stream
    A Stream class object.
windowsToCSV(self, csvFile, start, end, width, depth, includeVersions, *streams)
Writes windows streams to a csv file using the provided
configuration.
 
Parameters
----------
csvFile: File
    The csv file where rows will be written
start: int
    The start time in nanoseconds for the queries
end: int
    The end time in nanoseconds
width: int
    The width of the stat points
depth: int
    The depth of the queries
includeVersions: bool
    Include the stream versions in the header labels
streams: *Tuple[int, str, UUID]
    The version, label and uuid for the streams to be queried.
writeCSV(self, csvWriter, queryType, start, end, width, depth, includeVersions, *streams)
Writes streams to a csv writer using the provided configuration.
 
Parameters
----------
csvWriter: csv.writer
    The csv writer where rows will be written
queryType: QueryType
    The type of query for the streams
start: int
    The start time in nanoseconds for the queries
end: int
    The end time in nanoseconds
width: int
    The width of the stat points (This is only used for windows queries)
depth: int
    The depth of the queries
includeVersions: bool
    Include the stream versions in the header labels
streams: *Tuple[int, str, UUID]
    The version, label and uuid for the streams to be queried.

Data descriptors defined here:
__dict__
dictionary for instance variables (if defined)
__weakref__
list of weak references to the object (if defined)

 
class Connection(__builtin__.object)
     Methods defined here:
__init__(self, addrportstr, apikey=None)
Connects to a BTrDB server
 
Parameters
----------
addrportstr: str
    The address of the cluster to connect to, e.g 123.123.123:4411
apikey: str
    The option API key to authenticate requests
 
Returns
-------
Connection
    A Connection class object.
newContext(self)

Data descriptors defined here:
__dict__
dictionary for instance variables (if defined)
__weakref__
list of weak references to the object (if defined)

 
class Stream(__builtin__.object)
     Methods defined here:
__init__(self, btrdb, uuid, knownToExist=False, collection=None, tags=None, annotations=None, annotationVersion=None)
alignedWindows(self, start, end, pointwidth, version=0)
Read statistical aggregates of windows of data from BTrDB.
 
Query BTrDB for aggregates (or roll ups or windows) of the time series with `version` between time `start` (inclusive) and `end` (exclusive) in nanoseconds. Each point returned is a statistical aggregate of all the raw data within a window of width 2**`pointwidth` nanoseconds. These statistical aggregates currently include the mean, minimum, and maximum of the data and the count of data points composing the window.
 
Note that `start` is inclusive, but `end` is exclusive. That is, results will be returned for all windows that start in the interval [start, end). If end < start+2^pointwidth you will not get any results. If start and end are not powers of two, the bottom pointwidth bits will be cleared. Each window will contain statistical summaries of the window. Statistical points with count == 0 will be omitted.
 
Parameters
----------
start : int
    The start time in nanoseconds for the range to be queried
end : int
    The end time in nanoseconds for the range to be queried
pointwidth : int
    Specify the number of ns between data points (2**pointwidth)
version : int
    Version of the stream to query
 
Yields
------
(StatPoint, int)
    Returns a tuple containing a StatPoint and the stream version
 
 
Notes
-----
As the window-width is a power-of-two, it aligns with BTrDB internal tree data structure and is faster to execute than `windows()`.
annotations(self)
Returns a stream's annotations
 
Annotations returns the annotations of the stream (and the annotation version). It will always require a round trip to the server. If you are ok with stale data and want a higher performance version, use Stream.CachedAnnotations().
 
Do not modify the resulting map.
 
 
Parameters
----------
None
 
Returns
-------
Tuple[Dict[str, str], int]
    A tuple containing a dictionary of annotations and an integer representing the version of those annotations.
cachedAnnotations(self)
CachedAnnotations returns the annotations of the stream, reusing previous results if available, otherwise fetching from the server.
 
Parameters
----------
None
 
Returns
-------
Tuple[Dict[str, str], int]
    A tuple containing a dictionary of annotations and an integer representing the version of those annotations.
changes(self, fromVersion, toVersion, resolution)
collection(self)
Returns the collection of the stream. It may require a round trip to the server depending on how the stream was acquired.
 
Returns
-------
str
    the collection of the stream
deleteRange(self, start, end)
"Delete" all points between [`start`, `end`)
 
"Delete" all points between `start` (inclusive) and `end` (exclusive), both in nanoseconds. As BTrDB has persistent multiversioning, the deleted points will still exist as part of an older version of the stream.
 
Parameters
----------
start : int
    The start time in nanoseconds for the range to be deleted
end : int
    The end time in nanoseconds for the range to be deleted
 
Returns
-------
int
    The version of the new stream created
exists(self)
Check if stream exists
 
Exists returns true if the stream exists. This is essential after using
StreamFromUUID as the stream may not exist, causing a 404 error on
later stream operations. Any operation that returns a stream from
collection and tags will have ensured the stream exists already.
 
Returns
-------
bool
    Indicates whether stream exists.
flush(self)
Flush writes the stream buffers out to persistent storage.
insert(self, vals)
Insert new data in the form (time, value) into the series.
 
Inserts a list of new (time, value) tuples into the series. The tuples in the list need not be sorted by time. If the arrays are larger than appropriate, this function will automatically chunk the inserts. As a consequence, the insert is not necessarily atomic, but can be used with a very large array.
 
Returns
-------
version : int
    The version of the stream after inserting new points.
nearest(self, time, version, backward)
Finds the closest point in the stream to a specified time.
 
Return the point nearest to the specified `time` in nanoseconds since Epoch in the stream with `version` while specifying whether to search forward or backward in time. If `backward` is false, the returned point will be >= `time`. If backward is true, the returned point will be < `time`. The version of the stream used to satisfy the query is returned.
 
 
Parameters
----------
time : int
    The time (in nanoseconds since Epoch) to search near
version : int
    Version of the stream to use in search
backward : boolean
    True to search backwards from time, else false for forward
 
Returns
-------
RawPoint
    The point closest to time
int
    Version of the stream used to satisfy the query
 
 
Raises
------
BTrDBError [401] no such point
    No point satisfies the query in the direction specified
patch(self, vals)
rawValues(self, start, end, version=0)
Read raw values from BTrDB between time [a, b) in nanoseconds.
 
RawValues queries BTrDB for the raw time series data points between `start` and `end` time, both in nanoseconds since the Epoch for the specified stream `version`.
 
Parameters
----------
start: int
    The start time in nanoseconds for the range to be retrieved
end : int
    The end time in nanoseconds for the range to be deleted
version: int
    The version of the stream to be queried
 
Yields
------
(RawPoint, version) : (RawPoint, int)
    Returns a tuple containing a RawPoint and the stream version
 
 
Notes
-----
Note that the raw data points are the original values at the sensor's native sampling rate (assuming the time series represents measurements from a sensor). This is the lowest level of data with the finest time granularity. In the tree data structure of BTrDB, this data is stored in the vector nodes.
refreshMeta(self)
Refreshes the locally cached meta data for a stream
 
Queries the BTrDB server for all stream metadata including collection, annotation, and tags. This method requires a round trip to the server.
tags(self)
Returns the stream's tags.
 
Tags returns the tags of the stream. It may require a round trip to the server depending on how the stream was acquired. Do not modify the resulting map as it is a reference to the internal stream state.
 
Parameters
----------
None
 
Returns
-------
List[Dict[str, str]]
    A list of dictionaries containing the tags.
uuid(self)
Returns the stream's UUID.
 
This method returns the stream's UUID. The stream may nor may not exist yet, depending on how the stream object was obtained.
 
Parameters
----------
None
 
Returns
-------
UUID
    The UUID of the stream.
 
 
See Also
--------
stream.exists()
version(self)
Returns the current data version of the stream.
 
Version returns the current data version of the stream. This is not cached, it queries each time. Take care that you do not intorduce races in your code by assuming this function will always return the same vaue
 
Parameters
----------
None
 
Returns
-------
int
    The version of the stream.
windows(self, start, end, width, depth=0, version=0)
Read arbitrarily-sized windows of data from BTrDB.
 
Windows returns arbitrary precision windows from BTrDB. It is slower than AlignedWindows, but still significantly faster than RawValues. Each returned window will be `width` nanoseconds long. `start` is inclusive, but `end` is exclusive (e.g if end < start+width you will get no results). That is, results will be returned for all windows that start at a time less than the end timestamp. If (`end` - `start`) is not a multiple of width, then end will be decreased to the greatest value less than end such that (end - start) is a multiple of `width` (i.e., we set end = start + width * floordiv(end - start, width). The `depth` parameter is an optimization that can be used to speed up queries on fast queries. Each window will be accurate to 2^depth nanoseconds. If depth is zero, the results are accurate to the nanosecond. On a dense stream for large windows, this accuracy may not be required. For example for a window of a day, +- one second may be appropriate, so a depth of 30 can be specified. This is much faster to execute on the database side.
 
 
Parameters
----------
start : int
    The start time in nanoseconds for the range to be queried
end : int
    The end time in nanoseconds for the range to be queried
width : int
    Specify the number of ns between data points
depth : int
 
version : int
    Version of the stream to query
 
Yields
------
(StatPoint, int)
    Returns a tuple containing a StatPoint and the stream version

Data descriptors defined here:
__dict__
dictionary for instance variables (if defined)
__weakref__
list of weak references to the object (if defined)

 
Functions
       
connect(addrportstr=None, apikey=None)
Connect to a BTrDB server.
 
Parameters
----------
addrportstr: str, default=None
    The address and port of the cluster to connect to, e.g. 192.168.1.1:4411.
    If set to None will look up the string from the environment variable
    $BTRDB_ENDPOINTS (recommended).
 
apikey: str, default=None
    The API key use to authenticate requests (optional). If None, the key
    is looked up from the environment variable $BTRDB_API_KEY.
 
Returns
-------
db : BTrDB
    An instance of the BTrDB context to directly interact with the database.
isCorrect()
verify changes to grpc

 
Data
        BTRDB_API_KEY = 'BTRDB_API_KEY'
BTRDB_ENDPOINTS = 'BTRDB_ENDPOINTS'
DAY = 86400000000000
HOUR = 3600000000000
MAX_POINTWIDTH = 63
MAX_TIME = 3458764513820540928
MICROSECOND = 1000
MILLISECOND = 1000000
MINUTE = 60000000000
MIN_TIME = -1152921504606846976
NANOSECOND = 1
SECOND = 1000000000