spinedb_api.db_mapping
======================

.. py:module:: spinedb_api.db_mapping

.. autoapi-nested-parse::

   This module defines the :class:`.DatabaseMapping` class, the main mean to communicate with a Spine DB.
   If you're planning to use this class, it is probably a good idea to first familiarize yourself a little bit with the
   :ref:`db_mapping_schema`.



Classes
-------

.. autoapisummary::

   spinedb_api.db_mapping.DatabaseMapping


Module Contents
---------------

.. py:class:: DatabaseMapping(db_url, username=None, upgrade=False, backup_url='', create=False, apply_filters=True, memory=False, commit_lock=None, sqlite_timeout=1800)

   Bases: :py:obj:`spinedb_api.db_mapping_query_mixin.DatabaseMappingQueryMixin`, :py:obj:`spinedb_api.db_mapping_commit_mixin.DatabaseMappingCommitMixin`, :py:obj:`spinedb_api.db_mapping_base.DatabaseMappingBase`


   Enables communication with a Spine DB.

   The DB is incrementally mapped into memory as data is requested/modified, following the :ref:`db_mapping_schema`.

   Data is typically retrieved using :meth:`item` or :meth:`find`.
   If the requested data is already in memory, it is returned from there;
   otherwise it is fetched from the DB, stored in memory, and then returned.
   In other words, the data is fetched from the DB exactly once.

   For convenience, we also provide specialized getter methods for each item type, e.g., :meth:`entity`
   and :meth:`find_entities`.

   Data is added via :meth:`add`;
   updated via :meth:`update`;
   removed via :meth:`remove`;
   and restored via :meth:`restore`.
   :meth:`add_or_update` adds an item or updates an existing one.
   All the above methods modify the in-memory mapping (not the DB itself).
   These methods also fetch data from the DB into the in-memory mapping to perform the necessary integrity checks
   (unique and foreign key constraints).

   For convenience, we also provide specialized 'add', 'update', 'remove', and 'restore' methods
   for each item type, e.g.,
   :meth:`add_entity`, :meth:`update_entity`, :meth:`remove_entity` and :meth:`restore_entity`.

   Modifications to the in-memory mapping are committed (written) to the DB via :meth:`commit_session`,
   or rolled back (discarded) via :meth:`rollback_session`.

   The DB fetch status is reset via :meth:`refresh_session`.
   This allows new items in the DB (added by other clients in the meantime) to be retrieved as well.

   You can also control the fetching process via :meth:`fetch_more` and/or :meth:`fetch_all`.
   For example, you can call :meth:`fetch_more` in a dedicated thread while you do some work on the main thread.
   This will nicely place items in the in-memory mapping, so you can access them later, without
   the overhead of fetching them from the DB.

   The :meth:`query` method is also provided as an alternative way to retrieve data from the DB
   while bypassing the in-memory mapping entirely.

   You usually use this class as a context manager, e.g.::

       with DatabaseMapping(db_url) as db_map:
           # Do stuff with db_map
           ...

   or::

       db_map = DatabaseMapping(db_url)
       ...
       with db_map:
           # Do stuff with db_map
           ...


   :param db_url: A URL in RFC-1738 format pointing to the database
                  to be mapped, or to a DB server.
   :type db_url: str or :class:`~sqlalchemy.engine.url.URL`
   :param username: A user name. If not given, it gets replaced by the string `anon`.
   :type username: str, optional
   :param upgrade: Whether the DB at the given `url` should be upgraded to the most recent
                   version.
   :type upgrade: bool, optional
   :param backup_url: A URL to backup the DB before upgrading.
   :type backup_url: str, optional
   :param create: Whether to create a new Spine DB at the given `url` if it's not already one.
   :type create: bool, optional
   :param apply_filters: Whether to apply filters in the `url`'s query segment.
   :type apply_filters: bool, optional
   :param commit_lock: If given, committing to the DB is done with the lock.
   :type commit_lock: threading.Lock, optional
   :param memory: Whether to use a SQLite memory DB as replacement for the original one.
   :type memory: bool, optional
   :param sqlite_timeout: The number of seconds to wait before raising SQLite connection errors.
   :type sqlite_timeout: int, optional


   .. py:method:: item_types() -> list[spinedb_api.helpers.ItemType]
      :staticmethod:


      Returns a list of public item types from the DB mapping schema (equivalent to the table names).



   .. py:method:: all_item_types() -> list[spinedb_api.helpers.ItemType]
      :staticmethod:


      Returns a list of all item types from the DB mapping schema (equivalent to the table names).



   .. py:method:: item_factory(item_type: spinedb_api.helpers.ItemType) -> Type[spinedb_api.db_mapping_base.MappedItemBase]
      :staticmethod:


      Returns a subclass of :class:`.MappedItemBase` to make items of given type.



   .. py:method:: add(mapped_table: spinedb_api.db_mapping_base.MappedTable, **kwargs) -> spinedb_api.db_mapping_base.PublicItem

      Adds an item to the in-memory mapping.

      Example::

          with DatabaseMapping(db_url) as db_map:
              class_table = db_map.mapped_table("entity_class")
              db_map.add(class_table, name="musician")
              entity_table = db_map.mapped_table("entity")
              db_map.add(entity_table, entity_class_name="musician", name="Prince")



   .. py:method:: item(mapped_table: spinedb_api.db_mapping_base.MappedTable, **kwargs) -> spinedb_api.db_mapping_base.PublicItem

      Returns an item matching the keyword arguments.

      Example::

          with DatabaseMapping(db_url) as db_map:
              entity_table = db_map.mapped_table("entity")
              prince = db_map.get_item(entity_table, entity_class_name="musician", name="Prince")




   .. py:method:: find(mapped_table: spinedb_api.db_mapping_base.MappedTable, **kwargs) -> list[spinedb_api.db_mapping_base.PublicItem]

      Finds items that match the keyword arguments.

      Example::

          with DatabaseMapping(db_url) as db_map:
              entity_table = db_map.mapped_table("entity")
              entities = db_map.find(entity_table, entity_class_name="musician")
              for entity in entities:
                  print(f"{entity['name']}: {entity['description']}")



   .. py:method:: update(mapped_table: spinedb_api.db_mapping_base.MappedTable, **kwargs) -> Optional[spinedb_api.db_mapping_base.PublicItem]
      :staticmethod:


      Updates an existing item.

      Returns the updated item or None if nothing was updated.

      Example::

          with DatabaseMapping(db_url) as db_map:
              entity_table = db_map.mapped_table("entity")
              prince = db_map.item(entity_table, entity_class_name="musician", name="Prince")
              db_map.update(
                  entity_table, id=prince["id"], name="the Artist", description="Formerly known as Prince."
              )



   .. py:method:: add_or_update(mapped_table: spinedb_api.db_mapping_base.MappedTable, **kwargs) -> Optional[spinedb_api.db_mapping_base.PublicItem]

      Adds an item if it does not exist, otherwise updates it.

      Returns the added/updated item or None if nothing was changed.



   .. py:method:: remove(mapped_table: spinedb_api.db_mapping_base.MappedTable, **kwargs) -> None
      :staticmethod:


      Removes an item matching the keyword arguments.

      Example::

          with DatabaseMapping(db_url) as db_map:
              entity_table = db_map.mapped_table("entity")
              prince = db_map.item(entity_table, entity_class_name="musician", name="Prince")
              db_map.remove_item(entity_table, id=prince["id"])



   .. py:method:: restore(mapped_table: spinedb_api.db_mapping_base.MappedTable, **kwargs) -> spinedb_api.db_mapping_base.PublicItem
      :staticmethod:


      Restores a previously removed item.

      Example::

          with DatabaseMapping(db_url) as db_map:
              entity_table = db_map.mapped_table("entity")
              db_map.restore(entity_table, entity_class_name="musician", name="Prince")



   .. py:method:: get_item(item_type: spinedb_api.helpers.ItemType | spinedb_api.helpers.LegacyItemType, fetch: bool = True, skip_removed: bool = True, **kwargs) -> spinedb_api.db_mapping_base.PublicItem | dict

      Finds and returns an item matching the arguments, or an empty dict if none found.

      This is legacy method. Use :meth:`item` instead.
      This method supports legacy item types, e.g. object and relationship_class.

      :param item_type: One of ``alternative``, ``scenario``, ``scenario_alternative``, ``entity_class``, ``display_mode``, ``entity_class_display_mode``, ``superclass_subclass``, ``entity``, ``entity_group``, ``entity_alternative``, ``parameter_value_list``, ``list_value``, ``parameter_type``, ``parameter_group``, ``parameter_definition``, ``parameter_value``, ``metadata``, ``entity_metadata``, ``parameter_value_metadata``, ``entity_location``.
      :param fetch: Whether to fetch the DB in case the item is not found in memory.
      :param skip_removed: Whether to ignore removed items.
      :param \*\*kwargs: Fields and values for one the unique keys as specified for the item type
                         in :ref:`db_mapping_schema`.

      :returns: :class:`PublicItem` or empty dict



   .. py:method:: get_items(item_type: spinedb_api.helpers.ItemType | spinedb_api.helpers.LegacyItemType, fetch: bool = True, skip_removed: bool = True, **kwargs) -> list[spinedb_api.db_mapping_base.PublicItem]

      Finds and returns all the items of one type.

      This is legacy method. Use :meth:`find` instead.
      This method supports legacy item types, e.g. object and relationship_class.

      :param item_type: One of ``alternative``, ``scenario``, ``scenario_alternative``, ``entity_class``, ``display_mode``, ``entity_class_display_mode``, ``superclass_subclass``, ``entity``, ``entity_group``, ``entity_alternative``, ``parameter_value_list``, ``list_value``, ``parameter_type``, ``parameter_group``, ``parameter_definition``, ``parameter_value``, ``metadata``, ``entity_metadata``, ``parameter_value_metadata``, ``entity_location``.
      :param fetch: Whether to fetch the DB before returning the items.
      :param skip_removed: Whether to ignore removed items.
      :param \*\*kwargs: Fields and values for one the unique keys as specified for the item type
                         in :ref:`db_mapping_schema`.

      :returns: The items.



   .. py:method:: add_item(item_type: spinedb_api.helpers.ItemType | spinedb_api.helpers.LegacyItemType, check: bool = True, **kwargs) -> tuple[spinedb_api.db_mapping_base.PublicItem | None, str | None]

      Adds an item to the in-memory mapping.

      This is legacy method. Use :meth:`add` instead.
      This method supports legacy item types, e.g. object and relationship_class.

      :param item_type: One of ``alternative``, ``scenario``, ``scenario_alternative``, ``entity_class``, ``display_mode``, ``entity_class_display_mode``, ``superclass_subclass``, ``entity``, ``entity_group``, ``entity_alternative``, ``parameter_value_list``, ``list_value``, ``parameter_type``, ``parameter_group``, ``parameter_definition``, ``parameter_value``, ``metadata``, ``entity_metadata``, ``parameter_value_metadata``, ``entity_location``.
      :param check: Whether to check for data integrity.
      :param \*\*kwargs: Fields and values as specified for the item type in :ref:`db_mapping_schema`.

      :returns: The added item and any errors.



   .. py:method:: add_items(item_type: spinedb_api.helpers.ItemType | spinedb_api.helpers.LegacyItemType, *items: dict, check: bool = True, strict: bool = False) -> tuple[list[spinedb_api.db_mapping_base.PublicItem | None], list[str | None]]

      Adds many items to the in-memory mapping.

      This is legacy method. Use the :meth:`add_entities`, :meth:`add_entity_classes` etc. methods instead.
      This method supports legacy item types, e.g. object and relationship_class.

      :param item_type: One of ``alternative``, ``scenario``, ``scenario_alternative``, ``entity_class``, ``display_mode``, ``entity_class_display_mode``, ``superclass_subclass``, ``entity``, ``entity_group``, ``entity_alternative``, ``parameter_value_list``, ``list_value``, ``parameter_type``, ``parameter_group``, ``parameter_definition``, ``parameter_value``, ``metadata``, ``entity_metadata``, ``parameter_value_metadata``, ``entity_location``.
      :param \*items: One or more :class:`dict` objects mapping fields to values of the item type,
                      as specified in :ref:`db_mapping_schema`.
      :param check: Whether to check for data integrity.
      :param strict: Whether the method should raise :exc:`~.exception.SpineIntegrityError`
                     if the insertion of one of the items violates an integrity constraint.

      :returns: items successfully added and found violations.



   .. py:method:: update_item(item_type: spinedb_api.helpers.ItemType | spinedb_api.helpers.LegacyItemType, check: bool = True, **kwargs) -> tuple[spinedb_api.db_mapping_base.PublicItem | None, str | None]

      Updates an item in the in-memory mapping.

      This is legacy method. Use :meth:`update` instead.
      This method supports legacy item types, e.g. object and relationship_class.

      :param item_type: One of ``alternative``, ``scenario``, ``scenario_alternative``, ``entity_class``, ``display_mode``, ``entity_class_display_mode``, ``superclass_subclass``, ``entity``, ``entity_group``, ``entity_alternative``, ``parameter_value_list``, ``list_value``, ``parameter_type``, ``parameter_group``, ``parameter_definition``, ``parameter_value``, ``metadata``, ``entity_metadata``, ``parameter_value_metadata``, ``entity_location``.
      :param check: Whether to check for data integrity and legacy item types.
      :param \*\*kwargs: Fields to update and their new values as specified for the item type in :ref:`db_mapping_schema`.

      :returns: The updated item and any errors.



   .. py:method:: update_items(item_type: spinedb_api.helpers.ItemType | spinedb_api.helpers.LegacyItemType, *items: dict, check: bool = True, strict: bool = False) -> tuple[list[spinedb_api.db_mapping_base.PublicItem | None], list[str | None]]

      Updates many items in the in-memory mapping.

      This is legacy method. Use the :meth:`update_entities`, :meth:`update_entity_classes` etc. methods instead.
      This method supports legacy item types, e.g. object and relationship_class.

      :param item_type: One of ``alternative``, ``scenario``, ``scenario_alternative``, ``entity_class``, ``display_mode``, ``entity_class_display_mode``, ``superclass_subclass``, ``entity``, ``entity_group``, ``entity_alternative``, ``parameter_value_list``, ``list_value``, ``parameter_type``, ``parameter_group``, ``parameter_definition``, ``parameter_value``, ``metadata``, ``entity_metadata``, ``parameter_value_metadata``, ``entity_location``.
      :param \*items: One or more :class:`dict` objects mapping fields to values of the item type,
                      as specified in :ref:`db_mapping_schema` and including the `id`.
      :param check: Whether to check for data integrity.
      :param strict: Whether the method should raise :exc:`~.exception.SpineIntegrityError`
                     if the update of one of the items violates an integrity constraint.

      :returns: items successfully updated and found violations.



   .. py:method:: add_update_item(item_type: spinedb_api.helpers.ItemType | spinedb_api.helpers.LegacyItemType, check: bool = True, **kwargs) -> tuple[spinedb_api.db_mapping_base.PublicItem | None, spinedb_api.db_mapping_base.PublicItem | None, str | None]

      Adds an item to the in-memory mapping if it doesn't exist; otherwise updates the current one.

      This is legacy method. Use :meth:`add_or_update` instead.
      This method supports legacy item types, e.g. object and relationship_class.

      :param item_type: One of ``alternative``, ``scenario``, ``scenario_alternative``, ``entity_class``, ``display_mode``, ``entity_class_display_mode``, ``superclass_subclass``, ``entity``, ``entity_group``, ``entity_alternative``, ``parameter_value_list``, ``list_value``, ``parameter_type``, ``parameter_group``, ``parameter_definition``, ``parameter_value``, ``metadata``, ``entity_metadata``, ``parameter_value_metadata``, ``entity_location``.
      :param check: Whether to check for data integrity.
      :param \*\*kwargs: Fields and values as specified for the item type in :ref:`db_mapping_schema`.

      :returns: The added item if any, the updated item if any, and any errors.



   .. py:method:: add_update_items(item_type: spinedb_api.helpers.ItemType | spinedb_api.helpers.LegacyItemType, *items: spinedb_api.db_mapping_base.PublicItem | spinedb_api.db_mapping_base.MappedItemBase | dict, check: bool = True, strict: bool = False) -> tuple[list[spinedb_api.db_mapping_base.PublicItem | None], list[spinedb_api.db_mapping_base.PublicItem | None], list[str | None]]

      Adds or updates many items into the in-memory mapping.

      This is legacy method.
      Use :meth:`add_or_update_entities`, :meth:`add_or_update_entity_classes` etc. methods instead.
      This method supports legacy item types, e.g. object and relationship_class.

      :param item_type: One of ``alternative``, ``scenario``, ``scenario_alternative``, ``entity_class``, ``display_mode``, ``entity_class_display_mode``, ``superclass_subclass``, ``entity``, ``entity_group``, ``entity_alternative``, ``parameter_value_list``, ``list_value``, ``parameter_type``, ``parameter_group``, ``parameter_definition``, ``parameter_value``, ``metadata``, ``entity_metadata``, ``parameter_value_metadata``, ``entity_location``.
      :param \*items: One or more :class:`dict` objects mapping fields to values of the item type,
                      as specified in :ref:`db_mapping_schema`.
      :param check: Whether to check for data integrity.
      :param strict: Whether the method should raise :exc:`~.exception.SpineIntegrityError`
                     if the insertion of one of the items violates an integrity constraint.

      :returns: items successfully added, items successfully updated, and found violations.



   .. py:method:: remove_item(item_type: spinedb_api.helpers.ItemType | spinedb_api.helpers.LegacyItemType, id_: spinedb_api.temp_id.TempId | int, check: bool = True) -> tuple[spinedb_api.db_mapping_base.PublicItem | None, str | None]

      Removes an item from the in-memory mapping.

      This is legacy method. Use :meth:`remove` instead.
      This method supports legacy item types, e.g. object and relationship_class.

      :param item_type: One of ``alternative``, ``scenario``, ``scenario_alternative``, ``entity_class``, ``display_mode``, ``entity_class_display_mode``, ``superclass_subclass``, ``entity``, ``entity_group``, ``entity_alternative``, ``parameter_value_list``, ``list_value``, ``parameter_type``, ``parameter_group``, ``parameter_definition``, ``parameter_value``, ``metadata``, ``entity_metadata``, ``parameter_value_metadata``, ``entity_location``.
      :param id_: The id of the item to remove.
      :param check: Whether to check for data integrity.

      :returns: The removed item and any errors.
      :rtype: tuple(:class:`PublicItem` or None, str)



   .. py:method:: remove_items(item_type: spinedb_api.helpers.ItemType | spinedb_api.helpers.LegacyItemType, *ids: spinedb_api.temp_id.TempId | int, check: bool = True, strict: bool = False) -> tuple[list[spinedb_api.db_mapping_base.PublicItem], list[str]]

      Removes many items from the in-memory mapping.

      This is legacy method.
      Use :meth:`remove_entities`, :meth:`remove_entity_classes` etc. methods instead.
      This method supports legacy item types, e.g. object and relationship_class.

      :param item_type: One of ``alternative``, ``scenario``, ``scenario_alternative``, ``entity_class``, ``display_mode``, ``entity_class_display_mode``, ``superclass_subclass``, ``entity``, ``entity_group``, ``entity_alternative``, ``parameter_value_list``, ``list_value``, ``parameter_type``, ``parameter_group``, ``parameter_definition``, ``parameter_value``, ``metadata``, ``entity_metadata``, ``parameter_value_metadata``, ``entity_location``.
      :param \*ids: Ids of items to be removed.
      :param check: Whether to check for data integrity.
      :param strict: Whether the method should raise :exc:`~.exception.SpineIntegrityError`
                     if the update of one of the items violates an integrity constraint.

      :returns: items successfully removed and found violations.



   .. py:method:: restore_item(item_type: spinedb_api.helpers.ItemType | spinedb_api.helpers.LegacyItemType, id_: spinedb_api.temp_id.TempId | int) -> tuple[spinedb_api.db_mapping_base.PublicItem | None, str | None]

      Restores a previously removed item into the in-memory mapping.

      This is legacy method. Use :meth:`restore` instead.
      This method supports legacy item types, e.g. object and relationship_class.

      :param item_type: One of ``alternative``, ``scenario``, ``scenario_alternative``, ``entity_class``, ``display_mode``, ``entity_class_display_mode``, ``superclass_subclass``, ``entity``, ``entity_group``, ``entity_alternative``, ``parameter_value_list``, ``list_value``, ``parameter_type``, ``parameter_group``, ``parameter_definition``, ``parameter_value``, ``metadata``, ``entity_metadata``, ``parameter_value_metadata``, ``entity_location``.
      :param id_: The id of the item to restore.

      :returns: The restored item if any and possible error.



   .. py:method:: restore_items(item_type: spinedb_api.helpers.ItemType | spinedb_api.helpers.LegacyItemType, *ids: spinedb_api.temp_id.TempId | int) -> tuple[list[spinedb_api.db_mapping_base.PublicItem | None], list[str | None]]

      Restores many previously removed items into the in-memory mapping.

      This is legacy method.
      Use :meth:`restore_entities`, :meth:`restore_entity_classes` etc. methods instead.
      This method supports legacy item types, e.g. object and relationship_class.

      :param item_type: One of ``alternative``, ``scenario``, ``scenario_alternative``, ``entity_class``, ``display_mode``, ``entity_class_display_mode``, ``superclass_subclass``, ``entity``, ``entity_group``, ``entity_alternative``, ``parameter_value_list``, ``list_value``, ``parameter_type``, ``parameter_group``, ``parameter_definition``, ``parameter_value``, ``metadata``, ``entity_metadata``, ``parameter_value_metadata``, ``entity_location``.
      :param \*ids: Ids of items to be removed.

      :returns: items successfully restored and found violations.



   .. py:method:: purge_items(item_type: spinedb_api.helpers.ItemType | spinedb_api.helpers.LegacyItemType) -> bool

      Removes all items of one type.

      This is legacy method. Use :meth:`remove_entity`, :meth:`remove_entity_class` etc.
      with ``id=Asterisk`` instead.
      This method supports legacy item types, e.g. object and relationship_class.

      :param item_type: One of ``alternative``, ``scenario``, ``scenario_alternative``, ``entity_class``, ``display_mode``, ``entity_class_display_mode``, ``superclass_subclass``, ``entity``, ``entity_group``, ``entity_alternative``, ``parameter_value_list``, ``list_value``, ``parameter_type``, ``parameter_group``, ``parameter_definition``, ``parameter_value``, ``metadata``, ``entity_metadata``, ``parameter_value_metadata``, ``entity_location``.

      :returns: True if any data was removed, False otherwise.



   .. py:method:: fetch_more(item_type: spinedb_api.helpers.ItemType | spinedb_api.helpers.LegacyItemType, offset: int = 0, limit: int | None = None, **kwargs) -> list[spinedb_api.db_mapping_base.PublicItem]

      Fetches items from the DB into the in-memory mapping, incrementally.

      :param item_type: One of ``alternative``, ``scenario``, ``scenario_alternative``, ``entity_class``, ``display_mode``, ``entity_class_display_mode``, ``superclass_subclass``, ``entity``, ``entity_group``, ``entity_alternative``, ``parameter_value_list``, ``list_value``, ``parameter_type``, ``parameter_group``, ``parameter_definition``, ``parameter_value``, ``metadata``, ``entity_metadata``, ``parameter_value_metadata``, ``entity_location``.
      :param offset: The initial row.
      :param limit: The maximum number of rows to fetch.
      :param \*\*kwargs: Fields and values for one the unique keys as specified for the item type
                         in :ref:`db_mapping_schema`.

      :returns: The items fetched.



   .. py:method:: fetch_all(*item_types: spinedb_api.helpers.ItemType | spinedb_api.helpers.LegacyItemType) -> list[spinedb_api.db_mapping_base.PublicItem]

      Fetches items from the DB into the in-memory mapping.
      Unlike :meth:`fetch_more`, this method fetches entire tables.

      :param \*item_types: One or more of ``alternative``, ``scenario``, ``scenario_alternative``, ``entity_class``, ``display_mode``, ``entity_class_display_mode``, ``superclass_subclass``, ``entity``, ``entity_group``, ``entity_alternative``, ``parameter_value_list``, ``list_value``, ``parameter_type``, ``parameter_group``, ``parameter_definition``, ``parameter_value``, ``metadata``, ``entity_metadata``, ``parameter_value_metadata``, ``entity_location``. If none given, then the entire DB is fetched.



   .. py:method:: query(*entities, **kwargs) -> sqlalchemy.orm.Query

      Returns a :class:`~spinedb_api.query.Query` object to execute against the mapped DB.

      To perform custom ``SELECT`` statements, call this method with one or more of the documented
      subquery properties of :class:`~spinedb_api.db_mapping_query_mixin.DatabaseMappingQueryMixin` returning
      :class:`~sqlalchemy.sql.expression.Subquery` objetcs.
      For example, to select the entity class with ``id`` equal to 1::

          from spinedb_api import DatabaseMapping
          url = 'sqlite:///spine.db'
          ...
          with DatabaseMapping(url) as db_map:
              entity_record = db_map.query(db_map.entity_class_sq).filter_by(id=1).one_or_none()
              if entity_record is not None:
                  ...

      To perform more complex queries, use SQLAlchemy's :class:`~sqlalchemy.orm.query.Query` interface.
      For example, to select all entity class names and the names of their entities concatenated in a comma-separated
      string::

          from sqlalchemy import func

          with DatabaseMapping(ur) as db_map:
              classes = db_map.query(
                  db_map.entity_class_sq.c.name,
                  func.group_concat(db_map.entity_sq.c.name).label("entities")
              ).filter(
                  db_map.entity_sq.c.class_id == db_map.entity_class_sq.c.id
              ).group_by(
                  db_map.entity_class_sq.c.name
              ).all()
              for entity_class in classes:
                  print(f"{entity_class.name}: {entity_class.entities}")

      :returns: The resulting query.
      :rtype: :class:`~sqlalchemy.orm.Query`



   .. py:method:: commit_session(comment: str, apply_compatibility_transforms: bool = True) -> spinedb_api.compatibility.CompatibilityTransformations

      Commits the changes from the in-memory mapping to the database.

      :param comment: commit message
      :param apply_compatibility_transforms: if True, apply compatibility transforms

      :returns: compatibility transformations



   .. py:method:: rollback_session() -> None

      Discards all the changes from the in-memory mapping.



   .. py:method:: has_external_commits() -> bool

      Tests whether the database has had commits from other sources than this mapping.

      :returns: True if database has external commits, False otherwise



   .. py:method:: get_filter_configs() -> list[dict]

      Returns the config dicts of filters applied to this database mapping.



   .. py:method:: close() -> None

      Closes this DB mapping.



   .. py:method:: alternative(**kwargs)

      Returns an `alternative` item matching the keyword arguments.

      :param name: The alternative name.
      :type name: str

      :returns: :class:`PublicItem`



   .. py:method:: scenario(**kwargs)

      Returns a `scenario` item matching the keyword arguments.

      :param name: The scenario name.
      :type name: str

      :returns: :class:`PublicItem`



   .. py:method:: scenario_alternative(**kwargs)

      Returns a `scenario_alternative` item matching the keyword arguments.

      :param alternative_name: The alternative name.
      :type alternative_name: str
      :param scenario_name: The scenario name.
      :type scenario_name: str
      :param rank: The rank - higher has precedence.
      :type rank: int

      :returns: :class:`PublicItem`



   .. py:method:: entity_class(**kwargs)

      Returns an `entity_class` item matching the keyword arguments.

      :param name: The class name.
      :type name: str

      :returns: :class:`PublicItem`



   .. py:method:: display_mode(**kwargs)

      Returns a `display_mode` item matching the keyword arguments.

      :param name: The display mode name.
      :type name: str

      :returns: :class:`PublicItem`



   .. py:method:: entity_class_display_mode(**kwargs)

      Returns an `entity_class_display_mode` item matching the keyword arguments.

      :param display_mode_name: The display mode name.
      :type display_mode_name: int
      :param entity_class_name: The entity class name.
      :type entity_class_name: str

      :returns: :class:`PublicItem`



   .. py:method:: superclass_subclass(**kwargs)

      Returns a `superclass_subclass` item matching the keyword arguments.

      :param subclass_name: The subclass name.
      :type subclass_name: str

      :returns: :class:`PublicItem`



   .. py:method:: entity(**kwargs)

      Returns an `entity` item matching the keyword arguments.

      :param entity_class_name: The entity class name.
      :type entity_class_name: str
      :param name: The entity name.
      :type name: str
      :param entity_byname: A tuple with the entity name as single element if the entity is 0-dimensional, or the 0-dimensional element names if it is multi-dimensional.
      :type entity_byname: tuple

      :returns: :class:`PublicItem`



   .. py:method:: entity_group(**kwargs)

      Returns an `entity_group` item matching the keyword arguments.

      :param entity_class_name: The entity class name.
      :type entity_class_name: str
      :param member_name: The member entity name.
      :type member_name: str
      :param group_name: The group entity name.
      :type group_name: str

      :returns: :class:`PublicItem`



   .. py:method:: entity_alternative(**kwargs)

      Returns an `entity_alternative` item matching the keyword arguments.

      :param entity_class_name: The entity class name.
      :type entity_class_name: str
      :param entity_byname: A tuple with the entity name as single element if the entity is 0-dimensional, or the 0-dimensional element names if it is multi-dimensional.
      :type entity_byname: tuple
      :param alternative_name: The alternative name.
      :type alternative_name: str

      :returns: :class:`PublicItem`



   .. py:method:: parameter_value_list(**kwargs)

      Returns a `parameter_value_list` item matching the keyword arguments.

      :param name: The parameter value list name.
      :type name: str

      :returns: :class:`PublicItem`



   .. py:method:: list_value(**kwargs)

      Returns a `list_value` item matching the keyword arguments.

      :param parameter_value_list_name: The parameter value list name.
      :type parameter_value_list_name: str
      :param index: The value index.
      :type index: int, optional

      :returns: :class:`PublicItem`



   .. py:method:: parameter_type(**kwargs)

      Returns a `parameter_type` item matching the keyword arguments.

      :param type: The value type.
      :type type: str
      :param entity_class_name: The entity class name.
      :type entity_class_name: str
      :param rank: The rank of the type.
      :type rank: int
      :param parameter_definition_name: The parameter name.
      :type parameter_definition_name: str

      :returns: :class:`PublicItem`



   .. py:method:: parameter_group(**kwargs)

      Returns a `parameter_group` item matching the keyword arguments.

      :param name: The parameter group name.
      :type name: str

      :returns: :class:`PublicItem`



   .. py:method:: parameter_definition(**kwargs)

      Returns a `parameter_definition` item matching the keyword arguments.

      :param entity_class_name: The entity class name.
      :type entity_class_name: str
      :param name: The parameter name.
      :type name: str

      :returns: :class:`PublicItem`



   .. py:method:: parameter_value(**kwargs)

      Returns a `parameter_value` item matching the keyword arguments.

      :param entity_class_name: The entity class name.
      :type entity_class_name: str
      :param entity_byname: A tuple with the entity name as single element if the entity is 0-dimensional, or the 0-dimensional element names if it is multi-dimensional.
      :type entity_byname: tuple
      :param alternative_name: The alternative name - defaults to 'Base'.
      :type alternative_name: str, optional
      :param parameter_definition_name: The parameter name.
      :type parameter_definition_name: str

      :returns: :class:`PublicItem`



   .. py:method:: metadata(**kwargs)

      Returns a `metadata` item matching the keyword arguments.

      :param name: The metadata entry name.
      :type name: str
      :param value: The metadata entry value.
      :type value: str

      :returns: :class:`PublicItem`



   .. py:method:: entity_metadata(**kwargs)

      Returns an `entity_metadata` item matching the keyword arguments.

      :param metadata_name: The metadata entry name.
      :type metadata_name: str
      :param entity_class_name: The entity class name.
      :type entity_class_name: str
      :param entity_byname: A tuple with the entity name as single element if the entity is 0-dimensional, or the 0-dimensional element names if it is multi-dimensional.
      :type entity_byname: tuple
      :param metadata_value: The metadata entry value.
      :type metadata_value: str

      :returns: :class:`PublicItem`



   .. py:method:: parameter_value_metadata(**kwargs)

      Returns a `parameter_value_metadata` item matching the keyword arguments.

      :param alternative_name: The alternative name.
      :type alternative_name: str
      :param metadata_name: The metadata entry name.
      :type metadata_name: str
      :param entity_class_name: The entity class name.
      :type entity_class_name: str
      :param metadata_value: The metadata entry value.
      :type metadata_value: str
      :param parameter_definition_name: The parameter name.
      :type parameter_definition_name: str
      :param entity_byname: A tuple with the entity name as single element if the entity is 0-dimensional, or the 0-dimensional element names if it is multi-dimensional.
      :type entity_byname: tuple

      :returns: :class:`PublicItem`



   .. py:method:: entity_location(**kwargs)

      Returns an `entity_location` item matching the keyword arguments.

      :param entity_class_name: The entity class name.
      :type entity_class_name: str
      :param entity_byname: A tuple with the entity name as single element if the entity is 0-dimensional, or the 0-dimensional element names if it is multi-dimensional.
      :type entity_byname: tuple

      :returns: :class:`PublicItem`



   .. py:method:: find_alternatives(**kwargs)

      Finds and returns all `alternative` items matching the keyword arguments.

      :param name: The alternative name.
      :type name: str

      :returns: The items.
      :rtype: list of :class:`PublicItem`



   .. py:method:: find_scenarios(**kwargs)

      Finds and returns all `scenario` items matching the keyword arguments.

      :param name: The scenario name.
      :type name: str

      :returns: The items.
      :rtype: list of :class:`PublicItem`



   .. py:method:: find_scenario_alternatives(**kwargs)

      Finds and returns all `scenario_alternative` items matching the keyword arguments.

      :param alternative_name: The alternative name.
      :type alternative_name: str
      :param scenario_name: The scenario name.
      :type scenario_name: str
      :param rank: The rank - higher has precedence.
      :type rank: int

      :returns: The items.
      :rtype: list of :class:`PublicItem`



   .. py:method:: find_entity_classes(**kwargs)

      Finds and returns all `entity_class` items matching the keyword arguments.

      :param name: The class name.
      :type name: str

      :returns: The items.
      :rtype: list of :class:`PublicItem`



   .. py:method:: find_display_modes(**kwargs)

      Finds and returns all `display_mode` items matching the keyword arguments.

      :param name: The display mode name.
      :type name: str

      :returns: The items.
      :rtype: list of :class:`PublicItem`



   .. py:method:: find_entity_class_display_modes(**kwargs)

      Finds and returns all `entity_class_display_mode` items matching the keyword arguments.

      :param display_mode_name: The display mode name.
      :type display_mode_name: int
      :param entity_class_name: The entity class name.
      :type entity_class_name: str

      :returns: The items.
      :rtype: list of :class:`PublicItem`



   .. py:method:: find_superclass_subclasses(**kwargs)

      Finds and returns all `superclass_subclass` items matching the keyword arguments.

      :param subclass_name: The subclass name.
      :type subclass_name: str

      :returns: The items.
      :rtype: list of :class:`PublicItem`



   .. py:method:: find_entities(**kwargs)

      Finds and returns all `entity` items matching the keyword arguments.

      :param entity_class_name: The entity class name.
      :type entity_class_name: str
      :param name: The entity name.
      :type name: str
      :param entity_byname: A tuple with the entity name as single element if the entity is 0-dimensional, or the 0-dimensional element names if it is multi-dimensional.
      :type entity_byname: tuple

      :returns: The items.
      :rtype: list of :class:`PublicItem`



   .. py:method:: find_entity_groups(**kwargs)

      Finds and returns all `entity_group` items matching the keyword arguments.

      :param entity_class_name: The entity class name.
      :type entity_class_name: str
      :param member_name: The member entity name.
      :type member_name: str
      :param group_name: The group entity name.
      :type group_name: str

      :returns: The items.
      :rtype: list of :class:`PublicItem`



   .. py:method:: find_entity_alternatives(**kwargs)

      Finds and returns all `entity_alternative` items matching the keyword arguments.

      :param entity_class_name: The entity class name.
      :type entity_class_name: str
      :param entity_byname: A tuple with the entity name as single element if the entity is 0-dimensional, or the 0-dimensional element names if it is multi-dimensional.
      :type entity_byname: tuple
      :param alternative_name: The alternative name.
      :type alternative_name: str

      :returns: The items.
      :rtype: list of :class:`PublicItem`



   .. py:method:: find_parameter_value_lists(**kwargs)

      Finds and returns all `parameter_value_list` items matching the keyword arguments.

      :param name: The parameter value list name.
      :type name: str

      :returns: The items.
      :rtype: list of :class:`PublicItem`



   .. py:method:: find_list_values(**kwargs)

      Finds and returns all `list_value` items matching the keyword arguments.

      :param parameter_value_list_name: The parameter value list name.
      :type parameter_value_list_name: str
      :param index: The value index.
      :type index: int, optional

      :returns: The items.
      :rtype: list of :class:`PublicItem`



   .. py:method:: find_parameter_types(**kwargs)

      Finds and returns all `parameter_type` items matching the keyword arguments.

      :param type: The value type.
      :type type: str
      :param entity_class_name: The entity class name.
      :type entity_class_name: str
      :param rank: The rank of the type.
      :type rank: int
      :param parameter_definition_name: The parameter name.
      :type parameter_definition_name: str

      :returns: The items.
      :rtype: list of :class:`PublicItem`



   .. py:method:: find_parameter_groups(**kwargs)

      Finds and returns all `parameter_group` items matching the keyword arguments.

      :param name: The parameter group name.
      :type name: str

      :returns: The items.
      :rtype: list of :class:`PublicItem`



   .. py:method:: find_parameter_definitions(**kwargs)

      Finds and returns all `parameter_definition` items matching the keyword arguments.

      :param entity_class_name: The entity class name.
      :type entity_class_name: str
      :param name: The parameter name.
      :type name: str

      :returns: The items.
      :rtype: list of :class:`PublicItem`



   .. py:method:: find_parameter_values(**kwargs)

      Finds and returns all `parameter_value` items matching the keyword arguments.

      :param entity_class_name: The entity class name.
      :type entity_class_name: str
      :param entity_byname: A tuple with the entity name as single element if the entity is 0-dimensional, or the 0-dimensional element names if it is multi-dimensional.
      :type entity_byname: tuple
      :param alternative_name: The alternative name - defaults to 'Base'.
      :type alternative_name: str, optional
      :param parameter_definition_name: The parameter name.
      :type parameter_definition_name: str

      :returns: The items.
      :rtype: list of :class:`PublicItem`



   .. py:method:: find_metadata_items(**kwargs)

      Finds and returns all `metadata` items matching the keyword arguments.

      :param name: The metadata entry name.
      :type name: str
      :param value: The metadata entry value.
      :type value: str

      :returns: The items.
      :rtype: list of :class:`PublicItem`



   .. py:method:: find_entity_metadata_items(**kwargs)

      Finds and returns all `entity_metadata` items matching the keyword arguments.

      :param metadata_name: The metadata entry name.
      :type metadata_name: str
      :param entity_class_name: The entity class name.
      :type entity_class_name: str
      :param entity_byname: A tuple with the entity name as single element if the entity is 0-dimensional, or the 0-dimensional element names if it is multi-dimensional.
      :type entity_byname: tuple
      :param metadata_value: The metadata entry value.
      :type metadata_value: str

      :returns: The items.
      :rtype: list of :class:`PublicItem`



   .. py:method:: find_parameter_value_metadata_items(**kwargs)

      Finds and returns all `parameter_value_metadata` items matching the keyword arguments.

      :param alternative_name: The alternative name.
      :type alternative_name: str
      :param metadata_name: The metadata entry name.
      :type metadata_name: str
      :param entity_class_name: The entity class name.
      :type entity_class_name: str
      :param metadata_value: The metadata entry value.
      :type metadata_value: str
      :param parameter_definition_name: The parameter name.
      :type parameter_definition_name: str
      :param entity_byname: A tuple with the entity name as single element if the entity is 0-dimensional, or the 0-dimensional element names if it is multi-dimensional.
      :type entity_byname: tuple

      :returns: The items.
      :rtype: list of :class:`PublicItem`



   .. py:method:: find_entity_locations(**kwargs)

      Finds and returns all `entity_location` items matching the keyword arguments.

      :param entity_class_name: The entity class name.
      :type entity_class_name: str
      :param entity_byname: A tuple with the entity name as single element if the entity is 0-dimensional, or the 0-dimensional element names if it is multi-dimensional.
      :type entity_byname: tuple

      :returns: The items.
      :rtype: list of :class:`PublicItem`



   .. py:method:: add_alternative(**kwargs)

      Adds an `alternative` item to the in-memory mapping.

      :param name: The alternative name.
      :type name: str
      :param description: The alternative description.
      :type description: str, optional

      :returns: The added item.
      :rtype: :class:`PublicItem`



   .. py:method:: add_scenario(**kwargs)

      Adds a `scenario` item to the in-memory mapping.

      :param name: The scenario name.
      :type name: str
      :param description: The scenario description.
      :type description: str, optional
      :param active: Not in use at the moment.
      :type active: bool, optional

      :returns: The added item.
      :rtype: :class:`PublicItem`



   .. py:method:: add_scenario_alternative(**kwargs)

      Adds a `scenario_alternative` item to the in-memory mapping.

      :param scenario_name: The scenario name.
      :type scenario_name: str
      :param alternative_name: The alternative name.
      :type alternative_name: str
      :param rank: The rank - higher has precedence.
      :type rank: int

      :returns: The added item.
      :rtype: :class:`PublicItem`



   .. py:method:: add_entity_class(**kwargs)

      Adds an `entity_class` item to the in-memory mapping.

      :param name: The class name.
      :type name: str
      :param dimension_name_list: The dimension names for a multi-dimensional class.
      :type dimension_name_list: tuple, optional
      :param entity_class_byname: A tuple with the class name as single element if the class is 0-dimensional, or the 0-dimensional class names if it is multi-dimensional.
      :type entity_class_byname: tuple
      :param description: The class description.
      :type description: str, optional
      :param display_icon: An integer representing an icon within your application.
      :type display_icon: int, optional
      :param display_order: Not in use at the moment.
      :type display_order: int, optional
      :param hidden: Not in use at the moment.
      :type hidden: int, optional
      :param active_by_default: Default activity for the entity alternatives of the class.
      :type active_by_default: bool, optional

      :returns: The added item.
      :rtype: :class:`PublicItem`



   .. py:method:: add_display_mode(**kwargs)

      Adds a `display_mode` item to the in-memory mapping.

      :param name: The display mode name.
      :type name: str
      :param description: The display mode description.
      :type description: str, optional

      :returns: The added item.
      :rtype: :class:`PublicItem`



   .. py:method:: add_entity_class_display_mode(**kwargs)

      Adds an `entity_class_display_mode` item to the in-memory mapping.

      :param entity_class_name: The entity class name.
      :type entity_class_name: str
      :param display_mode_name: The display mode name.
      :type display_mode_name: int
      :param display_order: The display order.
      :type display_order: int
      :param display_status: The display status; one of 'visible', 'hidden' or 'greyed_out'.
      :type display_status: str
      :param display_font_color: The color of the font.
      :type display_font_color: str, optional
      :param display_background_color: The  color of the background.
      :type display_background_color: str, optional

      :returns: The added item.
      :rtype: :class:`PublicItem`



   .. py:method:: add_superclass_subclass(**kwargs)

      Adds a `superclass_subclass` item to the in-memory mapping.

      :param superclass_name: The superclass name.
      :type superclass_name: str
      :param subclass_name: The subclass name.
      :type subclass_name: str

      :returns: The added item.
      :rtype: :class:`PublicItem`



   .. py:method:: add_entity(**kwargs)

      Adds an `entity` item to the in-memory mapping.

      :param entity_class_name: The entity class name.
      :type entity_class_name: str
      :param name: The entity name.
      :type name: str
      :param element_name_list: The element names if the entity is multi-dimensional.
      :type element_name_list: tuple
      :param entity_byname: A tuple with the entity name as single element if the entity is 0-dimensional, or the 0-dimensional element names if it is multi-dimensional.
      :type entity_byname: tuple
      :param description: The entity description.
      :type description: str, optional
      :param lat: The latitude of entity.
      :type lat: float, optional
      :param lon: The longitude of entity.
      :type lon: float, optional
      :param alt: The altitude of entity.
      :type alt: float, optional
      :param shape_name: The name of the entity's shape.
      :type shape_name: str, optional
      :param shape_blob: The shape as GEOJSON string.
      :type shape_blob: str, optional

      :returns: The added item.
      :rtype: :class:`PublicItem`



   .. py:method:: add_entity_group(**kwargs)

      Adds an `entity_group` item to the in-memory mapping.

      :param entity_class_name: The entity class name.
      :type entity_class_name: str
      :param group_name: The group entity name.
      :type group_name: str
      :param member_name: The member entity name.
      :type member_name: str

      :returns: The added item.
      :rtype: :class:`PublicItem`



   .. py:method:: add_entity_alternative(**kwargs)

      Adds an `entity_alternative` item to the in-memory mapping.

      :param entity_class_name: The entity class name.
      :type entity_class_name: str
      :param entity_byname: A tuple with the entity name as single element if the entity is 0-dimensional, or the 0-dimensional element names if it is multi-dimensional.
      :type entity_byname: tuple
      :param alternative_name: The alternative name.
      :type alternative_name: str
      :param active: Whether the entity is active in the alternative - defaults to True.
      :type active: bool, optional

      :returns: The added item.
      :rtype: :class:`PublicItem`



   .. py:method:: add_parameter_value_list(**kwargs)

      Adds a `parameter_value_list` item to the in-memory mapping.

      :param name: The parameter value list name.
      :type name: str

      :returns: The added item.
      :rtype: :class:`PublicItem`



   .. py:method:: add_list_value(**kwargs)

      Adds a `list_value` item to the in-memory mapping.

      :param parameter_value_list_name: The parameter value list name.
      :type parameter_value_list_name: str
      :param value: The value's database representation.
      :type value: bytes
      :param type: The value's type.
      :type type: str, optional
      :param parsed_value: The value.
      :type parsed_value: ParameterValue, optional
      :param index: The value index.
      :type index: int, optional

      :returns: The added item.
      :rtype: :class:`PublicItem`



   .. py:method:: add_parameter_type(**kwargs)

      Adds a `parameter_type` item to the in-memory mapping.

      :param entity_class_name: The entity class name.
      :type entity_class_name: str
      :param parameter_definition_name: The parameter name.
      :type parameter_definition_name: str
      :param rank: The rank of the type.
      :type rank: int
      :param type: The value type.
      :type type: str

      :returns: The added item.
      :rtype: :class:`PublicItem`



   .. py:method:: add_parameter_group(**kwargs)

      Adds a `parameter_group` item to the in-memory mapping.

      :param name: The parameter group name.
      :type name: str
      :param color: Group's color as HEX.
      :type color: str
      :param priority: Group's priority.
      :type priority: int

      :returns: The added item.
      :rtype: :class:`PublicItem`



   .. py:method:: add_parameter_definition(**kwargs)

      Adds a `parameter_definition` item to the in-memory mapping.

      :param entity_class_name: The entity class name.
      :type entity_class_name: str
      :param name: The parameter name.
      :type name: str
      :param parameter_group_name: The name of the group of the parameter.
      :type parameter_group_name: str, optional
      :param parameter_type_list: List of valid value types.
      :type parameter_type_list: tuple, optional
      :param default_value: The default value's database representation.
      :type default_value: bytes, optional
      :param default_type: The default value's type.
      :type default_type: str, optional
      :param parsed_value: The default value.
      :type parsed_value: ParameterValue, optional
      :param parameter_value_list_name: The parameter value list name if any.
      :type parameter_value_list_name: str, optional
      :param description: The parameter description.
      :type description: str, optional

      :returns: The added item.
      :rtype: :class:`PublicItem`



   .. py:method:: add_parameter_value(**kwargs)

      Adds a `parameter_value` item to the in-memory mapping.

      :param entity_class_name: The entity class name.
      :type entity_class_name: str
      :param parameter_definition_name: The parameter name.
      :type parameter_definition_name: str
      :param entity_byname: A tuple with the entity name as single element if the entity is 0-dimensional, or the 0-dimensional element names if it is multi-dimensional.
      :type entity_byname: tuple
      :param value: The value's database representation.
      :type value: bytes
      :param type: The value's type. Optional only when value is null.
      :type type: str, optional
      :param parsed_value: The value.
      :type parsed_value: ParameterValue, optional
      :param alternative_name: The alternative name - defaults to 'Base'.
      :type alternative_name: str, optional

      :returns: The added item.
      :rtype: :class:`PublicItem`



   .. py:method:: add_metadata(**kwargs)

      Adds a `metadata` item to the in-memory mapping.

      :param name: The metadata entry name.
      :type name: str
      :param value: The metadata entry value.
      :type value: str

      :returns: The added item.
      :rtype: :class:`PublicItem`



   .. py:method:: add_entity_metadata(**kwargs)

      Adds an `entity_metadata` item to the in-memory mapping.

      :param entity_class_name: The entity class name.
      :type entity_class_name: str
      :param entity_byname: A tuple with the entity name as single element if the entity is 0-dimensional, or the 0-dimensional element names if it is multi-dimensional.
      :type entity_byname: tuple
      :param metadata_name: The metadata entry name.
      :type metadata_name: str
      :param metadata_value: The metadata entry value.
      :type metadata_value: str

      :returns: The added item.
      :rtype: :class:`PublicItem`



   .. py:method:: add_parameter_value_metadata(**kwargs)

      Adds a `parameter_value_metadata` item to the in-memory mapping.

      :param entity_class_name: The entity class name.
      :type entity_class_name: str
      :param parameter_definition_name: The parameter name.
      :type parameter_definition_name: str
      :param entity_byname: A tuple with the entity name as single element if the entity is 0-dimensional, or the 0-dimensional element names if it is multi-dimensional.
      :type entity_byname: tuple
      :param alternative_name: The alternative name.
      :type alternative_name: str
      :param metadata_name: The metadata entry name.
      :type metadata_name: str
      :param metadata_value: The metadata entry value.
      :type metadata_value: str

      :returns: The added item.
      :rtype: :class:`PublicItem`



   .. py:method:: add_entity_location(**kwargs)

      Adds an `entity_location` item to the in-memory mapping.

      :param entity_class_name: The entity class name.
      :type entity_class_name: str
      :param entity_byname: A tuple with the entity name as single element if the entity is 0-dimensional, or the 0-dimensional element names if it is multi-dimensional.
      :type entity_byname: tuple
      :param lat: Latitude.
      :type lat: float, optional
      :param lon: Longitude.
      :type lon: float, optional
      :param alt: Altitude.
      :type alt: float, optional
      :param shape_name: Name identifying the shape.
      :type shape_name: str, optional
      :param shape_blob: Shape as GEOJSON feature.
      :type shape_blob: str, optional

      :returns: The added item.
      :rtype: :class:`PublicItem`



   .. py:method:: add_alternatives(items)

      Adds multiple `alternative` items to the in-memory mapping.

      :param items: items to add
      :type items: list of dict



   .. py:method:: add_scenarios(items)

      Adds multiple `scenario` items to the in-memory mapping.

      :param items: items to add
      :type items: list of dict



   .. py:method:: add_scenario_alternatives(items)

      Adds multiple `scenario_alternative` items to the in-memory mapping.

      :param items: items to add
      :type items: list of dict



   .. py:method:: add_entity_classes(items)

      Adds multiple `entity_class` items to the in-memory mapping.

      :param items: items to add
      :type items: list of dict



   .. py:method:: add_display_modes(items)

      Adds multiple `display_mode` items to the in-memory mapping.

      :param items: items to add
      :type items: list of dict



   .. py:method:: add_entity_class_display_modes(items)

      Adds multiple `entity_class_display_mode` items to the in-memory mapping.

      :param items: items to add
      :type items: list of dict



   .. py:method:: add_superclass_subclasses(items)

      Adds multiple `superclass_subclass` items to the in-memory mapping.

      :param items: items to add
      :type items: list of dict



   .. py:method:: add_entities(items)

      Adds multiple `entity` items to the in-memory mapping.

      :param items: items to add
      :type items: list of dict



   .. py:method:: add_entity_groups(items)

      Adds multiple `entity_group` items to the in-memory mapping.

      :param items: items to add
      :type items: list of dict



   .. py:method:: add_entity_alternatives(items)

      Adds multiple `entity_alternative` items to the in-memory mapping.

      :param items: items to add
      :type items: list of dict



   .. py:method:: add_parameter_value_lists(items)

      Adds multiple `parameter_value_list` items to the in-memory mapping.

      :param items: items to add
      :type items: list of dict



   .. py:method:: add_list_values(items)

      Adds multiple `list_value` items to the in-memory mapping.

      :param items: items to add
      :type items: list of dict



   .. py:method:: add_parameter_types(items)

      Adds multiple `parameter_type` items to the in-memory mapping.

      :param items: items to add
      :type items: list of dict



   .. py:method:: add_parameter_groups(items)

      Adds multiple `parameter_group` items to the in-memory mapping.

      :param items: items to add
      :type items: list of dict



   .. py:method:: add_parameter_definitions(items)

      Adds multiple `parameter_definition` items to the in-memory mapping.

      :param items: items to add
      :type items: list of dict



   .. py:method:: add_parameter_values(items)

      Adds multiple `parameter_value` items to the in-memory mapping.

      :param items: items to add
      :type items: list of dict



   .. py:method:: add_metadata_items(items)

      Adds multiple `metadata` items to the in-memory mapping.

      :param items: items to add
      :type items: list of dict



   .. py:method:: add_entity_metadata_items(items)

      Adds multiple `entity_metadata` items to the in-memory mapping.

      :param items: items to add
      :type items: list of dict



   .. py:method:: add_parameter_value_metadata_items(items)

      Adds multiple `parameter_value_metadata` items to the in-memory mapping.

      :param items: items to add
      :type items: list of dict



   .. py:method:: add_entity_locations(items)

      Adds multiple `entity_location` items to the in-memory mapping.

      :param items: items to add
      :type items: list of dict



   .. py:method:: update_alternative(**kwargs)

      Updates an `alternative` item in the in-memory mapping.

      :param id: The id of the item to update.
      :type id: int
      :param name: The alternative name.
      :type name: str
      :param description: The alternative description.
      :type description: str, optional

      :returns: The updated item or None if nothing was updated.
      :rtype: :class:`PublicItem` or None



   .. py:method:: update_scenario(**kwargs)

      Updates a `scenario` item in the in-memory mapping.

      :param id: The id of the item to update.
      :type id: int
      :param name: The scenario name.
      :type name: str
      :param description: The scenario description.
      :type description: str, optional
      :param active: Not in use at the moment.
      :type active: bool, optional

      :returns: The updated item or None if nothing was updated.
      :rtype: :class:`PublicItem` or None



   .. py:method:: update_scenario_alternative(**kwargs)

      Updates a `scenario_alternative` item in the in-memory mapping.

      :param id: The id of the item to update.
      :type id: int
      :param scenario_name: The scenario name.
      :type scenario_name: str
      :param alternative_name: The alternative name.
      :type alternative_name: str
      :param rank: The rank - higher has precedence.
      :type rank: int

      :returns: The updated item or None if nothing was updated.
      :rtype: :class:`PublicItem` or None



   .. py:method:: update_entity_class(**kwargs)

      Updates an `entity_class` item in the in-memory mapping.

      :param id: The id of the item to update.
      :type id: int
      :param name: The class name.
      :type name: str
      :param dimension_name_list: The dimension names for a multi-dimensional class.
      :type dimension_name_list: tuple, optional
      :param entity_class_byname: A tuple with the class name as single element if the class is 0-dimensional, or the 0-dimensional class names if it is multi-dimensional.
      :type entity_class_byname: tuple
      :param description: The class description.
      :type description: str, optional
      :param display_icon: An integer representing an icon within your application.
      :type display_icon: int, optional
      :param display_order: Not in use at the moment.
      :type display_order: int, optional
      :param hidden: Not in use at the moment.
      :type hidden: int, optional
      :param active_by_default: Default activity for the entity alternatives of the class.
      :type active_by_default: bool, optional

      :returns: The updated item or None if nothing was updated.
      :rtype: :class:`PublicItem` or None



   .. py:method:: update_display_mode(**kwargs)

      Updates a `display_mode` item in the in-memory mapping.

      :param id: The id of the item to update.
      :type id: int
      :param name: The display mode name.
      :type name: str
      :param description: The display mode description.
      :type description: str, optional

      :returns: The updated item or None if nothing was updated.
      :rtype: :class:`PublicItem` or None



   .. py:method:: update_entity_class_display_mode(**kwargs)

      Updates an `entity_class_display_mode` item in the in-memory mapping.

      :param id: The id of the item to update.
      :type id: int
      :param entity_class_name: The entity class name.
      :type entity_class_name: str
      :param display_mode_name: The display mode name.
      :type display_mode_name: int
      :param display_order: The display order.
      :type display_order: int
      :param display_status: The display status; one of 'visible', 'hidden' or 'greyed_out'.
      :type display_status: str
      :param display_font_color: The color of the font.
      :type display_font_color: str, optional
      :param display_background_color: The  color of the background.
      :type display_background_color: str, optional

      :returns: The updated item or None if nothing was updated.
      :rtype: :class:`PublicItem` or None



   .. py:method:: update_superclass_subclass(**kwargs)

      Updates a `superclass_subclass` item in the in-memory mapping.

      :param id: The id of the item to update.
      :type id: int
      :param superclass_name: The superclass name.
      :type superclass_name: str
      :param subclass_name: The subclass name.
      :type subclass_name: str

      :returns: The updated item or None if nothing was updated.
      :rtype: :class:`PublicItem` or None



   .. py:method:: update_entity(**kwargs)

      Updates an `entity` item in the in-memory mapping.

      :param id: The id of the item to update.
      :type id: int
      :param entity_class_name: The entity class name.
      :type entity_class_name: str
      :param name: The entity name.
      :type name: str
      :param element_name_list: The element names if the entity is multi-dimensional.
      :type element_name_list: tuple
      :param entity_byname: A tuple with the entity name as single element if the entity is 0-dimensional, or the 0-dimensional element names if it is multi-dimensional.
      :type entity_byname: tuple
      :param description: The entity description.
      :type description: str, optional
      :param lat: The latitude of entity.
      :type lat: float, optional
      :param lon: The longitude of entity.
      :type lon: float, optional
      :param alt: The altitude of entity.
      :type alt: float, optional
      :param shape_name: The name of the entity's shape.
      :type shape_name: str, optional
      :param shape_blob: The shape as GEOJSON string.
      :type shape_blob: str, optional

      :returns: The updated item or None if nothing was updated.
      :rtype: :class:`PublicItem` or None



   .. py:method:: update_entity_group(**kwargs)

      Updates an `entity_group` item in the in-memory mapping.

      :param id: The id of the item to update.
      :type id: int
      :param entity_class_name: The entity class name.
      :type entity_class_name: str
      :param group_name: The group entity name.
      :type group_name: str
      :param member_name: The member entity name.
      :type member_name: str

      :returns: The updated item or None if nothing was updated.
      :rtype: :class:`PublicItem` or None



   .. py:method:: update_entity_alternative(**kwargs)

      Updates an `entity_alternative` item in the in-memory mapping.

      :param id: The id of the item to update.
      :type id: int
      :param entity_class_name: The entity class name.
      :type entity_class_name: str
      :param entity_byname: A tuple with the entity name as single element if the entity is 0-dimensional, or the 0-dimensional element names if it is multi-dimensional.
      :type entity_byname: tuple
      :param alternative_name: The alternative name.
      :type alternative_name: str
      :param active: Whether the entity is active in the alternative - defaults to True.
      :type active: bool, optional

      :returns: The updated item or None if nothing was updated.
      :rtype: :class:`PublicItem` or None



   .. py:method:: update_parameter_value_list(**kwargs)

      Updates a `parameter_value_list` item in the in-memory mapping.

      :param id: The id of the item to update.
      :type id: int
      :param name: The parameter value list name.
      :type name: str

      :returns: The updated item or None if nothing was updated.
      :rtype: :class:`PublicItem` or None



   .. py:method:: update_list_value(**kwargs)

      Updates a `list_value` item in the in-memory mapping.

      :param id: The id of the item to update.
      :type id: int
      :param parameter_value_list_name: The parameter value list name.
      :type parameter_value_list_name: str
      :param value: The value's database representation.
      :type value: bytes
      :param type: The value's type.
      :type type: str, optional
      :param parsed_value: The value.
      :type parsed_value: ParameterValue, optional
      :param index: The value index.
      :type index: int, optional

      :returns: The updated item or None if nothing was updated.
      :rtype: :class:`PublicItem` or None



   .. py:method:: update_parameter_type(**kwargs)

      Updates a `parameter_type` item in the in-memory mapping.

      :param id: The id of the item to update.
      :type id: int
      :param entity_class_name: The entity class name.
      :type entity_class_name: str
      :param parameter_definition_name: The parameter name.
      :type parameter_definition_name: str
      :param rank: The rank of the type.
      :type rank: int
      :param type: The value type.
      :type type: str

      :returns: The updated item or None if nothing was updated.
      :rtype: :class:`PublicItem` or None



   .. py:method:: update_parameter_group(**kwargs)

      Updates a `parameter_group` item in the in-memory mapping.

      :param id: The id of the item to update.
      :type id: int
      :param name: The parameter group name.
      :type name: str
      :param color: Group's color as HEX.
      :type color: str
      :param priority: Group's priority.
      :type priority: int

      :returns: The updated item or None if nothing was updated.
      :rtype: :class:`PublicItem` or None



   .. py:method:: update_parameter_definition(**kwargs)

      Updates a `parameter_definition` item in the in-memory mapping.

      :param id: The id of the item to update.
      :type id: int
      :param entity_class_name: The entity class name.
      :type entity_class_name: str
      :param name: The parameter name.
      :type name: str
      :param parameter_group_name: The name of the group of the parameter.
      :type parameter_group_name: str, optional
      :param parameter_type_list: List of valid value types.
      :type parameter_type_list: tuple, optional
      :param default_value: The default value's database representation.
      :type default_value: bytes, optional
      :param default_type: The default value's type.
      :type default_type: str, optional
      :param parsed_value: The default value.
      :type parsed_value: ParameterValue, optional
      :param parameter_value_list_name: The parameter value list name if any.
      :type parameter_value_list_name: str, optional
      :param description: The parameter description.
      :type description: str, optional

      :returns: The updated item or None if nothing was updated.
      :rtype: :class:`PublicItem` or None



   .. py:method:: update_parameter_value(**kwargs)

      Updates a `parameter_value` item in the in-memory mapping.

      :param id: The id of the item to update.
      :type id: int
      :param entity_class_name: The entity class name.
      :type entity_class_name: str
      :param parameter_definition_name: The parameter name.
      :type parameter_definition_name: str
      :param entity_byname: A tuple with the entity name as single element if the entity is 0-dimensional, or the 0-dimensional element names if it is multi-dimensional.
      :type entity_byname: tuple
      :param value: The value's database representation.
      :type value: bytes
      :param type: The value's type. Optional only when value is null.
      :type type: str, optional
      :param parsed_value: The value.
      :type parsed_value: ParameterValue, optional
      :param alternative_name: The alternative name - defaults to 'Base'.
      :type alternative_name: str, optional

      :returns: The updated item or None if nothing was updated.
      :rtype: :class:`PublicItem` or None



   .. py:method:: update_metadata(**kwargs)

      Updates a `metadata` item in the in-memory mapping.

      :param id: The id of the item to update.
      :type id: int
      :param name: The metadata entry name.
      :type name: str
      :param value: The metadata entry value.
      :type value: str

      :returns: The updated item or None if nothing was updated.
      :rtype: :class:`PublicItem` or None



   .. py:method:: update_entity_metadata(**kwargs)

      Updates an `entity_metadata` item in the in-memory mapping.

      :param id: The id of the item to update.
      :type id: int
      :param entity_class_name: The entity class name.
      :type entity_class_name: str
      :param entity_byname: A tuple with the entity name as single element if the entity is 0-dimensional, or the 0-dimensional element names if it is multi-dimensional.
      :type entity_byname: tuple
      :param metadata_name: The metadata entry name.
      :type metadata_name: str
      :param metadata_value: The metadata entry value.
      :type metadata_value: str

      :returns: The updated item or None if nothing was updated.
      :rtype: :class:`PublicItem` or None



   .. py:method:: update_parameter_value_metadata(**kwargs)

      Updates a `parameter_value_metadata` item in the in-memory mapping.

      :param id: The id of the item to update.
      :type id: int
      :param entity_class_name: The entity class name.
      :type entity_class_name: str
      :param parameter_definition_name: The parameter name.
      :type parameter_definition_name: str
      :param entity_byname: A tuple with the entity name as single element if the entity is 0-dimensional, or the 0-dimensional element names if it is multi-dimensional.
      :type entity_byname: tuple
      :param alternative_name: The alternative name.
      :type alternative_name: str
      :param metadata_name: The metadata entry name.
      :type metadata_name: str
      :param metadata_value: The metadata entry value.
      :type metadata_value: str

      :returns: The updated item or None if nothing was updated.
      :rtype: :class:`PublicItem` or None



   .. py:method:: update_entity_location(**kwargs)

      Updates an `entity_location` item in the in-memory mapping.

      :param id: The id of the item to update.
      :type id: int
      :param entity_class_name: The entity class name.
      :type entity_class_name: str
      :param entity_byname: A tuple with the entity name as single element if the entity is 0-dimensional, or the 0-dimensional element names if it is multi-dimensional.
      :type entity_byname: tuple
      :param lat: Latitude.
      :type lat: float, optional
      :param lon: Longitude.
      :type lon: float, optional
      :param alt: Altitude.
      :type alt: float, optional
      :param shape_name: Name identifying the shape.
      :type shape_name: str, optional
      :param shape_blob: Shape as GEOJSON feature.
      :type shape_blob: str, optional

      :returns: The updated item or None if nothing was updated.
      :rtype: :class:`PublicItem` or None



   .. py:method:: update_alternatives(items)

      Updates multiple `alternative` items in the in-memory mapping.

      :param items: items to update
      :type items: list of dict



   .. py:method:: update_scenarios(items)

      Updates multiple `scenario` items in the in-memory mapping.

      :param items: items to update
      :type items: list of dict



   .. py:method:: update_scenario_alternatives(items)

      Updates multiple `scenario_alternative` items in the in-memory mapping.

      :param items: items to update
      :type items: list of dict



   .. py:method:: update_entity_classes(items)

      Updates multiple `entity_class` items in the in-memory mapping.

      :param items: items to update
      :type items: list of dict



   .. py:method:: update_display_modes(items)

      Updates multiple `display_mode` items in the in-memory mapping.

      :param items: items to update
      :type items: list of dict



   .. py:method:: update_entity_class_display_modes(items)

      Updates multiple `entity_class_display_mode` items in the in-memory mapping.

      :param items: items to update
      :type items: list of dict



   .. py:method:: update_superclass_subclasses(items)

      Updates multiple `superclass_subclass` items in the in-memory mapping.

      :param items: items to update
      :type items: list of dict



   .. py:method:: update_entities(items)

      Updates multiple `entity` items in the in-memory mapping.

      :param items: items to update
      :type items: list of dict



   .. py:method:: update_entity_groups(items)

      Updates multiple `entity_group` items in the in-memory mapping.

      :param items: items to update
      :type items: list of dict



   .. py:method:: update_entity_alternatives(items)

      Updates multiple `entity_alternative` items in the in-memory mapping.

      :param items: items to update
      :type items: list of dict



   .. py:method:: update_parameter_value_lists(items)

      Updates multiple `parameter_value_list` items in the in-memory mapping.

      :param items: items to update
      :type items: list of dict



   .. py:method:: update_list_values(items)

      Updates multiple `list_value` items in the in-memory mapping.

      :param items: items to update
      :type items: list of dict



   .. py:method:: update_parameter_types(items)

      Updates multiple `parameter_type` items in the in-memory mapping.

      :param items: items to update
      :type items: list of dict



   .. py:method:: update_parameter_groups(items)

      Updates multiple `parameter_group` items in the in-memory mapping.

      :param items: items to update
      :type items: list of dict



   .. py:method:: update_parameter_definitions(items)

      Updates multiple `parameter_definition` items in the in-memory mapping.

      :param items: items to update
      :type items: list of dict



   .. py:method:: update_parameter_values(items)

      Updates multiple `parameter_value` items in the in-memory mapping.

      :param items: items to update
      :type items: list of dict



   .. py:method:: update_metadata_items(items)

      Updates multiple `metadata` items in the in-memory mapping.

      :param items: items to update
      :type items: list of dict



   .. py:method:: update_entity_metadata_items(items)

      Updates multiple `entity_metadata` items in the in-memory mapping.

      :param items: items to update
      :type items: list of dict



   .. py:method:: update_parameter_value_metadata_items(items)

      Updates multiple `parameter_value_metadata` items in the in-memory mapping.

      :param items: items to update
      :type items: list of dict



   .. py:method:: update_entity_locations(items)

      Updates multiple `entity_location` items in the in-memory mapping.

      :param items: items to update
      :type items: list of dict



   .. py:method:: add_or_update_alternative(**kwargs)

      Adds an `alternative` item to the in-memory mapping if it doesn't exist;
      otherwise updates the current one.

      :param name: The alternative name.
      :type name: str
      :param description: The alternative description.
      :type description: str, optional

      :returns: The added or updated item or None if nothing was added or updated.
      :rtype: :class:`PublicItem` or None



   .. py:method:: add_or_update_scenario(**kwargs)

      Adds a `scenario` item to the in-memory mapping if it doesn't exist;
      otherwise updates the current one.

      :param name: The scenario name.
      :type name: str
      :param description: The scenario description.
      :type description: str, optional
      :param active: Not in use at the moment.
      :type active: bool, optional

      :returns: The added or updated item or None if nothing was added or updated.
      :rtype: :class:`PublicItem` or None



   .. py:method:: add_or_update_scenario_alternative(**kwargs)

      Adds a `scenario_alternative` item to the in-memory mapping if it doesn't exist;
      otherwise updates the current one.

      :param scenario_name: The scenario name.
      :type scenario_name: str
      :param alternative_name: The alternative name.
      :type alternative_name: str
      :param rank: The rank - higher has precedence.
      :type rank: int

      :returns: The added or updated item or None if nothing was added or updated.
      :rtype: :class:`PublicItem` or None



   .. py:method:: add_or_update_entity_class(**kwargs)

      Adds an `entity_class` item to the in-memory mapping if it doesn't exist;
      otherwise updates the current one.

      :param name: The class name.
      :type name: str
      :param dimension_name_list: The dimension names for a multi-dimensional class.
      :type dimension_name_list: tuple, optional
      :param entity_class_byname: A tuple with the class name as single element if the class is 0-dimensional, or the 0-dimensional class names if it is multi-dimensional.
      :type entity_class_byname: tuple
      :param description: The class description.
      :type description: str, optional
      :param display_icon: An integer representing an icon within your application.
      :type display_icon: int, optional
      :param display_order: Not in use at the moment.
      :type display_order: int, optional
      :param hidden: Not in use at the moment.
      :type hidden: int, optional
      :param active_by_default: Default activity for the entity alternatives of the class.
      :type active_by_default: bool, optional

      :returns: The added or updated item or None if nothing was added or updated.
      :rtype: :class:`PublicItem` or None



   .. py:method:: add_or_update_display_mode(**kwargs)

      Adds a `display_mode` item to the in-memory mapping if it doesn't exist;
      otherwise updates the current one.

      :param name: The display mode name.
      :type name: str
      :param description: The display mode description.
      :type description: str, optional

      :returns: The added or updated item or None if nothing was added or updated.
      :rtype: :class:`PublicItem` or None



   .. py:method:: add_or_update_entity_class_display_mode(**kwargs)

      Adds an `entity_class_display_mode` item to the in-memory mapping if it doesn't exist;
      otherwise updates the current one.

      :param entity_class_name: The entity class name.
      :type entity_class_name: str
      :param display_mode_name: The display mode name.
      :type display_mode_name: int
      :param display_order: The display order.
      :type display_order: int
      :param display_status: The display status; one of 'visible', 'hidden' or 'greyed_out'.
      :type display_status: str
      :param display_font_color: The color of the font.
      :type display_font_color: str, optional
      :param display_background_color: The  color of the background.
      :type display_background_color: str, optional

      :returns: The added or updated item or None if nothing was added or updated.
      :rtype: :class:`PublicItem` or None



   .. py:method:: add_or_update_superclass_subclass(**kwargs)

      Adds a `superclass_subclass` item to the in-memory mapping if it doesn't exist;
      otherwise updates the current one.

      :param superclass_name: The superclass name.
      :type superclass_name: str
      :param subclass_name: The subclass name.
      :type subclass_name: str

      :returns: The added or updated item or None if nothing was added or updated.
      :rtype: :class:`PublicItem` or None



   .. py:method:: add_or_update_entity(**kwargs)

      Adds an `entity` item to the in-memory mapping if it doesn't exist;
      otherwise updates the current one.

      :param entity_class_name: The entity class name.
      :type entity_class_name: str
      :param name: The entity name.
      :type name: str
      :param element_name_list: The element names if the entity is multi-dimensional.
      :type element_name_list: tuple
      :param entity_byname: A tuple with the entity name as single element if the entity is 0-dimensional, or the 0-dimensional element names if it is multi-dimensional.
      :type entity_byname: tuple
      :param description: The entity description.
      :type description: str, optional
      :param lat: The latitude of entity.
      :type lat: float, optional
      :param lon: The longitude of entity.
      :type lon: float, optional
      :param alt: The altitude of entity.
      :type alt: float, optional
      :param shape_name: The name of the entity's shape.
      :type shape_name: str, optional
      :param shape_blob: The shape as GEOJSON string.
      :type shape_blob: str, optional

      :returns: The added or updated item or None if nothing was added or updated.
      :rtype: :class:`PublicItem` or None



   .. py:method:: add_or_update_entity_group(**kwargs)

      Adds an `entity_group` item to the in-memory mapping if it doesn't exist;
      otherwise updates the current one.

      :param entity_class_name: The entity class name.
      :type entity_class_name: str
      :param group_name: The group entity name.
      :type group_name: str
      :param member_name: The member entity name.
      :type member_name: str

      :returns: The added or updated item or None if nothing was added or updated.
      :rtype: :class:`PublicItem` or None



   .. py:method:: add_or_update_entity_alternative(**kwargs)

      Adds an `entity_alternative` item to the in-memory mapping if it doesn't exist;
      otherwise updates the current one.

      :param entity_class_name: The entity class name.
      :type entity_class_name: str
      :param entity_byname: A tuple with the entity name as single element if the entity is 0-dimensional, or the 0-dimensional element names if it is multi-dimensional.
      :type entity_byname: tuple
      :param alternative_name: The alternative name.
      :type alternative_name: str
      :param active: Whether the entity is active in the alternative - defaults to True.
      :type active: bool, optional

      :returns: The added or updated item or None if nothing was added or updated.
      :rtype: :class:`PublicItem` or None



   .. py:method:: add_or_update_parameter_value_list(**kwargs)

      Adds a `parameter_value_list` item to the in-memory mapping if it doesn't exist;
      otherwise updates the current one.

      :param name: The parameter value list name.
      :type name: str

      :returns: The added or updated item or None if nothing was added or updated.
      :rtype: :class:`PublicItem` or None



   .. py:method:: add_or_update_list_value(**kwargs)

      Adds a `list_value` item to the in-memory mapping if it doesn't exist;
      otherwise updates the current one.

      :param parameter_value_list_name: The parameter value list name.
      :type parameter_value_list_name: str
      :param value: The value's database representation.
      :type value: bytes
      :param type: The value's type.
      :type type: str, optional
      :param parsed_value: The value.
      :type parsed_value: ParameterValue, optional
      :param index: The value index.
      :type index: int, optional

      :returns: The added or updated item or None if nothing was added or updated.
      :rtype: :class:`PublicItem` or None



   .. py:method:: add_or_update_parameter_type(**kwargs)

      Adds a `parameter_type` item to the in-memory mapping if it doesn't exist;
      otherwise updates the current one.

      :param entity_class_name: The entity class name.
      :type entity_class_name: str
      :param parameter_definition_name: The parameter name.
      :type parameter_definition_name: str
      :param rank: The rank of the type.
      :type rank: int
      :param type: The value type.
      :type type: str

      :returns: The added or updated item or None if nothing was added or updated.
      :rtype: :class:`PublicItem` or None



   .. py:method:: add_or_update_parameter_group(**kwargs)

      Adds a `parameter_group` item to the in-memory mapping if it doesn't exist;
      otherwise updates the current one.

      :param name: The parameter group name.
      :type name: str
      :param color: Group's color as HEX.
      :type color: str
      :param priority: Group's priority.
      :type priority: int

      :returns: The added or updated item or None if nothing was added or updated.
      :rtype: :class:`PublicItem` or None



   .. py:method:: add_or_update_parameter_definition(**kwargs)

      Adds a `parameter_definition` item to the in-memory mapping if it doesn't exist;
      otherwise updates the current one.

      :param entity_class_name: The entity class name.
      :type entity_class_name: str
      :param name: The parameter name.
      :type name: str
      :param parameter_group_name: The name of the group of the parameter.
      :type parameter_group_name: str, optional
      :param parameter_type_list: List of valid value types.
      :type parameter_type_list: tuple, optional
      :param default_value: The default value's database representation.
      :type default_value: bytes, optional
      :param default_type: The default value's type.
      :type default_type: str, optional
      :param parsed_value: The default value.
      :type parsed_value: ParameterValue, optional
      :param parameter_value_list_name: The parameter value list name if any.
      :type parameter_value_list_name: str, optional
      :param description: The parameter description.
      :type description: str, optional

      :returns: The added or updated item or None if nothing was added or updated.
      :rtype: :class:`PublicItem` or None



   .. py:method:: add_or_update_parameter_value(**kwargs)

      Adds a `parameter_value` item to the in-memory mapping if it doesn't exist;
      otherwise updates the current one.

      :param entity_class_name: The entity class name.
      :type entity_class_name: str
      :param parameter_definition_name: The parameter name.
      :type parameter_definition_name: str
      :param entity_byname: A tuple with the entity name as single element if the entity is 0-dimensional, or the 0-dimensional element names if it is multi-dimensional.
      :type entity_byname: tuple
      :param value: The value's database representation.
      :type value: bytes
      :param type: The value's type. Optional only when value is null.
      :type type: str, optional
      :param parsed_value: The value.
      :type parsed_value: ParameterValue, optional
      :param alternative_name: The alternative name - defaults to 'Base'.
      :type alternative_name: str, optional

      :returns: The added or updated item or None if nothing was added or updated.
      :rtype: :class:`PublicItem` or None



   .. py:method:: add_or_update_metadata(**kwargs)

      Adds a `metadata` item to the in-memory mapping if it doesn't exist;
      otherwise updates the current one.

      :param name: The metadata entry name.
      :type name: str
      :param value: The metadata entry value.
      :type value: str

      :returns: The added or updated item or None if nothing was added or updated.
      :rtype: :class:`PublicItem` or None



   .. py:method:: add_or_update_entity_metadata(**kwargs)

      Adds an `entity_metadata` item to the in-memory mapping if it doesn't exist;
      otherwise updates the current one.

      :param entity_class_name: The entity class name.
      :type entity_class_name: str
      :param entity_byname: A tuple with the entity name as single element if the entity is 0-dimensional, or the 0-dimensional element names if it is multi-dimensional.
      :type entity_byname: tuple
      :param metadata_name: The metadata entry name.
      :type metadata_name: str
      :param metadata_value: The metadata entry value.
      :type metadata_value: str

      :returns: The added or updated item or None if nothing was added or updated.
      :rtype: :class:`PublicItem` or None



   .. py:method:: add_or_update_parameter_value_metadata(**kwargs)

      Adds a `parameter_value_metadata` item to the in-memory mapping if it doesn't exist;
      otherwise updates the current one.

      :param entity_class_name: The entity class name.
      :type entity_class_name: str
      :param parameter_definition_name: The parameter name.
      :type parameter_definition_name: str
      :param entity_byname: A tuple with the entity name as single element if the entity is 0-dimensional, or the 0-dimensional element names if it is multi-dimensional.
      :type entity_byname: tuple
      :param alternative_name: The alternative name.
      :type alternative_name: str
      :param metadata_name: The metadata entry name.
      :type metadata_name: str
      :param metadata_value: The metadata entry value.
      :type metadata_value: str

      :returns: The added or updated item or None if nothing was added or updated.
      :rtype: :class:`PublicItem` or None



   .. py:method:: add_or_update_entity_location(**kwargs)

      Adds an `entity_location` item to the in-memory mapping if it doesn't exist;
      otherwise updates the current one.

      :param entity_class_name: The entity class name.
      :type entity_class_name: str
      :param entity_byname: A tuple with the entity name as single element if the entity is 0-dimensional, or the 0-dimensional element names if it is multi-dimensional.
      :type entity_byname: tuple
      :param lat: Latitude.
      :type lat: float, optional
      :param lon: Longitude.
      :type lon: float, optional
      :param alt: Altitude.
      :type alt: float, optional
      :param shape_name: Name identifying the shape.
      :type shape_name: str, optional
      :param shape_blob: Shape as GEOJSON feature.
      :type shape_blob: str, optional

      :returns: The added or updated item or None if nothing was added or updated.
      :rtype: :class:`PublicItem` or None



   .. py:method:: add_or_update_alternatives(items)

      Adds multiple `alternative` items to the in-memory mapping if they don't exist;
      otherwise updates the items.

      :param items: items to add or update
      :type items: list of dict



   .. py:method:: add_or_update_scenarios(items)

      Adds multiple `scenario` items to the in-memory mapping if they don't exist;
      otherwise updates the items.

      :param items: items to add or update
      :type items: list of dict



   .. py:method:: add_or_update_scenario_alternatives(items)

      Adds multiple `scenario_alternative` items to the in-memory mapping if they don't exist;
      otherwise updates the items.

      :param items: items to add or update
      :type items: list of dict



   .. py:method:: add_or_update_entity_classes(items)

      Adds multiple `entity_class` items to the in-memory mapping if they don't exist;
      otherwise updates the items.

      :param items: items to add or update
      :type items: list of dict



   .. py:method:: add_or_update_display_modes(items)

      Adds multiple `display_mode` items to the in-memory mapping if they don't exist;
      otherwise updates the items.

      :param items: items to add or update
      :type items: list of dict



   .. py:method:: add_or_update_entity_class_display_modes(items)

      Adds multiple `entity_class_display_mode` items to the in-memory mapping if they don't exist;
      otherwise updates the items.

      :param items: items to add or update
      :type items: list of dict



   .. py:method:: add_or_update_superclass_subclasses(items)

      Adds multiple `superclass_subclass` items to the in-memory mapping if they don't exist;
      otherwise updates the items.

      :param items: items to add or update
      :type items: list of dict



   .. py:method:: add_or_update_entities(items)

      Adds multiple `entity` items to the in-memory mapping if they don't exist;
      otherwise updates the items.

      :param items: items to add or update
      :type items: list of dict



   .. py:method:: add_or_update_entity_groups(items)

      Adds multiple `entity_group` items to the in-memory mapping if they don't exist;
      otherwise updates the items.

      :param items: items to add or update
      :type items: list of dict



   .. py:method:: add_or_update_entity_alternatives(items)

      Adds multiple `entity_alternative` items to the in-memory mapping if they don't exist;
      otherwise updates the items.

      :param items: items to add or update
      :type items: list of dict



   .. py:method:: add_or_update_parameter_value_lists(items)

      Adds multiple `parameter_value_list` items to the in-memory mapping if they don't exist;
      otherwise updates the items.

      :param items: items to add or update
      :type items: list of dict



   .. py:method:: add_or_update_list_values(items)

      Adds multiple `list_value` items to the in-memory mapping if they don't exist;
      otherwise updates the items.

      :param items: items to add or update
      :type items: list of dict



   .. py:method:: add_or_update_parameter_types(items)

      Adds multiple `parameter_type` items to the in-memory mapping if they don't exist;
      otherwise updates the items.

      :param items: items to add or update
      :type items: list of dict



   .. py:method:: add_or_update_parameter_groups(items)

      Adds multiple `parameter_group` items to the in-memory mapping if they don't exist;
      otherwise updates the items.

      :param items: items to add or update
      :type items: list of dict



   .. py:method:: add_or_update_parameter_definitions(items)

      Adds multiple `parameter_definition` items to the in-memory mapping if they don't exist;
      otherwise updates the items.

      :param items: items to add or update
      :type items: list of dict



   .. py:method:: add_or_update_parameter_values(items)

      Adds multiple `parameter_value` items to the in-memory mapping if they don't exist;
      otherwise updates the items.

      :param items: items to add or update
      :type items: list of dict



   .. py:method:: add_or_update_metadata_items(items)

      Adds multiple `metadata` items to the in-memory mapping if they don't exist;
      otherwise updates the items.

      :param items: items to add or update
      :type items: list of dict



   .. py:method:: add_or_update_entity_metadata_items(items)

      Adds multiple `entity_metadata` items to the in-memory mapping if they don't exist;
      otherwise updates the items.

      :param items: items to add or update
      :type items: list of dict



   .. py:method:: add_or_update_parameter_value_metadata_items(items)

      Adds multiple `parameter_value_metadata` items to the in-memory mapping if they don't exist;
      otherwise updates the items.

      :param items: items to add or update
      :type items: list of dict



   .. py:method:: add_or_update_entity_locations(items)

      Adds multiple `entity_location` items to the in-memory mapping if they don't exist;
      otherwise updates the items.

      :param items: items to add or update
      :type items: list of dict



   .. py:method:: remove_alternative(**kwargs)

      Removes an `alternative` item from the in-memory mapping.

      :param name: The alternative name.
      :type name: str
      :param description: The alternative description.
      :type description: str, optional



   .. py:method:: remove_scenario(**kwargs)

      Removes a `scenario` item from the in-memory mapping.

      :param name: The scenario name.
      :type name: str
      :param description: The scenario description.
      :type description: str, optional
      :param active: Not in use at the moment.
      :type active: bool, optional



   .. py:method:: remove_scenario_alternative(**kwargs)

      Removes a `scenario_alternative` item from the in-memory mapping.

      :param scenario_name: The scenario name.
      :type scenario_name: str
      :param alternative_name: The alternative name.
      :type alternative_name: str
      :param rank: The rank - higher has precedence.
      :type rank: int



   .. py:method:: remove_entity_class(**kwargs)

      Removes an `entity_class` item from the in-memory mapping.

      :param name: The class name.
      :type name: str
      :param dimension_name_list: The dimension names for a multi-dimensional class.
      :type dimension_name_list: tuple, optional
      :param entity_class_byname: A tuple with the class name as single element if the class is 0-dimensional, or the 0-dimensional class names if it is multi-dimensional.
      :type entity_class_byname: tuple
      :param description: The class description.
      :type description: str, optional
      :param display_icon: An integer representing an icon within your application.
      :type display_icon: int, optional
      :param display_order: Not in use at the moment.
      :type display_order: int, optional
      :param hidden: Not in use at the moment.
      :type hidden: int, optional
      :param active_by_default: Default activity for the entity alternatives of the class.
      :type active_by_default: bool, optional



   .. py:method:: remove_display_mode(**kwargs)

      Removes a `display_mode` item from the in-memory mapping.

      :param name: The display mode name.
      :type name: str
      :param description: The display mode description.
      :type description: str, optional



   .. py:method:: remove_entity_class_display_mode(**kwargs)

      Removes an `entity_class_display_mode` item from the in-memory mapping.

      :param entity_class_name: The entity class name.
      :type entity_class_name: str
      :param display_mode_name: The display mode name.
      :type display_mode_name: int
      :param display_order: The display order.
      :type display_order: int
      :param display_status: The display status; one of 'visible', 'hidden' or 'greyed_out'.
      :type display_status: str
      :param display_font_color: The color of the font.
      :type display_font_color: str, optional
      :param display_background_color: The  color of the background.
      :type display_background_color: str, optional



   .. py:method:: remove_superclass_subclass(**kwargs)

      Removes a `superclass_subclass` item from the in-memory mapping.

      :param superclass_name: The superclass name.
      :type superclass_name: str
      :param subclass_name: The subclass name.
      :type subclass_name: str



   .. py:method:: remove_entity(**kwargs)

      Removes an `entity` item from the in-memory mapping.

      :param entity_class_name: The entity class name.
      :type entity_class_name: str
      :param name: The entity name.
      :type name: str
      :param element_name_list: The element names if the entity is multi-dimensional.
      :type element_name_list: tuple
      :param entity_byname: A tuple with the entity name as single element if the entity is 0-dimensional, or the 0-dimensional element names if it is multi-dimensional.
      :type entity_byname: tuple
      :param description: The entity description.
      :type description: str, optional
      :param lat: The latitude of entity.
      :type lat: float, optional
      :param lon: The longitude of entity.
      :type lon: float, optional
      :param alt: The altitude of entity.
      :type alt: float, optional
      :param shape_name: The name of the entity's shape.
      :type shape_name: str, optional
      :param shape_blob: The shape as GEOJSON string.
      :type shape_blob: str, optional



   .. py:method:: remove_entity_group(**kwargs)

      Removes an `entity_group` item from the in-memory mapping.

      :param entity_class_name: The entity class name.
      :type entity_class_name: str
      :param group_name: The group entity name.
      :type group_name: str
      :param member_name: The member entity name.
      :type member_name: str



   .. py:method:: remove_entity_alternative(**kwargs)

      Removes an `entity_alternative` item from the in-memory mapping.

      :param entity_class_name: The entity class name.
      :type entity_class_name: str
      :param entity_byname: A tuple with the entity name as single element if the entity is 0-dimensional, or the 0-dimensional element names if it is multi-dimensional.
      :type entity_byname: tuple
      :param alternative_name: The alternative name.
      :type alternative_name: str
      :param active: Whether the entity is active in the alternative - defaults to True.
      :type active: bool, optional



   .. py:method:: remove_parameter_value_list(**kwargs)

      Removes a `parameter_value_list` item from the in-memory mapping.

      :param name: The parameter value list name.
      :type name: str



   .. py:method:: remove_list_value(**kwargs)

      Removes a `list_value` item from the in-memory mapping.

      :param parameter_value_list_name: The parameter value list name.
      :type parameter_value_list_name: str
      :param value: The value's database representation.
      :type value: bytes
      :param type: The value's type.
      :type type: str, optional
      :param parsed_value: The value.
      :type parsed_value: ParameterValue, optional
      :param index: The value index.
      :type index: int, optional



   .. py:method:: remove_parameter_type(**kwargs)

      Removes a `parameter_type` item from the in-memory mapping.

      :param entity_class_name: The entity class name.
      :type entity_class_name: str
      :param parameter_definition_name: The parameter name.
      :type parameter_definition_name: str
      :param rank: The rank of the type.
      :type rank: int
      :param type: The value type.
      :type type: str



   .. py:method:: remove_parameter_group(**kwargs)

      Removes a `parameter_group` item from the in-memory mapping.

      :param name: The parameter group name.
      :type name: str
      :param color: Group's color as HEX.
      :type color: str
      :param priority: Group's priority.
      :type priority: int



   .. py:method:: remove_parameter_definition(**kwargs)

      Removes a `parameter_definition` item from the in-memory mapping.

      :param entity_class_name: The entity class name.
      :type entity_class_name: str
      :param name: The parameter name.
      :type name: str
      :param parameter_group_name: The name of the group of the parameter.
      :type parameter_group_name: str, optional
      :param parameter_type_list: List of valid value types.
      :type parameter_type_list: tuple, optional
      :param default_value: The default value's database representation.
      :type default_value: bytes, optional
      :param default_type: The default value's type.
      :type default_type: str, optional
      :param parsed_value: The default value.
      :type parsed_value: ParameterValue, optional
      :param parameter_value_list_name: The parameter value list name if any.
      :type parameter_value_list_name: str, optional
      :param description: The parameter description.
      :type description: str, optional



   .. py:method:: remove_parameter_value(**kwargs)

      Removes a `parameter_value` item from the in-memory mapping.

      :param entity_class_name: The entity class name.
      :type entity_class_name: str
      :param parameter_definition_name: The parameter name.
      :type parameter_definition_name: str
      :param entity_byname: A tuple with the entity name as single element if the entity is 0-dimensional, or the 0-dimensional element names if it is multi-dimensional.
      :type entity_byname: tuple
      :param value: The value's database representation.
      :type value: bytes
      :param type: The value's type. Optional only when value is null.
      :type type: str, optional
      :param parsed_value: The value.
      :type parsed_value: ParameterValue, optional
      :param alternative_name: The alternative name - defaults to 'Base'.
      :type alternative_name: str, optional



   .. py:method:: remove_metadata(**kwargs)

      Removes a `metadata` item from the in-memory mapping.

      :param name: The metadata entry name.
      :type name: str
      :param value: The metadata entry value.
      :type value: str



   .. py:method:: remove_entity_metadata(**kwargs)

      Removes an `entity_metadata` item from the in-memory mapping.

      :param entity_class_name: The entity class name.
      :type entity_class_name: str
      :param entity_byname: A tuple with the entity name as single element if the entity is 0-dimensional, or the 0-dimensional element names if it is multi-dimensional.
      :type entity_byname: tuple
      :param metadata_name: The metadata entry name.
      :type metadata_name: str
      :param metadata_value: The metadata entry value.
      :type metadata_value: str



   .. py:method:: remove_parameter_value_metadata(**kwargs)

      Removes a `parameter_value_metadata` item from the in-memory mapping.

      :param entity_class_name: The entity class name.
      :type entity_class_name: str
      :param parameter_definition_name: The parameter name.
      :type parameter_definition_name: str
      :param entity_byname: A tuple with the entity name as single element if the entity is 0-dimensional, or the 0-dimensional element names if it is multi-dimensional.
      :type entity_byname: tuple
      :param alternative_name: The alternative name.
      :type alternative_name: str
      :param metadata_name: The metadata entry name.
      :type metadata_name: str
      :param metadata_value: The metadata entry value.
      :type metadata_value: str



   .. py:method:: remove_entity_location(**kwargs)

      Removes an `entity_location` item from the in-memory mapping.

      :param entity_class_name: The entity class name.
      :type entity_class_name: str
      :param entity_byname: A tuple with the entity name as single element if the entity is 0-dimensional, or the 0-dimensional element names if it is multi-dimensional.
      :type entity_byname: tuple
      :param lat: Latitude.
      :type lat: float, optional
      :param lon: Longitude.
      :type lon: float, optional
      :param alt: Altitude.
      :type alt: float, optional
      :param shape_name: Name identifying the shape.
      :type shape_name: str, optional
      :param shape_blob: Shape as GEOJSON feature.
      :type shape_blob: str, optional



   .. py:method:: remove_alternatives(items)

      Removes multiple `alternative` items from the in-memory mapping.

      :param items: items to remove
      :type items: list of dict



   .. py:method:: remove_scenarios(items)

      Removes multiple `scenario` items from the in-memory mapping.

      :param items: items to remove
      :type items: list of dict



   .. py:method:: remove_scenario_alternatives(items)

      Removes multiple `scenario_alternative` items from the in-memory mapping.

      :param items: items to remove
      :type items: list of dict



   .. py:method:: remove_entity_classes(items)

      Removes multiple `entity_class` items from the in-memory mapping.

      :param items: items to remove
      :type items: list of dict



   .. py:method:: remove_display_modes(items)

      Removes multiple `display_mode` items from the in-memory mapping.

      :param items: items to remove
      :type items: list of dict



   .. py:method:: remove_entity_class_display_modes(items)

      Removes multiple `entity_class_display_mode` items from the in-memory mapping.

      :param items: items to remove
      :type items: list of dict



   .. py:method:: remove_superclass_subclasses(items)

      Removes multiple `superclass_subclass` items from the in-memory mapping.

      :param items: items to remove
      :type items: list of dict



   .. py:method:: remove_entities(items)

      Removes multiple `entity` items from the in-memory mapping.

      :param items: items to remove
      :type items: list of dict



   .. py:method:: remove_entity_groups(items)

      Removes multiple `entity_group` items from the in-memory mapping.

      :param items: items to remove
      :type items: list of dict



   .. py:method:: remove_entity_alternatives(items)

      Removes multiple `entity_alternative` items from the in-memory mapping.

      :param items: items to remove
      :type items: list of dict



   .. py:method:: remove_parameter_value_lists(items)

      Removes multiple `parameter_value_list` items from the in-memory mapping.

      :param items: items to remove
      :type items: list of dict



   .. py:method:: remove_list_values(items)

      Removes multiple `list_value` items from the in-memory mapping.

      :param items: items to remove
      :type items: list of dict



   .. py:method:: remove_parameter_types(items)

      Removes multiple `parameter_type` items from the in-memory mapping.

      :param items: items to remove
      :type items: list of dict



   .. py:method:: remove_parameter_groups(items)

      Removes multiple `parameter_group` items from the in-memory mapping.

      :param items: items to remove
      :type items: list of dict



   .. py:method:: remove_parameter_definitions(items)

      Removes multiple `parameter_definition` items from the in-memory mapping.

      :param items: items to remove
      :type items: list of dict



   .. py:method:: remove_parameter_values(items)

      Removes multiple `parameter_value` items from the in-memory mapping.

      :param items: items to remove
      :type items: list of dict



   .. py:method:: remove_metadata_items(items)

      Removes multiple `metadata` items from the in-memory mapping.

      :param items: items to remove
      :type items: list of dict



   .. py:method:: remove_entity_metadata_items(items)

      Removes multiple `entity_metadata` items from the in-memory mapping.

      :param items: items to remove
      :type items: list of dict



   .. py:method:: remove_parameter_value_metadata_items(items)

      Removes multiple `parameter_value_metadata` items from the in-memory mapping.

      :param items: items to remove
      :type items: list of dict



   .. py:method:: remove_entity_locations(items)

      Removes multiple `entity_location` items from the in-memory mapping.

      :param items: items to remove
      :type items: list of dict



   .. py:method:: restore_alternative(**kwargs)

      Restores a previously removed `alternative` item into the in-memory mapping.

      :param name: The alternative name.
      :type name: str
      :param description: The alternative description.
      :type description: str, optional

      :returns: The restored item.
      :rtype: :class:`PublicItem`



   .. py:method:: restore_scenario(**kwargs)

      Restores a previously removed `scenario` item into the in-memory mapping.

      :param name: The scenario name.
      :type name: str
      :param description: The scenario description.
      :type description: str, optional
      :param active: Not in use at the moment.
      :type active: bool, optional

      :returns: The restored item.
      :rtype: :class:`PublicItem`



   .. py:method:: restore_scenario_alternative(**kwargs)

      Restores a previously removed `scenario_alternative` item into the in-memory mapping.

      :param scenario_name: The scenario name.
      :type scenario_name: str
      :param alternative_name: The alternative name.
      :type alternative_name: str
      :param rank: The rank - higher has precedence.
      :type rank: int

      :returns: The restored item.
      :rtype: :class:`PublicItem`



   .. py:method:: restore_entity_class(**kwargs)

      Restores a previously removed `entity_class` item into the in-memory mapping.

      :param name: The class name.
      :type name: str
      :param dimension_name_list: The dimension names for a multi-dimensional class.
      :type dimension_name_list: tuple, optional
      :param entity_class_byname: A tuple with the class name as single element if the class is 0-dimensional, or the 0-dimensional class names if it is multi-dimensional.
      :type entity_class_byname: tuple
      :param description: The class description.
      :type description: str, optional
      :param display_icon: An integer representing an icon within your application.
      :type display_icon: int, optional
      :param display_order: Not in use at the moment.
      :type display_order: int, optional
      :param hidden: Not in use at the moment.
      :type hidden: int, optional
      :param active_by_default: Default activity for the entity alternatives of the class.
      :type active_by_default: bool, optional

      :returns: The restored item.
      :rtype: :class:`PublicItem`



   .. py:method:: restore_display_mode(**kwargs)

      Restores a previously removed `display_mode` item into the in-memory mapping.

      :param name: The display mode name.
      :type name: str
      :param description: The display mode description.
      :type description: str, optional

      :returns: The restored item.
      :rtype: :class:`PublicItem`



   .. py:method:: restore_entity_class_display_mode(**kwargs)

      Restores a previously removed `entity_class_display_mode` item into the in-memory mapping.

      :param entity_class_name: The entity class name.
      :type entity_class_name: str
      :param display_mode_name: The display mode name.
      :type display_mode_name: int
      :param display_order: The display order.
      :type display_order: int
      :param display_status: The display status; one of 'visible', 'hidden' or 'greyed_out'.
      :type display_status: str
      :param display_font_color: The color of the font.
      :type display_font_color: str, optional
      :param display_background_color: The  color of the background.
      :type display_background_color: str, optional

      :returns: The restored item.
      :rtype: :class:`PublicItem`



   .. py:method:: restore_superclass_subclass(**kwargs)

      Restores a previously removed `superclass_subclass` item into the in-memory mapping.

      :param superclass_name: The superclass name.
      :type superclass_name: str
      :param subclass_name: The subclass name.
      :type subclass_name: str

      :returns: The restored item.
      :rtype: :class:`PublicItem`



   .. py:method:: restore_entity(**kwargs)

      Restores a previously removed `entity` item into the in-memory mapping.

      :param entity_class_name: The entity class name.
      :type entity_class_name: str
      :param name: The entity name.
      :type name: str
      :param element_name_list: The element names if the entity is multi-dimensional.
      :type element_name_list: tuple
      :param entity_byname: A tuple with the entity name as single element if the entity is 0-dimensional, or the 0-dimensional element names if it is multi-dimensional.
      :type entity_byname: tuple
      :param description: The entity description.
      :type description: str, optional
      :param lat: The latitude of entity.
      :type lat: float, optional
      :param lon: The longitude of entity.
      :type lon: float, optional
      :param alt: The altitude of entity.
      :type alt: float, optional
      :param shape_name: The name of the entity's shape.
      :type shape_name: str, optional
      :param shape_blob: The shape as GEOJSON string.
      :type shape_blob: str, optional

      :returns: The restored item.
      :rtype: :class:`PublicItem`



   .. py:method:: restore_entity_group(**kwargs)

      Restores a previously removed `entity_group` item into the in-memory mapping.

      :param entity_class_name: The entity class name.
      :type entity_class_name: str
      :param group_name: The group entity name.
      :type group_name: str
      :param member_name: The member entity name.
      :type member_name: str

      :returns: The restored item.
      :rtype: :class:`PublicItem`



   .. py:method:: restore_entity_alternative(**kwargs)

      Restores a previously removed `entity_alternative` item into the in-memory mapping.

      :param entity_class_name: The entity class name.
      :type entity_class_name: str
      :param entity_byname: A tuple with the entity name as single element if the entity is 0-dimensional, or the 0-dimensional element names if it is multi-dimensional.
      :type entity_byname: tuple
      :param alternative_name: The alternative name.
      :type alternative_name: str
      :param active: Whether the entity is active in the alternative - defaults to True.
      :type active: bool, optional

      :returns: The restored item.
      :rtype: :class:`PublicItem`



   .. py:method:: restore_parameter_value_list(**kwargs)

      Restores a previously removed `parameter_value_list` item into the in-memory mapping.

      :param name: The parameter value list name.
      :type name: str

      :returns: The restored item.
      :rtype: :class:`PublicItem`



   .. py:method:: restore_list_value(**kwargs)

      Restores a previously removed `list_value` item into the in-memory mapping.

      :param parameter_value_list_name: The parameter value list name.
      :type parameter_value_list_name: str
      :param value: The value's database representation.
      :type value: bytes
      :param type: The value's type.
      :type type: str, optional
      :param parsed_value: The value.
      :type parsed_value: ParameterValue, optional
      :param index: The value index.
      :type index: int, optional

      :returns: The restored item.
      :rtype: :class:`PublicItem`



   .. py:method:: restore_parameter_type(**kwargs)

      Restores a previously removed `parameter_type` item into the in-memory mapping.

      :param entity_class_name: The entity class name.
      :type entity_class_name: str
      :param parameter_definition_name: The parameter name.
      :type parameter_definition_name: str
      :param rank: The rank of the type.
      :type rank: int
      :param type: The value type.
      :type type: str

      :returns: The restored item.
      :rtype: :class:`PublicItem`



   .. py:method:: restore_parameter_group(**kwargs)

      Restores a previously removed `parameter_group` item into the in-memory mapping.

      :param name: The parameter group name.
      :type name: str
      :param color: Group's color as HEX.
      :type color: str
      :param priority: Group's priority.
      :type priority: int

      :returns: The restored item.
      :rtype: :class:`PublicItem`



   .. py:method:: restore_parameter_definition(**kwargs)

      Restores a previously removed `parameter_definition` item into the in-memory mapping.

      :param entity_class_name: The entity class name.
      :type entity_class_name: str
      :param name: The parameter name.
      :type name: str
      :param parameter_group_name: The name of the group of the parameter.
      :type parameter_group_name: str, optional
      :param parameter_type_list: List of valid value types.
      :type parameter_type_list: tuple, optional
      :param default_value: The default value's database representation.
      :type default_value: bytes, optional
      :param default_type: The default value's type.
      :type default_type: str, optional
      :param parsed_value: The default value.
      :type parsed_value: ParameterValue, optional
      :param parameter_value_list_name: The parameter value list name if any.
      :type parameter_value_list_name: str, optional
      :param description: The parameter description.
      :type description: str, optional

      :returns: The restored item.
      :rtype: :class:`PublicItem`



   .. py:method:: restore_parameter_value(**kwargs)

      Restores a previously removed `parameter_value` item into the in-memory mapping.

      :param entity_class_name: The entity class name.
      :type entity_class_name: str
      :param parameter_definition_name: The parameter name.
      :type parameter_definition_name: str
      :param entity_byname: A tuple with the entity name as single element if the entity is 0-dimensional, or the 0-dimensional element names if it is multi-dimensional.
      :type entity_byname: tuple
      :param value: The value's database representation.
      :type value: bytes
      :param type: The value's type. Optional only when value is null.
      :type type: str, optional
      :param parsed_value: The value.
      :type parsed_value: ParameterValue, optional
      :param alternative_name: The alternative name - defaults to 'Base'.
      :type alternative_name: str, optional

      :returns: The restored item.
      :rtype: :class:`PublicItem`



   .. py:method:: restore_metadata(**kwargs)

      Restores a previously removed `metadata` item into the in-memory mapping.

      :param name: The metadata entry name.
      :type name: str
      :param value: The metadata entry value.
      :type value: str

      :returns: The restored item.
      :rtype: :class:`PublicItem`



   .. py:method:: restore_entity_metadata(**kwargs)

      Restores a previously removed `entity_metadata` item into the in-memory mapping.

      :param entity_class_name: The entity class name.
      :type entity_class_name: str
      :param entity_byname: A tuple with the entity name as single element if the entity is 0-dimensional, or the 0-dimensional element names if it is multi-dimensional.
      :type entity_byname: tuple
      :param metadata_name: The metadata entry name.
      :type metadata_name: str
      :param metadata_value: The metadata entry value.
      :type metadata_value: str

      :returns: The restored item.
      :rtype: :class:`PublicItem`



   .. py:method:: restore_parameter_value_metadata(**kwargs)

      Restores a previously removed `parameter_value_metadata` item into the in-memory mapping.

      :param entity_class_name: The entity class name.
      :type entity_class_name: str
      :param parameter_definition_name: The parameter name.
      :type parameter_definition_name: str
      :param entity_byname: A tuple with the entity name as single element if the entity is 0-dimensional, or the 0-dimensional element names if it is multi-dimensional.
      :type entity_byname: tuple
      :param alternative_name: The alternative name.
      :type alternative_name: str
      :param metadata_name: The metadata entry name.
      :type metadata_name: str
      :param metadata_value: The metadata entry value.
      :type metadata_value: str

      :returns: The restored item.
      :rtype: :class:`PublicItem`



   .. py:method:: restore_entity_location(**kwargs)

      Restores a previously removed `entity_location` item into the in-memory mapping.

      :param entity_class_name: The entity class name.
      :type entity_class_name: str
      :param entity_byname: A tuple with the entity name as single element if the entity is 0-dimensional, or the 0-dimensional element names if it is multi-dimensional.
      :type entity_byname: tuple
      :param lat: Latitude.
      :type lat: float, optional
      :param lon: Longitude.
      :type lon: float, optional
      :param alt: Altitude.
      :type alt: float, optional
      :param shape_name: Name identifying the shape.
      :type shape_name: str, optional
      :param shape_blob: Shape as GEOJSON feature.
      :type shape_blob: str, optional

      :returns: The restored item.
      :rtype: :class:`PublicItem`



   .. py:method:: restore_alternatives(items)

      Restores multiple `alternative` items back into the in-memory mapping.

      :param items: items to restore
      :type items: list of dict



   .. py:method:: restore_scenarios(items)

      Restores multiple `scenario` items back into the in-memory mapping.

      :param items: items to restore
      :type items: list of dict



   .. py:method:: restore_scenario_alternatives(items)

      Restores multiple `scenario_alternative` items back into the in-memory mapping.

      :param items: items to restore
      :type items: list of dict



   .. py:method:: restore_entity_classes(items)

      Restores multiple `entity_class` items back into the in-memory mapping.

      :param items: items to restore
      :type items: list of dict



   .. py:method:: restore_display_modes(items)

      Restores multiple `display_mode` items back into the in-memory mapping.

      :param items: items to restore
      :type items: list of dict



   .. py:method:: restore_entity_class_display_modes(items)

      Restores multiple `entity_class_display_mode` items back into the in-memory mapping.

      :param items: items to restore
      :type items: list of dict



   .. py:method:: restore_superclass_subclasses(items)

      Restores multiple `superclass_subclass` items back into the in-memory mapping.

      :param items: items to restore
      :type items: list of dict



   .. py:method:: restore_entities(items)

      Restores multiple `entity` items back into the in-memory mapping.

      :param items: items to restore
      :type items: list of dict



   .. py:method:: restore_entity_groups(items)

      Restores multiple `entity_group` items back into the in-memory mapping.

      :param items: items to restore
      :type items: list of dict



   .. py:method:: restore_entity_alternatives(items)

      Restores multiple `entity_alternative` items back into the in-memory mapping.

      :param items: items to restore
      :type items: list of dict



   .. py:method:: restore_parameter_value_lists(items)

      Restores multiple `parameter_value_list` items back into the in-memory mapping.

      :param items: items to restore
      :type items: list of dict



   .. py:method:: restore_list_values(items)

      Restores multiple `list_value` items back into the in-memory mapping.

      :param items: items to restore
      :type items: list of dict



   .. py:method:: restore_parameter_types(items)

      Restores multiple `parameter_type` items back into the in-memory mapping.

      :param items: items to restore
      :type items: list of dict



   .. py:method:: restore_parameter_groups(items)

      Restores multiple `parameter_group` items back into the in-memory mapping.

      :param items: items to restore
      :type items: list of dict



   .. py:method:: restore_parameter_definitions(items)

      Restores multiple `parameter_definition` items back into the in-memory mapping.

      :param items: items to restore
      :type items: list of dict



   .. py:method:: restore_parameter_values(items)

      Restores multiple `parameter_value` items back into the in-memory mapping.

      :param items: items to restore
      :type items: list of dict



   .. py:method:: restore_metadata_items(items)

      Restores multiple `metadata` items back into the in-memory mapping.

      :param items: items to restore
      :type items: list of dict



   .. py:method:: restore_entity_metadata_items(items)

      Restores multiple `entity_metadata` items back into the in-memory mapping.

      :param items: items to restore
      :type items: list of dict



   .. py:method:: restore_parameter_value_metadata_items(items)

      Restores multiple `parameter_value_metadata` items back into the in-memory mapping.

      :param items: items to restore
      :type items: list of dict



   .. py:method:: restore_entity_locations(items)

      Restores multiple `entity_location` items back into the in-memory mapping.

      :param items: items to restore
      :type items: list of dict