exness-data-preprocess 2.0.0__tar.gz → 2.1.1__tar.gz

exness_data_preprocess-2.1.1/.github/dependabot.yml

@@ -0,0 +1,26 @@
+# Dependency update PRs. Replaces the scheduled pre-commit-autoupdate workflow.
+# No `uv` entry: uv.lock is not tracked and this is a library, so the only possible updates
+# would be raising the `>=` floors in pyproject.toml, which narrows what downstream users can install.
+version: 2
+updates:
+  - package-ecosystem: "pre-commit"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    commit-message:
+      prefix: "chore(deps)"
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    commit-message:
+      prefix: "ci(deps)"
+  - package-ecosystem: "npm"
+    directory: "/"
+    schedule:
+      interval: "monthly"
+    commit-message:
+      prefix: "chore(deps)"
+    groups:
+      semantic-release:
+        patterns: ["*"]

{exness_data_preprocess-2.0.0 → exness_data_preprocess-2.1.1}/.gitignore

@@ -41,7 +41,6 @@ venv.bak/
 .ipynb_checkpoints
 
 # pyenv
-.python-version
 
 # Environments
 .env.local
@@ -106,9 +105,16 @@ node_modules/
 
 # Link checking (lychee)
 .lychee*
-.lycheecache
 
 # DBeaver (credentials in generated JSON)
 # ADR: /docs/adr/2025-12-10-clickhouse-pydantic-config.md
 .dbeaver/
 .dbeaver-workspace/
+
+# Claude Code local files
+.claude/
+.lint-relative-paths-results.txt
+
+# moon (task runner) local cache
+.moon/cache/
+.moon/docker/

exness_data_preprocess-2.1.1/.moon/toolchain.yml

@@ -0,0 +1,2 @@
+# yaml-language-server: $schema=https://moonrepo.dev/schemas/toolchain.json
+# No moon-managed toolchains: tasks run on the `system` platform (uv from proto on PATH).

exness_data_preprocess-2.1.1/.moon/workspace.yml

@@ -0,0 +1,8 @@
+# yaml-language-server: $schema=https://moonrepo.dev/schemas/workspace.json
+# moon runs this repo's tasks; proto (.prototools) pins the tools.
+projects:
+  repo: '.'
+
+vcs:
+  client: 'git'
+  defaultBranch: 'main'

{exness_data_preprocess-2.0.0 → exness_data_preprocess-2.1.1}/.pre-commit-config.yaml

@@ -1,6 +1,6 @@
 repos:
 - repo: https://github.com/commitizen-tools/commitizen
-  rev: v4.9.1
+  rev: v4.19.2
   hooks:
   - id: commitizen
     stages: [commit-msg]
@@ -8,7 +8,7 @@ repos:
     stages: [pre-push]
     args: [--rev-range, origin/main..HEAD]
 - repo: https://github.com/pre-commit/pre-commit-hooks
-  rev: v4.4.0
+  rev: v6.0.0
   hooks:
   - id: trailing-whitespace
   - id: end-of-file-fixer
@@ -17,8 +17,8 @@ repos:
   - id: check-merge-conflict
   - id: debug-statements
 - repo: https://github.com/astral-sh/ruff-pre-commit
-  rev: v0.13.0
+  rev: v0.17.1
   hooks:
-  - id: ruff
+  - id: ruff-check
     args: [--fix, --unsafe-fixes]
   - id: ruff-format

exness_data_preprocess-2.1.1/.prototools

@@ -0,0 +1,5 @@
+# proto — repo-local toolchain versions.
+# uv owns Python: the interpreter version is .python-version, and uv.toml makes uv use only its own
+# managed build. ClickHouse comes from the system PATH (e.g. Homebrew), not from proto.
+uv = "latest"
+moon = "2.6.1"

exness_data_preprocess-2.1.1/.python-version

@@ -0,0 +1 @@
+3.11

exness_data_preprocess-2.1.1/.releaserc.yml

@@ -0,0 +1,24 @@
+# semantic-release configuration for Python project
+# Uses @semantic-release/exec instead of @semantic-release/npm
+branches:
+  - main
+
+plugins:
+  - "@semantic-release/commit-analyzer"
+  - "@semantic-release/release-notes-generator"
+  - "@semantic-release/changelog"
+  - - "@semantic-release/exec"
+    # `uv version --frozen` rewrites [project].version in pyproject.toml only (uv.lock is not tracked).
+    # __version__ is read from the installed distribution metadata, so nothing else needs bumping.
+    # The release narrative is a tracked file written in the PR before the release; without it
+    # there is no release. After @semantic-release/github publishes, the body is rebuilt as
+    # narrative + generated section (idempotent; see scripts/publish-release-notes.sh).
+    - verifyReleaseCmd: "test -s docs/release-notes/${nextRelease.version}.md || { echo 'missing docs/release-notes/${nextRelease.version}.md' >&2; exit 1; }"
+      prepareCmd: "uv version ${nextRelease.version} --frozen"
+      successCmd: "bash scripts/publish-release-notes.sh ${nextRelease.version}"
+  - - "@semantic-release/git"
+    - assets:
+        - pyproject.toml
+        - CHANGELOG.md
+      message: "chore(release): bump version ${lastRelease.version} → ${nextRelease.version} [skip ci]"
+  - "@semantic-release/github"

{exness_data_preprocess-2.0.0 → exness_data_preprocess-2.1.1}/CHANGELOG.md

@@ -1,3 +1,28 @@
+## [2.1.1](https://github.com/terrylica/exness-data-preprocess/compare/v2.1.0...v2.1.1) (2026-10-19)
+
+
+### Bug Fixes
+
+* **clickhouse:** resolve the binary from PATH instead of a dead mise shim ([2e5cbe0](https://github.com/terrylica/exness-data-preprocess/commit/2e5cbe0bd3c51f0d95d6c1baf583a98727a12d36))
+* **e2e:** apply review findings (memory cap, isolated downloads, marker selection, signals) ([ec2d8aa](https://github.com/terrylica/exness-data-preprocess/commit/ec2d8aaea4cc1f2ca7bb5527208345ad2d526a4b)), closes [#6](https://github.com/terrylica/exness-data-preprocess/issues/6)
+* **processor:** bootstrap exness database before first get_client() call ([0cc55a4](https://github.com/terrylica/exness-data-preprocess/commit/0cc55a43fa482e48870f4685d170f2b2ff1aa941))
+* **release:** bump the version with `uv version`, read __version__ from metadata ([aa86693](https://github.com/terrylica/exness-data-preprocess/commit/aa866932bb41517629a51186af740555cc959774)), closes [#4](https://github.com/terrylica/exness-data-preprocess/issues/4)
+* **scripts:** resolve ruff lint errors and formatting issues ([68d939f](https://github.com/terrylica/exness-data-preprocess/commit/68d939f5fafdd2692b5ef6f1ad4e5811e3364a87))
+* **types:** make `moon run repo:check` green (mypy 15 errors to 0) ([79b2259](https://github.com/terrylica/exness-data-preprocess/commit/79b2259af62e4d5086016669d8dba825fd69dbd9)), closes [#7](https://github.com/terrylica/exness-data-preprocess/issues/7)
+
+# [2.1.0](https://github.com/terrylica/exness-data-preprocess/compare/v2.0.0...v2.1.0) (2025-12-28)
+
+
+### Bug Fixes
+
+* **clickhouse:** add parameters support to execute_command and fix OHLC generator ([391b939](https://github.com/terrylica/exness-data-preprocess/commit/391b939bd2f7e6baad8945d98fc63e8843799682))
+* **docs:** fix 22 broken links identified by lychee link checker ([a85862e](https://github.com/terrylica/exness-data-preprocess/commit/a85862e7af58bdd9e28eef59f364f56e0df37c24))
+
+
+### Features
+
+* **scripts:** add DuckDB to ClickHouse migration scripts ([1920903](https://github.com/terrylica/exness-data-preprocess/commit/1920903df113bea810cc3607273d6f2ececd3f4b))
+
 # [2.0.0](https://github.com/terrylica/exness-data-preprocess/compare/v1.2.1...v2.0.0) (2025-12-27)
 
 

exness_data_preprocess-2.1.1/CLAUDE.md

@@ -0,0 +1,30 @@
+# CLAUDE.md
+
+`exness-data-preprocess`: downloads Exness forex ticks from ticks.ex2archive.com into ClickHouse (database `exness`: `raw_spread_ticks`, `standard_ticks`, `ohlc_1m`, plus `exchange_sessions` and `holidays`) and serves tick and OHLC queries. Entry point: `ExnessDataProcessor`. User docs: [README.md](/README.md); index of the rest: [docs/README.md](/docs/README.md).
+
+## Commands
+
+```bash
+uv sync --dev
+moon run repo:check      # offline gate: ruff check + ruff format --check + mypy + pytest
+moon run repo:e2e        # hermetic: throwaway ClickHouse on free ports, pytest with ClickHouse required,
+                         # validate_clickhouse.py all (incl. a real EURUSD download), examples/basic_usage.py
+moon run repo:build      # sdist + wheel into dist/
+```
+
+`repo:validate`, `repo:clickhouse-start` / `repo:clickhouse-stop` and `repo:validate-clickhouse-*` target a persistent local server on :8123 (see [moon.yml](/moon.yml)).
+
+## Toolchain
+
+- proto pins uv (`.prototools`); uv owns Python. `.python-version` pins 3.11 and wins. If `UV_PYTHON` is exported in the shell, it overrides the pin, so run `env -u UV_PYTHON uv ...` or the venv is built on the wrong interpreter.
+- Releases: write `docs/release-notes/<next>.md` (narrative paragraph + Keep a Changelog bullets, one line each) in the PR before releasing; semantic-release (`npm run release`) refuses to release without it, runs `uv version <next> --frozen`, and `scripts/publish-release-notes.sh` rebuilds the GitHub Release body as narrative + generated section. pyproject.toml is the only place the version lives; `__version__` reads installed metadata. Publishing is `.github/workflows/publish.yml` (PyPI Trusted Publishing on a GitHub Release), the only publish path.
+- Dependency update PRs come from `.github/dependabot.yml`. No other CI runs in Actions; gates are local.
+
+## Invariants
+
+- `ensure_database_bootstrap()` must run before the first `get_client()` that binds the `exness` database (`tests/test_database_bootstrap_order.py`).
+- Insert DataFrames with `client.insert_df(...)`, never `client.insert(data=df)` (that takes row sequences).
+- Tables are ReplacingMergeTree: re-inserting a month is safe; duplicates collapse at merge time, so counts can be higher until a merge or `FINAL`.
+- ClickHouse-backed tests are marked `clickhouse` or use `processor_with_clickhouse` (fixture users get the marker at collection, so `-m clickhouse` selects them); `conftest.py` skips them with the probe's reason unless `EXNESS_REQUIRE_CLICKHOUSE=1`. A server that holds :8123 but rejects the credentials (el02's shared system ClickHouse) counts as unavailable. Use `repo:e2e`, not that server.
+- `gapless-crypto-clickhouse` also uses localhost:8123. `clickhouse-stop` only stops the PID in this repo's pidfile.
+- ADRs and design specs under `docs/adr/` and `docs/design/` are historical records: add new ones, don't rewrite old ones.

exness_data_preprocess-2.1.1/CONTRIBUTING.md

@@ -0,0 +1,32 @@
+# Contributing
+
+## Setup
+
+```bash
+git clone https://github.com/terrylica/exness-data-preprocess.git
+cd exness-data-preprocess
+uv sync --dev                 # Python version comes from .python-version
+```
+
+You also need [moon](https://moonrepo.dev/) (pinned through proto) for the task runner and a `clickhouse` binary on `PATH` for the end-to-end run.
+
+## Before you open a pull request
+
+```bash
+moon run repo:check   # ruff check, ruff format --check, mypy, pytest
+moon run repo:e2e     # throwaway ClickHouse + full pytest + validate checks + examples
+```
+
+Both gates run locally; GitHub Actions only publishes releases and runs Dependabot. See [tests/README.md](/tests/README.md) for how ClickHouse-backed tests are selected and skipped.
+
+## Commits and releases
+
+Commit messages follow [Conventional Commits](https://www.conventionalcommits.org/) (`feat:`, `fix:`, `docs:`, `test:`, `refactor:`, `perf:`, `chore:`, `ci:`); the commitizen pre-commit hook checks them (`uv run pre-commit install --hook-type commit-msg --hook-type pre-push`). semantic-release derives the next version and the changelog from them, so never edit the version or `CHANGELOG.md` by hand.
+
+## Reporting issues
+
+Include the package version (`uv pip show exness-data-preprocess`), Python version, OS, a minimal reproduction, and the full traceback.
+
+## License
+
+Contributions are licensed under the MIT License.

exness_data_preprocess-2.1.1/PKG-INFO

@@ -0,0 +1,227 @@
+Metadata-Version: 2.5
+Name: exness-data-preprocess
+Version: 2.1.1
+Summary: Professional Exness forex tick data preprocessing with ClickHouse backend. Provides efficient storage with lossless precision and direct queryability.
+Project-URL: Homepage, https://github.com/terrylica/exness-data-preprocess
+Project-URL: Documentation, https://github.com/terrylica/exness-data-preprocess#readme
+Project-URL: Repository, https://github.com/terrylica/exness-data-preprocess.git
+Project-URL: Bug Tracker, https://github.com/terrylica/exness-data-preprocess/issues
+Project-URL: Source Code, https://github.com/terrylica/exness-data-preprocess
+Project-URL: Changelog, https://github.com/terrylica/exness-data-preprocess/blob/main/CHANGELOG.md
+Author-email: Eon Labs <terry@eonlabs.com>
+Maintainer-email: Terry Li <terry@eonlabs.com>
+License: MIT
+License-File: LICENSE
+Keywords: backtesting,clickhouse,data-engineering,efficient-storage,eurusd,exness,financial-data,forex,forex-data,lossless,microstructure,ohlc,pandas,preprocessing,quantitative-finance,queryable,tick-data,time-series
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Requires-Dist: clickhouse-connect>=0.7.0
+Requires-Dist: exchange-calendars>=4.5.6
+Requires-Dist: pandas>=2.0.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: pyyaml>=6.0.0
+Provides-Extra: examples
+Requires-Dist: tqdm>=4.65.0; extra == 'examples'
+Description-Content-Type: text/markdown
+
+# exness-data-preprocess
+
+Forex tick data preprocessing with ClickHouse backend. Downloads, stores, and queries tick data from Exness public repository.
+
+## Data Inventory (Validated 2025-12-28)
+
+| Instrument | raw_spread_ticks | standard_ticks | ohlc_1m   | Date Range              |
+| ---------- | ---------------- | -------------- | --------- | ----------------------- |
+| EURUSD     | 56,687,313       | 62,203,144     | 1,466,724 | 2022-01-02 → 2025-12-26 |
+| XAUUSD     | 166,820,410      | 167,871,871    | 1,401,953 | 2022-01-02 → 2025-12-26 |
+
+**Total**: 453.6M ticks, 2.87M OHLC bars in 5.99 GiB
+
+## Requirements
+
+- Python 3.11+
+- ClickHouse running on `localhost:8123`
+
+## Verify ClickHouse
+
+```bash
+# Check ClickHouse is running
+clickhouse client --query "SELECT version()"
+
+# Check exness database exists
+clickhouse client --query "SELECT count() FROM exness.raw_spread_ticks"
+```
+
+## Installation
+
+```bash
+# Using uv
+uv pip install exness-data-preprocess
+
+# From source
+git clone https://github.com/Eon-Labs/exness-data-preprocess.git
+cd exness-data-preprocess
+uv sync
+```
+
+## Python API
+
+```python
+import exness_data_preprocess as edp
+
+# Context manager (recommended)
+with edp.ExnessDataProcessor() as processor:
+    # Query ticks
+    df = processor.query_ticks("EURUSD", "raw_spread", "2024-01-01", "2024-01-31")
+
+    # Query OHLC
+    df = processor.query_ohlc("EURUSD", "1m", "2024-01-01", "2024-01-31")
+
+    # Get coverage info
+    cov = processor.get_data_coverage("EURUSD")
+
+    # Download new data (incremental)
+    result = processor.update_data("EURUSD", start_date="2022-01-01")
+```
+
+### API Methods
+
+| Method                                              | Parameters                                     | Returns      |
+| --------------------------------------------------- | ---------------------------------------------- | ------------ |
+| `query_ticks(pair, variant, start_date, end_date)`  | variant: `raw_spread` or `standard`            | DataFrame    |
+| `query_ohlc(pair, timeframe, start_date, end_date)` | timeframe: `1m`, `5m`, `15m`, `1h`, `4h`, `1d` | DataFrame    |
+| `get_data_coverage(pair)`                           |                                                | CoverageInfo |
+| `update_data(pair, start_date, delete_zip=True)`    |                                                | UpdateResult |
+
+### Return Models
+
+```python
+# UpdateResult
+result.months_added  # int: months downloaded
+result.raw_ticks_added  # int: raw spread ticks added
+result.standard_ticks_added  # int: standard ticks added
+result.ohlc_bars  # int: OHLC bars generated
+result.storage_bytes  # int: storage used
+
+# CoverageInfo
+cov.raw_spread_ticks  # int: total raw spread ticks
+cov.standard_ticks  # int: total standard ticks
+cov.ohlc_bars  # int: total OHLC bars
+cov.earliest_date  # str: earliest timestamp
+cov.latest_date  # str: latest timestamp
+cov.storage_bytes  # int: storage used
+```
+
+## Direct SQL Access
+
+```bash
+# Count ticks
+clickhouse client --query "SELECT count() FROM exness.raw_spread_ticks WHERE instrument='EURUSD'"
+
+# Query tick data
+clickhouse client --query "
+SELECT timestamp, bid, ask
+FROM exness.raw_spread_ticks
+WHERE instrument='EURUSD'
+  AND timestamp >= '2024-01-01'
+  AND timestamp < '2024-01-02'
+LIMIT 10"
+
+# Query OHLC
+clickhouse client --query "
+SELECT timestamp, open, high, low, close
+FROM exness.ohlc_1m
+WHERE instrument='EURUSD'
+  AND timestamp >= '2024-01-01'
+LIMIT 10"
+
+# Resample to 1h
+clickhouse client --query "
+SELECT
+    toStartOfHour(timestamp) AS ts,
+    argMin(open, timestamp) AS open,
+    max(high) AS high,
+    min(low) AS low,
+    argMax(close, timestamp) AS close
+FROM exness.ohlc_1m
+WHERE instrument='EURUSD' AND timestamp >= '2024-01-01'
+GROUP BY ts
+ORDER BY ts"
+```
+
+## Schema
+
+### Tick Tables
+
+`exness.raw_spread_ticks`, `exness.standard_ticks`:
+
+| Column     | Type                   | Codec               |
+| ---------- | ---------------------- | ------------------- |
+| instrument | LowCardinality(String) | -                   |
+| timestamp  | DateTime64(6, 'UTC')   | DoubleDelta, LZ4    |
+| bid        | Float64                | Gorilla, ZSTD       |
+| ask        | Float64                | Gorilla, ZSTD       |
+
+### OHLC Table
+
+`exness.ohlc_1m` (27 columns):
+
+| Category    | Columns                                                                                                                                                                 |
+| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Core        | instrument, timestamp, open, high, low, close                                                                                                                           |
+| Spreads     | raw_spread_avg, standard_spread_avg                                                                                                                                     |
+| Tick counts | tick_count_raw_spread, tick_count_standard                                                                                                                              |
+| Timezone    | ny_hour, london_hour, ny_session, london_session                                                                                                                        |
+| Holidays    | is_us_holiday, is_uk_holiday, is_major_holiday                                                                                                                          |
+| Sessions    | is_nyse_session, is_lse_session, is_xswx_session, is_xfra_session, is_xtse_session, is_xnze_session, is_xtks_session, is_xasx_session, is_xhkg_session, is_xses_session |
+
+Engine: `ReplacingMergeTree` (automatic deduplication)
+
+Partition: `toYYYYMM(timestamp)`
+
+Order: `(instrument, timestamp)`
+
+## Data Source
+
+- URL: <https://ticks.ex2archive.com/>
+- Format: Monthly ZIP files with CSV tick data
+- Variants: Raw_Spread (zero spreads) + Standard (market spreads)
+- Precision: Microsecond timestamps
+
+## Development
+
+```bash
+# Setup
+uv sync --dev
+
+# Test
+uv run pytest
+
+# Lint
+uv run ruff check --fix .
+
+# Type check
+uv run mypy src/
+```
+
+## Documentation
+
+- [ClickHouse User Guide](/docs/CLICKHOUSE_USER_GUIDE.md) - Detailed ClickHouse usage
+- [Schema](#schema) - summary above; the DDL in [`clickhouse_manager.py`](/src/exness_data_preprocess/clickhouse_manager.py) is authoritative
+- [Exness Data Sources](/docs/EXNESS_DATA_SOURCES.md) - archive layout and variants
+- [ADR: ClickHouse Migration](/docs/adr/2025-12-11-duckdb-removal-clickhouse.md) - Architecture decision
+
+## License
+
+MIT

exness_data_preprocess-2.1.1/README.md

@@ -0,0 +1,190 @@
+# exness-data-preprocess
+
+Forex tick data preprocessing with ClickHouse backend. Downloads, stores, and queries tick data from Exness public repository.
+
+## Data Inventory (Validated 2025-12-28)
+
+| Instrument | raw_spread_ticks | standard_ticks | ohlc_1m   | Date Range              |
+| ---------- | ---------------- | -------------- | --------- | ----------------------- |
+| EURUSD     | 56,687,313       | 62,203,144     | 1,466,724 | 2022-01-02 → 2025-12-26 |
+| XAUUSD     | 166,820,410      | 167,871,871    | 1,401,953 | 2022-01-02 → 2025-12-26 |
+
+**Total**: 453.6M ticks, 2.87M OHLC bars in 5.99 GiB
+
+## Requirements
+
+- Python 3.11+
+- ClickHouse running on `localhost:8123`
+
+## Verify ClickHouse
+
+```bash
+# Check ClickHouse is running
+clickhouse client --query "SELECT version()"
+
+# Check exness database exists
+clickhouse client --query "SELECT count() FROM exness.raw_spread_ticks"
+```
+
+## Installation
+
+```bash
+# Using uv
+uv pip install exness-data-preprocess
+
+# From source
+git clone https://github.com/Eon-Labs/exness-data-preprocess.git
+cd exness-data-preprocess
+uv sync
+```
+
+## Python API
+
+```python
+import exness_data_preprocess as edp
+
+# Context manager (recommended)
+with edp.ExnessDataProcessor() as processor:
+    # Query ticks
+    df = processor.query_ticks("EURUSD", "raw_spread", "2024-01-01", "2024-01-31")
+
+    # Query OHLC
+    df = processor.query_ohlc("EURUSD", "1m", "2024-01-01", "2024-01-31")
+
+    # Get coverage info
+    cov = processor.get_data_coverage("EURUSD")
+
+    # Download new data (incremental)
+    result = processor.update_data("EURUSD", start_date="2022-01-01")
+```
+
+### API Methods
+
+| Method                                              | Parameters                                     | Returns      |
+| --------------------------------------------------- | ---------------------------------------------- | ------------ |
+| `query_ticks(pair, variant, start_date, end_date)`  | variant: `raw_spread` or `standard`            | DataFrame    |
+| `query_ohlc(pair, timeframe, start_date, end_date)` | timeframe: `1m`, `5m`, `15m`, `1h`, `4h`, `1d` | DataFrame    |
+| `get_data_coverage(pair)`                           |                                                | CoverageInfo |
+| `update_data(pair, start_date, delete_zip=True)`    |                                                | UpdateResult |
+
+### Return Models
+
+```python
+# UpdateResult
+result.months_added  # int: months downloaded
+result.raw_ticks_added  # int: raw spread ticks added
+result.standard_ticks_added  # int: standard ticks added
+result.ohlc_bars  # int: OHLC bars generated
+result.storage_bytes  # int: storage used
+
+# CoverageInfo
+cov.raw_spread_ticks  # int: total raw spread ticks
+cov.standard_ticks  # int: total standard ticks
+cov.ohlc_bars  # int: total OHLC bars
+cov.earliest_date  # str: earliest timestamp
+cov.latest_date  # str: latest timestamp
+cov.storage_bytes  # int: storage used
+```
+
+## Direct SQL Access
+
+```bash
+# Count ticks
+clickhouse client --query "SELECT count() FROM exness.raw_spread_ticks WHERE instrument='EURUSD'"
+
+# Query tick data
+clickhouse client --query "
+SELECT timestamp, bid, ask
+FROM exness.raw_spread_ticks
+WHERE instrument='EURUSD'
+  AND timestamp >= '2024-01-01'
+  AND timestamp < '2024-01-02'
+LIMIT 10"
+
+# Query OHLC
+clickhouse client --query "
+SELECT timestamp, open, high, low, close
+FROM exness.ohlc_1m
+WHERE instrument='EURUSD'
+  AND timestamp >= '2024-01-01'
+LIMIT 10"
+
+# Resample to 1h
+clickhouse client --query "
+SELECT
+    toStartOfHour(timestamp) AS ts,
+    argMin(open, timestamp) AS open,
+    max(high) AS high,
+    min(low) AS low,
+    argMax(close, timestamp) AS close
+FROM exness.ohlc_1m
+WHERE instrument='EURUSD' AND timestamp >= '2024-01-01'
+GROUP BY ts
+ORDER BY ts"
+```
+
+## Schema
+
+### Tick Tables
+
+`exness.raw_spread_ticks`, `exness.standard_ticks`:
+
+| Column     | Type                   | Codec               |
+| ---------- | ---------------------- | ------------------- |
+| instrument | LowCardinality(String) | -                   |
+| timestamp  | DateTime64(6, 'UTC')   | DoubleDelta, LZ4    |
+| bid        | Float64                | Gorilla, ZSTD       |
+| ask        | Float64                | Gorilla, ZSTD       |
+
+### OHLC Table
+
+`exness.ohlc_1m` (27 columns):
+
+| Category    | Columns                                                                                                                                                                 |
+| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Core        | instrument, timestamp, open, high, low, close                                                                                                                           |
+| Spreads     | raw_spread_avg, standard_spread_avg                                                                                                                                     |
+| Tick counts | tick_count_raw_spread, tick_count_standard                                                                                                                              |
+| Timezone    | ny_hour, london_hour, ny_session, london_session                                                                                                                        |
+| Holidays    | is_us_holiday, is_uk_holiday, is_major_holiday                                                                                                                          |
+| Sessions    | is_nyse_session, is_lse_session, is_xswx_session, is_xfra_session, is_xtse_session, is_xnze_session, is_xtks_session, is_xasx_session, is_xhkg_session, is_xses_session |
+
+Engine: `ReplacingMergeTree` (automatic deduplication)
+
+Partition: `toYYYYMM(timestamp)`
+
+Order: `(instrument, timestamp)`
+
+## Data Source
+
+- URL: <https://ticks.ex2archive.com/>
+- Format: Monthly ZIP files with CSV tick data
+- Variants: Raw_Spread (zero spreads) + Standard (market spreads)
+- Precision: Microsecond timestamps
+
+## Development
+
+```bash
+# Setup
+uv sync --dev
+
+# Test
+uv run pytest
+
+# Lint
+uv run ruff check --fix .
+
+# Type check
+uv run mypy src/
+```
+
+## Documentation
+
+- [ClickHouse User Guide](/docs/CLICKHOUSE_USER_GUIDE.md) - Detailed ClickHouse usage
+- [Schema](#schema) - summary above; the DDL in [`clickhouse_manager.py`](/src/exness_data_preprocess/clickhouse_manager.py) is authoritative
+- [Exness Data Sources](/docs/EXNESS_DATA_SOURCES.md) - archive layout and variants
+- [ADR: ClickHouse Migration](/docs/adr/2025-12-11-duckdb-removal-clickhouse.md) - Architecture decision
+
+## License
+
+MIT