# About the Data Items API

<blockquote class="important">

**Important:**
Starting from version **1.0.185**, the Data Items API was significantly revised to closely match the functionality and syntax of the [Velo `wix-data` API](portalId::f356b938-ca2c-46f4-a390-e7ed146e00e0resourceId::963a94da-6231-4ab9-88c7-1149bd7c1b06slug::introduction*fallback::https://dev.wix.com/docs/velo/api-reference/wix-data/introduction). If you are using an earlier version of this API, updating to the new version requires changes to your code.
For previous versions, refer to the documentation for [the deprecated API](portalId::b85dea5b-341b-493b-b99e-4d4ca12baaa2resourceId::e8ae0bc0-16dc-4f95-b66e-c64d2998fcf7slug::aggregate-data-items*fallback::https://dev.wix.com/docs/sdk/backend-modules/data/items-deprecated/introduction).

</blockquote>

> **Note for app developers:** Wix Data APIs require the site's [code editor](portalId::bcc88c7b-94f5-4c35-b1cb-d7a20f2669b0resourceId::fd577f1d-9c28-4aba-acc2-d08943df22e2#code-editor*fallback::https://dev.wix.com/docs/develop-websites/articles/getting-started/development-environments#code-editor) to be enabled. If you are building a Wix app, add a [data collections extension](fallback::https://dev.wix.com/docs/build-apps/develop-your-app/extensions/backend-extensions/data-collections/about-data-collections-extensions) to automatically enable the code editor and create data collections when your app is installed on a site.

The Data Items API allows you to access and manage items in a Wix site's data collections.

With the Data Items API, you can:

- Create and manage data items in a site's collections.
- Retrieve data items from a collection individually or with filtering and sorting queries.
- Create and manage reference fields.
- Perform aggregations and calculations on data in collections.
- Truncate a data collection, removing all its contents.

The Data Items API only works with existing collections. To create and manage data collections, use the [Data Collections API](portalId::b85dea5b-341b-493b-b99e-4d4ca12baaa2resourceId::d02f8f8f-0240-45ab-b27f-8842dacf2264slug::introduction*fallback::https://dev.wix.com/api/sdk/data/collections).

## Before you begin

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

- The maximum size of an item you can save to a collection is 500 kb.
- We don't recommend updating a data item more than once per second.
- When using data retrieval methods such as [`query()`](fallback::https://dev.wix.com/docs/sdk/backend-modules/data/items/query) or [`get()`](fallback::https://dev.wix.com/docs/sdk/backend-modules/data/items/get) following an update to a collection's data, the data retrieved may not yet contain the most recent changes. See [Wix Data and Eventual Consistency](portalId::b85dea5b-341b-493b-b99e-4d4ca12baaa2resourceId::bedbd951-7b7e-4712-8825-a237b0b3314f*fallback::https://dev.wix.com/api/sdk/data/eventual-consistency) for more information and instructions for overriding this.
- To speed up data retrieval, the results of certain data queries are cached. Learn more about [caching data query results](fallback::https://dev.wix.com/docs/develop-websites/articles/databases/wix-data/data-api/about-caching-data-query-results).
- When your site makes a data request, it may take some time to receive a response. Wix Data places limits on how long a response can take before the [request times out](fallback::https://dev.wix.com/docs/develop-websites/articles/databases/wix-data/data-api/working-with-wix-data#request-timeouts). If the response time exceeds this limit, Wix Data returns an error instead of the intended result.
- When querying [Wix app collections](fallback::https://dev.wix.com/docs/develop-websites/articles/databases/wix-data/collections/working-with-wix-app-collections-and-code), check which fields can be filtered in the relevant collection field article.
- Updating a data item replaces the existing item entirely. If the existing item had fields with values and those fields aren't included in the updated item, the values in those properties are lost.
- Aggregations can't be performed on [Wix app collections](fallback::https://dev.wix.com/docs/develop-websites/articles/databases/wix-data/collections/working-with-wix-app-collections-and-code).
- After connecting external database collections to a Wix site using the [External Database Connections API](portalId::b85dea5b-341b-493b-b99e-4d4ca12baaa2resourceId::f2d073e8-be2c-403c-b400-0d9245c36aa0slug::introduction*fallback::https://dev.wix.com/api/sdk/data/externaldatabaseconnections), you can use the Data Items API to manage and retrieve data from those collections as if they were Wix Data collections.

@package_metadata:@wix/data

<blockquote class="important">

**Important:** Starting from version **1.0.185**, the data items API was significantly revised to closely match the functionality and syntax of the [Velo `wix-data` API](portalId::f356b938-ca2c-46f4-a390-e7ed146e00e0resourceId::963a94da-6231-4ab9-88c7-1149bd7c1b06slug::introduction*fallback::https://dev.wix.com/docs/velo/api-reference/wix-data/introduction). If you are using an earlier version of this API, updating to the new version requires significant changes to your code.
For previous versions, refer to the documentation for [the deprecated API](fallback::https://dev.wix.com/docs/sdk/backend-modules/data/items-deprecated/introduction).

</blockquote>

To use the Items API, install the `@wix/data` package.

## Install the package

To install the package, follow the instructions below based on your development environment.

### Wix sites and Blocks apps

When developing with:

+ Editor or Wix IDE: Use the [package manager](fallback::https://dev.wix.com/docs/develop-websites/articles/coding-with-velo/packages/work-with-npm-packages-in-the-editor).
+ Local IDE: Use the [Wix CLI](fallback::https://dev.wix.com/docs/develop-websites/articles/coding-with-velo/packages/work-with-npm-packages-with-the-wix-cli). Run the following command:
    ```bash
    npm install @wix/data
    ```
    or
    ```bash
    yarn add @wix/data
    ```

### Wix apps and Headless

When developing CLI or self-hosted apps, as well as headless apps or sites, run the following command:
```bash
npm install @wix/data
```
or
```bash
yarn add @wix/data
```

## Import the package

To import the package in your code:
```js
import { items } from "@wix/data";
```

# Run an Aggregation Pipeline

This guide explains how to build and run an aggregation pipeline. The aggregation pipeline lets you perform complex transformations and calculations on [data items](portalId::b85dea5b-341b-493b-b99e-4d4ca12baaa2resourceId::e8ae0bc0-16dc-4f95-b66e-c64d2998fcf7slug::aggregate-data-items*fallback::https://dev.wix.com/docs/sdk/backend-modules/data/items/introduction). A pipeline consists of 1 or more stages that process your data sequentially, with each stage's output becoming the input for the next stage.

The pipeline allows you to:

- Group items and calculate aggregate values.
- Transform result items by including, excluding, or reshaping fields.
- Filter, sort, and limit results.

> **Note**: You can only build an aggregation pipeline for collections [created in the CMS](fallback::https://support.wix.com/en/article/cms-formerly-content-manager-creating-a-collection) or with the [Data Collections API](fallback::https://dev.wix.com/docs/sdk/backend-modules/data/collections/introduction). You can't use them on [Wix app collections](fallback::https://support.wix.com/en/article/cms-formerly-content-manager-working-with-wix-app-collections) or [external collections](fallback::https://dev.wix.com/docs/develop-websites/articles/databases/external-databases/overview/integrating-external-databases-with-your-wix-site).

## Anatomy of a pipeline

An aggregation pipeline has the following key components:

- `aggregatePipeline()`: Runs an aggregation pipeline on the specified collection and returns the results.
- `pipelineBuilder()`: Builds an aggregation pipeline with stages and pagination configuration.
- [Stages](fallback::https://dev.wix.com/docs/sdk/backend-modules/data/items/wix-data-aggregate-pipeline-stages/introduction): Operations that process and transform data sequentially. Each [stage type](fallback::https://dev.wix.com/docs/sdk/backend-modules/data/items/wix-data-aggregate-pipeline-stages/introduction#backend-modules_data_items_stage-types) performs a different operation.
- [Expressions](fallback::https://dev.wix.com/docs/sdk/backend-modules/data/items/wix-data-aggregate-pipeline-expressions/introduction): Operators and values for performing calculations, transformations, and field manipulations.

## Build and run an aggregation pipeline

Building and running an aggregation pipeline involves 2 main phases: building the pipeline with your desired stages, then running it on a collection:

1. Import the `items` module and deconstruct the required submodules:

    ```js
    import { items } from '@wix/data';

    const { pipelineBuilder, stages, expressions } = items;
    ```

2. Add 1 or more [stages](fallback::https://dev.wix.com/docs/sdk/backend-modules/data/items/wix-data-aggregate-pipeline-stages/introduction) to build the pipeline:

    ```js
    const pipelineStages = [
      stages.filter().eq("year", 2010),
      stages.group("state").max("population", "maxPopulation"),
      stages.sort().descending("maxPopulation")
    ];
    ```

    Some stages resolve [expressions](fallback::https://dev.wix.com/docs/sdk/backend-modules/data/items/wix-data-aggregate-pipeline-expressions/introduction) to perform calculations and transformations. For example, you can create a new field by combining existing fields:

    ```js
    const pipelineStages = [
      stages.project().reshape(
          "fullName", 
          expressions.concat(
            expressions.field("firstName"),
            expressions.text(" "),
            expressions.field("lastName")
          )
        )
      ]
    ```

3. Pass the stages array to the [`withStages()`](fallback::https://dev.wix.com/docs/sdk/backend-modules/data/items/pipeline-builder/with-stages) method. You can also add paging configuration with the [`withPaging()`](fallback::https://dev.wix.com/docs/sdk/backend-modules/data/items/pipeline-builder/with-paging) method. Finally, call [`build()`](fallback::https://dev.wix.com/docs/sdk/backend-modules/data/items/pipeline-builder/build) to build the pipeline:

    ```js
    const pipeline = pipelineBuilder()
      .withStages(pipelineStages)
      .withPaging({ limit: 10 })
      .build();
    ```

    The pipeline is now ready.

4. Pass the configured pipeline to the [`aggregatePipeline()`](fallback::https://dev.wix.com/docs/sdk/backend-modules/data/items/aggregate-pipeline) method to run the pipeline on the collection:

    ```js
    const results = await items.aggregatePipeline('Contacts', pipeline);
    ```

## See also

- [Pipeline builder](fallback::https://dev.wix.com/docs/sdk/backend-modules/data/items/pipeline-builder/introduction)
- [Aggregation pipeline stages](fallback::https://dev.wix.com/docs/sdk/backend-modules/data/items/wix-data-aggregate-pipeline-stages/introduction)
- [Aggregation pipeline expressions](fallback::https://dev.wix.com/docs/sdk/backend-modules/data/items/wix-data-aggregate-pipeline-expressions/introduction)

query( )