> Portal Navigation:
> 
> - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version.
> - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages).
> - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`).
> - Top-level index of all portals: https://dev.wix.com/docs/llms.txt
> - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt

## Resource: Run an Aggregation Pipeline

## Article: Run an Aggregation Pipeline

## Article Link: https://dev.wix.com/docs/sdk/data-items-sdk/data/items/run-an-aggregation-pipeline.md

## Article Content:

# 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](https://dev.wix.com/docs/sdk/backend-modules/data/items/introduction.md). 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](https://support.wix.com/en/article/cms-formerly-content-manager-creating-a-collection) or with the [Data Collections API](https://dev.wix.com/docs/sdk/backend-modules/data/collections/introduction.md). You can't use them on [Wix app collections](https://support.wix.com/en/article/cms-formerly-content-manager-working-with-wix-app-collections) or [external collections](https://dev.wix.com/docs/develop-websites/articles/databases/external-databases/overview/integrating-external-databases-with-your-wix-site.md).

## 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](https://dev.wix.com/docs/sdk/backend-modules/data/items/wix-data-aggregate-pipeline-stages/introduction.md): Operations that process and transform data sequentially. Each [stage type](https://dev.wix.com/docs/sdk/backend-modules/data/items/wix-data-aggregate-pipeline-stages/introduction.md#backend-modules_data_items_stage-types) performs a different operation.
- [Expressions](https://dev.wix.com/docs/sdk/backend-modules/data/items/wix-data-aggregate-pipeline-expressions/introduction.md): 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](https://dev.wix.com/docs/sdk/backend-modules/data/items/wix-data-aggregate-pipeline-stages/introduction.md) 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](https://dev.wix.com/docs/sdk/backend-modules/data/items/wix-data-aggregate-pipeline-expressions/introduction.md) 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()`](https://dev.wix.com/docs/sdk/backend-modules/data/items/pipeline-builder/with-stages.md) method. You can also add paging configuration with the [`withPaging()`](https://dev.wix.com/docs/sdk/backend-modules/data/items/pipeline-builder/with-paging.md) method. Finally, call [`build()`](https://dev.wix.com/docs/sdk/backend-modules/data/items/pipeline-builder/build.md) 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()`](https://dev.wix.com/docs/sdk/backend-modules/data/items/aggregate-pipeline.md) method to run the pipeline on the collection:

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

## See also

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