0
# ObjectId Operations
1

2
MongoDB-compatible ObjectId implementation providing unique 12-byte identifiers. ObjectIds consist of a timestamp, machine identifier, process ID, and counter, ensuring uniqueness across distributed systems.
3

4
## Capabilities
5

6
### ObjectId Creation
7

8
Create new ObjectIds or parse existing ones from various formats including hex strings, bytes, or automatic generation.
9

10
```python { .api }
11
class ObjectId:
12
    def __init__(self, oid=None):
13
        """
14
        Initialize a new ObjectId.
15

16
        Parameters:
17
        - oid: None (generate new), ObjectId instance (copy), 
18
               bytes (12-byte binary), or str (24-char hex)
19

20
        Raises:
21
        InvalidId: If oid is not valid format
22
        TypeError: If oid is not accepted type
23
        """
24
```
25

26
Usage examples:
27

28
```python
29
from bson import ObjectId
30

31
# Generate new ObjectId
32
oid1 = ObjectId()
33
print(str(oid1))  # e.g., '507f1f77bcf86cd799439011'
34

35
# From hex string
36
oid2 = ObjectId('507f1f77bcf86cd799439011')
37

38
# From bytes
39
binary_data = b'foo-bar-quux'  # any 12 bytes
40
oid3 = ObjectId(binary_data)
41

42
# Copy existing ObjectId
43
oid4 = ObjectId(oid1)
44
```
45

46
### ObjectId Validation
47

48
Check if strings or objects represent valid ObjectIds before attempting to create them.
49

50
```python { .api }
51
@classmethod
52
def is_valid(cls, oid):
53
    """
54
    Check if oid string/object is valid ObjectId format.
55

56
    Parameters:
57
    - oid: Value to validate (str, bytes, ObjectId, or other)
58

59
    Returns:
60
    bool: True if valid ObjectId format, False otherwise
61
    """
62
```
63

64
Usage example:
65

66
```python
67
from bson import ObjectId
68

69
# Valid cases
70
print(ObjectId.is_valid('507f1f77bcf86cd799439011'))  # True
71
print(ObjectId.is_valid(ObjectId()))  # True
72
print(ObjectId.is_valid(b'123456789012'))  # True
73

74
# Invalid cases  
75
print(ObjectId.is_valid('invalid'))  # False
76
print(ObjectId.is_valid('507f1f77bcf86cd79943901'))  # False (23 chars)
77
print(ObjectId.is_valid(None))  # False
78
print(ObjectId.is_valid(123))  # False
79
```
80

81
### DateTime-based ObjectId Generation
82

83
Create ObjectIds with specific generation timestamps for range queries and time-based operations.
84

85
```python { .api }
86
@classmethod
87
def from_datetime(cls, generation_time):
88
    """
89
    Create ObjectId with specific generation time for queries.
90

91
    Warning: Not safe for insertion - eliminates uniqueness guarantee.
92
    Use only for range queries.
93

94
    Parameters:
95
    - generation_time: datetime object (converted to UTC if timezone-aware)
96

97
    Returns:
98
    ObjectId: ObjectId with specified timestamp, other fields zeroed
99
    """
100
```
101

102
Usage example:
103

104
```python
105
from bson import ObjectId
106
from datetime import datetime
107

108
# Create ObjectId for range query
109
query_time = datetime(2010, 1, 1)
110
dummy_id = ObjectId.from_datetime(query_time)
111

112
# Use in MongoDB-style range query
113
# collection.find({"_id": {"$lt": dummy_id}})
114

115
# Compare with current ObjectIds
116
current_id = ObjectId()
117
print(dummy_id < current_id)  # True (older timestamp)
118
```
119

120
### ObjectId Properties
121

122
Access ObjectId components and metadata including binary representation and generation timestamp.
123

124
```python { .api }
125
@property
126
def binary(self):
127
    """
128
    12-byte binary representation of ObjectId.
129
    
130
    Returns:
131
    bytes: Raw 12-byte ObjectId data
132
    """
133

134
@property  
135
def generation_time(self):
136
    """
137
    Generation time as timezone-aware datetime.
138
    
139
    Returns:
140
    datetime: UTC datetime of ObjectId creation (precise to second)
141
    """
142
```
143

144
Usage example:
145

146
```python
147
from bson import ObjectId
148
import datetime
149

150
oid = ObjectId()
151

152
# Get binary representation
153
binary_data = oid.binary
154
print(len(binary_data))  # 12
155
print(type(binary_data))  # <class 'bytes'>
156

157
# Get generation time
158
gen_time = oid.generation_time
159
print(type(gen_time))  # <class 'datetime.datetime'>
160
print(gen_time.tzinfo)  # <bson.tz_util.FixedOffset object>
161

162
# Time comparison
163
now = datetime.datetime.now(datetime.timezone.utc)
164
print(gen_time <= now)  # True
165
```
166

167
### ObjectId Comparison and Hashing
168

169
Compare ObjectIds chronologically and use them as dictionary keys or in sets.
170

171
```python { .api }
172
def __eq__(self, other): ...
173
def __ne__(self, other): ...  
174
def __lt__(self, other): ...
175
def __le__(self, other): ...
176
def __gt__(self, other): ...
177
def __ge__(self, other): ...
178
def __hash__(self): ...
179
```
180

181
Usage example:
182

183
```python
184
from bson import ObjectId
185
import time
186

187
# Create ObjectIds at different times
188
oid1 = ObjectId()
189
time.sleep(0.1)
190
oid2 = ObjectId()
191

192
# Chronological comparison
193
print(oid1 < oid2)  # True (oid1 created first)
194
print(oid1 == oid1)  # True
195
print(oid1 != oid2)  # True
196

197
# Use as dictionary keys
198
data = {oid1: "first", oid2: "second"}
199
print(data[oid1])  # "first"
200

201
# Use in sets
202
oid_set = {oid1, oid2, oid1}  # Duplicates removed
203
print(len(oid_set))  # 2
204
```
205

206
### String Representation
207

208
Convert ObjectIds to various string formats for display and serialization.
209

210
```python { .api }
211
def __str__(self): 
212
    """24-character hex string representation"""
213

214
def __repr__(self):
215
    """ObjectId('hex_string') representation"""
216
```
217

218
Usage example:
219

220
```python
221
from bson import ObjectId
222

223
oid = ObjectId()
224

225
# String formats
226
hex_string = str(oid)  # '507f1f77bcf86cd799439011'
227
repr_string = repr(oid)  # "ObjectId('507f1f77bcf86cd799439011')"
228

229
print(f"ObjectId: {oid}")
230
print(f"Repr: {oid!r}")
231

232
# Roundtrip conversion
233
oid_copy = ObjectId(str(oid))
234
print(oid == oid_copy)  # True
235
```
236

237
## Error Handling
238

239
### ObjectId Exceptions
240

241
```python { .api }
242
class InvalidId(ValueError):
243
    """Raised when creating ObjectId from invalid data"""
244
```
245

246
Common causes of InvalidId:
247
- Hex strings not exactly 24 characters
248
- Bytes not exactly 12 bytes  
249
- Non-hex characters in string
250
- Invalid types (numbers, lists, etc.)
251

252
Usage example:
253

254
```python
255
from bson import ObjectId
256
from bson.objectid import InvalidId
257

258
try:
259
    # Invalid hex string (23 chars)
260
    bad_oid = ObjectId('507f1f77bcf86cd79943901')
261
except InvalidId as e:
262
    print(f"Invalid ObjectId: {e}")
263

264
try:
265
    # Invalid type
266
    bad_oid = ObjectId(12345)
267
except TypeError as e:
268
    print(f"Type error: {e}")
269
```
270

271
## ObjectId Structure
272

273
ObjectIds contain the following components in 12 bytes:
274

275
1. **Timestamp** (4 bytes): Seconds since Unix epoch
276
2. **Machine ID** (3 bytes): Hash of hostname  
277
3. **Process ID** (2 bytes): Process ID modulo 65535
278
4. **Counter** (3 bytes): Incrementing counter starting from random value
279

280
This structure ensures uniqueness across distributed systems and provides natural chronological ordering.