CPS-251 [WIP] Define REST Query interface for Temporal service

CPS-251 - Getting issue details... STATUS

Overview

CPS temporal data query will allow the user to fetch data based on multiple filtering criteria. This data can be used to create graphs and help the analytical system to take decisions.

Filtering based on data

As it is time-series data, it can be filtered based on three main criteria:

Datetime

Data in last X hours
Data after a particular DateTime ( To be supported in version 1)
Data between a date range
Last X network data

DataTypes in CPS Core

Dataspace & schema-set ( To be supported in version 1)
Dataspace & anchor ( To be supported in version 1)
Dataspace & multiple anchors - To improve performance, if there is a need to fetch data for multiple anchors.

Payload ( To be partially supported in version 1)

Based on a field or subsection in the payload, but it is important to provide the entire path from the root. These criteria need schema-set to be fixed to search in the same set of anchors. The details of the format are defined here.

We will implement only the basic APIs first and will add complex ones when required.

Other Parameters

There are other parameters, listed below, that can have an impact on the response.

No

Name

Type

Default

Purpose

Example

1

index

int

0

The query output can have many rows so it is important to limit the fetched data. To limit the number of records and to provide pagination, these two parameters can be used.

"index" parameter represents the page number, starts with 0, and maxSize is the page size.

2

maxSize

int

1000

3

pointInTime

DateTime

CurrentDateTime

Pagination does not work well if new data gets added which fulfils the search criteria. The user must provide this value to avoid this issue.

Assumptions

Temporal database stores full information in the payload ( CPS-192: Design data store for Temporal Service).
Data in the response body will always contain the entire payload data.

Payload Filter Format

The filter can be provided on any field at any level, but it is important to provide the entire path from the root. The below mention JSON is used as an example to explain the filtering format

{
  "idNearRTRIC": "1",
  "labels" : [ "cps", "ran"],
  "nestedObject": {
    "id": "4",
	"
    "attributes": {
      "gNBDUId": 4.0,
      "gNBDUName": "gnduserver4",
      "gNBIdLength": 32.0
    }
  },
  "GNBDUFunction": [
    {
      "idGNBDUFunction": "5",
      "NRCellDU": [
        {
          "idNRCellDU": "13905",
          "attributes": {
            "nRPCI": 12.0,
            "nRTAC": 310.0,
            "cellLocalId": 13905.0
          }
        },
        {
          "idNRCellDU": "14655",
          "attributes": {
            "nRPCI": 12.0,
            "nRTAC": 310.0,
            "cellLocalId": 14655.0
          }
        }
      ],
      "attributes": {
        "gNBDUId": 5.0,
        "gNBDUName": "gnduserver5",
        "gNBIdLength": 32.0
      }
    }
  ]
}

The filtering scenarios and the format to be used for each is defined below:

No	Type of field	To be search
1	Top-level field	idNearRTRIC
2	The field inside another object	nestedObject → id
3	String collection field at the top level	labels
4	The field inside a collection	GNBDUFunction → idGNBDUFunction

Proposed APIs

Currently, we are not supporting all the filtering criteria defined in the overview. The supported ones are defined below and are passed as query parameter.

after - timestamp ( ISO Format) to consider date created after the specified Timestamp
payload - to define data filtering criteria
index - defined the page number and required for pagination
maxSize - To limit the response size
pointInTime - to consider data changed or added before this time.

The response format for all get APIs is the same and defined here

Data by Anchor Name

URL: GET /dataspaces/{dataspace-name}/anchors/{anchor-name}

Example: GET /dataspaces/{dataspace-name}/anchors/{anchor-name}?after=2021-03-21T00:00:00-0:00&payload=/device/port/interface[status=up]&maxSize=500

Date by Dataspace and Schema-set

URL: GET /dataspaces/{dataspace-name}/schema-sets/{schema-set}

Example: GET /dataspaces/{dataspace-name}/schema-sets/{schema-set}?after=2021-03-21T00:00:00-0:00&payload=/device/port/interface[status=up]

Response

name	type
nextRecordsLink	string	added only if there are remaining records to be fetched for the query.
previousRecordsLink	string	added only if it is not the first set of records.
records	list	contains one record for each timestamp that meets filtering criteria. It contains header information along with data.

{
  "nextRecordsLink": "cps-temporal/api/v1/dataspaces/{dataspace-name}/anchors/{anchor-name}?after=2021-03-21T00:00:00-0:00&maxSize=500&pointInTime=2021-04-21T00:00:00-0:00&index=2",
  "previousRecordsLink": "cps-temporal/api/v1/dataspaces/{dataspace-name}/anchors/{anchor-name}?after=2021-03-21T00:00:00-0:00&maxSize=500&pointInTime=2021-04-21T00:00:00-0:00&index=0",
  "records": [
    {
      "timestamp": "1234567788889", // TODO change the format
      "dataspace": "my-dataspace",
      "schemaSet": "my-schema-set",
      "anchor": "my-anchor",
      "data": {
        "status" : "UP"
      }
    }
  ]
}

Space shortcuts

Page tree