Skip to content

feat: add GlideAggregate (Stats API) support#146

Open
orwellsanimal wants to merge 1 commit into
ServiceNow:mainfrom
orwellsanimal:feat/glide-aggregate
Open

feat: add GlideAggregate (Stats API) support#146
orwellsanimal wants to merge 1 commit into
ServiceNow:mainfrom
orwellsanimal:feat/glide-aggregate

Conversation

@orwellsanimal
Copy link
Copy Markdown

Summary

Implements GlideAggregate, a REST wrapper over /api/now/stats/{table} that mirrors the server-side GlideAggregate. This picks up the design discussed and approved in #145.

ga = client.GlideAggregate('incident')
ga.add_active_query()
ga.add_aggregate('COUNT')
ga.add_aggregate('AVG', 'reassignment_count')
ga.group_by('priority')
ga.query()
for row in ga:
    print(row.get_value('priority'), row.get_aggregate('COUNT'))

Design (per #145)

  • class GlideAggregate(Query) — inherits the query builder (add_query, add_active_query, add_null_query, add_not_null_query) rather than GlideRecord, matching the JoinQuery / RLQuery precedent and avoiding the CRUD surface that doesn't apply to aggregates. Result-cursor methods live on the class because the Stats wire shape (groupby_fields[] + stats{}) differs from a Table record.
  • StatsAPI — added as a peer alongside TableAPI / AttachmentAPI / BatchAPI, sharing API._send (and therefore the 401/403/404 → exception mapping).
  • client.GlideAggregate(table) factory, mirroring client.GlideRecord(table).
  • Async sibling deferred to a follow-up PR.

Notes from building against a live instance

  • STDDEV omitted — server-side GlideAggregate supports it, but the REST Stats API doesn't expose sysparm_stddev_fields (only count/sum/avg/min/max). Left out with a docstring note rather than faked client-side.
  • order_by_aggregate is server-side via sysparm_order_by=AVG^field / COUNT.
  • HAVING uses the caret form aggregate^field^operator^value (field required even for COUNT), multiple clauses joined by ,.
  • set_display_value(True) sends sysparm_display_value=all, so both raw (get_value) and label (get_display_value) are available from a single query.

Files

  • pysnc/aggregate.pyGlideAggregate + AggregateType
  • pysnc/client.py — factory method + StatsAPI
  • pysnc/__init__.py — export
  • test/test_snc_aggregate.py — integration tests (mirror the test_snc_* style)
  • docs/api.rst — document the new classes
  • README.md — moved out of "Feature Wants and TODO" + added a Quick Start

Test plan

  • pytest test/test_snc_aggregate.py — 11 integration tests against a live instance
  • full suite green, mypy clean
  • tests skipTest where they depend on optional demo data (e.g. ITAM assets) so they don't false-fail on instances without it

Refs #145

Implements GlideAggregate(Query) wrapping /api/now/stats/{table},
with a client.GlideAggregate(table) factory and a StatsAPI peer.

Refs ServiceNow#145
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant