ChDriver.Params (ch_driver v0.1.1)

Copy Markdown

Converts Elixir values into ClickHouse query parameters.

Every bound query parameter needs three things: a ClickHouse type name for its {name:Type} placeholder, the literal text of its value, and how many rounds of escaping that text needs on the wire. type/1, text/1, and escape_rounds/1 produce each of those from a plain Elixir value; encode/1 returns all three at once.

nil isn't supported here — see text/1's docs.

Summary

Functions

encode(term)

Encodes term as {type, text, rounds} — the ClickHouse type name for its {name:Type} placeholder (see type/1), the literal text for its value (see text/1), and the escaping depth that text needs on the wire (see escape_rounds/1).

escape_rounds(list)

How many rounds of backslash/quote escaping value's bound text needs to round-trip through ClickHouse correctly: 1 for a list, 2 for everything else.

text(b)

Renders an Elixir term as ClickHouse literal text — the same text you'd write after CAST(..., 'Type') for that value, unquoted and unescaped.

type(b)

Maps an Elixir value to the ClickHouse type name for its {name:Type} placeholder, e.g. 5 -> "Int64", "hi" -> "String".

Functions

encode(term)

@spec encode(term()) :: {binary(), binary(), 1 | 2}

Encodes term as {type, text, rounds} — the ClickHouse type name for its {name:Type} placeholder (see type/1), the literal text for its value (see text/1), and the escaping depth that text needs on the wire (see escape_rounds/1).

escape_rounds(list)

@spec escape_rounds(term()) :: 1 | 2

How many rounds of backslash/quote escaping value's bound text needs to round-trip through ClickHouse correctly: 1 for a list, 2 for everything else.

Takes the same Elixir term you'd pass to text/1, not its rendered text. See ChDriver.Query's wire encoding for where this gets applied — the two escaping depths aren't arbitrary, they match how ClickHouse's server actually unescapes scalar values vs. array elements (see ARCHITECTURE.md if you're curious why).

text(b)

@spec text(term()) :: binary()

Renders an Elixir term as ClickHouse literal text — the same text you'd write after CAST(..., 'Type') for that value, unquoted and unescaped.

There's no clause for nil: ClickHouse query parameters have no type-independent way to express NULL. If your value can be nil, inline a literal NULL into the query text yourself instead of binding it as a parameter.

type(b)

@spec type(term()) :: binary()

Maps an Elixir value to the ClickHouse type name for its {name:Type} placeholder, e.g. 5 -> "Int64", "hi" -> "String".

Raises ArgumentError for nil and for any type this driver doesn't know how to bind — see text/1 for why nil isn't supported.