diff --git a/source/data-formats/bson.txt b/source/data-formats/bson.txt index 75e71771..d81d0070 100644 --- a/source/data-formats/bson.txt +++ b/source/data-formats/bson.txt @@ -25,6 +25,39 @@ binary data. You can use BSON documents in your {+language+} application by incl `bson <{+api-root+}bson/index.html>`__ package. For a complete list of supported types, see the :manual:`BSON Types ` server manual page. +BSON documents are stored in MongoDB collections in binary format, while {+driver-short+} +represents BSON documents as {+language+} dictionaries. {+driver-short+} automatically +converts {+language+} dictionaries into BSON documents when inserting them into a collection. +Likewise, when you retrieve a document from a collection, {+driver-short+} converts the BSON +document back into a {+language+} dictionary. + +The following example shows a document in both dictionary and BSON formats. Use the +:guilabel:`Dictionary` or :guilabel:`BSON` tab to see the corresponding format: + +.. tabs:: + + .. tab:: Dictionary + :tabid: dict + + .. code-block:: python + + {"hello": "world"} + + .. tab:: BSON + :tabid: bson + + .. code-block:: none + + \x16\x00\x00\x00 # total document size + \x02 # 0x02 = type String + hello\x00 # field name + \x06\x00\x00\x00world\x00 # field value + \x00 # 0x00 = type EOO ("end of object") + + +Sample Data +~~~~~~~~~~~ + The code samples in this guide use the following BSON document as an example: .. code-block:: none @@ -43,10 +76,7 @@ Create a BSON Document ---------------------- You can create a BSON document by using the same notation you use to create a -dictionary in {+language+}. {+driver-short+} automatically converts {+language+} dictionaries -into BSON documents when inserting them into a collection. - -The following example creates a BSON document that +dictionary in {+language+}. The following example creates a BSON document that represents the preceding sample BSON document: .. code-block:: python @@ -65,7 +95,7 @@ Change a BSON Document ---------------------- You can modify the contents of a BSON document by using the same notation you use to modify -a dictionary in {+language+}. The following example makes three changes to the previous +a dictionary in {+language+}. The following example makes three changes to the sample BSON document: 1. Adds a new field, ``restaurant_id``, with the value ``12345``