MongoDB Shell or Compass query with a GUID

GUID with MongoDB
5 1 vote
Article Rating

Just a small one for today. Have you ever tried to query MongoDB with a GUID? Well I did and it can be confusing!


Some time ago I created a project for storing product prices but for multiple markets around the world. Markets would be a dynamic thing, meaning different ones being added every once and a while, and old ones potentially removed. Since the data to be stored were fairly simple, I was lead to a design featuring one documentDB per market. The document-oriented database selected was MongoDB, but I always had in mind a future move to Azure Cosmos DB, so avoiding vendor lock was a requirement. That thought alone and the fact that a unique ID through out all databases for each price would be a nice to have, made me decide for a GUID instead of MongoBD’s ObjectId().

ObjectIds are small, likely unique, fast to generate, and ordered. ObjectId values are 12 bytes in length, consisting of:

  • 4-byte timestamp value, representing the ObjectId’s creation, measured in seconds since the Unix epoch
  • 5-byte random value generated once per process. This random value is unique to the machine and process.
  • 3-byte incrementing counter, initialized to a random value

The schema of the document is not very important other than the fact that the ID should be of type GUID:

Nevertheless, the schema above gave room for some beautiful data like the following image, with some databases and collections ending up having millions of data located in an availability zone probably near you!

MongoDB Compass GUID
The capture above is showing a part of MongoDB compass connected to a beta database with partially real but old data, located locally. Far from the previous useless sentence though, mind the blue square because this is how MongoDB stores a GUID. The value you see is actually a base64 encoded string of the GUID value.

And everything was cool for years, up until I had to manually debug a situation where I had to connect directly to MongoDB to search for a document based on a GUID I knew. No matter how many times I attempted to convert the GUID using various online services to its base64 equivalent, I always failed because these services were converting the GUID to base64 as string!

And there’s your problem! Encoding a GUID’s bytes is different than encoding GUID’s representative string value.

Worth mentioning here that we were working on this problem with Dean Herringer and he was the first to notice the problem.


Follows a C# solution which is simple enough, but of course requires to at least copy-paste the code to a project and run it:

And here is a way to decode a base64 string that contains GUID bytes:

Finally, if you just need it now without writing code use a Blazor WebAssembly app I made just for this: It’s open source and the code is available in Github.

And if it is a bit slow on startup, be patient! Dev/Test Service Plan doesn’t allow Always On!

5 1 vote
Article Rating
Notify of
Newest Most Voted
Inline Feedbacks
View all comments
Tomas Virag

Thank you for the post.

I would just add small thing. It is best to avoid using binary type 3. It is important to mention that every mongo db driver will decode binary type 3 to own UUID representation. Simple to say, if I code my UUID to mongo binary wit c# driver, decoding it in any other one will give me different result. That can bring problems between applications with different language code base.