Go Headless

Build Apps

Client

API Preview

test

Ricos

Develop Websites

REST

Velo

GraphQL (Alpha)

ID of the data collection for which to generate the index.

dataCollectionId

string

index

Index

options

CreateIndexOptions

Creates an index for a data collection.

The index can't be used immediately, as the process of generating the index takes time.
You can check whether your index is ready using `listIndexes()`.

Note that when an index fails to create, the failed index still occupies a slot.
To remove the failed index and free up the slot for a new index, use `dropIndex()`.

import { indexes } from 'wix-data.v2';

/* 
 * Sample dataCollectionId value = 'Jackets'
 *
 * Sample index value: 
 * {
 *   fields: [
 *     {
 *       path: 'price'
 *     }
 *   ],
 *   name: 'byPrice'
 * }
 */


export async function myCreateIndexFunction(dataCollectionId, index) {
  try {
    const createIndexResponse = await indexes.createIndex(dataCollectionId, index);
    console.log(`Successfully created an index named ${createIndexResponse.name}. Full response: `, createIndexResponse);

    return createIndexResponse;
  } catch (error) {
    console.error(error);
    // Handle the error
  }
}

/* Promise resolves to:
 * {
 *   "caseInsensitive": false,
 *   "fields": [
 *     {
 *       "order": "ASC",
 *       "path": "price"
 *     }
 *   ],
 *   "name": "byPrice",
 *   "status": "BUILDING",
 *   "unique": false,
 * }
 */


Create an index (dashboard page code)

import { Permissions, webMethod } from 'wix-web-module';
import { indexes } from 'wix-data.v2';
import { elevate } from 'wix-auth';

/* 
 * Sample dataCollectionId value = 'Jackets'
 *
 * Sample index value: 
 * {
 *   fields: [
 *     {
 *       path: 'price'
 *     }
 *   ],
 *   name: 'byPrice'
 * }
 */

export const myCreateIndexFunction = webMethod(Permissions.Anyone, async (dataCollectionId, index) => {
  try {
    const elevatedCreateIndex = elevate(indexes.createIndex);
    const createIndexResponse = await elevatedCreateIndex(dataCollectionId, index);
    console.log(`Successfully created an index named ${createIndexResponse.name}. Full response: `, createIndexResponse);

    return createIndexResponse;
  } catch (error) {
    console.error(error);
    // Handle the error
  }
});

/* Promise resolves to:
 * {
 *   "caseInsensitive": false,
 *   "fields": [
 *     {
 *       "order": "ASC",
 *       "path": "price"
 *     }
 *   ],
 *   "name": "byPrice",
 *   "status": "BUILDING",
 *   "unique": false,
 * }
 */


Create an index (export from backend code)

import { Permissions, webMethod } from 'wix-web-module';
import { indexes } from 'wix-data.v2';
import { elevate } from 'wix-auth';

/* 
 * Sample dataCollectionId value = 'Jackets'
 *
 * Sample index value: 
 * {
 *   caseInsensitive: true,
 *   fields: [
 *     {
 *       path: 'itemName'
 *     },
 *     {
 *       path: 'price'
 *     },
 *     {
 *       order: 'DESC',
 *       path: 'size'
 *     }
 *   ],
 *   name: 'byItemNameAndPriceAndSize'
 * }
 */

export const myCreateIndexFunction = webMethod(Permissions.Anyone, async (dataCollectionId, index) => {
  try {
    const elevatedCreateIndex = elevate(indexes.createIndex);
    const createIndexResponse = await elevatedCreateIndex(dataCollectionId, index);
    console.log(`Successfully created an index named ${createIndexResponse.name}. Full response: `, createIndexResponse);

    return createIndexResponse;
  } catch (error) {
    console.error(error);
    // Handle the error
  }
});

/* Promise resolves to:
 * {
 *   "caseInsensitive": true,
 *   "fields": [
 *     {
 *       "order": "ASC",
 *       "path": "itemName"
 *     }, 
 *     {
 *       "order": "ASC",
 *       "path": "price"
 *     },
 *     {
 *       "order": "DESC",
 *       "path": "size"
 *     }
 *   ],
 *   "name": "byItemNameAndPriceAndSize",
 *   "status": "BUILDING",
 *   "unique": false,
 * }
 */


Create a case-insensitive index based on the item name and price in ascending order, and item size in descending order

Create an index 

import { Permissions, webMethod } from 'wix-web-module';
import { indexes } from 'wix-data.v2';
import { elevate } from 'wix-auth';

/* 
 * Sample dataCollectionId value = 'shoes';
 * 
 * Sample index value = 
 * {
 *   name: 'bySerialNum',
 *   unique: true,
 *   fields: [
 *     {
 *       path: 'serial'
 *     }
 *   ]
 * };
*/

export const myCreateIndexFunction = webMethod(Permissions.Anyone, async (dataCollectionId, index) => {
  try {
    const elevatedCreateIndex = elevate(indexes.createIndex);
    const createUniqueIndexResponse = await elevatedCreateIndex(dataCollectionId, index);
    console.log(`Successfully created an index named ${createUniqueIndexResponse.name}. Full response: `, createUniqueIndexResponse);

    return createUniqueIndexResponse;
  } catch (error) {
    console.error(error);
    // Handle the error
  }
});

/* Returns a promise that resolves to the index being created:
 * {
 *   "caseInsensitive": false,
 *   "fields": [
 *     {
 *       "order": "ASC",
 *       "path": "serial"
 *     }
 *   ],
 *   "name": "bySerialNum",
 *   "status": "BUILDING",
 *   "unique": true,
 * }
 */


Create a unique index 

createIndex

ID of the data collection for which the index to be dropped is defined.

indexName

DropIndexOptions

Removes an index from a data collection.

The process of dropping an index from a collection takes time.
You can check whether your index has been dropped by calling `listIndexes()`.

import { indexes } from "wix-data.v2";

/* 
 * Sample dataCollectionId value = 'Jackets'
 *
 * Sample indexName value = 'BySizeAndAvailability'
*/

export async function myDropIndexFunction(dataCollectionId, indexName) {
  try {
    await indexes.dropIndex(dataCollectionId, indexName);
    console.log(`The ${indexName} index is being dropped.`);

    return;
  } catch (error) {
    console.error(error);
    // Handle the error
  }
}

/* Promise resolves to void */


Drop an index (dashboard page code)

import { Permissions, webMethod } from 'wix-web-module';
import { indexes } from 'wix-data.v2';
import { elevate } from 'wix-auth';

/* 
 * Sample dataCollectionId value = 'Jackets'
 *
 * Sample indexName value = 'BySizeAndAvailability'
*/


export const myDropIndexFunction = webMethod(Permissions.Anyone, async (dataCollectionId, indexName) => {
  try {
    const elevatedDropIndex = elevate(indexes.dropIndex);
    await elevatedDropIndex(dataCollectionId, indexName);
    console.log(`The ${indexName} index is being dropped.`);

    return;
  } catch (error) {
    console.error(error);
    // Handle the error
  }
});

/* Promise resolves to void */

Drop an index (export from backend code)

dropIndex

void

ID of the data collection for which to list indexes.

Options for retrieving a list of indexes.

ListIndexesOptions

Lists all indexes defined for a data collection.

When an index's status is `ACTIVE`, it is ready to use.
While it is still being created, its status is `BUILDING`.

When an index's status is `DROPPED`, it has been dropped successfully.
While it is still in the process of being removed, its status is `DROPPING`.

import { indexes } from "wix-data.v2";

/* 
 * Sample dataCollectionId value = 'Jackets'
 *
 * Sample options value = {
 *   limit: 5
 * }
*/

export async function myListIndexesFunction(dataCollectionId, options) {
  try {
    const listIndexesResponse = await indexes.listIndexes(dataCollectionId, options);
    console.log(`List of indexes for this collection: ${listIndexesResponse.indexes}`);

    return listIndexesResponse;
  } catch (error) {
    console.error(error);
    // Handle the error
  }
}

/* Promise resolves to a list of indexes for the specified collection, with paging metadata:
* {
*   "indexes": [
*     {
*       "caseInsensitive": true,
*       "fields": [
*         {
*           "order": "ASC"
*           "path": "itemName",
*         },
*         {
*           "order": "DESC"
*           "path": "size",
*         }
*       ],
*       "name": "byItemNameAndSize",
*       "status": "ACTIVE",
*       "unique": false,
*     },
*     {
*       "caseInsensitive": false
*       "fields": [
*         {
*           "order": "ASC"
*           "path": "size",
*         },
*         {
*           "order": "DESC"
*           "path": "available",
*         }
*       ],
*       "name": "bySizeAndAvailability",
*       "status": "ACTIVE",
*       "unique": false,
*     }
*   ],
*   "pagingMetadata": {
*     "count": 2,
*     "offset": 0,
*     "total": 2,
*     "tooManyToCount": false
*   }
* }
*/


List indexes (dashboard page code)

import { Permissions, webMethod } from 'wix-web-module';
import { indexes } from 'wix-data.v2';
import { elevate } from 'wix-auth';

/* 
 * Sample dataCollectionId value = 'Jackets'
 *
 * Sample options value = {
 *   limit: 5
 * }
*/

export const myListIndexesFunction = webMethod(Permissions.Anyone, async (dataCollectionId, options) => {
  try {
    const elevatedListIndexes = elevate(indexes.listIndexes);
    const listIndexesResponse = await elevatedListIndexes(dataCollectionId, options);
    console.log(`List of indexes for this collection: ${listIndexesResponse.indexes}`);

    return listIndexesResponse;
  } catch (error) {
    console.error(error);
    // Handle the error
  }
});

/* Promise resolves to a list of indexes for the specified collection, with paging metadata:
* {
*   "indexes": [
*     {
*       "caseInsensitive": true,
*       "fields": [
*         {
*           "order": "ASC"
*           "path": "itemName",
*         },
*         {
*           "order": "DESC"
*           "path": "size",
*         }
*       ],
*       "name": "byItemNameAndSize",
*       "status": "ACTIVE",
*       "unique": false,
*     },
*     {
*       "caseInsensitive": false
*       "fields": [
*         {
*           "order": "ASC"
*           "path": "size",
*         },
*         {
*           "order": "DESC"
*           "path": "available",
*         }
*       ],
*       "name": "bySizeAndAvailability",
*       "status": "ACTIVE",
*       "unique": false,
*     }
*   ],
*   "pagingMetadata": {
*     "count": 2,
*     "offset": 0,
*     "total": 2,
*     "tooManyToCount": false
*   }
* }
*/


List indexes (export from backend code)

listIndexes

ListIndexesResponse

---
title: Introduction
---

# About the Indexes API



The Indexes API enables you to create indexes for data collections, to make querying data faster.

An index is a map of a collection's data, organized according to fields that you select. An index [increases the speed of queries](https://www.wix.com/velo/reference/wix-data-v2/indexes/indexes-and-query-speed) by providing a query with a shortcut to the information it is looking for. Instead of iterating through every data item in the collection, a query can use the index to skip to potentially relevant items. The larger a collection is, the more time this saves.

With the Indexes API, your app can:

- Create regular indexes to accelerate query speed.
- Create unique indexes to enforce unique values.
- Access and drop existing indexes.

To learn about the differences between regular and unique indexes, see [Index Types](https://www.wix.com/velo/reference/wix-data-v2/indexes/index-types).

## Before you begin

It's important to note the following points before starting to code:

- A collection can have up to 3 regular indexes (for up to 3 fields per index). It may also have 1 unique index (for 1 field).
- The value contained in an indexed field can't be larger than 982 bytes, including the collection name. For example, in a collection named "Products", the maximum length of each value in the indexed fields is 974 bytes.
- When an index creation fails, the failed index still occupies a slot. To remove the failed index and free up the slot for a new index, use the [`dropIndex()`](https://www.wix.com/velo/reference/wix-data-v2/indexes/dropindex) function.
- Case-insensitive filters, such as `$startsWith`, aren't accelerated by an index.

## Terminology

- **Regular index:** An index that increases query speed for up to 3 fields.
- **Unique index:** An index that increases query speed and enforces unique values for 1 field.

---
title: Index Types
---

# Index Types

The Indexes API allows you to create 2 kinds of indexes:

- A regular index accelerates queries for up to 3 fields in a collection.
- A unique index enforces unique values for 1 field in a collection and also functions as a regular index for that field.

## Regular indexes

You can create up to 3 regular indexes for each collection. A regular index can be created for up to 3 fields, with each field sorted either in ascending or descending order.

For example, consider a database containing information about many different products. Each data item contains `productName`, `category`, and `price` fields.

An index for the `productName` field in ascending order accelerates queries based on the `productName` field. Instead of searching through all of the data entries until one is found with the desired name, the index enables the query to jump based on alphabetical ordering.

An index for the `category` and `price` fields speeds up queries that include these fields. A general query for all products in a particular `category`, ordered by `price`, doesn't need to iterate through the entire collection to find all items in the specified `category`. The results of that search will already be ordered by `price` and thus will not need to be sorted again. For a large collection, this can save a significant amount of time.

## Unique indexes

A unique index enforces unique values for an indexed field. You can create 1 unique index for each collection, in addition to its regular indexes.

A unique index can only have 1 field. For that field, it functions like a regular index. For example, a unique index for the `productName` field in a product database enables faster queries based on that field.

In addition, a unique index enforces unique values for the indexed field in all data items across the collection. So if you created a unique index for the `productName` field, you will not be able to create more than one item with any given `productName` value.

---
title: Indexes and Query Speed
---

# Indexes and Query Speed

Every time you query a data collection, you are initiating filtering and sorting operations that take time to carry out because they iterate through every item in the collection. For a small collection, the time it takes to execute a query and receive its results might be negligible. But as the quantity of data in a collection increases, each query takes longer to process, and this can impact the performance of your app.

An index is a map of the collection's data, organized according to fields that you select. An index increases the speed of queries by providing a query with a shortcut to the information it is looking for. Instead of iterating through every data item in the collection, a query can use the index to skip to potentially relevant items. The larger a collection is, the more time this saves.

The best fields to use for indexes are those with a wide range of values. Indexes of fields with a narrow range of values, such as booleans, don't speed up queries significantly.


---
title: Querying Indexed Data
---

# Querying Indexed Data

Indexes accelerate filtering and sorting queries of certain types. For details of the query language used in Wix Data queries, see [API Query Language](https://dev.wix.com/api/rest/getting-started/api-query-language).

## Filtering

Indexes accelerate queries based on equality operators, such as `$eq` and `$in`. They also accelerate queries based on range operators, such as `$gt`, `$gte`, `$lt`, and `$lte` under certain circumstances. In Wix Data collections, indexes don't accelerate queries based on the case insensitive `$startsWith` operator.

The order of fields in an index determines when and how filter queries use the index to save time.

For example, consider a collection containing information about paintings. The collection has an index for fields called `artist` (in ascending order), `dateCompleted` (in ascending order), and `title` (in ascending order), respectively.

Queries that filter based on the fields in the following orders can use the index to find the resulting entries more quickly:
- `artist` alone.
- `artist` and `dateCompleted`.
- `artist`, `dateCompleted`, and `title`.

A query that filters based on the `dateCompleted` field or the `title` field first doesn't use the index and will iterate through all items in the collection.

A query based on `artist` and `title` uses the index for looking up values in the `artist` field, but then iterates through all of the resulting items for the query of the `title` field. The index thus improves the speed of this query, but only partially.

Note that queries can use an index to accelerate a range filter (such as `$gt`, `$gte`, `$lt`, or `$lte`) only if it is the last filtering action of the query. For example, in our example collection with an index for `artist`, `dateCompleted`, and `title`, the following queries would make full use of the index:
- A range filter for `artist` alone.
- An equality filter for `artist` and a range filter for `dateCompleted`.
- An equality filter for `artist`, an equality filter for `dateCompleted`, and a range filter for `title`.

## Sorting

An index also speeds up sorting operations in a query, if the following conditions are met:

- The query doesn't include filters that prevent the index from being used.
- The sorting order in the query either matches the order defined in the index or is its exact inverse.

For example, consider again a collection containing information about paintings, with an index for fields called `artist` (in ascending order), `dateCompleted` (in ascending order), and `title` (in ascending order), respectively.

A query that has no filters and sorts by `artist`, `dateCompleted`, and `title` uses the index if the query sorts all the fields in ascending order (corresponding to the index) or if sorts all fields in descending order (inversely corresponding to the index).

A query that contains an equality filter for `artist` and subsequently sorts by `dateCompleted` and `title` (in the appropriate order) also uses the index.

However, a query that contains a range filter for `artist` and subsequently sorts by `dateCompleted` and `title` doesn't use the index.

## Example

Consider again a collection with information about paintings. Each data item contains an `artist` field, a `dateCompleted` field, and a `title` field.

What indexes might be useful for this collection? The answer depends on which queries are likely to be carried out most often.

Suppose that users are most likely to carry out the following types of queries:

1. Show all paintings by a particular artist.
2. Show all paintings by all artists, ordered only by their date of completion.

Defining an index for `artist` (ascending order) and `dateCompleted` (ascending order) accelerates queries of the first kind. A query for all works by Michelangelo, for example, uses the index and returns results more quickly than if there was no index. The same index would also accelerate a more complex query which filters by `artist` and sorts the results by `dateCompleted`.

However, a query of the second kind isn't accelerated by this index, since the index first orders by `artist`. To speed up a query for all paintings ordered only by `dateCompleted`, we can create a second index with `dateCompleted` as its first (or only) field.

velo-deps_wix-data.v2_indexes

Environment

Failure

Error code.
- `WDE0112`: Unknown error while building collection index.
- `WDE0113`: Duplicate key error while building collection index.
- `WDE0114`: Document too large while building collection index.

code

description

ID of the data item that caused the failure.
For example, if `unique` is `true`, the ID of an item containing a duplicate value.

itemId

Field

Sort order for the index. Base on how the data is regularly queried.

Default: `ASC`

order

Order

Path of the field to index. For example: `title` or `options.price`.

path

Whether the index ignores case.

Default: `false`

caseInsensitive

boolean

Contains details about the reasons for failure when `status` is `FAILED`.

failure

Fields for which the index is defined.

Max: 3 fields (for a unique index: 1 field)

fields

name

Current status of the index.
- `BUILDING`: Index creation is in progress.
- `ACTIVE`: Index has been successfully created and can be used in queries.
- `DROPPING`: Index is in the process of being dropped.
- `DROPPED`: Index has been dropped successfully.
- `FAILED`: Index creation has failed.
- `INVALID`: Index contains incorrectly indexed data.

status

Status

Whether the index enforces uniqueness of values in the field for which it is defined.
If `true`, the index can have only one field.

Default: `false`

unique

paging

Paging

List of all indexes for the requested data collection.

indexes

pagingMetadata

PagingMetadata

limit

number

Number of items to skip in the current sort order.

offset

Number of items returned in the response.

count

Flag that indicates the server failed to calculate the `total` field.

tooManyToCount

Total number of items that match the query.