Reference documentation and code samples for the Cloud Firestore API class Google::Cloud::Firestore::CollectionReference.
CollectionReference
A collection reference object is used for adding documents, getting document references, and querying for documents (See Query).
Inherits
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
Methods
#add
def add(data = nil) -> DocumentReference
Create a document with random document identifier.
The operation will fail if the document already exists.
- data (Hash) — The document's fields and values. Optional.
- (DocumentReference) — A created document.
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"
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"
#collection_id
def collection_id() -> String
The collection identifier for the collection resource.
- (String) — collection identifier.
#collection_path
def collection_path() -> String
A string representing the path of the collection, relative to the document root of the database.
- (String) — collection path.
#doc
def doc(document_path = nil) -> DocumentReference
Retrieves a document reference.
- document_path (String, nil) — 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.
- (DocumentReference) — A document.
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"
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"
#document
def document(document_path = nil) -> DocumentReference
Retrieves a document reference.
- document_path (String, nil) — 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.
- (DocumentReference) — A document.
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"
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"
#list_documents
def list_documents(token: nil, max: nil, read_time: nil) -> Array<DocumentReference>
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.
- token (String) (defaults to: nil) — A previously-returned page token representing part of the larger set of results to view.
- max (Integer) (defaults to: nil) — Maximum number of results to return.
- read_time (Time) (defaults to: nil) — Reads documents as they were at the given time. This may not be older than 270 seconds. Optional
- (Array<DocumentReference>) — An array of document references.
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
List documents with read time
require "google/cloud/firestore" firestore = Google::Cloud::Firestore.new read_time = Time.now col = firestore.col "cities" col.list_documents(read_time: read_time).each do |doc_ref| puts doc_ref.document_id end
#parent
def parent() -> Client, DocumentReference
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.
- (Client, DocumentReference) — parent object.
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
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