Fixes gh-2516 New SQL data types and function changes, second commit

Author: pgulutzan

doc/reference/reference_sql/sql_plus_lua.rst

@@ -151,7 +151,7 @@ Limitations: (`Issue#4659 <https://github.com/tarantool/tarantool/issues/4659>`_
 `Issue#4758 <https://github.com/tarantool/tarantool/issues/4758>`_) |br|
 SELECT with * or ORDER BY or GROUP BY from spaces that have map fields
 or array fields may cause errors. Any access to spaces that have hash
-indexes may cause severe errors.
+indexes may cause severe errors in Tarantool version 2.3 or earlier.
 
 .. _sql_system_tables:
 
@@ -257,7 +257,7 @@ See also: :ref:`Lua functions to make views of metadata <sql_lua_functions>`.
    and 2**6 possibilities for the other opts options, Tarantool supports
    about 736 * 2 * 5 * 64 = 471,040 different collations out of the box.
    In fact three of the pre-defined collations (unicode_uk_s1 unicode_uk_s2 unicode_uk_s3)
-   re the standard CLDR variants for Ukrainian, so the above example was
+   are the standard CLDR variants for Ukrainian, so the above example was
    made only to show how one makes a new one, not because there is any need to do so for this situation.
 
    Limitations:
@@ -312,23 +312,25 @@ For a useful example, here is a general function for decoding a single Lua ``'ma
     box.schema.func.create('_DECODE',
        {language = 'LUA',
         returns = 'string',
-        body = [[function (field, part)
-                 __GLOBAL= field
-                 return dostring("return require('msgpack').decode(__GLOBAL,1)." .. part)
+        body = [[function (field, key)
+                 -- If Tarantool version < 2.10.1, replace next line with
+                 -- return require('msgpack').decode(field)[key]
+                 return field[key]
                  end]],
         is_sandboxed = false,
-        param_list = {'string', "string"},
+        -- If Tarantool version < 2.10.1, replace next line with
+        -- param_list = {'string', 'string'},
+        param_list = {'map', 'string'},
         exports = {'LUA', 'SQL'},
         is_deterministic = true})
 
 See it work with, say, the _trigger space.
-That space has a ``'map'`` field named opts which has a part named sql.
-By selecting from the space and passing the field and the part name to _DECODE,
+That space has a ``'map'`` field named opts which has a key named sql.
+By selecting from the space and passing the field and the key name to _DECODE,
 you can get a list of all the trigger bodies.
 
 .. code-block:: lua
 
-    __GLOBAL = ""
     box.execute([[SELECT _decode("opts", 'sql') FROM "_trigger";]])
 
 Remember that SQL converts :ref:`regular identifiers <sql_identifiers>` to upper case,
@@ -359,12 +361,16 @@ So our way of making the function looks like this:
           returns = 'boolean',
           body = [[function (flags)
               local view
-              view = require('msgpack').decode(flags).view
+              -- If Tarantool version < 2.10.1, replace next line with
+              -- view = require('msgpack').decode(flags).view
+              view = flags.view
               if view == nil then return false end
               return view
               end]],
          is_sandboxed = false,
-         param_list = {'string'},
+         -- If Tarantool version < 2.10.1, replace next line with
+         -- param_list = {'string'},
+         param_list = {'map'},
          exports = {'LUA', 'SQL'},
          is_deterministic = true})
 
@@ -597,14 +603,17 @@ Definition of the function and the CREATE VIEW statement:
           returns = 'boolean',
           body = [[function (flags)
               local view
-              view = require('msgpack').decode(flags).view
+              -- If Tarantool version < 2.10.1, replace next line with
+              -- view = require('msgpack').decode(flags).view
+              view = flags.view
               if view == nil then return false end
               return view
               end]],
          is_sandboxed = false,
-         param_list = {'string'},
+         -- If Tarantool version < 2.10.1, replace next line with
+         -- param_list = {'string'},
+         param_list = {'map'},
          exports = {'LUA', 'SQL'},
-         setuid = false,
          is_deterministic = true})
     box.schema.role.grant('public', 'execute', 'function', '_TABLES_IS_VIEW')
     pcall(function ()
@@ -769,8 +778,13 @@ Definition of the function and the CREATE VIEW statement:
         {language = 'LUA',
          returns = 'string',
          body = [[function (flags)
-                      return require('msgpack').decode(flags).sql end]],
-         param_list = {'string'},
+                  -- If Tarantool version < 2.10.1, replace next line with
+                  -- return require('msgpack').decode(flags).sql
+                  return flags.sql
+                  end]],
+         -- If Tarantool version < 2.10.1, replace next line with
+         -- param_list = {'string'},
+         param_list = {'map'},
          exports = {'LUA', 'SQL'},
          is_sandboxed = false,
          setuid = false,
@@ -824,8 +838,13 @@ Definition of the function and the CREATE VIEW statement:
         {language = 'LUA',
          returns = 'string',
          body = [[function (opts)
-                      return require('msgpack').decode(opts).sql end]],
-         param_list = {'string'},
+                  -- If Tarantool version < 2.10.1, replace next line with
+                  -- return require('msgpack').decode(opts).sql
+                  return opts.sql
+                  end]],
+         -- If Tarantool version < 2.10.1, replace next line with
+         -- param_list = {'string'},
+         param_list = {'map'},
          exports = {'LUA', 'SQL'},
          is_sandboxed = false,
          setuid = false,

doc/reference/reference_sql/sql_user_guide.rst

@@ -169,7 +169,7 @@ but for readability one would usually use spaces to separate tokens: |br|
 Literals
 ********************************************************************************
 
-There are eight kinds of literals: BOOLEAN INTEGER DOUBLE DECIMAL STRING VARBINARY ARRAY MAP.
+There are eight kinds of literals: BOOLEAN INTEGER DOUBLE DECIMAL STRING VARBINARY MAP ARRAY.
 
 BOOLEAN literals:  |br|
 TRUE | FALSE | UNKNOWN |br|
@@ -221,27 +221,20 @@ Example: ``X'414243'``, which will be displayed as ``'ABC'``. |br|
 A literal has :ref:`data type = VARBINARY <sql_data_type_varbinary>`
 ("variable-length binary") if it is the letter X followed by quotes containing pairs of hexadecimal digits, representing byte values.
 
-ARRAY expressions: |br|
-[left square bracket] [comma-separated list of values] [right square bracket] |br|
-Examples: ``[1,2,3,4]``, ``[1,[2,3],4]``, ``X['a','22',uuid()]`` |br|
-An expression has data type = ARRAY if it is a sequence of zero or more values
-enclosed in square brackets (``[`` and ``]``).
-Values may be of any type; values may be expressions; arrays may be nested.
-In formal terms we should say that ``[`` and ``]`` are actually "operators"
-and the values are "elements", but most of the examples we have used are in
-fact arrays of literals.
-
-MAP expressions: |br|
-[left curly bracket] key [colon] value [right curly bracket] |br|
-Examples: ``{'a':1}``, ``{ "column_1" : X'1234' }`` |br|
-An expression has data type = MAP if it is enclosed in curly brackets
-(also called braces) ``{`` and ``}`` and contains a key for identification,
-then a colon ``:``, then a value for what the key identifies.
-As with ARRAY expressions, the ``{`` and ``}`` are actually operators
-so the key and the value are not necessarily literals themselves.
-It is not uncommon to have an array of maps, for example
-``[{'a':1},{'b':2}]``, which can be called an associative array and can
-be converted to a `Lua table <https://www.lua.org/pil/2.5.html>`_.
+MAP literals: |br|
+[left curly bracket] key [colon] value [right square bracket] |br|
+Examples: ``{'a':1}``, ``{1:'a'}`` |br|
+A map literal a pair of curly brackets (also called "braces")
+enclosing a STRING or INTEGER or UUID literal (called the map "key")
+followed by a colon
+followed by any type of literal (called the map "value").
+This is a minimal form of a :ref:`MAP expression <sql_map_expression>`.
+
+ARRAY literals: |br|
+[left square bracket] [literal] [right square bracket] |br|
+Examples: ``[1]``, ``['a']`` |br|
+An ARRAY literal is a literal value which is enclosed inside square brackets.
+This is a minimal form of an :ref:`ARRAY expression <sql_array_expression>`.
 
 Here are four ways to put non-ASCII characters,such as the Greek letter α alpha, in string literals: |br|
 First make sure that your shell program is set to accept characters as UTF-8. A simple way to check is |br|
@@ -495,10 +488,12 @@ and minimum / maximum literal examples.
     +-----------+------------+------------+----------------------+-------------------------+
     | SCALAR    | (varies)   | (none)     | FALSE                | maximum UUID value      |
     +-----------+------------+------------+----------------------+-------------------------+
-    | ARRAY     | array      | (none)     | []                   | ``many values``         |
-    +-----------+------------+------------+----------------------+-------------------------+
     | MAP       | map        | (none)     | ``{'':''}``          | ``big-key:big-value``   |
     +-----------+------------+------------+----------------------+-------------------------+
+    | ARRAY     | array      | (none)     | []                   | ``[many values]``       |
+    +-----------+------------+------------+----------------------+-------------------------+
+    | ANY       | any        | (none)     | FALSE                | ``[many values]``       |
+    +-----------+------------+------------+----------------------+-------------------------+
 
 
 .. _sql_data_type_boolean:
@@ -589,27 +584,33 @@ Prior to Tarantool version 2.10.1, individual column values had
 one of the preceding types -- BOOLEAN, INTEGER, DOUBLE, DECIMAL, STRING, VARBINARY, or UUID.
 Starting in Tarantool version 2.10.1, all values have type SCALAR.
 
-.. _sql_data_type_array:
+.. _sql_data_type_map:
 
-ARRAY values are lists of values of any type, including other ARRAY values
--- that is, arrays can be "nested". Tarantool does
-not require that all values in an array must have the same type.
-Arrays cannot be used in arithmetic or comparison (except ``IS [NOT] NULL``), and the only
+MAP values are key:value combinations which can be produced with
+:ref:`MAP expressions <sql_map_expression>`.
+Maps cannot be used in arithmetic or comparison (except ``IS [NOT] NULL``),
+and the only
 functions where they are allowed are :ref:`CAST <sql_function_cast>`,
 :ref:`QUOTE <sql_function_quote>`,
 :ref:`TYPEOF <sql_function_typeof>`, and functions involving NULL comparisons.
 
-.. _sql_data_type_map:
+.. _sql_data_type_array:
 
-MAP values are key:value combinations which can be produced with expressions
-like ``LUA('return {a=1}')``, although the SQL literal will look more like
-``{'a':1}``.
-Maps cannot be used in arithmetic or comparison (except ``IS [NOT] NULL``),
-and the only
+ARRAY values are lists which can be produced with
+:ref:`ARRAY expressions <sql_array_expression>`.
+Arrays cannot be used in arithmetic or comparison (except ``IS [NOT] NULL``), and the only
 functions where they are allowed are :ref:`CAST <sql_function_cast>`,
 :ref:`QUOTE <sql_function_quote>`,
 :ref:`TYPEOF <sql_function_typeof>`, and functions involving NULL comparisons.
 
+.. _sql_data_type_any:
+
+ANY can be used for
+:ref:`column definitions <sql_column_def_data_type>` and the individual column values have
+type ANY.
+The difference between SCALAR and ANY is:
+SCALAR columns may not contain MAP or ARRAY values, but ANY columns may contain them.
+
 Any value of any data type may be NULL. Ordinarily NULL will be cast to the
 data type of any operand it is being compared to or to the data type of the
 column it is in. If the data type of NULL cannot be determined from context,
@@ -865,6 +866,40 @@ value IS [NOT] NULL |br|
 CASE ... WHEN ... THEN ... ELSE ... END |br|
   ... for setting a series of conditions.
 
+.. _sql_map_expression:
+
+{ key : value } |br|
+... for MAP expressions. |br|
+Literal Examples: ``{'a':1}``, ``{ "column_1" : X'1234' }`` |br|
+Non-literal Examples: ``{"a":"a"}``, ``{UUID(), (SELECT 1) + 1}`` |br|
+An expression has data type = MAP if it is enclosed in curly brackets
+(also called braces) ``{`` and ``}`` and contains a key for identification,
+then a colon ``:``, then a value for what the key identifies.
+The key data type must be INTEGER or STRING or UUID.
+The value data type may be anything.
+The Lua equivalent type is 'map' but the syntax is slightly different,
+for example the SQL value ``{'a': 1}`` is represented in Lua as ``{a = 1}``.
+
+.. _sql_array_expression:
+
+[ value ... ] |br|
+... for ARRAY expressions. |br|
+Examples: ``[1,2,3,4]``, ``[1,[2,3],4]``, ``['a', "column_1", uuid()]`` |br|
+An expression has data type = ARRAY if it is a sequence of zero or more values
+enclosed in square brackets (``[`` and ``]``).
+Often the values in the sequence are called "elements".
+The element data type may be anything, including ARRAY -- that is, ARRAYs may be nested.
+Different elements may have different types.
+The Lua equivalent type is `'array' <https://www.lua.org/pil/11.1.html>`_.
+
+.. _sql_array_index_expression:
+
+ARRAY index expression: |br|
+array-value [square bracket] index [square bracket] |br|
+Example: ``['a', 'b', 'c'] [2]`` (this equals 'b') |br|
+As in other languages, an element of an array can be referenced with an
+integer inside square brackets.
+
 See also: :ref:`subquery <sql_subquery>`.
 
 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++