wix-data

wix-data

The wix-data module contains functionality for working with data in collections.

To use the data module, import wixData from the wix-data module:

ICAgaW1wb3J0IHdpeERhdGEgZnJvbSAnd2l4LWRhdGEnOw==
   import wixData from 'wix-data';

The wix-data API can be used in your site’s front-end or backend code.

The wix-data API includes fuctions for managing the data in your collections, building queries on collections, and registering hooks.

For more information, see Working with the Data API.

Data Types

The following is a list of the field types from database collections and their corresponding JavaScript data types. When you retrieve data from a collection, that data will be represented in the JavaScript data types that correspond to your collection's field types. When you add or update data in a collection, you provide the data using the JavaScript data types that correspond to your collection's field types.

Field Type Data Type Notes
Text JavaScript string
Image JavaScript string An image URL as described here.
Boolean JavaScript boolean
Number JavaScript number
Date and Time JavaScript Date object
Rich Text JavaScript string A string which can contain a subset of HTML tags.
URL JavaScript string A valid URL.
Document JavaScript string A Media Manager document URL as described here.
Reference JavaScript string An item ID from the referenced collection.

Contents

Hooks Hooks that can be added to wix-data operations.
WixDataFilter Provides functionality for filtering a query.
WixDataQuery Contains functionality for refining a data query.
WixDataQueryResult The results of a data query, containing the retrieved items.
WixDataSort Provides functionality for sorting a query.
filter( ) Creates a filter to be used with the dataset setFilter() function.
get( ) Retrieves an item from a collection.
insert( ) Adds an item to a collection.
query( ) Creates a query.
remove( ) Removes an item from a collection.
save( ) Inserts or updates an item in a collection.
sort( ) Creates a sort to be used with the dataset setSort() function.
update( ) Updates an item in a collection.
WixDataOptions An object that you pass as the options parameter that modifies how an operation is performed.
filter( )

filter( )

Creates a filter to be used with the dataset setFilter() function.

function filter(): WixDataFilter

Description

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

Return Value

WixDataFilter A filter object.

Examples

Filter a dataset

aW1wb3J0IHdpeERhdGEgZnJvbSAnd2l4LWRhdGEnOwoKLy8gLi4uCgokdygiI215RGF0YXNldCIpLnNldEZpbHRlciggd2l4RGF0YS5maWx0ZXIoKQogIC5zdGFydHNXaXRoKCJsYXN0TmFtZSIsICJEIikKICAuZ2UoImFnZSIsICIyMSIpCik7Cg==
import wixData from 'wix-data';

// ...

$w("#myDataset").setFilter( wixData.filter()
  .startsWith("lastName", "D")
  .ge("age", "21")
);
get( )

get( )

Retrieves an item from a collection.

function get(collectionName: String, itemId: String,
  [options:WixDataOptions]): Promise<Object>

Description

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

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

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

Parameters

collectionName String The name of the collection to retrieve the item from.
itemId String The ID of the item to retrieve.
options (optional) WixDataOptions An object with one or both of the following boolean properties: suppressAuth, suppressHooks.

Return Value

Returns a Promise

On fulfillment Object The retrieved item.
On rejection Error The error that caused the rejection.

Examples

Get an item from a collection

aW1wb3J0IHdpeERhdGEgZnJvbSAnd2l4LWRhdGEnOwoKLy8gLi4uCgp3aXhEYXRhLmdldCgibXlDb2xsZWN0aW9uIiwgIjAwMDAxIikKICAudGhlbiggKHJlc3VsdHMpID0+IHsKICAgIGxldCBpdGVtID0gcmVzdWx0czsgLy9zZWUgaXRlbSBiZWxvdwogIH0gKQogIC5jYXRjaCggKGVycikgPT4gewogICAgbGV0IGVycm9yTXNnID0gZXJyOwogIH0gKTsKCi8qICBpdGVtIGlzOgogKgogKiAgewogKiAgICAiX2lkIjogICAgICAgICAgIjAwMDAxIiwKICogICAgIl9vd25lciI6ICAgICAgICJmZmRrajljMi1kZjhnLWY5a2UtbGs5OC00a2poZnI4OWtlZWRiIiwKICogICAgIl9jcmVhdGVkRGF0ZSI6ICIyMDE3LTA1LTI0VDEyOjMzOjE4LjkzOFoiLAogKiAgICAiX3VwZGF0ZWREYXRlIjogIjIwMTctMDUtMjRUMTI6MzM6MTguOTM4WiIsCiAqICAgICJ0aXRsZSI6ICAgICAgICAiTXIuIiwKICogICAgImZpcnN0X25hbWUiOiAgICJKb2huIiwKICogICAgImxhc3RfbmFtZSI6ICAgICJEb2UiCiAqICB9CiAqLwo=
import wixData from 'wix-data';

// ...

wixData.get("myCollection", "00001")
  .then( (results) => {
    let item = results; //see item below
  } )
  .catch( (err) => {
    let errorMsg = 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"
 *  }
 */

Get an item from a collection using data options

aW1wb3J0IHdpeERhdGEgZnJvbSAnd2l4LWRhdGEnOwoKLy8gLi4uCgpsZXQgb3B0aW9ucyA9IHsKICAic3VwcHJlc3NBdXRoIjogdHJ1ZSwKICAic3VwcHJlc3NIb29rcyI6IHRydWUKfTsKCndpeERhdGEuZ2V0KCJteUNvbGxlY3Rpb24iLCAiMDAwMDEiLCBvcHRpb25zKQogIC50aGVuKCAocmVzdWx0cykgPT4gewogICAgbGV0IGl0ZW0gPSByZXN1bHRzOyAvL3NlZSBpdGVtIGJlbG93CiAgfSApCiAgLmNhdGNoKCAoZXJyKSA9PiB7CiAgICBsZXQgZXJyb3JNc2cgPSBlcnI7CiAgfSApOwoKLyogIGl0ZW0gaXM6CiAqCiAqICB7CiAqICAgICJfaWQiOiAgICAgICAgICAiMDAwMDEiLAogKiAgICAiX293bmVyIjogICAgICAgImZmZGtqOWMyLWRmOGctZjlrZS1sazk4LTRramhmcjg5a2VlZGIiLAogKiAgICAiX2NyZWF0ZWREYXRlIjogIjIwMTctMDUtMjRUMTI6MzM6MTguOTM4WiIsCiAqICAgICJfdXBkYXRlZERhdGUiOiAiMjAxNy0wNS0yNFQxMjozMzoxOC45MzhaIiwKICogICAgInRpdGxlIjogICAgICAgICJNci4iLAogKiAgICAiZmlyc3RfbmFtZSI6ICAgIkpvaG4iLAogKiAgICAibGFzdF9uYW1lIjogICAgIkRvZSIKICogIH0KICovCg==
import wixData from 'wix-data';

// ...

let options = {
  "suppressAuth": true,
  "suppressHooks": true
};

wixData.get("myCollection", "00001", options)
  .then( (results) => {
    let item = results; //see item below
  } )
  .catch( (err) => {
    let errorMsg = 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"
 *  }
 */
insert( )

insert( )

Adds an item to a collection.

function insert(collectionName: String, item: Object,
  [options:WixDataOptions]): Promise<Object>

Description

The insert() function returns a Promise that resolves to the inserted item after the specified item has been added to the collection collectionName. The Promise is rejected with an error if:

  • The specified collection does not exist.
  • The specified item is not of type Object.
  • 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.
  • The current user does not have create permissions for the collection.

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

Use the options parameter to run insert() 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 the item with collection, if the item does not include one. 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 200kb.

Parameters

collectionName String The name of the collection to add the item to.
item Object The item to add.
options (optional) WixDataOptions An object with one or both of the following boolean properties: suppressAuth, suppressHooks.

Return Value

Returns a Promise

On fulfillment Object The item that was added.
On rejection Error The error that caused the rejection.

Examples

Insert an item into a collection

aW1wb3J0IHdpeERhdGEgZnJvbSAnd2l4LWRhdGEnOwoKLy8gLi4uCgpsZXQgdG9JbnNlcnQgPSB7CiAgInRpdGxlIjogICAgICAgICJNci4iLAogICJmaXJzdF9uYW1lIjogICAiSm9obiIsCiAgImxhc3RfbmFtZSI6ICAgICJEb2UiCn07Cgp3aXhEYXRhLmluc2VydCgibXlDb2xsZWN0aW9uIiwgdG9JbnNlcnQpCgkudGhlbiggKHJlc3VsdHMpID0+IHsKCQlsZXQgaXRlbSA9IHJlc3VsdHM7IC8vc2VlIGl0ZW0gYmVsb3cKCX0gKQoJLmNhdGNoKCAoZXJyKSA9PiB7CgkJbGV0IGVycm9yTXNnID0gZXJyOwoJfSApOwoKLyogIGl0ZW0gaXM6CiAqCiAqICB7CiAqICAgICJfaWQiOiAgICAgICAgICAicmlmazRucmstZGo0by1kamhlLW9pZGstZm5vcXc0b2lnbGs0aSIsCiAqICAgICJfb3duZXIiOiAgICAgICAiZmZka2o5YzItZGY4Zy1mOWtlLWxrOTgtNGtqaGZyODlrZWVkYiIsCiAqICAgICJfY3JlYXRlZERhdGUiOiAiMjAxNy0wNS0yNFQxMjozMzoxOC45MzhaIiwKICogICAgIl91cGRhdGVkRGF0ZSI6ICIyMDE3LTA1LTI0VDEyOjMzOjE4LjkzOFoiLAogKiAgICAidGl0bGUiOiAgICAgICAgIk1yLiIsCiAqICAgICJmaXJzdF9uYW1lIjogICAiSm9obiIsCiAqICAgICJsYXN0X25hbWUiOiAgICAiRG9lIgogKiAgfQogKi8K
import wixData from 'wix-data';

// ...

let toInsert = {
  "title":        "Mr.",
  "first_name":   "John",
  "last_name":    "Doe"
};

wixData.insert("myCollection", toInsert)
	.then( (results) => {
		let item = results; //see item below
	} )
	.catch( (err) => {
		let errorMsg = 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"
 *  }
 */

Insert an item with a specified ID into a collection

aW1wb3J0IHdpeERhdGEgZnJvbSAnd2l4LWRhdGEnOwoKLy8gLi4uCgpsZXQgdG9JbnNlcnQgPSB7CiAgIl9pZCI6ICAgICAgICAgICIwMDAwMSIsCiAgInRpdGxlIjogICAgICAgICJNci4iLAogICJmaXJzdF9uYW1lIjogICAiSm9obiIsCiAgImxhc3RfbmFtZSI6ICAgICJEb2UiCn07Cgp3aXhEYXRhLmluc2VydCgibXlDb2xsZWN0aW9uIiwgdG9JbnNlcnQpCgkudGhlbiggKHJlc3VsdHMpID0+IHsKCQlsZXQgaXRlbSA9IHJlc3VsdHM7IC8vc2VlIGl0ZW0gYmVsb3cKCX0gKQoJLmNhdGNoKCAoZXJyKSA9PiB7CgkJbGV0IGVycm9yTXNnID0gZXJyOwoJfSApOwoKLyogIGl0ZW0gaXM6CiAqCiAqICB7CiAqICAgICJfaWQiOiAgICAgICAgICAiMDAwMDEiLAogKiAgICAiX293bmVyIjogICAgICAgImZmZGtqOWMyLWRmOGctZjlrZS1sazk4LTRramhmcjg5a2VlZGIiLAogKiAgICAiX2NyZWF0ZWREYXRlIjogIjIwMTctMDUtMjRUMTI6MzM6MTguOTM4WiIsCiAqICAgICJfdXBkYXRlZERhdGUiOiAiMjAxNy0wNS0yNFQxMjozMzoxOC45MzhaIiwKICogICAgInRpdGxlIjogICAgICAgICJNci4iLAogKiAgICAiZmlyc3RfbmFtZSI6ICAgIkpvaG4iLAogKiAgICAibGFzdF9uYW1lIjogICAgIkRvZSIKICogIH0KICovCg==
import wixData from 'wix-data';

// ...

let toInsert = {
  "_id":          "00001",
  "title":        "Mr.",
  "first_name":   "John",
  "last_name":    "Doe"
};

wixData.insert("myCollection", toInsert)
	.then( (results) => {
		let item = results; //see item below
	} )
	.catch( (err) => {
		let errorMsg = 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"
 *  }
 */

Insert an item into a collection using data options

aW1wb3J0IHdpeERhdGEgZnJvbSAnd2l4LWRhdGEnOwoKLy8gLi4uCgpsZXQgdG9JbnNlcnQgPSB7CiAgIl9pZCI6ICAgICAgICAgICIwMDAwMSIsCiAgInRpdGxlIjogICAgICAgICJNci4iLAogICJmaXJzdF9uYW1lIjogICAiSm9obiIsCiAgImxhc3RfbmFtZSI6ICAgICJEb2UiCn07CgpsZXQgb3B0aW9ucyA9IHsKICAic3VwcHJlc3NBdXRoIjogdHJ1ZSwKICAic3VwcHJlc3NIb29rcyI6IHRydWUKfTsKCndpeERhdGEuaW5zZXJ0KCJteUNvbGxlY3Rpb24iLCB0b0luc2VydCwgb3B0aW9ucykKCS50aGVuKCAocmVzdWx0cykgPT4gewoJCWxldCBpdGVtID0gcmVzdWx0czsgLy9zZWUgaXRlbSBiZWxvdwoJfSApCgkuY2F0Y2goIChlcnIpID0+IHsKCQlsZXQgZXJyb3JNc2cgPSBlcnI7Cgl9ICk7CgovKiAgaXRlbSBpczoKICoKICogIHsKICogICAgIl9pZCI6ICAgICAgICAgICIwMDAwMSIsCiAqICAgICJfb3duZXIiOiAgICAgICAiZmZka2o5YzItZGY4Zy1mOWtlLWxrOTgtNGtqaGZyODlrZWVkYiIsCiAqICAgICJfY3JlYXRlZERhdGUiOiAiMjAxNy0wNS0yNFQxMjozMzoxOC45MzhaIiwKICogICAgIl91cGRhdGVkRGF0ZSI6ICIyMDE3LTA1LTI0VDEyOjMzOjE4LjkzOFoiLAogKiAgICAidGl0bGUiOiAgICAgICAgIk1yLiIsCiAqICAgICJmaXJzdF9uYW1lIjogICAiSm9obiIsCiAqICAgICJsYXN0X25hbWUiOiAgICAiRG9lIgogKiAgfQogKi8K
import wixData from 'wix-data';

// ...

let toInsert = {
  "_id":          "00001",
  "title":        "Mr.",
  "first_name":   "John",
  "last_name":    "Doe"
};

let options = {
  "suppressAuth": true,
  "suppressHooks": true
};

wixData.insert("myCollection", toInsert, options)
	.then( (results) => {
		let item = results; //see item below
	} )
	.catch( (err) => {
		let errorMsg = 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"
 *  }
 */

Insert an item including a reference to another item

aW1wb3J0IHdpeERhdGEgZnJvbSAnd2l4LWRhdGEnOwoKLy8gLi4uCgpsZXQgY291bnRyeUlkID0gImlkLW9mLXVzYS1pdGVtIjsKCmxldCB0b0luc2VydCA9IHsKICAidGl0bGUiOiAgICAgICAgIk1yLiIsCiAgImZpcnN0X25hbWUiOiAgICJKb2huIiwKICAibGFzdF9uYW1lIjogICAgIkRvZSIsCiAgImNvdW50cnkiOiAgICAgIGNvdW50cnlJZAp9OwoKd2l4RGF0YS5pbnNlcnQoIm15Q29sbGVjdGlvbiIsIHRvSW5zZXJ0KQogIC50aGVuKCAocmVzdWx0cykgPT4gewogICAgbGV0IGl0ZW0gPSByZXN1bHRzOyAvL3NlZSBpdGVtIGJlbG93CiAgfSApCiAgLmNhdGNoKCAoZXJyKSA9PiB7CiAgICBsZXQgZXJyb3JNc2cgPSBlcnI7CiAgfSApOwoKLyogIGl0ZW0gaXM6CiAqCiAqICB7CiAqICAgICJfaWQiOiAgICAgICAgICAicmlmazRucmstZGo0by1kamhlLW9pZGstZm5vcXc0b2lnbGs0aSIsCiAqICAgICJfb3duZXIiOiAgICAgICAiZmZka2o5YzItZGY4Zy1mOWtlLWxrOTgtNGtqaGZyODlrZWVkYiIsCiAqICAgICJfY3JlYXRlZERhdGUiOiAiMjAxNy0wNS0yNFQxMjozMzoxOC45MzhaIiwKICogICAgIl91cGRhdGVkRGF0ZSI6ICIyMDE3LTA1LTI0VDEyOjMzOjE4LjkzOFoiLAogKiAgICAidGl0bGUiOiAgICAgICAgIk1yLiIsCiAqICAgICJmaXJzdF9uYW1lIjogICAiSm9obiIsCiAqICAgICJsYXN0X25hbWUiOiAgICAiRG9lIiwKICogICAgImNvdW50cnkiOiAgICAgICJpZC1vZi11c2EtaXRlbSIKICogIH0KICovCg==
import wixData from 'wix-data';

// ...

let countryId = "id-of-usa-item";

let toInsert = {
  "title":        "Mr.",
  "first_name":   "John",
  "last_name":    "Doe",
  "country":      countryId
};

wixData.insert("myCollection", toInsert)
  .then( (results) => {
    let item = results; //see item below
  } )
  .catch( (err) => {
    let errorMsg = 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",
 *    "country":      "id-of-usa-item"
 *  }
 */

Insert an item including a reference to another item

aW1wb3J0IHdpeERhdGEgZnJvbSAnd2l4LWRhdGEnOwoKLy8gLi4uCgpsZXQgY291bnRyeUl0ZW0gPSAvLyBnZXQgY291bnRyeSBpdGVtIGZyb20gc29tZXdoZXJlCgpsZXQgdG9JbnNlcnQgPSB7CiAgInRpdGxlIjogICAgICAgICJNci4iLAogICJmaXJzdF9uYW1lIjogICAiSm9obiIsCiAgImxhc3RfbmFtZSI6ICAgICJEb2UiLAogICJjb3VudHJ5IjogICAgICBjb3VudHJ5SXRlbQp9OwoKd2l4RGF0YS5pbnNlcnQoIm15Q29sbGVjdGlvbiIsIHRvSW5zZXJ0KQogIC50aGVuKCAocmVzdWx0cykgPT4gewogICAgbGV0IGl0ZW0gPSByZXN1bHRzOyAvL3NlZSBpdGVtIGJlbG93CiAgfSApCiAgLmNhdGNoKCAoZXJyKSA9PiB7CiAgICBsZXQgZXJyb3JNc2cgPSBlcnI7CiAgfSApOwoKLyogIGl0ZW0gaXM6CiAqCiAqICB7CiAqICAgICJfaWQiOiAgICAgICAgICAicmlmazRucmstZGo0by1kamhlLW9pZGstZm5vcXc0b2lnbGs0aSIsCiAqICAgICJfb3duZXIiOiAgICAgICAiZmZka2o5YzItZGY4Zy1mOWtlLWxrOTgtNGtqaGZyODlrZWVkYiIsCiAqICAgICJfY3JlYXRlZERhdGUiOiAiMjAxNy0wNS0yNFQxMjozMzoxOC45MzhaIiwKICogICAgIl91cGRhdGVkRGF0ZSI6ICIyMDE3LTA1LTI0VDEyOjMzOjE4LjkzOFoiLAogKiAgICAidGl0bGUiOiAgICAgICAgIk1yLiIsCiAqICAgICJmaXJzdF9uYW1lIjogICAiSm9obiIsCiAqICAgICJsYXN0X25hbWUiOiAgICAiRG9lIiwKICogICAgImNvdW50cnkiOiAgICAgICJpZC1vZi11c2EtaXRlbSIKICogIH0KICovCg==
import wixData from 'wix-data';

// ...

let countryItem = // get country item from somewhere

let toInsert = {
  "title":        "Mr.",
  "first_name":   "John",
  "last_name":    "Doe",
  "country":      countryItem
};

wixData.insert("myCollection", toInsert)
  .then( (results) => {
    let item = results; //see item below
  } )
  .catch( (err) => {
    let errorMsg = 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",
 *    "country":      "id-of-usa-item"
 *  }
 */
query( )

query( )

Creates a query.

function query(collectionName: String): WixDataQuery

Description

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 on to the query. WixDataQuery functions enable you to sort, filter, and control the number of results a query returns.

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

The functions that are chained to query() are applied in the order they are called. For example, if you sort on an age property in ascending order and then on a name property in descending order, the results are sorted first by the age of the items and then, if there are multiple results with the same age, the items are sorted by name in descending order, per age value.

Parameters

collectionName String The collection you want to run the query on.

Return Value

WixDataQuery A query object.

Examples

Build a query

aW1wb3J0IHdpeERhdGEgZnJvbSAnd2l4LWRhdGEnOwoKLy8gLi4uCgpsZXQgcXVlcnkgPSB3aXhEYXRhLnF1ZXJ5KCJteUNvbGxlY3Rpb24iKTsK
import wixData from 'wix-data';

// ...

let query = wixData.query("myCollection");

Build and perform a query

aW1wb3J0IHdpeERhdGEgZnJvbSAnd2l4LWRhdGEnOwoKLy8gLi4uCgp3aXhEYXRhLnF1ZXJ5KCJteUNvbGxlY3Rpb24iKQogIC5maW5kKCkKICAudGhlbiggKHJlc3VsdHMpID0+IHsKICAgIGxldCBmaXJzdEl0ZW0gPSByZXN1bHRzLml0ZW1zWzBdOyAvL3NlZSBpdGVtIGJlbG93CiAgfSApCiAgLmNhdGNoKCAoZXJyKSA9PiB7CiAgICBsZXQgZXJyb3JNc2cgPSBlcnI7CiAgfSApOwoKLyogIGZpcnN0SXRlbSBpczoKICoKICogIHsKICogICAgIl9pZCI6ICAgICAgICAgICIwMDAwMSIsCiAqICAgICJfb3duZXIiOiAgICAgICAiZmZka2o5YzItZGY4Zy1mOWtlLWxrOTgtNGtqaGZyODlrZWVkYiIsCiAqICAgICJfY3JlYXRlZERhdGUiOiAiMjAxNy0wNS0yNFQxMjozMzoxOC45MzhaIiwKICogICAgIl91cGRhdGVkRGF0ZSI6ICIyMDE3LTA1LTI0VDEyOjMzOjE4LjkzOFoiLAogKiAgICAidGl0bGUiOiAgICAgICAgIk1yLiIsCiAqICAgICJmaXJzdF9uYW1lIjogICAiSm9obiIsCiAqICAgICJsYXN0X25hbWUiOiAgICAiRG9lIgogKiAgfQogKi8K
import wixData from 'wix-data';

// ...

wixData.query("myCollection")
  .find()
  .then( (results) => {
    let firstItem = results.items[0]; //see item below
  } )
  .catch( (err) => {
    let errorMsg = err;
  } );

/*  firstItem 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"
 *  }
 */

Build and perform a query using data options

aW1wb3J0IHdpeERhdGEgZnJvbSAnd2l4LWRhdGEnOwoKLy8gLi4uCgp3aXhEYXRhLnF1ZXJ5KCJteUNvbGxlY3Rpb24iKQogIC5lcSgidGl0bGUiLCAiRHIuIikKICAuZmluZCgpCiAgLnRoZW4oIChyZXN1bHRzKSA9PiB7CiAgICBsZXQgZmlyc3RJdGVtID0gcmVzdWx0cy5pdGVtc1swXTsgLy9zZWUgaXRlbSBiZWxvdwogIH0gKQogIC5jYXRjaCggKGVycikgPT4gewogICAgbGV0IGVycm9yTXNnID0gZXJyOwogIH0gKTsKCi8qICBmaXJzdEl0ZW0gaXM6CiAqCiAqICB7CiAqICAgICJfaWQiOiAgICAgICAgICAiMDAwMDIiLAogKiAgICAiX293bmVyIjogICAgICAgImZmZGtqOWMyLWRmOGctZjlrZS1sazk4LTRramhmcjg5a2VlZGIiLAogKiAgICAiX2NyZWF0ZWREYXRlIjogIjIwMTctMDUtMjRUMTI6MzM6MTguOTM4WiIsCiAqICAgICJfdXBkYXRlZERhdGUiOiAiMjAxNy0wNS0yNFQxMjozMzoxOC45MzhaIiwKICogICAgInRpdGxlIjogICAgICAgICJEci4iLAogKiAgICAiZmlyc3RfbmFtZSI6ICAgIkphbmUiLAogKiAgICAibGFzdF9uYW1lIjogICAgIkRvZSIKICogIH0KICovCg==
import wixData from 'wix-data';

// ...

wixData.query("myCollection")
  .eq("title", "Dr.")
  .find()
  .then( (results) => {
    let firstItem = results.items[0]; //see item below
  } )
  .catch( (err) => {
    let errorMsg = err;
  } );

/*  firstItem is:
 *
 *  {
 *    "_id":          "00002",
 *    "_owner":       "ffdkj9c2-df8g-f9ke-lk98-4kjhfr89keedb",
 *    "_createdDate": "2017-05-24T12:33:18.938Z",
 *    "_updatedDate": "2017-05-24T12:33:18.938Z",
 *    "title":        "Dr.",
 *    "first_name":   "Jane",
 *    "last_name":    "Doe"
 *  }
 */

Build a query incrementally

This example builds a query based on certain conditions. It then performs the query and uses the results to populate a table.

aW1wb3J0IHdpeERhdGEgZnJvbSAnd2l4LWRhdGEnOwoKLy8gLi4uCgpmdW5jdGlvbiBydW5RdWVyeShsb3csIGhpZ2gpIHsKICBsZXQgcXVlcnkgPSB3aXhEYXRhLnF1ZXJ5KCJteUNvbGxlY3Rpb24iKTsKCiAgaWYobG93KSB7CiAgICBxdWVyeSA9IHF1ZXJ5LmdlKCJwcmljZSIsIGxvdyk7CiAgfQoKICBpZihoaWdoKSB7CiAgICBxdWVyeSA9IHF1ZXJ5LmxlKCJsZW5ndGgiLCBoaWdoKTsKICB9CgogIHF1ZXJ5LmZpbmQoKQogICAgLnRoZW4oIChyZXN1bHRzKSA9PiB7CiAgICAgICR3KCIjbXlUYWJsZSIpLnJvd3MgPSByZXN1bHRzLml0ZW1zOwogICAgfSApOwp9Cg==
import wixData from 'wix-data';

// ...

function runQuery(low, high) {
  let query = wixData.query("myCollection");

  if(low) {
    query = query.ge("price", low);
  }

  if(high) {
    query = query.le("length", high);
  }

  query.find()
    .then( (results) => {
      $w("#myTable").rows = results.items;
    } );
}
remove( )

remove( )

Removes an item from a collection.

function remove(collectionName: String, itemId: String,
  [options:WixDataOptions]): Promise<Object>

Description

The remove() function returns a Promise that resolves to the removed item after the specified item has been deleted from the collection collectionName. 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() without checking for permissions or without its registered hooks.

Parameters

collectionName String The collection to remove the item from.
itemId String The ID of the item to remove.
options (optional) WixDataOptions An object with one or both of the following boolean properties: suppressAuth, suppressHooks.

Return Value

Returns a Promise

On fulfillment Object The removed item.
On rejection Error The error that caused the rejection.

Examples

Remove an item from a collection

aW1wb3J0IHdpeERhdGEgZnJvbSAnd2l4LWRhdGEnOwoKLy8gLi4uCgp3aXhEYXRhLnJlbW92ZSgibXlDb2xsZWN0aW9uIiwgIjAwMDAxIikKICAudGhlbiggKHJlc3VsdHMpID0+IHsKICAgIGxldCBpdGVtID0gcmVzdWx0czsgLy9zZWUgaXRlbSBiZWxvdwogIH0gKQogIC5jYXRjaCggKGVycikgPT4gewogICAgbGV0IGVycm9yTXNnID0gZXJyOwogIH0gKTsKCi8qICBpdGVtIGlzOgogKgogKiAgewogKiAgICAiX2lkIjogICAgICAgICAgIjAwMDAxIiwKICogICAgIl9vd25lciI6ICAgICAgICJmZmRrajljMi1kZjhnLWY5a2UtbGs5OC00a2poZnI4OWtlZWRiIiwKICogICAgIl9jcmVhdGVkRGF0ZSI6ICIyMDE3LTA1LTI0VDEyOjMzOjE4LjkzOFoiLAogKiAgICAiX3VwZGF0ZWREYXRlIjogIjIwMTctMDUtMjRUMTI6MzM6MTguOTM4WiIsCiAqICAgICJ0aXRsZSI6ICAgICAgICAiTXIuIiwKICogICAgImZpcnN0X25hbWUiOiAgICJKb2huIiwKICogICAgImxhc3RfbmFtZSI6ICAgICJEb2UiCiAqICB9CiAqLwo=
import wixData from 'wix-data';

// ...

wixData.remove("myCollection", "00001")
  .then( (results) => {
    let item = results; //see item below
  } )
  .catch( (err) => {
    let errorMsg = 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"
 *  }
 */

Remove an item from a collection using data options

aW1wb3J0IHdpeERhdGEgZnJvbSAnd2l4LWRhdGEnOwoKLy8gLi4uCgpsZXQgb3B0aW9ucyA9IHsKICAic3VwcHJlc3NBdXRoIjogdHJ1ZSwKICAic3VwcHJlc3NIb29rcyI6IHRydWUKfTsKCndpeERhdGEucmVtb3ZlKCJteUNvbGxlY3Rpb24iLCAiMDAwMDEiLCBvcHRpb25zKQogIC50aGVuKCAocmVzdWx0cykgPT4gewogICAgbGV0IGl0ZW0gPSByZXN1bHRzOyAvL3NlZSBpdGVtIGJlbG93CiAgfSApCiAgLmNhdGNoKCAoZXJyKSA9PiB7CiAgICBsZXQgZXJyb3JNc2cgPSBlcnI7CiAgfSApOwoKLyogIGl0ZW0gaXM6CiAqCiAqICB7CiAqICAgICJfaWQiOiAgICAgICAgICAiMDAwMDEiLAogKiAgICAiX293bmVyIjogICAgICAgImZmZGtqOWMyLWRmOGctZjlrZS1sazk4LTRramhmcjg5a2VlZGIiLAogKiAgICAiX2NyZWF0ZWREYXRlIjogIjIwMTctMDUtMjRUMTI6MzM6MTguOTM4WiIsCiAqICAgICJfdXBkYXRlZERhdGUiOiAiMjAxNy0wNS0yNFQxMjozMzoxOC45MzhaIiwKICogICAgInRpdGxlIjogICAgICAgICJNci4iLAogKiAgICAiZmlyc3RfbmFtZSI6ICAgIkpvaG4iLAogKiAgICAibGFzdF9uYW1lIjogICAgIkRvZSIKICogIH0KICovCg==
import wixData from 'wix-data';

// ...

let options = {
  "suppressAuth": true,
  "suppressHooks": true
};

wixData.remove("myCollection", "00001", options)
  .then( (results) => {
    let item = results; //see item below
  } )
  .catch( (err) => {
    let errorMsg = 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"
 *  }
 */
save( )

save( )

Inserts or updates an item in a collection.

function save(collectionName: String, item: object,
  [options:WixDataOptions]): Promise<Object>

Description

The save() function returns a Promise that resolves to the inserted or updated item after the specified item has been added or updated in the collection collectionName. The Promise is rejected with an error if:

  • The specified collection does not exist.
  • The specified item is not of type Object.
  • 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 no items in the collection have that _id value, or if the specified item does not have an _id property, save uses insert to add the specified item into the collection, triggering the beforeInsert() and afterInsert() hooks if they have been defined.

Use the options parameter to run save() 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.

Parameters

collectionName String The name of the collection to save the item to.
item Object The item to insert or update.
options (optional) WixDataOptions An object with one or both of the following boolean properties: suppressAuth, suppressHooks.

Return Value

Returns a Promise

On fulfillment Object The item that was either inserted or updated, depending on whether it previously existed in the collection.
On rejection Error The error that caused the rejection.

Examples

Save an item in a collection

aW1wb3J0IHdpeERhdGEgZnJvbSAnd2l4LWRhdGEnOwoKLy8gLi4uCgpsZXQgdG9TYXZlID0gewogICJ0aXRsZSI6ICAgICAgICAiTXIuIiwKICAiZmlyc3RfbmFtZSI6ICAgIkpvaG4iLAogICJsYXN0X25hbWUiOiAgICAiRG9lIgp9OwoKd2l4RGF0YS5zYXZlKCJteUNvbGxlY3Rpb24iLCB0b1NhdmUpCgkudGhlbiggKHJlc3VsdHMpID0+IHsKCQlsZXQgaXRlbSA9IHJlc3VsdHM7IC8vc2VlIGl0ZW0gYmVsb3cKCX0gKQoJLmNhdGNoKCAoZXJyKSA9PiB7CgkJbGV0IGVycm9yTXNnID0gZXJyOwoJfSApOwoKLyogIGl0ZW0gaXM6CiAqCiAqICB7CiAqICAgICJfaWQiOiAgICAgICAgICAicmlmazRucmstZGo0by1kamhlLW9pZGstZm5vcXc0b2lnbGs0aSIsCiAqICAgICJfb3duZXIiOiAgICAgICAiZmZka2o5YzItZGY4Zy1mOWtlLWxrOTgtNGtqaGZyODlrZWVkYiIsCiAqICAgICJfY3JlYXRlZERhdGUiOiAiMjAxNy0wNS0yNFQxMjozMzoxOC45MzhaIiwKICogICAgIl91cGRhdGVkRGF0ZSI6ICIyMDE3LTA1LTI0VDEyOjMzOjE4LjkzOFoiLAogKiAgICAidGl0bGUiOiAgICAgICAgIk1yLiIsCiAqICAgICJmaXJzdF9uYW1lIjogICAiSm9obiIsCiAqICAgICJsYXN0X25hbWUiOiAgICAiRG9lIgogKiAgfQogKi8K
import wixData from 'wix-data';

// ...

let toSave = {
  "title":        "Mr.",
  "first_name":   "John",
  "last_name":    "Doe"
};

wixData.save("myCollection", toSave)
	.then( (results) => {
		let item = results; //see item below
	} )
	.catch( (err) => {
		let errorMsg = 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"
 *  }
 */

Save an item with a specified ID in a collection

aW1wb3J0IHdpeERhdGEgZnJvbSAnd2l4LWRhdGEnOwoKLy8gLi4uCgpsZXQgdG9TYXZlID0gewogICJfaWQiOiAgICAgICAgICAiMDAwMDEiLAogICJ0aXRsZSI6ICAgICAgICAiTXIuIiwKICAiZmlyc3RfbmFtZSI6ICAgIkpvaG4iLAogICJsYXN0X25hbWUiOiAgICAiRG9lIgp9OwoKd2l4RGF0YS5zYXZlKCJteUNvbGxlY3Rpb24iLCB0b1NhdmUpCgkudGhlbiggKHJlc3VsdHMpID0+IHsKCQlsZXQgaXRlbSA9IHJlc3VsdHM7IC8vc2VlIGl0ZW0gYmVsb3cKCX0gKQoJLmNhdGNoKCAoZXJyKSA9PiB7CgkJbGV0IGVycm9yTXNnID0gZXJyOwoJfSApOwoKLyogIGl0ZW0gaXM6CiAqCiAqICB7CiAqICAgICJfaWQiOiAgICAgICAgICAiMDAwMDEiLAogKiAgICAiX293bmVyIjogICAgICAgImZmZGtqOWMyLWRmOGctZjlrZS1sazk4LTRramhmcjg5a2VlZGIiLAogKiAgICAiX2NyZWF0ZWREYXRlIjogIjIwMTctMDUtMjRUMTI6MzM6MTguOTM4WiIsCiAqICAgICJfdXBkYXRlZERhdGUiOiAiMjAxNy0wNS0yNFQxMjozMzoxOC45MzhaIiwKICogICAgInRpdGxlIjogICAgICAgICJNci4iLAogKiAgICAiZmlyc3RfbmFtZSI6ICAgIkpvaG4iLAogKiAgICAibGFzdF9uYW1lIjogICAgIkRvZSIKICogIH0KICovCg==
import wixData from 'wix-data';

// ...

let toSave = {
  "_id":          "00001",
  "title":        "Mr.",
  "first_name":   "John",
  "last_name":    "Doe"
};

wixData.save("myCollection", toSave)
	.then( (results) => {
		let item = results; //see item below
	} )
	.catch( (err) => {
		let errorMsg = 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"
 *  }
 */

Save an item in a collection using data options

aW1wb3J0IHdpeERhdGEgZnJvbSAnd2l4LWRhdGEnOwoKLy8gLi4uCgpsZXQgdG9TYXZlID0gewogICJfaWQiOiAgICAgICAgICAiMDAwMDEiLAogICJ0aXRsZSI6ICAgICAgICAiTXIuIiwKICAiZmlyc3RfbmFtZSI6ICAgIkpvaG4iLAogICJsYXN0X25hbWUiOiAgICAiRG9lIgp9OwoKbGV0IG9wdGlvbnMgPSB7CiAgInN1cHByZXNzQXV0aCI6IHRydWUsCiAgInN1cHByZXNzSG9va3MiOiB0cnVlCn07Cgp3aXhEYXRhLnNhdmUoIm15Q29sbGVjdGlvbiIsIHRvU2F2ZSwgb3B0aW9ucykKCS50aGVuKCAocmVzdWx0cykgPT4gewoJCWxldCBpdGVtID0gcmVzdWx0czsgLy9zZWUgaXRlbSBiZWxvdwoJfSApCgkuY2F0Y2goIChlcnIpID0+IHsKCQlsZXQgZXJyb3JNc2cgPSBlcnI7Cgl9ICk7CgovKiAgaXRlbSBpczoKICoKICogIHsKICogICAgIl9pZCI6ICAgICAgICAgICIwMDAwMSIsCiAqICAgICJfb3duZXIiOiAgICAgICAiZmZka2o5YzItZGY4Zy1mOWtlLWxrOTgtNGtqaGZyODlrZWVkYiIsCiAqICAgICJfY3JlYXRlZERhdGUiOiAiMjAxNy0wNS0yNFQxMjozMzoxOC45MzhaIiwKICogICAgIl91cGRhdGVkRGF0ZSI6ICIyMDE3LTA1LTI0VDEyOjMzOjE4LjkzOFoiLAogKiAgICAidGl0bGUiOiAgICAgICAgIk1yLiIsCiAqICAgICJmaXJzdF9uYW1lIjogICAiSm9obiIsCiAqICAgICJsYXN0X25hbWUiOiAgICAiRG9lIgogKiAgfQogKi8K
import wixData from 'wix-data';

// ...

let toSave = {
  "_id":          "00001",
  "title":        "Mr.",
  "first_name":   "John",
  "last_name":    "Doe"
};

let options = {
  "suppressAuth": true,
  "suppressHooks": true
};

wixData.save("myCollection", toSave, options)
	.then( (results) => {
		let item = results; //see item below
	} )
	.catch( (err) => {
		let errorMsg = 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"
 *  }
 */

Save an item including a reference to another item

aW1wb3J0IHdpeERhdGEgZnJvbSAnd2l4LWRhdGEnOwoKLy8gLi4uCgpsZXQgY291bnRyeUlkID0gImlkLW9mLXVzYS1pdGVtIjsKCmxldCB0b1NhdmUgPSB7CiAgInRpdGxlIjogICAgICAgICJNci4iLAogICJmaXJzdF9uYW1lIjogICAiSm9obiIsCiAgImxhc3RfbmFtZSI6ICAgICJEb2UiLAogICJjb3VudHJ5IjogICAgICBjb3VudHJ5SWQKfTsKCndpeERhdGEuc2F2ZSgibXlDb2xsZWN0aW9uIiwgdG9TYXZlKQogIC50aGVuKCAocmVzdWx0cykgPT4gewogICAgbGV0IGl0ZW0gPSByZXN1bHRzOyAvL3NlZSBpdGVtIGJlbG93CiAgfSApCiAgLmNhdGNoKCAoZXJyKSA9PiB7CiAgICBsZXQgZXJyb3JNc2cgPSBlcnI7CiAgfSApOwoKLyogIGl0ZW0gaXM6CiAqCiAqICB7CiAqICAgICJfaWQiOiAgICAgICAgICAicmlmazRucmstZGo0by1kamhlLW9pZGstZm5vcXc0b2lnbGs0aSIsCiAqICAgICJfb3duZXIiOiAgICAgICAiZmZka2o5YzItZGY4Zy1mOWtlLWxrOTgtNGtqaGZyODlrZWVkYiIsCiAqICAgICJfY3JlYXRlZERhdGUiOiAiMjAxNy0wNS0yNFQxMjozMzoxOC45MzhaIiwKICogICAgIl91cGRhdGVkRGF0ZSI6ICIyMDE3LTA1LTI0VDEyOjMzOjE4LjkzOFoiLAogKiAgICAidGl0bGUiOiAgICAgICAgIk1yLiIsCiAqICAgICJmaXJzdF9uYW1lIjogICAiSm9obiIsCiAqICAgICJsYXN0X25hbWUiOiAgICAiRG9lIiwKICogICAgImNvdW50cnkiOiAgICAgICJpZC1vZi11c2EtaXRlbSIKICogIH0KICovCg==
import wixData from 'wix-data';

// ...

let countryId = "id-of-usa-item";

let toSave = {
  "title":        "Mr.",
  "first_name":   "John",
  "last_name":    "Doe",
  "country":      countryId
};

wixData.save("myCollection", toSave)
  .then( (results) => {
    let item = results; //see item below
  } )
  .catch( (err) => {
    let errorMsg = 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",
 *    "country":      "id-of-usa-item"
 *  }
 */

Save an item including a reference to another item

aW1wb3J0IHdpeERhdGEgZnJvbSAnd2l4LWRhdGEnOwoKLy8gLi4uCgpsZXQgY291bnRyeUl0ZW0gPSAvLyBnZXQgY291bnRyeSBpdGVtIGZyb20gc29tZXdoZXJlCgpsZXQgdG9TYXZlID0gewogICJ0aXRsZSI6ICAgICAgICAiTXIuIiwKICAiZmlyc3RfbmFtZSI6ICAgIkpvaG4iLAogICJsYXN0X25hbWUiOiAgICAiRG9lIiwKICAiY291bnRyeSI6ICAgICAgY291bnRyeUl0ZW0KfTsKCndpeERhdGEuc2F2ZSgibXlDb2xsZWN0aW9uIiwgdG9TYXZlKQogIC50aGVuKCAocmVzdWx0cykgPT4gewogICAgbGV0IGl0ZW0gPSByZXN1bHRzOyAvL3NlZSBpdGVtIGJlbG93CiAgfSApCiAgLmNhdGNoKCAoZXJyKSA9PiB7CiAgICBsZXQgZXJyb3JNc2cgPSBlcnI7CiAgfSApOwoKLyogIGl0ZW0gaXM6CiAqCiAqICB7CiAqICAgICJfaWQiOiAgICAgICAgICAicmlmazRucmstZGo0by1kamhlLW9pZGstZm5vcXc0b2lnbGs0aSIsCiAqICAgICJfb3duZXIiOiAgICAgICAiZmZka2o5YzItZGY4Zy1mOWtlLWxrOTgtNGtqaGZyODlrZWVkYiIsCiAqICAgICJfY3JlYXRlZERhdGUiOiAiMjAxNy0wNS0yNFQxMjozMzoxOC45MzhaIiwKICogICAgIl91cGRhdGVkRGF0ZSI6ICIyMDE3LTA1LTI0VDEyOjMzOjE4LjkzOFoiLAogKiAgICAidGl0bGUiOiAgICAgICAgIk1yLiIsCiAqICAgICJmaXJzdF9uYW1lIjogICAiSm9obiIsCiAqICAgICJsYXN0X25hbWUiOiAgICAiRG9lIiwKICogICAgImNvdW50cnkiOiAgICAgICJpZC1vZi11c2EtaXRlbSIKICogIH0KICovCg==
import wixData from 'wix-data';

// ...

let countryItem = // get country item from somewhere

let toSave = {
  "title":        "Mr.",
  "first_name":   "John",
  "last_name":    "Doe",
  "country":      countryItem
};

wixData.save("myCollection", toSave)
  .then( (results) => {
    let item = results; //see item below
  } )
  .catch( (err) => {
    let errorMsg = 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",
 *    "country":      "id-of-usa-item"
 *  }
 */
sort( )

sort( )

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

function sort(): WixDataSort

Description

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

Return Value

WixDataSort A sort object.

Examples

Sort a dataset

aW1wb3J0IHdpeERhdGEgZnJvbSAnd2l4LWRhdGEnOwoKLy8gLi4uCgokdygiI215RGF0YXNldCIpLnNldFNvcnQoIHdpeERhdGEuc29ydCgpCiAgLmFzY2VuZGluZygibGFzdE5hbWUiKQogIC5kZXNjZW5kaW5nKCJhZ2UiKQopOwo=
import wixData from 'wix-data';

// ...

$w("#myDataset").setSort( wixData.sort()
  .ascending("lastName")
  .descending("age")
);
update( )

update( )

Updates an item in a collection.

function update(collectionName: String, item: Object,
  [options:WixDataOptions]): Promise<Object>

Description

The update() function returns a Promise that resolves to the updated item from collection collectionName. The Promise is rejected if:

  • The specified collection does not exist.
  • The specified item is not of type Object.
  • No item in the collection has the specified _id value.
  • The specified item does not have an _id property.
  • 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 replaced 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 supplied 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() 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 200kb.

Parameters

collectionName String The name of the collection that contains the item to update.
item Object The item to update.
options (optional) WixDataOptions An object with one or both of the following boolean properties: suppressAuth, suppressHooks.

Return Value

Returns a Promise

On fulfillment Object The object that was updated.
On rejection Error The error that caused the rejection.

Examples

Update an item with a specified ID in a collection

aW1wb3J0IHdpeERhdGEgZnJvbSAnd2l4LWRhdGEnOwoKLy8gLi4uCgpsZXQgdG9VcGRhdGUgPSB7CiAgIl9pZCI6ICAgICAgICAgICIwMDAwMSIsCiAgInRpdGxlIjogICAgICAgICJNci4iLAogICJmaXJzdF9uYW1lIjogICAiSm9obiIsCiAgImxhc3RfbmFtZSI6ICAgICJEb2UiCn07Cgp3aXhEYXRhLnVwZGF0ZSgibXlDb2xsZWN0aW9uIiwgdG9VcGRhdGUpCgkudGhlbiggKHJlc3VsdHMpID0+IHsKCQlsZXQgaXRlbSA9IHJlc3VsdHM7IC8vc2VlIGl0ZW0gYmVsb3cKCX0gKQoJLmNhdGNoKCAoZXJyKSA9PiB7CgkJbGV0IGVycm9yTXNnID0gZXJyOwoJfSApOwoKLyogIGl0ZW0gaXM6CiAqCiAqICB7CiAqICAgICJfaWQiOiAgICAgICAgICAiMDAwMDEiLAogKiAgICAiX293bmVyIjogICAgICAgImZmZGtqOWMyLWRmOGctZjlrZS1sazk4LTRramhmcjg5a2VlZGIiLAogKiAgICAiX2NyZWF0ZWREYXRlIjogIjIwMTctMDUtMjRUMTI6MzM6MTguOTM4WiIsCiAqICAgICJfdXBkYXRlZERhdGUiOiAiMjAxNy0wNS0yNFQxMjozMzoxOC45MzhaIiwKICogICAgInRpdGxlIjogICAgICAgICJNci4iLAogKiAgICAiZmlyc3RfbmFtZSI6ICAgIkpvaG4iLAogKiAgICAibGFzdF9uYW1lIjogICAgIkRvZSIKICogIH0KICovCg==
import wixData from 'wix-data';

// ...

let toUpdate = {
  "_id":          "00001",
  "title":        "Mr.",
  "first_name":   "John",
  "last_name":    "Doe"
};

wixData.update("myCollection", toUpdate)
	.then( (results) => {
		let item = results; //see item below
	} )
	.catch( (err) => {
		let errorMsg = 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"
 *  }
 */

Update an item in a collection using data options

aW1wb3J0IHdpeERhdGEgZnJvbSAnd2l4LWRhdGEnOwoKLy8gLi4uCgpsZXQgdG9VcGRhdGUgPSB7CiAgIl9pZCI6ICAgICAgICAgICIwMDAwMSIsCiAgInRpdGxlIjogICAgICAgICJNci4iLAogICJmaXJzdF9uYW1lIjogICAiSm9obiIsCiAgImxhc3RfbmFtZSI6ICAgICJEb2UiCn07CgpsZXQgb3B0aW9ucyA9IHsKICAic3VwcHJlc3NBdXRoIjogdHJ1ZSwKICAic3VwcHJlc3NIb29rcyI6IHRydWUKfTsKCndpeERhdGEudXBkYXRlKCJteUNvbGxlY3Rpb24iLCB0b1VwZGF0ZSwgb3B0aW9ucykKCS50aGVuKCAocmVzdWx0cykgPT4gewoJCWxldCBpdGVtID0gcmVzdWx0czsgLy9zZWUgaXRlbSBiZWxvdwoJfSApCgkuY2F0Y2goIChlcnIpID0+IHsKCQlsZXQgZXJyb3JNc2cgPSBlcnI7Cgl9ICk7CgovKiAgaXRlbSBpczoKICoKICogIHsKICogICAgIl9pZCI6ICAgICAgICAgICIwMDAwMSIsCiAqICAgICJfb3duZXIiOiAgICAgICAiZmZka2o5YzItZGY4Zy1mOWtlLWxrOTgtNGtqaGZyODlrZWVkYiIsCiAqICAgICJfY3JlYXRlZERhdGUiOiAiMjAxNy0wNS0yNFQxMjozMzoxOC45MzhaIiwKICogICAgIl91cGRhdGVkRGF0ZSI6ICIyMDE3LTA1LTI0VDEyOjMzOjE4LjkzOFoiLAogKiAgICAidGl0bGUiOiAgICAgICAgIk1yLiIsCiAqICAgICJmaXJzdF9uYW1lIjogICAiSm9obiIsCiAqICAgICJsYXN0X25hbWUiOiAgICAiRG9lIgogKiAgfQogKi8K
import wixData from 'wix-data';

// ...

let toUpdate = {
  "_id":          "00001",
  "title":        "Mr.",
  "first_name":   "John",
  "last_name":    "Doe"
};

let options = {
  "suppressAuth": true,
  "suppressHooks": true
};

wixData.update("myCollection", toUpdate, options)
	.then( (results) => {
		let item = results; //see item below
	} )
	.catch( (err) => {
		let errorMsg = 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"
 *  }
 */

Update an item including a reference to another item

aW1wb3J0IHdpeERhdGEgZnJvbSAnd2l4LWRhdGEnOwoKLy8gLi4uCgpldCBjb3VudHJ5SWQgPSAiaWQtb2YtdXNhLWl0ZW0iOwoKbGV0IHRvVXBkYXRlID0gewogICJfaWQiOiAgICAgICAgICAiMDAwMDEiLAogICJ0aXRsZSI6ICAgICAgICAiTXIuIiwKICAiZmlyc3RfbmFtZSI6ICAgIkpvaG4iLAogICJsYXN0X25hbWUiOiAgICAiRG9lIiwKICAiY291bnRyeSI6ICAgICAgY291bnRyeUlkCn07Cgp3aXhEYXRhLnVwZGF0ZSgibXlDb2xsZWN0aW9uIiwgdG9VcGRhdGUpCgkudGhlbiggKHJlc3VsdHMpID0+IHsKCQlsZXQgaXRlbSA9IHJlc3VsdHM7IC8vc2VlIGl0ZW0gYmVsb3cKCX0gKQoJLmNhdGNoKCAoZXJyKSA9PiB7CgkJbGV0IGVycm9yTXNnID0gZXJyOwoJfSApOwoKLyogIGl0ZW0gaXM6CiAqCiAqICB7CiAqICAgICJfaWQiOiAgICAgICAgICAicmlmazRucmstZGo0by1kamhlLW9pZGstZm5vcXc0b2lnbGs0aSIsCiAqICAgICJfb3duZXIiOiAgICAgICAiZmZka2o5YzItZGY4Zy1mOWtlLWxrOTgtNGtqaGZyODlrZWVkYiIsCiAqICAgICJfY3JlYXRlZERhdGUiOiAiMjAxNy0wNS0yNFQxMjozMzoxOC45MzhaIiwKICogICAgIl91cGRhdGVkRGF0ZSI6ICIyMDE3LTA1LTI0VDEyOjMzOjE4LjkzOFoiLAogKiAgICAidGl0bGUiOiAgICAgICAgIk1yLiIsCiAqICAgICJmaXJzdF9uYW1lIjogICAiSm9obiIsCiAqICAgICJsYXN0X25hbWUiOiAgICAiRG9lIiwKICogICAgImNvdW50cnkiOiAgICAgICJpZC1vZi11c2EtaXRlbSIKICogIH0KICovCg==
import wixData from 'wix-data';

// ...

et countryId = "id-of-usa-item";

let toUpdate = {
  "_id":          "00001",
  "title":        "Mr.",
  "first_name":   "John",
  "last_name":    "Doe",
  "country":      countryId
};

wixData.update("myCollection", toUpdate)
	.then( (results) => {
		let item = results; //see item below
	} )
	.catch( (err) => {
		let errorMsg = 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",
 *    "country":      "id-of-usa-item"
 *  }
 */

Update an item including a reference to another item

aW1wb3J0IHdpeERhdGEgZnJvbSAnd2l4LWRhdGEnOwoKLy8gLi4uCgpsZXQgY291bnRyeUl0ZW0gPSAvLyBnZXQgY291bnRyeSBpdGVtIGZyb20gc29tZXdoZXJlCgpsZXQgdG9VcGRhdGUgPSB7CiAgIl9pZCI6ICAgICAgICAgICIwMDAwMSIsCiAgInRpdGxlIjogICAgICAgICJNci4iLAogICJmaXJzdF9uYW1lIjogICAiSm9obiIsCiAgImxhc3RfbmFtZSI6ICAgICJEb2UiLAogICJjb3VudHJ5IjogICAgICBjb3VudHJ5SXRlbQp9OwoKd2l4RGF0YS51cGRhdGUoIm15Q29sbGVjdGlvbiIsIHRvVXBkYXRlKQoJLnRoZW4oIChyZXN1bHRzKSA9PiB7CgkJbGV0IGl0ZW0gPSByZXN1bHRzOyAvL3NlZSBpdGVtIGJlbG93Cgl9ICkKCS5jYXRjaCggKGVycikgPT4gewoJCWxldCBlcnJvck1zZyA9IGVycjsKCX0gKTsKCi8qICBpdGVtIGlzOgogKgogKiAgewogKiAgICAiX2lkIjogICAgICAgICAgInJpZms0bnJrLWRqNG8tZGpoZS1vaWRrLWZub3F3NG9pZ2xrNGkiLAogKiAgICAiX293bmVyIjogICAgICAgImZmZGtqOWMyLWRmOGctZjlrZS1sazk4LTRramhmcjg5a2VlZGIiLAogKiAgICAiX2NyZWF0ZWREYXRlIjogIjIwMTctMDUtMjRUMTI6MzM6MTguOTM4WiIsCiAqICAgICJfdXBkYXRlZERhdGUiOiAiMjAxNy0wNS0yNFQxMjozMzoxOC45MzhaIiwKICogICAgInRpdGxlIjogICAgICAgICJNci4iLAogKiAgICAiZmlyc3RfbmFtZSI6ICAgIkpvaG4iLAogKiAgICAibGFzdF9uYW1lIjogICAgIkRvZSIsCiAqICAgICJjb3VudHJ5IjogICAgICAiaWQtb2YtdXNhLWl0ZW0iCiAqICB9CiAqLwo=
import wixData from 'wix-data';

// ...

let countryItem = // get country item from somewhere

let toUpdate = {
  "_id":          "00001",
  "title":        "Mr.",
  "first_name":   "John",
  "last_name":    "Doe",
  "country":      countryItem
};

wixData.update("myCollection", toUpdate)
	.then( (results) => {
		let item = results; //see item below
	} )
	.catch( (err) => {
		let errorMsg = 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",
 *    "country":      "id-of-usa-item"
 *  }
 */
WixDataOptions

WixDataOptions

An object that you pass as the options parameter that modifies how an operation is performed.

Description

The options parameter is an optional parameter that can be used when calling some wix-data functions. To use options, pass it a WixDataOptions object with one or both of the following key:value pairs:

  • "suppressAuth": true/false
  • "suppressHooks": true/false

The options parameter can only be used in backend code. Permission checks and hooks always run for wix-data functions called from Page, Site and Public code.

Properties

suppressAuth Boolean Prevents permission checks from running for the operation.
suppressHooks Boolean Prevents hooks from running for the operation.

Examples

Create a data options object

bGV0IG9wdGlvbnMgPSB7CiAgInN1cHByZXNzQXV0aCI6IHRydWUsCiAgInN1cHByZXNzSG9va3MiOiB0cnVlCn07Cg==
let options = {
  "suppressAuth": true,
  "suppressHooks": true
};

Use data options to prevent permission checks and hooks from running

aW1wb3J0IHdpeERhdGEgZnJvbSAnd2l4LWRhdGEnOwoKLy8gLi4uCgpsZXQgb3B0aW9ucyA9IHsKICAic3VwcHJlc3NBdXRoIjogdHJ1ZSwKICAic3VwcHJlc3NIb29rcyI6IHRydWUKfTsKCndpeERhdGEuZ2V0KCJteUNvbGxlY3Rpb24iLCAiMDAwMDEiLCBvcHRpb25zKQogIC50aGVuKCAocmVzdWx0cykgPT4gewogICAgbGV0IGl0ZW0gPSByZXN1bHRzOwogIH0gKQogIC5jYXRjaCggKGVycikgPT4gewoJCWxldCBlcnJvck1zZyA9IGVycjsKCX0gKTsK
import wixData from 'wix-data';

// ...

let options = {
  "suppressAuth": true,
  "suppressHooks": true
};

wixData.get("myCollection", "00001", options)
  .then( (results) => {
    let item = results;
  } )
  .catch( (err) => {
		let errorMsg = err;
	} );