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 ise 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

#end_at, #end_before, #get, #limit, #offset, #order, #select, #start_after, #start_at, #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:



207
208
209
210
 
# File 'lib/google/cloud/firestore/collection_reference.rb', line 207

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.



53
54
55
 
# File 'lib/google/cloud/firestore/collection_reference.rb', line 53

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.



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

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:



121
122
123
124
125
126
 
# File 'lib/google/cloud/firestore/collection_reference.rb', line 121

def doc document_path = nil
  document_path ||= random_document_id

  ensure_client!
  client.doc "#{collection_path}/#{document_path}"
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:



159
160
161
162
163
164
 
# File 'lib/google/cloud/firestore/collection_reference.rb', line 159

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