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



154
155
156
# File 'lib/redis/commands/hashes.rb', line 154

def hdel(key, *fields)
  send_command([:hdel, key, *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



163
164
165
# File 'lib/redis/commands/hashes.rb', line 163

def hexists(key, field)
  send_command([:hexists, key, field], &Boolify)
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>)


207
208
209
# File 'lib/redis/commands/hashes.rb', line 207

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



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

def hincrby(key, field, increment)
  send_command([:hincrby, key, field, 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



183
184
185
# File 'lib/redis/commands/hashes.rb', line 183

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

#hkeys(key) ⇒ Array<String>

Get all the fields in a hash.

Parameters:

  • key (String)

Returns:

  • (Array<String>)


191
192
193
# File 'lib/redis/commands/hashes.rb', line 191

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
# File 'lib/redis/commands/hashes.rb', line 89

def hmget(key, *fields, &blk)
  send_command([:hmget, key] + 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

#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



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

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, Array<[String, String]>

Scan a hash

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

Returns:

  • (String, Array<[String, String]>)

    the next cursor and all found keys



222
223
224
225
226
# File 'lib/redis/commands/hashes.rb', line 222

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

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

Scan a hash

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

Returns:

  • (Enumerator)

    an enumerator for all found keys



239
240
241
242
243
244
245
246
247
248
# File 'lib/redis/commands/hashes.rb', line 239

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

#hvals(key) ⇒ Array<String>

Get all the values in a hash.

Parameters:

  • key (String)

Returns:

  • (Array<String>)


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

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:



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

def mapped_hmget(key, *fields)
  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.to_a.flatten)
end