DRIVERS-3064 Clarify that rawData is for internal use only (#1839)

Author: prestonvasquez

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.

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<any>;
-  
+
   /**
    * 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<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
@@ -1035,11 +1069,18 @@ class BulkWriteOptions {
    * The value of let will be passed to all update and delete, but not insert, commands.
    */
   let: Optional<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
@@ -1067,11 +1108,18 @@ class InsertOneOptions {
    * and providing one will result in a server-side error.
    */
   comment: Optional<any>;
-  
+
   /**
    * 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<any>;
-  
+
   /**
    * 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<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
@@ -1296,11 +1358,18 @@ class ReplaceOptions {
    * @see https://www.mongodb.com/docs/manual/reference/command/update/
    */
   sort: Optional<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
@@ -1356,11 +1425,18 @@ class DeleteOptions {
    * and providing one will result in a server-side error.
    */
   comment: Optional<any>;
-  
+
   /**
    * 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<any>;
-  
+
   /**
    * 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<any>;
-  
+
   /**
    * 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<any>;
-  
+
   /**
    * 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,15 +2552,15 @@ specifically. An example, using Node, might look like:
 collection.find({ name: 'john doe' }).explain({ maxTimeMS: 1000 });
 
 // sends:
-{ 
+{
   explain: { find: <collection>, query: { name: 'john doe' } },
   maxTimeMS: 1000
 }
 
 collection.find({ name: 'john doe' }).explain({ timeoutMS: 1000 });
 
 // sends:
-{ 
+{
   explain: { find: <collection>, 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.