sqlhistorian.historian module¶
-
class
sqlhistorian.historian.
SQLHistorian
(connection, tables_def=None, **kwargs)[source]¶ Bases:
volttron.platform.agent.base_historian.BaseHistorian
This is a historian agent that writes data to a SQLite or Mysql database based on the connection parameters in the configuration. .. seealso:
- :py:mod:`volttron.platform.dbutils.basedb` - :py:mod:`volttron.platform.dbutils.mysqlfuncts` - :py:mod:`volttron.platform.dbutils.sqlitefuncts`
-
historian_setup
()[source]¶ Optional setup routine, run in the processing thread before main processing loop starts. Gives the Historian a chance to setup connections in the publishing thread.
-
manage_db_size
(history_limit_timestamp, storage_limit_gb)[source]¶ Optional function to manage database size.
-
publish_to_historian
(to_publish_list)[source]¶ Main publishing method for historian Agents.
- Parameters
to_publish_list (list) – List of records
to_publish_list takes the following form:
[ { 'timestamp': timestamp1.replace(tzinfo=pytz.UTC), 'source': 'scrape', 'topic': "pnnl/isb1/hvac1/thermostat", 'value': 73.0, 'meta': {"units": "F", "tz": "UTC", "type": "float"} }, { 'timestamp': timestamp2.replace(tzinfo=pytz.UTC), 'source': 'scrape', 'topic': "pnnl/isb1/hvac1/temperature", 'value': 74.1, 'meta': {"units": "F", "tz": "UTC", "type": "float"} }, ... ]
The contents of meta is not consistent. The keys in the meta data values can be different and can change along with the values of the meta data. It is safe to assume that the most recent value of the “meta” dictionary are the only values that are relevant. This is the way the cache treats meta data.
Once one or more records are published either
BaseHistorianAgent.report_all_handled()
orBaseHistorianAgent.report_handled()
must be called to report records as being published.
-
query_aggregate_topics
()[source]¶ This function is called by
BaseQueryHistorianAgent.get_aggregate_topics()
to find out the available aggregates in the data store- Returns
List of tuples containing (topic_name, aggregation_type, aggregation_time_period, metadata)
- Return type
-
query_historian
(topic, start=None, end=None, agg_type=None, agg_period=None, skip=0, count=None, order='FIRST_TO_LAST')[source]¶ This function is called by
BaseQueryHistorianAgent.query()
to actually query the data store and must return the results of a query in the following format:Single topic query:
{ "values": [(timestamp1, value1), (timestamp2:,value2), ...], "metadata": {"key1": value1, "key2": value2, ...} }
Multiple topics query:
{ "values": {topic_name:[(timestamp1, value1), (timestamp2:,value2), ...], topic_name:[(timestamp1, value1), (timestamp2:,value2), ...], ...} "metadata": {} #empty metadata }
Timestamps must be strings formatted by
volttron.platform.agent.utils.format_timestamp()
.“metadata” is not required. The caller will normalize this to {} for you if it is missing.
- Parameters
start (datetime) – Start of query timestamp as a datetime.
end (datetime) – End of query timestamp as a datetime.
agg_type – If this is a query for aggregate data, the type of aggregation ( for example, sum, avg)
agg_period – If this is a query for aggregate data, the time period of aggregation
skip (int) – Skip this number of results.
count (int) – Limit results to this value. When the query is for multiple topics, count applies to individual topics. For example, a query on 2 topics with count=5 will return 5 records for each topic
order (str) – How to order the results, either “FIRST_TO_LAST” or “LAST_TO_FIRST”
- Returns
Results of the query
- Return type
-
query_topic_list
()[source]¶ This function is called by
BaseQueryHistorianAgent.get_topic_list()
to actually topic list from the data store.- Returns
List of topics in the data store.
- Return type
-
query_topics_by_pattern
(topic_pattern)[source]¶ Find the list of topics and its id for a given topic_pattern
- Returns
returns list of dictionary object {topic_name:id}
-
-
sqlhistorian.historian.
historian
(config_path, **kwargs)[source]¶ This method is called by the
sqlhistorian.historian.main()
to parse the passed config file or configuration dictionary object, validate the configuration entries, and create an instance of SQLHistorian :param config_path: could be a path to a configuration file or can be adictionary object
- Parameters
kwargs – additional keyword arguments if any
- Returns
an instance of
sqlhistorian.historian.SQLHistorian