Context

allowUnknownIndexOptions is a temporary parameter introduced to several internal functions and one external API to support backwards compatibility in driver behavior.

• Original driver behavior is to verify the index options passed by the caller against a known list of valid options.
• New behavior is to pass all options on to the server, which will validate the options.

For a period of time, allowUnknownIndexOptions allows users in driver v7.x to opt into this new passthrough behavior, with the opt-in set to a default of false.

In v8, this option should be removed so that all users are on the same passthrough path. (equivalent to setting true in 7.x)

User Experience

• What is the desired/expected outcome for the user once this ticket is implemented?
  • This will end a journey to migrate the createIndex and createIndexes APIs to the function signature defined in the spec
  • This will remove ambiguity in options that are for the creation of the index itself, versus options that manage the command (or operation)
  • This will give users of multiple drivers a consistent accept/reject surface from the server.
  • While the driver can still offer a type containing known valid options for the purpose of intellisense / IDE auto-complete, this will allow users to "force" through an option newly supported by the server but not yet acknowledged by the implementing driver. In other words, bleeding edge adopters are not hampered by the driver.

Dependencies

• Mongosh consumes from the Node.js driver specifically and should be warned/tested against the changed API surface (allowUnknownIndexOptions is visible in createIndexes)

Risks/Unknowns

• What could go wrong while implementing this change? (e.g., performance, inadvertent behavioral changes in adjacent functionality, existing tech debt, etc)
  • This is a planned breaking change that must happen in a major version release.
  • The behavioral change is twofold:
    • There will be a new error message shape from the server when a bad option is passed.
    • The driver will no longer quietly remove bad options and pass on the good ones. Bad options may be sitting latent in codebases, getting passed to createIndex(es) and the driver has been saving them this whole time. These options will now go to the server and error when they would not have before.
• Is there an opportunity for better cross-driver alignment or testing in this area?
  • createIndex in Node.js was not aligned with the spec, and is old enough that its implementation may have pre-dated the spec. If that is the case, other drivers may need a nudge to check if they are using passthrough behavior or not
• Is there an opportunity to improve existing documentation on this subject?

Acceptance Criteria

Implementation Requirements

• functional reqs, potential snafus to avoid, performance targets, etc

Testing Requirements

• There are tests for the allowUnknownIndexOptions=false and allowUnknownIndexOptions=true paths in unit and integration tests. Remove tests that vary on allowUnknownIndexOptions. Drop the allowUnknownIndexOptions parameter, drop the false path, and implicitly take the true path.

Documentation Requirements

• Remove allowUnknownIndexOptions from the createIndexes API documentation.

Follow Up Requirements