+ Powerful techniques for complex analytical queries +
++ Calculate percentage contributions using window functions +
+
+ {`# Define a measure that calculates percentage of total
+measures = {
+ 'flight_count': lambda t: t.count(),
+ 'pct_of_total': lambda t: (
+ t.count() / t.count().sum().over()
+ ) * 100
+}
+
+result = flights_sm.query(
+ dimensions=['origin'],
+ measures=['flight_count', 'pct_of_total']
+).execute()`}
+
+ + Create hierarchical subtotals for grouped data +
+
+ {`# Query with multiple group levels
+result = flights_sm.query(
+ dimensions=['origin', 'carrier'],
+ measures=['flight_count', 'total_distance']
+).execute()
+
+# Add subtotals using grouping sets
+from ibis import _
+
+subtotals = flights_sm.table.group_by([
+ _.origin,
+ _.carrier
+]).agg(
+ flight_count=_.count(),
+ total_distance=_.distance.sum()
+).union(
+ # Subtotals by origin only
+ flights_sm.table.group_by(_.origin).agg(
+ carrier=ibis.literal('TOTAL'),
+ flight_count=_.count(),
+ total_distance=_.distance.sum()
+ )
+)`}
+
+ + Group low-frequency values into an "Others" category +
+
+ {`# Create bucketed dimension
+dimensions = {
+ 'origin': lambda t: t.origin,
+ 'origin_bucketed': lambda t: t.origin.isin(['JFK', 'LGA', 'EWR']).ifelse(
+ t.origin,
+ 'Others'
+ )
+}
+
+result = flights_sm.query(
+ dimensions=['origin_bucketed'],
+ measures=['flight_count']
+).execute()`}
+
+ + Analyze user sessions and event sequences +
++ Create session IDs based on time gaps between events +
+
+ {`# Define session dimension using window functions
+dimensions = {
+ 'user_id': lambda t: t.user_id,
+ 'session_id': lambda t: (
+ (t.timestamp - t.timestamp.lag().over(
+ ibis.window(group_by='user_id', order_by='timestamp')
+ ) > ibis.interval(minutes=30))
+ .cast('int32')
+ .sum()
+ .over(ibis.window(group_by='user_id', order_by='timestamp'))
+ )
+}
+
+measures = {
+ 'session_count': lambda t: t.session_id.nunique(),
+ 'events_per_session': lambda t: t.count() / t.session_id.nunique()
+}`}
+
+ + Create indexed values for time series comparisons +
+
+ {`# Index to base period (e.g., first month = 100)
+measures = {
+ 'flight_count': lambda t: t.count(),
+ 'indexed_count': lambda t: (
+ t.count() / t.count().first().over(
+ ibis.window(order_by='date')
+ ) * 100
+ )
+}
+
+result = flights_sm.query(
+ dimensions=['date'],
+ measures=['flight_count', 'indexed_count'],
+ time_grain='TIME_GRAIN_MONTH'
+).execute()`}
+
+ + Build measures on top of other measures for complex calculations +
+
+ {`# Layer measures on top of each other
+measures = {
+ # Base measures
+ 'total_flights': lambda t: t.count(),
+ 'total_distance': lambda t: t.distance.sum(),
+
+ # Nested measure using base measures
+ 'avg_distance_per_flight': lambda t: (
+ t.total_distance / t.total_flights
+ ),
+
+ # Further nesting
+ 'distance_efficiency': lambda t: (
+ t.avg_distance_per_flight / t.avg_distance_per_flight.max()
+ ) * 100
+}
+
+result = flights_sm.query(
+ dimensions=['carrier'],
+ measures=[
+ 'total_flights',
+ 'avg_distance_per_flight',
+ 'distance_efficiency'
+ ]
+).execute()`}
+
+
+ {data.error}
+
+ + ✓ Semantic table {data.name} defined +
+| + + | + {data.columns.map((col, idx) => ( ++ {col} + | + ))} +
|---|---|
| + {rowIdx} + | + {row.map((cell, cellIdx) => { + const formattedValue = formatCellValue(cell) + const isComplex = formattedValue.includes('\n') || formattedValue.length > 50 + + return ( +
+ {isComplex ? (
+
+ {formattedValue}
+
+ ) : (
+ formattedValue
+ )}
+ |
+ )
+ })}
+
+
+ + Everything you need to build a powerful semantic layer +
++ {feature.description} +
++ Choose the installation that fits your needs +
+
+ {option.command}
+
+ {children},
+ a: ({ href, children }) => {children}
+ }}
+ >
+ {content}
+ + Use powerful query methods to analyze your data +
++ Once you've defined your semantic tables, you can query them using intuitive methods + like group_by, aggregate, mutate, and more. All queries are composable and generate + optimized SQL. +
++ Core query methods for data transformation and analysis +
+Group data by dimensions
+
+ {`# Group by single dimension
+result = flights_sm.query(
+ dimensions=['origin'],
+ measures=['flight_count']
+).execute()
+
+# Group by multiple dimensions
+result = flights_sm.query(
+ dimensions=['origin', 'carrier'],
+ measures=['flight_count', 'avg_distance']
+).execute()`}
+
+ Apply aggregation functions
+
+ {`# Aggregate measures
+result = flights_sm.query(
+ measures=['total_flights', 'total_distance', 'avg_distance']
+).execute()`}
+
+ Sort results by dimensions or measures
+
+ {`# Order by dimension
+result = flights_sm.query(
+ dimensions=['origin'],
+ measures=['flight_count'],
+ order_by=['origin']
+).execute()
+
+# Order by measure (descending)
+result = flights_sm.query(
+ dimensions=['origin'],
+ measures=['flight_count'],
+ order_by=[('flight_count', 'desc')]
+).execute()`}
+
+ + Query across multiple joined semantic tables +
+
+ {`# Query dimensions and measures from joined models
+result = flights_sm.query(
+ dimensions=[
+ 'origin', # From flights
+ 'carriers.name', # From joined carriers
+ 'carriers.nickname' # Also from carriers
+ ],
+ measures=[
+ 'flight_count', # From flights
+ 'carriers.carrier_count' # From carriers
+ ]
+).execute()`}
+
+ + Control result size and filter data +
+
+ {`# Get top 10 results
+result = flights_sm.query(
+ dimensions=['origin'],
+ measures=['flight_count'],
+ limit=10
+).execute()`}
+
+
+ {`# Filter using lambda
+result = flights_sm.query(
+ dimensions=['origin'],
+ measures=['flight_count'],
+ filters=[lambda t: t.origin == 'JFK']
+).execute()`}
+
+
+ {`# Filter using JSON syntax
+result = flights_sm.query(
+ dimensions=['origin'],
+ measures=['flight_count'],
+ filters=[
+ {
+ 'operator': 'AND',
+ 'conditions': [
+ {'field': 'origin', 'operator': 'in', 'values': ['JFK', 'LGA']},
+ {'field': 'year', 'operator': '=', 'values': [2013]}
+ ]
+ }
+ ]
+).execute()`}
+
+ + Handle naming conflicts when joining models +
++ When multiple models have dimensions or measures with the same name, + use the model prefix to disambiguate. +
+
+ {`# Both models have a 'name' dimension
+result = flights_sm.query(
+ dimensions=[
+ 'flights.name', # Explicitly from flights
+ 'carriers.name' # Explicitly from carriers
+ ],
+ measures=['flight_count']
+).execute()`}
+
+ + Visualize your query results with built-in charting +
+
+ {`# Install with viz support
+pip install 'boring-semantic-layer[viz-altair]'
+
+# Create a chart from your query
+query = flights_sm.query(
+ dimensions=['origin'],
+ measures=['flight_count']
+)
+
+# Auto-detect chart type
+chart = query.chart()
+chart.save('flights.html')`}
+
+
+ {`# Specify mark type
+chart = query.chart(mark='bar')
+chart = query.chart(mark='line')
+chart = query.chart(mark='point')
+
+# Time series
+time_query = flights_sm.query(
+ dimensions=['date'],
+ measures=['flight_count'],
+ time_range={'start': '2013-01-01', 'end': '2013-12-31'},
+ time_grain='TIME_GRAIN_MONTH'
+)
+chart = time_query.chart() # Auto-detects time series`}
+
+ + Three simple steps to get started - Try the code live in Marimo! +
+Expected output:
+| origin | +flight_count | +
|---|---|
| JFK | +3689 | +
| LGA | +2941 | +
+ {code}
+
+ )
+ }
+
+ // Plain text with multiple lines
+ if (lines.length > 1) {
+ return (
+ + Define your data model with dimensions and measures using Ibis expressions +
++ A Semantic Table is the core building block of BSL. It transforms a raw Ibis table + into a reusable, self-documenting data model by defining dimensions (attributes to group by) + and measures (aggregations and calculations). +
++ Transform your Ibis tables into semantic models +
+
+ {`import ibis
+from boring_semantic_layer import SemanticModel
+
+# 1. Start with an Ibis table
+flights_tbl = ibis.table(
+ name="flights",
+ schema={"origin": "string", "carrier": "string", "distance": "int64"}
+)
+
+# 2. Convert to a Semantic Table
+flights_sm = SemanticModel(
+ name="flights",
+ table=flights_tbl,
+ dimensions={
+ 'origin': lambda t: t.origin,
+ 'carrier': lambda t: t.carrier
+ },
+ measures={
+ 'flight_count': lambda t: t.count(),
+ 'total_distance': lambda t: t.distance.sum()
+ }
+)`}
+
+ + Define dimensions with optional descriptions for better documentation +
+
+ {`from boring_semantic_layer import SemanticModel
+
+flights_sm = SemanticModel(
+ table=flights_tbl,
+ dimensions={
+ 'origin': lambda t: t.origin,
+ 'destination': lambda t: t.dest,
+ 'year': lambda t: t.year
+ }
+)`}
+
+ + Add descriptions to make your models self-documenting and AI-friendly +
+
+ {`from boring_semantic_layer import SemanticModel, DimensionSpec
+
+flights_sm = SemanticModel(
+ table=flights_tbl,
+ dimensions={
+ "origin": DimensionSpec(
+ expr=lambda t: t.origin,
+ description="Origin airport code where the flight departed"
+ ),
+ "destination": DimensionSpec(
+ expr=lambda t: t.dest,
+ description="Destination airport code where the flight arrived"
+ ),
+ "year": DimensionSpec(
+ expr=lambda t: t.year,
+ description="Year of the flight"
+ )
+ }
+)`}
+
+ + Define measures with lambda expressions, shortcuts, and descriptions +
+
+ {`measures={
+ 'total_flights': lambda t: t.count(),
+ 'total_distance': lambda t: t.distance.sum(),
+ 'avg_distance': lambda t: t.distance.mean(),
+ 'max_delay': lambda t: t.dep_delay.max()
+}`}
+
+
+ {`from boring_semantic_layer import MeasureSpec
+
+measures={
+ "flight_count": MeasureSpec(
+ expr=lambda t: t.count(),
+ description="Total number of flights"
+ ),
+ "avg_distance": MeasureSpec(
+ expr=lambda t: t.distance.mean(),
+ description="Average flight distance in miles"
+ )
+}`}
+
+ + Build complex measures by referencing other measures +
+
+ {`measures={
+ 'total_distance': lambda t: t.distance.sum(),
+ 'flight_count': lambda t: t.count(),
+ # Reference other measures
+ 'avg_distance_per_flight': lambda t: t.total_distance / t.flight_count
+}`}
+
+ + Connect semantic tables with join, join_one, and join_cross +
+
+ {`from boring_semantic_layer import Join
+
+# Define carriers model
+carriers_sm = SemanticModel(
+ name="carriers",
+ table=carriers_tbl,
+ dimensions={
+ "code": lambda t: t.code,
+ "name": lambda t: t.name
+ }
+)
+
+# Join with flights
+flights_sm = SemanticModel(
+ name="flights",
+ table=flights_tbl,
+ dimensions={"carrier": lambda t: t.carrier},
+ measures={"flight_count": lambda t: t.count()},
+ joins={
+ "carriers": Join(
+ model=carriers_sm,
+ on=lambda left, right: left.carrier == right.code,
+ how="left" # or "inner", "right", "outer"
+ )
+ }
+)
+
+# Query across joined models
+flights_sm.query(
+ dimensions=['carriers.name'],
+ measures=['flight_count']
+).execute()`}
+
+ + Use join_one for relationships where each row matches exactly one row in the joined table +
+
+ {`from boring_semantic_layer import join_one
+
+flights_sm = SemanticModel(
+ table=flights_tbl,
+ joins={
+ "carrier_details": join_one(
+ model=carriers_sm,
+ on=lambda left, right: left.carrier == right.code
+ )
+ }
+)`}
+
+ + Create cartesian products for special analytical needs +
+
+ {`from boring_semantic_layer import join_cross
+
+# Cross join for generating all combinations
+flights_sm = SemanticModel(
+ table=flights_tbl,
+ joins={
+ "all_carriers": join_cross(model=carriers_sm)
+ }
+)`}
+
+ + Build complex data models by combining multiple semantic tables +
+
+ {`# Build layered models
+base_flights = SemanticModel(
+ table=flights_tbl,
+ dimensions={'origin': lambda t: t.origin},
+ measures={'count': lambda t: t.count()}
+)
+
+enriched_flights = SemanticModel(
+ table=base_flights.table,
+ dimensions={
+ **base_flights.dimensions,
+ 'destination': lambda t: t.dest
+ },
+ measures={
+ **base_flights.measures,
+ 'avg_distance': lambda t: t.distance.mean()
+ }
+)`}
+
+ + Define your semantic models using YAML for better organization +
+
+ {`# flights_model.yml
+flights:
+ table: flights_table
+ description: "Flight data with departure and arrival information"
+
+ dimensions:
+ origin:
+ expr: _.origin
+ description: "Origin airport code"
+
+ destination:
+ expr: _.destination
+ description: "Destination airport code"
+
+ measures:
+ flight_count:
+ expr: _.count()
+ description: "Total number of flights"
+
+ avg_distance:
+ expr: _.distance.mean()
+ description: "Average flight distance in miles"`}
+
+
+ {`from boring_semantic_layer import SemanticModel
+
+# Load models from YAML
+models = SemanticModel.from_yaml(
+ "flights_model.yml",
+ tables={"flights_table": flights_tbl}
+)
+
+flights_sm = models["flights"]`}
+
+
+ {data.error}
+
+
+ {data.output}
+
+ {data.message}
++ The Boring Semantic Layer (BSL) is a lightweight semantic layer based on{" "} + + Ibis + + . +
++ BSL provides a simple, consistent way to define your data model once and query it anywhere. + Built on top of Ibis, it inherits all the power and flexibility of Ibis expressions while + adding a semantic layer that makes your data more accessible and reusable. +
+Joint Project
++ This project is a collaborative effort between{" "} + + xorq-labs + + {" "}and{" "} + + boringdata + + . We welcome feedback and contributions! +
+