X-Git-Url: https://git.saurik.com/redis.git/blobdiff_plain/924aa408b99837036b679bd3895f836af6bc763f..12ebe2ac17a26ecf263f90b2acdf03db29b00223:/doc/README.html
diff --git a/doc/README.html b/doc/README.html
index 38242aa0..c71d6386 100644
--- a/doc/README.html
+++ b/doc/README.html
@@ -16,7 +16,7 @@
-
Redis is a database. To be specific, Redis is a very simple database implementing a dictionary, where every key is associated with a value. For example I can set the key "surname_1992" to the string "Smith".
-What makes Redis different from many other key-value stores, is that every single value has a type. The following types are supported:
- String
- List
- Set
- Sorted Set (since version 1.1)
-The type of a value determines what operations (called commands) are available for the value itself.
-For example you can append elements to a list stored at the key "mylist" using the LPUSH or RPUSH command in O(1). Later you'll be able to get a range of elements with LRANGE or trim the list with LTRIM. Sets are very flexible too, it is possible to add and remove elements from Sets (unsorted collections of strings), and then ask for server-side intersection, union, difference of Sets. Each command is performed through server-side atomic operations.
-Please refer to the
Command Reference to see the full list of operations associated to these data types.
In other words, you can look at Redis as a data structures server. A Redis user is virtually provided with an interface to
Abstract Data Types, saving her from the responsibility to implement concrete data structures and algorithms. Indeed both algorithms and data structures in Redis are properly choosed in order to obtain the best performance.
Redis loads and mantains the whole dataset into memory, but the dataset is persistent, since from time to time Redis writes a dump on disk asynchronously. The dataset is loaded from the dump every time the server is (re)started.
Redis can be configured to save the dataset when a certain number of changes is reached and after a given number of seconds elapses. For example, you can configure Redis to save after 1000 changes and at most 60 seconds since the last save. You can specify any combination for these numbers.
Because data is written asynchronously, when a system crash occurs, the last few queries can get lost (that is acceptable in many applications). Anyway it is possible to make this a non issue, since Redis supports master-slave replication from its early days, being effective even in the case where a few records lost are not acceptable.
All these features allow to use Redis as the sole DB for your scalable application without the need of any relational database.
We wrote a simple Twitter clone in PHP + Redis to show a real world example, the link points to an article explaining the design and internals in very simple words.
In the following ways:
- Memcached is not persistent, it just holds everything in memory without saving since its main goal is to be used as a cache. Redis instead can be used as the main DB for the application. We wrote a simple Twitter clone using only Redis as database.
-
- Like memcached Redis uses a key-value model, but while keys can just be strings, values in Redis can be lists and sets, and complex operations like intersections, set/get n-th element of lists, pop/push of elements, can be performed against sets and lists. It is possible to use lists as message queues.
-
Redis and Tokyo Cabinet can be used for the same applications, but actually they are
very different beasts. If you read twitter messages of people involved in scalable things both products are reported to work well, but surely there are times where one or the other can be the best choice. Some differences are the followings (I may be biased, make sure to check yourself both the products).
- Tokyo Cabinet writes synchronously on disk, Redis takes the whole dataset on memory and writes on disk asynchronously. Tokyo Cabinet is safer and probably a better idea if your dataset is going to be bigger than RAM, but Redis is faster (note that Redis supports master-slave replication that is trivial to setup, so you are safe anyway if you want a setup where data can't be lost even after a disaster).
-
- Redis supports higher level operations and data structures. Tokyo Cabinet supports a kind of database that is able to organize data into rows with named fields (in a way very similar to Berkeley DB) but can't do things like server side List and Set operations Redis is able to do: pushing or popping from Lists in an atomic way, in O(1) time complexity, server side Set intersections, SortCommand ing of schema free data in complex ways (Btw TC supports sorting in the table-based database format). Redis on the other hand does not support the abstraction of tables with fields, the idea is that you can build this stuff in software easily if you really need a table-alike approach.
-
- Tokyo Cabinet does not implement a networking layer. You have to use a networking layer called Tokyo Tyrant that interfaces to Tokyo Cabinet so you can talk to Tokyo Cabinet in a client-server fashion. In Redis the networking support is built-in inside the server, and is basically the only interface between the external world and the dataset.
-
- Redis is reported to be much faster, especially if you plan to access Tokyo Cabinet via Tokyo Tyrant. Here I can only say that with Redis you can expect 100,000 operations/seconds with a normal Linux box and 50 concurrent clients. You should test Redis, Tokyo, and the other alternatives with your specific work load to get a feeling about performances for your application.
-
- Redis is not an on-disk DB engine like Tokyo: the latter can be used as a fast DB engine in your C project without the networking overhead just linking to the library. Still in many scalable applications you need multiple servers talking with multiple clients, so the client-server model is almost always needed, this is why in Redis this is built-in.
-
No, the idea is to provide atomic primitives in order to make the programmer
-able to use redis with locking free algorithms. For example imagine you have
-10 computers and one Redis server. You want to count words in a very large text.
-This large text is split among the 10 computers, every computer will process
-its part and use Redis's INCR command to atomically increment a counter
-for every occurrence of the word found.
INCR/DECR are not the only atomic primitives, there are others like PUSH/POP
-on lists, POP RANDOM KEY operations, UPDATE and so on. For example you can
-use Redis like a Tuple Space (
http://en.wikipedia.org/wiki/Tuple_space) in
-order to implement distributed algorithms.
(News: locking with key-granularity is now planned)
Another synchronization primitive is the support for multiple DBs. By default DB 0 is selected for every new connection, but using the SELECT command it is possible to select a different database. The MOVE operation can move an item from one DB to another atomically. This can be used as a base for locking free algorithms together with the 'RANDOMKEY' commands.
Redis supports the following three data types as values:
- Strings: just any sequence of bytes. Redis strings are binary safe so they can not just hold text, but images, compressed data and everything else.
- Lists: lists of strings, with support for operations like append a new string on head, on tail, list length, obtain a range of elements, truncate the list to a given length, sort the list, and so on.
- Sets: an unsorted set of strings. It is possible to add or delete elements from a set, to perform set intersection, union, subtraction, and so on.
-Values can be Strings, Lists or Sets. Keys can be a subset of strings not containing newlines ("\n") and spaces (" ").
Note that sometimes strings may hold numeric vaules that must be parsed by
-Redis. An example is the INCR command that atomically increments the number
-stored at the specified key. In this case Redis is able to handle integers
-that can be stored inside a 'long long' type, that is a 64-bit signed integer.
Strings are implemented as dynamically allocated strings of characters.
-Lists are implemented as doubly linked lists with cached length.
-Sets are implemented using hash tables that use chaining to resolve collisions.
(note, you can skip this section if you are only interested in "formal" doc.)
Later in this document you can find detailed information about Redis commands,
+ = Introduction =
Redis is an extremely fast and powerful key-value store database and server implemented in ANSI C. Redis offers many different ways to do one straightforward thing: store a value ("antirez") to a key ("redis"). While the format of keys must always be simple strings, the power is with the values, which support the following data types:
+Each value type has an associated list of commands which can operate on them, and the
The Redis Command Reference contains an up to date list of these commands, organized primarily by data type. The Redis source also includes a
Redis command line interface which allows you to interact directly with the server, and is the means by which this introduction will provide examples. Once you walk through the
Redis Quick Start Guide to get your instance of Redis running, you can follow along.
One of the most powerful aspects of Redis is the wide range of commands which are optimized to work with specific data value types and executed as atomic server-side operations. The
List type is a great example - Redis implements O(1) operations such as
LPUSH or
RPUSH, which have accompanying
LPOP and
RPOP methods:
+redis> lpush programming_languages C
+OK
+redis> lpush programming_languages Ruby
+OK
+redis> rpush programming_languages Python
+OK
+redis> rpop programming_languages
+Python
+redis> lpop programming_languages
+Ruby
+
More complex operations are available for each data type as well. Continuing with lists, you can get a range of elements with
LRANGE (O(start+n)) or trim the list with
LTRIM (O(n)):
+redis> lpush cities NYC
+OK
+redis> lpush cities SF
+OK
+redis> lpush cities Tokyo
+OK
+redis> lpush cities London
+OK
+redis> lpush cities Paris
+OK
+redis> lrange cities 0 2
+1. Paris
+2. London
+3. Tokyo
+redis> ltrim cities 0 1
+OK
+redis> lpop cities
+Paris
+redis> lpop cities
+London
+redis> lpop cities
+(nil)
+
You can also add and remove elements from a set, and perform intersections, unions, and differences.
Redis can also be looked at as a data structures server. A Redis user is virtually provided with an interface to
Abstract Data Types, saving them from the responsibility of implementing concrete data structures and algorithms -- indeed both algorithms and data structures in Redis are properly chosen in order to obtain the best performance.
Redis loads and mantains the whole dataset into memory, but the dataset is persistent, since at the same time it is saved on disk, so that when the server is restarted data can be loaded back in memory.
There are two kinds of persistence supported: the first one is called snapshotting. In this mode Redis periodically writes to disk asynchronously. The dataset is loaded from the dump every time the server is (re)started.
Redis can be configured to save the dataset when a certain number of changes is reached and after a given number of seconds elapses. For example, you can configure Redis to save after 1000 changes and at most 60 seconds since the last save. You can specify any combination for these numbers.
Because data is written asynchronously, when a system crash occurs, the last few queries can get lost (that is acceptable in many applications but not in all). In order to make this a non issue Redis supports another, safer persistence mode, called
Append Only File, where every command received altering the dataset (so not a read-only command, but a write command) is written on an append only file ASAP. This commands are
replayed when the server is restarted in order to rebuild the dataset in memory.
Redis Append Only File supports a very handy feature: the server is able to safely rebuild the append only file in background in a non-blocking fashion when it gets too long. You can find
more details in the Append Only File HOWTO.
Whatever will be the persistence mode you'll use Redis supports master-slave replications if you want to stay really safe or if you need to scale to huge amounts of reads.
Redis Replication is trivial to setup. So trivial that all you need to do in order to configure a Redis server to be a slave of another one, with automatic synchronization if the link will go down and so forth, is the following config line:
slaveof 192.168.1.100 6379
.
We provide a Replication Howto if you want to know more about this feature.
Redis can be used as a
memcached on steroids because is as fast as memcached but with a number of features more. Like memcached, Redis also supports setting timeouts to keys so that this key will be automatically removed when a given amount of time passes.
All these features allow to use Redis as the sole DB for your scalable application without the need of any relational database.
We wrote a simple Twitter clone in PHP + Redis to show a real world example, the link points to an article explaining the design and internals in very simple words.
Redis supports multiple databases with commands to atomically move keys from one database to the other. By default DB 0 is selected for every new connection, but using the SELECT command it is possible to select a different database. The MOVE operation can move an item from one DB to another atomically. This can be used as a base for locking free algorithms together with the 'RANDOMKEY' commands.
To really get a feeling about what Redis is and how it works please try reading
A fifteen minutes introduction to Redis data types.
To know a bit more about how Redis works
internally continue reading.
(note, you can skip this section if you are only interested in "formal" doc.)
Later in this document you can find detailed information about Redis commands,
the protocol specification, and so on. This kind of documentation is useful
but... if you are new to Redis it is also BORING! The Redis protocol is designed
so that is both pretty efficient to be parsed by computers, but simple enough
@@ -61,7 +71,7 @@ feeling about it, and how it works.
To start just compile redis with 'm
The server will start and log stuff on the standard output, if you want
it to log more edit redis.conf, set the loglevel to debug, and restart it.
You can specify a configuration file as unique parameter:
./redis-server /etc/redis.conf
This is NOT required. The server will start even without a configuration file
-using a default built-in configuration.
Now let's try to set a key to a given value:
+using a default built-in configuration.
Now let's try to set a key to a given value:
$ telnet localhost 6379
Trying 127.0.0.1...
Connected to localhost.
@@ -80,17 +90,17 @@ the point of view of both the server and client but allows us to play with
Redis with the telnet command easily.
The last line of the chat between server and client is "+OK". This means
our key was added without problems. Actually SET can never fail but
the "+OK" sent lets us know that the server received everything and
-the command was actually executed.
Let's try to get the key content now:
+the command was actually executed.
Let's try to get the key content now:
GET foo
$3
bar
Ok that's very similar to 'set', just the other way around. We sent "get foo",
the server replied with a first line that is just the $ character follwed by
the number of bytes the value stored at key contained, followed by the actual
-bytes. Again "\r\n" are appended both to the bytes count and the actual data. In Redis slang this is called a bulk reply.
What about requesting a non existing key?
+bytes. Again "\r\n" are appended both to the bytes count and the actual data. In Redis slang this is called a bulk reply.
What about requesting a non existing key?
GET blabla
$-1
-
When the key does not exist instead of the length, just the "$-1" string is sent. Since a -1 length of a bulk reply has no meaning it is used in order to specifiy a 'nil' value and distinguish it from a zero length value. Another way to check if a given key exists or not is indeed the EXISTS command:
+
When the key does not exist instead of the length, just the "$-1" string is sent. Since a -1 length of a bulk reply has no meaning it is used in order to specifiy a 'nil' value and distinguish it from a zero length value. Another way to check if a given key exists or not is indeed the EXISTS command:
EXISTS nokey
:0
EXISTS foo
@@ -99,8 +109,7 @@ EXISTS foo
exist, and ':1' for 'foo', a key that actually exists. Replies starting with the colon character are integer reply.
Ok... now you know the basics, read the REDIS COMMAND REFERENCE section to
learn all the commands supported by Redis and the PROTOCOL SPECIFICATION
section for more details about the protocol used if you plan to implement one
-for a language missing a decent client implementation.Redis is released under the BSD license. See the COPYING file for more information.Redis is written and maintained by Salvatore Sanfilippo, Aka 'antirez'.
Enjoy,
-antirez
+for a language missing a decent client implementation.Redis is released under the BSD license. See the COPYING file for more information.Redis is written and maintained by Salvatore Sanfilippo, Aka 'antirez'.