Introduction

The Data API allows you to interact programmatically with your site's database collections.

With the Data API, you can:

• Manage the data in your site's collections.
• Filter, sort, and query your data.
• Intercept interactions with your collections using data hooks.
• Work programmatically with reference fields.
• Aggregate data from your collections.

For more information, see Working with the Data API and Overview of the Wix Data and Wix Dataset APIs.

Get hands-on experience with the Data API on our Hello Data example page.

To use the data module, import wixData from the wix-data module:

Before you begin

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

• The Data API can be used in your site’s frontend or backend code.

• The maximum size of an item that you can save to a collection is 500 kb.

• When using data retrieval methods such as query() or get() following a change to your database collection, the data retrieved may not yet contain your most recent changes. See Wix-data and Eventual Consistency for more information.

• When querying Wix App Collections, check which fields can be filtered in the relevant collection field article.

• When your site makes a data request, it may take some time to receive a response. Wix Data places limits on how long a response can take before the request times out. If the response time exceeds this limit, Wix Data returns an error instead of the intended result.

• Updating a collection item replaces the existing database item. If the existing item had properties with values and those properties are not included in the updated item, the values in those properties are lost.

• Aggregations can only be used on collections you created. They cannot be used on Wix App Collections.

• Some functions don't apply to Single Item Collections.

• Depending on the permissions defined for your database collection, your site visitors may not have the permissions required to run a specific function. A function called with insufficient permissions will fail. When necessary, you can override permission checks in backend code by using the SuppressAuth option.

• You can connect external database collections to your Wix site and use any of the Wix Data APIs to manage and retrieve data from those collections.

Terminology

• Aggregate: Perform calculations on collection data to retrieve meaningful summaries.

• Distinct: Function that returns the distinct values that match a query, without duplicates.

• Hooks: Hooks run code before or after certain interactions with your site's collections, sometimes allowing you to interact with the data handled in the interaction. For example, you can use the beforeInsert() hook to capitalize text before it's inserted into a collection.

• Query: Retrieve information from a database.

• Reference field: Fields in a database collection that let you link one collection with other collections. Specifically, a reference field associates an item in one collection with an item in a different collection.

• Truncate: Removes all items from a collection.

Data Types

The Wix Data API works with a schemaless database behind the scenes. In theory, you can store any type of data in any database collection field. In practice, each collection has a non-enforced schema that you should conform to. This schema is used to determine which page elements can connect to which fields and to provide a better experience in the Content Management System (CMS). For example, if you set a field's type to Date and Time, you can then connect that field to elements that work with dates, such as DatePicker and Text elements. Also, in the CMS, values will appear as dates and you can add new values using a date picker.

The following is a list of the field types from database collections and their corresponding JavaScript data types. When you retrieve data from a collection, that data will be represented in the JavaScript data types that correspond to your collection's field types. When you add or update data in a collection, you should provide the data using the JavaScript data types that correspond to your collection's field types.

Wix Data and Eventual Consistency

Wix Data stores your data in a primary database instance, as well as several geographically dispersed mirror instances. The wix-data API is eventually consistent, meaning that it always updates your data in the primary database instance first, then propagates your changes to the mirror instances. When you update your database collection, there may be a short delay (typically a few seconds) until all mirror instances are up to date with your recent changes.

When you call a data retrieval function, your request goes to the closest mirror database instance. This saves time, as the request and response don't have to travel as far. However, if you attempt to retrieve data shortly after updating it, your latest changes may not yet be reflected in the data you get back. For example, initially wixData.get('Collection', 'x'); may resolve to null following wixData.insert('Collection', { _id: 'x' });.

If you need a data retrieval function to get fully up-to-date data immediately after an update, you can set the consistentRead property in the options parameter to true. This slows down the operation but ensures the data is retrieved from the up-to-date primary database instance.

Data Quotas

Wix places quotas on requests made by your site using the wix-data API. These quotas affect the number of requests your site can make per minute and the amount of time your requests can run for. Learn more about data quotas and how to work with them.