Home/Tools/@tpmjs/tools-rows-group-aggregate

rowsGroupAggregateTool

@tpmjs/tools-rows-group-aggregate

Groups an array of objects by a specified key field and performs aggregation operations (sum, count, avg, min, max) on other fields. Useful for analyzing data by categories or creating summary statistics.

Official
data
v0.2.0
MIT

Interactive Playground

Test @tpmjs/tools-rows-group-aggregate (rowsGroupAggregateTool) with AI-powered execution

0/2000 characters

Installation & Usage

Install this tool and use it with the AI SDK

1. Install the package

npm install @tpmjs/tools-rows-group-aggregate
pnpm add @tpmjs/tools-rows-group-aggregate
yarn add @tpmjs/tools-rows-group-aggregate
bun add @tpmjs/tools-rows-group-aggregate
deno add npm:@tpmjs/tools-rows-group-aggregate

2. Import the tool

import { rowsGroupAggregateTool } from '@tpmjs/tools-rows-group-aggregate';

3. Use with AI SDK

import { generateText } from 'ai';
import { openai } from '@ai-sdk/openai';
import { rowsGroupAggregateTool } from '@tpmjs/tools-rows-group-aggregate';

const result = await generateText({
  model: openai('gpt-4o'),
  tools: { rowsGroupAggregateTool },
  prompt: 'Your prompt here...',
});

console.log(result.text);

Parameters

Available configuration options

Auto-extracted
rows
Required
Type: array

Array of objects to group and aggregate

groupBy
Required
Type: string

The field name to group by (supports nested fields with dot notation)

aggregates
Required
Type: array

Array of aggregation operations to perform on each group. Each operation specifies a field and operation type.

Schema extracted: 1/1/2026, 8:17:46 AM

README

@tpmjs/tools-rows-group-aggregate

Groups rows by a key field and aggregates values using operations like sum, count, avg, min, max.

Installation

npm install @tpmjs/tools-rows-group-aggregate

Usage

import { rowsGroupAggregateTool } from '@tpmjs/tools-rows-group-aggregate';

const result = await rowsGroupAggregateTool.execute({
  rows: [
    { category: 'A', value: 10, price: 5.5 },
    { category: 'A', value: 20, price: 6.0 },
    { category: 'B', value: 30, price: 7.5 },
    { category: 'B', value: 40, price: 8.0 },
  ],
  groupBy: 'category',
  aggregates: [
    { field: 'value', operation: 'sum' },
    { field: 'value', operation: 'avg' },
    { field: 'price', operation: 'max' },
    { field: 'price', operation: 'min' },
  ],
});

console.log(result);
// {
//   groups: [
//     {
//       groupKey: 'A',
//       aggregates: {
//         value_sum: 30,
//         value_avg: 15,
//         price_max: 6.0,
//         price_min: 5.5
//       },
//       rowCount: 2
//     },
//     {
//       groupKey: 'B',
//       aggregates: {
//         value_sum: 70,
//         value_avg: 35,
//         price_max: 8.0,
//         price_min: 7.5
//       },
//       rowCount: 2
//     }
//   ],
//   groupCount: 2
// }

Parameters

  • rows (required): Array of objects to group and aggregate
  • groupBy (required): Field name to group by (supports nested fields with dot notation like user.id)
  • aggregates (required): Array of aggregation operations, each with:
    • field: Field name to aggregate
    • operation: One of sum, count, avg, min, max

Aggregation Operations

  • sum: Total of all numeric values
  • count: Number of rows in the group
  • avg: Average of numeric values
  • min: Minimum numeric value
  • max: Maximum numeric value

Features

  • Supports nested field access with dot notation
  • Handles null/undefined values gracefully
  • Multiple aggregations per group
  • Type-safe with TypeScript

License

MIT

Statistics

Downloads/month

0

Quality Score

67%

Bundle Size

NPM Keywords

tpmjs
data
aggregate
group-by

Maintainers

thomasdavis(thomasalwyndavis@gmail.com)

Frameworks

vercel-ai
rowsGroupAggregateTool | TPMJS | TPMJS