class Google::Cloud::Firestore::CollectionReference
A collection reference object is used for adding documents, getting document references, and querying for documents (See {Query}).
@example
require "google/cloud/firestore" firestore = Google::Cloud::Firestore.new # Get a collection reference cities_col = firestore.col "cities" # Get and print all city documents cities_col.get do |city| puts "#{city.document_id} has #{city[:population]} residents." end
Attributes
@private The firestore client object.
Public Class Methods
@private New Collection reference object from a path.
# File lib/google/cloud/firestore/collection_reference.rb, line 257 def self.from_path path, client # Very important to correctly set @query on a collection object query = StructuredQuery.new( from: [ StructuredQuery::CollectionSelector.new( collection_id: path.split("/").last ) ] ) CollectionReference.new query, path, client end
@private Creates a new CollectionReference
.
# File lib/google/cloud/firestore/collection_reference.rb, line 52 def initialize query, path, client super query, nil, client # Pass nil parent_path arg since this class implements #parent_path @path = path end
Public Instance Methods
Create a document with random document identifier.
The operation will fail if the document already exists.
@param [Hash] data The document's fields and values. Optional.
@return [DocumentReference] A created document.
@example Create a document with a random ID:
require "google/cloud/firestore" firestore = Google::Cloud::Firestore.new # Get a collection reference cities_col = firestore.col "cities" # Get a document reference without data random_ref = cities_col.add # The document ID is randomly generated random_ref.document_id #=> "RANDOMID123XYZ"
@example Create a document snapshot:
require "google/cloud/firestore" firestore = Google::Cloud::Firestore.new # Get a collection reference cities_col = firestore.col "cities" # Get a document snapshot random_ref = cities_col.add({ name: "New York City" }) # The document ID is randomly generated random_ref.document_id #=> "RANDOMID123XYZ"
# File lib/google/cloud/firestore/collection_reference.rb, line 248 def add data = nil data ||= {} doc.tap { |d| d.create data } end
The collection identifier for the collection resource.
@return [String] collection identifier.
# File lib/google/cloud/firestore/collection_reference.rb, line 61 def collection_id path.split("/").last end
A string representing the path of the collection, relative to the document root of the database.
@return [String] collection path.
# File lib/google/cloud/firestore/collection_reference.rb, line 70 def collection_path path.split("/", 6).last end
Retrieves a document reference.
@param [String, nil] document_path A string representing the path of
the document, relative to the document root of the database. If a string is not provided, and random document identifier will be generated. Optional.
@return [DocumentReference] A document.
@example
require "google/cloud/firestore" firestore = Google::Cloud::Firestore.new # Get a collection reference cities_col = firestore.col "cities" # Get a document reference nyc_ref = cities_col.doc "NYC" # The document ID is what was provided nyc_ref.document_id #=> "NYC"
@example Create a document reference with a random ID:
require "google/cloud/firestore" firestore = Google::Cloud::Firestore.new # Get a collection reference cities_col = firestore.col "cities" # Get a document reference without specifying path random_ref = cities_col.doc # The document ID is randomly generated random_ref.document_id #=> "RANDOMID123XYZ"
# File lib/google/cloud/firestore/collection_reference.rb, line 129 def doc document_path = nil document_path ||= random_document_id ensure_client! client.doc "#{collection_path}/#{document_path}" end
Retrieves a list of document references for the documents in this collection.
The document references returned may include references to “missing documents”, i.e. document locations that have no document present but which contain subcollections with documents. Attempting to read such a document reference (e.g. via {DocumentReference#get}) will return a {DocumentSnapshot} whose `exists?` method returns false.
@param [String] token A previously-returned page token representing
part of the larger set of results to view.
@param [Integer] max Maximum number of results to return.
@return [Array<DocumentReference>] An array of document references.
@example
require "google/cloud/firestore" firestore = Google::Cloud::Firestore.new col = firestore.col "cities" col.list_documents.each do |doc_ref| puts doc_ref.document_id end
# File lib/google/cloud/firestore/collection_reference.rb, line 164 def list_documents token: nil, max: nil ensure_client! client.list_documents \ parent_path, collection_id, token: token, max: max end
The document reference or database the collection reference belongs to. If the collection is a root collection, it will return the client object. If the collection is nested under a document, it will return the document reference object.
@return [Client, DocumentReference] parent object.
@example Returns client object for root collections:
require "google/cloud/firestore" firestore = Google::Cloud::Firestore.new # Get a collection reference cities_col = firestore.col "cities" # Get the document's parent collection database = cities_col.parent
@example Returns document object for nested collections:
require "google/cloud/firestore" firestore = Google::Cloud::Firestore.new # Get a collection reference precincts_ref = firestore.col "cities/NYC/precincts" # Get the document's parent collection nyc_ref = precincts_ref.parent
# File lib/google/cloud/firestore/collection_reference.rb, line 200 def parent if collection_path.include? "/" return DocumentReference.from_path parent_path, client end client end
@private The parent path for the collection.
# File lib/google/cloud/firestore/collection_reference.rb, line 85 def parent_path path.split("/")[0...-1].join "/" end
@private A string representing the full path of the collection resource.
@return [String] collection resource path.
# File lib/google/cloud/firestore/collection_reference.rb, line 79 def path @path end
Protected Instance Methods
@private Raise an error unless an database available.
# File lib/google/cloud/firestore/collection_reference.rb, line 280 def ensure_client! raise "Must have active connection to service" unless client end
@private
# File lib/google/cloud/firestore/collection_reference.rb, line 274 def random_document_id Generate.unique_id end