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.
A query object by itself is only the baseline. Actual runtime behavior is often shaped by additional parameter state such as:
Understanding query parameters is essential if you want to understand:
Think of query parameters as three layers:
This matters because the platform does not treat every parameter equally.
Jetstack uses predictable parameter families and prefixes.
| Prefix family | Meaning |
|---|---|
vs_* |
compact share-state parameter |
vc_* |
visible columns |
vch_* |
hidden columns |
vsort_* |
sorting |
vcals_*, vcal_* |
calculations |
vtags_*, vtagsmode_*, vtagsdesc_* |
tag filtering |
fids_*, f_*, fors_*, fnest_* |
filters, filter forms, OR chains, nested filter paths |
g_* |
groupings |
m_* |
mergings |
fld_* |
current folder |
p_* |
page |
ipp_* |
items per page |
vlimit_*, voffset_* |
explicit limit and offset |
rd_* |
render direction |
pfix_* |
fixed-parameter metadata |
The * part is usually the view or component identifier. For a query stored directly on the query object, that identifier may be empty.
Filters are the richest part of the parameter model.
Each filter instance is represented by:
fids_*f_<component>_<filterId>_...fnest_*fors_*This means a filter is not just "property + value". It is a full typed filter definition.
The query parameter model distinguishes:
vc_*vch_*Visible and hidden columns are stored separately because the platform needs to support:
Sorting is stored in vsort_* as a map of:
ASC or DESCAt runtime, the parser turns each sorting entry into:
These are related but distinct:
g_* = grouping statem_* = merging stateThe parser resolves each referenced property into a GroupingDefinition or MergingDefinition.
Use this distinction as the platform does:
Calculations are stored with:
vcals_*vcal_*Each calculation ID encodes:
The runtime turns this into a typed CalculationDefinition using the registered supported calculations.
Tag-related parameter state uses:
vtags_* for selected tag IDsvtagsmode_* for tag matching modevtagsdesc_* for whether descendant tags should be includedThe model supports:
any versus all matchingThe remaining families are comparatively direct:
fld_* for current folderp_* for current pageipp_* for items per pagevlimit_* for explicit limitvoffset_* for explicit offsetrd_* for render direction, normalized to rows or colsEach filter ID contains:
That lets the runtime:
Nested filters are stored through fnest_*.
This tells the runtime to traverse related properties before applying the final filter condition.
Use nested filters when:
Avoid them when:
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.
The runtime decides which filter parameters belong to a filter by checking whether:
subquery_reference_propThis matters because the query-parameter system is typed. It does not treat all filter payload keys as equally meaningful.
Read Filter Operators.
This is one of the most important concepts in the query runtime.
A fixed parameter is a query parameter that is also marked as locked through pfix_* metadata.
Examples:
pfix_<component>_filterspfix_<component>_columnspfix_<component>_sortingpfix_<component>_groupingspfix_<component>_tagspfix_<component>_pageThe parameter still exists in the normal family, but the pfix_* metadata says:
Regular parameter behavior:
Examples:
Fixed parameter behavior:
fixedParameters objectExamples:
When QueryParameters::from(...) parses input, it supplements the main parameter state with a fixedParameters map containing entries for:
filterscolumnshideColumnssortinggroupingsmergingscalculationstagstagsModeincludeTagDescendantsfolderpageitemsPerPagelimitoffsetrenderDirectionSome fixed entries are arrays of specific locked item IDs, such as:
Others are booleans indicating that the scalar value itself is fixed, such as:
In the data-display runtime:
viewQueryParametersuserQueryParametersfixedParametersThis ordering is important because it gives fixed parameters priority.
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.
QueryParameters::export(...) can export:
includeFixed = falseThis is important in two directions:
The export logic deliberately removes fixed items when includeFixed = false.
Jetstack also supports compact share-state encoding for query/view state.
The share-state model captures differences from a baseline and may include:
This is how current view state can become part of:
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.
Ask these when designing a query/view experience:
Use regular parameters for:
This gives users a strong starting point without locking them in.
Use fixed parameters for:
This is appropriate when the dashboard must always stay within a specific business scope.
Use query parameters to capture:
This is the basis of User template queries created from view/filter UIs.
When a query plays a security or policy role, use fixed parameters for any state that should not be overridden downstream.