commands.go

package main

// This file is auto-generated by ./update 

var Commands = map[string]Command{
    "hdel": {"hdel", "Delete one or more hash fields", "key field [field ...]", "hash", "1.3.10", `@complexity

O(N) where N is the number of fields to be removed.


Removes the specified fields from the hash stored at 'key'. Specified fields
that do not exist within this hash are ignored.
If 'key' does not exist, it is treated as an empty hash and this command returns
'0'.

@return

@integer-reply: the number of fields that were removed from the hash, not including specified but non existing fields.

@history

* '>= 2.4': Accepts multiple 'field' arguments. Redis versions older than 2.4 can only remove a field per call.

  To remove multiple fields from a hash in an atomic fashion in earlier
  versions, use a 'MULTI'/'EXEC' block.

@examples

    @cli
    HSET myhash field1 "foo"
    HDEL myhash field1
    HDEL myhash field2`},
    "srandmember": {"srandmember", "Get a random member from a set", "key", "set", "1.001", `@complexity

O(1)


Return a random element from the set value stored at 'key'.

This operation is similar to 'SPOP', however while 'SPOP' also removes the
randomly selected element from the set, 'SRANDMEMBER' will just return a random
element without altering the original set in any way.

@return

@bulk-reply: the randomly selected element, or 'nil' when 'key' does not exist.

@examples

    @cli
    SADD myset "one"
    SADD myset "two"
    SADD myset "three"
    SRANDMEMBER myset`},
    "smove": {"smove", "Move a member from one set to another", "source destination member", "set", "0.091", `@complexity

O(1)


Move 'member' from the set at 'source' to the set at 'destination'. This
operation is atomic. In every given moment the element will appear to be a
member of 'source' **or** 'destination' for other clients.

If the source set does not exist or does not contain the specified element, no
operation is performed and '0' is returned. Otherwise, the element is removed
from the source set and added to the destination set. When the specified
element already exists in the destination set, it is only removed from the
source set.

An error is returned if 'source' or 'destination' does not hold a set value.

@return

@integer-reply, specifically:

* '1' if the element is moved.
* '0' if the element is not a member of 'source' and no operation was performed.

@examples

    @cli
    SADD myset "one"
    SADD myset "two"
    SADD myotherset "three"
    SMOVE myset myotherset "two"
    SMEMBERS myset
    SMEMBERS myotherset`},
    "flushdb": {"flushdb", "Remove all keys from the current database", "-", "server", "0.07", `Delete all the keys of the currently selected DB. This command never fails.

@return

@status-reply`},
    "srem": {"srem", "Remove one or more members from a set", "key member [member ...]", "set", "0.07", `@complexity

O(N) where N is the number of members to be removed.


Remove the specified members from the set stored at 'key'. Specified members
that are not a member of this set are ignored.  If 'key' does not exist, it is
treated as an empty set and this command returns '0'.

An error is returned when the value stored at 'key' is not a set.

@return

@integer-reply: the number of members that were removed from the set, not including non existing members.

@history

* '>= 2.4': Accepts multiple 'member' arguments. Redis versions older than 2.4 can only remove a set member per call.

@examples

    @cli
    SADD myset "one"
    SADD myset "two"
    SADD myset "three"
    SREM myset "one"
    SREM myset "four"
    SMEMBERS myset`},
    "bgsave": {"bgsave", "Asynchronously save the dataset to disk", "-", "server", "0.07", `Save the DB in background. The OK code is immediately returned.
Redis forks, the parent continues to server the clients, the child
saves the DB on disk then exit. A client my be able to check if the
operation succeeded using the 'LASTSAVE' command.

@return

@status-reply`},
    "brpoplpush": {"brpoplpush", "Pop a value from a list, push it to another list and return it; or block until one is available", "source destination timeout", "list", "2.1.7", `@complexity

O(1).

'BRPOPLPUSH' is the blocking variant of 'RPOPLPUSH'. When 'source'
contains elements, this command behaves exactly like 'RPOPLPUSH'.  When
'source' is empty, Redis will block the connection until another client
pushes to it or until 'timeout' is reached. A 'timeout' of zero can be
used to block indefinitely.

See 'RPOPLPUSH' for more information.

@return

@bulk-reply: the element being popped from 'source' and pushed to
'destination'. If 'timeout' is reached, a @nil-reply is returned.`},
    "lindex": {"lindex", "Get an element from a list by its index", "key index", "list", "0.07", `@complexity

O(N) where N is the number of elements to traverse to get to the element
at 'index'. This makes asking for the first or the last
element of the list O(1).

Returns the element at index 'index' in the list stored at 'key'.
The index is zero-based, so '0' means the first element, '1' the second
element and so on. Negative indices can be used to designate elements
starting at the tail of the list. Here, '-1' means the last element, '-2' means
the penultimate and so forth.

When the value at 'key' is not a list, an error is returned.

@return

@bulk-reply: the requested element, or 'nil' when 'index' is out of range.

@examples

    @cli
    LPUSH mylist "World"
    LPUSH mylist "Hello"
    LINDEX mylist 0
    LINDEX mylist -1
    LINDEX mylist 3`},
    "hexists": {"hexists", "Determine if a hash field exists", "key field", "hash", "1.3.10", `@complexity

O(1)


Returns if 'field' is an existing field in the hash stored at 'key'.

@return

@integer-reply, specifically:

* '1' if the hash contains 'field'.
* '0' if the hash does not contain 'field', or 'key' does not exist.

@examples

    @cli
    HSET myhash field1 "foo"
    HEXISTS myhash field1
    HEXISTS myhash field2`},
    "zrange": {"zrange", "Return a range of members in a sorted set, by index", "key start stop [WITHSCORES]", "sorted_set", "1.1", `@complexity

O(log(N)+M) with N being the number of elements in the sorted set and M the
number of elements returned.

Returns the specified range of elements in the sorted set stored at 'key'. The
elements are considered to be ordered from the lowest to the highest score.
Lexicographical order is used for elements with equal score.

See 'ZREVRANGE' when you need the elements ordered from highest to lowest
score (and descending lexicographical order for elements with equal score).

Both 'start' and 'stop' are zero-based indexes, where '0' is the first element,
'1' is the next element and so on. They can also be negative numbers indicating
offsets from the end of the sorted set, with '-1' being the last element of the
sorted set, '-2' the penultimate element and so on.

Out of range indexes will not produce an error. If 'start' is larger than the
largest index in the sorted set, or 'start > stop', an empty list is returned.
If 'stop' is larger than the end of the sorted set Redis will treat it like it
is the last element of the sorted set.

It is possible to pass the 'WITHSCORES' option in order to return the scores of
the elements together with the elements.  The returned list will contain
'value1,score1,...,valueN,scoreN' instead of 'value1,...,valueN'.  Client
libraries are free to return a more appropriate data type (suggestion: an array
with (value, score) arrays/tuples).

@return

@multi-bulk-reply: list of elements in the specified range (optionally with
their scores).

@examples

    @cli
    ZADD myzset 1 "one"
    ZADD myzset 2 "two"
    ZADD myzset 3 "three"
    ZRANGE myzset 0 -1
    ZRANGE myzset 2 3
    ZRANGE myzset -2 -1`},
    "setbit": {"setbit", "Sets or clears the bit at offset in the string value stored at key", "key offset value", "string", "2.1.8", `@complexity

O(1)


Sets or clears the bit at _offset_ in the string value stored at _key_.

The bit is either set or cleared depending on _value_, which can be either 0 or
1. When _key_ does not exist, a new string value is created. The string is
grown to make sure it can hold a bit at _offset_. The _offset_ argument is
required to be greater than or equal to 0, and smaller than 2^32 (this
limits bitmaps to 512MB). When the string at _key_ is grown, added
bits are set to 0.

**Warning**: When setting the last possible bit (_offset_ equal to 2^32 -1) and
the string value stored at _key_ does not yet hold a string value, or holds a
small string value, Redis needs to allocate all intermediate memory which can
block the server for some time.  On a 2010 MacBook Pro, setting bit number
2^32 -1 (512MB allocation) takes ~300ms, setting bit number 2^30 -1 (128MB
allocation) takes ~80ms, setting bit number 2^28 -1 (32MB allocation) takes
~30ms and setting bit number 2^26 -1 (8MB allocation) takes ~8ms.  Note that
once this first allocation is done, subsequent calls to 'SETBIT' for the same
_key_ will not have the allocation overhead.

@return

@integer-reply: the original bit value stored at _offset_.

@examples

    @cli
    SETBIT mykey 7 1
    SETBIT mykey 7 0
    GET mykey`},
    "getbit": {"getbit", "Returns the bit value at offset in the string value stored at key", "key offset", "string", "2.1.8", `@complexity

O(1)


Returns the bit value at _offset_ in the string value stored at _key_.

When _offset_ is beyond the string length, the string is assumed to be a
contiguous space with 0 bits. When _key_ does not exist it is assumed to be an
empty string, so _offset_ is always out of range and the value is also assumed
to be a contiguous space with 0 bits.

@return

@integer-reply: the bit value stored at _offset_.

@examples

    @cli
    SETBIT mykey 7 1
    GETBIT mykey 0
    GETBIT mykey 7
    GETBIT mykey 100`},
    "watch": {"watch", "Watch the given keys to determine execution of the MULTI/EXEC block", "key [key ...]", "transactions", "2.1.0", `@complexity

O(1) for every key.

Marks the given keys to be watched for conditional execution of a [transaction](/topics/transactions).

@return

@status-reply: always 'OK'.`},
    "keys": {"keys", "Find all keys matching the given pattern", "pattern", "generic", "0.07", `@complexity

O(N) with N being the number of keys in the database, under the assumption that
the key names in the database and the given pattern have limited length.

Returns all keys matching 'pattern'.

While the time complexity for this operation is O(N), the constant
times are fairly low. For example, Redis running on an entry level laptop can
scan a 1 million key database in 40 milliseconds.

**Warning**: consider 'KEYS' as a command that should only be used in
production environments with extreme care.  It may ruin performance when it is
executed against large databases. This command is intended for debugging and
special operations, such as changing your keyspace layout. Don't use 'KEYS'
in your regular application code.  If you're looking for a way to find keys in
a subset of your keyspace, consider using [sets](/topics/data-types#sets).

Supported glob-style patterns:

* 'h?llo' matches 'hello', 'hallo' and 'hxllo'
* 'h*llo' matches 'hllo' and 'heeeello'
* 'h[ae]llo' matches 'hello' and 'hallo,' but not 'hillo'

Use '\' to escape special characters if you want to match them verbatim.

@return

@multi-bulk-reply: list of keys matching 'pattern'.

@examples

    @cli
    MSET one 1 two 2 three 3 four 4
    KEYS *o*
    KEYS t??
    KEYS *`},
    "randomkey": {"randomkey", "Return a random key from the keyspace", "-", "generic", "0.07", `@complexity

O(1)


Return a random key from the currently selected database.

@return

@bulk-reply: the random key, or 'nil' when the database is empty.`},
    "lpop": {"lpop", "Remove and get the first element in a list", "key", "list", "0.07", `@complexity

O(1)


Removes and returns the first element of the list stored at 'key'.

@return

@bulk-reply: the value of the first element, or 'nil' when 'key' does not exist.

@examples

    @cli
    RPUSH mylist "one"
    RPUSH mylist "two"
    RPUSH mylist "three"
    LPOP mylist
    LRANGE mylist 0 -1`},
    "sadd": {"sadd", "Add one or more members to a set", "key member [member ...]", "set", "0.07", `@complexity

O(N) where N is the number of members to be added.


Add the specified members to the set stored at 'key'. Specified members that
are already a member of this set are ignored.  If 'key' does not exist, a new
set is created before adding the specified members.

An error is returned when the value stored at 'key' is not a set.

@return

@integer-reply: the number of elements that were added to the set, not including all the elements already present into the set.

@history

* '>= 2.4': Accepts multiple 'member' arguments. Redis versions before 2.4 are only able to add a single member per call.

@examples

    @cli
    SADD myset "Hello"
    SADD myset "World"
    SADD myset "World"
    SMEMBERS myset`},
    "dbsize": {"dbsize", "Return the number of keys in the selected database", "-", "server", "0.07", `Return the number of keys in the currently selected database.

@return

@integer-reply`},
    "rpushx": {"rpushx", "Append a value to a list, only if the list exists", "key value", "list", "2.1.1", `@complexity

O(1)


Inserts 'value' at the tail of the list stored at 'key', only if 'key'
already exists and holds a list. In contrary to 'RPUSH', no operation will
be performed when 'key' does not yet exist.

@return

@integer-reply: the length of the list after the push operation.

@examples

    @cli
    RPUSH mylist "Hello"
    RPUSHX mylist "World"
    RPUSHX myotherlist "World"
    LRANGE mylist 0 -1
    LRANGE myotherlist 0 -1`},
    "zremrangebyscore": {"zremrangebyscore", "Remove all members in a sorted set within the given scores", "key min max", "sorted_set", "1.1", `@complexity

O(log(N)+M) with N being the number of elements in the sorted set and M the
number of elements removed by the operation.

Removes all elements in the sorted set stored at 'key' with a score between
'min' and 'max' (inclusive).

Since version 2.1.6, 'min' and 'max' can be exclusive, following the syntax of
'ZRANGEBYSCORE'.

@return

@integer-reply: the number of elements removed.

@examples

    @cli
    ZADD myzset 1 "one"
    ZADD myzset 2 "two"
    ZADD myzset 3 "three"
    ZREMRANGEBYSCORE myzset -inf (2
    ZRANGE myzset 0 -1 WITHSCORES`},
    "bgrewriteaof": {"bgrewriteaof", "Asynchronously rewrite the append-only file", "-", "server", "1.07", `Rewrites the [append-only file](/topics/persistence#append-only-file) to reflect the current dataset in memory.

If 'BGREWRITEAOF' fails, no data gets lost as the old AOF will be untouched.

@return

@status-reply: always 'OK'.`},
    "unwatch": {"unwatch", "Forget about all watched keys", "-", "transactions", "2.1.0", `@complexity

O(1).

Flushes all the previously watched keys for a [transaction](/topics/transactions).

If you call 'EXEC' or 'DISCARD', there's no need to manually call 'UNWATCH'.

@return

@status-reply: always 'OK'.`},
    "lpush": {"lpush", "Prepend one or multiple values to a list", "key value [value ...]", "list", "0.07", `@complexity

O(1)


Insert all the specified values at the head of the list stored at 'key'.
If 'key' does not exist, it is created as empty list before performing
the push operations.
When 'key' holds a value that is not a list, an error is returned.

It is possible to push multiple elements using a single command call just specifying multiple arguments at the end of the command. Elements are inserted one after the other to the head of the list, from the leftmost element to the rightmost element. So for instance the command 'LPUSH mylist a b c' will result into a list containing 'c' as first element, 'b' as second element and 'a' as third element.

@return

@integer-reply: the length of the list after the push operations.

@history

* '>= 2.4': Accepts multiple 'value' arguments. In Redis versions older than 2.4 it was possible to push a single value per command.

@examples

    @cli
    LPUSH mylist "world"
    LPUSH mylist "hello"
    LRANGE mylist 0 -1`},
    "append": {"append", "Append a value to a key", "key value", "string", "1.3.3", `@complexity

O(1). The amortized time complexity is O(1) assuming the appended value is
small and the already present value is of any size, since the dynamic string
library used by Redis will double the free space available on every
reallocation.

If 'key' already exists and is a string, this command appends the 'value' at
the end of the string.  If 'key' does not exist it is created and set as an
empty string, so 'APPEND' will be similar to 'SET' in this special case.

@return

@integer-reply: the length of the string after the append operation.

@examples

    @cli
    EXISTS mykey
    APPEND mykey "Hello"
    APPEND mykey " World"
    GET mykey`},
    "zincrby": {"zincrby", "Increment the score of a member in a sorted set", "key increment member", "sorted_set", "1.1", `@complexity

O(log(N)) where N is the number of elements in the sorted set.

Increments the score of 'member' in the sorted set stored at 'key' by
'increment'.  If 'member' does not exist in the sorted set, it is added with
'increment' as its score (as if its previous score was '0.0').  If 'key' does
not exist, a new sorted set with the specified 'member' as its sole member is
created.

An error is returned when 'key' exists but does not hold a sorted set.

The 'score' value should be the string representation of a numeric value, and
accepts double precision floating point numbers. It is possible to provide a
negative value to decrement the score.

@return

@bulk-reply: the new score of 'member' (a double precision floating point
number), represented as string.

@examples

    @cli
    ZADD myzset 1 "one"
    ZADD myzset 2 "two"
    ZINCRBY myzset 2 "one"
    ZRANGE myzset 0 -1 WITHSCORES`},
    "zrevrank": {"zrevrank", "Determine the index of a member in a sorted set, with scores ordered from high to low", "key member", "sorted_set", "1.3.4", `@complexity

O(log(N))


Returns the rank of 'member' in the sorted set stored at 'key', with the scores
ordered from high to low. The rank (or index) is 0-based, which means that the
member with the highest score has rank '0'.

Use 'ZRANK' to get the rank of an element with the scores ordered from low to
high.

@return

* If 'member' exists in the sorted set, @integer-reply: the rank of 'member'.
* If 'member' does not exist in the sorted set or 'key' does not exist,
@bulk-reply: 'nil'.

@examples

    @cli
    ZADD myzset 1 "one"
    ZADD myzset 2 "two"
    ZADD myzset 3 "three"
    ZREVRANK myzset "one"
    ZREVRANK myzset "four"`},
    "scard": {"scard", "Get the number of members in a set", "key", "set", "0.07", `@complexity

O(1)


Returns the set cardinality (number of elements) of the set stored at 'key'.

@return

@integer-reply: the cardinality (number of elements) of the set, or '0' if
'key' does not exist.

@examples

    @cli
    SADD myset "Hello"
    SADD myset "World"
    SCARD myset`},
    "zrevrangebyscore": {"zrevrangebyscore", "Return a range of members in a sorted set, by score, with scores ordered from high to low", "key max min [WITHSCORES] [LIMIT offset count]", "sorted_set", "2.1.6", `@complexity

O(log(N)+M) with N being the number of elements in the sorted set and M the
number of elements being returned. If M is constant (e.g. always asking for the
first 10 elements with 'LIMIT'), you can consider it O(log(N)).

Returns all the elements in the sorted set at 'key' with a score between 'max'
and 'min' (including elements with score equal to 'max' or 'min'). In contrary
to the default ordering of sorted sets, for this command the elements are
considered to be ordered from high to low scores.

The elements having the same score are returned in reverse lexicographical order.

Apart from the reversed ordering, 'ZREVRANGEBYSCORE' is similar to
'ZRANGEBYSCORE'.

@return

@multi-bulk-reply: list of elements in the specified score range (optionally with
their scores).

@examples

    @cli
    ZADD myzset 1 "one"
    ZADD myzset 2 "two"
    ZADD myzset 3 "three"
    ZREVRANGEBYSCORE myzset +inf -inf
    ZREVRANGEBYSCORE myzset 2 1
    ZREVRANGEBYSCORE myzset 2 (1
    ZREVRANGEBYSCORE myzset (2 (1`},
    "ltrim": {"ltrim", "Trim a list to the specified range", "key start stop", "list", "0.07", `@complexity

O(N) where N is the number of elements to be removed by the operation.

Trim an existing list so that it will contain only the specified range of
elements specified. Both 'start' and 'stop' are zero-based indexes, where '0'
is the first element of the list (the head), '1' the next element and so on.

For example: 'LTRIM foobar 0 2' will modify the list stored at 'foobar' so that
only the first three elements of the list will remain.

'start' and 'end' can also be negative numbers indicating offsets from the end
of the list, where '-1' is the last element of the list, '-2' the penultimate
element and so on.

Out of range indexes will not produce an error: if 'start' is larger than the
end of the list, or 'start > end', the result will be an empty list (which
causes 'key' to be removed).  If 'end' is larger than the end of the list,
Redis will treat it like the last element of the list.

A common use of 'LTRIM' is together with 'LPUSH'/'RPUSH'. For example:

    LPUSH mylist someelement
    LTRIM mylist 0 99

This pair of commands will push a new element on the list, while making sure
that the list will not grow larger than 100 elements. This is very useful when
using Redis to store logs for example. It is important to note that when used
in this way 'LTRIM' is an O(1) operation because in the average case just one
element is removed from the tail of the list.

@return

@status-reply

@examples

    @cli
    RPUSH mylist "one"
    RPUSH mylist "two"
    RPUSH mylist "three"
    LTRIM mylist 1 -1
    LRANGE mylist 0 -1`},
    "hkeys": {"hkeys", "Get all the fields in a hash", "key", "hash", "1.3.10", `@complexity

O(N) where N is the size of the hash.

Returns all field names in the hash stored at 'key'.

@return

@multi-bulk-reply: list of fields in the hash, or an empty list when 'key' does
not exist.

@examples

    @cli
    HSET myhash field1 "Hello"
    HSET myhash field2 "World"
    HKEYS myhash`},
    "zremrangebyrank": {"zremrangebyrank", "Remove all members in a sorted set within the given indexes", "key start stop", "sorted_set", "1.3.4", `@complexity

O(log(N)+M) with N being the number of elements in the sorted set and M the
number of elements removed by the operation.

Removes all elements in the sorted set stored at 'key' with rank between
'start' and 'stop'.  Both 'start' and 'stop' are '0'-based indexes with '0'
being the element with the lowest score. These indexes can be negative numbers,
where they indicate offsets starting at the element with the highest score. For
example: '-1' is the element with the highest score, '-2' the element with the
second highest score and so forth.

@return

@integer-reply: the number of elements removed.

@examples

    @cli
    ZADD myzset 1 "one"
    ZADD myzset 2 "two"
    ZADD myzset 3 "three"
    ZREMRANGEBYRANK myzset 0 1
    ZRANGE myzset 0 -1 WITHSCORES`},
    "config resetstat": {"config resetstat", "Reset the stats returned by INFO", "-", "server", "2.0", `@complexity

O(1).

Resets the statistics reported by Redis using the 'INFO' command.

These are the counters that are reset:

* Keyspace hits
* Keyspace misses
* Number of commands processed
* Number of connections received
* Number of expired keys

@return

@status-reply: always 'OK'.`},
    "lset": {"lset", "Set the value of an element in a list by its index", "key index value", "list", "0.07", `@complexity

O(N) where N is the length of the list. Setting either the first or the last
element of the list is O(1).

Sets the list element at 'index' to 'value'. For more information on the
'index' argument, see 'LINDEX'.

An error is returned for out of range indexes.

@return

@status-reply

@examples

    @cli
    RPUSH mylist "one"
    RPUSH mylist "two"
    RPUSH mylist "three"
    LSET mylist 0 "four"
    LSET mylist -2 "five"
    LRANGE mylist 0 -1`},
    "move": {"move", "Move a key to another database", "key db", "generic", "0.07", `@complexity

O(1)


Move 'key' from the currently selected database (see 'SELECT') to the specified
destination database. When 'key' already exists in the destination database, or
it does not exist in the source database, it does nothing. It is possible to
use 'MOVE' as a locking primitive because of this.

@return

@integer-reply, specifically:

* '1' if 'key' was moved.
* '0' if 'key' was not moved.`},
    "getset": {"getset", "Set the string value of a key and return its old value", "key value", "string", "0.091", `@complexity

O(1)


Atomically sets 'key' to 'value' and returns the old value stored at 'key'.
Returns an error when 'key' exists but does not hold a string value.

## Design pattern

'GETSET' can be used together with 'INCR' for counting with atomic reset.  For
example: a process may call 'INCR' against the key 'mycounter' every time some
event occurs, but from time to time we need to get the value of the counter and
reset it to zero atomically.  This can be done using 'GETSET mycounter "0"':

    @cli
    INCR mycounter
    GETSET mycounter "0"
    GET mycounter

@return

@bulk-reply: the old value stored at 'key', or 'nil' when 'key' did not exist.

@examples

    @cli
    SET mykey "Hello"
    GETSET mykey "World"
    GET mykey`},
    "set": {"set", "Set the string value of a key", "key value", "string", "0.07", `@complexity

O(1)


Set 'key' to hold the string 'value'. If 'key' already holds a value, it is
overwritten, regardless of its type.

@return

@status-reply: always 'OK' since 'SET' can't fail.

@examples

    @cli
    SET mykey "Hello"
    GET mykey`},
    "del": {"del", "Delete a key", "key [key ...]", "generic", "0.07", `@complexity

O(N) where N is the number of keys that will be removed. When a key to remove
holds a value other than a string, the individual complexity for this key is
O(M) where M is the number of elements in the list, set, sorted set or hash.
Removing a single key that holds a string value is O(1).

Removes the specified keys.  A key is ignored if it does not exist.

@return

@integer-reply: The number of keys that were removed.

@examples

    @cli
    SET key1 "Hello"
    SET key2 "World"
    DEL key1 key2 key3`},
    "strlen": {"strlen", "Get the length of the value stored in a key", "key", "string", "2.1.2", `@complexity

O(1)


Returns the length of the string value stored at 'key'.
An error is returned when 'key' holds a non-string value.

@return

@integer-reply: the length of the string at 'key', or '0' when 'key' does not exist.

@examples

    @cli
    SET mykey "Hello world"
    STRLEN mykey
    STRLEN nonexisting`},
    "zrem": {"zrem", "Remove one or more members from a sorted set", "key member [member ...]", "sorted_set", "1.1", `@complexity

O(M log(N)) with N being the number of elements in the sorted set and M the number of elements to be removed.

Removes the specified members from the sorted set stored at 'key'. Non existing members are ignored.

An error is returned when 'key' exists and does not hold a sorted set.

@return

@integer-reply, specifically:

* The number of members removed from the sorted set, not including non existing members.

@history

* '>= 2.4': Accepts multiple elements. In Redis versions older than 2.4 it was possible to remove a single member per call.

@examples

    @cli
    ZADD myzset 1 "one"
    ZADD myzset 2 "two"
    ZADD myzset 3 "three"
    ZREM myzset "two"
    ZRANGE myzset 0 -1 WITHSCORES`},
    "sunionstore": {"sunionstore", "Add multiple sets and store the resulting set in a key", "destination key [key ...]", "set", "0.091", `@complexity

O(N) where N is the total number of elements in all given sets.

This command is equal to 'SUNION', but instead of returning the resulting set,
it is stored in 'destination'.

If 'destination' already exists, it is overwritten.

@return

@integer-reply: the number of elements in the resulting set.`},
    "persist": {"persist", "Remove the expiration from a key", "key", "generic", "2.1.2", `@complexity

O(1)


Remove the existing timeout on 'key'.

@return

@integer-reply, specifically:

* '1' if the timeout was removed.
* '0' if 'key' does not exist or does not have an associated timeout.

@examples

    @cli
    SET mykey "Hello"
    EXPIRE mykey 10
    TTL mykey
    PERSIST mykey
    TTL mykey`},
    "config get": {"config get", "Get the value of a configuration parameter", "parameter", "server", "2.0", `@complexity

Not applicable.

@description

The 'CONFIG GET' command is used to read the configuration parameters of a running
Redis server. Not all the configuration parameters are supported.
The symmetric command used to alter the configuration at run time is
'CONFIG SET'.

'CONFIG GET' takes a single argument, that is glob style pattern. All the
configuration parameters matching this parameter are reported as a
list of key-value pairs. Example:

    redis> config get *max-*-entries*
    1) "hash-max-zipmap-entries"
    2) "512"
    3) "list-max-ziplist-entries"
    4) "512"
    5) "set-max-intset-entries"
    6) "512"

You can obtain a list of all the supported configuration parameters typing
'CONFIG GET *' in an open 'redis-cli' prompt.

All the supported parameters have the same meaning of the equivalent
configuration parameter used in the [redis.conf](http://github.com/antirez/redis/raw/2.2/redis.conf) file, with the following important differences:

* Where bytes or other quantities are specified, it is not possible to use the redis.conf abbreviated form (10k 2gb ... and so forth), everything should be specified as a well formed 64 bit integer, in the base unit of the configuration directive.
* The save parameter is a single string of space separated integers. Every pair of integers represent a seconds/modifications threshold.

For instance what in redis.conf looks like:

    save 900 1
    save 300 10

that means, save after 900 seconds if there is at least 1 change to the
dataset, and after 300 seconds if there are at least 10 changes to the
datasets, will be reported by 'CONFIG GET' as "900 1 300 10".

@return

The return type of the command is a @bulk-reply.`},
    "sinter": {"sinter", "Intersect multiple sets", "key [key ...]", "set", "0.07", `@complexity

O(N\*M) worst case where N is the cardinality of the smallest set and M is the
number of sets.

Returns the members of the set resulting from the intersection of all the given
sets.

For example:

    key1 = {a,b,c,d}
    key2 = {c}
    key3 = {a,c,e}
    SINTER key1 key2 key3 = {c}

Keys that do not exist are considered to be empty sets. With one of the keys
being an empty set, the resulting set is also empty (since set intersection
with an empty set always results in an empty set).

@return

@multi-bulk-reply: list with members of the resulting set.

@examples

    @cli
    SADD key1 "a"
    SADD key1 "b"
    SADD key1 "c"
    SADD key2 "c"
    SADD key2 "d"
    SADD key2 "e"
    SINTER key1 key2`},
    "renamenx": {"renamenx", "Rename a key, only if the new key does not exist", "key newkey", "generic", "0.07", `@complexity

O(1)


Renames 'key' to 'newkey' if 'newkey' does not yet exist.
It returns an error under the same conditions as 'RENAME'.

@return

@integer-reply, specifically:

* '1' if 'key' was renamed to 'newkey'.
* '0' if 'newkey' already exists.

@examples

    @cli
    SET mykey "Hello"
    SET myotherkey "World"
    RENAMENX mykey myotherkey
    GET myotherkey`},
    "sismember": {"sismember", "Determine if a given value is a member of a set", "key member", "set", "0.07", `@complexity

O(1)


Returns if 'member' is a member of the set stored at 'key'.

@return

@integer-reply, specifically:

* '1' if the element is a member of the set.
* '0' if the element is not a member of the set, or if 'key' does not exist.

@examples

    @cli
    SADD myset "one"
    SISMEMBER myset "one"
    SISMEMBER myset "two"`},
    "rename": {"rename", "Rename a key", "key newkey", "generic", "0.07", `@complexity

O(1)


Renames 'key' to 'newkey'. It returns an error when the source and destination
names are the same, or when 'key' does not exist. If 'newkey' already exists it
is overwritten.

@return

@status-reply

@examples

    @cli
    SET mykey "Hello"
    RENAME mykey myotherkey
    GET myotherkey`},
    "hgetall": {"hgetall", "Get all the fields and values in a hash", "key", "hash", "1.3.10", `@complexity

O(N) where N is the size of the hash.

Returns all fields and values of the hash stored at 'key'. In the returned
value, every field name is followed by its value, so the length
of the reply is twice the size of the hash.

@return

@multi-bulk-reply: list of fields and their values stored in the hash, or an
empty list when 'key' does not exist.

@examples

    @cli
    HSET myhash field1 "Hello"
    HSET myhash field2 "World"
    HGETALL myhash`},
    "zcount": {"zcount", "Count the members in a sorted set with scores within the given values", "key min max", "sorted_set", "1.3.3", `@complexity

O(log(N)+M) with N being the number of elements in the
sorted set and M being the number of elements between 'min' and 'max'.

Returns the number of elements in the sorted set at 'key' with
a score between 'min' and 'max'.

The 'min' and 'max' arguments have the same semantic as described
for 'ZRANGEBYSCORE'.

@return

@integer-reply: the number of elements in the specified score range.

@examples

    @cli
    ZADD myzset 1 "one"
    ZADD myzset 2 "two"
    ZADD myzset 3 "three"
    ZCOUNT myzset -inf +inf
    ZCOUNT myzset (1 3`},
    "mget": {"mget", "Get the values of all the given keys", "key [key ...]", "string", "0.07", `@complexity

O(N) where N is the number of keys to retrieve


Returns the values of all specified keys. For every key that does not hold a string value
or does not exist, the special value 'nil' is returned.
Because of this, the operation never fails.

@return

@multi-bulk-reply: list of values at the specified keys.

@examples

    @cli
    SET key1 "Hello"
    SET key2 "World"
    MGET key1 key2 nonexisting`},
    "subscribe": {"subscribe", "Listen for messages published to the given channels", "channel [channel ...]", "pubsub", "1.3.8", `@complexity

O(N) where N is the number of channels to subscribe to.

Subscribes the client to the specified channels.

Once the client enters the subscribed state it is not supposed to issue
any other commands, except for additional 'SUBSCRIBE', 'PSUBSCRIBE',
'UNSUBSCRIBE' and 'PUNSUBSCRIBE' commands.`},
    "publish": {"publish", "Post a message to a channel", "channel message", "pubsub", "1.3.8", `@complexity

O(N+M) where N is the number of clients subscribed to the receiving
channel and M is the total number of subscribed patterns (by any
client).

Posts a message to the given channel.

@return

@integer-reply: the number of clients that received the message.`},
    "rpoplpush": {"rpoplpush", "Remove the last element in a list, append it to another list and return it", "source destination", "list", "1.1", `@complexity

O(1)


Atomically returns and removes the last element (tail) of the list stored at
'source', and pushes the element at the first element (head) of the list stored
at 'destination'.

For example: consider 'source' holding the list 'a,b,c', and 'destination'
holding the list 'x,y,z'. Executing 'RPOPLPUSH' results in 'source' holding
'a,b' and 'destination' holding 'c,x,y,z'.

If 'source' does not exist, the value 'nil' is returned and no operation is
performed. If 'source' and 'destination' are the same, the operation is
equivalent to removing the last element from the list and pushing it as first
element of the list, so it can be considered as a list rotation command.

@return

@bulk-reply: the element being popped and pushed.

@examples

    @cli
    RPUSH mylist "one"
    RPUSH mylist "two"
    RPUSH mylist "three"
    RPOPLPUSH mylist myotherlist
    LRANGE mylist 0 -1
    LRANGE myotherlist 0 -1

## Design pattern: safe queues

Redis lists are often used as queues in order to exchange messages between
different programs. A program can add a message performing an 'LPUSH' operation
against a Redis list (we call this program the _Producer_), while another program
(that we call _Consumer_) can process the messages performing an 'RPOP' command
in order to start reading the messages starting at the oldest.

Unfortunately, if a _Consumer_ crashes just after an 'RPOP' operation, the message
is lost. 'RPOPLPUSH' solves this problem since the returned message is
added to another backup list. The _Consumer_ can later remove the message
from the backup list using the 'LREM' command when the message was correctly
processed.

Another process (that we call _Helper_), can monitor the backup list to check for
timed out entries to re-push against the main queue.

## Design pattern: server-side O(N) list traversal

Using 'RPOPLPUSH' with the same source and destination key, a process can
visit all the elements of an N-elements list in O(N) without transferring
the full list from the server to the client in a single 'LRANGE' operation.
Note that a process can traverse the list even while other processes
are actively pushing to the list, and still no element will be skipped.`},
    "brpop": {"brpop", "Remove and get the last element in a list, or block until one is available", "key [key ...] timeout", "list", "1.3.1", `@complexity

O(1)


'BRPOP' is a blocking list pop primitive.  It is the blocking version of 'RPOP'
because it blocks the connection when there are no elements to pop from any of
the given lists. An element is popped from the tail of the first list that is
non-empty, with the given keys being checked in the order that they are given.

See 'BLPOP' for the exact semantics. 'BRPOP' is identical to 'BLPOP', apart
from popping from the tail of a list instead of the head of a list.

@return

@multi-bulk-reply: specifically:

* A 'nil' multi-bulk when no element could be popped and the timeout expired.
* A two-element multi-bulk with the first element being the name of the key where an element
  was popped and the second element being the value of the popped element.`},
    "expireat": {"expireat", "Set the expiration for a key as a UNIX timestamp", "key timestamp", "generic", "1.1", `@complexity

O(1)


Set a timeout on 'key'. After the timeout has expired, the key will
automatically be deleted. A key with an associated timeout is said to be
_volatile_ in Redis terminology.

'EXPIREAT' has the same effect and semantic as 'EXPIRE', but instead of
specifying the number of seconds representing the TTL (time to live), it takes
an absolute [UNIX timestamp][2] (seconds since January 1, 1970).

As in the case of 'EXPIRE' command, if 'key' is updated before the timeout has
expired, then the timeout is removed as if the 'PERSIST' command was invoked on
'key'.

[2]: http://en.wikipedia.org/wiki/Unix_time

## Background

'EXPIREAT' was introduced in order to convert relative timeouts to absolute
timeouts for the AOF persistence mode. Of course, it can be used directly to
specify that a given key should expire at a given time in the future.

@return

@integer-reply, specifically:

* '1' if the timeout was set.
* '0' if 'key' does not exist or the timeout could not be set (see: 'EXPIRE').

@examples

    @cli
    SET mykey "Hello"
    EXISTS mykey
    EXPIREAT mykey 1293840000
    EXISTS mykey`},
    "sort": {"sort", "Sort the elements in a list, set or sorted set", "key [BY pattern] [LIMIT offset count] [GET pattern [GET pattern ...]] [ASC|DESC] [ALPHA] [STORE destination]", "generic", "0.07", `@complexity

O(N+M\*log(M)) where N is the number of elements in the list or set to sort, and M the number of returned elements. When the elements are not sorted, complexity is currently O(N) as there is a copy step that will be avoided in next releases.

Returns or stores the elements contained in the
[list](/topics/data-types#lists), [set](/topics/data-types#set) or [sorted
set](/topics/data-types#sorted-sets) at 'key'.  By default, sorting is numeric
and elements are compared by their value interpreted as double precision
floating point number.  This is 'SORT' in its simplest form:

    SORT mylist

Assuming 'mylist' is a list of numbers, this command will return the same list
with the elements sorted from small to large. In order to sort the numbers from
large to small, use the '!DESC' modifier:

    SORT mylist DESC

When 'mylist' contains string values and you want to sort them lexicographically,
use the '!ALPHA' modifier:

    SORT mylist ALPHA

Redis is UTF-8 aware, assuming you correctly set the '!LC_COLLATE' environment
variable.

The number of returned elements can be limited using the '!LIMIT' modifier.
This modifier takes the 'offset' argument, specifying the number of elements to
skip and the 'count' argument, specifying the number of elements to return from
starting at 'offset'.  The following example will return 10 elements of the
sorted version of 'mylist', starting at element 0 ('offset' is zero-based):

    SORT mylist LIMIT 0 10

Almost all modifiers can be used together. The following example will return
the first 5 elements, lexicographically sorted in descending order:

    SORT mylist LIMIT 0 5 ALPHA DESC

## Sorting by external keys

Sometimes you want to sort elements using external keys as weights to compare
instead of comparing the actual elements in the list, set or sorted set.  Let's
say the list 'mylist' contains the elements '1', '2' and '3' representing
unique IDs of objects stored in 'object_1', 'object_2' and 'object_3'.  When
these objects have associated weights stored in 'weight_1', 'weight_2' and
'weight_3', 'SORT' can be instructed to use these weights to sort 'mylist' with
the following statement:

    SORT mylist BY weight_*

The 'BY' option takes a pattern (equal to 'weight_*' in this example) that is
used to generate the keys that are used for sorting.  These key names are
obtained substituting the first occurrence of '*' with the actual value of the
element in the list ('1', '2' and '3' in this example).

## Skip sorting the elements

The '!BY' option can also take a non-existent key, which causes 'SORT' to skip
the sorting operation. This is useful if you want to retrieve external keys
(see the '!GET' option below) without the overhead of sorting.

    SORT mylist BY nosort

## Retrieving external keys

Our previous example returns just the sorted IDs. In some cases, it is more
useful to get the actual objects instead of their IDs ('object_1', 'object_2'
and 'object_3').  Retrieving external keys based on the elements in a list, set
or sorted set can be done with the following command:

    SORT mylist BY weight_* GET object_*

The '!GET' option can be used multiple times in order to get more keys for
every element of the original list, set or sorted set.

It is also possible to '!GET' the element itself using the special pattern '#':

    SORT mylist BY weight_* GET object_* GET #

## Storing the result of a SORT operation

By default, 'SORT' returns the sorted elements to the client. With the '!STORE'
option, the result will be stored as a list at the specified key instead of
being returned to the client.

    SORT mylist BY weight_* STORE resultkey

An interesting pattern using 'SORT ... STORE' consists in associating an
'EXPIRE' timeout to the resulting key so that in applications where the result
of a 'SORT' operation can be cached for some time. Other clients will use the
cached list instead of calling 'SORT' for every request. When the key will
timeout, an updated version of the cache can be created by calling 'SORT ... STORE' again.

Note that for correctly implementing this pattern it is important to avoid multiple
clients rebuilding the cache at the same time. Some kind of locking is needed here
(for instance using 'SETNX').

## Using hashes in '!BY' and '!GET'

It is possible to use '!BY' and '!GET' options against hash fields with the
following syntax:

    SORT mylist BY weight_*->fieldname GET object_*->fieldname

The string '->' is used to separate the key name from the hash field name.
The key is substituted as documented above, and the hash stored at the
resulting key is accessed to retrieve the specified hash field.

@return

@multi-bulk-reply: list of sorted elements.`},
    "debug segfault": {"debug segfault", "Make the server crash", "-", "server", "0.101", `@complexity

@description

@examples

@return`},
    "sdiff": {"sdiff", "Subtract multiple sets", "key [key ...]", "set", "0.100", `@complexity

O(N) where N is the total number of elements in all given sets.

Returns the members of the set resulting from the difference between the first
set and all the successive sets.

For example:

    key1 = {a,b,c,d}
    key2 = {c}
    key3 = {a,c,e}
    SDIFF key1 key2 key3 = {b,d}

Keys that do not exist are considered to be empty sets.

@return

@multi-bulk-reply: list with members of the resulting set.

@examples

    @cli
    SADD key1 "a"
    SADD key1 "b"
    SADD key1 "c"
    SADD key2 "c"
    SADD key2 "d"
    SADD key2 "e"
    SDIFF key1 key2`},
    "linsert": {"linsert", "Insert an element before or after another element in a list", "key BEFORE|AFTER pivot value", "list", "2.1.1", `@complexity

O(N) where N is the number of elements to traverse before seeing the value
'pivot'. This means that inserting somewhere on the left end on the list (head)
can be considered O(1) and inserting somewhere on the right end (tail) is O(N).

Inserts 'value' in the list stored at 'key' either before or after the
reference value 'pivot'.

When 'key' does not exist, it is considered an empty list and no operation is
performed.

An error is returned when 'key' exists but does not hold a list value.

@return

@integer-reply: the length of the list after the insert operation, or '-1' when
the value 'pivot' was not found.

@examples

    @cli
    RPUSH mylist "Hello"
    RPUSH mylist "World"
    LINSERT mylist BEFORE "World" "There"
    LRANGE mylist 0 -1`},
    "incr": {"incr", "Increment the integer value of a key by one", "key", "string", "0.07", `@complexity

O(1)


Increments the number stored at 'key' by one.
If the key does not exist, it is set to '0' before performing the operation. An
error is returned if the key contains a value of the wrong type or contains a
string that is not representable as integer. This operation is limited to 64
bit signed integers.

**Note**: this is a string operation because Redis does not have a dedicated
integer type. The the string stored at the key is interpreted as a base-10 64
bit signed integer to execute the operation.

Redis stores integers in their integer representation, so for string values
that actually hold an integer, there is no overhead for storing the
string representation of the integer.

@return

@integer-reply: the value of 'key' after the increment

@examples

    @cli
    SET mykey "10"
    INCR mykey
    GET mykey`},
    "hlen": {"hlen", "Get the number of fields in a hash", "key", "hash", "1.3.10", `@complexity

O(1)


Returns the number of fields contained in the hash stored at 'key'.

@return

@integer-reply: number of fields in the hash, or '0' when 'key' does not exist.

@examples

    @cli
    HSET myhash field1 "Hello"
    HSET myhash field2 "World"
    HLEN myhash`},
    "eval": {"eval", "Execute a Lua script server side", "script numkeys key [key ...] arg [arg ...]", "generic", "2.6.0", `@complexity

Looking up the script both with 'EVAL' or 'EVALSHA' is an O(1) business. The
additional complexity is up to the script you execute.

Warning
---

Redis scripting support is currently a work in progress. This feature
will be shipped as stable with the release of Redis 2.6. The information
in this document reflects what is currently implemented, but it is
possible that changes will be made before the release of the stable
version.

Introduction to EVAL
---

'EVAL' and 'EVALSHA' are used to evaluate scripts using the Lua interpreter
built into Redis starting from version 2.6.0.

The first argument of 'EVAL' itself is a Lua script. The script does not need
to define a Lua function, it is just a Lua program that will run in the context
of the Redis server.

The second argument of 'EVAL' is the number of arguments that follows
(starting from the third argument) that represent Redis key names.
This arguments can be accessed by Lua using the 'KEYS' global variable in
the form of a one-based array (so 'KEYS[1]', 'KEYS[2]', ...).

All the additional arguments that should not represent key names can
be accessed by Lua using the 'ARGV' global variable, very similarly to
what happens with keys (so 'ARGV[1]', 'ARGV[2]', ...).

The following example can clarify what stated above:

    > eval "return {KEYS[1],KEYS[2],ARGV[1],ARGV[2]}" 2 key1 key2 first second
    1) "key1"
    2) "key2"
    3) "first"
    4) "second"

Note: as you can see Lua arrays are returned as Redis multi bulk
replies, that is a Redis return type that your client library will
likely convert into an Array in your programming language.

It is possible to call Redis program from a Lua script using two different
Lua functions:

* 'redis.call()'
* 'redis.pcall()'

'redis.call()' is similar to 'redis.pcall()', the only difference is that if a
Redis command call will result into an error, 'redis.call()' will raise a
Lua error that in turn will make 'EVAL' to fail, while 'redis.pcall' will trap
the error returning a Lua table representing the error.

The arguments of the 'redis.call()' and 'redis.pcall()' functions are simply
all the arguments of a well formed Redis command:

    > eval "return redis.call('set','foo','bar')" 0
    OK

The above script works and will set the key 'foo' to the string "bar".
However it violates the 'EVAL' command semantics as all the keys that the
script uses should be passed using the KEYS array, in the following way:

    > eval "return redis.call('set',KEYS[1],'bar')" 1 foo
    OK

The reason for passing keys in the proper way is that, before of 'EVAL' all
the Redis commands could be analyzed before execution in order to
establish what are the keys the command will operate on.

In order for this to be true for 'EVAL' also keys must be explicit.
This is useful in many ways, but especially in order to make sure Redis Cluster
is able to forward your request to the appropriate cluster node (Redis
Cluster is a work in progress, but the scripting feature was designed
in order to play well with it).

Lua scripts can return a value that is converted from Lua to the Redis protocol
using a set of conversion rules.

Conversion between Lua and Redis data types
---

Redis return values are converted into Lua data types when Lua calls a
Redis command using call() or pcall(). Similarly Lua data types are
converted into Redis data types when a script returns some value, that
we need to use as the 'EVAL' reply.

This conversion between data types is designed in a way that if
a Redis type is converted into a Lua type, and then the result is converted
back into a Redis type, the result is the same as of the initial value.

In other words there is a one to one conversion between Lua and Redis types.
The following table shows you all the conversions rules:

**Redis to Lua** conversion table.

* Redis integer reply -> Lua number
* Redis bulk reply -> Lua string
* Redis multi bulk reply -> Lua table (may have other Redis data types nested)
* Redis status reply -> Lua table with a single 'ok' field containing the status
* Redis error reply -> Lua table with a single 'err' field containing the error
* Redis Nil bulk reply and Nil multi bulk reply -> Lua false boolean type

**Lua to Redis** conversion table.

* Lua number -> Redis integer reply
* Lua string -> Redis bulk reply
* Lua table (array) -> Redis multi bulk reply
* Lua table with a single 'ok' field -> Redis status reply
* Lua table with a single 'err' field -> Redis error reply
* Lua boolean false -> Redis Nil bulk reply.

There is an additional Lua to Redis conversion that has no corresponding
Redis to Lua conversion:

 * Lua boolean true -> Redis integer reply with value of 1.

The followings are a few conversion examples:

    > eval "return 10" 0
    (integer) 10

    > eval "return {1,2,{3,'Hello World!'}}" 0
    1) (integer) 1
    2) (integer) 2
    3) 1) (integer) 3
       2) "Hello World!"

    > eval "return redis.call('get','foo')" 0
    "bar"

The last example shows how it is possible to directly return from Lua
the return value of 'redis.call()' and 'redis.pcall()' with the result of
returning exactly what the called command would return if called directly.

Atomicity of scripts
---

Redis uses the same Lua interpreter to run all the commands. Also Redis
guarantees that a script is executed in an atomic way: no other script
or Redis command will be executed while a script is being executed.
This semantics is very similar to the one of 'MULTI' / 'EXEC'.

However this also means that executing slow scripts is not a good idea.
It is not hard to create fast scripts, as the script overhead is very low,
but if you are going to use slow scripts you should be aware that while the
script is running no other client can execute commands since the server
is busy.

Error handling
---

As already stated calls to 'redis.call()' resulting into a Redis command error
will stop the execution of the script and will return that error back, in a
way that makes it obvious the error was generated by a script:

    > del foo
    (integer) 1
    > lpush foo a
    (integer) 1
    > eval "return redis.call('get','foo')" 0
    (error) ERR Error running script (call to f_6b1bf486c81ceb7edf3c093f4c48582e38c0e791): ERR Operation against a key holding the wrong kind of value

Using the 'redis.pcall()' command no error is raised, but an error object
is returned in the format specified above (as a Lua table with an 'err'
field). The user can later return this error to the user just returning the
error object returned by 'redis.pcall()'.

Bandwidth and EVALSHA
---

The 'EVAL' command forces you to send the script body again and again, even if
it does not need to recompile the script every time as it uses an internal
caching mechanism. However paying the cost of the additional bandwidth may
not be optimal in all the contexts.

On the other hand defining commands using a special command or via 'redis.conf'
would be a problem for a few reasons:

* Different instances may have different versions of a command
implementation.

* Deployment is hard if there is to make sure all the instances contain
a given command, especially in a distributed environment.

* Reading an application code the full semantic could not be clear since
the application would call commands defined server side.

In order to avoid the above three problems and at the same time don't incur
in the bandwidth penalty Redis implements the 'EVALSHA' command.

'EVALSHA' works exactly as 'EVAL', but instead of having a script as first argument
it has the SHA1 sum of a script. The behavior is the following:

* If the server still remembers a script whose SHA1 sum was the one
specified, the script is executed.

* If the server does not remember a script with this SHA1 sum, a special
error is returned that will tell the client to use 'EVAL' instead.

Example:

    > set foo bar
    OK
    > eval "return redis.call('get','foo')" 0
    "bar"
    > evalsha 6b1bf486c81ceb7edf3c093f4c48582e38c0e791 0
    "bar"
    > evalsha ffffffffffffffffffffffffffffffffffffffff 0
    (error) 'NOSCRIPT' No matching script. Please use 'EVAL'.

The client library implementation can always optimistically send 'EVALSHA' under
the hoods even when the client actually called 'EVAL', in the hope the script
was already seen by the server. If the 'NOSCRIPT' error is returned 'EVAL' will be
used instead. Passing keys and arguments as 'EVAL' additional arguments is also
very useful in this context as the script string remains constant and can be
efficiently cached by Redis.

Script cache semantics
---

Executed scripts are guaranteed to be in the script cache forever.
This means that if an 'EVAL' is performed against a Redis instance all the
subsequent 'EVALSHA' calls will succeed.

The only way to flush the script cache is by explicitly calling the
SCRIPT FLUSH command, that will flush the scripts cache. This is usually
needed only when the instance is going to be instantiated for another
customer in a cloud environment.

The reason why scripts can be cached for long time is that it is unlikely
for a well written application to have so many different scripts to create
memory problems. Every script is conceptually like the implementation of
a new command, and even a large application will likely have just a few
hundreds of that. Even if the application is modified many times and
scripts will change, still the memory used is negligible.

The fact that the user can count on Redis not removing scripts
is semantically a very good thing. For instance an application taking
a persistent connection to Redis can stay sure that if a script was
sent once it is still in memory, thus for instance can use EVALSHA
against those scripts in a pipeline without the change that an error
will be generated since the script is not known (we'll see this problem
in its details later).

The SCRIPT command
---

Redis offers a SCRIPT command that can be used in order to control
the scripting subsystem. SCRIPT currently accepts three different commands:

* SCRIPT FLUSH. This command is the only way to force Redis to flush the
scripts cache. It is mostly useful in a cloud environment where the same
instance can be reassigned to a different user. It is also useful for
testing client libraries implementations of the scripting feature.

* SCRIPT EXISTS *sha1* *sha2* ... *shaN*. Given a list of SHA1 digests
as arguments this command returns an array of 1 or 0, where 1 means the
specific SHA1 is recognized as a script already present in the scripting
cache, while 0 means that a script with this SHA1 was never seen before
(or at least never seen after the latest SCRIPT FLUSH command).

* SCRIPT LOAD *script*. This command registers the specified script in
the Redis script cache. The command is useful in all the contexts where
we want to make sure that 'EVALSHA' will not fail (for instance during a
pipeline or MULTI/EXEC operation).

* SCRIPT KILL. This command is the only wait to interrupt a long running
script that reached the configured maximum execution time for scripts.
The SCRIPT KILL command can only be used with scripts that did not modified
the dataset during their execution (since stopping a read only script does
not violate the scripting engine guaranteed atomicity).
See the next sections for more information about long running scripts.

Scripts as pure functions
---

A very important part of scripting is writing scripts that are pure functions.
Scripts executed in a Redis instance are replicated on slaves sending the
same script, instead of the resulting commands. The same happens for the
Append Only File. The reason is that scripts are much faster than sending
commands one after the other to a Redis instance, so if the client is
taking the master very busy sending scripts, turning this scripts into single
commands for the slave / AOF would result in too much load for the replication
link or the Append Only File.

The only drawback with this approach is that scripts are required to
have the following property:

* The script always evaluates the same Redis *write* commands with the
same arguments given the same input data set. Operations performed by
the script cannot depend on any hidden information or state that may
change as script execution proceeds or between different executions of
the script, nor can it depend on any external input from I/O devices.

Things like using the system time, calling Redis random commands like
RANDOMKEY, or using Lua random number generator, could result into scripts
that will not evaluate always in the same way.

In order to enforce this behavior in scripts Redis does the following:

* Lua does not export commands to access the system time or other
external state.

* Redis will block the script with an error if a script will call a
Redis command able to alter the data set **after** a Redis random
command like RANDOMKEY or SRANDMEMBER. This means that if a script is
read only and does not modify the data set it is free to call those
commands.

* Lua pseudo random number generation functions 'math.random' and
'math.randomseed' are modified in order to always have the same seed every
time a new script is executed. This means that calling 'math.random' will
always generate the same sequence of numbers every time a script is
executed if 'math.randomseed' is not used.

However the user is still able to write commands with random behaviors
using the following simple trick. For example I want to write a Redis
script that will populate a list with N random integers.

I can start writing the following script, using a small Ruby program:

    require 'rubygems'
    require 'redis'

    r = Redis.new

    RandomPushScript = <<EOF
        local i = tonumber(ARGV[1])
        while (i > 0) do
            res = redis.call('lpush',KEYS[1],math.random())
            i = i-1
        end
        return res
    EOF

    r.del(:mylist)
    puts r.eval(RandomPushScript,1,:mylist,10)

Every time this script executed the resulting list will have exactly the
following elements:

    > lrange mylist 0 -1
     1) "0.74509509873814"
     2) "0.87390407681181"
     3) "0.36876626981831"
     4) "0.6921941534114"
     5) "0.7857992587545"
     6) "0.57730350670279"
     7) "0.87046522734243"
     8) "0.09637165539729"
     9) "0.74990198051087"
    10) "0.17082803611217"

In order to make it a pure function, but still making sure that every
invocation of the script will result in a different random elements, we can
simply add an additional argument to the script, that will be used in order to
seed the Lua PRNG. The new script will be like the following:

    RandomPushScript = <<EOF
        local i = tonumber(ARGV[1])
        math.randomseed(tonumber(ARGV[2]))
        while (i > 0) do
            res = redis.call('lpush',KEYS[1],math.random())
            i = i-1
        end
        return res
    EOF

    r.del(:mylist)
    puts r.eval(RandomPushScript,1,:mylist,10,rand(2**32))

What we are doing here is to send the seed of the PRNG as one of the
arguments. This way the script output will be the same given the same
arguments, but we are changing one of the argument at every invocation,
generating the random seed client side. The seed will be propagated as
one of the arguments both in the replication link and in the Append Only
File, guaranteeing that the same changes will be generated when the AOF
is reloaded or when the slave will process the script.

Note: an important part of this behavior is that the PRNG that Redis implements
as 'math.random' and 'math.randomseed' is guaranteed to have the same output
regardless of the architecture of the system running Redis. 32 or 64 bit systems
like big or little endian systems will still produce the same output.

Available libraries
---

The Redis Lua interpreter loads the following Lua libraries:

* Base lib.
* Table lib.
* String lib.
* Math lib.
* Debug lib.
* CJSON lib.

Every Redis instance is *guaranteed* to have all the above libraries so you
can be sure that the environment for your Redis scripts is always the same.

The CJSON library allows to manipulate JSON data in a very fast way from Lua.
All the other libraries are standard Lua libraries.

Sandbox and maximum execution time
---

Scripts should never try to access the external system, like the file system,
nor calling any other system call. A script should just do its work operating
on Redis data, starting form Redis data.

Scripts also are subject to a maximum execution time of five seconds.
This default timeout is huge since a script should run usually in a sub
millisecond amount of time. The limit is mostly needed in order to avoid
problems when developing scripts that may loop forever for a programming
error.

It is possible to modify the maximum time a script can be executed
with milliseconds precision, either via 'redis.conf' or using the
CONFIG GET / CONFIG SET command. The configuration parameter
affecting max execution time is called 'lua-time-limit'.

When a script reaches the timeout it is not automatically terminated by
Redis since this violates the contract Redis has with the scripting engine
to ensure that scripts are atomic in nature. Stopping a script half-way means
to possibly leave the dataset with half-written data inside.
For this reasons when a script executes for more than the specified time
the following happens:

* Redis logs that a script that is running for too much time is still in execution.
* It starts accepting commands again from other clients, but will reply with a BUSY error to all the clients sending normal commands. The only allowed commands in this status are 'SCRIPT KILL' and 'SHUTDOWN NOSAVE'.
* It is possible to terminate a script that executed only read-only commands using the 'SCRIPT KILL' command. This does not violate the scripting semantic as no data was yet written on the dataset by the script.
* If the script already called write commands against the data set the only allowed command becomes 'SHUTDOWN NOSAVE' that stops the server not saving the current data set on disk (basically the server is aborted).

EVALSHA in the context of pipelining
---

Care should be taken when executing 'EVALSHA' in the context of a pipelined
request, since even in a pipeline the order of execution of commands must
be guaranteed. If 'EVALSHA' will return a 'NOSCRIPT' error the command can not
be reissued later otherwise the order of execution is violated.

The client library implementation should take one of the following
approaches:

* Always use plain 'EVAL' when in the context of a pipeline.

* Accumulate all the commands to send into the pipeline, then check for
'EVAL' commands and use the SCRIPT EXISTS command to check if all the
scripts are already defined. If not add SCRIPT LOAD commands on top of
the pipeline as required, and use 'EVALSHA' for all the 'EVAL' calls.`},
    "auth": {"auth", "Authenticate to the server", "password", "connection", "0.08", `@description

Request for authentication in a password protected Redis server.
Redis can be instructed to require a password before allowing clients
to execute commands. This is done using the 'requirepass' directive in the
configuration file.

If 'password' matches the password in the configuration file, the server replies with
the 'OK' status code and starts accepting commands.
Otherwise, an error is returned and the clients needs to try a new password.

**Note**: because of the high performance nature of Redis, it is possible to try
a lot of passwords in parallel in very short time, so make sure to generate
a strong and very long password so that this attack is infeasible.

@return

@status-reply`},
    "psubscribe": {"psubscribe", "Listen for messages published to channels matching the given patterns", "pattern [pattern ...]", "pubsub", "1.3.8", `@complexity

O(N) where N is the number of patterns the client is already subscribed to.

Subscribes the client to the given patterns.`},
    "zrank": {"zrank", "Determine the index of a member in a sorted set", "key member", "sorted_set", "1.3.4", `@complexity

O(log(N))


Returns the rank of 'member' in the sorted set stored at 'key', with the scores
ordered from low to high. The rank (or index) is 0-based, which means that the
member with the lowest score has rank '0'.

Use 'ZREVRANK' to get the rank of an element with the scores ordered from high
to low.

@return

* If 'member' exists in the sorted set, @integer-reply: the rank of 'member'.
* If 'member' does not exist in the sorted set or 'key' does not exist,
@bulk-reply: 'nil'.

@examples

    @cli
    ZADD myzset 1 "one"
    ZADD myzset 2 "two"
    ZADD myzset 3 "three"
    ZRANK myzset "three"
    ZRANK myzset "four"`},
    "lrem": {"lrem", "Remove elements from a list", "key count value", "list", "0.07", `@complexity

O(N) where N is the length of the list.

Removes the first 'count' occurrences of elements equal to 'value' from the
list stored at 'key'. The 'count' argument influences the operation in the
following ways:

* 'count > 0': Remove elements equal to 'value' moving from head to tail.
* 'count < 0': Remove elements equal to 'value' moving from tail to head.
* 'count = 0': Remove all elements equal to 'value'.

For example, 'LREM list -2 "hello"' will remove the last two occurrences of
'"hello"' in the list stored at 'list'.

Note that non-existing keys are treated like empty lists, so when 'key' does
not exist, the command will always return '0'.

@return

@integer-reply: the number of removed elements.

@examples

    @cli
    RPUSH mylist "hello"
    RPUSH mylist "hello"
    RPUSH mylist "foo"
    RPUSH mylist "hello"
    LREM mylist -2 "hello"
    LRANGE mylist 0 -1`},
    "select": {"select", "Change the selected database for the current connection", "index", "connection", "0.07", `@description

Select the DB with having the specified zero-based numeric index.
New connections always use DB 0.

@return

@status-reply`},
    "slowlog": {"slowlog", "Manages the Redis slow queries log", "subcommand [argument]", "server", "2.2.12", `This command is used in order to read and reset the Redis slow queries log.

## Redis slow log overview

The Redis Slow Log is a system to log queries that exceeded a specified
execution time. The execution time does not include I/O operations
like talking with the client, sending the reply and so forth,
but just the time needed to actually execute the command (this is the only
stage of command execution where the thread is blocked and can not serve
other requests in the meantime).

You can configure the slow log with two parameters: one tells Redis
what is the execution time, in microseconds, to exceed in order for the
command to get logged, and the other parameter is the length of the
slow log. When a new command is logged and the slow log is already at its
maximum length, the oldest one is removed from the queue of logged commands
in order to make space.

The configuration can be done both editing the redis.conf file or 
while the server is running using
the [CONFIG GET](/commands/config-get) and [CONFIG SET](/commands/config-set)
commands.

## Reading the slow log

The slow log is accumulated in memory, so no file is written with information
about the slow command executions. This makes the slow log remarkably fast
at the point that you can enable the logging of all the commands (setting the
*slowlog-log-slower-than* config parameter to zero) with minor performance
hit.

To read the slow log the **SLOWLOG GET** command is used, that returns every
entry in the slow log. It is possible to return only the N most recent entries
passing an additional argument to the command (for instance **SLOWLOG GET 10**).

Note that you need a recent version of redis-cli in order to read the slow
log output, since it uses some features of the protocol that were not
formerly implemented in redis-cli (deeply nested multi bulk replies).

## Output format

    redis 127.0.0.1:6379> slowlog get 2
    1) 1) (integer) 14
       2) (integer) 1309448221
       3) (integer) 15
       4) 1) "ping"
    2) 1) (integer) 13
       2) (integer) 1309448128
       3) (integer) 30
       4) 1) "slowlog"
          2) "get"
          3) "100"

Every entry is composed of four fields:
* A unique progressive identifier for every slow log entry.
* The unix timestamp at which the logged command was processed.
* The amount of time needed for its execution, in microseconds.
* The array composing the arguments of the command.

The entry's unique ID can be used in order to avoid processing slow log entries
multiple times (for instance you may have a script sending you an email
alert for every new slow log entry).

The ID is never reset in the course of the Redis server execution, only a
server restart will reset it.

## Obtaining the current length of the slow log

It is possible to get just the length of the slow log using the command **SLOWLOG LEN**.

## Resetting the slow log.

You can reset the slow log using the **SLOWLOG RESET** command.
Once deleted the information is lost forever.`},
    "discard": {"discard", "Discard all commands issued after MULTI", "-", "transactions", "1.3.3", `Flushes all previously queued commands in a
[transaction](/topics/transactions) and restores the connection state to
normal.

If 'WATCH' was used, 'DISCARD' unwatches all keys.

@return

@status-reply: always 'OK'.`},
    "zadd": {"zadd", "Add one or more members to a sorted set, or update its score if it already exists", "key score member [score] [member]", "sorted_set", "1.1", `@complexity

O(log(N)) where N is the number of elements in the sorted set.

Adds all the specified members with the specified scores to the sorted set stored at 'key'. It is possible to specify multiple score/member pairs.
If a specified member is already a member of the sorted set, the score is updated and the element reinserted at the right position to ensure the correct ordering.  If 'key' does not exist, a new sorted set with the specified members as sole
members is created, like if the sorted set was empty.
If the key exists but does not hold a sorted set, an error is returned.

The score values should be the string representation of a numeric value, and
accepts double precision floating point numbers.

For an introduction to sorted sets, see the data types page on [sorted
sets](/topics/data-types#sorted-sets).

@return

@integer-reply, specifically:

* The number of elements added to the sorted sets, not including elements already existing for which the score was updated.

@history

* '>= 2.4': Accepts multiple elements. In Redis versions older than 2.4 it was possible to add or update a single member per call.

@examples

    @cli
    ZADD myzset 1 "one"
    ZADD myzset 1 "uno"
    ZADD myzset 2 "two"
    ZADD myzset 3 "two"
    ZRANGE myzset 0 -1 WITHSCORES`},
    "info": {"info", "Get information and statistics about the server", "-", "server", "0.07", `The 'INFO' command returns information and statistics about the server
in format that is simple to parse by computers and easy to red by humans.

@return

@bulk-reply: in the following format (compacted for brevity):

    redis_version:2.2.2
    uptime_in_seconds:148
    used_cpu_sys:0.01
    used_cpu_user:0.03
    used_memory:768384
    used_memory_rss:1536000
    mem_fragmentation_ratio:2.00
    changes_since_last_save:118
    keyspace_hits:174
    keyspace_misses:37
    allocation_stats:4=56,8=312,16=1498,...
    db0:keys=1240,expires=0

All the fields are in the form of 'field:value' terminated by '\r\n'.

## Notes

* 'used_memory' is the total number of bytes allocated by Redis using its
  allocator (either standard 'libc' 'malloc', or an alternative allocator such as
  ['tcmalloc'][1]

* 'used_memory_rss' is the number of bytes that Redis allocated as seen by the
  operating system. Optimally, this number is close to 'used_memory' and there
  is little memory fragmentation. This is the number reported by tools such as
  'top' and 'ps'. A large difference between these numbers means there is
  memory fragmentation. Because Redis does not have control over how its
  allocations are mapped to memory pages, 'used_memory_rss' is often the result
  of a spike in memory usage. The ratio between 'used_memory_rss' and
  'used_memory' is given as 'mem_fragmentation_ratio'.

* 'changes_since_last_save' refers to the number of operations that produced
  some kind of change in the dataset since the last time either 'SAVE' or
  'BGSAVE' was called.

* 'allocation_stats' holds a histogram containing the number of allocations of
  a certain size (up to 256). This provides a means of introspection for the
  type of allocations performed by Redis at run time.

[1]: http://code.google.com/p/google-perftools/`},
    "exec": {"exec", "Execute all commands issued after MULTI", "-", "transactions", "1.1.95", `Executes all previously queued commands in a
[transaction](/topics/transactions) and restores the connection state to
normal.

When using 'WATCH', 'EXEC' will execute commands only if the
watched keys were not modified, allowing for a [check-and-set
mechanism](/topics/transactions#cas).

@return

@multi-bulk-reply: each element being the reply to each of the commands
in the atomic transaction.

When using 'WATCH', 'EXEC' can return a @nil-reply if the execution was
aborted.`},
    "decrby": {"decrby", "Decrement the integer value of a key by the given number", "key decrement", "string", "0.07", `@complexity

O(1)


Decrements the number stored at 'key' by 'decrement'.
If the key does not exist, it is set to '0' before performing the operation. An
error is returned if the key contains a value of the wrong type or contains a
string that is not representable as integer. This operation is limited to 64
bit signed integers.

See 'INCR' for extra information on increment/decrement operations.

@return

@integer-reply: the value of 'key' after the decrement

@examples

    @cli
    SET mykey "10"
    DECRBY mykey 5`},
    "ping": {"ping", "Ping the server", "-", "connection", "0.07", `@description

Returns 'PONG'. This command is often used to test if a connection is still
alive, or to measure latency.

@return

@status-reply

@examples

    @cli
    PING`},
    "llen": {"llen", "Get the length of a list", "key", "list", "0.07", `@complexity

O(1)


Returns the length of the list stored at 'key'.
If 'key' does not exist, it is interpreted as an empty list and '0' is returned.
An error is returned when the value stored at 'key' is not a list.

@return

@integer-reply: the length of the list at 'key'.

@examples

    @cli
    LPUSH mylist "World"
    LPUSH mylist "Hello"
    LLEN mylist`},
    "hmget": {"hmget", "Get the values of all the given hash fields", "key field [field ...]", "hash", "1.3.10", `@complexity

O(N) where N is the number of fields being requested.

Returns the values associated with the specified 'fields' in the hash stored at
'key'.

For every 'field' that does not exist in the hash, a 'nil' value is returned.
Because a non-existing keys are treated as empty hashes, running 'HMGET'
against a non-existing 'key' will return a list of 'nil' values.

@return

@multi-bulk-reply: list of values associated with the given fields, in the same
order as they are requested.

    @cli
    HSET myhash field1 "Hello"
    HSET myhash field2 "World"
    HMGET myhash field1 field2 nofield`},
    "unsubscribe": {"unsubscribe", "Stop listening for messages posted to the given channels", "[channel [channel ...]]", "pubsub", "1.3.8", `@complexity

O(N) where N is the number of clients already subscribed to a channel.

Unsubscribes the client from the given channels, or from all of them if
none is given.

When no channels are specified, the client is unsubscribed from all
the previously subscribed channels. In this case, a message for every
unsubscribed channel will be sent to the client.`},
    "decr": {"decr", "Decrement the integer value of a key by one", "key", "string", "0.07", `@complexity

O(1)


Decrements the number stored at 'key' by one.
If the key does not exist, it is set to '0' before performing the operation. An
error is returned if the key contains a value of the wrong type or contains a
string that is not representable as integer. This operation is limited to 64
bit signed integers.

See 'INCR' for extra information on increment/decrement operations.

@return

@integer-reply: the value of 'key' after the decrement

@examples

    @cli
    SET mykey "10"
    DECR mykey`},
    "rpop": {"rpop", "Remove and get the last element in a list", "key", "list", "0.07", `@complexity

O(1)


Removes and returns the last element of the list stored at 'key'.

@return

@bulk-reply: the value of the last element, or 'nil' when 'key' does not exist.

@examples

    @cli
    RPUSH mylist "one"
    RPUSH mylist "two"
    RPUSH mylist "three"
    RPOP mylist
    LRANGE mylist 0 -1`},
    "zrevrange": {"zrevrange", "Return a range of members in a sorted set, by index, with scores ordered from high to low", "key start stop [WITHSCORES]", "sorted_set", "1.1", `@complexity

O(log(N)+M) with N being the number of elements in the
sorted set and M the number of elements returned.

Returns the specified range of elements in the sorted set stored at 'key'. The
elements are considered to be ordered from the highest to the lowest score.
Descending lexicographical order is used for elements with equal score.

Apart from the reversed ordering, 'ZREVRANGE' is similar to 'ZRANGE'.

@return

@multi-bulk-reply: list of elements in the specified range (optionally with
their scores).

@examples

    @cli
    ZADD myzset 1 "one"
    ZADD myzset 2 "two"
    ZADD myzset 3 "three"
    ZREVRANGE myzset 0 -1
    ZREVRANGE myzset 2 3
    ZREVRANGE myzset -2 -1`},
    "zrangebyscore": {"zrangebyscore", "Return a range of members in a sorted set, by score", "key min max [WITHSCORES] [LIMIT offset count]", "sorted_set", "1.050", `@complexity

O(log(N)+M) with N being the number of elements in the sorted set and M the
number of elements being returned. If M is constant (e.g. always asking for the
first 10 elements with 'LIMIT'), you can consider it O(log(N)).

Returns all the elements in the sorted set at 'key' with a score between 'min'
and 'max' (including elements with score equal to 'min' or 'max'). The
elements are considered to be ordered from low to high scores.

The elements having the same score are returned in lexicographical order (this
follows from a property of the sorted set implementation in Redis and does not
involve further computation).

The optional 'LIMIT' argument can be used to only get a range of the matching
elements (similar to _SELECT LIMIT offset, count_ in SQL). Keep in mind that if
'offset' is large, the sorted set needs to be traversed for 'offset' elements
before getting to the elements to return, which can add up to O(N) time
complexity.

The optional 'WITHSCORES' argument makes the command return both the element
and its score, instead of the element alone. This option is available since
Redis 2.0.

## Exclusive intervals and infinity

'min' and 'max' can be '-inf' and '+inf', so that you are not required to know
the highest or lowest score in the sorted set to get all elements from or up to
a certain score.

By default, the interval specified by 'min' and 'max' is closed (inclusive).
It is possible to specify an open interval (exclusive) by prefixing the score
with the character '('. For example:

    ZRANGEBYSCORE zset (1 5

Will return all elements with '1 < score <= 5' while:

    ZRANGEBYSCORE zset (5 (10

Will return all the elements with '5 < score < 10' (5 and 10 excluded).

@return

@multi-bulk-reply: list of elements in the specified score range (optionally with
their scores).

@examples

    @cli
    ZADD myzset 1 "one"
    ZADD myzset 2 "two"
    ZADD myzset 3 "three"
    ZRANGEBYSCORE myzset -inf +inf
    ZRANGEBYSCORE myzset 1 2
    ZRANGEBYSCORE myzset (1 2
    ZRANGEBYSCORE myzset (1 (2`},
    "lpushx": {"lpushx", "Prepend a value to a list, only if the list exists", "key value", "list", "2.1.1", `@complexity

O(1)


Inserts 'value' at the head of the list stored at 'key', only if 'key'
already exists and holds a list. In contrary to 'LPUSH', no operation will
be performed when 'key' does not yet exist.

@return

@integer-reply: the length of the list after the push operation.

@examples

    @cli
    LPUSH mylist "World"
    LPUSHX mylist "Hello"
    LPUSHX myotherlist "Hello"
    LRANGE mylist 0 -1
    LRANGE myotherlist 0 -1`},
    "blpop": {"blpop", "Remove and get the first element in a list, or block until one is available", "key [key ...] timeout", "list", "1.3.1", `@complexity

O(1)


'BLPOP' is a blocking list pop primitive.  It is the blocking version of 'LPOP'
because it blocks the connection when there are no elements to pop from any of
the given lists. An element is popped from the head of the first list that is
non-empty, with the given keys being checked in the order that they are given.

## Non-blocking behavior

When 'BLPOP' is called, if at least one of the specified keys contain a
non-empty list, an element is popped from the head of the list and returned to
the caller together with the 'key' it was popped from.

Keys are checked in the order that they are given. Let's say that the key
'list1' doesn't exist and 'list2' and 'list3' hold non-empty lists. Consider
the following command:

    BLPOP list1 list2 list3 0

'BLPOP' guarantees to return an element from the list stored at 'list2' (since
it is the first non empty list when checking 'list1', 'list2' and 'list3' in
that order).

## Blocking behavior

If none of the specified keys exist, 'BLPOP' blocks
the connection until another client performs an 'LPUSH' or 'RPUSH' operation
against one of the keys.

Once new data is present on one of the lists, the client returns with the name
of the key unblocking it and the popped value.

When 'BLPOP' causes a client to block and a non-zero timeout is specified, the
client will unblock returning a 'nil' multi-bulk value when the specified
timeout has expired without a push operation against at least one of the
specified keys.

The timeout argument is interpreted as an integer value. A timeout of zero can
be used to block indefinitely.

## Multiple clients blocking for the same keys

Multiple clients can block for the same key. They are put into
a queue, so the first to be served will be the one that started to wait
earlier, in a first-'!BLPOP' first-served fashion.

## '!BLPOP' inside a '!MULTI'/'!EXEC' transaction

'BLPOP' can be used with pipelining (sending multiple commands and reading the
replies in batch), but it does not make sense to use 'BLPOP' inside a
'MULTI'/'EXEC' block. This would require blocking the entire server in order to
execute the block atomically, which in turn does not allow other clients to
perform a push operation.

The behavior of 'BLPOP' inside 'MULTI'/'EXEC' when the list is empty is to
return a 'nil' multi-bulk reply, which is the same thing that happens when the
timeout is reached. If you like science fiction, think of time flowing at
infinite speed inside a 'MULTI'/'EXEC' block.

@return

@multi-bulk-reply: specifically:

* A 'nil' multi-bulk when no element could be popped and the timeout expired.
* A two-element multi-bulk with the first element being the name of the key where an element
  was popped and the second element being the value of the popped element.`},
    "hget": {"hget", "Get the value of a hash field", "key field", "hash", "1.3.10", `@complexity

O(1)


Returns the value associated with 'field' in the hash stored at 'key'.

@return

@bulk-reply: the value associated with 'field', or 'nil' when 'field' is not
present in the hash or 'key' does not exist.

@examples

    @cli
    HSET myhash field1 "foo"
    HGET myhash field1
    HGET myhash field2`},
    "setex": {"setex", "Set the value and expiration of a key", "key seconds value", "string", "1.3.10", `@complexity

O(1)


Set 'key' to hold the string 'value' and set 'key' to timeout after a given
number of seconds.  This command is equivalent to executing the following
commands:

    SET mykey value
    EXPIRE mykey seconds

'SETEX' is atomic, and can be reproduced by using the previous two commands
inside an 'MULTI'/'EXEC' block. It is provided as a faster alternative to the
given sequence of operations, because this operation is very common when Redis
is used as a cache.

An error is returned when 'seconds' is invalid.

@return

@status-reply

@examples

    @cli
    SETEX mykey 10 "Hello"
    TTL mykey
    GET mykey`},
    "type": {"type", "Determine the type stored at key", "key", "generic", "0.07", `@complexity

O(1)


Returns the string representation of the type of the value stored at 'key'.
The different types that can be returned are: 'string', 'list', 'set', 'zset'
and 'hash'.

@return

@status-reply: type of 'key', or 'none' when 'key' does not exist.

@examples

    @cli
    SET key1 "value"
    LPUSH key2 "value"
    SADD key3 "value"
    TYPE key1
    TYPE key2
    TYPE key3`},
    "sinterstore": {"sinterstore", "Intersect multiple sets and store the resulting set in a key", "destination key [key ...]", "set", "0.07", `@complexity

O(N*M) worst case where N is the cardinality of the smallest set and M is the
number of sets.

This command is equal to 'SINTER', but instead of returning the resulting set,
it is stored in 'destination'.

If 'destination' already exists, it is overwritten.

@return

@integer-reply: the number of elements in the resulting set.`},
    "msetnx": {"msetnx", "Set multiple keys to multiple values, only if none of the keys exist", "key value [key value ...]", "string", "1.001", `@complexity

O(N) where N is the number of keys to set


Sets the given keys to their respective values. 'MSETNX' will not perform any
operation at all even if just a single key already exists.

Because of this semantic 'MSETNX' can be used in order to set different keys
representing different fields of an unique logic object in a way that
ensures that either all the fields or none at all are set.

'MSETNX' is atomic, so all given keys are set at once. It is not possible for
clients to see that some of the keys were updated while others are unchanged.

@return

@integer-reply, specifically:

* '1' if the all the keys were set.
* '0' if no key was set (at least one key already existed).

@examples

    @cli
    MSETNX key1 "Hello" key2 "there"
    MSETNX key2 "there" key3 "world"
    MGET key1 key2 key3`},
    "ttl": {"ttl", "Get the time to live for a key", "key", "generic", "0.100", `@complexity

O(1)


Returns the remaining time to live of a key that has a timeout.  This
introspection capability allows a Redis client to check how many seconds a
given key will continue to be part of the dataset.

@return

@integer-reply: TTL in seconds or '-1' when 'key' does not exist or does not have a timeout.

@examples

    @cli
    SET mykey "Hello"
    EXPIRE mykey 10
    TTL mykey`},
    "save": {"save", "Synchronously save the dataset to disk", "-", "server", "0.07", `@complexity

@description

@examples

@return`},
    "sdiffstore": {"sdiffstore", "Subtract multiple sets and store the resulting set in a key", "destination key [key ...]", "set", "0.100", `@complexity

O(N) where N is the total number of elements in all given sets.

This command is equal to 'SDIFF', but instead of returning the resulting set,
it is stored in 'destination'.

If 'destination' already exists, it is overwritten.

@return

@integer-reply: the number of elements in the resulting set.`},
    "hincrby": {"hincrby", "Increment the integer value of a hash field by the given number", "key field increment", "hash", "1.3.10", `@complexity

O(1)


Increments the number stored at 'field' in the hash stored at 'key' by
'increment'. If 'key' does not exist, a new key holding a hash is created. If
'field' does not exist the value is set to '0' before the operation is
performed.

The range of values supported by 'HINCRBY' is limited to 64 bit signed
integers.

@return

@integer-reply: the value at 'field' after the increment operation.

@examples

Since the 'increment' argument is signed, both increment and decrement
operations can be performed:

    @cli
    HSET myhash field 5
    HINCRBY myhash field 1
    HINCRBY myhash field -1
    HINCRBY myhash field -10`},
    "smembers": {"smembers", "Get all the members in a set", "key", "set", "0.07", `@complexity

O(N) where N is the set cardinality.

Returns all the members of the set value stored at 'key'.

This has the same effect as running 'SINTER' with one argument 'key'.

@return

@multi-bulk-reply: all elements of the set.

@examples

    @cli
    SADD myset "Hello"
    SADD myset "World"
    SMEMBERS myset`},
    "slaveof": {"slaveof", "Make the server a slave of another instance, or promote it as master", "host port", "server", "0.100", `The 'SLAVEOF' command can change the replication settings of a slave on the fly.
If a Redis server is already acting as slave, the command 'SLAVEOF' NO ONE
will turn off the replication turning the Redis server into a MASTER.
In the proper form 'SLAVEOF' hostname port will make the server a slave of the
specific server listening at the specified hostname and port.

If a server is already a slave of some master, 'SLAVEOF' hostname port will
stop the replication against the old server and start the synchronization
against the new one discarding the old dataset.

The form 'SLAVEOF' no one will stop replication turning the server into a
MASTER but will not discard the replication. So if the old master stop working
it is possible to turn the slave into a master and set the application to
use the new master in read/write. Later when the other Redis server will be
fixed it can be configured in order to work as slave.

@return

@status-reply`},
    "lastsave": {"lastsave", "Get the UNIX time stamp of the last successful save to disk", "-", "server", "0.07", `Return the UNIX TIME of the last DB save executed with success.
A client may check if a 'BGSAVE' command succeeded reading the 'LASTSAVE'
value, then issuing a 'BGSAVE' command and checking at regular intervals
every N seconds if 'LASTSAVE' changed.

@return

@integer-reply: an UNIX time stamp.`},
    "punsubscribe": {"punsubscribe", "Stop listening for messages posted to channels matching the given patterns", "[pattern [pattern ...]]", "pubsub", "1.3.8", `@complexity

O(N+M) where N is the number of patterns the client is already
subscribed and M is the number of total patterns subscribed in the
system (by any client).

Unsubscribes the client from the given patterns, or from all of them if
none is given.

When no patters are specified, the client is unsubscribed from all
the previously subscribed patterns. In this case, a message for every
unsubscribed pattern will be sent to the client.`},
    "echo": {"echo", "Echo the given string", "message", "connection", "0.07", `@description

Returns 'message'.

@return

@bulk-reply

@examples

    @cli
    ECHO "Hello World!"`},
    "object": {"object", "Inspect the internals of Redis objects", "subcommand [arguments [arguments ...]]", "generic", "2.2.3", `@complexity

O(1) for all the currently implemented subcommands.

The 'OBJECT' command allows to inspect the internals of Redis Objects associated
with keys. It is useful for debugging or to understand if your keys are using
the specially encoded data types to save space. Your application may also use
the information reported by the 'OBJECT' command to implement application level
key eviction policies when using Redis as a Cache.

The 'OBJECT' command supports multiple sub commands:

* 'OBJECT REFCOUNT <key>' returns the number of references of the value associated with the specified key. This command is mainly useful for debugging.
* 'OBJECT ENCODING <key>' returns the kind of internal representation used in order to store the value associated with a key.
* 'OBJECT IDLETIME <key>' returns the number of seconds since the object stored at the specified key is idle (not requested by read or write operations). While the value is returned in seconds the actual resolution of this timer is 10 seconds, but may vary in future implementations.

Objects can be encoded in different ways:

* Strings can be encoded as 'raw' (normal string encoding) or 'int' (strings representing integers in a 64 bit signed interval are encoded in this way in order to save space).
* Lists can be encoded as 'ziplist' or 'linkedlist'. The 'ziplist' is the special representation that is used to save space for small lists.
* Sets can be encoded as 'intset' or 'hashtable'. The 'intset' is a special encoding used for small sets composed solely of integers.
* Hashes can be encoded as 'zipmap' or 'hashtable'. The 'zipmap' is a special encoding used for small hashes.
* Sorted Sets can be encoded as 'ziplist' or 'skiplist' format. As for the List type small sorted sets can be specially encoded using 'ziplist', while the 'skiplist' encoding is the one that works with sorted sets of any size.

All the specially encoded types are automatically converted to the general type once you perform an operation that makes it no possible for Redis to retain the space saving encoding.

@return

Different return values are used for different subcommands.

* Subcommands 'refcount' and 'idletime' returns integers.
* Subcommand 'encoding' returns a bulk reply.

If the object you try to inspect is missing, a null bulk reply is returned.

@examples

    redis> lpush mylist "Hello World"
    (integer) 4
    redis> object refcount mylist
    (integer) 1
    redis> object encoding mylist
    "ziplist"
    redis> object idletime mylist
    (integer) 10

In the following example you can see how the encoding changes once Redis is no longer able to use the space saving encoding.

    redis> set foo 1000
    OK
    redis> object encoding foo
    "int"
    redis> append foo bar
    (integer) 7
    redis> get foo
    "1000bar"
    redis> object encoding foo
    "raw"`},
    "debug object": {"debug object", "Get debugging information about a key", "key", "server", "0.101", `@complexity

@description

@examples

@return`},
    "getrange": {"getrange", "Get a substring of the string stored at a key", "key start end", "string", "1.3.4", `@complexity

O(N) where N is the length of the returned string. The complexity is ultimately
determined by the returned length, but because creating a substring from an
existing string is very cheap, it can be considered O(1) for small strings.

**Warning**: this command was renamed to 'GETRANGE', it is called 'SUBSTR' in Redis versions '<= 2.0'.

Returns the substring of the string value stored at 'key', determined by the
offsets 'start' and 'end' (both are inclusive). Negative offsets can be used in
order to provide an offset starting from the end of the string. So -1 means the
last character, -2 the penultimate and so forth.

The function handles out of range requests by limiting the resulting range to
the actual length of the string.

@return

@bulk-reply

@examples

    @cli
    SET mykey "This is a string"
    GETRANGE mykey 0 3
    GETRANGE mykey -3 -1
    GETRANGE mykey 0 -1
    GETRANGE mykey 10 100`},
    "hset": {"hset", "Set the string value of a hash field", "key field value", "hash", "1.3.10", `@complexity

O(1)


Sets 'field' in the hash stored at 'key' to 'value'. If 'key' does not exist, a
new key holding a hash is created. If 'field' already exists in the hash, it
is overwritten.

@return

@integer-reply, specifically:

* '1' if 'field' is a new field in the hash and 'value' was set.
* '0' if 'field' already exists in the hash and the value was updated.

@examples

    @cli
    HSET myhash field1 "Hello"
    HGET myhash field1`},
    "rpush": {"rpush", "Append one or multiple values to a list", "key value [value ...]", "list", "0.07", `@complexity

O(1)


Insert all the specified values at the tail of the list stored at 'key'.
If 'key' does not exist, it is created as empty list before performing the
push operation.
When 'key' holds a value that is not a list, an error is returned.

It is possible to push multiple elements using a single command call just specifying multiple arguments at the end of the command. Elements are inserted one after the other to the tail of the list, from the leftmost element to the rightmost element. So for instance the command 'RPUSH mylist a b c' will result into a list containing 'a' as first element, 'b' as second element and 'c' as third element.

@return

@integer-reply: the length of the list after the push operation.

@history

* '>= 2.4': Accepts multiple 'value' arguments. In Redis versions older than 2.4 it was possible to push a single value per command.

@examples

    @cli
    RPUSH mylist "hello"
    RPUSH mylist "world"
    LRANGE mylist 0 -1`},
    "quit": {"quit", "Close the connection", "-", "connection", "0.07", `@description

Ask the server to close the connection. The connection is closed as soon as all
pending replies have been written to the client.

@return

@status-reply: always OK.`},
    "lrange": {"lrange", "Get a range of elements from a list", "key start stop", "list", "0.07", `@complexity

O(S+N) where S is the 'start' offset and N is the number of elements in the
specified range.

Returns the specified elements of the list stored at 'key'.  The offsets
'start' and 'stop' are zero-based indexes, with '0' being the first element of
the list (the head of the list), '1' being the next element and so on.

These offsets can also be negative numbers indicating offsets starting at the
end of the list. For example, '-1' is the last element of the list, '-2' the
penultimate, and so on.

## Consistency with range functions in various programming languages

Note that if you have a list of numbers from 0 to 100, 'LRANGE list 0 10' will
return 11 elements, that is, the rightmost item is included. This **may or may
not** be consistent with behavior of range-related functions in your
programming language of choice (think Ruby's 'Range.new', 'Array#slice' or
Python's 'range()' function).

## Out-of-range indexes

Out of range indexes will not produce an error. If 'start' is larger than the
end of the list, an empty list is returned.  If 'stop' is
larger than the actual end of the list, Redis will treat it like the last
element of the list.

@return

@multi-bulk-reply: list of elements in the specified range.

@examples

    @cli
    RPUSH mylist "one"
    RPUSH mylist "two"
    RPUSH mylist "three"
    LRANGE mylist 0 0
    LRANGE mylist -3 2
    LRANGE mylist -100 100
    LRANGE mylist 5 10`},
    "sync": {"sync", "Internal command used for replication", "-", "server", "0.07", `@complexity

@description

@examples

@return`},
    "setnx": {"setnx", "Set the value of a key, only if the key does not exist", "key value", "string", "0.07", `@complexity

O(1)


Set 'key' to hold string 'value' if 'key' does not exist.
In that case, it is equal to 'SET'. When 'key' already holds
a value, no operation is performed.
'SETNX' is short for "**SET** if **N**ot e**X**ists".

@return

@integer-reply, specifically:

* '1' if the key was set
* '0' if the key was not set

@examples

    @cli
    SETNX mykey "Hello"
    SETNX mykey "World"
    GET mykey

## Design pattern: Locking with '!SETNX'

'SETNX' can be used as a locking primitive. For example, to acquire
the lock of the key 'foo', the client could try the following:

    SETNX lock.foo <current Unix time + lock timeout + 1>

If 'SETNX' returns '1' the client acquired the lock, setting the 'lock.foo'
key to the Unix time at which the lock should no longer be considered valid.
The client will later use 'DEL lock.foo' in order to release the lock.

If 'SETNX' returns '0' the key is already locked by some other client. We can
either return to the caller if it's a non blocking lock, or enter a
loop retrying to hold the lock until we succeed or some kind of timeout
expires.

### Handling deadlocks

In the above locking algorithm there is a problem: what happens if a client
fails, crashes, or is otherwise not able to release the lock?
It's possible to detect this condition because the lock key contains a
UNIX timestamp. If such a timestamp is equal to the current Unix time the lock
is no longer valid.

When this happens we can't just call 'DEL' against the key to remove the lock
and then try to issue a 'SETNX', as there is a race condition here, when
multiple clients detected an expired lock and are trying to release it.

* C1 and C2 read 'lock.foo' to check the timestamp, because they both received
  '0' after executing 'SETNX', as the lock is still held by C3 that crashed
  after holding the lock.
* C1 sends 'DEL lock.foo'
* C1 sends 'SETNX lock.foo' and it succeeds
* C2 sends 'DEL lock.foo'
* C2 sends 'SETNX lock.foo' and it succeeds
* **ERROR**: both C1 and C2 acquired the lock because of the race condition.

Fortunately, it's possible to avoid this issue using the following algorithm.
Let's see how C4, our sane client, uses the good algorithm:

* C4 sends 'SETNX lock.foo' in order to acquire the lock
* The crashed client C3 still holds it, so Redis will reply with '0' to C4.
* C4 sends 'GET lock.foo' to check if the lock expired. If it is not, it will
  sleep for some time and retry from the start.
* Instead, if the lock is expired because the Unix time at 'lock.foo' is older
  than the current Unix time, C4 tries to perform:

      GETSET lock.foo <current Unix timestamp + lock timeout + 1>

* Because of the 'GETSET' semantic, C4 can check if the old value stored
  at 'key' is still an expired timestamp. If it is, the lock was acquired.
* If another client, for instance C5, was faster than C4 and acquired
  the lock with the 'GETSET' operation, the C4 'GETSET' operation will return a non
  expired timestamp. C4 will simply restart from the first step. Note that even
  if C4 set the key a bit a few seconds in the future this is not a problem.

**Important note**: In order to make this locking algorithm more robust, a client
holding a lock should always check the timeout didn't expire before unlocking
the key with 'DEL' because client failures can be complex, not just crashing
but also blocking a lot of time against some operations and trying to issue
'DEL' after a lot of time (when the LOCK is already held by another client).`},
    "spop": {"spop", "Remove and return a random member from a set", "key", "set", "0.101", `@complexity

O(1)


Removes and returns a random element from the set value stored at 'key'.

This operation is similar to 'SRANDMEMBER', that returns a random
element from a set but does not remove it.

@return

@bulk-reply: the removed element, or 'nil' when 'key' does not exist.

@examples

    @cli
    SADD myset "one"
    SADD myset "two"
    SADD myset "three"
    SPOP myset
    SMEMBERS myset`},
    "monitor": {"monitor", "Listen for all requests received by the server in real time", "-", "server", "0.07", `'MONITOR' is a debugging command that outputs the whole sequence of commands
received by the Redis server. is very handy in order to understand
what is happening into the database. This command is used directly
via telnet.
    % telnet 127.0.0.1 6379
    Trying 127.0.0.1...
    Connected to segnalo-local.com.
    Escape character is '^]'.
    MONITOR
    +OK
    monitor
    keys *
    dbsize
    set x 6
    foobar
    get x
    del x
    get x
    set key_x 5
    hello
    set key_y 5
    hello
    set key_z 5
    hello
    set foo_a 5
    hello
The ability to see all the requests processed by the server is useful in order
to spot bugs in the application both when using Redis as a database and as
a distributed caching system.

In order to end a monitoring session just issue a 'QUIT' command by hand.

@return

**Non standard return value**, just dumps the received commands in an infinite
flow.`},
    "zinterstore": {"zinterstore", "Intersect multiple sorted sets and store the resulting sorted set in a new key", "destination numkeys key [key ...] [WEIGHTS weight] [AGGREGATE SUM|MIN|MAX]", "sorted_set", "1.3.10", `@complexity

O(N\*K)+O(M\*log(M)) worst case with N being the smallest input sorted set, K
being the number of input sorted sets and M being the number of elements in the
resulting sorted set.

Computes the intersection of 'numkeys' sorted sets given by the specified keys,
and stores the result in 'destination'. It is mandatory to provide the number
of input keys ('numkeys') before passing the input keys and the other
(optional) arguments.

By default, the resulting score of an element is the sum of its scores in the
sorted sets where it exists. Because intersection requires an element
to be a member of every given sorted set, this results in the score of every
element in the resulting sorted set to be equal to the number of input sorted sets.

For a description of the 'WEIGHTS' and 'AGGREGATE' options, see 'ZUNIONSTORE'.

If 'destination' already exists, it is overwritten.

@return

@integer-reply: the number of elements in the resulting sorted set at
'destination'.

@examples

    @cli
    ZADD zset1 1 "one"
    ZADD zset1 2 "two"
    ZADD zset2 1 "one"
    ZADD zset2 2 "two"
    ZADD zset2 3 "three"
    ZINTERSTORE out 2 zset1 zset2 WEIGHTS 2 3
    ZRANGE out 0 -1 WITHSCORES`},
    "get": {"get", "Get the value of a key", "key", "string", "0.07", `@complexity

O(1)


Get the value of 'key'. If the key does not exist the special value 'nil' is returned.
An error is returned if the value stored at 'key' is not a string, because 'GET'
only handles string values.

@return

@bulk-reply: the value of 'key', or 'nil' when 'key' does not exist.

@examples

    @cli
    GET nonexisting
    SET mykey "Hello"
    GET mykey`},
    "zcard": {"zcard", "Get the number of members in a sorted set", "key", "sorted_set", "1.1", `@complexity

O(1)


Returns the sorted set cardinality (number of elements) of the sorted set
stored at 'key'.

@return

@integer-reply: the cardinality (number of elements) of the sorted set, or '0'
if 'key' does not exist.

@examples

    @cli
    ZADD myzset 1 "one"
    ZADD myzset 2 "two"
    ZCARD myzset`},
    "setrange": {"setrange", "Overwrite part of a string at key starting at the specified offset", "key offset value", "string", "2.1.8", `@complexity

O(1), not counting the time taken to copy the new string in place. Usually,
this string is very small so the amortized complexity is O(1). Otherwise,
complexity is O(M) with M being the length of the _value_ argument.

Overwrites part of the string stored at _key_, starting at the specified
offset, for the entire length of _value_. If the offset is larger than the
current length of the string at _key_, the string is padded with zero-bytes to
make _offset_ fit. Non-existing keys are considered as empty strings, so this
command will make sure it holds a string large enough to be able to set _value_
at _offset_.

Note that the maximum offset that you can set is 2^29 -1 (536870911), as Redis
Strings are limited to 512 megabytes. If you need to grow beyond this size, you
can use multiple keys.

**Warning**: When setting the last possible byte and the string value stored at
_key_ does not yet hold a string value, or holds a small string value, Redis
needs to allocate all intermediate memory which can block the server for some
time.  On a 2010 MacBook Pro, setting byte number 536870911 (512MB allocation)
takes ~300ms, setting byte number 134217728 (128MB allocation) takes ~80ms,
setting bit number 33554432 (32MB allocation) takes ~30ms and setting bit
number 8388608 (8MB allocation) takes ~8ms. Note that once this first
allocation is done, subsequent calls to 'SETRANGE' for the same _key_ will not
have the allocation overhead.

## Patterns

Thanks to 'SETRANGE' and the analogous 'GETRANGE' commands, you can use Redis strings
as a linear array with O(1) random access. This is a very fast and
efficient storage in many real world use cases.

@return

@integer-reply: the length of the string after it was modified by the command.

@examples

Basic usage:

    @cli
    SET key1 "Hello World"
    SETRANGE key1 6 "Redis"
    GET key1

Example of zero padding:

    @cli
    SETRANGE key2 6 "Redis"
    GET key2`},
    "flushall": {"flushall", "Remove all keys from all databases", "-", "server", "0.07", `Delete all the keys of all the existing databases, not just the currently selected one. This command never fails.

@return

@status-reply`},
    "sunion": {"sunion", "Add multiple sets", "key [key ...]", "set", "0.091", `@complexity

O(N) where N is the total number of elements in all given sets.

Returns the members of the set resulting from the union of all the
given sets.

For example:

    key1 = {a,b,c,d}
    key2 = {c}
    key3 = {a,c,e}
    SUNION key1 key2 key3 = {a,b,c,d,e}

Keys that do not exist are considered to be empty sets.

@return

@multi-bulk-reply: list with members of the resulting set.

@examples

    @cli
    SADD key1 "a"
    SADD key1 "b"
    SADD key1 "c"
    SADD key2 "c"
    SADD key2 "d"
    SADD key2 "e"
    SUNION key1 key2`},
    "zscore": {"zscore", "Get the score associated with the given member in a sorted set", "key member", "sorted_set", "1.1", `@complexity

O(1)


Returns the score of 'member' in the sorted set at 'key'.

If 'member' does not exist in the sorted set, or 'key' does not exist,
'nil' is returned.

@return

@bulk-reply: the score of 'member' (a double precision floating point number),
represented as string.

@examples

    @cli
    ZADD myzset 1 "one"
    ZSCORE myzset "one"`},
    "multi": {"multi", "Mark the start of a transaction block", "-", "transactions", "1.1.95", `Marks the start of a [transaction](/topics/transactions)
block. Subsequent commands will be queued for atomic execution using
'EXEC'.

@return

@status-reply: always 'OK'.`},
    "hmset": {"hmset", "Set multiple hash fields to multiple values", "key field value [field value ...]", "hash", "1.3.8", `@complexity

O(N) where N is the number of fields being set.

Sets the specified fields to their respective values in the hash
stored at 'key'. This command overwrites any existing fields in the hash.
If 'key' does not exist, a new key holding a hash is created.

@return

@status-reply

@examples

    @cli
    HMSET myhash field1 "Hello" field2 "World"
    HGET myhash field1
    HGET myhash field2`},
    "incrby": {"incrby", "Increment the integer value of a key by the given number", "key increment", "string", "0.07", `@complexity

O(1)


Increments the number stored at 'key' by 'increment'.
If the key does not exist, it is set to '0' before performing the operation. An
error is returned if the key contains a value of the wrong type or contains a
string that is not representable as integer. This operation is limited to 64
bit signed integers.

See 'INCR' for extra information on increment/decrement operations.

@return

@integer-reply: the value of 'key' after the increment

@examples

    @cli
    SET mykey "10"
    INCRBY mykey 5`},
    "hvals": {"hvals", "Get all the values in a hash", "key", "hash", "1.3.10", `@complexity

O(N) where N is the size of the hash.

Returns all values in the hash stored at 'key'.

@return

@multi-bulk-reply: list of values in the hash, or an empty list when 'key' does
not exist.

@examples

    @cli
    HSET myhash field1 "Hello"
    HSET myhash field2 "World"
    HVALS myhash`},
    "config set": {"config set", "Set a configuration parameter to the given value", "parameter value", "server", "2.0", `@complexity

Not applicable.

@description

The 'CONFIG SET' command is used in order to reconfigure the server at runtime
without the need to restart Redis. You can change both trivial parameters or
switch from one to another persistence option using this command.

The list of configuration parameters supported by 'CONFIG SET' can be
obtained issuing a 'CONFIG GET *' command, that is the symmetrical command
used to obtain information about the configuration of a running
Redis instance.

All the configuration parameters set using 'CONFIG SET' are immediately loaded
by Redis that will start acting as specified starting from the next command
executed.

All the supported parameters have the same meaning of the equivalent
configuration parameter used in the [redis.conf](http://github.com/antirez/redis/raw/2.2/redis.conf) file, with the following important differences:

* Where bytes or other quantities are specified, it is not possible to use the redis.conf abbreviated form (10k 2gb ... and so forth), everything should be specified as a well formed 64 bit integer, in the base unit of the configuration directive.
* The save parameter is a single string of space separated integers. Every pair of integers represent a seconds/modifications threshold.

For instance what in redis.conf looks like:

    save 900 1
    save 300 10

that means, save after 900 seconds if there is at least 1 change to the
dataset, and after 300 seconds if there are at least 10 changes to the
datasets, should be set using 'CONFIG SET' as "900 1 300 10".

It is possible to switch persistence form .rdb snapshotting to append only file
(and the other way around) using the 'CONFIG SET' command. For more information
about how to do that please check [persistence page](/topics/persistence).

In general what you should know is that setting the *appendonly* parameter to
*yes* will start a background process to save the initial append only file
(obtained from the in memory data set), and will append all the subsequent
commands on the append only file, thus obtaining exactly the same effect of
a Redis server that started with AOF turned on since the start.

You can have both the AOF enabled with .rdb snapshotting if you want, the
two options are not mutually exclusive.

@return

@status-reply: 'OK' when the configuration was set properly. Otherwise an error is returned.`},
    "shutdown": {"shutdown", "Synchronously save the dataset to disk and then shut down the server", "-", "server", "0.07", `The command behavior is the following:

* Stop all the clients.
* Perform a blocking SAVE if at least one **save point** is configured.
* Flush the Append Only File if AOF is enabled.
* Quit the server.

If persistence is enabled this commands makes sure that Redis is switched
off without the lost of any data. This is not guaranteed if the client uses
simply 'SAVE' and then 'QUIT' because other clients may alter the DB data
between the two commands.

Note: A Redis instance that is configured for not persisting on disk
(no AOF configured, nor "save" directive) will not dump the RDB file on
'SHUTDOWN', as usually you don't want Redis instances used only for caching
to block on when shutting down.

@return

@status-reply on error. On success nothing is returned since the server
quits and the connection is closed.`},
    "exists": {"exists", "Determine if a key exists", "key", "generic", "0.07", `@complexity

O(1)


Returns if 'key' exists.

@return

@integer-reply, specifically:

* '1' if the key exists.
* '0' if the key does not exist.

@examples

    @cli
    SET key1 "Hello"
    EXISTS key1
    EXISTS key2`},
    "mset": {"mset", "Set multiple keys to multiple values", "key value [key value ...]", "string", "1.001", `@complexity

O(N) where N is the number of keys to set


Sets the given keys to their respective values. 'MSET' replaces existing values
with new values, just as regular 'SET'.  See 'MSETNX' if you don't want to
overwrite existing values.

'MSET' is atomic, so all given keys are set at once. It is not possible for
clients to see that some of the keys were updated while others are unchanged.

@return

@status-reply: always 'OK' since 'MSET' can't fail.

@examples

    @cli
    MSET key1 "Hello" key2 "World"
    GET key1
    GET key2`},
    "zunionstore": {"zunionstore", "Add multiple sorted sets and store the resulting sorted set in a new key", "destination numkeys key [key ...] [WEIGHTS weight] [AGGREGATE SUM|MIN|MAX]", "sorted_set", "1.3.10", `@complexity

O(N)+O(M log(M)) with N being the sum of the sizes of the input sorted sets,
and M being the number of elements in the resulting sorted set.

Computes the union of 'numkeys' sorted sets given by the specified keys, and
stores the result in 'destination'. It is mandatory to provide the number of
input keys ('numkeys') before passing the input keys and the other (optional)
arguments.

By default, the resulting score of an element is the sum of its scores in the
sorted sets where it exists.

Using the 'WEIGHTS' option, it is possible to specify a multiplication factor
for each input sorted set. This means that the score of every element in every
input sorted set is multiplied by this factor before being passed to the
aggregation function.  When 'WEIGHTS' is not given, the multiplication factors
default to '1'.

With the 'AGGREGATE' option, it is possible to specify how the results of the
union are aggregated. This option defaults to 'SUM', where the score of an
element is summed across the inputs where it exists. When this option is set to
either 'MIN' or 'MAX', the resulting set will contain the minimum or maximum
score of an element across the inputs where it exists.

If 'destination' already exists, it is overwritten.

@return

@integer-reply: the number of elements in the resulting sorted set at
'destination'.

@examples

    @cli
    ZADD zset1 1 "one"
    ZADD zset1 2 "two"
    ZADD zset2 1 "one"
    ZADD zset2 2 "two"
    ZADD zset2 3 "three"
    ZUNIONSTORE out 2 zset1 zset2 WEIGHTS 2 3
    ZRANGE out 0 -1 WITHSCORES`},
    "expire": {"expire", "Set a key's time to live in seconds", "key seconds", "generic", "0.09", `@complexity

O(1)


Set a timeout on 'key'. After the timeout has expired, the key will
automatically be deleted. A key with an associated timeout is said to be
_volatile_ in Redis terminology.

If 'key' is updated before the timeout has expired, then the timeout is removed
as if the 'PERSIST' command was invoked on 'key'.

For Redis versions **< 2.1.3**, existing timeouts cannot be overwritten. So, if
'key' already has an associated timeout, it will do nothing and return '0'.
Since Redis **2.1.3**, you can update the timeout of a key. It is also possible
to remove the timeout using the 'PERSIST' command. See the page on [key expiry][1]
for more information.

Note that in Redis 2.4 the expire might not be pin-point accurate, and
it could be between zero to one seconds out. Development versions of
Redis fixed this bug and Redis 2.6 will feature a millisecond precision
'EXPIRE'.

[1]: /topics/expire

@return

@integer-reply, specifically:

* '1' if the timeout was set.
* '0' if 'key' does not exist or the timeout could not be set.

@examples

    @cli
    SET mykey "Hello"
    EXPIRE mykey 10
    TTL mykey
    SET mykey "Hello World"
    TTL mykey`},
    "hsetnx": {"hsetnx", "Set the value of a hash field, only if the field does not exist", "key field value", "hash", "1.3.8", `@complexity

O(1)


Sets 'field' in the hash stored at 'key' to 'value', only if 'field' does not
yet exist. If 'key' does not exist, a new key holding a hash is created. If
'field' already exists, this operation has no effect.

@return

@integer-reply, specifically:

* '1' if 'field' is a new field in the hash and 'value' was set.
* '0' if 'field' already exists in the hash and no operation was performed.

@examples

    @cli
    HSETNX myhash field "Hello"
    HSETNX myhash field "World"
    HGET myhash field`},
}