lib/google/cloud/firestore/v1/firestore/client.rb in google-cloud-firestore-v1-0.8.0 vs lib/google/cloud/firestore/v1/firestore/client.rb in google-cloud-firestore-v1-0.9.0

- old
+ new

@@ -32,12 +32,12 @@ # # Cloud Firestore is a fast, fully managed, serverless, cloud-native NoSQL # document database that simplifies storing, syncing, and querying data for # your mobile, web, and IoT apps at global scale. Its client libraries provide # live synchronization and offline support, while its security features and - # integrations with Firebase and Google Cloud Platform (GCP) accelerate - # building truly serverless apps. + # integrations with Firebase and Google Cloud Platform accelerate building + # truly serverless apps. # class Client # @private attr_reader :firestore_stub @@ -356,41 +356,61 @@ # # @param parent [::String] # Required. The parent resource name. In the format: # `projects/{project_id}/databases/{database_id}/documents` or # `projects/{project_id}/databases/{database_id}/documents/{document_path}`. + # # For example: # `projects/my-project/databases/my-database/documents` or # `projects/my-project/databases/my-database/documents/chatrooms/my-chatroom` # @param collection_id [::String] - # Required. The collection ID, relative to `parent`, to list. For example: `chatrooms` - # or `messages`. + # Optional. The collection ID, relative to `parent`, to list. + # + # For example: `chatrooms` or `messages`. + # + # This is optional, and when not provided, Firestore will list documents + # from all collections under the provided `parent`. # @param page_size [::Integer] - # The maximum number of documents to return. + # Optional. The maximum number of documents to return in a single response. + # + # Firestore may return fewer than this value. # @param page_token [::String] - # The `next_page_token` value returned from a previous List request, if any. + # Optional. A page token, received from a previous `ListDocuments` response. + # + # Provide this to retrieve the subsequent page. When paginating, all other + # parameters (with the exception of `page_size`) must match the values set + # in the request that generated the page token. # @param order_by [::String] - # The order to sort results by. For example: `priority desc, name`. + # Optional. The optional ordering of the documents to return. + # + # For example: `priority desc, __name__ desc`. + # + # This mirrors the {::Google::Cloud::Firestore::V1::StructuredQuery#order_by `ORDER BY`} + # used in Firestore queries but in a string representation. When absent, + # documents are ordered based on `__name__ ASC`. # @param mask [::Google::Cloud::Firestore::V1::DocumentMask, ::Hash] - # The fields to return. If not set, returns all fields. + # Optional. The fields to return. If not set, returns all fields. # # If a document has a field that is not present in this mask, that field # will not be returned in the response. # @param transaction [::String] - # Reads documents in a transaction. + # Perform the read as part of an already active transaction. # @param read_time [::Google::Protobuf::Timestamp, ::Hash] - # Reads documents as they were at the given time. + # Perform the read at the provided time. + # # This may not be older than 270 seconds. # @param show_missing [::Boolean] - # If the list should show missing documents. A missing document is a - # document that does not exist but has sub-documents. These documents will - # be returned with a key but will not have fields, {::Google::Cloud::Firestore::V1::Document#create_time Document.create_time}, - # or {::Google::Cloud::Firestore::V1::Document#update_time Document.update_time} set. + # If the list should show missing documents. # - # Requests with `show_missing` may not specify `where` or - # `order_by`. + # A document is missing if it does not exist, but there are sub-documents + # nested underneath it. When true, such missing documents will be returned + # with a key but will not have fields, + # {::Google::Cloud::Firestore::V1::Document#create_time `create_time`}, or + # {::Google::Cloud::Firestore::V1::Document#update_time `update_time`} set. # + # Requests with `show_missing` may not specify `where` or `order_by`. + # # @yield [response, operation] Access the result along with the RPC operation # @yieldparam response [::Gapic::PagedEnumerable<::Google::Cloud::Firestore::V1::Document>] # @yieldparam operation [::GRPC::ActiveCall::Operation] # # @return [::Gapic::PagedEnumerable<::Google::Cloud::Firestore::V1::Document>] @@ -407,17 +427,15 @@ # request = Google::Cloud::Firestore::V1::ListDocumentsRequest.new # # # Call the list_documents method. # result = client.list_documents request # - # # The returned object is of type Gapic::PagedEnumerable. You can - # # iterate over all elements by calling #each, and the enumerable - # # will lazily make API calls to fetch subsequent pages. Other - # # methods are also available for managing paging directly. - # result.each do |response| + # # The returned object is of type Gapic::PagedEnumerable. You can iterate + # # over elements, and API calls will be issued to fetch pages as needed. + # result.each do |item| # # Each element is of type ::Google::Cloud::Firestore::V1::Document. - # p response + # p item # end # def list_documents request, options = nil raise ::ArgumentError, "request must be provided" if request.nil? @@ -714,17 +732,17 @@ # client = Google::Cloud::Firestore::V1::Firestore::Client.new # # # Create a request. To set request fields, pass in keyword arguments. # request = Google::Cloud::Firestore::V1::BatchGetDocumentsRequest.new # - # # Call the batch_get_documents method. - # result = client.batch_get_documents request + # # Call the batch_get_documents method to start streaming. + # output = client.batch_get_documents request # - # # The returned object is a streamed enumerable yielding elements of - # # type ::Google::Cloud::Firestore::V1::BatchGetDocumentsResponse. - # result.each do |response| - # p response + # # The returned object is a streamed enumerable yielding elements of type + # # ::Google::Cloud::Firestore::V1::BatchGetDocumentsResponse + # output.each do |current_response| + # p current_response # end # def batch_get_documents request, options = nil raise ::ArgumentError, "request must be provided" if request.nil? @@ -1090,17 +1108,17 @@ # client = Google::Cloud::Firestore::V1::Firestore::Client.new # # # Create a request. To set request fields, pass in keyword arguments. # request = Google::Cloud::Firestore::V1::RunQueryRequest.new # - # # Call the run_query method. - # result = client.run_query request + # # Call the run_query method to start streaming. + # output = client.run_query request # - # # The returned object is a streamed enumerable yielding elements of - # # type ::Google::Cloud::Firestore::V1::RunQueryResponse. - # result.each do |response| - # p response + # # The returned object is a streamed enumerable yielding elements of type + # # ::Google::Cloud::Firestore::V1::RunQueryResponse + # output.each do |current_response| + # p current_response # end # def run_query request, options = nil raise ::ArgumentError, "request must be provided" if request.nil? @@ -1143,12 +1161,13 @@ end ## # Runs an aggregation query. # - # Rather than producing {::Google::Cloud::Firestore::V1::Document Document} results like {::Google::Cloud::Firestore::V1::Firestore::Client#run_query Firestore.RunQuery}, - # this API allows running an aggregation to produce a series of + # Rather than producing {::Google::Cloud::Firestore::V1::Document Document} results like + # {::Google::Cloud::Firestore::V1::Firestore::Client#run_query Firestore.RunQuery}, this API + # allows running an aggregation to produce a series of # {::Google::Cloud::Firestore::V1::AggregationResult AggregationResult} server-side. # # High-Level Example: # # ``` @@ -1211,17 +1230,17 @@ # client = Google::Cloud::Firestore::V1::Firestore::Client.new # # # Create a request. To set request fields, pass in keyword arguments. # request = Google::Cloud::Firestore::V1::RunAggregationQueryRequest.new # - # # Call the run_aggregation_query method. - # result = client.run_aggregation_query request + # # Call the run_aggregation_query method to start streaming. + # output = client.run_aggregation_query request # - # # The returned object is a streamed enumerable yielding elements of - # # type ::Google::Cloud::Firestore::V1::RunAggregationQueryResponse. - # result.each do |response| - # p response + # # The returned object is a streamed enumerable yielding elements of type + # # ::Google::Cloud::Firestore::V1::RunAggregationQueryResponse + # output.each do |current_response| + # p current_response # end # def run_aggregation_query request, options = nil raise ::ArgumentError, "request must be provided" if request.nil? @@ -1346,17 +1365,15 @@ # request = Google::Cloud::Firestore::V1::PartitionQueryRequest.new # # # Call the partition_query method. # result = client.partition_query request # - # # The returned object is of type Gapic::PagedEnumerable. You can - # # iterate over all elements by calling #each, and the enumerable - # # will lazily make API calls to fetch subsequent pages. Other - # # methods are also available for managing paging directly. - # result.each do |response| + # # The returned object is of type Gapic::PagedEnumerable. You can iterate + # # over elements, and API calls will be issued to fetch pages as needed. + # result.each do |item| # # Each element is of type ::Google::Cloud::Firestore::V1::Cursor. - # p response + # p item # end # def partition_query request, options = nil raise ::ArgumentError, "request must be provided" if request.nil? @@ -1398,11 +1415,12 @@ rescue ::GRPC::BadStatus => e raise ::Google::Cloud::Error.from_error(e) end ## - # Streams batches of document updates and deletes, in order. + # Streams batches of document updates and deletes, in order. This method is + # only available via the gRPC API (not REST). # # @param request [::Gapic::StreamInput, ::Enumerable<::Google::Cloud::Firestore::V1::WriteRequest, ::Hash>] # An enumerable of {::Google::Cloud::Firestore::V1::WriteRequest} instances. # @param options [::Gapic::CallOptions, ::Hash] # Overrides the default settings for this call, e.g, timeout, retries, etc. Optional. @@ -1419,26 +1437,26 @@ # require "google/cloud/firestore/v1" # # # Create a client object. The client can be reused for multiple calls. # client = Google::Cloud::Firestore::V1::Firestore::Client.new # - # # Create an input stream + # # Create an input stream. # input = Gapic::StreamInput.new # # # Call the write method to start streaming. # output = client.write input # - # # Send requests on the stream. For each request, pass in keyword - # # arguments to set fields. Be sure to close the stream when done. + # # Send requests on the stream. For each request object, set fields by + # # passing keyword arguments. Be sure to close the stream when done. # input << Google::Cloud::Firestore::V1::WriteRequest.new # input << Google::Cloud::Firestore::V1::WriteRequest.new # input.close # - # # Handle streamed responses. These may be interleaved with inputs. - # # Each response is of type ::Google::Cloud::Firestore::V1::WriteResponse. - # output.each do |response| - # p response + # # The returned object is a streamed enumerable yielding elements of type + # # ::Google::Cloud::Firestore::V1::WriteResponse + # output.each do |current_response| + # p current_response # end # def write request, options = nil unless request.is_a? ::Enumerable raise ::ArgumentError, "request must be an Enumerable" unless request.respond_to? :to_enum @@ -1476,11 +1494,12 @@ rescue ::GRPC::BadStatus => e raise ::Google::Cloud::Error.from_error(e) end ## - # Listens to changes. + # Listens to changes. This method is only available via the gRPC API (not + # REST). # # @param request [::Gapic::StreamInput, ::Enumerable<::Google::Cloud::Firestore::V1::ListenRequest, ::Hash>] # An enumerable of {::Google::Cloud::Firestore::V1::ListenRequest} instances. # @param options [::Gapic::CallOptions, ::Hash] # Overrides the default settings for this call, e.g, timeout, retries, etc. Optional. @@ -1497,26 +1516,26 @@ # require "google/cloud/firestore/v1" # # # Create a client object. The client can be reused for multiple calls. # client = Google::Cloud::Firestore::V1::Firestore::Client.new # - # # Create an input stream + # # Create an input stream. # input = Gapic::StreamInput.new # # # Call the listen method to start streaming. # output = client.listen input # - # # Send requests on the stream. For each request, pass in keyword - # # arguments to set fields. Be sure to close the stream when done. + # # Send requests on the stream. For each request object, set fields by + # # passing keyword arguments. Be sure to close the stream when done. # input << Google::Cloud::Firestore::V1::ListenRequest.new # input << Google::Cloud::Firestore::V1::ListenRequest.new # input.close # - # # Handle streamed responses. These may be interleaved with inputs. - # # Each response is of type ::Google::Cloud::Firestore::V1::ListenResponse. - # output.each do |response| - # p response + # # The returned object is a streamed enumerable yielding elements of type + # # ::Google::Cloud::Firestore::V1::ListenResponse + # output.each do |current_response| + # p current_response # end # def listen request, options = nil unless request.is_a? ::Enumerable raise ::ArgumentError, "request must be an Enumerable" unless request.respond_to? :to_enum @@ -1655,11 +1674,12 @@ # Applies a batch of write operations. # # The BatchWrite method does not apply the write operations atomically # and can apply them out of order. Method does not allow more than one write # per document. Each write succeeds or fails independently. See the - # {::Google::Cloud::Firestore::V1::BatchWriteResponse BatchWriteResponse} for the success status of each write. + # {::Google::Cloud::Firestore::V1::BatchWriteResponse BatchWriteResponse} for the + # success status of each write. # # If you require an atomically applied set of writes, use # {::Google::Cloud::Firestore::V1::Firestore::Client#commit Commit} instead. # # @overload batch_write(request, options = nil) @@ -1774,10 +1794,11 @@ # @param parent [::String] # Required. The parent resource. For example: # `projects/{project_id}/databases/{database_id}/documents` or # `projects/{project_id}/databases/{database_id}/documents/chatrooms/{chatroom_id}` # @param collection_id [::String] - # Required. The collection ID, relative to `parent`, to list. For example: `chatrooms`. + # Required. The collection ID, relative to `parent`, to list. For example: + # `chatrooms`. # @param document_id [::String] # The client-assigned document ID to use for this document. # # Optional. If not specified, an ID will be assigned by the service. # @param document [::Google::Cloud::Firestore::V1::Document, ::Hash]