From 673a1a8ff70b4b344d090c0160faf1005c62841f Mon Sep 17 00:00:00 2001 From: Guanzhou Song Date: Wed, 11 Mar 2026 13:48:45 -0400 Subject: [PATCH 1/2] docs: add Extended RUM reference and document --disable-extended-rum flag Add a new Extended RUM reference page under api-reference/commands/indexing/ covering: - Default behavior by PostgreSQL version (PG18+ requires Extended RUM) - GUC configuration (rum_library_load_option, alternate_index_handler_name) - DocumentDB Local usage with --disable-extended-rum flag - Related ordered-index behavior and version history Update documentdb-local/index.md to include the --disable-extended-rum flag in the Docker commands table. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .../indexing/_metadata.description.md | 1 + .../commands/indexing/extended-rum.md | 83 +++++++++++++++++++ documentdb-local/index.md | 5 +- 3 files changed, 87 insertions(+), 2 deletions(-) create mode 100644 api-reference/commands/indexing/_metadata.description.md create mode 100644 api-reference/commands/indexing/extended-rum.md diff --git a/api-reference/commands/indexing/_metadata.description.md b/api-reference/commands/indexing/_metadata.description.md new file mode 100644 index 0000000..e5ba0a1 --- /dev/null +++ b/api-reference/commands/indexing/_metadata.description.md @@ -0,0 +1 @@ +Indexing commands and behavior reference for DocumentDB, including index types, Extended RUM, and configuration options. diff --git a/api-reference/commands/indexing/extended-rum.md b/api-reference/commands/indexing/extended-rum.md new file mode 100644 index 0000000..95fea20 --- /dev/null +++ b/api-reference/commands/indexing/extended-rum.md @@ -0,0 +1,83 @@ +--- +title: Extended RUM +description: Extended RUM is the default index access method for DocumentDB on PostgreSQL 18 and later, providing enhanced query and scan capabilities over the standard RUM index. +type: commands +category: indexing +--- + +# Extended RUM + +Extended RUM (`documentdb_extended_rum`) is a fork of the [RUM](https://github.com/postgrespro/rum) index access method that extends it with capabilities specific to DocumentDB's document-oriented workloads. Starting with DocumentDB **v0.108**, Extended RUM is the **default** index access method on PostgreSQL 18+ setups. + +## Overview + +DocumentDB uses RUM indexes internally for document indexing and query execution. Extended RUM builds on the standard RUM access method with improvements to the query path while keeping the same on-disk storage layout. This means: + +- Indexes created with standard RUM and Extended RUM are **storage-compatible** — they have the same layout on disk. +- All changes in Extended RUM are limited to the query and scan paths. Existing indexes do not need to be rebuilt. +- Extended RUM is loaded as a separate PostgreSQL extension (`documentdb_extended_rum`) alongside the core DocumentDB extension. + +## Default behavior by PostgreSQL version + +| PostgreSQL version | Default RUM behavior | GUC default | +|---|---|---| +| PG 16, PG 17 | Standard RUM | `none` | +| PG 18+ | Extended RUM (**required**) | `require_documentdb_extended_rum` | + +On PostgreSQL 18 and later, DocumentDB defaults to `require_documentdb_extended_rum`, meaning the Extended RUM library must be loaded for the server to function correctly. On earlier PostgreSQL versions, the standard RUM access method is used unless explicitly overridden. + +## Configuration + +### `documentdb.rum_library_load_option` + +This GUC controls how the RUM library is loaded. It is a **postmaster-level** setting, meaning it requires a server restart to take effect. + +| Value | Behavior | +|---|---| +| `none` | Use the standard RUM access method. Default on PG 16/17. | +| `prefer_documentdb_extended_rum` | Use Extended RUM if available; fall back to standard RUM otherwise. | +| `require_documentdb_extended_rum` | Require Extended RUM; fail to start if it is not available. Default on PG 18+. | + +### `documentdb.alternate_index_handler_name` + +When Extended RUM is enabled, this is set to `extended_rum` to route index operations through the Extended RUM access method. + +## DocumentDB Local + +When running DocumentDB Local via Docker, Extended RUM is **enabled by default**. + +To disable Extended RUM, pass the `--disable-extended-rum` flag: + +```bash +docker run -dt -p 10260:10260 --name docdb \ + ghcr.io/documentdb/documentdb/documentdb-local:latest \ + --username demo --password test \ + --disable-extended-rum +``` + +You can also set the `DISABLE_EXTENDED_RUM=true` environment variable: + +```bash +docker run -dt -p 10260:10260 --name docdb \ + -e DISABLE_EXTENDED_RUM=true \ + ghcr.io/documentdb/documentdb/documentdb-local:latest \ + --username demo --password test +``` + +## Related features + +### Ordered indexes + +DocumentDB v0.109 enabled **ordered indexes by default**. Ordered indexes use a composite operator class that can improve sort and range query performance. This behavior works alongside Extended RUM and can be controlled independently: + +- Per-index: specify `"storageEngine": {"enableOrderedIndex": false}` when creating an index. +- Server-wide: set the `documentdb.defaultUseCompositeOpClass` GUC to `off`. + +## Version history + +| Version | Change | +|---|---| +| v0.104 | `rum_enable_index_scan` enabled by default. | +| v0.106 | Internal Extended RUM extension added. | +| v0.108 | Extended RUM becomes the default on PG 18+. RUM dependency becomes implicit via the shared library. | +| v0.109 | Ordered indexes enabled by default (`defaultUseCompositeOpClass`). | diff --git a/documentdb-local/index.md b/documentdb-local/index.md index 80c9a7a..22547af 100644 --- a/documentdb-local/index.md +++ b/documentdb-local/index.md @@ -74,6 +74,7 @@ The following table summarizes the available Docker commands for configuring the | Override default key with key in key file. | `--key-file [value]` | Overrides `KEY_FILE` environment variable. | STRING | NA | You need to mount this file into the container. For example, to set `/mykey.key`, add this option to `docker run` command: `--mount type=bind,source=./mykey.key,target=/mykey.key` | | Enable telemetry data. | `--enable-telemetry` | Overrides `ENABLE_TELEMETRY` environment variable | `true`, `false` | `false` | Enable telemetry data sent to the usage collector (Azure Application Insights). | | Specify log verbosity. | `--log-level [value]` | Overrides `LOG_LEVEL` environment variable. | `quiet`, `error`, `warn`, `info`, `debug`, `trace` | `info` | The verbosity of logs that will be emitted. | +| Disable Extended RUM for indexes. | `--disable-extended-rum` | Overrides `DISABLE_EXTENDED_RUM` environment variable | `true`, `false` | `false` | By default, Extended RUM is enabled. Set this flag to use the standard RUM index access method instead. See [Extended RUM](../api-reference/commands/indexing/extended-rum.md) for details. | ## Feature support @@ -81,14 +82,14 @@ The following table summarizes the available Docker commands for configuring the Please refer to the [documentdb](https://documentdb.io/docs/) documentation for currently supported features. -## Installing certificates +## Installing certificates By default, DocumentDB Local generates new self-signed certificates each time the container starts. To prevent certificate errors, install them on your local machine. The example below shows how to use this setup with `mongosh`. ### Get certificate In a `bash` window, run the following to copy the certificate from the container to the local -host: +host: ```bash docker cp docdb:/home/documentdb/gateway/pg_documentdb_gw/cert.pem ~/documentdb-cert.pem From 617b3f7aa7819e49e9a251644f41a6e992f28aad Mon Sep 17 00:00:00 2001 From: Guanzhou Song Date: Wed, 11 Mar 2026 13:51:40 -0400 Subject: [PATCH 2/2] remove --- .../indexing/_metadata.description.md | 1 - .../commands/indexing/extended-rum.md | 83 ------------------- 2 files changed, 84 deletions(-) delete mode 100644 api-reference/commands/indexing/_metadata.description.md delete mode 100644 api-reference/commands/indexing/extended-rum.md diff --git a/api-reference/commands/indexing/_metadata.description.md b/api-reference/commands/indexing/_metadata.description.md deleted file mode 100644 index e5ba0a1..0000000 --- a/api-reference/commands/indexing/_metadata.description.md +++ /dev/null @@ -1 +0,0 @@ -Indexing commands and behavior reference for DocumentDB, including index types, Extended RUM, and configuration options. diff --git a/api-reference/commands/indexing/extended-rum.md b/api-reference/commands/indexing/extended-rum.md deleted file mode 100644 index 95fea20..0000000 --- a/api-reference/commands/indexing/extended-rum.md +++ /dev/null @@ -1,83 +0,0 @@ ---- -title: Extended RUM -description: Extended RUM is the default index access method for DocumentDB on PostgreSQL 18 and later, providing enhanced query and scan capabilities over the standard RUM index. -type: commands -category: indexing ---- - -# Extended RUM - -Extended RUM (`documentdb_extended_rum`) is a fork of the [RUM](https://github.com/postgrespro/rum) index access method that extends it with capabilities specific to DocumentDB's document-oriented workloads. Starting with DocumentDB **v0.108**, Extended RUM is the **default** index access method on PostgreSQL 18+ setups. - -## Overview - -DocumentDB uses RUM indexes internally for document indexing and query execution. Extended RUM builds on the standard RUM access method with improvements to the query path while keeping the same on-disk storage layout. This means: - -- Indexes created with standard RUM and Extended RUM are **storage-compatible** — they have the same layout on disk. -- All changes in Extended RUM are limited to the query and scan paths. Existing indexes do not need to be rebuilt. -- Extended RUM is loaded as a separate PostgreSQL extension (`documentdb_extended_rum`) alongside the core DocumentDB extension. - -## Default behavior by PostgreSQL version - -| PostgreSQL version | Default RUM behavior | GUC default | -|---|---|---| -| PG 16, PG 17 | Standard RUM | `none` | -| PG 18+ | Extended RUM (**required**) | `require_documentdb_extended_rum` | - -On PostgreSQL 18 and later, DocumentDB defaults to `require_documentdb_extended_rum`, meaning the Extended RUM library must be loaded for the server to function correctly. On earlier PostgreSQL versions, the standard RUM access method is used unless explicitly overridden. - -## Configuration - -### `documentdb.rum_library_load_option` - -This GUC controls how the RUM library is loaded. It is a **postmaster-level** setting, meaning it requires a server restart to take effect. - -| Value | Behavior | -|---|---| -| `none` | Use the standard RUM access method. Default on PG 16/17. | -| `prefer_documentdb_extended_rum` | Use Extended RUM if available; fall back to standard RUM otherwise. | -| `require_documentdb_extended_rum` | Require Extended RUM; fail to start if it is not available. Default on PG 18+. | - -### `documentdb.alternate_index_handler_name` - -When Extended RUM is enabled, this is set to `extended_rum` to route index operations through the Extended RUM access method. - -## DocumentDB Local - -When running DocumentDB Local via Docker, Extended RUM is **enabled by default**. - -To disable Extended RUM, pass the `--disable-extended-rum` flag: - -```bash -docker run -dt -p 10260:10260 --name docdb \ - ghcr.io/documentdb/documentdb/documentdb-local:latest \ - --username demo --password test \ - --disable-extended-rum -``` - -You can also set the `DISABLE_EXTENDED_RUM=true` environment variable: - -```bash -docker run -dt -p 10260:10260 --name docdb \ - -e DISABLE_EXTENDED_RUM=true \ - ghcr.io/documentdb/documentdb/documentdb-local:latest \ - --username demo --password test -``` - -## Related features - -### Ordered indexes - -DocumentDB v0.109 enabled **ordered indexes by default**. Ordered indexes use a composite operator class that can improve sort and range query performance. This behavior works alongside Extended RUM and can be controlled independently: - -- Per-index: specify `"storageEngine": {"enableOrderedIndex": false}` when creating an index. -- Server-wide: set the `documentdb.defaultUseCompositeOpClass` GUC to `off`. - -## Version history - -| Version | Change | -|---|---| -| v0.104 | `rum_enable_index_scan` enabled by default. | -| v0.106 | Internal Extended RUM extension added. | -| v0.108 | Extended RUM becomes the default on PG 18+. RUM dependency becomes implicit via the shared library. | -| v0.109 | Ordered indexes enabled by default (`defaultUseCompositeOpClass`). |