Hierarchical Value Service API  future
api indexresource index

POST {+table}/data/batch

since: 0.29
Batch operation to create, update or delete multiple records to the specified table.

Please note that all the single record updates and deletes are no longer supported for the newly provisioned tenants. Use the Batch Scope APIs i.e SCOPE UPSERT and SCOPE DELETE) for the upsert operations.

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

The length of the response's records array is guaranteed to be exactly the same as the length of the request's records array. Furthermore, the order of elements in the response's records array is guaranteed to be exactly the same as the order of corresponding reference elements in the request's records array.

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 request's records array must contain between 1 and 100 records, inclusive. Any other size results in an error.

Note that a single large batch is not necessarily the most optimal request. Smaller batches that are sent in parallel on multiple connections will generally perform better than a single maximally-sized request. Ideal performance optimization needs to weigh the trade-off between batch size and request volume.

The response header pros-batch-errors indicates the number of elements with errors in the response body. This header is only returned when the status code is 200 and errors are present in the response, otherwise the header is omitted.

Resource Information

Request Content
json
Request Object
Response Content
json
Response Object
Success Statuses
200  OK
Error Statuses
400  BAD REQUEST

Example - Batch Request to create multiple new records in the same table

Request:

            
  {
    "records":[
      {
        "start": "2014-04-14T10:05:43",
        "end": "2014-05-18T20:14:21",
        "key": [
          {
            "nodeName" : "0011491975135",
            "dimName"  : "SAMPLE_PRODUCTS"
          },
          {
            "dimName"  : "LARGE_CITIES",
            "nodeName" : "US-TX"
          }
        ],
        "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 

{
  "records": [
    {
      "record":
      {
        "tableID" : "bb18498a-3228-425a-816c-481bac1030ca",
        "start": "2014-04-14T10:05:43",
        "end": "2014-05-18T20:14:21",
        "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-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"
          }
        ],
        "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"
          }
        ]
      }
    }
  ]
}

Example - Batch Request to create a successful and an error record

Request:

            
  {
    "records":[
      {
        "start": "2014-04-14T10:05:43",
        "end": "2014-05-18T20:14:21",
        "key": [
          {
            "nodeName" : "0011491975135",
            "dimName"  : "SAMPLE_PRODUCTS"
          },
          {
            "dimName"  : "LARGE_CITIES",
            "nodeName" : "US-TX"
          }
        ],
        "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"
          }
        ]
      },
      {
        "start": "2014-04-14T10:05:43",
        "end": "2014-05-18T20:14:21",
        "key":
          [
            {
              "nodeName" : "0011491975135",
              "dimName"  : "SAMPLE_PRODUCTS"
            },
            {
              "dimName"  : "LARGE_CITIES1",
              "nodeName" : "US-TX"
            }
          ],
          "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 

{
  "records": [
    {
      "record": {
        "tableID" : "bb18498a-3228-425a-816c-481bac1030ca",
        "start": "2014-04-14T10:05:43",
        "end": "2014-05-18T20:14:21",
        "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-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"
          }
        ],
        "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"
          }
        ]
      }
    },
    {
      "error" : {
        "errorID": "HVS-004017",
        "errorMessage": "The dimension LARGE_CITIES1 was not found.",
        "resourceType": "record"
      }
    }
  ]
}

Example - Batch Request to delete record successfully

Request:

            
  {
    "records":[
      {
        "start": "2014-04-14T10:05:43",
        "end": "2014-05-18T20:14:21",
        "key": [
          {
            "nodeName" : "0011491975135",
            "dimName"  : "SAMPLE_PRODUCTS"
          },
          {
            "dimName"  : "LARGE_CITIES",
            "nodeName" : "US-TX"
          }
        ],
        "deleted": true
      }
  }

Response:
HTTP/1.1  200  OK 

{
  "records": [
    {
      "record" :
        {
          "start": "2014-04-14T10:05:43",
          "end": "2014-05-18T20:14:21",
          "key":
          [
              {
                "nodeName" : "0011491975135",
                "dimName"  : "SAMPLE_PRODUCTS"
              },
              {
                "dimName"  : "LARGE_CITIES",
                "nodeName" : "US-TX"
              }
          ],
          "deleted": true
        }
    }
  ]
}

Example - Batch Request with an invalid dimension

Request:

            
        {
          "records":[
          {
            "start": "2014-04-14T10:05:43",
            "end": "2014-05-18T20:14:21",
            "key":
            [
              {
                "nodeName" : "0011491975135",
                "dimName"  : "SAMPLE_PRODUCTS"
              },
              {
                "dimName"  : "LARGE_CITIES1",
                "nodeName" : "US-TX"
              }
            ],
            "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 

{
  "records": [
    {
      "error" : {
        "errorID": "HVS-004017",
        "errorMessage": "The dimension LARGE_CITIES1 was not found.",
        "resourceType": "record"
      }
    }
  ]
}

Example - Batch Request to delete record with an error

Request:

            
  {
    "records":[
      {
        "start": "2014-04-14T10:05:43",
        "end": "2014-05-18T20:14:21",
        "key": [
          {
            "nodeName" : "0011491975135",
            "dimName"  : "SAMPLE_PRODUCTS"
          },
          {
            "dimName"  : "LARGE_CITIES1",
            "nodeName" : "US-TX"
          }
        ],
        "deleted": true
      }
  }

Response:
HTTP/1.1  200  OK 

{
  "records": [
    {
      "error" : {
        "errorID": "HVS-004017",
        "errorMessage": "The dimension LARGE_CITIES1 was not found.",
        "resourceType": "record"
      }
    }
  ]
}

Error Example - Too many records in one request

Request:

            
        {
          "records":
          [
            { "start": "2014-04-14T10:05:43" },
            { "start": "2015-04-14T10:05:43" },
            // ... 98 other records ...
            { "start": "2020-04-14T10:05:43" }
          ]
        }

Response:
HTTP/1.1  400  BAD REQUEST 

{
  "errorID": "HVS-004044",
  "errorMessage": "Could not process the batch request because the request payload contains more than 100.",
  "resourceType": "batch",
  "requestID": "HVS-ae5d8b94c215dec9",
  "details": [
    {
      "fieldID": "records",
      "fieldValue": "limit"
    }
  ]
}

Error Example - Batch Request error response when adding records in the new schema

Request:

            
  {
    "records":[
      {
        "start": "2014-04-14T10:05:43",
        "end": "2014-05-18T20:14:21",
        "key": [
          {
            "nodeName" : "0011491975135",
            "dimName"  : "SAMPLE_PRODUCTS"
          },
          {
            "dimName"  : "LARGE_CITIES",
            "nodeName" : "US-TX"
          }
        ],
        "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  400  BAD REQUEST 

{
    "errorID": "HVS-004046",
    "errorMessage": "Single record updates have been disabled for this tenant. Please use Batch Scope APIs.",
    "resourceType": "record",
    "requestID": "HVS-5ba77a6d6efb37b8"
}

Example - Batch Request with an invalid perQuantity values

Request:

            
        {
          "records":[
          {
            "start": "2014-04-14T10:05:43",
            "end": "2014-05-18T20:14:21",
            "key":
            [
              {
                "nodeName" : "0011491975135",
                "dimName"  : "SAMPLE_PRODUCTS"
              },
              {
                "dimName"  : "LARGE_CITIES",
                "nodeName" : "US-TX"
              }
            ],
            "values" :
            [
              {
                "name"  : "Forecasted Volume",
                "value" : "17.26172",
                "unit"  : "cubic feet",
                "perQuantity" : 0
              }
            ]
          },
          {
            "start": "2014-06-14T10:05:43",
            "end": "2014-07-18T20:14:21",
            "key":
            [
              {
                "nodeName" : "0011491975135",
                "dimName"  : "SAMPLE_PRODUCTS"
              },
              {
                "dimName"  : "LARGE_CITIES",
                "nodeName" : "US-TX"
              }
            ],
            "values" :
            [
              {
                "name"  : "Forecasted Volume",
                "value" : "17.26172",
                "currency"  : "USD",
                "perQuantity" : 1
              }
            ]
          },
          ,
          {
            "start": "2014-06-14T10:05:43",
            "end": "2014-07-18T20:14:21",
            "key":
            [
              {
                "nodeName" : "0011491975135",
                "dimName"  : "SAMPLE_PRODUCTS"
              },
              {
                "dimName"  : "LARGE_CITIES",
                "nodeName" : "US-TX"
              }
            ],
            "values" :
            [
              {
                "name"  : "Forecasted Volume",
                "value" : "17.26172",
                "unit"  : "cubic feet",
                "currency"  : "DKR",
                "perQuantity" : 0
              }
            ]
          }
          ]
        }

Response:
HTTP/1.1  200  OK 

{
  "records": [
    {
      "error" : {
        "errorID": "HVS-004051",
        "errorMessage": "Per quantity value is invalid.",
        "resourceType": "record"
      }
    },
    {
      "error" : {
        "errorID": "HVS-004051",
        "errorMessage": "Per quantity value is invalid.",
        "resourceType": "record"
      }
    },{
      "error" : {
        "errorID": "HVS-004051",
        "errorMessage": "Per quantity value is invalid.",
        "resourceType": "record"
      }
    }
  ]
}