Page History

Overview

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

Filtering

...

Criteria

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

Datetime

• Data after specified

  Datetime 

• Data in last X hours 
Data after a particular DateTime (To be supported in version 1Istanbul Release)
• Data between a date rangebefore specified DateTime 
• Last X network datarecords

DataTypes in CPS Core

• Dataspace & schema-set (To be supported in

  version 1

  Istanbul Release)

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

Payload (To be partially supported in

...

Istanbul Release)

• Based on a field

  or subsection

  in the payload

  , the entire path from the root must be provided

  . These criteria need schema-set to be fixed to search in the same set of anchors. The details of the format

  is

  are defined

  later

  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. 

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 

Anchor
payloadFilterFormat payloadFilterFormat

The filter data can be provided on any filtered, using JSON format, on one  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 are defined below:

Proposed APIs

Currently, we are not supporting all the filtering criteria defined in the overview. The below list defined the query parameters which can be used for all the endpoints.

...

The GET Endpoints contains information about the anchors and the rest of the filtering criteria are passed as query parameter. The below-mentioned query parameters are supported by all endpoints.

1. after - timestamp ( ISO Format) to consider data created after the specified Timestamp
2. simplePayloadFilter - to define payload filtering criteria
3. pageNumber - to define the page number (required for pagination)
4. pageLimit - to limit the response size
5. pointInTime - to consider data changed or added before this time.
6. sort - to define the order of data in the result set

The response format for endpoints is the same and defined here

By Dataspace and Anchor

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

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

Supported Query Parameter apart from other parameter

1. after - timestamp ( ISO Format) to consider date created after the specified Timestamp
2. payload - to define data filtering criteria

...

simplePayloadFilter={"idNearRTRIC":"1"}&pageLimit=500

By Dataspace and Schema-set

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

Supported Query Parameter apart from other parameter

1. after - timestamp ( ISO Format) to consider date created after the specified Timestamp
2. payload - to define data filtering criteria

anchors/history?schemaSet={schemaset-name}

Example: GET /dataspaces/{dataspace-name}/schema-sets/{schema-set}?anchors?schemaSet={schemaset-name}&after=2021-03-21T00:00:00-0:00

...

Return data entries for an anchor after the specified Datetime, which matches the payload format.

...

Return data entries based on provided schema-set after the specified Datetime, which matches the payload format.

&simplePayloadFilter={"idNearRTRIC":"1"}

Response 

Anchor
responseBody responseBody

...

...

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

Pros:

• Provides the ability to cache data based on URL. It is not relevant as data can change based on when the API is called. 
• Can provide links for the next record and previous record link in the response itself.
• pointInTime can have the current timestamp as the default value because we can add it in the next record and previous record link as a part of the response.

Cons

• If the payload filter condition becomes longer, it will not fit within the GET URL length limit. - TODO mention it somewhere ( Assumptions / Limitations / ? )

Questions

1. Should we disable caching or ask the user to pass the pointInTime parameter value? 

Open Items

...