Class: Google::Cloud::Firestore::CollectionReference

Inherits:
Query
  • Object
show all
Defined in:
lib/google/cloud/firestore/collection_reference.rb

Overview

CollectionReference

A collection reference object is used for adding documents, getting document references, and querying for documents (See Query).

Examples:

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

Access collapse

Modifications collapse

Instance Method Summary collapse

Methods inherited from Query

#aggregate_query, #end_at, #end_before, from_json, #get, #limit, #limit_to_last, #listen, #offset, #order, #select, #start_after, #start_at, #to_json, #where

Instance Method Details

#add(data = nil) ⇒ DocumentReference

Create a document with random document identifier.

The operation will fail if the document already exists.

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"

Parameters:

  • data (Hash) (defaults to: nil) —

    The document's fields and values. Optional.

Returns:



263
264
265
266
 
# File 'lib/google/cloud/firestore/collection_reference.rb', line 263

def add data = nil
  data ||= {}
  doc.tap { |d| d.create data }
end

#collection_id ⇒ String

The collection identifier for the collection resource.

Returns:

  • (String) —

    collection identifier.



61
62
63
 
# File 'lib/google/cloud/firestore/collection_reference.rb', line 61

def collection_id
  path.split("/").last
end

#collection_path ⇒ String

A string representing the path of the collection, relative to the document root of the database.

Returns:

  • (String) —

    collection path.



70
71
72
 
# File 'lib/google/cloud/firestore/collection_reference.rb', line 70

def collection_path
  path.split("/", 6).last
end

#doc(document_path = nil) ⇒ DocumentReference Also known as: document

Retrieves a document reference.

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"

Parameters:

  • document_path (String, nil) (defaults to: 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:



129
130
131
132
133
134
 
# 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

#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.

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

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:



179
180
181
182
183
 
# File 'lib/google/cloud/firestore/collection_reference.rb', line 179

def list_documents token: nil, max: nil, read_time: nil
  ensure_client!
  client.list_documents \
    parent_path, collection_id, token: token, max: max, read_time: read_time
end

#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.

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

Returns:



215
216
217
218
219
220
 
# File 'lib/google/cloud/firestore/collection_reference.rb', line 215

def parent
  if collection_path.include? "/"
    return DocumentReference.from_path parent_path, client
  end
  client
end