tesseract-olap 0.23.2

A semantic layer for your data.

Tesseract OLAP

A semantic layer for your data, enabling OLAP operations over relational databases. Tesseract OLAP provides a Python interface to translate multidimensional queries into optimized SQL, executing them against a backend, and returning the results in a structured format.

Key Capabilities

• Multidimensional Analysis: Supports standard OLAP operations like drilling down, slicing, dicing, and pivoting.
• Backend Agnostic: Designed to work with various data backends. Currently supports ClickHouse with specialized drivers.
• Schema Validation: Uses a robust XML schema definition to validate queries and ensure data integrity.
• High Performance: leverages polars for efficient data handling and transformation.
• Caching: Built-in support for caching query results to improve performance (supports Redis).

Installation

Install the package using pip:

pip install tesseract-olap

Optional Dependencies

To use specific backends or features, install the corresponding extras:

• ClickHouse Backend:

  pip install "tesseract-olap[clickhouse]"
  

• Redis Caching:

  pip install "tesseract-olap[redis]"
  

Getting Started

In its most basic form, the tesseract-olap package provides a way to translate OLAP-type queries into request statements that a data backend can understand and execute safely.

1. Define your Schema

Tesseract uses a schema to define cubes, dimensions, and measures. Supported formats include XML, JSON, and YAML. See the OLAP Model Concepts and examples in the repository for schema details.

2. Initialize the Server

from tesseract_olap.backend.clickhouse import ClickhouseBackend
from tesseract_olap import OlapServer

# Initialize the backend connection
backend = ClickhouseBackend("clickhouse://user:pass@localhost:9000/database")

# Create the server instance with the schema
server = OlapServer(backend=backend, schema="./path/to/schema.xml")

3. Execute a Query

from tesseract_olap.query import DataRequest, DataQuery

def get_data():
    # Create a request object defining the query
    request = DataRequest.new("cube_name", {
        "drilldowns": ["Time", "Country"],
        "measures": ["Units", "Price"],
    })

    # Validate and compile the request against the schema
    query = DataQuery.from_request(server.schema, request)

    # Execute the query
    with server.session() as session:
        # Fetch results in different formats
        # result = session.fetch(query)           # Returns a Result object
        # result = session.fetch_records(query)   # Returns a list of dicts
        result = session.fetch_dataframe(query)   # Returns a Polars DataFrame

    return result.data

if __name__ == "__main__":
    data = get_data()
    print(data)

The server instance can be integrated into web applications (like FastAPI or LogicLayer) to provide a full-fledged OLAP API.

---

© 2022-2024 Datawheel, LLC.