Skip to content

Compass

Compass is the module in Pirivision where Compass records (queries, MQTT topics, REST endpoints, Excel sheets) connected to data sources are created and managed.

A data source added in Port (PostgreSQL, MSSQL, MySQL, MQTT, REST API, or Excel) is turned into a meaningful data definition through Compass. The saved Compass records are then converted into chart / KPI widgets in the Cartography module.

flowchart LR
    A[Port<br/>Data Source] --> B[Compass<br/>Record]
    B --> C[Cartography<br/>Chart / KPI]
    C --> D[Horizon<br/>Page / Board]
    D --> E[Atlas<br/>Dashboard]

Terminology

Different data sources in Pirivision produce different types of Compass records:

  • SQL (PostgreSQL / MSSQL / MySQL) → Query (the SQL code written)
  • MQTT → Topic Selection (the path of the topic in the broker)
  • REST API → Endpoint Definition (HTTP path + method + parameters)
  • Excel → Sheet Selection (the worksheet in the uploaded file)

All of them appear in the same list and are fed into Cartography in the same way; only the definition style differs.

Compass Record Types

Type Data Source Definition Style Save Action
SQL PostgreSQL, MSSQL, MySQL Standard SQL / T-SQL code Save
MQTT MQTT Broker Topic path selection (fabrika/hat1/sicaklik) Save
REST API REST API HTTP method + path + parameters Save
Excel Excel Offline Sheet selection + preview Save

What You Can Do in Compass

Action Data Source Description
Write SQL Query PostgreSQL, MSSQL, MySQL Filter and transform data with SELECT, JOIN, WHERE, GROUP BY
MQTT Topic Selection MQTT Topic registration and monitoring for real-time sensor data
Define REST Endpoint REST API Define HTTP GET/POST endpoints
Excel Sheet Selection Excel Offline Define a specific sheet of an uploaded file as a Compass record
Global Variables / Parameters SQL · REST Use {{param}} syntax — Textbox, Datepicker, Dropdown types
Test All Preview the returned data before saving
Folder Organization All Group Compass records into folders

Compass Creation Guides

Type Create Edit
SQL Create PostgreSQL Query · Create MSSQL Query · Create MySQL Query Edit PostgreSQL Query · Edit MSSQL Query · Edit MySQL Query
MQTT MQTT Topic Selection Edit MQTT Topic
REST API Define REST Endpoint Edit REST Endpoint
Excel Excel Sheet Selection Edit Excel Sheet

Parameters (Common to All Types)

SQL queries, REST endpoints and query parameter / header fields all support dynamic values via the {{parameter_name}} placeholder. For full coverage of syntax, parameter types (Textbox / Datepicker / Dropdown), default values, and dialect-specific behavior (PostgreSQL $1, MySQL ?, MSSQL @name):

→ Compass Parameters — Detailed Guide

Difference from Global Variables

Compass Parameters ({{param}}) are values entered by the user at query runtime (date range, dropdown selection, etc.). Global Variables (${variable}) are user-defined constants pre-set in Settings; they are substituted automatically in every query.

→ Features — Global Variables

AI-Assisted SQL Writing

For SQL-type Compass records (PostgreSQL, MSSQL, MySQL), the Write with AI button on the query editor opens the Makinist assistant. Write your request in natural language and get executable SQL back — transfer it to the editor with one click.

→ Makinist — SQL Assistant

Compass Management

Action Description
Move Move a Compass record or folder to a different location
Duplicate Copy an existing record with the same settings
Delete Remove an unused record

At least one data source must have been added in the Port module before using Compass.

→ Port — Add Data Source

Next Step

After creating a record in Compass, create a chart / KPI in the Cartography module.

→ Cartography