ob-bigquery 0.1.0__tar.gz

ob_bigquery-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_bigquery-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_bigquery-0.1.0/PKG-INFO

@@ -0,0 +1,35 @@
+Metadata-Version: 2.4
+Name: ob-bigquery
+Version: 0.1.0
+Summary: OrionBelt Semantic Layer driver for BigQuery (DB-API 2.0)
+Author-email: Ralf Becher <info@orionbelt.ai>
+License: BSL-1.1
+License-File: LICENSE
+Keywords: bigquery,db-api,obml,orionbelt,semantic-layer
+Requires-Python: >=3.12
+Requires-Dist: google-cloud-bigquery[pandas]>=3.20
+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'
+Description-Content-Type: text/markdown
+
+# ob-bigquery
+
+OrionBelt Semantic Layer driver for BigQuery (DB-API 2.0)
+
+Part of the [OrionBelt Semantic Layer](https://github.com/ralfbecher/orionbelt-semantic-layer) project.
+
+## Installation
+
+```bash
+pip install ob-bigquery
+```
+
+## License
+
+BSL-1.1 — see [LICENSE](LICENSE) for details.

ob_bigquery-0.1.0/README.md

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

ob_bigquery-0.1.0/pyproject.toml

@@ -0,0 +1,48 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "ob-bigquery"
+version = "0.1.0"
+description = "OrionBelt Semantic Layer driver for BigQuery (DB-API 2.0)"
+license = { text = "BSL-1.1" }
+readme = "README.md"
+authors = [{ name = "Ralf Becher", email = "info@orionbelt.ai" }]
+keywords = ["bigquery", "semantic-layer", "obml", "db-api", "orionbelt"]
+requires-python = ">=3.12"
+dependencies = [
+    "ob-driver-core>=0.1",
+    "google-cloud-bigquery[pandas]>=3.20",
+    "pyarrow>=16.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+    "mypy>=1.10",
+    "ruff>=0.4",
+    "respx>=0.21",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/ob_bigquery"]
+
+[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_bigquery"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+markers = ["integration: requires live DB + OB API"]
+addopts = "-m 'not integration'"

ob_bigquery-0.1.0/src/ob_bigquery/__init__.py

@@ -0,0 +1,109 @@
+"""ob-bigquery — OrionBelt Semantic Layer driver for BigQuery (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_bigquery
+
+    conn = ob_bigquery.connect(project="my-gcp-project")
+    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
+
+from google.cloud import bigquery
+
+from ob_bigquery.connection import Connection
+from ob_bigquery.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"  # BigQuery uses %(name)s placeholders
+
+
+def connect(
+    *,
+    project: str | None = None,
+    credentials: Any = None,
+    credentials_file: str | None = None,
+    location: str | None = None,
+    # OrionBelt parameters
+    ob_api_url: str = "http://localhost:8000",
+    ob_timeout: int = 30,
+) -> Connection:
+    """Open a BigQuery connection with OBML support.
+
+    Parameters
+    ----------
+    project : str, optional
+        GCP project ID. If not set, uses Application Default Credentials project.
+    credentials : google.auth.credentials.Credentials, optional
+        Explicit credentials object. If not set, uses ADC.
+    credentials_file : str, optional
+        Path to a service account JSON key file. Alternative to setting
+        ``GOOGLE_APPLICATION_CREDENTIALS`` env var.
+    location : str, optional
+        Default dataset location (e.g. ``US``, ``EU``).
+    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.
+    """
+    if credentials_file is not None and credentials is None:
+        from google.oauth2 import service_account
+
+        credentials = service_account.Credentials.from_service_account_file(
+            credentials_file
+        )
+
+    client_kwargs: dict[str, Any] = {}
+    if project is not None:
+        client_kwargs["project"] = project
+    if credentials is not None:
+        client_kwargs["credentials"] = credentials
+    if location is not None:
+        client_kwargs["location"] = location
+
+    native = bigquery.Client(**client_kwargs)
+    return Connection(
+        native,
+        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_bigquery-0.1.0/src/ob_bigquery/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_bigquery-0.1.0/src/ob_bigquery/connection.py

@@ -0,0 +1,59 @@
+"""PEP 249 Connection wrapping ``google.cloud.bigquery.Client``."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ob_bigquery.cursor import Cursor
+from ob_bigquery.exceptions import ProgrammingError
+
+
+class Connection:
+    """DB-API 2.0 connection that wraps a native BigQuery client.
+
+    OBML queries are compiled to SQL via the OrionBelt REST API
+    (single-model mode, ``/v1/query/sql`` shortcut).
+    """
+
+    def __init__(
+        self,
+        native: Any,
+        *,
+        ob_api_url: str = "http://localhost:8000",
+        ob_timeout: int = 30,
+    ) -> None:
+        self._native = native
+        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 for this connection."""
+        self._check_open()
+        return Cursor(
+            self._native,
+            ob_api_url=self._ob_api_url,
+            ob_timeout=self._ob_timeout,
+        )
+
+    def commit(self) -> None:
+        """No-op — BigQuery auto-commits all statements."""
+
+    def rollback(self) -> None:
+        """No-op — BigQuery does not support transactions via this driver."""
+
+    def close(self) -> None:
+        """Close the connection."""
+        if not self._closed:
+            self._native.close()
+            self._closed = True
+
+    def __enter__(self) -> Connection:
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()

ob_bigquery-0.1.0/src/ob_bigquery/cursor.py

@@ -0,0 +1,209 @@
+"""PEP 249 Cursor with OBML interception for BigQuery.
+
+``execute()`` fetches results as an Arrow table via ``RowIterator.to_arrow()``
+for zero-copy Arrow Flight support.  ``fetch_arrow_table()`` returns the
+native Arrow table directly.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import pyarrow as pa
+
+from ob_bigquery.compiler import compile_obml, is_obml, parse_obml
+from ob_bigquery.exceptions import NotSupportedError, ProgrammingError
+from ob_bigquery.type_codes import BQ_TYPE_MAP, STRING
+
+
+class Cursor:
+    """DB-API 2.0 cursor that intercepts OBML YAML queries.
+
+    If the query is OBML, it is compiled to BigQuery SQL via the OrionBelt
+    REST API before execution. Plain SQL is passed through unchanged.
+
+    Results are kept in Arrow columnar format via ``to_arrow()``.
+    ``fetch_arrow_table()`` returns the Arrow table directly for efficient
+    Arrow Flight SQL streaming.
+    """
+
+    arraysize: int = 1
+
+    def __init__(
+        self,
+        native: Any,
+        *,
+        ob_api_url: str = "http://localhost:8000",
+        ob_timeout: int = 30,
+    ) -> None:
+        self._native = native
+        self._closed = False
+        self._ob_api_url = ob_api_url
+        self._ob_timeout = ob_timeout
+        self._results: Any = None
+        self._rows: list[tuple[Any, ...]] = []
+        self._index: int = 0
+        self._arrow_table: pa.Table | None = None
+
+    @property
+    def description(
+        self,
+    ) -> tuple[tuple[str, Any, None, None, None, None, None], ...] | None:
+        """PEP 249 cursor description — 7-item tuples per column."""
+        if self._results is None:
+            return None
+        schema = self._results.schema
+        if not schema:
+            return None
+        cols: list[tuple[str, Any, None, None, None, None, None]] = []
+        for field in schema:
+            type_code = BQ_TYPE_MAP.get(field.field_type, STRING)
+            cols.append((field.name, type_code, None, None, None, None, None))
+        return tuple(cols)
+
+    @property
+    def rowcount(self) -> int:
+        if self._results is None:
+            return -1
+        return self._results.total_rows or -1
+
+    def _check_open(self) -> None:
+        if self._closed:
+            raise ProgrammingError("Cursor is closed.")
+
+    def execute(self, operation: str, parameters: Any = None) -> Cursor:
+        """Execute a query — OBML YAML or plain SQL.
+
+        Fetches results as an Arrow table via ``to_arrow()`` for zero-copy
+        Arrow Flight support.
+        """
+        self._check_open()
+        sql = self._resolve_sql(operation)
+        if parameters is not None:
+            query_params = [
+                _to_query_parameter(k, v) for k, v in parameters.items()
+            ]
+            from google.cloud.bigquery import QueryJobConfig
+
+            job_config = QueryJobConfig(query_parameters=query_params)
+            self._results = self._native.query(sql, job_config=job_config)
+        else:
+            self._results = self._native.query(sql)
+
+        self._arrow_table = self._results.to_arrow()
+        pydict = self._arrow_table.to_pydict()
+        col_names = list(pydict.keys())
+        n = self._arrow_table.num_rows
+        self._rows = [tuple(pydict[c][i] for c in col_names) for i in range(n)]
+        self._index = 0
+        return self
+
+    def executemany(self, operation: str, seq_of_parameters: Any) -> None:
+        """Execute against all parameter sequences.
+
+        OBML queries are not supported with executemany — raises NotSupportedError.
+        """
+        self._check_open()
+        if is_obml(operation):
+            raise NotSupportedError("executemany() is not supported for OBML queries.")
+        for params in seq_of_parameters:
+            self.execute(operation, params)
+
+    def _resolve_sql(self, operation: str) -> str:
+        """Compile OBML to SQL or return plain SQL unchanged."""
+        if not is_obml(operation):
+            return operation
+        obml = parse_obml(operation)
+        return compile_obml(
+            obml,
+            dialect="bigquery",
+            ob_api_url=self._ob_api_url,
+            ob_timeout=self._ob_timeout,
+        )
+
+    def fetchone(self) -> tuple[Any, ...] | None:
+        """Fetch the next row."""
+        self._check_open()
+        if self._index >= len(self._rows):
+            return None
+        row = self._rows[self._index]
+        self._index += 1
+        return row
+
+    def fetchmany(self, size: int | None = None) -> list[tuple[Any, ...]]:
+        """Fetch the next *size* rows."""
+        self._check_open()
+        n = size if size is not None else self.arraysize
+        end = min(self._index + n, len(self._rows))
+        rows = self._rows[self._index : end]
+        self._index = end
+        return rows
+
+    def fetchall(self) -> list[tuple[Any, ...]]:
+        """Fetch all remaining rows."""
+        self._check_open()
+        rows = self._rows[self._index :]
+        self._index = len(self._rows)
+        return rows
+
+    def fetch_arrow_table(self) -> pa.Table:
+        """Fetch all remaining rows as a PyArrow Table.
+
+        BigQuery results are fetched via ``RowIterator.to_arrow()`` during
+        ``execute()``, providing zero-copy Arrow access.  Significantly more
+        memory-efficient for large result sets and enables efficient Arrow
+        Flight SQL streaming.
+        """
+        self._check_open()
+        if self._arrow_table is None:
+            raise ProgrammingError("No Arrow result available — already consumed.")
+        table = self._arrow_table
+        self._arrow_table = None
+        return table
+
+    def close(self) -> None:
+        """Close the cursor."""
+        if not self._closed:
+            self._results = None
+            self._rows = []
+            self._arrow_table = None
+            self._closed = True
+
+    def setinputsizes(self, sizes: Any) -> None:
+        """No-op — required by PEP 249."""
+
+    def setoutputsize(self, size: int, column: int | None = None) -> None:
+        """No-op — required by PEP 249."""
+
+    @property
+    def lastrowid(self) -> None:
+        """BigQuery does not support lastrowid."""
+        return None
+
+    def __enter__(self) -> Cursor:
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+    def __iter__(self) -> Cursor:
+        return self
+
+    def __next__(self) -> tuple[Any, ...]:
+        row = self.fetchone()
+        if row is None:
+            raise StopIteration
+        return row
+
+
+def _to_query_parameter(name: str, value: Any) -> Any:
+    """Convert a Python value to a BigQuery ScalarQueryParameter."""
+    from google.cloud.bigquery import ScalarQueryParameter
+
+    if isinstance(value, int):
+        return ScalarQueryParameter(name, "INT64", value)
+    if isinstance(value, float):
+        return ScalarQueryParameter(name, "FLOAT64", value)
+    if isinstance(value, bool):
+        return ScalarQueryParameter(name, "BOOL", value)
+    return ScalarQueryParameter(name, "STRING", str(value))

ob_bigquery-0.1.0/src/ob_bigquery/exceptions.py

@@ -0,0 +1,32 @@
+"""PEP 249 exceptions — re-exported from ob-driver-core for convenience.
+
+Allows users to do: ``from ob_bigquery.exceptions import ProgrammingError``
+"""
+
+from __future__ import annotations
+
+from ob_driver_core.exceptions import (
+    DataError,
+    DatabaseError,
+    Error,
+    IntegrityError,
+    InterfaceError,
+    InternalError,
+    NotSupportedError,
+    OperationalError,
+    ProgrammingError,
+    Warning,
+)
+
+__all__ = [
+    "Warning",
+    "Error",
+    "InterfaceError",
+    "DatabaseError",
+    "DataError",
+    "OperationalError",
+    "IntegrityError",
+    "InternalError",
+    "ProgrammingError",
+    "NotSupportedError",
+]

ob_bigquery-0.1.0/src/ob_bigquery/type_codes.py

@@ -0,0 +1,40 @@
+"""PEP 249 type objects — re-exported from ob-driver-core plus BigQuery type mapping.
+
+google-cloud-bigquery cursor.description returns string type names.
+The BQ_TYPE_MAP maps them to PEP 249 type objects.
+"""
+
+from __future__ import annotations
+
+from ob_driver_core.type_codes import BINARY, DATETIME, NUMBER, ROWID, STRING
+
+__all__ = ["STRING", "BINARY", "NUMBER", "DATETIME", "ROWID", "BQ_TYPE_MAP"]
+
+# BigQuery standard SQL type names
+# https://cloud.google.com/bigquery/docs/reference/standard-sql/data-types
+BQ_TYPE_MAP: dict[str, object] = {
+    # Numeric types
+    "INTEGER": NUMBER,
+    "INT64": NUMBER,
+    "FLOAT": NUMBER,
+    "FLOAT64": NUMBER,
+    "NUMERIC": NUMBER,
+    "BIGNUMERIC": NUMBER,
+    "BOOLEAN": STRING,
+    "BOOL": STRING,
+    # String types
+    "STRING": STRING,
+    "JSON": STRING,
+    # Date/time types
+    "DATE": DATETIME,
+    "TIME": DATETIME,
+    "DATETIME": DATETIME,
+    "TIMESTAMP": DATETIME,
+    # Binary types
+    "BYTES": BINARY,
+    # Geo/struct/array — map to STRING for display
+    "GEOGRAPHY": STRING,
+    "STRUCT": STRING,
+    "RECORD": STRING,
+    "ARRAY": STRING,
+}