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:
function aggregate(collectionId: string): WixDataAggregate;
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.
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;
});
This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.
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:
_id
property value is set to null
or an empty string, an error is thrown.bulkInsert()
function is not supported for Single Item Collections.bulkInsert()
function does not support multi-reference fields. For multi-reference fields, use insertReference()
.bulkInsert()
will fail and issue an error.function bulkInsert(
collectionId: string,
items: Array<object>,
options: WixDataOptions,
): Promise<WixDataBulkResult>;
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.
The items to add.
An object containing options to use when processing this operation.
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"
* ]
*/
This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.
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.
function bulkRemove(
collectionId: string,
itemIds: Array<string>,
options: WixDataOptions,
): Promise<WixDataBulkRemoveResult>;
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.
IDs of the items to remove.
The array must contain at least one item. Passing an empty array returns an error.
An object containing options to use when processing this operation.
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"
* ]
*/
This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.
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.
_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._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:
_id
property value is set to null
or an empty string, an error is thrown.bulkSave()
function is not supported for Single Item Collections.bulkSave()
function does not support multi-reference fields. For multi-reference fields, use replaceReferences()
or insertReference()
.bulkSave()
will fail and issue an error.function bulkSave(
collectionId: string,
items: Array<object>,
options: WixDataOptions,
): Promise<WixDataBulkResult>;
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.
The items to insert or update.
The array must contain at least one item. Passing an empty array returns an error.
An object containing options to use when processing this operation.
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"
* ]
*/
This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.
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:
bulkUpdate()
function is not supported for Single Item Collections.bulkUpdate()
function does not support multi-reference fields. For multi-reference fields, use replaceReferences()
or insertReference()
.bulkUpdate()
will fail and issue an error.function bulkUpdate(
collectionId: string,
items: Array<object>,
options: WixDataOptions,
): Promise<WixDataBulkResult>;
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.
The items to update.
The array must contain at least one item. Passing an empty array returns an error.
An object containing options to use when processing this operation.
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;
});
This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.
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.
function filter(): WixDataFilter;
import wixData from "wix-data";
// ...
$w("#myDataset").setFilter(
wixData.filter().startsWith("lastName", "D").ge("age", "21"),
);
This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.
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:
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.itemId
is required to retrieve an item even from a single-item collection.function get(
collectionId: string,
itemId: string,
options: WixDataOptions,
): Promise<object>;
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.
The ID of the item to retrieve.
An object containing options to use when processing this operation.
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"
* }
*/
This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.
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:
_id
property value is set to null
or an empty string, an error is thrown._id
is pre-inserted into the collection. Single Item Collections may contain only one item.insert()
function will not run. To update or change an item in a Single Item Collection see the update()
and save()
functions.insert()
function does not support multi-reference fields. For multi-reference fields, use insertReference()
.insert()
will fail and issue an error.function insert(
collectionId: string,
item: object,
options: WixDataOptions,
): Promise<object>;
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.
The item to add.
An object containing options to use when processing this operation.
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"
* }
*/
This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.
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:
insertReference()
function only applies to multi-reference fields.insertReference()
function is not supported for Single Item Collections.function insertReference(
collectionId: string,
propertyName: string,
referringItem: union,
referencedItem: union,
options: WixDataOptions,
): Promise<void>;
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.
The property to insert the reference into.
The referring item or referring item's ID.
The referenced item, referenced item's ID, an array of referenced items, or an array of referenced item IDs.
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.
import wixData from "wix-data";
// ...
wixData
.insertReference("movies", "actors", "00001", "12345")
.then(() => {
console.log("Reference inserted");
})
.catch((error) => {
console.log(error);
});
This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.
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.
function isReferenced(
collectionId: string,
propertyName: string,
referringItem: union,
referencedItem: union,
options: WixDataOptions,
): Promise<boolean>;
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.
The property that possibly contains the references to the referenced item.
The referring item or referring item's ID.
The referenced item or referenced item's ID.
An object containing options to use when processing this operation.
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.
import wixData from "wix-data";
// ...
wixData
.isReferenced("movies", "actors", "00001", "12345")
.then((result) => {
let isReferenced = result; // true
})
.catch((err) => {
let errorMsg = err;
});
This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.
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:
skip
: 0
limit
: 50
descending
: by _createdDate
include
: noneThe 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:
Notes:
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]https://dev.wix.com/docs/velo/api-reference/wix-data/introduction#api-reference_wix-data_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.function query(collectionId: string): WixDataQuery;
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.
import wixData from "wix-data";
// ...
let query = wixData.query("myCollection");
This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.
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:
queryReferenced()
function does not trigger any hooks.queryReferenced()
function with multiple-item reference fields, and not with single-item (regular) reference fields.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.
function queryReferenced(
collectionId: string,
item: union,
propertyName: string,
options: WixDataQueryReferencedOptions,
): Promise<WixDataQueryReferencedResult>;
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.
The referring item or referring item's ID.
The property that contains the references to the referenced items.
An object for controlling the order of the returned referenced items.
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.
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"
* }
*/
This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.
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:
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.function remove(
collectionId: string,
itemId: string,
options: WixDataOptions,
): Promise<object>;
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.
The ID of the item to remove.
An object containing options to use when processing this operation.
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"
* }
*/
This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.
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.
function removeReference(
collectionId: string,
propertyName: string,
referringItem: union,
referencedItem: union,
options: WixDataOptions,
): Promise<void>;
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.
The property to remove the reference from.
The referring item or referring item's ID.
The referenced item, referenced item's ID, an array of referenced items, or an array of referenced item IDs.
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.
import wixData from "wix-data";
// ...
wixData
.removeReference("movies", "actors", "00001", "12345")
.then(() => {
console.log("Reference removed");
})
.catch((error) => {
console.log(error);
});
This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.
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.
function replaceReferences(
collectionId: string,
propertyName: string,
referringItem: union,
referencedItem: union,
options: WixDataOptions,
): Promise<void>;
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.
The property to replaces the references in.
The referring item or referring item's ID.
The referenced item, referenced item's ID, an array of referenced items, or an array of referenced item IDs.
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.
import wixData from "wix-data";
// ...
wixData
.replaceReferences("movies", "actors", "00001", "12345")
.then(() => {
console.log("References replaced");
})
.catch((error) => {
console.log(error);
});
This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.
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:
_id
property value is set to null
or an empty string, an error is thrown.save()
function does not support multi-reference fields. For multi-reference fields, use insertReference()
or replaceReferences()
save()
will fail and issue an error.function save(
collectionId: string,
item: object,
options: WixDataOptions,
): Promise<object>;
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.
The item to insert or update.
An object containing options to use when processing this operation.
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"
* }
*/
This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.
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.
function sort(): WixDataSort;
import wixData from "wix-data";
// ...
$w("#myDataset").setSort(
wixData.sort().ascending("lastName").descending("age"),
);
This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.
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:
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.
function truncate(
collectionId: string,
options: WixDataOptions,
): Promise<object>;
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.
An object containing options you can use when calling this function.
import wixData from "wix-data";
// ...
wixData
.truncate("myCollection")
.then(() => {
console.log("All items removed");
})
.catch((err) => {
console.log(err);
});
This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.
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:
_id
property that already exists in the collection.update()
function does not support multi-reference fields. For multi-reference fields, use replaceReferences()
or insertReference()
.update()
will fail and issue an error.function update(
collectionId: string,
item: object,
options: WixDataOptions,
): Promise<object>;
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.
The item to update.
An object containing options to use when processing this operation.
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"
* }
*/
This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.
The WixDataFilter
functions enable you to filter and control which results are returned by a dataset when the
setFilter()
function is applied.
A filter is used to control which data is contained in a dataset on your page.
Typically, you build a filter using the filter()
function, refine the filter with WixDataFilter
functions, and then apply the filter to the dataset using the setFilter()
function.
For example, the following code shows a filter on a dataset that is connected to a collection containing customer data. The filter includes only customers over the age of 20:
import wixData from "wix-data";
const customerFilter = wixData.filter().gt("age", 20);
$w("#myDataset").setFilter(customerFilter);
When working with Wix app collections, check which fields can be used in a filter.
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);
This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.
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);
This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.
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");
This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.
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");
This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.
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");
This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.
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);
This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.
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);
This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.
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]);
This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.
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]);
This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.
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");
This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.
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");
This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.
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);
This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.
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);
This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.
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");
This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.
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);
This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.
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);
This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.
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");
This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.