123456789_123456789_123456789_123456789_123456789_

Module: Redis::Commands::Hashes

Relationships & Source Files
Extension / Inclusion / Inheritance Descendants
Included In:
::Redis, ::Redis::Commands, ::Redis::MultiConnection, ::Redis::PipelinedConnection
Defined in: lib/redis/commands/hashes.rb

Instance Method Summary

Instance Method Details

#hash_field_expiration_condition(nx, xx, gt, lt) (private)

The HEXPIRE command family accepts a single optional condition token ([NX | XX | GT | LT]); the server rejects combinations, so fail fast in Ruby.

Raises:

  • (ArgumentError)
[ GitHub ] 

  


# File 'lib/redis/commands/hashes.rb', line 653



def hash_field_expiration_condition(nx, xx, gt, lt)
  condition = []
  condition << "NX" if nx
  condition << "XX" if xx
  condition << "GT" if gt
  condition << "LT" if lt
  raise ArgumentError, "only one of :nx, :xx, :gt, :lt can be specified" if condition.size > 1

  condition
end


  








  

    #hdel(key, *fields)  ⇒ Integer 
  



  

    
Delete one or more hash fields.

  





  
Parameters:


    
  
  • 
    key
    (String)
  
    • 
  
  • 
    field
    (String, Array<String>)
  
    • 



Returns:


    
  
  • 
    (Integer)
—    
    the number of fields that were removed from the hash
    
  
    • 





  [ GitHub ]


  

  


# File 'lib/redis/commands/hashes.rb', line 157



def hdel(key, *fields)
  fields.flatten!(1)
  send_command([:hdel, key].concat(fields))
end


  








  

    #hexists(key, field)  ⇒ Boolean 
  



  

    
Determine if a hash field exists.

  





  
Parameters:


    
  
  • 
    key
    (String)
  
    • 
  
  • 
    field
    (String)
  
    • 



Returns:


    
  
  • 
    (Boolean)
—    
    whether or not the field exists in the hash
    
  
    • 





  [ GitHub ]


  

  


# File 'lib/redis/commands/hashes.rb', line 267



def hexists(key, field)
  send_command([:hexists, key, field], &Boolify)
end


  








  

    #hexpire(key, ttl, *fields, nx: nil, xx: nil, gt: nil, lt: nil)  ⇒ Array<Integer> 
  



  

    
Sets the time to live in seconds for one or more fields.


See https://redis.io/docs/latest/commands/hexpire/#return-information for array reply.

  





    

    
Examples:

      
redis.hset("hash", "f1", "v1")
redis.hexpire("hash", 10, "f1", "f2") # => [1, -2]
redis.hexpire("hash", 10, "f1", "f2", nx: true) # => [0, -2]

  


Parameters:


    
  
  • 
    key
    (String)
  
    • 
  
  • 
    ttl
    (Integer)
  
    • 
  
  • 
    options
    (Hash)
—    
      

    • :nx => true: Set expiry only when the field has no expiry.
      • 

    • :xx => true: Set expiry only when the field has an existing expiry.
      • 

    • :gt => true: Set expiry only when the new expiry is greater than current one.
      • 

    • :lt => true: Set expiry only when the new expiry is less than current one.
      • 

    
  
    • 
  
  • 
    fields
    (Array<String>)
  
    • 



Returns:


    
  
  • 
    (Array<Integer>)
—    
    Feedback on if the fields have been updated.
    
  
    • 



Raises:


    
  
  • 
    (ArgumentError)
—    
    when more than one of :nx, :xx, :gt, :lt is given
    
  
    • 





  [ GitHub ]


  

  


# File 'lib/redis/commands/hashes.rb', line 385



def hexpire(key, ttl, *fields, nx: nil, xx: nil, gt: nil, lt: nil)
  fields.flatten!(1)
  args = [:hexpire, key, Integer(ttl)]
  args.concat(hash_field_expiration_condition(nx, xx, gt, lt))
  args.concat(['FIELDS', fields.length, *fields])

  send_command(args)
end


  








  

    #hexpireat(key, unix_time_seconds, *fields, nx: nil, xx: nil, gt: nil, lt: nil)  ⇒ Array<Integer> 
  



  

    
Sets the expiration for one or more fields as an absolute Unix
timestamp in seconds. A timestamp in the past deletes the field
immediately.


See https://redis.io/docs/latest/commands/hexpireat/#return-information for array reply.

  





    

    
Examples:

      
redis.hset("hash", "f1", "v1")
redis.hexpireat("hash", Time.now.to_i + 10, "f1", "f2") # => [1, -2]
redis.hexpireat("hash", Time.now.to_i - 10, "f1") # => [2]

  


Parameters:


    
  
  • 
    key
    (String)
  
    • 
  
  • 
    unix_time_seconds
    (Integer)
—    
    absolute expiration timestamp in seconds since epoch
    
  
    • 
  
  • 
    options
    (Hash)
—    
      

    • :nx => true: Set expiry only when the field has no expiry.
      • 

    • :xx => true: Set expiry only when the field has an existing expiry.
      • 

    • :gt => true: Set expiry only when the new expiry is greater than current one.
      • 

    • :lt => true: Set expiry only when the new expiry is less than current one.
      • 

    
  
    • 
  
  • 
    fields
    (Array<String>)
  
    • 



Returns:


    
  
  • 
    (Array<Integer>)
—    
    Feedback on if the fields have been updated.
    
  
    • 



Raises:


    
  
  • 
    (ArgumentError)
—    
    when more than one of :nx, :xx, :gt, :lt is given
    
  
    • 





  [ GitHub ]


  

  


# File 'lib/redis/commands/hashes.rb', line 477



def hexpireat(key, unix_time_seconds, *fields, nx: nil, xx: nil, gt: nil, lt: nil)
  fields.flatten!(1)
  args = [:hexpireat, key, Integer(unix_time_seconds)]
  args.concat(hash_field_expiration_condition(nx, xx, gt, lt))
  args.concat(['FIELDS', fields.length, *fields])

  send_command(args)
end


  








  

    #hexpiretime(key, *fields)  ⇒ Array<Integer> 
  



  

    
Returns the expiration time of one or more fields as an absolute Unix
timestamp in seconds.


See https://redis.io/docs/latest/commands/hexpiretime/#return-information for array reply.

  





    

    
Examples:

      
redis.hset("hash", "f1", "v1", "f2", "v2")
redis.hexpireat("hash", Time.now.to_i + 100, "f1")
redis.hexpiretime("hash", "f1", "f2", "f3") # => [<unix timestamp in seconds>, -1, -2]

  


Parameters:


    
  
  • 
    key
    (String)
  
    • 
  
  • 
    fields
    (Array<String>)
  
    • 



Returns:


    
  
  • 
    (Array<Integer>)
—    
    Expiration Unix timestamps of the fields in seconds.
    
  
    • 





  [ GitHub ]


  

  


# File 'lib/redis/commands/hashes.rb', line 529



def hexpiretime(key, *fields)
  fields.flatten!(1)
  send_command([:hexpiretime, key, 'FIELDS', fields.length, *fields])
end


  








  

    #hget(key, field)  ⇒ String 
  



  

    
Get the value of a hash field.

  





  
Parameters:


    
  
  • 
    key
    (String)
  
    • 
  
  • 
    field
    (String)
  
    • 





  [ GitHub ]


  

  


# File 'lib/redis/commands/hashes.rb', line 75



def hget(key, field)
  send_command([:hget, key, field])
end


  








  

    #hgetall(key)  ⇒ Hash<String, String> 
  



  

    
Get all the fields and values in a hash.

  





  
Parameters:


    
  
  • 
    key
    (String)
  
    • 





  [ GitHub ]


  

  


# File 'lib/redis/commands/hashes.rb', line 311



def hgetall(key)
  send_command([:hgetall, key], &Hashify)
end


  








  

    #hgetdel(key, *fields)  ⇒ Array<String, nil> 
  



  

    
Get the value of one or more hash fields and delete them.

  





    

    
Examples:

      
redis.hset("hash", "f1", "v1", "f2", "v2")
redis.hgetdel("hash", "f1", "f2") # => ["v1", "v2"]
redis.hgetdel("hash", "f1", "f3") # => [nil, nil]

  


Parameters:


    
  
  • 
    key
    (String)
  
    • 
  
  • 
    fields
    (Array<String>)
  
    • 



Returns:


    
  
  • 
    (Array<String, nil>)
—    
    the value of each requested field, nil for fields that
did not exist
    
  
    • 





  [ GitHub ]


  

  


# File 'lib/redis/commands/hashes.rb', line 173



def hgetdel(key, *fields)
  fields.flatten!(1)
  send_command([:hgetdel, key, 'FIELDS', fields.length, *fields])
end


  








  

    #hgetex(key, *fields, ex: nil, px: nil, exat: nil, pxat: nil, persist: false)  ⇒ Array<String, nil> 
  



  

    
Get the value of one or more hash fields and optionally set their expiration. HGETEX is
similar to HMGET, but is a write command with additional options. When no options are
provided, HGETEX behaves like HMGET.

  





    

    
Examples:

      
redis.hset("hash", "f1", "v1", "f2", "v2")
redis.hgetex("hash", "f1", "f2") # => ["v1", "v2"]
redis.hgetex("hash", "f1", ex: 60) # => ["v1"]

  


Parameters:


    
  
  • 
    key
    (String)
  
    • 
  
  • 
    fields
    (Array<String>)
  
    • 
  
  • 
    options
    (Hash)
—    
      

    • :ex => Integer: Set the specified expire time on the fields, in seconds.
      • 

    • :px => Integer: Set the specified expire time on the fields, in milliseconds.
      • 

    • :exat => Integer: Set the specified Unix time at which the fields will expire, in
seconds.
      • 

    • :pxat => Integer: Set the specified Unix time at which the fields will expire, in
milliseconds.
      • 

    • :persist => true: Remove the time to live associated with the fields.
      • 

    
  
    • 



Returns:


    
  
  • 
    (Array<String, nil>)
—    
    the value of each requested field, nil for fields that
did not exist
    
  
    • 





  [ GitHub ]


  

  


# File 'lib/redis/commands/hashes.rb', line 199



def hgetex(key, *fields, ex: nil, px: nil, exat: nil, pxat: nil, persist: false)
  if [ex, px, exat, pxat, persist].count { |option| option } > 1
    raise ArgumentError, "ex, px, exat, pxat, and persist are mutually exclusive"
  end

  fields.flatten!(1)
  args = [:hgetex, key]
  args << "EX" << Integer(ex) if ex
  args << "PX" << Integer(px) if px
  args << "EXAT" << Integer(exat) if exat
  args << "PXAT" << Integer(pxat) if pxat
  args << "PERSIST" if persist
  args.concat(['FIELDS', fields.length, *fields])

  send_command(args)
end


  








  

    #himport_discard(fieldset_name)  ⇒ Integer 
  



  

    
  

    Note:
    
HIMPORT support is experimental: the client API may change in a
future minor release without a major version bump.

  



Remove fieldset_name from this connection's session. Keys already
written through the fieldset are not affected.

  





  
Parameters:


    
  
  • 
    fieldset_name
    (String)
  
    • 



Returns:


    
  
  • 
    (Integer)
—    
    1 if the fieldset was removed, 0 if it did not exist
    
  
    • 





  [ GitHub ]


  

  


# File 'lib/redis/commands/hashes.rb', line 634



def himport_discard(fieldset_name)
  send_command([:himport, "DISCARD", fieldset_name])
end


  








  

    #himport_discard_all  ⇒ Integer 
  



  

    
  

    Note:
    
HIMPORT support is experimental: the client API may change in a
future minor release without a major version bump.

  



Remove all fieldsets from this connection's session.

  





  
Returns:


    
  
  • 
    (Integer)
—    
    number of fieldsets removed
    
  
    • 





  [ GitHub ]


  

  


# File 'lib/redis/commands/hashes.rb', line 645



def himport_discard_all
  send_command([:himport, "DISCARDALL"])
end


  








  

    #himport_prepare(fieldset_name, *fields)  ⇒ String 
  



  

    
  

    Note:
    
HIMPORT support is experimental: the client API may change in a
future minor release without a major version bump.

  



Register an ordered list of hash field names under fieldset_name for
use by subsequent #himport_set calls on the same connection.


Fieldsets are server-side session state scoped to the current physical
connection: they vanish on disconnect or RESET and are invisible to
other connections. See the README "Bulk hash ingestion (HIMPORT)"
section for connection-scoping guidance. Re-preparing an existing
fieldset_name silently replaces it. Field order is preserved as
given; it defines the positional pairing used by #himport_set.

  





    

    
Examples:

      
redis.himport_prepare("shared", ["name", "email", "age"])
  # => "OK"

  


Parameters:


    
  
  • 
    fieldset_name
    (String)
—    
    name used by later SET and DISCARD calls
    
  
    • 
  
  • 
    fields
    (String, Array<String>)
—    
    one or more field names
    
  
    • 



Returns:


    
  
  • 
    (String)
—    
    "OK"
    
  
    • 



Raises:


    
  
  • 
    (ArgumentError)
  
    • 





  [ GitHub ]


  

  


# File 'lib/redis/commands/hashes.rb', line 591



def himport_prepare(fieldset_name, *fields)
  fields.flatten!(1)
  raise ArgumentError, "fields must not be empty" if fields.empty?

  send_command([:himport, "PREPARE", fieldset_name].concat(fields))
end


  








  

    #himport_set(key, fieldset_name, *values)  ⇒ String 
  



  

    
  

    Note:
    
HIMPORT support is experimental: the client API may change in a
future minor release without a major version bump.

  



Create or fully replace the hash at key using the field list
registered under fieldset_name on this connection. Values pair
positionally with the fields given to #himport_prepare; the value
count must equal the field count.


The fieldset must exist on the executing connection, otherwise the
server replies with a "no such fieldset" error.

  





    

    
Examples:

      
redis.himport_set("shared:1", "shared", ["alice", "alice@example.com", "25"])
  # => "OK"

  


Parameters:


    
  
  • 
    key
    (String)
—    
    hash key to create or overwrite
    
  
    • 
  
  • 
    fieldset_name
    (String)
—    
    fieldset previously prepared on this connection
    
  
    • 
  
  • 
    values
    (String, Array<String>)
—    
    one or more values, order preserved
    
  
    • 



Returns:


    
  
  • 
    (String)
—    
    "OK"
    
  
    • 



Raises:


    
  
  • 
    (ArgumentError)
  
    • 





  [ GitHub ]


  

  


# File 'lib/redis/commands/hashes.rb', line 618



def himport_set(key, fieldset_name, *values)
  values.flatten!(1)
  raise ArgumentError, "values must not be empty" if values.empty?

  send_command([:himport, "SET", key, fieldset_name].concat(values))
end


  








  

    #hincrby(key, field, increment)  ⇒ Integer 
  



  

    
Increment the integer value of a hash field by the given integer number.

  





  
Parameters:


    
  
  • 
    key
    (String)
  
    • 
  
  • 
    field
    (String)
  
    • 
  
  • 
    increment
    (Integer)
  
    • 



Returns:


    
  
  • 
    (Integer)
—    
    value of the field after incrementing it
    
  
    • 





  [ GitHub ]


  

  


# File 'lib/redis/commands/hashes.rb', line 277



def hincrby(key, field, increment)
  send_command([:hincrby, key, field, Integer(increment)])
end


  








  

    #hincrbyfloat(key, field, increment)  ⇒ Float 
  



  

    
Increment the numeric value of a hash field by the given float number.

  





  
Parameters:


    
  
  • 
    key
    (String)
  
    • 
  
  • 
    field
    (String)
  
    • 
  
  • 
    increment
    (Float)
  
    • 



Returns:


    
  
  • 
    (Float)
—    
    value of the field after incrementing it
    
  
    • 





  [ GitHub ]


  

  


# File 'lib/redis/commands/hashes.rb', line 287



def hincrbyfloat(key, field, increment)
  send_command([:hincrbyfloat, key, field, Float(increment)], &Floatify)
end


  








  

    #hkeys(key)  ⇒ Array<String> 
  



  

    
Get all the fields in a hash.

  





  
Parameters:


    
  
  • 
    key
    (String)
  
    • 





  [ GitHub ]


  

  


# File 'lib/redis/commands/hashes.rb', line 295



def hkeys(key)
  send_command([:hkeys, key])
end


  








  

    #hlen(key)  ⇒ Integer 
  



  

    
Get the number of fields in a hash.

  





  
Parameters:


    
  
  • 
    key
    (String)
  
    • 



Returns:


    
  
  • 
    (Integer)
—    
    number of fields in the hash
    
  
    • 





  [ GitHub ]


  

  


# File 'lib/redis/commands/hashes.rb', line 10



def hlen(key)
  send_command([:hlen, key])
end


  








  

    #hmget(key, *fields, &blk)  ⇒ Array<String> 
  



  

    
Get the values of all the given hash fields.

  





    

    
Examples:

      
redis.hmget("hash", "f1", "f2")
  # => ["v1", "v2"]

  


Parameters:


    
  
  • 
    key
    (String)
  
    • 
  
  • 
    fields
    (Array<String>)
—    
    array of fields
    
  
    • 



Returns:


    
  
  • 
    (Array<String>)
—    
    an array of values for the specified fields
    
  
    • 


  
See Also:

  



  [ GitHub ]


  

  


# File 'lib/redis/commands/hashes.rb', line 90



def hmget(key, *fields, &blk)
  fields.flatten!(1)
  send_command([:hmget, key].concat(fields), &blk)
end


  








  

    #hmset(key, *attrs)  ⇒ String 
  



  

    
Set one or more hash values.

  





    

    
Examples:

      
redis.hmset("hash", "f1", "v1", "f2", "v2")
  # => "OK"

  


Parameters:


    
  
  • 
    key
    (String)
  
    • 
  
  • 
    attrs
    (Array<String>)
—    
    array of fields and values
    
  
    • 



Returns:


    
  
  • 
    (String)
—    
    "OK"
    
  
    • 


  
See Also:

  



  [ GitHub ]


  

  


# File 'lib/redis/commands/hashes.rb', line 51



def hmset(key, *attrs)
  send_command([:hmset, key] + attrs)
end


  








  

    #hpersist(key, *fields)  ⇒ Array<Integer> 
  



  

    
Removes the expiration from one or more fields, making them persistent.


See https://redis.io/docs/latest/commands/hpersist/#return-information for array reply.

  





    

    
Examples:

      
redis.hset("hash", "f1", "v1", "f2", "v2")
redis.hexpire("hash", 100, "f1")
redis.hpersist("hash", "f1", "f2", "f3") # => [1, -1, -2]

  


Parameters:


    
  
  • 
    key
    (String)
  
    • 
  
  • 
    fields
    (Array<String>)
  
    • 



Returns:


    
  
  • 
    (Array<Integer>)
—    
    1 when the expiration was removed, -1 when the
field has no expiration, -2 when the field or key does not exist.
    
  
    • 





  [ GitHub ]


  

  


# File 'lib/redis/commands/hashes.rb', line 565



def hpersist(key, *fields)
  fields.flatten!(1)
  send_command([:hpersist, key, 'FIELDS', fields.length, *fields])
end


  








  

    #hpexpire(key, ttl, *fields, nx: nil, xx: nil, gt: nil, lt: nil)  ⇒ Array<Integer> 
  



  

    
Sets the time to live in milliseconds for one or more fields.


See https://redis.io/docs/latest/commands/hpexpire/#return-information for array reply.

  





    

    
Examples:

      
redis.hset("hash", "f1", "v1")
redis.hpexpire("hash", 500, "f1", "f2") # => [1, -2]
redis.hpexpire("hash", 500, "f1", "f2", nx: true) # => [0, -2]

  


Parameters:


    
  
  • 
    key
    (String)
  
    • 
  
  • 
    ttl
    (Integer)
  
    • 
  
  • 
    options
    (Hash)
—    
      

    • :nx => true: Set expiry only when the key has no expiry.
      • 

    • :xx => true: Set expiry only when the key has an existing expiry.
      • 

    • :gt => true: Set expiry only when the new expiry is greater than current one.
      • 

    • :lt => true: Set expiry only when the new expiry is less than current one.
      • 

    
  
    • 
  
  • 
    fields
    (Array<String>)
  
    • 



Returns:


    
  
  • 
    (Array<Integer>)
—    
    Feedback on if the fields have been updated.
    
  
    • 



Raises:


    
  
  • 
    (ArgumentError)
—    
    when more than one of :nx, :xx, :gt, :lt is given
    
  
    • 





  [ GitHub ]


  

  


# File 'lib/redis/commands/hashes.rb', line 430



def hpexpire(key, ttl, *fields, nx: nil, xx: nil, gt: nil, lt: nil)
  fields.flatten!(1)
  args = [:hpexpire, key, Integer(ttl)]
  args.concat(hash_field_expiration_condition(nx, xx, gt, lt))
  args.concat(['FIELDS', fields.length, *fields])

  send_command(args)
end


  








  

    #hpexpireat(key, unix_time_milliseconds, *fields, nx: nil, xx: nil, gt: nil, lt: nil)  ⇒ Array<Integer> 
  



  

    
Sets the expiration for one or more fields as an absolute Unix
timestamp in milliseconds. A timestamp in the past deletes the field
immediately.


See https://redis.io/docs/latest/commands/hpexpireat/#return-information for array reply.

  





    

    
Examples:

      
redis.hset("hash", "f1", "v1")
redis.hpexpireat("hash", (Time.now.to_f * 1000).to_i + 500, "f1", "f2") # => [1, -2]
redis.hpexpireat("hash", (Time.now.to_f * 1000).to_i - 500, "f1") # => [2]

  


Parameters:


    
  
  • 
    key
    (String)
  
    • 
  
  • 
    unix_time_milliseconds
    (Integer)
—    
    absolute expiration timestamp in milliseconds since epoch
    
  
    • 
  
  • 
    options
    (Hash)
—    
      

    • :nx => true: Set expiry only when the field has no expiry.
      • 

    • :xx => true: Set expiry only when the field has an existing expiry.
      • 

    • :gt => true: Set expiry only when the new expiry is greater than current one.
      • 

    • :lt => true: Set expiry only when the new expiry is less than current one.
      • 

    
  
    • 
  
  • 
    fields
    (Array<String>)
  
    • 



Returns:


    
  
  • 
    (Array<Integer>)
—    
    Feedback on if the fields have been updated.
    
  
    • 



Raises:


    
  
  • 
    (ArgumentError)
—    
    when more than one of :nx, :xx, :gt, :lt is given
    
  
    • 





  [ GitHub ]


  

  


# File 'lib/redis/commands/hashes.rb', line 507



def hpexpireat(key, unix_time_milliseconds, *fields, nx: nil, xx: nil, gt: nil, lt: nil)
  fields.flatten!(1)
  args = [:hpexpireat, key, Integer(unix_time_milliseconds)]
  args.concat(hash_field_expiration_condition(nx, xx, gt, lt))
  args.concat(['FIELDS', fields.length, *fields])

  send_command(args)
end


  








  

    #hpexpiretime(key, *fields)  ⇒ Array<Integer> 
  



  

    
Returns the expiration time of one or more fields as an absolute Unix
timestamp in milliseconds.


See https://redis.io/docs/latest/commands/hpexpiretime/#return-information for array reply.

  





    

    
Examples:

      
redis.hset("hash", "f1", "v1", "f2", "v2")
redis.hpexpireat("hash", (Time.now.to_f * 1000).to_i + 100_000, "f1")
redis.hpexpiretime("hash", "f1", "f2", "f3") # => [<unix timestamp in milliseconds>, -1, -2]

  


Parameters:


    
  
  • 
    key
    (String)
  
    • 
  
  • 
    fields
    (Array<String>)
  
    • 



Returns:


    
  
  • 
    (Array<Integer>)
—    
    Expiration Unix timestamps of the fields in milliseconds.
    
  
    • 





  [ GitHub ]


  

  


# File 'lib/redis/commands/hashes.rb', line 547



def hpexpiretime(key, *fields)
  fields.flatten!(1)
  send_command([:hpexpiretime, key, 'FIELDS', fields.length, *fields])
end


  








  

    #hpttl(key, *fields)  ⇒ Array<Integer> 
  



  

    
Returns the time to live in milliseconds for one or more fields.


See https://redis.io/docs/latest/commands/hpttl/#return-information for array reply.

  





    

    
Examples:

      
redis.hset("hash", "f1", "v1", "f2", "v2")
redis.hpexpire("hash", 500, "f1") # => [1]
redis.hpttl("hash", "f1", "f2", "f3") # => [500, -1, -2]

  


Parameters:


    
  
  • 
    key
    (String)
  
    • 
  
  • 
    fields
    (Array<String>)
  
    • 



Returns:


    
  
  • 
    (Array<Integer>)
—    
    Feedback on the TTL of the fields.
    
  
    • 





  [ GitHub ]


  

  


# File 'lib/redis/commands/hashes.rb', line 451



def hpttl(key, *fields)
  fields.flatten!(1)
  send_command([:hpttl, key, 'FIELDS', fields.length, *fields])
end


  








  

    #hrandfield(key, count = nil, withvalues: false, with_values: withvalues)  ⇒ nil, ... 
  



  

    
Get one or more random fields from a hash.

  





    

    
Examples:

        
Get one random field

      
redis.hrandfield("hash")
  # => "f1"

        
Get multiple random fields

      
redis.hrandfield("hash", 2)
  # => ["f1, "f2"]

        
Get multiple random fields with values

      
redis.hrandfield("hash", 2, with_values: true)
  # => [["f1", "s1"], ["f2", "s2"]]

  


Parameters:


    
  
  • 
    key
    (String)
  
    • 
  
  • 
    count
    (Integer)
    (defaults to: nil)
  
    • 
  
  • 
    options
    (Hash)
—    
      

    • :with_values => true: include values in output
      • 

    
  
    • 



Returns:


    
  
  • 
    (nil, String, Array<String>, Array<[String, Float]>)
—    
      

    • when key does not exist, nil
      • 

    • when count is not specified, a field name
      • 

    • when count is specified and :with_values is not specified, an array of field names
      • 

    • when :with_values is specified, an array with [field, value] pairs
      • 

    
  
    • 





  [ GitHub ]


  

  


# File 'lib/redis/commands/hashes.rb', line 139



def hrandfield(key, count = nil, withvalues: false, with_values: withvalues)
  if with_values && count.nil?
    raise ArgumentError, "count argument must be specified"
  end

  args = [:hrandfield, key]
  args << count if count
  args << "WITHVALUES" if with_values

  parser = Pairify if with_values
  send_command(args, &parser)
end


  








  

    #hscan(key, cursor, **options)  ⇒ String, ... 
  



  

    
Scan a hash


See the Redis Server HSCAN documentation for further details

  





    

    
Examples:

        
Retrieve the first batch of key/value pairs in a hash

      
redis.hscan("hash", 0)

  


Parameters:


    
  
  • 
    cursor
    (String, Integer)
—    
    the cursor of the iteration
    
  
    • 
  
  • 
    options
    (Hash)
—    
      

    • :match => String: only return keys matching the pattern
      • 

    • :count => Integer: return count keys at most per iteration
      • 

    • :novalues => Boolean: whether or not to include values in the output (default: false)
      • 

    
  
    • 



Returns:


    
  
  • 
    (String, Array<[String, String]>, Array<String>)
—    
    the next cursor and all found keys
    

      

    • when :novalues is false: [cursor, [[field1, value1], [field2, value2], ...]]
      • 

    • when :novalues is true: [cursor, [field1, field2, ...]]
      • 

    
  
    • 





  [ GitHub ]


  

  


# File 'lib/redis/commands/hashes.rb', line 331



def hscan(key, cursor, **options)
  _scan(:hscan, cursor, [key], **options) do |reply|
    if options[:novalues]
      reply
    else
      [reply[0], reply[1].each_slice(2).to_a]
    end
  end
end


  








  

    #hscan_each(key, **options, &block)  ⇒ Enumerator 
  



  

    
Scan a hash


See the Redis Server HSCAN documentation for further details

  





    

    
Examples:

        
Retrieve all of the key/value pairs in a hash

      
redis.hscan_each("hash").to_a
# => [["key70", "70"], ["key80", "80"]]

  


Parameters:


    
  
  • 
    options
    (Hash)
—    
      

    • :match => String: only return keys matching the pattern
      • 

    • :count => Integer: return count keys at most per iteration
      • 

    • :novalues => Boolean: whether or not to include values in the output (default: false)
      • 

    
  
    • 



Returns:


    
  
  • 
    (Enumerator)
—    
    an enumerator for all found keys
    
  
    • 





  [ GitHub ]


  

  


# File 'lib/redis/commands/hashes.rb', line 355



def hscan_each(key, **options, &block)
  return to_enum(:hscan_each, key, **options) unless block_given?

  cursor = 0
  loop do
    cursor, values = hscan(key, cursor, **options)
    values.each(&block)
    break if cursor == "0"
  end
end


  








  

    #hset(key, *attrs)  ⇒ Integer 
  



  

    
Set one or more hash values.

  





    

    
Examples:

      
redis.hset("hash", "f1", "v1", "f2", "v2") # => 2
redis.hset("hash", { "f1" => "v1", "f2" => "v2" }) # => 2

  


Parameters:


    
  
  • 
    key
    (String)
  
    • 
  
  • 
    attrs
    (Array<String> | Hash<String, String>)
—    
    array or hash of fields and values
    
  
    • 



Returns:


    
  
  • 
    (Integer)
—    
    The number of fields that were added to the hash
    
  
    • 





  [ GitHub ]


  

  


# File 'lib/redis/commands/hashes.rb', line 23



def hset(key, *attrs)
  attrs = attrs.first.flatten if attrs.size == 1 && attrs.first.is_a?(Hash)
  return 0 if attrs.empty?

  send_command([:hset, key, *attrs])
end


  








  

    #hsetex(key, *attrs, fnx: nil, fxx: nil, ex: nil, px: nil, exat: nil, pxat: nil, keepttl: false)  ⇒ Integer 
  



  

    
Set the value of one or more hash fields, and optionally their expiration. Existing
values for the given fields are overwritten, and any previous TTL on those fields is
discarded unless :keepttl is given.

  





    

    
Examples:

      
redis.hsetex("hash", "f1", "v1", "f2", "v2") # => 1
redis.hsetex("hash", { "f1" => "v1", "f2" => "v2" }, ex: 60) # => 1

  


Parameters:


    
  
  • 
    key
    (String)
  
    • 
  
  • 
    attrs
    (Array<String> | Hash<String, String>)
—    
    array or hash of fields and values
    
  
    • 
  
  • 
    options
    (Hash)
—    
      

    • :fnx => true: Only set the fields if none of them already exist. Mutually
exclusive with :fxx.
      • 

    • :fxx => true: Only set the fields if all of them already exist. Mutually
exclusive with :fnx.
      • 

    • :ex => Integer: Set the specified expire time on the fields, in seconds.
      • 

    • :px => Integer: Set the specified expire time on the fields, in milliseconds.
      • 

    • :exat => Integer: Set the specified Unix time at which the fields will expire, in
seconds.
      • 

    • :pxat => Integer: Set the specified Unix time at which the fields will expire, in
milliseconds.
      • 

    • :keepttl => true: Retain the time to live already associated with the fields.
      • 

    
  
    • 



Returns:


    
  
  • 
    (Integer)
—    
    1 if all the fields were set, 0 if none were set (e.g. the
:fnx/:fxx condition was not met)
    
  
    • 



Raises:


    
  
  • 
    (ArgumentError)
  
    • 





  [ GitHub ]


  

  


# File 'lib/redis/commands/hashes.rb', line 240



def hsetex(key, *attrs, fnx: nil, fxx: nil, ex: nil, px: nil, exat: nil, pxat: nil, keepttl: false)
  raise ArgumentError, "fnx and fxx are mutually exclusive" if fnx && fxx
  if [ex, px, exat, pxat, keepttl].count { |option| option } > 1
    raise ArgumentError, "ex, px, exat, pxat, and keepttl are mutually exclusive"
  end

  attrs = attrs.first.flatten if attrs.size == 1 && attrs.first.is_a?(Hash)
  attrs.flatten!(1)

  args = [:hsetex, key]
  args << "FNX" if fnx
  args << "FXX" if fxx
  args << "EX" << Integer(ex) if ex
  args << "PX" << Integer(px) if px
  args << "EXAT" << Integer(exat) if exat
  args << "PXAT" << Integer(pxat) if pxat
  args << "KEEPTTL" if keepttl
  args.concat(['FIELDS', attrs.length / 2, *attrs])

  send_command(args)
end


  








  

    #hsetnx(key, field, value)  ⇒ Boolean 
  



  

    
Set the value of a hash field, only if the field does not exist.

  





  
Parameters:


    
  
  • 
    key
    (String)
  
    • 
  
  • 
    field
    (String)
  
    • 
  
  • 
    value
    (String)
  
    • 



Returns:


    
  
  • 
    (Boolean)
—    
    whether or not the field was added to the hash
    
  
    • 





  [ GitHub ]


  

  


# File 'lib/redis/commands/hashes.rb', line 36



def hsetnx(key, field, value)
  send_command([:hsetnx, key, field, value], &Boolify)
end


  








  

    #httl(key, *fields)  ⇒ Array<Integer> 
  



  

    
Returns the time to live in seconds for one or more fields.


See https://redis.io/docs/latest/commands/httl/#return-information for array reply.

  





    

    
Examples:

      
redis.hset("hash", "f1", "v1", "f2", "v2")
redis.hexpire("hash", 10, "f1") # => [1]
redis.httl("hash", "f1", "f2", "f3") # => [10, -1, -2]

  


Parameters:


    
  
  • 
    key
    (String)
  
    • 
  
  • 
    fields
    (Array<String>)
  
    • 



Returns:


    
  
  • 
    (Array<Integer>)
—    
    Feedback on the TTL of the fields.
    
  
    • 





  [ GitHub ]


  

  


# File 'lib/redis/commands/hashes.rb', line 406



def httl(key, *fields)
  fields.flatten!(1)
  send_command([:httl, key, 'FIELDS', fields.length, *fields])
end


  








  

    #hvals(key)  ⇒ Array<String> 
  



  

    
Get all the values in a hash.

  





  
Parameters:


    
  
  • 
    key
    (String)
  
    • 





  [ GitHub ]


  

  


# File 'lib/redis/commands/hashes.rb', line 303



def hvals(key)
  send_command([:hvals, key])
end


  








  

    #mapped_hmget(key, *fields)  ⇒ Hash 
  



  

    
Get the values of all the given hash fields.

  





    

    
Examples:

      
redis.mapped_hmget("hash", "f1", "f2")
  # => { "f1" => "v1", "f2" => "v2" }

  


Parameters:


    
  
  • 
    key
    (String)
  
    • 
  
  • 
    fields
    (Array<String>)
—    
    array of fields
    
  
    • 



Returns:


    
  
  • 
    (Hash)
—    
    a hash mapping the specified fields to their values
    
  
    • 


  
See Also:

  



  [ GitHub ]


  

  


# File 'lib/redis/commands/hashes.rb', line 106



def mapped_hmget(key, *fields)
  fields.flatten!(1)
  hmget(key, fields) do |reply|
    if reply.is_a?(Array)
      Hash[fields.zip(reply)]
    else
      reply
    end
  end
end


  








  

    #mapped_hmset(key, hash)  ⇒ String 
  



  

    
Set one or more hash values.

  





    

    
Examples:

      
redis.mapped_hmset("hash", { "f1" => "v1", "f2" => "v2" })
  # => "OK"

  


Parameters:


    
  
  • 
    key
    (String)
  
    • 
  
  • 
    hash
    (Hash)
—    
    a non-empty hash with fields mapping to values
    
  
    • 



Returns:


    
  
  • 
    (String)
—    
    "OK"
    
  
    • 


  
See Also:

  



  [ GitHub ]


  

  


# File 'lib/redis/commands/hashes.rb', line 66



def mapped_hmset(key, hash)
  hmset(key, hash.flatten)
end