Skip to content
Studio 3T - The professional GUI, IDE and client for MongoDB
  • Tools
    • Aggregation Editor
    • IntelliShell
    • Visual Query Builder
    • Export Wizard
    • Import Wizard
    • Query Code
    • SQL Query
    • Connect
    • Schema Explorer
    • Compare
    • SQL ⇔ MongoDB Migration
    • Data Masking
    • Task Scheduler
    • Reschema
    • AI Helper
    • Team Sharing
    • Index Manager
    • More Tools and Features
  • Solutions
  • Resources
    • Knowledge Base
    • MongoDB Tutorials & Courses
    • Tool/Feature Documentation
    • Blog
    • Community
    • Testimonials
    • Whitepapers
    • Reports
  • Contact us
    • Contact
    • Sales Support
    • Feedback and Support
    • Careers
    • About Us
  • Store
    • Buy Now
    • Preferred Resellers
    • Team Pricing
  • Download
  • My 3T
search

Studio 3T® Knowledge Base

  • Documentation
  • Tutorials
  • Workshops
Take the fastest route to learning MongoDB. Cover the basics in two hours with MongoDB 101, no registration required.
Start the free course

MongoDB Best Practices for UUID Data

Posted on: 20/07/2018 (last updated: 18/02/2022) by Tomasz Naumowicz

In this post, we’ll take a look at how MongoDB handles UUID data.

We’ll also go through a few complex cases, from which we can glean best practices when working with UUID data on our MongoDB GUI, Studio 3T.

Download our MongoDB GUI now, in case you haven’t yet.

MongoDB UUID Data

MongoDB and MongoDB drivers come with built-in support for the UUID data type.

It’s very easy and convenient to start using UUID immediately, without having to review the BSON specification. In most cases you’ll most likely be fine. There are some scenarios however, where you might run into unexpected issues that are very difficult to debug.

As soon as you go multi-language with your deployments you might discover that your applications no longer work as expected, e.g. you might no longer be able to match orders to customers.

It’s also very likely that your data gets corrupted over time and it will be very difficult to recover from such a disaster without having to restore your backups (you do backups on a regular basis, don’t you?).

We’ll take a closer look at scenarios where working with UUID data in MongoDB might become more complex. We’ll make you aware of those configurations and provide you with a set of best practices to follow.

What is a UUID?

A Universally Unique IDentifier (UUID) is a unique number used as an identifier in computer software.

Sometimes the term Globally Unique IDentifier (GUID) is used to describe it.

A GUID is one of many implementations of the UUID standard.

UUIDs are 128-bit values and are usually displayed as 32 hexadecimal digits separated by hyphens, for example:

176BF052-4ECB-4E1D-B48F-F3523F7F277F

(The example above is a random Version 4 UUID generated by Studio 3T)

MongoDB and UUID support

MongoDB has built-in support for the UUID data type and most of the MongoDB drivers support UUID natively.

MongoDB itself stores UUIDs as Binary fields and when such Binary fields are accessed from software,

MongoDB drivers usually convert their value as found in the database to language-specific UUID or GUID objects.

For example, when you read a UUID from a MongoDB database using the Java driver, an object of type java.util.UUID will be returned. The C# driver on the other hand will return a struct of type System.GUID.

This makes it very convenient and easy to work with the UUID data type from your application code.

Complex UUID scenarios

You might run into problems when working with UUIDs in multi-platform/multi-language environments because accessing your database from different programming languages using different MongoDB drivers might not always be safe, as we will demonstrate below.

Furthermore, you should be careful when working with UUID data types in third-party MongoDB management software because only a few MongoDB tools take due care in handling UUID data types.

MongoDB drivers usually convert UUIDs between their Binary database representation and the language specific UUID data type. Initially the encoding method was platform specific and wasn’t consistently implemented across different MongoDB drivers.

Example

An example UUID created and displayed in a Java application would be shown as follows:

00010203-0405-4007-8009-0A0B0C0D0E0F

The MongoDB Java driver (version 2.9.1 in this example) will convert it to a Binary database representation and store it with the following byte order:

07 40 05 04 03 02 01 00 0F 0E 0D 0C 0B 0A 09 80

However, the C# driver used to access the same field will return and display the following:

04054007-0203-0001-0F0E-0D0C0B0A0980

You’ll notice the representation of the same UUID differs depending on the platform used to access it.

As long as you’re not editing those UUIDs on both ends, you shouldn’t experience any serious problems (besides confusion when analysing your data). However, if one day you do edit a UUID, you’ll very likely run into issues that can be very difficult to locate and debug because you’ll essentially be dealing with scrambled data.

Binary subtypes 0x03 and 0x04

While reviewing the BSON specification you’ll notice two Binary subtypes assigned to the UUID data type:

UUID BSON Specification

Originally, only the 0x03 subtype was used to annotate UUIDs. To address the portability issues in multi-platform environments that arose from the language specific UUID implementations, the MongoDB designers later introduced the new 0x04 subtype.

The byte order used to store UUIDs as Binary fields with the 0x04 subtype is now consistently implemented across all MongoDB drivers and the legacy 0x03 subtype is being supported for legacy data only.

Using the Binary 0x04 subtype when working with UUIDs guarantees that you’ll be able to access your data from any platform and any programming language without these compatibility issues.

MongoDB best practices

1. Make sure you always know what the UUID subtype is that your applications are using

You can find out the subtype in use by looking at the JSON representation of your existing data (e.g. in the mongo shell):

BinData(3,"B0AFBAMCAQAPDg0MCwoJgA==")
the 3 stands for a UUID stored as Binary field with the legacy 0x03 subtype
BinData(4,”SDcTgfx0SOq0Cl7DMRAzDQ==”)
the 4 stands for a UUID stored as a Binary field with the 0x04 subtype

You can also use our MongoDB GUI which has support for legacy UUIDs to access this information.

Studio 3T annotates regular UUIDs as Binary - UUID and for legacy UUIDs it lets you know which encoding it currently uses (e.g. Java, C# or none):

2. Configure your drivers to work with 0x04 subtype for new deployments

MongoDB drivers usually store UUIDs as Binary fields with the legacy 0x03 subtype assigned by default. This configuration can be changed:

C# / .NET

You can override the driver’s default settings and configure it to use the Binary 0x04 subtype by modifying the value of BsonDefaults.GuidRepresentation:

MongoDefaults.GuidRepresentation = MongoDB.Bson.GuidRepresentation.Standard;

You can also modify GuidRepresentation at the server, database and collection level.

Python

You can configure the behavior of your Python driver. Read more about the uuid_subtype attribute here.

Java

Support for UUID configuration was added in the 3.0 release of the MongoDB driver (JAVA-403). With pre 3.0 drivers you will have to perform the conversion yourself:

/**
 * Convert a UUID object to a Binary with a subtype 0x04
 */
public static Binary toStandardBinaryUUID(java.util.UUID uuid) {
    long msb = uuid.getMostSignificantBits();
    long lsb = uuid.getLeastSignificantBits();

    byte[] uuidBytes = new byte[16];

    for (int i = 15; i >= 8; i--) {
        uuidBytes[i] = (byte) (lsb & 0xFFL);
        lsb >>= 8;
    }
    
    for (int i = 7; i >= 0; i--) {
        uuidBytes[i] = (byte) (msb & 0xFFL);
        msb >>= 8;
    }

    return new Binary((byte) 0x04, uuidBytes);
}

/**
 * Convert a Binary with a subtype 0x04 to a UUID object
 * Please note: the subtype is not being checked.
 */
public static UUID fromStandardBinaryUUID(Binary binary) {
    long msb = 0;
    long lsb = 0;
    byte[] uuidBytes = binary.getData();

    for (int i = 8; i < 16; i++) {
        lsb <<= 8;
        lsb |= uuidBytes[i] & 0xFFL;
    }

    for (int i = 0; i < 8; i++) {
        msb <<= 8;
        msb |= uuidBytes[i] & 0xFFL;
    }

    return new UUID(msb, lsb);
}

3. Configure your MongoDB GUI to handle legacy UUIDs with 0x03 subtype

Studio 3T has built-in support for both, the 0x03 and the 0x04 subtype. You can configure the behavior in the Preferences dialog’s Legacy UUID tab and select from the following options:

  • Legacy .NET / C# Encoding
    • The default encoding used by the .NET/C# driver. Studio 3T will read, store and display the UUID the same way a .NET application would do
  • Legacy Java Encoding
    • The default encoding used by the Java driver. Studio 3T will read, store and display the UUID the same way a Java application would do
  • Legacy Python Encoding
    • The default encoding used by the Python driver. Studio 3T will read, store and display the UUID the same way a Python application would do
  • No Encoding / Raw Data
    • No conversion is being performed. The data is read, stored and displayed in the existing byte order

Summary

Make sure your applications don’t suffer from unnecessary portability issues when working with the UUID data type and avoid the legacy Binary 0x03 subtype whenever possible. If you can’t migrate your existing deployment to the new Binary 0x04 subtype, remember to configure your MongoDB tools to the correct encoding for the legacy Binary 0x03 subtype.

If you enjoyed this article, read more about workarounds to corner cases when querying and updating MongoDB arrays or how to query MongoDB secondary replica set members, among other tips and tricks.


How helpful was this article?
This article was hideous
This article was bad
This article was ok
This article was good
This article was great
Thank you for your feedback!

About The Author

Tomasz Naumowicz

Article navigation

Related articles

  • MongoDB Database Testing: A Detailed Walkthrough of Best Practices
  • The Best Data Masking Tools for MongoDB
  • 9 Best MongoDB Tutorials & Courses (Free & Paid)
  • Best MongoDB Tools (Updated: April 2021)
  • 3 Best MongoDB Aggregation Pipeline Builders

Studio 3T

MongoDB Enterprise Certified Technology PartnerSince 2014, 3T has been helping thousands of MongoDB developers and administrators with their everyday jobs by providing the finest MongoDB tools on the market. We guarantee the best compatibility with current and legacy releases of MongoDB, continue to deliver new features with every new software release, and provide high quality support.

Find us on FacebookFind us on TwitterFind us on YouTubeFind us on LinkedIn

Education

  • Free MongoDB Tutorials
  • Connect to MongoDB
  • Connect to MongoDB Atlas
  • Import Data to MongoDB
  • Export MongoDB Data
  • Build Aggregation Queries
  • Query MongoDB with SQL
  • Migrate from SQL to MongoDB

Resources

  • Feedback and Support
  • Sales Support
  • Knowledge Base
  • FAQ
  • Reports
  • White Papers
  • Testimonials
  • Discounts

Company

  • About Us
  • Blog
  • Careers
  • Legal
  • Press
  • Privacy Policy
  • EULA

© 2023 3T Software Labs Ltd. All rights reserved.

  • Privacy Policy
  • Cookie settings
  • Impressum

We value your privacy

With your consent, we and third-party providers use cookies and similar technologies on our website to analyse your use of our site for market research or advertising purposes ("analytics and marketing") and to provide you with additional functions (“functional”). This may result in the creation of pseudonymous usage profiles and the transfer of personal data to third countries, including the USA, which may have no adequate level of protection for the processing of personal data.

By clicking “Accept all”, you consent to the storage of cookies and the processing of personal data for these purposes, including any transfers to third countries. By clicking on “Decline all”, you do not give your consent and we will only store cookies that are necessary for our website. You can customize the cookies we store on your device or change your selection at any time - thus also revoking your consent with effect for the future - under “Manage Cookies”, or “Cookie Settings” at the bottom of the page. You can find further information in our Privacy Policy.
Accept all
Decline all
Manage cookies
✕

Privacy Preference Center

With your consent, we and third-party providers use cookies and similar technologies on our website to analyse your use of our site for market research or advertising purposes ("analytics and marketing") and to provide you with additional functions (“functional”). This may result in the creation of pseudonymous usage profiles and the transfer of personal data to third countries, including the USA, which may have no adequate level of protection for the processing of personal data. Please choose for which purposes you wish to give us your consent and store your preferences by clicking on “Accept selected”. You can find further information in our Privacy Policy.

Accept all cookies

Manage consent preferences

Essential cookies are strictly necessary to provide an online service such as our website or a service on our website which you have requested. The website or service will not work without them.

Performance cookies allow us to collect information such as number of visits and sources of traffic. This information is used in aggregate form to help us understand how our websites are being used, allowing us to improve both our website’s performance and your experience.

Google Analytics

Google Ads

Bing Ads

Facebook

LinkedIn

Quora

Hotjar

Reddit

Functional cookies collect information about your preferences and choices and make using the website a lot easier and more relevant. Without these cookies, some of the site functionality may not work as intended.

HubSpot

Social media cookies are cookies used to share user behaviour information with a third-party social media platform. They may consequently effect how social media sites present you with information in the future.

Accept selected
✕