DOCSP-47282: RawBSONDocument information

source/data-formats/bson.txt

@@ -117,6 +117,36 @@ 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 blobs to a disk
+- Bypassing the performance overhead of converting to and from {+language+} dictionaries
+
+You can use the ``RawBSONDocument`` class to represent raw BSON documents. 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``,
+then retrieves the sample document:
+
+.. code-block:: python
+
+      from bson.raw_bson import RawBSONDocument
+
+      client = pymongo.MongoClient("<connection URI>", document_class=RawBSONDocument)
+      collection = client["<database name>"]["<collection name>"]
+      raw_doc = collection.find_one({"name": "Mongo's Pizza"})
+
+.. note::
+
+   ``RawBSONDocument`` objects are read-only. To modify a ``RawBSONDocument``, you must
+   first convert it to a {+language+} dictionary.
+
 API Documentation
 -----------------