data_tools.query.PostgresClient

class data_tools.query.PostgresClient(db_name: str = None, ip_address: str = None, username: str = None, password: str = None, timeout: float = 10)

Bases: object

Connect to a PostgresSQL database and concisely make queries for time-series data.

__init__(db_name: str = None, ip_address: str = None, username: str = None, password: str = None, timeout: float = 10)

Methods

__init__([db_name, ip_address, username, ...])
get_session()	Obtain a new Session to make queries to this database.
init_schema()	Initialize the Postgres database schema.
query(field, start_time, end_time[, granularity])	Query the database for time-series data matching field, between start_time and end_time.
write(instance[, session])	Write some data instance to this database using session.

get_session() → Session

Obtain a new Session to make queries to this database. :return: a new Session bound to this connection

init_schema()

Initialize the Postgres database schema. This only needs to be called ONCE PER DATABASE.

Has no effect if called on an already initialized database.

query(field: str, start_time: datetime, end_time: datetime, granularity: float = 1.0) → TimeSeries

Query the database for time-series data matching field, between start_time and end_time.

Undefined behaviour when timestamps provided are not in UTC!

PLEASE NOTE: If your data does not have a frequency of 1.0Hz, then you will be decimating or up-sampling your data. Set granularity to control the temporal granularity (time between measurements) of your data!

Parameters:

• field (str) – name of the field that will be queried

• start_time (datetime.datetime) – the UTC datetime of the beginning of the data to be queried

• end_time (datetime.datetime) – the UTC datetime of the end of the data to be queried

• granularity (float) – the desired temporal granularity (time between measurements) of the returned data

Returns:

successfully queried data formatted as a TimeSeries

Raises:

• IndexError – if no data could be queried

• RuntimeError – if the query failed for any reason

• ValueError – if timestamps cannot be localized to UTC

write(instance: object | List[object], session: Session = None) → None

Write some data instance to this database using session.

Parameters:

• instance – the data that will be uploaded, can be a single object or an iterable of objects.

• session – optionally specify the Session that will be used to write to the database

Raises:

RuntimeError – if the database write fails