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.
572 573 574 575 576 |
# File 'lib/google/cloud/firestore/client.rb', line 572 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 172 |
# 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.
193 194 195 196 197 198 199 200 201 |
# File 'lib/google/cloud/firestore/client.rb', line 193 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.
301 302 303 |
# File 'lib/google/cloud/firestore/client.rb', line 301 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.
417 418 419 |
# File 'lib/google/cloud/firestore/client.rb', line 417 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.
392 393 394 |
# File 'lib/google/cloud/firestore/client.rb', line 392 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.
346 347 348 |
# File 'lib/google/cloud/firestore/client.rb', line 346 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.
454 455 456 |
# File 'lib/google/cloud/firestore/client.rb', line 454 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.
493 494 495 |
# File 'lib/google/cloud/firestore/client.rb', line 493 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.
532 533 534 |
# File 'lib/google/cloud/firestore/client.rb', line 532 def field_minimum value FieldValue.minimum value end |
#field_path(*fields) ⇒ FieldPath
Creates a field path object representing a nested field for document data.
325 326 327 |
# File 'lib/google/cloud/firestore/client.rb', line 325 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.
367 368 369 |
# File 'lib/google/cloud/firestore/client.rb', line 367 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.
249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 |
# File 'lib/google/cloud/firestore/client.rb', line 249 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.
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 |
# File 'lib/google/cloud/firestore/client.rb', line 621 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::UnavailableError => e # 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 Google::Cloud::InvalidArgumentError => e # Return if a previous call was retried but ultimately succeeded return nil if backoff[:current].positive? # Re-raise error. raise e rescue StandardError => e # Rollback transaction when handling unexpected error transaction.rollback rescue nil # Re-raise error. raise e end end |