Sidequery

Getting Started

Learn how to get started with Sidequery tools and services.

Installation

pip install sidemantic
# or
uv add sidemantic

Workbench

Try the interactive workbench with demo data (no installation required):

uvx sidemantic workbench --demo

See Workbench for more details on the interactive TUI.

Your First Semantic Layer

Sidemantic supports three definition syntaxes: YAML, SQL, and Python. Choose your preference!

YAML Syntax

Create semantic_layer.yml:

models:
  - name: orders
    table: orders
    primary_key: order_id

    dimensions:
      - name: order_date
        type: time
        sql: order_date
        granularity: day

      - name: status
        type: categorical
        sql: status

    metrics:
      - name: revenue
        agg: sum
        sql: amount

      - name: order_count
        agg: count

SQL Syntax

Create semantic_layer.sql:

MODEL (
    name orders,
    table orders,
    primary_key order_id
);

DIMENSION (
    name order_date,
    type time,
    sql order_date,
    granularity day
);

DIMENSION (
    name status,
    type categorical,
    sql status
);

METRIC (
    name revenue,
    agg sum,
    sql amount
);

METRIC (
    name order_count,
    agg count
);

Python Syntax

Create your semantic layer in code:

from sidemantic import SemanticLayer, Model, Dimension, Metric

layer = SemanticLayer()

orders = Model(
    name="orders",
    table="orders",
    primary_key="order_id",
    dimensions=[
        Dimension(name="order_date", type="time", sql="order_date", granularity="day"),
        Dimension(name="status", type="categorical", sql="status"),
    ],
    metrics=[
        Metric(name="revenue", agg="sum", sql="amount"),
        Metric(name="order_count", agg="count"),
    ]
)

layer.add_model(orders)

Query with SQL

from sidemantic import SemanticLayer

# Load from YAML or SQL file
layer = SemanticLayer.from_yaml("semantic_layer.yml")  # or .sql

# Query with SQL
result = layer.sql("""
    SELECT revenue, order_count, status
    FROM orders
    WHERE status = 'completed'
""")

df = result.fetchdf()
print(df)

Note: from_yaml() works with both .yml and .sql files!

Add Relationships

Define relationships between models:

models:
  - name: orders
    table: orders
    primary_key: order_id
    relationships:
      - name: customer
        type: many_to_one
        foreign_key: customer_id

  - name: customers
    table: customers
    primary_key: customer_id

Query across models:

# Automatic join
result = layer.sql("""
    SELECT orders.revenue, customers.region
    FROM orders
""")

Complex Metrics

Add graph-level metrics with automatic dependency detection:

models:
  - name: orders
    metrics:
      - name: revenue
        agg: sum
        sql: amount

      - name: completed_revenue
        agg: sum
        sql: amount
        filters: ["status = 'completed'"]

# Graph-level metrics (dependencies auto-detected!)
metrics:
  # Simple reference
  - name: total_revenue
    sql: orders.revenue

  # Ratio
  - name: conversion_rate
    type: ratio
    numerator: orders.completed_revenue
    denominator: orders.revenue

  # Derived (dependencies auto-detected from formula!)
  - name: profit_margin
    type: derived
    sql: "(revenue - cost) / revenue"

  # Cumulative
  - name: running_total
    type: cumulative
    sql: orders.revenue
    window: "7 days"

Editor Autocomplete (YAML)

For YAML definitions, add this comment to get autocomplete in VS Code, IntelliJ, and other editors:

# yaml-language-server: $schema=https://sidemantic.com/schema.json
models:
  - name: orders
    # ... autocomplete works here!

Next Steps