Skip to main content
Version: v5.3

Collection mapping

Collection mapping​

A collection mapping binds an ontology class to the Item Service collection that stores its individuals. A class must have a collection mapping in the live version of the ontology before you can create, read, or import its individuals. For more information on individuals, see Individuals.

A collection mapping has two parts:

  • A collection binding, which names the collection and the item type of the class's individuals.
  • Any number of property mappings, which link item fields to ontology properties.

Collection bindings​

Each class has at most one collection binding. If you bind a class that already has a binding, the new binding replaces it.

You can bind a class in one of two ways:

  • By ID. Send _collectionId to use a NamedUserCollection or NamedTelemetryCollection that already exists in your namespace. You can send the collection's _userItemId or its _id. You need READ on the collection, and the collection can't belong to another platform service.
  • By name. Send _collectionName to have the service create a new collection when you promote the version. Until then, the binding's _collectionId is null. Only one class in a version can request a given name.

The service picks the type of a collection it creates from the class hierarchy. A class that descends from the base Telemetry class gets a NamedTelemetryCollection. Every other class gets a NamedUserCollection. A telemetry class can't use a NamedUserCollection, because that collection can't store readings. If you bind a telemetry class to one by ID, the call returns 400 and the existing binding stays. For more information, see Telemetry readings.

_userType sets the item type of the class's individuals in the collection. It defaults to the class name.

You can't map the platform lifecycle classes State, Event, Action, and StateTransition.

For the binding fields, see Bind a class to a collection. To list the bindings of every class in an ontology, see List collection mappings.

Mappings and ontology versions​

A collection mapping belongs to one version of the ontology, like classes and constraints. You add, change, and remove mappings in a draft version. Individuals always use the mapping in the live version. For more information, see Versions and drafts.

When you promote a version, the service brings the Item Service in line with the version's mappings:

  • It registers the item type of each mapped class, with a schema built from the class's field-based property mappings.
  • It creates each collection that a binding requested by name, and binds the new collection to the class. The binding's _collectionId is then the new collection's _userItemId.

Promotion only adds to the Item Service. It never removes an item type or deletes data it didn't create.

If a live binding has no collection yet, individual calls for the class return 409. To fix this, promote the version again, or bind the class to an existing collection by ID in a new draft.

Removing a binding also removes the class's property mappings. The collection and its items stay in the Item Service. For more information, see Remove a collection binding.

Shared collections​

Several classes can bind to the same existing collection by ID. For example, MechanicalAsset and ElectricalAsset can both store their individuals in one assets collection.

The service records each individual's class on the item, so it can tell individuals of different classes apart in a shared collection. A read on a class returns only the individuals of that class and its subclasses. A request for an individual of a sibling class returns 404. Class permissions are scoped the same way. For more information, see Permissions.

Property mappings​

A property mapping links a field on the item to a property in the ontology. Name the field with a dot path, such as properties.flowRate. A path that doesn't exist on an item gives no value, not an error.

To convert the field value, set _transform to string, number, boolean, or isoDate. Instead of a field, a mapping can hold a _script. The service stores the script but doesn't run it.

The service uses property mappings to check individual writes and imports, and to build the item type schema at promotion. Reads return the stored field names, not the mapped property names. For example, to filter individuals by flow rate, use properties.flowRate, not nominalFlowRate.

You can't change a property mapping. To change one, delete it and add a new one. For the mapping fields, see Add a property mapping.

Permissions​

Reading a mapping needs READ on the ontology, and changing one needs EDIT. For more information, see Permissions.