Cloud Firestore API - Class Google::Cloud::Firestore::CollectionReference (v2.16.0)

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.

Parameter
  • data (Hash) — The document's fields and values. Optional.
Returns
Examples

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.

Returns
  • (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.

Returns
  • (String) — collection path.

#doc

def doc(document_path = nil) -> DocumentReference
Aliases

Retrieves a document reference.

Parameter
  • 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.
Returns
Examples 
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
Alias Of: #doc

Retrieves a document reference.

Parameter
  • 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.
Returns
Examples 
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.

Parameters
  • 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
Returns
Examples 
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.

Returns
Examples

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