ConDB Direct Access Python API

This document describes the low lovel API, which allows direct access to the ConDB database.

class condb.ConDB(connection=None, connstr=None)
__init__(connection=None, connstr=None)

Initializes the connection to the ConDB

Parameters:

  • connection – Psycopg2 connection object

  • connstr (str) – Postgres connection string, e.g. “host=… port=… dbname=…”. Ignored if connection is provided

__weakref__

list of weak references to the object (if defined)

createFolder(name, column_types, owner=None, grants={}, drop_existing=False)

Creates or opens ConDB folder

Parameters:

  • name (str) – Folder name. May include namespace (schema), e.g.: “my_namespace.my_folder”. If namespace is not given, use “public” namespace

  • column_types (list) – List of tuples: (column_name, data_type). column_name is a valid Postgres column name. data_type is a Postgres data type e.g. “int” or “double precision” or “text”

  • grants (dict) – Dictionary with 2 optional keys: ‘r’ and ‘w’. Each key, if present has a value of a list of strings, each item is the database username to grant “read” or “write” permissions to when the folder is created.

  • owner (str) – Owner for folder tables if the folder is to be created

  • drop_existing (boolean) – If the folder already exists and drop_existing is True, then existing folder will be dropped and data will be discarded. If the folder already exists and drop_existing is False, the existing folder will be opened instead of creating new folder.

openFolder(name)

Opens existing ConDB folder.

Parameters:

name (str) – Name of the folder to open

Returns:

If the folder does not exist, returns None. Otherwise - CDFolder object representing the folder

Return type:

CDFolder or None

class condb.CDFolder(db, name, data_columns_types=None)
addData(data, data_type='', tr=None, columns=None)

Adds data to the folder

Parameters:

  • data (iterable) – Iterable with tuples: (channel, tv, <data values>, …) channel is the integer channel number tv is numeric validity time (integer or floating point) data values are in the same order as the list of columns used when the folder was created

  • data_type (str) – Data type to associate with the data. Default - blank “”

  • tr (float or int) – Tr to associate the data with. Bt default, current timestamp will be used as floating point number

  • columns (list of strings) – Optional, names of data columns present in the input data, without channel amd tv. If not specified, the data is assumed to contain all the data columns

Returns:

Tr timestamp

Return type:

float

copyTag(tag, new_tag, comment='', override=False)

Creates new tag with the same Tr as an existing tag

Parameters:

  • tag (str) – Exisitng tag name

  • new_tag (str) – New tag name

  • comment (str) – Comment to add to the new tag

  • override (boolean) – If true and new_tag already exists, it will be moved to the Tr corresponding to tag

static create(db, name, column_types, owner, grants={}, drop_existing=False)

Static method to create a ConDB folder.

Parameters:

  • db (ConDB) – ConDB object

  • rest (the) – same arguments as for ConDB.createFolder() method

dataTypes()

Returns list of data types defined for the folder

Returns:

list of strings

Return type:

list

data_column_types()
Returns:

list of (name, type) tuples for the data columns

Return type:

list

getData(t0, t1=None, tag=None, tr=None, data_type=None, channel_range=None)

Retieves data for specified validity time or time interval from the folder

Parameters:

  • t0 (float, int) – The beginning of the time interval.

  • t1 (float, int or None) – The end of the time interval. For each channel, the output will include the most recent data values preceding t1 and all the values between t1 and t2. If t0 == t1 or t1 == None, the method returns data for the t0 point in time

  • tr (float, int) – Retieve data retrospectively from a previous state of the database specified with tr as a timestamp. The result will include only data added before the specified tr. By default, will include most recent data.

  • tag (str) – Text tag previously assigned to a Tr value.

  • data_type (str) – Data type to include. If None, will include data for all data types

  • channel_range (tuple) – Tuple (min_channel, max_channel) if provided, only the channels within the specified interval, inclusively will be included in the output. Each one of the limits can be None, which means there is no limit.

Returns:

Generator of tuples: (channel, tv, tr, data_type, <data column values>…)

Return type:

generator

searchData(tag=None, tr=None, data_type=None, channel_range=None, conditions=[])
Find all data records on the timeline determined by (tag, tr, data_type)

and satisfying specified conditions expressed in terms of data column values

Parameters:

  • conditions (list) –

    Conditions cpecified as tuples:

    (“column_name”, op, value)

    column_name is a name of a data column op is a string “<”, “<=”, “=”, “!=”, “>=”, “>” value is a string, boolean, numeric or None

  • tr (float, int) – Retieve data retrospectively from a previous state of the database recorded at tr or earlier. By default, will include most recent data.

  • tag (str) – Text tag previously assigned to a Tr value.

  • data_type (str) – Data type to include. If None, will include data for all data types

  • channel_range (tuple) – Tuple (min_channel, max_channel) if provided, only the channels within the specified interval, inclusively will be included in the output. Each one of the limits can be None, which means there is no limit.

Returns:

Generator of tuples: (channel, tv, tr, data_type, <data column values>…)

Return type:

generator

tag(tag, comment='', override=False, tr=None)

Creates new tag with the specified Tr

Parameters:

  • tag (str) – New tag name

  • tr (float or int) – Tr for the tag

  • comment (str) – Comment to add to the new tag

  • override (boolean) – Whether to override an existing tag

tags()

Returns list of tags defined for the folder

Returns:

generates list of tuples (name, tr) for existing tags

Return type:

generator