google-cloud-firestore-v1 0.4.0 → 0.6.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 (22) hide show
  1. checksums.yaml +4 -4
  2. data/.yardopts +1 -1
  3. data/AUTHENTICATION.md +15 -33
  4. data/README.md +7 -2
  5. data/lib/google/cloud/firestore/v1/firestore/client.rb +432 -152
  6. data/lib/google/cloud/firestore/v1/version.rb +1 -1
  7. data/lib/google/cloud/firestore/v1.rb +2 -0
  8. data/lib/google/firestore/v1/common_pb.rb +1 -1
  9. data/lib/google/firestore/v1/document_pb.rb +1 -1
  10. data/lib/google/firestore/v1/firestore_pb.rb +10 -0
  11. data/lib/google/firestore/v1/firestore_services_pb.rb +1 -1
  12. data/lib/google/firestore/v1/query_pb.rb +2 -1
  13. data/lib/google/firestore/v1/write_pb.rb +1 -1
  14. data/proto_docs/google/api/field_behavior.rb +7 -1
  15. data/proto_docs/google/api/resource.rb +10 -71
  16. data/proto_docs/google/firestore/v1/common.rb +1 -1
  17. data/proto_docs/google/firestore/v1/firestore.rb +16 -3
  18. data/proto_docs/google/firestore/v1/query.rb +5 -2
  19. data/proto_docs/google/firestore/v1/write.rb +2 -1
  20. data/proto_docs/google/protobuf/any.rb +3 -3
  21. data/proto_docs/google/protobuf/struct.rb +2 -2
  22. metadata +13 -7
data/lib/google/cloud/firestore/v1/firestore/client.rb CHANGED
@@ -46,13 +46,12 @@ module Google
46
46
  # See {::Google::Cloud::Firestore::V1::Firestore::Client::Configuration}
47
47
  # for a description of the configuration fields.
48
48
  #
49
- # ## Example
49
+ # @example
50
50
  #
51
- # To modify the configuration for all Firestore clients:
52
- #
53
- # ::Google::Cloud::Firestore::V1::Firestore::Client.configure do |config|
54
- # config.timeout = 10.0
55
- # end
51
+ # # Modify the configuration for all Firestore clients
52
+ # ::Google::Cloud::Firestore::V1::Firestore::Client.configure do |config|
53
+ # config.timeout = 10.0
54
+ # end
56
55
  #
57
56
  # @yield [config] Configure the Client client.
58
57
  # @yieldparam config [Client::Configuration]
@@ -72,116 +71,74 @@ module Google
72
71
 
73
72
  default_config.rpcs.get_document.timeout = 60.0
74
73
  default_config.rpcs.get_document.retry_policy = {
75
- initial_delay: 0.1,
76
- max_delay: 60.0,
77
- multiplier: 1.3,
78
- retry_codes: [14, 13, 4]
74
+ initial_delay: 0.1, max_delay: 60.0, multiplier: 1.3, retry_codes: [8, 14, 13, 4]
79
75
  }
80
76
 
81
77
  default_config.rpcs.list_documents.timeout = 60.0
82
78
  default_config.rpcs.list_documents.retry_policy = {
83
- initial_delay: 0.1,
84
- max_delay: 60.0,
85
- multiplier: 1.3,
86
- retry_codes: [14, 13, 4]
79
+ initial_delay: 0.1, max_delay: 60.0, multiplier: 1.3, retry_codes: [8, 14, 13, 4]
87
80
  }
88
81
 
89
82
  default_config.rpcs.update_document.timeout = 60.0
90
83
  default_config.rpcs.update_document.retry_policy = {
91
- initial_delay: 0.1,
92
- max_delay: 60.0,
93
- multiplier: 1.3,
94
- retry_codes: [14]
84
+ initial_delay: 0.1, max_delay: 60.0, multiplier: 1.3, retry_codes: [8, 14]
95
85
  }
96
86
 
97
87
  default_config.rpcs.delete_document.timeout = 60.0
98
88
  default_config.rpcs.delete_document.retry_policy = {
99
- initial_delay: 0.1,
100
- max_delay: 60.0,
101
- multiplier: 1.3,
102
- retry_codes: [14, 13, 4]
89
+ initial_delay: 0.1, max_delay: 60.0, multiplier: 1.3, retry_codes: [8, 14, 13, 4]
103
90
  }
104
91
 
105
92
  default_config.rpcs.batch_get_documents.timeout = 300.0
106
93
  default_config.rpcs.batch_get_documents.retry_policy = {
107
- initial_delay: 0.1,
108
- max_delay: 60.0,
109
- multiplier: 1.3,
110
- retry_codes: [14, 13, 4]
94
+ initial_delay: 0.1, max_delay: 60.0, multiplier: 1.3, retry_codes: [8, 14, 13, 4]
111
95
  }
112
96
 
113
97
  default_config.rpcs.begin_transaction.timeout = 60.0
114
98
  default_config.rpcs.begin_transaction.retry_policy = {
115
- initial_delay: 0.1,
116
- max_delay: 60.0,
117
- multiplier: 1.3,
118
- retry_codes: [14, 13, 4]
99
+ initial_delay: 0.1, max_delay: 60.0, multiplier: 1.3, retry_codes: [8, 14, 13, 4]
119
100
  }
120
101
 
121
102
  default_config.rpcs.commit.timeout = 60.0
122
103
  default_config.rpcs.commit.retry_policy = {
123
- initial_delay: 0.1,
124
- max_delay: 60.0,
125
- multiplier: 1.3,
126
- retry_codes: [14]
104
+ initial_delay: 0.1, max_delay: 60.0, multiplier: 1.3, retry_codes: [8, 14]
127
105
  }
128
106
 
129
107
  default_config.rpcs.rollback.timeout = 60.0
130
108
  default_config.rpcs.rollback.retry_policy = {
131
- initial_delay: 0.1,
132
- max_delay: 60.0,
133
- multiplier: 1.3,
134
- retry_codes: [14, 13, 4]
109
+ initial_delay: 0.1, max_delay: 60.0, multiplier: 1.3, retry_codes: [8, 14, 13, 4]
135
110
  }
136
111
 
137
112
  default_config.rpcs.run_query.timeout = 300.0
138
113
  default_config.rpcs.run_query.retry_policy = {
139
- initial_delay: 0.1,
140
- max_delay: 60.0,
141
- multiplier: 1.3,
142
- retry_codes: [14, 13, 4]
114
+ initial_delay: 0.1, max_delay: 60.0, multiplier: 1.3, retry_codes: [8, 14, 13, 4]
143
115
  }
144
116
 
145
117
  default_config.rpcs.partition_query.timeout = 300.0
146
118
  default_config.rpcs.partition_query.retry_policy = {
147
- initial_delay: 0.1,
148
- max_delay: 60.0,
149
- multiplier: 1.3,
150
- retry_codes: [14, 13, 4]
119
+ initial_delay: 0.1, max_delay: 60.0, multiplier: 1.3, retry_codes: [8, 14, 13, 4]
151
120
  }
152
121
 
153
122
  default_config.rpcs.write.timeout = 86_400.0
154
123
 
155
124
  default_config.rpcs.listen.timeout = 86_400.0
156
125
  default_config.rpcs.listen.retry_policy = {
157
- initial_delay: 0.1,
158
- max_delay: 60.0,
159
- multiplier: 1.3,
160
- retry_codes: [14, 13, 4]
126
+ initial_delay: 0.1, max_delay: 60.0, multiplier: 1.3, retry_codes: [8, 14, 13, 4]
161
127
  }
162
128
 
163
129
  default_config.rpcs.list_collection_ids.timeout = 60.0
164
130
  default_config.rpcs.list_collection_ids.retry_policy = {
165
- initial_delay: 0.1,
166
- max_delay: 60.0,
167
- multiplier: 1.3,
168
- retry_codes: [14, 13, 4]
131
+ initial_delay: 0.1, max_delay: 60.0, multiplier: 1.3, retry_codes: [8, 14, 13, 4]
169
132
  }
170
133
 
171
134
  default_config.rpcs.batch_write.timeout = 60.0
172
135
  default_config.rpcs.batch_write.retry_policy = {
173
- initial_delay: 0.1,
174
- max_delay: 60.0,
175
- multiplier: 1.3,
176
- retry_codes: [14, 10]
136
+ initial_delay: 0.1, max_delay: 60.0, multiplier: 1.3, retry_codes: [8, 14, 10]
177
137
  }
178
138
 
179
139
  default_config.rpcs.create_document.timeout = 60.0
180
140
  default_config.rpcs.create_document.retry_policy = {
181
- initial_delay: 0.1,
182
- max_delay: 60.0,
183
- multiplier: 1.3,
184
- retry_codes: [14]
141
+ initial_delay: 0.1, max_delay: 60.0, multiplier: 1.3, retry_codes: [8, 14]
185
142
  }
186
143
 
187
144
  default_config
@@ -213,19 +170,15 @@ module Google
213
170
  ##
214
171
  # Create a new Firestore client object.
215
172
  #
216
- # ## Examples
217
- #
218
- # To create a new Firestore client with the default
219
- # configuration:
220
- #
221
- # client = ::Google::Cloud::Firestore::V1::Firestore::Client.new
173
+ # @example
222
174
  #
223
- # To create a new Firestore client with a custom
224
- # configuration:
175
+ # # Create a client using the default configuration
176
+ # client = ::Google::Cloud::Firestore::V1::Firestore::Client.new
225
177
  #
226
- # client = ::Google::Cloud::Firestore::V1::Firestore::Client.new do |config|
227
- # config.timeout = 10.0
228
- # end
178
+ # # Create a client using a custom configuration
179
+ # client = ::Google::Cloud::Firestore::V1::Firestore::Client.new do |config|
180
+ # config.timeout = 10.0
181
+ # end
229
182
  #
230
183
  # @yield [config] Configure the Firestore client.
231
184
  # @yieldparam config [Client::Configuration]
@@ -245,14 +198,13 @@ module Google
245
198
 
246
199
  # Create credentials
247
200
  credentials = @config.credentials
248
- # Use self-signed JWT if the scope and endpoint are unchanged from default,
201
+ # Use self-signed JWT if the endpoint is unchanged from default,
249
202
  # but only if the default endpoint does not have a region prefix.
250
- enable_self_signed_jwt = @config.scope == Client.configure.scope &&
251
- @config.endpoint == Client.configure.endpoint &&
203
+ enable_self_signed_jwt = @config.endpoint == Client.configure.endpoint &&
252
204
  !@config.endpoint.split(".").first.include?("-")
253
205
  credentials ||= Credentials.default scope: @config.scope,
254
206
  enable_self_signed_jwt: enable_self_signed_jwt
255
- if credentials.is_a?(String) || credentials.is_a?(Hash)
207
+ if credentials.is_a?(::String) || credentials.is_a?(::Hash)
256
208
  credentials = Credentials.new credentials, scope: @config.scope
257
209
  end
258
210
  @quota_project_id = @config.quota_project
@@ -309,6 +261,21 @@ module Google
309
261
  #
310
262
  # @raise [::Google::Cloud::Error] if the RPC is aborted.
311
263
  #
264
+ # @example Basic example
265
+ # require "google/cloud/firestore/v1"
266
+ #
267
+ # # Create a client object. The client can be reused for multiple calls.
268
+ # client = Google::Cloud::Firestore::V1::Firestore::Client.new
269
+ #
270
+ # # Create a request. To set request fields, pass in keyword arguments.
271
+ # request = Google::Cloud::Firestore::V1::GetDocumentRequest.new
272
+ #
273
+ # # Call the get_document method.
274
+ # result = client.get_document request
275
+ #
276
+ # # The returned object is of type Google::Cloud::Firestore::V1::Document.
277
+ # p result
278
+ #
312
279
  def get_document request, options = nil
313
280
  raise ::ArgumentError, "request must be provided" if request.nil?
314
281
 
@@ -326,16 +293,20 @@ module Google
326
293
  gapic_version: ::Google::Cloud::Firestore::V1::VERSION
327
294
  metadata[:"x-goog-user-project"] = @quota_project_id if @quota_project_id
328
295
 
329
- header_params = {
330
- "name" => request.name
331
- }
296
+ header_params = {}
297
+ if request.name
298
+ header_params["name"] = request.name
299
+ end
300
+
332
301
  request_params_header = header_params.map { |k, v| "#{k}=#{v}" }.join("&")
333
302
  metadata[:"x-goog-request-params"] ||= request_params_header
334
303
 
335
304
  options.apply_defaults timeout: @config.rpcs.get_document.timeout,
336
305
  metadata: metadata,
337
306
  retry_policy: @config.rpcs.get_document.retry_policy
338
- options.apply_defaults metadata: @config.metadata,
307
+
308
+ options.apply_defaults timeout: @config.timeout,
309
+ metadata: @config.metadata,
339
310
  retry_policy: @config.retry_policy
340
311
 
341
312
  @firestore_stub.call_rpc :get_document, request, options: options do |response, operation|
@@ -407,6 +378,27 @@ module Google
407
378
  #
408
379
  # @raise [::Google::Cloud::Error] if the RPC is aborted.
409
380
  #
381
+ # @example Basic example
382
+ # require "google/cloud/firestore/v1"
383
+ #
384
+ # # Create a client object. The client can be reused for multiple calls.
385
+ # client = Google::Cloud::Firestore::V1::Firestore::Client.new
386
+ #
387
+ # # Create a request. To set request fields, pass in keyword arguments.
388
+ # request = Google::Cloud::Firestore::V1::ListDocumentsRequest.new
389
+ #
390
+ # # Call the list_documents method.
391
+ # result = client.list_documents request
392
+ #
393
+ # # The returned object is of type Gapic::PagedEnumerable. You can
394
+ # # iterate over all elements by calling #each, and the enumerable
395
+ # # will lazily make API calls to fetch subsequent pages. Other
396
+ # # methods are also available for managing paging directly.
397
+ # result.each do |response|
398
+ # # Each element is of type ::Google::Cloud::Firestore::V1::Document.
399
+ # p response
400
+ # end
401
+ #
410
402
  def list_documents request, options = nil
411
403
  raise ::ArgumentError, "request must be provided" if request.nil?
412
404
 
@@ -424,17 +416,23 @@ module Google
424
416
  gapic_version: ::Google::Cloud::Firestore::V1::VERSION
425
417
  metadata[:"x-goog-user-project"] = @quota_project_id if @quota_project_id
426
418
 
427
- header_params = {
428
- "parent" => request.parent,
429
- "collection_id" => request.collection_id
430
- }
419
+ header_params = {}
420
+ if request.parent
421
+ header_params["parent"] = request.parent
422
+ end
423
+ if request.collection_id
424
+ header_params["collection_id"] = request.collection_id
425
+ end
426
+
431
427
  request_params_header = header_params.map { |k, v| "#{k}=#{v}" }.join("&")
432
428
  metadata[:"x-goog-request-params"] ||= request_params_header
433
429
 
434
430
  options.apply_defaults timeout: @config.rpcs.list_documents.timeout,
435
431
  metadata: metadata,
436
432
  retry_policy: @config.rpcs.list_documents.retry_policy
437
- options.apply_defaults metadata: @config.metadata,
433
+
434
+ options.apply_defaults timeout: @config.timeout,
435
+ metadata: @config.metadata,
438
436
  retry_policy: @config.retry_policy
439
437
 
440
438
  @firestore_stub.call_rpc :list_documents, request, options: options do |response, operation|
@@ -492,6 +490,21 @@ module Google
492
490
  #
493
491
  # @raise [::Google::Cloud::Error] if the RPC is aborted.
494
492
  #
493
+ # @example Basic example
494
+ # require "google/cloud/firestore/v1"
495
+ #
496
+ # # Create a client object. The client can be reused for multiple calls.
497
+ # client = Google::Cloud::Firestore::V1::Firestore::Client.new
498
+ #
499
+ # # Create a request. To set request fields, pass in keyword arguments.
500
+ # request = Google::Cloud::Firestore::V1::UpdateDocumentRequest.new
501
+ #
502
+ # # Call the update_document method.
503
+ # result = client.update_document request
504
+ #
505
+ # # The returned object is of type Google::Cloud::Firestore::V1::Document.
506
+ # p result
507
+ #
495
508
  def update_document request, options = nil
496
509
  raise ::ArgumentError, "request must be provided" if request.nil?
497
510
 
@@ -509,16 +522,20 @@ module Google
509
522
  gapic_version: ::Google::Cloud::Firestore::V1::VERSION
510
523
  metadata[:"x-goog-user-project"] = @quota_project_id if @quota_project_id
511
524
 
512
- header_params = {
513
- "document.name" => request.document.name
514
- }
525
+ header_params = {}
526
+ if request.document&.name
527
+ header_params["document.name"] = request.document.name
528
+ end
529
+
515
530
  request_params_header = header_params.map { |k, v| "#{k}=#{v}" }.join("&")
516
531
  metadata[:"x-goog-request-params"] ||= request_params_header
517
532
 
518
533
  options.apply_defaults timeout: @config.rpcs.update_document.timeout,
519
534
  metadata: metadata,
520
535
  retry_policy: @config.rpcs.update_document.retry_policy
521
- options.apply_defaults metadata: @config.metadata,
536
+
537
+ options.apply_defaults timeout: @config.timeout,
538
+ metadata: @config.metadata,
522
539
  retry_policy: @config.retry_policy
523
540
 
524
541
  @firestore_stub.call_rpc :update_document, request, options: options do |response, operation|
@@ -562,6 +579,21 @@ module Google
562
579
  #
563
580
  # @raise [::Google::Cloud::Error] if the RPC is aborted.
564
581
  #
582
+ # @example Basic example
583
+ # require "google/cloud/firestore/v1"
584
+ #
585
+ # # Create a client object. The client can be reused for multiple calls.
586
+ # client = Google::Cloud::Firestore::V1::Firestore::Client.new
587
+ #
588
+ # # Create a request. To set request fields, pass in keyword arguments.
589
+ # request = Google::Cloud::Firestore::V1::DeleteDocumentRequest.new
590
+ #
591
+ # # Call the delete_document method.
592
+ # result = client.delete_document request
593
+ #
594
+ # # The returned object is of type Google::Protobuf::Empty.
595
+ # p result
596
+ #
565
597
  def delete_document request, options = nil
566
598
  raise ::ArgumentError, "request must be provided" if request.nil?
567
599
 
@@ -579,16 +611,20 @@ module Google
579
611
  gapic_version: ::Google::Cloud::Firestore::V1::VERSION
580
612
  metadata[:"x-goog-user-project"] = @quota_project_id if @quota_project_id
581
613
 
582
- header_params = {
583
- "name" => request.name
584
- }
614
+ header_params = {}
615
+ if request.name
616
+ header_params["name"] = request.name
617
+ end
618
+
585
619
  request_params_header = header_params.map { |k, v| "#{k}=#{v}" }.join("&")
586
620
  metadata[:"x-goog-request-params"] ||= request_params_header
587
621
 
588
622
  options.apply_defaults timeout: @config.rpcs.delete_document.timeout,
589
623
  metadata: metadata,
590
624
  retry_policy: @config.rpcs.delete_document.retry_policy
591
- options.apply_defaults metadata: @config.metadata,
625
+
626
+ options.apply_defaults timeout: @config.timeout,
627
+ metadata: @config.metadata,
592
628
  retry_policy: @config.retry_policy
593
629
 
594
630
  @firestore_stub.call_rpc :delete_document, request, options: options do |response, operation|
@@ -652,6 +688,24 @@ module Google
652
688
  #
653
689
  # @raise [::Google::Cloud::Error] if the RPC is aborted.
654
690
  #
691
+ # @example Basic example
692
+ # require "google/cloud/firestore/v1"
693
+ #
694
+ # # Create a client object. The client can be reused for multiple calls.
695
+ # client = Google::Cloud::Firestore::V1::Firestore::Client.new
696
+ #
697
+ # # Create a request. To set request fields, pass in keyword arguments.
698
+ # request = Google::Cloud::Firestore::V1::BatchGetDocumentsRequest.new
699
+ #
700
+ # # Call the batch_get_documents method.
701
+ # result = client.batch_get_documents request
702
+ #
703
+ # # The returned object is a streamed enumerable yielding elements of
704
+ # # type ::Google::Cloud::Firestore::V1::BatchGetDocumentsResponse.
705
+ # result.each do |response|
706
+ # p response
707
+ # end
708
+ #
655
709
  def batch_get_documents request, options = nil
656
710
  raise ::ArgumentError, "request must be provided" if request.nil?
657
711
 
@@ -669,16 +723,20 @@ module Google
669
723
  gapic_version: ::Google::Cloud::Firestore::V1::VERSION
670
724
  metadata[:"x-goog-user-project"] = @quota_project_id if @quota_project_id
671
725
 
672
- header_params = {
673
- "database" => request.database
674
- }
726
+ header_params = {}
727
+ if request.database
728
+ header_params["database"] = request.database
729
+ end
730
+
675
731
  request_params_header = header_params.map { |k, v| "#{k}=#{v}" }.join("&")
676
732
  metadata[:"x-goog-request-params"] ||= request_params_header
677
733
 
678
734
  options.apply_defaults timeout: @config.rpcs.batch_get_documents.timeout,
679
735
  metadata: metadata,
680
736
  retry_policy: @config.rpcs.batch_get_documents.retry_policy
681
- options.apply_defaults metadata: @config.metadata,
737
+
738
+ options.apply_defaults timeout: @config.timeout,
739
+ metadata: @config.metadata,
682
740
  retry_policy: @config.retry_policy
683
741
 
684
742
  @firestore_stub.call_rpc :batch_get_documents, request, options: options do |response, operation|
@@ -722,6 +780,21 @@ module Google
722
780
  #
723
781
  # @raise [::Google::Cloud::Error] if the RPC is aborted.
724
782
  #
783
+ # @example Basic example
784
+ # require "google/cloud/firestore/v1"
785
+ #
786
+ # # Create a client object. The client can be reused for multiple calls.
787
+ # client = Google::Cloud::Firestore::V1::Firestore::Client.new
788
+ #
789
+ # # Create a request. To set request fields, pass in keyword arguments.
790
+ # request = Google::Cloud::Firestore::V1::BeginTransactionRequest.new
791
+ #
792
+ # # Call the begin_transaction method.
793
+ # result = client.begin_transaction request
794
+ #
795
+ # # The returned object is of type Google::Cloud::Firestore::V1::BeginTransactionResponse.
796
+ # p result
797
+ #
725
798
  def begin_transaction request, options = nil
726
799
  raise ::ArgumentError, "request must be provided" if request.nil?
727
800
 
@@ -739,16 +812,20 @@ module Google
739
812
  gapic_version: ::Google::Cloud::Firestore::V1::VERSION
740
813
  metadata[:"x-goog-user-project"] = @quota_project_id if @quota_project_id
741
814
 
742
- header_params = {
743
- "database" => request.database
744
- }
815
+ header_params = {}
816
+ if request.database
817
+ header_params["database"] = request.database
818
+ end
819
+
745
820
  request_params_header = header_params.map { |k, v| "#{k}=#{v}" }.join("&")
746
821
  metadata[:"x-goog-request-params"] ||= request_params_header
747
822
 
748
823
  options.apply_defaults timeout: @config.rpcs.begin_transaction.timeout,
749
824
  metadata: metadata,
750
825
  retry_policy: @config.rpcs.begin_transaction.retry_policy
751
- options.apply_defaults metadata: @config.metadata,
826
+
827
+ options.apply_defaults timeout: @config.timeout,
828
+ metadata: @config.metadata,
752
829
  retry_policy: @config.retry_policy
753
830
 
754
831
  @firestore_stub.call_rpc :begin_transaction, request, options: options do |response, operation|
@@ -795,6 +872,21 @@ module Google
795
872
  #
796
873
  # @raise [::Google::Cloud::Error] if the RPC is aborted.
797
874
  #
875
+ # @example Basic example
876
+ # require "google/cloud/firestore/v1"
877
+ #
878
+ # # Create a client object. The client can be reused for multiple calls.
879
+ # client = Google::Cloud::Firestore::V1::Firestore::Client.new
880
+ #
881
+ # # Create a request. To set request fields, pass in keyword arguments.
882
+ # request = Google::Cloud::Firestore::V1::CommitRequest.new
883
+ #
884
+ # # Call the commit method.
885
+ # result = client.commit request
886
+ #
887
+ # # The returned object is of type Google::Cloud::Firestore::V1::CommitResponse.
888
+ # p result
889
+ #
798
890
  def commit request, options = nil
799
891
  raise ::ArgumentError, "request must be provided" if request.nil?
800
892
 
@@ -812,16 +904,20 @@ module Google
812
904
  gapic_version: ::Google::Cloud::Firestore::V1::VERSION
813
905
  metadata[:"x-goog-user-project"] = @quota_project_id if @quota_project_id
814
906
 
815
- header_params = {
816
- "database" => request.database
817
- }
907
+ header_params = {}
908
+ if request.database
909
+ header_params["database"] = request.database
910
+ end
911
+
818
912
  request_params_header = header_params.map { |k, v| "#{k}=#{v}" }.join("&")
819
913
  metadata[:"x-goog-request-params"] ||= request_params_header
820
914
 
821
915
  options.apply_defaults timeout: @config.rpcs.commit.timeout,
822
916
  metadata: metadata,
823
917
  retry_policy: @config.rpcs.commit.retry_policy
824
- options.apply_defaults metadata: @config.metadata,
918
+
919
+ options.apply_defaults timeout: @config.timeout,
920
+ metadata: @config.metadata,
825
921
  retry_policy: @config.retry_policy
826
922
 
827
923
  @firestore_stub.call_rpc :commit, request, options: options do |response, operation|
@@ -864,6 +960,21 @@ module Google
864
960
  #
865
961
  # @raise [::Google::Cloud::Error] if the RPC is aborted.
866
962
  #
963
+ # @example Basic example
964
+ # require "google/cloud/firestore/v1"
965
+ #
966
+ # # Create a client object. The client can be reused for multiple calls.
967
+ # client = Google::Cloud::Firestore::V1::Firestore::Client.new
968
+ #
969
+ # # Create a request. To set request fields, pass in keyword arguments.
970
+ # request = Google::Cloud::Firestore::V1::RollbackRequest.new
971
+ #
972
+ # # Call the rollback method.
973
+ # result = client.rollback request
974
+ #
975
+ # # The returned object is of type Google::Protobuf::Empty.
976
+ # p result
977
+ #
867
978
  def rollback request, options = nil
868
979
  raise ::ArgumentError, "request must be provided" if request.nil?
869
980
 
@@ -881,16 +992,20 @@ module Google
881
992
  gapic_version: ::Google::Cloud::Firestore::V1::VERSION
882
993
  metadata[:"x-goog-user-project"] = @quota_project_id if @quota_project_id
883
994
 
884
- header_params = {
885
- "database" => request.database
886
- }
995
+ header_params = {}
996
+ if request.database
997
+ header_params["database"] = request.database
998
+ end
999
+
887
1000
  request_params_header = header_params.map { |k, v| "#{k}=#{v}" }.join("&")
888
1001
  metadata[:"x-goog-request-params"] ||= request_params_header
889
1002
 
890
1003
  options.apply_defaults timeout: @config.rpcs.rollback.timeout,
891
1004
  metadata: metadata,
892
1005
  retry_policy: @config.rpcs.rollback.retry_policy
893
- options.apply_defaults metadata: @config.metadata,
1006
+
1007
+ options.apply_defaults timeout: @config.timeout,
1008
+ metadata: @config.metadata,
894
1009
  retry_policy: @config.retry_policy
895
1010
 
896
1011
  @firestore_stub.call_rpc :rollback, request, options: options do |response, operation|
@@ -929,7 +1044,9 @@ module Google
929
1044
  # @param structured_query [::Google::Cloud::Firestore::V1::StructuredQuery, ::Hash]
930
1045
  # A structured query.
931
1046
  # @param transaction [::String]
932
- # Reads documents in a transaction.
1047
+ # Run the query within an already active transaction.
1048
+ #
1049
+ # The value here is the opaque transaction ID to execute the query in.
933
1050
  # @param new_transaction [::Google::Cloud::Firestore::V1::TransactionOptions, ::Hash]
934
1051
  # Starts a new transaction and reads the documents.
935
1052
  # Defaults to a read-only transaction.
@@ -947,6 +1064,24 @@ module Google
947
1064
  #
948
1065
  # @raise [::Google::Cloud::Error] if the RPC is aborted.
949
1066
  #
1067
+ # @example Basic example
1068
+ # require "google/cloud/firestore/v1"
1069
+ #
1070
+ # # Create a client object. The client can be reused for multiple calls.
1071
+ # client = Google::Cloud::Firestore::V1::Firestore::Client.new
1072
+ #
1073
+ # # Create a request. To set request fields, pass in keyword arguments.
1074
+ # request = Google::Cloud::Firestore::V1::RunQueryRequest.new
1075
+ #
1076
+ # # Call the run_query method.
1077
+ # result = client.run_query request
1078
+ #
1079
+ # # The returned object is a streamed enumerable yielding elements of
1080
+ # # type ::Google::Cloud::Firestore::V1::RunQueryResponse.
1081
+ # result.each do |response|
1082
+ # p response
1083
+ # end
1084
+ #
950
1085
  def run_query request, options = nil
951
1086
  raise ::ArgumentError, "request must be provided" if request.nil?
952
1087
 
@@ -964,16 +1099,20 @@ module Google
964
1099
  gapic_version: ::Google::Cloud::Firestore::V1::VERSION
965
1100
  metadata[:"x-goog-user-project"] = @quota_project_id if @quota_project_id
966
1101
 
967
- header_params = {
968
- "parent" => request.parent
969
- }
1102
+ header_params = {}
1103
+ if request.parent
1104
+ header_params["parent"] = request.parent
1105
+ end
1106
+
970
1107
  request_params_header = header_params.map { |k, v| "#{k}=#{v}" }.join("&")
971
1108
  metadata[:"x-goog-request-params"] ||= request_params_header
972
1109
 
973
1110
  options.apply_defaults timeout: @config.rpcs.run_query.timeout,
974
1111
  metadata: metadata,
975
1112
  retry_policy: @config.rpcs.run_query.retry_policy
976
- options.apply_defaults metadata: @config.metadata,
1113
+
1114
+ options.apply_defaults timeout: @config.timeout,
1115
+ metadata: @config.metadata,
977
1116
  retry_policy: @config.retry_policy
978
1117
 
979
1118
  @firestore_stub.call_rpc :run_query, request, options: options do |response, operation|
@@ -999,7 +1138,7 @@ module Google
999
1138
  # @param options [::Gapic::CallOptions, ::Hash]
1000
1139
  # Overrides the default settings for this call, e.g, timeout, retries, etc. Optional.
1001
1140
  #
1002
- # @overload partition_query(parent: nil, structured_query: nil, partition_count: nil, page_token: nil, page_size: nil)
1141
+ # @overload partition_query(parent: nil, structured_query: nil, partition_count: nil, page_token: nil, page_size: nil, read_time: nil)
1003
1142
  # Pass arguments to `partition_query` via keyword arguments. Note that at
1004
1143
  # least one keyword argument is required. To specify no parameters, or to keep all
1005
1144
  # the default parameter values, pass an empty Hash as a request object (see above).
@@ -1045,6 +1184,9 @@ module Google
1045
1184
  # to PartitionQuery will return up to 8 partitions and a `next_page_token`
1046
1185
  # if more results exist. A second call to PartitionQuery will return up to
1047
1186
  # 2 partitions, to complete the total of 10 specified in `partition_count`.
1187
+ # @param read_time [::Google::Protobuf::Timestamp, ::Hash]
1188
+ # Reads documents as they were at the given time.
1189
+ # This may not be older than 270 seconds.
1048
1190
  #
1049
1191
  # @yield [response, operation] Access the result along with the RPC operation
1050
1192
  # @yieldparam response [::Gapic::PagedEnumerable<::Google::Cloud::Firestore::V1::Cursor>]
@@ -1054,6 +1196,27 @@ module Google
1054
1196
  #
1055
1197
  # @raise [::Google::Cloud::Error] if the RPC is aborted.
1056
1198
  #
1199
+ # @example Basic example
1200
+ # require "google/cloud/firestore/v1"
1201
+ #
1202
+ # # Create a client object. The client can be reused for multiple calls.
1203
+ # client = Google::Cloud::Firestore::V1::Firestore::Client.new
1204
+ #
1205
+ # # Create a request. To set request fields, pass in keyword arguments.
1206
+ # request = Google::Cloud::Firestore::V1::PartitionQueryRequest.new
1207
+ #
1208
+ # # Call the partition_query method.
1209
+ # result = client.partition_query request
1210
+ #
1211
+ # # The returned object is of type Gapic::PagedEnumerable. You can
1212
+ # # iterate over all elements by calling #each, and the enumerable
1213
+ # # will lazily make API calls to fetch subsequent pages. Other
1214
+ # # methods are also available for managing paging directly.
1215
+ # result.each do |response|
1216
+ # # Each element is of type ::Google::Cloud::Firestore::V1::Cursor.
1217
+ # p response
1218
+ # end
1219
+ #
1057
1220
  def partition_query request, options = nil
1058
1221
  raise ::ArgumentError, "request must be provided" if request.nil?
1059
1222
 
@@ -1071,16 +1234,20 @@ module Google
1071
1234
  gapic_version: ::Google::Cloud::Firestore::V1::VERSION
1072
1235
  metadata[:"x-goog-user-project"] = @quota_project_id if @quota_project_id
1073
1236
 
1074
- header_params = {
1075
- "parent" => request.parent
1076
- }
1237
+ header_params = {}
1238
+ if request.parent
1239
+ header_params["parent"] = request.parent
1240
+ end
1241
+
1077
1242
  request_params_header = header_params.map { |k, v| "#{k}=#{v}" }.join("&")
1078
1243
  metadata[:"x-goog-request-params"] ||= request_params_header
1079
1244
 
1080
1245
  options.apply_defaults timeout: @config.rpcs.partition_query.timeout,
1081
1246
  metadata: metadata,
1082
1247
  retry_policy: @config.rpcs.partition_query.retry_policy
1083
- options.apply_defaults metadata: @config.metadata,
1248
+
1249
+ options.apply_defaults timeout: @config.timeout,
1250
+ metadata: @config.metadata,
1084
1251
  retry_policy: @config.retry_policy
1085
1252
 
1086
1253
  @firestore_stub.call_rpc :partition_query, request, options: options do |response, operation|
@@ -1108,6 +1275,30 @@ module Google
1108
1275
  #
1109
1276
  # @raise [::Google::Cloud::Error] if the RPC is aborted.
1110
1277
  #
1278
+ # @example Basic example
1279
+ # require "google/cloud/firestore/v1"
1280
+ #
1281
+ # # Create a client object. The client can be reused for multiple calls.
1282
+ # client = Google::Cloud::Firestore::V1::Firestore::Client.new
1283
+ #
1284
+ # # Create an input stream
1285
+ # input = Gapic::StreamInput.new
1286
+ #
1287
+ # # Call the write method to start streaming.
1288
+ # output = client.write input
1289
+ #
1290
+ # # Send requests on the stream. For each request, pass in keyword
1291
+ # # arguments to set fields. Be sure to close the stream when done.
1292
+ # input << Google::Cloud::Firestore::V1::WriteRequest.new
1293
+ # input << Google::Cloud::Firestore::V1::WriteRequest.new
1294
+ # input.close
1295
+ #
1296
+ # # Handle streamed responses. These may be interleaved with inputs.
1297
+ # # Each response is of type ::Google::Cloud::Firestore::V1::WriteResponse.
1298
+ # output.each do |response|
1299
+ # p response
1300
+ # end
1301
+ #
1111
1302
  def write request, options = nil
1112
1303
  unless request.is_a? ::Enumerable
1113
1304
  raise ::ArgumentError, "request must be an Enumerable" unless request.respond_to? :to_enum
@@ -1133,7 +1324,9 @@ module Google
1133
1324
  options.apply_defaults timeout: @config.rpcs.write.timeout,
1134
1325
  metadata: metadata,
1135
1326
  retry_policy: @config.rpcs.write.retry_policy
1136
- options.apply_defaults metadata: @config.metadata,
1327
+
1328
+ options.apply_defaults timeout: @config.timeout,
1329
+ metadata: @config.metadata,
1137
1330
  retry_policy: @config.retry_policy
1138
1331
 
1139
1332
  @firestore_stub.call_rpc :write, request, options: options do |response, operation|
@@ -1160,6 +1353,30 @@ module Google
1160
1353
  #
1161
1354
  # @raise [::Google::Cloud::Error] if the RPC is aborted.
1162
1355
  #
1356
+ # @example Basic example
1357
+ # require "google/cloud/firestore/v1"
1358
+ #
1359
+ # # Create a client object. The client can be reused for multiple calls.
1360
+ # client = Google::Cloud::Firestore::V1::Firestore::Client.new
1361
+ #
1362
+ # # Create an input stream
1363
+ # input = Gapic::StreamInput.new
1364
+ #
1365
+ # # Call the listen method to start streaming.
1366
+ # output = client.listen input
1367
+ #
1368
+ # # Send requests on the stream. For each request, pass in keyword
1369
+ # # arguments to set fields. Be sure to close the stream when done.
1370
+ # input << Google::Cloud::Firestore::V1::ListenRequest.new
1371
+ # input << Google::Cloud::Firestore::V1::ListenRequest.new
1372
+ # input.close
1373
+ #
1374
+ # # Handle streamed responses. These may be interleaved with inputs.
1375
+ # # Each response is of type ::Google::Cloud::Firestore::V1::ListenResponse.
1376
+ # output.each do |response|
1377
+ # p response
1378
+ # end
1379
+ #
1163
1380
  def listen request, options = nil
1164
1381
  unless request.is_a? ::Enumerable
1165
1382
  raise ::ArgumentError, "request must be an Enumerable" unless request.respond_to? :to_enum
@@ -1185,7 +1402,9 @@ module Google
1185
1402
  options.apply_defaults timeout: @config.rpcs.listen.timeout,
1186
1403
  metadata: metadata,
1187
1404
  retry_policy: @config.rpcs.listen.retry_policy
1188
- options.apply_defaults metadata: @config.metadata,
1405
+
1406
+ options.apply_defaults timeout: @config.timeout,
1407
+ metadata: @config.metadata,
1189
1408
  retry_policy: @config.retry_policy
1190
1409
 
1191
1410
  @firestore_stub.call_rpc :listen, request, options: options do |response, operation|
@@ -1209,7 +1428,7 @@ module Google
1209
1428
  # @param options [::Gapic::CallOptions, ::Hash]
1210
1429
  # Overrides the default settings for this call, e.g, timeout, retries, etc. Optional.
1211
1430
  #
1212
- # @overload list_collection_ids(parent: nil, page_size: nil, page_token: nil)
1431
+ # @overload list_collection_ids(parent: nil, page_size: nil, page_token: nil, read_time: nil)
1213
1432
  # Pass arguments to `list_collection_ids` via keyword arguments. Note that at
1214
1433
  # least one keyword argument is required. To specify no parameters, or to keep all
1215
1434
  # the default parameter values, pass an empty Hash as a request object (see above).
@@ -1224,6 +1443,9 @@ module Google
1224
1443
  # @param page_token [::String]
1225
1444
  # A page token. Must be a value from
1226
1445
  # {::Google::Cloud::Firestore::V1::ListCollectionIdsResponse ListCollectionIdsResponse}.
1446
+ # @param read_time [::Google::Protobuf::Timestamp, ::Hash]
1447
+ # Reads documents as they were at the given time.
1448
+ # This may not be older than 270 seconds.
1227
1449
  #
1228
1450
  # @yield [response, operation] Access the result along with the RPC operation
1229
1451
  # @yieldparam response [::Google::Cloud::Firestore::V1::ListCollectionIdsResponse]
@@ -1233,6 +1455,21 @@ module Google
1233
1455
  #
1234
1456
  # @raise [::Google::Cloud::Error] if the RPC is aborted.
1235
1457
  #
1458
+ # @example Basic example
1459
+ # require "google/cloud/firestore/v1"
1460
+ #
1461
+ # # Create a client object. The client can be reused for multiple calls.
1462
+ # client = Google::Cloud::Firestore::V1::Firestore::Client.new
1463
+ #
1464
+ # # Create a request. To set request fields, pass in keyword arguments.
1465
+ # request = Google::Cloud::Firestore::V1::ListCollectionIdsRequest.new
1466
+ #
1467
+ # # Call the list_collection_ids method.
1468
+ # result = client.list_collection_ids request
1469
+ #
1470
+ # # The returned object is of type Google::Cloud::Firestore::V1::ListCollectionIdsResponse.
1471
+ # p result
1472
+ #
1236
1473
  def list_collection_ids request, options = nil
1237
1474
  raise ::ArgumentError, "request must be provided" if request.nil?
1238
1475
 
@@ -1250,16 +1487,20 @@ module Google
1250
1487
  gapic_version: ::Google::Cloud::Firestore::V1::VERSION
1251
1488
  metadata[:"x-goog-user-project"] = @quota_project_id if @quota_project_id
1252
1489
 
1253
- header_params = {
1254
- "parent" => request.parent
1255
- }
1490
+ header_params = {}
1491
+ if request.parent
1492
+ header_params["parent"] = request.parent
1493
+ end
1494
+
1256
1495
  request_params_header = header_params.map { |k, v| "#{k}=#{v}" }.join("&")
1257
1496
  metadata[:"x-goog-request-params"] ||= request_params_header
1258
1497
 
1259
1498
  options.apply_defaults timeout: @config.rpcs.list_collection_ids.timeout,
1260
1499
  metadata: metadata,
1261
1500
  retry_policy: @config.rpcs.list_collection_ids.retry_policy
1262
- options.apply_defaults metadata: @config.metadata,
1501
+
1502
+ options.apply_defaults timeout: @config.timeout,
1503
+ metadata: @config.metadata,
1263
1504
  retry_policy: @config.retry_policy
1264
1505
 
1265
1506
  @firestore_stub.call_rpc :list_collection_ids, request, options: options do |response, operation|
@@ -1316,6 +1557,21 @@ module Google
1316
1557
  #
1317
1558
  # @raise [::Google::Cloud::Error] if the RPC is aborted.
1318
1559
  #
1560
+ # @example Basic example
1561
+ # require "google/cloud/firestore/v1"
1562
+ #
1563
+ # # Create a client object. The client can be reused for multiple calls.
1564
+ # client = Google::Cloud::Firestore::V1::Firestore::Client.new
1565
+ #
1566
+ # # Create a request. To set request fields, pass in keyword arguments.
1567
+ # request = Google::Cloud::Firestore::V1::BatchWriteRequest.new
1568
+ #
1569
+ # # Call the batch_write method.
1570
+ # result = client.batch_write request
1571
+ #
1572
+ # # The returned object is of type Google::Cloud::Firestore::V1::BatchWriteResponse.
1573
+ # p result
1574
+ #
1319
1575
  def batch_write request, options = nil
1320
1576
  raise ::ArgumentError, "request must be provided" if request.nil?
1321
1577
 
@@ -1333,16 +1589,20 @@ module Google
1333
1589
  gapic_version: ::Google::Cloud::Firestore::V1::VERSION
1334
1590
  metadata[:"x-goog-user-project"] = @quota_project_id if @quota_project_id
1335
1591
 
1336
- header_params = {
1337
- "database" => request.database
1338
- }
1592
+ header_params = {}
1593
+ if request.database
1594
+ header_params["database"] = request.database
1595
+ end
1596
+
1339
1597
  request_params_header = header_params.map { |k, v| "#{k}=#{v}" }.join("&")
1340
1598
  metadata[:"x-goog-request-params"] ||= request_params_header
1341
1599
 
1342
1600
  options.apply_defaults timeout: @config.rpcs.batch_write.timeout,
1343
1601
  metadata: metadata,
1344
1602
  retry_policy: @config.rpcs.batch_write.retry_policy
1345
- options.apply_defaults metadata: @config.metadata,
1603
+
1604
+ options.apply_defaults timeout: @config.timeout,
1605
+ metadata: @config.metadata,
1346
1606
  retry_policy: @config.retry_policy
1347
1607
 
1348
1608
  @firestore_stub.call_rpc :batch_write, request, options: options do |response, operation|
@@ -1397,6 +1657,21 @@ module Google
1397
1657
  #
1398
1658
  # @raise [::Google::Cloud::Error] if the RPC is aborted.
1399
1659
  #
1660
+ # @example Basic example
1661
+ # require "google/cloud/firestore/v1"
1662
+ #
1663
+ # # Create a client object. The client can be reused for multiple calls.
1664
+ # client = Google::Cloud::Firestore::V1::Firestore::Client.new
1665
+ #
1666
+ # # Create a request. To set request fields, pass in keyword arguments.
1667
+ # request = Google::Cloud::Firestore::V1::CreateDocumentRequest.new
1668
+ #
1669
+ # # Call the create_document method.
1670
+ # result = client.create_document request
1671
+ #
1672
+ # # The returned object is of type Google::Cloud::Firestore::V1::Document.
1673
+ # p result
1674
+ #
1400
1675
  def create_document request, options = nil
1401
1676
  raise ::ArgumentError, "request must be provided" if request.nil?
1402
1677
 
@@ -1414,17 +1689,23 @@ module Google
1414
1689
  gapic_version: ::Google::Cloud::Firestore::V1::VERSION
1415
1690
  metadata[:"x-goog-user-project"] = @quota_project_id if @quota_project_id
1416
1691
 
1417
- header_params = {
1418
- "parent" => request.parent,
1419
- "collection_id" => request.collection_id
1420
- }
1692
+ header_params = {}
1693
+ if request.parent
1694
+ header_params["parent"] = request.parent
1695
+ end
1696
+ if request.collection_id
1697
+ header_params["collection_id"] = request.collection_id
1698
+ end
1699
+
1421
1700
  request_params_header = header_params.map { |k, v| "#{k}=#{v}" }.join("&")
1422
1701
  metadata[:"x-goog-request-params"] ||= request_params_header
1423
1702
 
1424
1703
  options.apply_defaults timeout: @config.rpcs.create_document.timeout,
1425
1704
  metadata: metadata,
1426
1705
  retry_policy: @config.rpcs.create_document.retry_policy
1427
- options.apply_defaults metadata: @config.metadata,
1706
+
1707
+ options.apply_defaults timeout: @config.timeout,
1708
+ metadata: @config.metadata,
1428
1709
  retry_policy: @config.retry_policy
1429
1710
 
1430
1711
  @firestore_stub.call_rpc :create_document, request, options: options do |response, operation|
@@ -1448,22 +1729,21 @@ module Google
1448
1729
  # Configuration can be applied globally to all clients, or to a single client
1449
1730
  # on construction.
1450
1731
  #
1451
- # # Examples
1452
- #
1453
- # To modify the global config, setting the timeout for get_document
1454
- # to 20 seconds, and all remaining timeouts to 10 seconds:
1455
- #
1456
- # ::Google::Cloud::Firestore::V1::Firestore::Client.configure do |config|
1457
- # config.timeout = 10.0
1458
- # config.rpcs.get_document.timeout = 20.0
1459
- # end
1460
- #
1461
- # To apply the above configuration only to a new client:
1462
- #
1463
- # client = ::Google::Cloud::Firestore::V1::Firestore::Client.new do |config|
1464
- # config.timeout = 10.0
1465
- # config.rpcs.get_document.timeout = 20.0
1466
- # end
1732
+ # @example
1733
+ #
1734
+ # # Modify the global config, setting the timeout for
1735
+ # # get_document to 20 seconds,
1736
+ # # and all remaining timeouts to 10 seconds.
1737
+ # ::Google::Cloud::Firestore::V1::Firestore::Client.configure do |config|
1738
+ # config.timeout = 10.0
1739
+ # config.rpcs.get_document.timeout = 20.0
1740
+ # end
1741
+ #
1742
+ # # Apply the above configuration only to a new client.
1743
+ # client = ::Google::Cloud::Firestore::V1::Firestore::Client.new do |config|
1744
+ # config.timeout = 10.0
1745
+ # config.rpcs.get_document.timeout = 20.0
1746
+ # end
1467
1747
  #
1468
1748
  # @!attribute [rw] endpoint
1469
1749
  # The hostname or hostname:port of the service endpoint.