Items class

Operations for creating new items, and reading/querying all items

See Item for reading, replacing, or deleting an existing container; use .item(id).

Properties

container

Methods

batch(OperationInput[], PartitionKey, RequestOptions)

Execute transactional batch operations on items.

Batch takes an array of Operations which are typed based on what the operation does. Batch is transactional and will rollback all operations if one fails. The choices are: Create, Upsert, Read, Replace, and Delete

Usage example:

// partitionKey is required as a second argument to batch, but defaults to the default partition key
const operations: OperationInput[] = [
   {
      operationType: "Create",
      resourceBody: { id: "doc1", name: "sample", key: "A" }
   },
   {
      operationType: "Upsert",
      partitionKey: 'A',
      resourceBody: { id: "doc2", name: "other", key: "A" }
   }
]

await database.container.items.batch(operations)
bulk(OperationInput[], BulkOptions, RequestOptions)

Execute bulk operations on items.

Bulk takes an array of Operations which are typed based on what the operation does. The choices are: Create, Upsert, Read, Replace, and Delete

Usage example:

// partitionKey is optional at the top level if present in the resourceBody
const operations: OperationInput[] = [
   {
      operationType: "Create",
      resourceBody: { id: "doc1", name: "sample", key: "A" }
   },
   {
      operationType: "Upsert",
      partitionKey: 'A',
      resourceBody: { id: "doc2", name: "other", key: "A" }
   }
]

await database.container.items.bulk(operations)
changeFeed(ChangeFeedOptions)

Create a ChangeFeedIterator to iterate over pages of changes

changeFeed(PartitionKey, ChangeFeedOptions)

Create a ChangeFeedIterator to iterate over pages of changes

Example

Read from the beginning of the change feed.

const iterator = items.readChangeFeed({ startFromBeginning: true });
const firstPage = await iterator.fetchNext();
const firstPageResults = firstPage.result
const secondPage = await iterator.fetchNext();
changeFeed<T>(ChangeFeedOptions)

Create a ChangeFeedIterator to iterate over pages of changes

changeFeed<T>(PartitionKey, ChangeFeedOptions)

Create a ChangeFeedIterator to iterate over pages of changes

create<T>(T, RequestOptions)

Create an item.

Any provided type, T, is not necessarily enforced by the SDK. You may get more or less properties and it's up to your logic to enforce it.

There is no set schema for JSON items. They may contain any number of custom properties.

getChangeFeedIterator<T>(ChangeFeedIteratorOptions)

Returns an iterator to iterate over pages of changes. The iterator returned can be used to fetch changes for a single partition key, feed range or an entire container.

query(string | SqlQuerySpec, FeedOptions)

Queries all items.

Example

Read all items to array.

const querySpec: SqlQuerySpec = {
  query: "SELECT * FROM Families f WHERE f.lastName = @lastName",
  parameters: [
    {name: "@lastName", value: "Hendricks"}
  ]
};
const {result: items} = await items.query(querySpec).fetchAll();
query<T>(string | SqlQuerySpec, FeedOptions)

Queries all items.

Example

Read all items to array.

const querySpec: SqlQuerySpec = {
  query: "SELECT firstname FROM Families f WHERE f.lastName = @lastName",
  parameters: [
    {name: "@lastName", value: "Hendricks"}
  ]
};
const {result: items} = await items.query<{firstName: string}>(querySpec).fetchAll();
readAll(FeedOptions)

Read all items.

There is no set schema for JSON items. They may contain any number of custom properties.

Example

Read all items to array.

const {body: containerList} = await items.readAll().fetchAll();
readAll<T>(FeedOptions)

Read all items.

Any provided type, T, is not necessarily enforced by the SDK. You may get more or less properties and it's up to your logic to enforce it.

There is no set schema for JSON items. They may contain any number of custom properties.

Example

Read all items to array.

const {body: containerList} = await items.readAll().fetchAll();
readChangeFeed(ChangeFeedOptions)

Create a ChangeFeedIterator to iterate over pages of changes

readChangeFeed(PartitionKey, ChangeFeedOptions)

Create a ChangeFeedIterator to iterate over pages of changes

Example

Read from the beginning of the change feed.

const iterator = items.readChangeFeed({ startFromBeginning: true });
const firstPage = await iterator.fetchNext();
const firstPageResults = firstPage.result
const secondPage = await iterator.fetchNext();
readChangeFeed<T>(ChangeFeedOptions)

Create a ChangeFeedIterator to iterate over pages of changes

readChangeFeed<T>(PartitionKey, ChangeFeedOptions)

Create a ChangeFeedIterator to iterate over pages of changes

upsert(unknown, RequestOptions)

Upsert an item.

There is no set schema for JSON items. They may contain any number of custom properties.

upsert<T>(T, RequestOptions)

Upsert an item.

Any provided type, T, is not necessarily enforced by the SDK. You may get more or less properties and it's up to your logic to enforce it.

There is no set schema for JSON items. They may contain any number of custom properties.

Property Details

container

container: Container

Property Value

Method Details

batch(OperationInput[], PartitionKey, RequestOptions)

Execute transactional batch operations on items.

Batch takes an array of Operations which are typed based on what the operation does. Batch is transactional and will rollback all operations if one fails. The choices are: Create, Upsert, Read, Replace, and Delete

Usage example:

// partitionKey is required as a second argument to batch, but defaults to the default partition key
const operations: OperationInput[] = [
   {
      operationType: "Create",
      resourceBody: { id: "doc1", name: "sample", key: "A" }
   },
   {
      operationType: "Upsert",
      partitionKey: 'A',
      resourceBody: { id: "doc2", name: "other", key: "A" }
   }
]

await database.container.items.batch(operations)
function batch(operations: OperationInput[], partitionKey?: PartitionKey, options?: RequestOptions): Promise<Response_2<OperationResponse[]>>

Parameters

operations

OperationInput[]

List of operations. Limit 100

partitionKey
PartitionKey
options
RequestOptions

Used for modifying the request

Returns

Promise<Response_2<OperationResponse[]>>

bulk(OperationInput[], BulkOptions, RequestOptions)

Execute bulk operations on items.

Bulk takes an array of Operations which are typed based on what the operation does. The choices are: Create, Upsert, Read, Replace, and Delete

Usage example:

// partitionKey is optional at the top level if present in the resourceBody
const operations: OperationInput[] = [
   {
      operationType: "Create",
      resourceBody: { id: "doc1", name: "sample", key: "A" }
   },
   {
      operationType: "Upsert",
      partitionKey: 'A',
      resourceBody: { id: "doc2", name: "other", key: "A" }
   }
]

await database.container.items.bulk(operations)
function bulk(operations: OperationInput[], bulkOptions?: BulkOptions, options?: RequestOptions): Promise<BulkOperationResponse>

Parameters

operations

OperationInput[]

List of operations. Limit 100

bulkOptions
BulkOptions

Optional options object to modify bulk behavior. Pass { continueOnError: true } to continue executing operations when one fails. (Defaults to false) ** NOTE: THIS WILL DEFAULT TO TRUE IN THE 4.0 RELEASE

options
RequestOptions

Used for modifying the request.

Returns

changeFeed(ChangeFeedOptions)

Create a ChangeFeedIterator to iterate over pages of changes

function changeFeed(changeFeedOptions?: ChangeFeedOptions): ChangeFeedIterator<any>

Parameters

changeFeedOptions
ChangeFeedOptions

Returns

changeFeed(PartitionKey, ChangeFeedOptions)

Create a ChangeFeedIterator to iterate over pages of changes

Example

Read from the beginning of the change feed.

const iterator = items.readChangeFeed({ startFromBeginning: true });
const firstPage = await iterator.fetchNext();
const firstPageResults = firstPage.result
const secondPage = await iterator.fetchNext();
function changeFeed(partitionKey: PartitionKey, changeFeedOptions?: ChangeFeedOptions): ChangeFeedIterator<any>

Parameters

partitionKey
PartitionKey
changeFeedOptions
ChangeFeedOptions

Returns

changeFeed<T>(ChangeFeedOptions)

Create a ChangeFeedIterator to iterate over pages of changes

function changeFeed<T>(changeFeedOptions?: ChangeFeedOptions): ChangeFeedIterator<T>

Parameters

changeFeedOptions
ChangeFeedOptions

Returns

changeFeed<T>(PartitionKey, ChangeFeedOptions)

Create a ChangeFeedIterator to iterate over pages of changes

function changeFeed<T>(partitionKey: PartitionKey, changeFeedOptions?: ChangeFeedOptions): ChangeFeedIterator<T>

Parameters

partitionKey
PartitionKey
changeFeedOptions
ChangeFeedOptions

Returns

create<T>(T, RequestOptions)

Create an item.

Any provided type, T, is not necessarily enforced by the SDK. You may get more or less properties and it's up to your logic to enforce it.

There is no set schema for JSON items. They may contain any number of custom properties.

function create<T>(body: T, options?: RequestOptions): Promise<ItemResponse<T>>

Parameters

body

T

Represents the body of the item. Can contain any number of user defined properties.

options
RequestOptions

Used for modifying the request (for instance, specifying the partition key).

Returns

Promise<ItemResponse<T>>

getChangeFeedIterator<T>(ChangeFeedIteratorOptions)

Returns an iterator to iterate over pages of changes. The iterator returned can be used to fetch changes for a single partition key, feed range or an entire container.

function getChangeFeedIterator<T>(changeFeedIteratorOptions?: ChangeFeedIteratorOptions): ChangeFeedPullModelIterator<T>

Parameters

changeFeedIteratorOptions
ChangeFeedIteratorOptions

Returns

query(string | SqlQuerySpec, FeedOptions)

Queries all items.

Example

Read all items to array.

const querySpec: SqlQuerySpec = {
  query: "SELECT * FROM Families f WHERE f.lastName = @lastName",
  parameters: [
    {name: "@lastName", value: "Hendricks"}
  ]
};
const {result: items} = await items.query(querySpec).fetchAll();
function query(query: string | SqlQuerySpec, options?: FeedOptions): QueryIterator<any>

Parameters

query

string | SqlQuerySpec

Query configuration for the operation. See SqlQuerySpec for more info on how to configure a query.

options
FeedOptions

Used for modifying the request (for instance, specifying the partition key).

Returns

query<T>(string | SqlQuerySpec, FeedOptions)

Queries all items.

Example

Read all items to array.

const querySpec: SqlQuerySpec = {
  query: "SELECT firstname FROM Families f WHERE f.lastName = @lastName",
  parameters: [
    {name: "@lastName", value: "Hendricks"}
  ]
};
const {result: items} = await items.query<{firstName: string}>(querySpec).fetchAll();
function query<T>(query: string | SqlQuerySpec, options?: FeedOptions): QueryIterator<T>

Parameters

query

string | SqlQuerySpec

Query configuration for the operation. See SqlQuerySpec for more info on how to configure a query.

options
FeedOptions

Used for modifying the request (for instance, specifying the partition key).

Returns

readAll(FeedOptions)

Read all items.

There is no set schema for JSON items. They may contain any number of custom properties.

Example

Read all items to array.

const {body: containerList} = await items.readAll().fetchAll();
function readAll(options?: FeedOptions): QueryIterator<ItemDefinition>

Parameters

options
FeedOptions

Used for modifying the request (for instance, specifying the partition key).

Returns

readAll<T>(FeedOptions)

Read all items.

Any provided type, T, is not necessarily enforced by the SDK. You may get more or less properties and it's up to your logic to enforce it.

There is no set schema for JSON items. They may contain any number of custom properties.

Example

Read all items to array.

const {body: containerList} = await items.readAll().fetchAll();
function readAll<T>(options?: FeedOptions): QueryIterator<T>

Parameters

options
FeedOptions

Used for modifying the request (for instance, specifying the partition key).

Returns

readChangeFeed(ChangeFeedOptions)

Warning

This API is now deprecated.

Use changeFeed instead.

Create a ChangeFeedIterator to iterate over pages of changes

function readChangeFeed(changeFeedOptions?: ChangeFeedOptions): ChangeFeedIterator<any>

Parameters

changeFeedOptions
ChangeFeedOptions

Returns

readChangeFeed(PartitionKey, ChangeFeedOptions)

Warning

This API is now deprecated.

Use changeFeed instead.

Create a ChangeFeedIterator to iterate over pages of changes

Example

Read from the beginning of the change feed.

const iterator = items.readChangeFeed({ startFromBeginning: true });
const firstPage = await iterator.fetchNext();
const firstPageResults = firstPage.result
const secondPage = await iterator.fetchNext();
function readChangeFeed(partitionKey: PartitionKey, changeFeedOptions?: ChangeFeedOptions): ChangeFeedIterator<any>

Parameters

partitionKey
PartitionKey
changeFeedOptions
ChangeFeedOptions

Returns

readChangeFeed<T>(ChangeFeedOptions)

Warning

This API is now deprecated.

Use changeFeed instead.

Create a ChangeFeedIterator to iterate over pages of changes

function readChangeFeed<T>(changeFeedOptions?: ChangeFeedOptions): ChangeFeedIterator<T>

Parameters

changeFeedOptions
ChangeFeedOptions

Returns

readChangeFeed<T>(PartitionKey, ChangeFeedOptions)

Warning

This API is now deprecated.

Use changeFeed instead.

Create a ChangeFeedIterator to iterate over pages of changes

function readChangeFeed<T>(partitionKey: PartitionKey, changeFeedOptions?: ChangeFeedOptions): ChangeFeedIterator<T>

Parameters

partitionKey
PartitionKey
changeFeedOptions
ChangeFeedOptions

Returns

upsert(unknown, RequestOptions)

Upsert an item.

There is no set schema for JSON items. They may contain any number of custom properties.

function upsert(body: unknown, options?: RequestOptions): Promise<ItemResponse<ItemDefinition>>

Parameters

body

unknown

Represents the body of the item. Can contain any number of user defined properties.

options
RequestOptions

Used for modifying the request (for instance, specifying the partition key).

Returns

upsert<T>(T, RequestOptions)

Upsert an item.

Any provided type, T, is not necessarily enforced by the SDK. You may get more or less properties and it's up to your logic to enforce it.

There is no set schema for JSON items. They may contain any number of custom properties.

function upsert<T>(body: T, options?: RequestOptions): Promise<ItemResponse<T>>

Parameters

body

T

Represents the body of the item. Can contain any number of user defined properties.

options
RequestOptions

Used for modifying the request (for instance, specifying the partition key).

Returns

Promise<ItemResponse<T>>