Module: Redis::Commands::Hashes

Included in:
Redis::Commands
Defined in:
lib/redis/commands/hashes.rb

Instance Method Summary collapse

Instance Method Details

#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



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

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



166
167
168
 
# File 'lib/redis/commands/hashes.rb', line 166

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

#hexpire(key, ttl, *fields) ⇒ 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]

Parameters:

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

Returns:

  • (Array<Integer>) —

    Feedback on if the fields have been updated.



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

def hexpire(key, ttl, *fields)
  send_command([:hexpire, key, ttl, 'FIELDS', fields.length, *fields])
end

#hget(key, field) ⇒ String

Get the value of a hash field.

Parameters:

  • key (String)
  • field (String)

Returns:

  • (String) 


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

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)

Returns:

  • (Hash<String, String>) 


210
211
212
 
# File 'lib/redis/commands/hashes.rb', line 210

def hgetall(key)
  send_command([:hgetall, key], &Hashify)
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



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

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



417
418
419
 
# File 'lib/redis/commands/hashes.rb', line 417

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) 


363
364
365
366
367
368
 
# File 'lib/redis/commands/hashes.rb', line 363

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) 


390
391
392
393
394
395
 
# File 'lib/redis/commands/hashes.rb', line 390

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



176
177
178
 
# File 'lib/redis/commands/hashes.rb', line 176

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



186
187
188
 
# File 'lib/redis/commands/hashes.rb', line 186

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)

Returns:

  • (Array<String>) 


194
195
196
 
# File 'lib/redis/commands/hashes.rb', line 194

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



10
11
12
 
# 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:



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

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:



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

def hmset(key, *attrs)
  send_command([:hmset, key] + attrs)
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.



315
316
317
318
319
320
321
322
323
324
 
# File 'lib/redis/commands/hashes.rb', line 315

def hpexpire(key, ttl, *fields, nx: nil, xx: nil, gt: nil, lt: nil)
  args = [:hpexpire, key, ttl]
  args << "NX" if nx
  args << "XX" if xx
  args << "GT" if gt
  args << "LT" if lt
  args.concat(['FIELDS', fields.length, *fields])

  send_command(args)
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.



338
339
340
 
# File 'lib/redis/commands/hashes.rb', line 338

def hpttl(key, *fields)
  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


138
139
140
141
142
143
144
145
146
147
148
149
 
# File 'lib/redis/commands/hashes.rb', line 138

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


230
231
232
233
234
235
236
237
238
 
# File 'lib/redis/commands/hashes.rb', line 230

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



254
255
256
257
258
259
260
261
262
263
 
# File 'lib/redis/commands/hashes.rb', line 254

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



23
24
25
26
27
 
# 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)

  send_command([:hset, key, *attrs])
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



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

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.



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

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

#hvals(key) ⇒ Array<String>

Get all the values in a hash.

Parameters:

  • key (String)

Returns:

  • (Array<String>) 


202
203
204
 
# File 'lib/redis/commands/hashes.rb', line 202

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:



105
106
107
108
109
110
111
112
113
114
 
# File 'lib/redis/commands/hashes.rb', line 105

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:



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

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