Query Templates

Joqi supports parameter references with $param. This lets you save a query once and run it with different request values.

Templates are useful for saved reports, dashboard cards, exports, and product-owned data views.

Template

{
  "version": "v1",
  "source": "placement",
  "select": ["name", "status", "budget", "campaign.name"],
  "where": {
    "and": [
      { "field": "status", "op": "eq", "value": { "$param": "status" } },
      { "field": "budget", "op": "gte", "value": { "$param": "minBudget" } },
      { "field": "campaign.name", "op": "contains", "value": { "$param": "campaignName" } }
    ]
  },
  "limit": { "$param": "limit" }
}

The template contains no request-specific values. It only names required params.

Runtime values

await runtime.run({
  spec: reportTemplate,
  params: {
    status: "active",
    minBudget: 10000,
    campaignName: "spring",
    limit: 25,
  },
});

Missing params fail validation before the executor is called.

Validation rules

• A $param ref must be exactly { "$param": "name" } with no extra properties.
• Filter params are checked against the resolved field type.
• limit and offset params must be non-negative integers.
• in params must be non-empty arrays.
• Missing params fail before SQL compilation and execution.

Why params are separate

Separating templates from values gives you stable JSON contracts:

• Store a template in a database.
• Review or approve templates before users run them.
• Reuse one template across tenants or dashboards.
• Bind user input only at request time.
• Keep SQL params bound through the adapter instead of interpolating values.