class Google::Cloud::Firestore::FieldValue

# FieldValue

Represents a change to be made to fields in document data in the Firestore API.

@example

require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

# Get a document reference
nyc_ref = firestore.doc "cities/NYC"

# Set the population to increment by 1.
increment_value = Google::Cloud::Firestore::FieldValue.increment 1

nyc_ref.update({ name: "New York City",
                 population: increment_value })

Public Class Methods

array_delete(*values) click to toggle source

Creates a sentinel value to indicate the removal of the given values with an array.

@param [Object] values The values to remove from the array. Required.

@return [FieldValue] The array delete field value object.

@example

require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

# Get a document reference
nyc_ref = firestore.doc "cities/NYC"

array_delete = Google::Cloud::Firestore::FieldValue.array_delete(
  7, 8, 9
)

nyc_ref.update({ name: "New York City",
                 lucky_numbers: array_delete })
# File lib/google/cloud/firestore/field_value.rb, line 201
def self.array_delete *values
  # We can flatten the values because arrays don't support sub-arrays
  values.flatten!
  raise ArgumentError, "values must be provided" if values.empty?
  # verify the values are the correct types
  Convert.raw_to_value values

  new :array_delete, values
end
array_union(*values) click to toggle source

Creates a sentinel value to indicate the union of the given value with an array.

@param [Object] values The values to add to the array. Required.

@return [FieldValue] The array union field value object.

@example

require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

# Get a document reference
nyc_ref = firestore.doc "cities/NYC"

array_union = Google::Cloud::Firestore::FieldValue.array_union(
  1, 2, 3
)

nyc_ref.update({ name: "New York City",
                 lucky_numbers: array_union })
# File lib/google/cloud/firestore/field_value.rb, line 168
def self.array_union *values
  # We can flatten the values because arrays don't support sub-arrays
  values.flatten!
  raise ArgumentError, "values must be provided" if values.empty?
  # verify the values are the correct types
  Convert.raw_to_value values

  new :array_union, values
end
delete() click to toggle source

Creates a field value object representing the deletion of a field in document data.

@return [FieldValue] The delete field value object.

@example

require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

# Get a document reference
nyc_ref = firestore.doc "cities/NYC"

field_delete = Google::Cloud::Firestore::FieldValue.delete

nyc_ref.update({ name: "New York City",
                 trash: field_delete })
# File lib/google/cloud/firestore/field_value.rb, line 118
def self.delete
  new :delete
end
increment(value) click to toggle source

Creates a sentinel value to indicate the addition the given value to the field's current value.

If the field's current value is not an integer or a double value (Numeric), or if the field does not yet exist, the transformation will set the field to the given value. If either of the given value or the current field value are doubles, both values will be interpreted as doubles. Double arithmetic and representation of double values follow IEEE 754 semantics. If there is positive/negative integer overflow, the field is resolved to the largest magnitude positive/negative integer.

@param [Numeric] value The value to add to the given value. Required.

@return [FieldValue] The increment field value object.

@raise [ArgumentError] if the value is not an Integer or Numeric.

@example

require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

# Get a document reference
nyc_ref = firestore.doc "cities/NYC"

# Set the population to increment by 1.
increment_value = Google::Cloud::Firestore::FieldValue.increment 1

nyc_ref.update({ name: "New York City",
                 population: increment_value })
# File lib/google/cloud/firestore/field_value.rb, line 244
def self.increment value
  # verify the values are the correct types
  unless value.is_a? Numeric
    raise ArgumentError, "value must be a Numeric"
  end

  new :increment, value
end
maximum(value) click to toggle source

Creates a sentinel value to indicate the setting the field to the maximum of its current value and the given value.

If the field is not an integer or double (Numeric), or if the field does not yet exist, the transformation will set the field to the given value. If a maximum operation is applied where the field and the input value are of mixed types (that is - one is an integer and one is a double) the field takes on the type of the larger operand. If the operands are equivalent (e.g. 3 and 3.0), the field does not change. 0, 0.0, and -0.0 are all zero. The maximum of a zero stored value and zero input value is always the stored value. The maximum of any numeric value x and NaN is NaN.

@param [Numeric] value The value to compare against the given value to

calculate the maximum value to set. Required.

@return [FieldValue] The maximum field value object.

@raise [ArgumentError] if the value is not an Integer or Numeric.

@example

require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

# Get a document reference
nyc_ref = firestore.doc "cities/NYC"

# Set the population to be at maximum 4,000,000.
maximum_value = Google::Cloud::Firestore::FieldValue.maximum 4000000

nyc_ref.update({ name: "New York City",
                 population: maximum_value })
# File lib/google/cloud/firestore/field_value.rb, line 288
def self.maximum value
  # verify the values are the correct types
  unless value.is_a? Numeric
    raise ArgumentError, "value must be a Numeric"
  end

  new :maximum, value
end
minimum(value) click to toggle source

Creates a sentinel value to indicate the setting the field to the minimum of its current value and the given value.

If the field is not an integer or double (Numeric), or if the field does not yet exist, the transformation will set the field to the input value. If a minimum operation is applied where the field and the input value are of mixed types (that is - one is an integer and one is a double) the field takes on the type of the smaller operand. If the operands are equivalent (e.g. 3 and 3.0), the field does not change. 0, 0.0, and -0.0 are all zero. The minimum of a zero stored value and zero input value is always the stored value. The minimum of any numeric value x and NaN is NaN.

@param [Numeric] value The value to compare against the given value to

calculate the minimum value to set. Required.

@return [FieldValue] The minimum field value object.

@raise [ArgumentError] if the value is not an Integer or Numeric.

@example

require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

# Get a document reference
nyc_ref = firestore.doc "cities/NYC"

# Set the population to be at minimum 1,000,000.
minimum_value = Google::Cloud::Firestore::FieldValue.minimum 1000000

nyc_ref.update({ name: "New York City",
                 population: minimum_value })
# File lib/google/cloud/firestore/field_value.rb, line 332
def self.minimum value
  # verify the values are the correct types
  unless value.is_a? Numeric
    raise ArgumentError, "value must be a Numeric"
  end

  new :minimum, value
end
new(type, value = nil) click to toggle source

@private Creates a field value object representing changes made to fields in document data.

# File lib/google/cloud/firestore/field_value.rb, line 43
def initialize type, value = nil
  @type = type
  @value = value
end
server_time() click to toggle source

Creates a field value object representing set a field's value to the server timestamp when accessing the document data.

@return [FieldValue] The server time field value object.

@example

require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

# Get a document reference
nyc_ref = firestore.doc "cities/NYC"

field_server_time = Google::Cloud::Firestore::FieldValue.server_time

nyc_ref.update({ name: "New York City",
                 updated_at: field_server_time })
# File lib/google/cloud/firestore/field_value.rb, line 141
def self.server_time
  new :server_time
end

Public Instance Methods

type() click to toggle source

The type of change to make to an individual field in document data.

@return [Symbol] The type.

@example

require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

# Get a document reference
nyc_ref = firestore.doc "cities/NYC"

field_delete = Google::Cloud::Firestore::FieldValue.delete
field_delete.type #=> :delete

nyc_ref.update({ name: "New York City",
                 trash: field_delete })
# File lib/google/cloud/firestore/field_value.rb, line 67
def type
  @type
end
value() click to toggle source

@private The value to change to an individual field in document data, depending on the type of change.

@return [Object] The value.

@example

require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

# Get a document reference
nyc_ref = firestore.doc "cities/NYC"

array_union = Google::Cloud::Firestore::FieldValue.array_union(
  1, 2, 3
)
array_union.type #=> :array_union
array_union.value #=> [1, 2, 3]

nyc_ref.update({ name: "New York City",
                 lucky_numbers: array_union })
# File lib/google/cloud/firestore/field_value.rb, line 95
def value
  @value
end