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:
import wixData from "wix-data";
wixData
.query("Customer")
.gt("age", 20)
.ascending("name")
.limit(15)
.find()
.then((results) => {
console.log(results.items);
});
When working with Wix app collections, fields in the collections have the following permissions:
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:
"abc"
comes after "XYZ"
.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.
function ascending(propertyName: Array<string>): WixDataQuery;
The properties used in the sort.
let newQuery = query.ascending("last_name", "first_name");
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.
function count(options: WixDataOptions): Promise<number>;
An object containing options to use when processing this operation.
query
.count()
.then((num) => {
let numberOfItems = num;
})
.catch((error) => {
let errorMsg = error.message;
let code = error.code;
});
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:
"abc"
comes before "XYZ"
.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.
function descending(propertyName: Array<string>): WixDataQuery;
The properties used in the sort.
let newQuery = query.descending("last_name", "first_name");
Returns the distinct values that match the query, without duplicates.
The distinct()
function returns a Promise that resolves to:
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:
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.function distinct(
propertyName: string,
options: WixDataQueryOptions,
): Promise<WixDataQueryResult>;
The property whose value will be compared for distinct values.
An object containing options to use when processing this operation.
This example demonstrates how to run a distinct()
on a query()
that was previously built and stored in a variable.
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;
});
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:
_id
field is returned.function fields(propertyName: Array<string>): WixDataQuery;
Properties to return. To return multiple properties, pass properties as additional arguments.
let myQuery = query.fields("fieldName1", "fieldName2");
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:
suppressAuth
.consistentRead
.suppressHooks
.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::
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.function find(options: WixDataQueryOptions): Promise<WixDataQueryResult>;
An object containing options to use when processing this operation.
This example demonstrates how to run a find()
on a query()
that was previously built and stored in a variable.
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;
});
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:
When including a property with multiple references, the following limitations apply:
limit()
function.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:
include()
function does not trigger any hooks.include()
function is not supported for Single Item Collections.function include(propertyName: Array<string>): WixDataQuery;
The properties for which to include referenced items.
let newQuery = query.include("referenceField");
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.
function limit(limit: number): WixDataQuery;
The number of items to return, which is also the pageSize
of the results object.
let newQuery = query.limit(10);
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.
function skip(skip: number): WixDataQuery;
The number of items to skip in the query results before returning the results.
let newQuery = query.skip(10);
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.
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.
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.
function and(query: WixDataQuery): WixDataQuery;
A query to add to the initial query as an and
condition.
let newQuery = query1.and(query2);
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:
"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.function between(
propertyName: string,
rangeStart: union,
rangeEnd: union,
): WixDataQuery;
The property whose value will be compared with rangeStart
and rangeEnd
.
The beginning value of the range to match against.
The ending value of the range to match against.
let newQuery = query.between("age", 25, 65);
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.
function contains(propertyName: string, string: string): WixDataQuery;
The property whose value will be compared with the string.
The string to look for inside the specified property value.
let newQuery = query.contains("description", "some words");
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.
function endsWith(propertyName: string, string: string): WixDataQuery;
The property whose value will be compared with the string.
The string to look for at the end of the specified property value.
let newQuery = query.endsWith("last_name", "z");
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
.
function eq(propertyName: string, value: any): WixDataQuery;
The property whose value will be compared with value
.
The value to match against.
let newQuery = query.eq("status", "active");
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:
"abc"
is greater than or equal to "ABC"
(because of the greater than),
but "ABC"
is not greater than or equal to "abc"
.function ge(propertyName: string, value: union): WixDataQuery;
The property whose value will be compared with value
.
The value to match against.
let newQuery = query.ge("age", 25);
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:
"text"
is greater than "Text"
.function gt(propertyName: string, value: union): WixDataQuery;
The property whose value will be compared with value
.
The value to match against.
let newQuery = query.gt("age", 25);
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.
function hasAll(propertyName: string, value: union): WixDataQuery;
The property whose value will be compared with value
.
The values to match against.
let newQuery = query.hasAll("sizes", [30, 38, 42]);
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.
function hasSome(propertyName: string, value: union): WixDataQuery;
The property whose value will be compared with value
.
The values to match against.
let newQuery = query.hasSome("sizes", [30, 38, 42]);
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.
function isEmpty(propertyName: string): WixDataQuery;
The the property in which to check for a value.
let newQuery = query.isEmpty("bio");
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.
function isNotEmpty(propertyName: string): WixDataQuery;
The property in which to check for a value.
let newQuery = query.isNotEmpty("bio");
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:
"ABC"
is less than or equal to "abc"
(because of the less than),
but "abc"
is not less than or equal to "ABC"
.function le(propertyName: string, value: union): WixDataQuery;
The property whose value will be compared with value
.
The value to match against.
let newQuery = query.le("age", 25);
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:
"Text"
is less than "text"
.function lt(propertyName: string, value: union): WixDataQuery;
The property whose value will be compared with value
.
The value to match against.
let newQuery = query.lt("age", 25);
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
.
function ne(propertyName: string, value: any): WixDataQuery;
The property whose value will be compared with value
.
The value to match against.
let newQuery = query.ne("status", "active");
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.
function not(query: WixDataQuery): WixDataQuery;
A query to add to the initial query as a not
condition.
let newQuery = query1.not(query2);
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.
function or(query: WixDataQuery): WixDataQuery;
A query to add to the initial query as an or
condition.
let newQuery = query1.or(query2);
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.
function startsWith(propertyName: string, string: string): WixDataQuery;
The property whose value will be compared with the string.
The string to look for at the beginning of the specified property value.
let newQuery = query.startsWith("last_name", "M");