feat(NODE-6893): Distinguish between command-level options and index-level options when creating indexes by seanrmilligan · Pull Request #5012 · mongodb/node-mongodb-native

seanrmilligan · 2026-07-28T03:08:35Z

Description

Summary of Changes

Differentiates between options for indexes and options for commands in the createIndex and createIndexes API.

More granular changes:

Create a createIndex overload with three parameters to differentiate between options for the index and options for the command
Add a @deprecated tag to the createIndex overoad with two parameters (the mixed index/command options path), to be removed in a future release.
Migrate internal calls to createIndex from the deprecated two-parameter overload to the preferred three-parameter overload.
Maintain parity with existing behavior (filtering unknown index options) by way of an allowUnknownIndexOptions toggle.
Import interface IndexOptions from the specifications repository
Align interface CreateIndexesOptions with the specifications repository by deprecating options related to indexes and leaving only options related to commands.

Notes for Reviewers

Types

There are many similar type names floating around. Some come by design from the spec, and some from the history of the API in this area. Note the differences between:

CreateIndexOptions -- options for the command createIndex
CreateIndexesOptions -- options for the command createIndexes
IndexOptions -- options for an index
CreateIndexesOperation -- the command to create indexes, containing all relevant parts including index property names, index options, and command options are fed.

`CreateIndexesOperation`

The CreateIndexesOperation command object is created on both the createIndex and createIndexes paths. It accepts an array of indexes, where the createIndex path is the special case of an array with only one item. There is no corresponding CreateIndexOperation for creating a single index.

`allowUnknownIndexOptions`

allowUnknownIndexOptions is inferred transparently on behalf of the consumer of the createIndex API by detecting whether the caller called the two parameter overload (old behavior, set to false) or the three parameter overload (new, set to true). Using the createIndex(<3>) overload is considered as opting into the new passthrough behavior.

allowUnknownIndexOptions cannot be inferred on the createIndexes path because the types on createIndexes already align with the spec.

What is the motivation for this change?

This is in support of achieving "passthrough" behavior where options are validated by the server rather than the driver. Validation of options by the server rather than the driver accomplishes two goals:

It presents a more consistent experience for users across drivers.
Where the language allows, users can now send an index option supported by the server before the driver has even added the option to the options type.

Release Highlight

Release notes highlight

Adds support for "pass-through" behavior for index options: all index options passed (when opted in) will now be validated by the server rather than the driver. This will become the default behavior in a future release.
Adds an overload for createIndex which separates options for the index from options for the command. This new overload also uses pass-through behavior by default.
The original createIndex overload, which retains driver-side options validation, has been deprecated and will be removed in a future major release.
Adds an opt-in flag to new passthrough behavior to the createIndexes API. This flag will be removed and pass-through will become the default in a future major release.

Double check the following

Lint is passing (npm run check:lint)
Self-review completed using the steps outlined here
PR title follows the correct format: type(NODE-xxxx)[!]: description
- Example: feat(NODE-1234)!: rewriting everything in coffeescript
Changes are covered by tests
New TODOs have a related JIRA ticket

Copilot

🟡 Changes recommended

Unresolved moderate issues affect overload typing, command-option typing, and serialization of language options.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

Adds opt-in passthrough for unknown index options while separating index and command options for createIndex.

Changes:

Adds allowUnknownIndexOptions handling.
Introduces IndexOptions and CreateIndexOptions.
Updates operation construction, exports, and test coverage.

File summaries

File	Summary
`test/unit/operations/indexes.test.ts`	Tests option filtering and passthrough behavior.
`test/unit/collection.test.ts`	Tests command and index option separation.
`test/integration/index-management/create_indexes_option_validation.test.ts`	Adds integration validation coverage.
`test/integration/index_management.test.ts`	Tests unknown-option handling.
`test/integration/crud/abstract_operation.test.ts`	Updates operation construction tests.
`src/utils.ts`	Resolves inherited command options.
`src/operations/indexes.ts`	Defines option types, filtering, and passthrough logic.
`src/operations/create_collection.ts`	Updates internal index creation.
`src/index.ts`	Exports new public option types.
`src/gridfs/upload.ts`	Documents future option migration.
`src/db.ts`	Updates `createIndex` operation construction.
`src/collection.ts`	Adds overloads and passthrough support.

Review details

Suppressed comments (7)

src/collection.ts:739

This new TODO also has no NODE/DRIVERS ticket identifier, unlike the repository's established TODO convention. Please link the future default-change work to a concrete ticket before merging.

        // TODO(seanrmilligan): default this to true and remove the parameter in a future major
        // release. Index options live on each index description, so nothing on this path
        // contaminates them -- but flipping it turns today's silently dropped unknown option into
        // a server error.

src/collection.ts:655

The passthrough overload leaves commandOptions optional, but the implementation uses commandOptions == null to select the legacy allowlist path. A valid two-argument call using the new IndexOptions shape (for example { defaultLanguage: 'english' }) is therefore accepted by TypeScript and then silently drops the option. Require the third argument for this overload, or use an unambiguous runtime discriminator.

    indexOptions?: IndexOptions,
    commandOptions?: CreateIndexOptions

src/gridfs/upload.ts:278

This TODO refers to validateOptions, but that is not the option controlling this code path; the new API uses allowUnknownIndexOptions. The stale name will mislead anyone implementing the GridFS migration, so update the comment to the actual overload/flag.

    // the index option allowlist. When validateOptions defaults to false, move the command
    // options into the third parameter.

src/gridfs/upload.ts:387

This TODO also names the nonexistent validateOptions setting. Refer to the legacy two-parameter createIndex path instead so the follow-up work is tied to the API that actually controls the behavior.

    // TODO(NODE-6893): timeoutMS is a command option; move it into the third parameter when
    // validateOptions defaults to false.

src/operations/indexes.ts:479

A command comment is normally any BSON value (CommandOperationOptions.comment is unknown), but this new public type narrows it to Document. The string comments used by the added createIndex tests are consequently not typeable through the new overload; use the existing unknown comment type.

  comment?: Document;

src/operations/indexes.ts:479

This new public option is documented as enabling comments, but CreateIndexesOperation.buildCommandDocument still emits only commitQuorum from the command options, so comment is silently dropped. The added unit test currently asserts the opposite behavior; either add comment to the command document or remove it from this API until it is supported.

  /**
   * Enables users to specify an arbitrary comment to help trace the operation through
   * the database profiler, currentOp and logs. The default is to not send a value.
   *
   * @see https://www.mongodb.com/docs/manual/reference/command/createIndexes/
   *
   * @sinceServerVersion 4.4
   */
  comment?: Document;

src/operations/indexes.ts:610

Repository TODOs consistently carry a NODE/DRIVERS ticket identifier, but this TODO explicitly asks for a future NODE ticket without one. Please attach the follow-up ticket so the planned default change remains traceable.

        // TODO(seanrmilligan): Add NODE ticket to set to remove allowUnknownIndexOptions with
        // a default behavior of true in a future 8.0.0 release

Files reviewed: 12/12 changed files
Comments generated: 4
Review effort level: Lite

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

PavelSafronov

There are a number of type additions, but no new types tests. You'll need to add these.

tadjik1 · 2026-09-14T14:13:16Z

2 tests are failing across the variants (looks relevant to changes):

[2026/09/11 16:19:54.080]   2 failing
[2026/09/11 16:19:54.080]   1) createIndex option validation
[2026/09/11 16:19:54.080]        when command options are given (three parameter form)
[2026/09/11 16:19:54.080]          creates an index using a server option the driver does not know about:
[2026/09/11 16:19:54.080]      MongoServerError: Error in specification { prepareUnique: true, key: { e: 1 }, name: "e_1" } :: caused by :: The field 'prepareUnique' is not valid for an index specification. Specification: { prepareUnique: true, key: { e: 1 }, name: "e_1" }
[2026/09/11 16:19:54.080]       at Connection.sendCommand (src/cmap/connection.ts:174:4)
[2026/09/11 16:19:54.080]       at processTicksAndRejections (node:internal/process/task_queues:104:5)
[2026/09/11 16:19:54.080]       at async Connection.command (src/cmap/connection.ts:174:4)
[2026/09/11 16:19:54.080]       at async Server.command (src/sdam/server.ts:68:58)
[2026/09/11 16:19:54.080]       at async executeOperationWithRetries (src/operations/execute_operation.ts:92:6)
[2026/09/11 16:19:54.080]       at async executeOperation (src/operations/execute_operation.ts:24:2576)
[2026/09/11 16:19:54.080]       at async Collection.createIndex (src/collection.ts:151:267)
[2026/09/11 16:19:54.080]       at async Context.<anonymous> (test/integration/index-management/create_indexes_option_validation.test.ts:166:9)
[2026/09/11 16:19:54.080] 
[2026/09/11 16:19:54.080]   2) createIndexes option validation
[2026/09/11 16:19:54.080]        when command options are given
[2026/09/11 16:19:54.080]          creates an index using a server option the driver does not know about:
[2026/09/11 16:19:54.080]      MongoServerError: Error in specification { key: { e: 1 }, name: "e_1", prepareUnique: true } :: caused by :: The field 'prepareUnique' is not valid for an index specification. Specification: { key: { e: 1 }, name: "e_1", prepareUnique: true }
[2026/09/11 16:19:54.080]       at Connection.sendCommand (src/cmap/connection.ts:174:4)
[2026/09/11 16:19:54.080]       at processTicksAndRejections (node:internal/process/task_queues:104:5)
[2026/09/11 16:19:54.080]       at async Connection.command (src/cmap/connection.ts:174:4)
[2026/09/11 16:19:54.080]       at async Server.command (src/sdam/server.ts:68:58)
[2026/09/11 16:19:54.080]       at async executeOperationWithRetries (src/operations/execute_operation.ts:92:6)
[2026/09/11 16:19:54.080]       at async executeOperation (src/operations/execute_operation.ts:24:2576)
[2026/09/11 16:19:54.080]       at async Collection.createIndexes (src/collection.ts:187:170)
[2026/09/11 16:19:54.080]       at async Context.<anonymous> (test/integration/index-management/create_indexes_option_validation.test.ts:357:9)

…eIndexOptions

seanrmilligan · 2026-09-15T13:57:06Z

2 tests are failing across the variants (looks relevant to changes):
...

I suspect this is because the wrong server version was used. Waiting on evergreen to confirm latest push.

…ptions is true

PavelSafronov

Can you also add release notes to the PR description? We'll definitely need those.

addaleax

This looks like something that will eventually require compatibility work in mongosh, let's make sure to give this ticket the appropriate downstream changes marker

addaleax · 2026-09-17T17:56:09Z

+   * @param commandOptions - Optional settings for the `createIndexes` command
+   * @param allowUnknownIndexOptions - When `true`, index options the driver does not recognise are
+   *   sent to the server instead of being dropped. Defaults to `false`; this will become the only
+   *   behaviour in a future major release.


Should this also be deprecated then?

Sean to add TODO(NODE-7868) to allowUnknownIndexOptions parameter.

Sean to consider declaring this function as a two-parameter, and three-parameter overload. If so, remove optionality for second parameter, making it | undefined. Mark new three parameter overload as deprecated so that 8.0 goes back to only having single two-parameter overload but with new passthrough behavior always on.

Sean implemented this: createIndexes now has two-parameter and three-parameter overloads, with the three-parameter one deprecated.

Note that the arity is flipped relative to createIndex, but this is correct. The rule we’re applying is deprecate whatever won’t exist in 8.0:

createIndex: the merged options bag goes away, so the two-parameter form is legacy.

createIndexes: allowUnknownIndexOptions goes away once passthrough is the default (NODE-7868), so the three-parameter form is the temporary one.

… parameter

…verride

seanrmilligan · 2026-09-24T14:00:45Z

Can you also add release notes to the PR description? We'll definitely need those.

Done.

…ateIndexes

…ndex

PavelSafronov · 2026-09-24T22:02:42Z

+  /**
+   * Creates the index in the background, yielding whenever possible.
+   *
+   * @deprecated Index options will be removed from this type in a future major release. Pass


These @deprecated attributes are no longer necessary, since the legacy 2-param method carries the @deprecated attribute now.

The spec provides for:

CreateIndexOptions for createIndex, and

CreateIndexesOptions for createIndexes

Note that CreateIndexOptions and CreateIndexesOptions have the same set of members so there isn't a functional difference. Where there is a difference is how:

(a) createIndex's two parameter overload erroneously used CreateIndexesOptions instead of CreateIndexOptions (mostly harmless)

(b) CreateIndexesOptions contained options for the command and options for the index (bad). It was essentially a union of CreateIndexesOptions and IndexOptions from the spec.

Deprecating the two-parameter overload moves us toward using the correct type (CreateIndexOptions singular) in the function signature.

Deprecating the individual fields in CreateIndexesOptions (plural) is also necessary to align createIndexes with the members that the spec provides as options for the command.

Right you are, I missed that.
For the plural method these field tags are the only signal that index options don't belong in the command input, so we definitely do want them there.

The issue with this approach, though, is that the Pick pulls in all the @deprecated attributes as well. So I think we need the explicit field definitions here after all. I tried this locally with unique and sparse and it worked.

Worth adding a type test for this as well:

expectDeprecated(legacyOptions.unique); expectNotDeprecated(indexDescription.unique);

johnmtll

Pretty much all nitpicks, feel free to skip as many as you like. Only 2 real requests, and they're just test restructuring.
https://github.com/mongodb/node-mongodb-native/pull/5012/changes#r4031303695 https://github.com/mongodb/node-mongodb-native/pull/5012/changes#r4040901817

Awesome stuff Sean. Thanks!

johnmtll · 2026-09-16T22:19:37Z

+    });
+
+    describe('and command options are passed in the third parameter', function () {
+      it('keeps a comment out of the index description', async function () {


This test seems to ensure that indexOptions are exclusively considered and not command options. I think this does a good job asserting that, but the following two tests ('sends maxTimeMS on the command and not in the index description', 'sends a session on the command and not in the index description') are redundant because they effectively assert the same thing. the session test actually tests a little bit more than just that though, so I suggest supplanting this test, and the following test, with that one.

johnmtll · 2026-09-17T19:55:42Z

    });
  });
+
+  context('#createIndex', () => {


I think these tests are a little hard to read and they escape the scope of the intended unit to test. The intent is just to test how CreateIndexesOperation is constructed. I think there are some places where we breach into the behaviour of fromIndexSpecification and executeOperation but that behaviour is external to collections.createIndex, and is already covered by indexes.test.ts. I'd prefer we reduce the test footprint to focus solely on the unit being tested (createIndex).

If you opt to do 2 tests here, you could do:

when commandOptions are supplied: it('enables passthrough and passes index/command options separately')
In here, assert an unknown option is forwarded, check that command opts come only from third param, and indexopts only come from second

when commandOptions are not supplied: it('disables passthrough and passes an index/command option composite').
In here, assert an unknown option is not forwarded, 2nd parameter opts lands on command and index respectively

…sOperation Collapse the private constructor to a single signature and make the trailing options parameters of the constructor and both static factories mandatory but nullable (`| undefined`). Callers must now pass `undefined` explicitly, so "forgot to pass command options" is a compile error rather than being indistinguishable from "there are no command options". Drops the redundant constructor overloads and the third `fromIndexSpecification` signature, and updates every call site (including tests) to pass `undefined` where no command options apply.

…eateIndex overload Make `indexOptions` and `commandOptions` on the three parameter `createIndex` overload mandatory (still nullable). With both optional, a two argument call that failed the legacy overload on an unknown option fell through to this overload, since `IndexOptions` accepts arbitrary keys. That silently dropped the compile error, hid the deprecation warning, and matched a pass-through signature for a call that takes the legacy path at runtime. Two argument calls can now only match the legacy overload, so the unknown option error is reported again. Restore the `@ts-expect-error` on the two tests that deliberately pass an unknown option on the legacy path.

`IndexOptions` is new in this change, and `background` has been ignored by the server since 4.2 while the driver's minimum supported server is 4.4. Rather than add the field only to deprecate and remove it later, leave it out. GridFS no longer sends `background` when creating its indexes, which has no effect on the server. The released `CreateIndexesOptions.background` is kept for the two parameter path and remains deprecated until v8.

seanrmilligan force-pushed the sean.milligan/createIndex branch from 93afa52 to 756f24d Compare August 26, 2026 20:18

dariakp changed the title ~~Allow passthrough options on createIndexes~~ feat(NODE-6893): Allow passthrough options on createIndexes Aug 31, 2026

seanrmilligan force-pushed the sean.milligan/createIndex branch from 756f24d to 5304629 Compare September 9, 2026 19:16

PavelSafronov reviewed Sep 9, 2026

View reviewed changes

Sean Milligan added 2 commits September 10, 2026 14:05

Allow passthrough options on createIndexes

8a0866f

Fix: createIndexes / fromIndexDescriptionArray interaction

991884f

seanrmilligan force-pushed the sean.milligan/createIndex branch from 5304629 to 991884f Compare September 11, 2026 13:55

seanrmilligan marked this pull request as ready for review September 11, 2026 13:56

seanrmilligan requested a review from a team as a code owner September 11, 2026 13:56

Copilot AI lite review requested due to automatic review settings September 11, 2026 13:56

Copilot started reviewing on behalf of seanrmilligan September 11, 2026 13:57 View session

Copilot AI reviewed Sep 11, 2026

View reviewed changes

Comment thread src/operations/indexes.ts Outdated

Comment thread src/operations/indexes.ts Outdated

Comment thread src/operations/indexes.ts Outdated

Comment thread src/utils.ts Outdated

PavelSafronov reviewed Sep 11, 2026

View reviewed changes

Comment thread src/collection.ts

Comment thread test/integration/index-management/create_indexes_option_validation.test.ts Outdated

Comment thread test/integration/index-management/create_indexes_option_validation.test.ts Outdated

PavelSafronov requested changes Sep 11, 2026

View reviewed changes

Comment thread src/operations/indexes.ts Outdated

Comment thread src/operations/indexes.ts Outdated

Comment thread src/operations/indexes.ts Outdated

Comment thread src/operations/indexes.ts Outdated

Comment thread src/utils.ts Outdated

Sean Milligan added 4 commits September 14, 2026 15:04

drop ticket number from test db string name

ab02deb

Inherit CSOT and other fields from CommandOperationOptions into Creat…

e1ad022

…eIndexOptions

support public api spec / wire property naming differences with a map

4a4310c

prepareUnique requires 6.0+

214cd1a

remove metadata

4c1630b

seanrmilligan requested a review from PavelSafronov September 15, 2026 14:32

PavelSafronov reviewed Sep 16, 2026

View reviewed changes

Comment thread src/operations/indexes.ts

Comment thread src/operations/indexes.ts

Comment thread src/operations/indexes.ts Outdated

seanrmilligan changed the title ~~feat(NODE-6893): Allow passthrough options on createIndexes~~ feat(NODE-6893): Distinguish between command-level options and index-level options when creating indexes Sep 17, 2026

Remove 'key' in resolveIndexDescription, even when allowUnknownIndexO…

4d84948

…ptions is true

PavelSafronov self-assigned this Sep 17, 2026

PavelSafronov added the Primary Review In Review with primary reviewer, not yet ready for team's eyes label Sep 17, 2026

PavelSafronov reviewed Sep 17, 2026

View reviewed changes

Comment thread src/collection.ts

addaleax reviewed Sep 17, 2026

View reviewed changes

Update TODO with ticket number

44b38b1

Sean Milligan added 6 commits September 23, 2026 13:22

remove optionality from CreateIndexesOperation options/commandOptions…

44c62ee

… parameter

deprecate option for removal in 8.x

f560c71

Extend Document to allow unknown options without a @ts-expect-error o…

e0ec424

…verride

Add 2dsphere options to IndexOptions interface

30f40b0

remove ts-expect-error

56d06d9

Add deprecated comment to two-parameter overload of createIndex

2712b41

Sean Milligan added 3 commits September 24, 2026 07:04

change how I deprecated the allowUnknownIndexOptions parameter on cre…

b3279ed

…ateIndexes

type tests

7339d8a

Merge remote-tracking branch 'origin/main' into sean.milligan/createI…

9cdbeef

…ndex

PavelSafronov reviewed Sep 24, 2026

View reviewed changes

more TODO -> ticket number updates

293bdc2

johnmtll reviewed Sep 29, 2026

View reviewed changes

Sean Milligan added 5 commits September 30, 2026 13:16

Remove clustered, finestIndexedLevel, coarsestIndexedLevel

f9fac6f

pr feedback: testing

1a43ad0

Conversation

seanrmilligan commented Jul 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Summary of Changes

Notes for Reviewers

Types

CreateIndexesOperation

allowUnknownIndexOptions

What is the motivation for this change?

Release Highlight

Release notes highlight

Double check the following

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟡 Changes recommended

Suppressed comments (7)

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

PavelSafronov left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

tadjik1 commented Sep 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

seanrmilligan commented Sep 15, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

PavelSafronov left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

addaleax left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

seanrmilligan commented Sep 24, 2026

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

johnmtll left a comment

Choose a reason for hiding this comment

Uh oh!

seanrmilligan commented Jul 28, 2026 •

edited

Loading

`CreateIndexesOperation`

`allowUnknownIndexOptions`

tadjik1 commented Sep 14, 2026 •

edited

Loading