Cosmos DB Gateway rejects GROUP BY queries that work in Azure Portal (NonValueAggregate / misleading SDK error)

[harsh123-baba]

When querying Azure Cosmos DB via the SDK (Python azure-cosmos 4.14.5) using the Gateway/thin-client path, certain valid GROUP BY queries fail with a BadRequest error, even though the same query executes successfully in the Azure Portal Data Explorer.

The error message references cosmos-netstandard-sdk/3.18.0 and None GroupBy NonValueAggregate, which is misleading and makes troubleshooting difficult.

Environment

Cosmos DB API: Core (SQL)

Query Interface:

Azure Portal Data Explorer → ✅ Works

SDK via Gateway (MCP / Python SDK) → ❌ Fails

Python SDK: azure-cosmos 4.14.5

OS: Windows 11

Connection Mode: Gateway (thin client proxy)

x-ms-version: 2020-07-15

Reproducible Example
Query that works in Azure Portal
SELECT c.Category, COUNT(1) AS Count
FROM c
WHERE CONTAINS(LOWER(c.Description), 'sso')
GROUP BY c.Category

Same query fails via SDK
Cosmos DB error: 400 - (BadRequest)
Query contains the following features, which the calling client does not support:
None GroupBy NonValueAggregate
ActivityId: , Windows/10.0.20348 cosmos-netstandard-sdk/3.18.0

Attempted Workarounds

VALUE projection

SELECT VALUE { "Category": c.Category, "Count": COUNT(1) }
FROM c
GROUP BY c.Category

❌ Still fails via Gateway

Subquery workaround (this works)

SELECT VALUE {
  "Category": x.Category,
  "Count": COUNT(1)
}
FROM (
  SELECT c.Category
  FROM c
) x
GROUP BY x.Category

Expected Behavior

Queries that execute successfully in Azure Portal should behave consistently when executed via supported SDKs.

Error messages should reflect the actual SDK and limitation, not reference older netstandard SDK versions when using modern clients.

Gateway behavior should either:

Support direct GROUP BY projections, or

Clearly document the limitation and required query patterns.

Actual Behavior

Valid queries fail only when executed via SDK / Gateway.

Error message references cosmos-netstandard-sdk/3.18.0 even when using azure-cosmos 4.14.5.

Request

Clarify whether this is a Gateway limitation or a client-side validation issue

Improve error messaging to reflect actual client behavior

Document supported GROUP BY query shapes for SDK users

Align Portal and SDK behavior where possible