Velo: Working with the Data API
Introduction
To learn more about managing your data without using the Data API and how the database is structured, see About Database Collections.
- You must first create a collection in the Editor before you can work with it using the Wix Data API.
- To use the Wix Data API, you need to import wixData.
1//Add the following to the top of your code to import wixData:
2import wixData from 'wix-data';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 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.
1let newCustomer = {
2 name: "Mary",
3 age: 47,
4 _id: "mary.jones@myemail.com",
5 phone: "(345)123-4567",
6 pic: "Mary.jpg",
7 labels: ["female", "adult", "hiking"],
8 relatives: ["husband", "daughter"],
9 purchases: [
10 {item: "watch", material: "gold", price: "2000.00"},
11 {item: "ring", material: "platinum", price: "500.00"},
12 {item: "bracelet", material: "silver", price: "250.00"}
13 ]
14};You would then add this item to your collection with the insert method:
1wixData.insert("Customer", newCustomer);Working with Permissions in Wix Data
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
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. 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:
1wixData.query("Customer")
2 .find()
3 .then( (results) => {
4 console.log(results.items);
5 } );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.
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:
1wixData.query("Customer")
2 .gt("age", 20)
3 .find()
4 .then( (results) => {
5 console.log(results.items);
6 } );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:
1wixData.query("Customer")
2 .gt("age", 20)
3 .hasSome("labels", "Male")
4 .find()
5 .then( (results) => {
6 console.log(results.items);
7 } );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: TheWixDataQueryobject 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 definedskipandlimitvalues.
For example, the following would display the number of results for the query for male customers over the age of 20:
1wixData.query("Customer")
2 .gt("age", 20)
3 .hasSome("labels", "Male")
4 .find()
5 .then( (results) => {
6 console.log(results.totalCount);
7 } );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.
1let femaleRingTwenty;
2
3wixData.query("Customer")
4 .ge("age", 20)
5 .hasSome("labels","Female")
6 .eq("purchases.item", "ring")
7 .limit(15)
8 .find()
9 .then( (results) => {
10 console.log(results.items);
11 femaleRingTwenty = results;
12 } );To display the next page of results, you would call next on the results:
1femaleRingTwenty.next()
2 .then(function(results) {
3 console.log(results.items);
4 femaleRingTwenty = results;
5 } );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:
1let queryResults;
2
3wixData.query("Customer")
4 .ge("age", 20)
5 .hasSome("labels","Female")
6 .eq("purchases.item", "ring")
7 .skip(48)
8 .limit(12)
9 .find()
10 .then ( (results) => {
11 console.log(results.items);
12 queryResults = results;
13 } );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
- Date and Time
- Date
Date
Date and Time
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:
1let newCustomer = {
2 name: "Mary",
3 age: 47,
4 _id: "mary.jones@myemail.com",
5 pic: "Mary.jpg",
6 labels: ["Female", "Adult", "Hiking"],
7 relatives: ["husband", "daughter"],
8 birthday: new Date(1975, 10, 5)
9};
10
11// Use wixData.insert to add a new item to the Customer collection
12let entry = wixData.insert("Customer", newCustomer);1entry.then( (results) => {
2 console.log(results);
3} );1{
2 name: "Mary",
3 age: 47,
4 _id: "mary.jones@myemail.com",
5 pic: "Mary.jpg",
6 labels: ["Female", "Adult", "Hiking"],
7 relatives: ["husband", "daughter"],
8 birthday: "1975-10-05T14:24:20Z",
9 _createdDate: "2004-04-01T01:04:45Z",
10 _UpdatedDate: "2006-02-15T12:35:20Z",
11}1const dateString = "1985-11-23";
2const dateObject = new Date(dateString);1const dateString = dateObject.toISOString().substring(0,10);