Cloud Firestore API - Class Google::Cloud::Firestore::FieldValue (v2.12.0)

Reference documentation and code samples for the Cloud Firestore API class Google::Cloud::Firestore::FieldValue.

FieldValue

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

Inherits

  • Object

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 })

Methods

.array_delete

def self.array_delete(*values) -> FieldValue

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

Parameter
  • values (Object) — The values to remove from the array. Required.
Returns
  • (FieldValue) — The array delete field value object.
Raises
  • (ArgumentError)
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 })

.array_union

def self.array_union(*values) -> FieldValue

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

Parameter
  • values (Object) — The values to add to the array. Required.
Returns
  • (FieldValue) — The array union field value object.
Raises
  • (ArgumentError)
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 })

.delete

def self.delete() -> FieldValue

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

Returns
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 })

.increment

def self.increment(value) -> FieldValue

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.

Parameter
  • value (Numeric) — The value to add to the given value. Required.
Returns
  • (FieldValue) — The increment field value object.
Raises
  • (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 })

.maximum

def self.maximum(value) -> FieldValue

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.

Parameter
  • value (Numeric) — The value to compare against the given value to calculate the maximum value to set. Required.
Returns
  • (FieldValue) — The maximum field value object.
Raises
  • (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 })

.minimum

def self.minimum(value) -> FieldValue

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.

Parameter
  • value (Numeric) — The value to compare against the given value to calculate the minimum value to set. Required.
Returns
  • (FieldValue) — The minimum field value object.
Raises
  • (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 })

.server_time

def self.server_time() -> FieldValue

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

Returns
  • (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 })

#type

def type() -> Symbol

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

Returns
  • (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 })