Skip to content

Predefined Query

A Predefined Query is a saved data query. It names one or more dataflows, a set of component filters (selections) and/or series keys, and REST query parameters. The document starts with ref: "PreDefinedQuery=AGENCY:ID(1.0)".

The writer is PreDefinedQueryCanonicalWriter.

Simple form

format: "fusion-yaml(1.0.0)"
ref: "PreDefinedQuery=TEST:PDQ_ONEFILTER(1.0)"
name: "PDQ_ONEFILTER"
dataflow: "ACY:DF_TEST0(1.0)"
selections:
- component: "FREQ"
  EQUALS: "Q"
Source: predefinedquery/testOneFilterFREQ.yaml

The document starts with the common header. Then come these body fields:

  • dataflow: the short URN of the dataflow being queried. It follows the value-or-array rule.
  • selections: an array of component filters. Each one has a component id, followed by one field per match function. The field holds the values to match, as a value or array.

Complete example

format: "fusion-yaml(1.0.0)"
ref: "PreDefinedQuery=TEST:PDQ_OPERATORS(1.0)"
name: "PDQ_OPERATORS"
virtualFlow: true
dataflow:
- "ACY:DF_TEST0(1.0)"
- "ACY:DF_TEST1(1.0)"
selections:
- component: "TIME_PERIOD"
  GREATER_THAN_EQUAL: "2008"
- component: "TIME_PERIOD"
  LESS_THAN_EQUAL: "2012"
- component: "INDICATOR"
  EQUALS:
  - "XYZ1"
  - "XYZ2"
  CONTAINS: "ABC"
series:
- "A.FR+DE..IND2"
- "A.UK..IND1"
parameters:
  detail: "noData"
  lastN: "10"
  max: "5"
Combined from predefinedquery/testVirtual.yaml, testMultipleDataflows.yaml, testOperators.yaml, testSeriesFilters.yaml and testParameters.yaml.

  • virtualFlow: true is written only when the query defines a virtual dataflow (booleans).
  • dataflow becomes an array when there are several dataflows. The entries are sorted by URN.
  • Selections are written in the order they are defined. The same component can appear in more than one selection. Within a selection, match functions are written in the order of the MATCH_FUNCTION enumeration (EQUALS, NOT_EQUALS, LESS_THAN, LESS_THAN_EQUAL, GREATER_THAN, GREATER_THAN_EQUAL, CONTAINS, NOT_CONTAINS, STARTS_WITH, ENDS_WITH, AND), which is not alphabetical. The values of each match function are sorted.
  • series holds series keys in REST key syntax (. between dimensions, + between alternatives, empty for a wildcard). It is sorted and follows the value-or-array rule.
  • parameters is a map of REST query parameter name to value, sorted by name. Values are always strings.

Field reference

Field Value Written when
virtualFlow true the query defines a virtual dataflow
dataflow dataflow short URN(s), sorted, value or array the query references dataflows
selections array of selection objects the query has selections
series series key(s), sorted, value or array the query has series keys
parameters map of parameter name to string value, sorted by name the query has parameters

Selection object (selections[]):

Field Value Written when
component component id always
match function (EQUALS, CONTAINS, …) value(s), sorted, value or array for each match function with values, in enumeration order

Reading notes

  • Every field in a selection other than component must be a MATCH_FUNCTION name. An unknown name is an error.
  • The reader accepts match function values and series either as a single value or as an array.