Filters file

The schema-companion to the Filters & display groups task guide. That guide covers the filter-vs-display distinction, nesting, and the header-matching that decides whether data appears; this page is the generated field list.

At a glance

Purpose : Builds the browsable tree in the FEWS Explorer — what data a user can reach and how it’s grouped (hop ⑤).

Folder : Config/RegionConfigFiles/

Root element : <filters> (version="1.1", required)

Depends on : The locations, parameters, and stored series its timeSeriesSet queries refer to.

Minimal example

Config/RegionConfigFiles/Filters 1.00 default.xml

<?xml version="1.0" encoding="UTF-8"?>
<filters xmlns="http://www.wldelft.nl/fews" version="1.1">
  <defaultFilterId>Discharge</defaultFilterId>
  <filter id="Discharge" name="Discharge observations">
    <timeSeriesSet>
      <moduleInstanceId>ImportObservations</moduleInstanceId>
      <valueType>scalar</valueType>
      <parameterId>Q.obs</parameterId>
      <locationSetId>AllDischargeGauges</locationSetId>
      <timeSeriesType>external historical</timeSeriesType>
      <timeStep unit="hour" multiplier="1"/>
      <readWriteMode>read only</readWriteMode>
    </timeSeriesSet>
  </filter>
</filters>

Caution

A <filter> is either a leaf (carries timeSeriesSet queries) or a branch (carries <child foreignKey="…"> references) — a schema <choice>, not both. And a leaf’s timeSeriesSet must match the stored header exactly, or the node is silently empty. See the task guide.

Field reference

Auto-generated from filters.xsd. Descriptions are the schema's own annotations.

Element <filters>

Attributes

Attribute	Use	Notes
version	required	fixed: 1.1.

Elements

Element	Type	Cardinality	Description
description	string	optional
defaultFilterId	idStringType	optional
timeSeriesSets	FilterTimeSeriesSetsComplexType	optional · repeats	Time series sets that can be referenced by the filters with the id
filter	FilterComplexType	required · repeats

FilterTimeSeriesSetsComplexType

Attributes

Attribute	Use	Notes
id	optional	Id of the time series set collection.

Elements

Element	Type	Cardinality	Description
timeSeriesSet	TimeSeriesSetComplexType	required · repeats

FilterComplexType

Attributes

Attribute	Use	Notes
id	required
name	optional

Elements

Element	Type	Cardinality	Description
description	string	optional
lastValueVisible	boolean	optional	Since 2013.01, FEWS-8568. When this filter is selected the last value is visible in the location label on the map
ignoreDeletionsOutsideViewPeriod	boolean	optional	Since 2021.02, A light red cross is displayed when there is data available outside the view period. By default for performance reasons a red cross is still displayed when values once exist but are now deleted. When this option is set to false the complete available time series are read to take the deletions outside the view period into account
thresholdIconsBasedOnLastNonMissingValue	boolean	optional	Since 2019.01, Only use the last not missing value for calculating the threshold
mapExtentId	string	optional
viewPermission	string	optional	set a permission to control who can view this filter
tableViewPermission	string	optional	set a permission to control who can view the time series in this filter in a table view
editPermission	string	optional	Set a permission to control who can edit timeseries enumerated in this filter (only editable timeseries can be editted)
additionalTimeSeries	AdditionalFilterTimeSeriesComplexType	optional · repeats	Since 2017.01 Additional time series that are invisible by default and can be made visible via time series visibility dialog
ignoreDoubtfulAndUnreliableFlagSourceColumnId	idStringType	optional	Hide validation icons when this flag source column is filled. Can be used to show all data that still needs to be validated
validationIconsViewPeriod	RelativePeriodComplexType	required	Since 2017.01. Calculate validation icons in the specified period. By this you can for example ignore the validation problems for the most recent data. The validation icons are only visible when ALL the selected filters, including there children, have the validation period or validation icons visible configured.
validationIconsVisible	boolean	required	Show all the validation icons in the period of the time series sets. The validation icons are only visible when ALL the selected filters, including there children, have the validation period or validation icons visible configured.
child	ChildComplexType	required · repeats
timeSeriesSet	TimeSeriesSetComplexType	required · repeats
groupBy	GroupByComplexType	optional	Since 2016.01. Automatically build up filters according to their attributes
locationConstraints	ConstraintsComplexType	optional	Since 2014.02. Restriction for the locations in the specified time series sets. When no time series sets are specified all the region locations that match the constraints are included
parameterConstraints	ConstraintsComplexType	optional	Since 2014.02. Restriction for the parameters in the specified time series sets. When no time series sets are specified all the region locations that match the constraints are included
qualifierConstraints	ConstraintsComplexType	optional	Since 2014.02. Restriction for the qualifiers in the specified time series sets. When no time series sets are specified all the region qualifiers that match the constraints are included
groupBy	GroupByComplexType	optional	Since 2016.01. Automatically build up filters according to their attributes
timeSeriesSetsId	idStringType	required · repeats	Reference to a time series set collection defined at the start of this file.
timeSeries	TimeSeriesFilterComplexType	optional · repeats	Since 2015.02. Instead of time series sets. All time series in the database that match the criteria are included. Similar to the time series used in the modifierTypes.xml
relativeViewPeriod	RelativePeriodComplexType	required	Since 2014.02. Instead of time series sets. All parameter, location and qualifier constraints are included in the filter. The view period is used for the icon in the explorer
editable	boolean	optional	Since 2016.01. Used when not using time series sets. In this case it is not possible to configure the readWriteMode of the time series set. When true the time series are editable in the time series dialog.
locationRelationId	idStringType	optional · repeats	Since 2015.01. All the related locations when available are added to the time series dialog. The related location are not added to the map and location tree. The warning level and data availability of the related location is merged with the original location
visibilityControllingFlagSourceColumnId	idStringType	optional	Since 2016.01 #66732. Used when not using time series sets. In this case it is not possible to configure the visibilityControllingFlagSourceColumnId of the time series set. All values that not passed this validation step are removed on read. Set to missing for equidistant and removed for non-equidistant
onlyReliableFlagSourceColumnId	idStringType	optional	Since 2022.02. All values that passed this validation step and are reliable will be included other will be set to missing for equidistant and removed for non-equidistant. This will work as an "or" operation together with "visibilityControllingFlagSourceColumnId", so data should either have passed "visibilityControllingFlagSourceColumnId" or "onlyReliableFlagSourceColumnId".

TimeSeriesSetComplexType

Attributes

Attribute	Use	Notes
id	optional
name	optional

Elements

Element	Type	Cardinality	Description
description	string	optional
valueType	timeSeriesValueTypeStringType	required
parameterId	idStringType	required
domainParameterId	idStringType	optional · repeats	For a spectrum specify the frequency / wave length parameter. For a directional spectrum specify first the frequency parameter and secondly the directional parameter
qualifierId	idStringType	optional · repeats	Id that references an qualifier listed in the regionConfigFiles/Qualifiers.xsd
timeSeriesType	timeSeriesTypeStringType	required
timeStep	TimeStepComplexType	required
aggregationPeriod	RelativePeriodComplexType	optional	The value at a time represents the aggregated value over the aggregation period e.g when the aggregation period is -6 to 0 hour the value at 13:00 represents an aggregation (e.g. moving average) from 7:00 till 13:00 (including)
cycle	CalendarTimeSpanComplexType	optional	If cycle specified, then the data is repeated periodically with this cycle as the period length. There is original data for only one cycle. After that cycle the data will be repeated periodically. In other words, when cycle is defined, then a missing value is filled up with a value from the last available cycle before the missing value.
externalForecastSearchTimeStep	TimeStepComplexType	optional	Since 2024.01. Only time series with an external forecast time that match this time step are visible while searching
externalForecastTimeCardinalTimeStep	TimeStepComplexType	optional	When no external forecast exists in the data store younger that the specified age a new external forecast is returned with a minimum age that applies to the specified cardinal time step
qualifierAggregation	qualifierAggregationStringType	optional	When specified all the time series that have ALL the specified qualifiers are aggregated to a single time series on read. Can not be specified when this time series set is meant for writing
readWriteMode	timeSeriesReadWriteModeStringType	required	Note: this readWriteMode is only used in the TimeSeriesDisplay. Other modules ignore this readWriteMode.
synchLevel	intStringType	optional
expiryTime	CalendarTimeSpanComplexType	optional
delay	TimeShiftComplexType	optional
multiplier	floatStringType	optional
divider	floatStringType	optional
incrementer	floatStringType	optional
ensembleId	idStringType	optional	Optional field for running ensembles. Ensemble id's in a time series set will override ensemble id's defined in the workflow.
visibilityControllingFlagSourceColumnId	idStringType	optional	All values that not passed this validation step are removed on read. Set to missing for equidistant and removed for non-equidistant
onlyReliableFlagSourceColumnId	idStringType	optional	Since 2022.02. All values that passed this validation step and are reliable will be included other will be set to missing for equidistant and removed for non-equidistant. This will work as an "or" operation together with "visibilityControllingFlagSourceColumnId", so data should either have passed "visibilityControllingFlagSourceColumnId" or "onlyReliableFlagSourceColumnId".
locationRelationId	idStringType	required	Relation id to map the time series set locations to related locations. Instead of the time series set locations the related locations are used to read/write the time series.
skipLocationsWithoutRelation	boolean	optional	Since 2020.01 When true locations that do not have a related location will be skipped, when false all location must have a related location. Default is false
moduleInstanceId	idStringType	required · repeats
moduleInstanceSetId	idStringType	required	Query a single module instance in the data store that is available for this time series set
filterModuleInstanceSetId	idStringType	required	Query all module instances in the data store that are available for this time series set
locationId	idStringType	required · repeats
locationSetId	idStringType	required
chainageLocationSetId	idStringType	required	Id of location set which represents a chainage of locations. This can only be used in combination with readWriteMode readOnly
relativeViewPeriod	TimeSeriesSetRelativePeriodComplexType	optional	Period relative the time 0 of the workflow or the system time of the fews explorer
relativeForecastPeriod	TimeSeriesSetRelativePeriodComplexType	optional	Period relative to first time of a simulated or external forecast time series
ensembleMemberId	nonEmptyStringType	required · repeats	Optional field used for reading or writing one or more particular ensemble member
ensembleMemberIndex	nonNegativeIntegerStringType	required	Optional field used for reading or writing one particular ensemble member
ensembleMemberIndexRange	EnsembleMemberIndexRangeComplexType	required	Optional field used for reading or writing one particular sub set of the ensemble
relativeForecastSearchPeriod	TimeSeriesSetRelativePeriodComplexType	required	Since 2015.02. The latest available external forecast in this period will be read. By default the latest before time0 is returned
externalForecastTimeId	idStringType	required	Since 2018.01. Forecast time reference id configured in the forecast length estimator config. Can only be used in workflows and only after the forecast length estimator.
externalForecastMinAge	TimeSpanComplexType	optional	Since 2014.02. By default is there is no minimum age. All external forecasts after the time0 are ignored. The age of an external forecast is defined as the time span between the external forecast time and the time 0
externalForecastMaxAge	TimeSpanComplexType	optional	By default is there is no maximum age so the returned external forecast can be very old when there is no recent forecast available. All external forecasts after the time0 are ignored. The age of an external forecast is defined as the time span between the external forecast time and the time 0

AdditionalFilterTimeSeriesComplexType

Attributes

Attribute	Use	Notes
name	optional

Elements

Element	Type	Cardinality	Description
locationFunctionEquals	AdditionalTimeSeriesFunctionEquals	required
timeSeriesSet	TimeSeriesSetComplexType	required · repeats
timeSeriesSetsId	idStringType	required · repeats	Reference to a time series set collection defined at the start of this file.

RelativePeriodComplexType

Defines a moving period in time. The start and end time are relative time to a certain time.

Attributes

Attribute	Use	Notes
start	required
end	required
startOverrulable	optional	default: false. When the running module (e.g. general adaptor) has exported a state the state time is used instead of the specified start time. This option is only available during a (forecast) run.
endOverrulable	optional	default: false. When a forecast length is specified (e.g. in the manual forecast dialog) the time 0 + forecast length is used instead of the specified end time This option is only available during a (forecast) run.
unit	required

Elements

Element	Type	Cardinality	Description
description	string	optional

ChildComplexType

Attributes

Attribute	Use	Notes
foreignKey	required

GroupByComplexType

Create filters based on the different attribute values, can be nested over multiple different location, parameter and or qualifier attributes.

Element	Type	Cardinality	Description
locationAttributeId	idStringType	required	Specifies location attribute items should be grouped by
parameterAttributeId	idStringType	required	Specifies parameter attribute items should be grouped by
qualifierAttributeId	idStringType	required	Specifies qualifier attribute items should be grouped by

ConstraintsComplexType

Element	Type	Cardinality	Description
not	ConstraintComplexType	required
anyValid	ConstraintsComplexType	required
allValid	ConstraintsComplexType	required
idStartsWith	IdStartsWithComplexType	required	Only the locations/parameters/qualifiers with an id that starts with the specified text will be included in the location set, other locations in the shape file or location sets are ignored
idEndsWith	IdEndsWithComplexType	required	Only the locations/parameters/qualifiers with an id that ends with the specified text will be included in the location set, other locations in the shape file or location sets are ignored
idContains	IdContainsComplexType	required	Only the locations/parameters/qualifiers with an id that contains the specified text will be included
relatedLocationExists	RelatedLocationExistsComplexType	required	Only the locations where the related location for the specified location relation is not NULL (empty, only spaces or NaN) will be included.
attributeExists	AttributeExistsComplexType	required	Only the locations/parameters/qualifiers where the attribute value is not NULL (empty, only spaces or NaN) will be included
attributeTextStartsWith	AttributeTextStartsWithComplexType	required	Only the locations with attribute value start with the specified text will be included.
attributeTextEndsWith	AttributeTextEndsWithComplexType	required	Only the locations/parameters/qualifiers with attribute value start with the specified text will be included.
attributeTextContains	AttributeTextContainsComplexType	required	Only the locations/parameters/qualifiers with attribute value contains the specified text will be included.
attributeTextEquals	AttributeTextEqualsComplexType	required	Only the locations/parameters/qualifiers with attribute value equals the specified text will be included in the location set, other locations in the shape file or location sets are ignored
attributeTrue	AttributeTrueOrFalseComplexType	required	Only the locations/parameters/qualifiers with attribute value equals true will be included in the location set, other locations in the shape file or location sets are ignored.
attributeFalse	AttributeTrueOrFalseComplexType	required	Only the locations/parameters/qualifiers with attribute value equals false will be included in the location set, other locations in the shape file or location sets are ignored.

TimeStepComplexType

Time step, There are 5 valid combinations of attributes. id, unit+[multiplier]+[divider]+[timeZone], times+[timeZone] + monthDays+[timeZone] ([]=optional)

Attributes

Attribute	Use	Notes
id	optional	Id of the time step. You can reference time steps defined in the regionConfig/timeSteps.xml. Only specify the id attribute when referring to a predefined time step. In the regionConfig/timeSteps.xml the time steps list both the id and the attributes that define the time step
label	optional	Short name for the time step which is shown to the user when he can choose one from a list.
unit	optional
divider	optional
multiplier	optional
times	optional	Defines the time step by a list of times without dates, e.g. "10:00 23:00"
minutes	optional	Since 2017.02. Defines the time step by a list of minutes (with prefix 0 for single digits), e.g. "05 25" which results in times 0:05, 0:25, 1:05, etc.
daysOfMonth	optional	Defines the time step by a list of days of month, use "01 11 21" for a decade time step
monthDays	optional	Defines the time step by a list of dates, e.g. ""--03-01 --06-01 --09-01 --12-01" for the meteorological seasons
timeZone	optional

Elements

Element	Type	Cardinality	Description
description	string	optional	Optional description of this timeStep. This is not used and is only present for convenience.

CalendarTimeSpanComplexType

Attributes

Attribute	Use	Notes
unit	required
divider	optional
multiplier	optional

TimeShiftComplexType

Attributes

Attribute	Use	Notes
unit	required
divider	optional
multiplier	optional

TimeSeriesSetRelativePeriodComplexType

Defines a moving period in time. The start and end time are relative time to a certain time. When the start time is not specified it is determined by the start time of the state of the current run. When the start is overrulable the time is overruled by the start of search period or the start of cold state run when one of two is specified When the end is overrulable this time is overruled by the end of the forecast when specified

Attributes

Attribute	Use	Notes
unit	required
start	optional	e.g. -1 hour means one before time 0
end	required	e.g. 1 hour means one hour after time 0
startOverrulable	optional	default: false. When the running module (e.g. general adaptor) has exported a state the state time is used instead of the specified start time. This option is only available during a (forecast) run.
endOverrulable	optional	default: false. When a forecast length is specified (e.g. in the manual forecast dialog) the time 0 + forecast length is used instead of the specified end time This option is only available during a (forecast) run.

Elements

Element	Type	Cardinality	Description
description	string	optional

EnsembleMemberIndexRangeComplexType

Attributes

Attribute	Use	Notes
start	required
end	optional

TimeSpanComplexType

Attributes

Attribute	Use	Notes
unit	required
divider	optional
multiplier	optional

AdditionalTimeSeriesFunctionEquals

Attributes

Attribute	Use	Notes
selected	required
additional	required

ConstraintComplexType

Element	Type	Cardinality	Description
not	ConstraintComplexType	required
anyValid	ConstraintsComplexType	required
allValid	ConstraintsComplexType	required
idStartsWith	IdStartsWithComplexType	required	Only the locations/parameters/qualifiers with an id that starts with the specified text will be included in the location set, other locations in the shape file or location sets are ignored
idEndsWith	IdEndsWithComplexType	required	Only the locations/parameters/qualifiers with an id that ends with the specified text will be included in the location set, other locations in the shape file or location sets are ignored
idContains	IdContainsComplexType	required	Only the locations/parameters/qualifiers with an id that contains the specified text will be included
relatedLocationExists	RelatedLocationExistsComplexType	required	Only the locations where the related location for the specified location relation is not NULL (empty, only spaces or NaN) will be included.
attributeExists	AttributeExistsComplexType	required	Only the locations/parameters/qualifiers where the attribute value is not NULL (empty, only spaces or NaN) will be included
attributeTextStartsWith	AttributeTextStartsWithComplexType	required	Only the locations with attribute value start with the specified text will be included.
attributeTextEndsWith	AttributeTextEndsWithComplexType	required	Only the locations/parameters/qualifiers with attribute value start with the specified text will be included.
attributeTextContains	AttributeTextContainsComplexType	required	Only the locations/parameters/qualifiers with attribute value contains the specified text will be included.
attributeTextEquals	AttributeTextEqualsComplexType	required	Only the locations/parameters/qualifiers with attribute value equals the specified text will be included in the location set, other locations in the shape file or location sets are ignored
attributeTrue	AttributeTrueOrFalseComplexType	required	Only the locations/parameters/qualifiers with attribute value equals true will be included in the location set, other locations in the shape file or location sets are ignored.
attributeFalse	AttributeTrueOrFalseComplexType	required	Only the locations/parameters/qualifiers with attribute value equals false will be included in the location set, other locations in the shape file or location sets are ignored.

RelatedLocationExistsComplexType

Attributes

Attribute	Use	Notes
locationRelationId	required	Id of the location relation (eg. UPSTREAM)

AttributeExistsComplexType

Attributes

Attribute	Use	Notes
id	required	Id of the attribute

AttributeTextStartsWithComplexType

Attributes

Attribute	Use	Notes
id	required	Id of the attribute
prefix	required	The text the attribute value should start with

AttributeTextEndsWithComplexType

Attributes

Attribute	Use	Notes
id	required	Id of the attribute
postfix	required	The text the attribute value should end with

AttributeTextContainsComplexType

Attributes

Attribute	Use	Notes
id	required	Id of the attribute
contains	required	The text the attribute value should contain

AttributeTextEqualsComplexType

Attributes

Attribute	Use	Notes
id	required	Id of the attribute
equals	required	The text the attribute value should match
modifierDependent	optional	When true the location set can change dynamically when a attribute is changed by a modifier. Only allowed in workflows and in the modifiers display

AttributeTrueOrFalseComplexType

Attributes

Attribute	Use	Notes
id	required	Id of the attribute
modifierDependent	optional	When true the location set can change dynamically when a attribute is changed by a modifier. Only allowed in workflows and in the modifiers display

Gotchas

The task guide covers the important ones: header mismatch (imported-but-won’t-display), a mistyped foreignKey giving an empty branch, and referencing undeclared locations/parameters. The version-suffix trap applies — see how FEWS finds a file.

See also

• Task guide: Filters & display groups
• Import time series — writes the header a filter must match
• Schema: filters.xsd