Query Parameters

What It Is

Query parameters are Jetstack's runtime state model for configured queries and data-display views. They describe not just what a query is in principle, but how that query is being used right now in a specific view, link, or user interaction state.

Why It Matters

A query object by itself is only the baseline. Actual runtime behavior is often shaped by additional parameter state such as:

• filters
• visible and hidden columns
• sorting
• groupings and mergings
• calculations
• tags
• folder context
• page and items per page
• explicit limits and offsets
• render direction
• fixed-parameter metadata

Understanding query parameters is essential if you want to understand:

• why a view shows a specific object set
• why a user can or cannot change a query setting
• how shareable filtered links work
• how query defaults differ from locked constraints

Mental Model

Think of query parameters as three layers:

1. baseline query parameter state stored on the query
2. runtime view or user parameter state
3. fixed parameter metadata that marks part of the state as locked

This matters because the platform does not treat every parameter equally.

• some parameters are just defaults
• some are user-supplied runtime refinements
• some are fixed and therefore applied with priority and hidden from normal overriding flows

Parameter Families

Jetstack uses predictable parameter families and prefixes.

The * part is usually the view or component identifier. For a query stored directly on the query object, that identifier may be empty.

Main Query Parameter Areas

Filters

Filters are the richest part of the parameter model.

Each filter instance is represented by:

• a filter ID in fids_*
• a property ID encoded in that filter ID
• a filter form prefix f_<component>_<filterId>_...
• the filter type
• filter-type-specific arguments
• optional nested property path via fnest_*
• optional OR-linked companion filters via fors_*

This means a filter is not just "property + value". It is a full typed filter definition.

Columns

The query parameter model distinguishes:

• visible columns: vc_*
• hidden columns: vch_*

Visible and hidden columns are stored separately because the platform needs to support:

• explicit column whitelisting
• explicit hiding of known columns
• merging fixed column behavior with user-visible column behavior

Sorting

Sorting is stored in vsort_* as a map of:

• property or column identifier
• direction ASC or DESC

At runtime, the parser turns each sorting entry into:

• display title
• internal column identifier
• normalized sort direction

Groupings And Mergings

These are related but distinct:

• g_* = grouping state
• m_* = merging state

The parser resolves each referenced property into a GroupingDefinition or MergingDefinition.

Use this distinction as the platform does:

• grouping is presentation-aware segmentation of results
• merging is closer to grouped-result aggregation behavior

Calculations

Calculations are stored with:

• a list of active calculation IDs in vcals_*
• the calculation code for each specific calculation ID in vcal_*

Each calculation ID encodes:

• the source property
• a running index

The runtime turns this into a typed CalculationDefinition using the registered supported calculations.

Tags

Tag-related parameter state uses:

• vtags_* for selected tag IDs
• vtagsmode_* for tag matching mode
• vtagsdesc_* for whether descendant tags should be included

The model supports:

• tag IDs
• any versus all matching
• descendant inclusion on or off

Folder, Pagination, Limits, And Direction

The remaining families are comparatively direct:

• fld_* for current folder
• p_* for current page
• ipp_* for items per page
• vlimit_* for explicit limit
• voffset_* for explicit offset
• rd_* for render direction, normalized to rows or cols

Filter Definitions In Detail

Filter IDs

Each filter ID contains:

• the property identifier
• a numeric index suffix

That lets the runtime:

• recognize repeated filters on the same property
• keep separate OR-linked branches
• maintain "next available filter index" bookkeeping

Nested Filters

Nested filters are stored through fnest_*.

This tells the runtime to traverse related properties before applying the final filter condition.

Use nested filters when:

• the business rule really depends on a related object path
• the path is explainable to implementers and users

Avoid them when:

• the same logic would be clearer as a dedicated query
• the relation path becomes too deep or fragile

OR Filters

OR-linked filters are stored with fors_*.

This allows one filter branch to carry multiple alternative conditions without flattening everything into a single opaque structure.

Filter-Type-Specific Parameters

The runtime decides which filter parameters belong to a filter by checking whether:

• the parameter name starts with the filter type
• or, for subquery filters, whether it is the special subquery_reference_prop

This matters because the query-parameter system is typed. It does not treat all filter payload keys as equally meaningful.

Read Filter Operators.

Fixed Query Parameters

This is one of the most important concepts in the query runtime.

What "Fixed" Means

A fixed parameter is a query parameter that is also marked as locked through pfix_* metadata.

Examples:

• pfix_<component>_filters
• pfix_<component>_columns
• pfix_<component>_sorting
• pfix_<component>_groupings
• pfix_<component>_tags
• pfix_<component>_page

The parameter still exists in the normal family, but the pfix_* metadata says:

• this part of the state is not just present
• it is intended to stay fixed when the view is used

Regular Parameters Versus Fixed Parameters

Regular parameter

Regular parameter behavior:

• contributes baseline query state
• may be overridden or refined by user runtime state
• behaves like a default

Examples:

• default sorting
• default visible columns
• default starting filters

Fixed parameter

Fixed parameter behavior:

• contributes baseline query state
• is extracted into a dedicated fixedParameters object
• is applied before non-fixed parameters
• is hidden from the ordinary adjustable query-parameter object
• behaves like a locked rule rather than a mere default

Examples:

• a view must always filter to the current business scope
• a permission-like list must always keep a mandatory tag constraint
• a shared dashboard must always keep a required grouping

How The Platform Reads Fixed Parameters

When QueryParameters::from(...) parses input, it supplements the main parameter state with a fixedParameters map containing entries for:

• filters
• columns
• hideColumns
• sorting
• groupings
• mergings
• calculations
• tags
• tagsMode
• includeTagDescendants
• folder
• page
• itemsPerPage
• limit
• offset
• renderDirection

Some fixed entries are arrays of specific locked item IDs, such as:

• fixed filter IDs
• fixed column IDs
• fixed grouping IDs

Others are booleans indicating that the scalar value itself is fixed, such as:

• page
• items per page
• folder
• limit
• offset

How Fixed Parameters Are Applied

In the data-display runtime:

1. query-defined parameters are parsed into viewQueryParameters
2. user/runtime parameters are parsed into userQueryParameters
3. fixed entries are extracted into fixedParameters
4. fixed parameters are applied first
5. the remaining query and user parameters are consolidated and applied afterward

This ordering is important because it gives fixed parameters priority.

What Users See

Because fixed parameters are moved into a separate object, the ordinary adjustable query-parameter state focuses on the non-fixed part of the view state.

That is why a fixed filter is not just "already selected." It is selected and also treated as locked.

How Parameters Are Exported

QueryParameters::export(...) can export:

• the full parameter set, including fixed metadata
• or a non-fixed-only parameter set by calling it with includeFixed = false

This is important in two directions:

• when you want to persist the full query state
• when you want to generate user-adjustable state without re-emitting locked parts

The export logic deliberately removes fixed items when includeFixed = false.

Share State

Jetstack also supports compact share-state encoding for query/view state.

The share-state model captures differences from a baseline and may include:

• filters
• columns
• hidden columns
• sorting
• groupings
• mergings
• calculations
• tags
• folder
• page
• items per page
• limit
• offset
• render direction

This is how current view state can become part of:

• links
• persisted user templates
• collaboration flows

Important Distinction

Share state is about portable current state.

Fixed parameters are about non-overridable baseline state.

Those are related, but they are not the same thing.

Typical Parameter Design Questions

Ask these when designing a query/view experience:

1. Which parts of the query should be a baseline default?
2. Which parts should users be able to change?
3. Which parts must remain locked?
4. Should the current state be shareable as a link or saved template?
5. Would a nested filter be clearer as a separate query?

Common Patterns

Default But Adjustable List

Use regular parameters for:

• columns
• sorting
• initial filters

This gives users a strong starting point without locking them in.

Locked Scope Dashboard

Use fixed parameters for:

• mandatory filters
• required tags
• fixed grouping

This is appropriate when the dashboard must always stay within a specific business scope.

Saved User Template

Use query parameters to capture:

• current filters
• visible columns
• sorting
• pagination reset if needed

This is the basis of User template queries created from view/filter UIs.

Permission-Like Query State

When a query plays a security or policy role, use fixed parameters for any state that should not be overridden downstream.

Best Practices

• Keep durable business logic in the query definition, not in ad hoc view state.
• Use regular parameters for defaults users may refine.
• Use fixed parameters only when the state must be enforced.
• Keep nested and OR filter logic explainable in one sentence.
• Prefer clear saved query templates over overly clever share-state links when a state should be reused long term.
• When debugging view behavior, inspect fixed parameters first; they often explain why a visible state cannot be changed.

Related Chapters

• Queries
• Views
• Filter Operators