diff --git a/source/data-formats.txt b/source/data-formats.txt index 5c518383..ec4a7064 100644 --- a/source/data-formats.txt +++ b/source/data-formats.txt @@ -21,6 +21,7 @@ Specialized Data Formats :titlesonly: :maxdepth: 1 + BSON Custom Types Dates & Times UUIDs @@ -33,6 +34,7 @@ You can use several types of specialized data formats in your {+driver-short+} application. To learn how to work with these data formats, see the following sections: +- Learn how to work with BSON documents in the :ref:`pymongo-bson` guide. - Learn how to encode and decode custom types in the :ref:`pymongo-custom-types` guide. - Learn how to work with Python ``datetime`` objects in {+driver-short+} in the :ref:`pymongo-dates-times` guide. diff --git a/source/data-formats/bson.txt b/source/data-formats/bson.txt new file mode 100644 index 00000000..d0a36209 --- /dev/null +++ b/source/data-formats/bson.txt @@ -0,0 +1,124 @@ +.. _pymongo-bson: + +==== +BSON +==== + +.. default-domain:: mongodb + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +Overview +-------- + +In this guide, you can learn how to create BSON documents, read BSON from a file, +and write BSON to a file by using {+driver-short+}. + +**BSON**, or Binary JSON, is the data format that MongoDB uses to organize +and store data. This data format includes all JSON data structure types and +adds support for types including dates, different size integers, ObjectIds, and +binary data. You can use BSON documents in your {+language+} application by including the +`bson <{+api-root+}bson/index.html>`__ package. For a complete list of supported types, see the +:manual:`BSON Types ` server manual page. + +The code samples in this guide use the following BSON document as an example: + +.. code-block:: none + + { + "address" : { + "street" : "Pizza St", + "zipcode" : "10003" + }, + "coord" : [-73.982419, 41.579505] + "cuisine" : "Pizza", + "name" : "Mongo's Pizza" + } + +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 +represents the preceding sample BSON document: + +.. code-block:: python + + document = { + "address": { + "street": "Pizza St", + "zipcode": "10003" + }, + "coord": [-73.982419, 41.579505], + "cuisine": "Pizza", + "name": "Mongo's Pizza" + } + +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 +BSON document: + +1. Adds a new field, ``restaurant_id``, with the value ``12345`` +#. Removes the ``cuisine`` field +#. Sets the value of the ``name`` field to ``"Mongo's Pizza Place"`` + +.. code-block:: python + + document["restaurant_id"] = 12345 + del document["cuisine"] + document["name"] = "Mongo's Pizza Place" + +Write BSON to a File +-------------------- + +To write BSON data to a file, open a file stream in write-binary mode on the output file. +Then, write each document to the output file. Ensure that documents are encoded in BSON +format by using the ``bson.encode()`` method. + +The following example writes the sample BSON document to ``file.bson``: + +.. code-block:: python + + with open("file.bson", "w") as file: + file.write(bson.encode(document)) + +Read BSON from a File +--------------------- + +To read BSON documents from a file, open a file stream in read-binary mode on the input +file. Then, decode the documents from BSON format as you read them by using the ``bson.decode()`` +method. + +The following example reads the sample BSON document from ``file.bson``: + +.. io-code-block:: + :copyable: true + + .. input:: + :language: python + + with open("file.bson", "rb") as file: + data = file.read() + document = bson.decode(data) + print(document) + + .. output:: + :visible: false + + {"address": {"street": "Pizza St", "zipcode": "10003"}, "coord": [-73.982419, 41.579505], "cuisine": "Pizza", "name": "Mongo's Pizza"} + +API Documentation +----------------- + +To learn more about any of the methods or types discussed in this +guide, see the `bson <{+api-root+}bson/index.html>`__ API documentation. \ No newline at end of file