Index options API

Author: andreyaksenov

doc/code_snippets/README.md

@@ -27,19 +27,26 @@ To test all the examples, go to the `doc/code_snippets` folder and execute the `
 .rocks/bin/luatest
 ```
 
-To run a specific example with tests, use the `luatest` command with the `-c` option, for example:
+To test the examples from the specified directory, pass its relative path to the `luatest` command:
+
+```shell
+.rocks/bin/luatest test/transactions
+```
+
+To test a specific example with the `stdout` output enabled, use the `luatest` command with the `-c` option, for example:
 
 ```shell
 .rocks/bin/luatest -c test/http_client/get_test.lua
 ```
 
-You can also run the `httpbin` service locally using Docker:
+Note that the HTTP client samples (placed in `test/http_client`) use the `httpbin` service.
+You can run `httpbin` locally using Docker to stabilize test results:
 
 ```shell
 docker run -p 80:80 kennethreitz/httpbin
 ```
 
-In this case, replace `https://httpbin.org` links with `http://127.0.0.1` to test the examples.
+In this case, you need to replace `https://httpbin.org` links with `http://127.0.0.1`.
 
 
 ## Referencing code snippets

doc/code_snippets/test/indexes/create_index_field_number_test.lua

@@ -0,0 +1,69 @@
+local fio = require('fio')
+local server = require('luatest.server')
+local t = require('luatest')
+local g = t.group()
+g.before_each(function(cg)
+    cg.server = server:new {
+        box_cfg = {},
+        workdir = fio.cwd() .. '/tmp'
+    }
+    cg.server:start()
+end)
+
+g.after_each(function(cg)
+    cg.server:stop()
+    cg.server:drop()
+end)
+
+g.test_indexes = function(cg)
+    cg.server:exec(function()
+        -- Create a space --
+        bands = box.schema.space.create('bands')
+
+        -- Specify field names and types --
+        box.space.bands:format({
+            { name = 'id', type = 'unsigned' },
+            { name = 'band_name', type = 'string' },
+            { name = 'year', type = 'unsigned' }
+        })
+
+        -- Create a primary index --
+        box.space.bands:create_index('primary', { parts = { 1 } })
+
+        -- Create a unique secondary index --
+        box.space.bands:create_index('band', { parts = { 2 } })
+
+        -- Create a non-unique secondary index --
+        box.space.bands:create_index('year', { parts = { { 3 } }, unique = false })
+
+        -- Create a multi-part index --
+        box.space.bands:create_index('year_band', { parts = { 3, 2 } })
+
+        -- Insert test data --
+        box.space.bands:insert { 1, 'Roxette', 1986 }
+        box.space.bands:insert { 2, 'Scorpions', 1965 }
+        box.space.bands:insert { 3, 'Ace of Base', 1987 }
+        box.space.bands:insert { 4, 'The Beatles', 1960 }
+        box.space.bands:insert { 5, 'Pink Floyd', 1965 }
+        box.space.bands:insert { 6, 'The Rolling Stones', 1962 }
+        box.space.bands:insert { 7, 'The Doors', 1965 }
+        box.space.bands:insert { 8, 'Nirvana', 1987 }
+        box.space.bands:insert { 9, 'Led Zeppelin', 1968 }
+        box.space.bands:insert { 10, 'Queen', 1970 }
+
+        select_all = bands.index.band:select()
+        select_one = bands.index.year_band:select { 1960, 'The Beatles' }
+        select_limit = bands.index.year:select({ 1965 }, { iterator = 'GT', limit = 3 })
+        select_after_tuple = bands.index.primary:select({}, { after = { 4, 'The Beatles', 1960 }, limit = 3 })
+
+        result, position = bands.index.primary:select({}, { limit = 3, fetch_pos = true })
+        select_after_position = bands.index.primary:select({}, { limit = 3, after = position })
+
+        -- Tests --
+        t.assert_equals(select_all[1], { 3, 'Ace of Base', 1987 })
+        t.assert_equals(select_one[1], {4, 'The Beatles', 1960})
+        t.assert_equals(select_limit, { { 9, 'Led Zeppelin', 1968 }, { 10, 'Queen', 1970 }, { 1, 'Roxette', 1986 } })
+        t.assert_equals(select_after_tuple, { { 5, 'Pink Floyd', 1965 }, { 6, 'The Rolling Stones', 1962 }, { 7, 'The Doors', 1965 } })
+        t.assert_equals(select_after_position, { { 4, 'The Beatles', 1960 }, { 5, 'Pink Floyd', 1965 }, { 6, 'The Rolling Stones', 1962 } })
+    end)
+end

doc/code_snippets/test/indexes/create_index_func_multikey_test.lua

@@ -0,0 +1,51 @@
+local fio = require('fio')
+local server = require('luatest.server')
+local t = require('luatest')
+local g = t.group()
+g.before_each(function(cg)
+    cg.server = server:new {
+        box_cfg = {},
+        workdir = fio.cwd() .. '/tmp'
+    }
+    cg.server:start()
+end)
+
+g.after_each(function(cg)
+    cg.server:stop()
+    cg.server:drop()
+end)
+
+g.test_func_multikey_index = function(cg)
+    cg.server:exec(function()
+        tester = box.schema.space.create('withdata')
+        tester:format({ { name = 'name', type = 'string' },
+                        { name = 'address', type = 'string' } })
+        name_index = tester:create_index('name', { parts = { { field = 1, type = 'string' } } })
+        function_code = [[function(tuple)
+               local address = string.split(tuple[2])
+               local ret = {}
+               for _, v in pairs(address) do
+                 table.insert(ret, {utf8.upper(v)})
+               end
+               return ret
+             end]]
+        box.schema.func.create('address',
+                { body = function_code,
+                  is_deterministic = true,
+                  is_sandboxed = true,
+                  is_multikey = true })
+        addr_index = tester:create_index('addr', { unique = false,
+                                                   func = 'address',
+                                                   parts = { { field = 1, type = 'string',
+                                                          collation = 'unicode_ci' } } })
+        tester:insert({ "James", "SIS Building Lambeth London UK" })
+        tester:insert({ "Sherlock", "221B Baker St Marylebone London NW1 6XE UK" })
+        addr_index:select('Uk')
+
+        -- Tests --
+        t.assert_equals(addr_index:select('Uk'), {
+            { 'James', 'SIS Building Lambeth London UK' },
+            { 'Sherlock', '221B Baker St Marylebone London NW1 6XE UK' },
+        })
+    end)
+end

doc/code_snippets/test/indexes/create_index_func_test.lua

@@ -0,0 +1,36 @@
+local fio = require('fio')
+local server = require('luatest.server')
+local t = require('luatest')
+local g = t.group()
+g.before_each(function(cg)
+    cg.server = server:new {
+        box_cfg = {},
+        workdir = fio.cwd() .. '/tmp'
+    }
+    cg.server:start()
+end)
+
+g.after_each(function(cg)
+    cg.server:stop()
+    cg.server:drop()
+end)
+
+g.test_func_index = function(cg)
+    cg.server:exec(function()
+        box.schema.space.create('tester')
+        box.space.tester:create_index('i', { parts = { { field = 1, type = 'string' } } })
+        function_code = [[function(tuple) return {string.sub(tuple[2],1,1)} end]]
+        box.schema.func.create('my_func',
+                { body = function_code, is_deterministic = true, is_sandboxed = true })
+        box.space.tester:create_index('func_index', { parts = { { field = 1, type = 'string' } },
+                                                      func = 'my_func' })
+        box.space.tester:insert({ 'a', 'wombat' })
+        box.space.tester:insert({ 'b', 'rabbit' })
+        box.space.tester.index.func_index:select('w')
+        box.space.tester.index.func_index:select(box.func.my_func:call({ { 'tester', 'wombat' } }))
+
+        -- Tests --
+        t.assert_equals(box.space.tester.index.func_index:select('w')[1], { 'a', 'wombat' })
+        t.assert_equals(box.space.tester.index.func_index:select(box.func.my_func:call({ { 'tester', 'wombat' } }))[1], { 'a', 'wombat' })
+    end)
+end

doc/code_snippets/test/indexes/create_index_json_path_test.lua

@@ -0,0 +1,39 @@
+local fio = require('fio')
+local server = require('luatest.server')
+local t = require('luatest')
+local g = t.group()
+g.before_each(function(cg)
+    cg.server = server:new {
+        box_cfg = {},
+        workdir = fio.cwd() .. '/tmp'
+    }
+    cg.server:start()
+end)
+
+g.after_each(function(cg)
+    cg.server:stop()
+    cg.server:drop()
+end)
+
+g.test_json_path_index = function(cg)
+    cg.server:exec(function()
+        box.schema.space.create('space1')
+        box.space.space1:create_index('primary', { parts = { { field = 1,
+                                                               type = 'scalar',
+                                                               path = 'age' } } })
+        box.space.space1:insert({ { age = 44 } })
+        box.space.space1:select(44)
+
+        box.schema.space.create('space2')
+        box.space.space2:format({ { 'id', 'unsigned' }, { 'data', 'map' } })
+        box.space.space2:create_index('info', { parts = { { 'data.full_name["firstname"]', 'str' },
+                                                          { 'data.full_name["surname"]', 'str' } } })
+        box.space.space2:insert({ 1, { full_name = { firstname = 'John', surname = 'Doe' } } })
+        box.space.space2:select { 'John' }
+
+        -- Tests --
+        json = require('json')
+        t.assert_equals(json.encode(box.space.space1:select(44)[1][1]), "{\"age\":44}")
+        t.assert_equals(json.encode(box.space.space2:select { 'John' }[1][2]), "{\"full_name\":{\"surname\":\"Doe\",\"firstname\":\"John\"}}")
+    end)
+end

doc/code_snippets/test/indexes/create_index_key_parts_test.lua

@@ -0,0 +1,47 @@
+local fio = require('fio')
+local server = require('luatest.server')
+local t = require('luatest')
+local g = t.group()
+g.before_each(function(cg)
+    cg.server = server:new {
+        box_cfg = {},
+        workdir = fio.cwd() .. '/tmp'
+    }
+    cg.server:start()
+end)
+
+g.after_each(function(cg)
+    cg.server:stop()
+    cg.server:drop()
+end)
+
+g.test_indexes = function(cg)
+    cg.server:exec(function()
+        -- Create a space --
+        box.schema.space.create('tester')
+
+        -- Use the 'unicode' collation --
+        box.space.tester:create_index('unicode', { parts = { { field = 1,
+                                                                type = 'string',
+                                                                collation = 'unicode' } } })
+
+        -- Use the 'unicode_ci' collation --
+        box.space.tester:create_index('unicode_ci', { parts = { { field = 1,
+                                                                type = 'string',
+                                                                collation = 'unicode_ci' } } })
+
+        -- Insert test data --
+        box.space.tester:insert { 'ЕЛЕ' }
+        box.space.tester:insert { 'елейный' }
+        box.space.tester:insert { 'ёлка' }
+
+        -- Returns nil --
+        select_unicode = box.space.tester.index.unicode:select({ 'ЁлКа' })
+        -- Returns 'ёлка' --
+        select_unicode_ci = box.space.tester.index.unicode_ci:select({ 'ЁлКа' })
+
+        -- Tests --
+        t.assert_equals(select_unicode[1], nil)
+        t.assert_equals(select_unicode_ci[1], { 'ёлка' })
+    end)
+end

doc/code_snippets/test/indexes/index_aggr_functions_test.lua

@@ -0,0 +1,110 @@
+local fio = require('fio')
+local server = require('luatest.server')
+local t = require('luatest')
+local g = t.group()
+g.before_each(function(cg)
+    cg.server = server:new {
+        box_cfg = {},
+        workdir = fio.cwd() .. '/tmp'
+    }
+    cg.server:start()
+end)
+
+g.after_each(function(cg)
+    cg.server:stop()
+    cg.server:drop()
+end)
+
+g.test_indexes = function(cg)
+    cg.server:exec(function()
+        -- Create a space --
+        bands = box.schema.space.create('bands')
+
+        -- Specify field names and types --
+        box.space.bands:format({
+            { name = 'id', type = 'unsigned' },
+            { name = 'band_name', type = 'string' },
+            { name = 'year', type = 'unsigned' }
+        })
+
+        -- Create a primary index --
+        box.space.bands:create_index('primary', { parts = { 'id' } })
+
+        -- Create a unique secondary index --
+        box.space.bands:create_index('band', { parts = { 'band_name' } })
+
+        -- Create a non-unique secondary index --
+        box.space.bands:create_index('year', { parts = { { 'year' } }, unique = false })
+
+        -- Create a multi-part index --
+        box.space.bands:create_index('year_band', { parts = { { 'year' }, { 'band_name' } } })
+
+        -- Insert test data --
+        box.space.bands:insert { 1, 'Roxette', 1986 }
+        box.space.bands:insert { 2, 'Scorpions', 1965 }
+        box.space.bands:insert { 3, 'Ace of Base', 1987 }
+        box.space.bands:insert { 4, 'The Beatles', 1960 }
+        box.space.bands:insert { 5, 'Pink Floyd', 1965 }
+        box.space.bands:insert { 6, 'The Rolling Stones', 1962 }
+        box.space.bands:insert { 7, 'The Doors', 1965 }
+        box.space.bands:insert { 8, 'Nirvana', 1987 }
+        box.space.bands:insert { 9, 'Led Zeppelin', 1968 }
+        box.space.bands:insert { 10, 'Queen', 1970 }
+
+        -- Count the number of tuples that match the full key value
+        count = box.space.bands.index.year:count(1965)
+        --[[
+        ---
+        - 3
+        ...
+        --]]
+
+        -- Count the number of tuples that match the partial key value
+        count_partial = box.space.bands.index.year_band:count(1965)
+        --[[
+        ---
+        - 3
+        ...
+        --]]
+
+        -- Find the minimum value in the specified index
+        min = box.space.bands.index.year:min()
+        --[[
+        ---
+        - [4, 'The Beatles', 1960]
+        ...
+        --]]
+
+        -- Find the minimum value that matches the partial key value
+        min_partial = box.space.bands.index.year_band:min(1965)
+        --[[
+        ---
+        - [5, 'Pink Floyd', 1965]
+        ...
+        --]]
+
+        -- Find the maximum value in the specified index
+        max = box.space.bands.index.year:max()
+        --[[
+        ---
+        - [8, 'Nirvana', 1987]
+        ...
+        --]]
+
+        -- Find the maximum value that matches the partial key value
+        max_partial = box.space.bands.index.year_band:max(1965)
+        --[[
+        ---
+        - [7, 'The Doors', 1965]
+        ...
+        --]]
+
+        -- Tests --
+        t.assert_equals(count, 3)
+        t.assert_equals(count_partial, 3)
+        t.assert_equals(min, { 4, 'The Beatles', 1960 })
+        t.assert_equals(min_partial, { 5, 'Pink Floyd', 1965 })
+        t.assert_equals(max, { 8, 'Nirvana', 1987 })
+        t.assert_equals(max_partial, { 7, 'The Doors', 1965 })
+    end)
+end