view release on metacpan or  search on metacpan

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

formatted strings (e.g. C<"2024-01-15">, C<"2024-01-15 10:30:00">) instead
of raw integer values. Uses UTC by default; if the column has an explicit
timezone (e.g. C<DateTime('America/New_York')>), values are converted to
that timezone.

=item decode_decimal => 0 | 1

Return C<Decimal32>/C<Decimal64>/C<Decimal128> columns as scaled
floating-point numbers instead of unscaled integers.

=item decode_enum => 0 | 1

Return C<Enum8>/C<Enum16> columns as string labels instead of numeric codes.

=item named_rows => 0 | 1

Return each row as a hashref (keyed by column name) instead of an arrayref.

    my $ch = EV::ClickHouse->new(named_rows => 1, ...);
    $ch->query("SELECT 1 as n", sub {
        my ($rows, $err) = @_;
        print $rows->[0]{n};  # 1
    });

=back

=head1 METHODS

=head2 query

    $ch->query($sql, sub { my ($rows, $err) = @_ });
    $ch->query($sql, \%settings, sub { my ($rows, $err) = @_ });

Executes a SQL query. For SELECT: callback receives C<($arrayref_of_arrayrefs)>.
For DDL/DML: callback receives C<(undef)> on success.
On error: C<(undef, $error_message)>.

The optional C<\%settings> hashref passes per-query ClickHouse settings
(e.g. C<max_execution_time>, C<max_threads>). These override any
connection-level defaults. Special keys (not sent to the server):

=over 4

=item C<query_id> — sets the query identifier (protocol-level field)

=item C<raw> — HTTP only. When true, the callback receives the raw response
body as a scalar string instead of parsed rows. Use this with an explicit
C<FORMAT> clause (CSV, JSONEachRow, Parquet, etc.):

    $ch->query("SELECT * FROM t FORMAT CSV", { raw => 1 }, sub {
        my ($body, $err) = @_;
        # $body is the raw CSV text
    });

Not supported with the native protocol (croaks).

=item C<query_timeout> — per-query timeout in seconds, overriding the
connection-level C<query_timeout>.

=item C<on_data> — native protocol only. A code ref called for each data
block as it arrives. Enables streaming: rows are delivered incrementally
and not accumulated.

    $ch->query("SELECT * FROM big_table",
        { on_data => sub { my ($rows) = @_; process_batch($rows) } },
        sub { my (undef, $err) = @_; ... }  # final callback
    );

=back

B<Native protocol type notes:> With the native protocol, column values
are returned as typed Perl scalars by default. C<Date> and C<DateTime>
columns return integer values (days since epoch and Unix timestamps);
enable C<decode_datetime> for formatted strings. C<Enum> columns return
numeric codes; enable C<decode_enum> for string labels. C<Decimal>
columns return unscaled integers; enable C<decode_decimal> for scaled
floats. C<SimpleAggregateFunction> columns are transparently decoded as
their inner type. C<Nested> columns are decoded as arrays of tuples.
C<LowCardinality> columns work 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> can be either:

=over 4

=item * A string in TabSeparated format (tab-separated columns, newline-separated rows)

=item * An arrayref of arrayrefs: C<[ [$col1, $col2, ...], ... ]>

=back

When using arrayrefs, values are encoded directly without TSV escaping:
C<undef> maps to NULL, strings may contain tabs and newlines freely,
arrayrefs encode Array/Tuple columns, and hashrefs encode Map columns.

    # TSV string (existing)
    $ch->insert("my_table", "1\thello\n2\tworld\n", sub { ... });

    # Arrayref (new) — no escaping needed
    $ch->insert("my_table", [
        [1, "hello\tworld"],      # embedded tab
        [2, undef],               # NULL
        [3, [10, 20]],            # Array column
    ], sub { ... });

The optional C<\%settings> hashref works the same as in L</query>.

=head2 ping

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

Checks if the connection is alive. On success C<$result> is a true value
and C<$err> is undef.  On error: C<(undef, $error_message)>.

=head2 finish