Introduction

The WixDataQuery functions enable you to run, sort, filter, and control which results a query returns.

Typically, you build a query using the query() function, refine the query by chaining WixDataQuery functions, and then execute the query by chaining one of the following: find(), distinct(), or count().

For example, the following code queries a collection for all male customers over the age of 20 and logs the first 15 results to the console, sorted in ascending order by name:

Copy

When querying Wix app collections, make sure the fields you use to refine your query support the intended operations. Learn more about querying by Wix app collection fields.

Did this help?

and( )


Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Adds an and condition to the query or filter.

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

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

Copy

The and() method 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

The and() method is designed to work with 2 or more queries or filters. When used on its own, it returns all the items in a collection.

Method Declaration
Copy
Method Parameters
filterWixDataFilterRequired

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

Returns
Return Type:WixDataQuery
Errors

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

Did this help?

ascending( )


Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

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

The ascending() method refines this query 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 is sorted alphabetically and not numerically. Items that do not have a value for the specified sort property are ranked lowest.

Method Declaration
Copy
Method Parameters
fieldsArray<string>Required

Fields used in the sort.

Returns
Return Type:WixDataQuery
Errors

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

Did this help?

between( )


Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

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

The between() method refines this query 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 is 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
Method Parameters
fieldstringRequired

Field whose value is compared with rangeStart and rangeEnd.


rangeStartunionRequired

Starting value of the range to match.


rangeEndunionRequired

Ending value of the range to match.

Returns
Return Type:WixDataQuery
Errors

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

Did this help?

contains( )


Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

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

The contains() method refines this query 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() method instead of contains(). With properties that are References, contains() matches by the ID of the referenced item as a String.

Method Declaration
Copy
Method Parameters
fieldstringRequired

Field whose value is compared with the string.


valuestringRequired

The string to look for inside the specified property value.

Returns
Return Type:WixDataQuery
Errors

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

Did this help?

count( )


Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Returns the number of items that match the query.

The count() method 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 methods used to refine the query is invalid.

Calling the count() method 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 method 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 methods, count() returns the total number of items in the collection.

Note: You can also retrieve the number of query results by calling find() and setting the options.returnTotalCount property to true.

Method Declaration
Copy
Method Parameters
optionsWixDataReadOptions

Options to use when processing this operation.

Returns
Return Type:Promise<number>
Errors

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

Did this help?

descending( )


Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

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

The descending() method refines this query 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 is sorted alphabetically and not numerically. Items that do not have a value for the specified sort property are ranked lowest.

Method Declaration
Copy
Method Parameters
fieldsArray<string>Required

Fields used in the sort.

Returns
Return Type:WixDataQuery
Errors

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

Did this help?

distinct( )


Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

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

The distinct() method 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 methods used to refine the query is invalid.

Note: Only site visitors with Data Read permissions can retrieve and view data. You can override the permissions by calling this method with elevated permissions.

Method Declaration
Copy
Method Parameters
fieldstringRequired

Field whose value is compared for distinct values.


optionsWixDataQueryOptions

Configuration options for building the query.

Returns
Return Type:Promise<WixDataResult>
Errors

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

Did this help?

endsWith( )


Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

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

The endsWith() method refines this query 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
Method Parameters
fieldstringRequired

Field whose value is compared with the string.


valuestringRequired

String to look for at the end of the specified property value.

Returns
Return Type:WixDataQuery
Errors

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

Did this help?

eq( )


Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

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

The eq() method refines this query to only match items where 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 field 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
Method Parameters
fieldstringRequired

Field whose value is compared with value.


valueanyRequired

Value to match.

Returns
Return Type:WixDataQuery
Errors

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

Did this help?

fields( )


Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

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

The fields() method 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
Method Parameters
fieldsArray<string>Required

Properties to return.

Returns
Return Type:WixDataQuery
Errors

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

Did this help?

find( )


Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Returns the items that match the query.

The find() method 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 methods used to refine the query is invalid.

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

Note: Calling find() triggers hooks for the specified collection only. It doesn't trigger hooks for referenced collections.

Use the options parameter to override default preferences:

  • Ensure the most up-to-date data is retrieved with consistentRead.
  • Prevent hooks from running with suppressHooks.
  • Get a count of all the items that match the query by setting returnTotalCount to true.

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

Method Declaration
Copy
Method Parameters
optionsWixDataQueryOptions

Configuration options for building the query.

Returns
Return Type:Promise<WixDataResult>
Errors

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

Did this help?

ge( )


Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

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

The ge() method refines this query 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 is 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
Method Parameters
fieldstringRequired

Field whose value is compared with value.


valueunionRequired

Value to match.

Returns
Return Type:WixDataQuery
Errors

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

Did this help?

gt( )


Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

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

The gt() method refines this query 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 is 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
Method Parameters
fieldstringRequired

Field whose value is compared with value.


valueunionRequired

Value to match.

Returns
Return Type:WixDataQuery
Errors

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

Did this help?

hasAll( )


Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

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

The hasAll() method refines this query 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
Method Parameters
fieldstringRequired

Field whose value is compared with value.


valuesArray<string>Required

Values to match.

Returns
Return Type:WixDataQuery
Errors

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

Did this help?

hasSome( )


Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

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

The hasSome() method refines this query 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
Method Parameters
fieldstringRequired

Field whose value is compared with value.


valuesArray<string>Required

Values to match.

Returns
Return Type:WixDataQuery
Errors

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

Did this help?

include( )


Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

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

The include() method 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() method:

  • 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() method.
  • 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() method.

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

Note: The include() method is not supported for single-item collections.

Method Declaration
Copy
Method Parameters
fieldsArray<string>Required

Fields for which to include referenced items.

Returns
Return Type:WixDataQuery
Errors

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

Did this help?

isEmpty( )


Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

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

The isEmpty() method refines this query 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
Method Parameters
fieldstringRequired

Field in which to check for a value.

Returns
Return Type:WixDataQuery
Errors

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

Did this help?

isNotEmpty( )


Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

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

The isNotEmpty() method refines this query 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
Method Parameters
fieldstringRequired

Field in which to check for a value.

Returns
Return Type:WixDataQuery
Errors

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

Did this help?

le( )


Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

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

The le() method refines this query 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 is 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
Method Parameters
fieldstringRequired

Field whose value is compared with value.


valueunionRequired

Value to match.

Returns
Return Type:WixDataQuery
Errors

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

Did this help?

limit( )


Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Limits the number of items the query returns.

The limit() method 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() methods 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
Method Parameters
limitNumbernumberRequired

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

Returns
Return Type:WixDataQuery
Errors

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

Did this help?

lt( )


Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

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

The lt() method refines this query 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 is 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
Method Parameters
fieldstringRequired

Field whose value is compared with value.


valueunionRequired

Value to match.

Returns
Return Type:WixDataQuery
Errors

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

Did this help?

ne( )


Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

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

The ne() method refines this query 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 field property is an array, ne() includes items in which none of the elements of the array match the specified value.

Method Declaration
Copy
Method Parameters
fieldstringRequired

Field whose value is compared with value.


valueanyRequired

Value to match.

Returns
Return Type:WixDataQuery
Errors

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

Did this help?

not( )


Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Adds a not condition to the query or filter.

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

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

Method Declaration
Copy
Method Parameters
filterWixDataFilterRequired

Filter to add to the initial filter as a not condition.

Returns
Return Type:WixDataQuery
Errors

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

Did this help?

or( )


Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Adds an or condition to the query or filter.

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

The or() method is designed to work with 2 or more queries or filters. Used on its own, it returns all the items in a collection.

Method Declaration
Copy
Method Parameters
filterWixDataFilterRequired

Filter to add to the initial filter as an or condition.

Returns
Return Type:WixDataQuery
Errors

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

Did this help?

skip( )


Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

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

The skip() method 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
Method Parameters
skipCountnumberRequired

Number of items to skip in the query results before returning the results.

Returns
Return Type:WixDataQuery
Errors

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

Did this help?

startsWith( )


Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

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

The startsWith() method refines this query 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
Method Parameters
fieldstringRequired

Field whose value is compared with the value parameter.


valuestringRequired

String to look for at the beginning of the specified property value.

Returns
Return Type:WixDataQuery
Errors

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

Did this help?