voyageai-cli
Version:
CLI for Voyage AI embeddings, reranking, and MongoDB Atlas Vector Search
287 lines (220 loc) • 8.02 kB
Markdown
# BSON Data Types
MongoDB stores data in BSON (Binary JSON), a binary-encoded serialization format that
extends JSON with additional data types. Understanding BSON types is essential for
schema design, validation, and querying.
## Core BSON Types
| Type | Number | Alias | Description |
|------------------|--------|-------------|------------------------------------------|
| Double | 1 | `double` | 64-bit floating point |
| String | 2 | `string` | UTF-8 encoded string |
| Object | 3 | `object` | Embedded document |
| Array | 4 | `array` | Ordered list of values |
| Binary Data | 5 | `binData` | Binary content (images, files, etc.) |
| ObjectId | 7 | `objectId` | 12-byte unique identifier |
| Boolean | 8 | `bool` | `true` or `false` |
| Date | 9 | `date` | 64-bit integer (ms since Unix epoch) |
| Null | 10 | `null` | Null value |
| Regular Expr. | 11 | `regex` | Regular expression with options |
| 32-bit Integer | 16 | `int` | 32-bit signed integer |
| Timestamp | 17 | `timestamp` | Internal MongoDB replication timestamp |
| 64-bit Integer | 18 | `long` | 64-bit signed integer |
| Decimal128 | 19 | `decimal` | 128-bit high-precision decimal |
## String
UTF-8 strings are the most common BSON type.
```javascript
db.products.insertOne({
name: "MongoDB in Action",
description: "A comprehensive guide to MongoDB",
sku: "MDB-2024-001"
})
// Query with regex on string fields
db.products.find({ name: /mongodb/i })
// String comparison
db.products.find({ sku: { $gte: "MDB-2024", $lt: "MDB-2025" } })
```
## Numeric Types
MongoDB distinguishes between several numeric types. In mongosh, numbers
default to Double unless you use explicit constructors.
```javascript
db.metrics.insertOne({
count: NumberInt(42), // Int32 - 32-bit integer
bigCount: NumberLong("900719925"), // Int64 - 64-bit integer
score: 3.14, // Double - 64-bit float (default)
price: NumberDecimal("29.99") // Decimal128 - exact precision
})
// Use Decimal128 for financial data to avoid floating-point errors
db.accounts.insertOne({
balance: NumberDecimal("10452.37"),
interestRate: NumberDecimal("0.0425")
})
```
## Boolean
Standard true/false values.
```javascript
db.users.insertOne({
email: "ada@example.com",
isActive: true,
emailVerified: false
})
db.users.find({ isActive: true, emailVerified: false })
```
## Date
Dates are stored as 64-bit integers representing milliseconds since the Unix epoch.
```javascript
db.events.insertOne({
title: "MongoDB World",
startDate: new Date("2025-06-10T09:00:00Z"),
endDate: new Date("2025-06-12T17:00:00Z"),
createdAt: new Date() // current timestamp
})
// Date range queries
db.events.find({
startDate: { $gte: new Date("2025-01-01"), $lt: new Date("2026-01-01") }
})
// Date aggregation
db.events.aggregate([
{ $project: { title: 1, year: { $year: "$startDate" }, month: { $month: "$startDate" } } }
])
```
## ObjectId
A 12-byte identifier automatically generated for the `_id` field. Contains a
timestamp, random value, and incrementing counter.
```javascript
// Auto-generated _id
db.logs.insertOne({ message: "App started" })
// { _id: ObjectId("65a1f2c3d4e5f6a7b8c9d0e1"), message: "App started" }
// Extract the creation timestamp from an ObjectId
const doc = db.logs.findOne()
doc._id.getTimestamp()
// ISODate("2025-01-13T10:30:27.000Z")
// Create a specific ObjectId
const customId = ObjectId("507f1f77bcf86cd799439011")
```
## UUID
Universally unique identifiers, stored as Binary subtype 4.
```javascript
db.sessions.insertOne({
sessionId: UUID(),
userId: ObjectId("65a1f2c3d4e5f6a7b8c9d0e1"),
createdAt: new Date()
})
// Query by UUID
db.sessions.find({ sessionId: UUID("a1b2c3d4-e5f6-7890-abcd-ef1234567890") })
```
## Array
Arrays can hold values of any BSON type, including other arrays and documents.
```javascript
db.articles.insertOne({
title: "Getting Started with MongoDB",
tags: ["mongodb", "nosql", "tutorial"],
scores: [95, 87, 92],
authors: [
{ name: "Alice", role: "lead" },
{ name: "Bob", role: "contributor" }
]
})
// Query elements in an array
db.articles.find({ tags: "mongodb" })
// Query with array operators
db.articles.find({ tags: { $all: ["mongodb", "tutorial"] } })
db.articles.find({ scores: { $elemMatch: { $gte: 90 } } })
db.articles.find({ tags: { $size: 3 } })
```
## Embedded Document (Object)
Documents can be nested to any depth, enabling rich data models.
```javascript
db.employees.insertOne({
name: "Grace Hopper",
contact: {
email: "grace@example.com",
phone: "+1-555-0100",
address: {
street: "123 Navy Yard",
city: "Arlington",
state: "VA",
zip: "22204"
}
}
})
// Query nested fields with dot notation
db.employees.find({ "contact.address.city": "Arlington" })
// Update nested fields
db.employees.updateOne(
{ name: "Grace Hopper" },
{ $set: { "contact.phone": "+1-555-0200" } }
)
```
## Binary Data
Store binary content such as small files, hashes, or encrypted data.
```javascript
db.files.insertOne({
filename: "avatar.png",
contentType: "image/png",
data: BinData(0, "iVBORw0KGgoAAAANSUhEUg..."), // base64-encoded
checksum: BinData(5, "d4a1b2c3e5f67890...") // MD5 subtype
})
```
## Null
Represents the absence of a value. Distinct from a field not existing.
```javascript
db.profiles.insertOne({ name: "Test User", bio: null })
// Find documents where bio is null
db.profiles.find({ bio: null })
// Find documents where bio field exists but is null (not just missing)
db.profiles.find({ bio: { $type: "null" } })
// Find documents where the field does not exist at all
db.profiles.find({ bio: { $exists: false } })
```
## Regular Expression
Store and query with regex patterns.
```javascript
// Store a regex
db.rules.insertOne({
name: "Email Pattern",
pattern: /^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$/
})
// Query using regex
db.users.find({ email: { $regex: /@example\.com$/, $options: "i" } })
```
## Timestamp
An internal type used by MongoDB for replication. Application code should
use `Date` instead.
```javascript
// Timestamp is typically set by the server for oplog entries
// In application code, prefer Date:
db.audit.insertOne({
action: "login",
performedAt: new Date()
})
```
## Querying by Type with $type
Use the `$type` operator to find documents based on the BSON type of a field.
```javascript
// Find documents where "price" is a Decimal128
db.products.find({ price: { $type: "decimal" } })
// Find documents where "value" is any numeric type
db.metrics.find({ value: { $type: ["int", "long", "double", "decimal"] } })
// Find documents where "tags" is an array
db.articles.find({ tags: { $type: "array" } })
// You can also use the numeric type code
db.products.find({ price: { $type: 19 } }) // 19 = Decimal128
```
## Type Conversion in Aggregation
```javascript
db.raw_data.aggregate([
{ $project: {
label: 1,
numericValue: { $toDouble: "$stringValue" },
dateValue: { $toDate: "$timestampMs" },
stringId: { $toString: "$_id" }
}}
])
```
## Tips
- Use `NumberDecimal()` for monetary values to avoid floating-point rounding.
- Use `ObjectId` for `_id` unless you have a natural unique key.
- Prefer `Date` over `Timestamp` in application documents.
- Arrays are automatically indexed as multikey indexes, enabling efficient queries
on array elements.
- In MongoDB Atlas, the Data Explorer displays BSON types with visual indicators
for easy identification.