---
name: bijection-aggregate
description: "Evaluate and integrate the Aggregate component with Bijection."
---

# Aggregate

Counts, sums, ranks and ordered aggregates

- Package: @bijectionhq/aggregate
- Category: Database & Backend
- Status: Reference
- License: Apache-2.0
- Bijection source (repository access required): https://github.com/bijectionhq/aggregate/tree/e9bdba0ff9fe7e72859f47ebd06b02b25b0d30d2
- Upstream: https://github.com/convex/aggregate/tree/5a72b010210abd3053eb373e8b4077d894115347
- Documentation: https://docs.bijection.com/components/using
- Directory: https://bijection.com/components/aggregate

## Get the source

Bijection repository access is required. Request access at https://bijection.com/contact.

```sh
git clone https://github.com/bijectionhq/aggregate.git
cd aggregate
git checkout e9bdba0ff9fe7e72859f47ebd06b02b25b0d30d2
```

## Before using this component

Read the package README at the recorded revision for setup, dependencies, and API examples. Upstream documentation describes the original package and may differ from the Bijection adaptation. This is a source candidate for evaluation. Catalog inclusion does not establish npm availability or runtime qualification. Check compatibility with your SDK and deployment before adoption. External providers run their own compute.

## Integration workflow

1. Read the source README and package manifest at the recorded revision.
2. Confirm the required SDK, dependency availability, and runtime compatibility.
3. Follow the component's documented setup and configuration. Never invent an npm install command from a catalog package name.
4. Keep credentials in the project's existing secret store.
5. Follow the project's execution rules for verification and report what was actually checked.

## Original upstream skill

The following guidance describes @convex-dev/aggregate. Its installation commands and APIs refer to the upstream package. Evaluate compatibility with the Bijection source separately.


> Agents: read this skill fully before writing code that uses Aggregate. Follow the installation and configuration steps exactly.

# Aggregate

## Instructions

The Aggregate component maintains denormalized counts and sums for efficient data aggregation in O(log n) time instead of O(n) table scans. It provides sorted key-value storage with range queries, supporting arbitrary Convex values as keys for flexible grouping and partitioning. The component handles both table-based aggregation with automatic sync and lower-level manual operations.

### Installation

```bash
npm install @convex-dev/aggregate
```

Current npm version: `@convex-dev/aggregate@0.3.3`

## Use cases

- **Building leaderboards and rankings** where you need to quickly find percentile scores, user rankings, or counts above/below thresholds without scanning all records
- **Implementing offset-based pagination** for traditional page-by-page navigation through large datasets, complementing Convex's cursor-based pagination
- **Creating random access patterns** like shuffling playlists or selecting random items by using total counts and index-based lookups
- **Tracking analytics and metrics** such as message counts per time period, user activity summaries, or grouped statistics across multiple dimensions
- **Supporting multi-tenant applications** using namespaces to isolate aggregations per tenant while maintaining high throughput

## How it works

You define a `TableAggregate` instance that specifies how to extract sort keys and sum values from your table documents. The component maintains a separate denormalized data structure that stays in sync as you call `insert()`, `replace()`, and `delete()` methods alongside your regular database operations.

The aggregate supports flexible grouping through tuple-based sort keys like `[game, username, score]` and prefix-based queries to aggregate at different levels. For completely separate data partitions, namespaces provide isolated aggregation with higher throughput by avoiding interference between unrelated data.

Core query methods include `count()` for totals within bounds, `sum()` for value aggregation, `at()` for index-based access, `indexOf()` for ranking, and `max()`/`min()` for extremes. All operations work with optional bounds and prefix filters to scope queries to specific data ranges.

## When NOT to use

- When a simpler built-in solution exists for your specific use case
- If you are not using Convex as your backend
- When the functionality provided by Aggregate is not needed

## Resources

- [npm package](https://www.npmjs.com/package/%40convex-dev%2Faggregate)
- [GitHub repository](https://github.com/convex/aggregate)
- [Convex Components Directory](https://www.convex.dev/components/aggregate)
- [Convex documentation](https://docs.convex.dev)