[Feature] implement cardinality(), element_at() (backport #22846) (#23389)

* [Feature] implement cardinality(), element_at()(backport #22846)

Signed-off-by: Zhuhe Fang <[email protected]>

* update codes

Signed-off-by: Zhuhe Fang <[email protected]>

---------

Signed-off-by: Zhuhe Fang <[email protected]>

Author: fzhedu

docs/TOC.md

@@ -359,6 +359,8 @@
       + [array_sum](./sql-reference/sql-functions/array-functions/array_sum.md)
       + [arrays_overlap](./sql-reference/sql-functions/array-functions/arrays_overlap.md)
       + [array_to_bitmap](./sql-reference/sql-functions/array-functions/array_to_bitmap.md)
+      + [cardinality](./sql-reference/sql-functions/array-functions/cardinality.md)
+      + [element_at](./sql-reference/sql-functions/array-functions/element_at.md)
       + [reverse](./sql-reference/sql-functions/array-functions/reverse.md)
       + [unnest](./sql-reference/sql-functions/array-functions/unnest.md)
     + Bit Functions
@@ -414,6 +416,8 @@
         + [json_query](./sql-reference/sql-functions/json-functions/json-query-and-processing-functions/json_query.md)
         + [json_string](./sql-reference/sql-functions/json-functions/json-query-and-processing-functions/json_string.md)
     + Map Functions
+      + [cardinality](./sql-reference/sql-functions/map-functions/cardinality.md)
+      + [element_at](./sql-reference/sql-functions/map-functions/element_at.md)
       + [map_apply](./sql-reference/sql-functions/map-functions/map_apply.md)
       + [map_filter](./sql-reference/sql-functions/map-functions/map_filter.md)
       + [map_from_arrays](./sql-reference/sql-functions/map-functions/map_from_arrays.md)

docs/sql-reference/sql-functions/array-functions/array_length.md

@@ -4,6 +4,8 @@
 
 Returns the number of elements in the array. The result type is INT. if the parameter is NULL, the result is also NULL.
 
+It has an alias [cardinality()](cardinality.md).
+
 ## Syntax
 
 ```Haskell

docs/sql-reference/sql-functions/array-functions/cardinality.md

@@ -0,0 +1,36 @@
+# cardinality
+
+## Description
+
+Returns the number of elements in the array. The result type is INT. if the parameter is NULL, the result is also NULL.
+
+It is the alias of [array_length()](array_length.md).
+
+## Syntax
+
+```Haskell
+cardinality(any_array)
+```
+
+## Examples
+
+```plain text
+mysql> select cardinality([1,2,3]);
++-----------------------+
+|  cardinality([1,2,3]) |
++-----------------------+
+|                     3 |
++-----------------------+
+1 row in set (0.00 sec)
+mysql> select cardinality([[1,2], [3,4]]);
++-----------------------------+
+|  cardinality([[1,2],[3,4]]) |
++-----------------------------+
+|                           2 |
++-----------------------------+
+1 row in set (0.01 sec)
+```
+
+## keyword
+
+CARDINALITY,ARRAY_LENGTH,ARRAY

docs/sql-reference/sql-functions/array-functions/element_at.md

@@ -0,0 +1,30 @@
+# element_at
+
+## Description
+
+Returns the array element at the specific position. if any parameter is NULL, the result is also NULL.
+
+It is the alias of `[]` to get an element from an array.
+
+## Syntax
+
+```Haskell
+element_at(any_array, position)
+```
+position is an integer, which is in [1, any_array.lenght], other values will return null.
+
+## Examples
+
+```plain text
+mysql> select element_at([11,2,3],3);
++-----------------------+
+|  element_at([11,2,3]) |
++-----------------------+
+|                     3 |
++-----------------------+
+1 row in set (0.00 sec)
+```
+
+## keyword
+
+ELEMENT_AT, ARRAY

docs/sql-reference/sql-functions/map-functions/cardinality.md

@@ -0,0 +1,61 @@
+# cardinality
+
+## Description
+
+Returns the number of elements in a MAP value, it is an alias of [map_size()](map_size.md).
+
+From version 2.5, StarRocks supports querying complex data types MAP and STRUCT from data lakes. MAP is an unordered collection of key-value pairs, for example, `{"a":1, "b":2}`. One key-value pair constitutes one element, for example, `{"a":1, "b":2}` contains two elements.
+
+You can use external catalogs provided by StarRocks to query MAP and STRUCT data from Apache Hive™, Apache Hudi, and Apache Iceberg. You can only query data from ORC and Parquet files. For more information about how to use external catalogs to query external data sources, see [Overview of catalogs](../../../data_source/catalog/catalog_overview.md) and topics related to the required catalog type.
+
+## Syntax
+
+```Haskell
+INT cardinality(any_map)
+```
+
+## Parameters
+
+`any_map`: the MAP value from which you want to retrieve the number of elements.
+
+## Return value
+
+Returns a value of the INT value.
+
+If the input is NULL, NULL is returned.
+
+If a key or value in the MAP value is NULL, NULL is processed as a normal value.
+
+## Examples
+
+This example uses the Hive table `hive_map`, which contains the following data:
+
+```Plain
+select * from hive_map order by col_int;
++---------+---------------+
+| col_int | col_map       |
++---------+---------------+
+|       1 | {"a":1,"b":2} |
+|       2 | {"c":3}       |
+|       3 | {"d":4,"e":5} |
++---------+---------------+
+3 rows in set (0.05 sec)
+```
+
+After a Hive catalog is created in your database, you can use this catalog and the cardinality() function to obtain the number of elements in each row of the `cardinality` column.
+
+```Plaintext
+select cardinality(col_map) from hive_map order by col_int;
++----------------------+
+| cardinality(col_map) |
++----------------------+
+|                    2 |
+|                    1 |
+|                    2 |
++----------------------+
+3 rows in set (0.05 sec)
+```
+
+## keyword
+
+CARDINALITY,MAP_LENGTH,MAP

docs/sql-reference/sql-functions/map-functions/element_at.md

@@ -0,0 +1,37 @@
+# element_at
+
+## Description
+
+Returns the map element with the specific key. if any parameter is NULL, the result is also NULL.
+
+It is the alias of `[]` to get an element from a map.
+
+## Syntax
+
+```Haskell
+element_at(any_map, any_key)
+```
+if any_key exists in any_map, the specific key-value pair will return, otherwise return null.
+
+## Examples
+
+```plain text
+mysql> select element_at({1:3,2:3},1);
++-------------------------+
+| element_at({1:3,2:3},1) |
++-------------------------+
+|                   {1:3} |
++-------------------------+
+1 row in set (0.00 sec)
+mysql> select element_at({1:3,2:3},3);
++-------------------------+
+| element_at({1:3,2:3},3) |
++-------------------------+
+|                    NULL |
++-------------------------+
+1 row in set (0.00 sec)
+```
+
+## keyword
+
+ELEMENT_AT, MAP

docs/sql-reference/sql-functions/map-functions/map_size.md

@@ -2,7 +2,7 @@
 
 ## Description
 
-Returns the number of elements in a MAP value.
+Returns the number of elements in a MAP value, it has an alias [cardinality()](cardinality.md).
 
 From version 2.5, StarRocks supports querying complex data types MAP and STRUCT from data lakes. MAP is an unordered collection of key-value pairs, for example, `{"a":1, "b":2}`. One key-value pair constitutes one element, for example, `{"a":1, "b":2}` contains two elements.
 

fe/fe-core/src/main/java/com/starrocks/catalog/FunctionSet.java

@@ -300,6 +300,8 @@ public class FunctionSet {
     public static final String ARRAY_FILTER = "array_filter";
     public static final String ARRAY_SORTBY = "array_sortby";
 
+    public static final String ELEMENT_AT = "element_at";
+    public static final String CARDINALITY = "cardinality";
     // Bit functions:
     public static final String BITAND = "bitand";
     public static final String BITNOT = "bitnot";

fe/fe-core/src/main/java/com/starrocks/sql/parser/AstBuilder.java

@@ -5007,6 +5007,14 @@ public ParseNode visitSimpleFunctionCall(StarRocksParser.SimpleFunctionCallConte
                     intervalLiteral.getUnitIdentifier().getDescription());
         }
 
+        if (functionName.equals(FunctionSet.ELEMENT_AT)) {
+            List<Expr> params = visit(context.expression(), Expr.class);
+            if (params.size() != 2) {
+                throw new ParsingException("element_at() should accept 2 arguments, but there are " + params.size());
+            }
+            return new CollectionElementExpr(params.get(0), params.get(1));
+        }
+
         if (functionName.equals(FunctionSet.ISNULL)) {
             List<Expr> params = visit(context.expression(), Expr.class);
             if (params.size() != 1) {

fe/fe-core/src/test/java/com/starrocks/sql/analyzer/AnalyzeArrayTest.java

@@ -61,7 +61,12 @@ public void testArray() {
                 "            array_contains([true, false, true], true),\n" +
                 "            array_contains([true, false, true], false)");
         analyzeSuccess("select array_length(null)");
+        analyzeSuccess("select cardinality(null)");
+        analyzeSuccess("select cardinality([])");
+        analyzeSuccess("select element_at([3,2], 0)");
 
+        analyzeFail("select element_at([3,2])");
+        analyzeFail("select element_at(1,[3,2])");
         analyzeFail("select array_concat([])");
     }
 

gensrc/script/functions.py

@@ -881,6 +881,11 @@
     [170002, 'map_values', 'ANY_ARRAY', ['ANY_MAP'], 'MapFunctions::map_values'],
     [170003, 'map_from_arrays', 'ANY_MAP', ['ANY_ARRAY', 'ANY_ARRAY'], 'MapFunctions::map_from_arrays'],
     [170004, 'map_apply', 'ANY_MAP', ['FUNCTION', 'ANY_MAP'], 'nullptr'],
+
+    # map, array common functions
+    [170100, 'cardinality', 'INT', ['ANY_MAP'], 'MapFunctions::map_size'],
+    [170101, 'cardinality', 'INT', ['ANY_ARRAY'], 'ArrayFunctions::array_length'],
+
     # struct functions
     # [170500, 'row', 'ANY_STRUCT', ['ANY_ELEMENT', "..."], 'StructFunctions::row'],
 ]