Hierarchical Value Service API Resources

Table Configuration

Manage a table of hierarchical value records and associated metadata. A table describes and contains a collection of closely related hierarchical data. It defines a named data store for strongly typed data that is grouped by dimensions and aspects. A list of access levels that consist of dimension/aspect pairs is defined as a sequence to specify the search order for the data. It also defines the dimension aspects allowed for the data stored in the table.

Resource	Description
POST table	Create a table and specify its metadata.
GET table	Returns all tables defined in short form, listing only their ID, name, and whether the table is configured for dynamic columns.
GET table/id/{id}	Return the table with the given ID. The ID can be either the ID of a table or the ID of a link that is linked to a table.
GET table/name/{name}	Return the table with the given name. The name can be either the name of a table or the name of a link that is linked to a table.
DELETE table/id/{id}	Delete a table using its ID as identifier.
DELETE table/name/{name}	Delete a table using its unique name as identifier.
PUT table/id/{id}/name	Change the name of the table that is identified by the given id.
PUT table/id/{id}	Updates the table with the given payload. Everything is updated except for the name. To update the table name use Rename Table.
PUT table/name/{name}	Updates the table with the given payload. Everything is updated except for the name. To update the table name use Rename Table.
PUT {+table}/accessSequence	Access levels within the sequence can be added, removed, or reordered. Reordering of the access levels within the sequence will not affect the availability of the data referenced by those levels. However, if an access level is removed, the data referenced by that access level will no longer be acces...
DELETE {+table}/truncate	Truncate a table. After this operation, all the records that are currently associated with this table will not be available for query.
DELETE {+table}/data	Truncate a table. After this operation, all the records that are currently associated with this table will not be available for query.
GET table/name/{name}/cache	Return the cache configuration of the table with the given name.
GET table/id/{id}/cache	Return the cache configuration of the table with the given id.

Link Configuration

Manage a symbolic link to a table. A link can be used to query table data but cannot be used to change the content of or delete its destination table.

Resource	Description
POST link	Create a link to a table.
GET link/id/{id}	Return the link with the given ID.
GET link/name/{name}	Return the link with the given name.
DELETE link/id/{id}	Delete a link using its ID as identifier.
DELETE link/name/{name}	Delete a link using its unique name as identifier.
PUT {+link}/table	Update link to link to a new destination. Only the tableID field in the payload will be used.

Storing and Retrieving Records

Once a table is defined, records containing dimensional data can be created for that table. Records are logically grouped by scopes. A record has an effective date time range that restricts its validity. For a given scope and effective date time range, existing values can be overwritten by new values or logically deleted. The hierarchical value service provides some basic validations to ensure the input data conforms to the structure of its table.

Once created, the record can be retrieved for a request by the scope and date time. The hierarchical value service finds the best match based on the access sequence from the table in the following manner:

Find the first access level from access sequence that matches the request.
Resolve the search scope based on the matching access level by finding the ancestors of the nodes in the given scope that belong to the aspects in this access level.
Retrieve records with the search scope and effective date time range covering the requested date time. When multiple records meet the search criteria, the record with the latest written at time UUID is selected. The written at time UUID is generated by the server. If a record is found, the record is returned; otherwise, the search continues by using the next matching access level in the access sequence till a record is found or the access levels are exhausted. If no applicable records are found, no content is returned.

When requesting a record, it is possible to specify particular columns of interest in the record to be retrieved instead of receiving all existing columns. If such filtering is desired the columns can be specifed in the request URI on the {data} path segment.

If none of the specified columns exist in the table, then the request yields a HTTP 204 response (NO CONTENT).
If only some of the specified columns have values, only those columns are returned in the response.
If all columns specified have values, they will all be returned in the response.

Resource	Description
POST {+table}/data	Add a single record to the specified table for existing tenants only. 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.
POST {+table}/data/batch	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.
POST {+table}/data/scope/batch	Batch operation to create / overwrite / delete the given scopes with the specified records.
PUT {+table}/data/scope/nameKey	Batch operation to overwrite the given scope with the specified records.
DELETE {+table}/data/scope/nameKey	Batch operation to delete all records in a given scope from the specified table.
GET {+table}/data/idKey	Finds the most specific record defined for the given search key, date, and time. Request a record with scope at specific level using GET {+table}/data/idKey/exact
GET {+table}/data/nameKey	Finds the most specific record defined for the given search key, date, and time. There is a alternate resource available for searching records by using dimension ID and dimension node ID in the scope. Request a record with scope at specific level using GET {+table}/data/nameKey/exact
GET {+table}/data/idKey/exact	Finds the most specific record defined for the given search key, date, and time. Since the idKey is specified for the scope, it is required that the dimensions and aspects are referred to by ID for exact. Unlike regular record retrieval which traverses the access sequence to find a matching record, when...
GET {+table}/data/nameKey/exact	Finds the most specific record defined for the given search key, date, and time. Since the nameKey is specified for the scope, it is required that the dimensions and aspects are referred to by name for exact. Unlike regular record retrieval which traverses the access sequence to find a matching record,...
DELETE {+table}/data/idKey	Deletes records matching a specific scope in a specified time range. Unlike the search operation, this method does not traverse the access sequence and will only delete records exactly matching the given key.
DELETE {+table}/data/nameKey	Deletes records matching a specific scope in a specified time range. Unlike the search operation, this method does not traverse the access sequence and will only delete records exactly matching the given key.