Array Functions

empty

Checks whether the input array is empty.

Syntax

An array is considered empty if it does not contain any elements.

note

Can be optimized by enabling the optimize_functions_to_subcolumns setting. With optimize_functions_to_subcolumns = 1 the function reads only size0 subcolumn instead of reading and processing the whole array column. The query SELECT empty(arr) FROM TABLE; transforms to SELECT arr.size0 = 0 FROM TABLE;.

The function also works for strings or UUID.

Arguments

• [x] — Input array. Array.

Returned value

• Returns 1 for an empty array or 0 for a non-empty array. UInt8.

Example

Query:

Result:

notEmpty

Checks whether the input array is non-empty.

Syntax

An array is considered non-empty if it contains at least one element.

note

Can be optimized by enabling the optimize_functions_to_subcolumns setting. With optimize_functions_to_subcolumns = 1 the function reads only size0 subcolumn instead of reading and processing the whole array column. The query SELECT notEmpty(arr) FROM table transforms to SELECT arr.size0 != 0 FROM TABLE.

The function also works for strings or UUID.

Arguments

• [x] — Input array. Array.

Returned value

• Returns 1 for a non-empty array or 0 for an empty array. UInt8.

Example

Query:

Result:

length

Returns the number of items in the array. The result type is UInt64. The function also works for strings.

Can be optimized by enabling the optimize_functions_to_subcolumns setting. With optimize_functions_to_subcolumns = 1 the function reads only size0 subcolumn instead of reading and processing the whole array column. The query SELECT length(arr) FROM table transforms to SELECT arr.size0 FROM TABLE.

Alias: OCTET_LENGTH

emptyArrayUInt8

Returns an empty UInt8 array.

Syntax

Arguments

None.

Returned value

An empty array.

Examples

Query:

Result:

emptyArrayUInt16

Returns an empty UInt16 array.

Syntax

Arguments

None.

Returned value

An empty array.

Examples

Query:

Result:

emptyArrayUInt32

Returns an empty UInt32 array.

Syntax

Arguments

None.

Returned value

An empty array.

Examples

Query:

Result:

emptyArrayUInt64

Returns an empty UInt64 array.

Syntax

Arguments

None.

Returned value

An empty array.

Examples

Query:

Result:

emptyArrayInt8

Returns an empty Int8 array.

Syntax

Arguments

None.

Returned value

An empty array.

Examples

Query:

Result:

emptyArrayInt16

Returns an empty Int16 array.

Syntax

Arguments

None.

Returned value

An empty array.

Examples

Query:

Result:

emptyArrayInt32

Returns an empty Int32 array.

Syntax

Arguments

None.

Returned value

An empty array.

Examples

Query:

Result:

emptyArrayInt64

Returns an empty Int64 array.

Syntax

Arguments

None.

Returned value

An empty array.

Examples

Query:

Result:

emptyArrayFloat32

Returns an empty Float32 array.

Syntax

Arguments

None.

Returned value

An empty array.

Examples

Query:

Result:

emptyArrayFloat64

Returns an empty Float64 array.

Syntax

Arguments

None.

Returned value

An empty array.

Examples

Query:

Result:

emptyArrayDate

Returns an empty Date array.

Syntax

Arguments

None.

Returned value

An empty array.

Examples

Query:

emptyArrayDateTime

Returns an empty DateTime array.

Syntax

Arguments

None.

Returned value

An empty array.

Examples

Query:

Result:

emptyArrayString

Returns an empty String array.

Syntax

Arguments

None.

Returned value

An empty array.

Examples

Query:

Result:

emptyArrayToSingle

Accepts an empty array and returns a one-element array that is equal to the default value.

range(end), range([start, ] end [, step])

Returns an array of numbers from start to end - 1 by step. The supported types are UInt8, UInt16, UInt32, UInt64, Int8, Int16, Int32, Int64.

Syntax

Arguments

• start — The first element of the array. Optional, required if step is used. Default value: 0.
• end — The number before which the array is constructed. Required.
• step — Determines the incremental step between each element in the array. Optional. Default value: 1.

Returned value

• Array of numbers from start to end - 1 by step.

Implementation details

• All arguments start, end, step must be below data types: UInt8, UInt16, UInt32, UInt64,Int8, Int16, Int32, Int64, as well as elements of the returned array, which's type is a super type of all arguments.
• An exception is thrown if query results in arrays with a total length of more than number of elements specified by the function_range_max_elements_in_block setting.
• Returns Null if any argument has Nullable(Nothing) type. An exception is thrown if any argument has Null value (Nullable(T) type).

Examples

Query:

Result:

array(x1, ...), operator [x1, ...]

Creates an array from the function arguments. The arguments must be constants and have types that have the smallest common type. At least one argument must be passed, because otherwise it isn't clear which type of array to create. That is, you can't use this function to create an empty array (to do that, use the 'emptyArray*' function described above). Returns an 'Array(T)' type result, where 'T' is the smallest common type out of the passed arguments.

arrayWithConstant(length, elem)

Creates an array of length length filled with the constant elem.

arrayConcat

Combines arrays passed as arguments.

Arguments

• arrays – Arbitrary number of arguments of Array type.

Example

arrayElement(arr, n), operator arr[n]

Get the element with the index n from the array arr. n must be any integer type. Indexes in an array begin from one.

Negative indexes are supported. In this case, it selects the corresponding element numbered from the end. For example, arr[-1] is the last item in the array.

If the index falls outside of the bounds of an array, it returns some default value (0 for numbers, an empty string for strings, etc.), except for the case with a non-constant array and a constant index 0 (in this case there will be an error Array indices are 1-based).

has(arr, elem)

Checks whether the 'arr' array has the 'elem' element. Returns 0 if the element is not in the array, or 1 if it is.

NULL is processed as a value.

arrayElementOrNull(arr, n)

Get the element with the index nfrom the array arr. n must be any integer type. Indexes in an array begin from one.

Negative indexes are supported. In this case, it selects the corresponding element numbered from the end. For example, arr[-1] is the last item in the array.

If the index falls outside of the bounds of an array, it returns NULL instead of a default value.

Examples

hasAll

Checks whether one array is a subset of another.

Arguments

• set – Array of any type with a set of elements.
• subset – Array of any type that shares a common supertype with set containing elements that should be tested to be a subset of set.

Return values

• 1, if set contains all of the elements from subset.
• 0, otherwise.

Raises an exception NO_COMMON_TYPE if the set and subset elements do not share a common supertype.

Peculiar properties

• An empty array is a subset of any array.
• Null processed as a value.
• Order of values in both of arrays does not matter.

Examples

SELECT hasAll([], []) returns 1.

SELECT hasAll([1, Null], [Null]) returns 1.

SELECT hasAll([1.0, 2, 3, 4], [1, 3]) returns 1.

SELECT hasAll(['a', 'b'], ['a']) returns 1.

SELECT hasAll([1], ['a']) raises a NO_COMMON_TYPE exception.

SELECT hasAll([[1, 2], [3, 4]], [[1, 2], [3, 5]]) returns 0.

hasAny

Checks whether two arrays have intersection by some elements.

Arguments

• array1 – Array of any type with a set of elements.
• array2 – Array of any type that shares a common supertype with array1.

Return values

• 1, if array1 and array2 have one similar element at least.
• 0, otherwise.

Raises an exception NO_COMMON_TYPE if the array1 and array2 elements do not share a common supertype.

Peculiar properties

• Null processed as a value.
• Order of values in both of arrays does not matter.

Examples

SELECT hasAny([1], []) returns 0.

SELECT hasAny([Null], [Null, 1]) returns 1.

SELECT hasAny([-128, 1., 512], [1]) returns 1.

SELECT hasAny([[1, 2], [3, 4]], ['a', 'c']) raises a NO_COMMON_TYPE exception.

SELECT hasAll([[1, 2], [3, 4]], [[1, 2], [1, 2]]) returns 1.

hasSubstr

Checks whether all the elements of array2 appear in array1 in the same exact order. Therefore, the function will return 1, if and only if array1 = prefix + array2 + suffix.

In other words, the functions will check whether all the elements of array2 are contained in array1 like the hasAll function. In addition, it will check that the elements are observed in the same order in both array1 and array2.

For Example:

• hasSubstr([1,2,3,4], [2,3]) returns 1. However, hasSubstr([1,2,3,4], [3,2]) will return 0.
• hasSubstr([1,2,3,4], [1,2,3]) returns 1. However, hasSubstr([1,2,3,4], [1,2,4]) will return 0.

Arguments

• array1 – Array of any type with a set of elements.
• array2 – Array of any type with a set of elements.

Return values

• 1, if array1 contains array2.
• 0, otherwise.

Raises an exception NO_COMMON_TYPE if the array1 and array2 elements do not share a common supertype.

Peculiar properties

• The function will return 1 if array2 is empty.
• Null processed as a value. In other words hasSubstr([1, 2, NULL, 3, 4], [2,3]) will return 0. However, hasSubstr([1, 2, NULL, 3, 4], [2,NULL,3]) will return 1
• Order of values in both of arrays does matter.

Examples

SELECT hasSubstr([], []) returns 1.

SELECT hasSubstr([1, Null], [Null]) returns 1.

SELECT hasSubstr([1.0, 2, 3, 4], [1, 3]) returns 0.

SELECT hasSubstr(['a', 'b'], ['a']) returns 1.

SELECT hasSubstr(['a', 'b' , 'c'], ['a', 'b']) returns 1.

SELECT hasSubstr(['a', 'b' , 'c'], ['a', 'c']) returns 0.

SELECT hasSubstr([[1, 2], [3, 4], [5, 6]], [[1, 2], [3, 4]]) returns 1. i SELECT hasSubstr([1, 2, NULL, 3, 4], ['a']) raises a NO_COMMON_TYPE exception.

indexOf(arr, x)

Returns the index of the first element with value 'x' (starting from 1) if it is in the array. If the array does not contain the searched-for value, the function returns 0.

Example:

Elements set to NULL are handled as normal values.

indexOfAssumeSorted(arr, x)

Returns the index of the first element with value 'x' (starting from 1) if it is in the array. If the array does not contain the searched-for value, the function returns 0. Assumes that the array is sorted in ascending order (i.e., the function uses binary search). If the array is not sorted, results are undefined. If the internal array is of type Nullable, function 'indexOf' will be called.

Example:

arrayCount([func,] arr1, ...)

Returns the number of elements for which func(arr1[i], ..., arrN[i]) returns something other than 0. If func is not specified, it returns the number of non-zero elements in the array.

Note that the arrayCount is a higher-order function. You can pass a lambda function to it as the first argument.

arrayDotProduct

Returns the dot product of two arrays.

Syntax

Alias: scalarProduct, dotProduct

Parameters

• vector1: First vector. Array or Tuple of numeric values.
• vector2: Second vector. Array or Tuple of numeric values.

note

The sizes of the two vectors must be equal. Arrays and Tuples may also contain mixed element types.

Returned value

• The dot product of the two vectors. Numeric.

note

The return type is determined by the type of the arguments. If Arrays or Tuples contain mixed element types then the result type is the supertype.

Examples

Query:

Result:

Query:

Result:

countEqual(arr, x)

Returns the number of elements in the array equal to x. Equivalent to arrayCount (elem -> elem = x, arr).

NULL elements are handled as separate values.

Example:

arrayEnumerate(arr)

Returns the array [1, 2, 3, ..., length (arr) ]

This function is normally used with ARRAY JOIN. It allows counting something just once for each array after applying ARRAY JOIN. Example:

In this example, Reaches is the number of conversions (the strings received after applying ARRAY JOIN), and Hits is the number of pageviews (strings before ARRAY JOIN). In this particular case, you can get the same result in an easier way:

This function can also be used in higher-order functions. For example, you can use it to get array indexes for elements that match a condition.

arrayEnumerateUniq

Returns an array the same size as the source array, indicating for each element what its position is among elements with the same value. For example: arrayEnumerateUniq([10, 20, 10, 30]) = [1, 1, 2, 1].

This function is useful when using ARRAY JOIN and aggregation of array elements. Example:

In this example, each goal ID has a calculation of the number of conversions (each element in the Goals nested data structure is a goal that was reached, which we refer to as a conversion) and the number of sessions. Without ARRAY JOIN, we would have counted the number of sessions as sum(Sign). But in this particular case, the rows were multiplied by the nested Goals structure, so in order to count each session one time after this, we apply a condition to the value of the arrayEnumerateUniq(Goals.ID) function.

The arrayEnumerateUniq function can take multiple arrays of the same size as arguments. In this case, uniqueness is considered for tuples of elements in the same positions in all the arrays.

This is necessary when using ARRAY JOIN with a nested data structure and further aggregation across multiple elements in this structure.

arrayEnumerateUniqRanked

Returns an array the same size as the source array, indicating for each element what its position is among elements with the same value. It allows for enumeration of a multidimensional array with the ability to specify how deep to look inside the array.

Syntax

Parameters

• clear_depth: Enumerate elements at the specified level separately. Positive Integer less than or equal to max_arr_depth.
• arr: N-dimensional array to enumerate. Array.
• max_array_depth: The maximum effective depth. Positive Integer less than or equal to the depth of arr.

Example

With clear_depth=1 and max_array_depth=1, the result of arrayEnumerateUniqRanked is identical to that which arrayEnumerateUniq would give for the same array.

Query:

Result:

In this example, arrayEnumerateUniqRanked is used to obtain an array indicating, for each element of the multidimensional array, what its position is among elements of the same value. For the first row of the passed array,[1,2,3], the corresponding result is [1,1,1], indicating that this is the first time 1,2 and 3 are encountered. For the second row of the provided array,[2,2,1], the corresponding result is [2,3,3], indicating that 2 is encountered for a second and third time, and 1 is encountered for the second time. Likewise, for the third row of the provided array [3] the corresponding result is [2] indicating that 3 is encountered for the second time.

Query:

Result:

Changing clear_depth=2, results in elements being enumerated separately for each row.

Query:

Result:

arrayPopBack

Removes the last item from the array.

Arguments

• array – Array.

Example

arrayPopFront

Removes the first item from the array.

Arguments

• array – Array.

Example

arrayPushBack

Adds one item to the end of the array.

Arguments

• array – Array.
• single_value – A single value. Only numbers can be added to an array with numbers, and only strings can be added to an array of strings. When adding numbers, ClickHouse automatically sets the single_value type for the data type of the array. For more information about the types of data in ClickHouse, see "Data types". Can be NULL. The function adds a NULL element to an array, and the type of array elements converts to Nullable.

Example

arrayPushFront

Adds one element to the beginning of the array.

Arguments

• array – Array.
• single_value – A single value. Only numbers can be added to an array with numbers, and only strings can be added to an array of strings. When adding numbers, ClickHouse automatically sets the single_value type for the data type of the array. For more information about the types of data in ClickHouse, see "Data types". Can be NULL. The function adds a NULL element to an array, and the type of array elements converts to Nullable.

Example

arrayResize

Changes the length of the array.

Arguments:

• array — Array.
• size — Required length of the array.
  • If size is less than the original size of the array, the array is truncated from the right.
• If size is larger than the initial size of the array, the array is extended to the right with extender values or default values for the data type of the array items.
• extender — Value for extending an array. Can be NULL.

Returned value:

An array of length size.

Examples of calls

arraySlice

Returns a slice of the array.

Arguments

• array – Array of data.
• offset – Indent from the edge of the array. A positive value indicates an offset on the left, and a negative value is an indent on the right. Numbering of the array items begins with 1.
• length – The length of the required slice. If you specify a negative value, the function returns an open slice [offset, array_length - length]. If you omit the value, the function returns the slice [offset, the_end_of_array].

Example

Array elements set to NULL are handled as normal values.

arrayShingles

Generates an array of "shingles", i.e. consecutive sub-arrays with specified length of the input array.

Syntax

Arguments

• array — Input array Array.
• length — The length of each shingle.

Returned value

• An array of generated shingles. Array.

Examples

Query:

Result:

arraySort([func,] arr, ...)

Sorts the elements of the arr array in ascending order. If the func function is specified, sorting order is determined by the result of the func function applied to the elements of the array. If func accepts multiple arguments, the arraySort function is passed several arrays that the arguments of func will correspond to. Detailed examples are shown at the end of arraySort description.

Example of integer values sorting:

Example of string values sorting:

Consider the following sorting order for the NULL, NaN and Inf values:

• -Inf values are first in the array.
• NULL values are last in the array.
• NaN values are right before NULL.
• Inf values are right before NaN.

Note that arraySort is a higher-order function. You can pass a lambda function to it as the first argument. In this case, sorting order is determined by the result of the lambda function applied to the elements of the array.

Let's consider the following example:

For each element of the source array, the lambda function returns the sorting key, that is, [1 –> -1, 2 –> -2, 3 –> -3]. Since the arraySort function sorts the keys in ascending order, the result is [3, 2, 1]. Thus, the (x) –> -x lambda function sets the descending order in a sorting.

The lambda function can accept multiple arguments. In this case, you need to pass the arraySort function several arrays of identical length that the arguments of lambda function will correspond to. The resulting array will consist of elements from the first input array; elements from the next input array(s) specify the sorting keys. For example:

Here, the elements that are passed in the second array ([2, 1]) define a sorting key for the corresponding element from the source array (['hello', 'world']), that is, ['hello' –> 2, 'world' –> 1]. Since the lambda function does not use x, actual values of the source array do not affect the order in the result. So, 'hello' will be the second element in the result, and 'world' will be the first.

Other examples are shown below.

note

To improve sorting efficiency, the Schwartzian transform is used.

arrayPartialSort([func,] limit, arr, ...)

Same as arraySort with additional limit argument allowing partial sorting. Returns an array of the same size as the original array where elements in range [1..limit] are sorted in ascending order. Remaining elements (limit..N] shall contain elements in unspecified order.

arrayReverseSort

Sorts the elements of the arr array in descending order. If the func function is specified, arr is sorted according to the result of the func function applied to the elements of the array, and then the sorted array is reversed. If func accepts multiple arguments, the arrayReverseSort function is passed several arrays that the arguments of func will correspond to. Detailed examples are shown at the end of arrayReverseSort description.

Syntax

Example of integer values sorting:

Example of string values sorting:

Consider the following sorting order for the NULL, NaN and Inf values:

• Inf values are first in the array.
• NULL values are last in the array.
• NaN values are right before NULL.
• -Inf values are right before NaN.

Note that the arrayReverseSort is a higher-order function. You can pass a lambda function to it as the first argument. Example is shown below.

The array is sorted in the following way:

1. At first, the source array ([1, 2, 3]) is sorted according to the result of the lambda function applied to the elements of the array. The result is an array [3, 2, 1].
2. Array that is obtained on the previous step, is reversed. So, the final result is [1, 2, 3].

The lambda function can accept multiple arguments. In this case, you need to pass the arrayReverseSort function several arrays of identical length that the arguments of lambda function will correspond to. The resulting array will consist of elements from the first input array; elements from the next input array(s) specify the sorting keys. For example:

In this example, the array is sorted in the following way:

1. At first, the source array (['hello', 'world']) is sorted according to the result of the lambda function applied to the elements of the arrays. The elements that are passed in the second array ([2, 1]), define the sorting keys for corresponding elements from the source array. The result is an array ['world', 'hello'].
2. Array that was sorted on the previous step, is reversed. So, the final result is ['hello', 'world'].

Other examples are shown below.

arrayPartialReverseSort([func,] limit, arr, ...)

Same as arrayReverseSort with additional limit argument allowing partial sorting. Returns an array of the same size as the original array where elements in range [1..limit] are sorted in descending order. Remaining elements (limit..N] shall contain elements in unspecified order.

arrayShuffle

Returns an array of the same size as the original array containing the elements in shuffled order. Elements are reordered in such a way that each possible permutation of those elements has equal probability of appearance.

Syntax

Parameters

• arr: The array to partially shuffle. Array.
• seed (optional): seed to be used with random number generation. If not provided a random one is used. UInt or Int.

Returned value

• Array with elements shuffled.

Implementation details

note

This function will not materialize constants.

Examples

In this example, arrayShuffle is used without providing a seed and will therefore generate one randomly itself.

Query:

Note: when using ClickHouse Fiddle, the exact response may differ due to random nature of the function.

Result:

In this example, arrayShuffle is provided a seed and will produce stable results.

Query:

Result:

arrayPartialShuffle

Given an input array of cardinality N, returns an array of size N where elements in the range [1...limit] are shuffled and the remaining elements in the range (limit...n] are unshuffled.

Syntax

Parameters

• arr: The array size N to partially shuffle. Array.
• limit (optional): The number to limit element swaps to, in the range [1..N]. UInt or Int.
• seed (optional): The seed value to be used with random number generation. If not provided a random one is used. UInt or Int

Returned value

• Array with elements partially shuffled.

Implementation details

note

This function will not materialize constants.

The value of limit should be in the range [1..N]. Values outside of that range are equivalent to performing full arrayShuffle.

Examples

Note: when using ClickHouse Fiddle, the exact response may differ due to random nature of the function.

Query:

Result:

The order of elements is preserved ([2,3,4,5], [7,8,9,10]) except for the two shuffled elements [1, 6]. No seed is provided so the function selects its own randomly.

In this example, the limit is increased to 2 and a seed value is provided. The order

Query:

The order of elements is preserved ([4, 5, 6, 7, 8], [10]) except for the four shuffled elements [1, 2, 3, 9].

Result:

arrayUniq(arr, ...)

If one argument is passed, it counts the number of different elements in the array. If multiple arguments are passed, it counts the number of different tuples of elements at corresponding positions in multiple arrays.

If you want to get a list of unique items in an array, you can use arrayReduce('groupUniqArray', arr).

arrayJoin(arr)

A special function. See the section "ArrayJoin function".

arrayDifference

Calculates an array of differences between adjacent array elements. The first element of the result array will be 0, the second a[1] - a[0], the third a[2] - a[1], etc. The type of elements in the result array is determined by the type inference rules for subtraction (e.g. UInt8 - UInt8 = Int16).

Syntax

Arguments

• array – Array.

Returned values

Returns an array of differences between adjacent array elements. UInt*, Int*, Float*.

Example

Query:

Result:

Example of the overflow due to result type Int64:

Query:

Result:

arrayDistinct

Takes an array, returns an array containing the distinct elements only.

Syntax

Arguments

• array – Array.

Returned values

Returns an array containing the distinct elements.

Example

Query:

Result:

arrayEnumerateDense

Returns an array of the same size as the source array, indicating where each element first appears in the source array.

Syntax

Example

Query:

Result:

arrayEnumerateDenseRanked

Returns an array the same size as the source array, indicating where each element first appears in the source array. It allows for enumeration of a multidimensional array with the ability to specify how deep to look inside the array.

Syntax

Parameters

• clear_depth: Enumerate elements at the specified level separately. Positive Integer less than or equal to max_arr_depth.
• arr: N-dimensional array to enumerate. Array.
• max_array_depth: The maximum effective depth. Positive Integer less than or equal to the depth of arr.

Example

With clear_depth=1 and max_array_depth=1, the result is identical to what arrayEnumerateDense would give.

Query:

Result:

In this example, arrayEnumerateDenseRanked is used to obtain an array indicating, for each element of the multidimensional array, what its position is among elements of the same value. For the first row of the passed array,[10,10,30,20], the corresponding first row of the result is [1,1,2,3], indicating that 10 is the first number encountered in position 1 and 2, 30 the second number encountered in position 3 and 20 is the third number encountered in position 4. For the second row, [40, 50, 10, 30], the corresponding second row of the result is [4,5,1,2], indicating that 40 and 50 are the fourth and fifth numbers encountered in position 1 and 2 of that row, that another 10 (the first encountered number) is in position 3 and 30 (the second number encountered) is in the last position.

Query:

Result:

Changing clear_depth=2 results in the enumeration occurring separately for each row anew.

Query:

Result:

arrayUnion

Takes multiple arrays and returns an array which contains all elements that are present in one of the source arrays. The result contains only unique values.

Syntax

Arguments

• arrN — Array.

The function can take any number of arrays of different types.

Returned value

• Array with distinct elements from the source arrays.

Example

Query:

Result:

arrayIntersect

Takes multiple arrays and returns an array with elements which are present in all source arrays. The result contains only unique values.

Syntax

Arguments

• arrN — Array.

The function can take any number of arrays of different types.

Returned value

• Array with distinct elements present in all source arrays.

Example

Query:

Result:

arraySymmetricDifference

Takes multiple arrays and returns an array with elements that are not present in all source arrays. The result contains only unique values.

note

The symmetric difference of more than two sets is mathematically defined as the set of all input elements which occur in an odd number of input sets. In contrast, function arraySymmetricDifference simply returns the set of input elements which do not occur in all input sets.

Syntax

Arguments

• arrN — Array.

The function can take any number of arrays of different types.

Returned value

• Array with distinct elements not present in all source arrays.

Example

Query:

Result:

arrayJaccardIndex

Returns the Jaccard index of two arrays.

Example

Query:

Result:

arrayReduce

Applies an aggregate function to array elements and returns its result. The name of the aggregation function is passed as a string in single quotes 'max', 'sum'. When using parametric aggregate functions, the parameter is indicated after the function name in parentheses 'uniqUpTo(6)'.

Syntax

Arguments

• agg_func — The name of an aggregate function which should be a constant string.
• arr — Any number of array type columns as the parameters of the aggregation function.

Returned value

Example

Query:

Result:

If an aggregate function takes multiple arguments, then this function must be applied to multiple arrays of the same size.

Query:

Result:

Example with a parametric aggregate function:

Query:

Result:

See also

• arrayFold

arrayReduceInRanges

Applies an aggregate function to array elements in given ranges and returns an array containing the result corresponding to each range. The function will return the same result as multiple arrayReduce(agg_func, arraySlice(arr1, index, length), ...).

Syntax

Arguments

• agg_func — The name of an aggregate function which should be a constant string.
• ranges — The ranges to aggretate which should be an array of tuples which containing the index and the length of each range.
• arr — Any number of Array type columns as the parameters of the aggregation function.

Returned value

• Array containing results of the aggregate function over specified ranges. Array.

Example

Query:

Result:

arrayFold

Applies a lambda function to one or more equally-sized arrays and collects the result in an accumulator.

Syntax

Example

Query:

Result:

Example with the Fibonacci sequence

See also

• arrayReduce

arrayReverse

Returns an array of the same size as the original array containing the elements in reverse order.

Syntax

Example:

reverse(arr)

Synonym for "arrayReverse"

arrayFlatten

Converts an array of arrays to a flat array.

Function:

• Applies to any depth of nested arrays.
• Does not change arrays that are already flat.

The flattened array contains all the elements from all source arrays.

Syntax

Alias: flatten.

Parameters

• array_of_arrays — Array of arrays. For example, [[1,2,3], [4,5]].

Examples

arrayCompact

Removes consecutive duplicate elements from an array. The order of result values is determined by the order in the source array.

Syntax

Arguments

arr — The array to inspect.

Returned value

The array without duplicate. Array.

Example

Query:

Result:

arrayZip

Combines multiple arrays into a single array. The resulting array contains the corresponding elements of the source arrays grouped into tuples in the listed order of arguments.

Syntax

Arguments

• arrN — Array.

The function can take any number of arrays of different types. All the input arrays must be of equal size.

Returned value

• Array with elements from the source arrays grouped into tuples. Data types in the tuple are the same as types of the input arrays and in the same order as arrays are passed. Array.

Example

Query:

Result:

arrayZipUnaligned

Combines multiple arrays into a single array, allowing for unaligned arrays. The resulting array contains the corresponding elements of the source arrays grouped into tuples in the listed order of arguments.

Syntax

Arguments

• arrN — Array.

The function can take any number of arrays of different types.

Returned value

• Array with elements from the source arrays grouped into tuples. Data types in the tuple are the same as types of the input arrays and in the same order as arrays are passed. Array. If the arrays have different sizes, the shorter arrays will be padded with null values.

Example

Query:

Result:

arrayROCAUC

Calculates the area under the receiver operating characteristic (ROC) curve. A ROC curve is created by plotting True Positive Rate (TPR) on the y-axis and False Positive Rate (FPR) on the x-axis across all thresholds. The resulting value ranges from 0 to 1, with a higher value indicating better model performance. The ROC AUC (also known as simply AUC) is a concept in machine learning. For more details, please see here, here and here.

Syntax

Alias: arrayAUC

Arguments

• arr_scores — Scores prediction model gives. Array of Integers or Floats.
• arr_labels — Labels of samples, usually 1 for positive sample and 0 for negative sample. Array of Integers or Enums.
• scale — Decides whether to return the normalized area. If false, returns the area under the TP (true positives) x FP (false positives) curve instead. Default value: true. Bool. Optional.
• arr_partial_offsets — An array of four non-negative integers for calculating a partial area under the ROC curve (equivalent to a vertical band of the ROC space) instead of the whole AUC. This option is useful for distributed computation of the ROC AUC. The array must contain the following elements [higher_partitions_tp, higher_partitions_fp, total_positives, total_negatives]. Array of non-negative Integers. Optional.
  • higher_partitions_tp: The number of positive labels in the higher-scored partitions.
  • higher_partitions_fp: The number of negative labels in the higher-scored partitions.
  • total_positives: The total number of positive samples in the entire dataset.
  • total_negatives: The total number of negative samples in the entire dataset.

note

When arr_partial_offsets is used, the arr_scores and arr_labels should be only a partition of the entire dataset, containing an interval of scores. The dataset should be divided into contiguous partitions, where each partition contains the subset of the data whose scores fall within a specific range. For example:

• One partition could contain all scores in the range [0, 0.5).
• Another partition could contain scores in the range [0.5, 1.0].

Returned value

Returns area under the receiver operating characteristic (ROC) curve. Float64.

Example

Query:

Result:

arrayAUCPR

Calculates the area under the precision-recall (PR) curve. A precision-recall curve is created by plotting precision on the y-axis and recall on the x-axis across all thresholds. The resulting value ranges from 0 to 1, with a higher value indicating better model performance. The PR AUC is particularly useful for imbalanced datasets, providing a clearer comparison of performance compared to ROC AUC on those cases. For more details, please see here, here and here.

Syntax

Alias: arrayPRAUC

Arguments

• arr_scores — Scores prediction model gives. Array of Integers or Floats.
• arr_labels — Labels of samples, usually 1 for positive sample and 0 for negative sample. Array of Integers or Enums.
• arr_partial_offsets — Optional. An Array of three non-negative integers for calculating a partial area under the PR curve (equivalent to a vertical band of the PR space) instead of the whole AUC. This option is useful for distributed computation of the PR AUC. The array must contain the following elements [higher_partitions_tp, higher_partitions_fp, total_positives]. Array of non-negative Integers. Optional.
  • higher_partitions_tp: The number of positive labels in the higher-scored partitions.
  • higher_partitions_fp: The number of negative labels in the higher-scored partitions.
  • total_positives: The total number of positive samples in the entire dataset.

note

When arr_partial_offsets is used, the arr_scores and arr_labels should be only a partition of the entire dataset, containing an interval of scores. The dataset should be divided into contiguous partitions, where each partition contains the subset of the data whose scores fall within a specific range. For example:

• One partition could contain all scores in the range [0, 0.5).
• Another partition could contain scores in the range [0.5, 1.0].

Returned value

Returns area under the precision-recall (PR) curve. Float64.

Example

Query:

Result:

arrayMap(func, arr1, ...)

Returns an array obtained from the original arrays by application of func(arr1[i], ..., arrN[i]) for each element. Arrays arr1 ... arrN must have the same number of elements.

Examples:

The following example shows how to create a tuple of elements from different arrays:

Note that the arrayMap is a higher-order function. You must pass a lambda function to it as the first argument, and it can't be omitted.

arrayFilter(func, arr1, ...)

Returns an array containing only the elements in arr1 for which func(arr1[i], ..., arrN[i]) returns something other than 0.

Examples:

Note that the arrayFilter is a higher-order function. You must pass a lambda function to it as the first argument, and it can't be omitted.

arrayFill(func, arr1, ...)

Scan through arr1 from the first element to the last element and replace arr1[i] by arr1[i - 1] if func(arr1[i], ..., arrN[i]) returns 0. The first element of arr1 will not be replaced.

Examples:

Note that the arrayFill is a higher-order function. You must pass a lambda function to it as the first argument, and it can't be omitted.

arrayReverseFill(func, arr1, ...)

Scan through arr1 from the last element to the first element and replace arr1[i] by arr1[i + 1] if func(arr1[i], ..., arrN[i]) returns 0. The last element of arr1 will not be replaced.

Examples:

Note that the arrayReverseFill is a higher-order function. You must pass a lambda function to it as the first argument, and it can't be omitted.

arraySplit(func, arr1, ...)

Split arr1 into multiple arrays. When func(arr1[i], ..., arrN[i]) returns something other than 0, the array will be split on the left hand side of the element. The array will not be split before the first element.

Examples:

Note that the arraySplit is a higher-order function. You must pass a lambda function to it as the first argument, and it can't be omitted.

arrayReverseSplit(func, arr1, ...)

Split arr1 into multiple arrays. When func(arr1[i], ..., arrN[i]) returns something other than 0, the array will be split on the right hand side of the element. The array will not be split after the last element.

Examples:

Note that the arrayReverseSplit is a higher-order function. You must pass a lambda function to it as the first argument, and it can't be omitted.

arrayExists([func,] arr1, ...)

Returns 1 if there is at least one element in arr for which func(arr1[i], ..., arrN[i]) returns something other than 0. Otherwise, it returns 0.

Note that the arrayExists is a higher-order function. You can pass a lambda function to it as the first argument.

arrayAll([func,] arr1, ...)

Returns 1 if func(arr1[i], ..., arrN[i]) returns something other than 0 for all the elements in arrays. Otherwise, it returns 0.

Note that the arrayAll is a higher-order function. You can pass a lambda function to it as the first argument.

arrayFirst(func, arr1, ...)

Returns the first element in the arr1 array for which func(arr1[i], ..., arrN[i]) returns something other than 0.

arrayFirstOrNull

Returns the first element in the arr1 array for which func(arr1[i], ..., arrN[i]) returns something other than 0, otherwise it returns NULL.

Syntax

Parameters

• func: Lambda function. Lambda function.
• arr1: Array to operate on. Array.

Returned value

• The first element in the passed array.
• Otherwise, returns NULL

Implementation details

Note that the arrayFirstOrNull is a higher-order function. You must pass a lambda function to it as the first argument, and it can't be omitted.

Example

Query:

Result:

Query:

Result:

Query:

Result:

arrayLast(func, arr1, ...)

Returns the last element in the arr1 array for which func(arr1[i], ..., arrN[i]) returns something other than 0.

Note that the arrayLast is a higher-order function. You must pass a lambda function to it as the first argument, and it can't be omitted.

arrayLastOrNull

Returns the last element in the arr1 array for which func(arr1[i], ..., arrN[i]) returns something other than 0, otherwise returns NULL.

Syntax

Parameters

• func: Lambda function. Lambda function.
• arr1: Array to operate on. Array.

Returned value

• The last element in the passed array.
• Otherwise, returns NULL

Implementation details

Note that the arrayLastOrNull is a higher-order function. You must pass a lambda function to it as the first argument, and it can't be omitted.

Example

Query:

Result:

Query:

Result:

arrayFirstIndex(func, arr1, ...)

Returns the index of the first element in the arr1 array for which func(arr1[i], ..., arrN[i]) returns something other than 0.

Note that the arrayFirstIndex is a higher-order function. You must pass a lambda function to it as the first argument, and it can't be omitted.

arrayLastIndex(func, arr1, ...)

Returns the index of the last element in the arr1 array for which func(arr1[i], ..., arrN[i]) returns something other than 0.

Note that the arrayLastIndex is a higher-order function. You must pass a lambda function to it as the first argument, and it can't be omitted.

arrayMin

Returns the minimum of elements in the source array.

If the func function is specified, returns the minimum of elements converted by this function.

Note that the arrayMin is a higher-order function. You can pass a lambda function to it as the first argument.

Syntax

Arguments

• func — Function. Expression.
• arr — Array. Array.

Returned value

• The minimum of function values (or the array minimum).

note

If func is specified, then the return type matches the return value type of func, otherwise it matches the type of the array elements.

Examples

Query:

Result:

Query:

Result:

arrayMax

Returns the maximum of elements in the source array.

If the func function is specified, returns the maximum of elements converted by this function.

Note that the arrayMax is a higher-order function. You can pass a lambda function to it as the first argument.

Syntax

Arguments

• func — Function. Expression.
• arr — Array. Array.

Returned value

• The maximum of function values (or the array maximum).

note

if func is specified then the return type matches the return value type of func, otherwise it matches the type of the array elements.

Examples

Query:

Result:

Query:

Result:

arraySum

Returns the sum of elements in the source array.

If the func function is specified, returns the sum of elements converted by this function.

Note that the arraySum is a higher-order function. You can pass a lambda function to it as the first argument.

Syntax

Arguments

• func — Function. Expression.
• arr — Array. Array.

Returned value

• The sum of the function values (or the array sum).

note

Return type:

• For decimal numbers in the source array (or for converted values, if func is specified) — Decimal128.
• For floating point numbers — Float64.
• For numeric unsigned — UInt64.
• For numeric signed — Int64.

Examples

Query:

Result:

Query:

Result:

arrayAvg

Returns the average of elements in the source array.

If the func function is specified, returns the average of elements converted by this function.

Note that the arrayAvg is a higher-order function. You can pass a lambda function to it as the first argument.

Syntax

Arguments

• func — Function. Expression.
• arr — Array. Array.

Returned value

• The average of function values (or the array average). Float64.

Examples

Query:

Result:

Query:

Result:

arrayCumSum([func,] arr1, ...)

Returns an array of the partial (running) sums of the elements in the source array arr1. If func is specified, then the sum is computed from applying func to arr1, arr2, ..., arrN, i.e. func(arr1[i], ..., arrN[i]).

Syntax

Arguments

• arr — Array of numeric values.

Returned value

• Returns an array of the partial sums of the elements in the source array. UInt*, Int*, Float*.

Example:

Note that the arrayCumSum is a higher-order function. You can pass a lambda function to it as the first argument.

arrayCumSumNonNegative([func,] arr1, ...)

Same as arrayCumSum, returns an array of the partial (running) sums of the elements in the source array. If func is specified, then the sum is computed from applying func to arr1, arr2, ..., arrN, i.e. func(arr1[i], ..., arrN[i]). Unlike arrayCumSum, if the current running sum is smaller than 0, it is replaced by 0.

Syntax

Arguments

• arr — Array of numeric values.

Returned value

• Returns an array of non-negative partial sums of elements in the source array. UInt*, Int*, Float*.

Note that the arraySumNonNegative is a higher-order function. You can pass a lambda function to it as the first argument.

arrayProduct

Multiplies elements of an array.

Syntax

Arguments

• arr — Array of numeric values.

Returned value

• A product of array's elements. Float64.

Examples

Query:

Result:

Query:

Return value type is always Float64. Result:

arrayRotateLeft

Rotates an array to the left by the specified number of elements. If the number of elements is negative, the array is rotated to the right.

Syntax

Arguments

• arr — Array.
• n — Number of elements to rotate.

Returned value

• An array rotated to the left by the specified number of elements. Array.

Examples

Query:

Result:

Query:

Result:

Query:

Result:

arrayRotateRight

Rotates an array to the right by the specified number of elements. If the number of elements is negative, the array is rotated to the left.

Syntax

Arguments

• arr — Array.
• n — Number of elements to rotate.

Returned value

• An array rotated to the right by the specified number of elements. Array.

Examples

Query:

Result:

Query:

Result:

Query:

Result:

arrayShiftLeft

Shifts an array to the left by the specified number of elements. New elements are filled with the provided argument or the default value of the array element type. If the number of elements is negative, the array is shifted to the right.

Syntax

Arguments

• arr — Array.
• n — Number of elements to shift.
• default — Optional. Default value for new elements.

Returned value

• An array shifted to the left by the specified number of elements. Array.

Examples

Query:

Result:

Query:

Result:

Query:

Result:

Query:

Result:

Query:

Result:

arrayShiftRight

Shifts an array to the right by the specified number of elements. New elements are filled with the provided argument or the default value of the array element type. If the number of elements is negative, the array is shifted to the left.

Syntax

Arguments

• arr — Array.
• n — Number of elements to shift.
• default — Optional. Default value for new elements.

Returned value

• An array shifted to the right by the specified number of elements. Array.

Examples

Query:

Result:

Query:

Result:

Query:

Result:

Query:

Result:

Query:

Result:

arrayRandomSample

Function arrayRandomSample returns a subset with samples-many random elements of an input array. If samples exceeds the size of the input array, the sample size is limited to the size of the array, i.e. all array elements are returned but their order is not guaranteed. The function can handle both flat arrays and nested arrays.

Syntax

Arguments

• arr — The input array from which to sample elements. (Array(T))
• samples — The number of elements to include in the random sample (UInt*)

Returned Value

• An array containing a random sample of elements from the input array. Array.

Examples

Query:

Result:

Query:

Result:

Query:

Result:

arrayNormalizedGini

Calculates the normalized Gini coefficient.

Syntax

Arguments

• predicted — Predicted values (Array(T))
• label — Actual values (Array(T))

Returned Value

• A tuple containing the Gini coefficients of the predicted values, the Gini coefficient of the normalized values, and the normalized Gini coefficient (= the ratio of the former two Gini coefficients).

Examples

Query:

Result:

arrayLevenshteinDistance

Calculates Levenshtein distance for two arrays.

Syntax

Arguments

• from — first array
• to — second array

Returned Value

• Levenshtein distance between the first and the second arrays

Examples

Query:

Result:

arrayLevenshteinDistanceWeighted

Calculates Levenshtein distance for two arrays with custom weights for each element. Number of elements for array and its weights should match

Syntax

Arguments

• from — first array
• to — second array
• from_weights — weights for the first array
• to_weights — weights for the second array

Returned Value

• Levenshtein distance between the first and the second arrays with custom weights for each element

Examples

Query:

Result:

arraySimilarity

Calculates arrays' similarity from 0 to 1 based on weighed Levenshtein distance. Accepts the same arguments as arrayLevenshteinDistanceWeighted function.

Syntax

Arguments

• from — first array
• to — second array
• from_weights — weights for the first array
• to_weights — weights for the second array

Returned Value

• Similarity of two arrays based on the weighted Levenshtein distance

Examples

Query:

Result:

Distance functions

All supported functions are described in distance functions documentation.

array

Introduced in: v1.1

Syntax

Arguments

• x1 — Constant value of any type T. If only this argument is provided, the array will be of type T.
• [, x2, ..., xN] — Additional N constant values sharing a common supertype with x1

Returned value

Returns an 'Array(T)' type result, where 'T' is the smallest common type out of the passed arguments.

Examples

Valid usage

Invalid usage

arrayAUCPR

Introduced in: v20.4

Syntax

Arguments

• cores — Scores prediction model gives. Array of Integers or Floats.
• labels — Labels of samples, usually 1 for positive sample and 0 for negative sample. Array of Integers or Enums.
• partial_offsets —
• Optional. An Array(T) of three non-negative integers for calculating a partial area under the PR curve (equivalent to a vertical band of the PR space) instead of the whole AUC. This option is useful for distributed computation of the PR AUC. The array must contain the following elements [higher_partitions_tp, higher_partitions_fp, total_positives]. Array of non-negative Integers. Optional.
  • higher_partitions_tp: The number of positive labels in the higher-scored partitions.
  • higher_partitions_fp: The number of negative labels in the higher-scored partitions.
  • total_positives: The total number of positive samples in the entire dataset.

note

When arr_partial_offsets is used, the arr_scores and arr_labels should be only a partition of the entire dataset, containing an interval of scores. The dataset should be divided into contiguous partitions, where each partition contains the subset of the data whose scores fall within a specific range. For example:

• One partition could contain all scores in the range [0, 0.5).
• Another partition could contain scores in the range [0.5, 1.0].

Returned value

Returns area under the precision-recall (PR) curve. Float64.

Examples

Usage example

arrayAll

Introduced in: v1.1

Syntax

Arguments

• func(x[, y1, ..., yN]) — A lambda function which operates on elements of the source array (x) and condition arrays (y). Lambda function.
• source_arr — The source array to process. Array(T).
• [, cond1_arr, ... , condN_arr] — Optional. N condition arrays providing additional arguments to the lambda function. Array(T).

Returned value

Returns 1 if the lambda function returns true for all elements, 0 otherwise. UInt8.

Examples

All elements match

Not all elements match

arrayAvg

Introduced in: v21.1

Syntax

Arguments

• func(x[, y1, ..., yN]) — Optional. A lambda function which operates on elements of the source array (x) and condition arrays (y). Lambda function.
• source_arr — The source array to process. Array(T).
• [, cond1_arr, ... , condN_arr] — Optional. N condition arrays providing additional arguments to the lambda function. Array(T).

Returned value

Returns the average of elements in the source array, or the average of elements of the lambda results if provided. Float64.

Examples

Basic example

Usage with lambda function

arrayCompact

Introduced in: v20.1

Syntax

Arguments

• arr — An array to remove duplicates from. Array(T)

Returned value

Returns an array without duplicate values. Array(T).

Examples

Usage example

arrayConcat

Introduced in: v1.1

Syntax

Arguments

• arr1 [, arr2, ... , arrN] — N number of arrays to concatenate. Array(T).

Returned value

Returns a single combined array from the provided array arguments.

Examples

Usage example

arrayCount

Introduced in: v1.1

Syntax

Arguments

• func — Function to apply to each element of the array(s). Optional. Lambda function
• arr1, ..., arrN — N arrays. Array(T).

Returned value

Returns the number of elements for which func returns true. Otherwise, returns the number of non-zero elements in the array.

Examples

Usage example

arrayCumSum

Introduced in: v1.1

Syntax

Arguments

• func — Optional. A lambda function to apply to the array elements at each position. Lambda function.
• arr1 — The source array of numeric values. Array(T).
• [arr2, ..., arrN] — Optional. Additional arrays of the same size, passed as arguments to the lambda function if specified. Array(T).

Returned value

Returns an array of the partial sums of the elements in the source array. The result type matches the input array's numeric type.

Examples

Basic usage

With lambda

arrayCumSumNonNegative

Introduced in: v18.12

Syntax

Arguments

• func — Optional. A lambda function to apply to the array elements at each position. Lambda function.
• arr1 — The source array of numeric values. Array(T).
• [arr2, ..., arrN] — Optional. Additional arrays of the same size, passed as arguments to the lambda function if specified. Array(T).

Returned value

Returns an array of the partial sums of the elements in the source array, with any negative running sum replaced by zero. The result type matches the input array's numeric type.

Examples

Basic usage

With lambda

arrayDifference

Introduced in: v1.1

Syntax

Arguments

• arr — Array for which to calculate differences between adjacent elements. Array(T).

Returned value

Returns an array of differences between adjacent array elements. UInt*, Int*, Float*.

Examples

Usage example

Example of overflow due to result type Int64

arrayDistinct

Introduced in: v1.1

Syntax

Arguments

• arr — Array for which to extract distinct elements. Array(T).

Returned value

Returns an array containing the distinct elements. Array(T).

Examples

Usage example

arrayDotProduct

Introduced in: v23.5

Syntax

Arguments

• v1 — First vector. Array(T) or Tuple(T1, T2, ...) of numeric values.
• v2 — Second vector. Array(T) or Tuple(T1, T2, ...) of numeric values.

Returned value

The dot product of the two vectors. Numeric.

note

The return type is determined by the type of the arguments. If Arrays or Tuples contain mixed element types then the result type is the supertype.

Examples

Array example

Tuple example

arrayElement

Introduced in: v1.1

Syntax

Arguments

• arr — The array to search. Array(T).
• n — Position of the element to get. (U)Int*.

Returned value

Returns a single combined array from the provided array arguments. Array(T).

Examples

Usage example

Negative indexing

Using [n] notation

Index out of array bounds

arrayElementOrNull

Introduced in: v1.1

Syntax

Arguments

• arrays — Arbitrary number of arguments of Array type.

Returned value

Returns a single combined array from the provided array arguments.

Examples

Usage example

Negative indexing

Index out of array bounds

arrayEnumerate

Introduced in: v1.1

Syntax

Arguments

• arr — The array to enumerate. Array.

Returned value

Returns the array [1, 2, 3, ..., length (arr)]. Array(UInt32)

Examples

Basic example with ARRAY JOIN

arrayEnumerateDense

Introduced in: v18.12

Syntax

Arguments

• arr — The array to enumerate. Array(T).

Returned value

Returns an array of the same size as arr, indicating where each element first appears in the source array. Array(T).

Examples

Usage example

arrayEnumerateDenseRanked

Introduced in: v20.1

Syntax

Arguments

• clear_depth — Enumerate elements at the specified level separately. (U)Int* less than or equal to max_arr_depth.
• arr — N-dimensional array to enumerate. Array(T).
• max_array_depth — The maximum effective depth. Positive (U)Int* less than or equal to the depth of arr.

Returned value

Returns an array denoting where each element first appears in the source array. Array.

Examples

Basic usage

Usage with a multidimensional array

Example with increased clear_depth

arrayEnumerateUniq

Introduced in: v1.1

Syntax

Arguments

• arr1 — First array. Array(T).
• [arr2, ..., arrN] — Optional. Additional arrays of the same size for tuple uniqueness. Array(UInt32).

Returned value

Returns an array where each element is the position among elements with the same value or tuple. Array(T).

Examples

Basic usage

Multiple arrays

ARRAY JOIN aggregation

arrayEnumerateUniqRanked

Introduced in: v20.1

Syntax

Arguments

• clear_depth — Enumerate elements at the specified level separately. Positive Integer less than or equal to max_arr_depth.
• arr — N-dimensional array to enumerate. Array.
• max_array_depth — The maximum effective depth. Positive Integer less than or equal to the depth of arr.

Returned value

Returns an N-dimensional array the same size as arr with each element showing the position of that element in relation to other elements of the same value.

Examples

Example 1

Example 2

Example 3

Example 4

arrayExists

Introduced in: v1.1

Syntax

Arguments

• func(x[, y1, ..., yN]) — A lambda function which operates on elements of the source array (x) and condition arrays (y). Lambda function.
• source_arr — The source array to process. Array(T).
• [, cond1_arr, ... , condN_arr] — Optional. N condition arrays providing additional arguments to the lambda function. Array(T).

Returned value

Returns 1 if the lambda function returns true for at least one element, 0 otherwise. UInt8.

Examples

Usage example

arrayFill

Introduced in: v20.1

Syntax

Arguments

• func(x [, y1, ..., yN]) — A lambda function func(x [, y1, y2, ... yN]) → F(x [, y1, y2, ... yN]) which operates on elements of the source array (x) and condition arrays (y). Lambda function.
• source_arr — The source array to process Array(T).
• [, cond1_arr, ... , condN_arr] — Optional. N condition arrays providing additional arguments to the lambda function. Array(T).

Returned value

Returns an array. Array(T).

Examples

Example with single array

Example with two arrays

arrayFilter

Introduced in: v1.1

Syntax

Arguments

• func(x[, y1, ..., yN]) — A lambda function which operates on elements of the source array (x) and condition arrays (y). Lambda function.
• source_arr — The source array to process Array(T).
• [, cond1_arr, ... , condN_arr] — Optional. N condition arrays providing additional arguments to the lambda function. Array(T).

Returned value

Returns a subset of the source array. Array(T).

Examples

Example 1

Example 2

arrayFirst

Introduced in: v1.1

Syntax

Arguments

• func(x[, y1, ..., yN]) — A lambda function which operates on elements of the source array (x) and condition arrays (y). Lambda function.
• source_arr — The source array to process. Array(T).
• [, cond1_arr, ... , condN_arr] — Optional. N condition arrays providing additional arguments to the lambda function. Array(T).

Returned value

Returns the first element of the source array for which λ is true, otherwise returns the default value of T.

Examples

Usage example

No match

arrayFirstIndex

Introduced in: v1.1

Syntax

Arguments

• func(x[, y1, ..., yN]) — A lambda function which operates on elements of the source array (x) and condition arrays (y). Lambda function.
• source_arr — The source array to process. Array(T).
• [, cond1_arr, ... , condN_arr] — Optional. N condition arrays providing additional arguments to the lambda function. Array(T).

Returned value

Returns the index of the first element of the source array for which func is true, otherwise returns 0. UInt32.

Examples

Usage example

No match

arrayFirstOrNull

Introduced in: v1.1

Syntax

Arguments

• func(x[, y1, ..., yN]) — A lambda function which operates on elements of the source array (x) and condition arrays (y). Lambda function.
• source_arr — The source array to process. Array(T).
• [, cond1_arr, ... , condN_arr] — Optional. N condition arrays providing additional arguments to the lambda function. Array(T).

Returned value

Returns the first element of the source array for which func is true, otherwise returns NULL.

Examples

Usage example

No match

arrayFlatten

Introduced in: v20.1

Syntax

Arguments

• arr — A multidimensional array. Array(T)(Array)

Returned value

Returns a flattened array from the multidimensional array. Array(T).

Examples

Usage example

arrayFold

Introduced in: v23.10

Syntax

Arguments

• λ(x, x1 [, x2, x3, ... xN]) — A lambda function λ(acc, x1 [, x2, x3, ... xN]) → F(acc, x1 [, x2, x3, ... xN]) where F is an operation applied to acc and array values from x with the result of acc re-used. Lambda function.
• arr1 [, arr2, arr3, ... arrN] — N arrays over which to operate. Array(T)
• acc — Accumulator value with the same type as the return type of the Lambda function.

Returned value

Returns the final acc value.

Examples

Usage example

Fibonacci sequence

Example using multiple arrays

arrayIntersect

Introduced in: v1.1

Syntax

Arguments

• arrN — N arrays from which to make the new array. Array(T).

Returned value

Returns an array with distinct elements that are present in all N arrays. Array(T).

Examples

Usage example

arrayJaccardIndex

Introduced in: v23.7

Syntax

Arguments

• arr_x — First array. Array(T).
• arr_y — Second array. Array(T).

Returned value

Returns the Jaccard index of arr_x and arr_y.Float64

Examples

Usage example

arrayJoin

Introduced in: v1.1

Syntax

Arguments

• arr — An array to unfold. Array(T).

Returned value

Returns a set of rows unfolded from arr.

Examples

Basic usage

arrayJoin affects all sections of the query

Using multiple arrayJoin functions

Unexpected results due to optimizations

Using the ARRAY JOIN syntax

Using Tuple

arrayLast

Introduced in: v1.1

Syntax

Arguments

• func(x[, y1, ..., yN]) — A lambda function which operates on elements of the source array (x) and condition arrays (y). Lambda function.
• source — The source array to process. Array(T).
• [, cond1, ... , condN] — Optional. N condition arrays providing additional arguments to the lambda function. Array(T).

Returned value

Returns the last element of the source array for which func is true, otherwise returns the default value of T.

Examples

Usage example

No match

arrayLastIndex

Introduced in: v1.1

Syntax

Arguments

• func(x[, y1, ..., yN]) — A lambda function which operates on elements of the source array (x) and condition arrays (y). Lambda function.
• source_arr — The source array to process. Array(T).
• [, cond1_arr, ... , condN_arr] — Optional. N condition arrays providing additional arguments to the lambda function. Array(T).

Returned value

Returns the index of the last element of the source array for which func is true, otherwise returns 0. UInt32.

Examples

Usage example

No match

arrayLastOrNull

Introduced in: v1.1

Syntax

Arguments

• func(x [, y1, ..., yN]) — A lambda function which operates on elements of the source array (x) and condition arrays (y). Lambda function.
• source_arr — The source array to process. Array(T).
• [, cond1_arr, ... , condN_arr] — Optional. N condition arrays providing additional arguments to the lambda function. Array(T).

Returned value

Returns the last element of the source array for which λ is not true, otherwise returns NULL.

Examples

Usage example

No match

arrayLevenshteinDistance

Introduced in: v25.4

Syntax

Arguments

• from — The first array. Array(T).
• to — The second array. Array(T).

Returned value

Levenshtein distance between the first and the second arrays. Float64.

Examples

Usage example

arrayLevenshteinDistanceWeighted

Introduced in: v25.4

Syntax

Arguments

• from — first array. Array(T).
• to — second array. Array(T).
• from_weights — weights for the first array. Array(Float32).
• to_weights — weights for the second array. Array(Float32).

Returned value

Levenshtein distance between the first and the second arrays with custom weights for each element. Float64.

Examples

Usage example

arrayMap

Introduced in: v1.1

Syntax

Arguments

• func — A lambda function which operates on elements of the source array (x) and condition arrays (y). Lambda function.
• arr — N arrays to process. Array(T).

Returned value

Returns an array from the lambda results. Array(T)

Examples

Usage example

Creating a tuple of elements from different arrays

arrayMax

Introduced in: v21.1

Syntax

Arguments

• func(x[, y1, ..., yN]) — Optional. A lambda function which operates on elements of the source array (x) and condition arrays (y). Lambda function.
• source_arr — The source array to process. Array(T).
• [, cond1_arr, ... , condN_arr] — Optional. N condition arrays providing additional arguments to the lambda function. Array(T).

Returned value

Returns the maximum element in the source array, or the minimum element of the lambda results if provided.

Examples

Basic example

Usage with lambda function

arrayMin

Introduced in: v21.1

Syntax

Arguments

• func(x[, y1, ..., yN]) — Optional. A lambda function which operates on elements of the source array (x) and condition arrays (y). Lambda function.
• source_arr — The source array to process Array(T).
• [, cond1_arr, ... , condN_arr] — Optional. N condition arrays providing additional arguments to the lambda function. Array(T).

Returned value

Returns the minimum element in the source array, or the minimum element of the lambda results if provided.

Examples

Basic example

Usage with lambda function

arrayNormalizedGini

Introduced in: v25.1

Syntax

Arguments

• predicted — The predicted value. Array(T).
• label — The actual value. Array(T).

Returned value

A tuple containing the Gini coefficients of the predicted values, the Gini coefficient of the normalized values, and the normalized Gini coefficient (= the ratio of the former two Gini coefficients). Tuple(Float64, Float64, Float64).

Examples

Usage example

arrayPartialReverseSort

Introduced in: v23.2

Syntax

Arguments

• f(arr[, arr1, ... ,arrN]) — The lambda function to apply to elements of array x.
• arr — Array to be sorted. Array(T).
• arr1, ... ,arrN — N additional arrays, in the case when f accepts multiple arguments. Array(T).
• limit — Index value up until which sorting will occur. (U)Int*`]

Returned value

Returns an array of the same size as the original array where elements in the range [1..limit] are sorted in descending order. The remaining elements (limit..N] are in an unspecified order.

Examples

simple_int

simple_string

retain_sorted

lambda_simple

lambda_complex

arrayPartialShuffle

Introduced in: v23.2

Syntax

Arguments

• arr — The array to shuffle. Array(T).
• seed — Optional. The seed to be used with random number generation. If not provided, a random one is used. (U)Int*.
• limit — Optional. The number to limit element swaps to, in the range [1..N]. (U)Int*.

Returned value

Array with elements partially shuffled. Array(T)).

Examples

no_limit1

no_limit2

random_seed

explicit_seed

materialize

arrayPartialSort

Introduced in: v23.2

Syntax

Arguments

• f(arr[, arr1, ... ,arrN]) — The lambda function to apply to elements of array x.
• arr — Array to be sorted. Array(T).
• arr1, ... ,arrN — N additional arrays, in the case when f accepts multiple arguments. Array(T).
• limit — Index value up until which sorting will occur. (U)Int*`]

Returned value

Returns an array of the same size as the original array where elements in the range [1..limit] are sorted in ascending order. The remaining elements (limit..N] are in an unspecified order.

Examples

simple_int

simple_string

retain_sorted

lambda_simple

lambda_complex

arrayPopBack

Introduced in: v1.1

Syntax

Arguments

• arr — The array for which to remove the last element from. Array(T).

Returned value

Returns an array identical to arr but without the last element of arr. Array(T).

Examples

Usage example

arrayPopFront

Introduced in: v1.1

Syntax

Arguments

• arr — The array for which to remove the first element from. Array(T).

Returned value

Returns an array identical to arr but without the first element of arr. Array(T).

Examples

Usage example

arrayProduct

Introduced in: v21.1

Syntax

Arguments

• func(x[, y1, ..., yN]) — Optional. A lambda function which operates on elements of the source array (x) and condition arrays (y). Lambda function.
• source_arr — The source array to process Array(T).
• [, cond1_arr, ... , condN_arr] — Optional. N condition arrays providing additional arguments to the lambda function. Array(T).

Returned value

Returns the product of elements in the source array, or the product of elements of the lambda results if provided. Float64.

Examples

Basic example

Usage with lambda function

arrayPushBack

Introduced in: v1.1

Syntax

Arguments

• arr — The array for which to add value x to the end of. Array(T).
• x —
• Single value to add to the end of the array. Array(T).

note

• Only numbers can be added to an array with numbers, and only strings can be added to an array of strings.
• When adding numbers, ClickHouse automatically sets the type of x for the data type of the array.
• Can be NULL. The function adds a NULL element to an array, and the type of array elements converts to Nullable.

For more information about the types of data in ClickHouse, see Data types.

Returned value

Returns an array identical to arr but with an additional value x at the end of the array. Array(T).

Examples

Usage example

arrayPushFront

Introduced in: v1.1

Syntax

Arguments

• arr — The array for which to add value x to the end of. Array(T).
• x —
• Single value to add to the start of the array. Array(T).

note

• Only numbers can be added to an array with numbers, and only strings can be added to an array of strings.
• When adding numbers, ClickHouse automatically sets the type of x for the data type of the array.
• Can be NULL. The function adds a NULL element to an array, and the type of array elements converts to Nullable.

For more information about the types of data in ClickHouse, see Data types.

Returned value

Returns an array identical to arr but with an additional value x at the beginning of the array. Array(T).

Examples

Usage example

arrayROCAUC

Introduced in: v20.4

Syntax

Arguments

• scores — Scores prediction model gives. Array(T) of Integers or Floats.
• labels — Labels of samples, usually 1 for positive sample and 0 for negative sample. Array of Integers or Enums.
• scale — Decides whether to return the normalized area. If false, returns the area under the TP (true positives) x FP (false positives) curve instead. Default value: true. Bool. Optional.
• partial_offsets —
• An array of four non-negative integers for calculating a partial area under the ROC curve (equivalent to a vertical band of the ROC space) instead of the whole AUC. This option is useful for distributed computation of the ROC AUC. The array must contain the following elements [higher_partitions_tp, higher_partitions_fp, total_positives, total_negatives]. Array of non-negative Integers. Optional.
  • higher_partitions_tp: The number of positive labels in the higher-scored partitions.
  • higher_partitions_fp: The number of negative labels in the higher-scored partitions.
  • total_positives: The total number of positive samples in the entire dataset.
  • total_negatives: The total number of negative samples in the entire dataset.

note

When arr_partial_offsets is used, the arr_scores and arr_labels should be only a partition of the entire dataset, containing an interval of scores. The dataset should be divided into contiguous partitions, where each partition contains the subset of the data whose scores fall within a specific range. For example:

• One partition could contain all scores in the range [0, 0.5).
• Another partition could contain scores in the range [0.5, 1.0].

Returned value

Returns area under the receiver operating characteristic (ROC) curve. Float64.

Examples

Usage example

arrayRandomSample

Introduced in: v23.10

Syntax

Arguments

• arr — The input array or multidimensional array from which to sample elements. (Array(T)).
• samples — The number of elements to include in the random sample ((U)Int*).

Returned value

An array containing a random sample of elements from the input array. Array(T).

Examples

Usage example

Using a multidimensional array

arrayReduce

Introduced in: v1.1

Syntax

Arguments

• agg_f — The name of an aggregate function which should be a constant String.
• arr1 [, arr2, ... , arrN)] — N arrays corresponding to the arguments of agg_f. Array(T).

Returned value

Returns the result of the aggregate function

Examples

Usage example

Example with aggregate function using multiple arguments

Example with a parametric aggregate function

arrayReduceInRanges

Introduced in: v20.4

Syntax

Arguments

• agg_f — The name of the aggregate function to use. String
• ranges — The range over which to aggregate. An array of tuples, (i, r) containing the index i from which to begin from and the range r over which to aggregate Array(T)(Tuple(T1, T2, ...))
• arr1 [, arr2, ... ,arrN)] — N arrays as arguments to the aggregate function. Array(T).

Returned value

Returns an array containing results of the aggregate function over the specified ranges. Array(T).

Examples

Usage example

arrayResize

Introduced in: v1.1

Syntax

Arguments

• arr — Array to resize. Array(T)

• size — -The new length of the array. If size is less than the original size of the array, the array is truncated from the right. If size is larger than the initial size of the array, the array is extended to the right with extender values or default values for the data type of the array items.

• extender — Value to use for extending the array. Can be NULL.

Returned value

An array of length size. Array(T).

Examples

Example 1

Example 2

arrayReverse

Introduced in: v1.1

Syntax

Arguments

• arr — The array to reverse. Array(T).

Returned value

Returns an array of the same size as the original array containing the elements in reverse order. Array(T).

Examples

Usage example

arrayReverseFill

Introduced in: v20.1

Syntax

Arguments

• func(x[, y1, ..., yN]) — A lambda function which operates on elements of the source array (x) and condition arrays (y). Lambda function.
• source_arr — The source array to process Array(T).
• [, cond1_arr, ... , condN_arr] — Optional. N condition arrays providing additional arguments to the lambda function. Array(T).

Returned value

Returns an array with elements of the source array replaced by the results of the lambda. Array(T).

Examples

Example with a single array

Example with two arrays

arrayReverseSort

Introduced in: v1.1

Syntax

Arguments

• f(y1[, y2 ... yN]) — The lambda function to apply to elements of array x.
• arr — An array to be sorted. Array(T)
• arr1, ..., yN — Optional. N additional arrays, in the case when f accepts multiple arguments.

Returned value

Returns the array x sorted in descending order if no lambda function is provided, otherwise it returns an array sorted according to the logic of the provided lambda function, and then reversed. Array(T).

Examples

Example 1

Example 2

arrayReverseSplit

Introduced in: v20.1

Syntax

Arguments

• func(x[, y1, ..., yN]) — A lambda function which operates on elements of the source array (x) and condition arrays (y). Lambda function.
• source_arr — The source array to process. Array(T).
• [, cond1_arr, ... , condN_arr] — Optional. N condition arrays providing additional arguments to the lambda function. Array(T).

Returned value

Returns an array of arrays. Array(Array(T)).

Examples

Usage example

arrayRotateLeft

Introduced in: v23.8

Syntax

Arguments

• arr — The array for which to rotate the elements.Array(T).
• n — Number of elements to rotate. (U)Int8/16/32/64.

Returned value

An array rotated to the left by the specified number of elements. Array(T).

Examples

Usage example

Negative value of n

arrayRotateRight

Introduced in: v23.8

Syntax

Arguments

• arr — The array for which to rotate the elements.Array(T).
• n — Number of elements to rotate. (U)Int8/16/32/64.

Returned value

An array rotated to the right by the specified number of elements. Array(T).

Examples

Usage example

Negative value of n

arrayShiftLeft

Introduced in: v23.8

Syntax

Arguments

• arr — The array for which to shift the elements.Array(T).
• n — Number of elements to shift.(U)Int8/16/32/64.
• default — Optional. Default value for new elements.

Returned value

An array shifted to the left by the specified number of elements. Array(T).

Examples

Usage example

Negative value of n

Using a default value

arrayShiftRight

Introduced in: v23.8

Syntax

Arguments

• arr — The array for which to shift the elements. Array(T).
• n — Number of elements to shift. (U)Int8/16/32/64.
• default — Optional. Default value for new elements.

Returned value

An array shifted to the right by the specified number of elements. Array(T).

Examples

Usage example

Negative value of n

Using a default value

arrayShingles

Introduced in: v24.1

Syntax

Arguments

• arr — Array for which to generate an array of shingles. Array(T).
• l — The length of each shingle. (U)Int*

Returned value

An array of generated shingles. Array(T)

Examples

Usage example

arrayShuffle

Introduced in: v23.2

Syntax

Arguments

• arr — The array to shuffle. Array(T).
• seed (optional) — Optional. The seed to be used with random number generation. If not provided a random one is used. (U)Int*.

Returned value

Array with elements shuffled. Array(T).

Examples

Example without seed (unstable results)

Example without seed (stable results)

arraySimilarity

Introduced in: v25.4

Syntax

Arguments

• from — first array
• to — second array
• from_weights — weights for the first array
• to_weights — weights for the second array

Returned value

Returns the similarity between 0 and 1 of the two arrays based on the weighted Levenshtein distance. Float64.

Examples

Usage example

arraySlice

Introduced in: v1.1

Syntax

Arguments

• arr — Array to slice. Array(T).
• offset — Indent from the edge of the array. A positive value indicates an offset on the left, and a negative value is an indent on the right. Numbering of the array items begins with 1. (U)Int*.
• length — The length of the required slice. If you specify a negative value, the function returns an open slice [offset, array_length - length]. If you omit the value, the function returns the slice [offset, the_end_of_array]. (U)Int*.

Returned value

Returns a slice of the array with length elements from the specified offset. Array(T).

Examples

Usage example

arraySort

Introduced in: v1.1

Syntax

Arguments

• f(y1[, y2 ... yN]) — The lambda function to apply to elements of array x.
• arr — An array to be sorted. Array(T)
• arr1, ..., yN — Optional. N additional arrays, in the case when f accepts multiple arguments.

Returned value

Returns the array arr sorted in ascending order if no lambda function is provided, otherwise it returns an array sorted according to the logic of the provided lambda function. Array(T).

Examples

Example 1

Example 2

Example 3

arraySplit

Introduced in: v20.1

Syntax

Arguments

• func(x[, y1, ..., yN]) — A lambda function which operates on elements of the source array (x) and condition arrays (y).Lambda function.
• source_arr — The source array to split Array(T).
• [, cond1_arr, ... , condN_arr] — Optional. N condition arrays providing additional arguments to the lambda function. Array(T).

Returned value

Returns an array of arrays. Array(Array(T)).

Examples

Usage example

arrayStringConcat

Introduced in: v1.1

Syntax

Arguments

• arr — The source array of strings. Array(String).
• delimiter — Optional. The delimiter to insert between elements. String. Defaults to empty string if not specified.

Returned value

A string consisting of the array elements joined by the delimiter. String.

Examples

Basic usage

With delimiter

arraySum

Introduced in: v21.1

Syntax

Arguments

• func(x[, y1, ..., yN]) — Optional. A lambda function which operates on elements of the source array (x) and condition arrays (y). Lambda function.
• source_arr — The source array to process. Array(T).
• [, cond1_arr, ... , condN_arr] — Optional. N condition arrays providing additional arguments to the lambda function. Array(T).

Returned value

Returns the sum of elements in the source array, or the sum of elements of the lambda results if provided.

Examples

Basic example

Usage with lambda function

arraySymmetricDifference

Introduced in: v25.4

Syntax

Arguments

• arrN — N arrays from which to make the new array. Array(T).

Returned value

Returns an array of distinct elements not present in all source arrays. Array(T).

Examples

Usage example

arrayUnion

Introduced in: v24.10

Syntax

Arguments

• arrN — N arrays from which to make the new array. Array(T).

Returned value

Returns an array with distinct elements from the source arrays. Array(T).

Examples

Usage example

arrayUniq

Introduced in: v1.1

Syntax

Arguments

• arr1 — Array for which to count the number of unique elements. Array(T).
• [, arr2, ..., arrN] (optional) — Optional. Additional arrays used to count the number of unique tuples of elements at corresponding positions in multiple arrays. Array(T).

Returned value

For a single argument returns the number of unique elements. For multiple arguments returns the number of unique tuples made from elements at corresponding positions across the arrays. UInt32.

Examples

Single argument

Multiple argument

arrayWithConstant

Introduced in: v20.1

Syntax

Arguments

• length — Number of elements in the array. (U)Int*.
• x — The value of the N elements in the array, of any type.

Returned value

Returns an Array with N elements of value x.

Examples

Usage example

arrayZip

Introduced in: v20.1

Syntax

Arguments

• arr1, arr2, ... , arrN — N arrays to combine into a single array. Array(T)

Returned value

Returns an array with elements from the source arrays grouped in tuples. Data types in the tuple are the same as types of the input arrays and in the same order as arrays are passed. Array(T)(Tuple).

Examples

Usage example

arrayZipUnaligned

Introduced in: v20.1

Syntax

Arguments

• arr1, arr2, ..., arrN — N arrays to combine into a single array. Array(T).

Returned value

Returns an array with elements from the source arrays grouped in tuples. Data types in the tuple are the same as types of the input arrays and in the same order as arrays are passed. Array(T)(Tuple(T1, T2, ...)).

Examples

Usage example

countEqual

Introduced in: v1.1

Syntax

Arguments

• arr — Array to search. Array(T).
• x — Value in the array to count. Any type.

Returned value

Returns the number of elements in the array equal to x. UInt64.

Examples

Usage example

empty

Introduced in: v1.1

Syntax

Arguments

• arr — Input array. Array(T).

Returned value

Returns 1 for an empty array or 0 for a non-empty array. UInt8.

Examples

Usage example

emptyArrayDate

Introduced in: v1.1

Syntax

Arguments

• None. Returned value

An empty Date array. Array(T).

Examples

Usage example

emptyArrayDateTime

Introduced in: v1.1

Syntax

Arguments

• None. Returned value

An empty DateTime array. Array(T).

Examples

Usage example

emptyArrayFloat32

Introduced in: v1.1

Syntax

Arguments

• None. Returned value

An empty Float32 array. Array(T).

Examples

Usage example

emptyArrayFloat64

Introduced in: v1.1

Syntax

Arguments

• None. Returned value

An empty Float64 array. Array(T).

Examples

Usage example

emptyArrayInt16

Introduced in: v1.1

Syntax

Arguments

• None. Returned value

An empty Int16 array. Array(T).

Examples

Usage example

emptyArrayInt32

Introduced in: v1.1

Syntax

Arguments

• None. Returned value

An empty Int32 array. Array(T).

Examples

Usage example

emptyArrayInt64

Introduced in: v1.1

Syntax

Arguments

• None. Returned value

An empty Int64 array. Array(T).

Examples

Usage example

emptyArrayInt8

Introduced in: v1.1

Syntax

Arguments

• None. Returned value

An empty Int8 array. Array(T).

Examples

Usage example

emptyArrayString

Introduced in: v1.1

Syntax

Arguments

• None. Returned value

An empty String array. Array(T).

Examples

Usage example

emptyArrayToSingle

Introduced in: v1.1

Syntax

Arguments

• arr — An empty array. Array(T)

Returned value

An array with a single value of the Array's default type.

Examples

Basic example

emptyArrayUInt16

Introduced in: v1.1

Syntax

Arguments

• None. Returned value

An empty UInt16 array. Array(T).

Examples

Usage example

emptyArrayUInt32

Introduced in: v1.1

Syntax

Arguments

• None. Returned value

An empty UInt32 array. Array(T).

Examples

Usage example

emptyArrayUInt64

Introduced in: v1.1

Syntax

Arguments

• None. Returned value

An empty UInt64 array. Array(T).

Examples

Usage example

emptyArrayUInt8

Introduced in: v1.1

Syntax

Arguments

• None. Returned value

An empty UInt8 array. Array(T).

Examples

Usage example

has

Introduced in: v1.1

Syntax

Arguments

• arr — The source array. Array(T).
• x — The value to search for in the array.

Returned value

Returns 1 if the array contains the specified element, otherwise 0. UInt8.

Examples

Basic usage

Not found

hasAll

Introduced in: v1.1

Syntax

Arguments

• set — Array of any type with a set of elements. Array.
• subset — Array of any type that shares a common supertype with set containing elements that should be tested to be a subset of set. Array.

Returned value

• 1, if set contains all of the elements from subset.
• 0, otherwise.

Raises a NO_COMMON_TYPE exception if the set and subset elements do not share a common supertype.

Examples

Empty arrays

Arrays containing NULL values

Arrays containing values of a different type

Arrays containing String values

Arrays without a common type

Array of arrays

hasAny

Introduced in: v1.1

Syntax

Arguments

• arr_x — Array of any type with a set of elements. Array(T).
• arr_y — Array of any type that shares a common supertype with array arr_x. Array(T).

Returned value

• 1, if arr_x and arr_y have one similar element at least.
• 0, otherwise.

Raises a NO_COMMON_TYPE exception if any of the elements of the two arrays do not share a common supertype.

Examples

One array is empty

Arrays containing NULL values

Arrays containing values of a different type

Arrays without a common type

Array of arrays

hasSubstr

Introduced in: v20.6

Syntax

Arguments

• arr1 — Array of any type with a set of elements. Array(T).
• arr2 — Array of any type with a set of elements. Array(T).

Returned value

Returns 1 if array arr1 contains array arr2. Otherwise, returns 0.

Examples

Both arrays are empty

Arrays containing NULL values

Arrays containing values of a different type

Arrays containing strings

Arrays with valid ordering

Arrays with invalid ordering

Array of arrays

Arrays without a common type

indexOf

Introduced in: v1.1

Syntax

Arguments

• arr — An array to search in for x. Array.
• x — Value of the first matching element in arr for which to return an index. UInt64.

Returned value

Returns the index (numbered from one) of the first x in arr if it exists. Otherwise, returns 0.

Examples

Basic example

Array with nulls

indexOfAssumeSorted

Introduced in: v24.12

Syntax

Arguments

• arr — A sorted array to search. Array(T).
• x — Value of the first matching element in sorted arr for which to return an index.UInt64

Returned value

Returns the index (numbered from one) of the first x in arr if it exists. Otherwise, returns 0.

Examples

Basic example

length

Introduced in: v1.1

Syntax

Arguments

• x — String, FixedString or Array for which to calculate the number of bytes (for String/FixedString) or elements (for Array).

Returned value

Returns the number of number of bytes in the String/FixedString x / the number of elements in array x

Examples

string1

arr1

constexpr

unicode

ascii_vs_utf8

notEmpty

Introduced in: v1.1

Syntax

Arguments

• arr — Input array. Array(T).

Returned value

Returns 1 for a non-empty array or 0 for an empty array. UInt8.

Examples

Usage example

range

Introduced in: v1.1

Syntax

Arguments

• start — Optional. The first element of the array. Required if step is used. Default value: 0.
• end — Required. The number before which the array is constructed.
• step — Optional. Determines the incremental step between each element in the array. Default value: 1.

Returned value

Array of numbers from start to end - 1 by step.

Examples

Usage example

reverse

Introduced in: v

Syntax

Arguments

• arr | str — The source array or string. Array(T), String.

Returned value

Returns an array or string with the order of elements or characters reversed.

Examples

Reverse array

Reverse string