@convex-dev/aggregate
v0.1.2
Published
[![npm version](https://badge.fury.io/js/@convex-dev%2Faggregate.svg)](https://badge.fury.io/js/@convex-dev%2Faggregate)
Downloads
97
Readme
Convex Component: Aggregate
This Convex component calculates count and sums of values for efficient aggregation.
Suppose you have a leaderboard of game scores. These are some operations
that the Aggregate component makes easy and efficient, with O(log(n))
-time
lookups:
- Count the total number of scores:
aggregate.count(ctx)
- Count the number of scores greater than 65:
aggregate.count(ctx, { lower: { key: 65, inclusive: true } })
- Find the p95 score:
aggregate.at(ctx, Math.floor(aggregate.count(ctx) * 0.95))
- Find the overall average score:
aggregate.sum(ctx) / aggregate.count(ctx)
- Find the ranking for a score of 65 in the leaderboard:
aggregate.rankOf(ctx, 65)
- Find the average score for an individual user:
const bounds = { lower: { key: username, inclusive: true }, upper: { key: username, inclusive: true } };
const avgScoreForUser = aggregateByUser.sum(ctx, bounds) / aggregateByUser.count(ctx, bounds);
What are Aggregates for?
With plain Convex indexes, you can insert new documents and you can paginate through all documents. But you don't want to lose sight of the forest for the trees. Sometimes you want big-picture data that encompases many of your individual data points, and that's where aggregates come in.
The Aggregates component keeps a data structure with denormalized counts and sums. It's effectively a key-value store which is sorted by the key, and where you can count values that lie between two keys.
The keys may be arbitrary Convex values, so you can choose to sort your data by:
- a number, like a leaderboard score
- a string, like user ids -- so you can count the data owned by each user
- an index key, for full pagination support
- nothing, use
key=null
for everything if you just want a counter
More examples
- In a messaging app, how many messages have been sent within the past month?
- Offset-based pagination: view the 100th page of photos, where each page has 50 photos.
- Look up a random song in a table, as the next song to play.
How to install
See example/
for a working demo.
- Install the Aggregate component:
npm install @convex-dev/aggregate
- Create a
convex.config.ts
file in your app'sconvex/
folder and install the component by callinguse
:
// convex/convex.config.ts
import { defineApp } from "convex/server";
import aggregate from "@convex-dev/aggregate/convex.config.js";
const app = defineApp();
app.use(aggregate);
export default app;
- Initialize the data structure so you can start writing to it.
npx convex run --component aggregate btree:init
# If there will be frequent writes, reduce contention by calculating top-level
# aggregates lazily.
npx convex run --component aggregate btree:makeRootLazy
How to Use
Write to the aggregate data structure
import { components } from "./_generated/api";
import { AggregateWriter } from "@convex-dev/aggregate";
const aggregateWriter = new AggregateWriter<number, Id<"mytable">>(components.aggregate);
// within a mutation, add values to be aggregated
await aggregateWriter.insert(ctx, key, id);
// or delete values that were previously added
await aggregateWriter.delete(ctx, key, id);
// or update values
await aggregateWriter.replace(ctx, oldKey, newKey, id);
If you want to automatically update the aggregates based on changes to a table, you can use
customFunction
s to wrapctx.db
in mutations. We intend to make this flow simpler; reach out in Discord to let us know if you're interested.
Calculate aggregates
// convex/myfunctions.ts
import { components } from "./_generated/api";
import { Aggregate } from "@convex-dev/aggregate";
const aggregate = new Aggregate<number, Id<"mytable">>(components.aggregate);
// then in your queries and mutations you can do
const tableCount = await aggregate.count(ctx);
// or any of the other examples listed above.
🧑🏫 What is Convex?
Convex is a hosted backend platform with a
built-in database that lets you write your
database schema and
server functions in
TypeScript. Server-side database
queries automatically
cache and
subscribe to data, powering a
realtime useQuery
hook in our
React client. There are also clients for
Python,
Rust,
ReactNative, and
Node, as well as a straightforward
HTTP API.
The database supports NoSQL-style documents with opt-in schema validation, relationships and custom indexes (including on fields in nested objects).
The
query
and
mutation
server functions have transactional,
low latency access to the database and leverage our
v8
runtime with
determinism guardrails
to provide the strongest ACID guarantees on the market:
immediate consistency,
serializable isolation, and
automatic conflict resolution via
optimistic multi-version concurrency control (OCC / MVCC).
The action
server functions have
access to external APIs and enable other side-effects and non-determinism in
either our
optimized v8
runtime or a more
flexible node
runtime.
Functions can run in the background via scheduling and cron jobs.
Development is cloud-first, with hot reloads for server function editing via the CLI, preview deployments, logging and exception reporting integrations, There is a dashboard UI to browse and edit data, edit environment variables, view logs, run server functions, and more.
There are built-in features for reactive pagination, file storage, reactive text search, vector search, https endpoints (for webhooks), snapshot import/export, streaming import/export, and runtime validation for function arguments and database data.
Everything scales automatically, and it’s free to start.