class Google::Cloud::Firestore::FieldPath

# FieldPath

Represents a field path to the Firestore API. See {Client#field_path}.

@example

require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

user_snap = firestore.doc("users/frank").get

nested_field_path = Google::Cloud::Firestore::FieldPath.new(
  :favorites, :food
)
user_snap.get(nested_field_path) #=> "Pizza"

Constants

INVALID_FIELD_PATH_CHARS
SIMPLE_FIELD_PATH_CHARS

Public Class Methods

document_id() click to toggle source

Creates a field path object representing the sentinel ID of a document. It can be used in queries to sort or filter by the document ID. See {Client#document_id}.

@return [FieldPath] The field path object.

@example

require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

# Get a collection reference
cities_col = firestore.col "cities"

# Create a query
query = cities_col.order(
  Google::Cloud::Firestore::FieldPath.document_id
).start_at("NYC")

query.get do |city|
  puts "#{city.document_id} has #{city[:population]} residents."
end
# File lib/google/cloud/firestore/field_path.rb, line 140
def self.document_id
  new :__name__
end
new(*fields) click to toggle source

Creates a field path object representing a nested field for document data.

@param [String, Symbol, Array<String|Symbol>] fields One or more

strings representing the path of the data to select. Each field must
be provided separately.

@return [FieldPath] The field path object.

@example

require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

user_snap = firestore.doc("users/frank").get

nested_field_path = Google::Cloud::Firestore::FieldPath.new(
  :favorites, :food
)
user_snap.get(nested_field_path) #=> "Pizza"
# File lib/google/cloud/firestore/field_path.rb, line 63
def initialize *fields
  @fields = fields.flatten.map(&:to_s).freeze

  invalid_fields = @fields.detect(&:empty?)
  raise ArgumentError, "empty paths not allowed" if invalid_fields
end
parse(dotted_string) click to toggle source

@private Creates a field path object representing the nested fields for document data.

The values are memoized to increase performance.

@param [String] dotted_string A string representing the path of the

document data. The string can represent as a string of individual
fields joined by ".". Fields containing `~`, `*`, `/`, `[`, `]`, and
`.` cannot be in a dotted string, and should be created by passing
individual field strings to  {FieldPath.new} instead.

@return [FieldPath] The field path object.

@example

require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

user_snap = firestore.doc("users/frank").get

field_path = Google::Cloud::Firestore::FieldPath.parse(
  "favorites.food"
)
field_path.fields #=> ["favorites", "food"]
# File lib/google/cloud/firestore/field_path.rb, line 170
def self.parse dotted_string
  # Memoize parsed field paths
  @memoized_field_paths ||= {}
  if @memoized_field_paths.key? dotted_string
    return @memoized_field_paths[dotted_string]
  end

  if dotted_string.is_a? Array
    @memoized_field_paths[dotted_string] = new dotted_string
    return @memoized_field_paths[dotted_string]
  end

  fields = String(dotted_string).split "."

  if fields.grep(INVALID_FIELD_PATH_CHARS).any?
    raise ArgumentError, "invalid character, use FieldPath instead"
  end

  @memoized_field_paths[dotted_string] = new fields
end

Public Instance Methods

<=>(other) click to toggle source

@private

# File lib/google/cloud/firestore/field_path.rb, line 193
def <=> other
  return nil unless other.is_a? FieldPath
  formatted_string <=> other.formatted_string
end
eql?(other) click to toggle source

@private

# File lib/google/cloud/firestore/field_path.rb, line 200
def eql? other
  formatted_string.eql? other.formatted_string
end
fields() click to toggle source

@private The individual fields representing the nested field path for document data. The fields are frozen.

@return [Array<String>] The fields.

@example

require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

user_snap = firestore.doc("users/frank").get

nested_field_path = Google::Cloud::Firestore::FieldPath.new(
  :favorites, :food
)
nested_field_path.fields #=> ["favorites", "food"]
# File lib/google/cloud/firestore/field_path.rb, line 88
def fields
  @fields
end
formatted_string() click to toggle source

@private A string representing the nested fields for document data as a string of individual fields joined by “.”. Fields containing `~`, `*`, `/`, `[`, `]`, and `.` are escaped.

@return [String] The formatted string.

@example

require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

user_snap = firestore.doc("users/frank").get

nested_field_path = Google::Cloud::Firestore::FieldPath.new(
  :favorites, :food
)
nested_field_path.formatted_string #=> "favorites.food"
# File lib/google/cloud/firestore/field_path.rb, line 111
def formatted_string
  escaped_fields = @fields.map { |field| escape_field_for_path field }
  escaped_fields.join "."
end
hash() click to toggle source

@private

# File lib/google/cloud/firestore/field_path.rb, line 206
def hash
  formatted_string.hash
end

Protected Instance Methods

escape_field_for_path(field) click to toggle source
# File lib/google/cloud/firestore/field_path.rb, line 215
def escape_field_for_path field
  field = String field

  return field if SIMPLE_FIELD_PATH_CHARS.match field

  field = field.gsub(/[`\\]/, "`" => "\\`", "\\" => "\\\\")

  "`#{field}`"
end