view release on metacpan or  search on metacpan

README.md  view on Meta::CPAN

- `raw => 1`

    HTTP only. The callback receives the raw response body as a scalar string
    instead of parsed rows. Use with an explicit `format` clause:

        $ch->query("select * from t format CSV", { raw => 1 }, sub {
            my ($body, $err) = @_;
        });

    Croaks if used with the native protocol.

- `query_timeout => $seconds`

    Per-query timeout, overriding the connection-level `query_timeout`.

- `on_data => sub { my ($rows) = @_; ... }`

    Native protocol only. A code ref called for each data block as it arrives,
    for streaming large result sets. Rows are delivered incrementally and
    **not** accumulated, so the final callback receives `(undef)` rather than
    all rows. The final callback always fires on completion or error, even if
    no data block was emitted (empty result, server-side error before the
    first block).

        $ch->query("select * from big_table",
            { on_data => sub { my ($rows) = @_; process_batch($rows) } },
            sub { my (undef, $err) = @_; warn $err if $err },
        );

- `external => \%tables`

    Native protocol only. Ships one or more in-memory data blocks that the
    query can reference as tables, JOIN against, or filter with `IN` -
    without creating a server-side temporary table. Each entry maps a table
    name to `{ structure => [...], data => [...] }`:

        $ch->query(
            "select u.id, u.name from users u where u.id in _wanted",
            { external => {
                _wanted => {
                    structure => [ id => 'UInt64' ],
                    data      => [ [7], [42], [911] ],
                },
            } },
            sub { my ($rows, $err) = @_; ... },
        );

    `structure` is a flat list of `name => type` pairs (ClickHouse type
    names, e.g. `UInt64`, `String`, `Float64`); `data` is an arrayref of
    row arrayrefs, encoded with the same type machinery as ["insert"](#insert). An
    empty `data` arrayref is a valid zero-row table. Several external tables
    may be supplied at once. Croaks on the HTTP protocol or on a malformed
    spec (odd structure list, non-arrayref row, or a column type that
    cannot be encoded).

**Native protocol type notes:** values come back as typed Perl scalars.
By default `Date`/`DateTime` are integers (days since epoch / Unix
timestamps); enable `decode_datetime` for strings. `Enum` values are
numeric codes; `decode_enum` returns labels. `Decimal` values are
unscaled integers; `decode_decimal` scales them to floats.
`SimpleAggregateFunction` is transparently decoded as its inner type.
`Nested` columns become arrays of tuples. `LowCardinality` works
correctly across multi-block results with shared dictionaries.

## insert

    $ch->insert($table, $data, sub { my (undef, $err) = @_ });
    $ch->insert($table, $data, \%settings, sub { my (undef, $err) = @_ });

`$data` may be either:

- A pre-formatted TabSeparated string (tabs separate columns,
newlines separate rows, with the standard ClickHouse escapes).
- An arrayref of arrayrefs (rows of column values).

When using arrayrefs, no TSV escaping is needed: `undef` maps to null
and strings may contain tabs and newlines freely.

Nested arrayrefs (Array/Tuple columns) and hashrefs (Map columns) are
supported **only on the native protocol**, where the encoder has the
column type from the server's sample block. On HTTP the same call
croaks rather than silently produce malformed TSV; use the native
protocol or pre-serialise nested types into ClickHouse TSV literal form.

    # Native: nested types encode directly.
    $ch->insert("my_table", [
        [1, "hello\tworld"],   # embedded tab
        [2, undef],            # null
        [3, [10, 20]],         # Array column   (native only)
        [4, { a => 1, b => 2 }],  # Map column  (native only)
    ], sub { ... });

The optional `\%settings` hashref works exactly as in ["query"](#query),
including `query_id`, `query_timeout`, and `params`. Two extra
flags are recognised here:

- `idempotent => 1 | $token`

    Auto-mints (or uses the supplied) `insert_deduplication_token`, so a
    reconnect-driven retry of the same insert doesn't double-write. Falsy
    values are a no-op.

- `async_insert => 1`

    Enables ClickHouse server-side insert batching by setting
    `async_insert=1, wait_for_async_insert=0`. Both sub-settings can be
    overridden by passing them explicitly.

## ping

    $ch->ping(sub { my ($result, $err) = @_ });

Send a no-op round trip to verify the connection is alive. On success
`$result` is true, `$err` is `undef`. On error: `(undef, $error)`.

## is\_healthy

    $ch->is_healthy(sub { my ($ok, $err) = @_ });
    $ch->is_healthy(sub { ... }, $timeout_seconds);

Bounded health probe: wraps ["ping"](#ping) with a deadline (default 5s). The