diff --git a/source/crud/bulk-write.md b/source/crud/bulk-write.md index b07329ef22..574307e9ab 100644 --- a/source/crud/bulk-write.md +++ b/source/crud/bulk-write.md @@ -313,6 +313,13 @@ class BulkWriteOptions { * This option MAY be implemented by drivers that need to grant access to underlying namespaces * for time-series collections. Drivers SHOULD NOT implement this option unless asked to do so. * + * This option is intended for internal use by MongoDB teams and should be discouraged for + * general application use. It may be changed or removed in any release without notice. + * + * Drivers SHOULD implement this option in a way that discourages customer use, such as: + * - Marking it as deprecated, experimental, or internal in their language's idioms + * - Excluding it from primary documentation + * * @note This option MUST NOT be sent when connected to pre-8.2 servers. * * @since MongoDB 8.2 @@ -940,6 +947,8 @@ error in this specific situation does not seem helpful enough to require size ch ## **Changelog** +- 2025-09-09: Clarify that `rawData` is for internal use only. + - 2025-08-13: Removed the requirement to error when QE is enabled. - 2025-06-27: Added `rawData` option. diff --git a/source/crud/crud.md b/source/crud/crud.md index e3cb258d27..3f2b2ca8fa 100644 --- a/source/crud/crud.md +++ b/source/crud/crud.md @@ -323,6 +323,13 @@ class AggregateOptions { /** * This option MAY be implemented by drivers that need to grant access to underlying namespaces * for time-series collections. Drivers SHOULD NOT implement this option unless asked to do so. + + * This option is intended for internal use by MongoDB teams and should be discouraged for + * general application use. It may be changed or removed in any release without notice. + * + * Drivers SHOULD implement this option in a way that discourages customer use, such as: + * - Marking it as deprecated, experimental, or internal in their language's idioms + * - Excluding it from primary documentation * * @note This option MUST NOT be sent when connected to pre-8.2 servers. * @@ -384,7 +391,13 @@ class CountOptions { /** * This option MAY be implemented by drivers that need to grant access to underlying namespaces - * for time-series collections. Drivers SHOULD NOT implement this option unless asked to do so. + * + * This option is intended for internal use by MongoDB teams and should be discouraged for + * general application use. It may be changed or removed in any release without notice. + * + * Drivers SHOULD implement this option in a way that discourages customer use, such as: + * - Marking it as deprecated, experimental, or internal in their language's idioms + * - Excluding it from primary documentation * * @note This option MUST NOT be sent when connected to pre-8.2 servers. * @@ -415,11 +428,18 @@ class EstimatedDocumentCountOptions { * comment may result in a server-side error. */ comment: Optional; - + /** * This option MAY be implemented by drivers that need to grant access to underlying namespaces * for time-series collections. Drivers SHOULD NOT implement this option unless asked to do so. * + * This option is intended for internal use by MongoDB teams and should be discouraged for + * general application use. It may be changed or removed in any release without notice. + * + * Drivers SHOULD implement this option in a way that discourages customer use, such as: + * - Marking it as deprecated, experimental, or internal in their language's idioms + * - Excluding it from primary documentation + * * @note This option MUST NOT be sent when connected to pre-8.2 servers. * * @since MongoDB 8.2 @@ -469,11 +489,18 @@ class DistinctOptions { * @see https://www.mongodb.com/docs/manual/reference/command/find/ */ hint: Optional<(String | Document)>; - + /** * This option MAY be implemented by drivers that need to grant access to underlying namespaces * for time-series collections. Drivers SHOULD NOT implement this option unless asked to do so. * + * This option is intended for internal use by MongoDB teams and should be discouraged for + * general application use. It may be changed or removed in any release without notice. + * + * Drivers SHOULD implement this option in a way that discourages customer use, such as: + * - Marking it as deprecated, experimental, or internal in their language's idioms + * - Excluding it from primary documentation + * * @note This option MUST NOT be sent when connected to pre-8.2 servers. * * @since MongoDB 8.2 @@ -753,11 +780,18 @@ class FindOptions { * @see https://www.mongodb.com/docs/manual/reference/command/find/ */ let: Optional; - + /** * This option MAY be implemented by drivers that need to grant access to underlying namespaces * for time-series collections. Drivers SHOULD NOT implement this option unless asked to do so. * + * This option is intended for internal use by MongoDB teams and should be discouraged for + * general application use. It may be changed or removed in any release without notice. + * + * Drivers SHOULD implement this option in a way that discourages customer use, such as: + * - Marking it as deprecated, experimental, or internal in their language's idioms + * - Excluding it from primary documentation + * * @note This option MUST NOT be sent when connected to pre-8.2 servers. * * @since MongoDB 8.2 @@ -1035,11 +1069,18 @@ class BulkWriteOptions { * The value of let will be passed to all update and delete, but not insert, commands. */ let: Optional; - + /** * This option MAY be implemented by drivers that need to grant access to underlying namespaces * for time-series collections. Drivers SHOULD NOT implement this option unless asked to do so. * + * This option is intended for internal use by MongoDB teams and should be discouraged for + * general application use. It may be changed or removed in any release without notice. + * + * Drivers SHOULD implement this option in a way that discourages customer use, such as: + * - Marking it as deprecated, experimental, or internal in their language's idioms + * - Excluding it from primary documentation + * * @note This option MUST NOT be sent when connected to pre-8.2 servers. * * @since MongoDB 8.2 @@ -1067,11 +1108,18 @@ class InsertOneOptions { * and providing one will result in a server-side error. */ comment: Optional; - + /** * This option MAY be implemented by drivers that need to grant access to underlying namespaces * for time-series collections. Drivers SHOULD NOT implement this option unless asked to do so. * + * This option is intended for internal use by MongoDB teams and should be discouraged for + * general application use. It may be changed or removed in any release without notice. + * + * Drivers SHOULD implement this option in a way that discourages customer use, such as: + * - Marking it as deprecated, experimental, or internal in their language's idioms + * - Excluding it from primary documentation + * * @note This option MUST NOT be sent when connected to pre-8.2 servers. * * @since MongoDB 8.2 @@ -1106,11 +1154,18 @@ class InsertManyOptions { * and providing one will result in a server-side error. */ comment: Optional; - + /** * This option MAY be implemented by drivers that need to grant access to underlying namespaces * for time-series collections. Drivers SHOULD NOT implement this option unless asked to do so. * + * This option is intended for internal use by MongoDB teams and should be discouraged for + * general application use. It may be changed or removed in any release without notice. + * + * Drivers SHOULD implement this option in a way that discourages customer use, such as: + * - Marking it as deprecated, experimental, or internal in their language's idioms + * - Excluding it from primary documentation + * * @note This option MUST NOT be sent when connected to pre-8.2 servers. * * @since MongoDB 8.2 @@ -1207,11 +1262,18 @@ class UpdateOptions { * @see https://www.mongodb.com/docs/manual/reference/command/update/ */ sort: Optional; - + /** * This option MAY be implemented by drivers that need to grant access to underlying namespaces * for time-series collections. Drivers SHOULD NOT implement this option unless asked to do so. * + * This option is intended for internal use by MongoDB teams and should be discouraged for + * general application use. It may be changed or removed in any release without notice. + * + * Drivers SHOULD implement this option in a way that discourages customer use, such as: + * - Marking it as deprecated, experimental, or internal in their language's idioms + * - Excluding it from primary documentation + * * @note This option MUST NOT be sent when connected to pre-8.2 servers. * * @since MongoDB 8.2 @@ -1296,11 +1358,18 @@ class ReplaceOptions { * @see https://www.mongodb.com/docs/manual/reference/command/update/ */ sort: Optional; - + /** * This option MAY be implemented by drivers that need to grant access to underlying namespaces * for time-series collections. Drivers SHOULD NOT implement this option unless asked to do so. * + * This option is intended for internal use by MongoDB teams and should be discouraged for + * general application use. It may be changed or removed in any release without notice. + * + * Drivers SHOULD implement this option in a way that discourages customer use, such as: + * - Marking it as deprecated, experimental, or internal in their language's idioms + * - Excluding it from primary documentation + * * @note This option MUST NOT be sent when connected to pre-8.2 servers. * * @since MongoDB 8.2 @@ -1356,11 +1425,18 @@ class DeleteOptions { * and providing one will result in a server-side error. */ comment: Optional; - + /** * This option MAY be implemented by drivers that need to grant access to underlying namespaces * for time-series collections. Drivers SHOULD NOT implement this option unless asked to do so. * + * This option is intended for internal use by MongoDB teams and should be discouraged for + * general application use. It may be changed or removed in any release without notice. + * + * Drivers SHOULD implement this option in a way that discourages customer use, such as: + * - Marking it as deprecated, experimental, or internal in their language's idioms + * - Excluding it from primary documentation + * * @note This option MUST NOT be sent when connected to pre-8.2 servers. * * @since MongoDB 8.2 @@ -2119,11 +2195,18 @@ class FindOneAndDeleteOptions { * and providing one will result in a server-side error. */ comment: Optional; - + /** * This option MAY be implemented by drivers that need to grant access to underlying namespaces * for time-series collections. Drivers SHOULD NOT implement this option unless asked to do so. * + * This option is intended for internal use by MongoDB teams and should be discouraged for + * general application use. It may be changed or removed in any release without notice. + * + * Drivers SHOULD implement this option in a way that discourages customer use, such as: + * - Marking it as deprecated, experimental, or internal in their language's idioms + * - Excluding it from primary documentation + * * @note This option MUST NOT be sent when connected to pre-8.2 servers. * * @since MongoDB 8.2 @@ -2237,11 +2320,18 @@ class FindOneAndReplaceOptions { * and providing one will result in a server-side error. */ comment: Optional; - + /** * This option MAY be implemented by drivers that need to grant access to underlying namespaces * for time-series collections. Drivers SHOULD NOT implement this option unless asked to do so. * + * This option is intended for internal use by MongoDB teams and should be discouraged for + * general application use. It may be changed or removed in any release without notice. + * + * Drivers SHOULD implement this option in a way that discourages customer use, such as: + * - Marking it as deprecated, experimental, or internal in their language's idioms + * - Excluding it from primary documentation + * * @note This option MUST NOT be sent when connected to pre-8.2 servers. * * @since MongoDB 8.2 @@ -2364,11 +2454,18 @@ class FindOneAndUpdateOptions { * and providing one will result in a server-side error. */ comment: Optional; - + /** * This option MAY be implemented by drivers that need to grant access to underlying namespaces * for time-series collections. Drivers SHOULD NOT implement this option unless asked to do so. * + * This option is intended for internal use by MongoDB teams and should be discouraged for + * general application use. It may be changed or removed in any release without notice. + * + * Drivers SHOULD implement this option in a way that discourages customer use, such as: + * - Marking it as deprecated, experimental, or internal in their language's idioms + * - Excluding it from primary documentation + * * @note This option MUST NOT be sent when connected to pre-8.2 servers. * * @since MongoDB 8.2 @@ -2455,7 +2552,7 @@ specifically. An example, using Node, might look like: collection.find({ name: 'john doe' }).explain({ maxTimeMS: 1000 }); // sends: -{ +{ explain: { find: , query: { name: 'john doe' } }, maxTimeMS: 1000 } @@ -2463,7 +2560,7 @@ collection.find({ name: 'john doe' }).explain({ maxTimeMS: 1000 }); collection.find({ name: 'john doe' }).explain({ timeoutMS: 1000 }); // sends: -{ +{ explain: { find: , query: { name: 'john doe' } }, maxTimeMS: <1000 - min rtt> } @@ -2652,6 +2749,8 @@ aforementioned allowance in the SemVer spec. ## Changelog +- 2025-09-09: Clarify that `rawData` is for internal use only. + - 2025-06-27: Added `rawData` options. - 2024-11-13: Define `findOne` operation as optional, and add guidance on `limit` and `batchSize` for `find` operations. diff --git a/source/index-management/index-management.md b/source/index-management/index-management.md index 2bdb13bcdc..4458e2e00c 100644 --- a/source/index-management/index-management.md +++ b/source/index-management/index-management.md @@ -138,7 +138,7 @@ interface Collection { /** * Creates multiple indexes in the collection. - * + * * In all server versions, this MUST execute a createIndexes command. * * @return The names of all the indexes that were created. @@ -183,7 +183,7 @@ interface Collection { dropIndexes(options: Optional): Result; /** - * Gets index information for all indexes in the collection. The behavior for + * Gets index information for all indexes in the collection. The behavior for * enumerating indexes is described in the :ref:`Enumerating Indexes` section. * */ @@ -218,12 +218,19 @@ interface CreateIndexOptions { * This option MAY be implemented by drivers that need to grant access to underlying namespaces * for time-series collections. Drivers SHOULD NOT implement this option unless asked to do so. * + * This option is intended for internal use by MongoDB teams and should be discouraged for + * general application use. It may be changed or removed in any release without notice. + * + * Drivers SHOULD implement this option in a way that discourages customer use, such as: + * - Marking it as deprecated, experimental, or internal in their language's idioms + * - Excluding it from primary documentation + * * @note This option MUST NOT be sent when connected to pre-8.2 servers. * * @since MongoDB 8.2 */ rawData: Optional; - + /** * 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. @@ -251,6 +258,13 @@ interface DropIndexOptions { * This option MAY be implemented by drivers that need to grant access to underlying namespaces * for time-series collections. Drivers SHOULD NOT implement this option unless asked to do so. * + * This option is intended for internal use by MongoDB teams and should be discouraged for + * general application use. It may be changed or removed in any release without notice. + * + * Drivers SHOULD implement this option in a way that discourages customer use, such as: + * - Marking it as deprecated, experimental, or internal in their language's idioms + * - Excluding it from primary documentation + * * @note This option MUST NOT be sent when connected to pre-8.2 servers. * * @since MongoDB 8.2 @@ -422,8 +436,8 @@ interface IndexView extends Iterable { * For drivers that cannot make IndexView iterable, they MUST implement this method to * return a list of indexes. In the case of async drivers, this MAY return a Future * or language/implementation equivalent. - * - * If drivers are unable to make the IndexView iterable, they MAY opt to provide the options for + * + * If drivers are unable to make the IndexView iterable, they MAY opt to provide the options for * listing search indexes via the `list` method instead of the `Collection.indexes` method. */ @@ -460,7 +474,7 @@ interface IndexView extends Iterable { * * @note Each specification document becomes the "key" field in the document that * is inserted or the command. - * + * */ createMany(models: Iterable, options: Optional): Iterable; @@ -688,7 +702,7 @@ interface IndexOptions { * @example For an index of name: 1, age: -1, the generated name would be "name_1_age_-1". */ name: String; - + /** * Optionally tells the index to only reference documents with the specified field in * the index. @@ -819,7 +833,7 @@ interface ListIndexesOptions { /** * Configures the batch size of the cursor returned from the ``listIndexes`` command. - * + * * @note drivers MAY chose to support batchSize on the ListIndexesOptions. */ batchSize: Optional; @@ -828,6 +842,13 @@ interface ListIndexesOptions { * This option MAY be implemented by drivers that need to grant access to underlying namespaces * for time-series collections. Drivers SHOULD NOT implement this option unless asked to do so. * + * This option is intended for internal use by MongoDB teams and should be discouraged for + * general application use. It may be changed or removed in any release without notice. + * + * Drivers SHOULD implement this option in a way that discourages customer use, such as: + * - Marking it as deprecated, experimental, or internal in their language's idioms + * - Excluding it from primary documentation + * * @note This option MUST NOT be sent when connected to pre-8.2 servers. * * @since MongoDB 8.2 @@ -970,10 +991,10 @@ interface SearchIndexOptions { } /** - * The following interfaces are empty but are provided as placeholders for drivers that cannot + * The following interfaces are empty but are provided as placeholders for drivers that cannot * add options in a non-breaking manner, if options are added in the future. */ -interface CreateSearchIndexOptions {} +interface CreateSearchIndexOptions {} interface UpdateSearchIndexOptions {} interface ListSearchIndexOptions {} interface DropSearchIndexOptions {} @@ -985,22 +1006,22 @@ interface DropSearchIndexOptions {} interface Collection { /** * Convenience method for creating a single search index. - * + * * @return The name of the created search index - * + * * @note Drivers MAY opt to implement this method signature, the signature that * takes an SearchIndexModel as a parameter, or for those languages with method * overloading MAY decide to implement both. - * + * * @note Drivers MAY combine the `indexOptions` with the `createSearchIndexOptions`, if that is idiomatic for their language. */ createSearchIndex(definition: Document, indexOptions: Optional, createSearchIndexOptions: Optional): String; /** * Convenience method for creating a single index. - * + * * @return The name of the created search index - * + * * @note Drivers MAY opt to implement this method signature, the signature that * takes an name and a definition as parameters, or for those languages with method * overloading MAY decide to implement both. @@ -1009,13 +1030,13 @@ interface Collection { /** * Creates multiple search indexes on the collection. - * + * * @return An iterable of the newly created index names. */ createSearchIndexes(models: Iterable, options: CreateSearchIndexOptions): Iterable; /** - * Updates the search index with the given name to use the provided + * Updates the search index with the given name to use the provided * definition. */ updateSearchIndex(name: String, definition: Document, options: Optional): void; @@ -1046,7 +1067,7 @@ interface Collection { interface SearchIndexView extends Iterable { /** - * Enumerates the index information for all search indexes in the collection. + * Enumerates the index information for all search indexes in the collection. * * @note For drivers that cannot make the IndexView iterable, they MUST implement a list * method. See below. @@ -1057,8 +1078,8 @@ interface SearchIndexView extends Iterable { * For drivers that cannot make SearchIndexView iterable, they MUST implement this method to * return a list of indexes. In the case of async drivers, this MAY return a Future * or language/implementation equivalent. - * - * If drivers are unable to make the SearchIndexView iterable, they MAY opt to provide the options for + * + * If drivers are unable to make the SearchIndexView iterable, they MAY opt to provide the options for * listing search indexes via the `list` method instead of the `Collection.searchIndexes` method. */ list(): Cursor; @@ -1072,7 +1093,7 @@ interface SearchIndexView extends Iterable { * @note Drivers MAY opt to implement this method signature, the signature that * takes an SearchIndexModel as a parameter, or for those languages with method * overloading MAY decide to implement both. - * + * * @note Drivers MAY combine the `indexOptions` with the `createSearchIndexOptions`, if that is idiomatic for their language. */ createOne(definition: Document, indexOptions: Optional, createSearchIndexOptions: Optional): String; @@ -1177,6 +1198,8 @@ from mistakenly specifying this option, drivers manually verify it is only sent #### Changelog +- 2025-09-09: Clarify that `rawData` is for internal use only. + - 2025-06-27: Added `rawData` option to CreateIndexOptions, DropIndexOptions and ListIndexesOptions. - 2024-09-05: Moved options in SearchIndexModel to SearchIndexOptions for consistency with IndexModel and IndexOptions.