4 Ways to Convert MongoDB BSON to JSON Format

This post was originally published in April, 2023 and was updated in April, 2025.

Binary Javascript Object Notation (BSON) is a bin­ary-en­coded seri­al­iz­a­tion of JSON documents. JSON is easier to understand as it is human-readable, but compared to BSON, it supports fewer data types. BSON has been extended to add some optional non-JSON-native data types, like dates and binary data.

MongoDB stores data efficiently using BSON (Binary JSON), both internally and in mongodump files. However, BSON isn’t human-readable. To inspect this data, you often need to convert BSON documents to JSON. While JSON supports fewer data types, its readability is essential for debugging and analysis.

This blog post demonstrates several practical methods to convert BSON to JSON, including using MongoDB’s own tools like bsondump and mongoexport, as well as scripting solutions with Python and Bash.

Convert BSON Files to JSON with bsondump

The bsondump converts BSON files into human-readable formats, including JSON. For example, bsondump is useful for reading the output files generated by mongodump. The bsondump tool is part of the MongoDB Database Tools package.

Run bsondump from the system command line:

It will create a JSON file ( collection.json) from an existing BSON document ( collection.bson), like the ones created after backing up your database.

Export MongoDB Data as JSON with mongoexport

mongoexport is a command-line tool that produces a JSON or CSV export of data stored in a MongoDB instance. The mongoexport tool is part of the MongoDB Database Tools package.

Run mongoexport from the command line:

To connect to a local MongoDB instance running on port 27017, you do not have to specify the host or port. If otherwise needed, check the Connect to a MongoDB Instance section in the documentation for more information.

The --pretty  option will pretty format the content of the JSON file.

Convert BSON to JSON using Python (PyMongo)

If you’re a Python developer, there are two ways for reading a BSON document and converting it to JSON.

1. Using the bson module from PyMongo

This is what the script is doing:

1. 1. Import the decode_all  and dumpsmethods from the bsonmodule.
   2. Open the file to read the content and decode the data.
   3. Create a JSON file, and write the JSON document created from the data of the BSON file.

The script works with BSON files generated by mongodump. Before running the script, you must install PyMongo: pip install pymongo.

2. Connecting to the database and querying the data with PyMongo, the Python driver for MongoDB.

This is what the script is doing:

1. 1. Import the method MongoClient from the pymongo library, and the dumps method from the bson module.
   2. Establish the connection to the database.
   3. Set the database (e.g., company ) and the collection (e.g., employees) you want to query.
   4. Retrieve the documents in the collection with the find()  method and create a list with the result. If you don’t pass any parameter to this method, the result will be similar to SELECT *  in MySQL.
   5. Create a JSON object by calling the dumps method. The indent = 2 parameter will tell dumps() to pretty format the JSON object.
   6. Write the content of the json_data  variable to the data.json file.

Before running the script, you must install PyMongo: pip install pymongo.

Batch Convert BSON Files to JSON with Bash

I asked the AI at phind.com to tell me how to convert a BSON file to JSON, and one of the solutions that it showed me was to create a Bash script in the directory where the BSON files are.

The script lists all the BSON files in the present directory and saves the result in an array, then loops through the array and converts every BSON file to JSON files. The script uses bsondump.

To run the script

1. Add execution permission to the script: chmod +x bson_to_json.sh.
2. Execute this command in the command line:

Conclusion

When you need to view the contents of MongoDB’s binary data format, several effective methods exist to convert BSON documents to human-readable JSON. For converting .bson files (like those from mongodump), bsondump is the dedicated tool. To export data directly from a live database as JSON, mongoexport is the standard utility. For developers needing programmatic conversion or data manipulation, Python with the PyMongo library offers flexibility, and simple Bash scripts can automate batch file conversions using bsondump. Choosing the right method depends on whether you’re working with files or a live database and your scripting preferences.

 

Ready to leave MongoDB, Inc. behind? Percona is the cost-effective, enterprise-grade alternative businesses trust.

FAQs: Converting BSON to JSON

Q1: What is the main difference between BSON and JSON?
A: JSON (JavaScript Object Notation) is a human-readable text format. BSON (Binary JSON) is a binary-encoded serialization format used by MongoDB for efficient storage and network transfer; it supports more data types than JSON but is not human-readable.

Q2: How can I view the contents of a .bson file from mongodump?
A: The easiest way is to use the bsondump command-line tool, which is part of the MongoDB Database Tools package. It directly converts the .bson file into a readable JSON format (e.g., bsondump file.bson --outFile=file.json).

Q3: Can mongoexport convert a .bson file to JSON?
A: No, mongoexport does not convert existing .bson files. It connects to a running MongoDB database instance and exports data directly from a collection into a JSON or CSV file.