Timeseries Metadata

General

A timeseries consists of both metadata and data. A timeseries name is not used as a unique identifier, we automatically assign a unique identifier (GUID) for each timeseries that remains unchanged throughout the timeseries life cycle. The client can cache this identifier.

We don't allow two timeseries with the same name linked to the exact same facility. As an example, on your computer file system you can have files with the same name, but not in the same folder.

A customer is at least required to provide a name and facility on the timeseries being created.

Current timeseries metadata fields:

• name: name of the timeseries (mandatory).
• description: description of the timeseries (optional).
• step: whether the timeseries is step or not - true/false. When interpolating between data points, you can assume that for a stepped timeseries each value stays the same until the next measurement / horizontal line fit (optional).
• unit: units of measurement of the timeseries (optional).
• assetId: id of the asset this timeseries belongs to (optional free text, best practice is to use STID code).
• facility: Represents the facility code the timeseries belongs to. Only valid facility codes according to Equinor Common Library (master data) will be accepted, SAP code/Plant no preferred. Codes accepted: SAP code, STID code, NPD id. All valid codes (for Equinor personnel) can be found at https://commonlib.equinor.com/. The facility code entered is the one you and all others will see in the facility field of that timeseries. However, if a timeseries is created with a STID facility code, the same record will also be retrieved if you filter on the corresponding SAP or NPD code. The facility code is case-insensitive so e.g. ASGB / asgb is the same (mandatory).
• metadata: A custom metadata object with key-value pairs (max 17) where the customer can add additional data (optional).
• externalId: id from another (external) system provided by client (optional).

Note: The values, except for description, cannot start with whitespace characters.

In addition, when reading timeseries metadata from the Timeseries API, you will also get three system-generated fields:

• id: The system-generated unique identifier (GUID) of the timeseries metadata object.
• changedTime: The time when the timeseries metadata object was last changed in Omnia.
• createdTime: The time when the timeseries metadata object was created in Omnia.

A customer is at least able to get timeseries metadata by the unique identifier, by name or by an external id. The external id is usually an internal system identifier provided by the customer.

The API currently supports the following methods:

• Create a timeseries metadata object (POST)
• Partial update of a timeseries metadata object (PATCH)
• Full update of a timeseries metadata object (PUT)
• Delete a timeseries (soft delete, but you are not allowed to delete a timeseries object with related data points)
• Get one timeseries metadata object
• Get all timeseries metadata objects (a list), or a subset based on selected query parameter

Search

The API also supports doing wildcard searches on name, unit and description. The query parameter (timeseries/vX/search/query) searches in both name, unit and description at the same time, and you can then filter it by specifying a wildcard search on name, unit and/or description.

Example:

Timeseries A = [name: Pressure_Transmitter, description: Measuring pressure, unit: bar]

Timeseries B = [name: Temperature_Transmitter, description: Measuring the temperature on pump, unit: degC]

• API request /search/*Transmitter* will return Timeseries A and Timeseries B
• API request /search/*Transmitter*?description=*pressure* will return Timeseries A
• API request /search/*Measuring* will return Timeseries A and Timeseries B
• API request /search/*Measuring*?unit=deg* will return Timeseries B

Filter

Both the search and list endpoints supports filtering on metdata properties.

Example on search:

• API request /search?source=X&changedTime=>2022-02-07T12:15:31.5790000Z will return all items where source is X and changeTime is greater than 2022-02-07T12:15:31.5790000Z
• API request /search?source=X&createdTime=>2022-02-07T12:15:31.5790000Z will return all items where source is X and createdTime is greater than 2022-02-07T12:15:31.5790000Z
• API request /search?source=X&createdTime=<2022-02-07T12:15:31.5790000Z will return all items where source is X and createdTime is less than 2022-02-07T12:15:31.5790000Z
• API request /search?source=X&facility=Y will return all items where source is X and facility is Y

Example on list:

• API request /?source=X&changedTime=>2022-02-07T12:15:31.5790000Z will return all items where source is X and changeTime is greater than 2022-02-07T12:15:31.5790000Z
• API request /?source=X&createdTime=>2022-02-07T12:15:31.5790000Z will return all items where source is X and createdTime is greater than 2022-02-
• API request /?source=X&createdTime=<2022-02-07T12:15:31.5790000Z will return all items where source is X and createdTime is less than 2022-02-07T12:15:31.5790000Z07T12:15:31.5790000Z
• API request /?source=X&facility=Y will return all items where source is X and facility is Y

Paging

When the client asks for a list of timeseries objects in return, the client can optionally specify a limit (integer) that will limit the number of results to retrieve. For timeseries metadata this limit must be between 1 and 1000. Note that the total result set size of a query cannot exceed 100.000 items.

Example: The backend database has in total 1000 timeseries metadata objects. The client sets limit = 500 in the first API request. The client will then first retrieve 500 objects and a continuation token. The client must add the continuation token as a query parameter (&continuationToken={token}) in the next request to get the next 500 timeseries metadata objects. In this example, the second response will not contain any continuation token since the database has 1000 objects in total.