raw_bson – Tools for representing raw BSON documents.

Tools for representing raw BSON documents.

Inserting and Retrieving RawBSONDocuments

Example: Moving a document between different databases/collections

>>> import bson
>>> from pymongo import MongoClient
>>> from bson.raw_bson import RawBSONDocument
>>> client = MongoClient(document_class=RawBSONDocument)
>>> client.drop_database('db')
>>> client.drop_database('replica_db')
>>> db = client.db
>>> result = db.test.insert_many([{'_id': 1, 'a': 1},
...                               {'_id': 2, 'b': 1},
...                               {'_id': 3, 'c': 1},
...                               {'_id': 4, 'd': 1}])
>>> replica_db = client.replica_db
>>> for doc in db.test.find():
...    print(f"raw document: {doc.raw}")
...    print(f"decoded document: {bson.decode(doc.raw)}")
...    result = replica_db.test.insert_one(doc)
raw document: b'...'
decoded document: {'_id': 1, 'a': 1}
raw document: b'...'
decoded document: {'_id': 2, 'b': 1}
raw document: b'...'
decoded document: {'_id': 3, 'c': 1}
raw document: b'...'
decoded document: {'_id': 4, 'd': 1}

For use cases like moving documents across different databases or writing binary blobs to disk, using raw BSON documents provides better speed and avoids the overhead of decoding or encoding BSON.

class bson.raw_bson.RawBSONDocument(bson_bytes: bytes, codec_options: Optional[bson.codec_options.CodecOptions] = None)

Create a new RawBSONDocument

RawBSONDocument is a representation of a BSON document that provides access to the underlying raw BSON bytes. Only when a field is accessed or modified within the document does RawBSONDocument decode its bytes.

RawBSONDocument implements the Mapping abstract base class from the standard library so it can be used like a read-only dict:

>>> from bson import encode
>>> raw_doc = RawBSONDocument(encode({'_id': 'my_doc'}))
>>> raw_doc.raw
b'...'
>>> raw_doc['_id']
'my_doc'
Parameters

  • bson_bytes: the BSON bytes that compose this document

  • codec_options (optional): An instance of CodecOptions whose document_class must be RawBSONDocument. The default is DEFAULT_RAW_BSON_OPTIONS.

Changed in version 3.8: RawBSONDocument now validates that the bson_bytes passed in represent a single bson document.

Changed in version 3.5: If a CodecOptions is passed in, its document_class must be RawBSONDocument.

items() → ItemsView[str, Any]

Lazily decode and iterate elements in this document.

property raw: bytes

The raw BSON bytes composing this document.