Velo: Working with the Data API
Introduction
The Wix Data API lets you work with your database collections using code and gives you more capabilities than what is available in the editor alone.
To learn more about managing your data without using the Data API and how the database is structured, see About Database Collections.
Wix Data includes functions that enable you to manage the data in existing collections, build queries on collections, and register hooks on different operations.
With the Collections API you can create new collections and manage their structure.
Important:
-
You must first create a collection either in the CMS or by using the Collections API before you can work with it using the Wix Data API.
-
To use the Wix Data API, you need to import the module as follows:
Copy1 -
Wix places quotas on requests made by your site using the Wix Data API. These quotas affect things like 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.
Wix Data API
The Wix Data API allows you to manipulate the data in your collections and retrieve it in meaningful and useful ways. It contains:
wix-data
: Functions that let you query and manipulate the data in your collections.- Hooks: Code you can set to run before or after you interact with a collection. Hooks are added to a collection in the Velo sidebar (Wix Editor) or CMS panel (Wix Studio) when you hover over the collection name. The code for the hooks are written in the data.js file which resides in the backend.
WixDataFilter
: Functions for filtering aWixDataQuery
.WixDataQuery
: An object that contains a query definition and functions that enable you to refine a query.WixDataQueryResult
: An object that contains a query's results, other information about the query, and pagination methods.WixDataSort
: Functions for sorting aWixDataQuery
.
Note: Wix places quotas on data requests made by your site, as well as the amount of data your site can contain. These quotas affect the number of requests your site can make per minute and the amount of time your requests can run for.
Let's say you are building a database of customers who have registered on your online jewelry store. Your registration form would collect basic personal information about each customer. It might also ask customers for other information, such as relatives they may shop for, so you could know when to send them notifications of special offers and sales. You may also want to know about their general interests so that you can provide better purchase suggestions. When a customer makes a purchase, you would save the details of their purchase as well.
An item in your collection may look like this:
1
You would then add this item to your collection with the insert
method:
1
As your customer list grows and your site has more traffic, as well as repeat visits from customers, you would use save()
, update()
, remove()
, and get()
to modify the items in your collection.
It is important to familiarize yourself with the Wix Data model and query()
methods so that you can use the most effective data modeling when you create your collections.
Working with Permissions in Wix Data
When you use Wix Data methods in your Public and Pages files you need to consider the permissions your site visitors will have. Some methods modify data in collections while other methods only read data. Your site visitor needs to have the corresponding permissions for these methods to work. If a method is called with insufficient permissions the method will fail. For more information, see About Database Collection Permissions.
By default, your site visitor's permissions apply to Wix Data methods you call from your backend code also. However, you can call Wix Data methods from backend code without checking permissions by passing the method the WixDataOptions
object as the options
parameter with the property:value pair suppressAuth: true
.
Working with Hooks in Wix Data
The wix-data
module contains hooks that allow you to run code before or after you interact with a collection. See How to Use Data Hooks to learn more.
When a method is called in your code, the system first checks that the method was called with the correct permissions. If you registered hooks to a method, they will run only if the method passes the permissions check.
You can call Wix Data methods from the backend without their registered hooks by passing the options
parameter for the method a WixDataOptions
object with the property:value pair suppressHooks: true
.
Querying Your Collection
A collection of data is only useful if you can retrieve the data in meaningful ways. To query a collection, use the query
method.
By default, query
returns the first 50 items in a collection in descending order of their _createdDate
value. Items that are marked as hidden are not returned. For example, the following query logs to the console the first 50 items in the Customer collection, sorted in descending order of their _createdDate
values:
1
The find()
function is chained to the query, and it runs the query. The find()
function returns a Promise that resolves to a WixDataQueryResult
object. Because find()
returns a Promise, then()
is also chained to the query to display the results.
To display the items that the query returns, use the items
property of the WixDataQueryResult
object.
Request Timeouts
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.
Learn more about request timeouts in Wix Data.
Refining Your Query
To refine the results of a query, chain WixDataQuery
methods to the query. For example, let's say you want to query the Customer collection for all customers over the age of 20. You would chain the gt()
(greater than) function to the query, like this:
1
The query()
function returns a WixDataQuery
object, which contains the definition of the query. Each WixDataQuery
method also returns a WixDataQuery
object. Since they both return the same type of object, you can chain multiple WixDataQuery
methods onto a call to query()
, which further refines the query results.
For example, let's say you want to take the results of the previous query, but return only the male customers. You would add the hasSome
method to your query, with labels
as the paremeterName
and Male
as the value:
1
This adds the gt()
and hasSome()
conditions to the query definition that is stored in the WixDataQuery
object. Now when you call find()
, it uses these conditions to run the query.
Query Results
Query results are returned in a WixDataQueryResult
object. This object has the following properties:
currentPage
: The index (zero-based) of the current results page number.items
: An array that holds the results of the query.length
: The number of items in the current results page.pageSize
: The query page size, based on the defined limit.query
: TheWixDataQuery
object used in the query.totalCount
: The total number of items that match the query.totalPages
: The total number of pages the query produces, based on the definedskip
andlimit
values.
For example, the following would display the number of results for the query for male customers over the age of 20:
1
Pagination
WixDataQueryResult
has next()
and prev()
functions that enable you to easily page forward and backward in your results.
For example, let's say you want to filter the Customer collection for all female customers 20 years or older who have purchased a ring. You also want each page of results to display 15 items. You use the limit
method to limit the number of results a query returns.
1
This displays the first 15 results from the query, starting at the first result and ending at the 15th.
To display the next page of results, you would call next
on the results:
1
The next()
function also returns a Promise, so you chain then()
to the call to next
and log the resolution of the Promise to the console, which returns the 16th through 30th results. Also, assign femaleRingTwenty
the results of next()
so that you can call prev()
or next()
on femaleRingTwenty
to get the previous or next page of results.
Manual Pagination with Prev and Next
The skip()
function enables next()
and prev()
to provide a page of query results that skips the first number of results from the total results that match the query. For example, when you query the collection in the pagination example above, it returns results with a limit()
of 15, but it also has a default skip()
value of 0. This returns the query results starting at the 1st result and ending at the 15th.
When you then call next()
for the first time, it returns results with a skip()
value of 15 and a limit()
of 15. This tells Wix Data to return the query results starting at the 16th result and ending at the 30th result. If you call femaleRingTwenty.next()
again, it returns results with a skip()
value of 30 and a limit of 15, returning results starting at the 31st result and ending at the 45th. When you call prev()
and next()
, they handle changing the skip()
value to match the requested range of results.
You can also manually assign a value to skip()
. This would be useful if you want to enable jumping to a specific page of results without having to use next()
or prev()
multiple times. For example, using the query in the previous example, if you want to get the 5th page of results with 12 results per page, you would query your collection with a skip of 48 (limit * (5-1)) and a limit of 12:
1
This logs the 49th through 60th results. If you then call next()
or prev()
on queryResults
, they return the next or previous 12 results.
Date Fields
Wix Data supports 2 kinds of date fields:
- Date and Time
- Date
These kinds of fields have different data types and should be used differently in your code.
Date
Date fields are represented as strings in ISO 8601 date format (YYY-MM-DD). When you retrieve an item with this kind of field, or write to one, you should use this format.
Date and Time
Date and Time fields are represented as JavaScript Date objects. When working with this type of field, you should use this format. If you assign a Date and Time field a value of an ISO date string, Wix Data treats it as it would any other string.
For example, you can use a JavaScript Date object as the value for a Date and Time field when creating a new Wix Data item. In this example, birthday
is assigned a date:
1
Wix Data always saves Date objects and displays them in the console as a string with a UTC timezone. For example, if you display the results of the previous insert:
1
it logs:
1
If you need to convert one type of date data to the other, you can do the following.
To convert ISO date strings to Date objects:
1
To convert a Date object into an ISO date string:
1
Media Fields
Wix Data supports video, image, and other common media files. One of the collection fields must be the media file's unique Media Manager URL. This URL has a specific format that varies based on media type and file specificiations.
Working with uploaded media using Wix Media V2
Follow these steps to upload and insert media files into your data collection using wix-media.v2
and Axios.
- Import the relevant API modules and packages.
Notes:
- Axios needs to be installed in your site.
- The
wix-media.v2
methods require elevated permissions.
1
- Call
generateFileUploadUrl()
to create and return the upload URL.
1
- Use the Upload API to make an Axios HTTP POST request. The request uploads the media file using the upload URL that was generated in the previous step. Pass in the upload URL as one of the request parameters. A successful request results in the media file being uploaded to your Media Manager.
1
- To get the compatible Media Manager URL, call
getFileDescriptor()
. Pass thefile.id
property from the Upload API's response object as the function's only parameter.
1
- Locate the Media Manager URL in the file descriptor response object. The Media Manager URL is located in the response's
media
property, however, the exact location of the URL depends on the type of media file that was uploaded.
The following table illustrates where the Media Manager URLs are located in the getFileDescriptor()
response object:
Media type | Property name |
---|---|
Audio files | media.audio._id |
Video files | media.video |
Image files | media.image.image |
Document files | media.document |
Vector image files | media.vector.image |
Archive files | media.archive.url |
- Insert the Media Manager URL into your data collection.
1