Overview of the NoSQL Web API

On This Page


The platform's NoSQL Web API provides access to the NoSQL database service, which enables storing and consuming data in a tabular format. For more information, see Working with NoSQL Data. The platform's unified data model enables you to use the NoSQL Web API to fetch and update any object in the system.

  • To add an item to a table or replace an existing item, use PutItem.

    To create a table, just begin adding items. The table will be created automatically with the first item that you add. See Working with NoSQL Data.

  • To update an existing item in a table, use UpdateItem. .

  • To retrieve attributes of a table item, use GetItem.

  • To retrieve attributes of multiple items in a table or in a data container's root directory, use GetItems.

    GetItems supports scan optimizations either by performing range scans that use the items' sharding and sorting keys to locate items more quickly, or by dividing the table-scan operation into multiple segments that can be assigned to different workers for implementing a parallel scan. See Scan Optimization in the GetItems documentation.

  • To delete a table, either delete (remove) the table directory by using a file-system command, or use the delete client method of the V3IO Frames NoSQL backend. See Working with NoSQL Data.

In the NoSQL Web API, an attribute is represented by an Attribute JSON object. This is true for all attribute types.

The NoSQL Web API is part of the data-service web APIs and conforms to the related structure and syntax rules — see Data-Service Web-API General Structure.

The maximum JSON body size for the NoSQL web-API requests is 2 MB.

Item Name and Primary Key

A table item is a data object, and as such needs to be assigned a unique primary-key value, which serves as the item's name and is stored by the platform in the __name system attribute — see Object Names and Primary Keys. When adding a new item by using the PutItem or UpdateItem operation, you can provide the item's primary-key value (name) either in the request URL or as the name of the request's Key attribute JSON request parameter (see Setting the Resource Path). If you select to use the Key JSON parameter, the platform defines a primary-key user attribute with the specified name and value, in addition to the __name system attribute that is always defined for a new item; (see Attribute Types for information about user and system attributes).

Table Schema

The NoSQL Web API doesn't enforce a specific table schema: i.e., the items don't all need to contain the same attributes and items can have different data types for the same attribute. However, be advised that if the table items don't follow a consistent attributes schema you might fail to read data from the table using a structured-data interface such as Spark Datasets, Presto, and V3IO Frames.

See Also