TQL Language Reference

params {
  -- Country code. Examples: "US", "CA", "BR"
  country: String = "US"

  -- Inclusive lower bound in ISO 8601 format.
  created_after: Timestamp?
}

SELECT *
FROM visits
WHERE country = ${country}
  AND created_at >= ${created_after}

params {
  include_region: Bool = false
}

let
  select_expr = if include_region then sql"region, COUNT(*)" else sql"COUNT(*)"
  group_clause = if include_region then sql"GROUP BY region" else sql""
in sql''
  SELECT ${select_expr}
  FROM orders
  ${group_clause}
''

params {
  -- Country code.
  country: String = "US"

  -- Inclusive lower bound in ISO 8601 timestamp format.
  created_after: Timestamp?

  -- Metrics to include.
  metrics: Set<"revenue" | "order_count">

  -- Optional filters.
  filters: List<FilterInput> = []
}

params {
  limit: Int = 100
  include_test: Bool = false
  country: String = "US"
  dimensions: Set<"buyer" | "seller"> = []
  filters: List<FilterInput> = []
}

params {
  -- Filter by country code. Examples: "US", "CA", "BR"
  country: String = "US"

  -- Filters to apply. Allowed keys: buyer_name (equals, like), created_at (gte, lte, between)
  filters: List<FilterInput> = []
}

let
  left = sql"a"
  right = sql"b"
  cols = concatSep ", " [left, right]
in sql"SELECT ${cols}"

if isEmpty select_dims
then select_metrics
else sql"${select_dims}, ${select_metrics}"

let
  buyer = { expr = sql"b.name", join = sql"JOIN buyers b ON t.buyer_id = b.id" }
in sql"SELECT ${buyer.expr}"

sql''
  SELECT ${select_expr}
  FROM orders o
  ${where_clause}
''

-- Correct
WHERE country = ${country}

-- Wrong — TQL rejects this
WHERE country = '${country}'

let
  where_clause =
    if created_after == null
    then sql""
    else sql"WHERE created_at >= ${created_after}"

-- Correct
WHERE id IN ${ids}

-- Wrong — double parentheses
WHERE id IN (${ids})

metric_frags = matchSet metrics {
  "revenue" -> sql"SUM(t.revenue) AS revenue"
  "order_count" -> sql"COUNT(*) AS order_count"
}

filterables = [
  { key = "buyer_name", expr = sql"buyer_u.name", ops = ["equals", "like"] }
, { key = "created_at", expr = sql"t.created_at", ops = ["gte", "lte", "between"] }
]
where_clause = wrap "WHERE " "" (filterWhere filterables filters)

select_dims = concatSep ", " (map (\d -> d.expr) dim_entries)

where_clause = wrap "WHERE " "" predicates
group_clause = wrap "GROUP BY " "" group_cols

map (\d -> d.expr) dim_entries          -- apply function to each item
any (map (\d -> d == "seller") dims)    -- true if any element is true
contains dimensions "buyer"             -- true if set/list contains value

params {
  metrics: Set<"revenue" | "gmv" | "order_count">
  dimensions: Set<"buyer" | "seller" | "category"> = []
  filters: List<FilterInput> = []
}

let
  metric_frags = matchSet metrics {
    "revenue" -> sql"SUM(t.revenue) AS revenue"
    "gmv" -> sql"SUM(t.gmv) AS gmv"
    "order_count" -> sql"COUNT(*) AS order_count"
  }
  dim_entries = matchSet dimensions {
    "buyer" -> { expr = sql"buyer_u.name", join = sql"JOIN users buyer_u ON t.buyer_user_id = buyer_u.id" }
    "seller" -> { expr = sql"seller_u.name", join = sql"JOIN users seller_u ON t.seller_user_id = seller_u.id" }
    "category" -> { expr = sql"p.category", join = sql"JOIN products p ON t.product_id = p.id" }
  }
  filterables = [
    { key = "buyer_name", expr = sql"buyer_u.name", ops = ["equals", "like"] }
  , { key = "created_at", expr = sql"t.created_at", ops = ["gte", "lte", "between"] }
  ]
  joins = concatSep " " (map (\d -> d.join) dim_entries)
  select_dims = concatSep ", " (map (\d -> d.expr) dim_entries)
  select_metrics = concatSep ", " metric_frags
  select_expr = if isEmpty select_dims then select_metrics else sql"${select_dims}, ${select_metrics}"
  group_clause = wrap "GROUP BY " "" select_dims
  where_clause = wrap "WHERE " "" (filterWhere filterables filters)
in sql''
  SELECT ${select_expr}
  FROM transactions t
  ${joins}
  ${where_clause}
  ${group_clause}
''