elasticsearch/docs/reference/rest-api/common-parms.asciidoc

tag::actions[]
`actions`::
+
--
(Optional, string)
Comma-separated list or wildcard expression
of actions used to limit the request.

Omit this parameter to return all actions.
--
end::actions[]

tag::active-only[]
`active_only`::
(Optional, boolean)
If `true`,
the response only includes ongoing shard recoveries.
Defaults to `false`.
end::active-only[]

tag::index-alias[]
Comma-separated list or wildcard expression of index alias names
used to limit the request.
end::index-alias[]

tag::aliases[]
`aliases`::
(Optional, <<indices-aliases,alias object>>) Index aliases which include the
index. See <<indices-aliases>>.
end::aliases[]

tag::target-index-aliases[]
`aliases`::
(Optional, <<indices-aliases,alias object>>)
Index aliases which include the target index.
See <<indices-aliases>>.
end::target-index-aliases[]

tag::allow-no-indices[]
`allow_no_indices`::
(Optional, boolean) If `true`,
the request does *not* return an error
if a wildcard expression
or `_all` value retrieves only missing or closed indices.
+
This parameter also applies to <<indices-aliases,index aliases>>
that point to a missing or closed index.
end::allow-no-indices[]

tag::allow-no-match-transforms1[]
Specifies what to do when the request:
+
--
* Contains wildcard expressions and there are no {transforms} that match.
* Contains the `_all` string or no identifiers and there are no matches.
* Contains wildcard expressions and there are only partial matches. 

The default value is `true`, which returns an empty `transforms` array when
there are no matches and the subset of results when there are partial matches.

If this parameter is `false`, the request returns a `404` status code when there
are no matches or only partial matches.
--
end::allow-no-match-transforms1[]

tag::allow-no-match-transforms2[]
Specifies what to do when the request:
+
--
* Contains wildcard expressions and there are no {transforms} that match.
* Contains the `_all` string or no identifiers and there are no matches.
* Contains wildcard expressions and there are only partial matches. 

The default value is `true`, which returns a successful acknowledgement message
when there are no matches. When there are only partial matches, the API stops
the appropriate {transforms}. For example, if the request contains
`test-id1*,test-id2*` as the identifiers and there are no {transforms}
that match `test-id2*`, the API nonetheless stops the {transforms}
that match `test-id1*`.

If this parameter is `false`, the request returns a `404` status code when there
are no matches or only partial matches.
--
end::allow-no-match-transforms2[]

tag::analyzer[]
`analyzer`::
(Optional, string) Analyzer to use for the query string.
end::analyzer[]

tag::analyze_wildcard[]
`analyze_wildcard`::
(Optional, boolean) If `true`, wildcard and prefix queries are 
analyzed. Defaults to `false`.
end::analyze_wildcard[]

tag::bytes[]
`bytes`::
(Optional, <<byte-units,byte size units>>) Unit used to display byte values.
end::bytes[]

tag::committed[]
If `true`,
the segments is synced to disk. Segments that are synced can survive a hard reboot.
+
If `false`,
the data from uncommitted segments is also stored in
the transaction log so that Elasticsearch is able to replay
changes on the next start.
end::committed[]

tag::completion-fields[]
`completion_fields`::
(Optional, string)
Comma-separated list or wildcard expressions of fields
to include in `fielddata` and `suggest` statistics.
end::completion-fields[]

tag::default_operator[]
`default_operator`::
(Optional, string) The default operator for query string query: AND or OR. 
Defaults to `OR`.
end::default_operator[]

tag::dest[]
The destination for the {transform}.
end::dest[]

tag::dest-index[]
The _destination index_ for the {transform}.
end::dest-index[]

tag::dest-pipeline[]
The unique identifier for a <<pipeline,pipeline>>.
end::dest-pipeline[]

tag::detailed[]
`detailed`::
(Optional, boolean)
If `true`,
the response includes detailed information about shard recoveries.
Defaults to `false`.
end::detailed[]

tag::df[]
`df`::
(Optional, string) Field to use as default where no field prefix is 
given in the query string.
end::df[]

tag::docs-count[]
Number of non-deleted documents in the segment, such as `25`. This
number is based on Lucene documents and may include documents from
<<nested,nested>> fields.
end::docs-count[]

tag::docs-deleted[]
Number of deleted documents in the segment, such as `0`. This number
is based on Lucene documents. {es} reclaims the disk space of deleted Lucene
documents when a segment is merged.
end::docs-deleted[]

tag::enrich-policy[]
Enrich policy name
used to limit the request.
end::enrich-policy[]

tag::expand-wildcards[]
`expand_wildcards`::
+
--
(Optional, string) Controls what kind of indices that wildcard
expressions can expand to. Valid values are:

`all`::
Expand to open and closed indices.

`open`::
Expand only to open indices.

`closed`::
Expand only to closed indices.

`none`::
Wildcard expressions are not accepted.
--
end::expand-wildcards[]

tag::field_statistics[]
`field_statistics`::
(Optional, boolean) If `true`, the response includes the document count, sum of document frequencies, 
and sum of total term frequencies.
Defaults to `true`.
end::field_statistics[]

tag::fielddata-fields[]
`fielddata_fields`::
(Optional, string)
Comma-separated list or wildcard expressions of fields
to include in `fielddata` statistics.
end::fielddata-fields[]

tag::fields[]
`fields`::
+
--
(Optional, string)
Comma-separated list or wildcard expressions of fields
to include in the statistics.

Used as the default list
unless a specific field list is provided
in the `completion_fields` or `fielddata_fields` parameters.
--
end::fields[]

tag::index-alias-filter[]
<<query-dsl-bool-query, Filter query>>
used to limit the index alias.
+
If specified,
the index alias only applies to documents returned by the filter.
end::index-alias-filter[]

tag::flat-settings[]
`flat_settings`::
(Optional, boolean) If `true`, returns settings in flat format. Defaults to
`false`.
end::flat-settings[]

tag::http-format[]
`format`::
(Optional, string) Short version of the
https://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html[HTTP accept header].
Valid values include JSON, YAML, etc.
end::http-format[]

tag::frequency[]
The interval between checks for changes in the source indices when the
{transform} is running continuously. Also determines the retry interval in the
event of transient failures while the {transform} is searching or indexing. The
minimum value is `1s` and the maximum is `1h`. The default value is `1m`.
end::frequency[]

tag::from[]
`from`::
(Optional, integer) Starting document offset. Defaults to `0`.
end::from[]

tag::from-transforms[]
Skips the specified number of {transforms}. The default value is `0`.
end::from-transforms[]

tag::generation[]
Generation number, such as `0`. {es} increments this generation number
for each segment written. {es} then uses this number to derive the segment name.
end::generation[]

tag::group-by[]
`group_by`::
+
--
(Optional, string)
Key used to group tasks in the response.

Possible values are:

`nodes`::
(Default)
Node ID

`parents`::
Parent task ID

`none`::
Do not group tasks.
--
end::group-by[]

tag::groups[]
`groups`::
(Optional, string)
Comma-separated list of search groups
to include in the `search` statistics.
end::groups[]

tag::cat-h[]
`h`::
(Optional, string) Comma-separated list of column names to display.
end::cat-h[]

tag::help[]
`help`::
(Optional, boolean) If `true`, the response includes help information. Defaults
to `false`.
end::help[]

tag::bulk-id[]
`_id`::
(Optional, string) 
The document ID.
If no ID is specified, a document ID is automatically generated. 
end::bulk-id[]

tag::if_primary_term[]
`if_primary_term`::
(Optional, integer) Only perform the operation if the document has
this primary term. See <<optimistic-concurrency-control-index>>.
end::if_primary_term[]

tag::if_seq_no[]
`if_seq_no`::
(Optional, integer) Only perform the operation if the document has this
sequence number. See <<optimistic-concurrency-control-index>>.
end::if_seq_no[]

tag::ignore_throttled[]
`ignore_throttled`::
(Optional, boolean) If `true`, concrete, expanded or aliased indices are 
ignored when throttled.
end::ignore_throttled[]

tag::index-ignore-unavailable[]
`ignore_unavailable`::
(Optional, boolean) If `true`, missing or closed indices are not included in the
response. Defaults to `false`.
end::index-ignore-unavailable[]

tag::include-defaults[]
`include_defaults`::
(Optional, string) If `true`, return all default settings in the response.
Defaults to `false`.
end::include-defaults[]

tag::include-segment-file-sizes[]
`include_segment_file_sizes`::
(Optional, boolean)
If `true`, the call reports the aggregated disk usage of
each one  of the Lucene index files (only applies if segment stats are
requested). Defaults to `false`.
end::include-segment-file-sizes[]

tag::include-unloaded-segments[]
`include_unloaded_segments`::
(Optional, boolean) If `true`, the response includes information from segments
that are **not** loaded into memory. Defaults to `false`.
end::include-unloaded-segments[]

tag::index-query-parm[]
`index`::
(Optional, string)
Comma-separated list or wildcard expression of index names
used to limit the request.
end::index-query-parm[]

tag::index[]
`<index>`::
(Optional, string) Comma-separated list or wildcard expression of index names
used to limit the request.
end::index[]

tag::bulk-index[]
`_index`::
(Optional, string)
The name of the target index. 
Required if not specified as a path parameter.
end::bulk-index[]

tag::index-metric[]
`<index-metric>`::
+
--
(Optional, string)
Comma-separated list of metrics used to limit the request.
Supported metrics are:

`_all`::
Return all statistics.

`completion`::
<<completion-suggester,Completion suggester>> statistics.

`docs`::
Number of documents and deleted docs, which have not yet merged out.
<<indices-refresh,Index refreshes>> can affect this statistic.

`fielddata`::
<<fielddata,Fielddata>> statistics.

`flush`::
<<indices-flush,Flush>> statistics.

`get`::
Get statistics,
including missing stats.

`indexing`::
<<docs-index_,Indexing>> statistics.

`merge`::
<<index-modules-merge,Merge>> statistics.

`query_cache`::
<<query-cache,Query cache>> statistics.

`refresh`::
<<indices-refresh,Refresh>> statistics.

`request_cache`::
<<shard-request-cache,Shard request cache>> statistics.

`search`::
Search statistics including suggest statistics.
You can include statistics for custom groups
by adding an extra `groups` parameter
(search operations can be associated with one or more groups).
The `groups` parameter accepts a comma separated list of group names.
Use `_all` to return statistics for all groups.

`segments`::
Memory use of all open segments.
+
If the `include_segment_file_sizes` parameter is `true`,
this metric includes the aggregated disk usage
of each Lucene index file.

`store`::
Size of the index in <<byte-units, byte units>>.

`suggest`::
<<search-suggesters,Suggester>> statistics.

`translog`::
<<index-modules-translog,Translog>> statistics.

`warmer`::
<<indices-warmers,Warmer>> statistics.
--
end::index-metric[]

tag::index-template[]
`<index-template>`::
(Required, string)
Comma-separated list or wildcard expression of index template names
used to limit the request.
end::index-template[]

tag::lenient[]
`lenient`::
(Optional, boolean) If `true`, format-based query failures (such as 
providing text to a numeric field) will be ignored. Defaults to `false`.
end::lenient[]

tag::level[]
`level`::
+
--
(Optional, string)
Indicates whether statistics are aggregated
at the cluster, index, or shard level.

Valid values are:

*   `cluster`
*   `indices`
*   `shards`
--
end::level[]

tag::local[]
`local`::
(Optional, boolean) If `true`, the request retrieves information from the local
node only. Defaults to `false`, which means information is retrieved from
the master node.
end::local[]

tag::mappings[]
`mappings`::
+
--
(Optional, <<mapping,mapping object>>) Mapping for fields in the index. If
specified, this mapping can include:

* Field names
* <<mapping-types,Field datatypes>>
* <<mapping-params,Mapping parameters>>

See <<mapping>>.
--
end::mappings[]

tag::max_docs[]
`max_docs`::
(Optional, integer) Maximum number of documents to process. Defaults to all
documents.
end::max_docs[]

tag::memory[]
Bytes of segment data stored in memory for efficient search,
such as `1264`.
+
A value of `-1` indicates {es} was unable to compute this number.
end::memory[]

tag::node-id[]
`<node_id>`::
(Optional, string) Comma-separated list of node IDs or names used to limit
returned information.
end::node-id[]

tag::node-id-query-parm[]
`node_id`::
(Optional, string)
Comma-separated list of node IDs or names
used to limit returned information.
end::node-id-query-parm[]

tag::offsets[]
`<offsets>`::
(Optional, boolean) If `true`, the response includes term offsets.
Defaults to `true`.
end::offsets[]

tag::parent-task-id[]
`parent_task_id`::
+
--
(Optional, string)
Parent task ID
used to limit returned information.

To return all tasks,
omit this parameter
or use a value of `-1`.
--
end::parent-task-id[]

tag::payloads[]
`payloads`::
(Optional, boolean) If `true`, the response includes term payloads.
Defaults to `true`.
end::payloads[]

tag::pipeline[]
`pipeline`::
(Optional, string) ID of the pipeline to use to preprocess incoming documents.
end::pipeline[]

tag::path-pipeline[]
`<pipeline>`::
(Optional, string) Comma-separated list or wildcard expression of pipeline IDs
used to limit the request.
end::path-pipeline[]

tag::pivot[]
The method for transforming the data. These objects define the pivot function
`group by` fields and the aggregation to reduce the data.
end::pivot[]

tag::pivot-aggs[]
Defines how to aggregate the grouped data. The following composite aggregations
are supported:
+
--
* <<search-aggregations-metrics-avg-aggregation,Average>>
* <<search-aggregations-metrics-weight-avg-aggregation,Weighted average>>
* <<search-aggregations-metrics-cardinality-aggregation,Cardinality>>
* <<search-aggregations-metrics-geobounds-aggregation,Geo bounds>>
* <<search-aggregations-metrics-geocentroid-aggregation,Geo centroid>>
* <<search-aggregations-metrics-max-aggregation,Max>>
* <<search-aggregations-metrics-min-aggregation,Min>>
* <<search-aggregations-metrics-scripted-metric-aggregation,Scripted metric>>
* <<search-aggregations-metrics-sum-aggregation,Sum>>
* <<search-aggregations-metrics-valuecount-aggregation,Value count>>
* <<search-aggregations-pipeline-bucket-script-aggregation,Bucket script>>
* <<search-aggregations-pipeline-bucket-selector-aggregation,Bucket selector>>

IMPORTANT: {transforms-cap} support a subset of the functionality in
composite aggregations. See <<transform-limitations>>.

--
end::pivot-aggs[]

tag::pivot-group-by[]
Defines how to group the data. More than one grouping can be defined
  per pivot. The following groupings are supported:
+
--
* <<_terms,Terms>>
* <<_histogram,Histogram>>
* <<_date_histogram,Date histogram>>
--
end::pivot-group-by[]

tag::pivot-max-page-search-size[]
Defines the initial page size to use for the composite aggregation for each
checkpoint. If circuit breaker exceptions occur, the page size is dynamically
adjusted to a lower value. The minimum value is `10` and the maximum is `10,000`.
The default value is `500`.
end::pivot-max-page-search-size[]

tag::positions[]
`positions`::
(Optional, boolean) If `true`, the response includes term positions.
Defaults to `true`.
end::positions[]

tag::preference[]
`preference`::
(Optional, string) Specifies the node or shard the operation should be
performed on. Random by default.
end::preference[]

tag::search-q[]
`q`::
(Optional, string) Query in the Lucene query string syntax.
end::search-q[]

tag::query[]
`query`::
(Optional, <<query-dsl,query object>>) Defines the search definition using the 
<<query-dsl,Query DSL>>.
end::query[]

tag::realtime[]
`realtime`::
(Optional, boolean) If `true`, the request is real-time as opposed to near-real-time. 
Defaults to `true`. See <<realtime>>.
end::realtime[]

tag::refresh[]
`refresh`::
(Optional, enum) If `true`, {es} refreshes the affected shards to make this
operation visible to search, if `wait_for` then wait for a refresh to make
this operation visible to search, if `false` do nothing with refreshes.
Valid values: `true`, `false`, `wait_for`. Default: `false`.
end::refresh[]

tag::request_cache[]
`request_cache`::
(Optional, boolean) If `true`, the request cache is used for this request. 
Defaults to the index-level setting.
end::request_cache[]

tag::requests_per_second[]
`requests_per_second`::
(Optional, integer) The throttle for this request in sub-requests per second.
-1 means no throttle. Defaults to 0.
end::requests_per_second[]

tag::routing[]
`routing`::
(Optional, string) Target the specified primary shard.
end::routing[]

tag::index-routing[]
`routing`::
(Optional, string)
Custom <<mapping-routing-field, routing value>>
used to route operations to a specific shard.
end::index-routing[]

tag::cat-s[]
`s`::
(Optional, string) Comma-separated list of column names or column aliases used
to sort the response.
end::cat-s[]

tag::scroll[]
`scroll`::
(Optional, <<time-units, time units>>) Specifies how long a consistent view of 
the index should be maintained for scrolled search.
end::scroll[]

tag::scroll_size[]
`scroll_size`::
(Optional, integer) Size of the scroll request that powers the operation. 
Defaults to 100. 
end::scroll_size[]

tag::search_timeout[]
`search_timeout`::
(Optional, <<time-units, time units>>)
Explicit timeout for each search request.
Defaults to no timeout.
end::search_timeout[]

tag::search_type[]
`search_type`::
(Optional, string) The type of the search operation. Available options:
* `query_then_fetch`
* `dfs_query_then_fetch`
end::search_type[]

tag::segment[]
Name of the segment, such as `_0`. The segment name is derived from
the segment generation and used internally to create file names in the directory
of the shard.
end::segment[]

tag::segment-search[]
If `true`,
the segment is searchable.
+
If `false`,
the segment has most likely been written to disk
but needs a <<indices-refresh,refresh>> to be searchable.
end::segment-search[]

tag::segment-size[]
Disk space used by the segment, such as `50kb`.
end::segment-size[]

tag::settings[]
`settings`::
(Optional, <<index-modules-settings,index setting object>>) Configuration
options for the index. See <<index-modules-settings>>.
end::settings[]

tag::target-index-settings[]
`settings`::
(Optional, <<index-modules-settings,index setting object>>)
Configuration options for the target index.
See <<index-modules-settings>>.
end::target-index-settings[]

tag::size-transforms[]
Specifies the maximum number of {transforms} to obtain. The default value is
`100`.
end::size-transforms[]

tag::slices[]
`slices`::
(Optional, integer) The number of slices this task should be divided into. 
Defaults to 1 meaning the task isn't sliced into subtasks.
end::slices[]

tag::sort[]
`sort`::
(Optional, string) A comma-separated list of <field>:<direction> pairs.
end::sort[]

tag::source[]
`_source`::
(Optional, string) True or false to return the `_source` field or not, or a 
list of fields to return.
end::source[]

tag::source_excludes[]
`_source_excludes`::
(Optional, string) A list of fields to exclude from the returned `_source` 
field.
end::source_excludes[]

tag::source_includes[]
`_source_includes`::
(Optional, string) A list of fields to extract and return from the `_source` 
field.
end::source_includes[]

tag::source-transforms[]
The source of the data for the {transform}. 
end::source-transforms[]

tag::source-index-transforms[]
The _source indices_ for the {transform}. It can be a single index, an index
pattern (for example, `"myindex*"`), or an array of indices (for example,
`["index1", "index2"]`).
end::source-index-transforms[]

tag::source-query-transforms[]
A query clause that retrieves a subset of data from the source index. See
<<query-dsl>>.
end::source-query-transforms[]

tag::stats[]
`stats`::
(Optional, string) Specific `tag` of the request for logging and statistical
purposes.
end::stats[]

tag::stored_fields[]
`stored_fields`::
(Optional, boolean) If `true`, retrieves the document fields stored in the
index rather than the document `_source`. Defaults to `false`.
end::stored_fields[]

tag::sync[]
Defines the properties {transforms} require to run continuously.
end::sync[]

tag::sync-time[]
Specifies that the {transform} uses a time field to synchronize the source and
destination indices.
end::sync-time[]

tag::sync-time-field[]
The date field that is used to identify new documents in the source.
end::sync-time-field[]

tag::sync-time-delay[]
The time delay between the current time and the latest input data time. The
default value is `60s`.
end::sync-time-delay[]

tag::target-index[]
`<target-index>`::
+
--
(Required, string)
Name of the target index to create.

include::{docdir}/indices/create-index.asciidoc[tag=index-name-reqs]
--
end::target-index[]

tag::task-id[]
`<task_id>`::
(Optional, string) ID of the task to return
(`node_id:task_number`).
end::task-id[]

tag::term_statistics[]
`term_statistics`::
(Optional, boolean) If `true`, the response includes term frequency and document frequency. 
Defaults to `false`.
end::term_statistics[]

tag::terminate_after[]
`terminate_after`::
(Optional, integer) The maximum number of documents to collect for each shard, 
upon reaching which the query execution will terminate early.
end::terminate_after[]

tag::time[]
`time`::
(Optional, <<time-units,time units>>)
Unit used to display time values.
end::time[]

tag::timeoutparms[]

tag::timeout[]
`timeout`::
(Optional, <<time-units, time units>>) Specifies the period of time to wait for
a response. If no response is received before the timeout expires, the request
fails and returns an error. Defaults to `30s`.
end::timeout[]

tag::master-timeout[]
`master_timeout`::
(Optional, <<time-units, time units>>) Specifies the period of time to wait for
a connection to the master node. If no response is received before the timeout
expires, the request fails and returns an error. Defaults to `30s`.
end::master-timeout[]

end::timeoutparms[]

tag::transform-id[]
Identifier for the {transform}. This identifier can contain lowercase
alphanumeric characters (a-z and 0-9), hyphens, and underscores. It must start
and end with alphanumeric characters.
end::transform-id[]

tag::transform-id-wildcard[]
Identifier for the {transform}. It can be a {transform} identifier or a wildcard
expression. If you do not specify one of these options, the API returns
information for all {transforms}.
end::transform-id-wildcard[]

tag::cat-v[]
`v`::
(Optional, boolean) If `true`, the response includes column headings. 
Defaults to `false`.
end::cat-v[]

tag::version[]
`version`::
(Optional, boolean) If `true`, returns the document version as part of a hit.
end::version[]

tag::doc-version[]
`version`::
(Optional, integer) Explicit version number for concurrency control.
The specified version must match the current version of the document for the
request to succeed.
end::doc-version[]

tag::segment-version[]
Version of Lucene used to write the segment.
end::segment-version[]

tag::version_type[]
`version_type`::
(Optional, enum) Specific version type: `internal`, `external`,
`external_gte`, `force`.
end::version_type[]

tag::wait_for_active_shards[]
`wait_for_active_shards`::
+
--
(Optional, string) The number of shard copies that must be active before
proceeding with the operation. Set to `all` or any positive integer up
to the total number of shards in the index (`number_of_replicas+1`).
Default: 1, the primary shard.

See <<index-wait-for-active-shards>>.
--
end::wait_for_active_shards[]

tag::wait_for_completion[]
`wait_for_completion`::
(Optional, boolean) If `true`, the request blocks until the operation is complete. 
Defaults to `true`.
end::wait_for_completion[]