[[filters]]
= Filters

[partintro]
--

Filters are the way to select only the indices (or snapshots) you want.

include::inc_filter_chaining.asciidoc[]

The index filtertypes are:

* <<filtertype_age,age>>
* <<filtertype_alias,alias>>
* <<filtertype_allocated,allocated>>
* <<filtertype_closed,closed>>
* <<filtertype_count,count>>
* <<filtertype_empty,empty>>
* <<filtertype_forcemerged,forcemerged>>
* <<filtertype_kibana,kibana>>
* <<filtertype_none,none>>
* <<filtertype_opened,opened>>
* <<filtertype_pattern,pattern>>
* <<filtertype_period,period>>
* <<filtertype_space,space>>

The snapshot filtertypes are:

* <<filtertype_age,age>>
* <<filtertype_count,count>>
* <<filtertype_none,none>>
* <<filtertype_pattern,pattern>>
* <<filtertype_period,period>>
* <<filtertype_state,state>>

You can use <<envvars,environment variables>> in your configuration files.
--



[[filtertype]]
== filtertype

Each filter is defined first by a `filtertype`.  Each filtertype has its own
settings, or no settings at all.  In a configuration file, filters are defined
as follows:

[source,yaml]
-------------
- filtertype: *first*
  setting1: ...
  ...
  settingN: ...
- filtertype: *second*
  setting1: ...
  ...
  settingN: ...
- filtertype: *third*
-------------

The `-` indicates in the YAML that this is an array element.  Each filtertype
declaration must be preceded by a `-` for the filters to be read properly.  This
is how Curator can chain filters together.  Anywhere filters can be used,
multiple can be chained together in this manner.

The index filtertypes are:

* <<filtertype_age,age>>
* <<filtertype_alias,alias>>
* <<filtertype_allocated,allocated>>
* <<filtertype_closed,closed>>
* <<filtertype_count,count>>
* <<filtertype_empty,empty>>
* <<filtertype_forcemerged,forcemerged>>
* <<filtertype_kibana,kibana>>
* <<filtertype_none,none>>
* <<filtertype_opened,opened>>
* <<filtertype_pattern,pattern>>
* <<filtertype_period,period>>
* <<filtertype_space,space>>

The snapshot filtertypes are:

* <<filtertype_age,age>>
* <<filtertype_count,count>>
* <<filtertype_none,none>>
* <<filtertype_pattern,pattern>>
* <<filtertype_period,period>>
* <<filtertype_state,state>>



[[filtertype_age]]
== age

NOTE: Empty values and commented lines will result in the default value, if any,
    being selected.  If a setting is set, but not used by a given
    <<filtertype,filtertype>>, it may generate an error.

This <<filtertype,filtertype>> will iterate over the actionable list and match
indices based on their age.  They will remain in, or be removed from the
actionable list based on the value of <<fe_exclude,exclude>>.

=== Age calculation

include::inc_unit_table.asciidoc[]

All calculations are in epoch time, which is the number of seconds elapsed since
1 Jan 1970.  If no <<fe_epoch,`epoch`>> is specified in the filter, then the
current epoch time-which is always UTC-is used as the basis for comparison.

As epoch time is always increasing, lower numbers indicate dates and times in
the past.

When age is calculated, <<fe_unit,`unit`>> is multiplied by
<<fe_unit_count,`unit_count`>> to obtain a total number of seconds to use as a
differential.

For example, if the time at execution were 2017-04-07T15:00:00Z (UTC), then the
epoch timestamp would be `1491577200`.  If I had an age filter defined like
this:

[source,yaml]
-------------
 - filtertype: age
   source: creation_date
   direction: older
   unit: days
   unit_count: 3
-------------

The time differential would be `3*24*60*60` seconds, which is `259200` seconds.
Subtracting this value from `1491577200` gives us `1491318000`, which is
2017-04-04T15:00:00Z (UTC), exactly 3 days in the past.  The `creation_date` of
indices or snapshots is compared to this timestamp. If it is `older`, it stays
in the actionable list, otherwise it is removed from the actionable list.

[IMPORTANT]
.`age` filter vs. `period` filter
=================================
The time differential means of calculation can lead to frustration.

Setting `unit` to `months`, and `unit_count` to `3` will actually calculate the
age as `3*30*24*60*60`, which is `7776000` seconds. This may be a big deal. If
the date is 2017-01-01T02:30:00Z, or `1483237800` in epoch time. Subtracting
`7776000` seconds makes `1475461800`, which is 2016-10-03T02:30:00Z. If you were
to try to match monthly indices, `index-2016.12`, `index-2016.11`, `2016.10`,
`2016.09`, etc., then both `index-2016.09` _and_ `index-2016.10` will be _older_
than the cutoff date.  This may result in unintended behavior.

Another way this can cause issues is with weeks. Weekly indices may start on
Sunday or Monday. The age filter's calculation doesn't take this into
consideration, and merely tests the difference between execution time and the
timestamp on the index (from any `source`).

Another means of selecting indices and snapshots is the
<<filtertype_period,period>> filter, which is perhaps a better choice for
selecting weeks and months as it compensates for these differences.
=================================

include::inc_sources.asciidoc[]

=== Required settings

* <<fe_source,source>>
* <<fe_direction,direction>>
* <<fe_unit,unit>>
* <<fe_unit_count,unit_count>>

=== Dependent settings

* <<fe_timestring,timestring>> (required if `source` is `name`)
* <<fe_field,field>> (required if `source` is `field_stats`) [Indices only]
* <<fe_stats_result,stats_result>> (only used if `source` is `field_stats`) [Indices only]

=== Optional settings

* <<fe_unit_count_pattern,unit_count_pattern>>
* <<fe_epoch,epoch>>
* <<fe_exclude,exclude>> (default is `False`)



[[filtertype_alias]]
== alias

[source,yaml]
-------------
- filtertype: alias
  aliases: ...
-------------

NOTE: Empty values and commented lines will result in the default value, if any,
    being selected.  If a setting is set, but not used by a given
    <<filtertype,filtertype>>, it may generate an error.

This <<filtertype,filtertype>> will iterate over the actionable list and match
indices based on whether they are associated with the given
<<fe_aliases,aliases>>, which can be a single value, or an array.  They will
remain in, or be removed from the actionable list based on the value of
<<fe_exclude,exclude>>.

include::inc_filter_by_aliases.asciidoc[]

=== Required settings

* <<fe_aliases,aliases>>

=== Optional settings

* <<fe_exclude,exclude>>



[[filtertype_allocated]]
== allocated

[source,yaml]
-------------
- filtertype: allocated
  key: ...
  value: ...
  allocation_type:
  exclude: True
-------------

NOTE: Empty values and commented lines will result in the default value, if any,
    being selected.  If a setting is set, but not used by a given
    <<filtertype,filtertype>>, it may generate an error.

This <<filtertype,filtertype>> will iterate over the actionable list and match
indices based on their shard routing allocation settings.  They will remain in,
or be removed from the actionable list based on the value of
<<fe_exclude,exclude>>.


By default the indices matched by the `allocated` filter will be excluded since the `exclude` setting defaults to `True`.

To include matching indices rather than exclude, set the `exclude` setting to `False`.

=== Required settings

* <<fe_key,key>>
* <<fe_value,value>>

=== Optional settings

* <<fe_allocation_type,allocation_type>>
* <<fe_exclude,exclude>> (default is `True`)



[[filtertype_closed]]
== closed

[source,yaml]
-------------
- filtertype: closed
  exclude: True
-------------

This <<filtertype,filtertype>> will iterate over the actionable list and match
indices which are closed.  They will remain in, or be removed from the
actionable list based on the value of <<fe_exclude,exclude>>.

=== Optional settings

* <<fe_exclude,exclude>> (default is `True`)



[[filtertype_count]]
== count

[source,yaml]
-------------
- filtertype: count
  count: 10
-------------

NOTE: Empty values and commented lines will result in the default value, if any,
    being selected.  If a setting is set, but not used by a given
    <<filtertype,filtertype>>, it may generate an error.

This <<filtertype,filtertype>> will iterate over the actionable list of indices
_or_ snapshots. They are ordered by age, or by alphabet, so as to guarantee
that the correct items will remain in, or be removed from the actionable list
based on the values of <<fe_count,count>>, <<fe_exclude,exclude>>, and
<<fe_reverse,reverse>>.

=== Age-based sorting

For use cases where "like" items are being counted, and their name pattern
guarantees date sorting is equal to alphabetical sorting, it is unnecessary to
set <<fe_use_age,use_age>> to `True`, as item names will be sorted in
<<fe_reverse,reverse>> order by default.  This means that the item count will
start beginning with the _newest_ indices or snapshots, and proceed through to
the oldest.

Where this is not the case, the <<fe_use_age,`use_age`>> setting can be used to
ensure that index or snapshot ages are properly considered for sorting:

[source,yaml]
-------------
- filtertype: count
  count: 10
  use_age: True
  source: creation_date
-------------

All of the age-related settings from the <<filtertype_age,`age`>> filter are
supported, and the same restrictions apply with regard to filtering indices vs.
snapshots.

=== Pattern-based sorting

[source,yaml]
-------------
- filtertype: count
  count: 1
  pattern: '^(.*)-\d{6}$'
  reverse: true
-------------

This particular example will match indices following the basic rollover pattern
of `indexname-######`, and keep the highest numbered index for each group.

For example, given indices `a-000001`, `a-000002`, `a-000003` and `b-000006`,
and `b-000007`, the indices will would be matched are `a-000003` and `b-000007`.
Indices that do not match the regular expression in `pattern` will be
automatically excluded.

This is particularly useful with indices created and managed using the
{ref}/indices-rollover-index.html[Rollover API], as you can select only the
active indices with the above example (<<fe_exclude,`exclude`>> defaults to `False`).
Setting <<fe_exclude,`exclude`>> to `True` with the above example will _remove_
the active rollover indices, leaving only those which have been rolled-over.

While this is perhaps most useful for the aforementioned scenario, it can
also be used with age-based indices as well.

=== Reversing sorting

Using the default configuration, <<fe_reverse,`reverse`>> is `True`.  Given
These indices:

[source,sh]
-------------
index1
index2
index3
index4
index5
-------------

And this filter:

[source,yaml]
-------------
- filtertype: count
  count: 2
-------------

Indices `index5` and `index4` will be recognized as the `2` _most recent,_ and
will be removed from the actionable list, leaving `index1`, `index2`, and
`index3` to be acted on by the given <<actions,action>>.

Similarly, given these indices:

[source,sh]
-------------
index-2017.03.01
index-2017.03.02
index-2017.03.03
index-2017.03.04
index-2017.03.05
-------------

And this filter:

[source,yaml]
-------------
- filtertype: count
  count: 2
  use_age: True
  source: name
  timestring: '%Y.%m.%d'
-------------

The result will be similar.  Indices `index-2017.03.05` and `index-2017.03.04`
will be recognized as the `2` _most recent,_ and will be removed from the
actionable list, leaving `index-2017.03.01`, `index-2017.03.02`, and
`index-2017.03.03` to be acted on by the given <<actions,action>>.

In some cases, you may wish to filter for the most recent indices.  To
accomplish this you set <<fe_reverse,`reverse`>> to `False`:

[source,yaml]
-------------
- filtertype: count
  count: 2
  reverse: False
-------------

This time indices `index1` and `index2` will be the `2` which will be removed
from the actionable list, leaving `index3`, `index4`, and `index5` to be acted
on by the given <<actions,action>>.

Likewise with the age sorted indices:

[source,yaml]
-------------
- filtertype: count
  count: 2
  use_age: True
  source: name
  timestring: '%Y.%m.%d'
  reverse: True
-------------

Indices `index-2017.03.01` and `index-2017.03.02` will be the `2` which will be
removed from the actionable list, leaving `index-2017.03.03`,
`index-2017.03.04`, and `index-2017.03.05` to be acted on by the given
<<actions,action>>.


=== Required settings

* <<fe_count,count>>

=== Optional settings

* <<fe_reverse,reverse>>
* <<fe_use_age,use_age>>
* <<fe_pattern,pattern>>
* <<fe_source,source>> (required if `use_age` is `True`)
* <<fe_timestring,timestring>> (required if `source` is `name`)
* <<fe_exclude,exclude>> (default is `True`)

=== Index-only settings

* <<fe_field,field>> (required if `source` is `field_stats`)
* <<fe_stats_result,stats_result>> (only used if `source` is `field_stats`)


[[filtertype_empty]]
== empty
[source,yaml]
-------------
- filtertype: empty
  exclude: False
-------------

This <<filtertype,filtertype>> will iterate over the actionable list and match
indices which do not contain any documents. Indices that are closed are automatically
removed from consideration. They will remain in, or be removed from the actionable list
based on the value of <<fe_exclude,exclude>>.

By default the indices matched by the empty filter will be excluded since
the exclude setting defaults to True. To include matching indices rather than
exclude, set the exclude setting to False.

=== Optional settings

* <<fe_exclude,exclude>> (default is `True`)


[[filtertype_forcemerged]]
== forcemerged

[source,yaml]
-------------
- filtertype: forcemerged
  max_num_segments: 2
  exclude: True
-------------

NOTE: Empty values and commented lines will result in the default value, if any,
    being selected.  If a setting is set, but not used by a given
    <<filtertype,filtertype>>, it may generate an error.

This <<filtertype,filtertype>> will iterate over the actionable list and match
indices which have `max_num_segments` segments per shard, or fewer.  They will
remain in, or be removed from the actionable list based on the value of
<<fe_exclude,exclude>>.

=== Required settings

* <<fe_max_num_segments,max_num_segments>>

=== Optional settings

* <<fe_exclude,exclude>> (default is `True`)



[[filtertype_kibana]]
== kibana

[source,yaml]
-------------
- filtertype: kibana
  exclude: True
-------------

This <<filtertype,filtertype>> will remove any index matching the regular
expression `^\.kibana.*$` from the list of indices, if present.

This <<filtertype,filtertype>> will iterate over the actionable list and match
indices matching the regular expression `^\.kibana.*$`. They will remain in, or
be removed from the actionable list based on the value of
<<fe_exclude,exclude>>.

=== Optional settings

* <<fe_exclude,exclude>> (default is `True`)



[[filtertype_none]]
== none

[source,yaml]
-------------
- filtertype: none
-------------

This <<filtertype,filtertype>> will not filter anything, returning the full
list of indices or snapshots.

There are no settings for this <<filtertype,filtertype>>.



[[filtertype_opened]]
== opened

[source,yaml]
-------------
- filtertype: opened
  exclude: True
-------------

This <<filtertype,filtertype>> will iterate over the actionable list and match
indices which are opened.  They will remain in, or be removed from the
actionable list based on the value of <<fe_exclude,exclude>>.

=== Optional settings

* <<fe_exclude,exclude>> (default is `True`)



[[filtertype_pattern]]
== pattern

[source,yaml]
-------------
- filtertype: pattern
 kind: ...
 value: ...
-------------

NOTE: Empty values and commented lines will result in the default value, if any,
    being selected.  If a setting is set, but not used by a given
    <<filtertype,filtertype>>, it may generate an error.

This <<filtertype,filtertype>> will iterate over the actionable list and match
indices matching a given pattern.  They will remain in, or be removed from
the actionable list based on the value of <<fe_exclude,exclude>>.

include::inc_filter_chaining.asciidoc[]

include::inc_kinds.asciidoc[]

=== Required settings

* <<fe_kind,kind>>
* <<fe_value,value>>

=== Optional settings

* <<fe_exclude,exclude>> (default is `False`)



[[filtertype_period]]
== period

This <<filtertype,filtertype>> will iterate over the actionable list and match
indices or snapshots based on whether they fit within the given time range.
They will remain in, or be removed from the actionable list based on the value
of <<fe_exclude,exclude>>.

[source,yaml]
-------------
 - filtertype: period
   period_type: relative
   source: name
   range_from: -1
   range_to: -1
   timestring: '%Y.%m.%d'
   unit: weeks
   week_starts_on: sunday
-------------

NOTE: Empty values and commented lines will result in the default value, if any,
    being selected.  If a setting is set, but not used by a given
    <<filtertype,filtertype>>, it may generate an error.

=== Relative Periods
A relative period will be reckoned relative to execution time, unless an
<<fe_epoch,epoch>> timestamp is provided.  Reckoning is truncated to the most
recent whole unit, where a <<fe_unit,unit>> can be one of `hours`, `days`, `weeks`, 
`months`, or `years`.  For example, if I selected `hours` as my `unit`, and I 
began execution at 02:35, then the point of reckoning would be 02:00. This is 
relatively easy with `days`, `months`, and `years`, but slightly more complicated 
with `weeks`. Some users may wish to reckon weeks by the ISO standard, which 
starts weeks on Monday. Others may wish to use Sunday as the first day of the 
week.  Both are acceptable options with the `period` filter. The default behavior 
for `weeks` is to have Sunday be the start of the week. This can be overridden 
with <<fe_week_starts_on,week_starts_on>> as follows:

[source,yaml]
-------------
 - filtertype: period
   period_type: relative
   source: name
   range_from: -1
   range_to: -1
   timestring: '%Y.%m.%d'
   unit: weeks
   week_starts_on: monday
-------------

<<fe_range_from,range_from>> and <<fe_range_to,range_to>> are counters of whole
<<fe_unit,units>>. A negative number indicates a whole unit in the past, while
a positive number indicates a whole unit in the future. A `0` indicates the
present unit. With such a timeline mentality, it is relatively easy to create
a date range that will meet your needs.

If the time of execution time is *2017-04-03T13:45:23.831*, this table will help
you figure out what the previous whole unit, current unit, and next whole unit
will be, in ISO8601 format.

[frame="topbot",options="header"]
|======================================================================
|unit      |-1                 |0                  |+1
|hours     |2017-04-03T12:00:00|2017-04-03T13:00:00|2017-04-03T14:00:00
|days      |2017-04-02T00:00:00|2017-04-03T00:00:00|2017-04-04T00:00:00
|weeks sun |2017-03-26T00:00:00|2017-04-02T00:00:00|2017-04-09T00:00:00
|weeks mon |2017-03-27T00:00:00|2017-04-03T00:00:00|2017-04-10T00:00:00
|months    |2017-03-01T00:00:00|2017-04-01T00:00:00|2017-05-01T00:00:00
|years     |2016-01-01T00:00:00|2017-01-01T00:00:00|2018-01-01T00:00:00
|======================================================================

Ranges must be from older dates to newer dates, or smaller numbers (including
negative numbers) to larger numbers or Curator will return an exception.

An example `period` filter demonstrating how to select all daily indices by
timestring found in the index name from last month might look like this:

[source,yaml]
-------------
 - filtertype: period
   period_type: relative
   source: name
   range_from: -1
   range_to: -1
   timestring: '%Y.%m.%d'
   unit: months
-------------

Having `range_from` and `range_to` both be the same value will mean that only
that whole unit will be selected, in this case, a month.

IMPORTANT: `range_from` and `range_to` are required for the `relative` pattern type.

=== Absolute Periods

[source,yaml]
-------------
 - filtertype: period
   period_type: absolute
   source: name
   timestring: '%Y.%m.%d'
   unit: months
   date_from: 2017.01
   date_from_format: '%Y.%m'
   date_to: 2017.01
   date_to_format: '%Y.%m'
-------------

In addition to relative periods, you can define absolute periods.  These
are defined as the period between the <<fe_date_from,`date_from`>> and the
<<fe_date_to,`date_to`>>.  For example, if `date_from` and `date_to` are
both `2017.01`, and <<fe_unit,`unit`>> is `months`, all indices with a
`name`, `creation_date`, or `stats_result` (depending on the value of
<<fe_source,`source`>>) within the month of January 2017 will match.

The `date_from` is used to establish the beginning of the time period, regardless
of whether `date_from_format` is in hours, and the indices you are trying to filter
are in weeks or months.  The format and date of `date_from` will simply set the
beginning of the time period.

The `date_to`, `date_to_format`, and `unit` work in conjunction to select the
end date.  For example, if my `date_to` were `2017.04`, and `date_to_format`
is `%Y.%m` to properly parse that date, it would follow that `unit` would be
`months`.

[IMPORTANT]
=====================================
The period filter is smart enough to calculate `months` and `years`
properly.  **If `unit` is not `months` or `years`,** then your date range will be `unit`
seconds more than the beginning of the `date_from` date, minus 1 second,
according to this table:

include::inc_unit_table.asciidoc[]
=====================================

Specific date ranges can be captured with up to whole second resolution:

[source,yaml]
-------------
 - filtertype: period
   period_type: absolute
   source: name
   timestring: '%Y.%m.%d.%H'
   unit: seconds
   date_from: 2017-01-01T00:00:00
   date_from_format: '%Y-%m-%dT%H:%M:%S'
   date_to: 2017-01-01T12:34:56
   date_to_format: '%Y-%m-%dT%H:%M:%S'
-------------

This example will capture indices with an hourly timestamp in their name that fit
between the `date_from` and `date_to` timestamps.

include::inc_strftime_table.asciidoc[]

=== Required settings

* <<fe_source,source>>
* <<fe_unit,unit>>

=== Dependent settings

* <<fe_range_from,range_from>>
* <<fe_range_to,range_to>>
* <<fe_date_from,date_from>>
* <<fe_date_to,date_to>>
* <<fe_date_from_format,date_from_format>>
* <<fe_date_to_format,date_to_format>>
* <<fe_timestring,timestring>> (required if `source` is `name`)
* <<fe_field,field>> (required if `source` is `field_stats`) [Indices only]
* <<fe_stats_result,stats_result>> (only used if `source` is `field_stats`) [Indices only]
* <<fe_intersect,intersect>> (optional if `source` is `field_stats`) [Indices only]

=== Optional settings

* <<fe_epoch,epoch>>
* <<fe_exclude,exclude>> (default is `False`)
* <<fe_week_starts_on,week_starts_on>>



[[filtertype_space]]
== space

This <<filtertype,filtertype>> will iterate over the actionable list and match
indices when their cumulative disk consumption is `greater_than` (default) or `less_than` than
<<fe_disk_space,disk_space>> gigabytes.  They are first ordered by age,
or by alphabet, so as to guarantee the oldest indices are deleted first. They
will remain in, or be removed from the actionable list based on the value of
<<fe_exclude,exclude>>.

=== Deleting Indices By Space

[source,yaml]
-------------
- filtertype: space
  disk_space: 100
-------------

This <<filtertype,filtertype>> is for those who want to retain indices based on
disk consumption, rather than by a set number of days. There are some important
caveats regarding this choice:

* Elasticsearch cannot calculate the size of closed indices. Elasticsearch does
  not keep tabs on how much disk-space closed indices consume. If you close
  indices, your space calculations will be inaccurate.
* Indices consume resources just by existing. You could run into performance
  and/or operational snags in Elasticsearch as the count of indices climbs.
* You need to manually calculate how much space across all nodes. The total you
  give will be the sum of all space consumed across all nodes in your cluster.
  If you use shard allocation to put more shards or indices on a single node, it
  will not affect the total space reported by the cluster, but you may still run
  out of space on that node.

These are only a few of the caveats. This is still a valid use-case, especially
for those running a single-node test box.

For use cases where "like" indices are being counted, and their name pattern
guarantees date sorting is equal to alphabetical sorting, it is unnecessary to
set <<fe_use_age,use_age>> to `True`, as index names will be sorted in
<<fe_reverse,reverse>> order by default.  For this case, this means that disk
space calculations will start beginning with the _newest_ indices, and
proceeding through to the oldest.

=== Age-based sorting

[source,yaml]
-------------
- filtertype: space
  disk_space: 100
  use_age: True
  source: creation_date
-------------

For use cases where "like" indices are being counted, and their name pattern
guarantees date sorting is equal to alphabetical sorting, it is unnecessary to
set <<fe_use_age,use_age>> to `True`, as index names will be sorted in
<<fe_reverse,reverse>> order by default.  For this case, this means that disk
space calculations will start beginning with the _newest_ indices, and
proceeding through to the oldest.

Where this is not the case, the <<fe_use_age,`use_age`>> setting can be used to
ensure that index or snapshot ages are properly considered for sorting:

All of the age-related settings from the <<filtertype_age,`age`>> filter are
supported.

=== Reversing sorting

IMPORTANT: The <<fe_reverse,`reverse`>> setting is ignored when
<<fe_use_age,`use_age`>> is `True`. When <<fe_use_age,`use_age`>> is `True`,
sorting is _always_ from newest to oldest, ensuring that old indices are always
selected first.

Using the default configuration, <<fe_reverse,`reverse`>> is `True`.  Given
These indices:

[source,sh]
-------------
index1 10g
index2 10g
index3 10g
index4 10g
index5 10g
-------------

And this filter:

[source,yaml]
-------------
- filtertype: space
  disk_space: 21
-------------

The indices will be sorted alphabetically and iterated over in the indicated
order (the value of <<fe_reverse,`reverse`>>) and the total disk space compared
after adding the size of each successive index. In this example, that means that
`index5` will be added first, and the running total of consumed disk space will
be `10g`. Since `10g` is less than the indicated threshold of `21`, `index5`
will be removed from the actionable list.

On the next iteration, the amount of space consumed by `index4` will be added,
which brings the running total to `20g`, which is still less than the `21`
threshold, so `index4` is also removed from the actionable list.

This process changes when the iteration adds the disk space consumed by
`index3`. Now the running total crosses the `21` threshold established by
<<fe_disk_space,`disk_space`>> (the running total is now `30g`).  Even though
it is only `1g` in excess of the total, `index3` will remain in the actionable
list. The threshold is absolute.

The remaining indices, `index2` and `index1` will also be in excess of the
threshold, so they will also remain in the actionable list.

So in this example `index1`, `index2`, and `index3` will be acted on by the
<<actions,action>> for this block.

If you were to run this with <<loglevel,loglevel>> set to `DEBUG`, you might see
messages like these in the output:

[source,sh]
-------------
...Removed from actionable list: index5, summed disk usage is 10GB and disk limit is 21.0GB.
...Removed from actionable list: index4, summed disk usage is 20GB and disk limit is 21.0GB.
...Remains in actionable list: index3, summed disk usage is 30GB and disk limit is 21.0GB.
...Remains in actionable list: index2, summed disk usage is 40GB and disk limit is 21.0GB.
...Remains in actionable list: index1, summed disk usage is 50GB and disk limit is 21.0GB.
-------------

In some cases, you may wish to filter in the reverse order.  To accomplish this,
you set <<fe_reverse,`reverse`>> to `False`:

[source,yaml]
-------------
- filtertype: space
  disk_space: 21
  reverse: False
-------------

This time indices `index1` and `index2` will be the ones removed from the
actionable list, leaving `index3`, `index4`, and `index5` to be acted on by the
given <<actions,action>>.

If you were to run this with <<loglevel,loglevel>> set to `DEBUG`, you might see
messages like these in the output:

[source,sh]
-------------
...Removed from actionable list: index1, summed disk usage is 10GB and disk limit is 21.0GB.
...Removed from actionable list: index2, summed disk usage is 20GB and disk limit is 21.0GB.
...Remains in actionable list: index3, summed disk usage is 30GB and disk limit is 21.0GB.
...Remains in actionable list: index4, summed disk usage is 40GB and disk limit is 21.0GB.
...Remains in actionable list: index5, summed disk usage is 50GB and disk limit is 21.0GB.
-------------

=== Required settings

* <<fe_disk_space,disk_space>>

=== Optional settings

* <<fe_reverse,reverse>>
* <<fe_use_age,use_age>>
* <<fe_source,source>> (required if `use_age` is `True`)
* <<fe_timestring,timestring>> (required if `source` is `name`)
* <<fe_threshold_behavior,threshold_behavior>> (default is `greater_than`)
* <<fe_field,field>> (required if `source` is `field_stats`)
* <<fe_stats_result,stats_result>> (only used if `source` is `field_stats`)
* <<fe_exclude,exclude>> (default is `False`)



[[filtertype_state]]
== state

[source,yaml]
-------------
- filtertype: state
  state: SUCCESS
-------------

NOTE: Empty values and commented lines will result in the default value, if any,
    being selected.  If a setting is set, but not used by a given
    <<filtertype,filtertype>>, it may generate an error.

This <<filtertype,filtertype>> will iterate over the actionable list and match
snapshots based on the value of <<fe_state,state>>.  They will remain in, or be
removed from the actionable list based on the value of <<fe_exclude,exclude>>.

=== Required settings

* <<fe_state,state>>

=== Optional settings

* <<fe_exclude,exclude>> (default is `False`)