Uh oh!
There was an error while loading. Please reload this page.
Fix markdown errors - #36
Closed
seesharprun wants to merge 2 commits into
Closed
Conversation
GuanzhouSong added a commit
to GuanzhouSong/docs
that referenced
this pull request
Aug 3, 2026
The Index Management row was wrong in three ways. It took the function
name from the filename rather than the definition: create_index_
background--*.sql (singular) defines create_indexes_background (plural).
It also had the wrong schema. The definition uses __API_SCHEMA_V2__,
which pg_documentdb/Makefile:28 resolves to documentdb_api, not
documentdb_api_internal - and documentdb_api_internal.create_index_
background does not exist in any schema in any version file.
And the description belonged to a different function. "Schedules
background index builds via the index queue" is the COMMENT ON for
create_indexes_background_internal ("Queues the Index creation
request(s) on a collection"). The public function is synchronous; its
own comment reads "Submits the build index(es) requests on a collection
and waits for them to finish."
Dropped "(the default since v0.104-0)" as unsupported: the v0.104-0
CHANGELOG entry says only "Support background index builds [Bugfix]
(documentdb#36)", nothing about it becoming the default.
Parameter naming is left as-is to match the neighbouring
create_indexes_non_concurrently row, which maps p_arg to spec the same
way.
Fixesdocumentdb/documentdb.github.io#128
Signed-off-by: Guanzhou Song <guanzhousong@microsoft.com>guanzhousongmicrosoft added a commit
that referenced
this pull request
Aug 3, 2026
…ge against v0.114-0 (#58) * Correct the create_indexes_background row The Index Management row was wrong in three ways. It took the function name from the filename rather than the definition: create_index_ background--*.sql (singular) defines create_indexes_background (plural). It also had the wrong schema. The definition uses __API_SCHEMA_V2__, which pg_documentdb/Makefile:28 resolves to documentdb_api, not documentdb_api_internal - and documentdb_api_internal.create_index_ background does not exist in any schema in any version file. And the description belonged to a different function. "Schedules background index builds via the index queue" is the COMMENT ON for create_indexes_background_internal ("Queues the Index creation request(s) on a collection"). The public function is synchronous; its own comment reads "Submits the build index(es) requests on a collection and waits for them to finish." Dropped "(the default since v0.104-0)" as unsupported: the v0.104-0 CHANGELOG entry says only "Support background index builds [Bugfix] (#36)", nothing about it becoming the default. Parameter naming is left as-is to match the neighbouring create_indexes_non_concurrently row, which maps p_arg to spec the same way. Fixesdocumentdb/documentdb.github.io#128 Signed-off-by: Guanzhou Song <guanzhousong@microsoft.com> * Audit the functions page against v0.114-0 Follow-up to the create_indexes_background row. Transcribing that one row correctly turned up the same class of error across the rest of the page, so this checks every row against the installed catalog (\df documentdb_api.*) at the v0.114-0 tag - the release getting-started/prebuilt-packages.md names as current. All 50 public documentdb_api entries are now documented and every signature matches name-for-name, including OUT/INOUT parameters and DEFAULTs that the page had been dropping. Validating against the tag rather than upstream main matters, and compact is why. On main, compact takes a `mode` field and defaults to a non-blocking standard VACUUM. That field does not exist in v0.114-0: the gate there is a bare `if (!EnableCompactVacuumFull)`, and that GUC defaults off, so on the shipped release compact returns { "ok": 1, "bytesFreed": 0 } and reclaims nothing by default. The page now documents the shipped behavior. create_indexes_background does not wait. The previous commit took "and waits for them to finish" from the SQL COMMENT ON, but the C implementation contradicts it: command_create_indexes_background only builds a SELECT of create_indexes_background_internal and hands it to ReindexOrCreateCommandCore, which runs one SPI query and returns. The waiting lives in the gateway and in upstream's own test helper. The page now documents the two-call protocol, adds check_build_index_status (the other half, previously absent from the whole docs repo), and covers the three ways a naive caller gets it wrong: no COMMIT after queueing leaves the request invisible to the drain worker; exiting the poll loop on `complete` alone reports success for a build that failed or that merely left the queue; and nothing drains the queue at all unless pg_cron or documentdb.indexBuildsScheduledOnBgWorker is running. Several rows described functions that cannot do what they claim: - documentdb_api_internal.insert_one is a stub that always raises "insert_one is deprecated and should not be called" - bulkWrite raises "bulkWrite is not yet implemented"; only its command surface shipped - the *_txn_proc and *_bulk procedures raise inside an explicit transaction rather than requiring one, and both variants sit behind gateway flags that default off - create_indexes_non_concurrently raises on an existing collection unless p_skip_check_collection_create is true - shard keys must be "hashed"; the remedial example used '{ "a": 1 }', which raises "only shard keys that use hashed are supported" - documentdb_api.collection requires constant name arguments and a FROM clause, or it raises Version corrections: current_op_command is v0.102-0, not v0.101-0; rolesInfo is v0.108-0, not v0.106-0; and create_indexes_background is not "added in v0.104-0" - it is declared as far back as create_index_background--0.23-0.sql. What v0.104-0 added was automatic scheduling of the drain job, which is what made background builds the working default, so the phrasing dropped by the previous commit was closer to right than its replacement. Also: delete has no procedure form in v0.114-0 (delete_txn_proc is post-release); the preamble's claim that OUT parameters imply a record return is true only for multi-OUT functions; the two list_* cursor functions ignore cursorId and can never be resumed; all four cursor functions are STRICT, so binding NULL silently yields an empty row; and create_collection_view is not the "only" entry point for collection options, since coll_mod takes the same set. configuration.md gains the three off-by-default flags this page now refers to - enableCompactVacuumFull, enablePreImages, and indexBuildsScheduledOnBgWorker - each of which fails by doing nothing rather than by raising. Signed-off-by: Guanzhou Song <guanzhousong@microsoft.com> --------- Signed-off-by: Guanzhou Song <guanzhousong@microsoft.com> Co-authored-by: Guanzhou Song <guanzhousong@microsoft.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for freeto join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This pull request makes a series of documentation improvements to the API reference, focusing on correcting internal links and clarifying the
$[identifier]array update operator. The main changes are grouped into two themes: link corrections for consistency and accuracy, and operator documentation clarification.Documentation link corrections:
.mdfile extension for consistency and to ensure proper navigation. This affects references toinsert,update,find, anddeletecommand documentation. [1][2][3][4][5]Operator documentation clarification:
$[identifier]array update operator by updating the title and description to accurately reflect its usage, replacing the generic$[]with the more precise$[identifier].