The ClickHouse client (Effect's @effect/sql-clickhouse
ClickhouseClient): an SqlClient over ClickHouse's HTTP interface,
with typed parameters (param), commands (as_command), inserts in any
format (insert_query) and per-effect query ids and settings.
make checks the server with /ping (within five seconds). Statements
compile to {p1: Type} placeholders, the type inferred from the value
(params.type_of) unless param names it, and "quoted" names::
program.pipe(fx.provide(clickhouse.layer(clickhouse.ClickhouseClientConfig(url=...))))A statement runs as a query with FORMAT JSON appended, which a
statement with data (INSERT ... VALUES) does not accept: run those with
as_command or use insert_query.
Re-exports#
- From
pyfect.sql.clickhouse:ClickhouseSettings,ClientMethod,QueryId - From
pyfect.sql.error:SqlError
Values#
| Attribute | Type | Description |
|---|---|---|
is_clickhouse_param | (object) -> TypeIs[Custom[Any, Any, Any, Any]] | |
CONNECT_TIMEOUT | Literal['5 seconds'] = '5 seconds' | How long |
Types#
| Type | Definition | Description |
|---|---|---|
ClickhouseParam | type ClickhouseParam = Custom[str, str, object, None] | A parameter bound as a named ClickHouse type ( |
Classes#
Functions#
make_compiler#
make_compiler(transform=None) -> CompilerClickHouse's compiler: {p1: Type} placeholders and "quoted"
names (renamed with transform unless a statement runs without
transforms).
| Parameter | Type | Description |
|---|---|---|
transform | Callable[[str], str] | None = None |
Returns Compiler
def make_compiler(transform: Callable[[str], str] | None = None) -> Compiler:
"""ClickHouse's compiler: ``{p1: Type}`` placeholders and ``"quoted"``
names (renamed with ``transform`` unless a statement runs without
transforms)."""
def on_identifier(value: str, without_transform: bool) -> str:
if transform is None or without_transform:
return _escape(value)
return _escape(transform(value))
return make_statement_compiler(
dialect="clickhouse",
placeholder=lambda index, value: f"{{p{index}: {_placeholder_type(value)}}}",
on_identifier=on_identifier,
on_record_update=_nothing,
on_custom=_on_custom,
)make#
make(config) -> Effect[ClickhouseClientService, SqlError, Scope | Reactivity]A client on config's server; the HTTP client it creates closes
with the scope.
| Parameter | Type | Description |
|---|---|---|
config | ClickhouseClientConfig |
Returns Effect[ClickhouseClientService, SqlError, Scope | Reactivity]
def make(
config: ClickhouseClientConfig,
) -> Effect[ClickhouseClientService, SqlError, Scope | Reactivity]:
"""A client on ``config``'s server; the HTTP client it creates closes
with the scope."""
compiler = make_compiler(config.transform_query_names)
transform_rows = (
None
if config.transform_result_names is None
else default_transforms(config.transform_result_names).array
)
span_attributes: list[tuple[str, object]] = [
*config.span_attributes.items(),
("db.system.name", "clickhouse"),
("db.namespace", config.connection.database),
]
def build(http: Any) -> Effect[ClickhouseClientService, SqlError, Reactivity]:
driver = ClickhouseDriver(http, config.connection)
connected = (
driver.ping()
.map_error(catch("ClickhouseClient: Failed to connect", "connect", "connection"))
.timeout_or_else(CONNECT_TIMEOUT, _connect_timed_out)
)
connection: Connection = ClickhouseConnection(driver)
client = make_sql_client(
driver="clickhouse",
acquirer=succeed(connection),
compiler=compiler,
span_attributes=span_attributes,
begin_transaction="BEGIN TRANSACTION",
transform_rows=transform_rows,
)
def finish(c: SqlClientService) -> ClickhouseClientService:
return ClickhouseClientService(config=config, client=driver, **c.fields())
return connected.and_then(client.map(finish))
return _config_warnings(config).and_then(_http_client(config).flat_map(build))layer_from#
layer_from[E](acquire) -> Layer[ClickhouseClient | SqlClient, E]Provides the client acquire makes as ClickhouseClient and
SqlClient, with its own Reactivity.
| Parameter | Type | Description |
|---|---|---|
acquire | Effect[ClickhouseClientService, E, Scope | Reactivity] |
Returns Layer[ClickhouseClient | SqlClient, E]
def layer_from[E](
acquire: Effect[ClickhouseClientService, E, Scope | Reactivity],
) -> Layer[ClickhouseClient | SqlClient, E]:
"""Provides the client ``acquire`` makes as ``ClickhouseClient`` and
``SqlClient``, with its own ``Reactivity``."""
require_effect(acquire, "acquire")
return layer_effect_context(acquire.map(_contexts)).pipe(provide(reactivity_layer))layer#
layer(config) -> Layer[ClickhouseClient | SqlClient, SqlError]Provides a client (make).
| Parameter | Type | Description |
|---|---|---|
config | ClickhouseClientConfig |
Returns Layer[ClickhouseClient | SqlClient, SqlError]
def layer(config: ClickhouseClientConfig) -> Layer[ClickhouseClient | SqlClient, SqlError]:
"""Provides a client (``make``)."""
return layer_from(make(config))layer_config#
layer_config(config) -> Layer[ClickhouseClient | SqlClient, ConfigError | SqlError]layer with the config read from the ConfigProvider: a
Config of the whole config, or a mapping from field names to their
Config (Effect's Config.Wrap)::
clickhouse.layer_config({
"url": fx.config.string("CLICKHOUSE_URL"),
"password": fx.config.redacted("CLICKHOUSE_PASSWORD"),
})| Parameter | Type | Description |
|---|---|---|
config | Config[ClickhouseClientConfig] | Mapping[str, Any] |
Returns Layer[ClickhouseClient | SqlClient, ConfigError | SqlError]
def layer_config(
config: Config[ClickhouseClientConfig] | Mapping[str, Any],
) -> Layer[ClickhouseClient | SqlClient, ConfigError | SqlError]:
"""``layer`` with the config read from the ``ConfigProvider``: a
``Config`` of the whole config, or a mapping from field names to their
``Config`` (Effect's ``Config.Wrap``)::
clickhouse.layer_config({
"url": fx.config.string("CLICKHOUSE_URL"),
"password": fx.config.redacted("CLICKHOUSE_PASSWORD"),
})
"""
read: Effect[ClickhouseClientConfig, ConfigError] = (
config
if isinstance(config, Config)
else unwrap(config).map(lambda fields: ClickhouseClientConfig(**fields))
)
return layer_from(read.flat_map(make))