Hierarchical Value Service API  future
api indexresource index

POST {+table}/data/scope/batch

since: 0.40
Batch operation to create / overwrite / delete the given scopes with the specified records.

Path Elements

+table
0.1required
string
The URI path to a specific table (whether by ID or by name).

Request Headers

pros-hvs-consistency
0.13optional
string
pros-hvs-consistency is an optional HTTP header used to define the data consistency level of the request. There is a trade off between data consistency and service availability and performance: higher data consistency can result in lower availability and slower performance, while lower data consistency can result in higher availability and faster performance.
0.13 valid values:
  • HIGHEST
  • HIGH
  • NORMAL
  • LOW
  • LOWEST
pros-rtpe-cache
0.35optional
string

pros-rtpe-cache is an optional HTTP header used to define the caching strategy used by Hierarchial Value Service for a request. This header helps control which internal caches should be used by the service when processing the request. There is a tradeoff between returning the most recent data and performance. Disabling caches will help ensure that the most recent data available are returned, but will likely increase the time required to process and respond to the request.

When disable.metadata is specified, caches related to table and dimension metadata will be disabled.

When disable.data is specified, caches related to table and dimension data will be disabled.

When disable.all is specified, all caches will be disabled.

When any cache is disabled, those caches will not be updated with values retrieved during a request.

0.35 valid values:
  • enable
  • disable.metadata
  • disable.data
  • disable.all

Extended description

Each scope you want to modify is an element in the list field batch. If the scope has no records it will be deleted. If there are any records included for the scope it will be upserted.

The response contains one record for each scope. If the operation for the given scope succeeded then a data field will contain the scope, and all its records in case of an upsert. If the scope was deleted the records array will be empty. If there was an error trying to perform the operation for a give scope then an error field will be returned on that index of the response list. Records in successfully upserted scopes will be in the same order as the ones provided in the request.

The same restrictions apply to each record in the request, as would apply when calling the non-batch create request to the specified table.

The response header pros-scope-expired-count indicates the number of expired records that were part of any scope of the request and omitted due to data retention limits. This header is only returned when the status code is 200 and expired records are present in any scope of the request, otherwise the header is omitted.

Resource Information

Request Content
json
Request Object
Response Content
json
Response Object
Success Statuses
200  OK

Example - A request with 3 scopes. First tries to upsert but fails. Second tries to delete and succeeds and third also succeeds but at upserting

Request:

      
    {
      "batch": [
        {
          "key": [
            {
              "dimName": "SAMPLE_PRODUCTS",
              "nodeName": "0011491975135"
            },
            {
              "dimName": "LARGE_CITIES",
              "nodeName": "US-TX"
            }
          ],
          "records": [
            {
              "start": "2014-04-14T10:05:43",
              "end": "2015-02-10T20:14:21",
              "values": [
                {
                  "name": "Price",
                  "value": "20",
                  "type": "DECIMAL",
                  "unit": "Each",
                  "currency": "USD",
                  "perQuantity": 1
                }
              ]
            }
          ]
        },
        {
          "key": [
            {
              "dimName": "SAMPLE_PRODUCTS",
              "nodeName": "0011491975135"
            },
            {
              "dimName": "LARGE_CITIES",
              "nodeName": "US-TX-Dallas"
            }
          ],
          "records": []
        },
        {
          "key": [
            {
              "dimName": "LARGE_CITIES",
              "nodeName": "US-TX-Houston"
            },
            {
              "dimName": "SAMPLE_PRODUCTS",
              "nodeName": "0011491975135"
            }
          ],
          "records": [
            {
              "start": "2014-04-14T10:05:43",
              "end": "2014-05-18T20:14:21",
              "values": [
                {
                  "name": "Forecasted Volume",
                  "value": "17.26172",
                  "unit": "cubic feet",
                  "perQuantity": 1
                },
                {
                  "name": "Historic Revenue",
                  "value": "15.27181",
                  "currency": "USD",
                  "perQuantity": 0
                },
                {
                  "name": "Product Cost",
                  "value": "7.97181",
                  "unit": "Each",
                  "currency": "DKR",
                  "perQuantity": 1
                },
                {
                  "name": "Competitor Influence",
                  "value": "High"
                }
              ]
            }
          ]
        }
      ]
    }

Response:
HTTP/1.1  200  OK 

        
        {
          "scopeErrorCount": 1,
          "batch": [
            {
              "error": {
                "errorID": "HVS-004014",
                "errorMessage": "Example error message",
                "resourceType": "scope",
                "resourceID": "type-specific-ID-c689acc7-ee13-3482-aa7b-c6a13419431c",
                "requestID": "d0af9f1b-3159-4212-940e-ce984c19e8d3"
              }
            },
            {
              "data": {
                "result": {
                  "tableId": "bb18498a-3228-425a-816c-481bac1030ca",
                  "key": [
                    {
                      "aspectID": "816022f0-8648-11ea-a21a-bf5ce690da27",
                      "aspectName": "CITY",
                      "dimID": "7f128970-8648-11ea-a21a-bf5ce690da27",
                      "dimName": "LARGE_CITIES",
                      "nodeID": "8e40f350-8648-11ea-a21a-bf5ce690da27",
                      "nodeName": "US-TX-Dallas"
                    },
                    {
                      "aspectID": "913522f0-8648-11ea-a21a-455ce690da27",
                      "aspectName": "UPC",
                      "dimID": "28484058-4ffc-329b-94ff-63e1ddbd7189",
                      "dimName": "SAMPLE_PRODUCTS",
                      "nodeID": "27de4ae8-61be-3fff-a397-16362cafeba2",
                      "nodeName": "0011491975135"
                    }
                  ],
                  "records": []
                }
              }
            },
            {
              "data": {
                "result": {
                  "tableID": "bb18498a-3228-425a-816c-481bac1030ca",
                  "key": [
                    {
                      "aspectID": "816022f0-8648-11ea-a21a-bf5ce690da27",
                      "aspectName": "CITY",
                      "dimID": "7f128970-8648-11ea-a21a-bf5ce690da28",
                      "dimName": "LARGE_CITIES",
                      "nodeID": "8e40f350-8648-11ea-a21a-bf5ce690da28",
                      "nodeName": "US-TX-Houston"
                    },
                    {
                      "aspectID": "913522f0-8648-11ea-a21a-455ce690da27",
                      "aspectName": "UPC",
                      "dimID": "28484058-4ffc-329b-94ff-63e1ddbd7189",
                      "dimName": "SAMPLE_PRODUCTS",
                      "nodeID": "27de4ae8-61be-3fff-a397-16362cafeba2",
                      "nodeName": "0011491975135"
                    }
                  ],
                  "records": [
                    {
                      "start": "2014-04-14T10:05:43",
                      "end": "2014-05-18T20:14:21",
                      "values": [
                        {
                          "name": "Forecasted Volume",
                          "value": "17.26172",
                          "unit": "cubic feet",
                          "perQuantity": 1
                        },
                        {
                          "name": "Historic Revenue",
                          "value": "15.27181",
                          "currency": "USD",
                          "perQuantity": 0
                        },
                        {
                          "name": "Product Cost",
                          "value": "7.97181",
                          "unit": "Each",
                          "currency": "DKR",
                          "perQuantity": 1
                        },
                        {
                          "name": "Competitor Influence",
                          "value": "High"
                        }
                      ]
                    }
                  ]
                }
              }
            }
          ]
        }