Class: Google::Cloud::Firestore::FieldValue

Inherits:
Object
  • Object
show all
Defined in:
lib/google/cloud/firestore/field_value.rb

Overview

FieldValue

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

Examples:

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

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.array_delete(*values) ⇒ FieldValue

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

Examples:

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

Parameters:

  • values (Object) —

    The values to remove from the array. Required.

Returns:

  • (FieldValue) —

    The array delete field value object.

Raises:

  • (ArgumentError) 


201
202
203
204
205
206
207
208
209
 
# 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) ⇒ FieldValue

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

Examples:

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

Parameters:

  • values (Object) —

    The values to add to the array. Required.

Returns:

  • (FieldValue) —

    The array union field value object.

Raises:

  • (ArgumentError) 


168
169
170
171
172
173
174
175
176
 
# 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 ⇒ FieldValue

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

Examples:

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

Returns:



118
119
120
 
# File 'lib/google/cloud/firestore/field_value.rb', line 118

def self.delete
  new :delete
end

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

Examples:

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

Parameters:

  • 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.



244
245
246
247
248
249
250
251
 
# 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) ⇒ 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.

Examples:

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

Parameters:

  • 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.



288
289
290
291
292
293
294
295
 
# 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) ⇒ 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.

Examples:

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

Parameters:

  • 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.



332
333
334
335
336
337
338
339
 
# 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

.server_time ⇒ FieldValue

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

Examples:

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

Returns:

  • (FieldValue) —

    The server time field value object.



141
142
143
 
# File 'lib/google/cloud/firestore/field_value.rb', line 141

def self.server_time
  new :server_time
end

Instance Method Details

#type ⇒ Symbol

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

Examples:

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

Returns:

  • (Symbol) —

    The type.



67
68
69
 
# File 'lib/google/cloud/firestore/field_value.rb', line 67

def type
  @type
end