Explore Developer Center's New Chatbot! MongoDB AI Chatbot can be accessed at the top of your navigation to answer all your MongoDB questions.

MongoDB Developer
MongoDB
plus
Sign in to follow topics
MongoDB Developer Centerchevron-right
Developer Topicschevron-right
Productschevron-right
MongoDBchevron-right

Quick Start: BSON Data Types - Decimal128

Ken W. Alger2 min read • Published Jan 31, 2022 • Updated Sep 23, 2022
MongoDB
Facebook Icontwitter iconlinkedin icon
Rate this quickstart
star-empty
star-empty
star-empty
star-empty
star-empty
BSON Quickstart badge
Think back to when you were first introduced to the concept of decimals in numerical calculations. Doing math problems along the lines of 3.231 / 1.28 caused problems when starting out because 1.28 doesn't go into 3.231 evenly. This causes a long string of numbers to be created to provide a more precise answer. In programming languages, we must choose which number format is correct depending on the amount of precision we need. When one needs high precision when working with BSON data types, the decimal128 is the one to use.
As the name suggests, decimal128 provides 128 bits of decimal representation for storing really big (or really small) numbers when rounding decimals exactly is important. Decimal128 supports 34 decimal digits of precision, or significand along with an exponent range of -6143 to +6144. The significand is not normalized in the decimal128 standard allowing for multiple possible representations: 10 x 10^-1 = 1 x 10^0 = .1 x 10^1 = .01 x 10^2 and so on. Having the ability to store maximum and minimum values in the order of 10^6144 and 10^-6143, respectively, allows for a lot of precision.
Decimal128 Precision Details

Why & Where to Use

Sometimes when doing mathematical calculations in a programmatic way, results are unexpected. For example in Node.js:
1> 0.1
20.1
3> 0.2
40.2
5> 0.1 * 0.2
60.020000000000000004
7> 0.1 + 0.1
80.010000000000000002
This issue is not unique to Node.js, in Java:
1class Main {
2 public static void main(String[] args) {
3 System.out.println("0.1 * 0.2:");
4 System.out.println(0.1 * 0.2);
5 }
6}
Produces an output of:
10.1 * 0.2:
20.020000000000000004
The same computations in Python, Ruby, Rust, and others produce the same results. What's going on here? Are these languages just bad at math? Not really, binary floating-point numbers just aren't great at representing base 10 values. For example, the 0.1 used in the above examples is represented in binary as 0.0001100110011001101.
For many situations, this isn't a huge issue. However, in monetary applications precision is very important. Who remembers the half-cent issue from Superman III? When precision and accuracy are important for computations, decimal128 should be the data type of choice.

How to Use

In MongoDB, storing data in decimal128 format is relatively straight forward with the NumberDecimal() constructor:
1NumberDecimal("9823.1297")
Passing in the decimal value as a string, the value gets stored in the database as:
1NumberDecimal("9823.1297")
If values are passed in as double values:
1NumberDecimal(1234.99999999999)
Loss of precision can occur in the database:
1NumberDecimal("1234.50000000000")
Another consideration, beyond simply the usage in MongoDB, is the usage and support your programming has for decimal128. Many languages don't natively support this feature and will require a plugin or additional package to get the functionality. Some examples...
Python: The decimal.Decimal module can be used for floating-point arithmetic.
Java: The Java BigDecimal class provides support for decimal128 numbers.
Node.js: There are several packages that provide support, such as js-big-decimal or node.js bigdecimal available on npm.

Wrap Up

Get started exploring BSON types, like decimal128, with MongoDB Atlas today!
The decimal128 field came about in August 2009 as part of the IEEE 754-2008 revision of floating points. MongoDB 3.4 is when support for decimal128 first appeared and to use the decimal data type with MongoDB, you'll want to make sure you use a driver version that supports this great feature. Decimal128 is great for huge (or very tiny) numbers and for when precision in those numbers is important.

Facebook Icontwitter iconlinkedin icon
Rate this quickstart
star-empty
star-empty
star-empty
star-empty
star-empty
Related
Tutorial

Secure your API with Spring Data MongoDB and Microsoft EntraID


Apr 02, 2024 | 8 min read
Tutorial

How to Deploy a Flask Application With MongoDB on Fly.io


Dec 02, 2024 | 5 min read
Article

Streamlining Java Application Development With MongoDB: A Comprehensive Guide to Using Testcontainers


Jul 22, 2024 | 7 min read
Quickstart

Reacting to Database Changes with MongoDB Change Streams and Go


Feb 03, 2023 | 5 min read
Table of Contents
  • Why & Where to Use