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

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

# TODO

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) 


196
197
198
199
200
201
202
203
204
 
# File 'lib/google/cloud/firestore/field_value.rb', line 196

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) 


163
164
165
166
167
168
169
170
171
 
# File 'lib/google/cloud/firestore/field_value.rb', line 163

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:



113
114
115
 
# File 'lib/google/cloud/firestore/field_value.rb', line 113

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.



239
240
241
242
243
244
245
246
 
# File 'lib/google/cloud/firestore/field_value.rb', line 239

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.



283
284
285
286
287
288
289
290
 
# File 'lib/google/cloud/firestore/field_value.rb', line 283

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.



327
328
329
330
331
332
333
334
 
# File 'lib/google/cloud/firestore/field_value.rb', line 327

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.



136
137
138
 
# File 'lib/google/cloud/firestore/field_value.rb', line 136

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.



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

def type
  @type
end