Create an item in Azure Cosmos DB for NoSQL using JavaScript

APPLIES TO: NoSQL

Items in Azure Cosmos DB represent a specific entity stored within a container. In the API for NoSQL, an item consists of JSON-formatted data with a unique identifier.

Item, item definition, and item response

In the JavaScript SDK, the three objects related to an item have different purposes.

Name	Operations
Item	Functionality including Read, Patch, Replace, Delete.
ItemDefinition	Your custom data object. Includes id and ttl properties automatically.
ItemResponse	Includes statusCode, item, and other properties.

Use the properties of the ItemResponse object to understand the result of the operation.

• statusCode: HTTP status code. A successful response is in the 200-299 range.
• activityId: Unique identifier for the operation such as create, read, replace, or delete.
• etag: Entity tag associated with the data. Use for optimistic concurrency, caching, and conditional requests.
• item: Item object used to perform operations such as read, replace, delete.
• resource: Your custom data.

Create a unique identifier for an item

The unique identifier is a distinct string that identifies an item within a container. The id property is the only required property when creating a new JSON document. For example, this JSON document is a valid item in Azure Cosmos DB:

{
  "id": "unique-string-2309509"
}

Within the scope of a container, two items can't share the same unique identifier.

Important

The id property is case-sensitive. Properties named ID, Id, iD, and _id will be treated as an arbitrary JSON property.

Once created, the URI for an item is in this format:

https://<cosmos-account-name>.documents.azure.com/dbs/<database-name>/docs/<item-resource-identifier>

When referencing the item using a URI, use the system-generated resource identifier instead of the id field. For more information about system-generated item properties in Azure Cosmos DB for NoSQL, see properties of an item

Create an item

Create an item with the container's items object using the create method.

const { statusCode, item, resource, activityId, etag} = await container.items.create({ 
        id: '2', 
        category: 'gear-surf-surfboards',
        name: 'Sunnox Surfboard',
        quantity: 8,
        sale: true 
    });

Access an item

Access an item through the Item object. This can accessed from the Container object or changed from either the Database or CosmosClient objects.

// Chained, then use a method of the Item object such as `read`
const { statusCode, item, resource, activityId, etag} = await client.database(databaseId).container(containerId).item(itemId).read();

Access by object:

• Items (plural): Create, batch, watch change feed, read all, upsert, or query items.
• Item (singular): Read, patch, replace, or delete an item.

Replace an item

Replace the data with the Item object with the replace method.

const { statusCode, item, resource, activityId, etag} = await item.replace({ 
        id: '2', 
        category: 'gear-surf-surfboards-retro',
        name: 'Sunnox Surfboard Retro',
        quantity: 5,
        sale: false 
    });

Read an item

Read the most current data with the Item object's read method.

const { statusCode, item, resource, activityId, etag} = await item.read();

Delete an item

Delete the item with the Item object's' delete method.

const { statusCode, item, activityId, etag} = await item.delete();

Next steps

Now that you've created various items, use the next guide to query for item.

Read an item