Queries are the heart of every TREVL component — they define what data to fetch and from where. Most HRM components use a dual-context pattern with two parallel queries: one for the target group and one for comparison.

📋 Query Structure

Each component defines one or more queries. Each query fetches data from a Cube model with specific dimensions, measures, and filters.

queries:
- context: target_group
  dimensions:
  - hrmOptionDistributionAcademics.optionText
  - hrmOptionDistributionAcademics.periodFilter
  measures:
  - hrmOptionDistributionAcademics.weightedShare
  filters:
  - member: hrmOptionDistributionAcademics.questionKey
    operator: equals
    values:
    - Q-193
  computed:
  - name: name
    code: '"Zielgruppe"'

🔀 Query Contexts

Most HRM components use a dual-context pattern with two parallel queries:

Context Purpose Filter Parameters
target_group Primary data (the group being analyzed) $param_*_zielgruppe
compare_group Comparison baseline $param_*_vergleichsgruppe

Both queries share the same structure (dimensions, measures, question key) but use different filter parameters so users can compare two demographic segments.

queries:
- context: target_group
  filters:
  - member: cube.geschlechtFilter
    operator: equals
    parameter: "$param_geschlecht_zielgruppe"
  computed:
  - name: name
    code: '"Zielgruppe"'
  - name: pointPaddingInfo
    code: '0.1'
  - name: zIndexInfo
    code: '2'

- context: compare_group
  filters:
  - member: cube.geschlechtFilter
    operator: equals
    parameter: "$param_geschlecht_vergleichsgruppe"
  computed:
  - name: name
    code: '"Vergleichsgruppe"'
  - name: pointPaddingInfo
    code: '-0.2'
  - name: zIndexInfo
    code: '1'

The pointPaddingInfo and zIndexInfo computed fields control how the two series are visually layered — the target group bar sits in front (zIndex: 2) and the compare group behind (zIndex: 1).

📐 Dimensions

Dimensions are the categorical axes of the data. Common dimensions:

Dimension Description
cube.optionText Answer option label (x-axis category)
cube.questionText Full question text (used in titles)
cube.title Short title
cube.periodFilter Survey period (e.g., “Jan 25”)
cube.periodCompare Comparison period (e.g., “Jul 24”)
cube.scoreCompText Score comparison label
cube.groupText Group label for matrix questions
cube.groupId Group identifier for matrix questions

📏 Measures

Measures are the numeric values. Common measures:

Measure Description
cube.weightedShare Weighted percentage share
cube.weightedShareDelta Delta vs. comparison period (numeric)
cube.weightedShareDeltaLabel Formatted delta label (e.g., “▲ 3,2 %”)
cube.weightedShareOfQuestion Score: weighted share for the full question
cube.weightedShareOfQuestionDelta Score delta
cube.count Raw count

🔌 Data Sources (v3.0)

The Trevl::Renderer supports pluggable data sources:

Cube (Default)

# Implicit — queries go to CubeJS
queries:
- dimensions: [cube.field]
  measures: [cube.measure]

TIE API

TIE components replace queries with api: tie and api-parameters. Data is referenced with $endpoint.data.field syntax.

id: salary-chart
type: chart
api: tie
api-parameters:
  profession:
    id: "43104"
    taxonomy: kldb
  location:
    country: DE
  time:
    start_month_offset: -12
    end_month_offset: 0
highchartsData:
  series:
  - data:
      y: "$salary.data.q50"

Resource-qualified references for non-default resources (e.g., surveys):

api: tie
api-parameters:
  survey_id: "hrm"
  question_key: "Q-1"
tableData:
  columns:
  - value: "$surveys.option-distribution.data.share"
    identifier: share

See TIE API for the full endpoint reference, parameter details, and examples.

Custom Data Sources

Register new sources via the Trevl::DataSource registry:

Trevl::DataSource.register("my_api", Trevl::DataSource::MyApi)

Then reference in TREVL: api: my_api