Setup

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

Copy
1
npm install @wix/data

or

Copy
1
yarn add @wix/data

Then import { items } from @wix/data:

Copy
1
import { items } from '@wix/data'
Was this helpful?
Yes
No

About the Data Items API

The Data Items API allows you to access and manage items in a Wix site or project's data collections.

With the Data Items API, you can:

  • Create and manage data items in a project or site's collections.
  • Retrieve data items from a collection individually or with filtering and sorting queries.
  • Create and manage reference fields.
  • Perform aggregations and calculations on data in collections.
  • Truncate a data collection, removing all its contents.

The Data Items API only works with existing collections. To create and manage data collections, use the Data Collections API.

Before you begin

It's important to note the following points before starting to code:

  • The maximum size of an item you can save to a collection is 500 kb.
  • We don't recommend updating a data item more than once per second.
  • When using data retrieval functions such as queryDataItems() or getDataItem() following an update to a collection's data, the data retrieved may not yet contain the most recent changes. See Wix Data and Eventual Consistency for more information and instructions for overriding this.
  • When querying Wix App Collections, check which fields can be filtered in the relevant collection field article.
  • Updating a data item replaces the existing item entirely. If the existing item had fields with values and those fields aren't included in the updated item, the values in those properties are lost.
  • Aggregations can't be performed on Wix App collections.
  • After connecting external database collections to a Wix site using the External Database Connections API, you can use the Data Items API to manage and retrieve data from those collections as if they were Wix Data collections.
Was this helpful?
Yes
No

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.

Permission Scopes

For app development, you must have one of the following permission scopes:
Read Data Items
Learn more about permission scopes.
Params
optionsAggregateDataItemsOptions
Options for running an aggregation.
Response Object
AggregateDataItemsResponse
Was this helpful?
Yes
No

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.

Permission Scopes

For app development, you must have one of the following permission scopes:
Write Data Items
Learn more about permission scopes.
Params
optionsBulkInsertDataItemReferencesOptions
Options for inserting one or more references.
Response Object
BulkInsertDataItemReferencesResponse
Was this helpful?
Yes
No

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.

Permission Scopes

For app development, you must have one of the following permission scopes:
Write Data Items
Learn more about permission scopes.
Params
optionsBulkInsertDataItemsOptions
Options for adding multiple items to a collection.
Response Object
BulkInsertDataItemsResponse
Was this helpful?
Yes
No

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.

Permission Scopes

For app development, you must have one of the following permission scopes:
Write Data Items
Learn more about permission scopes.
Params
optionsBulkRemoveDataItemReferencesOptionsRequired
Options for removing one or more references.
Response Object
BulkRemoveDataItemReferencesResponse
Was this helpful?
Yes
No

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.

Permission Scopes

For app development, you must have one of the following permission scopes:
Write Data Items
Learn more about permission scopes.
Params
optionsBulkRemoveDataItemsOptionsRequired
Options for removing multiple items from a collection.
Response Object
BulkRemoveDataItemsResponse
Was this helpful?
Yes
No

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.

Permission Scopes

For app development, you must have one of the following permission scopes:
Write Data Items
Learn more about permission scopes.
Params
optionsBulkSaveDataItemsOptions
Options for saving multiple items in a collection.
Response Object
BulkSaveDataItemsResponse
Was this helpful?
Yes
No

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.

Permission Scopes

For app development, you must have one of the following permission scopes:
Write Data Items
Learn more about permission scopes.
Params
optionsBulkUpdateDataItemsOptions
Options for updating multiple items in a collection.
Response Object
BulkUpdateDataItemsResponse
Was this helpful?
Yes
No

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.

Permission Scopes

For app development, you must have one of the following permission scopes:
Read Data Items
Learn more about permission scopes.
Params
optionsCountDataItemsOptions
Options for counting the number of items in a data collection.
Response Object
CountDataItemsResponse
Was this helpful?
Yes
No

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.

Permission Scopes

For app development, you must have one of the following permission scopes:
Read Data Items
Learn more about permission scopes.
Params
dataItemIdstringRequired
ID of the data item to retrieve.

optionsGetDataItemOptions
Options for retrieving an item from a collection.
Response Object
DataItem
Was this helpful?
Yes
No

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.

Permission Scopes

For app development, you must have one of the following permission scopes:
Write Data Items
Learn more about permission scopes.
Params
optionsInsertDataItemOptionsRequired
Options for adding an item to a collection.
Response Object
InsertDataItemResponse
Was this helpful?
Yes
No

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.

Permission Scopes

For app development, you must have one of the following permission scopes:
Write Data Items
Learn more about permission scopes.
Params
optionsInsertDataItemReferenceOptions
Options for inserting a reference.
Response Object
InsertDataItemReferenceResponse
Was this helpful?
Yes
No

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.

Permission Scopes

For app development, you must have one of the following permission scopes:
Read Data Items
Learn more about permission scopes.
Params
optionsIsReferencedDataItemOptions
Options for checking whether a field contains a reference to an item.
Response Object
IsReferencedDataItemResponse
Was this helpful?
Yes
No

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.

Permission Scopes

For app development, you must have one of the following permission scopes:
Read Data Items
Learn more about permission scopes.
Params
optionsQueryDataItemsOptions
Options for querying data items.
Response Object
DataItemsQueryBuilder
Was this helpful?
Yes
No

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.

Permission Scopes

For app development, you must have one of the following permission scopes:
Read Data Items
Learn more about permission scopes.
Params
optionsQueryDistinctValuesOptions
Options for querying distinct values.
Response Object
QueryDistinctValuesResponse
Was this helpful?
Yes
No

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.

Permission Scopes

For app development, you must have one of the following permission scopes:
Read Data Items
Learn more about permission scopes.
Params
optionsQueryReferencedDataItemsOptions
Options for querying referenced data items.
Response Object
QueryReferencedDataItemsResponse
Was this helpful?
Yes
No

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.

Permission Scopes

For app development, you must have one of the following permission scopes:
Write Data Items
Learn more about permission scopes.
Params
dataItemIdstringRequired
ID of the item to remove.

optionsRemoveDataItemOptionsRequired
Options for removing an item from a collection.
Response Object
RemoveDataItemResponse
Was this helpful?
Yes
No

removeDataItemReference( )

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 the specified reference from the specified field.

Permission Scopes

For app development, you must have one of the following permission scopes:
Write Data Items
Learn more about permission scopes.
Params
optionsRemoveDataItemReferenceOptionsRequired
Options for removing a reference.
Response Object
RemoveDataItemReferenceResponse
Was this helpful?
Yes
No

replaceDataItemReferences( )

Developer Preview

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

Replaces references in a specified field of a specified data item.

This function replaces the existing reference or references contained in the field specified in options.referringItemFieldName within the data item specified in options.referringItemId. The function removes existing references and in their place it adds references to the items specified in options.newReferencedItemIds.

Note: If you pass an empty array in options.newReferencedItemIds, all existing references are removed.

Permission Scopes

For app development, you must have one of the following permission scopes:
Write Data Items
Learn more about permission scopes.
Params
optionsReplaceDataItemReferencesOptions
Options for replacing references.
Response Object
ReplaceDataItemReferencesResponse
Was this helpful?
Yes
No

saveDataItem( )

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 an item in a collection.

The saveDataItem() function inserts or updates the specified item, depending on whether it already exists in the collection.

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

  • If you provide an ID that does not 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 payload you provide in options.dataItem.data replaces the existing item with that ID. This means that the item's previous fields and values are lost.

Permission Scopes

For app development, you must have one of the following permission scopes:
Write Data Items
Learn more about permission scopes.
Params
optionsSaveDataItemOptionsRequired
Options for saving an item in a collection.
Response Object
SaveDataItemResponse
Was this helpful?
Yes
No

truncateDataItems( )

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 all 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 items have been removed from a collection, they can't be restored.

Permission Scopes

For app development, you must have one of the following permission scopes:
Write Data Items
Learn more about permission scopes.
Params
optionsTruncateDataItemsOptionsRequired
Options for truncating data items from a collection.
Response Object
void
Was this helpful?
Yes
No

updateDataItem( )

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 an item in a collection.

This function replaces the data item's existing data with the payload provided in options.dataItem.data in the request.

To update an item, you need to specify an item ID and a collection ID. If an item is found in the specified collection with the specified ID, that item is updated. If the collection doesn't contain an item with that ID, the request fails.

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

Note: After an item is updated, it only contains the fields included in the options.dataItem.data payload in the updateDataItem() call. If the existing item has fields with values and those fields aren't included in the updated item, their values are lost.

Permission Scopes

For app development, you must have one of the following permission scopes:
Write Data Items
Learn more about permission scopes.
Params
_idstringRequired
Data item ID.

optionsUpdateDataItemOptionsRequired
Options for updating an item in a collection.
Response Object
UpdateDataItemResponse
Was this helpful?
Yes
No