mongotagging.tagging module

class mongotagging.tagging.MongodbTaggingService(connection, table_prefix=None, **kwargs)

Bases: volttron.platform.agent.base_tagging.BaseTaggingService

This is a tagging service agent that writes data to a Mongo database. For instance with large amount of tags and frequent tag queries, a NOSQL database such as Mongodb would provide better efficiency than SQLite.

insert_topic_tags(tags, update_version=False)

Add tags to multiple topics.

Parameters

• tags (dict) –

  dictionary object or file containing the topic and the tag details. dictionary object or the file content should be of the format:

  <topic_name or prefix or topic_name pattern>: {<valid
  tag>:<value>, ... }, ... }
  

• update_version (bool) – True/False. Default to False. If set to True and if any of the tags update an existing tag value the older value would be preserved as part of tag version history. Note: this feature is not implemented in the current version of sqlite and mongodb tagging service.

load_tag_refs()

Called right after setup to load a dictionary of reference tags and its corresponding parent tag. Implementing methods should load self.tag_refs with tag and parent tag information

load_valid_tags()

Called right after setup to load a dictionary of valid tags. It should load self.valid_tags with tag and type information

query_categories(include_description=False, skip=0, count=None, order='FIRST_TO_LAST')

Get the available list tag categories. category can have multiple tags and tags could belong to multiple categories

Parameters

• include_description (bool) – indicate if result should include available description for categories returned

• skip (int) – number of tags to skip. usually used with order

• count (int) – limit on the number of tags to return

• order (str) – order of result - “FIRST_TO_LAST” or “LAST_TO_FIRST”

Returns

list of category names if include_description is False, list of (category name, description) if include_description is True

Return type

list

query_tags_by_category(category, include_kind=False, include_description=False, skip=0, count=None, order='FIRST_TO_LAST')

Get the list of tags for a given category name. category can have multiple tags and tags could belong to multiple categories

Parameters

• category (str) – name of the category for which associated tags should be returned

• include_kind (bool) – indicate if result should include the kind/datatype for tags returned

• include_description (bool) – indicate if result should include available description for tags returned

• skip (int) – number of tags to skip. usually used with order

• count (int) – limit on the number of tags to return

• order (str) – order of result - “FIRST_TO_LAST” or “LAST_TO_FIRST”

Returns

Will return one of the following

• list of tag names

• list of (tags, its data type/kind) if include_kind is True

• list of (tags, description) if include_description is True

• list of (tags, its data type/kind, description) if include_kind is True and include_description is true

Return type

list

query_tags_by_topic(topic_prefix, include_kind=False, include_description=False, skip=0, count=None, order='FIRST_TO_LAST')

Get the list of tags for a given topic prefix or name.

Parameters

• topic_prefix (str) – topic_prefix for which associated tags should be returned

• include_kind (bool) – indicate if result should include the kind/datatype for tags returned

• include_description (bool) – indicate if result should include available description for tags returned

• skip (int) – number of tags to skip. usually used with order

• count (int) – limit on the number of tags to return

• order (str) – order of result - “FIRST_TO_LAST” or “LAST_TO_FIRST”

Returns

Will return one of the following

• list of (tag name, value)

• list of (tag name, value, data type/kind) if include_kind is True

• list of (tag name, value, description) if include_description is True

• list of (tags, value, data type/kind, description) if include_kind is True and include_description is true

Return type

list

query_topics_by_tags(ast, skip=0, count=None, order=None)

Get list of topic names and topic name prefixes based on query condition. Query condition is passed as an abstract syntax tree.

Parameters

• ast (tuple) –

  Abstract syntax tree that represents conditional statement to be used for matching tags. The abstract syntax tree represents query condition that is created using the following specification

  Query condition is a boolean expression that contains one or more query conditions combined together with an “AND” or “OR”. Query conditions can be grouped together using parenthesis. Each condition in the expression should conform to one of the following format:

  1. <tag name/ parent.tag_name> <binary_operator> <value>

  2. <tag name/ parent.tag_name>

  3. <tag name/ parent.tag_name> LIKE <regular expression within single quotes

  4. the word NOT can be prefixed before any of the above three to negate the condition.

  5. expressions can be grouped with parenthesis. For example

     condition="(tag1 = 1 or tag1 = 2) and (tag2 < '' and tag2 >
     '') and tag3 and  (tag4 LIKE '^a.*b$')"
     condition="NOT (tag5='US' OR tag5='UK') AND NOT tag3 AND
     NOT (tag4 LIKE 'a.*')"
     condition="campusRef.geoPostalCode='20500' and equip and
     boiler"
     

• skip (int) – number of tags to skip. usually used with order

• count (int) – limit on the number of tags to return

• order (str) – order of result - “FIRST_TO_LAST” or “LAST_TO_FIRST”

Returns

list of topics/topic_prefix that match the given query conditions

Return type

list

setup()

Called on start of agent Method to establish database connection, do any initial bootstrap necessary. Example - load master list of tags, units, categories etc. into data store/memory

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

Main entry point for the agent.

Parameters

argv –

Returns

mongotagging.tagging.tagging_service(config_path, **kwargs)

This method is called by the tagging.main() to parse the passed config file or configuration dictionary object, validate the configuration entries, and create an instance of MongodbTaggingService

Parameters

• config_path – could be a path to a configuration file or can be a dictionary object

• kwargs – additional keyword arguments if any

Returns

an instance of tagging.MongodbTaggingService