Index options API #3562

andreyaksenov · 2023-07-05T15:02:21Z

The #3227 issue is fixed as a part of index docs refactoring. The next steps of improving docs for indexes are described in this issue: #3572.

Here are the changes directly related to #3227:

The collation option is added to the space_object:format() description.
key_part.is_nullable is updated to reflect that its value is inherited from the space format.
key_part.collation is updated to reflect that its value is inherited from the space format.

Fixes related to feedback issues for index docs:

Describe index part collation #2746 - key_part.collation now contains the example of using a non-default collation.
[2pt] feedback: index_object:count() #2279 - index_object:count() now has the example with a partial key value.
[2pt] feedback: index_object:user_defined() | Tarantool #2107 - the title of user_defined is changed to reflect that there is no such method. space_object.user_defined is also updated.
[2pt] tuple: allow nullable multikey index root #1484 - this issue doesn't need any change in docs as this behaviour is by design.

Changes related to index docs refactoring:

space_object:create_index() is restructured to make it look like the API member doc. Now it documents the index_opts and key_part objects with all their members.
Removed the Index field types table from the API as it duplicates the corresponding table in the main topic. All links are updated.
A bunch of examples for creating and using indexes are now added to the doc/code_snippets folder and have tests. For example, the following topics share index_select_test.lua for referenced examples:
Other affected topics:

Totktonada · 2023-07-11T10:13:58Z

doc/reference/reference_lua/box_index/max.rst

-            ---
-            - ['Gamma!', 55, 'This is the third tuple!']
-            ...
+        Below are few examples of using ``min``.


yep, thanks!

p7nov

That's an impressive work!

Some minor edits and suggestions from my side.
Although, I couldn't make myself actually check all 100500 links you've changed on different pages.

p7nov · 2023-07-13T05:13:58Z

doc/concepts/data_model/value_store.rst

@@ -188,31 +188,43 @@ Example: ``nil``.

 ..  _index-box_boolean:

-**boolean**. A boolean is either ``true`` or ``false``.
+**boolean**


Maybe convert all bold type names to headings? This will be a better semantic markup.

agree, will do

p7nov · 2023-07-13T05:23:02Z

doc/how-to/db/indexes.rst

@@ -64,99 +64,58 @@ Index operations
 Index operations are automatic: if a data manipulation request changes a tuple,
 then it also changes the index keys defined for the tuple.

-#.  Let's create a sample space named ``tester`` and
-    put it in a variable ``my_space``:
+#.  Let's create a sample space named ``bands``:


Suggested change

#. Let's create a sample space named ``bands``:

#. Create a sample space named ``bands``:

Nit: for consistency, let's use direct second person instructions in all new content.

p7nov · 2023-07-13T05:28:45Z

doc/how-to/db/indexes.rst

+    ..  literalinclude:: /code_snippets/test/indexes/index_select_test.lua
+        :language: lua
+        :lines: 40
+        :dedent:

 **There are the following SELECT variations:**


Suggested change

**There are the following SELECT variations:**

There are the following SELECT variations:

p7nov · 2023-07-13T05:30:06Z

doc/how-to/db/indexes.rst

+    ..  literalinclude:: /code_snippets/test/indexes/index_select_test.lua
+        :language: lua
+        :lines: 98-106
+        :dedent:

    The :ref:`comparison operators <box_index-iterator-types>` are:


Pls fix the punctuation in the list below.

p7nov · 2023-07-13T05:31:34Z

doc/how-to/db/indexes.rst

-    ..  code-block:: tarantoolsession
-
-        tarantool> my_space = box.schema.space.create('tester')
+    ..  literalinclude:: /code_snippets/test/indexes/index_select_test.lua


Code reuse on this page is really awesome 👍

p7nov · 2023-07-13T05:55:05Z

doc/reference/reference_lua/box_index/user_defined.rst

+(1) Create a Lua function.
+(2) Add the function name to a predefined global variable, which has the ``table`` type.
+(3) Call the function on the ``index_object``: ``index_object:function-name([parameters])``.


Suggested change

(1) Create a Lua function.

(2) Add the function name to a predefined global variable, which has the ``table`` type.

(3) Call the function on the ``index_object``: ``index_object:function-name([parameters])``.

1. Create a Lua function.

2. Add the function name to a predefined global variable, which has the ``table`` type.

3. Call the function on the ``index_object``: ``index_object:function-name([parameters])``.

Convert to the usual list formatting.

Step 2: maybe naviagate reader to the functions list below or move the list inside this procedure?

p7nov · 2023-07-13T05:57:59Z

doc/reference/reference_lua/box_index/user_defined.rst


-        There are three predefined global variables:
+Alternatively, user-defined functions can be made available for only one index,


Suggested change

Alternatively, user-defined functions can be made available for only one index,

Alternatively, you can make a user-defined function available for only one index

Simplify the sentence a bit and fix punctuation

p7nov · 2023-07-13T05:59:56Z

doc/reference/reference_lua/box_index/user_defined.rst

-        Alternatively, user-defined methods can be made available for only one index,
-        by calling ``getmetatable(index_object)`` and then adding the function name to the
-        meta table.
+**Example 1:**


Maybe add text descriptions?

p7nov · 2023-07-13T06:12:11Z

doc/reference/reference_lua/box_space/user_defined.rst


-    .. method:: user_defined()
+(1) Create a Lua function.
+(2) Add the function name to a predefined global variable, which has the ``table`` type.


The structure looks awkward with only one "predefined global variable" below.
Also, please fix the step number formatting.

p7nov · 2023-07-13T06:15:22Z

locale/ru/LC_MESSAGES/reference/reference_lua/box_space/create_index.po

@@ -1070,7 +1070,7 @@ msgstr ""
 "box.space.tester:create_index('i',{parts={{field = 1, type = 'string'}}})"

 msgid ""
-"Make a function. The function expects a tuple. In this example it will work "
+"Make a function. The function expects a tuple. In this example, it will work "


Suggested change

"Make a function. The function expects a tuple. In this example, it will work "

"Create a function. The function expects a tuple. In this example, it will work "

Same for "Make a space"

andreyaksenov force-pushed the index-options branch 3 times, most recently from 7108927 to 2cd5472 Compare July 6, 2023 08:50

andreyaksenov linked an issue Jul 6, 2023 that may be closed by this pull request

Index options are inherited from the space format #3227

Closed

andreyaksenov force-pushed the index-options branch 19 times, most recently from 4833b3b to 623e8d9 Compare July 10, 2023 14:44

This was linked to issues Jul 10, 2023

Describe index part collation #2746

Closed

[2pt] tuple: allow nullable multikey index root #1484

Closed

[2pt] feedback: index_object:user_defined() | Tarantool #2107

Closed

[2pt] feedback: index_object:count() #2279

Closed

andreyaksenov force-pushed the index-options branch 3 times, most recently from 867671a to dbe83b8 Compare July 11, 2023 07:44

andreyaksenov force-pushed the index-options branch from dbe83b8 to 1609686 Compare July 11, 2023 09:08

Totktonada reviewed Jul 11, 2023

View reviewed changes

andreyaksenov force-pushed the index-options branch 2 times, most recently from 5934251 to d4aa371 Compare July 11, 2023 14:28

andreyaksenov mentioned this pull request Jul 12, 2023

[Epic] Improve docs for indexes #3572

Open

andreyaksenov requested a review from p7nov July 12, 2023 08:14

p7nov approved these changes Jul 13, 2023

View reviewed changes

andreyaksenov force-pushed the index-options branch 3 times, most recently from b004a68 to 53ce704 Compare July 13, 2023 11:02

Index options API

da89114

andreyaksenov force-pushed the index-options branch from 53ce704 to da89114 Compare July 13, 2023 11:19

andreyaksenov merged commit acbc3c6 into latest Jul 13, 2023

andreyaksenov deleted the index-options branch July 13, 2023 11:20

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Index options API #3562

Index options API #3562

Uh oh!

andreyaksenov commented Jul 5, 2023 •

edited

Loading

Uh oh!

Totktonada Jul 11, 2023

Uh oh!

andreyaksenov Jul 11, 2023

Uh oh!

p7nov left a comment

Uh oh!

p7nov Jul 13, 2023

Uh oh!

andreyaksenov Jul 13, 2023

Uh oh!

p7nov Jul 13, 2023

Uh oh!

p7nov Jul 13, 2023

Uh oh!

p7nov Jul 13, 2023

Uh oh!

p7nov Jul 13, 2023

Uh oh!

p7nov Jul 13, 2023

Uh oh!

p7nov Jul 13, 2023

Uh oh!

p7nov Jul 13, 2023

Uh oh!

p7nov Jul 13, 2023

Uh oh!

p7nov Jul 13, 2023

Uh oh!

p7nov Jul 13, 2023

Uh oh!

Uh oh!

	#. Let's create a sample space named ``bands``:
	#. Create a sample space named ``bands``:

	There are the following SELECT variations:
	There are the following SELECT variations:


		There are three predefined global variables:
		Alternatively, user-defined functions can be made available for only one index,

	Alternatively, user-defined functions can be made available for only one index,
	Alternatively, you can make a user-defined function available for only one index

	"Make a function. The function expects a tuple. In this example, it will work "
	"Create a function. The function expects a tuple. In this example, it will work "

Index options API #3562

Index options API #3562

Uh oh!

Conversation

andreyaksenov commented Jul 5, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

p7nov left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

andreyaksenov commented Jul 5, 2023 •

edited

Loading