Helpers & the Run Context

Reusable helper queries and the run context (the seek object) your model code receives at runtime.

Everything on this page works the same for SBT Beta and SBT 1.0 apps.

This page covers the two tools your model code can lean on: helper queries (reusable SQL) and the run context (the seek object every model receives). Not to be confused with App Context, which is the platform tool for describing your app's data to Intelligence.

Helper queries

Helper queries are reusable SQL queries, defined in .sql files in the helpers/ directory of your project. They can use the run context to access sources and other models.

Current uses across Insight Cloud:

  • Defining the freshness timestamp of an app

  • Defining the valid options for a model parameter. This query populates the dropdown in the variant parameter management screen — and, for RLS parameters, the Set Data Access screen at install time.

A values query must return exactly two columns, aliased value and label. value is stored and passed to your model; label is displayed to the user in the dropdown. A values query with different column names produces an empty dropdown — and for RLS parameters, blocks the install with a server error.

select distinct REGION as value, REGION as label
from MY_DB.MY_SCHEMA.STORES

The run context (the seek object)

Every model receives a parameter named seek: a SeekRunContext object created when someone runs the app. It tells your code what it is connected to for this run:

class SeekRunContext:
    model_name: str   # name of currently running model
    target_name: str  # schema.table name of output object
    current_db: str   # db name of output object
    params: dict
    sources: dict
    models: dict

SQL models

SQL models reference the seek object with a Python-like syntax. Your SQL runs through a Python runtime that fills in the run context values:

select *
from {seek.sources['known_source_name']} as source
join {seek.models['upstream_model']} as model
  on source.id = model.id
where date >= {seek.params['lookback_date']}

Python models

def model(session, seek):
    source = seek.sources['known_source_name']
    model = seek.models['upstream_model']
    lookback_date = seek.params['lookback_date']
    # do some python magic
    return result

Note: values of parameters marked rls: true arrive as a LIST (subscribers can select multiple values). Filter with .isin(), not ==. See RLS Parameters.

Related articles

⏭️ Next: Dependencies: packages, wheels, and requirements.txt