Setup

To use the Items API, install the @wix/data package using npm or Yarn:

Copy

or

Copy

Then import { items } from @wix/data:

Copy
Did this help?

aggregateDataItems( )


Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Runs an aggregation on a data collection and returns the resulting list of items.

An aggregation enables you to perform certain calculations on your collection data, or on groups of items that you define, to retrieve meaningful summaries. You can also add paging, filtering, and sorting preferences to your aggregation to retrieve exactly what you need.

Authentication
  • When developing websites or building an app with Blocks, this method may require elevated permissions, depending on the identity of the user calling it and the calling user’s permissions.
  • When building apps without Blocks or for headless projects, you can only call this method directly when authenticated as a Wix app or Wix user identity. When authenticated as a different identity, you can call this method using elevation.
  • Elevation permits users to call methods they typically cannot access. Therefore, you should only use it intentionally and securely.
Permissions
Manage All Data Resources
Manage Data Items
Read Data Items
Learn more about app permissions.
Method Declaration
Copy
Method Parameters
optionsAggregateDataItemsOptions

Options for running an aggregation.

Returns
Return Type:Promise<AggregateDataItemsResponse>
JavaScript
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

bulkInsertDataItemReferences( )


Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Inserts one or more references in the specified fields of items in a collection.

This endpoint adds one or more references to a collection. Each new reference in options.dataItemReferences specifies a referring item's ID, the field in which to insert the reference, and the ID of the referenced item.

Authentication
  • When developing websites or building an app with Blocks, this method may require elevated permissions, depending on the identity of the user calling it and the calling user’s permissions.
  • When building apps without Blocks or for headless projects, you can only call this method directly when authenticated as a Wix app or Wix user identity. When authenticated as a different identity, you can call this method using elevation.
  • Elevation permits users to call methods they typically cannot access. Therefore, you should only use it intentionally and securely.
Permissions
Manage All Data Resources
Manage Data Items
Write Data Items
Learn more about app permissions.
Method Declaration
Copy
Method Parameters
optionsBulkInsertDataItemReferencesOptions

Options for inserting one or more references.

Returns
Return Type:Promise<BulkInsertDataItemReferencesResponse>
JavaScript
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

bulkInsertDataItems( )


Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Adds multiple items to a collection.

When each item is inserted into a collection, its ID is automatically assigned a random value. You can optionally provide your own ID when inserting the item. If you specify an ID that already exists in the collection, the insertion will fail.

Authentication
  • When developing websites or building an app with Blocks, this method may require elevated permissions, depending on the identity of the user calling it and the calling user’s permissions.
  • When building apps without Blocks or for headless projects, you can only call this method directly when authenticated as a Wix app or Wix user identity. When authenticated as a different identity, you can call this method using elevation.
  • Elevation permits users to call methods they typically cannot access. Therefore, you should only use it intentionally and securely.
Permissions
Manage All Data Resources
Manage Data Items
Write Data Items
Learn more about app permissions.
Method Declaration
Copy
Method Parameters
optionsBulkInsertDataItemsOptions

Options for adding multiple items to a collection.

Returns
Return Type:Promise<BulkInsertDataItemsResponse>
JavaScript
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

bulkRemoveDataItemReferences( )


Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Removes one or more references.

Authentication
  • When developing websites or building an app with Blocks, this method may require elevated permissions, depending on the identity of the user calling it and the calling user’s permissions.
  • When building apps without Blocks or for headless projects, you can only call this method directly when authenticated as a Wix app or Wix user identity. When authenticated as a different identity, you can call this method using elevation.
  • Elevation permits users to call methods they typically cannot access. Therefore, you should only use it intentionally and securely.
Permissions
Manage All Data Resources
Manage Data Items
Write Data Items
Learn more about app permissions.
Method Declaration
Copy
Method Parameters
optionsBulkRemoveDataItemReferencesOptionsRequired

Options for removing one or more references.

Returns
Return Type:Promise<BulkRemoveDataItemReferencesResponse>
JavaScript
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

bulkRemoveDataItems( )


Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Removes multiple items from a collection.

If any items in other collections reference the removed items in reference or multi-reference fields, those fields are cleared.

Note: Once an item has been removed from a collection, it can't be restored.

Authentication
  • When developing websites or building an app with Blocks, this method may require elevated permissions, depending on the identity of the user calling it and the calling user’s permissions.
  • When building apps without Blocks or for headless projects, you can only call this method directly when authenticated as a Wix app or Wix user identity. When authenticated as a different identity, you can call this method using elevation.
  • Elevation permits users to call methods they typically cannot access. Therefore, you should only use it intentionally and securely.
Permissions
Manage All Data Resources
Manage Data Items
Write Data Items
Learn more about app permissions.
Method Declaration
Copy
Method Parameters
optionsBulkRemoveDataItemsOptions

Options for removing multiple items from a collection.

Returns
Return Type:Promise<BulkRemoveDataItemsResponse>
JavaScript
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

bulkSaveDataItems( )


Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Inserts or updates multiple items in a collection.

This function inserts or updates each item provided, depending on whether it already exists in the collection. For each item:

  • If you don't provide an ID, a new item is created.

  • If you provide an ID that doesn't exist in the collection, a new item is created with that ID.

  • If an item with the ID you provide already exists in the collection, that item is updated. When an item is updated, its data._updatedDate field is changed to the current date and time.

Note: When you provide an item with an ID that already exists in the collection, the item you provide completely replaces the existing item with that ID. This means that all of the item's previous fields and values are lost.

Authentication
  • When developing websites or building an app with Blocks, this method may require elevated permissions, depending on the identity of the user calling it and the calling user’s permissions.
  • When building apps without Blocks or for headless projects, you can only call this method directly when authenticated as a Wix app or Wix user identity. When authenticated as a different identity, you can call this method using elevation.
  • Elevation permits users to call methods they typically cannot access. Therefore, you should only use it intentionally and securely.
Permissions
Manage All Data Resources
Manage Data Items
Write Data Items
Learn more about app permissions.
Method Declaration
Copy
Method Parameters
optionsBulkSaveDataItemsOptions

Options for saving multiple items in a collection.

Returns
Return Type:Promise<BulkSaveDataItemsResponse>
JavaScript
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

bulkUpdateDataItems( )


Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Updates multiple items in a collection.

This function replaces each specified data item's existing data with the payload provided in the request.

Each item in the request must include an ID. If an item is found in the specified collection with the same ID, that item is updated. If the collection doesn't contain an item with that ID, the update fails.

When an item is updated, its data._updatedDate field is changed to the current date and time.

Note: After each item is updated, it only contains the fields included in the request. If the existing item has fields with values and those fields aren't included in the updated item, their values are lost.

Authentication
  • When developing websites or building an app with Blocks, this method may require elevated permissions, depending on the identity of the user calling it and the calling user’s permissions.
  • When building apps without Blocks or for headless projects, you can only call this method directly when authenticated as a Wix app or Wix user identity. When authenticated as a different identity, you can call this method using elevation.
  • Elevation permits users to call methods they typically cannot access. Therefore, you should only use it intentionally and securely.
Permissions
Manage All Data Resources
Manage Data Items
Write Data Items
Learn more about app permissions.
Method Declaration
Copy
Method Parameters
optionsBulkUpdateDataItemsOptions

Options for updating multiple items in a collection.

Returns
Return Type:Promise<BulkUpdateDataItemsResponse>
JavaScript
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

countDataItems( )


Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Counts the number of items in a data collection that match the provided filtering preferences.

Note: When calling countDataItems() following an update to your collection, the result returned may not reflect the most recent changes. If you need the most up-to-date data, set options.consistentRead to true.

Authentication
  • When developing websites or building an app with Blocks, this method may require elevated permissions, depending on the identity of the user calling it and the calling user’s permissions.
  • When building apps without Blocks or for headless projects, you can only call this method directly when authenticated as a Wix app or Wix user identity. When authenticated as a different identity, you can call this method using elevation.
  • Elevation permits users to call methods they typically cannot access. Therefore, you should only use it intentionally and securely.
Permissions
Manage All Data Resources
Manage Data Items
Read Data Items
Learn more about app permissions.
Method Declaration
Copy
Method Parameters
optionsCountDataItemsOptions

Options for counting the number of items in a data collection.

Returns
Return Type:Promise<CountDataItemsResponse>
JavaScript
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

getDataItem( )


Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Retrieves an item from a collection.

Note: When calling getDataItem() following an update to your collection, the data retrieved may not contain the most recent changes. If you need the most up-to-date data, set options.consistentRead to true.

Authentication
  • When developing websites or building an app with Blocks, this method may require elevated permissions, depending on the identity of the user calling it and the calling user’s permissions.
  • When building apps without Blocks or for headless projects, you can only call this method directly when authenticated as a Wix app or Wix user identity. When authenticated as a different identity, you can call this method using elevation.
  • Elevation permits users to call methods they typically cannot access. Therefore, you should only use it intentionally and securely.
Permissions
Manage All Data Resources
Manage Data Items
Read Data Items
Learn more about app permissions.
Method Declaration
Copy
Method Parameters
dataItemIdstringRequired

ID of the data item to retrieve.


optionsGetDataItemOptions

Options for retrieving an item from a collection.

Returns
Return Type:Promise<DataItem>
JavaScript
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

insertDataItem( )


Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Adds an item to a collection.

An item can only be inserted into an existing connection. You can create a new collection using the Data Collections API.

When an item is inserted into a collection, the item's ID is automatically assigned a random value. You can optionally provide a custom ID in dataItem.id when inserting the item. If you specify an ID that already exists in the collection, the insertion will fail.

If options.dataItem.data is empty, a new item is created with no data fields.

Authentication
  • When developing websites or building an app with Blocks, this method may require elevated permissions, depending on the identity of the user calling it and the calling user’s permissions.
  • When building apps without Blocks or for headless projects, you can only call this method directly when authenticated as a Wix app or Wix user identity. When authenticated as a different identity, you can call this method using elevation.
  • Elevation permits users to call methods they typically cannot access. Therefore, you should only use it intentionally and securely.
Permissions
Manage All Data Resources
Manage Data Items
Write Data Items
Learn more about app permissions.
Method Declaration
Copy
Method Parameters
optionsInsertDataItemOptions

Options for adding an item to a collection.

Returns
Return Type:Promise<InsertDataItemResponse>
JavaScript
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

insertDataItemReference( )


Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Inserts a reference in the specified field in an item in a collection.

A reference in options.dataItemReference specifies a referring item's ID, the field in which to insert the reference, and the ID of the referenced item.

Authentication
  • When developing websites or building an app with Blocks, this method may require elevated permissions, depending on the identity of the user calling it and the calling user’s permissions.
  • When building apps without Blocks or for headless projects, you can only call this method directly when authenticated as a Wix app or Wix user identity. When authenticated as a different identity, you can call this method using elevation.
  • Elevation permits users to call methods they typically cannot access. Therefore, you should only use it intentionally and securely.
Permissions
Manage All Data Resources
Manage Data Items
Write Data Items
Learn more about app permissions.
Method Declaration
Copy
Method Parameters
optionsInsertDataItemReferenceOptions

Options for inserting a reference.

Returns
Return Type:Promise<InsertDataItemReferenceResponse>
JavaScript
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

isReferencedDataItem( )


Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Checks whether a field in a referring item contains a reference to a specified item.

Note: When calling isReferencedDataItem() following an update to your collection, the result returned may not reflect the most recent changes. If you need the most up-to-date data, set options.consistentRead to true.

Authentication
  • When developing websites or building an app with Blocks, this method may require elevated permissions, depending on the identity of the user calling it and the calling user’s permissions.
  • When building apps without Blocks or for headless projects, you can only call this method directly when authenticated as a Wix app or Wix user identity. When authenticated as a different identity, you can call this method using elevation.
  • Elevation permits users to call methods they typically cannot access. Therefore, you should only use it intentionally and securely.
Permissions
Manage All Data Resources
Manage Data Items
Read Data Items
Learn more about app permissions.
Method Declaration
Copy
Method Parameters
optionsIsReferencedDataItemOptions

Options for checking whether a field contains a reference to an item.

Returns
Return Type:Promise<IsReferencedDataItemResponse>
JavaScript
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

queryDataItems( )


Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Creates a query to retrieve items from a database collection.

The queryDataItems() function builds a query to retrieve data items from a collection and returns a DataItemsQueryBuilder object.

The returned object contains the query definition which is typically used to run the query using the find() function.

You can refine the query by chaining DataItemsQueryBuilder functions onto the query. DataItemsQueryBuilder functions enable you to sort, filter, and control the results that queryDataItems() returns.

The queryDataItems() function runs with the following DataItemsQueryBuilder defaults that you can override:

  • skip: 0
  • limit: 50
  • descending: by _createdDate

The functions that are chained to queryDataItems() are applied in the order they are called. For example, if you sort on an age field in ascending order and then on a name field in descending order, the results are sorted first by the age of the items and then, if there are multiple results with the same age, the items are sorted by name in descending order, per age value.

If the collection that you are querying has references to other collections, by default the data from referenced collections is not retrieved. To get the data from referenced items, specify them in the options.includeReferencedItems parameter.

Note: When calling queryDataItems() following an update to your collection, the data retrieved may not contain the most recent changes. If you need the most up-to-date data, set options.consistentRead to true.

Authentication
  • When developing websites or building an app with Blocks, this method may require elevated permissions, depending on the identity of the user calling it and the calling user’s permissions.
  • When building apps without Blocks or for headless projects, you can only call this method directly when authenticated as a Wix app or Wix user identity. When authenticated as a different identity, you can call this method using elevation.
  • Elevation permits users to call methods they typically cannot access. Therefore, you should only use it intentionally and securely.
Permissions
Manage All Data Resources
Manage Data Items
Read Data Items
Learn more about app permissions.
Method Declaration
Copy
Method Parameters
optionsQueryDataItemsOptions

Options for querying data items.

Returns
JavaScript
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

queryDistinctValues( )


Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Retrieves a list of distinct values for a given field in all items that match a query, without duplicates.

As with queryDataItems(), this endpoint retrieves items based on the filtering, sorting, and paging preferences you provide. However, queryDistinctValues() doesn't return all of the full items that match the query. Rather, it returns all unique values of the field you specify in options.fieldName for items that match the query. If more than one item has the same value for that field, that value appears only once.

For more details on using queries, see API Query Language.

Note: When calling queryDistinctValues() following an update to your collection, the data retrieved may not reflect the most recent changes. If you need the most up-to-date data, set options.consistentRead to true.

Authentication
  • When developing websites or building an app with Blocks, this method may require elevated permissions, depending on the identity of the user calling it and the calling user’s permissions.
  • When building apps without Blocks or for headless projects, you can only call this method directly when authenticated as a Wix app or Wix user identity. When authenticated as a different identity, you can call this method using elevation.
  • Elevation permits users to call methods they typically cannot access. Therefore, you should only use it intentionally and securely.
Permissions
Manage All Data Resources
Manage Data Items
Read Data Items
Learn more about app permissions.
Method Declaration
Copy
Method Parameters
optionsQueryDistinctValuesOptions

Options for querying distinct values.

Returns
Return Type:Promise<QueryDistinctValuesResponse>
JavaScript
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

queryReferencedDataItems( )


Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Retrieves the full items referenced in the specified field of an item.

Reference and multi-reference fields refer to items in different collections. Use this function to retrieve the full details of the referenced items themselves.

For example, suppose you have a Movies collection with an Actors field that contains references to items in a People collection. Querying the Movies collection using queryReferencedDataItems() returns the relevant People items referenced in the Actors field of the specified Movie item. This gives you information from the People collection about each of the actors in the specified movie.

Note: When calling queryReferencedDataItems() following an update to your collection, the data retrieved may not contain the most recent changes. If you need the most up-to-date data, set options.consistentRead to true.

Authentication
  • When developing websites or building an app with Blocks, this method may require elevated permissions, depending on the identity of the user calling it and the calling user’s permissions.
  • When building apps without Blocks or for headless projects, you can only call this method directly when authenticated as a Wix app or Wix user identity. When authenticated as a different identity, you can call this method using elevation.
  • Elevation permits users to call methods they typically cannot access. Therefore, you should only use it intentionally and securely.
Permissions
Manage All Data Resources
Manage Data Items
Read Data Items
Learn more about app permissions.
Method Declaration
Copy
Method Parameters
optionsQueryReferencedDataItemsOptions

Options for querying referenced data items.

Returns
Return Type:Promise<QueryReferencedDataItemsResponse>
JavaScript
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

removeDataItem( )


Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Removes an item from a collection.

If any items in other collections reference the removed item in reference or multi-reference fields, those fields are cleared.

Note: Once an item has been removed from a collection, it can't be restored.

Authentication
  • When developing websites or building an app with Blocks, this method may require elevated permissions, depending on the identity of the user calling it and the calling user’s permissions.
  • When building apps without Blocks or for headless projects, you can only call this method directly when authenticated as a Wix app or Wix user identity. When authenticated as a different identity, you can call this method using elevation.
  • Elevation permits users to call methods they typically cannot access. Therefore, you should only use it intentionally and securely.
Permissions
Manage All Data Resources
Manage Data Items
Write Data Items
Learn more about app permissions.
Method Declaration
Copy
Method Parameters
dataItemIdstringRequired

ID of the item to remove.


optionsRemoveDataItemOptions

Options for removing an item from a collection.

Returns
Return Type:Promise<RemoveDataItemResponse>
JavaScript
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?