Merge #68263

68263: builtin: add cardinality builtin function r=rafiss a=jlevesy

To ensure PostgreSQL compatibility, this commit adds a new builtin
function called `cardinality` which returns the total number of elements
present in a given array.

Fixes: #67996

Release note (sql change): Added cardinality builtin function that
returns the total number of elements in a given array.

Co-authored-by: Julien Levesy <jlevesy@gmail.com>

docs/generated/sql/functions.md

@@ -279,6 +279,8 @@
 </span></td></tr>
 <tr><td><a name="array_upper"></a><code>array_upper(input: anyelement[], array_dimension: <a href="int.html">int</a>) &rarr; <a href="int.html">int</a></code></td><td><span class="funcdesc"><p>Calculates the maximum value of <code>input</code> on the provided <code>array_dimension</code>. However, because CockroachDB doesn’t yet support multi-dimensional arrays, the only supported <code>array_dimension</code> is <strong>1</strong>.</p>
 </span></td></tr>
+<tr><td><a name="cardinality"></a><code>cardinality(input: anyelement[]) &rarr; <a href="int.html">int</a></code></td><td><span class="funcdesc"><p>Calculates the number of elements contained in <code>input</code></p>
+</span></td></tr>
 <tr><td><a name="string_to_array"></a><code>string_to_array(str: <a href="string.html">string</a>, delimiter: <a href="string.html">string</a>) &rarr; <a href="string.html">string</a>[]</code></td><td><span class="funcdesc"><p>Split a string into components on a delimiter.</p>
 </span></td></tr>
 <tr><td><a name="string_to_array"></a><code>string_to_array(str: <a href="string.html">string</a>, delimiter: <a href="string.html">string</a>, null: <a href="string.html">string</a>) &rarr; <a href="string.html">string</a>[]</code></td><td><span class="funcdesc"><p>Split a string into components on a delimiter with a specified string to consider NULL.</p>

pkg/sql/logictest/testdata/logic_test/builtin_function

@@ -1776,6 +1776,21 @@ SELECT array_length(ARRAY['a'], 2)
 ----
 NULL
 
+query I
+SELECT cardinality(ARRAY['a', 'b'])
+----
+2
+
+query I
+SELECT cardinality(ARRAY[]:::int[])
+----
+0
+
+query I
+SELECT cardinality(NULL:::int[])
+----
+NULL
+
 query I
 SELECT array_lower(ARRAY['a', 'b'], 1)
 ----

pkg/sql/sem/builtins/builtins.go

@@ -3125,6 +3125,19 @@ may increase either contention or retry errors, or both.`,
 		},
 	),
 
+	"cardinality": makeBuiltin(arrayProps(),
+		tree.Overload{
+			Types:      tree.ArgTypes{{"input", types.AnyArray}},
+			ReturnType: tree.FixedReturnType(types.Int),
+			Fn: func(_ *tree.EvalContext, args tree.Datums) (tree.Datum, error) {
+				arr := tree.MustBeDArray(args[0])
+				return cardinality(arr), nil
+			},
+			Info:       "Calculates the number of elements contained in `input`",
+			Volatility: tree.VolatilityImmutable,
+		},
+	),
+
 	"array_lower": makeBuiltin(arrayProps(),
 		tree.Overload{
 			Types:      tree.ArgTypes{{"input", types.AnyArray}, {"array_dimension", types.Int}},
@@ -7056,6 +7069,17 @@ func GenerateUniqueID(instanceID int32, timestamp uint64) tree.DInt {
 	return tree.DInt(id)
 }
 
+func cardinality(arr *tree.DArray) tree.Datum {
+	if arr.ParamTyp.Family() != types.ArrayFamily {
+		return tree.NewDInt(tree.DInt(arr.Len()))
+	}
+	card := 0
+	for _, a := range arr.Array {
+		card += int(tree.MustBeDInt(cardinality(tree.MustBeDArray(a))))
+	}
+	return tree.NewDInt(tree.DInt(card))
+}
+
 func arrayLength(arr *tree.DArray, dim int64) tree.Datum {
 	if arr.Len() == 0 || dim < 1 {
 		return tree.DNull