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