Class: Familia::HashKey

Inherits:
DataType show all
Includes:
DataType::CollectionBase
Defined in:
lib/familia/data_type/types/hashkey.rb

Constant Summary collapse

CLAIM_FIELD_SCRIPT =

Server-side compare-and-set: HSET the field only if it is unclaimed or already holds a value this caller owns.

KEYS[1] is the hash; ARGV[1] the field; ARGV[2] the canonical value to write; ARGV[3..] additional values that count as "already ours" (see #claim_field for the legacy-encoding case). A stored value matching a non-canonical variant is rewritten to the canonical form, so a claim doubles as an in-place normalization.

Returns:

  • (Integer, String) —

    0 when newly created, 1 when re-affirmed, or the conflicting stored value.

<<~LUA
  local current = redis.call('HGET', KEYS[1], ARGV[1])
  if current == false then
    redis.call('HSET', KEYS[1], ARGV[1], ARGV[2])
    return 0
  end
  for i = 2, #ARGV do
    if current == ARGV[i] then
      if current ~= ARGV[2] then
        redis.call('HSET', KEYS[1], ARGV[1], ARGV[2])
      end
      return 1
    end
  end
  return current
LUA
RELEASE_FIELD_SCRIPT =

Server-side compare-and-delete: HDEL the field only if it holds a value this caller owns. Same KEYS/ARGV shape as CLAIM_FIELD_SCRIPT minus the normalization (there is nothing to normalize on the way out).

Returns:

  • (Integer) —

    1 when deleted, 0 when the field was absent or owned by someone else.

<<~LUA
  local current = redis.call('HGET', KEYS[1], ARGV[1])
  if current == false then
    return 0
  end
  for i = 2, #ARGV do
    if current == ARGV[i] then
      return redis.call('HDEL', KEYS[1], ARGV[1])
    end
  end
  return 0
LUA

Instance Attribute Summary collapse

Attributes included from Settings

#current_key_version, #default_expiration, #delim, #encryption_hkdf_salt, #encryption_hkdf_salt_history, #encryption_keys, #encryption_personalization, #encryption_personalization_history, #logical_database, #prefix, #raise_on_unsaved_parent_write, #schema_path, #schema_validator, #schemas, #strict_write_order, #suffix, #transaction_mode

Instance Method Summary collapse

Methods included from DataType::CollectionBase

#collection_type?, #each_record

Methods included from Features::Autoloader

autoload_files, included, normalize_to_config_name

Methods included from DataType::Serialization

#deserialize_value, #deserialize_values, #deserialize_values_with_nil, #serialize_value, #strip_legacy_json_encoding

Methods included from DataType::DatabaseCommands

#current_expiration, #delete!, #echo, #exists?, #expire, #expireat, #move, #persist, #rename, #renamenx, #type

Methods included from DataType::Connection

#dbclient, #dbkey, #uri

Methods included from Connection::Behavior

#connect, #create_dbclient, #multi, #normalize_uri, #pipeline, #pipelined, #transaction, #uri=, #url, #url=, #with_connection_scope

Methods included from Settings

#configure, #default_suffix, #dirty_write_warnings, #dirty_write_warnings=, #pipelined_mode, #pipelined_mode=

Methods included from Base

add_feature, #as_json, #expired?, #expires?, find_feature, #generate_id, #to_json, #to_s, #ttl, #update_expiration, #uuid

Constructor Details

This class inherits a constructor from Familia::DataType

Instance Attribute Details

#features_enabled ⇒ Object (readonly) Originally defined in module Features

Returns the value of attribute features_enabled.

#logical_database(val = nil) ⇒ Object Originally defined in module DataType::ClassMethods

#parent ⇒ Object Originally defined in module DataType::ClassMethods

Returns the value of attribute parent.

#prefix ⇒ Object Originally defined in module DataType::ClassMethods

Returns the value of attribute prefix.

#suffix ⇒ Object Originally defined in module DataType::ClassMethods

Returns the value of attribute suffix.

#uri(val = nil) ⇒ Object Originally defined in module DataType::ClassMethods

Returns the value of attribute uri.

Instance Method Details

#[](field) ⇒ Object, ... Also known as: get

Returns the deserialized value, or nil when the field is missing. Inside a transaction or pipeline, the HGET Future (resolves to the stored value, still serialized).

Parameters:

  • field (String, Symbol) —

    the field name

Returns:

  • (Object, nil, Redis::Future) —

    the deserialized value, or nil when the field is missing. Inside a transaction or pipeline, the HGET Future (resolves to the stored value, still serialized).



171
172
173
# File 'lib/familia/data_type/types/hashkey.rb', line 171

def [](field)
  deserialize_value dbclient.hget(dbkey, field.to_s)
end

#[]=(field, val) ⇒ Object Also known as: put, store, add

Note:

This method executes a Redis HSET immediately, unlike scalar field setters which are deferred until save. If the parent object has unsaved scalar field changes, consider calling save first to avoid split-brain state.

+return+ [Integer] Returns 1 if the field is new and added, 0 if the field already existed and the value was updated.



146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
# File 'lib/familia/data_type/types/hashkey.rb', line 146

def []=(field, val)
  warn_if_dirty!
  ret = dbclient.hset dbkey, field.to_s, serialize_value(val)
  update_expiration
  ret
rescue TypeError => e
  Familia.error "[hset]= #{e.message}"
  if Familia.debug?
    Familia.debug "[hset]= #{Familia.loggable_text(dbkey)} " \
                  "#{Familia.loggable_text(field)}=#{Familia.loggable_text(val)}"
  end
  echo :hset, Familia.pretty_stack(limit: 1) if Familia.debug # logs via echo to the db and back
  klass = val.class
  msg = "Cannot store #{Familia.loggable_text(field)} => #{val.inspect} (#{klass}) " \
        "in #{Familia.loggable_text(dbkey)}"
  raise e.class, msg
end

#claim_field(field, val) ⇒ Symbol, Object

Claims +field+ for +val+, atomically, server-side.

This is the enforcement half of the unique-index invariant (ADR-0002). A read-then-HSET pair cannot enforce uniqueness on a key many writers share -- two savers both read "unclaimed" and the second HSET silently overwrites the first. WATCH does not help either: its granularity is the whole key, so every concurrent save of the class aborts every other one. A single EVAL checks and writes at field granularity, conflicting only on a genuine collision, and touches exactly one key (so it is Redis Cluster safe).

Parameters:

  • field (String, Symbol) —

    hash field (an indexed value)

  • val (Object) —

    the value to claim it for (an identifier)

Returns:

  • (Symbol, Object) —

    +:created+ when the field was unclaimed, +:owned+ when it already held an equivalent value (normalized to the canonical form as a side effect), or the deserialized conflicting value when another owner holds it.

Raises:

  • (Familia::OperationModeError) —

    when called inside a transaction or pipeline, where EVAL returns a Future and its verdict cannot be acted on.

See Also:



78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
# File 'lib/familia/data_type/types/hashkey.rb', line 78

def claim_field(field, val)
  if Familia.transaction_or_pipeline?
    raise Familia::OperationModeError, <<~ERROR_MESSAGE
      Cannot claim_field inside a transaction or pipeline: EVAL returns a Future there, so the claim's verdict cannot be checked. Claim before opening the MULTI (see ADR-0002).
    ERROR_MESSAGE
  end

  result = dbclient.eval(
    CLAIM_FIELD_SCRIPT, keys: [dbkey], argv: [field.to_s, *ownership_variants(val)]
  )

  return deserialize_value(result) unless result.is_a?(Integer)

  update_expiration
  result.zero? ? :created : :owned
end

#decrement(field, by = 1) ⇒ Integer, Redis::Future Also known as: decr, decrby

Returns The new value. Inside a transaction or pipeline, the HINCRBY Future of that Integer.

Parameters:

  • field (String, Symbol) —

    The field name

  • by (Integer) (defaults to: 1) —

    The amount to decrement by

Returns:

  • (Integer, Redis::Future) —

    The new value. Inside a transaction or pipeline, the HINCRBY Future of that Integer.



294
295
296
# File 'lib/familia/data_type/types/hashkey.rb', line 294

def decrement(field, by = 1)
  increment field, -by
end

#each(matching: nil, batch_size: 100) {|field, value| ... } ⇒ Enumerator, self

Note:

Pattern matches field names only (plain strings). To filter on values, use Enumerable#select instead.

Iterates over field-value pairs in the hash.

Uses HSCAN for memory-efficient iteration. Optionally filters by field name pattern using Redis MATCH.

Examples:

Iterate all pairs

settings.each { |field, value| puts "#{field}: #{value}" }

Filter by field name pattern

settings.each(matching: "cache_*") { |f, v| puts "#{f}: #{v}" }

Parameters:

  • matching (String, nil) (defaults to: nil) —

    Optional glob-style pattern to filter field names (e.g., "user:", "_count"). Pattern is passed to Redis HSCAN MATCH and matches against field names (plain strings, not JSON-encoded).

  • batch_size (Integer) (defaults to: 100) —

    Number of elements to fetch per HSCAN iteration

Yields:

  • (field, value) —

    Each field-value pair (values are deserialized)

Returns:

  • (Enumerator, self) —

    Returns Enumerator if no block given, self otherwise



343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
# File 'lib/familia/data_type/types/hashkey.rb', line 343

def each(matching: nil, batch_size: 100, &block)
  return to_enum(:each, matching: matching, batch_size: batch_size) unless block

  Familia.assert_replies_available!('HashKey#each')

  cursor = 0
  loop do
    new_cursor, pairs = scan(cursor, match: matching, count: batch_size)
    pairs.each(&block)
    cursor = new_cursor
    break if cursor.zero?
  end

  self
end

#empty? ⇒ Boolean, Redis::Future

Returns whether the hash has no fields. Inside a transaction or pipeline, the HLEN Future (resolves to the count).

Returns:

  • (Boolean, Redis::Future) —

    whether the hash has no fields. Inside a transaction or pipeline, the HLEN Future (resolves to the count).



136
137
138
# File 'lib/familia/data_type/types/hashkey.rb', line 136

def empty?
  Familia.transform_reply(field_count, &:zero?)
end

#expire_fields(seconds, *fields) ⇒ Array<Integer> Also known as: hexpire

Note:

Requires Redis 7.4+

Sets expiration time in seconds on one or more hash fields.

Examples:

Set 1 hour TTL on specific fields

my_hash.expire_fields(3600, 'session_token', 'temp_data')

Parameters:

  • seconds (Integer) —

    TTL in seconds

  • fields (Array<String>) —

    One or more field names

Returns:

  • (Array<Integer>) —

    Array of results for each field: -2 if field does not exist, 1 if expiration was set, 0 if expiration was not set (e.g., field has no expiration)



478
479
480
# File 'lib/familia/data_type/types/hashkey.rb', line 478

def expire_fields(seconds, *fields)
  call_hash_field_command('HEXPIRE', seconds, fields: fields)
end

#expireat_fields(unix_time, *fields) ⇒ Array<Integer> Also known as: hexpireat

Note:

Requires Redis 7.4+

Sets absolute expiration time (Unix timestamp in seconds) on hash fields.

Examples:

Expire fields at midnight tonight

midnight = Time.now.to_i + (24 * 60 * 60)
my_hash.expireat_fields(midnight, 'daily_counter')

Parameters:

  • unix_time (Integer) —

    Absolute Unix timestamp in seconds

  • fields (Array<String>) —

    One or more field names

Returns:

  • (Array<Integer>) —

    Array of results for each field



507
508
509
# File 'lib/familia/data_type/types/hashkey.rb', line 507

def expireat_fields(unix_time, *fields)
  call_hash_field_command('HEXPIREAT', unix_time, fields: fields)
end

#expiretime_fields(*fields) ⇒ Array<Integer> Also known as: hexpiretime

Note:

Requires Redis 7.4+

Returns the absolute Unix expiration timestamp in seconds for hash fields.

Examples:

Get expiration timestamp

my_hash.expiretime_fields('session')  #=> [1700000000]

Parameters:

  • fields (Array<String>) —

    One or more field names

Returns:

  • (Array<Integer>) —

    Array of timestamps for each field: -2 if field does not exist, -1 if field has no expiration, otherwise the absolute Unix timestamp in seconds



579
580
581
# File 'lib/familia/data_type/types/hashkey.rb', line 579

def expiretime_fields(*fields)
  call_hash_field_command('HEXPIRETIME', fields: fields)
end

#fetch(field, default = nil) ⇒ Object

Raises:

  • (IndexError) —

    when the field is missing and no default is given

  • (Familia::OperationModeError) —

    inside a transaction or pipeline, where the missing-field check cannot see the reply



179
180
181
182
183
184
185
186
187
188
189
190
# File 'lib/familia/data_type/types/hashkey.rb', line 179

def fetch(field, default = nil)
  Familia.assert_replies_available!('HashKey#fetch')

  ret = self[field.to_s]
  if ret.nil?
    raise IndexError, "No such index for: #{field}" if default.nil?

    default
  else
    ret
  end
end

#field_count ⇒ Integer Also known as: size, length, count

Returns the number of fields in the hash

Returns:

  • (Integer) —

    number of fields



127
128
129
# File 'lib/familia/data_type/types/hashkey.rb', line 127

def field_count
  dbclient.hlen dbkey
end

#hgetall ⇒ Hash, Redis::Future Also known as: all

Returns Fields mapped to deserialized values. Inside a transaction or pipeline, the HGETALL Future (resolves to the raw Hash).

Returns:

  • (Hash, Redis::Future) —

    Fields mapped to deserialized values. Inside a transaction or pipeline, the HGETALL Future (resolves to the raw Hash).



208
209
210
211
212
# File 'lib/familia/data_type/types/hashkey.rb', line 208

def hgetall
  Familia.transform_reply(dbclient.hgetall(dbkey)) do |hsh|
    hsh.transform_values { |v| deserialize_value v }
  end
end

#hsetnx(field, val) ⇒ Boolean, Redis::Future

Sets field in the hash stored at key to value, only if field does not yet exist. If field already exists, this operation has no effect. Refreshes the TTL only when the field was set. Inside a transaction or pipeline the write and the refresh are queued as one EVAL that makes the same decision when it runs, so an existing field leaves the hash's TTL unchanged there too.

Parameters:

  • field (String) —

    The field name

  • val (Object) —

    The value to set

Returns:

  • (Boolean, Redis::Future) —

    true if field is a new field and value was set, false if field already exists (redis-rb converts the 1/0 reply). Inside a transaction or pipeline, the EVAL Future, which resolves to that Boolean.



229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
# File 'lib/familia/data_type/types/hashkey.rb', line 229

def hsetnx(field, val)
  warn_if_dirty!
  conn = dbclient
  if queued_connection?(conn)
    return queue_conditional_write(conn, :hsetnx, field.to_s, serialize_value(val)) { |reply| reply == 1 }
  end

  ret = conn.hsetnx dbkey, field.to_s, serialize_value(val)
  update_expiration_if_written(ret)
  ret
rescue TypeError => e
  Familia.error "[hsetnx] #{e.message}"
  if Familia.debug?
    Familia.debug "[hsetnx] #{Familia.loggable_text(dbkey)} " \
                  "#{Familia.loggable_text(field)}=#{Familia.loggable_text(val)}"
  end
  echo :hsetnx, Familia.pretty_stack(limit: 1) if Familia.debug # logs via echo to the db and back
  klass = val.class
  msg = "Cannot store #{Familia.loggable_text(field)} => #{val.inspect} (#{klass}) " \
        "in #{Familia.loggable_text(dbkey)}"
  raise e.class, msg
end

#incrbyfloat(field, by) ⇒ Float, Redis::Future Also known as: incrfloat

Increments the float value of a hash field by the given amount.

Examples:

my_hash.incrbyfloat('temperature', 0.5)  #=> 23.5
my_hash.incrbyfloat('temperature', -1.2) #=> 22.3

Parameters:

  • field (String) —

    The field name

  • by (Float, Integer) —

    The amount to increment by (can be negative)

Returns:

  • (Float, Redis::Future) —

    The new value after incrementing. redis-rb already converts the HINCRBYFLOAT reply to a Float. Inside a transaction or pipeline, the Future of that Float.



404
405
406
407
408
# File 'lib/familia/data_type/types/hashkey.rb', line 404

def incrbyfloat(field, by)
  ret = dbclient.hincrbyfloat(dbkey, field.to_s, by)
  update_expiration
  ret
end

#increment(field, by = 1) ⇒ Integer, Redis::Future Also known as: incr, incrby

Increments the integer value of a hash field.

Parameters:

  • field (String, Symbol) —

    The field name

  • by (Integer) (defaults to: 1) —

    The amount to increment by (can be negative)

Returns:

  • (Integer, Redis::Future) —

    The new value. HINCRBY replies with an Integer, so no conversion is needed. Inside a transaction or pipeline, the Future of that Integer.



282
283
284
285
286
# File 'lib/familia/data_type/types/hashkey.rb', line 282

def increment(field, by = 1)
  ret = dbclient.hincrby(dbkey, field.to_s, by)
  update_expiration
  ret
end

#key?(field) ⇒ Boolean, Redis::Future Also known as: has_key?, include?, member?

Returns whether the field exists. Inside a transaction or pipeline, the HEXISTS Future (resolves to true or false; the Future itself is always truthy).

Parameters:

  • field (String, Symbol) —

    the field name

Returns:

  • (Boolean, Redis::Future) —

    whether the field exists. Inside a transaction or pipeline, the HEXISTS Future (resolves to true or false; the Future itself is always truthy).



256
257
258
# File 'lib/familia/data_type/types/hashkey.rb', line 256

def key?(field)
  dbclient.hexists dbkey, field.to_s
end

#keys ⇒ Object



192
193
194
# File 'lib/familia/data_type/types/hashkey.rb', line 192

def keys
  dbclient.hkeys dbkey
end

#persist_fields(*fields) ⇒ Array<Integer> Also known as: hpersist

Note:

Requires Redis 7.4+

Removes expiration from one or more hash fields.

Examples:

Remove expiration from fields

my_hash.persist_fields('important_data')  #=> [1]

Parameters:

  • fields (Array<String>) —

    One or more field names

Returns:

  • (Array<Integer>) —

    Array of results for each field: -2 if field does not exist, -1 if field has no expiration, 1 if expiration was removed



564
565
566
# File 'lib/familia/data_type/types/hashkey.rb', line 564

def persist_fields(*fields)
  call_hash_field_command('HPERSIST', fields: fields)
end

#pexpire_fields(milliseconds, *fields) ⇒ Array<Integer> Also known as: hpexpire

Note:

Requires Redis 7.4+

Sets expiration time in milliseconds on one or more hash fields.

Examples:

Set 500ms TTL on a field

my_hash.pexpire_fields(500, 'rate_limit_counter')

Parameters:

  • milliseconds (Integer) —

    TTL in milliseconds

  • fields (Array<String>) —

    One or more field names

Returns:

  • (Array<Integer>) —

    Array of results for each field



492
493
494
# File 'lib/familia/data_type/types/hashkey.rb', line 492

def pexpire_fields(milliseconds, *fields)
  call_hash_field_command('HPEXPIRE', milliseconds, fields: fields)
end

#pexpireat_fields(unix_time_ms, *fields) ⇒ Array<Integer> Also known as: hpexpireat

Note:

Requires Redis 7.4+

Sets absolute expiration time (Unix timestamp in milliseconds) on hash fields.

Examples:

Expire field at a precise millisecond

my_hash.pexpireat_fields(1700000000000, 'precise_data')

Parameters:

  • unix_time_ms (Integer) —

    Absolute Unix timestamp in milliseconds

  • fields (Array<String>) —

    One or more field names

Returns:

  • (Array<Integer>) —

    Array of results for each field



521
522
523
# File 'lib/familia/data_type/types/hashkey.rb', line 521

def pexpireat_fields(unix_time_ms, *fields)
  call_hash_field_command('HPEXPIREAT', unix_time_ms, fields: fields)
end

#pexpiretime_fields(*fields) ⇒ Array<Integer> Also known as: hpexpiretime

Note:

Requires Redis 7.4+

Returns the absolute Unix expiration timestamp in milliseconds for hash fields.

Examples:

Get precise expiration timestamp

my_hash.pexpiretime_fields('session')  #=> [1700000000000]

Parameters:

  • fields (Array<String>) —

    One or more field names

Returns:

  • (Array<Integer>) —

    Array of timestamps in milliseconds



592
593
594
# File 'lib/familia/data_type/types/hashkey.rb', line 592

def pexpiretime_fields(*fields)
  call_hash_field_command('HPEXPIRETIME', fields: fields)
end

#pttl_fields(*fields) ⇒ Array<Integer> Also known as: hpttl

Note:

Requires Redis 7.4+

Returns the remaining TTL in milliseconds for one or more hash fields.

Examples:

Check remaining TTL in milliseconds

my_hash.pttl_fields('rate_limit')  #=> [450]

Parameters:

  • fields (Array<String>) —

    One or more field names

Returns:

  • (Array<Integer>) —

    Array of TTL values in milliseconds



549
550
551
# File 'lib/familia/data_type/types/hashkey.rb', line 549

def pttl_fields(*fields)
  call_hash_field_command('HPTTL', fields: fields)
end

#randfield(count = nil, withvalues: false) ⇒ String, ... Also known as: hrandfield

Returns one or more random fields from the hash.

Examples:

Get a single random field

my_hash.randfield  #=> "some_field"

Get 3 distinct random fields

my_hash.randfield(3)  #=> ["field1", "field2", "field3"]

Get 2 random fields with values

my_hash.randfield(2, withvalues: true)  #=> [["field1", value1], ["field2", value2]]

Parameters:

  • count (Integer, nil) (defaults to: nil) —

    Number of fields to return. If nil, returns a single field. If positive, returns distinct fields. If negative, allows duplicates.

  • withvalues (Boolean) (defaults to: false) —

    If true, returns fields with their values

Returns:

  • (String, Array<String>, Array<Array>, Redis::Future) —

    Depending on arguments:

    • No count: single field name (or nil if hash is empty)
    • With count: array of field names
    • With count and withvalues: array of [field, value] pairs Inside a transaction or pipeline, the HRANDFIELD Future (resolves to the same shape, with values still serialized).


445
446
447
448
449
450
451
452
453
454
455
456
457
# File 'lib/familia/data_type/types/hashkey.rb', line 445

def randfield(count = nil, withvalues: false)
  if count.nil?
    dbclient.hrandfield(dbkey)
  elsif withvalues
    # redis-rb already groups the flat WITHVALUES reply into
    # [field, value] pairs, so only the values need deserializing.
    Familia.transform_reply(dbclient.hrandfield(dbkey, count, withvalues: true)) do |pairs|
      pairs.map { |field, val| [field, deserialize_value(val)] }
    end
  else
    dbclient.hrandfield(dbkey, count)
  end
end

#refresh ⇒ self

Confirms the hash exists and returns self.

Runs #refresh! and discards the fields it read. Like refresh! it is read-only. A method chained after it sends its own command, so it sees the hash as it is at that later moment, not as refresh read it. Use the return value of #refresh! when the fields must come from the same read as the existence check.

Examples:

Fail fast on a missing hash, then read one field

user.settings.refresh['theme']  #=> "dark"

Returns:

  • (self)

Raises:

See Also:



722
723
724
725
# File 'lib/familia/data_type/types/hashkey.rb', line 722

def refresh
  refresh!
  self
end

#refresh! ⇒ Hash{String => Object}

Confirms the hash exists and returns its fields as stored right now.

A HashKey keeps no field values in memory: every read method queries the database (see "Live Proxies, Not Cached Relations" on DataType), so there is no local copy to reload. refresh! reads the whole hash with one HGETALL, raises when the reply is empty, and returns what it read.

It is read-only. It sends no command besides the HGETALL: it does not write the fields back, does not change the key's expiration, and does not run the dirty-write check that collection writes run against the parent object.

The returned Hash is a new object each call. Reads made later through this HashKey query the database again and see writes made after this call.

Examples:

Read the fields, raising when the hash is gone

user.settings.refresh!  #=> {"theme" => "dark", "lang" => "en"}

Treat a missing hash as empty

begin
  user.settings.refresh!
rescue Familia::KeyNotFoundError
  {}
end

Returns:

  • (Hash{String => Object}) —

    every field with its deserialized value, as #hgetall returns them

Raises:

  • (Familia::KeyNotFoundError) —

    when the hash does not exist. A hash with no fields does not exist, so one whose last field was removed raises too.

  • (Familia::OperationModeError) —

    inside a transaction or pipeline, where HGETALL is only queued and returns a Redis::Future, so a missing key cannot be detected.

See Also:



686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
# File 'lib/familia/data_type/types/hashkey.rb', line 686

def refresh!
  if Fiber[:familia_transaction] || Fiber[:familia_pipeline]
    raise Familia::OperationModeError,
          'HashKey#refresh! cannot run inside a transaction or pipeline: ' \
          'HGETALL returns a Redis::Future there, so a missing key cannot ' \
          'be detected. Call it before opening the block.'
  end

  Familia.trace :REFRESH, nil, self.class.uri if Familia.debug?
  fields = hgetall
  # A hash with no fields does not exist, so an empty reply means the
  # key is missing. Checking the reply instead of a separate EXISTS
  # leaves no gap for the key to expire or be deleted before the read.
  raise Familia::KeyNotFoundError, dbkey if fields.empty?

  Familia.debug "[refresh!] #{self.class} #{Familia.loggable_text(dbkey)} #{fields.keys}" if Familia.debug?
  fields
end

#release_field(field, val) ⇒ Integer, Redis::Future

Deletes +field+ only if it currently holds a value equivalent to +val+.

The release half of the claim protocol. An unconditional HDEL lets a stale in-memory value delete a claim another record now legitimately owns -- the same shared-key overwrite #claim_field closes on the way in.

Unlike #claim_field this is safe to queue inside a MULTI: it needs no return value to decide anything, so the script's atomicity still holds at EXEC time.

Parameters:

  • field (String, Symbol) —

    hash field to release

  • val (Object) —

    the value the caller believes it owns

Returns:

  • (Integer, Redis::Future) —

    1 if deleted, 0 if absent or not ours

See Also:



111
112
113
114
115
116
117
118
119
120
121
122
123
# File 'lib/familia/data_type/types/hashkey.rb', line 111

def release_field(field, val)
  ret = dbclient.eval(
    RELEASE_FIELD_SCRIPT, keys: [dbkey], argv: [field.to_s, *ownership_variants(val)]
  )
  # Refreshed unconditionally, matching #[]= -- a release that deleted
  # nothing still touched the index key's TTL policy, and `ret` cannot gate
  # it anyway: inside a MULTI (where this method is explicitly safe to
  # queue) `ret` is a Future with no value to test. On an index hash with
  # no default_expiration -- the usual case -- this returns early without
  # issuing a command.
  update_expiration
  ret
end

#remove_field(field) ⇒ Integer Also known as: remove, remove_element

Removes a field from the hash

Parameters:

  • field (String) —

    The field to remove

Returns:

  • (Integer) —

    The number of fields that were removed (0 or 1)



266
267
268
269
270
271
# File 'lib/familia/data_type/types/hashkey.rb', line 266

def remove_field(field)
  warn_if_dirty!
  ret = dbclient.hdel dbkey, field.to_s
  update_expiration
  ret
end

#scan(cursor = 0, match: nil, count: nil) ⇒ Array<Integer, Hash>, Redis::Future Also known as: hscan

Incrementally iterates over fields in the hash using cursor-based iteration. This is more memory-efficient than hgetall for large hashes.

Examples:

Basic iteration

cursor = 0
loop do
  cursor, results = my_hash.scan(cursor)
  results.each { |field, value| puts "#{field}: #{value}" }
  break if cursor == 0
end

With pattern matching

cursor, results = my_hash.scan(0, match: "user:*", count: 100)

Parameters:

  • cursor (Integer) (defaults to: 0) —

    The cursor position to start from (0 for initial call)

  • match (String, nil) (defaults to: nil) —

    Optional glob-style pattern to filter field names

  • count (Integer, nil) (defaults to: nil) —

    Optional hint for number of elements to return per call

Returns:

  • (Array<Integer, Hash>, Redis::Future) —

    A two-element array: [new_cursor, => value, ...]. When new_cursor is 0, iteration is complete. Inside a transaction or pipeline, the HSCAN Future.



379
380
381
382
383
384
385
386
387
388
389
390
# File 'lib/familia/data_type/types/hashkey.rb', line 379

def scan(cursor = 0, match: nil, count: nil)
  opts = {}
  opts[:match] = match if match
  opts[:count] = count if count

  Familia.transform_reply(dbclient.hscan(dbkey, cursor, **opts)) do |(new_cursor, pairs)|
    # pairs is an array of [field, value] pairs, convert to hash with deserialization
    result_hash = pairs.to_h.transform_values { |v| deserialize_value(v) }

    [new_cursor.to_i, result_hash]
  end
end

#strlen(field) ⇒ Integer Also known as: hstrlen

Returns the string length of the value associated with field.

Examples:

my_hash['name'] = 'Alice'
my_hash.strlen('name')  #=> 7 (includes JSON quotes: "Alice")

Parameters:

  • field (String) —

    The field name

Returns:

  • (Integer) —

    The length of the value in bytes, or 0 if field does not exist



419
420
421
# File 'lib/familia/data_type/types/hashkey.rb', line 419

def strlen(field)
  dbclient.hstrlen(dbkey, field.to_s)
end

#ttl_fields(*fields) ⇒ Array<Integer> Also known as: httl

Note:

Requires Redis 7.4+

Returns the remaining TTL in seconds for one or more hash fields.

Examples:

Check remaining TTL on fields

my_hash.ttl_fields('session_token', 'temp_data')  #=> [3600, -1]

Parameters:

  • fields (Array<String>) —

    One or more field names

Returns:

  • (Array<Integer>) —

    Array of TTL values for each field: -2 if field does not exist, -1 if field has no expiration, otherwise the TTL in seconds



536
537
538
# File 'lib/familia/data_type/types/hashkey.rb', line 536

def ttl_fields(*fields)
  call_hash_field_command('HTTL', fields: fields)
end

#update(hsh = {}) ⇒ Object Also known as: merge!

Raises:

  • (ArgumentError)


300
301
302
303
304
305
306
307
308
309
# File 'lib/familia/data_type/types/hashkey.rb', line 300

def update(hsh = {})
  warn_if_dirty!
  raise ArgumentError, 'Argument to bulk_set must be a hash' unless hsh.is_a?(Hash)

  data = hsh.inject([]) { |ret, pair| ret << [pair[0], serialize_value(pair[1])] }.flatten

  ret = dbclient.hmset(dbkey, *data)
  update_expiration
  ret
end

#values ⇒ Array, Redis::Future

Returns Deserialized values. Inside a transaction or pipeline, the HVALS Future (resolves to the raw values).

Returns:

  • (Array, Redis::Future) —

    Deserialized values. Inside a transaction or pipeline, the HVALS Future (resolves to the raw values).



199
200
201
202
203
# File 'lib/familia/data_type/types/hashkey.rb', line 199

def values
  Familia.transform_reply(dbclient.hvals(dbkey)) do |vals|
    vals.map { |v| deserialize_value v }
  end
end

#values_at(*fields) ⇒ Array, Redis::Future

Returns Deserialized values of +fields+, with missing fields dropped. Inside a transaction or pipeline, the HMGET Future (resolves to the raw values, with nil for missing fields).

Returns:

  • (Array, Redis::Future) —

    Deserialized values of +fields+, with missing fields dropped. Inside a transaction or pipeline, the HMGET Future (resolves to the raw values, with nil for missing fields).



315
316
317
318
319
320
# File 'lib/familia/data_type/types/hashkey.rb', line 315

def values_at *fields
  string_fields = fields.flatten.compact.map(&:to_s)
  Familia.transform_reply(dbclient.hmget(dbkey, *string_fields)) do |elements|
    deserialize_values(*elements)
  end
end