Versioned API is a new feature in MongoDB 5.0 that allows user-selectable API versions, subsets of MongoDB server semantics, to be declared on a client. During communication with a server, clients with a declared API version will force the server to behave in a manner compatible with the API version. Declaring an API version on a client can be used to ensure consistent responses from a server, providing long term API stability for an application. The declared API version is applied to all commands run through the client, including those sent through the generic RunCommand helper. Specifying versioned API options in the command document AND declaring an API version on the client is not supported and will lead to undefined behavior.
// Declare API version "1" for the client
client = new MongoClient(uri, { serverApi: { version: '1' } });
cursor = client.db('database').collection('coll').find(...);
Declaring a strict
API version will cause the MongoDB server to reject all commands that are not part of the declared API version. This includes command options and aggregation pipeline stages. For example, the following find
call would fail because the tailable
option is not part of version 1:
// Declare API version "1" for the client, with strict on
client = new MongoClient(uri, { serverApi: { version: '1', strict: true } });
// Fails with an error
cursor = client.db('database').collection('coll').find({ ... }, { tailable: true });
The deprecationErrors
option can be used to enable command failures when using functionality that is deprecated from version 1. Note that at the time of this writing, no deprecations in version 1 exist.
// Declare API version "1" for the client, with deprecationErrors on
client = new MongoClient(uri, { serverApi: { version: '1', deprecationErrors: true } });
// Note: since API version "1" is the initial version, there are no deprecated commands to provide as an example yet.
NODE-3392
: enable snapshot reads on secondaries (#2897) (523e05c)NODE-2751
: add arrayFilters builder to bulk FindOperators (#2820) (d099622)NODE-3274
: add type hinting for UpdateFilter (#2842) (05035eb)NODE-3325
: support 'let' option for aggregate command (#2828) (e38838e)NODE-3331
: offer downleveled types for legacy typescript versions (#2859) (27cf1d2)NODE-3333
: support 'let' option for CRUD commands (#2829) (0d91da1)NODE-3115
: add generic parameterization (#2767) (4d12491)NODE-3132
: add TypedEventEmitter (#2785) (f4d40a4)NODE-3106
: add fermium to evergreen test runs (#2762) (2303b41)NODE-2950
: versioned api (#2736) (93f3ea5)NODE-2806
: addwithReadConcern
builder to AbstractCursor (#2645) (0cca729)NODE-2917
: add an internaltryNext
method (#2638) (43c94b6)NODE-2569
: add commitQuorum option to createIndexes command (#2345) (168a952)NODE-2853
: add explain support for cursor commands (#2622) (bb1e081)NODE-2852
: add explain support for non-cursor commands (#2599) (4472308)NODE-2288
: add MONGODB-AWS as a supported auth mechanism (7f3cfba)NODE-2699
: add MongoOption builder logic (#2623) (cb9ee9e)NODE-2871
: implement post-assignment operations (tls, dns, aliases) (#2623) (cb9ee9e)NODE-2698
: add MongoOptions interface (#2616) (54c456b)NODE-2932
: add types for the result of bulk initialize methods (#2654) (3e5ff57)NODE-2591
: adds "hidden" option when creating indexes (#2548) (ee8ca1a)NODE-2590
: adds async iterator for custom promises (#2578) (16d6572)NODE-2477
: allow hinting the delete command (#2302) (95fedf4)NODE-2150
: bump wire protocol version for 4.4 (6d3f313)NODE-1452
: convert the entire codebase to TypeScript (272bc18)NODE-2452
: directConnection adds unify behavior for replica set discovery (#2349) (34c9195)NODE-2379
: expand use of error labels for retryable writes (c775a4a)NODE-2579
: implements promise provider (#2348) (e5b762c)NODE-2704
: integrate MongoOptions parser into driver (#2680) (b1bdb06)NODE-2809
: introduce AbstractCursor and its concrete subclasses (#2619) (a2d78b2)NODE-2930
: introduce BufferPool to replace BufferList (#2669) (3c56efc)NODE-2811
: reintroduce clone and rewind for cursors (#2647) (a5154fb)NODE-2289
: supportallowDiskUse
for find commands (dbc0b37)NODE-2295
: support creating collections and indexes in transactions (917f2b0)NODE-2757
: add collation to FindOperators (#2679) (a41d503)NODE-2510
: support hedged reads (#2350) (2b7b936)NODE-2290
: support passing a hint to findOneAndReplace/findOneAndUpdate (faee15b)NODE-2301
: support shorter SCRAM conversations (6b9ff05)NODE-2955
: fluent builder for allowDiskUse option (#2678) (d442aac)NODE-2487
: support speculative authentication in scram-sha and x509 (#2353) (f71f09b)NODE-2379
: use error labels for retryable writes in legacy topologies (fefc165)NO TICKET
: options object precedence over URI options (#2691) (85d8d09)NO TICKET
: introduce an interruptable async interval timer (21cbabd)NO TICKET
: support the streaming protocol for topology updates (7e9c5bc)