view release on metacpan or  search on metacpan

lib/EV/ClickHouse.pm  view on Meta::CPAN

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

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

Croaks if used with the native protocol.

=item C<query_timeout =E<gt> $seconds>

Per-query timeout, overriding the connection-level C<query_timeout>.

=item C<on_data =E<gt> 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
B<not> accumulated, so the final callback receives C<(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 },
    );

=item C<external =E<gt> \%tables>

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

    $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) = @_; ... },
    );

C<structure> is a flat list of C<name =E<gt> type> pairs (ClickHouse type
names, e.g. C<UInt64>, C<String>, C<Float64>); C<data> is an arrayref of
row arrayrefs, encoded with the same type machinery as L</insert>. An
empty C<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).

=back

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

=head2 insert

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

C<$data> may be either:

=over 4

=item * A pre-formatted TabSeparated string (tabs separate columns,
newlines separate rows, with the standard ClickHouse escapes).

=item * An arrayref of arrayrefs (rows of column values).

=back

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

Nested arrayrefs (Array/Tuple columns) and hashrefs (Map columns) are
supported B<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 C<\%settings> hashref works exactly as in L</query>,
including C<query_id>, C<query_timeout>, and C<params>. Two extra
flags are recognised here:

=over 4

=item C<idempotent =E<gt> 1 | $token>

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

=item C<async_insert =E<gt> 1>

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

=back

=head2 ping

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