An API returning ten statistical buckets does not establish that its database processed only ten records. Grouping and sorting an entire repository before taking a page can produce a small response while retaining substantial upstream work. Examine input bounds, query plans and API meaning alongside JSON size.

GitHub’s October 14 star-history engineering article discusses that trade-off. Ninety synthetic records without user identities illustrate grouping before pagination versus grouping within an explicit time range. The walkthrough also examines calendar windows and historical semantics. No real stargazer data was requested and no GitHub performance test was reproduced. 中文版.

The change serves a trend query

The GitHub article discovered through Google News was published October 14, 2026. It describes serving trends through an aggregate history endpoint without returning identities, filtering by time before grouping. Production figures and request reductions in that article are GitHub’s reports, not measurements repeated here.

The direction is useful, but its headline request counts cannot become a speedup ratio for another database. Requests, response bytes, candidate rows, actual scanned rows, CPU and waiting time are distinct quantities. Several may change together, or only one may improve.

The example below groups synthetic rows within one repository. Consult the official API reference for real parameters, boundaries and permissions. Teaching SQL does not describe GitHub’s server implementation.

LIMIT bounds output, not automatically grouping input

Suppose a request needs daily counts for a repository and a middle page of ten days. One straightforward query filters by repository, groups by day, orders the buckets and applies LIMIT and OFFSET. Logically, the returned page is a slice of an already formed grouped result.

Another query puts the known day range into WHERE before grouping matching rows. Both can return the same result for a particular dataset and window. The first query’s output limit alone does not express the second query’s input boundary.

SQL’s logical order is not a guarantee of every database’s physical execution order. Optimizers, indexes and statistics can change plans. Inspect the actual plan instead of declaring a scan count directly from the statement’s text.

Run a bounded-range example locally

The in-memory SQLite example creates thirty days with three rows each: ninety total. The day column is an invented integer, not a GitHub timestamp. One query skips ten daily buckets and takes ten; the other selects 10≤day<20. Every teaching day deliberately has rows, allowing both expressions to select the same days.

# Synthetic current rows; no GitHub API calls or user identities.
import sqlite3

con = sqlite3.connect(":memory:")
con.execute("CREATE TABLE stars(repo TEXT, day INTEGER)")
con.executemany("INSERT INTO stars VALUES (?,?)",
                [("demo",day) for day in range(30) for _ in range(3)])
con.execute("CREATE INDEX stars_repo_day ON stars(repo,day)")

all_then_page = """SELECT day,COUNT(*) FROM stars
WHERE repo='demo' GROUP BY day ORDER BY day LIMIT 10 OFFSET 10"""
range_then_group = """SELECT day,COUNT(*) FROM stars
WHERE repo='demo' AND day>=10 AND day<20
GROUP BY day ORDER BY day"""
a = con.execute(all_then_page).fetchall()
b = con.execute(range_then_group).fetchall()
assert a == b
assert len(b) == 10
assert all(count == 3 for day,count in b)
assert sum(count for day,count in b) == 30
assert con.execute("SELECT COUNT(*) FROM stars WHERE repo='demo'").fetchone()[0] == 90
assert con.execute("SELECT COUNT(*) FROM stars WHERE repo='demo' AND day>=10 AND day<20").fetchone()[0] == 30
assert b[-1][0] == 19
assert con.execute("SELECT day FROM stars WHERE day>=30").fetchall() == []
print("Synthetic range and grouping checks passed")
print(con.execute("EXPLAIN QUERY PLAN " + range_then_group).fetchall())

Eight local checks passed: equivalent results, ten buckets with count three each, thirty matching rows, the upper boundary and an empty range. The code also prints the range query’s plan. This local run reported a covering-index SEARCH with repository and day bounds; other versions or datasets still require their own plan inspection.

Ninety is the synthetic total, thirty the rows satisfying the time condition, and ten the returned buckets. These are not a universal measurement of physical rows scanned or proof of a threefold speedup. No latency benchmark was run, and the dataset is too small to justify production-performance conclusions.

Result pagination and calendar windows differ

If some days have no rows, taking ten grouped results means ten populated buckets, not necessarily ten consecutive calendar days. The explicit interval 10≤day<20 still describes that period. Whether to fill absent days with zeros is another API contract decision.

Do not generalize the example’s equivalence to arbitrary data. Time-window pagination answers what happened during particular weeks. Paging existing grouped results may jump over dates with no records. Select the contract from the caller’s question.

The GitHub reference specifies week-organized history, pagination toward older periods and daily counts. Each response can contain up to thirty weeks; the page unit is weeks, not individual stars. Week and day boundaries must not be assumed to align with UTC. Ordering, boundaries and empty-bucket rules all belong in chart parsing and tests.

An indexed range is not a fixed-cost guarantee

The teaching index on (repo,day) places repository and day bounds in one access path. It gives the database an opportunity to locate the relevant range instead of grouping unrelated dates first. Check the plan to establish whether it is used and whether additional sorting is needed.

A bounded period does not bound the number of records inside it. One week can be sparse and another unusually dense. Even an endpoint that always returns seven daily counts can require different amounts of counting work. Dense windows and resource limits remain design considerations.

For a real service, record plans, actual row metrics, elapsed time and concurrency conditions before comparing changes. Response size alone cannot establish reduced database work. One warm-cache sample is also insufficient evidence of consistent performance.

Current-state history is not an event log

The source explains that the star model retains current records and removes a record when its star is removed. Grouping current rows by creation time cannot recover all past creation events that later disappeared. That is a data-model limitation rather than a pagination defect.

Imagine two records created on day one, one of which is removed on day three. On day four, grouping current rows by creation day may leave just one for day one. That answers a different question from the two creation events that actually occurred that day.

A chart should identify whether it shows current records distributed by creation time, cumulative creation events or snapshots at particular moments. Calling all three historical totals invites conclusions the data cannot support.

Let the requirement determine whether detail is needed

If a feature needs daily counts, fetching individual identities only to discard them brings unnecessary data into the caller. An aggregate endpoint can reduce that extra handling and retention. It still needs accurate definitions of the counted object, bucket boundaries and available range.

This does not mean detail endpoints lack legitimate uses. Auditing a properly authorized record and plotting a public trend can require different interfaces and access scopes. No user list was collected for this article and no access-restriction workaround is provided.

As with on-demand source checkout, avoiding work often starts with a more precise request. Here the request is a trend for a particular period, not every underlying record followed by client-side reduction.

Test three boundaries explicitly

First test time bounds: do inclusive starts and exclusive ends match the client? Then test sparse periods: how are dates with no rows represented? Finally test state changes: can deletion or removal change an older bucket? Testing only ordinary dense data misses the last two distinctions.

Report output size separately from execution cost. This example establishes query results and bounds for its supplied data. Production costs need production-scale evidence and actual plans. If the SQL example and boundary analysis help diagnose an aggregate query, voluntary support through the section below is welcome.

Sources and backfill note

Discovered through Google News and checked against the October 14 GitHub engineering article and official history API reference. Both figures, ninety rows and SQLite checks are original teaching material. No real GitHub data endpoint or production benchmark was run. The article retains October 19, 2026 at 22:00 Beijing time as its planned date and was backfilled later that day.