Skip to main content
Skip to main content
Edit this page

Array Functions

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

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

Returned value

Returns the Jaccard index of arr_x and arr_y.Float64

Examples

Usage example

arrayJoin​

Introduced in: v1.1

Syntax

Arguments

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

Returned value

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

Examples

Usage example

arrayLevenshteinDistanceWeighted​

Introduced in: v25.4

Syntax

Arguments

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

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

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

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

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

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

Returned value

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

Examples

Reverse array

Reverse string

Distance functions​

All supported functions are described in distance functions documentation.