0
# Google Cloud Datastore
1
2
Google Cloud Datastore is a NoSQL document database service that provides automatic scaling, ACID transactions, and SQL-like queries. It stores data as entities with properties in a schemaless format.
3
4
## Capabilities
5
6
### Client Operations
7
8
High-level client for managing Datastore operations including entity CRUD, queries, transactions, and batch operations.
9
10
```python { .api }
11
class Client:
12
def __init__(self, dataset_id=None, namespace=None, connection=None):
13
"""
14
Initialize Datastore client.
15
16
Parameters:
17
- dataset_id (str): Google Cloud project ID
18
- namespace (str): Optional namespace for entity isolation
19
- connection (Connection): Optional custom connection
20
"""
21
22
def get(self, key, missing=None, deferred=None):
23
"""
24
Retrieve entity by key.
25
26
Parameters:
27
- key (Key): Entity key to retrieve
28
- missing (list): Optional list to populate with missing keys
29
- deferred (list): Optional list to populate with deferred keys
30
31
Returns:
32
Entity or None if not found
33
"""
34
35
def get_multi(self, keys, missing=None, deferred=None):
36
"""
37
Retrieve multiple entities by keys.
38
39
Parameters:
40
- keys (list[Key]): List of entity keys
41
- missing (list): Optional list to populate with missing keys
42
- deferred (list): Optional list to populate with deferred keys
43
44
Returns:
45
list[Entity]: List of retrieved entities
46
"""
47
48
def put(self, entity):
49
"""
50
Save entity to datastore.
51
52
Parameters:
53
- entity (Entity): Entity to save
54
"""
55
56
def put_multi(self, entities):
57
"""
58
Save multiple entities to datastore.
59
60
Parameters:
61
- entities (list[Entity]): List of entities to save
62
"""
63
64
def delete(self, key):
65
"""
66
Delete entity by key.
67
68
Parameters:
69
- key (Key): Key of entity to delete
70
"""
71
72
def delete_multi(self, keys):
73
"""
74
Delete multiple entities by keys.
75
76
Parameters:
77
- keys (list[Key]): List of keys to delete
78
"""
79
80
def allocate_ids(self, incomplete_key, num_ids):
81
"""
82
Allocate unique IDs for incomplete keys.
83
84
Parameters:
85
- incomplete_key (Key): Partial key without ID
86
- num_ids (int): Number of IDs to allocate
87
88
Returns:
89
list[Key]: List of complete keys with allocated IDs
90
"""
91
92
def key(self, *path_args, **kwargs):
93
"""
94
Create Key instance.
95
96
Parameters:
97
- path_args: Alternating kind/id pairs for key path
98
- namespace (str): Optional namespace
99
- dataset_id (str): Optional dataset ID
100
101
Returns:
102
Key: New key instance
103
"""
104
105
def batch(self):
106
"""
107
Create batch context manager for grouping operations.
108
109
Returns:
110
Batch: Batch context manager
111
"""
112
113
def transaction(self):
114
"""
115
Create transaction context manager.
116
117
Returns:
118
Transaction: Transaction context manager
119
"""
120
121
def query(self, **kwargs):
122
"""
123
Create query instance.
124
125
Parameters:
126
- kind (str): Entity kind to query
127
- ancestor (Key): Optional ancestor filter
128
- filters (tuple): Property filters
129
- projection (tuple): Fields to return
130
- order (tuple): Sort order
131
- group_by (tuple): Group by fields
132
133
Returns:
134
Query: Query instance
135
"""
136
```
137
138
### Entity Management
139
140
Entities represent individual records in Datastore, extending Python dictionaries with key association and indexing control.
141
142
```python { .api }
143
class Entity(dict):
144
def __init__(self, key=None, exclude_from_indexes=()):
145
"""
146
Initialize entity.
147
148
Parameters:
149
- key (Key): Optional associated key
150
- exclude_from_indexes (tuple): Property names to exclude from indexing
151
"""
152
153
@property
154
def key(self):
155
"""
156
Associated Key instance.
157
158
Returns:
159
Key or None
160
"""
161
162
@property
163
def kind(self):
164
"""
165
Entity kind derived from key.
166
167
Returns:
168
str or None
169
"""
170
171
@property
172
def exclude_from_indexes(self):
173
"""
174
Properties excluded from indexing.
175
176
Returns:
177
tuple: Property names
178
"""
179
```
180
181
### Key Management
182
183
Keys provide unique identification for Datastore entities, supporting hierarchical relationships and partial/complete states.
184
185
```python { .api }
186
class Key:
187
def __init__(self, *path_args, **kwargs):
188
"""
189
Initialize key with path elements.
190
191
Parameters:
192
- path_args: Alternating kind/id pairs
193
- namespace (str): Optional namespace
194
- dataset_id (str): Optional dataset ID
195
"""
196
197
def completed_key(self, id_or_name):
198
"""
199
Create complete key from partial key.
200
201
Parameters:
202
- id_or_name (int|str): ID or name for final path element
203
204
Returns:
205
Key: Complete key
206
"""
207
208
def to_protobuf(self):
209
"""
210
Convert to protocol buffer representation.
211
212
Returns:
213
Protocol buffer key
214
"""
215
216
@property
217
def is_partial(self):
218
"""
219
Whether key lacks final ID/name.
220
221
Returns:
222
bool: True if incomplete
223
"""
224
225
@property
226
def namespace(self):
227
"""
228
Key namespace.
229
230
Returns:
231
str or None
232
"""
233
234
@property
235
def dataset_id(self):
236
"""
237
Dataset ID.
238
239
Returns:
240
str
241
"""
242
243
@property
244
def path(self):
245
"""
246
Full path as tuples.
247
248
Returns:
249
tuple: Path elements
250
"""
251
252
@property
253
def kind(self):
254
"""
255
Entity kind (final path element).
256
257
Returns:
258
str
259
"""
260
261
@property
262
def id(self):
263
"""
264
Entity numeric ID if any.
265
266
Returns:
267
int or None
268
"""
269
270
@property
271
def name(self):
272
"""
273
Entity string name if any.
274
275
Returns:
276
str or None
277
"""
278
279
@property
280
def parent(self):
281
"""
282
Parent key if any.
283
284
Returns:
285
Key or None
286
"""
287
```
288
289
### Query Operations
290
291
Query interface for searching and filtering entities with support for ordering, projection, and pagination.
292
293
```python { .api }
294
class Query:
295
def __init__(self, client, kind=None, dataset_id=None, namespace=None,
296
ancestor=None, filters=(), projection=(), order=(), group_by=()):
297
"""
298
Initialize query.
299
300
Parameters:
301
- client (Client): Datastore client
302
- kind (str): Entity kind to query
303
- dataset_id (str): Optional dataset ID
304
- namespace (str): Optional namespace
305
- ancestor (Key): Optional ancestor filter
306
- filters (tuple): Property filters
307
- projection (tuple): Fields to return
308
- order (tuple): Sort order specifications
309
- group_by (tuple): Group by fields
310
"""
311
312
def add_filter(self, property_name, operator, value):
313
"""
314
Add property filter to query.
315
316
Parameters:
317
- property_name (str): Property to filter
318
- operator (str): Comparison operator ('=', '<', '<=', '>', '>=')
319
- value: Filter value
320
"""
321
322
def keys_only(self):
323
"""
324
Set projection to return only keys.
325
"""
326
327
def fetch(self, limit=None, offset=0, start_cursor=None, end_cursor=None, client=None):
328
"""
329
Execute query and return iterator.
330
331
Parameters:
332
- limit (int): Maximum results to return
333
- offset (int): Number of results to skip
334
- start_cursor (str): Starting cursor for pagination
335
- end_cursor (str): Ending cursor for pagination
336
- client (Client): Optional client override
337
338
Returns:
339
Iterator: Query result iterator
340
"""
341
342
@property
343
def kind(self):
344
"""
345
Entity kind being queried.
346
347
Returns:
348
str or None
349
"""
350
351
@property
352
def filters(self):
353
"""
354
Applied property filters.
355
356
Returns:
357
list: Filter specifications
358
"""
359
```
360
361
### Batch Operations
362
363
Batch operations group multiple datastore operations for efficient execution.
364
365
```python { .api }
366
class Batch:
367
def __init__(self, client):
368
"""
369
Initialize batch with client.
370
371
Parameters:
372
- client (Client): Datastore client
373
"""
374
375
def put(self, entity):
376
"""
377
Add entity save to batch.
378
379
Parameters:
380
- entity (Entity): Entity to save
381
"""
382
383
def delete(self, key):
384
"""
385
Add key deletion to batch.
386
387
Parameters:
388
- key (Key): Key to delete
389
"""
390
391
def commit(self):
392
"""
393
Execute all batched operations.
394
"""
395
396
def __enter__(self):
397
"""
398
Enter context manager.
399
400
Returns:
401
Batch: Self
402
"""
403
404
def __exit__(self, exc_type, exc_val, exc_tb):
405
"""
406
Exit context manager and commit.
407
"""
408
```
409
410
### Transaction Operations
411
412
Transactions provide ACID guarantees for datastore operations with automatic retry and rollback support.
413
414
```python { .api }
415
class Transaction(Batch):
416
def __init__(self, client):
417
"""
418
Initialize transaction.
419
420
Parameters:
421
- client (Client): Datastore client
422
"""
423
424
def begin(self):
425
"""
426
Start transaction.
427
"""
428
429
def commit(self):
430
"""
431
Commit transaction.
432
"""
433
434
def rollback(self):
435
"""
436
Rollback transaction.
437
"""
438
439
@property
440
def id(self):
441
"""
442
Transaction identifier.
443
444
Returns:
445
str: Transaction ID
446
"""
447
```
448
449
## Usage Examples
450
451
### Basic Entity Operations
452
453
```python
454
from gcloud import datastore
455
456
# Initialize client
457
client = datastore.Client(dataset_id='my-project')
458
459
# Create and save entity
460
key = client.key('Person', 'alice')
461
entity = datastore.Entity(key)
462
entity.update({
463
'name': 'Alice Smith',
464
'age': 30,
465
'email': 'alice@example.com'
466
})
467
client.put(entity)
468
469
# Retrieve entity
470
retrieved = client.get(key)
471
print(retrieved['name']) # Alice Smith
472
473
# Delete entity
474
client.delete(key)
475
```
476
477
### Query Operations
478
479
```python
480
# Create query
481
query = client.query(kind='Person')
482
query.add_filter('age', '>=', 18)
483
query.add_filter('age', '<', 65)
484
485
# Execute query
486
results = list(query.fetch(limit=10))
487
for entity in results:
488
print(f"{entity['name']}: {entity['age']}")
489
```
490
491
### Batch Operations
492
493
```python
494
# Batch multiple operations
495
with client.batch() as batch:
496
for i in range(5):
497
key = client.key('TestEntity', i)
498
entity = datastore.Entity(key)
499
entity['value'] = f'test-{i}'
500
batch.put(entity)
501
```
502
503
### Transaction Operations
504
505
```python
506
# Atomic transaction
507
with client.transaction() as txn:
508
key = client.key('Counter', 'global')
509
counter = client.get(key)
510
if counter is None:
511
counter = datastore.Entity(key)
512
counter['count'] = 0
513
counter['count'] += 1
514
txn.put(counter)
515
```