Metadata-Version: 2.4
Name: meridian-storage-clickhouse
Version: 1.0.0
Summary: ClickHouse adapter for Meridian V1 evidence and time-series operations
Project-URL: Documentation, https://github.com/zephytiju/meridian-storage-clickhouse#readme
Project-URL: Issues, https://github.com/zephytiju/meridian-storage-clickhouse/issues
Project-URL: Repository, https://github.com/zephytiju/meridian-storage-clickhouse
Author: Meridian contributors
License-Expression: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Keywords: adapter,analytics,clickhouse,meridian,observability,time-series
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Typing :: Typed
Requires-Python: <3.15,>=3.12
Requires-Dist: clickhouse-connect<0.16,>=0.15
Requires-Dist: meridian-storage-core==1.0.0
Requires-Dist: meridian-storage-query==1.0.0
Requires-Dist: meridian-storage-semantics==1.0.0
Provides-Extra: test
Requires-Dist: build<2,>=1.2; extra == 'test'
Requires-Dist: hatchling==1.27.0; extra == 'test'
Requires-Dist: hypothesis<7,>=6.135; extra == 'test'
Requires-Dist: jsonschema<5,>=4.23; extra == 'test'
Requires-Dist: mypy<2,>=1.15; extra == 'test'
Requires-Dist: packaging<27,>=24; extra == 'test'
Requires-Dist: pytest-cov<8,>=6; extra == 'test'
Requires-Dist: pytest<10,>=8.3; extra == 'test'
Requires-Dist: ruff<1,>=0.11; extra == 'test'
Requires-Dist: twine<7,>=6; extra == 'test'
Description-Content-Type: text/markdown

<!-- SPDX-License-Identifier: Apache-2.0 -->

# Meridian Storage ClickHouse

[![CI](https://github.com/zephytiju/meridian-storage-clickhouse/actions/workflows/ci.yml/badge.svg)](https://github.com/zephytiju/meridian-storage-clickhouse/actions/workflows/ci.yml)
[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
[![Python](https://img.shields.io/badge/python-3.12--3.14-blue.svg)](pyproject.toml)

`meridian-storage-clickhouse` is the independently released ClickHouse adapter for Meridian
V1. It executes mapping-first, engine-neutral Operations for stored logs, spans, metric points,
usage, cost, and generic analytical time-series Records. It provides deterministic schema and
migration plans, bounded idempotent batch ingestion, mandatory time-bounded query pushdown,
live keyset pagination, result normalization, authenticated probes, and physical fingerprints.

The distribution contributes exactly one adapter package,
`meridian_storage.adapters.clickhouse`, and discovers through the released Meridian Core 1.0.0
Adapter SPI. It consumes only the released `meridian-storage-core`,
`meridian-storage-semantics`, and `meridian-storage-query` 1.0.0 contracts.

## Boundary

Application code does not import this package, create a ClickHouse client, issue SQL, select a
table engine, or provide an endpoint. It uses the registered `evidence` or `structured` Catalog
Expression surface. The composition root starts Meridian after deployment IaC has injected an
opaque Binding:

```python
from meridian_storage import Meridian, OperationContext

meridian = Meridian.from_environment()
meridian.start()
evidence = meridian.catalog("evidence")

with meridian.context(
    OperationContext(
        principal_ref="identity:service/worker",
        tenant="tenant-a",
        scope={"workspace": "operations"},
    )
):
    result = meridian.execute(
        evidence.query(
            resource="runtime.logs",
            where={
                "event_time": {
                    "gte": "2026-08-25T00:00:00Z",
                    "lt": "2026-08-26T00:00:00Z",
                }
            },
            limit=100,
        )
    )
```

Collector deployment, topology, credentials, ACLs, retention, backups, restores, and migration
job lifecycle remain owned by Platform or Vangu IaC through MeridianConstructs. Runtime startup
only authenticates, probes compatibility, and verifies pre-provisioned physical fingerprints.

## Guarantees and limits

- Writes are append-oriented and idempotent only within the advertised retry/deduplication
  window. The adapter does not claim general exactly-once execution.
- Every scan and aggregate requires a bounded UTC time range within the Binding limit.
- Scope isolation is injected ahead of user predicates and leads every table sort key.
- Visibility is eventual. General transactions, compare-and-set, authoritative patch, foreign
  keys, cross-Binding joins, and native SQL Expressions are denied.
- Decimal, timestamp, UUID, bytes, JSON, nullable, and quantile values are normalized back to
  Meridian wire representations. Percentiles use the exact ClickHouse quantile function in V1.

## Adapter-author and IaC integration

The public adapter-author surface includes `ClickHouseAdapterFactory`,
`ClickHouseSchemaCompiler`, `ClickHouseMigrator`, `ClickHouseQueryTranslator`,
`adapter_descriptor`, `capability_manifest`, and `plan_initial_migration`. These are deployment
and adapter integration contracts, not business APIs. See
[architecture.md](docs/architecture.md), [configuration.md](docs/configuration.md),
[operations.md](docs/operations.md), [migrations.md](docs/migrations.md), and
[conformance.md](docs/conformance.md).

## Development

```console
python -m venv .venv
.venv/bin/python -m pip install -e '.[test]'
.venv/bin/ruff check .
.venv/bin/mypy src
.venv/bin/pytest -m 'not integration and not cluster'
./scripts/run-standalone-conformance.sh
./scripts/run-cluster-conformance.sh
```

Real-engine tests use disposable ClickHouse containers and never target a deployment-owned
database. See `tests/integration` and `tests/cluster` for the exact profiles.

## License

Licensed under the Apache License, Version 2.0. See [LICENSE](LICENSE) and [NOTICE](NOTICE).
