[redis.git] / doc / MultiExecCommand.html


<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN">
<html>
    <head>
        <link type="text/css" rel="stylesheet" href="style.css" />
    </head>
    <body>
        <div id="page">
        
            <div id='header'>
            <a href="index.html">
            <img style="border:none" alt="Redis Documentation" src="redis.png">
            </a>
            </div>
        
            <div id="pagecontent">
                <div class="index">
<!-- This is a (PRE) block.  Make sure it's left aligned or your toc title will be off. -->
<b>MultiExecCommand: Contents</b><br>&nbsp;&nbsp;<a href="#WATCH key1 key2 ... keyN (Redis &gt;">WATCH key1 key2 ... keyN (Redis &gt;</a><br>&nbsp;&nbsp;<a href="#UNWATCH">UNWATCH</a><br>&nbsp;&nbsp;<a href="#MULTI">MULTI</a><br>&nbsp;&nbsp;<a href="#COMMAND_1 ...">COMMAND_1 ...</a><br>&nbsp;&nbsp;<a href="#COMMAND_2 ...">COMMAND_2 ...</a><br>&nbsp;&nbsp;<a href="#COMMAND_N ...">COMMAND_N ...</a><br>&nbsp;&nbsp;<a href="#EXEC or DISCARD">EXEC or DISCARD</a><br>&nbsp;&nbsp;&nbsp;&nbsp;<a href="#Usage">Usage</a><br>&nbsp;&nbsp;&nbsp;&nbsp;<a href="#The DISCARD command">The DISCARD command</a><br>&nbsp;&nbsp;&nbsp;&nbsp;<a href="#Check and Set (CAS) transactions using WATCH">Check and Set (CAS) transactions using WATCH</a><br>&nbsp;&nbsp;&nbsp;&nbsp;<a href="#WATCH explained">WATCH explained</a><br>&nbsp;&nbsp;&nbsp;&nbsp;<a href="#WATCH used to implement ZPOP">WATCH used to implement ZPOP</a><br>&nbsp;&nbsp;&nbsp;&nbsp;<a href="#Return value">Return value</a>
                </div>
                
                <h1 class="wikiname">MultiExecCommand</h1>

                <div class="summary">
                    
                </div>

                <div class="narrow">
                    &iuml;&raquo;&iquest;#sidebar <a href="GenericCommandsSidebar.html">GenericCommandsSidebar</a><h1><a name="WATCH key1 key2 ... keyN (Redis &gt;">WATCH key1 key2 ... keyN (Redis &gt;</a></h1> 2.1.0)=
<h1><a name="UNWATCH">UNWATCH</a></h1>
<h1><a name="MULTI">MULTI</a></h1>
<h1><a name="COMMAND_1 ...">COMMAND_1 ...</a></h1>
<h1><a name="COMMAND_2 ...">COMMAND_2 ...</a></h1>
<h1><a name="COMMAND_N ...">COMMAND_N ...</a></h1>
<h1><a name="EXEC or DISCARD">EXEC or DISCARD</a></h1>MULTI, EXEC, DISCARD and WATCH commands are the foundation of Redis Transactions.
A Redis Transaction allows the execution of a group of Redis commands in a single
step, with two important guarantees:<br/><br/><ul><li> All the commands in a transaction are serialized and executed sequentially. It can never happen that a request issued by another client is served <b>in the middle</b> of the execution of a Redis transaction. This guarantees that the commands are executed as a single atomic operation.</li><li> Either all of the commands or none are processed. The EXEC command triggers the execution of all the commands in the transaction, so if a client loses the connection to the server in the context of a transaction before calling the MULTI command none of the operations are performed, instead if the EXEC command is called, all the operations are performed. An exception to this rule is when the Append Only File is enabled: every command that is part of a Redis transaction will log in the AOF as long as the operation is completed, so if the Redis server crashes or is killed by the system administrator in some hard way it is possible that only a partial number of operations are registered.</li></ul>
Since Redis 2.1.0, it's also possible to add a further guarantee to the above two, in the form of optimistic locking of a set of keys in a way very similar to a CAS (check and set) operation. This is documented later in this manual page.<h2><a name="Usage">Usage</a></h2>A Redis transaction is entered using the MULTI command. The command always
replies with OK. At this point the user can issue multiple commands. Instead
of executing these commands, Redis will &quot;queue&quot; them. All the commands are
executed once EXEC is called.<br/><br/>Calling DISCARD instead will flush the transaction queue and will exit
the transaction.<br/><br/>The following is an example using the Ruby client:
<pre class="codeblock python" name="code">
?&gt; r.multi
=&gt; &quot;OK&quot;
&gt;&gt; r.incr &quot;foo&quot;
=&gt; &quot;QUEUED&quot;
&gt;&gt; r.incr &quot;bar&quot;
=&gt; &quot;QUEUED&quot;
&gt;&gt; r.incr &quot;bar&quot;
=&gt; &quot;QUEUED&quot;
&gt;&gt; r.exec
=&gt; [1, 1, 2]
</pre>
As it is possible to see from the session above, MULTI returns an &quot;array&quot; of
replies, where every element is the reply of a single command in the
transaction, in the same order the commands were queued.<br/><br/>When a Redis connection is in the context of a MULTI request, all the commands
will reply with a simple string &quot;QUEUED&quot; if they are correct from the
point of view of the syntax and arity (number of arguments) of the commaand.
Some commands are still allowed to fail during execution time.<br/><br/>This is more clear on the protocol level; In the following example one command
will fail when executed even if the syntax is right:
<pre class="codeblock python python" name="code">
Trying 127.0.0.1...
Connected to localhost.
Escape character is '^]'.
MULTI
+OK
SET a 3 
abc
+QUEUED
LPOP a
+QUEUED
EXEC
*2
+OK
-ERR Operation against a key holding the wrong kind of value
</pre>
MULTI returned a two elements bulk reply where one is an +OK
code and one is a -ERR reply. It's up to the client lib to find a sensible
way to provide the error to the user.<br/><br/><blockquote>IMPORTANT: even when a command will raise an error, all the other commandsin the queue will be processed. Redis will NOT stop the processing ofcommands once an error is found.</blockquote>
Another example, again using the write protocol with telnet, shows how
syntax errors are reported ASAP instead:
<pre class="codeblock python python python" name="code">
MULTI
+OK
INCR a b c
-ERR wrong number of arguments for 'incr' command
</pre>
This time due to the syntax error the &quot;bad&quot; INCR command is not queued
at all.<h2><a name="The DISCARD command">The DISCARD command</a></h2>DISCARD can be used in order to abort a transaction. No command will be executed, and the state of the client is again the normal one, outside of a transaction. Example using the Ruby client:
<pre class="codeblock python python python python" name="code">
?&gt; r.set(&quot;foo&quot;,1)
=&gt; true
&gt;&gt; r.multi
=&gt; &quot;OK&quot;
&gt;&gt; r.incr(&quot;foo&quot;)
=&gt; &quot;QUEUED&quot;
&gt;&gt; r.discard
=&gt; &quot;OK&quot;
&gt;&gt; r.get(&quot;foo&quot;)
=&gt; &quot;1&quot;
</pre><h2><a name="Check and Set (CAS) transactions using WATCH">Check and Set (CAS) transactions using WATCH</a></h2>WATCH is used in order to provide a CAS (Check and Set) behavior to
Redis Transactions.<br/><br/>WATCHed keys are monitored in order to detect changes against this keys.
If at least a watched key will be modified before the EXEC call, the
whole transaction will abort, and EXEC will return a nil object
(A Null Multi Bulk reply) to notify that the transaction failed.<br/><br/>For example imagine we have the need to atomically increment the value
of a key by 1 (I know we have INCR, let's suppose we don't have it).<br/><br/>The first try may be the following:
<pre class="codeblock python python python python python" name="code">
val = GET mykey
val = val + 1
SET mykey $val
</pre>
This will work reliably only if we have a single client performing the operation in a given time.
If multiple clients will try to increment the key about at the same time
there will be a race condition. For instance client A and B will read the
old value, for instance, 10. The value will be incremented to 11 by both
the clients, and finally SET as the value of the key. So the final value
will be &quot;11&quot; instead of &quot;12&quot;.<br/><br/>Thanks to WATCH we are able to model the problem very well:
<pre class="codeblock python python python python python python" name="code">
WATCH mykey
val = GET mykey
val = val + 1
MULTI
SET mykey $val
EXEC
</pre>
Using the above code, if there are race conditions and another client
modified the result of <i>val</i> in the time between our call to WATCH and
our call to EXEC, the transaction will fail.<br/><br/>We'll have just to re-iterate the operation hoping this time we'll not get
a new race. This form of locking is called <b>optimistic locking</b> and is
a very powerful form of locking as in many problems there are multiple
clients accessing a much bigger number of keys, so it's very unlikely that
there are collisions: usually operations don't need to be performed
multiple times.<h2><a name="WATCH explained">WATCH explained</a></h2>So what is WATCH really about? It is a command that will make the EXEC
conditional: we are asking Redis to perform the transaction only if no
other client modified any of the WATCHed keys. Otherwise the transaction is not
entered at all. (Note that if you WATCH a volatile key and Redis expires the key after you WATCHed it, EXEC will still work. <a href="http://code.google.com/p/redis/issues/detail?id=270" target="_blank">More</a>.)<br/><br/>WATCH can be called multiple times. Simply all the WATCH calls will
have the effects to watch for changes starting from the call, up to the
moment EXEC is called.<br/><br/>When EXEC is called, either if it will fail or succeed, all keys are
UNWATCHed. Also when a client connection is closed, everything gets
UNWATCHed.<br/><br/>It is also possible to use the UNWATCH command (without arguments) in order
to flush all the watched keys. Sometimes this is useful as we
optimistically lock a few keys, since possibly we need to perform a transaction
to alter those keys, but after reading the current content of the keys
we don't want to proceed. When this happens we just call UNWATCH so that
the connection can already be used freely for new transactions.<h2><a name="WATCH used to implement ZPOP">WATCH used to implement ZPOP</a></h2>A good example to illustrate how WATCH can be used to create new atomic
operations otherwise not supported by Redis is to implement ZPOP, that is
a command that pops the element with the lower score from a sorted set
in an atomic way. This is the simplest implementation:
<pre class="codeblock python python python python python python python" name="code">
WATCH zset
ele = ZRANGE zset 0 0
MULTI
ZREM zset ele
EXEC
</pre>
If EXEC fails (returns a nil value) we just re-iterate the operation.<h2><a name="Return value">Return value</a></h2><a href="ReplyTypes.html">Multi bulk reply</a>, specifically:<br/><br/><pre class="codeblock python python python python python python python python" name="code">
The result of a MULTI/EXEC command is a multi bulk reply where every element is the return value of every command in the atomic transaction.
</pre>If a MULTI/EXEC transaction is aborted because of WATCH detected modified keys, a <a href="ReplyTypes.html">Null Multi Bulk reply</a> is returned.
                </div>
        
            </div>
        </div>
    </body>
</html>
Commit	Line	Data
aed57a31	1
	2	<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN">
	3	<html>
	4	<head>
	5	<link type="text/css" rel="stylesheet" href="style.css" />
	6	</head>
	7	<body>
	8	<div id="page">
	9
	10	<div id='header'>
	11	<a href="index.html">
	12	<img style="border:none" alt="Redis Documentation" src="redis.png">
	13	</a>
	14	</div>
	15
	16	<div id="pagecontent">
	17	<div class="index">
	18	<!-- This is a (PRE) block. Make sure it's left aligned or your toc title will be off. -->
abe18d0e	19	<b>MultiExecCommand: Contents</b><br>  <a href="#WATCH key1 key2 ... keyN (Redis >">WATCH key1 key2 ... keyN (Redis ></a><br>  <a href="#UNWATCH">UNWATCH</a><br>  <a href="#MULTI">MULTI</a><br>  <a href="#COMMAND_1 ...">COMMAND_1 ...</a><br>  <a href="#COMMAND_2 ...">COMMAND_2 ...</a><br>  <a href="#COMMAND_N ...">COMMAND_N ...</a><br>  <a href="#EXEC or DISCARD">EXEC or DISCARD</a><br>    <a href="#Usage">Usage</a><br>    <a href="#The DISCARD command">The DISCARD command</a><br>    <a href="#Check and Set (CAS) transactions using WATCH">Check and Set (CAS) transactions using WATCH</a><br>    <a href="#WATCH explained">WATCH explained</a><br>    <a href="#WATCH used to implement ZPOP">WATCH used to implement ZPOP</a><br>    <a href="#Return value">Return value</a>
aed57a31	20	</div>
	21
	22	<h1 class="wikiname">MultiExecCommand</h1>
	23
	24	<div class="summary">
	25
	26	</div>
	27
	28	<div class="narrow">
abe18d0e	29	ï»¿#sidebar <a href="GenericCommandsSidebar.html">GenericCommandsSidebar</a><h1><a name="WATCH key1 key2 ... keyN (Redis >">WATCH key1 key2 ... keyN (Redis ></a></h1> 2.1.0)=
	30	<h1><a name="UNWATCH">UNWATCH</a></h1>
	31	<h1><a name="MULTI">MULTI</a></h1>
aed57a31	32	<h1><a name="COMMAND_1 ...">COMMAND_1 ...</a></h1>
	33	<h1><a name="COMMAND_2 ...">COMMAND_2 ...</a></h1>
	34	<h1><a name="COMMAND_N ...">COMMAND_N ...</a></h1>
b9f7e9e6	35	<h1><a name="EXEC or DISCARD">EXEC or DISCARD</a></h1>MULTI, EXEC, DISCARD and WATCH commands are the foundation of Redis Transactions.
abe18d0e	36	A Redis Transaction allows the execution of a group of Redis commands in a single
	37	step, with two important guarantees:<br/><br/><ul><li> All the commands in a transaction are serialized and executed sequentially. It can never happen that a request issued by another client is served <b>in the middle</b> of the execution of a Redis transaction. This guarantees that the commands are executed as a single atomic operation.</li><li> Either all of the commands or none are processed. The EXEC command triggers the execution of all the commands in the transaction, so if a client loses the connection to the server in the context of a transaction before calling the MULTI command none of the operations are performed, instead if the EXEC command is called, all the operations are performed. An exception to this rule is when the Append Only File is enabled: every command that is part of a Redis transaction will log in the AOF as long as the operation is completed, so if the Redis server crashes or is killed by the system administrator in some hard way it is possible that only a partial number of operations are registered.</li></ul>
	38	Since Redis 2.1.0, it's also possible to add a further guarantee to the above two, in the form of optimistic locking of a set of keys in a way very similar to a CAS (check and set) operation. This is documented later in this manual page.<h2><a name="Usage">Usage</a></h2>A Redis transaction is entered using the MULTI command. The command always
	39	replies with OK. At this point the user can issue multiple commands. Instead
b9f7e9e6	40	of executing these commands, Redis will "queue" them. All the commands are
abe18d0e	41	executed once EXEC is called.<br/><br/>Calling DISCARD instead will flush the transaction queue and will exit
	42	the transaction.<br/><br/>The following is an example using the Ruby client:
	43	<pre class="codeblock python" name="code">
aed57a31	44	?> r.multi
	45	=> "OK"
	46	>> r.incr "foo"
	47	=> "QUEUED"
	48	>> r.incr "bar"
	49	=> "QUEUED"
	50	>> r.incr "bar"
	51	=> "QUEUED"
	52	>> r.exec
	53	=> [1, 1, 2]
	54	</pre>
abe18d0e	55	As it is possible to see from the session above, MULTI returns an "array" of
	56	replies, where every element is the reply of a single command in the
	57	transaction, in the same order the commands were queued.<br/><br/>When a Redis connection is in the context of a MULTI request, all the commands
	58	will reply with a simple string "QUEUED" if they are correct from the
	59	point of view of the syntax and arity (number of arguments) of the commaand.
b9f7e9e6	60	Some commands are still allowed to fail during execution time.<br/><br/>This is more clear on the protocol level; In the following example one command
abe18d0e	61	will fail when executed even if the syntax is right:
abe18d0e	62	<pre class="codeblock python python" name="code">
aed57a31	63	Trying 127.0.0.1...
	64	Connected to localhost.
	65	Escape character is '^]'.
	66	MULTI
	67	+OK
	68	SET a 3
	69	abc
	70	+QUEUED
	71	LPOP a
	72	+QUEUED
	73	EXEC
	74	*2
	75	+OK
	76	-ERR Operation against a key holding the wrong kind of value
	77	</pre>
b9f7e9e6	78	MULTI returned a two elements bulk reply where one is an +OK
abe18d0e	79	code and one is a -ERR reply. It's up to the client lib to find a sensible
	80	way to provide the error to the user.<br/><br/><blockquote>IMPORTANT: even when a command will raise an error, all the other commandsin the queue will be processed. Redis will NOT stop the processing ofcommands once an error is found.</blockquote>
	81	Another example, again using the write protocol with telnet, shows how
	82	syntax errors are reported ASAP instead:
	83	<pre class="codeblock python python python" name="code">
aed57a31	84	MULTI
	85	+OK
	86	INCR a b c
	87	-ERR wrong number of arguments for 'incr' command
	88	</pre>
abe18d0e	89	This time due to the syntax error the "bad" INCR command is not queued
b9f7e9e6	90	at all.<h2><a name="The DISCARD command">The DISCARD command</a></h2>DISCARD can be used in order to abort a transaction. No command will be executed, and the state of the client is again the normal one, outside of a transaction. Example using the Ruby client:
b9f7e9e6	91	<pre class="codeblock python python python python" name="code">
aed57a31	92	?> r.set("foo",1)
	93	=> true
	94	>> r.multi
	95	=> "OK"
	96	>> r.incr("foo")
	97	=> "QUEUED"
	98	>> r.discard
	99	=> "OK"
	100	>> r.get("foo")
	101	=> "1"
abe18d0e	102	</pre><h2><a name="Check and Set (CAS) transactions using WATCH">Check and Set (CAS) transactions using WATCH</a></h2>WATCH is used in order to provide a CAS (Check and Set) behavior to
	103	Redis Transactions.<br/><br/>WATCHed keys are monitored in order to detect changes against this keys.
	104	If at least a watched key will be modified before the EXEC call, the
	105	whole transaction will abort, and EXEC will return a nil object
	106	(A Null Multi Bulk reply) to notify that the transaction failed.<br/><br/>For example imagine we have the need to atomically increment the value
	107	of a key by 1 (I know we have INCR, let's suppose we don't have it).<br/><br/>The first try may be the following:
	108	<pre class="codeblock python python python python python" name="code">
	109	val = GET mykey
	110	val = val + 1
	111	SET mykey $val
	112	</pre>
	113	This will work reliably only if we have a single client performing the operation in a given time.
	114	If multiple clients will try to increment the key about at the same time
	115	there will be a race condition. For instance client A and B will read the
	116	old value, for instance, 10. The value will be incremented to 11 by both
	117	the clients, and finally SET as the value of the key. So the final value
	118	will be "11" instead of "12".<br/><br/>Thanks to WATCH we are able to model the problem very well:
	119	<pre class="codeblock python python python python python python" name="code">
	120	WATCH mykey
	121	val = GET mykey
	122	val = val + 1
	123	MULTI
	124	SET mykey $val
	125	EXEC
aed57a31	126	</pre>
abe18d0e	127	Using the above code, if there are race conditions and another client
	128	modified the result of <i>val</i> in the time between our call to WATCH and
	129	our call to EXEC, the transaction will fail.<br/><br/>We'll have just to re-iterate the operation hoping this time we'll not get
	130	a new race. This form of locking is called <b>optimistic locking</b> and is
	131	a very powerful form of locking as in many problems there are multiple
	132	clients accessing a much bigger number of keys, so it's very unlikely that
	133	there are collisions: usually operations don't need to be performed
	134	multiple times.<h2><a name="WATCH explained">WATCH explained</a></h2>So what is WATCH really about? It is a command that will make the EXEC
	135	conditional: we are asking Redis to perform the transaction only if no
	136	other client modified any of the WATCHed keys. Otherwise the transaction is not
	137	entered at all. (Note that if you WATCH a volatile key and Redis expires the key after you WATCHed it, EXEC will still work. <a href="http://code.google.com/p/redis/issues/detail?id=270" target="_blank">More</a>.)<br/><br/>WATCH can be called multiple times. Simply all the WATCH calls will
	138	have the effects to watch for changes starting from the call, up to the
	139	moment EXEC is called.<br/><br/>When EXEC is called, either if it will fail or succeed, all keys are
	140	UNWATCHed. Also when a client connection is closed, everything gets
	141	UNWATCHed.<br/><br/>It is also possible to use the UNWATCH command (without arguments) in order
	142	to flush all the watched keys. Sometimes this is useful as we
	143	optimistically lock a few keys, since possibly we need to perform a transaction
	144	to alter those keys, but after reading the current content of the keys
	145	we don't want to proceed. When this happens we just call UNWATCH so that
	146	the connection can already be used freely for new transactions.<h2><a name="WATCH used to implement ZPOP">WATCH used to implement ZPOP</a></h2>A good example to illustrate how WATCH can be used to create new atomic
	147	operations otherwise not supported by Redis is to implement ZPOP, that is
	148	a command that pops the element with the lower score from a sorted set
	149	in an atomic way. This is the simplest implementation:
	150	<pre class="codeblock python python python python python python python" name="code">
	151	WATCH zset
	152	ele = ZRANGE zset 0 0
	153	MULTI
	154	ZREM zset ele
	155	EXEC
	156	</pre>
	157	If EXEC fails (returns a nil value) we just re-iterate the operation.<h2><a name="Return value">Return value</a></h2><a href="ReplyTypes.html">Multi bulk reply</a>, specifically:<br/><br/><pre class="codeblock python python python python python python python python" name="code">
	158	The result of a MULTI/EXEC command is a multi bulk reply where every element is the return value of every command in the atomic transaction.
	159	</pre>If a MULTI/EXEC transaction is aborted because of WATCH detected modified keys, a <a href="ReplyTypes.html">Null Multi Bulk reply</a> is returned.
aed57a31	160	</div>
	161
	162	</div>
	163	</div>
	164	</body>
	165	</html>
	166