From 339e5130b2f930a5986b8927ad8bb39a261e59ad Mon Sep 17 00:00:00 2001 From: Pieter Noordhuis Date: Mon, 18 Jun 2012 21:20:45 -0700 Subject: [PATCH] Start every sentence on a new line --- commands/append.md | 21 +-- commands/auth.md | 9 +- commands/bgrewriteaof.md | 16 +- commands/bgsave.md | 10 +- commands/bitcount.md | 25 +-- commands/bitop.md | 9 +- commands/blpop.md | 51 ++++--- commands/brpop.md | 9 +- commands/brpoplpush.md | 9 +- commands/config get.md | 17 ++- commands/config set.md | 17 ++- commands/debug object.md | 4 +- commands/debug segfault.md | 4 +- commands/decr.md | 9 +- commands/decrby.md | 9 +- commands/del.md | 3 +- commands/dump.md | 15 +- commands/eval.md | 285 +++++++++++++++++++---------------- commands/expire.md | 82 +++++----- commands/expireat.md | 5 +- commands/flushall.md | 3 +- commands/flushdb.md | 3 +- commands/get.md | 7 +- commands/getbit.md | 7 +- commands/getrange.md | 7 +- commands/getset.md | 9 +- commands/hdel.md | 11 +- commands/hgetall.md | 6 +- commands/hincrby.md | 3 +- commands/hincrbyfloat.md | 8 +- commands/hmset.md | 5 +- commands/hset.md | 6 +- commands/hsetnx.md | 5 +- commands/incr.md | 69 +++++---- commands/incrby.md | 9 +- commands/incrbyfloat.md | 11 +- commands/info.md | 22 +-- commands/keys.md | 17 ++- commands/lastsave.md | 8 +- commands/lindex.md | 11 +- commands/llen.md | 6 +- commands/lpush.md | 22 +-- commands/lpushx.md | 5 +- commands/lrange.md | 29 ++-- commands/lrem.md | 4 +- commands/lset.md | 4 +- commands/ltrim.md | 22 +-- commands/mget.md | 7 +- commands/migrate.md | 25 +-- commands/monitor.md | 17 ++- commands/move.md | 7 +- commands/mset.md | 11 +- commands/msetnx.md | 10 +- commands/multi.md | 4 +- commands/object.md | 35 +++-- commands/ping.md | 5 +- commands/punsubscribe.md | 5 +- commands/quit.md | 5 +- commands/rename.md | 7 +- commands/renamenx.md | 4 +- commands/restore.md | 4 +- commands/rpoplpush.md | 38 ++--- commands/rpush.md | 22 +-- commands/rpushx.md | 5 +- commands/sadd.md | 11 +- commands/save.md | 9 +- commands/script exists.md | 6 +- commands/script kill.md | 13 +- commands/script load.md | 8 +- commands/select.md | 4 +- commands/set.md | 4 +- commands/setbit.md | 27 ++-- commands/setex.md | 10 +- commands/setnx.md | 36 +++-- commands/setrange.md | 31 ++-- commands/shutdown.md | 19 ++- commands/sinter.md | 6 +- commands/slaveof.md | 15 +- commands/slowlog.md | 38 +++-- commands/smove.md | 15 +- commands/sort.md | 78 +++++----- commands/srem.md | 11 +- commands/strlen.md | 4 +- commands/ttl.md | 6 +- commands/type.md | 6 +- commands/unsubscribe.md | 5 +- commands/zadd.md | 17 ++- commands/zincrby.md | 13 +- commands/zinterstore.md | 13 +- commands/zrange.md | 29 ++-- commands/zrangebyscore.md | 23 +-- commands/zrank.md | 5 +- commands/zrem.md | 9 +- commands/zremrangebyrank.md | 12 +- commands/zrevrange.md | 4 +- commands/zrevrangebyscore.md | 6 +- commands/zrevrank.md | 5 +- commands/zunionstore.md | 23 +-- remarkdown.rb | 7 +- 99 files changed, 922 insertions(+), 745 deletions(-) diff --git a/commands/append.md b/commands/append.md index b353b27602..3b673eb0e9 100644 --- a/commands/append.md +++ b/commands/append.md @@ -1,6 +1,7 @@ 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. +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 @@ -17,24 +18,24 @@ string, so `APPEND` will be similar to `SET` in this special case. ## Pattern: Time series the `APPEND` command can be used to create a very compact representation of a -list of fixed-size samples, usually referred as _time series_. Every time a new -sample arrives we can store it using the command +list of fixed-size samples, usually referred as _time series_. +Every time a new sample arrives we can store it using the command APPEND timeseries "fixed-size sample" Accessing individual elements in the time series is not hard: * `STRLEN` can be used in order to obtain the number of samples. -* `GETRANGE` allows for random access of elements. If our time series have an - associated time information we can easily implement a binary search to get - range combining `GETRANGE` with the Lua scripting engine available in Redis - 2.6. +* `GETRANGE` allows for random access of elements. + If our time series have an associated time information we can easily implement + a binary search to get range combining `GETRANGE` with the Lua scripting + engine available in Redis 2.6. * `SETRANGE` can be used to overwrite an existing time serie. The limitations of this pattern is that we are forced into an append-only mode of operation, there is no way to cut the time series to a given size easily -because Redis currently lacks a command able to trim string objects. However the -space efficiency of time series stored in this way is remarkable. +because Redis currently lacks a command able to trim string objects. +However the space efficiency of time series stored in this way is remarkable. Hint: it is possible to switch to a different key based on the current Unix time, in this way it is possible to have just a relatively small amount of diff --git a/commands/auth.md b/commands/auth.md index 661ecd8016..63d185dbf6 100644 --- a/commands/auth.md +++ b/commands/auth.md @@ -1,10 +1,11 @@ -Request for authentication in a password protected Redis server. Redis can be -instructed to require a password before allowing clients to execute commands. +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. +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 diff --git a/commands/bgrewriteaof.md b/commands/bgrewriteaof.md index c69a801e6f..c9b73882b1 100644 --- a/commands/bgrewriteaof.md +++ b/commands/bgrewriteaof.md @@ -1,18 +1,22 @@ -Instruct Redis to start an [Append Only File][tpaof] rewrite process. The -rewrite will create a small optimized version of the current Append Only File. +Instruct Redis to start an [Append Only File][tpaof] rewrite process. +The rewrite will create a small optimized version of the current Append Only +File. [tpaof]: /topics/persistence#append-only-file If `BGREWRITEAOF` fails, no data gets lost as the old AOF will be untouched. The rewrite will be only triggered by Redis if there is not already a background -process doing persistence. Specifically: +process doing persistence. +Specifically: * If a Redis child is creating a snapshot on disk, the AOF rewrite is _scheduled_ but not started until the saving child producing the RDB file - terminates. In this case the `BGREWRITEAOF` will still return an OK code, but - with an appropriate message. You can check if an AOF rewrite is scheduled - looking at the `INFO` command starting from Redis 2.6. + terminates. + In this case the `BGREWRITEAOF` will still return an OK code, but with an + appropriate message. + You can check if an AOF rewrite is scheduled looking at the `INFO` command + starting from Redis 2.6. * If an AOF rewrite is already in progress the command returns an error and no AOF rewrite will be scheduled for a later time. diff --git a/commands/bgsave.md b/commands/bgsave.md index 25a5f1f696..7a65e2e3b7 100644 --- a/commands/bgsave.md +++ b/commands/bgsave.md @@ -1,7 +1,9 @@ -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. +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. Please refer to the [persistence documentation][tp] for detailed information. diff --git a/commands/bitcount.md b/commands/bitcount.md index 1d193cafc8..fdac855364 100644 --- a/commands/bitcount.md +++ b/commands/bitcount.md @@ -1,8 +1,8 @@ Count the number of set bits (population counting) in a string. -By default all the bytes contained in the string are examined. It is possible -to specify the counting operation only in an interval passing the additional -arguments _start_ and _end_. +By default all the bytes contained in the string are examined. +It is possible to specify the counting operation only in an interval passing the +additional arguments _start_ and _end_. Like for the `GETRANGE` command start and end can contain negative values in order to index bytes starting from the end of the string, where -1 is the last @@ -27,13 +27,15 @@ The number of bits set to 1. ## Pattern: real time metrics using bitmaps Bitmaps are a very space efficient representation of certain kinds of -information. One example is a web application that needs the history of user -visits, so that for instance it is possible to determine what users are good -targets of beta features, or for any other purpose. +information. +One example is a web application that needs the history of user visits, so that +for instance it is possible to determine what users are good targets of beta +features, or for any other purpose. -Using the `SETBIT` command this is trivial to accomplish, identifying every -day with a small progressive integer. For instance day 0 is the first day the -application was put online, day 1 the next day, and so forth. +Using the `SETBIT` command this is trivial to accomplish, identifying every day +with a small progressive integer. +For instance day 0 is the first day the application was put online, day 1 the +next day, and so forth. Every time an user performs a page view, the application can register that in the current day the user visited the web site using the `SETBIT` command setting @@ -52,8 +54,9 @@ bitmaps][hbgc212fermurb]". In the above example of counting days, even after 10 years the application is online we still have just `365*10` bits of data per user, that is just 456 bytes -per user. With this amount of data `BITCOUNT` is still as fast as any other O(1) -Redis command like `GET` or `INCR`. +per user. +With this amount of data `BITCOUNT` is still as fast as any other O(1) Redis +command like `GET` or `INCR`. When the bitmap is big, there are two alternatives: diff --git a/commands/bitop.md b/commands/bitop.md index b9e5f3a9f9..948cce7856 100644 --- a/commands/bitop.md +++ b/commands/bitop.md @@ -41,8 +41,9 @@ size of the longest input string. ## Pattern: real time metrics using bitmaps `BITOP` is a good complement to the pattern documented in the `BITCOUNT` command -documentation. Different bitmaps can be combined in order to obtain a target -bitmap where to perform the population counting operation. +documentation. +Different bitmaps can be combined in order to obtain a target bitmap where to +perform the population counting operation. See the article called "[Fast easy realtime metrics using Redis bitmaps][hbgc212fermurb]" for an interesting use cases. @@ -51,8 +52,8 @@ bitmaps][hbgc212fermurb]" for an interesting use cases. ## Performance considerations -`BITOP` is a potentially slow command as it runs in O(N) time. Care should be -taken when running it against long input strings. +`BITOP` is a potentially slow command as it runs in O(N) time. +Care should be taken when running it against long input strings. For real time metrics and statistics involving large inputs a good approach is to use a slave (with read-only option disabled) where to perform the bit-wise diff --git a/commands/blpop.md b/commands/blpop.md index c500782eee..24ed8f24ec 100644 --- a/commands/blpop.md +++ b/commands/blpop.md @@ -1,7 +1,8 @@ -`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. +`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 @@ -9,9 +10,10 @@ 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: +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 @@ -32,27 +34,29 @@ 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. +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. +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. +`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 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 @@ -76,11 +80,12 @@ infinite speed inside a `MULTI` / `EXEC` block. ## Pattern: Event notification Using blocking list operations it is possible to mount different blocking -primitives. For instance for some application you may need to block waiting for -elements into a Redis Set, so that as far as a new element is added to the Set, -it is possible to retrieve it without resort to polling. This would require -a blocking version of `SPOP` that is not available, but using blocking list -operations we can easily accomplish this task. +primitives. +For instance for some application you may need to block waiting for elements +into a Redis Set, so that as far as a new element is added to the Set, it is +possible to retrieve it without resort to polling. +This would require a blocking version of `SPOP` that is not available, but using +blocking list operations we can easily accomplish this task. The consumer will do: diff --git a/commands/brpop.md b/commands/brpop.md index da44a3ae4e..fffc65fc55 100644 --- a/commands/brpop.md +++ b/commands/brpop.md @@ -1,7 +1,8 @@ -`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. +`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 the [BLPOP documentation][cb] for the exact semantics, since `BRPOP` is identical to `BLPOP` with the only difference being that it pops elements from diff --git a/commands/brpoplpush.md b/commands/brpoplpush.md index 73b726db62..025dc3749c 100644 --- a/commands/brpoplpush.md +++ b/commands/brpoplpush.md @@ -1,7 +1,8 @@ -`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. +`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. diff --git a/commands/config get.md b/commands/config get.md index 588d46fd76..c35cd8af1f 100644 --- a/commands/config get.md +++ b/commands/config get.md @@ -1,14 +1,15 @@ The `CONFIG GET` command is used to read the configuration parameters of a -running Redis server. Not all the configuration parameters are supported in -Redis 2.4, while Redis 2.6 can read the whole configuration of a server using -this command. +running Redis server. +Not all the configuration parameters are supported in Redis 2.4, while Redis 2.6 +can read the whole configuration of a server using this command. 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: +`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" @@ -31,8 +32,8 @@ following important differences: 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. +* 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: diff --git a/commands/config set.md b/commands/config set.md index 084c88aabc..dc845853c7 100644 --- a/commands/config set.md +++ b/commands/config set.md @@ -1,6 +1,7 @@ The `CONFIG SET` command is used in order to reconfigure the server at run time -without the need to restart Redis. You can change both trivial parameters or -switch from one to another persistence option using this command. +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 @@ -20,8 +21,8 @@ following important differences: 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. +* 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: @@ -33,8 +34,8 @@ 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 from 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][tp]. +(and the other way around) using the `CONFIG SET` command. +For more information about how to do that please check [persistence page][tp]. [tp]: /topics/persistence @@ -49,5 +50,5 @@ options are not mutually exclusive. @return -@status-reply: `OK` when the configuration was set properly. Otherwise an error -is returned. +@status-reply: `OK` when the configuration was set properly. +Otherwise an error is returned. diff --git a/commands/debug object.md b/commands/debug object.md index 4d3cf6de22..ffc969d8ab 100644 --- a/commands/debug object.md +++ b/commands/debug object.md @@ -1,4 +1,4 @@ -`DEBUG OBJECT` is a debugging command that should not be used by clients. Check -the `OBJECT` command instead. +`DEBUG OBJECT` is a debugging command that should not be used by clients. +Check the `OBJECT` command instead. @status-reply diff --git a/commands/debug segfault.md b/commands/debug segfault.md index c01d06a38c..7524c166f2 100644 --- a/commands/debug segfault.md +++ b/commands/debug segfault.md @@ -1,4 +1,4 @@ -`DEBUG SEGFAULT` performs an invalid memory access that crashes Redis. It is -used to simulate bugs during the development. +`DEBUG SEGFAULT` performs an invalid memory access that crashes Redis. +It is used to simulate bugs during the development. @status-reply diff --git a/commands/decr.md b/commands/decr.md index 038ba06b56..875d553b15 100644 --- a/commands/decr.md +++ b/commands/decr.md @@ -1,7 +1,8 @@ -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 can not be -represented as integer. This operation is limited to **64 bit signed integers**. +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 can not be represented as integer. +This operation is limited to **64 bit signed integers**. See `INCR` for extra information on increment/decrement operations. diff --git a/commands/decrby.md b/commands/decrby.md index 16a77dc814..d2493dc9d0 100644 --- a/commands/decrby.md +++ b/commands/decrby.md @@ -1,7 +1,8 @@ -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 can not be -represented as integer. This operation is limited to 64 bit signed integers. +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 can not be represented as integer. +This operation is limited to 64 bit signed integers. See `INCR` for extra information on increment/decrement operations. diff --git a/commands/del.md b/commands/del.md index 6d20c0c314..c37b3f3e1d 100644 --- a/commands/del.md +++ b/commands/del.md @@ -1,4 +1,5 @@ -Removes the specified keys. A key is ignored if it does not exist. +Removes the specified keys. +A key is ignored if it does not exist. @return diff --git a/commands/dump.md b/commands/dump.md index 58ec12a22e..fd92bb9bd6 100644 --- a/commands/dump.md +++ b/commands/dump.md @@ -1,20 +1,23 @@ Serialize the value stored at key in a Redis-specific format and return it to -the user. The returned value can be synthesized back into a Redis key using the -`RESTORE` command. +the user. +The returned value can be synthesized back into a Redis key using the `RESTORE` +command. The serialization format is opaque and non-standard, however it has a few semantical characteristics: * It contains a 64bit checksum that is used to make sure errors will be - detected. The `RESTORE` command makes sure to check the checksum before - synthesizing a key using the serialized value. + detected. + The `RESTORE` command makes sure to check the checksum before synthesizing a + key using the serialized value. * Values are encoded in the same format used by RDB. * An RDB version is encoded inside the serialized value, so that different Redis versions with incompatible RDB formats will refuse to process the serialized value. -The serialized value does NOT contain expire information. In order to capture -the time to live of the current value the `PTTL` command should be used. +The serialized value does NOT contain expire information. +In order to capture the time to live of the current value the `PTTL` command +should be used. If `key` does not exist a nil bulk reply is returned. diff --git a/commands/eval.md b/commands/eval.md index 277e46cf4e..602c30df6e 100644 --- a/commands/eval.md +++ b/commands/eval.md @@ -3,14 +3,14 @@ `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` is a Lua 5.1 script. The script does not need to -define a Lua function (and should not). It is just a Lua program that will run -in the context of the Redis server. +The first argument of `EVAL` is a Lua 5.1 script. +The script does not need to define a Lua function (and should not). +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 the -script (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]`, ...). +The second argument of `EVAL` is the number of arguments that follows the script +(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 should not represent key names and can be accessed by Lua using the `ARGV` global variable, very similarly to what happens with @@ -46,9 +46,9 @@ the arguments of a well formed Redis command: > eval "return redis.call('set','foo','bar')" 0 OK -The above script actually sets 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: +The above script actually sets 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 @@ -57,11 +57,12 @@ 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). However this rule is not enforced in order to provide the user with +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). +However this rule is not enforced in order to provide the user with opportunities to abuse the Redis single instance configuration, at the cost of writing scripts not compatible with Redis Cluster. @@ -71,16 +72,17 @@ 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 protocol when a Lua script returns some value, so that scripts can control -what `EVAL` will reply to the client. +command using call() or pcall(). +Similarly Lua data types are converted into Redis protocol when a Lua script +returns some value, so that scripts can control what `EVAL` will reply to the +client. 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: +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. @@ -125,17 +127,17 @@ 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`. From the point of view of all the -other clients the effects of a script are either still not visible or already -completed. +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`. +From the point of view of all the other clients the effects of a script are +either still not visible or already completed. -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. +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 @@ -157,10 +159,10 @@ object returned by `redis.pcall()`. ## Bandwidth and EVALSHA -The `EVAL` command forces you to send the script body again and again. Redis -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 many contexts. +The `EVAL` command forces you to send the script body again and again. +Redis 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 many contexts. On the other hand defining commands using a special command or via `redis.conf` would be a problem for a few reasons: @@ -177,7 +179,8 @@ 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: +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. @@ -198,8 +201,8 @@ Example: 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. +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 @@ -207,64 +210,74 @@ 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. +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 _completely flush_ the scripts cache removing all the scripts -executed so far. This is usually needed only when the instance is going to be -instantiated for another customer or application in a cloud environment. +executed so far. +This is usually needed only when the instance is going to be instantiated for +another customer or application 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. +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 -chance that an error will be generated since the script is not known (we'll see -this problem in its details later). +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 chance 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), without the need to actually execute the script. - -* 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. +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), without the need to actually execute the script. + +* 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 +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 bandwidth for the replication link or the Append Only File (and also too much CPU since dispatching a command received via network @@ -275,10 +288,11 @@ 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 (non explicit) 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. + arguments given the same input data set. + Operations performed by the script cannot depend on any hidden (non explicit) + 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 @@ -291,29 +305,31 @@ In order to enforce this behavior in scripts Redis does the following: * 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`, `SRANDMEMBER`, `TIME`. This means that if a script is read only - and does not modify the data set it is free to call those commands. Note that - a _random command_ does not necessarily identifies a command that uses random - numbers: any non deterministic command is considered a random command (the - best example in this regard is the `TIME` command). + `RANDOMKEY`, `SRANDMEMBER`, `TIME`. + This means that if a script is read only and does not modify the data set it + is free to call those commands. + Note that a _random command_ does not necessarily identifies a command that + uses random numbers: any non deterministic command is considered a random + command (the best example in this regard is the `TIME` command). * Redis commands that may return elements in random order, like `SMEMBERS` (because Redis Sets are _unordered_) have a different behavior when called from Lua, and undergone a silent lexicographical sorting filter before - returning data to Lua scripts. So `redis.call("smembers",KEYS[1])` will always - return the Set elements in the same order, while the same command invoked from - normal clients may return different results even if the key contains exactly - the same elements. + returning data to Lua scripts. + So `redis.call("smembers",KEYS[1])` will always return the Set elements in + the same order, while the same command invoked from normal clients may return + different results even if the key contains exactly the same elements. * 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. + 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. Imagine I want to write a Redis script that will -populate a list with N random integers. +However the user is still able to write commands with random behaviors using the +following simple trick. +Imagine 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: @@ -353,7 +369,8 @@ following elements: In order to make it a pure function, but still making sure that every invocation of the script will result in different random elements, we can simply add an additional argument to the script, that will be used in order to seed the Lua -pseudo random number generator. The new script will be like the following: +pseudo random number generator. +The new script will be like the following: RandomPushScript = <= 2.4`: Accepts multiple `field` arguments. Redis versions older than 2.4 - can only remove a field per call. +* `>= 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. diff --git a/commands/hgetall.md b/commands/hgetall.md index 6a858f0035..84ea9a3604 100644 --- a/commands/hgetall.md +++ b/commands/hgetall.md @@ -1,6 +1,6 @@ -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. +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 diff --git a/commands/hincrby.md b/commands/hincrby.md index 75c49aab02..22a4124060 100644 --- a/commands/hincrby.md +++ b/commands/hincrby.md @@ -1,5 +1,6 @@ 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. +`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. diff --git a/commands/hincrbyfloat.md b/commands/hincrbyfloat.md index b80f7b619d..cd86669750 100644 --- a/commands/hincrbyfloat.md +++ b/commands/hincrbyfloat.md @@ -1,7 +1,7 @@ -Increment the specified `field` of an hash stored at `key`, and representing -a floating point number, by the specified `increment`. If the field does not -exist, it is set to `0` before performing the operation. An error is returned if -one of the following conditions occur: +Increment the specified `field` of an hash stored at `key`, and representing a +floating point number, by the specified `increment`. +If the field does not exist, it is set to `0` before performing the operation. +An error is returned if one of the following conditions occur: * The field contains a value of the wrong type (not a string). * The current field content or the specified increment are not parsable as a diff --git a/commands/hmset.md b/commands/hmset.md index fba775cfaa..9444092e6a 100644 --- a/commands/hmset.md +++ b/commands/hmset.md @@ -1,6 +1,7 @@ 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. +`key`. +This command overwrites any existing fields in the hash. +If `key` does not exist, a new key holding a hash is created. @return diff --git a/commands/hset.md b/commands/hset.md index cfe15ef113..8a2c299dbd 100644 --- a/commands/hset.md +++ b/commands/hset.md @@ -1,6 +1,6 @@ -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. +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 diff --git a/commands/hsetnx.md b/commands/hsetnx.md index 49e98781e4..b24200370b 100644 --- a/commands/hsetnx.md +++ b/commands/hsetnx.md @@ -1,6 +1,7 @@ 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. +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 diff --git a/commands/incr.md b/commands/incr.md index feefe6fcfa..f59b0d6088 100644 --- a/commands/incr.md +++ b/commands/incr.md @@ -1,11 +1,13 @@ -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 can not be -represented as integer. This operation is limited to 64 bit signed integers. +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 can not be represented 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. +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 @@ -25,9 +27,11 @@ representation of the integer. ## Pattern: Counter The counter pattern is the most obvious thing you can do with Redis atomic -increment operations. The idea is simply send an `INCR` command to Redis every -time an operation occurs. For instance in a web application we may want to know -how many page views this user did every day of the year. +increment operations. +The idea is simply send an `INCR` command to Redis every time an operation +occurs. +For instance in a web application we may want to know how many page views this +user did every day of the year. To do so the web application may simply increment a key every time the user performs a page view, creating the key name concatenating the User ID and a @@ -42,15 +46,15 @@ This simple pattern can be extended in many ways: and reset it to zero. * Using other atomic increment/decrement commands like `DECR` or `INCRBY` it is possible to handle values that may get bigger or smaller depending on the - operations performed by the user. Imagine for instance the score of different - users in an online game. + operations performed by the user. + Imagine for instance the score of different users in an online game. ## Pattern: Rate limiter -The rate limiter pattern is a special counter that is used to limit the rate -at which an operation can be performed. The classical materialization of this -pattern involves limiting the number of requests that can be performed against a -public API. +The rate limiter pattern is a special counter that is used to limit the rate at +which an operation can be performed. +The classical materialization of this pattern involves limiting the number of +requests that can be performed against a public API. We provide two implementations of this pattern using `INCR`, where we assume that the problem to solve is limiting the number of API calls to a maximum of @@ -74,9 +78,10 @@ The more simple and direct implementation of this pattern is the following: PERFORM_API_CALL() END -Basically we have a counter for every IP, for every different second. But this -counters are always incremented setting an expire of 10 seconds so that they'll -be removed by Redis automatically when the current second is a different one. +Basically we have a counter for every IP, for every different second. +But this counters are always incremented setting an expire of 10 seconds so that +they'll be removed by Redis automatically when the current second is a different +one. Note the used of `MULTI` and `EXEC` in order to make sure that we'll both increment and set the expire at every API call. @@ -84,7 +89,8 @@ increment and set the expire at every API call. ## Pattern: Rate limiter 2 An alternative implementation uses a single counter, but is a bit more complex -to get it right without race conditions. We'll examine different variants. +to get it right without race conditions. +We'll examine different variants. FUNCTION LIMIT_API_CALL(ip): current = GET(ip) @@ -99,13 +105,13 @@ to get it right without race conditions. We'll examine different variants. END The counter is created in a way that it only will survive one second, starting -from the first request performed in the current second. If there are more than -10 requests in the same second the counter will reach a value greater than 10, -otherwise it will expire and start again from 0. +from the first request performed in the current second. +If there are more than 10 requests in the same second the counter will reach a +value greater than 10, otherwise it will expire and start again from 0. -**In the above code there is a race condition**. If for some reason the client -performs the `INCR` command but does not perform the `EXPIRE` the key will be -leaked until we'll see the same IP address again. +**In the above code there is a race condition**. +If for some reason the client performs the `INCR` command but does not perform +the `EXPIRE` the key will be leaked until we'll see the same IP address again. This can be fixed easily turning the `INCR` with optional `EXPIRE` into a Lua script that is send using the `EVAL` command (only available since Redis version @@ -118,10 +124,10 @@ script that is send using the `EVAL` command (only available since Redis version end There is a different way to fix this issue without using scripting, but using -Redis lists instead of counters. The implementation is more complex and uses -more advanced features but has the advantage of remembering the IP addresses -of the clients currently performing an API call, that may be useful or not -depending on the application. +Redis lists instead of counters. +The implementation is more complex and uses more advanced features but has the +advantage of remembering the IP addresses of the clients currently performing an +API call, that may be useful or not depending on the application. FUNCTION LIMIT_API_CALL(ip) current = LLEN(ip) @@ -143,5 +149,6 @@ The `RPUSHX` command only pushes the element if the key already exists. Note that we have a race here, but it is not a problem: `EXISTS` may return false but the key may be created by another client before we create it inside -the `MULTI` / `EXEC` block. However this race will just miss an API call under -rare conditions, so the rate limiting will still work correctly. +the `MULTI` / `EXEC` block. +However this race will just miss an API call under rare conditions, so the rate +limiting will still work correctly. diff --git a/commands/incrby.md b/commands/incrby.md index e60e45fe9d..8f4d049023 100644 --- a/commands/incrby.md +++ b/commands/incrby.md @@ -1,7 +1,8 @@ -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 can not be -represented as integer. This operation is limited to 64 bit signed integers. +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 can not be represented as integer. +This operation is limited to 64 bit signed integers. See `INCR` for extra information on increment/decrement operations. diff --git a/commands/incrbyfloat.md b/commands/incrbyfloat.md index 8dcea20f13..cfe606a741 100644 --- a/commands/incrbyfloat.md +++ b/commands/incrbyfloat.md @@ -1,7 +1,7 @@ -Increment the string representing a floating point number stored at `key` -by the specified `increment`. If the key does not exist, it is set to `0` -before performing the operation. An error is returned if one of the following -conditions occur: +Increment the string representing a floating point number stored at `key` by the +specified `increment`. +If the key does not exist, it is set to `0` before performing the operation. +An error is returned if one of the following conditions occur: * The key contains a value of the wrong type (not a string). * The current key content or the specified increment are not parsable as a @@ -15,7 +15,8 @@ Both the value already contained in the string key and the increment argument can be optionally provided in exponential notation, however the value computed after the increment is stored consistently in the same format, that is, an integer number followed (if needed) by a dot, and a variable number of digits -representing the decimal part of the number. Trailing zeroes are always removed. +representing the decimal part of the number. +Trailing zeroes are always removed. The precision of the output is fixed at 17 digits after the decimal point regardless of the actual internal precision of the computation. diff --git a/commands/info.md b/commands/info.md index a1b6fffe66..1b65229439 100644 --- a/commands/info.md +++ b/commands/info.md @@ -27,20 +27,24 @@ All the fields are in the form of `field:value` terminated by `\r\n`. as [`tcmalloc`][hcgcpgp] * `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`. + 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. + certain size (up to 256). + This provides a means of introspection for the type of allocations performed + by Redis at run time. [hcgcpgp]: http://code.google.com/p/google-perftools/ diff --git a/commands/keys.md b/commands/keys.md index 8499438d3a..ef31b7bd86 100644 --- a/commands/keys.md +++ b/commands/keys.md @@ -1,15 +1,18 @@ 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. +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][tdts]. +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][tdts]. [tdts]: /topics/data-types#sets diff --git a/commands/lastsave.md b/commands/lastsave.md index 93c5cbcce5..cfec6253ab 100644 --- a/commands/lastsave.md +++ b/commands/lastsave.md @@ -1,7 +1,7 @@ -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 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 diff --git a/commands/lindex.md b/commands/lindex.md index c9bd85ccc3..c96ccfde64 100644 --- a/commands/lindex.md +++ b/commands/lindex.md @@ -1,8 +1,9 @@ -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. +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. diff --git a/commands/llen.md b/commands/llen.md index b4d7e16319..a41f2ae6a9 100644 --- a/commands/llen.md +++ b/commands/llen.md @@ -1,6 +1,6 @@ -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. +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 diff --git a/commands/lpush.md b/commands/lpush.md index f4125de5e4..e29b151417 100644 --- a/commands/lpush.md +++ b/commands/lpush.md @@ -1,13 +1,14 @@ -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. +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. +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 @@ -15,8 +16,9 @@ third element. @history -* `>= 2.4`: Accepts multiple `value` arguments. In Redis versions older than 2.4 - it was possible to push a single value per command. +* `>= 2.4`: Accepts multiple `value` arguments. + In Redis versions older than 2.4 it was possible to push a single value per + command. @examples diff --git a/commands/lpushx.md b/commands/lpushx.md index 22da91e651..8376b5de40 100644 --- a/commands/lpushx.md +++ b/commands/lpushx.md @@ -1,6 +1,7 @@ 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. +exists and holds a list. +In contrary to `LPUSH`, no operation will be performed when `key` does not yet +exist. @return diff --git a/commands/lrange.md b/commands/lrange.md index 9a6f9c9a85..25936d567f 100644 --- a/commands/lrange.md +++ b/commands/lrange.md @@ -1,24 +1,27 @@ -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. +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. +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). +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. +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 diff --git a/commands/lrem.md b/commands/lrem.md index baa2328857..4fd9b50efc 100644 --- a/commands/lrem.md +++ b/commands/lrem.md @@ -1,6 +1,6 @@ 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: +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. diff --git a/commands/lset.md b/commands/lset.md index 12fa6e7621..6a4703f416 100644 --- a/commands/lset.md +++ b/commands/lset.md @@ -1,5 +1,5 @@ -Sets the list element at `index` to `value`. For more information on the `index` -argument, see `LINDEX`. +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. diff --git a/commands/ltrim.md b/commands/ltrim.md index 08b8f87d40..45c6accf75 100644 --- a/commands/ltrim.md +++ b/commands/ltrim.md @@ -1,6 +1,7 @@ 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. +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. @@ -11,19 +12,22 @@ 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. +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: +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. +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 diff --git a/commands/mget.md b/commands/mget.md index eda675894e..fb9c79d286 100644 --- a/commands/mget.md +++ b/commands/mget.md @@ -1,6 +1,7 @@ -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. +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 diff --git a/commands/migrate.md b/commands/migrate.md index 7c48941885..69736e1f21 100644 --- a/commands/migrate.md +++ b/commands/migrate.md @@ -1,27 +1,28 @@ Atomically transfer a key from a source Redis instance to a destination Redis -instance. On success the key is deleted from the original instance and is -guaranteed to exist in the target instance. +instance. +On success the key is deleted from the original instance and is guaranteed to +exist in the target instance. The command is atomic and blocks the two instances for the time required to transfer the key, at any given time the key will appear to exist in a given instance or in the other instance, unless a timeout error occurs. The command internally uses `DUMP` to generate the serialized version of the key -value, and `RESTORE` in order to synthesize the key in the target instance. The -source instance acts as a client for the target instance. If the target instance -returns OK to the `RESTORE` command, the source instance deletes the key using -`DEL`. +value, and `RESTORE` in order to synthesize the key in the target instance. +The source instance acts as a client for the target instance. +If the target instance returns OK to the `RESTORE` command, the source instance +deletes the key using `DEL`. The timeout specifies the maximum idle time in any moment of the communication -with the destination instance in milliseconds. This means that the operation -does not need to be completed within the specified amount of milliseconds, but -that the transfer should make progresses without blocking for more than the -specified amount of milliseconds. +with the destination instance in milliseconds. +This means that the operation does not need to be completed within the specified +amount of milliseconds, but that the transfer should make progresses without +blocking for more than the specified amount of milliseconds. `MIGRATE` needs to perform I/O operations and to honor the specified timeout. When there is an I/O error during the transfer or if the timeout is reached the -operation is aborted and the special error - `IOERR` returned. When this happens -the following two cases are possible: +operation is aborted and the special error - `IOERR` returned. +When this happens the following two cases are possible: * The key may be on both the instances. * The key may be only in the source instance. diff --git a/commands/monitor.md b/commands/monitor.md index 93ebd1af0a..3bd2b1c29e 100644 --- a/commands/monitor.md +++ b/commands/monitor.md @@ -1,6 +1,7 @@ -`MONITOR` is a debugging command that streams back every command processed -by the Redis server. It can help in understanding what is happening to the -database. This command can both be used via `redis-cli` and via `telnet`. +`MONITOR` is a debugging command that streams back every command processed by +the Redis server. +It can help in understanding what is happening to the database. +This command can both be used via `redis-cli` and via `telnet`. The ability to see all the requests processed by the server is useful in order to spot bugs in an application both when using Redis as a database and as a @@ -37,9 +38,9 @@ Manually issue the `QUIT` command to stop a `MONITOR` stream running via ## Cost of running `MONITOR` -Because `MONITOR` streams back **all** commands, its use comes at a cost. The -following (totally unscientific) benchmark numbers illustrate what the cost of -running `MONITOR` can be. +Because `MONITOR` streams back **all** commands, its use comes at a cost. +The following (totally unscientific) benchmark numbers illustrate what the cost +of running `MONITOR` can be. Benchmark result **without** `MONITOR` running: @@ -60,8 +61,8 @@ Benchmark result **with** `MONITOR` running (`redis-cli monitor > /dev/null`): INCR: 41771.09 requests per second In this particular case, running a single `MONITOR` client can reduce the -throughput by more than 50%. Running more `MONITOR` clients will reduce -throughput even more. +throughput by more than 50%. +Running more `MONITOR` clients will reduce throughput even more. @return diff --git a/commands/move.md b/commands/move.md index f63a045bdb..ceb212caac 100644 --- a/commands/move.md +++ b/commands/move.md @@ -1,7 +1,8 @@ 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. +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 diff --git a/commands/mset.md b/commands/mset.md index 4a45c03637..76e81d959a 100644 --- a/commands/mset.md +++ b/commands/mset.md @@ -1,9 +1,10 @@ -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. +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. +`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 diff --git a/commands/msetnx.md b/commands/msetnx.md index e9b656bcfb..1b1c060b0f 100644 --- a/commands/msetnx.md +++ b/commands/msetnx.md @@ -1,12 +1,14 @@ -Sets the given keys to their respective values. `MSETNX` will not perform any -operation at all even if just a single key already exists. +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. +`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 diff --git a/commands/multi.md b/commands/multi.md index f6c69be303..437a3e1f93 100644 --- a/commands/multi.md +++ b/commands/multi.md @@ -1,5 +1,5 @@ -Marks the start of a [transaction][tt] block. Subsequent commands will be queued -for atomic execution using `EXEC`. +Marks the start of a [transaction][tt] block. +Subsequent commands will be queued for atomic execution using `EXEC`. [tt]: /topics/transactions diff --git a/commands/object.md b/commands/object.md index 35379b01bc..a560dbefd0 100644 --- a/commands/object.md +++ b/commands/object.md @@ -1,14 +1,16 @@ 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. +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 ` returns the number of references of the value - associated with the specified key. This command is mainly useful for - debugging. + associated with the specified key. + This command is mainly useful for debugging. * `OBJECT ENCODING ` returns the kind of internal representation used in order to store the value associated with a key. * `OBJECT IDLETIME ` returns the number of seconds since the object stored @@ -21,15 +23,18 @@ 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. +* 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 diff --git a/commands/ping.md b/commands/ping.md index f80ca6a931..f2405ce93d 100644 --- a/commands/ping.md +++ b/commands/ping.md @@ -1,5 +1,6 @@ -Returns `PONG`. This command is often used to test if a connection is still -alive, or to measure latency. +Returns `PONG`. +This command is often used to test if a connection is still alive, or to measure +latency. @return diff --git a/commands/punsubscribe.md b/commands/punsubscribe.md index 449fddcfec..2dffcd53cd 100644 --- a/commands/punsubscribe.md +++ b/commands/punsubscribe.md @@ -2,5 +2,6 @@ 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. +previously subscribed patterns. +In this case, a message for every unsubscribed pattern will be sent to the +client. diff --git a/commands/quit.md b/commands/quit.md index f36b86a1ce..9ade700edc 100644 --- a/commands/quit.md +++ b/commands/quit.md @@ -1,5 +1,6 @@ -Ask the server to close the connection. The connection is closed as soon as all -pending replies have been written to the client. +Ask the server to close the connection. +The connection is closed as soon as all pending replies have been written to the +client. @return diff --git a/commands/rename.md b/commands/rename.md index 1dd586018a..0f80d67b81 100644 --- a/commands/rename.md +++ b/commands/rename.md @@ -1,6 +1,7 @@ -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. +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 diff --git a/commands/renamenx.md b/commands/renamenx.md index 1128bf6757..737c9dfdf0 100644 --- a/commands/renamenx.md +++ b/commands/renamenx.md @@ -1,5 +1,5 @@ -Renames `key` to `newkey` if `newkey` does not yet exist. It returns an error -under the same conditions as `RENAME`. +Renames `key` to `newkey` if `newkey` does not yet exist. +It returns an error under the same conditions as `RENAME`. @return diff --git a/commands/restore.md b/commands/restore.md index 9b04f820fe..861dcbfbad 100644 --- a/commands/restore.md +++ b/commands/restore.md @@ -4,8 +4,8 @@ provided serialized value (obtained via `DUMP`). If `ttl` is 0 the key is created without any expire, otherwise the specified expire time (in milliseconds) is set. -`RESTORE` checks the RDB version and data checksum. If they don't match an error -is returned. +`RESTORE` checks the RDB version and data checksum. +If they don't match an error is returned. @return diff --git a/commands/rpoplpush.md b/commands/rpoplpush.md index a6644658a5..34c393bac2 100644 --- a/commands/rpoplpush.md +++ b/commands/rpoplpush.md @@ -3,13 +3,15 @@ Atomically returns and removes the last element (tail) of the list stored at 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`. +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. +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 @@ -28,10 +30,11 @@ element of the list, so it can be considered as a list rotation command. ## Pattern: Reliable queue Redis is often used as a messaging server to implement processing of background -jobs or other kinds of messaging tasks. A simple form of queue is often obtained -pushing values into a list in the producer side, and waiting for this values -in the consumer side using `RPOP` (using polling), or `BRPOP` if the client is -better served by a blocking operation. +jobs or other kinds of messaging tasks. +A simple form of queue is often obtained pushing values into a list in the +producer side, and waiting for this values in the consumer side using `RPOP` +(using polling), or `BRPOP` if the client is better served by a blocking +operation. However in this context the obtained queue is not _reliable_ as messages can be lost, for example in the case there is a network problem or if the consumer @@ -39,8 +42,9 @@ crashes just after the message is received but it is still to process. `RPOPLPUSH` (or `BRPOPLPUSH` for the blocking variant) offers a way to avoid this problem: the consumer fetches the message and at the same time pushes it -into a _processing_ list. It will use the `LREM` command in order to remove the -message from the _processing_ list once the message has been processed. +into a _processing_ list. +It will use the `LREM` command in order to remove the message from the +_processing_ list once the message has been processed. An additional client may monitor the _processing_ list for items that remain there for too much time, and will push those timed out items into the queue @@ -55,13 +59,13 @@ operation. The above pattern works even if the following two conditions: * There are multiple clients rotating the list: they'll fetch different elements, until all -the elements of the list are visited, and the process restarts. * Even if other -clients are actively pushing new items at the end of the list. +the elements of the list are visited, and the process restarts. +* Even if other clients are actively pushing new items at the end of the list. The above makes it very simple to implement a system where a set of items must -be processed by N workers continuously as fast as possible. An example is a -monitoring system that must check that a set of web sites are reachable, with -the smallest delay possible, using a number of parallel workers. +be processed by N workers continuously as fast as possible. +An example is a monitoring system that must check that a set of web sites are +reachable, with the smallest delay possible, using a number of parallel workers. Note that this implementation of workers is trivially scalable and reliable, because even if a message is lost the item is still in the queue and will be diff --git a/commands/rpush.md b/commands/rpush.md index a655598e0a..6ed764f650 100644 --- a/commands/rpush.md +++ b/commands/rpush.md @@ -1,13 +1,14 @@ -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. +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. +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 @@ -15,8 +16,9 @@ third element. @history -* `>= 2.4`: Accepts multiple `value` arguments. In Redis versions older than 2.4 - it was possible to push a single value per command. +* `>= 2.4`: Accepts multiple `value` arguments. + In Redis versions older than 2.4 it was possible to push a single value per + command. @examples diff --git a/commands/rpushx.md b/commands/rpushx.md index a7f8d04a73..5375485707 100644 --- a/commands/rpushx.md +++ b/commands/rpushx.md @@ -1,6 +1,7 @@ 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. +exists and holds a list. +In contrary to `RPUSH`, no operation will be performed when `key` does not yet +exist. @return diff --git a/commands/sadd.md b/commands/sadd.md index e6ad0cf3d4..92de4c30ad 100644 --- a/commands/sadd.md +++ b/commands/sadd.md @@ -1,6 +1,7 @@ -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. +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. @@ -11,8 +12,8 @@ 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. +* `>= 2.4`: Accepts multiple `member` arguments. + Redis versions before 2.4 are only able to add a single member per call. @examples diff --git a/commands/save.md b/commands/save.md index 6a20aad3d1..783c9d117c 100644 --- a/commands/save.md +++ b/commands/save.md @@ -3,10 +3,11 @@ _point in time_ snapshot of all the data inside the Redis instance, in the form of an RDB file. You almost never what to call `SAVE` in production environments where it will -block all the other clients. Instead usually `BGSAVE` is used. However in case -of issues preventing Redis to create the background saving child (for instance -errors in the fork(2) system call), the `SAVE` command can be a good last resort -to perform the dump of the latest dataset. +block all the other clients. +Instead usually `BGSAVE` is used. +However in case of issues preventing Redis to create the background saving child +(for instance errors in the fork(2) system call), the `SAVE` command can be a +good last resort to perform the dump of the latest dataset. Please refer to the [persistence documentation][tp] for detailed information. diff --git a/commands/script exists.md b/commands/script exists.md index 17aac20883..b1f7cf7e37 100644 --- a/commands/script exists.md +++ b/commands/script exists.md @@ -13,9 +13,9 @@ Lua scripting. @return @multi-bulk-reply The command returns an array of integers that correspond to -the specified SHA1 sum arguments. For every corresponding SHA1 sum of a script -that actually exists in the script cache, an 1 is returned, otherwise 0 is -returned. +the specified SHA1 sum arguments. +For every corresponding SHA1 sum of a script that actually exists in the script +cache, an 1 is returned, otherwise 0 is returned. @example diff --git a/commands/script kill.md b/commands/script kill.md index 2be073997b..4fea76f7d9 100644 --- a/commands/script kill.md +++ b/commands/script kill.md @@ -2,14 +2,15 @@ Kills the currently executing Lua script, assuming no write operation was yet performed by the script. This command is mainly useful to kill a script that is running for too much -time(for instance because it entered an infinite loop because of a bug). The -script will be killed and the client currently blocked into EVAL will see the -command returning with an error. +time(for instance because it entered an infinite loop because of a bug). +The script will be killed and the client currently blocked into EVAL will see +the command returning with an error. If the script already performed write operations it can not be killed in this -way because it would violate Lua script atomicity contract. In such a case only -`SHUTDOWN NOSAVE` is able to kill the script, killing the Redis process in an -hard way preventing it to persist with half-written information. +way because it would violate Lua script atomicity contract. +In such a case only `SHUTDOWN NOSAVE` is able to kill the script, killing +the Redis process in an hard way preventing it to persist with half-written +information. Please refer to the `EVAL` documentation for detailed information about Redis Lua scripting. diff --git a/commands/script load.md b/commands/script load.md index 15bd451c86..4709695bec 100644 --- a/commands/script load.md +++ b/commands/script load.md @@ -1,7 +1,7 @@ -Load a script into the scripts cache, without executing it. After the specified -command is loaded into the script cache it will be callable using `EVALSHA` with -the correct SHA1 digest of the script, exactly like after the first successful -invocation of `EVAL`. +Load a script into the scripts cache, without executing it. +After the specified command is loaded into the script cache it will be callable +using `EVALSHA` with the correct SHA1 digest of the script, exactly like after +the first successful invocation of `EVAL`. The script is guaranteed to stay in the script cache forever (unless `SCRIPT FLUSH` is called). diff --git a/commands/select.md b/commands/select.md index 29825ad3d7..b0a4cd565a 100644 --- a/commands/select.md +++ b/commands/select.md @@ -1,5 +1,5 @@ -Select the DB with having the specified zero-based numeric index. New -connections always use DB 0. +Select the DB with having the specified zero-based numeric index. +New connections always use DB 0. @return diff --git a/commands/set.md b/commands/set.md index 34d9a8c284..547f4c0824 100644 --- a/commands/set.md +++ b/commands/set.md @@ -1,5 +1,5 @@ -Set `key` to hold the string `value`. If `key` already holds a value, it is -overwritten, regardless of its type. +Set `key` to hold the string `value`. +If `key` already holds a value, it is overwritten, regardless of its type. @return diff --git a/commands/setbit.md b/commands/setbit.md index 1cf7f1b914..3541cddfb6 100644 --- a/commands/setbit.md +++ b/commands/setbit.md @@ -1,20 +1,23 @@ 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. +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. +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 diff --git a/commands/setex.md b/commands/setex.md index d29221df96..53221baaee 100644 --- a/commands/setex.md +++ b/commands/setex.md @@ -1,14 +1,14 @@ 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: +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. +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. diff --git a/commands/setnx.md b/commands/setnx.md index 37b4b64484..df607d33c8 100644 --- a/commands/setnx.md +++ b/commands/setnx.md @@ -1,5 +1,6 @@ -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. +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 @@ -18,25 +19,27 @@ equal to `SET`. When `key` already holds a value, no operation is performed. ## 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` 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 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. +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 +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. +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 @@ -56,20 +59,23 @@ 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. +* 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 * 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. + `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. + 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 diff --git a/commands/setrange.md b/commands/setrange.md index 3b99b658eb..38821216cb 100644 --- a/commands/setrange.md +++ b/commands/setrange.md @@ -1,29 +1,30 @@ 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_. +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. +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. +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. +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 diff --git a/commands/shutdown.md b/commands/shutdown.md index dd7c239de2..e659d86349 100644 --- a/commands/shutdown.md +++ b/commands/shutdown.md @@ -6,9 +6,9 @@ The command behavior is the following: * 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. +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 @@ -18,15 +18,18 @@ shutting down. ## SAVE and NOSAVE modifiers It is possible to specify an optional modifier to alter the behavior of the -command. Specifically: +command. +Specifically: * **SHUTDOWN SAVE** will force a DB saving operation even if no save points are configured. * **SHUTDOWN NOSAVE** will prevent a DB saving operation even if one or more - save points are configured. (You can think at this variant as an hypothetical - **ABORT** command that just stops the server). + save points are configured. + (You can think at this variant as an hypothetical **ABORT** command that just + stops the server). @return -@status-reply on error. On success nothing is returned since the server quits -and the connection is closed. +@status-reply on error. +On success nothing is returned since the server quits and the connection is +closed. diff --git a/commands/sinter.md b/commands/sinter.md index 70c848aba6..d7bdceb551 100644 --- a/commands/sinter.md +++ b/commands/sinter.md @@ -8,9 +8,9 @@ For example: 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). +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 diff --git a/commands/slaveof.md b/commands/slaveof.md index 3ff3091476..f3d20e6b24 100644 --- a/commands/slaveof.md +++ b/commands/slaveof.md @@ -1,18 +1,19 @@ 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 another server -listening at the specified hostname and port. +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 +another 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 stops -working, it is possible to turn the slave into a master and set the application -to use this new master in read/write. Later when the other Redis server is -fixed, it can be reconfigured to work as a slave. +MASTER, but will not discard the replication. +So, if the old master stops working, it is possible to turn the slave into a +master and set the application to use this new master in read/write. +Later when the other Redis server is fixed, it can be reconfigured to work as a +slave. @return diff --git a/commands/slowlog.md b/commands/slowlog.md index 943764ebfc..55306cdda1 100644 --- a/commands/slowlog.md +++ b/commands/slowlog.md @@ -3,18 +3,22 @@ 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). +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: _slowlog-log-slower-than_ tells Redis what is the execution time, in microseconds, to exceed in order for -the command to get logged. Note that a negative number disables the slow log, -while a value of zero forces the logging of every command. _slowlog-max-len_ -is the length of the slow log. The minimum value is zero. 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 command to get logged. +Note that a negative number disables the slow log, while a value of zero forces +the logging of every command. +_slowlog-max-len_ is the length of the slow log. +The minimum value is zero. +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 by editing `redis.conf` or while the server is running using the `CONFIG GET` and `CONFIG SET` commands. @@ -22,13 +26,15 @@ running using the `CONFIG GET` and `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. +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**). +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 @@ -69,5 +75,5 @@ It is possible to get just the length of the slow log using the command ## Resetting the slow log. -You can reset the slow log using the **SLOWLOG RESET** command. Once deleted the -information is lost forever. +You can reset the slow log using the **SLOWLOG RESET** command. +Once deleted the information is lost forever. diff --git a/commands/smove.md b/commands/smove.md index 7a4b689dd4..e2dfccb14c 100644 --- a/commands/smove.md +++ b/commands/smove.md @@ -1,11 +1,14 @@ -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. +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. +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. diff --git a/commands/sort.md b/commands/sort.md index 6f53952dbe..c2c7b5e533 100644 --- a/commands/sort.md +++ b/commands/sort.md @@ -1,6 +1,7 @@ Returns or stores the elements contained in the [list][tdtl], [set][tdts] or -[sorted set][tdtss] at `key`. By default, sorting is numeric and elements are -compared by their value interpreted as double precision floating point number. +[sorted set][tdtss] 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: [tdtl]: /topics/data-types#lists @@ -10,8 +11,8 @@ 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: +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 @@ -24,49 +25,53 @@ 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): +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: +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 +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). +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. +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: +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_* @@ -79,22 +84,23 @@ It is also possible to `!GET` the element itself using the special pattern `#`: ## 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. +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. +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`). +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` @@ -103,9 +109,9 @@ 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. +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 diff --git a/commands/srem.md b/commands/srem.md index 759c8b853c..f92a1d0d92 100644 --- a/commands/srem.md +++ b/commands/srem.md @@ -1,6 +1,7 @@ -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`. +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. @@ -11,8 +12,8 @@ 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. +* `>= 2.4`: Accepts multiple `member` arguments. + Redis versions older than 2.4 can only remove a set member per call. @examples diff --git a/commands/strlen.md b/commands/strlen.md index 6700b71d0d..4b36ab8b80 100644 --- a/commands/strlen.md +++ b/commands/strlen.md @@ -1,5 +1,5 @@ -Returns the length of the string value stored at `key`. An error is returned -when `key` holds a non-string value. +Returns the length of the string value stored at `key`. +An error is returned when `key` holds a non-string value. @return diff --git a/commands/ttl.md b/commands/ttl.md index 3c31fcec5f..1e1914cad8 100644 --- a/commands/ttl.md +++ b/commands/ttl.md @@ -1,6 +1,6 @@ -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. +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 diff --git a/commands/type.md b/commands/type.md index 9a0225f7e8..9c5fefb048 100644 --- a/commands/type.md +++ b/commands/type.md @@ -1,6 +1,6 @@ -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`. +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 diff --git a/commands/unsubscribe.md b/commands/unsubscribe.md index 78c4d0c759..7bdf1d15e5 100644 --- a/commands/unsubscribe.md +++ b/commands/unsubscribe.md @@ -2,5 +2,6 @@ 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. +previously subscribed channels. +In this case, a message for every unsubscribed channel will be sent to the +client. diff --git a/commands/zadd.md b/commands/zadd.md index 65664f4901..081b926b3f 100644 --- a/commands/zadd.md +++ b/commands/zadd.md @@ -1,10 +1,12 @@ 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. +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. +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. @@ -23,8 +25,9 @@ sets][tdtss]. @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. +* `>= 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 diff --git a/commands/zincrby.md b/commands/zincrby.md index 1623b6b6dd..4e30a49ab2 100644 --- a/commands/zincrby.md +++ b/commands/zincrby.md @@ -1,14 +1,15 @@ 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. +`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. +accepts double precision floating point numbers. +It is possible to provide a negative value to decrement the score. @return diff --git a/commands/zinterstore.md b/commands/zinterstore.md index dd7e71dfe4..7b7f1afe2e 100644 --- a/commands/zinterstore.md +++ b/commands/zinterstore.md @@ -1,12 +1,13 @@ 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. +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. +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`. diff --git a/commands/zrange.md b/commands/zrange.md index 42275f6c77..3ec95281b7 100644 --- a/commands/zrange.md +++ b/commands/zrange.md @@ -1,25 +1,28 @@ -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. +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. +`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). +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 diff --git a/commands/zrangebyscore.md b/commands/zrangebyscore.md index 2a355904b5..92c7be524b 100644 --- a/commands/zrangebyscore.md +++ b/commands/zrangebyscore.md @@ -1,20 +1,20 @@ 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. +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. +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. +its score, instead of the element alone. +This option is available since Redis 2.0. ## Exclusive intervals and infinity @@ -22,9 +22,10 @@ its score, instead of the element alone. This option is available since Redis 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: +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 diff --git a/commands/zrank.md b/commands/zrank.md index 3703b5bee1..243af3c338 100644 --- a/commands/zrank.md +++ b/commands/zrank.md @@ -1,6 +1,7 @@ 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`. +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. diff --git a/commands/zrem.md b/commands/zrem.md index 8733647153..9461fd7eeb 100644 --- a/commands/zrem.md +++ b/commands/zrem.md @@ -1,5 +1,5 @@ -Removes the specified members from the sorted set stored at `key`. Non existing -members are ignored. +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. @@ -12,8 +12,9 @@ An error is returned when `key` exists and does not hold a sorted set. @history -* `>= 2.4`: Accepts multiple elements. In Redis versions older than 2.4 it was - possible to remove a single member per call. +* `>= 2.4`: Accepts multiple elements. + In Redis versions older than 2.4 it was possible to remove a single member per + call. @examples diff --git a/commands/zremrangebyrank.md b/commands/zremrangebyrank.md index e0458d21de..7a77d12900 100644 --- a/commands/zremrangebyrank.md +++ b/commands/zremrangebyrank.md @@ -1,9 +1,11 @@ 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. +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 diff --git a/commands/zrevrange.md b/commands/zrevrange.md index 772be477e2..c77c66001e 100644 --- a/commands/zrevrange.md +++ b/commands/zrevrange.md @@ -1,5 +1,5 @@ -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. +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`. diff --git a/commands/zrevrangebyscore.md b/commands/zrevrangebyscore.md index bc2257cea2..84aaead246 100644 --- a/commands/zrevrangebyscore.md +++ b/commands/zrevrangebyscore.md @@ -1,7 +1,7 @@ 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. +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. diff --git a/commands/zrevrank.md b/commands/zrevrank.md index 90f86352c4..928dea02bd 100644 --- a/commands/zrevrank.md +++ b/commands/zrevrank.md @@ -1,6 +1,7 @@ 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`. +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. diff --git a/commands/zunionstore.md b/commands/zunionstore.md index f2710f61e6..196c7f14de 100644 --- a/commands/zunionstore.md +++ b/commands/zunionstore.md @@ -1,22 +1,23 @@ 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. +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`. +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. +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. diff --git a/remarkdown.rb b/remarkdown.rb index 50f5e518b0..3a18e1b9a1 100644 --- a/remarkdown.rb +++ b/remarkdown.rb @@ -93,7 +93,12 @@ def format_inline_nodes(nodes) end end - par(result).chomp + sentences = result.gsub(/\s*\r?\n\s*/, " ").split(/(?<=[^.]\.)\s+/) + sentences = sentences.map do |e| + par(e).chomp + end + + sentences.join("\n") end def format_inline_node(node)