google-cloud-datastore 0.21.0 → 0.23.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (25) hide show
  1. checksums.yaml +4 -4
  2. data/.yardopts +7 -0
  3. data/LICENSE +201 -0
  4. data/README.md +75 -0
  5. data/lib/google-cloud-datastore.rb +2 -2
  6. data/lib/google/cloud/datastore.rb +24 -0
  7. data/lib/google/cloud/datastore/commit.rb +17 -2
  8. data/lib/google/cloud/datastore/cursor.rb +1 -1
  9. data/lib/google/cloud/datastore/dataset.rb +143 -4
  10. data/lib/google/cloud/datastore/dataset/lookup_results.rb +21 -5
  11. data/lib/google/cloud/datastore/dataset/query_results.rb +14 -4
  12. data/lib/google/cloud/datastore/entity.rb +88 -9
  13. data/lib/google/cloud/datastore/gql_query.rb +12 -0
  14. data/lib/google/cloud/datastore/key.rb +21 -1
  15. data/lib/google/cloud/datastore/query.rb +82 -0
  16. data/lib/google/cloud/datastore/service.rb +2 -2
  17. data/lib/google/cloud/datastore/transaction.rb +45 -11
  18. data/lib/google/cloud/datastore/v1.rb +1 -1
  19. data/lib/google/cloud/datastore/v1/{datastore_api.rb → datastore_client.rb} +42 -42
  20. data/lib/google/cloud/datastore/v1/doc/google/datastore/v1/datastore.rb +240 -0
  21. data/lib/google/cloud/datastore/v1/doc/google/datastore/v1/entity.rb +187 -0
  22. data/lib/google/cloud/datastore/v1/doc/google/datastore/v1/query.rb +292 -0
  23. data/lib/google/cloud/datastore/v1/doc/google/protobuf/wrappers.rb +89 -0
  24. data/lib/google/cloud/datastore/version.rb +1 -1
  25. metadata +13 -6
data/lib/google/cloud/datastore/dataset.rb CHANGED
@@ -101,6 +101,10 @@ module Google
101
101
  # @return [Array<Google::Cloud::Datastore::Key>]
102
102
  #
103
103
  # @example
104
+ # require "google/cloud/datastore"
105
+ #
106
+ # datastore = Google::Cloud::Datastore.new
107
+ #
104
108
  # task_key = datastore.key "Task"
105
109
  # task_keys = datastore.allocate_ids task_key, 5
106
110
  #
@@ -124,6 +128,10 @@ module Google
124
128
  # @return [Array<Google::Cloud::Datastore::Entity>]
125
129
  #
126
130
  # @example Insert a new entity:
131
+ # require "google/cloud/datastore"
132
+ #
133
+ # datastore = Google::Cloud::Datastore.new
134
+ #
127
135
  # task = datastore.entity "Task" do |t|
128
136
  # t["type"] = "Personal"
129
137
  # t["done"] = false
@@ -135,6 +143,10 @@ module Google
135
143
  # task.key.id #=> 123456
136
144
  #
137
145
  # @example Insert multiple new entities in a batch:
146
+ # require "google/cloud/datastore"
147
+ #
148
+ # datastore = Google::Cloud::Datastore.new
149
+ #
138
150
  # task1 = datastore.entity "Task" do |t|
139
151
  # t["type"] = "Personal"
140
152
  # t["done"] = false
@@ -152,6 +164,10 @@ module Google
152
164
  # task_key1, task_key2 = datastore.save(task1, task2).map(&:key)
153
165
  #
154
166
  # @example Update an existing entity:
167
+ # require "google/cloud/datastore"
168
+ #
169
+ # datastore = Google::Cloud::Datastore.new
170
+ #
155
171
  # task = datastore.find "Task", "sampleTask"
156
172
  # task["priority"] = 5
157
173
  # datastore.save task
@@ -170,6 +186,10 @@ module Google
170
186
  # @return [Array<Google::Cloud::Datastore::Entity>]
171
187
  #
172
188
  # @example Insert a new entity:
189
+ # require "google/cloud/datastore"
190
+ #
191
+ # datastore = Google::Cloud::Datastore.new
192
+ #
173
193
  # task = datastore.entity "Task" do |t|
174
194
  # t["type"] = "Personal"
175
195
  # t["done"] = false
@@ -181,6 +201,10 @@ module Google
181
201
  # task.key.id #=> 123456
182
202
  #
183
203
  # @example Insert multiple new entities in a batch:
204
+ # require "google/cloud/datastore"
205
+ #
206
+ # datastore = Google::Cloud::Datastore.new
207
+ #
184
208
  # task1 = datastore.entity "Task" do |t|
185
209
  # t["type"] = "Personal"
186
210
  # t["done"] = false
@@ -210,11 +234,19 @@ module Google
210
234
  # @return [Array<Google::Cloud::Datastore::Entity>]
211
235
  #
212
236
  # @example Update an existing entity:
237
+ # require "google/cloud/datastore"
238
+ #
239
+ # datastore = Google::Cloud::Datastore.new
240
+ #
213
241
  # task = datastore.find "Task", "sampleTask"
214
242
  # task["done"] = true
215
243
  # datastore.save task
216
244
  #
217
- # @example update multiple new entities in a batch:
245
+ # @example Update multiple new entities in a batch:
246
+ # require "google/cloud/datastore"
247
+ #
248
+ # datastore = Google::Cloud::Datastore.new
249
+ #
218
250
  # query = datastore.query("Task").where("done", "=", false)
219
251
  # tasks = datastore.run query
220
252
  # tasks.each { |t| t["done"] = true }
@@ -233,7 +265,10 @@ module Google
233
265
  # @return [Boolean] Returns `true` if successful
234
266
  #
235
267
  # @example
268
+ # require "google/cloud/datastore"
269
+ #
236
270
  # datastore = Google::Cloud::Datastore.new
271
+ #
237
272
  # datastore.delete task1, task2
238
273
  #
239
274
  def delete *entities_or_keys
@@ -251,7 +286,10 @@ module Google
251
286
  # were persisted.
252
287
  #
253
288
  # @example
289
+ # require "google/cloud/datastore"
290
+ #
254
291
  # datastore = Google::Cloud::Datastore.new
292
+ #
255
293
  # datastore.commit do |c|
256
294
  # c.save task3, task4
257
295
  # c.delete task1, task2
@@ -292,10 +330,18 @@ module Google
292
330
  # @return [Google::Cloud::Datastore::Entity, nil]
293
331
  #
294
332
  # @example Finding an entity with a key:
333
+ # require "google/cloud/datastore"
334
+ #
335
+ # datastore = Google::Cloud::Datastore.new
336
+ #
295
337
  # task_key = datastore.key "Task", "sampleTask"
296
338
  # task = datastore.find task_key
297
339
  #
298
340
  # @example Finding an entity with a `kind` and `id`/`name`:
341
+ # require "google/cloud/datastore"
342
+ #
343
+ # datastore = Google::Cloud::Datastore.new
344
+ #
299
345
  # task = datastore.find "Task", "sampleTask"
300
346
  #
301
347
  def find key_or_kind, id_or_name = nil, consistency: nil
@@ -324,6 +370,8 @@ module Google
324
370
  # @return [Google::Cloud::Datastore::Dataset::LookupResults]
325
371
  #
326
372
  # @example
373
+ # require "google/cloud/datastore"
374
+ #
327
375
  # datastore = Google::Cloud::Datastore.new
328
376
  #
329
377
  # task_key1 = datastore.key "Task", "sampleTask1"
@@ -356,28 +404,48 @@ module Google
356
404
  # @return [Google::Cloud::Datastore::Dataset::QueryResults]
357
405
  #
358
406
  # @example
407
+ # require "google/cloud/datastore"
408
+ #
409
+ # datastore = Google::Cloud::Datastore.new
410
+ #
359
411
  # query = datastore.query("Task").
360
412
  # where("done", "=", false)
361
413
  # tasks = datastore.run query
362
414
  #
363
415
  # @example Run an ancestor query with eventual consistency:
416
+ # require "google/cloud/datastore"
417
+ #
418
+ # datastore = Google::Cloud::Datastore.new
419
+ #
364
420
  # task_list_key = datastore.key "TaskList", "default"
365
- # query.kind("Task").
421
+ # query = datastore.query.kind("Task").
366
422
  # ancestor(task_list_key)
367
423
  #
368
424
  # tasks = datastore.run query, consistency: :eventual
369
425
  #
370
426
  # @example Run the query within a namespace with the `namespace` option:
427
+ # require "google/cloud/datastore"
428
+ #
429
+ # datastore = Google::Cloud::Datastore.new
430
+ #
371
431
  # query = datastore.query("Task").
372
432
  # where("done", "=", false)
373
433
  # tasks = datastore.run query, namespace: "ns~todo-project"
374
434
  #
375
435
  # @example Run the query with a GQL string.
436
+ # require "google/cloud/datastore"
437
+ #
438
+ # datastore = Google::Cloud::Datastore.new
439
+ #
376
440
  # gql_query = datastore.gql "SELECT * FROM Task WHERE done = @done",
377
441
  # done: false
378
442
  # tasks = datastore.run gql_query
379
443
  #
380
444
  # @example Run the GQL query within a namespace with `namespace` option:
445
+ # require "google/cloud/datastore"
446
+ #
447
+ # datastore = Google::Cloud::Datastore.new
448
+ #
381
449
  # gql_query = datastore.gql "SELECT * FROM Task WHERE done = @done",
382
450
  # done: false
383
451
  # tasks = datastore.run gql_query, namespace: "ns~todo-project"
@@ -468,11 +536,19 @@ module Google
468
536
  # @return [Google::Cloud::Datastore::Query]
469
537
  #
470
538
  # @example
539
+ # require "google/cloud/datastore"
540
+ #
541
+ # datastore = Google::Cloud::Datastore.new
542
+ #
471
543
  # query = datastore.query("Task").
472
544
  # where("done", "=", false)
473
545
  # tasks = datastore.run query
474
546
  #
475
547
  # @example The previous example is equivalent to:
548
+ # require "google/cloud/datastore"
549
+ #
550
+ # datastore = Google::Cloud::Datastore.new
551
+ #
476
552
  # query = Google::Cloud::Datastore::Query.new.
477
553
  # kind("Task").
478
554
  # where("done", "=", false)
@@ -497,11 +573,19 @@ module Google
497
573
  # @return [Google::Cloud::Datastore::GqlQuery]
498
574
  #
499
575
  # @example
576
+ # require "google/cloud/datastore"
577
+ #
578
+ # datastore = Google::Cloud::Datastore.new
579
+ #
500
580
  # gql_query = datastore.gql "SELECT * FROM Task WHERE done = @done",
501
581
  # done: false
502
582
  # tasks = datastore.run gql_query
503
583
  #
504
584
  # @example The previous example is equivalent to:
585
+ # require "google/cloud/datastore"
586
+ #
587
+ # datastore = Google::Cloud::Datastore.new
588
+ #
505
589
  # gql_query = Google::Cloud::Datastore::GqlQuery.new
506
590
  # gql_query.query_string = "SELECT * FROM Task WHERE done = @done"
507
591
  # gql_query.named_bindings = {done: false}
@@ -528,40 +612,73 @@ module Google
528
612
  # @return [Google::Cloud::Datastore::Key]
529
613
  #
530
614
  # @example
615
+ # require "google/cloud/datastore"
616
+ #
617
+ # datastore = Google::Cloud::Datastore.new
618
+ #
531
619
  # task_key = datastore.key "Task", "sampleTask"
532
620
  #
533
621
  # @example The previous example is equivalent to:
622
+ # require "google/cloud/datastore"
623
+ #
534
624
  # task_key = Google::Cloud::Datastore::Key.new "Task", "sampleTask"
535
625
  #
536
626
  # @example Create an empty key:
627
+ # require "google/cloud/datastore"
628
+ #
629
+ # datastore = Google::Cloud::Datastore.new
630
+ #
537
631
  # key = datastore.key
538
632
  #
539
633
  # @example Create an incomplete key:
634
+ # require "google/cloud/datastore"
635
+ #
636
+ # datastore = Google::Cloud::Datastore.new
637
+ #
540
638
  # key = datastore.key "User"
541
639
  #
542
640
  # @example Create a key with a parent:
641
+ # require "google/cloud/datastore"
642
+ #
643
+ # datastore = Google::Cloud::Datastore.new
644
+ #
543
645
  # key = datastore.key [["TaskList", "default"],
544
646
  # ["Task", "sampleTask"]]
545
647
  # key.path #=> [["TaskList", "default"], ["Task", "sampleTask"]]
546
648
  #
547
649
  # @example Create a key with multi-level ancestry:
650
+ # require "google/cloud/datastore"
651
+ #
652
+ # datastore = Google::Cloud::Datastore.new
653
+ #
548
654
  # key = datastore.key([
549
655
  # ["User", "alice"],
550
656
  # ["TaskList", "default"],
551
657
  # ["Task", "sampleTask"]
552
658
  # ])
553
- # key.path #=> [["User", "alice"], ["TaskList", "default"], [ ... ]]
659
+ # key.path.count #=> 3
660
+ # key.path[0] #=> ["User", "alice"]
661
+ # key.path[1] #=> ["TaskList", "default"]
662
+ # key.path[2] #=> ["Task", "sampleTask"]
554
663
  #
555
664
  # @example Create an incomplete key with a parent:
665
+ # require "google/cloud/datastore"
666
+ #
667
+ # datastore = Google::Cloud::Datastore.new
668
+ #
556
669
  # key = datastore.key "TaskList", "default", "Task"
557
670
  # key.path #=> [["TaskList", "default"], ["Task", nil]]
558
671
  #
559
672
  # @example Create a key with a project and namespace:
673
+ # require "google/cloud/datastore"
674
+ #
675
+ # datastore = Google::Cloud::Datastore.new
676
+ #
560
677
  # key = datastore.key ["TaskList", "default"], ["Task", "sampleTask"],
561
678
  # project: "my-todo-project",
562
679
  # namespace: "ns~todo-project"
563
680
  # key.path #=> [["TaskList", "default"], ["Task", "sampleTask"]]
564
- # key.project #=> "my-todo-project",
681
+ # key.project #=> "my-todo-project"
565
682
  # key.namespace #=> "ns~todo-project"
566
683
  #
567
684
  def key *path, project: nil, namespace: nil
@@ -592,24 +709,44 @@ module Google
592
709
  # @return [Google::Cloud::Datastore::Entity]
593
710
  #
594
711
  # @example
712
+ # require "google/cloud/datastore"
713
+ #
714
+ # datastore = Google::Cloud::Datastore.new
715
+ #
595
716
  # task = datastore.entity
596
717
  #
597
718
  # @example The previous example is equivalent to:
719
+ # require "google/cloud/datastore"
720
+ #
598
721
  # task = Google::Cloud::Datastore::Entity.new
599
722
  #
600
723
  # @example The key can also be passed in as an object:
724
+ # require "google/cloud/datastore"
725
+ #
726
+ # datastore = Google::Cloud::Datastore.new
727
+ #
601
728
  # task_key = datastore.key "Task", "sampleTask"
602
729
  # task = datastore.entity task_key
603
730
  #
604
731
  # @example Or the key values can be passed in as parameters:
732
+ # require "google/cloud/datastore"
733
+ #
734
+ # datastore = Google::Cloud::Datastore.new
735
+ #
605
736
  # task = datastore.entity "Task", "sampleTask"
606
737
  #
607
738
  # @example The previous example is equivalent to:
739
+ # require "google/cloud/datastore"
740
+ #
608
741
  # task_key = Google::Cloud::Datastore::Key.new "Task", "sampleTask"
609
742
  # task = Google::Cloud::Datastore::Entity.new
610
743
  # task.key = task_key
611
744
  #
612
745
  # @example The newly created entity can also be configured using block:
746
+ # require "google/cloud/datastore"
747
+ #
748
+ # datastore = Google::Cloud::Datastore.new
749
+ #
613
750
  # task = datastore.entity "Task", "sampleTask" do |t|
614
751
  # t["type"] = "Personal"
615
752
  # t["done"] = false
@@ -618,6 +755,8 @@ module Google
618
755
  # end
619
756
  #
620
757
  # @example The previous example is equivalent to:
758
+ # require "google/cloud/datastore"
759
+ #
621
760
  # task_key = Google::Cloud::Datastore::Key.new "Task", "sampleTask"
622
761
  # task = Google::Cloud::Datastore::Entity.new
623
762
  # task.key = task_key
data/lib/google/cloud/datastore/dataset/lookup_results.rb CHANGED
@@ -29,20 +29,28 @@ module Google
29
29
  # Many common Array methods will return a new Array instance.
30
30
  #
31
31
  # @example
32
+ # require "google/cloud/datastore"
33
+ #
34
+ # datastore = Google::Cloud::Datastore.new
35
+ #
32
36
  # tasks = datastore.find_all task_key1, task_key2, task_key3
33
37
  # tasks.size #=> 3
34
38
  # tasks.deferred #=> []
35
39
  # tasks.missing #=> []
36
40
  #
37
41
  # @example Caution, many Array methods will return a new Array instance:
42
+ # require "google/cloud/datastore"
43
+ #
44
+ # datastore = Google::Cloud::Datastore.new
45
+ #
38
46
  # tasks = datastore.find_all task_key1, task_key2, task_key3
39
47
  # tasks.size #=> 3
40
48
  # tasks.deferred #=> []
41
49
  # tasks.missing #=> []
42
50
  # descriptions = tasks.map { |task| task["description"] }
43
51
  # descriptions.size #=> 3
44
- # descriptions.deferred #=> NoMethodError
45
- # descriptions.missing #=> NoMethodError
52
+ # descriptions.deferred #=> raise NoMethodError
53
+ # descriptions.missing #=> raise NoMethodError
46
54
  #
47
55
  class LookupResults < DelegateClass(::Array)
48
56
  ##
@@ -65,6 +73,8 @@ module Google
65
73
  # @return [Boolean]
66
74
  #
67
75
  # @example
76
+ # require "google/cloud/datastore"
77
+ #
68
78
  # datastore = Google::Cloud::Datastore.new
69
79
  #
70
80
  # task_key1 = datastore.key "Task", "sampleTask1"
@@ -84,6 +94,8 @@ module Google
84
94
  # @return [LookupResults]
85
95
  #
86
96
  # @example
97
+ # require "google/cloud/datastore"
98
+ #
87
99
  # datastore = Google::Cloud::Datastore.new
88
100
  #
89
101
  # task_key1 = datastore.key "Task", "sampleTask1"
@@ -121,6 +133,8 @@ module Google
121
133
  # @return [Enumerator]
122
134
  #
123
135
  # @example Iterating each result by passing a block:
136
+ # require "google/cloud/datastore"
137
+ #
124
138
  # datastore = Google::Cloud::Datastore.new
125
139
  #
126
140
  # task_key1 = datastore.key "Task", "sampleTask1"
@@ -131,16 +145,18 @@ module Google
131
145
  # end
132
146
  #
133
147
  # @example Using the enumerator by not passing a block:
148
+ # require "google/cloud/datastore"
149
+ #
134
150
  # datastore = Google::Cloud::Datastore.new
135
151
  #
136
152
  # task_key1 = datastore.key "Task", "sampleTask1"
137
153
  # task_key2 = datastore.key "Task", "sampleTask2"
138
154
  # tasks = datastore.find_all task_key1, task_key2
139
- # all_keys = tasks.all.map(&:key).each do |task|
140
- # task.key
141
- # end
155
+ # all_keys = tasks.all.map(&:key)
142
156
  #
143
157
  # @example Limit the number of API calls made:
158
+ # require "google/cloud/datastore"
159
+ #
144
160
  # datastore = Google::Cloud::Datastore.new
145
161
  #
146
162
  # task_key1 = datastore.key "Task", "sampleTask1"
data/lib/google/cloud/datastore/dataset/query_results.rb CHANGED
@@ -37,7 +37,7 @@ module Google
37
37
  # tasks = datastore.run query
38
38
  #
39
39
  # tasks.size #=> 3
40
- # tasks.cursor #=> Cursor(c3VwZXJhd2Vzb21lIQ)
40
+ # tasks.cursor.to_s #=> "c2Vjb25kLXBhZ2UtY3Vyc29y"
41
41
  #
42
42
  # @example Caution, many Array methods will return a new Array instance:
43
43
  # require "google/cloud/datastore"
@@ -48,10 +48,10 @@ module Google
48
48
  # tasks = datastore.run query
49
49
  #
50
50
  # tasks.size #=> 3
51
- # tasks.end_cursor #=> Cursor(c3VwZXJhd2Vzb21lIQ)
51
+ # tasks.cursor.to_s #=> "c2Vjb25kLXBhZ2UtY3Vyc29y"
52
52
  # descriptions = tasks.map { |task| task["description"] }
53
53
  # descriptions.size #=> 3
54
- # descriptions.cursor #=> NoMethodError
54
+ # descriptions.cursor #=> raise NoMethodError
55
55
  #
56
56
  class QueryResults < DelegateClass(::Array)
57
57
  ##
@@ -123,6 +123,7 @@ module Google
123
123
  # require "google/cloud/datastore"
124
124
  #
125
125
  # datastore = Google::Cloud::Datastore.new
126
+ #
126
127
  # query = datastore.query "Task"
127
128
  # tasks = datastore.run query
128
129
  #
@@ -143,6 +144,7 @@ module Google
143
144
  # require "google/cloud/datastore"
144
145
  #
145
146
  # datastore = Google::Cloud::Datastore.new
147
+ #
146
148
  # query = datastore.query "Task"
147
149
  # tasks = datastore.run query
148
150
  #
@@ -170,6 +172,7 @@ module Google
170
172
  # require "google/cloud/datastore"
171
173
  #
172
174
  # datastore = Google::Cloud::Datastore.new
175
+ #
173
176
  # query = datastore.query "Task"
174
177
  # tasks = datastore.run query
175
178
  #
@@ -199,6 +202,7 @@ module Google
199
202
  # require "google/cloud/datastore"
200
203
  #
201
204
  # datastore = Google::Cloud::Datastore.new
205
+ #
202
206
  # query = datastore.query "Task"
203
207
  # tasks = datastore.run query
204
208
  # tasks.each_with_cursor do |task, cursor|
@@ -232,6 +236,7 @@ module Google
232
236
  # require "google/cloud/datastore"
233
237
  #
234
238
  # datastore = Google::Cloud::Datastore.new
239
+ #
235
240
  # query = datastore.query "Task"
236
241
  # tasks = datastore.run query
237
242
  # tasks.all do |task|
@@ -242,6 +247,7 @@ module Google
242
247
  # require "google/cloud/datastore"
243
248
  #
244
249
  # datastore = Google::Cloud::Datastore.new
250
+ #
245
251
  # query = datastore.query "Task"
246
252
  # tasks = datastore.run query
247
253
  # tasks.all.map(&:key).each do |key|
@@ -252,6 +258,7 @@ module Google
252
258
  # require "google/cloud/datastore"
253
259
  #
254
260
  # datastore = Google::Cloud::Datastore.new
261
+ #
255
262
  # query = datastore.query "Task"
256
263
  # tasks = datastore.run query
257
264
  # tasks.all(request_limit: 10) do |task|
@@ -300,6 +307,7 @@ module Google
300
307
  # require "google/cloud/datastore"
301
308
  #
302
309
  # datastore = Google::Cloud::Datastore.new
310
+ #
303
311
  # query = datastore.query "Task"
304
312
  # tasks = datastore.run query
305
313
  # tasks.all_with_cursor do |task, cursor|
@@ -310,14 +318,16 @@ module Google
310
318
  # require "google/cloud/datastore"
311
319
  #
312
320
  # datastore = Google::Cloud::Datastore.new
321
+ #
313
322
  # query = datastore.query "Task"
314
323
  # tasks = datastore.run query
315
- # tasks.all_with_cursor.count #=> number of result/cursor pairs
324
+ # tasks.all_with_cursor.count # number of result/cursor pairs
316
325
  #
317
326
  # @example Limit the number of API calls made:
318
327
  # require "google/cloud/datastore"
319
328
  #
320
329
  # datastore = Google::Cloud::Datastore.new
330
+ #
321
331
  # query = datastore.query "Task"
322
332
  # tasks = datastore.run query
323
333
  # tasks.all_with_cursor(request_limit: 10) do |task, cursor|