# `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, codec_options=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 (bytes | memoryview) – the BSON bytes that compose this document

    - codec_options (Optional[CodecOptions[RawBSONDocument]]) – 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()

    Lazily decode and iterate elements in this document.

    Return type:

      ItemsView[str, Any]

  property raw: bytes | memoryview

    The raw BSON bytes composing this document.