How to choose and configure a backend¶

Semolina supports multiple data warehouse backends:

Snowflake – via semolina[snowflake]
Databricks – via semolina[databricks]
DuckDB – via semolina[duckdb]

The query API is identical across all three – only the connection configuration changes.

Register an engine¶

Build an engine with create_engine() and register it under a name. The engine owns one connection pool and the dialect for the backend. Two ways to build it: from a .semolina.toml connection name, or from a config object.

From a connection name (recommended)¶

from semolina import register, create_engine

register(
    "default", create_engine("default")
)  # reads .semolina.toml

create_engine("default") reads the [connections.default] section of .semolina.toml, creates an adbc-poolhouse connection pool, and derives the dialect from the section’s type. See How to connect to Snowflake, How to connect to Databricks, or How to connect to DuckDB for the TOML fields.

From a config object¶

Pass a config object when credentials come from a vault, a secrets manager, or need programmatic configuration.

Snowflake

from adbc_poolhouse import SnowflakeConfig

from semolina import register, create_engine

engine = create_engine(
    SnowflakeConfig(
        account="xy12345.us-east-1",
        user="myuser",
        password="mypassword",
        database="analytics",
        warehouse="compute_wh",
    )
)
register("default", engine)

Databricks

from adbc_poolhouse import DatabricksConfig

from semolina import register, create_engine

engine = create_engine(
    DatabricksConfig(
        host="workspace.cloud.databricks.com",
        http_path="/sql/1.0/warehouses/abc123",
        token="dapi...",
    )
)
register("default", engine)

DuckDB

from adbc_poolhouse import DuckDBConfig

from semolina import register, create_engine

engine = create_engine(
    DuckDBConfig(database="/path/to/warehouse.db")
)
register("default", engine)

Query with a registered engine¶

Once an engine is registered, the query API works the same regardless of backend:

from semolina import SemanticView, Metric, Dimension


class Sales(SemanticView, view="sales"):
    revenue = Metric()
    country = Dimension()


cursor = (
    Sales.query()
    .metrics(Sales.revenue)
    .dimensions(Sales.country)
    .execute()
)

for row in cursor.fetchall_rows():
    print(row.country, row.revenue)

Test locally without a warehouse¶

DuckDB works as a local backend for development and testing – no warehouse credentials needed. Install semolina[duckdb] and point at an in-memory or file-backed database. See How to connect to DuckDB for full setup instructions and How to test query code without a warehouse for the testing pattern.