ob-clickhouse 0.1.0__tar.gz

ob_clickhouse-0.1.0/.gitignore

@@ -0,0 +1,35 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+dist/
+build/
+*.egg-info/
+*.egg
+.eggs/
+.venv/
+venv/
+.env
+*.db
+*.duckdb
+*.sqlite3
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+htmlcov/
+.coverage
+.coverage.*
+*.log
+.DS_Store
+.claude/
+security/
+infra/
+site/
+scripts/
+.mcpregistry_github_token
+.mcpregistry_registry_token
+_*/
+blog/
+review*
+design/
+examples/test*

ob_clickhouse-0.1.0/CLAUDE.md

@@ -0,0 +1,105 @@
+# ob-clickhouse — OrionBelt Semantic Layer Driver for Clickhouse
+
+## Purpose
+
+PEP 249 DB-API 2.0 driver wrapping `clickhouse-connect = ">=0.7"` that intercepts OBML YAML
+queries, compiles them to clickhouse SQL via the OrionBelt CompilationPipeline
+(direct import) or OB REST API (standalone), and executes them natively.
+
+**OB dialect string:** `"clickhouse"`
+**Author:** Ralf Becher / RALFORION d.o.o. (info@orionbelt.ai)
+**License:** Apache 2.0
+
+---
+
+## Module Map
+
+| File | Responsibility |
+|---|---|
+| `__init__.py` | PEP 249 connect() + module constants |
+| `connection.py` | Connection class |
+| `cursor.py` | Cursor class — OBML detection + execution |
+| `compiler.py` | Direct OB import or REST fallback |
+| `exceptions.py` | PEP 249 exception hierarchy |
+| `type_codes.py` | PEP 249 type objects |
+
+---
+
+## connect() Parameters
+
+### clickhouse-specific
+| host | str | ClickHouse host |
+| port | int | HTTP port (default: 8123) or native (9000) |
+| username | str | Username (default: default) |
+| password | str | Password |
+| database | str | Database name |
+| secure | bool | Use HTTPS (default: False) |
+
+### OrionBelt parameters (same across all vendors)
+| Parameter | Default | Description |
+|---|---|---|
+| ob_model_id | None | Pre-loaded OB model ID |
+| ob_model_yaml | None | OBML YAML string to load |
+| ob_model_file | None | Path to .obml.yaml file |
+| ob_api_url | http://localhost:8000 | OB REST API URL (standalone mode only) |
+| ob_timeout | 30 | HTTP timeout in seconds |
+
+---
+
+## Compiler Bridge (compiler.py)
+
+Auto-detects whether OB core is importable (same process as orionbelt-api)
+or whether to fall back to REST:
+
+```python
+def compile_obml(obml: dict, model, dialect: str) -> str:
+    try:
+        # Direct call — zero overhead, used when embedded in orionbelt-api
+        from orionbelt.compiler.pipeline import CompilationPipeline
+        result = CompilationPipeline().compile(obml, model, dialect)
+        return result.sql
+    except ImportError:
+        # Standalone mode — call REST API
+        return _compile_via_rest(obml, dialect)
+```
+
+---
+
+## Vendor-Specific Notes
+
+- ClickHouse has no transactions; commit() and rollback() are no-ops
+- Use clickhouse_connect.get_client() not legacy clickhouse-driver
+- FixedString padding: strip trailing null bytes in _post_process_rows()
+- OB dialect "clickhouse" generates toStartOfMonth() etc. for time grains
+- Arrays and Maps are not supported in OBML measures — raise DataError if encountered
+
+---
+
+## Type System
+
+clickhouse-connect returns Python native types.
+Map: Int32/64→int, Float32/64→float, String→str, DateTime→datetime.
+FixedString columns require TRIM() — add post-processing in cursor.fetchall().
+
+---
+
+## Build Order
+
+Session 1: exceptions.py + type_codes.py + compiler.py + unit tests
+Session 2: connection.py + cursor.py (OBML detection, core execute)
+Session 3: __init__.py + connect() + integration tests
+Session 4: SQLAlchemy dialect (ob+clickhouse:// URL scheme)
+
+---
+
+## Dependencies
+
+```toml
+[project.dependencies]
+clickhouse-connect = ">=0.7"
+pyyaml = ">=6.0"
+
+[project.optional-dependencies]
+sqlalchemy = ["sqlalchemy>=2.0"]
+dev = ["pytest>=8.0", "pytest-asyncio>=0.23", "mypy>=1.10", "ruff>=0.4", "respx>=0.21"]
+```

ob_clickhouse-0.1.0/LICENSE

@@ -0,0 +1,70 @@
+Business Source License 1.1
+
+Parameters
+
+Licensor:             RALFORION d.o.o.
+Licensed Work:        OrionBelt Semantic Layer 1.0
+                      The Licensed Work is (c) 2025 RALFORION d.o.o.
+Additional Use Grant: You may use the Licensed Work for any purpose,
+                      including production use, PROVIDED THAT you may
+                      not embed OrionBelt in a commercial product or
+                      provide it as part of a commercial service
+                      without purchasing a commercial license from
+                      the Licensor. Contact licensing@ralforion.com
+                      for commercial licensing inquiries.
+Change Date:          2030-03-16
+Change License:       Apache License, Version 2.0
+
+-----------------------------------------------------------------------------
+
+Business Source License 1.1
+
+License text copyright (c) 2017 MariaDB Corporation Ab, All Rights Reserved.
+"Business Source License" is a trademark of MariaDB Corporation Ab.
+
+Terms
+
+The Licensor hereby grants you the right to copy, modify, create derivative
+works, redistribute, and make non-production use of the Licensed Work. The
+Licensor may make an Additional Use Grant, above, permitting limited
+production use.
+
+Effective on the Change Date, or the fourth anniversary of the first publicly
+available distribution of a specific version of the Licensed Work under this
+License, whichever comes first, the Licensor hereby grants you rights under
+the terms of the Change License, and the rights granted in the paragraph
+above terminate.
+
+If your use of the Licensed Work does not comply with the requirements
+currently in effect as described in this License, you must purchase a
+commercial license from the Licensor, its affiliated entities, or authorized
+resellers, or you must refrain from using the Licensed Work.
+
+All copies of the original and modified Licensed Work, and derivative works
+of the Licensed Work, are subject to this License. This License applies
+separately for each version of the Licensed Work and the Change Date may vary
+for each version of the Licensed Work released by Licensor.
+
+You must conspicuously display this License on each original or modified copy
+of the Licensed Work. If you receive the Licensed Work in original or
+modified form from a third party, the terms and conditions set forth in this
+License apply to your use of that work.
+
+Any use of the Licensed Work in violation of this License will automatically
+terminate your rights under this License for the current and all other
+versions of the Licensed Work.
+
+This License does not grant you any right in any trademark or logo of
+Licensor or its affiliates (provided that you may use a trademark or logo of
+Licensor as expressly required by this License).
+
+TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON
+AN "AS IS" BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS,
+EXPRESS OR IMPLIED, INCLUDING (WITHOUT LIMITATION) WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, AND
+TITLE.
+
+MariaDB hereby grants you permission to use this License's text to license
+your works, and to refer to it using the trademark "Business Source License",
+as long as you comply with the Covenants of Licensor of MariaDB's Business Source
+License Trademark Policy available at https://mariadb.com/bsl11/.

ob_clickhouse-0.1.0/PKG-INFO

@@ -0,0 +1,37 @@
+Metadata-Version: 2.4
+Name: ob-clickhouse
+Version: 0.1.0
+Summary: OrionBelt Semantic Layer driver for ClickHouse (DB-API 2.0)
+Author-email: Ralf Becher <info@orionbelt.ai>
+License: BSL-1.1
+License-File: LICENSE
+Keywords: clickhouse,db-api,obml,orionbelt,semantic-layer
+Requires-Python: >=3.12
+Requires-Dist: clickhouse-connect>=0.7
+Requires-Dist: ob-driver-core>=0.1
+Requires-Dist: pyarrow>=16.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Provides-Extra: sqlalchemy
+Requires-Dist: sqlalchemy>=2.0; extra == 'sqlalchemy'
+Description-Content-Type: text/markdown
+
+# ob-clickhouse
+
+OrionBelt Semantic Layer driver for ClickHouse (DB-API 2.0)
+
+Part of the [OrionBelt Semantic Layer](https://github.com/ralfbecher/orionbelt-semantic-layer) project.
+
+## Installation
+
+```bash
+pip install ob-clickhouse
+```
+
+## License
+
+BSL-1.1 — see [LICENSE](LICENSE) for details.

ob_clickhouse-0.1.0/README.md

@@ -0,0 +1,15 @@
+# ob-clickhouse
+
+OrionBelt Semantic Layer driver for ClickHouse (DB-API 2.0)
+
+Part of the [OrionBelt Semantic Layer](https://github.com/ralfbecher/orionbelt-semantic-layer) project.
+
+## Installation
+
+```bash
+pip install ob-clickhouse
+```
+
+## License
+
+BSL-1.1 — see [LICENSE](LICENSE) for details.

ob_clickhouse-0.1.0/pyproject.toml

@@ -0,0 +1,52 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "ob-clickhouse"
+version = "0.1.0"
+description = "OrionBelt Semantic Layer driver for ClickHouse (DB-API 2.0)"
+license = { text = "BSL-1.1" }
+readme = "README.md"
+authors = [{ name = "Ralf Becher", email = "info@orionbelt.ai" }]
+keywords = ["clickhouse", "semantic-layer", "obml", "db-api", "orionbelt"]
+requires-python = ">=3.12"
+dependencies = [
+    "ob-driver-core>=0.1",
+    "clickhouse-connect>=0.7",
+    "pyarrow>=16.0",
+]
+
+[project.optional-dependencies]
+sqlalchemy = ["sqlalchemy>=2.0"]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+    "mypy>=1.10",
+    "ruff>=0.4",
+    "respx>=0.21",
+]
+
+[project.entry-points."sqlalchemy.dialects"]
+"ob.clickhouse" = "ob_clickhouse.dialect:OBClickHouseDialect"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/ob_clickhouse"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM", "ANN"]
+
+[tool.mypy]
+python_version = "3.12"
+strict = true
+files = ["src/ob_clickhouse"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+markers = ["integration: requires live DB + OB API"]
+addopts = "-m 'not integration'"

ob_clickhouse-0.1.0/src/ob_clickhouse/__init__.py

@@ -0,0 +1,114 @@
+"""ob-clickhouse — OrionBelt Semantic Layer driver for ClickHouse (PEP 249 DB-API 2.0).
+
+Requires the OrionBelt REST API running in single-model mode (MODEL_FILE set).
+OBML queries are compiled to SQL via ``POST /v1/query/sql``.
+
+Usage::
+
+    import ob_clickhouse
+
+    conn = ob_clickhouse.connect(host="localhost", database="default")
+    with conn.cursor() as cur:
+        cur.execute("select:\\n  dimensions:\\n    - Region\\n  measures:\\n    - Revenue")
+        print(cur.fetchall())
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import clickhouse_connect
+
+from ob_clickhouse.connection import Connection
+from ob_clickhouse.exceptions import (
+    DataError,
+    DatabaseError,
+    Error,
+    IntegrityError,
+    InterfaceError,
+    InternalError,
+    NotSupportedError,
+    OperationalError,
+    ProgrammingError,
+    Warning,
+)
+
+# PEP 249 module-level constants
+apilevel = "2.0"
+threadsafety = 1  # threads may share the module but not connections
+paramstyle = "pyformat"  # clickhouse-connect uses %(name)s placeholders
+
+
+def connect(
+    *,
+    host: str = "localhost",
+    port: int = 8123,
+    username: str = "default",
+    password: str = "",
+    database: str = "default",
+    secure: bool = False,
+    # Extra clickhouse-connect kwargs
+    settings: dict[str, Any] | None = None,
+    # OrionBelt parameters
+    ob_api_url: str = "http://localhost:8000",
+    ob_timeout: int = 30,
+) -> Connection:
+    """Open a ClickHouse connection with OBML support.
+
+    Parameters
+    ----------
+    host : str
+        ClickHouse host (default: ``localhost``).
+    port : int
+        ClickHouse HTTP port (default: ``8123``).
+    username : str
+        Username (default: ``default``).
+    password : str
+        Password (default: empty string).
+    database : str
+        Database name (default: ``default``).
+    secure : bool
+        Use HTTPS (default: ``False``).
+    settings : dict, optional
+        Extra ClickHouse server settings.
+    ob_api_url : str
+        OrionBelt REST API URL (must be running in single-model mode).
+    ob_timeout : int
+        HTTP timeout in seconds for OBML compilation.
+    """
+    client_kwargs: dict[str, Any] = {
+        "host": host,
+        "port": port,
+        "username": username,
+        "password": password,
+        "database": database,
+        "secure": secure,
+    }
+    if settings:
+        client_kwargs["settings"] = settings
+
+    client = clickhouse_connect.get_client(**client_kwargs)
+    return Connection(
+        client,
+        ob_api_url=ob_api_url,
+        ob_timeout=ob_timeout,
+    )
+
+
+__all__ = [
+    "apilevel",
+    "threadsafety",
+    "paramstyle",
+    "connect",
+    "Connection",
+    "Warning",
+    "Error",
+    "InterfaceError",
+    "DatabaseError",
+    "DataError",
+    "OperationalError",
+    "IntegrityError",
+    "InternalError",
+    "ProgrammingError",
+    "NotSupportedError",
+]

ob_clickhouse-0.1.0/src/ob_clickhouse/compiler.py

@@ -0,0 +1,8 @@
+"""OrionBelt compilation bridge — delegates to ob-driver-core."""
+
+from __future__ import annotations
+
+from ob_driver_core.compiler import compile_obml
+from ob_driver_core.detection import is_obml, parse_obml
+
+__all__ = ["compile_obml", "is_obml", "parse_obml"]

ob_clickhouse-0.1.0/src/ob_clickhouse/connection.py

@@ -0,0 +1,69 @@
+"""PEP 249 Connection wrapping a clickhouse-connect ``Client``.
+
+ClickHouse has no transactions — ``commit()`` and ``rollback()`` are no-ops
+that simply verify the connection is still open.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ob_clickhouse.cursor import Cursor
+from ob_clickhouse.exceptions import ProgrammingError
+
+
+class Connection:
+    """DB-API 2.0 connection wrapping a clickhouse-connect Client.
+
+    OBML queries are compiled to SQL via the OrionBelt REST API
+    (single-model mode, ``/v1/query/sql`` shortcut).
+    """
+
+    def __init__(
+        self,
+        client: Any,
+        *,
+        ob_api_url: str = "http://localhost:8000",
+        ob_timeout: int = 30,
+    ) -> None:
+        self._client = client
+        self._closed = False
+        self._ob_api_url = ob_api_url
+        self._ob_timeout = ob_timeout
+
+    def _check_open(self) -> None:
+        if self._closed:
+            raise ProgrammingError("Connection is closed.")
+
+    def cursor(self) -> Cursor:
+        """Return a new Cursor backed by the shared Client.
+
+        clickhouse-connect does not have its own cursor concept — our
+        ``Cursor`` wraps the Client directly.
+        """
+        self._check_open()
+        return Cursor(
+            self._client,
+            ob_api_url=self._ob_api_url,
+            ob_timeout=self._ob_timeout,
+        )
+
+    def commit(self) -> None:
+        """No-op — ClickHouse has no transactions."""
+        self._check_open()
+
+    def rollback(self) -> None:
+        """No-op — ClickHouse has no transactions."""
+        self._check_open()
+
+    def close(self) -> None:
+        """Close the connection and the underlying Client."""
+        if not self._closed:
+            self._client.close()
+            self._closed = True
+
+    def __enter__(self) -> Connection:
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()