DOCSP-47282: RawBSONDocument information

source/data-formats/bson.txt

@@ -117,6 +117,47 @@ The following example reads the sample BSON document from ``file.bson``:
 
       {"address": {"street": "Pizza St", "zipcode": "10003"}, "coord": [-73.982419, 41.579505], "cuisine": "Pizza", "name": "Mongo's Pizza"}
 
+Work with Raw BSON Data
+-----------------------
+
+{+driver-short+} supports the usage of raw BSON documents. The following list contains
+some situations that might require using raw BSON documents:
+
+- Moving a document between databases or collections
+- Writing binary data to a disk
+- Bypassing the performance overhead of converting to and from {+language+} dictionaries
+
+The ``RawBSONDocument`` class is a representation of a BSON document that provides
+access to the underlying raw BSON bytes. To use ``RawBSONDocument`` objects to represent
+documents in your collection, set the ``document_class`` parameter of the ``MongoClient``
+constructor to ``RawBSONDocument``.
+
+The following example configures a ``MongoClient`` object to use ``RawBSONDocument`` objects
+to model the collection, then retrieves the sample document from the preceding examples:
+
+.. io-code-block::
+   :copyable: true
+
+   .. input::
+      :language: python
+
+      from bson.raw_bson import RawBSONDocument
+
+      client = pymongo.MongoClient("<connection URI>", document_class=RawBSONDocument)
+      collection = client.sample_restaurants.restaurants
+      raw_doc = collection.find_one({"name": "Mongo's Pizza"})
+      print(type(raw_doc))
+
+   .. output::
+      :visible: false
+
+      <class 'bson.raw_bson.RawBSONDocument'>
+
+.. note::
+
+   ``RawBSONDocument`` objects are read-only. To modify a ``RawBSONDocument``, you must
+   first convert it to a {+language+} dictionary.
+
 API Documentation
 -----------------