From 3ecd0f2e2107c6bab00c750e0f9d324485b31176 Mon Sep 17 00:00:00 2001 From: Michael Morisi Date: Fri, 14 Mar 2025 13:56:40 -0400 Subject: [PATCH 1/2] DOCSP-48322: BSON tech feedback --- source/data-formats/bson.txt | 40 +++++++++++++++++++++++++++++++----- 1 file changed, 35 insertions(+), 5 deletions(-) diff --git a/source/data-formats/bson.txt b/source/data-formats/bson.txt index 75e71771..dd7d18b1 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`` From bdd1c688f1efe2337b7c538d9f8a6f360bb462e7 Mon Sep 17 00:00:00 2001 From: Michael Morisi Date: Fri, 14 Mar 2025 14:03:43 -0400 Subject: [PATCH 2/2] Fix --- source/data-formats/bson.txt | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/source/data-formats/bson.txt b/source/data-formats/bson.txt index dd7d18b1..d81d0070 100644 --- a/source/data-formats/bson.txt +++ b/source/data-formats/bson.txt @@ -48,11 +48,11 @@ The following example shows a document in both dictionary and BSON formats. Use .. 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') + \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