diff --git a/source/data-formats/bson.txt b/source/data-formats/bson.txt index d0a36209..3a91f882 100644 --- a/source/data-formats/bson.txt +++ b/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``. + +.. note:: + + ``RawBSONDocument`` objects are read-only. To modify a ``RawBSONDocument``, you must + first convert it to a {+language+} dictionary. + +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("", document_class=RawBSONDocument) + collection = client.sample_restaurants.restaurants + raw_doc = collection.find_one({"name": "Mongo's Pizza"}) + print(type(raw_doc)) + + .. output:: + :visible: false + + + API Documentation -----------------