Compass Parameters

Compass records support dynamic values through the {{parameter_name}} placeholder syntax. Instead of writing the same query multiple times for different date ranges, machine IDs or line selections, Pirivision uses a single record + values passed from the dashboard model.

This page explains how parameters are written, how they are interpreted per data source, how they are configured in the Display Info / Parameter Settings panel, and how they are fed by Cartography / dashboard filters.

flowchart LR
    A["Compass Query<br/>&#123;&#123;line_id&#125;&#125;"] --> B["Save Panel<br/>Parameter Type + Default"]
    B --> C["Cartography Widget<br/>Filter / Tag / GlobalVar"]
    C --> D["Horizon / Atlas<br/>Dashboard Filter"]
    D -- "Value at runtime" --> A

1. Syntax — `{{parameter_name}}`

Rule	Description
Open / close	Double curly braces: `{{` ... `}}`
Allowed characters	Letters (`A-Z`, `a-z`), digits (`0-9`) and underscore (`_`). No spaces, dashes or non-ASCII characters
Case sensitivity	Case-sensitive — `{{Line_Id}}` and `{{line_id}}` are different parameters
Quoting	Never quote — backend produces dialect-safe placeholders for you
Reuse	The same parameter may appear multiple times in a query; backend handles each dialect correctly

Never wrap in quotes — silent 0-row failure

Compass placeholders are written without quotes:

✅ Correct	❌ Wrong
`WHERE line_id = {{line_id}}`	`WHERE line_id = '{{line_id}}'`
`WHERE plant = {{plant_code}}`	`WHERE plant = "{{plant_code}}"`

If wrapped in single quotes, the query becomes a literal WHERE line_id = '$1' (PostgreSQL) or WHERE line_id = '?' (MySQL) and returns 0 rows silently — no error.

2. Behavior per Data Source

The Pirivision backend generates a different placeholder per dialect; you always write {{name}} — Pirivision rewrites it.

2.1. PostgreSQL — `$1, $2, ...`

{{line_id}} → $1. The same parameter reuses the same $N index:

SELECT *
FROM   sensor_zaman_serisi s
JOIN   makineler m ON m.hat_id = {{hat_id}}   -- $1
WHERE  s.hat_id = {{hat_id}}                          -- $1 again, no new arg
ORDER  BY ts DESC;

Benefit	Description
SQL-injection safe	The `pq` driver escapes via prepared statements
Type casts	Cast inside the query when needed: `{{start_date}}::timestamp`, `{{plant_id}}::int`

2.2. MySQL — Positional `?`

{{name}} → ?. Each occurrence becomes a new ? and the value is appended to args list each time:

SELECT *
FROM   demo_vardiya_uretim
WHERE  hat     = {{hat_id}}      -- ?  (args[0])
   OR  vardiya = {{hat_id}};     -- ?  (args[1])

2.3. MSSQL (T-SQL) — Named `@name`

{{line_id}} → @line_id:

SELECT *
FROM   demo_fabrika.vardiya_uretim WITH (NOLOCK)
WHERE  hat      = {{hat_id}}      -- @hat_id
  AND  tarih   >= {{start_date}}  -- @start_date

Auto integer detection (MSSQL only)

Backend tries strconv.Atoi on the parameter; if it succeeds, the value is sent as sql.Named(name, intValue). Otherwise it is sent as a string. Explicit CAST({{id}} AS INT) is therefore optional.

2.4. REST API — Literal String Substitution

REST endpoint records perform literal string substitution (not prepared statements). {{param}} is replaced inline with the value.

Field	Parameter Support	Example
Endpoint Path	✅	`/api/recete` (path fixed; parameters in query string)
Query Parameters	✅ (in Value)	Key: `makine`, Value: `{{makine_id}}`
Headers	✅ (in Header Value)	Header Key: `X-Hat-ID`, Value: `{{hat_id}}`
Body (POST)	✅ (inside JSON body)	`{"hat": "{{hat_id}}"}` (JSON requires quotes)

REST body requires quotes

Unlike SQL, when writing a JSON string value in a REST body, {{param}} must be inside quotes:

{ "filter": { "plant_id": "{{plant_id}}" } }

Otherwise the JSON body becomes invalid.

2.5. MQTT — Not Supported

MQTT topic selections do not support {{...}}. Topic paths are static (fabrika/hat1/sicaklik); dynamic filtering happens at the Cartography widget via the tag mechanism.

→ Detail: MQTT Topic Selection

2.6. Excel — Not Supported

Excel sheet selections do not support parameters either; the sheet name is static.

3. Adding a Parameter — Step-by-Step

3.1. Write the Query with Parameters

Write your query directly with {{hat_id}} double curly brace syntax:

SELECT ts, sicaklik, basinc, makine_id
FROM   sensor_zaman_serisi
WHERE  ts >= NOW() - INTERVAL '24 hours'
  AND  hat_id = {{hat_id}}
ORDER  BY ts;

The editor automatically detects {{hat_id}} and lists it under Parameters.

3.2. Enter a Test Value

In the Parameters panel below the editor, type hat_id = HAT-1 and click Preview. This is for testing only; the real default is set on the save panel.

3.3. Save → Parameter Settings

Clicking Next opens Set Parameters type and Default Values, where each unique parameter appears as a card.

4. Parameter Settings — Type Options

Click Set Parameter on a card to expand it. Four types are available:

Type	Internal Value	Dashboard Render	Typical Use
Textbox	`textbox`	Free text input	Code, ID, label (`LINE-1`)
Datepicker	`datepicker`	Date/time picker + quick presets	Time range (`start_date`, `end_date`)
Dropdown — From Query	`dropdown enter items into query`	List fed by another Compass record	Line / machine list (from DB)
Dropdown — Manual	`dropdown enter items manually`	Comma-separated static list	Shift codes (`A,B,C`)

4.1. Textbox

Simplest type. The user types freely on the dashboard.

4.2. Datepicker

For date/time values. Default Value supports two modes:

A) Pick a moment from the calendar — Choose from calendar opens a calendar; the absolute timestamp is saved.

B) Relative preset — computed at execution time:

Option	Meaning
`Now`	Current time
`5 / 15 / 30 Minute Ago`	Minutes ago
`1 / 6 / 12 Hour Ago`	Hours ago
`Yesterday`	Yesterday at 00:00
`1 Week Ago` / `1 / 3 / 6 Month Ago`	Calendar offsets
`1 Year Ago` / `2 Year Ago`	Year offsets

Typical date range pattern

Define two parameters for a trend chart: - start_date → default: 1 Week Ago - end_date → default: Now

WHERE ts >= {{start_date}}::timestamp
  AND ts <= {{end_date}}::timestamp

Options come from another Compass query's result:

Field	Description
Select a Query	Pick a previously saved listing query
Default Value	Initial selection (one of the rows returned)

Example feeder query (hatlar_listesi):

SELECT hat_id AS value, ad AS label
FROM   hatlar
ORDER  BY ad;

The first column is the actual value sent to the parameter; the second is the label shown to the user.

Options entered as comma-separated static text:

Field	Example
Items	`A,B,C` or `Line-1,Line-2,Line-3`
Default Value	One of the items

5. Global Variables vs Local Parameters

Type	Look	Lifecycle
Local parameter	Light background, Set Parameter button	Scoped to this Compass record
Global Variable	Dark background, blue border, lock icon 🔒, View Settings button	Shared across multiple records

Global parameters appear read-only in this panel ("Managed by Global Variable Settings"). Edit them via Settings → Global Variables.

When to make a parameter global

plant_id used in many queries → make it global, change once
A query-specific filter (device_serial) → keep it local

6. Resolution at Runtime (Cartography → Dashboard)

When a Compass record is used in a Cartography widget, parameter values are resolved in this order (high → low priority):

Dashboard runtime filter — what the user picks via dropdown / datepicker
Widget tag context — Cartography widget's tag filter
Compass record's Default Value — set in the save panel
Empty — fallback is empty string ("")

Empty parameter call

If no source provides a value, the parameter is sent as empty string: - PostgreSQL: WHERE line_id = '' → likely 0 rows - Numeric column comparison: WHERE id = '' → may raise a type error

Always set a Default Value or guard with COALESCE / ISNULL in the query.

7. Comprehensive Examples

7.1. PostgreSQL — Parametric Time Series

SELECT
    ts,
    sicaklik,
    basinc,
    makine_id
FROM   sensor_zaman_serisi
WHERE  ts      >= {{start_date}}::timestamp
  AND  ts      <= {{end_date}}::timestamp
  AND  hat_id   = {{hat_id}}
ORDER  BY ts;

Parameter	Type	Default
`start_date`	Datepicker	`1 Week Ago`
`end_date`	Datepicker	`Now`
`hat_id`	Dropdown (from query: `hatlar_listesi`)	`HAT-1`

7.2. MSSQL — Shift-Based Filter

SELECT
    vardiya,
    SUM(gerceklesen) AS toplam_uretim,
    SUM(hedef)       AS toplam_hedef
FROM   demo_fabrika.vardiya_uretim WITH (NOLOCK)
WHERE  tarih      >= {{start_date}}
  AND  tarih      <= {{end_date}}
  AND  vardiya     = {{vardiya}}
GROUP  BY vardiya;

Parameter	Type	Default
`start_date`	Datepicker	`1 Day Ago`
`end_date`	Datepicker	`Now`
`vardiya`	Dropdown (manual: `A,B,C`)	`A`

7.3. MySQL — Dynamic LIMIT

SELECT *
FROM   demo_vardiya_uretim
ORDER  BY tarih DESC
LIMIT {{row_count}};

Parameter	Type	Default
`row_count`	Textbox	`100`

7.4. REST API — Parameterized Query String

Endpoint Path:     /api/sicaklik/trend
HTTP Method:       GET
Query Parameters:
  Key: hat         Value: {{hat_id}}
  Key: hours       Value: 24

Parameter	Type	Default
`hat_id`	Dropdown (from query: `hatlar_listesi`)	`HAT-1`

8. Common Errors

Symptom	Likely Cause	Fix
Query returns 0 rows	`'{{param}}'` wrapped in quotes	Remove quotes: `= {{param}}`
`column "..." does not exist`	Typo in parameter location	Use editor's autocomplete to verify column names
`invalid input syntax for type integer: ""`	Default Value blank, no runtime value	Set a Default Value in Parameter Settings
`Operand type clash` (MSSQL)	Parameter is string, column is int	Explicit cast: `CAST({{id}} AS INT)`
Parameter not listed in Parameters panel	Whitespace inside braces (`{{ line_id }}`)	Remove spaces: `{{line_id}}`
Same name appears as two cards	Case difference (`{{Line_Id}}` vs `{{line_id}}`)	Normalize all occurrences to one casing
Datepicker `Now` selected but old data returned	Cache (default 300 s) not yet expired	Wait or lower the cache TTL
Dropdown (from query) is empty	Feeder query returns no rows / was deleted	Test the feeder query manually
REST body parse error around `{{param}}`	Missing JSON quotes	Use `"field": "{{param}}"`

9. Best Practices

Practice	Why
Use `snake_case` parameter names (`line_id`, `start_date`)	Safe across all dialects
Enter a test value in the Parameters panel and click Preview	Validate syntax and data separately
Set datepicker defaults to relative values (`Now`, `1 Week Ago`)	Dashboard always opens with a meaningful range
Promote frequently shared parameters to Global Variables	One change updates every dependent record
In PostgreSQL, cast date parameters with `::timestamp`	Driver sends strings; comparison needs a cast
Don't over-parameterize	More than 4–5 dashboard filters becomes a UX burden

10. Quick Reference

Syntax:              {{parameter_name}}
Allowed chars:       A-Z, a-z, 0-9, _
Quotes:              NEVER (SQL); REQUIRED (REST JSON body)
PostgreSQL → $1, $2, ... (same name → same index)
MySQL      → ?  (each occurrence → new ?)
MSSQL      → @name (auto int detection)
REST       → literal string substitution
MQTT/Excel → not supported

Next Step

After defining parameters, the Compass record is converted into a chart / KPI widget in Cartography and executed by the dashboard.

→ Cartography → Create PostgreSQL Query → Create MSSQL Query → Create MySQL Query → Define REST Endpoint