In mongosh, UUID() creates a BSON UUID value. Use it directly for an _id or another UUID field. When copying a UUID from an online generator, wrap its text in UUID("...") so MongoDB stores a UUID value rather than a plain string.
Key takeaways
- Use UUID() in mongosh to generate an identifier locally in the shell.
- Modern BSON UUIDs use binary subtype 4; a UUID string is a different BSON type.
- Match the stored type when querying and use Extended JSON to preserve binary values.
For implementation context, continue with UUID v4, UUID v7, and UUID JSON. These pages cover the closest generator, comparison, validation or storage decisions without repeating this guide.
Generate a MongoDB UUID in mongosh
Create the value once and reuse it for both the insert and lookup. The _id field has a unique index in ordinary collections, so MongoDB rejects a duplicate _id. A UUID can also be stored in a separate field when you keep ObjectId as the primary key.
// Run in mongosh, not in a browser console.
const accountId = UUID();
db.accounts.insertOne({ _id: accountId, name: 'Sample account' });
db.accounts.findOne({ _id: accountId });Insert and query a UUID copied from this generator
Generate a fresh UUID v4 or v7, then pass the canonical text to UUID(). The fixed value below is only a format example; create a new identifier for each new record.
A query with a text string will not match a field stored as BSON binary. Wrap the lookup value in UUID() as well. For application code, use your MongoDB driver’s UUID or BSON Binary API rather than copying mongosh-specific functions into the application.
const externalId = UUID('4f8b1a9a-7c2d-4a59-9b9f-1c2d2f7e5a01');
db.fixtures.insertOne({ externalId, label: 'UUID example' });
db.fixtures.findOne({ externalId });UUID vs ObjectId in MongoDB
ObjectId is a 12-byte BSON identifier used by default for many MongoDB documents. A UUID is 16 bytes and can be shared with other databases and services that already use UUID identifiers. Both can identify a document; choose based on interoperability and how your application creates records.
A separate externalId field can preserve your existing ObjectId schema. If it must be unique, create a unique index deliberately and plan how existing documents will receive values before introducing the constraint.
| Representation | BSON storage | Typical use |
|---|---|---|
| ObjectId | 12-byte ObjectId | MongoDB-native document identity |
| UUID | 16-byte binary, subtype 4 | Shared identifiers across services |
| UUID text | String | Simple text integration with consistent formatting |
Export BSON UUIDs without losing their type
Plain JSON cannot express BSON binary types. Use MongoDB Extended JSON for exports that must preserve UUID storage. In mongosh, EJSON.stringify() serializes BSON values and EJSON.parse() reconstructs them.
Legacy drivers may use UUID binary subtype 3 and different byte orders. Check driver UUID representation settings before migrating data; changing text formatting alone does not convert a legacy binary representation.
const fixture = { externalId: UUID(), label: 'Export example' };
const json = EJSON.stringify(fixture);
const restored = EJSON.parse(json);
print(json);