[redis.git] / doc / ProtocolSpecification.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>ProtocolSpecification: Contents</b><br>&nbsp;&nbsp;<a href="#Protocol Specification">Protocol Specification</a><br>&nbsp;&nbsp;&nbsp;&nbsp;<a href="#Networking layer">Networking layer</a><br>&nbsp;&nbsp;&nbsp;&nbsp;<a href="#Simple INLINE commands">Simple INLINE commands</a><br>&nbsp;&nbsp;&nbsp;&nbsp;<a href="#Bulk commands">Bulk commands</a><br>&nbsp;&nbsp;&nbsp;&nbsp;<a href="#Bulk replies">Bulk replies</a><br>&nbsp;&nbsp;&nbsp;&nbsp;<a href="#Multi-Bulk replies">Multi-Bulk replies</a><br>&nbsp;&nbsp;&nbsp;&nbsp;<a href="#Nil elements in Multi-Bulk replies">Nil elements in Multi-Bulk replies</a><br>&nbsp;&nbsp;&nbsp;&nbsp;<a href="#Single line reply">Single line reply</a><br>&nbsp;&nbsp;&nbsp;&nbsp;<a href="#Integer reply">Integer reply</a><br>&nbsp;&nbsp;&nbsp;&nbsp;<a href="#Multiple commands and pipelining">Multiple commands and pipelining</a>
                </div>
                
                <h1 class="wikiname">ProtocolSpecification</h1>

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

                <div class="narrow">
                    <h1><a name="Protocol Specification">Protocol Specification</a></h1>The Redis protocol is a compromise between being easy to parse by a computer
and being easy to parse by an human. Before reading this section you are
strongly encouraged to read the &quot;REDIS TUTORIAL&quot; section of this README in order
to get a first feeling of the protocol playing with it by TELNET.<h2><a name="Networking layer">Networking layer</a></h2>A client connects to a Redis server creating a TCP connection to the port 6379.
Every redis command or data transmitted by the client and the server is
terminated by &quot;\r\n&quot; (CRLF).<h2><a name="Simple INLINE commands">Simple INLINE commands</a></h2>The simplest commands are the inline commands. This is an example of a
server/client chat (the server chat starts with S:, the client chat with C:)<br/><br/><pre class="codeblock python" name="code">
C: PING
S: +PONG
</pre>An inline command is a CRLF-terminated string sent to the client. The server can reply to commands in different ways:
<ul><li> With an error message (the first byte of the reply will be &quot;-&quot;)</li><li> With a single line reply (the first byte of the reply will be &quot;+)</li><li> With bulk data (the first byte of the reply will be &quot;$&quot;)</li><li> With multi-bulk data, a list of values (the first byte of the reply will be &quot;<code name="code" class="python">*</code>&quot;)</li><li> With an integer number (the first byte of the reply will be &quot;:&quot;)</li></ul>
The following is another example of an INLINE command returning an integer:<br/><br/><pre class="codeblock python python" name="code">
C: EXISTS somekey
S: :0
</pre>Since 'somekey' does not exist the server returned ':0'.<br/><br/>Note that the EXISTS command takes one argument. Arguments are separated
simply by spaces.<h2><a name="Bulk commands">Bulk commands</a></h2>A bulk command is exactly like an inline command, but the last argument
of the command must be a stream of bytes in order to send data to the server.
the &quot;SET&quot; command is a bulk command, see the following example:<br/><br/><pre class="codeblock python python python" name="code">
C: SET mykey 6
C: foobar
S: +OK
</pre>The last argument of the commnad is '6'. This specify the number of DATA
bytes that will follow (note that even this bytes are terminated by two
additional bytes of CRLF).<br/><br/>All the bulk commands are in this exact form: instead of the last argument
the number of bytes that will follow is specified, followed by the bytes,
and CRLF. In order to be more clear for the programmer this is the string
sent by the client in the above sample:<br/><br/><blockquote>&quot;SET mykey 6\r\nfoobar\r\n&quot;</blockquote>
<h2><a name="Bulk replies">Bulk replies</a></h2>The server may reply to an inline or bulk command with a bulk reply. See
the following example:<br/><br/><pre class="codeblock python python python python" name="code">
C: GET mykey
S: $6
S: foobar
</pre>A bulk reply is very similar to the last argument of a bulk command. The
server sends as the first line a &quot;$&quot; byte followed by the number of bytes
of the actual reply followed by CRLF, then the bytes are sent followed by
additional two bytes for the final CRLF. The exact sequence sent by the
server is:<br/><br/><blockquote>&quot;$6\r\nfoobar\r\n&quot;</blockquote>
If the requested value does not exist the bulk reply will use the special
value -1 as data length, example:<br/><br/><pre class="codeblock python python python python python" name="code">
C: GET nonexistingkey
S: $-1
</pre>The client library API should not return an empty string, but a nil object, when the requested object does not exist.
For example a Ruby library should return 'nil' while a C library should return
NULL, and so forth.<h2><a name="Multi-Bulk replies">Multi-Bulk replies</a></h2>Commands similar to LRANGE needs to return multiple values (every element
of the list is a value, and LRANGE needs to return more than a single element). This is accomplished using multiple bulk writes,
prefixed by an initial line indicating how many bulk writes will follow.
The first byte of a multi bulk reply is always <code name="code" class="python">*</code>. Example:<br/><br/><pre class="codeblock python python python python python python" name="code">
C: LRANGE mylist 0 3
S: *4
S: $3
S: foo
S: $3
S: bar
S: $5
S: Hello
S: $5
S: World
</pre>The first line the server sent is &quot;<b>4\r\n&quot; in order to specify that four bulk
write will follow. Then every bulk write is transmitted.<br/><br/>If the specified key does not exist instead of the number of elements in the
list, the special value -1 is sent as count. Example:<br/><br/><pre class="codeblock python python python python python python python" name="code">
C: LRANGE nokey 0 1
S: *-1
</pre>A client library API SHOULD return a nil object and not an empty list when this
happens. This makes possible to distinguish between empty list and non existing ones.<h2><a name="Nil elements in Multi-Bulk replies">Nil elements in Multi-Bulk replies</a></h2>Single elements of a multi bulk reply may have -1 length, in order to signal that this elements are missing and not empty strings. This can happen with the SORT command when used with the GET <i>pattern</i> option when the specified key is missing. Example of a multi bulk reply containing an empty element:<br/><br/><pre class="codeblock python python python python python python python python" name="code">
S: *3
S: $3
S: foo
S: $-1
S: $3
S: bar
</pre>The second element is nul. The client library should return something like this:<br/><br/><pre class="codeblock python python python python python python python python python" name="code">
[&quot;foo&quot;,nil,&quot;bar&quot;]
</pre><h2><a name="Single line reply">Single line reply</a></h2>As already seen a single line reply is in the form of a single line string
starting with &quot;+&quot; terminated by &quot;\r\n&quot;. For example:<br/><br/><pre class="codeblock python python python python python python python python python python" name="code">
+OK
</pre>The client library should return everything after the &quot;+&quot;, that is, the string &quot;OK&quot; in the example.<br/><br/>The following commands reply with a status code reply:
PING, SET, SELECT, SAVE, BGSAVE, SHUTDOWN, RENAME, LPUSH, RPUSH, LSET, LTRIM<h2><a name="Integer reply">Integer reply</a></h2>This type of reply is just a CRLF terminated string representing an integer, prefixed by a &quot;:&quot; byte. For example &quot;:0\r\n&quot;, or &quot;:1000\r\n&quot; are integer replies.<br/><br/>With commands like INCR or LASTSAVE using the integer reply to actually return a value there is no special meaning for the returned integer. It is just an incremental number for INCR, a UNIX time for LASTSAVE and so on.<br/><br/>Some commands like EXISTS will return 1 for true and 0 for false.<br/><br/>Other commands like SADD, SREM and SETNX will return 1 if the operation was actually done, 0 otherwise.<br/><br/>The following commands will reply with an integer reply: SETNX, DEL, EXISTS, INCR, INCRBY, DECR, DECRBY, DBSIZE, LASTSAVE, RENAMENX, MOVE, LLEN, SADD, SREM, SISMEMBER, SCARD<h2><a name="Multiple commands and pipelining">Multiple commands and pipelining</a></h2>A client can use the same connection in order to issue multiple commands.
Pipelining is supported so multiple commands can be sent with a single
write operation by the client, it is not needed to read the server reply
in order to issue the next command. All the replies can be read at the end.<br/><br/>Usually Redis server and client will have a very fast link so this is not
very important to support this feature in a client implementation, still
if an application needs to issue a very large number of commands in short
time to use pipelining can be much faster.
</b>
                </div>
        
            </div>
        </div>
    </body>
</html>
Commit	Line	Data
ed9b544e	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. -->
fab3a740	19	<b>ProtocolSpecification: Contents</b><br>  <a href="#Protocol Specification">Protocol Specification</a><br>    <a href="#Networking layer">Networking layer</a><br>    <a href="#Simple INLINE commands">Simple INLINE commands</a><br>    <a href="#Bulk commands">Bulk commands</a><br>    <a href="#Bulk replies">Bulk replies</a><br>    <a href="#Multi-Bulk replies">Multi-Bulk replies</a><br>    <a href="#Nil elements in Multi-Bulk replies">Nil elements in Multi-Bulk replies</a><br>    <a href="#Single line reply">Single line reply</a><br>    <a href="#Integer reply">Integer reply</a><br>    <a href="#Multiple commands and pipelining">Multiple commands and pipelining</a>
ed9b544e	20	</div>
	21
	22	<h1 class="wikiname">ProtocolSpecification</h1>
	23
	24	<div class="summary">
	25
	26	</div>
	27
	28	<div class="narrow">
	29	<h1><a name="Protocol Specification">Protocol Specification</a></h1>The Redis protocol is a compromise between being easy to parse by a computer
	30	and being easy to parse by an human. Before reading this section you are
	31	strongly encouraged to read the "REDIS TUTORIAL" section of this README in order
4e405577	32	to get a first feeling of the protocol playing with it by TELNET.<h2><a name="Networking layer">Networking layer</a></h2>A client connects to a Redis server creating a TCP connection to the port 6379.
ed9b544e	33	Every redis command or data transmitted by the client and the server is
	34	terminated by "\r\n" (CRLF).<h2><a name="Simple INLINE commands">Simple INLINE commands</a></h2>The simplest commands are the inline commands. This is an example of a
	35	server/client chat (the server chat starts with S:, the client chat with C:)<br/><br/><pre class="codeblock python" name="code">
	36	C: PING
	37	S: +PONG
fab3a740	38	</pre>An inline command is a CRLF-terminated string sent to the client. The server can reply to commands in different ways:
	39	<ul><li> With an error message (the first byte of the reply will be "-")</li><li> With a single line reply (the first byte of the reply will be "+)</li><li> With bulk data (the first byte of the reply will be "$")</li><li> With multi-bulk data, a list of values (the first byte of the reply will be "<code name="code" class="python">*</code>")</li><li> With an integer number (the first byte of the reply will be ":")</li></ul>
	40	The following is another example of an INLINE command returning an integer:<br/><br/><pre class="codeblock python python" name="code">
ed9b544e	41	C: EXISTS somekey
fab3a740	42	S: :0
fab3a740	43	</pre>Since 'somekey' does not exist the server returned ':0'.<br/><br/>Note that the EXISTS command takes one argument. Arguments are separated
ed9b544e	44	simply by spaces.<h2><a name="Bulk commands">Bulk commands</a></h2>A bulk command is exactly like an inline command, but the last argument
	45	of the command must be a stream of bytes in order to send data to the server.
	46	the "SET" command is a bulk command, see the following example:<br/><br/><pre class="codeblock python python python" name="code">
	47	C: SET mykey 6
	48	C: foobar
	49	S: +OK
	50	</pre>The last argument of the commnad is '6'. This specify the number of DATA
	51	bytes that will follow (note that even this bytes are terminated by two
	52	additional bytes of CRLF).<br/><br/>All the bulk commands are in this exact form: instead of the last argument
	53	the number of bytes that will follow is specified, followed by the bytes,
	54	and CRLF. In order to be more clear for the programmer this is the string
	55	sent by the client in the above sample:<br/><br/><blockquote>"SET mykey 6\r\nfoobar\r\n"</blockquote>
	56	<h2><a name="Bulk replies">Bulk replies</a></h2>The server may reply to an inline or bulk command with a bulk reply. See
	57	the following example:<br/><br/><pre class="codeblock python python python python" name="code">
	58	C: GET mykey
fab3a740	59	S: $6
ed9b544e	60	S: foobar
ed9b544e	61	</pre>A bulk reply is very similar to the last argument of a bulk command. The
fab3a740	62	server sends as the first line a "$" byte followed by the number of bytes
	63	of the actual reply followed by CRLF, then the bytes are sent followed by
	64	additional two bytes for the final CRLF. The exact sequence sent by the
	65	server is:<br/><br/><blockquote>"$6\r\nfoobar\r\n"</blockquote>
ed9b544e	66	If the requested value does not exist the bulk reply will use the special
fab3a740	67	value -1 as data length, example:<br/><br/><pre class="codeblock python python python python python" name="code">
ed9b544e	68	C: GET nonexistingkey
fab3a740	69	S: $-1
fab3a740	70	</pre>The client library API should not return an empty string, but a nil object, when the requested object does not exist.
ed9b544e	71	For example a Ruby library should return 'nil' while a C library should return
fab3a740	72	NULL, and so forth.<h2><a name="Multi-Bulk replies">Multi-Bulk replies</a></h2>Commands similar to LRANGE needs to return multiple values (every element
ed9b544e	73	of the list is a value, and LRANGE needs to return more than a single element). This is accomplished using multiple bulk writes,
ed9b544e	74	prefixed by an initial line indicating how many bulk writes will follow.
fab3a740	75	The first byte of a multi bulk reply is always <code name="code" class="python">*</code>. Example:<br/><br/><pre class="codeblock python python python python python python" name="code">
ed9b544e	76	C: LRANGE mylist 0 3
fab3a740	77	S: *4
fab3a740	78	S: $3
ed9b544e	79	S: foo
fab3a740	80	S: $3
ed9b544e	81	S: bar
fab3a740	82	S: $5
ed9b544e	83	S: Hello
fab3a740	84	S: $5
ed9b544e	85	S: World
fab3a740	86	</pre>The first line the server sent is "<b>4\r\n" in order to specify that four bulk
ed9b544e	87	write will follow. Then every bulk write is transmitted.<br/><br/>If the specified key does not exist instead of the number of elements in the
fab3a740	88	list, the special value -1 is sent as count. Example:<br/><br/><pre class="codeblock python python python python python python python" name="code">
ed9b544e	89	C: LRANGE nokey 0 1
fab3a740	90	S: *-1
ed9b544e	91	</pre>A client library API SHOULD return a nil object and not an empty list when this
fab3a740	92	happens. This makes possible to distinguish between empty list and non existing ones.<h2><a name="Nil elements in Multi-Bulk replies">Nil elements in Multi-Bulk replies</a></h2>Single elements of a multi bulk reply may have -1 length, in order to signal that this elements are missing and not empty strings. This can happen with the SORT command when used with the GET <i>pattern</i> option when the specified key is missing. Example of a multi bulk reply containing an empty element:<br/><br/><pre class="codeblock python python python python python python python python" name="code">
	93	S: *3
	94	S: $3
ed9b544e	95	S: foo
fab3a740	96	S: $-1
fab3a740	97	S: $3
ed9b544e	98	S: bar
fab3a740	99	</pre>The second element is nul. The client library should return something like this:<br/><br/><pre class="codeblock python python python python python python python python python" name="code">
ed9b544e	100	["foo",nil,"bar"]
fab3a740	101	</pre><h2><a name="Single line reply">Single line reply</a></h2>As already seen a single line reply is in the form of a single line string
fab3a740	102	starting with "+" terminated by "\r\n". For example:<br/><br/><pre class="codeblock python python python python python python python python python python" name="code">
ed9b544e	103	+OK
fab3a740	104	</pre>The client library should return everything after the "+", that is, the string "OK" in the example.<br/><br/>The following commands reply with a status code reply:
fab3a740	105	PING, SET, SELECT, SAVE, BGSAVE, SHUTDOWN, RENAME, LPUSH, RPUSH, LSET, LTRIM<h2><a name="Integer reply">Integer reply</a></h2>This type of reply is just a CRLF terminated string representing an integer, prefixed by a ":" byte. For example ":0\r\n", or ":1000\r\n" are integer replies.<br/><br/>With commands like INCR or LASTSAVE using the integer reply to actually return a value there is no special meaning for the returned integer. It is just an incremental number for INCR, a UNIX time for LASTSAVE and so on.<br/><br/>Some commands like EXISTS will return 1 for true and 0 for false.<br/><br/>Other commands like SADD, SREM and SETNX will return 1 if the operation was actually done, 0 otherwise.<br/><br/>The following commands will reply with an integer reply: SETNX, DEL, EXISTS, INCR, INCRBY, DECR, DECRBY, DBSIZE, LASTSAVE, RENAMENX, MOVE, LLEN, SADD, SREM, SISMEMBER, SCARD<h2><a name="Multiple commands and pipelining">Multiple commands and pipelining</a></h2>A client can use the same connection in order to issue multiple commands.
ed9b544e	106	Pipelining is supported so multiple commands can be sent with a single
	107	write operation by the client, it is not needed to read the server reply
	108	in order to issue the next command. All the replies can be read at the end.<br/><br/>Usually Redis server and client will have a very fast link so this is not
	109	very important to support this feature in a client implementation, still
	110	if an application needs to issue a very large number of commands in short
fab3a740	111	time to use pipelining can be much faster.
fab3a740	112	</b>
ed9b544e	113	</div>
	114
	115	</div>
	116	</div>
	117	</body>
	118	</html>
	119