mirror of
http://github.com/valkey-io/valkey
synced 2024-11-21 16:46:15 +00:00
protocol doc changed
This commit is contained in:
antirez
parent
c937aa89b5
commit
fab3a740ab
File diff suppressed because one or more lines are too long
@ -16,7 +16,7 @@
|
||||
<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> <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="#Bulk reply error reporting">Bulk reply error reporting</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="#Multi-Bulk replies errors">Multi-Bulk replies errors</a><br> <a href="#Status code reply">Status code reply</a><br> <a href="#Integer reply">Integer reply</a><br> <a href="#Single line reply">Single line reply</a><br> <a href="#Multiple commands and pipelining">Multiple commands and pipelining</a>
|
||||
<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>
|
||||
</div>
|
||||
|
||||
<h1 class="wikiname">ProtocolSpecification</h1>
|
||||
@ -35,14 +35,12 @@ terminated by "\r\n" (CRLF).<h2><a name="Simple INLINE commands">Simpl
|
||||
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
|
||||
usually replies to inline commands with a single line that can be a number
|
||||
or a return code.<br/><br/>When the server replies with a status code (that is a one line reply just indicating if the operation succeeded or not), if the first character of the
|
||||
reply is a "+" then the command succeeded, if it is a "-" then the following
|
||||
part of the string is an error.<br/><br/>The following is another example of an INLINE command returning an integer:<br/><br/><pre class="codeblock python python" name="code">
|
||||
</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 "-")</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>
|
||||
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
|
||||
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 "SET" command is a bulk command, see the following example:<br/><br/><pre class="codeblock python python python" name="code">
|
||||
@ -58,82 +56,60 @@ sent by the client in the above sample:<br/><br/><blockquote>"SET mykey 6\r
|
||||
<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: $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 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>"6\r\nfoobar\r\n"</blockquote>
|
||||
server sends as the first line a "$" 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>"$6\r\nfoobar\r\n"</blockquote>
|
||||
If the requested value does not exist the bulk reply will use the special
|
||||
value 'nil' instead to send the line containing the number of bytes to read.
|
||||
This is an example:<br/><br/><pre class="codeblock python python python python python" name="code">
|
||||
value -1 as data length, example:<br/><br/><pre class="codeblock python python python python python" name="code">
|
||||
C: GET nonexistingkey
|
||||
S: nil
|
||||
</pre>The client library API should not return an empty string, but a nil object.
|
||||
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.<h2><a name="Bulk reply error reporting">Bulk reply error reporting</a></h2>Bulk replies can signal errors, for example trying to use GET against a list
|
||||
value is not permitted. Bulk replies use a negative bytes count in order to
|
||||
signal an error. An error string of ABS(bytes_count) bytes will follow. See
|
||||
the following example:<br/><br/><pre class="codeblock python python python python python python" name="code">
|
||||
S: GET alistkey
|
||||
S: -38
|
||||
S: -ERR Requested element is not a string
|
||||
</pre>-38 means: sorry your operation resulted in an error, but a 38 bytes string
|
||||
that explains this error will follow. Client APIs should abort on this kind
|
||||
of errors, for example a PHP client should call the die() function.<br/><br/>The following commands reply with a bulk reply: GET, KEYS, LINDEX, LPOP, RPOP<h2><a name="Multi-Bulk replies">Multi-Bulk replies</a></h2>Commands similar to LRANGE needs to return multiple values (every element
|
||||
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.
|
||||
Example:<br/><br/><pre class="codeblock python python python python python python python" name="code">
|
||||
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: *4
|
||||
S: $3
|
||||
S: foo
|
||||
S: 3
|
||||
S: $3
|
||||
S: bar
|
||||
S: 5
|
||||
S: $5
|
||||
S: Hello
|
||||
S: 5
|
||||
S: $5
|
||||
S: World
|
||||
</pre>The first line the server sent is "4\r\n" in order to specify that four bulk
|
||||
</pre>The first line the server sent is "<b>4\r\n" 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 'nil' is sent. Example:<br/><br/><pre class="codeblock python python python python python python python python" name="code">
|
||||
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: nil
|
||||
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 python" name="code">
|
||||
S: 3
|
||||
S: 3
|
||||
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: $-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 python" name="code">
|
||||
</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">
|
||||
["foo",nil,"bar"]
|
||||
</pre><h2><a name="Multi-Bulk replies errors">Multi-Bulk replies errors</a></h2>Like bulk reply errors Multi-bulk reply errors are reported using a negative
|
||||
count. Example:<br/><br/><pre class="codeblock python python python python python python python python python python python" name="code">
|
||||
C: LRANGE stringkey 0 1
|
||||
S: -38
|
||||
S: -ERR Requested element is not a string
|
||||
</pre>The following commands reply with a multi-bulk reply: LRANGE, LINTER<br/><br/>Check the Bulk replies errors section for more information.<h2><a name="Status code reply">Status code reply</a></h2>As already seen a status code reply is in the form of a single line string
|
||||
terminated by "\r\n". For example:<br/><br/><pre class="codeblock python python python python python python python python python python python python" name="code">
|
||||
</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 "+" terminated by "\r\n". For example:<br/><br/><pre class="codeblock python python python python python python python python python python" name="code">
|
||||
+OK
|
||||
</pre>and<br/><br/><pre class="codeblock python python python python python python python python python python python python python" name="code">
|
||||
-ERR no suck key
|
||||
</pre>are two examples of status code replies. The first character of a status code reply is always "+" or "-".<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. 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, and <b>a negative value</b> if the operation is invalid (for example SADD against a non-set value), accordingly to this table:
|
||||
<pre class="codeblock python python python python python python python python python python python python python python" name="code">
|
||||
-1 no such key
|
||||
-2 operation against the a key holding a value of the wrong type
|
||||
-3 source and destiantion objects/dbs are the same
|
||||
-4 argument out of range
|
||||
</pre>
|
||||
In all this cases it is mandatory that the client raises an error instead to pass the negative value to the caller. Please check the commands documentation for the exact behaviour.<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<br/><br/>The commands that will never return a negative integer (commands that can't fail) are: INCR, DECR, INCRBY, DECRBY, LASTSAVE, EXISTS, SETNX, DEL, DBSIZE.<h2><a name="Single line reply">Single line reply</a></h2>This replies are just single line strings terminated by CRLF. Only two commands reply in this way currently, RANDOMKEY and TYPE.<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.
|
||||
</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:
|
||||
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.
|
||||
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.<br/><br/>
|
||||
time to use pipelining can be much faster.
|
||||
</b>
|
||||
</div>
|
||||
|
||||
</div>
|
||||
|
||||
Loading…
Reference in New Issue
Block a user