class Google::Cloud::Firestore::CollectionReference

# 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

client[RW]

@private The firestore client object.

Public Class Methods

from_path(path, client) click to toggle source

@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
new(query, path, client) click to toggle source

@private Creates a new CollectionReference.

Calls superclass method
# 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

add(data = nil) click to toggle source

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
collection_id() click to toggle source

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
collection_path() click to toggle source

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
doc(document_path = nil) click to toggle source

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
Also aliased as: document
document(document_path = nil)
Alias for: doc
list_documents(token: nil, max: nil) click to toggle source

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
parent() click to toggle source

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
parent_path() click to toggle source

@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
path() click to toggle source

@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

ensure_client!() click to toggle source

@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
random_document_id() click to toggle source

@private

# File lib/google/cloud/firestore/collection_reference.rb, line 274
def random_document_id
  Generate.unique_id
end