sqlhistorian.historian module

class sqlhistorian.historian.MaskedString[source]

Bases: str

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`
get_dbfuncts_object()[source]
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() or BaseHistorianAgent.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

list

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
  • topic (str or list) – Topic or list of topics to query for.

  • 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

dict

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

list

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}

query_topics_metadata(topics)[source]

This function is called by BaseQueryHistorianAgent.get_topics_metadata() to find out the metadata for the given topics

Parameters

topics (str or list) – single topic or list of topics

Returns

dictionary with the format

{topic_name: {metadata_key:metadata_value, ...},
topic_name: {metadata_key:metadata_value, ...} ...}
Return type

dict

version()[source]

Return the current version number of the historian :return: version number

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 a

dictionary object

Parameters

kwargs – additional keyword arguments if any

Returns

an instance of sqlhistorian.historian.SQLHistorian

sqlhistorian.historian.main(argv=['/home/docs/checkouts/readthedocs.org/user_builds/volttron/envs/stable/lib/python3.6/site-packages/sphinx/__main__.py', '-T', '-E', '-b', 'html', '-d', '_build/doctrees', '-D', 'language=en', '.', '_build/html'])[source]

Main entry point for the agent.