Class: Google::Cloud::Firestore::Client
- Inherits:
-
Object
- Object
- Google::Cloud::Firestore::Client
- Defined in:
- lib/google/cloud/firestore/client.rb
Overview
Client
The Cloud Firestore Client used is to access and manipulate the collections and documents in the Firestore database.
Access collapse
-
#col(collection_path) ⇒ CollectionReference
(also: #collection)
Retrieves a collection.
-
#col_group(collection_id) ⇒ CollectionGroup
(also: #collection_group)
Creates and returns a new collection group that includes all documents in the database that are contained in a collection or subcollection with the given collection_id.
-
#cols {|collections| ... } ⇒ Enumerator<CollectionReference>
(also: #collections, #list_collections)
Retrieves an enumerator for the root collections.
-
#doc(document_path) ⇒ DocumentReference
(also: #document)
Retrieves a document reference.
-
#document_id ⇒ FieldPath
Creates a field path object representing the sentinel ID of a document.
-
#field_array_delete(*values) ⇒ FieldValue
Creates a sentinel value to indicate the removal of the given values with an array.
-
#field_array_union(*values) ⇒ FieldValue
Creates a sentinel value to indicate the union of the given values with an array.
-
#field_delete ⇒ FieldValue
Creates a field value object representing the deletion of a field in document data.
-
#field_increment(value) ⇒ FieldValue
Creates a sentinel value to indicate the addition the given value to the field's current value.
-
#field_maximum(value) ⇒ FieldValue
Creates a sentinel value to indicate the setting the field to the maximum of its current value and the given value.
-
#field_minimum(value) ⇒ FieldValue
Creates a sentinel value to indicate the setting the field to the minimum of its current value and the given value.
-
#field_path(*fields) ⇒ FieldPath
Creates a field path object representing a nested field for document data.
-
#field_server_time ⇒ FieldValue
Creates a field value object representing set a field's value to the server timestamp when accessing the document data.
-
#get_all(*docs, field_mask: nil) {|documents| ... } ⇒ Enumerator<DocumentSnapshot>
(also: #get_docs, #get_documents, #find)
Retrieves a list of document snapshots.
Operations collapse
-
#batch {|batch| ... } ⇒ CommitResponse
Perform multiple changes at the same time.
-
#transaction(max_retries: nil, commit_response: nil) {|transaction| ... } ⇒ Object, CommitResponse
Create a transaction to perform multiple reads and writes that are executed atomically at a single logical point in time in a database.
Instance Method Summary collapse
-
#database_id ⇒ String
The database identifier for the Cloud Firestore database.
-
#project_id ⇒ String
The project identifier for the Cloud Firestore database.
Instance Method Details
#batch {|batch| ... } ⇒ CommitResponse
Perform multiple changes at the same time.
All changes are accumulated in memory until the block completes. Unlike transactions, batches don't lock on document reads, should only fail if users provide preconditions, and are not automatically retried. See Batch.
571 572 573 574 575 |
# File 'lib/google/cloud/firestore/client.rb', line 571 def batch batch = Batch.from_client self yield batch batch.commit end |
#col(collection_path) ⇒ CollectionReference Also known as: collection
Retrieves a collection.
133 134 135 136 137 138 139 |
# File 'lib/google/cloud/firestore/client.rb', line 133 def col collection_path if collection_path.to_s.split("/").count.even? raise ArgumentError, "collection_path must refer to a collection." end CollectionReference.from_path "#{path}/documents/#{collection_path}", self end |
#col_group(collection_id) ⇒ CollectionGroup Also known as: collection_group
Creates and returns a new collection group that includes all documents in the database that are contained in a collection or subcollection with the given collection_id.
165 166 167 168 169 170 171 |
# File 'lib/google/cloud/firestore/client.rb', line 165 def col_group collection_id if collection_id.include? "/" raise ArgumentError, "Invalid collection_id: '#{collection_id}', must not contain '/'." end CollectionGroup.from_collection_id service.documents_path, collection_id, self end |
#cols {|collections| ... } ⇒ Enumerator<CollectionReference> Also known as: collections, list_collections
Retrieves an enumerator for the root collections.
104 105 106 107 108 109 110 |
# File 'lib/google/cloud/firestore/client.rb', line 104 def cols &block ensure_service! grpc = service.list_collections "#{path}/documents" cols_enum = CollectionReferenceList.from_grpc(grpc, self, "#{path}/documents").all cols_enum.each(&block) if block_given? cols_enum end |
#database_id ⇒ String
The database identifier for the Cloud Firestore database.
71 72 73 |
# File 'lib/google/cloud/firestore/client.rb', line 71 def database_id "(default)" end |
#doc(document_path) ⇒ DocumentReference Also known as: document
Retrieves a document reference.
192 193 194 195 196 197 198 199 200 |
# File 'lib/google/cloud/firestore/client.rb', line 192 def doc document_path if document_path.to_s.split("/").count.odd? raise ArgumentError, "document_path must refer to a document." end doc_path = "#{path}/documents/#{document_path}" DocumentReference.from_path doc_path, self end |
#document_id ⇒ FieldPath
Creates a field path object representing the sentinel ID of a document. It can be used in queries to sort or filter by the document ID. See FieldPath.document_id.
300 301 302 |
# File 'lib/google/cloud/firestore/client.rb', line 300 def document_id FieldPath.document_id end |
#field_array_delete(*values) ⇒ FieldValue
Creates a sentinel value to indicate the removal of the given values with an array.
416 417 418 |
# File 'lib/google/cloud/firestore/client.rb', line 416 def field_array_delete *values FieldValue.array_delete(*values) end |
#field_array_union(*values) ⇒ FieldValue
Creates a sentinel value to indicate the union of the given values with an array.
391 392 393 |
# File 'lib/google/cloud/firestore/client.rb', line 391 def field_array_union *values FieldValue.array_union(*values) end |
#field_delete ⇒ FieldValue
Creates a field value object representing the deletion of a field in document data.
345 346 347 |
# File 'lib/google/cloud/firestore/client.rb', line 345 def field_delete FieldValue.delete end |
#field_increment(value) ⇒ FieldValue
Creates a sentinel value to indicate the addition the given value to the field's current value.
If the field's current value is not an integer or a double value (Numeric), or if the field does not yet exist, the transformation will set the field to the given value. If either of the given value or the current field value are doubles, both values will be interpreted as doubles. Double arithmetic and representation of double values follow IEEE 754 semantics. If there is positive/negative integer overflow, the field is resolved to the largest magnitude positive/negative integer.
453 454 455 |
# File 'lib/google/cloud/firestore/client.rb', line 453 def field_increment value FieldValue.increment value end |
#field_maximum(value) ⇒ FieldValue
Creates a sentinel value to indicate the setting the field to the maximum of its current value and the given value.
If the field is not an integer or double (Numeric), or if the field does not yet exist, the transformation will set the field to the given value. If a maximum operation is applied where the field and the input value are of mixed types (that is - one is an integer and one is a double) the field takes on the type of the larger operand. If the operands are equivalent (e.g. 3 and 3.0), the field does not change. 0, 0.0, and -0.0 are all zero. The maximum of a zero stored value and zero input value is always the stored value. The maximum of any numeric value x and NaN is NaN.
492 493 494 |
# File 'lib/google/cloud/firestore/client.rb', line 492 def field_maximum value FieldValue.maximum value end |
#field_minimum(value) ⇒ FieldValue
Creates a sentinel value to indicate the setting the field to the minimum of its current value and the given value.
If the field is not an integer or double (Numeric), or if the field does not yet exist, the transformation will set the field to the input value. If a minimum operation is applied where the field and the input value are of mixed types (that is - one is an integer and one is a double) the field takes on the type of the smaller operand. If the operands are equivalent (e.g. 3 and 3.0), the field does not change. 0, 0.0, and -0.0 are all zero. The minimum of a zero stored value and zero input value is always the stored value. The minimum of any numeric value x and NaN is NaN.
531 532 533 |
# File 'lib/google/cloud/firestore/client.rb', line 531 def field_minimum value FieldValue.minimum value end |
#field_path(*fields) ⇒ FieldPath
Creates a field path object representing a nested field for document data.
324 325 326 |
# File 'lib/google/cloud/firestore/client.rb', line 324 def field_path *fields FieldPath.new(*fields) end |
#field_server_time ⇒ FieldValue
Creates a field value object representing set a field's value to the server timestamp when accessing the document data.
366 367 368 |
# File 'lib/google/cloud/firestore/client.rb', line 366 def field_server_time FieldValue.server_time end |
#get_all(*docs, field_mask: nil) {|documents| ... } ⇒ Enumerator<DocumentSnapshot> Also known as: get_docs, get_documents, find
Retrieves a list of document snapshots.
248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 |
# File 'lib/google/cloud/firestore/client.rb', line 248 def get_all *docs, field_mask: nil ensure_service! unless block_given? return enum_for :get_all, *docs, field_mask: field_mask end doc_paths = Array(docs).flatten.map do |doc_path| coalesce_doc_path_argument doc_path end mask = Array(field_mask).map do |field_path| if field_path.is_a? FieldPath field_path.formatted_string else FieldPath.parse(field_path).formatted_string end end mask = nil if mask.empty? results = service.get_documents doc_paths, mask: mask results.each do |result| next if result.result.nil? yield DocumentSnapshot.from_batch_result result, self end end |
#project_id ⇒ String
The project identifier for the Cloud Firestore database.
63 64 65 |
# File 'lib/google/cloud/firestore/client.rb', line 63 def project_id service.project end |
#transaction(max_retries: nil, commit_response: nil) {|transaction| ... } ⇒ Object, CommitResponse
Create a transaction to perform multiple reads and writes that are executed atomically at a single logical point in time in a database.
All changes are accumulated in memory until the block completes. Transactions will be automatically retried when documents change before the transaction is committed. See Transaction.
620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 |
# File 'lib/google/cloud/firestore/client.rb', line 620 def transaction max_retries: nil, commit_response: nil max_retries = 5 unless max_retries.is_a? Integer backoff = { current: 0, delay: 1.0, max: max_retries, mod: 1.3 } transaction = Transaction.from_client self begin transaction_return = yield transaction commit_return = transaction.commit # Conditional return value, depending on truthy commit_response commit_response ? commit_return : transaction_return rescue Google::Cloud::AbortedError, Google::Cloud::CanceledError, Google::Cloud::UnknownError, Google::Cloud::DeadlineExceededError, Google::Cloud::InternalError, Google::Cloud::UnauthenticatedError, Google::Cloud::ResourceExhaustedError, Google::Cloud::UnavailableError, Google::Cloud::InvalidArgumentError => e if e.instance_of? Google::Cloud::InvalidArgumentError # Return if a previous call was retried but ultimately succeeded return nil if backoff[:current].positive? # The Firestore backend uses "INVALID_ARGUMENT" for transaction IDs that have expired. # While INVALID_ARGUMENT is generally not retryable, we retry this specific case. raise e unless e. =~ /transaction has expired/ end # Re-raise if retried more than the max raise e if backoff[:current] > backoff[:max] # Sleep with incremental backoff before restarting sleep backoff[:delay] # Update increment backoff delay and retry counter backoff[:delay] *= backoff[:mod] backoff[:current] += 1 # Create new transaction and retry transaction = Transaction.from_client \ self, previous_transaction: transaction.transaction_id retry rescue StandardError => e # Rollback transaction when handling unexpected error transaction.rollback rescue nil # Re-raise error. raise e end end |