GraphQL aggregation docs misleading

[flof]

The documentation for data-api-builder GraphQL aggregations contains examples that seem not to work. Neither with 1.x nor with 2.x versions of data-api-builder.

For example: This is the first query in the docs:

{
  books(
    groupBy: { fields: ["year"] }
  ) {
    items {
      year
    }
    aggregates {
      pages {
        sum
        average
        min
        max
      }
    }
  }
}

This query doesn't work. It returns an error saying that "groupBy" is not valid here.

But i found out that this works:

{
  books {
    groupBy(fields: [year]) {
        fields {
            year
        }
        aggregations {
            sum(field: pages)
        }
    }
}

I learned about this query syntax in an example in the source code .

I tested with the Docker versions 1.7.93 and 2.0.8 of data-api-builder and got the same results on both versions.

Is there a mismatch between documentation and implementation? Or do i look at the wrong documentation?

[JerryNixon]

Update on the GraphQL aggregation docs

Thanks for reporting the issue. You were right: the previous GraphQL aggregation page showed patterns that didn’t match how Data API builder actually exposes aggregation in GraphQL.

I rewrote the page to match the real DAB implementation and validated the examples against a live DAB instance.

What changed:

• Corrected the GraphQL syntax for aggregation:
  • groupBy is selected inside the collection query.
  • Aggregate fields use aggregations.
  • Functions use sum, avg, min, max, and count.
  • Grouping fields use enum values, such as fields: [year], not strings.
• Replaced the old examples with scenario-based examples that show:
  • SQL table or view
  • GraphQL query
  • SQL generated by DAB
  • JSON response
• Added examples for:
  • Aggregating all rows
  • Grouping by one field
  • Grouping by multiple fields
  • Aggregating over a SQL view
  • Filtering rows before aggregation
  • Filtering groups with having
  • Counting distinct values
• Added view-specific guidance, including the need to configure key fields for views.
• Clarified support:
  • Supported for SQL Server family and Azure Synapse Analytics Dedicated SQL pool.
  • Not supported for Azure Cosmos DB for NoSQL, PostgreSQL, or MySQL.
• Added notes for real implementation behavior:
  • Aggregation is enabled by default.
  • Aggregation results are paged, with 100 groups returned by default.
  • sum, avg, min, and max apply to numeric fields; count works on any field.

Validation performed:

• Ran the examples against DAB 2.0.8.
• Used SQL Server tables and a SQL view to verify the examples.
• Confirmed the GraphQL responses and generated SQL match the updated documentation.
• Ran the docs build and confirmed there were no broken Markdown links or build errors.

---

The update should show up in the next day or two. Thank you for this issue.