[redis.git] / doc / SortCommand.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>SortCommand: Contents</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<a href="#Sorting by external keys">Sorting by external keys</a><br>&nbsp;&nbsp;&nbsp;&nbsp;<a href="#Not Sorting at all">Not Sorting at all</a><br>&nbsp;&nbsp;&nbsp;&nbsp;<a href="#Retrieving external keys">Retrieving external keys</a><br>&nbsp;&nbsp;&nbsp;&nbsp;<a href="#Storing the result of a SORT operation">Storing the result of a SORT operation</a><br>&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SORT and Hashes: BY and GET by hash field">SORT and Hashes: BY and GET by hash field</a><br>&nbsp;&nbsp;&nbsp;&nbsp;<a href="#Return value">Return value</a>
                </div>
                
                <h1 class="wikiname">SortCommand</h1>

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

                <div class="narrow">
                    &iuml;&raquo;&iquest;= SORT <i>key</i> <code name="code" class="python">[</code>BY <i>pattern</i><code name="code" class="python">]</code> <code name="code" class="python">[</code>LIMIT <i>start</i> <i>count</i><code name="code" class="python">]</code> <code name="code" class="python">[</code>GET <i>pattern</i><code name="code" class="python">]</code> <code name="code" class="python">[</code>ASC|DESC<code name="code" class="python">]</code> <code name="code" class="python">[</code>ALPHA<code name="code" class="python">]</code> <code name="code" class="python">[</code>STORE <i>dstkey</i><code name="code" class="python">]</code> =
<blockquote>Sort the elements contained in the <a href="Lists.html">List</a>, <a href="Sets.html">Set</a>, or<a href="SortedSets.html">Sorted Set</a> value at <i>key</i>. By defaultsorting is numeric with elements being compared as double precisionfloating point numbers. This is the simplest form of SORT:</blockquote>
<pre class="codeblock python" name="code">
SORT mylist
</pre><blockquote>Assuming mylist contains a list of numbers, the return value will bethe list of numbers ordered from the smallest to the biggest number.In order to get the sorting in reverse order use <b>DESC</b>:</blockquote>
<pre class="codeblock python python" name="code">
SORT mylist DESC
</pre><blockquote>The <b>ASC</b> option is also supported but it's the default so you don'treally need it.If you want to sort lexicographically use <b>ALPHA</b>. Note that Redis isutf-8 aware assuming you set the right value for the LC_COLLATEenvironment variable.</blockquote>
<blockquote>Sort is able to limit the number of returned elements using the <b>LIMIT</b> option:</blockquote>
<pre class="codeblock python python python" name="code">
SORT mylist LIMIT 0 10
</pre><blockquote>In the above example SORT will return only 10 elements, starting fromthe first one (start is zero-based). Almost all the sort options canbe mixed together. For example the command:</blockquote>
<pre class="codeblock python python python python" name="code">
SORT mylist LIMIT 0 10 ALPHA DESC
</pre><blockquote>Will sort <i>mylist</i> lexicographically, in descending order, returning onlythe first 10 elements.</blockquote>
<blockquote>Sometimes you want to sort elements using external keys as weights tocompare instead to compare the actual List Sets or Sorted Set elements.For example the list <i>mylist</i> may contain the elements 1, 2, 3, 4, thatare just unique IDs of objects stored at object_1, object_2, object_3and object_4, while the keys weight_1, weight_2, weight_3 and weight_4can contain weights we want to use to sort our list of objectsidentifiers. We can use the following command:</blockquote>
<h2><a name="Sorting by external keys">Sorting by external keys</a></h2><pre class="codeblock python python python python python" name="code">
SORT mylist BY weight_*
</pre><blockquote>the <b>BY</b> option takes a pattern (<code name="code" class="python">weight_*</code> in our example) that is usedin order to generate the key names of the weights used for sorting.Weight key names are obtained substituting the first occurrence of <code name="code" class="python">*</code>with the actual value of the elements on the list (1,2,3,4 in our example).</blockquote>
<blockquote>Our previous example will return just the sorted IDs. Often it isneeded to get the actual objects sorted (object_1, ..., object_4 in theexample). We can do it with the following command:</blockquote>
<h2><a name="Not Sorting at all">Not Sorting at all</a></h2><pre class="codeblock python python python python python python" name="code">
SORT mylist BY nosort
</pre><blockquote>also the <b>BY</b> option can take a &quot;nosort&quot; specifier. This is useful if you want to retrieve a external key (using GET, read below) but you don't want the sorting overhead.</blockquote>
<h2><a name="Retrieving external keys">Retrieving external keys</a></h2><pre class="codeblock python python python python python python python" name="code">
SORT mylist BY weight_* GET object_*
</pre><blockquote>Note that <b>GET</b> can be used multiple times in order to get more keys forevery element of the original List, Set or Sorted Set sorted.</blockquote>
<blockquote>Since Redis &gt;= 1.1 it's possible to also GET the list elements itselfusing the special # pattern:</blockquote>
<pre class="codeblock python python python python python python python python" name="code">
SORT mylist BY weight_* GET object_* GET #
</pre><h2><a name="Storing the result of a SORT operation">Storing the result of a SORT operation</a></h2><blockquote>By default SORT returns the sorted elements as its return value.Using the <b>STORE</b> option instead to return the elements SORT willstore this elements as a <a href="Lists.html">Redis List</a> in the specified key.An example:</blockquote>
<pre class="codeblock python python python python python python python python python" name="code">
SORT mylist BY weight_* STORE resultkey
</pre><blockquote>An interesting pattern using SORT ... STORE consists in associatingan <a href="ExpireCommand.html">EXPIRE</a> timeout to the resulting key so that inapplications where the result of a sort operation can be cached forsome time other clients will use the cached list instead to call SORTfor every request. When the key will timeout an updated version ofthe cache can be created using SORT ... STORE again.</blockquote>
<blockquote>Note that implementing this pattern it is important to avoid that multipleclients will try to rebuild the cached version of the cacheat the same time, so some form of locking should be implemented(for instance using <a href="SetnxCommand.html">SETNX</a>).</blockquote>
<h2><a name="SORT and Hashes: BY and GET by hash field">SORT and Hashes: BY and GET by hash field</a></h2>
<blockquote>It's possible to use BY and GET options against Hash fields using the following syntax:</blockquote><pre class="codeblock python python python python python python python python python python" name="code">
SORT mylist BY weight_*-&gt;fieldname
SORT mylist GET object_*-&gt;fieldname
</pre>
<blockquote>The two chars string -&gt; is used in order to signal the name of the Hash field. The key is substituted as documented above with sort BY and GET against normal keys, and the Hash stored at the resulting key is accessed in order to retrieve the specified field.</blockquote><h2><a name="Return value">Return value</a></h2><a href="ReplyTypes.html">Multi bulk reply</a>, specifically a list of sorted elements.
                </div>
        
            </div>
        </div>
    </body>
</html>
Commit	Line	Data
8fb13ce8	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. -->
5d373da9	19	<b>SortCommand: Contents</b><br>    <a href="#Sorting by external keys">Sorting by external keys</a><br>    <a href="#Not Sorting at all">Not Sorting at all</a><br>    <a href="#Retrieving external keys">Retrieving external keys</a><br>    <a href="#Storing the result of a SORT operation">Storing the result of a SORT operation</a><br>    <a href="#SORT and Hashes: BY and GET by hash field">SORT and Hashes: BY and GET by hash field</a><br>    <a href="#Return value">Return value</a>
8fb13ce8	20	</div>
	21
	22	<h1 class="wikiname">SortCommand</h1>
	23
	24	<div class="summary">
	25
	26	</div>
	27
	28	<div class="narrow">
	29	ï»¿= SORT <i>key</i> <code name="code" class="python">[</code>BY <i>pattern</i><code name="code" class="python">]</code> <code name="code" class="python">[</code>LIMIT <i>start</i> <i>count</i><code name="code" class="python">]</code> <code name="code" class="python">[</code>GET <i>pattern</i><code name="code" class="python">]</code> <code name="code" class="python">[</code>ASC\|DESC<code name="code" class="python">]</code> <code name="code" class="python">[</code>ALPHA<code name="code" class="python">]</code> <code name="code" class="python">[</code>STORE <i>dstkey</i><code name="code" class="python">]</code> =
	30	<blockquote>Sort the elements contained in the <a href="Lists.html">List</a>, <a href="Sets.html">Set</a>, or<a href="SortedSets.html">Sorted Set</a> value at <i>key</i>. By defaultsorting is numeric with elements being compared as double precisionfloating point numbers. This is the simplest form of SORT:</blockquote>
	31	<pre class="codeblock python" name="code">
	32	SORT mylist
	33	</pre><blockquote>Assuming mylist contains a list of numbers, the return value will bethe list of numbers ordered from the smallest to the biggest number.In order to get the sorting in reverse order use <b>DESC</b>:</blockquote>
	34	<pre class="codeblock python python" name="code">
	35	SORT mylist DESC
	36	</pre><blockquote>The <b>ASC</b> option is also supported but it's the default so you don'treally need it.If you want to sort lexicographically use <b>ALPHA</b>. Note that Redis isutf-8 aware assuming you set the right value for the LC_COLLATEenvironment variable.</blockquote>
	37	<blockquote>Sort is able to limit the number of returned elements using the <b>LIMIT</b> option:</blockquote>
	38	<pre class="codeblock python python python" name="code">
	39	SORT mylist LIMIT 0 10
	40	</pre><blockquote>In the above example SORT will return only 10 elements, starting fromthe first one (start is zero-based). Almost all the sort options canbe mixed together. For example the command:</blockquote>
	41	<pre class="codeblock python python python python" name="code">
	42	SORT mylist LIMIT 0 10 ALPHA DESC
	43	</pre><blockquote>Will sort <i>mylist</i> lexicographically, in descending order, returning onlythe first 10 elements.</blockquote>
	44	<blockquote>Sometimes you want to sort elements using external keys as weights tocompare instead to compare the actual List Sets or Sorted Set elements.For example the list <i>mylist</i> may contain the elements 1, 2, 3, 4, thatare just unique IDs of objects stored at object_1, object_2, object_3and object_4, while the keys weight_1, weight_2, weight_3 and weight_4can contain weights we want to use to sort our list of objectsidentifiers. We can use the following command:</blockquote>
	45	<h2><a name="Sorting by external keys">Sorting by external keys</a></h2><pre class="codeblock python python python python python" name="code">
	46	SORT mylist BY weight_*
	47	</pre><blockquote>the <b>BY</b> option takes a pattern (<code name="code" class="python">weight_</code> in our example) that is usedin order to generate the key names of the weights used for sorting.Weight key names are obtained substituting the first occurrence of <code name="code" class="python"></code>with the actual value of the elements on the list (1,2,3,4 in our example).</blockquote>
	48	<blockquote>Our previous example will return just the sorted IDs. Often it isneeded to get the actual objects sorted (object_1, ..., object_4 in theexample). We can do it with the following command:</blockquote>
5d373da9	49	<h2><a name="Not Sorting at all">Not Sorting at all</a></h2><pre class="codeblock python python python python python python" name="code">
	50	SORT mylist BY nosort
	51	</pre><blockquote>also the <b>BY</b> option can take a "nosort" specifier. This is useful if you want to retrieve a external key (using GET, read below) but you don't want the sorting overhead.</blockquote>
	52	<h2><a name="Retrieving external keys">Retrieving external keys</a></h2><pre class="codeblock python python python python python python python" name="code">
8fb13ce8	53	SORT mylist BY weight_* GET object_*
	54	</pre><blockquote>Note that <b>GET</b> can be used multiple times in order to get more keys forevery element of the original List, Set or Sorted Set sorted.</blockquote>
	55	<blockquote>Since Redis >= 1.1 it's possible to also GET the list elements itselfusing the special # pattern:</blockquote>
5d373da9	56	<pre class="codeblock python python python python python python python python" name="code">
8fb13ce8	57	SORT mylist BY weight_* GET object_* GET #
8fb13ce8	58	</pre><h2><a name="Storing the result of a SORT operation">Storing the result of a SORT operation</a></h2><blockquote>By default SORT returns the sorted elements as its return value.Using the <b>STORE</b> option instead to return the elements SORT willstore this elements as a <a href="Lists.html">Redis List</a> in the specified key.An example:</blockquote>
5d373da9	59	<pre class="codeblock python python python python python python python python python" name="code">
8fb13ce8	60	SORT mylist BY weight_* STORE resultkey
	61	</pre><blockquote>An interesting pattern using SORT ... STORE consists in associatingan <a href="ExpireCommand.html">EXPIRE</a> timeout to the resulting key so that inapplications where the result of a sort operation can be cached forsome time other clients will use the cached list instead to call SORTfor every request. When the key will timeout an updated version ofthe cache can be created using SORT ... STORE again.</blockquote>
	62	<blockquote>Note that implementing this pattern it is important to avoid that multipleclients will try to rebuild the cached version of the cacheat the same time, so some form of locking should be implemented(for instance using <a href="SetnxCommand.html">SETNX</a>).</blockquote>
ab72b483	63	<h2><a name="SORT and Hashes: BY and GET by hash field">SORT and Hashes: BY and GET by hash field</a></h2>
5d373da9	64	<blockquote>It's possible to use BY and GET options against Hash fields using the following syntax:</blockquote><pre class="codeblock python python python python python python python python python python" name="code">
ab72b483	65	SORT mylist BY weight_*->fieldname
	66	SORT mylist GET object_*->fieldname
	67	</pre>
	68	<blockquote>The two chars string -> is used in order to signal the name of the Hash field. The key is substituted as documented above with sort BY and GET against normal keys, and the Hash stored at the resulting key is accessed in order to retrieve the specified field.</blockquote><h2><a name="Return value">Return value</a></h2><a href="ReplyTypes.html">Multi bulk reply</a>, specifically a list of sorted elements.
8fb13ce8	69	</div>
	70
	71	</div>
	72	</div>
	73	</body>
	74	</html>
	75