arrayFilter
Keep only the array elements that match a lambda predicate — the array-native WHERE clause.
Signature
arrayFilter(func: x -> UInt8, arr: Array(T)): Array(T)Returns
Array(T) — a new array of the same element type, containing only the matching elements
What it does
Returns a new array containing only the elements of the input array for which the lambda x -> cond evaluates to a nonzero value. The array-column equivalent of a WHERE clause.
arrayFilter walks an array and keeps every element where the lambda predicate returns nonzero (truthy), dropping the rest. It uses the same x -> expr lambda syntax as arrayMap, so the two pair naturally: filter an array down to the elements you care about, then map over the survivors — all in a single SQL expression, with no subquery or arrayJoin round-trip. Because it operates row-by-row on the array column, it is the idiomatic way to slice event lists, tag arrays, or per-order line items before aggregating with functions like groupArray, sum, or length.
Notes
- The lambda must return a nonzero value to keep an element; ClickHouse treats any nonzero number as true, so predicates like x -> x > 100 or x -> x != '' work directly.
- arrayFilter uses the same x -> expr lambda syntax as arrayMap, so you can filter then map in one expression — arrayMap(x -> x * 2, arrayFilter(x -> x > 100, order_values)) — without a subquery.
- When you only need a boolean or a count rather than the filtered array, reach for the predicate cousins: arrayExists (any element matches), arrayAll (every element matches), and arrayCount (how many match).
- In hypequery there is no dedicated array-lambda builder method — pass the whole arrayFilter(...) call through selectExpr(sql, alias) inside .select([...]) and you still get typed results back.
Example SQL
arrayFilter in ClickHouse SQL
TypeScript with hypequery
Use arrayFilter in a typed TypeScript query
hypequery gives you a type-safe query builder for ClickHouse. The generated schema maps your ClickHouse columns to TypeScript types, and raw SQL expressions let you incorporate functions like arrayFilter when you need them inside a builder query.
Common questions
What developers search for with arrayFilter
Filter an array column in ClickHouse
arrayFilter(x -> cond, arr) is the array-native WHERE clause: it returns a new array of only the elements where the lambda is nonzero, leaving the rest of the row untouched.
arrayFilter vs arrayMap
arrayMap transforms every element; arrayFilter drops the ones that fail a predicate. They share the x -> expr lambda syntax, so nest them to filter then transform in a single expression.
ClickHouse array filtering in TypeScript
hypequery has no array-lambda builder method, so pass arrayFilter(x -> x > 100, order_values) through selectExpr inside .select([...]) and get a typed array back on the result row.
FAQ
Frequently asked questions about arrayFilter
What does arrayFilter return?
A new array of the same element type containing only the elements for which the lambda x -> cond returned a nonzero value. Non-matching elements are removed and the original array is unchanged.
How is arrayFilter different from arrayExists or arrayCount?
arrayFilter returns the filtered array itself, while arrayExists returns 1 if any element matches, arrayAll returns 1 only if every element matches, and arrayCount returns how many matched. Use the predicate versions when you need a boolean or a number instead of the sub-array.
Can I use arrayFilter in hypequery's query builder?
Yes. There is no dedicated array-lambda method, so wrap the full call in selectExpr('arrayFilter(x -> x > 100, order_values)', 'large_orders') inside .select([...]). hypequery passes the raw expression through and still types the returned column.
Next step
Use arrayFilter in a type-safe TypeScript query
hypequery generates TypeScript types from your ClickHouse schema. Use arrayFilter alongside the builder, and reach for raw SQL expressions when the function is not exposed as a dedicated helper.