aggregate( )


Creates an aggregation.

The aggregate() function builds an aggregation on the specified collection and returns a WixDataAggregate object.

The returned object contains the aggregate definition which is typically used to run the aggregation using the run() function.

You can refine the aggregation by chaining WixDataAggregate functions on to the aggregate.

The aggregate() function runs with the following WixDataAggregate defaults that you can override:

Method Declaration
Copy
function aggregate(collectionId: string): WixDataAggregate;
Method Parameters
collectionIdstringRequired

The ID of the collection to run the aggregation on.

To find your collectionId, select the Databases tab in the Velo Sidebar. Hover over your collection, click the three dots, and select Edit Settings.

Returns
Return Type:WixDataAggregate
JavaScript
aggregate .run() .then((results) => { if (results.items.length > 0) { let items = results.items; let numItems = results.length; let hasNext = results.hasNext(); } else { // handle case where no matching items found } }) .catch((error) => { let errorMsg = error.message; let code = error.code; });
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

bulkInsert( )


Adds a number of items to a collection.

The bulkInsert() function returns a Promise that resolves after the items have been added to the specified collection. The Promise is rejected if the current user does not have "create" permissions for the collection. Items are skipped if they include an _id property whose value matches an existing ID in the collection. Meaning, bulkInsert() cannot overwrite an existing item in the collection.

Calling the bulkInsert() function triggers the beforeInsert() and afterInsert() hooks for each item that is inserted if the hooks have been defined.

Use the options parameter to run bulkInsert() from backend code without checking for permissions or without its registered hooks.

When inserting items into a collection that has a reference field, set the values of the reference fields to the referenced item's _id value or the entire referenced item object.

The bulkInsert() function adds the following properties and values to the item when it adds it to the collection:

  • _id: A unique identifier for an item in a collection, if the item doesn't have one or has one that is undefined. You can optionally provide your own ID. Once an ID is assigned to an item it cannot be changed.
  • _createdDate: The date the item was added to the collection.
  • _updatedDate: The date the item was modified. When the item is first added, the createdDate and updatedDate are the same.

Any valid JavaScript object can be added as a property value. The bulkInsert() function maintains the structure of the specified object. For example, objects that contain nested objects, Arrays, or Arrays with nested objects are all added to the collection as defined.

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

Notes:

  • If an item's _id property value is set to null or an empty string, an error is thrown.
  • Bulk operations are limited to 1000 items per function call.
  • The bulkInsert() function is not supported for Single Item Collections.
  • The bulkInsert() function does not support multi-reference fields. For multi-reference fields, use insertReference().
  • Translatable collections do not allow insertion and modification of items when working in a non-primary language. For example, if a collection's primary language is English, and the site visitor is viewing the site in French, calling bulkInsert() will fail and issue an error.
Method Declaration
Copy
function bulkInsert(
  collectionId: string,
  items: Array<object>,
  options: WixDataOptions,
): Promise<WixDataBulkResult>;
Method Parameters
collectionIdstringRequired

The ID of the collection to add the item to.

The array must contain at least one item. Passing an empty array returns an error.

To find your collectionId, select the Databases tab in the Velo Sidebar. Hover over your collection, click the three dots, and select Edit Settings.


itemsArray<object>Required

The items to add.


optionsWixDataOptions

An object containing options to use when processing this operation.

Returns
Return Type:Promise<WixDataBulkResult>
JavaScript
import wixData from "wix-data"; // ... let toInsert1 = { title: "Mr.", first_name: "John", last_name: "Doe", }; let toInsert2 = { title: "Ms.", first_name: "Jane", last_name: "Doe", }; wixData .bulkInsert("myCollection", [toInsert1, toInsert2]) .then((results) => { let inserted = results.inserted; // 2 let insertedIds = results.insertedItemIds; // see below let updated = results.updated; // 0 let skipped = results.skipped; // 0 let errors = results.errors; // [] }) .catch((err) => { let errorMsg = err; }); /* insertedIds is: * * [ * "d9ea65a6-726a-4c3e-b97d-1128c0a06b5f", * "472c1da9-e5e4-4620-8ee3-962e9d1a7df5" * ] */
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

bulkRemove( )


Removes a number of items from a collection.

The bulkRemove() function returns a Promise that resolves after the items have been removed from the specified collection. The Promise is rejected if the current user does not have "delete" permissions for the collection. If the delete permissions for the collection are set to Site member author, the only items that will be deleted are those for which the current user is the owner. All other items will be skipped.

Calling the bulkRemove() function triggers the beforeRemove() and afterRemove() hooks for each item that is deleted if the hooks have been defined.

Use the options parameter to run bulkRemove() from backend code without checking for permissions or without its registered hooks.

Notes:

  • The bulkRemove() function also clears multiple-item reference fields for items in collections referenced by the specified items. For example, suppose you have a Movies collection with an Actors field that contains multiple references to items in a People collection. Removing items in the Movies collection also clears the data in the corresponding multiple-item reference fields in the People collection.

  • Bulk operations are limited to 1000 items per function call.

Method Declaration
Copy
function bulkRemove(
  collectionId: string,
  itemIds: Array<string>,
  options: WixDataOptions,
): Promise<WixDataBulkRemoveResult>;
Method Parameters
collectionIdstringRequired

The ID of the collection to remove the items from.

To find your collectionId, select the Databases tab in the Velo Sidebar. Hover over your collection, click the three dots, and select Edit Settings.


itemIdsArray<string>Required

IDs of the items to remove.

The array must contain at least one item. Passing an empty array returns an error.


optionsWixDataOptions

An object containing options to use when processing this operation.

Returns
Return Type:Promise<WixDataBulkRemoveResult>
JavaScript
import wixData from "wix-data"; // ... let toRemove = ["00001", "00003", "00004"]; wixData .bulkRemove("myCollection", toRemove) .then((results) => { let removed = results.removed; // 2 let removedIds = results.removedItemIds; // see below let skipped = results.skipped; // 0 }) .catch((err) => { let errorMsg = err; }); /* removedIds is: * * [ * "00001", * "00002", * "00003" * ] */
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

bulkSave( )


Inserts or updates a number of items in a collection.

The bulkSave() function returns a Promise that resolves after the items have been added or updated in the specified collection. The Promise is rejected if the current user does not have the necessary permissions for the collection.

The bulkSave() function inserts or updates the specified items, depending on whether they already exist in the collection. It compares the _id property value of the specified items with the _id property values of the items in the specified collection.

  • If an item in the collection has the specified _id value, bulkSave() uses update() to update the item in the collection, triggering the beforeUpdate() and afterUpdate() hooks for that item if they have been defined.
  • If none of the items in the collection contain that _id value, the specified item does not have an _id property, or if the specified item's _id property is undefined, bulkSave() uses insert() to add the specified item into the collection. This triggers the beforeInsert() and afterInsert() hooks for that item if they have been defined.

Use the options parameter to run bulkSave() from backend code without checking for permissions or without its registered hooks.

When saving items to a collection that has a reference field, set the values of the reference fields to the referenced item's _id value or the entire referenced item object.

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

Notes:

  • If an item's _id property value is set to null or an empty string, an error is thrown.
  • Bulk operations are limited to 1000 items per function call.
  • The bulkSave() function is not supported for Single Item Collections.
  • The bulkSave() function does not support multi-reference fields. For multi-reference fields, use replaceReferences() or insertReference().
  • Translatable collections do not allow insertion and modification of items when working in a non-primary language. For example, if a collection's primary language is English, and the site visitor is viewing the site in French, calling bulkSave() will fail and issue an error.
Method Declaration
Copy
function bulkSave(
  collectionId: string,
  items: Array<object>,
  options: WixDataOptions,
): Promise<WixDataBulkResult>;
Method Parameters
collectionIdstringRequired

The ID of the collection to save the item to.

To find your collectionId, select the Databases tab in the Velo Sidebar. Hover over your collection, click the three dots, and select Edit Settings.


itemsArray<object>Required

The items to insert or update.

The array must contain at least one item. Passing an empty array returns an error.


optionsWixDataOptions

An object containing options to use when processing this operation.

Returns
Return Type:Promise<WixDataBulkResult>
JavaScript
import wixData from "wix-data"; // ... let toSave1 = { title: "Mr.", first_name: "John", last_name: "Doe", }; let toSave2 = { title: "Ms.", first_name: "Jane", last_name: "Doe", }; wixData .bulkSave("myCollection", [toSave1, toSave2]) .then((results) => { let inserted = results.inserted; // 2 let insertedIds = results.insertedItemIds; // see below let updated = results.updated; // 0 let skipped = results.skipped; // 0 let errors = results.errors; // [] }) .catch((err) => { let errorMsg = err; }); /* insertedIds is: * * [ * "d9ea65a6-726a-4c3e-b97d-1128c0a06b5f", * "472c1da9-e5e4-4620-8ee3-962e9d1a7df5" * ] */
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

bulkUpdate( )


Updates a number of items in a collection.

The bulkUpdate() function returns a Promise that resolves after the items have been updated in the specified collection. The Promise is rejected if the current user does not have update permissions for the collection. Items are skipped if they include an _id property whose value does not match an existing ID in the collection. Meaning, bulkUpdate() cannot add new items into the collection.

Calling the bulkUpdate() function triggers the beforeUpdate() and afterUpdate() hooks for each item that is updated if the hooks have been defined.

The bulkUpdate() function compares the _id property of the specified items with the _id property values of the items in the specified collection.

Warning: If an existing item in the specified collection matches the _id of the specified item, bulkUpdate replaces the existing item's property values with the ones in the specified item. If the existing item had properties with values and those properties were not included in the specified item, the values in those properties are lost. The item's _updatedDate property is also updated to the current date.

Any valid JavaScript object can be used as a property value. The bulkUpdate() function maintains the structure of the specified object. For example, objects that contain nested objects, Arrays, or Arrays with nested objects are all added to the collection as defined.

Use the options parameter to run bulkUpdate() from backend code without checking for permissions or without its registered hooks.

When updating items in a collection that has a reference field, set the values of the reference field to the referenced item's _id value or the entire referenced item object.

The maximum size of an item that you can update in a collection is 500kb.

Notes:

  • Bulk operations are limited to 1000 items per function call.
  • The bulkUpdate() function is not supported for Single Item Collections.
  • The bulkUpdate() function does not support multi-reference fields. For multi-reference fields, use replaceReferences() or insertReference().
  • Translatable collections do not allow insertion and modification of items when working in a non-primary language. For example, if a collection's primary language is English, and the site visitor is viewing the site in French, calling bulkUpdate() will fail and issue an error.
Method Declaration
Copy
function bulkUpdate(
  collectionId: string,
  items: Array<object>,
  options: WixDataOptions,
): Promise<WixDataBulkResult>;
Method Parameters
collectionIdstringRequired

The ID of the collection that contains the item to update.

To find your collectionId, select the Databases tab in the Velo Sidebar. Hover over your collection, click the three dots, and select Edit Settings.


itemsArray<object>Required

The items to update.

The array must contain at least one item. Passing an empty array returns an error.


optionsWixDataOptions

An object containing options to use when processing this operation.

Returns
Return Type:Promise<WixDataBulkResult>
JavaScript
import wixData from "wix-data"; // ... let toUpdate1 = { _id: "00001", title: "Mr.", first_name: "John", last_name: "Doe", }; let toUpdate2 = { _id: "00002", title: "Ms.", first_name: "Jane", last_name: "Doe", }; wixData .bulkUpdate("myCollection", [toUpdate1, toUpdate2]) .then((results) => { let inserted = results.inserted; // 0 let insertedIds = results.insertedItemIds; // [] let updated = results.updated; // 2 let skipped = results.skipped; // 0 let errors = results.errors; // [] }) .catch((err) => { let errorMsg = err; });
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

filter( )


Creates a filter to be used with datasets and aggregations.

The filter() function builds a filter to be applied to a dataset or an aggregation, and returns a WixDataFilter object. The returned object contains the filter definition and is used with the setFilter() function.

When working with Wix app collections, check which fields can be used in a filter.

Method Declaration
Copy
function filter(): WixDataFilter;
Request
This method does not take any parameters
Returns
Return Type:WixDataFilter
Filter a dataset
JavaScript
import wixData from "wix-data"; // ... $w("#myDataset").setFilter( wixData.filter().startsWith("lastName", "D").ge("age", "21"), );
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

get( )


Retrieves an item from a collection.

The get() function returns a Promise that resolves to the item with ID itemId from the specified collection, or null if the itemId is not found. The Promise is rejected if the current user does not have read permissions for the collection.

If the specified collection contains reference fields, the ID of the referenced item is returned. To return the values of the referenced items use query() and include().

If the get() function is passed the ID of a hidden item, it returns null.

Calling the get() function triggers the beforeGet() and afterGet() hooks if they have been defined.

Use the options parameter to run get() from backend code without checking for permissions or without its registered hooks.

Notes:

  • When using the query() or get() functions or another data retrieval method following a change to your database collection, the data retrieved may not contain your most recent changes. See Wix Data and Eventual Consistency for more information. To solve this problem, you can use the setTimeout() function to delay retrieving data following any changes to your database collection.
  • To speed up data retrieval, the results of certain data queries are cached. Learn more about caching data query results.
  • An itemId is required to retrieve an item even from a single-item collection.
Method Declaration
Copy
function get(
  collectionId: string,
  itemId: string,
  options: WixDataOptions,
): Promise<object>;
Method Parameters
collectionIdstringRequired

The ID of the collection to retrieve the item from.

To find your collectionId, select the Databases tab in the Velo Sidebar. Hover over your collection, click the three dots, and select Edit Settings.


itemIdstringRequired

The ID of the item to retrieve.


optionsWixDataOptions

An object containing options to use when processing this operation.

Returns
Return Type:Promise<object>
JavaScript
import wixData from "wix-data"; // ... wixData .get("myCollection", "00001") .then((item) => { console.log(item); //see item below }) .catch((err) => { console.log(err); }); /* item is: * * { * "_id": "00001", * "_owner": "ffdkj9c2-df8g-f9ke-lk98-4kjhfr89keedb", * "_createdDate": "2017-05-24T12:33:18.938Z", * "_updatedDate": "2017-05-24T12:33:18.938Z", * "title": "Mr.", * "first_name": "John", * "last_name": "Doe" * } */
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

insert( )


Adds an item to a collection.

The insert() function returns a Promise that resolves to the inserted item after it has been added to the specified collection. The Promise is rejected if the current user does not have "create" permissions for the collection or the specified item includes an _id property whose value matches an existing ID in the collection. Meaning, insert() cannot overwrite an existing item in the collection.

Calling the insert() function triggers the beforeInsert() and afterInsert() hooks if they have been defined.

Use the options parameter to run insert() from backend code without checking for permissions or without its registered hooks.

When inserting an item into a collection that has a reference field, set the value of the reference field to the referenced item's _id value or the entire referenced item object.

The insert() function adds the following properties and values to the item when it adds it to the collection:

  • _id: A unique identifier for an item in a collection, if the item doesn't have one or has one that is undefined. You can optionally provide your own ID. Once an ID is assigned to an item it cannot be changed.
  • _createdDate: The date the item was added to the collection.
  • _updatedDate: The date the item was modified. When the item is first added, the _createdDate and _updatedDate are the same.

Any valid JavaScript object can be added as a property value. The insert() function maintains the structure of the specified object. For example, objects that contain nested objects, Arrays, or Arrays with nested objects are all added to the collection as defined.

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

Notes:

  • If an item's _id property value is set to null or an empty string, an error is thrown.
  • When creating a Single Item Collection, an item with the system field _id is pre-inserted into the collection. Single Item Collections may contain only one item.
  • If there is a pre-existing item in a Single Item Collection, the insert() function will not run. To update or change an item in a Single Item Collection see the update() and save() functions.
  • The insert() function does not support multi-reference fields. For multi-reference fields, use insertReference().
  • Translatable collections do not allow insertion and modification of items when working in a non-primary language. For example, if a collection's primary language is English, and the site visitor is viewing the site in French, calling insert() will fail and issue an error.
Method Declaration
Copy
function insert(
  collectionId: string,
  item: object,
  options: WixDataOptions,
): Promise<object>;
Method Parameters
collectionIdstringRequired

The ID of the collection to add the item to.

To find your collectionId, select the Databases tab in the Velo Sidebar. Hover over your collection, click the three dots, and select Edit Settings.


itemItemRequired

The item to add.


optionsWixDataOptions

An object containing options to use when processing this operation.

Returns
Return Type:Promise<object>
JavaScript
import wixData from "wix-data"; // ... let toInsert = { title: "Mr.", first_name: "John", last_name: "Doe", }; wixData .insert("myCollection", toInsert) .then((item) => { console.log(item); //see item below }) .catch((err) => { console.log(err); }); /* item is: * * { * "_id": "rifk4nrk-dj4o-djhe-oidk-fnoqw4oiglk4i", * "_owner": "ffdkj9c2-df8g-f9ke-lk98-4kjhfr89keedb", * "_createdDate": "2017-05-24T12:33:18.938Z", * "_updatedDate": "2017-05-24T12:33:18.938Z", * "title": "Mr.", * "first_name": "John", * "last_name": "Doe" * } */
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

insertReference( )


Inserts a reference in the specified property.

The insertReference() function returns a Promise that resolves when a reference to the referenced item(s) is added to the referring item in the specified property. The Promise is rejected if the current user does not have update permissions for the collection.

Calling the insertReference() function does not trigger any hooks.

Notes:

  • The insertReference() function only applies to multi-reference fields.
  • The insertReference() function is not supported for Single Item Collections.
Method Declaration
Copy
function insertReference(
  collectionId: string,
  propertyName: string,
  referringItem: union,
  referencedItem: union,
  options: WixDataOptions,
): Promise<void>;
Method Parameters
collectionIdstringRequired

The ID of the collection that contains the referring item.

To find your collectionId, select the Databases tab in the Velo Sidebar. Hover over your collection, click the three dots, and select Edit Settings.


propertyNamestringRequired

The property to insert the reference into.


referringItemunionRequired

The referring item or referring item's ID.


referencedItemunionRequired

The referenced item, referenced item's ID, an array of referenced items, or an array of referenced item IDs.


optionsWixDataOptions

An object containing options to use when processing this operation.

This example inserts a reference to the item with ID 12345 in the Actors field of the item in the Movies collection with the ID 00001.

JavaScript
import wixData from "wix-data"; // ... wixData .insertReference("movies", "actors", "00001", "12345") .then(() => { console.log("Reference inserted"); }) .catch((error) => { console.log(error); });
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

isReferenced( )


Checks if a reference to the referenced item exists in the specified property of the referring item.

The isReferenced() function returns a Promise that resolves to true if the referring item contains a reference to the referenced item in the specified property. The Promise is rejected if the current user does not have read permissions for the collection.

Calling the isReferenced() function does not trigger any hooks.

Note: The isReferenced() function is not supported for Single Item Collections.

Method Declaration
Copy
function isReferenced(
  collectionId: string,
  propertyName: string,
  referringItem: union,
  referencedItem: union,
  options: WixDataOptions,
): Promise<boolean>;
Method Parameters
collectionIdstringRequired

The ID of the collection that contains the referring item.

To find your collectionId, select the Databases tab in the Velo Sidebar. Hover over your collection, click the three dots, and select Edit Settings.


propertyNamestringRequired

The property that possibly contains the references to the referenced item.


referringItemunionRequired

The referring item or referring item's ID.


referencedItemunionRequired

The referenced item or referenced item's ID.


optionsWixDataOptions

An object containing options to use when processing this operation.

Returns
Return Type:Promise<boolean>
Get referenced items

This example checks if the item in the Movies collection with the ID 00001 has a reference in its Actors field that refers to an item with the ID 12345.

JavaScript
import wixData from "wix-data"; // ... wixData .isReferenced("movies", "actors", "00001", "12345") .then((result) => { let isReferenced = result; // true }) .catch((err) => { let errorMsg = err; });
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

query( )


Creates a query for retrieving items from a database collection.

The query() function builds a query on the specified collection and returns a WixDataQuery 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 WixDataQuery functions onto the query. WixDataQuery functions enable you to sort, filter, and control the results a query returns.

The query() runs with the following WixDataQuery defaults that you can override:

The functions that are chained to query() are applied in the order they are called. For example, if you sort on an age property in ascending order and then on a name property 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 will not be retrieved. To get the data from the referenced items, you must either use the include() chained function before find() or use the queryReferenced() function instead of query().

Items marked as hidden in the collection are not returned.

When working with Wix app collections, fields in the collections have the following permissions:

  • Can connect to data
  • Can use in dynamic page URL
  • Can be sorted
  • Can be filtered
  • Read-only Check which fields can be used in a query.

Notes:

Method Declaration
Copy
function query(collectionId: string): WixDataQuery;
Method Parameters
collectionIdstringRequired

The ID of the collection to run the query on.

To find your collectionId, select the Databases tab in the Velo Sidebar. Hover over your collection, click the three dots, and select Edit Settings.

Returns
Return Type:WixDataQuery
JavaScript
import wixData from "wix-data"; // ... let query = wixData.query("myCollection");
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

queryReferenced( )


Gets the full items referenced in the specified property.

The queryReferenced() function returns a Promise that resolves to the full items that are referenced in the specified property of the item from the specified collection. The Promise is rejected if the current user does not have read permissions for the specified collection or the collection containing the referenced items.

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 queryReferenced() returns the relevant People items referenced in the Actors field of the specified Movies item. Meaning, it returns the full actor information for all actors in the specified movie.

The queryReferenced() function can be used instead of a standard query() with an include() to overcome the limitations of the include() function.

You can optionally control the order of the returned referenced items by passing a WixDataQueryReferencedOptions object.

Notes:

  • Calling the queryReferenced() function does not trigger any hooks.
  • You can only use the queryReferenced() function with multiple-item reference fields, and not with single-item (regular) reference fields.
  • The queryReferenced() function is not supported for Single Item Collections.

For a discussion of when to use the similar include() function and when to use queryReferenced(), see Querying Items that Reference Other Items.

Method Declaration
Copy
function queryReferenced(
  collectionId: string,
  item: union,
  propertyName: string,
  options: WixDataQueryReferencedOptions,
): Promise<WixDataQueryReferencedResult>;
Method Parameters
collectionIdstringRequired

The ID of the collection that contains the referring item.

To find your collectionId, select the Databases tab in the Velo Sidebar. Hover over your collection, click the three dots, and select Edit Settings.


itemunionRequired

The referring item or referring item's ID.


propertyNamestringRequired

The property that contains the references to the referenced items.


optionsWixDataQueryReferencedOptions

An object for controlling the order of the returned referenced items.

Returns
Return Type:Promise<WixDataQueryReferencedResult>

This example finds the item in the Movies collection with the ID 00001. It gets all of the items referenced in the Actors field of that item and then stores the first actor in a variable.

JavaScript
import wixData from "wix-data"; // ... wixData .queryReferenced("movies", "00001", "actors") .then((results) => { if (results.items.length > 0) { console.log(results.items[0]); //see item below } else { // handle case where no matching items found } }) .catch((err) => { console.log(err); }); /* firstItem is: * * { * "_id": "12345", * "_owner": "ffdkj9c2-df8g-f9ke-lk98-4kjhfr89keedb", * "_createdDate": "2017-05-24T12:33:18.938Z", * "_updatedDate": "2017-05-24T12:33:18.938Z", * "first_name": "John", * "last_name": "Doe" * } */
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

remove( )


Removes an item from a collection.

The remove() function returns a Promise that resolves to the removed item after it has been removed from the specified collection. The Promise is rejected if the current user does not have "delete" permissions for the collection.

Calling the remove() function triggers the beforeRemove() and afterRemove() hooks if they have been defined.

Use the options parameter to run remove() from backend code without checking for permissions or without its registered hooks.

Notes:

  • The remove() function also clears multiple-item reference fields for items in collections referenced by the specified item. For example, suppose you have a Movies collection with an Actors field that contains multiple references to items in a People collection. Removing an item in the Movies collection also clears the data in the corresponding multiple-item reference fields in the People collection.
Method Declaration
Copy
function remove(
  collectionId: string,
  itemId: string,
  options: WixDataOptions,
): Promise<object>;
Method Parameters
collectionIdstringRequired

The ID of the collection to remove the item from.

To find your collectionId, select the Databases tab in the Velo Sidebar. Hover over your collection, click the three dots, and select Edit Settings.


itemIdstringRequired

The ID of the item to remove.


optionsWixDataOptions

An object containing options to use when processing this operation.

Returns
Return Type:Promise<object>
JavaScript
import wixData from "wix-data"; // ... wixData .remove("myCollection", "00001") .then((result) => { console.log(result); // see removed item below }) .catch((err) => { console.log(err); }); /* removed item is: * * { * "_id": "00001", * "_owner": "ffdkj9c2-df8g-f9ke-lk98-4kjhfr89keedb", * "_createdDate": "2017-05-24T12:33:18.938Z", * "_updatedDate": "2017-05-24T12:33:18.938Z", * "title": "Mr.", * "first_name": "John", * "last_name": "Doe" * } */
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

removeReference( )


Removes a reference from the specified property.

The removeReference() function returns a Promise that resolves when a reference to the referenced item(s) is removed from the specified property in the referring item. The Promise is rejected if the current user does not have update permissions for the collection.

Calling the removeReference() function does not trigger any hooks.

Note: The removeReference() function is not supported for Single Item Collections.

Method Declaration
Copy
function removeReference(
  collectionId: string,
  propertyName: string,
  referringItem: union,
  referencedItem: union,
  options: WixDataOptions,
): Promise<void>;
Method Parameters
collectionIdstringRequired

The ID of the collection that contains the referring item.

To find your collectionId, select the Databases tab in the Velo Sidebar. Hover over your collection, click the three dots, and select Edit Settings.


propertyNamestringRequired

The property to remove the reference from.


referringItemunionRequired

The referring item or referring item's ID.


referencedItemunionRequired

The referenced item, referenced item's ID, an array of referenced items, or an array of referenced item IDs.


optionsWixDataOptions

An object containing options to use when processing this operation.

This example removes a reference to the item with ID 12345 from the Actors field of the item in the Movies collection with the ID 00001.

JavaScript
import wixData from "wix-data"; // ... wixData .removeReference("movies", "actors", "00001", "12345") .then(() => { console.log("Reference removed"); }) .catch((error) => { console.log(error); });
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

replaceReferences( )


Replaces current references with references in the specified property.

The replaceReferences() function returns a Promise that resolves when the item's current references in the specified property are removed and references to the referenced items are added in their place. The Promise is rejected if the current user does not have update permissions for the collection.

Calling the replaceReferences() function does not trigger any hooks.

Note: The replaceReferences() function is not supported for Single Item Collections.

Method Declaration
Copy
function replaceReferences(
  collectionId: string,
  propertyName: string,
  referringItem: union,
  referencedItem: union,
  options: WixDataOptions,
): Promise<void>;
Method Parameters
collectionIdstringRequired

The ID of the collection that contains the referring item.

To find your collectionId, select the Databases tab in the Velo Sidebar. Hover over your collection, click the three dots, and select Edit Settings.


propertyNamestringRequired

The property to replaces the references in.


referringItemunionRequired

The referring item or referring item's ID.


referencedItemunionRequired

The referenced item, referenced item's ID, an array of referenced items, or an array of referenced item IDs.


optionsWixDataOptions

An object containing options to use when processing this operation.

This example replaces the references in the Actors field of the item in the Movies collection with the ID 00001 with a reference to the item with ID 12345.

JavaScript
import wixData from "wix-data"; // ... wixData .replaceReferences("movies", "actors", "00001", "12345") .then(() => { console.log("References replaced"); }) .catch((error) => { console.log(error); });
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

save( )


Inserts or updates an item in a collection.

The save() function returns a Promise that resolves to the inserted or updated item after it has been added or updated in the specified collection. The Promise is rejected if the current user does not have the necessary permissions for the collection.

The save() function inserts or updates the specified item, depending on whether it already exists in the collection. It compares the _id property value of the specified item with the _id property values of the items in the specified collection. If an item in the collection has that _id value, save() uses update() to update the item in the collection, triggering the beforeUpdate() and afterUpdate() hooks if they have been defined. If none of the items in the collection contain that _id value, the specified item does not have an _id property, or if the specified item's id property is undefined, save() uses insert() to add the specified item to the collection. This triggers the beforeInsert() and afterInsert() hooks if they have been defined.

Use the options parameter to run save() from backend code without checking for permissions or without its registered hooks.

When saving an item to a collection that has a reference field, set the value of the reference field to the referenced item's _id value or the entire referenced item object.

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

Notes:

  • If an item's _id property value is set to null or an empty string, an error is thrown.
  • The save() function does not support multi-reference fields. For multi-reference fields, use insertReference() or replaceReferences()
  • Translatable collections do not allow insertion and modification of items when working in a non-primary language. For example, if a collection's primary language is English, and the site visitor is viewing the site in French, calling save() will fail and issue an error.
Method Declaration
Copy
function save(
  collectionId: string,
  item: object,
  options: WixDataOptions,
): Promise<object>;
Method Parameters
collectionIdstringRequired

The ID of the collection to save the item to.

To find your collectionId, select the Databases tab in the Velo Sidebar. Hover over your collection, click the three dots, and select Edit Settings.


itemItemRequired

The item to insert or update.


optionsWixDataOptions

An object containing options to use when processing this operation.

Returns
Return Type:Promise<object>
JavaScript
import wixData from "wix-data"; // ... let toSave = { title: "Mr.", first_name: "John", last_name: "Doe", }; wixData .save("myCollection", toSave) .then((results) => { console.log(results); //see item below }) .catch((err) => { console.log(err); }); /* item is: * * { * "_id": "rifk4nrk-dj4o-djhe-oidk-fnoqw4oiglk4i", * "_owner": "ffdkj9c2-df8g-f9ke-lk98-4kjhfr89keedb", * "_createdDate": "2017-05-24T12:33:18.938Z", * "_updatedDate": "2017-05-24T12:33:18.938Z", * "title": "Mr.", * "first_name": "John", * "last_name": "Doe" * } */
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

sort( )


Creates a sort to be used with the dataset setSort() function.

This function is not used on its own. It is only used to create a sort for a dataset using the setSort() function.

When working with Wix app collections, check which fields can be used in a sort.

Method Declaration
Copy
function sort(): WixDataSort;
Request
This method does not take any parameters
Returns
Return Type:WixDataSort
Sort a dataset
JavaScript
import wixData from "wix-data"; // ... $w("#myDataset").setSort( wixData.sort().ascending("lastName").descending("age"), );
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

truncate( )


Removes all items from a collection.

The truncate() function returns a Promise that resolves after all items have been removed from the specified collection.

truncate() runs when at least one of the following is true:

  • The current user is the site owner.
  • The request is performed in backend code with a suppressAuth options value of true.

Calling the truncate() function does not trigger any hooks.

Note: truncate() also clears multiple-item reference fields in collections referenced by the specified collection. For example, suppose you have a Movies collection with an Actors field that contains multiple references to items in a People collection. Truncating the Movies collection also clears the data in the corresponding multiple-item reference field in the People collection.

Method Declaration
Copy
function truncate(
  collectionId: string,
  options: WixDataOptions,
): Promise<object>;
Method Parameters
collectionIdstringRequired

The ID of the collection to remove items from.

To find your collectionId, select the Databases tab in the Velo Sidebar. Hover over your collection, click the three dots, and select Edit Settings.


optionsWixDataOptions

An object containing options you can use when calling this function.

Returns
Return Type:Promise<object>
JavaScript
import wixData from "wix-data"; // ... wixData .truncate("myCollection") .then(() => { console.log("All items removed"); }) .catch((err) => { console.log(err); });
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

update( )


Updates an item in a collection.

The update() function returns a Promise that resolves to the updated item from the specified collection. The Promise is rejected if the current user does not have update permissions for the collection.

Calling the update() function triggers the beforeUpdate() and afterUpdate() hooks if they have been defined.

The update() function compares the _id property of the specified item with the _id property values of the items in the specified collection. If an item in the collection has that _id value, update() replaces the item's property values with the ones in the specified item. If the existing item had properties with values and those properties were not included in the specified item, the values in those properties are lost. The item's _updatedDate property is also updated to the current date.

Any valid JavaScript object can be used as a property value. The update() function maintains the structure of the specified object. For example, objects that contain nested objects, Arrays, or Arrays with nested objects are all added to the collection as defined.

Use the options parameter to run update() from backend code without checking for permissions or without its registered hooks.

When updating an item in a collection that has a reference field, set the value of the reference field to the referenced item's _id value or the entire referenced item object.

The maximum size of an item that you can update in a collection is 500kb.

Notes:

  • The specified item must include an _id property that already exists in the collection.
  • The update() function does not support multi-reference fields. For multi-reference fields, use replaceReferences() or insertReference().
  • Translatable collections do not allow insertion and modification of items when working in a non-primary language. For example, if a collection's primary language is English, and the site visitor is viewing the site in French, calling update() will fail and issue an error.
Method Declaration
Copy
function update(
  collectionId: string,
  item: object,
  options: WixDataOptions,
): Promise<object>;
Method Parameters
collectionIdstringRequired

The ID of the collection that contains the item to update.

To find your collectionId, select the Databases tab in the Velo Sidebar. Hover over your collection, click the three dots, and select Edit Settings.


itemItemRequired

The item to update.


optionsWixDataOptions

An object containing options to use when processing this operation.

Returns
Return Type:Promise<object>
JavaScript
import wixData from "wix-data"; // ... let toUpdate = { _id: "00001", title: "Mr.", first_name: "John", last_name: "Doe", }; wixData .update("myCollection", toUpdate) .then((results) => { console.log(results); //see item below }) .catch((err) => { console.log(err); }); /* item is: * * { * "_id": "00001", * "_owner": "ffdkj9c2-df8g-f9ke-lk98-4kjhfr89keedb", * "_createdDate": "2017-05-24T12:33:18.938Z", * "_updatedDate": "2017-05-24T12:33:18.938Z", * "title": "Mr.", * "first_name": "John", * "last_name": "Doe" * } */
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

ascending( )


Adds a sort to a query or sort, sorting by the specified properties in ascending order.

The ascending() function refines a WixDataQuery or WixDataSort to sort in ascending order of the specified properties. If you specify more than one property, ascending() sorts the results in ascending order by each property in the order they are listed.

You can sort the following types:

  • Number: Sorts numerically.
  • Date: Sorts by date and time.
  • String: Sorts lexicographically, so "abc" comes after "XYZ".
  • Reference: Compares by the ID of the referenced item as a String.

If a property contains a number as a String, that value will be sorted alphabetically and not numerically. Items that do not have a value for the specified sort property are ranked lowest.

Method Declaration
Copy
function ascending(propertyName: Array<string>): WixDataQuery;
Method Parameters
propertyNameArray<string>Required

The properties used in the sort.

Returns
Return Type:WixDataQuery
JavaScript
let newQuery = query.ascending("last_name", "first_name");
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

count( )


Returns the number of items that match the query.

The count() function returns a Promise that resolves to the number of items that match the query. The Promise is rejected if count() is called with incorrect permissions or if any of the functions used to refine the query is invalid.

Calling the count() function triggers the beforeCount() and afterCount() hooks if they have been defined.

Use the options parameter to run count() without checking for permissions or without its registered hooks.

Any function that does not filter query results (e.g., ascending()) does not affect the result of count().

If you build a query and don't refine it with any WixDataQuery functions, count() returns the total number of items in the collection.

If you have already run a query with find(), you can retrieve the number of query results without calling count(). The find() function returns a Promise that resolves to a WixDataQueryResult object, which has a totalCount property whose value is the number of results.

Method Declaration
Copy
function count(options: WixDataOptions): Promise<number>;
Method Parameters
optionsWixDataOptions

An object containing options to use when processing this operation.

Returns
Return Type:Promise<number>
JavaScript
query .count() .then((num) => { let numberOfItems = num; }) .catch((error) => { let errorMsg = error.message; let code = error.code; });
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

descending( )


Adds a sort to a query or sort, sorting by the specified properties in descending order.

The descending() function refines a WixDataQuery or WixDataSort to sort in descending order of the specified properties. If you specify more than one property, descending() sorts the results in descending order by each property in the order they are listed.

You can sort the following types:

  • Number: Sorts numerically.
  • Date: Sorts by date and time.
  • String: Sorts lexicographically, so "abc" comes before "XYZ".
  • Reference: Compares by the ID of the referenced item as a String.

If a property contains a number as a String, that value will be sorted alphabetically and not numerically. Items that do not have a value for the specified sort property are ranked lowest.

Method Declaration
Copy
function descending(propertyName: Array<string>): WixDataQuery;
Method Parameters
propertyNameArray<string>Required

The properties used in the sort.

Returns
Return Type:WixDataQuery
JavaScript
let newQuery = query.descending("last_name", "first_name");
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

distinct( )


Returns the distinct values that match the query, without duplicates.

The distinct() function returns a Promise that resolves to:

  • The distinct values found in the specified field when running the query.
  • Additional information about the results, such as the number of values that match the query.

Unlike find(), which returns all item objects that match the query, distinct() returns matching field values, and eliminates duplicate field values from the query result. You cannot use find() and distinct() together.

For an item to be resolved as distinct, only the specified field must be distinct. Other fields for that item in the collection are not evaluated when resolving the promise.

The Promise is rejected if distinct() is called with incorrect permissions or if any of the functions used to refine the query is invalid.

Notes:

  • Only site visitors with Data Read permissions can retrieve and view data. You can override the permissions by setting the suppressAuth option to true.
  • distinct() returns the full distinct items that match the query. To specify which fields to return for each retrieved item, use the fields() method.
Method Declaration
Copy
function distinct(
  propertyName: string,
  options: WixDataQueryOptions,
): Promise<WixDataQueryResult>;
Method Parameters
propertyNamestringRequired

The property whose value will be compared for distinct values.


optionsWixDataQueryOptions

An object containing options to use when processing this operation.

Returns
Return Type:Promise<WixDataQueryResult>

This example demonstrates how to run a distinct() on a query() that was previously built and stored in a variable.

JavaScript
query .distinct("state") .then((results) => { if (results.items.length > 0) { let items = results.items; let firstItem = items[0]; let totalCount = results.totalCount; let pageSize = results.pageSize; let currentPage = results.currentPage; let totalPages = results.totalPages; let hasNext = results.hasNext(); let hasPrev = results.hasPrev(); let length = results.length; let query = results.query; } else { // handle case where no matching items found } }) .catch((error) => { let errorMsg = error.message; let code = error.code; });
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

fields( )


Lists the fields to return in a query's results.

The fields() function returns only the specified fields in the query's results.

You can use include() in conjunction with fields() to get referenced items.

When fields() receives an empty or invalid property, the query behaves as follows:

  • When no fields are specified, the query returns all fields.
  • When multiple fields are specified but some are invalid, invalid fields are ignored and valid fields are returned.
  • When only invalid fields are specified, only the default _id field is returned.
Method Declaration
Copy
function fields(propertyName: Array<string>): WixDataQuery;
Method Parameters
propertyNameArray<string>Required

Properties to return. To return multiple properties, pass properties as additional arguments.

Returns
Return Type:WixDataQuery
JavaScript
let myQuery = query.fields("fieldName1", "fieldName2");
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

find( )


Returns the items that match the query.

The find() function returns a Promise that resolves to the results found by the query and some information about the results. The Promise is rejected if find() is called with incorrect permissions or if any of the functions used to refine the query is invalid.

Calling the find() function triggers the beforeQuery() and afterQuery() hooks if they have been defined.

Use the options parameter to override default preferences:

  • Override permission checks with suppressAuth.
  • Ensure the most up-to-date data is retrieved with consistentRead.
  • Prevent hooks from running with suppressHooks.
  • Speed up execution with omitTotalCount, if you don't need a count of items matching the query.

If you build a query and don't refine it with any wixDataQuery functions, find() returns the entire collection.

Notes::

  • Calling find() triggers hooks for the specified collection only. It doesn’t trigger hooks for referenced collections.
  • find() returns the full items that match the query. To specify which fields to return for each retrieved item, use the fields() method.
Method Declaration
Copy
function find(options: WixDataQueryOptions): Promise<WixDataQueryResult>;
Method Parameters
optionsWixDataQueryOptions

An object containing options to use when processing this operation.

Returns
Return Type:Promise<WixDataQueryResult>

This example demonstrates how to run a find() on a query() that was previously built and stored in a variable.

JavaScript
query .find() .then((results) => { if (results.items.length > 0) { let items = results.items; let firstItem = items[0]; let totalCount = results.totalCount; let pageSize = results.pageSize; let currentPage = results.currentPage; let totalPages = results.totalPages; let hasNext = results.hasNext(); let hasPrev = results.hasPrev(); let length = results.length; let query = results.query; } else { // handle case where no matching items found } }) .catch((error) => { let errorMsg = error.message; let code = error.code; });
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

include( )


Includes referenced items for the specified properties in a query's results.

The include() function refines a query so that the items returned in the query's results include the full referenced items for the specified properties.

For example, suppose you have a books collection with an author field that references an authors collection. Querying the books collection with an include("author") returns the relevant book items and each item will include the full referenced author item in the book's author property.

When querying a collection that contains a reference field without using the include() function:

  • Single reference field: returned items contain only the ID of the referenced item, and not the full referenced items.
  • Multiple reference field: returned items do not contain the multiple reference field at all.

When including a property with multiple references, the following limitations apply:

  • Only one property with multiple references can be included.
  • The query will return an error if more than 50 items are returned, regardless of any query limit set using the limit() function.
  • Each returned item can include up to 50 referenced items. If there are more than 50 referenced items, only 50 are returned when the query is run and the partialIncludes property of the returned WixDataQueryResult is true. To retrieve more than 50 referenced items, use the queryReferenced() function.

For a discussion of when to use the similar queryReferenced() function and when to use include(), see Querying Items that Reference Other Items.

Notes:

  • Calling the include() function does not trigger any hooks.
  • The include() function is not supported for Single Item Collections.
Method Declaration
Copy
function include(propertyName: Array<string>): WixDataQuery;
Method Parameters
propertyNameArray<string>Required

The properties for which to include referenced items.

Returns
Return Type:WixDataQuery
JavaScript
let newQuery = query.include("referenceField");
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

limit( )


Limits the number of items the query returns.

The limit() function defines the number of results a query returns in each page. Only one page of results is retrieved at a time. The next() and prev() functions are used to navigate the pages of a query result.

By default, limit is set to 50.

The maximum value that limit() can accept is 1000.

Note that for some Wix app collections, the maximum value limit() can accept is less than 1000. For example, the maximum limit for the Wix Stores/Product collection is 100.

Method Declaration
Copy
function limit(limit: number): WixDataQuery;
Method Parameters
limitnumberRequired

The number of items to return, which is also the pageSize of the results object.

Returns
Return Type:WixDataQuery
JavaScript
let newQuery = query.limit(10);
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

skip( )


Sets the number of items to skip before returning query results.

The skip() function defines the number of results to skip in the query results before returning new query results.

For example, if you query a collection and 50 items match your query, but you set skip to 10, the results returned will skip the first 10 items that match and return the 11th through 50th items.

By default, skip is set to 0.

Method Declaration
Copy
function skip(skip: number): WixDataQuery;
Method Parameters
skipnumberRequired

The number of items to skip in the query results before returning the results.

Returns
Return Type:WixDataQuery
JavaScript
let newQuery = query.skip(10);
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

and( )


Adds an and condition to the query or filter.

The and() function adds an and condition to a WixDataQuery or WixDataFilter. A query or filter with an and returns all the items that match the query or filter as defined up to the and function and also match the query or filter passed to the and function.

Note that when chaining multiple WixDataFilter functions to a query an and condition is assumed. In such cases, you do not need to add a call to the and() function. For example, this query returns results where status is active and age is greater than 25.

Copy
wixData.query("myCollection").eq("status", "active").gt("age", 25);

The and() function is needed when performing compound queries. For example, the final query in this set of queries returns results where status is either pending or rejected and age is either less than 25 or greater than 65.

Copy
let statusQuery = wixData .query("myCollection") .eq("status", "pending") .or(wixData.query("myCollection").eq("status", "rejected")); let ageQuery = wixData .query("myCollection") .lt("age", 25) .or(wixData.query("myCollection").gt("age", 65)); let statusAndAgeQuery = statusQuery.and(ageQuery);

The collections referenced by both the initial query and the query passed to the and function must be the same.

The 'and()' function is designed to work with 2 or more queries or filters. If you use it on its own, it will return all the items in a collection.

Method Declaration
Copy
function and(query: WixDataQuery): WixDataQuery;
Method Parameters
queryWixDataQueryRequired

A query to add to the initial query as an and condition.

Returns
Return Type:WixDataQuery
JavaScript
let newQuery = query1.and(query2);
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

between( )


Refines a query or filter to match items whose specified property value is within a specified range.

The between() function refines a WixDataQuery or WixDataFilter to only match items where the value of the specified property is greater than or equal to rangeStart and less than rangeEnd.

It only matches values of the same type. For example, a number value stored as a String type does not match the same number stored as a Number type.

If a property contains a number as a String, that value will be compared alphabetically and not numerically. Items that do not have a value for the specified property are ranked lowest.

The following types of properties can be compared:

  • Number: Compares numerically.
  • Date: Compares JavaScript Date objects.
  • String: Compares lexicographically, so
    • "A" and "M" are between "A" and "Z", but "a", "m", "z" and "Z" are not.
    • "A", "M", "Z", and "a" are between "A" and "z", but "z" is not.
Method Declaration
Copy
function between(
  propertyName: string,
  rangeStart: union,
  rangeEnd: union,
): WixDataQuery;
Method Parameters
propertyNamestringRequired

The property whose value will be compared with rangeStart and rangeEnd.


rangeStartunionRequired

The beginning value of the range to match against.


rangeEndunionRequired

The ending value of the range to match against.

Returns
Return Type:WixDataQuery
JavaScript
let newQuery = query.between("age", 25, 65);
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

contains( )


Refines a query or filter to match items whose specified property value contains a specified string.

The contains() function refines a WixDataQuery or WixDataFilter to only match items where the value of the specified property contains the specified string. Matching with contains() is not case sensitive, so "text" does contain "Tex".

You can use contains() with a property whose value is a String or a Reference. For properties of type reference it is recommended that you use the eq() function instead of contains(). With properties that are References, contains() matches by the ID of the referenced item as a String.

Method Declaration
Copy
function contains(propertyName: string, string: string): WixDataQuery;
Method Parameters
propertyNamestringRequired

The property whose value will be compared with the string.


stringstringRequired

The string to look for inside the specified property value.

Returns
Return Type:WixDataQuery
JavaScript
let newQuery = query.contains("description", "some words");
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

endsWith( )


Refines a query or filter to match items whose specified property value ends with a specified string.

The endsWith() function refines a WixDataQuery or WixDataFilter to only match items where the value of the specified property ends with the specified string. Matching with endsWith() is not case sensitive, so "TEXT" ends with "ext".

You can only use endsWith() with a property whose value is a String or Reference. When using a Reference, endsWith() matches by the ID of the referenced item as Strings.

Method Declaration
Copy
function endsWith(propertyName: string, string: string): WixDataQuery;
Method Parameters
propertyNamestringRequired

The property whose value will be compared with the string.


stringstringRequired

The string to look for at the end of the specified property value.

Returns
Return Type:WixDataQuery
JavaScript
let newQuery = query.endsWith("last_name", "z");
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

eq( )


Refines a query or filter to match items whose specified property value equals the specified value.

The eq() function refines a WixDataQuery or WixDataFilter to only match items where the value of the specified property equals the specified value.

It only matches values of the same type. For example, a number value stored as a String type does not match the same number stored as a Number type.

Matching strings with eq() is case sensitive, so "text" is not equal to "Text".

If propertyName points to a collection field of type Array, eq() includes the item as long as at least one Array element matches the specified value.

Method Declaration
Copy
function eq(propertyName: string, value: any): WixDataQuery;
Method Parameters
propertyNamestringRequired

The property whose value will be compared with value.


valueanyRequired

The value to match against.

Returns
Return Type:WixDataQuery
JavaScript
let newQuery = query.eq("status", "active");
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

ge( )


Refines a query or filter to match items whose specified property value is greater than or equal to the specified value.

The ge() function refines a WixDataQuery or WixDataFilter to only match items where the value of the specified property is greater than or equal to the specified value.

It only matches values of the same type. For example, a number value stored as a String type does not match the same number stored as a Number type.

If a property contains a number as a String, that value will be compared alphabetically and not numerically. Items that do not have a value for the specified property are ranked lowest.

The following types of properties can be compared:

  • Number: Compares numerically.
  • Date: Compares JavaScript Date objects.
  • String: Compares lexicographically, so "abc" is greater than or equal to "ABC" (because of the greater than), but "ABC" is not greater than or equal to "abc".
  • Reference: Compares by the ID of the referenced item as a String.
Method Declaration
Copy
function ge(propertyName: string, value: union): WixDataQuery;
Method Parameters
propertyNamestringRequired

The property whose value will be compared with value.


valueunionRequired

The value to match against.

Returns
Return Type:WixDataQuery
JavaScript
let newQuery = query.ge("age", 25);
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

gt( )


Refines a query or filter to match items whose specified property value is greater than the specified value.

The gt() function refines a WixDataQuery or WixDataFilter to only match items where the value of the specified property is greater than the specified value.

It only matches values of the same type. For example, a number value stored as a String type does not match the same number stored as a Number type.

If a property contains a number as a String, that value will be compared alphabetically and not numerically. Items that do not have a value for the specified property are ranked lowest.

The following types of properties can be compared:

  • Number: Compares numerically.
  • Date: Compares JavaScript Date objects.
  • String: Compares lexicographically, so "text" is greater than "Text".
  • Reference: Compares by the ID of the referenced item as a String.
Method Declaration
Copy
function gt(propertyName: string, value: union): WixDataQuery;
Method Parameters
propertyNamestringRequired

The property whose value will be compared with value.


valueunionRequired

The value to match against.

Returns
Return Type:WixDataQuery
JavaScript
let newQuery = query.gt("age", 25);
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

hasAll( )


Refines a query or filter to match items whose specified property values equals all of the specified value parameters.

The hasAll() function refines a WixDataQuery or WixDataFilter to only match items where the value of the specified property equals all of the specified values.

Matching strings with hasAll() is case sensitive, so "text" is not equal to "Text".

If the value of the specified property is an array, hasAll() will match if there is a match in the elements of that array for all of the specified values.

You can specify a list of values to match by providing an array of String, Number, or Date types as the value parameters.

Method Declaration
Copy
function hasAll(propertyName: string, value: union): WixDataQuery;
Method Parameters
propertyNamestringRequired

The property whose value will be compared with value.


valueunionRequired

The values to match against.

Returns
Return Type:WixDataQuery
JavaScript
let newQuery = query.hasAll("sizes", [30, 38, 42]);
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

hasSome( )


Refines a query or filter to match items whose specified property value equals any of the specified value parameters.

The hasSome() function refines a WixDataQuery or WixDataFilter to only match items where the value of the specified property equals any of the specified values.

Matching strings with hasSome() is case sensitive, so "text" is not equal to "Text".

If the value of the specified property is an array, hasSome() will match if any of the elements of that array match any of the specified values.

If the specified property contains multiple references, pass item IDs in the value property. In such a case, hasSome() will match if any of the multiple references match any of the specified ID values.

You can specify a list of values to match by providing an array of String, Number, or Date types as the value parameters.

Method Declaration
Copy
function hasSome(propertyName: string, value: union): WixDataQuery;
Method Parameters
propertyNamestringRequired

The property whose value will be compared with value.


valueunionRequired

The values to match against.

Returns
Return Type:WixDataQuery
JavaScript
let newQuery = query.hasSome("sizes", [30, 38, 42]);
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

isEmpty( )


Refines a query or filter to match items whose specified property does not exist or does not have any value.

The isEmpty() function refines a WixDataQuery or WixDataFilter to only match items where the value of the specified property is null or undefined or the property does not exist.

If the property contains any value at all for a given item, including the empty string or an invalid value, that item will match the query.

Method Declaration
Copy
function isEmpty(propertyName: string): WixDataQuery;
Method Parameters
propertyNamestringRequired

The the property in which to check for a value.

Returns
Return Type:WixDataQuery
JavaScript
let newQuery = query.isEmpty("bio");
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

isNotEmpty( )


Refines a query or filter to match items whose specified property has any value.

The isNotEmpty() function refines a WixDataQuery or WixDataFilter to only match items where the value of the specified property is not null or undefined.

If the property contains any value at all for a given item, including the empty string or an invalid value, that item will match the query.

Method Declaration
Copy
function isNotEmpty(propertyName: string): WixDataQuery;
Method Parameters
propertyNamestringRequired

The property in which to check for a value.

Returns
Return Type:WixDataQuery
JavaScript
let newQuery = query.isNotEmpty("bio");
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

le( )


Refines a query or filter to match items whose specified property value is less than or equal to the specified value.

The le() function refines a WixDataQuery or WixDataFilter to only match items where the value of the specified property is less than or equal to the specified value.

It only matches values of the same type. For example, a number value stored as a String type does not match the same number stored as a Number type.

If a property contains a number as a String, that value will be compared alphabetically and not numerically. Items that do not have a value for the specified property are ranked lowest.

The following types of properties can be compared:

  • Number: Compares numerically.
  • Date: Compares JavaScript Date objects.
  • String: Compares lexicographically, so "ABC" is less than or equal to "abc" (because of the less than), but "abc" is not less than or equal to "ABC".
  • Reference: Compares by the ID of the referenced item as a String.
Method Declaration
Copy
function le(propertyName: string, value: union): WixDataQuery;
Method Parameters
propertyNamestringRequired

The property whose value will be compared with value.


valueunionRequired

The value to match against.

Returns
Return Type:WixDataQuery
JavaScript
let newQuery = query.le("age", 25);
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

lt( )


Refines a query or filter to match items whose specified property value is less than the specified value.

The lt() function refines a WixDataQuery or WixDataFilter to only match items where the value of the specified property is less than the specified value.

It only matches values of the same type. For example, a number value stored as a String type does not match the same number stored as a Number type.

If a property contains a number as a String, that value will be compared alphabetically and not numerically. Items that do not have a value for the specified property are ranked lowest.

The following types of properties can be compared:

  • Number: Compares numerically.
  • Date: Compares JavaScript Date objects.
  • String: Compares lexicographically, so "Text" is less than "text".
  • Reference: Compares by the ID of the referenced item as a String.
Method Declaration
Copy
function lt(propertyName: string, value: union): WixDataQuery;
Method Parameters
propertyNamestringRequired

The property whose value will be compared with value.


valueunionRequired

The value to match against.

Returns
Return Type:WixDataQuery
JavaScript
let newQuery = query.lt("age", 25);
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

ne( )


Refines a query or filter to match items whose specified property value does not equal the specified value.

The ne() function refines a WixDataQuery or WixDataFilter to only match items where the value of the specified property does not equal the specified value.

It only matches values of the same type. For example, a number value stored as a String type is considered not equal to the same number stored as a Number type.

Matching strings with ne() is case sensitive, so "text" is not equal to "Text".

If the value of the propertyName property is an Array, ne() includes items in which none of the elements of the Array match the specified value.

Method Declaration
Copy
function ne(propertyName: string, value: any): WixDataQuery;
Method Parameters
propertyNamestringRequired

The property whose value will be compared with value.


valueanyRequired

The value to match against.

Returns
Return Type:WixDataQuery
JavaScript
let newQuery = query.ne("status", "active");
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

not( )


Adds a not condition to the query or filter.

The not() function adds a not condition to a WixDataQuery or WixDataFilter. A query or filter with a not returns all the items that match the query or filter as defined up to the not function, but don't match the query or filter passed to the not function.

If the query or filter only contains a not() function, it returns all the items that don't match the query defined by the not method.

The collections referenced by both the initial query and the query passed to the not function must be the same.

Method Declaration
Copy
function not(query: WixDataQuery): WixDataQuery;
Method Parameters
queryWixDataQueryRequired

A query to add to the initial query as a not condition.

Returns
Return Type:WixDataQuery
JavaScript
let newQuery = query1.not(query2);
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

or( )


Adds an or condition to the query or filter.

The or() function adds an inclusive or condition to a WixDataQuery or WixDataFilter. A query or filter with an or returns all the items that match the query or filter as defined up to the or function, the items that match the query or filter passed to the or function, and the items that match both.

The collections used by both the initial query and the query passed to the or function must be the same.

The 'or()' function is designed to work with 2 or more queries or filters. If you use it on its own, it will return all the items in a collection.

Method Declaration
Copy
function or(query: WixDataQuery): WixDataQuery;
Method Parameters
queryWixDataQueryRequired

A query to add to the initial query as an or condition.

Returns
Return Type:WixDataQuery
JavaScript
let newQuery = query1.or(query2);
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

startsWith( )


Refines a query or filter to match items whose specified property value starts with a specified string.

The startsWith() function refines a WixDataQuery or WixDataFilter to only match items where the value of the specified property starts with the defined string. Matching with startsWith() is not case sensitive, so "TEXT" starts with "tex".

You can only use startsWith() with a property whose value is a String or Reference. When using a Reference, startsWith() matches by the ID of the referenced item as Strings.

Method Declaration
Copy
function startsWith(propertyName: string, string: string): WixDataQuery;
Method Parameters
propertyNamestringRequired

The property whose value will be compared with the string.


stringstringRequired

The string to look for at the beginning of the specified property value.

Returns
Return Type:WixDataQuery
JavaScript
let newQuery = query.startsWith("last_name", "M");
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?