From e1e598a2ec236b97b90d9fea00c9eb930e4e8987 Mon Sep 17 00:00:00 2001
From: ocelot-inc <pgulutzan@ocelot.ca>
Date: Sun, 24 Aug 2014 11:44:47 -0600
Subject: [PATCH] revised description of select
---
doc/user/databases.xml | 65 +++++++++++++++++++++++++---------
doc/user/iterator-types.xml | 14 ++++----
doc/user/stored-procedures.xml | 2 +-
3 files changed, 56 insertions(+), 25 deletions(-)
diff --git a/doc/user/databases.xml b/doc/user/databases.xml
index ffc46ed98c..881595c0c1 100644
--- a/doc/user/databases.xml
+++ b/doc/user/databases.xml
@@ -380,14 +380,17 @@ tarantool> <userinput>s:create_index('primary', {unique = true, parts = {1, 'NUM
</term>
<listitem>
<para>
- Search for a tuple in the given space.
+ Search for a tuple or a set of tuples in the given space.
</para>
<para>
Parameters: (type = tuple, as a Lua table) <code>field-value(s)</code>—
= values to be matched against the index key, which may be multi-part.
</para>
<para>
- Returns: (type = tuple set, as a Lua table) the selected tuple.
+ Returns: (type = tuple set, as a Lua table) the tuples whose primary-key fields
+ are equal to the passed field-values. If the number of passed field-values is
+ less than the number of fields in the primary key, then only the passed field-values are
+ compared, so <code>select{1,2}</code> will match a tuple whose primary key is {1,2,3}.
</para>
<para>
Complexity Factors: Index size, Index type.
@@ -396,28 +399,50 @@ tarantool> <userinput>s:create_index('primary', {unique = true, parts = {1, 'NUM
Possible Errors: No such space; wrong type.
<bridgehead renderas="sect4">Example</bridgehead>
<programlisting>
-tarantool> <userinput>box.space.tester:insert{101, 'test#1', 'my first tuple'}</userinput>
+tarantool> <userinput>s = box.schema.create_space('tmp', {temporary=true})</userinput>
---
-- [101, 'test#1', 'my first tuple']
...
-tarantool> <userinput>box.space.tester:select{101}</userinput>
+tarantool> <userinput> s:create_index('primary',{parts = {1,'NUM', 2, 'STR'}})</userinput>
---
-- - [101, 'test#1', 'my first tuple']
...
-tarantool> <userinput>box.space.tester:insert{105, 'test#2', 'first_name', 'last_name'}</userinput>
+tarantool> <userinput> s:insert{1,'A'}</userinput>
---
-- [105, 'test#2', 'first_name', 'last_name']
+- [1, 'A']
...
-tarantool> <userinput>table_of_tuples = box.space.tester:select{105}</userinput>
+tarantool> <userinput> s:insert{1,'B'}</userinput>
---
+- [1, 'B']
...
-tarantool> <userinput>table_of_tuples[1]</userinput>
+tarantool> <userinput> s:insert{1,'C'}</userinput>
---
-- [105, 'test#2', 'first_name', 'last_name']
+- [1, 'C']
...
-</programlisting>
- For examples of complex <code>select</code>s, which can return multiple tuples
- via secondary indexes, see the later section <olink targetptr="box.index.iterator">box.space.space-name.index.index-name]:select</olink>.
+tarantool> <userinput> s:insert{2,'D'}</userinput>
+---
+- [2, 'D']
+...
+tarantool> <userinput> s:select{1,'B'} -- must equal both primary-key fields</userinput>
+---
+- - [1, 'B']
+...
+
+tarantool> <userinput> s:select{1} -- must equal only one primary-key field</userinput>
+---
+- - [1, 'A']
+ - [1, 'B']
+ - [1, 'C']
+...
+tarantool> <userinput> s:select{} -- must equal 0 fields, so returns all tuples</userinput>
+---
+- - [1, 'A']
+ - [1, 'B']
+ - [1, 'C']
+ - [2, 'D']
+...</programlisting>
+ For examples of complex <code>select</code>s, where one can specify which
+ index to search and what condition to use (for example "greater than"
+ instead of "equal to") and how many tuples to return, see the later section
+ <link linkend="box.index.iterator.select">box.space.space-name[.index.index-name]:select</link>.
</para>
</listitem>
</varlistentry>
@@ -1442,8 +1467,8 @@ console.delimiter('')!
<varlistentry>
<term>
- <emphasis role="lua" xml:id="box.index.iterator" xreflabel="box.index.select(type, ...)">
- box.space.<replaceable>space-name</replaceable>[.index.<replaceable>index-name</replaceable>]:select({<replaceable>{fields}, {parameters}]</replaceable>)</emphasis>
+ <emphasis role="lua" xml:id="box.index.iterator.select" xreflabel="box.index.select(type, ...)">
+ box.space.<replaceable>space-name</replaceable>[.index.<replaceable>index-name</replaceable>]:select({<replaceable>[field-value [, field-value ...]]</replaceable>}, {<replaceable>[option [, option ...]]</replaceable>})</emphasis>
</term>
<listitem>
<para>
@@ -1452,6 +1477,12 @@ console.delimiter('')!
specify the iterator type, and the limit (that is, the maximum number of tuples to
return) and the offset (that is, which tuple to start with in the list).
</para>
+ <para>
+ Parameters: <code>field-value(s)</code> = values to be matched against the index key.
+ <code>option(s)</code> = any or all of <code>iterator=<replaceable>iterator-type</replaceable></code>,
+ <code>limit=<replaceable>maximum-number-of-tuples</replaceable></code>,
+ <code>offset=<replaceable>start-tuple-number</replaceable></code>.
+ </para>
<para>
Returns: (type = tuple set, as a Lua table) the tuple or tuples that match the field values.
</para>
@@ -1469,7 +1500,7 @@ box.space.tester:create_index('secondary', {type = 'tree', unique = false, parts
box.space.tester:insert{1,'X','Row with field[2]=X'}
box.space.tester:insert{2,'Y','Row with field[2]=Y'}
box.space.tester:insert{3,'Z','Row with field[2]=Z'}
-box.space.tester.index.secondary:select({'X'}, {iterator = 'GT'})
+box.space.tester.index.secondary:select({'X'}, {iterator = 'GT', limit = 1000})
</programlisting>
The result will be a table of tuples and will look like this:
<programlisting>
diff --git a/doc/user/iterator-types.xml b/doc/user/iterator-types.xml
index efb50c86a3..4ea57bb281 100644
--- a/doc/user/iterator-types.xml
+++ b/doc/user/iterator-types.xml
@@ -26,7 +26,7 @@
<tbody>
<row>
- <entry>box.index.ALL</entry>
+ <entry>box.index.ALL or 'ALL'</entry>
<entry>none</entry>
<entry>yes</entry>
<entry>yes</entry>
@@ -41,7 +41,7 @@
</row>
<row>
- <entry>box.index.EQ</entry>
+ <entry>box.index.EQ or 'EQ'</entry>
<entry>key</entry>
<entry>yes</entry>
<entry>yes</entry>
@@ -73,7 +73,7 @@
</row>
<row>
- <entry>box.index.GT</entry>
+ <entry>box.index.GT or 'GT'</entry>
<entry>key</entry>
<entry>yes (*)</entry>
<entry>yes </entry>
@@ -115,7 +115,7 @@
<tbody>
<row>
- <entry>box.index.REQ</entry>
+ <entry>box.index.REQ or 'REQ'</entry>
<entry>key or key part</entry>
<entry>
Reverse equality iterator. Is equivalent to
@@ -126,7 +126,7 @@
</row>
<row>
- <entry>box.index.GE</entry>
+ <entry>box.index.GE or 'GE'</entry>
<entry>key or key part</entry>
<entry>
Iterate over all tuples for which the corresponding
@@ -139,7 +139,7 @@
</entry>
</row>
<row>
- <entry>box.index.LT</entry>
+ <entry>box.index.LT or 'LT'</entry>
<entry>key or key part</entry>
<entry>
Similar to <code>box.index.GT</code>,
@@ -152,7 +152,7 @@
</row>
<row>
- <entry>box.index.LE</entry>
+ <entry>box.index.LE or 'LE'</entry>
<entry>key or key part</entry>
<entry>
Similar to <code>box.index.GE</code>, but
diff --git a/doc/user/stored-procedures.xml b/doc/user/stored-procedures.xml
index 7e8ed1d596..0fd3637ba1 100644
--- a/doc/user/stored-procedures.xml
+++ b/doc/user/stored-procedures.xml
@@ -1885,7 +1885,7 @@ end
<listitem>
<para>
Accept a new client connection and create a new connected socket.
- It is good practice to set the socket's blocking mode explicitly affer accepting.
+ It is good practice to set the socket's blocking mode explicitly after accepting.
</para>
<para>
Returns: new socket if success, null if error.
--
GitLab