About the Data Collections API

The Data Collections API enables you to create, delete, and modify the structure of data collections in a Wix project or site.

Data collections and their structure

Wix projects and sites store data in collections. A collection determines the structure of the data to be stored, defining the fields each item should contain and the data type of each field. You can create and modify collections for a project or site using the Content Management System (CMS). With the Data Collections API, you can also use code to create, modify, and delete collections in a Wix project or site. You can then store and retrieve data in these collections using the Data Items API.

Note: The structure you define for a data collection isn't enforced. This means that if you add or update an item containing a field or data type that doesn't match the collection's structure, your data is stored anyway.

Permissions

Access to a data collection is controlled by its permissions. These permissions are defined in the collection object and they specify which types of user can perform actions on the data contained in the collection.

Wix Data recognizes 4 roles:

  • ADMIN: The site owner.
  • SITE_MEMBER_AUTHOR: A signed-in user who has added content to the collection.
  • SITE MEMBER: Any signed-in user.
  • ANYONE: Any site visitor.

For each of the 4 basic actions (inserting, updating, removing, and reading content) the minimal role required must be set. For example, if you want to allow only site members to view data, and only the site owner to insert, update, and remove data, declare your permissions as follows:

  • insert: ADMIN
  • update: ADMIN
  • remove: ADMIN
  • read: SITE_MEMBER
Was this helpful?
Yes
No

Setup

To use the Collections 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 { collections } from @wix/data:

Copy
1
import { collections } from '@wix/data'
Was this helpful?
Yes
No
createDataCollection( )

Creates a new data collection.

The request body must include an ID, details for at least 1 field, and a permissions object. If any of these are missing, the collection isn't created.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Data Collections
Learn more about permission scopes.
Copy
function createDataCollection(collection: DataCollection): Promise<DataCollection>
Method Parameters
collectionDataCollectionRequired
Collection details.
Returns
Return Type:Promise<DataCollection>
Was this helpful?
Yes
No
deleteDataCollection( )

Deletes a data collection.

Note: Once a collection is deleted, it can't be restored.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Data Collections
Learn more about permission scopes.
Copy
function deleteDataCollection(dataCollectionId: string): Promise<void>
Method Parameters
dataCollectionIdstringRequired
ID of the collection to delete.
Returns
Return Type:Promise<void>
Was this helpful?
Yes
No
getDataCollection( )

Retrieves a data collection by ID.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Data Collections
Learn more about permission scopes.
Copy
function getDataCollection(dataCollectionId: string, options: GetDataCollectionOptions): Promise<DataCollection>
Method Parameters
dataCollectionIdstringRequired
ID of the collection to retrieve.
optionsGetDataCollectionOptions
Options for retrieving a data collection.
Returns
Return Type:Promise<DataCollection>
Was this helpful?
Yes
No
listDataCollections( )

Retrieves a list of all data collections associated with the site or project.

By default, the list is ordered by ID in ascending order.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Data Collections
Learn more about permission scopes.
Copy
function listDataCollections(options: ListDataCollectionsOptions): Promise<ListDataCollectionsResponse>
Method Parameters
optionsListDataCollectionsOptions
Options for retrieving a list of data collections.
Returns
Return Type:Promise<ListDataCollectionsResponse>
Was this helpful?
Yes
No
updateDataCollection( )

Updates a data collection.

A collection ID, revision number, permissions, and at least 1 field must be provided within options.collection. If a collection with that ID exists, and if its current revision number matches the one provided, it is updated. Otherwise, the request fails.

When a collection is updated, its _updatedDate property is changed to the current date and its revision property is incremented.

Note: After a collection is updated, it only contains the properties included in the updateDataCollection() call. If the existing collection has properties with values and those properties aren't included in the updated collection details, their values are lost.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Data Collections
Learn more about permission scopes.
Copy
function updateDataCollection(collection: DataCollection): Promise<DataCollection>
Method Parameters
collectionDataCollectionRequired
Updated collection details. The existing collection is replaced with this version.
Returns
Return Type:Promise<DataCollection>
Was this helpful?
Yes
No