[DOCS] create_indexes_background documented with wrong name and schema; GitHub stats stale and inconsistent between pages #128

Two content-accuracy problems found by cross-checking the site against upstream documentdb/documentdb and the GitHub API.

Revised. Expanded §1 — the same table row also carries a wrong description and an unsupported version claim, and the suggested replacement now matches the table's existing formatting conventions.

1. create_index_background row is wrong in three ways

articles/postgres-api/functions.md:56, under ## Index Management (:51):

| `documentdb_api_internal.create_index_background(database text, spec bson)` | Schedules background index builds via the index queue (the default since v0.104-0). |

Root cause

The row conflates two different upstream functions — the synchronous public wrapper and the internal queueing function — and takes the name from the filename rather than the definition. The file create_index_background--*.sql (singular) defines create_indexes_background (plural).

pg_documentdb/sql/udfs/index_mgmt/create_index_background--0.111-0.sql:20:

CREATE OR REPLACE FUNCTION __API_SCHEMA_V2__.create_indexes_background(
    p_database_name text,
    p_index_spec __CORE_SCHEMA__.bson,
    OUT retval __CORE_SCHEMA__.bson,
    OUT ok boolean,
    OUT requests __CORE_SCHEMA__.bson)
RETURNS record

The schema macro resolves through pg_documentdb/Makefile.cflags:105:

-D__API_SCHEMA_V2__=$(API_SCHEMA_NAME_V2)

and pg_documentdb/Makefile:28:

API_SCHEMA_NAME_V2=documentdb_api

So __API_SCHEMA_V2__ is documentdb_api, not documentdb_api_internal.

The three defects

1. Wrong name — create_index_background → create_indexes_background.
2. Wrong schema — documentdb_api_internal → documentdb_api. (documentdb_api_internal.create_index_background does not exist in any schema in any version file.)
3. Wrong description — "Schedules background index builds via the index queue" is the comment for a different function, create_indexes_background_internal (:50-51, "Queues the Index creation request(s) on a collection"). The public function is synchronous: its own COMMENT ON at :30-31 reads "Submits the build index(es) requests on a collection and waits for them to finish."

Additionally, "(the default since v0.104-0)" appears unsupported. CHANGELOG.md:164 under v0.104-0 says only "Support background index builds [Bugfix] (#36)" — nothing about it becoming the default. Recommend dropping the parenthetical unless someone can source it.

Suggested replacement row

Matching the table's existing conventions — other rows strip p_ prefixes and omit OUT parameters:

| `documentdb_api.create_indexes_background(database text, index_spec bson)` | Submits background index build requests for a collection and waits for them to finish. |

Version currency

Checked all six versions of the file (--0.23-0, --0.104-0, --0.108-0, --0.110-0, --0.111-0, --latest). --0.111-0.sql and --latest.sql are byte-identical, so the citation is current.

Not a defect, for contrast

The neighbouring documentdb_api_internal.create_indexes_non_concurrently(database text, spec bson, skip_check_collection_create bool DEFAULT false) row is correct — create_indexes_non_concurrently--latest.sql:6-9 confirms __API_SCHEMA_INTERNAL_V2__ (= documentdb_api_internal, Makefile:26) and the boolean default FALSE third parameter.

Scope of the audit

All 43 function references in this page (42 table rows plus the inline current_op_aggregation) were checked against pg_documentdb/sql/udfs/** with macros resolved. Every other entry exists under its documented schema. create_indexes_background is the only name/schema mismatch.

One nuance the page glosses over generally: with ENABLE_RBAC_SCHEMA=1 (Makefile:31), most of these functions are defined in more than one schema (documentdb_api_v2, documentdb_api_internal_readwrite, documentdb_api_internal_readonly). documentdb_api is the right answer for users; it just isn't the whole picture.

2. GitHub stats are stale and inconsistent between pages

Root cause

The numbers are hardcoded independently in two files with no shared constant, so they drifted apart and then went stale.

curl -s https://api.github.com/repos/documentdb/documentdb | jq '{stars:.stargazers_count, forks:.forks_count}'
# { "stars": 3423, "forks": 248 }

Both render in adjacent sections — "Built in the open" (app/page.tsx:570) and "Built in the open, backed by a real ecosystem" (app/ai/page.tsx:440) — so a visitor moving between the two pages sees two different star counts. No third location on the site duplicates these values.

Fix: hoist into one shared constant so the pages cannot drift again. Fetching at build time is an option but adds a network dependency to the build.

Verified accurate

The "11 TSC members representing 5 organizations" claim on both pages is correct — upstream MAINTAINERS.md lists exactly 11 members across Microsoft (4), Amazon (4), AB InBev (1), Rippling (1), YugabyteDB (1).