[MCP] aggregate_records DML tool by souvikghosh04 · Pull Request #3199 · Azure/data-api-builder

souvikghosh04 · 2026-03-06T05:56:40Z

Why make this change?

Closes [Enh]: add aggregate_records DML tool to MCP server #3178
Adds aggregate_records as a new DML tool to the MCP server, enabling models to answer common aggregation questions like "How many products are there?" and "What is our most expensive product?"
Continuation of work from Add aggregate_records DML tool and query-timeout to MCP server #3179 (stale PR with resolved review comments).

What is this change?

New aggregate_records DML tool (AggregateRecordsTool.cs) that generates SQL-level aggregation queries (COUNT, AVG, SUM, MIN, MAX) with support for DISTINCT, OData $filter (WHERE), GROUP BY, HAVING operators (eq, neq, gt, gte, lt, lte, in), ORDER BY (asc/desc), and cursor-based pagination (first/after) — all per the spec in [Enh]: add aggregate_records DML tool to MCP server #3178.
query-timeout configuration for MCP runtime options — allows setting a per-query timeout (1–600 seconds, default 30s) via McpRuntimeOptions.QueryTimeout, validated at startup.
Config & CLI plumbing: DmlToolsConfig gains AggregateRecords/UserProvidedAggregateRecords; McpRuntimeOptionsConverterFactory handles query-timeout serialization; ConfigureOptions.cs updated for CLI configure support; JSON schema updated.
Telemetry: Aggregation operations emit OpenTelemetry traces with structured error codes.
Updated 37 CLI + 4 Service.Tests snapshot files to reflect new default properties.

How was this tested?

Integration Tests — AggregateRecordsToolTests.cs (all 13 spec examples + edge cases), McpQueryTimeoutTests.cs, EntityLevelDmlToolConfigurationTests.cs, McpToolRegistryTests.cs
Unit Tests — AggregateRecordsToolTests.cs (unit), McpTelemetryTests.cs, RequestParserUnitTests.cs, SqlQueryExecutorUnitTests.cs

Co-authored-by: JerryNixon <1749983+JerryNixon@users.noreply.github.com>

Co-authored-by: JerryNixon <210500244+JerryNixon@users.noreply.github.com>

…eout to all MCP tools, add tests Co-authored-by: JerryNixon <1749983+JerryNixon@users.noreply.github.com>

…test file Co-authored-by: JerryNixon <1749983+JerryNixon@users.noreply.github.com>

Co-authored-by: anushakolan <45540936+anushakolan@users.noreply.github.com>

…gate-records-tool-fixes

…organization

…g performance by offloading computations to the database

Replace in-memory aggregation tests (PerformAggregation, ApplyPagination) with SQL expression generation tests (BuildAggregateExpression, BuildQuotedTableRef, DecodeCursorOffset). All 13 spec examples and 5 blog scenarios now validate SQL patterns instead of in-memory computation. 89 tests pass. Build and format clean. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

- DecodeCursorOffset now rejects negative values (returns 0) - Add max validation for 'first' parameter (100000 limit) - Prevents integer overflow on first+1 and invalid SQL OFFSET - Add tests for both edge cases Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Replace custom SQL string building with engine's SqlQueryStructure + GroupByMetadata + queryBuilder.Build(structure) pattern. This uses the same AggregationColumn, AggregationOperation, and Predicate types that the engine's GraphQL aggregation path uses. Removed methods: BuildAggregateSql, BuildAggregateExpression, BuildQuotedTableRef, BuildWhereClause, BuildHavingClause, AppendPagination. These are now handled by the engine's query builder. Updated both test files to remove references to removed methods. All 69 aggregate tests pass. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

- Fix COUNT(*): Use primary key column (PK NOT NULL, so COUNT(pk) COUNT(*)) instead of AggregationColumn with empty schema/table/'*' which produced invalid SQL like count([].[*]) - Fix TOP + OFFSET/FETCH conflict: Remove TOP N when pagination is used since SQL Server forbids both in the same query - Add database type validation: Return error for PostgreSQL/MySQL/ CosmosDB since engine only supports aggregation for MsSql/DWSQL - Add HAVING validation: Reject having without groupby - Add tests for star-field-with-avg, distinct-count-star, and having-without-groupby validation Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Add 8 tests covering all 5 scenarios from the DAB MCP blog post (devblogs.microsoft.com/azure-sql/data-api-builder-mcp-questions): 1. Strategic customer importance (sum/groupby/orderby desc/first 1) 2. Product discontinuation (sum/groupby/orderby asc/first 1) 3. Quarterly performance (avg/groupby/having gt/orderby desc) 4. Revenue concentration (sum/complex filter/multi-groupby/having) 5. Risk exposure (sum/filter/multi-groupby/having gt) Each test verifies the exact blog JSON payload passes input validation, plus tests for schema completeness, describe_entities instruction, and alias convention documentation. 80 tests pass. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Remove redundant parameter listings from Description (already in InputSchema). Description now covers only: workflow steps, rules not expressed elsewhere, and response alias convention. Parameter descriptions simplified to one sentence each, removing repeated phrases like 'from describe_entities' and 'ONLY applies when groupby is provided' (stated once in groupby description). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Validate field and groupby field names immediately after metadata resolution, before authorization or query building. Invalid field names now return a FieldNotFound error with model-friendly guidance to call describe_entities for valid field names. - Add McpErrorHelpers.FieldNotFound() with entity name, field name, parameter name, and describe_entities guidance - Move field existence checks before auth in AggregateRecordsTool - Remove redundant late validation (already caught early) - Add tests for FieldNotFound error type and message content 82 tests pass. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Rename abbreviated variable names to their full, readable forms: funcElfunctionElement, fieldElfieldElement, distinctEldistinctElement, filterElfilterElement, orderbyElorderbyElement, firstElfirstElement, afterElafterElement, groupbyElgroupbyElement, ggroupbyItem, gValgroupbyFieldName, gFieldgroupbyField, havingElhavingElement, havingOpshavingOperators, havingInhavingInValues, aggTypeaggregationType, aggColumnaggregationColumn, predOppredicateOperation, ophavingOperator, predpredicate, backingColbackingColumn, backingGColbackingGroupbyColumn, timeoutExtimeoutException, taskExtaskCanceledException, dbExdbException, argExargumentException/dabException. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

DAB config already has MaxResponseSize property that handles this downstream through structure.Limit(). The engine applies the configured limit automatically, making this artificial cap redundant. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Co-authored-by: souvikghosh04 <210500244+souvikghosh04@users.noreply.github.com>

souvikghosh04 · 2026-03-06T10:44:12Z

/azp run

azure-pipelines · 2026-03-06T10:44:37Z

Azure Pipelines successfully started running 6 pipeline(s).

schemas/dab.draft.schema.json

src/Azure.DataApiBuilder.Mcp/BuiltInTools/AggregateRecordsTool.cs

src/Service.Tests/Mcp/AggregateRecordsToolTests.cs

src/Service/Utilities/McpStdioHelper.cs

src/Service.Tests/Mcp/McpQueryTimeoutTests.cs

src/Service.Tests/UnitTests/AggregateRecordsToolTests.cs

Aniruddh25 · 2026-03-08T06:11:21Z

/azp run

azure-pipelines · 2026-03-08T06:11:44Z

Azure Pipelines successfully started running 6 pipeline(s).

Aniruddh25 · 2026-03-09T00:39:29Z

/azp run

azure-pipelines · 2026-03-09T00:39:52Z

Azure Pipelines successfully started running 6 pipeline(s).

…/data-api-builder into Usr/sogh/aggregate_records

souvikghosh04 · 2026-03-09T13:27:43Z

/azp run

azure-pipelines · 2026-03-09T13:28:11Z

Azure Pipelines successfully started running 6 pipeline(s).

souvikghosh04 · 2026-03-09T13:58:20Z

/azp run

azure-pipelines · 2026-03-09T13:58:47Z

Azure Pipelines successfully started running 6 pipeline(s).

Copilot AI and others added 30 commits February 28, 2026 05:55

Initial plan

2d96151

Changes before error encountered

eaaa522

Co-authored-by: JerryNixon <1749983+JerryNixon@users.noreply.github.com>

Add first/after pagination support to aggregate_records tool

f855e96

Co-authored-by: JerryNixon <1749983+JerryNixon@users.noreply.github.com>

Add exhaustive tool instructions and all 13 spec example tests

3573321

Co-authored-by: JerryNixon <1749983+JerryNixon@users.noreply.github.com>

Changes before error encountered

f66bf3f

Co-authored-by: JerryNixon <1749983+JerryNixon@users.noreply.github.com>

Changes before error encountered

829a630

Co-authored-by: JerryNixon <210500244+JerryNixon@users.noreply.github.com>

Update query-timeout default to 30s, add converter support, apply tim…

3ccc748

…eout to all MCP tools, add tests Co-authored-by: JerryNixon <1749983+JerryNixon@users.noreply.github.com>

Fix group key collision using \\0 delimiter, add #nullable enable to …

381899d

…test file Co-authored-by: JerryNixon <1749983+JerryNixon@users.noreply.github.com>

Fix nullable warnings in AggregateRecordsToolTests.cs

fde4d65

Co-authored-by: anushakolan <45540936+anushakolan@users.noreply.github.com>

Add null check for errorType in AggregateRecordsToolTests

ba371d5

Co-authored-by: anushakolan <45540936+anushakolan@users.noreply.github.com>

Apply validation fixes and additional tests from copilot/update-aggre…

d340cb4

…gate-records-tool-fixes

Refactor using directives in AggregateRecordsTool.cs to improve code …

41ccb2f

…organization

Enhance AggregateRecordsTool to build SQL aggregate queries, improvin…

eb99aba

…g performance by offloading computations to the database

Clean up extra blank line from validation removal

b55cdde

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Add AggregateRecordsTool documentation for SQL-level aggregations

7f4e259

Simplify sequence diagram and expand design decisions

d83ded2

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Merge branch 'main' into copilot/add-aggregate-records-tool

1327150

Changes before error encountered

6815b65

Co-authored-by: souvikghosh04 <210500244+souvikghosh04@users.noreply.github.com>

Removing duplicate registration from stdio which is failing runs

c7010ff

update snapshot test files

5038cc7

Merge branch 'main' into copilot/add-aggregate-records-tool

ecbb2fa

Format and consistency fixing

d5de2b4

souvikghosh04 marked this pull request as ready for review March 6, 2026 11:10

souvikghosh04 requested review from Alekhya-Polavarapu, Aniruddh25, JerryNixon, RubenCerna2079, aaronburtle, anushakolan, rusamant, sourabh1007, stuartpa and vadeveka as code owners March 6, 2026 11:10

Aniruddh25 approved these changes Mar 8, 2026

View reviewed changes

Merge branch 'main' into Usr/sogh/aggregate_records

f951685

Merge branch 'main' into Usr/sogh/aggregate_records

388e231

souvikghosh04 added 3 commits March 9, 2026 18:34

Review comments fixes

a08da11

Merge branch 'Usr/sogh/aggregate_records' of https://github.com/Azure…

d4b527c

…/data-api-builder into Usr/sogh/aggregate_records

Revert unwanted changes

3add20a

Fix failing tests

c5ceded

Aniruddh25 assigned anushakolan Mar 9, 2026

Conversation

souvikghosh04 commented Mar 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Why make this change?

What is this change?

How was this tested?

Uh oh!

souvikghosh04 commented Mar 6, 2026

Uh oh!

azure-pipelines bot commented Mar 6, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Aniruddh25 commented Mar 8, 2026

Uh oh!

azure-pipelines bot commented Mar 8, 2026

Uh oh!

Aniruddh25 commented Mar 9, 2026

Uh oh!

azure-pipelines bot commented Mar 9, 2026

Uh oh!

souvikghosh04 commented Mar 9, 2026

Uh oh!

azure-pipelines bot commented Mar 9, 2026

Uh oh!

souvikghosh04 commented Mar 9, 2026

Uh oh!

azure-pipelines bot commented Mar 9, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

souvikghosh04 commented Mar 6, 2026 •

edited

Loading