The API accepts 3 different authentication methods:
Elasticsearch APIs support key-based authentication. You must create an API key and use the encoded value in the request header. For example:
curl -X GET "${ES_URL}/_cat/indices?v=true" \
-H "Authorization: ApiKey ${API_KEY}"
To get API keys, use the /_security/api_key APIs.
Elasticsearch APIs support the use of bearer tokens in the Authorization HTTP header to authenticate with the API.
For examples, refer to Token-based authentication services
All methods and paths for this operation:
GET _application/analytics/my*
resp = client.search_application.get_behavioral_analytics(
name="my*",
)const response = await client.searchApplication.getBehavioralAnalytics({
name: "my*",
});response = client.search_application.get_behavioral_analytics(
name: "my*"
)$resp = $client->searchApplication()->getBehavioralAnalytics([
"name" => "my*",
]);curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_application/analytics/my*"client.searchApplication().getBehavioralAnalytics(g -> g
.name("my*")
);
{
"my_analytics_collection": {
"event_data_stream": {
"name": "behavioral_analytics-events-my_analytics_collection"
}
},
"my_analytics_collection2": {
"event_data_stream": {
"name": "behavioral_analytics-events-my_analytics_collection2"
}
}
}PUT _application/analytics/my_analytics_collection
resp = client.search_application.put_behavioral_analytics(
name="my_analytics_collection",
)const response = await client.searchApplication.putBehavioralAnalytics({
name: "my_analytics_collection",
});response = client.search_application.put_behavioral_analytics(
name: "my_analytics_collection"
)$resp = $client->searchApplication()->putBehavioralAnalytics([
"name" => "my_analytics_collection",
]);curl -X PUT -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_application/analytics/my_analytics_collection"client.searchApplication().putBehavioralAnalytics(p -> p
.name("my_analytics_collection")
);
The compact and aligned text (CAT) APIs aim are intended only for human consumption using the Kibana console or command line. They are not intended for use by applications. For application consumption, it's recommend to use a corresponding JSON API.
All the cat commands accept a query string parameter help to see all the headers and info they provide, and the /_cat command alone lists all the available commands.
All methods and paths for this operation:
Get the cluster's index aliases, including filter and routing information. This API does not return data stream aliases.
IMPORTANT: CAT APIs are only intended for human consumption using the command line or the Kibana console. They are not intended for use by applications. For application consumption, use the aliases API.
view_index_metadataA comma-separated list of aliases to retrieve. Supports wildcards (*). To retrieve all aliases, omit this parameter or use * or _all.
A comma-separated list of columns names to display. It supports simple wildcards.
Supported values include:
alias (or a): The name of the alias.index (or i, idx): The name of the index the alias points to.filter (or f, fi): The filter applied to the alias.routing.index (or ri, routingIndex): Index routing value for the alias.routing.search (or rs, routingSearch): Search routing value for the alias.is_write_index (or w, isWriteIndex): Indicates if the index is the write index for the alias.Values are alias, a, index, i, idx, filter, f, fi, routing.index, ri, routingIndex, routing.search, rs, routingSearch, is_write_index, w, or isWriteIndex.
List of columns that determine how the table should be sorted.
Sorting defaults to ascending and can be changed by setting :asc
or :desc as a suffix to the column name.
The type of index that wildcard patterns can match.
If the request can target data streams, this argument determines whether wildcard expressions match hidden data streams.
It supports comma-separated values, such as open,hidden.
Supported values include:
all: Match any data stream or index, including hidden ones.open: Match open, non-hidden indices. Also matches any non-hidden data stream.closed: Match closed, non-hidden indices. Also matches any non-hidden data stream. Data streams cannot be closed.hidden: Match hidden data streams and hidden indices. Must be combined with open, closed, or both.none: Wildcard expressions are not accepted.Values are all, open, closed, hidden, or none.
If true, the request computes the list of selected nodes from the
local cluster state. If false the list of selected nodes are computed
from the cluster state of the master node. In both cases the coordinating
node will send requests for further information to each selected node.
GET _cat/aliases?format=json&v=true
resp = client.cat.aliases(
format="json",
v=True,
)const response = await client.cat.aliases({
format: "json",
v: "true",
});response = client.cat.aliases(
format: "json",
v: "true"
)$resp = $client->cat()->aliases([
"format" => "json",
"v" => "true",
]);curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_cat/aliases?format=json&v=true"client.cat().aliases();
[
{
"alias": "alias1",
"index": "test1",
"filter": "-",
"routing.index": "-",
"routing.search": "-",
"is_write_index": "true"
},
{
"alias": "alias1",
"index": "test1",
"filter": "*",
"routing.index": "-",
"routing.search": "-",
"is_write_index": "true"
},
{
"alias": "alias3",
"index": "test1",
"filter": "-",
"routing.index": "1",
"routing.search": "1",
"is_write_index": "true"
},
{
"alias": "alias4",
"index": "test1",
"filter": "-",
"routing.index": "2",
"routing.search": "1,2",
"is_write_index": "true"
}
]All methods and paths for this operation:
Get information about component templates in a cluster. Component templates are building blocks for constructing index templates that specify index mappings, settings, and aliases.
IMPORTANT: CAT APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications. For application consumption, use the get component template API.
monitorThe name of the component template. It accepts wildcard expressions. If it is omitted, all component templates are returned.
A comma-separated list of columns names to display. It supports simple wildcards.
Supported values include:
name (or n): The name of the component template.version (or v): The version number of the component template.alias_count (or a): The number of aliases in the component template.mapping_count (or m): The number of mappings in the component template.settings_count (or s): The number of settings in the component template.metadata_count (or me): The number of metadata entries in the component template.included_in (or i): The index templates that include this component template.Values are name, n, version, v, alias_count, a, mapping_count, m, settings_count, s, metadata_count, me, included_in, or i.
List of columns that determine how the table should be sorted.
Sorting defaults to ascending and can be changed by setting :asc
or :desc as a suffix to the column name.
If true, the request computes the list of selected nodes from the
local cluster state. If false the list of selected nodes are computed
from the cluster state of the master node. In both cases the coordinating
node will send requests for further information to each selected node.
The period to wait for a connection to the master node.
Values are -1 or 0.
GET _cat/component_templates/my-template-*?v=true&s=name&format=json
resp = client.cat.component_templates(
name="my-template-*",
v=True,
s="name",
format="json",
)const response = await client.cat.componentTemplates({
name: "my-template-*",
v: "true",
s: "name",
format: "json",
});response = client.cat.component_templates(
name: "my-template-*",
v: "true",
s: "name",
format: "json"
)$resp = $client->cat()->componentTemplates([
"name" => "my-template-*",
"v" => "true",
"s" => "name",
"format" => "json",
]);curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_cat/component_templates/my-template-*?v=true&s=name&format=json"client.cat().componentTemplates();
[
{
"name": "my-template-1",
"version": "null",
"alias_count": "0",
"mapping_count": "0",
"settings_count": "1",
"metadata_count": "0",
"included_in": "[my-index-template]"
},
{
"name": "my-template-2",
"version": null,
"alias_count": "0",
"mapping_count": "3",
"settings_count": "0",
"metadata_count": "0",
"included_in": "[my-index-template]"
}
]All methods and paths for this operation:
Get quick access to a document count for a data stream, an index, or an entire cluster. The document count only includes live documents, not deleted documents which have not yet been removed by the merge process.
IMPORTANT: CAT APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications. For application consumption, use the count API.
readA comma-separated list of data streams, indices, and aliases used to limit the request.
It supports wildcards (*).
To target all data streams and indices, omit this parameter or use * or _all.
A comma-separated list of columns names to display. It supports simple wildcards.
Supported values include:
epoch (or t, time): The Unix epoch time in seconds since 1970-01-01 00:00:00.timestamp (or ts, hms, hhmmss): The current time in HH:MM:SS format.count (or dc, docs.count, docsCount): The document count in the cluster or index.Values are epoch, t, time, timestamp, ts, hms, hhmmss, count, dc, docs.count, or docsCount.
List of columns that determine how the table should be sorted.
Sorting defaults to ascending and can be changed by setting :asc
or :desc as a suffix to the column name.
GET /_cat/count/my-index-000001?v=true&format=json
resp = client.cat.count(
index="my-index-000001",
v=True,
format="json",
)const response = await client.cat.count({
index: "my-index-000001",
v: "true",
format: "json",
});response = client.cat.count(
index: "my-index-000001",
v: "true",
format: "json"
)$resp = $client->cat()->count([
"index" => "my-index-000001",
"v" => "true",
"format" => "json",
]);curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_cat/count/my-index-000001?v=true&format=json"client.cat().count();
[
{
"epoch": "1475868259",
"timestamp": "15:24:20",
"count": "120"
}
][
{
"epoch": "1475868259",
"timestamp": "15:24:20",
"count": "121"
}
]curl \
--request GET 'http://api.example.com/_cat' \
--header "Authorization: $API_KEY"All methods and paths for this operation:
Get configuration and usage information about datafeeds.
This API returns a maximum of 10,000 datafeeds.
If the Elasticsearch security features are enabled, you must have monitor_ml, monitor, manage_ml, or manage
cluster privileges to use this API.
IMPORTANT: CAT APIs are only intended for human consumption using the Kibana console or command line. They are not intended for use by applications. For application consumption, use the get datafeed statistics API.
monitor_mlSpecifies what to do when the request:
_all string or no identifiers and there are no matches.If true, the API returns an empty datafeeds array when there are no matches and the subset of results when
there are partial matches. If false, the API returns a 404 status code when there are no matches or only
partial matches.
Comma-separated list of column names to display.
Supported values include:
ae (or assignment_explanation): For started datafeeds only, contains messages relating to the selection of
a node.bc (or buckets.count, bucketsCount): The number of buckets processed.id: A numerical character string that uniquely identifies the datafeed.na (or node.address, nodeAddress): For started datafeeds only, the network address of the node where the
datafeed is started.ne (or node.ephemeral_id, nodeEphemeralId): For started datafeeds only, the ephemeral ID of the node where the
datafeed is started.ni (or node.id, nodeId): For started datafeeds only, the unique identifier of the node where the
datafeed is started.nn (or node.name, nodeName): For started datafeeds only, the name of the node where the datafeed is
started.sba (or search.bucket_avg, searchBucketAvg): The average search time per bucket, in milliseconds.sc (or search.count, searchCount): The number of searches run by the datafeed.seah (or search.exp_avg_hour, searchExpAvgHour): The exponential average search time per hour, in milliseconds.st (or search.time, searchTime): The total time the datafeed spent searching, in milliseconds.s (or state): The status of the datafeed: starting, started, stopping, or stopped.
If starting, the datafeed has been requested to start but has not yet
started. If started, the datafeed is actively receiving data. If
stopping, the datafeed has been requested to stop gracefully and is
completing its final action. If stopped, the datafeed is stopped and will
not receive data until it is re-started.Comma-separated list of column names or column aliases used to sort the response.
Supported values include:
ae (or assignment_explanation): For started datafeeds only, contains messages relating to the selection of
a node.bc (or buckets.count, bucketsCount): The number of buckets processed.id: A numerical character string that uniquely identifies the datafeed.na (or node.address, nodeAddress): For started datafeeds only, the network address of the node where the
datafeed is started.ne (or node.ephemeral_id, nodeEphemeralId): For started datafeeds only, the ephemeral ID of the node where the
datafeed is started.ni (or node.id, nodeId): For started datafeeds only, the unique identifier of the node where the
datafeed is started.nn (or node.name, nodeName): For started datafeeds only, the name of the node where the datafeed is
started.sba (or search.bucket_avg, searchBucketAvg): The average search time per bucket, in milliseconds.sc (or search.count, searchCount): The number of searches run by the datafeed.seah (or search.exp_avg_hour, searchExpAvgHour): The exponential average search time per hour, in milliseconds.st (or search.time, searchTime): The total time the datafeed spent searching, in milliseconds.s (or state): The status of the datafeed: starting, started, stopping, or stopped.
If starting, the datafeed has been requested to start but has not yet
started. If started, the datafeed is actively receiving data. If
stopping, the datafeed has been requested to stop gracefully and is
completing its final action. If stopped, the datafeed is stopped and will
not receive data until it is re-started.The unit used to display time values.
Values are nanos, micros, ms, s, m, h, or d.
GET _cat/ml/datafeeds?v=true&format=json
resp = client.cat.ml_datafeeds(
v=True,
format="json",
)const response = await client.cat.mlDatafeeds({
v: "true",
format: "json",
});response = client.cat.ml_datafeeds(
v: "true",
format: "json"
)$resp = $client->cat()->mlDatafeeds([
"v" => "true",
"format" => "json",
]);curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_cat/ml/datafeeds?v=true&format=json"client.cat().mlDatafeeds();
[
{
"id": "datafeed-high_sum_total_sales",
"state": "stopped",
"buckets.count": "743",
"search.count": "7"
},
{
"id": "datafeed-low_request_rate",
"state": "stopped",
"buckets.count": "1457",
"search.count": "3"
},
{
"id": "datafeed-response_code_rates",
"state": "stopped",
"buckets.count": "1460",
"search.count": "18"
},
{
"id": "datafeed-url_scanning",
"state": "stopped",
"buckets.count": "1460",
"search.count": "18"
}
]All methods and paths for this operation:
Get configuration and usage information about inference trained models.
IMPORTANT: CAT APIs are only intended for human consumption using the Kibana console or command line. They are not intended for use by applications. For application consumption, use the get trained models statistics API.
monitor_mlSpecifies what to do when the request: contains wildcard expressions and there are no models that match; contains the _all string or no identifiers and there are no matches; contains wildcard expressions and there are only partial matches.
If true, the API returns an empty array when there are no matches and the subset of results when there are partial matches.
If false, the API returns a 404 status code when there are no matches or only partial matches.
The unit used to display byte values.
Values are b, kb, mb, gb, tb, or pb.
A comma-separated list of column names to display.
Supported values include:
create_time (or ct): The time when the trained model was created.created_by (or c, createdBy): Information on the creator of the trained model.data_frame_analytics_id (or df, dataFrameAnalytics, dfid): Identifier for the data frame analytics job that created the model. Only
displayed if it is still available.description (or d): The description of the trained model.heap_size (or hs, modelHeapSize): The estimated heap size to keep the trained model in memory.id: Identifier for the trained model.ingest.count (or ic, ingestCount): The total number of documents that are processed by the model.ingest.current (or icurr, ingestCurrent): The total number of document that are currently being handled by the
trained model.ingest.failed (or if, ingestFailed): The total number of failed ingest attempts with the trained model.ingest.pipelines (or ip, ingestPipelines): The total number of ingest pipelines that are referencing the trained
model.ingest.time (or it, ingestTime): The total time that is spent processing documents with the trained model.license (or l): The license level of the trained model.operations (or o, modelOperations): The estimated number of operations to use the trained model. This number
helps measuring the computational complexity of the model.version (or v): The Elasticsearch version number in which the trained model was created.A comma-separated list of column names or aliases used to sort the response.
Supported values include:
create_time (or ct): The time when the trained model was created.created_by (or c, createdBy): Information on the creator of the trained model.data_frame_analytics_id (or df, dataFrameAnalytics, dfid): Identifier for the data frame analytics job that created the model. Only
displayed if it is still available.description (or d): The description of the trained model.heap_size (or hs, modelHeapSize): The estimated heap size to keep the trained model in memory.id: Identifier for the trained model.ingest.count (or ic, ingestCount): The total number of documents that are processed by the model.ingest.current (or icurr, ingestCurrent): The total number of document that are currently being handled by the
trained model.ingest.failed (or if, ingestFailed): The total number of failed ingest attempts with the trained model.ingest.pipelines (or ip, ingestPipelines): The total number of ingest pipelines that are referencing the trained
model.ingest.time (or it, ingestTime): The total time that is spent processing documents with the trained model.license (or l): The license level of the trained model.operations (or o, modelOperations): The estimated number of operations to use the trained model. This number
helps measuring the computational complexity of the model.version (or v): The Elasticsearch version number in which the trained model was created.Skips the specified number of transforms.
The maximum number of transforms to display.
Unit used to display time values.
Values are nanos, micros, ms, s, m, h, or d.
GET _cat/ml/trained_models?v=true&format=json
resp = client.cat.ml_trained_models(
v=True,
format="json",
)const response = await client.cat.mlTrainedModels({
v: "true",
format: "json",
});response = client.cat.ml_trained_models(
v: "true",
format: "json"
)$resp = $client->cat()->mlTrainedModels([
"v" => "true",
"format" => "json",
]);curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_cat/ml/trained_models?v=true&format=json"client.cat().mlTrainedModels();
[
{
"id": "ddddd-1580216177138",
"heap_size": "0b",
"operations": "196",
"create_time": "2025-03-25T00:01:38.662Z",
"type": "pytorch",
"ingest.pipelines": "0",
"data_frame.id": "__none__"
},
{
"id": "lang_ident_model_1",
"heap_size": "1mb",
"operations": "39629",
"create_time": "2019-12-05T12:28:34.594Z",
"type": "lang_ident",
"ingest.pipelines": "0",
"data_frame.id": "__none__"
}
]Get a list of plugins running on each node of a cluster. IMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications. For application consumption, use the nodes info API.
monitorList of columns to appear in the response. Supports simple wildcards.
List of columns that determine how the table should be sorted.
Sorting defaults to ascending and can be changed by setting :asc
or :desc as a suffix to the column name.
Include bootstrap plugins in the response
If true, the request computes the list of selected nodes from the
local cluster state. If false the list of selected nodes are computed
from the cluster state of the master node. In both cases the coordinating
node will send requests for further information to each selected node.
Period to wait for a connection to the master node.
Values are -1 or 0.
GET /_cat/plugins?v=true&s=component&h=name,component,version,description&format=json
resp = client.cat.plugins(
v=True,
s="component",
h="name,component,version,description",
format="json",
)const response = await client.cat.plugins({
v: "true",
s: "component",
h: "name,component,version,description",
format: "json",
});response = client.cat.plugins(
v: "true",
s: "component",
h: "name,component,version,description",
format: "json"
)$resp = $client->cat()->plugins([
"v" => "true",
"s" => "component",
"h" => "name,component,version,description",
"format" => "json",
]);curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_cat/plugins?v=true&s=component&h=name,component,version,description&format=json"client.cat().plugins();
[
{ "name": "U7321H6", "component": "analysis-icu", "version": "8.17.0", "description": "The ICU Analysis plugin integrates the Lucene ICU module into Elasticsearch, adding ICU-related analysis components."},
{"name": "U7321H6", "component": "analysis-kuromoji", "verison": "8.17.0", description: "The Japanese (kuromoji) Analysis plugin integrates Lucene kuromoji analysis module into elasticsearch."},
{"name" "U7321H6", "component": "analysis-nori", "version": "8.17.0", "description": "The Korean (nori) Analysis plugin integrates Lucene nori analysis module into elasticsearch."},
{"name": "U7321H6", "component": "analysis-phonetic", "verison": "8.17.0", "description": "The Phonetic Analysis plugin integrates phonetic token filter analysis with elasticsearch."},
{"name": "U7321H6", "component": "analysis-smartcn", "verison": "8.17.0", "description": "Smart Chinese Analysis plugin integrates Lucene Smart Chinese analysis module into elasticsearch."},
{"name": "U7321H6", "component": "analysis-stempel", "verison": "8.17.0", "description": "The Stempel (Polish) Analysis plugin integrates Lucene stempel (polish) analysis module into elasticsearch."},
{"name": "U7321H6", "component": "analysis-ukrainian", "verison": "8.17.0", "description": "The Ukrainian Analysis plugin integrates the Lucene UkrainianMorfologikAnalyzer into elasticsearch."},
{"name": "U7321H6", "component": "discovery-azure-classic", "verison": "8.17.0", "description": "The Azure Classic Discovery plugin allows to use Azure Classic API for the unicast discovery mechanism"},
{"name": "U7321H6", "component": "discovery-ec2", "verison": "8.17.0", "description": "The EC2 discovery plugin allows to use AWS API for the unicast discovery mechanism."},
{"name": "U7321H6", "component": "discovery-gce", "verison": "8.17.0", "description": "The Google Compute Engine (GCE) Discovery plugin allows to use GCE API for the unicast discovery mechanism."},
{"name": "U7321H6", "component": "mapper-annotated-text", "verison": "8.17.0", "description": "The Mapper Annotated_text plugin adds support for text fields with markup used to inject annotation tokens into the index."},
{"name": "U7321H6", "component": "mapper-murmur3", "verison": "8.17.0", "description": "The Mapper Murmur3 plugin allows to compute hashes of a field's values at index-time and to store them in the index."},
{"name": "U7321H6", "component": "mapper-size", "verison": "8.17.0", "description": "The Mapper Size plugin allows document to record their uncompressed size at index time."},
{"name": "U7321H6", "component": "store-smb", "verison": "8.17.0", "description": "The Store SMB plugin adds support for SMB stores."}
]All methods and paths for this operation:
Get information about ongoing and completed shard recoveries. Shard recovery is the process of initializing a shard copy, such as restoring a primary shard from a snapshot or syncing a replica shard from a primary shard. When a shard recovery completes, the recovered shard is available for search and indexing. For data streams, the API returns information about the stream’s backing indices. IMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications. For application consumption, use the index recovery API.
monitormonitorA comma-separated list of data streams, indices, and aliases used to limit the request.
Supports wildcards (*). To target all data streams and indices, omit this parameter or use * or _all.
If true, the response only includes ongoing shard recoveries.
The unit used to display byte values.
Values are b, kb, mb, gb, tb, or pb.
If true, the response includes detailed information about shard recoveries.
Comma-separated list or wildcard expression of index names to limit the returned information
A comma-separated list of columns names to display. It supports simple wildcards.
Supported values include:
index (or i, idx): The name of the index.shard (or s, sh): The name of the shard.time (or t, ti, primaryOrReplica): The recovery time elasped.type: The type of recovery, from a peer or a snapshot.stage (or st): The stage of the recovery. Returned values are: INIT, INDEX: recovery of lucene files, either reusing local ones are copying new ones, VERIFY_INDEX: potentially running check index, TRANSLOG: starting up the engine, replaying the translog, FINALIZE: performing final task after all translog ops have been done, DONEsource_host (or shost): The host address the index is moving from.source_node (or snode): The node name the index is moving from.target_host (or thost): The host address the index is moving to.target_node (or tnode): The node name the index is moving to.repository (or tnode): The name of the repository being used. if not relevant 'n/a'.snapshot (or snap): The name of the snapshot being used. if not relevant 'n/a'.files (or f): The total number of files to recover.files_recovered (or fr): The number of files currently recovered.files_percent (or fp): The percentage of files currently recovered.files_total (or tf): The total number of files.bytes (or b): The total number of bytes to recover.bytes_recovered (or br): Total number of bytes currently recovered.bytes_percent (or bp): The percentage of bytes currently recovered.bytes_total (or tb): The total number of bytes.translog_ops (or to): The total number of translog ops to recover.translog_ops_recovered (or tor): The total number of translog ops currently recovered.translog_ops_percent (or top): The percentage of translog ops currently recovered.start_time (or start): The start time of the recovery operation.start_time_millis (or start_millis): The start time of the recovery operation in eopch milliseconds.stop_time (or stop): The end time of the recovery operation. If ongoing '1970-01-01T00:00:00.000Z'stop_time_millis (or stop_millis): The end time of the recovery operation in eopch milliseconds. If ongoing '0'Values are index, i, idx, shard, s, sh, time, t, ti, primaryOrReplica, type, stage, st, source_host, shost, source_node, snode, target_host, thost, target_node, tnode, repository, snapshot, snap, files, f, files_recovered, fr, files_percent, fp, files_total, tf, bytes, b, bytes_recovered, br, bytes_percent, bp, bytes_total, tb, translog_ops, to, translog_ops_recovered, tor, translog_ops_percent, top, start_time, start, start_time_millis, start_millis, stop_time, stop, stop_time_millis, or stop_millis.
A comma-separated list of column names or aliases that determines the sort order.
Sorting defaults to ascending and can be changed by setting :asc
or :desc as a suffix to the column name.
The unit used to display time values.
Values are nanos, micros, ms, s, m, h, or d.
GET _cat/recovery?v=true&format=json
resp = client.cat.recovery(
v=True,
format="json",
)const response = await client.cat.recovery({
v: "true",
format: "json",
});response = client.cat.recovery(
v: "true",
format: "json"
)$resp = $client->cat()->recovery([
"v" => "true",
"format" => "json",
]);curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_cat/recovery?v=true&format=json"client.cat().recovery();
[
{
"index": "my-index-000001 ",
"shard": "0",
"time": "13ms",
"type": "store",
"stage": "done",
"source_host": "n/a",
"source_node": "n/a",
"target_host": "127.0.0.1",
"target_node": "node-0",
"repository": "n/a",
"snapshot": "n/a",
"files": "0",
"files_recovered": "0",
"files_percent": "100.0%",
"files_total": "13",
"bytes": "0b",
"bytes_recovered": "0b",
"bytes_percent": "100.0%",
"bytes_total": "9928b",
"translog_ops": "0",
"translog_ops_recovered": "0",
"translog_ops_percent": "100.0%"
}
][
{
"i": "my-index-000001",
"s": "0",
"t": "1252ms",
"ty": "peer",
"st": "done",
"shost": "192.168.1.1",
"thost": "192.168.1.1",
"f": "0",
"fp": "100.0%",
"b": "0b",
"bp": "100.0%",
}
][
{
"i": "my-index-000001",
"s": "0",
"t": "1978ms",
"ty": "snapshot",
"st": "done",
"rep": "my-repo",
"snap": "snap-1",
"f": "79",
"fp": "8.0%",
"b": "12086",
"bp": "9.0%"
}
]Get a list of snapshot repositories for a cluster. IMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications. For application consumption, use the get snapshot repository API.
monitor_snapshotList of columns to appear in the response. Supports simple wildcards.
List of columns that determine how the table should be sorted.
Sorting defaults to ascending and can be changed by setting :asc
or :desc as a suffix to the column name.
If true, the request computes the list of selected nodes from the
local cluster state. If false the list of selected nodes are computed
from the cluster state of the master node. In both cases the coordinating
node will send requests for further information to each selected node.
Period to wait for a connection to the master node.
Values are -1 or 0.
GET /_cat/repositories?v=true&format=json
resp = client.cat.repositories(
v=True,
format="json",
)const response = await client.cat.repositories({
v: "true",
format: "json",
});response = client.cat.repositories(
v: "true",
format: "json"
)$resp = $client->cat()->repositories([
"v" => "true",
"format" => "json",
]);curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_cat/repositories?v=true&format=json"client.cat().repositories();
[
{
"id": "repo1",
"type": "fs"
},
{
"id": "repo2",
"type": "s3"
}
]All methods and paths for this operation:
Get information about the shards in a cluster. For data streams, the API returns information about the backing indices. IMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications.
monitormonitorA comma-separated list of data streams, indices, and aliases used to limit the request.
Supports wildcards (*).
To target all data streams and indices, omit this parameter or use * or _all.
The unit used to display byte values.
Values are b, kb, mb, gb, tb, or pb.
List of columns to appear in the response. Supports simple wildcards.
Supported values include:
completion.size (or cs, completionSize): Size of completion. For example: 0b.dataset.size: Disk space used by the shard’s dataset, which may or may not be the size on
disk, but includes space used by the shard on object storage. Reported as a size value for example: 5kb.dense_vector.value_count (or dvc, denseVectorCount): Number of indexed dense vectors.docs (or d, dc): Number of documents in shard, for example: 25.fielddata.evictions (or fe, fielddataEvictions): Fielddata cache evictions, for example: 0.fielddata.memory_size (or fm, fielddataMemory): Used fielddata cache memory, for example: 0b.flush.total (or ft, flushTotal): Number of flushes, for example: 1.flush.total_time (or ftt, flushTotalTime): Time spent in flush, for example: 1.get.current (or gc, getCurrent): Number of current get operations, for example: 0.get.exists_time (or geti, getExistsTime): Time spent in successful gets, for example: 14ms.get.exists_total (or geto, getExistsTotal): Number of successful get operations, for example: 2.get.missing_time (or gmti, getMissingTime): Time spent in failed gets, for example: 0s.get.missing_total (or gmto, getMissingTotal): Number of failed get operations, for example: 1.get.time (or gti, getTime): Time spent in get, for example: 14ms.get.total (or gto, getTotal): Number of get operations, for example: 2.id: ID of the node, for example: k0zy.index (or i, idx): Name of the index.indexing.delete_current (or idc, indexingDeleteCurrent): Number of current deletion operations, for example: 0.indexing.delete_time (or idti, indexingDeleteTime): Time spent in deletions, for example: 2ms.indexing.delete_total (or idto, indexingDeleteTotal): Number of deletion operations, for example: 2.indexing.index_current (or iic, indexingIndexCurrent): Number of current indexing operations, for example: 0.indexing.index_failed_due_to_version_conflict (or iifvc, indexingIndexFailedDueToVersionConflict): Number of failed indexing operations due to version conflict, for example: 0.indexing.index_failed (or iif, indexingIndexFailed): Number of failed indexing operations, for example: 0.indexing.index_time (or iiti, indexingIndexTime): Time spent in indexing, such as for example: 134ms.indexing.index_total (or iito, indexingIndexTotal): Number of indexing operations, for example: 1.ip: IP address of the node, for example: 127.0.1.1.merges.current (or mc, mergesCurrent): Number of current merge operations, for example: 0.merges.current_docs (or mcd, mergesCurrentDocs): Number of current merging documents, for example: 0.merges.current_size (or mcs, mergesCurrentSize): Size of current merges, for example: 0b.merges.total (or mt, mergesTotal): Number of completed merge operations, for example: 0.merges.total_docs (or mtd, mergesTotalDocs): Number of merged documents, for example: 0.merges.total_size (or mts, mergesTotalSize): Size of current merges, for example: 0b.merges.total_time (or mtt, mergesTotalTime): Time spent merging documents, for example: 0s.node (or n): Node name, for example: I8hydUG.prirep (or p, pr, primaryOrReplica): Shard type. Returned values are primary or replica.query_cache.evictions (or qce, queryCacheEvictions): Query cache evictions, for example: 0.query_cache.memory_size (or qcm, queryCacheMemory): Used query cache memory, for example: 0b.recoverysource.type (or rs): Type of recovery source.refresh.time (or rti, refreshTime): Time spent in refreshes, for example: 91ms.refresh.total (or rto, refreshTotal): Number of refreshes, for example: 16.search.fetch_current (or sfc, searchFetchCurrent): Current fetch phase operations, for example: 0.search.fetch_time (or sfti, searchFetchTime): Time spent in fetch phase, for example: 37ms.search.fetch_total (or sfto, searchFetchTotal): Number of fetch operations, for example: 7.search.open_contexts (or so, searchOpenContexts): Open search contexts, for example: 0.search.query_current (or sqc, searchQueryCurrent): Current query phase operations, for example: 0.search.query_time (or sqti, searchQueryTime): Time spent in query phase, for example: 43ms.search.query_total (or sqto, searchQueryTotal): Number of query operations, for example: 9.search.scroll_current (or scc, searchScrollCurrent): Open scroll contexts, for example: 2.search.scroll_time (or scti, searchScrollTime): Time scroll contexts held open, for example: 2m.search.scroll_total (or scto, searchScrollTotal): Completed scroll contexts, for example: 1.segments.count (or sc, segmentsCount): Number of segments, for example: 4.segments.fixed_bitset_memory (or sfbm, fixedBitsetMemory): Memory used by fixed bit sets for nested object field types and type filters for types referred in join fields, for example: 1.0kb.segments.index_writer_memory (or siwm, segmentsIndexWriterMemory): Memory used by index writer, for example: 18mb.segments.memory (or sm, segmentsMemory): Memory used by segments, for example: 1.4kb.segments.version_map_memory (or svmm, segmentsVersionMapMemory): Memory used by version map, for example: 1.0kb.seq_no.global_checkpoint (or sqg, globalCheckpoint): Global checkpoint.seq_no.local_checkpoint (or sql, localCheckpoint): Local checkpoint.seq_no.max (or sqm, maxSeqNo): Maximum sequence number.shard (or s, sh): Name of the shard.dsparse_vector.value_count (or svc, sparseVectorCount): Number of indexed sparse vectors.state (or st): State of the shard. Returned values are:
INITIALIZING: The shard is recovering from a peer shard or gateway.RELOCATING: The shard is relocating.STARTED: The shard has started.UNASSIGNED: The shard is not assigned to any node.store (or sto): Disk space used by the shard, for example: 5kb.suggest.current (or suc, suggestCurrent): Number of current suggest operations, for example: 0.suggest.time (or suti, suggestTime): Time spent in suggest, for example: 0.suggest.total (or suto, suggestTotal): Number of suggest operations, for example: 0.sync_id: Sync ID of the shard.unassigned.at (or ua): Time at which the shard became unassigned in Coordinated Universal Time (UTC).unassigned.details (or ud): Details about why the shard became unassigned. This does not explain why the shard is currently unassigned. To understand why a shard
is not assigned, use the Cluster allocation explain API.unassigned.for (or uf): Time at which the shard was requested to be unassigned in Coordinated Universal Time (UTC).unassigned.reason (or ur): Indicates the reason for the last change to the state of this unassigned shard. This does not explain why the shard is currently unassigned.
To understand why a shard is not assigned, use the Cluster allocation explain API. Returned values include:
ALLOCATION_FAILED: Unassigned as a result of a failed allocation of the shard.CLUSTER_RECOVERED: Unassigned as a result of a full cluster recovery.DANGLING_INDEX_IMPORTED: Unassigned as a result of importing a dangling index.EXISTING_INDEX_RESTORED: Unassigned as a result of restoring into a closed index.FORCED_EMPTY_PRIMARY: The shard’s allocation was last modified by forcing an empty primary using the Cluster reroute API.INDEX_CLOSED: Unassigned because the index was closed.INDEX_CREATED: Unassigned as a result of an API creation of an index.INDEX_REOPENED: Unassigned as a result of opening a closed index.MANUAL_ALLOCATION: The shard’s allocation was last modified by the Cluster reroute API.NEW_INDEX_RESTORED: Unassigned as a result of restoring into a new index.NODE_LEFT: Unassigned as a result of the node hosting it leaving the cluster.NODE_RESTARTING: Similar to NODE_LEFT, except that the node was registered as restarting using the Node shutdown API.PRIMARY_FAILED: The shard was initializing as a replica, but the primary shard failed before the initialization completed.REALLOCATED_REPLICA: A better replica location is identified and causes the existing replica allocation to be cancelled.REINITIALIZED: When a shard moves from started back to initializing.REPLICA_ADDED: Unassigned as a result of explicit addition of a replica.REROUTE_CANCELLED: Unassigned as a result of explicit cancel reroute command.Values are completion.size, cs, completionSize, dataset.size, dense_vector.value_count, dvc, denseVectorCount, docs, d, dc, fielddata.evictions, fe, fielddataEvictions, fielddata.memory_size, fm, fielddataMemory, flush.total, ft, flushTotal, flush.total_time, ftt, flushTotalTime, get.current, gc, getCurrent, get.exists_time, geti, getExistsTime, get.exists_total, geto, getExistsTotal, get.missing_time, gmti, getMissingTime, get.missing_total, gmto, getMissingTotal, get.time, gti, getTime, get.total, gto, getTotal, id, index, i, idx, indexing.delete_current, idc, indexingDeleteCurrent, indexing.delete_time, idti, indexingDeleteTime, indexing.delete_total, idto, indexingDeleteTotal, indexing.index_current, iic, indexingIndexCurrent, indexing.index_failed_due_to_version_conflict, iifvc, indexingIndexFailedDueToVersionConflict, indexing.index_failed, iif, indexingIndexFailed, indexing.index_time, iiti, indexingIndexTime, indexing.index_total, iito, indexingIndexTotal, ip, merges.current, mc, mergesCurrent, merges.current_docs, mcd, mergesCurrentDocs, merges.current_size, mcs, mergesCurrentSize, merges.total, mt, mergesTotal, merges.total_docs, mtd, mergesTotalDocs, merges.total_size, mts, mergesTotalSize, merges.total_time, mtt, mergesTotalTime, node, n, prirep, p, pr, primaryOrReplica, query_cache.evictions, qce, queryCacheEvictions, query_cache.memory_size, qcm, queryCacheMemory, recoverysource.type, rs, refresh.time, rti, refreshTime, refresh.total, rto, refreshTotal, search.fetch_current, sfc, searchFetchCurrent, search.fetch_time, sfti, searchFetchTime, search.fetch_total, sfto, searchFetchTotal, search.open_contexts, so, searchOpenContexts, search.query_current, sqc, searchQueryCurrent, search.query_time, sqti, searchQueryTime, search.query_total, sqto, searchQueryTotal, search.scroll_current, scc, searchScrollCurrent, search.scroll_time, scti, searchScrollTime, search.scroll_total, scto, searchScrollTotal, segments.count, sc, segmentsCount, segments.fixed_bitset_memory, sfbm, fixedBitsetMemory, segments.index_writer_memory, siwm, segmentsIndexWriterMemory, segments.memory, sm, segmentsMemory, segments.version_map_memory, svmm, segmentsVersionMapMemory, seq_no.global_checkpoint, sqg, globalCheckpoint, seq_no.local_checkpoint, sql, localCheckpoint, seq_no.max, sqm, maxSeqNo, shard, s, sh, dsparse_vector.value_count, svc, sparseVectorCount, state, st, store, sto, suggest.current, suc, suggestCurrent, suggest.time, suti, suggestTime, suggest.total, suto, suggestTotal, sync_id, unassigned.at, ua, unassigned.details, ud, unassigned.for, uf, unassigned.reason, or ur.
A comma-separated list of column names or aliases that determines the sort order.
Sorting defaults to ascending and can be changed by setting :asc
or :desc as a suffix to the column name.
The period to wait for a connection to the master node.
Values are -1 or 0.
The unit used to display time values.
Values are nanos, micros, ms, s, m, h, or d.
GET _cat/shards?format=json
resp = client.cat.shards(
format="json",
)const response = await client.cat.shards({
format: "json",
});response = client.cat.shards(
format: "json"
)$resp = $client->cat()->shards([
"format" => "json",
]);curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_cat/shards?format=json"client.cat().shards();
[
{
"index": "my-index-000001",
"shard": "0",
"prirep": "p",
"state": "STARTED",
"docs": "3014",
"store": "31.1mb",
"dataset": "249b",
"ip": "192.168.56.10",
"node": "H5dfFeA"
}
][
{
"index": "my-index-000001",
"shard": "0",
"prirep": "p",
"state": "STARTED",
"docs": "3014",
"store": "31.1mb",
"dataset": "249b",
"ip": "192.168.56.10",
"node": "H5dfFeA"
}
][
{
"index": "my-index-000001",
"shard": "0",
"prirep": "p",
"state": "RELOCATING",
"docs": "3014",
"store": "31.1mb",
"dataset": "249b",
"ip": "192.168.56.10",
"node": "H5dfFeA -> -> 192.168.56.30 bGG90GE"
}
][
{
"index": "my-index-000001",
"shard": "0",
"prirep": "p",
"state": "STARTED",
"docs": "3014",
"store": "31.1mb",
"dataset": "249b",
"ip": "192.168.56.10",
"node": "H5dfFeA"
},
{
"index": "my-index-000001",
"shard": "0",
"prirep": "r",
"state": "INITIALIZING",
"docs": "0",
"store": "14.3mb",
"dataset": "249b",
"ip": "192.168.56.30",
"node": "bGG90GE"
}
][
{
"index": "my-index-000001",
"shard": "0",
"prirep": "p",
"state": "STARTED",
"unassigned.reason": "3014 31.1mb 192.168.56.10 H5dfFeA"
},
{
"index": "my-index-000001",
"shard": "0",
"prirep": "r",
"state": "STARTED",
"unassigned.reason": "3014 31.1mb 192.168.56.30 bGG90GE"
},
{
"index": "my-index-000001",
"shard": "0",
"prirep": "r",
"state": "STARTED",
"unassigned.reason": "3014 31.1mb 192.168.56.20 I8hydUG"
},
{
"index": "my-index-000001",
"shard": "0",
"prirep": "r",
"state": "UNASSIGNED",
"unassigned.reason": "ALLOCATION_FAILED"
}
]All methods and paths for this operation:
Get information about the snapshots stored in one or more repositories. A snapshot is a backup of an index or running Elasticsearch cluster. IMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications. For application consumption, use the get snapshot API.
monitor_snapshotA comma-separated list of snapshot repositories used to limit the request.
Accepts wildcard expressions.
_all returns all repositories.
If any repository fails during the request, Elasticsearch returns an error.
A comma-separated list of columns names to display. It supports simple wildcards.
Supported values include:
id (or snapshot): The ID of the snapshot, such as 'snap1'.repository (or re, repo): The name of the repository, such as 'repo1'.status (or s): State of the snapshot process. Returned values are: 'FAILED': The snapshot process failed. 'INCOMPATIBLE': The snapshot process is incompatible with the current cluster version. 'IN_PROGRESS': The snapshot process started but has not completed. 'PARTIAL': The snapshot process completed with a partial success. 'SUCCESS': The snapshot process completed with a full success.start_epoch (or ste, startEpoch): The unix epoch time at which the snapshot process started.start_time (or sti, startTime): 'HH:MM:SS' time at which the snapshot process started.end_epoch (or ete, endEpoch): The unix epoch time at which the snapshot process ended.end_time (or eti, endTime): 'HH:MM:SS' time at which the snapshot process ended.duration (or dur): The time it took the snapshot process to complete in time units.indices (or i): The number of indices in the snapshot.successful_shards (or ss): The number of successful shards in the snapshot.failed_shards (or fs): The number of failed shards in the snapshot.total_shards (or ts): The total number of shards in the snapshot.reason (or r): The reason for any snapshot failures.Values are id, snapshot, repository, re, repo, status, s, start_epoch, ste, startEpoch, start_time, sti, startTime, end_epoch, ete, endEpoch, end_time, eti, endTime, duration, dur, indices, i, successful_shards, ss, failed_shards, fs, total_shards, ts, reason, or r.
List of columns that determine how the table should be sorted.
Sorting defaults to ascending and can be changed by setting :asc
or :desc as a suffix to the column name.
Period to wait for a connection to the master node.
Values are -1 or 0.
Unit used to display time values.
Values are nanos, micros, ms, s, m, h, or d.
GET /_cat/snapshots/repo1?v=true&s=id&format=json
resp = client.cat.snapshots(
repository="repo1",
v=True,
s="id",
format="json",
)const response = await client.cat.snapshots({
repository: "repo1",
v: "true",
s: "id",
format: "json",
});response = client.cat.snapshots(
repository: "repo1",
v: "true",
s: "id",
format: "json"
)$resp = $client->cat()->snapshots([
"repository" => "repo1",
"v" => "true",
"s" => "id",
"format" => "json",
]);curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_cat/snapshots/repo1?v=true&s=id&format=json"client.cat().snapshots();
[
{
"id": "snap1",
"repository": "repo1",
"status": "FAILED",
"start_epoch": "1445616705",
"start_time": "18:11:45",
"end_epoch": "1445616978",
"end_time": "18:16:18",
"duration": "4.6m",
"indices": "1",
"successful_shards": "4",
"failed_shards": "1",
"total_shards": "5"
},
{
"id": "snap2",
"repository": "repo1",
"status": "SUCCESS",
"start_epoch": "1445634298",
"start_time": "23:04:58",
"end_epoch": "1445634672",
"end_time": "23:11:12",
"duration": "6.2m",
"indices": "2",
"successful_shards": "10",
"failed_shards": "0",
"total_shards": "10"
}
]Get information about tasks currently running in the cluster. IMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications. For application consumption, use the task management API.
monitorThe task action names, which are used to limit the response.
If true, the response includes detailed information about shard recoveries.
Unique node identifiers, which are used to limit the response.
The parent task identifier, which is used to limit the response.
List of columns to appear in the response. Supports simple wildcards.
List of columns that determine how the table should be sorted.
Sorting defaults to ascending and can be changed by setting :asc
or :desc as a suffix to the column name.
Unit used to display time values.
Values are nanos, micros, ms, s, m, h, or d.
Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error.
Values are -1 or 0.
If true, the request blocks until the task has completed.
GET _cat/tasks?v=true&format=json
resp = client.cat.tasks(
v=True,
format="json",
)const response = await client.cat.tasks({
v: "true",
format: "json",
});response = client.cat.tasks(
v: "true",
format: "json"
)$resp = $client->cat()->tasks([
"v" => "true",
"format" => "json",
]);curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_cat/tasks?v=true&format=json"client.cat().tasks();
[
{
"action": "cluster:monitor/tasks/lists[n]",
"task_id": "oTUltX4IQMOUUVeiohTt8A:124",
"parent_task_id": "oTUltX4IQMOUUVeiohTt8A:123",
"type": "direct",
"start_time": "1458585884904",
"timestamp": "01:48:24",
"running_time": "44.1micros",
"ip": "127.0.0.1:9300",
"node": "oTUltX4IQMOUUVeiohTt8A"
},
{
"action": "cluster:monitor/tasks/lists",
"task_id": "oTUltX4IQMOUUVeiohTt8A:123",
"parent_task_id": "-",
"type": "transport",
"start_time": "1458585884904",
"timestamp": "01:48:24",
"running_time": "186.2micros",
"ip": "127.0.0.1:9300",
"node": "oTUltX4IQMOUUVeiohTt8A"
}
]All methods and paths for this operation:
Get explanations for shard allocations in the cluster. For unassigned shards, it provides an explanation for why the shard is unassigned. For assigned shards, it provides an explanation for why the shard is remaining on its current node and has not moved or rebalanced to another node. This API can be very useful when attempting to diagnose why a shard is unassigned or why a shard continues to remain on its current node when you might expect otherwise.
If true, returns information about disk usage and shard sizes.
If true, returns YES decisions in explanation.
Period to wait for a connection to the master node.
Values are -1 or 0.
Specifies the node ID or the name of the node to only explain a shard that is currently located on the specified node.
Specifies the name of the index that you would like an explanation for.
If true, returns explanation for the primary shard for the given shard ID.
Specifies the ID of the shard that you would like an explanation for.
GET _cluster/allocation/explain
{
"index": "my-index-000001",
"shard": 0,
"primary": false,
"current_node": "my-node"
}resp = client.cluster.allocation_explain(
index="my-index-000001",
shard=0,
primary=False,
current_node="my-node",
)const response = await client.cluster.allocationExplain({
index: "my-index-000001",
shard: 0,
primary: false,
current_node: "my-node",
});response = client.cluster.allocation_explain(
body: {
"index": "my-index-000001",
"shard": 0,
"primary": false,
"current_node": "my-node"
}
)$resp = $client->cluster()->allocationExplain([
"body" => [
"index" => "my-index-000001",
"shard" => 0,
"primary" => false,
"current_node" => "my-node",
],
]);curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"index":"my-index-000001","shard":0,"primary":false,"current_node":"my-node"}' "$ELASTICSEARCH_URL/_cluster/allocation/explain"client.cluster().allocationExplain(a -> a
.currentNode("my-node")
.index("my-index-000001")
.primary(false)
.shard(0)
);
{
"index": "my-index-000001",
"shard": 0,
"primary": false,
"current_node": "my-node"
}{
"index" : "my-index-000001",
"shard" : 0,
"primary" : true,
"current_state" : "unassigned",
"unassigned_info" : {
"reason" : "INDEX_CREATED",
"at" : "2017-01-04T18:08:16.600Z",
"last_allocation_status" : "no"
},
"can_allocate" : "no",
"allocate_explanation" : "Elasticsearch isn't allowed to allocate this shard to any of the nodes in the cluster. Choose a node to which you expect this shard to be allocated, find this node in the node-by-node explanation, and address the reasons which prevent Elasticsearch from allocating this shard there.",
"node_allocation_decisions" : [
{
"node_id" : "8qt2rY-pT6KNZB3-hGfLnw",
"node_name" : "node-0",
"transport_address" : "127.0.0.1:9401",
"roles" : ["data", "data_cold", "data_content", "data_frozen", "data_hot", "data_warm", "ingest", "master", "ml", "remote_cluster_client", "transform"],
"node_attributes" : {},
"node_decision" : "no",
"weight_ranking" : 1,
"deciders" : [
{
"decider" : "filter",
"decision" : "NO",
"explanation" : "node does not match index setting [index.routing.allocation.include] filters [_name:\"nonexistent_node\"]"
}
]
}
]
}{
"index" : "my-index-000001",
"shard" : 0,
"primary" : true,
"current_state" : "unassigned",
"unassigned_info" : {
"at" : "2017-01-04T18:03:28.464Z",
"failed shard on node [mEKjwwzLT1yJVb8UxT6anw]: failed recovery, failure RecoveryFailedException",
"reason": "ALLOCATION_FAILED",
"failed_allocation_attempts": 5,
"last_allocation_status": "no",
},
"can_allocate": "no",
"allocate_explanation": "cannot allocate because allocation is not permitted to any of the nodes",
"node_allocation_decisions" : [
{
"node_id" : "3sULLVJrRneSg0EfBB-2Ew",
"node_name" : "node_t0",
"transport_address" : "127.0.0.1:9400",
"roles" : ["data_content", "data_hot"],
"node_decision" : "no",
"store" : {
"matching_size" : "4.2kb",
"matching_size_in_bytes" : 4325
},
"deciders" : [
{
"decider": "max_retry",
"decision" : "NO",
"explanation": "shard has exceeded the maximum number of retries [5] on failed allocation attempts - manually call [POST /_cluster/reroute?retry_failed] to retry, [unassigned_info[[reason=ALLOCATION_FAILED], at[2024-07-30T21:04:12.166Z], failed_attempts[5], failed_nodes[[mEKjwwzLT1yJVb8UxT6anw]], delayed=false, details[failed shard on node [mEKjwwzLT1yJVb8UxT6anw]: failed recovery, failure RecoveryFailedException], allocation_status[deciders_no]]]"
}
]
}
]
}Remove master-eligible nodes from the voting configuration exclusion list.
Period to wait for a connection to the master node.
Values are -1 or 0.
Specifies whether to wait for all excluded nodes to be removed from the cluster before clearing the voting configuration exclusions list. Defaults to true, meaning that all excluded nodes must be removed from the cluster before this API takes any action. If set to false then the voting configuration exclusions list is cleared even if some excluded nodes are still in the cluster.
curl \
--request DELETE 'http://api.example.com/_cluster/voting_config_exclusions' \
--header "Authorization: $API_KEY"By default, it returns only settings that have been explicitly defined.
monitorIf true, returns settings in flat format.
If true, also returns default values for all other cluster settings, reflecting the values
in the elasticsearch.yml file of one of the nodes in the cluster. If the nodes in your
cluster do not all have the same values in their elasticsearch.yml config files then the
values returned by this API may vary from invocation to invocation and may not reflect the
values that Elasticsearch uses in all situations. Use the GET _nodes/settings API to
fetch the settings for each individual node in your cluster.
Period 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.
Values are -1 or 0.
Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error.
Values are -1 or 0.
GET /_cluster/settings?filter_path=persistent.cluster.remote
resp = client.cluster.get_settings(
filter_path="persistent.cluster.remote",
)const response = await client.cluster.getSettings({
filter_path: "persistent.cluster.remote",
});response = client.cluster.get_settings(
filter_path: "persistent.cluster.remote"
)$resp = $client->cluster()->getSettings([
"filter_path" => "persistent.cluster.remote",
]);curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_cluster/settings?filter_path=persistent.cluster.remote"Configure and update dynamic settings on a running cluster.
You can also configure dynamic settings locally on an unstarted or shut down node in elasticsearch.yml.
Updates made with this API can be persistent, which apply across cluster restarts, or transient, which reset after a cluster restart. You can also reset transient or persistent settings by assigning them a null value.
If you configure the same setting using multiple methods, Elasticsearch applies the settings in following order of precedence: 1) Transient setting; 2) Persistent setting; 3) elasticsearch.yml setting; 4) Default setting value.
For example, you can apply a transient setting to override a persistent setting or elasticsearch.yml setting.
However, a change to an elasticsearch.yml setting will not override a defined transient or persistent setting.
TIP: In Elastic Cloud, use the user settings feature to configure all cluster settings. This method automatically rejects unsafe settings that could break your cluster.
If you run Elasticsearch on your own hardware, use this API to configure dynamic cluster settings.
Only use elasticsearch.yml for static cluster settings and node settings.
The API doesn’t require a restart and ensures a setting’s value is the same on all nodes.
WARNING: Transient cluster settings are no longer recommended. Use persistent cluster settings instead. If a cluster becomes unstable, transient settings can clear unexpectedly, resulting in a potentially undesired cluster configuration.
Return settings in flat format (default: false)
Explicit operation timeout for connection to master node
Values are -1 or 0.
Explicit operation timeout
Values are -1 or 0.
PUT /_cluster/settings
{
"persistent" : {
"indices.recovery.max_bytes_per_sec" : "50mb"
}
}resp = client.cluster.put_settings(
persistent={
"indices.recovery.max_bytes_per_sec": "50mb"
},
)const response = await client.cluster.putSettings({
persistent: {
"indices.recovery.max_bytes_per_sec": "50mb",
},
});response = client.cluster.put_settings(
body: {
"persistent": {
"indices.recovery.max_bytes_per_sec": "50mb"
}
}
)$resp = $client->cluster()->putSettings([
"body" => [
"persistent" => [
"indices.recovery.max_bytes_per_sec" => "50mb",
],
],
]);curl -X PUT -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"persistent":{"indices.recovery.max_bytes_per_sec":"50mb"}}' "$ELASTICSEARCH_URL/_cluster/settings"client.cluster().putSettings(p -> p
.persistent("indices.recovery.max_bytes_per_sec", JsonData.fromJson("\"50mb\""))
);
{
"persistent" : {
"indices.recovery.max_bytes_per_sec" : "50mb"
}
}{
"persistent": {
"action.auto_create_index": "my-index-000001,index10,-index1*,+ind*"
}
}All methods and paths for this operation:
You can also use the API to get the health status of only specified data streams and indices. For data streams, the API retrieves the health status of the stream’s backing indices.
The cluster health status is: green, yellow or red. On the shard level, a red status indicates that the specific shard is not allocated in the cluster. Yellow means that the primary shard is allocated but replicas are not. Green means that all shards are allocated. The index level status is controlled by the worst shard status.
One of the main benefits of the API is the ability to wait until the cluster reaches a certain high watermark health level. The cluster status is controlled by the worst index status.
monitor,manageComma-separated list of data streams, indices, and index aliases used to limit the request. Wildcard expressions (*) are supported. To target all data streams and indices in a cluster, omit this parameter or use _all or *.
Whether to expand wildcard expression to concrete indices that are open, closed or both.
Supported values include:
all: Match any data stream or index, including hidden ones.open: Match open, non-hidden indices. Also matches any non-hidden data stream.closed: Match closed, non-hidden indices. Also matches any non-hidden data stream. Data streams cannot be closed.hidden: Match hidden data streams and hidden indices. Must be combined with open, closed, or both.none: Wildcard expressions are not accepted.Values are all, open, closed, hidden, or none.
Can be one of cluster, indices or shards. Controls the details level of the health information returned.
Values are cluster, indices, or shards.
If true, the request retrieves information from the local node only. Defaults to false, which means information is retrieved from the master node.
Period 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.
Values are -1 or 0.
Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error.
Values are -1 or 0.
A number controlling to how many active shards to wait for, all to wait for all shards in the cluster to be active, or 0 to not wait.
Values are all or index-setting.
Can be one of immediate, urgent, high, normal, low, languid. Wait until all currently queued events with the given priority are processed.
Values are immediate, urgent, high, normal, low, or languid.
The request waits until the specified number N of nodes is available. It also accepts >=N, <=N, >N and <N. Alternatively, it is possible to use ge(N), le(N), gt(N) and lt(N) notation.
A boolean value which controls whether to wait (until the timeout provided) for the cluster to have no shard initializations. Defaults to false, which means it will not wait for initializing shards.
A boolean value which controls whether to wait (until the timeout provided) for the cluster to have no shard relocations. Defaults to false, which means it will not wait for relocating shards.
One of green, yellow or red. Will wait (until the timeout provided) until the status of the cluster changes to the one provided or better, i.e. green > yellow > red. By default, will not wait for any status.
Supported values include:
green (or GREEN): All shards are assigned.yellow (or YELLOW): All primary shards are assigned, but one or more replica shards are unassigned. If a node in the cluster fails, some data could be unavailable until that node is repaired.red (or RED): One or more primary shards are unassigned, so some data is unavailable. This can occur briefly during cluster startup as primary shards are assigned.unknownunavailableValues are green, GREEN, yellow, YELLOW, red, RED, unknown, or unavailable.
GET _cluster/health
resp = client.cluster.health()const response = await client.cluster.health();response = client.cluster.health$resp = $client->cluster()->health();curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_cluster/health"client.cluster().health(h -> h);
{
"cluster_name" : "testcluster",
"status" : "yellow",
"timed_out" : false,
"number_of_nodes" : 1,
"number_of_data_nodes" : 1,
"active_primary_shards" : 1,
"active_shards" : 1,
"relocating_shards" : 0,
"initializing_shards" : 0,
"unassigned_shards" : 1,
"delayed_unassigned_shards": 0,
"number_of_pending_tasks" : 0,
"number_of_in_flight_fetch": 0,
"task_max_waiting_in_queue_millis": 0,
"active_shards_percent_as_number": 50.0
}Returns basic information about the cluster.
GET /_info/_all
resp = client.cluster.info(
target="_all",
)const response = await client.cluster.info({
target: "_all",
});response = client.cluster.info(
target: "_all"
)$resp = $client->cluster()->info([
"target" => "_all",
]);curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_info/_all"client.cluster().info(i -> i
.target("_all")
);
All methods and paths for this operation:
Get basic index metrics (shard numbers, store size, memory usage) and information about the current nodes that form the cluster (number, roles, os, jvm versions, memory usage, cpu and installed plugins).
monitorComma-separated list of node filters used to limit returned information. Defaults to all nodes in the cluster.
Include remote cluster data into the response
Period to wait for each node to respond.
If a node does not respond before its timeout expires, the response does not include its stats.
However, timed out nodes are included in the response’s _nodes.failed property. Defaults to no timeout.
Values are -1 or 0.
GET _cluster/stats?human&filter_path=indices.mappings.total_deduplicated_mapping_size*
resp = client.cluster.stats(
human=True,
filter_path="indices.mappings.total_deduplicated_mapping_size*",
)const response = await client.cluster.stats({
human: "true",
filter_path: "indices.mappings.total_deduplicated_mapping_size*",
});response = client.cluster.stats(
human: "true",
filter_path: "indices.mappings.total_deduplicated_mapping_size*"
)$resp = $client->cluster()->stats([
"human" => "true",
"filter_path" => "indices.mappings.total_deduplicated_mapping_size*",
]);curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_cluster/stats?human&filter_path=indices.mappings.total_deduplicated_mapping_size*"Get repositories metering information for a cluster. This API exposes monotonically non-decreasing counters and it is expected that clients would durably store the information needed to compute aggregations over a period of time. Additionally, the information exposed by this API is volatile, meaning that it will not be present after node restarts.
monitor,managecurl \
--request GET 'http://api.example.com/_nodes/{node_id}/_repositories_metering' \
--header "Authorization: $API_KEY"All methods and paths for this operation:
By default, the API returns all attributes and core settings for cluster nodes.
Comma-separated list of node IDs or names used to limit returned information.
Limits the information returned to the specific metrics. Supports a comma-separated list, such as http,ingest.
GET _nodes/_all/jvm
resp = client.nodes.info(
node_id="_all",
metric="jvm",
)const response = await client.nodes.info({
node_id: "_all",
metric: "jvm",
});response = client.nodes.info(
node_id: "_all",
metric: "jvm"
)$resp = $client->nodes()->info([
"node_id" => "_all",
"metric" => "jvm",
]);curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_nodes/_all/jvm"client.nodes().info(i -> i
.metric("jvm")
.nodeId("_all")
);
{
"_nodes": {},
"cluster_name": "elasticsearch",
"nodes": {
"USpTGYaBSIKbgSUJR2Z9lg": {
"name": "node-0",
"transport_address": "192.168.17:9300",
"host": "node-0.elastic.co",
"ip": "192.168.17",
"version": "{version}",
"transport_version": 100000298,
"index_version": 100000074,
"component_versions": {
"ml_config_version": 100000162,
"transform_config_version": 100000096
},
"build_flavor": "default",
"build_type": "{build_type}",
"build_hash": "587409e",
"roles": [
"master",
"data",
"ingest"
],
"attributes": {},
"plugins": [
{
"name": "analysis-icu",
"version": "{version}",
"description": "The ICU Analysis plugin integrates Lucene ICU
module into elasticsearch, adding ICU relates analysis components.",
"classname":
"org.elasticsearch.plugin.analysis.icu.AnalysisICUPlugin",
"has_native_controller": false
}
],
"modules": [
{
"name": "lang-painless",
"version": "{version}",
"description": "An easy, safe and fast scripting language for
Elasticsearch",
"classname": "org.elasticsearch.painless.PainlessPlugin",
"has_native_controller": false
}
]
}
}
}All methods and paths for this operation:
Secure settings are stored in an on-disk keystore. Certain of these settings are reloadable. That is, you can change them on disk and reload them without restarting any nodes in the cluster. When you have updated reloadable secure settings in your keystore, you can use this API to reload those settings on each node.
When the Elasticsearch keystore is password protected and not simply obfuscated, you must provide the password for the keystore when you reload the secure settings. Reloading the settings for the whole cluster assumes that the keystores for all nodes are protected with the same password; this method is allowed only when inter-node communications are encrypted. Alternatively, you can reload the secure settings on each node by locally accessing the API and passing the node-specific Elasticsearch keystore password.
Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error.
Values are -1 or 0.
POST _nodes/reload_secure_settings
{
"secure_settings_password": "keystore-password"
}resp = client.nodes.reload_secure_settings(
secure_settings_password="keystore-password",
)const response = await client.nodes.reloadSecureSettings({
secure_settings_password: "keystore-password",
});response = client.nodes.reload_secure_settings(
body: {
"secure_settings_password": "keystore-password"
}
)$resp = $client->nodes()->reloadSecureSettings([
"body" => [
"secure_settings_password" => "keystore-password",
],
]);curl -X POST -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"secure_settings_password":"keystore-password"}' "$ELASTICSEARCH_URL/_nodes/reload_secure_settings"client.nodes().reloadSecureSettings(r -> r
.secureSettingsPassword("keystore-password")
);
{
"secure_settings_password": "keystore-password"
}{
"_nodes": {
"total": 1,
"successful": 1,
"failed": 0
},
"cluster_name": "my_cluster",
"nodes": {
"pQHNt5rXTTWNvUgOrdynKg": {
"name": "node-0"
}
}
}All methods and paths for this operation:
Get a report with the health status of an Elasticsearch cluster. The report contains a list of indicators that compose Elasticsearch functionality.
Each indicator has a health status of: green, unknown, yellow or red. The indicator will provide an explanation and metadata describing the reason for its current health status.
The cluster’s status is controlled by the worst indicator status.
In the event that an indicator’s status is non-green, a list of impacts may be present in the indicator result which detail the functionalities that are negatively affected by the health issue. Each impact carries with it a severity level, an area of the system that is affected, and a simple description of the impact on the system.
Some health indicators can determine the root cause of a health problem and prescribe a set of steps that can be performed in order to improve the health of the system. The root cause and remediation steps are encapsulated in a diagnosis. A diagnosis contains a cause detailing a root cause analysis, an action containing a brief description of the steps to take to fix the problem, the list of affected resources (if applicable), and a detailed step-by-step troubleshooting guide to fix the diagnosed problem.
NOTE: The health indicators perform root cause analysis of non-green health statuses. This can be computationally expensive when called frequently. When setting up automated polling of the API for health status, set verbose to false to disable the more expensive analysis logic.
GET _health_report
resp = client.health_report()const response = await client.healthReport();response = client.health_report$resp = $client->healthReport();curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_health_report"client.healthReport(h -> h);
Update the last_seen field in the connector and set it to the current timestamp.
PUT _connector/my-connector/_check_in
resp = client.connector.check_in(
connector_id="my-connector",
)const response = await client.connector.checkIn({
connector_id: "my-connector",
});response = client.connector.check_in(
connector_id: "my-connector"
)$resp = $client->connector()->checkIn([
"connector_id" => "my-connector",
]);curl -X PUT -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_connector/my-connector/_check_in"client.connector().checkIn(c -> c
.connectorId("my-connector")
);
{
"result": "updated"
}GET _connector/my-connector-id
resp = client.connector.get(
connector_id="my-connector-id",
)const response = await client.connector.get({
connector_id: "my-connector-id",
});response = client.connector.get(
connector_id: "my-connector-id"
)$resp = $client->connector()->get([
"connector_id" => "my-connector-id",
]);curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_connector/my-connector-id"client.connector().get(g -> g
.connectorId("my-connector-id")
);
All methods and paths for this operation:
The unique identifier of the connector to be created or updated. ID is auto-generated if not provided.
PUT _connector/my-connector
{
"index_name": "search-google-drive",
"name": "My Connector",
"service_type": "google_drive"
}resp = client.connector.put(
connector_id="my-connector",
index_name="search-google-drive",
name="My Connector",
service_type="google_drive",
)const response = await client.connector.put({
connector_id: "my-connector",
index_name: "search-google-drive",
name: "My Connector",
service_type: "google_drive",
});response = client.connector.put(
connector_id: "my-connector",
body: {
"index_name": "search-google-drive",
"name": "My Connector",
"service_type": "google_drive"
}
)$resp = $client->connector()->put([
"connector_id" => "my-connector",
"body" => [
"index_name" => "search-google-drive",
"name" => "My Connector",
"service_type" => "google_drive",
],
]);curl -X PUT -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"index_name":"search-google-drive","name":"My Connector","service_type":"google_drive"}' "$ELASTICSEARCH_URL/_connector/my-connector"client.connector().put(p -> p
.connectorId("my-connector")
.indexName("search-google-drive")
.name("My Connector")
.serviceType("google_drive")
);
{
"index_name": "search-google-drive",
"name": "My Connector",
"service_type": "google_drive"
}{
"index_name": "search-google-drive",
"name": "My Connector",
"description": "My Connector to sync data to Elastic index from Google Drive",
"service_type": "google_drive",
"language": "english"
}{
"result": "created",
"id": "my-connector"
}Removes a connector and associated sync jobs. This is a destructive action that is not recoverable. NOTE: This action doesn’t delete any API keys, ingest pipelines, or data indices associated with the connector. These need to be removed manually.
DELETE _connector/my-connector-id&delete_sync_jobs=true
resp = client.connector.delete(
connector_id="my-connector-id&delete_sync_jobs=true",
)const response = await client.connector.delete({
connector_id: "my-connector-id&delete_sync_jobs=true",
});response = client.connector.delete(
connector_id: "my-connector-id&delete_sync_jobs=true"
)$resp = $client->connector()->delete([
"connector_id" => "my-connector-id&delete_sync_jobs=true",
]);curl -X DELETE -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_connector/my-connector-id&delete_sync_jobs=true"client.connector().delete(d -> d
.connectorId("my-connector-id&delete_sync_jobs=true")
);
{
"acknowledged": true
}Cancel a connector sync job, which sets the status to cancelling and updates cancellation_requested_at to the current time.
The connector service is then responsible for setting the status of connector sync jobs to cancelled.
PUT _connector/_sync_job/my-connector-sync-job-id/_cancel
resp = client.connector.sync_job_cancel(
connector_sync_job_id="my-connector-sync-job-id",
)const response = await client.connector.syncJobCancel({
connector_sync_job_id: "my-connector-sync-job-id",
});response = client.connector.sync_job_cancel(
connector_sync_job_id: "my-connector-sync-job-id"
)$resp = $client->connector()->syncJobCancel([
"connector_sync_job_id" => "my-connector-sync-job-id",
]);curl -X PUT -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_connector/_sync_job/my-connector-sync-job-id/_cancel"client.connector().syncJobCancel(s -> s
.connectorSyncJobId("my-connector-sync-job-id")
);
Check in a connector sync job and set the last_seen field to the current time before updating it in the internal index.
To sync data using self-managed connectors, you need to deploy the Elastic connector service on your own infrastructure. This service runs automatically on Elastic Cloud for Elastic managed connectors.
PUT _connector/_sync_job/my-connector-sync-job/_check_in
resp = client.connector.sync_job_check_in(
connector_sync_job_id="my-connector-sync-job",
)const response = await client.connector.syncJobCheckIn({
connector_sync_job_id: "my-connector-sync-job",
});response = client.connector.sync_job_check_in(
connector_sync_job_id: "my-connector-sync-job"
)$resp = $client->connector()->syncJobCheckIn([
"connector_sync_job_id" => "my-connector-sync-job",
]);curl -X PUT -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_connector/_sync_job/my-connector-sync-job/_check_in"client.connector().syncJobCheckIn(s -> s
.connectorSyncJobId("my-connector-sync-job")
);
This action updates the job status to in_progress and sets the last_seen and started_at timestamps to the current time.
Additionally, it can set the sync_cursor property for the sync job.
This API is not intended for direct connector management by users. It supports the implementation of services that utilize the connector protocol to communicate with Elasticsearch.
To sync data using self-managed connectors, you need to deploy the Elastic connector service on your own infrastructure. This service runs automatically on Elastic Cloud for Elastic managed connectors.
PUT _connector/_sync_job/my-connector-sync-job-id/_claim
{
"worker_hostname": "some-machine"
}resp = client.connector.sync_job_claim(
connector_sync_job_id="my-connector-sync-job-id",
worker_hostname="some-machine",
)const response = await client.connector.syncJobClaim({
connector_sync_job_id: "my-connector-sync-job-id",
worker_hostname: "some-machine",
});response = client.connector.sync_job_claim(
connector_sync_job_id: "my-connector-sync-job-id",
body: {
"worker_hostname": "some-machine"
}
)$resp = $client->connector()->syncJobClaim([
"connector_sync_job_id" => "my-connector-sync-job-id",
"body" => [
"worker_hostname" => "some-machine",
],
]);curl -X PUT -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"worker_hostname":"some-machine"}' "$ELASTICSEARCH_URL/_connector/_sync_job/my-connector-sync-job-id/_claim"client.connector().syncJobClaim(s -> s
.connectorSyncJobId("my-connector-sync-job-id")
.workerHostname("some-machine")
);
{
"worker_hostname": "some-machine"
}GET _connector/_sync_job/my-connector-sync-job
resp = client.connector.sync_job_get(
connector_sync_job_id="my-connector-sync-job",
)const response = await client.connector.syncJobGet({
connector_sync_job_id: "my-connector-sync-job",
});response = client.connector.sync_job_get(
connector_sync_job_id: "my-connector-sync-job"
)$resp = $client->connector()->syncJobGet([
"connector_sync_job_id" => "my-connector-sync-job",
]);curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_connector/_sync_job/my-connector-sync-job"client.connector().syncJobGet(s -> s
.connectorSyncJobId("my-connector-sync-job")
);
Remove a connector sync job and its associated data. This is a destructive action that is not recoverable.
DELETE _connector/_sync_job/my-connector-sync-job-id
resp = client.connector.sync_job_delete(
connector_sync_job_id="my-connector-sync-job-id",
)const response = await client.connector.syncJobDelete({
connector_sync_job_id: "my-connector-sync-job-id",
});response = client.connector.sync_job_delete(
connector_sync_job_id: "my-connector-sync-job-id"
)$resp = $client->connector()->syncJobDelete([
"connector_sync_job_id" => "my-connector-sync-job-id",
]);curl -X DELETE -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_connector/_sync_job/my-connector-sync-job-id"client.connector().syncJobDelete(s -> s
.connectorSyncJobId("my-connector-sync-job-id")
);
{
"acknowledged": true
}Set the error field for a connector sync job and set its status to error.
To sync data using self-managed connectors, you need to deploy the Elastic connector service on your own infrastructure. This service runs automatically on Elastic Cloud for Elastic managed connectors.
PUT _connector/_sync_job/my-connector-sync-job/_error
{
"error": "some-error"
}resp = client.connector.sync_job_error(
connector_sync_job_id="my-connector-sync-job",
error="some-error",
)const response = await client.connector.syncJobError({
connector_sync_job_id: "my-connector-sync-job",
error: "some-error",
});response = client.connector.sync_job_error(
connector_sync_job_id: "my-connector-sync-job",
body: {
"error": "some-error"
}
)$resp = $client->connector()->syncJobError([
"connector_sync_job_id" => "my-connector-sync-job",
"body" => [
"error" => "some-error",
],
]);curl -X PUT -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"error":"some-error"}' "$ELASTICSEARCH_URL/_connector/_sync_job/my-connector-sync-job/_error"client.connector().syncJobError(s -> s
.connectorSyncJobId("my-connector-sync-job")
.error("some-error")
);
{
"error": "some-error"
}Get information about all stored connector sync jobs listed by their creation date in ascending order.
Starting offset (default: 0)
Specifies a max number of results to get
A sync job status to fetch connector sync jobs for
Values are canceling, canceled, completed, error, in_progress, pending, or suspended.
A connector id to fetch connector sync jobs for
A comma-separated list of job types to fetch the sync jobs for
Supported values include: full, incremental, access_control
Values are full, incremental, or access_control.
GET _connector/_sync_job?connector_id=my-connector-id&size=1
resp = client.connector.sync_job_list(
connector_id="my-connector-id",
size="1",
)const response = await client.connector.syncJobList({
connector_id: "my-connector-id",
size: 1,
});response = client.connector.sync_job_list(
connector_id: "my-connector-id",
size: "1"
)$resp = $client->connector()->syncJobList([
"connector_id" => "my-connector-id",
"size" => "1",
]);curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_connector/_sync_job?connector_id=my-connector-id&size=1"client.connector().syncJobList(s -> s
.connectorId("my-connector-id")
.size(1)
);
Stats include: deleted_document_count, indexed_document_count, indexed_document_volume, and total_document_count.
You can also update last_seen.
This API is mainly used by the connector service for updating sync job information.
To sync data using self-managed connectors, you need to deploy the Elastic connector service on your own infrastructure. This service runs automatically on Elastic Cloud for Elastic managed connectors.
The number of documents the sync job deleted.
The number of documents the sync job indexed.
The total size of the data (in MiB) the sync job indexed.
The timestamp to use in the last_seen property for the connector sync job.
The connector-specific metadata.
The total number of documents in the target index after the sync job finished.
PUT _connector/_sync_job/my-connector-sync-job/_stats
{
"deleted_document_count": 10,
"indexed_document_count": 20,
"indexed_document_volume": 1000,
"total_document_count": 2000,
"last_seen": "2023-01-02T10:00:00Z"
}resp = client.connector.sync_job_update_stats(
connector_sync_job_id="my-connector-sync-job",
deleted_document_count=10,
indexed_document_count=20,
indexed_document_volume=1000,
total_document_count=2000,
last_seen="2023-01-02T10:00:00Z",
)const response = await client.connector.syncJobUpdateStats({
connector_sync_job_id: "my-connector-sync-job",
deleted_document_count: 10,
indexed_document_count: 20,
indexed_document_volume: 1000,
total_document_count: 2000,
last_seen: "2023-01-02T10:00:00Z",
});response = client.connector.sync_job_update_stats(
connector_sync_job_id: "my-connector-sync-job",
body: {
"deleted_document_count": 10,
"indexed_document_count": 20,
"indexed_document_volume": 1000,
"total_document_count": 2000,
"last_seen": "2023-01-02T10:00:00Z"
}
)$resp = $client->connector()->syncJobUpdateStats([
"connector_sync_job_id" => "my-connector-sync-job",
"body" => [
"deleted_document_count" => 10,
"indexed_document_count" => 20,
"indexed_document_volume" => 1000,
"total_document_count" => 2000,
"last_seen" => "2023-01-02T10:00:00Z",
],
]);curl -X PUT -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"deleted_document_count":10,"indexed_document_count":20,"indexed_document_volume":1000,"total_document_count":2000,"last_seen":"2023-01-02T10:00:00Z"}' "$ELASTICSEARCH_URL/_connector/_sync_job/my-connector-sync-job/_stats"client.connector().syncJobUpdateStats(s -> s
.connectorSyncJobId("my-connector-sync-job")
.deletedDocumentCount(10L)
.indexedDocumentCount(20L)
.indexedDocumentVolume(1000L)
.lastSeen(l -> l
.time("2023-01-02T10:00:00Z")
)
.totalDocumentCount(2000)
);
{
"deleted_document_count": 10,
"indexed_document_count": 20,
"indexed_document_volume": 1000,
"total_document_count": 2000,
"last_seen": "2023-01-02T10:00:00Z"
}curl \
--request PUT 'http://api.example.com/_connector/{connector_id}/_filtering/_activate' \
--header "Authorization: $API_KEY"Update the api_key_id and api_key_secret_id fields of a connector.
You can specify the ID of the API key used for authorization and the ID of the connector secret where the API key is stored.
The connector secret ID is required only for Elastic managed (native) connectors.
Self-managed connectors (connector clients) do not use this field.
PUT _connector/my-connector/_api_key_id
{
"api_key_id": "my-api-key-id",
"api_key_secret_id": "my-connector-secret-id"
}resp = client.connector.update_api_key_id(
connector_id="my-connector",
api_key_id="my-api-key-id",
api_key_secret_id="my-connector-secret-id",
)const response = await client.connector.updateApiKeyId({
connector_id: "my-connector",
api_key_id: "my-api-key-id",
api_key_secret_id: "my-connector-secret-id",
});response = client.connector.update_api_key_id(
connector_id: "my-connector",
body: {
"api_key_id": "my-api-key-id",
"api_key_secret_id": "my-connector-secret-id"
}
)$resp = $client->connector()->updateApiKeyId([
"connector_id" => "my-connector",
"body" => [
"api_key_id" => "my-api-key-id",
"api_key_secret_id" => "my-connector-secret-id",
],
]);curl -X PUT -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"api_key_id":"my-api-key-id","api_key_secret_id":"my-connector-secret-id"}' "$ELASTICSEARCH_URL/_connector/my-connector/_api_key_id"client.connector().updateApiKeyId(u -> u
.apiKeyId("my-api-key-id")
.apiKeySecretId("my-connector-secret-id")
.connectorId("my-connector")
);
{
"api_key_id": "my-api-key-id",
"api_key_secret_id": "my-connector-secret-id"
}{
"result": "updated"
}Set the error field for the connector. If the error provided in the request body is non-null, the connector’s status is updated to error. Otherwise, if the error is reset to null, the connector status is updated to connected.
PUT _connector/my-connector/_error
{
"error": "Houston, we have a problem!"
}resp = client.connector.update_error(
connector_id="my-connector",
error="Houston, we have a problem!",
)const response = await client.connector.updateError({
connector_id: "my-connector",
error: "Houston, we have a problem!",
});response = client.connector.update_error(
connector_id: "my-connector",
body: {
"error": "Houston, we have a problem!"
}
)$resp = $client->connector()->updateError([
"connector_id" => "my-connector",
"body" => [
"error" => "Houston, we have a problem!",
],
]);curl -X PUT -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"error":"Houston, we have a problem!"}' "$ELASTICSEARCH_URL/_connector/my-connector/_error"client.connector().updateError(u -> u
.connectorId("my-connector")
.error("Houston, we have a problem!")
);
{
"error": "Houston, we have a problem!"
}{
"result": "updated"
}Update the connector features in the connector document. This API can be used to control the following aspects of a connector:
Normally, the running connector service automatically manages these features. However, you can use this API to override the default behavior.
To sync data using self-managed connectors, you need to deploy the Elastic connector service on your own infrastructure. This service runs automatically on Elastic Cloud for Elastic managed connectors.
PUT _connector/my-connector/_features
{
"features": {
"document_level_security": {
"enabled": true
},
"incremental_sync": {
"enabled": true
},
"sync_rules": {
"advanced": {
"enabled": false
},
"basic": {
"enabled": true
}
}
}
}resp = client.connector.update_features(
connector_id="my-connector",
features={
"document_level_security": {
"enabled": True
},
"incremental_sync": {
"enabled": True
},
"sync_rules": {
"advanced": {
"enabled": False
},
"basic": {
"enabled": True
}
}
},
)const response = await client.connector.updateFeatures({
connector_id: "my-connector",
features: {
document_level_security: {
enabled: true,
},
incremental_sync: {
enabled: true,
},
sync_rules: {
advanced: {
enabled: false,
},
basic: {
enabled: true,
},
},
},
});response = client.connector.update_features(
connector_id: "my-connector",
body: {
"features": {
"document_level_security": {
"enabled": true
},
"incremental_sync": {
"enabled": true
},
"sync_rules": {
"advanced": {
"enabled": false
},
"basic": {
"enabled": true
}
}
}
}
)$resp = $client->connector()->updateFeatures([
"connector_id" => "my-connector",
"body" => [
"features" => [
"document_level_security" => [
"enabled" => true,
],
"incremental_sync" => [
"enabled" => true,
],
"sync_rules" => [
"advanced" => [
"enabled" => false,
],
"basic" => [
"enabled" => true,
],
],
],
],
]);curl -X PUT -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"features":{"document_level_security":{"enabled":true},"incremental_sync":{"enabled":true},"sync_rules":{"advanced":{"enabled":false},"basic":{"enabled":true}}}}' "$ELASTICSEARCH_URL/_connector/my-connector/_features"client.connector().updateFeatures(u -> u
.connectorId("my-connector")
.features(f -> f
.documentLevelSecurity(d -> d
.enabled(true)
)
.incrementalSync(i -> i
.enabled(true)
)
.syncRules(s -> s
.advanced(a -> a
.enabled(false)
)
.basic(b -> b
.enabled(true)
)
)
)
);
{
"features": {
"document_level_security": {
"enabled": true
},
"incremental_sync": {
"enabled": true
},
"sync_rules": {
"advanced": {
"enabled": false
},
"basic": {
"enabled": true
}
}
}
}{
"features": {
"document_level_security": {
"enabled": true
}
}
}{
"result": "updated"
}Update the draft filtering configuration of a connector and marks the draft validation state as edited. The filtering draft is activated once validated by the running Elastic connector service. The filtering property is used to configure sync rules (both basic and advanced) for a connector.
PUT _connector/my-g-drive-connector/_filtering
{
"rules": [
{
"field": "file_extension",
"id": "exclude-txt-files",
"order": 0,
"policy": "exclude",
"rule": "equals",
"value": "txt"
},
{
"field": "_",
"id": "DEFAULT",
"order": 1,
"policy": "include",
"rule": "regex",
"value": ".*"
}
]
}resp = client.connector.update_filtering(
connector_id="my-g-drive-connector",
rules=[
{
"field": "file_extension",
"id": "exclude-txt-files",
"order": 0,
"policy": "exclude",
"rule": "equals",
"value": "txt"
},
{
"field": "_",
"id": "DEFAULT",
"order": 1,
"policy": "include",
"rule": "regex",
"value": ".*"
}
],
)const response = await client.connector.updateFiltering({
connector_id: "my-g-drive-connector",
rules: [
{
field: "file_extension",
id: "exclude-txt-files",
order: 0,
policy: "exclude",
rule: "equals",
value: "txt",
},
{
field: "_",
id: "DEFAULT",
order: 1,
policy: "include",
rule: "regex",
value: ".*",
},
],
});response = client.connector.update_filtering(
connector_id: "my-g-drive-connector",
body: {
"rules": [
{
"field": "file_extension",
"id": "exclude-txt-files",
"order": 0,
"policy": "exclude",
"rule": "equals",
"value": "txt"
},
{
"field": "_",
"id": "DEFAULT",
"order": 1,
"policy": "include",
"rule": "regex",
"value": ".*"
}
]
}
)$resp = $client->connector()->updateFiltering([
"connector_id" => "my-g-drive-connector",
"body" => [
"rules" => array(
[
"field" => "file_extension",
"id" => "exclude-txt-files",
"order" => 0,
"policy" => "exclude",
"rule" => "equals",
"value" => "txt",
],
[
"field" => "_",
"id" => "DEFAULT",
"order" => 1,
"policy" => "include",
"rule" => "regex",
"value" => ".*",
],
),
],
]);curl -X PUT -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"rules":[{"field":"file_extension","id":"exclude-txt-files","order":0,"policy":"exclude","rule":"equals","value":"txt"},{"field":"_","id":"DEFAULT","order":1,"policy":"include","rule":"regex","value":".*"}]}' "$ELASTICSEARCH_URL/_connector/my-g-drive-connector/_filtering"client.connector().updateFiltering(u -> u
.connectorId("my-g-drive-connector")
.rules(List.of(FilteringRule.of(f -> f
.field("file_extension")
.id("exclude-txt-files")
.order(0)
.policy(FilteringPolicy.Exclude)
.rule(FilteringRuleRule.Equals)
.value("txt")),FilteringRule.of(f -> f
.field("_")
.id("DEFAULT")
.order(1)
.policy(FilteringPolicy.Include)
.rule(FilteringRuleRule.Regex)
.value(".*"))))
);
{
"rules": [
{
"field": "file_extension",
"id": "exclude-txt-files",
"order": 0,
"policy": "exclude",
"rule": "equals",
"value": "txt"
},
{
"field": "_",
"id": "DEFAULT",
"order": 1,
"policy": "include",
"rule": "regex",
"value": ".*"
}
]
}{
"advanced_snippet": {
"value": [{
"tables": [
"users",
"orders"
],
"query": "SELECT users.id AS id, orders.order_id AS order_id FROM users JOIN orders ON users.id = orders.user_id"
}]
}
}{
"result": "updated"
}Update the draft filtering validation info for a connector.
curl \
--request PUT 'http://api.example.com/_connector/{connector_id}/_filtering/_validation' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--data '{"validation":{"errors":[{"ids":["string"],"messages":["string"]}],"state":"edited"}}'PUT _connector/my-connector/_name
{
"name": "Custom connector",
"description": "This is my customized connector"
}resp = client.connector.update_name(
connector_id="my-connector",
name="Custom connector",
description="This is my customized connector",
)const response = await client.connector.updateName({
connector_id: "my-connector",
name: "Custom connector",
description: "This is my customized connector",
});response = client.connector.update_name(
connector_id: "my-connector",
body: {
"name": "Custom connector",
"description": "This is my customized connector"
}
)$resp = $client->connector()->updateName([
"connector_id" => "my-connector",
"body" => [
"name" => "Custom connector",
"description" => "This is my customized connector",
],
]);curl -X PUT -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"name":"Custom connector","description":"This is my customized connector"}' "$ELASTICSEARCH_URL/_connector/my-connector/_name"client.connector().updateName(u -> u
.connectorId("my-connector")
.description("This is my customized connector")
.name("Custom connector")
);
{
"name": "Custom connector",
"description": "This is my customized connector"
}{
"result": "updated"
}curl \
--request PUT 'http://api.example.com/_connector/{connector_id}/_native' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--data '{"is_native":true}'PUT _connector/my-connector/_service_type
{
"service_type": "sharepoint_online"
}resp = client.connector.update_service_type(
connector_id="my-connector",
service_type="sharepoint_online",
)const response = await client.connector.updateServiceType({
connector_id: "my-connector",
service_type: "sharepoint_online",
});response = client.connector.update_service_type(
connector_id: "my-connector",
body: {
"service_type": "sharepoint_online"
}
)$resp = $client->connector()->updateServiceType([
"connector_id" => "my-connector",
"body" => [
"service_type" => "sharepoint_online",
],
]);curl -X PUT -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"service_type":"sharepoint_online"}' "$ELASTICSEARCH_URL/_connector/my-connector/_service_type"client.connector().updateServiceType(u -> u
.connectorId("my-connector")
.serviceType("sharepoint_online")
);
{
"service_type": "sharepoint_online"
}{
"result": "updated"
}Create a collection of cross-cluster replication auto-follow patterns for a remote cluster. Newly created indices on the remote cluster that match any of the patterns are automatically configured as follower indices. Indices on the remote cluster that were created before the auto-follow pattern was created will not be auto-followed even if they match the pattern.
This API can also be used to update auto-follow patterns. NOTE: Follower indices that were configured automatically before updating an auto-follow pattern will remain unchanged even if they do not match against the new patterns.
The remote cluster containing the leader indices to match against.
The name of follower index. The template {{leader_index}} can be used to derive the name of the follower index from the name of the leader index. When following a data stream, use {{leader_index}}; CCR does not support changes to the names of a follower data stream’s backing indices.
An array of simple index patterns to match against indices in the remote cluster specified by the remote_cluster field.
An array of simple index patterns that can be used to exclude indices from being auto-followed. Indices in the remote cluster whose names are matching one or more leader_index_patterns and one or more leader_index_exclusion_patterns won’t be followed.
The maximum number of outstanding reads requests from the remote cluster.
Default value is 12.
Settings to override from the leader index. Note that certain settings can not be overrode (e.g., index.number_of_shards).
The maximum number of outstanding reads requests from the remote cluster.
Default value is 9.
The maximum time to wait for new operations on the remote cluster when the follower index is synchronized with the leader index. When the timeout has elapsed, the poll for operations will return to the follower so that it can update some statistics. Then the follower will immediately attempt to read from the leader again.
The maximum number of operations to pull per read from the remote cluster.
Default value is 5120.
The maximum time to wait before retrying an operation that failed exceptionally. An exponential backoff strategy is employed when retrying.
The maximum number of operations that can be queued for writing. When this limit is reached, reads from the remote cluster will be deferred until the number of queued operations goes below the limit.
Default value is 2147483647.
The maximum total bytes of operations that can be queued for writing. When this limit is reached, reads from the remote cluster will be deferred until the total bytes of queued operations goes below the limit.
The maximum number of operations per bulk write request executed on the follower.
Default value is 5120.
PUT /_ccr/auto_follow/my_auto_follow_pattern
{
"remote_cluster" : "remote_cluster",
"leader_index_patterns" :
[
"leader_index*"
],
"follow_index_pattern" : "{{leader_index}}-follower",
"settings": {
"index.number_of_replicas": 0
},
"max_read_request_operation_count" : 1024,
"max_outstanding_read_requests" : 16,
"max_read_request_size" : "1024k",
"max_write_request_operation_count" : 32768,
"max_write_request_size" : "16k",
"max_outstanding_write_requests" : 8,
"max_write_buffer_count" : 512,
"max_write_buffer_size" : "512k",
"max_retry_delay" : "10s",
"read_poll_timeout" : "30s"
}resp = client.ccr.put_auto_follow_pattern(
name="my_auto_follow_pattern",
remote_cluster="remote_cluster",
leader_index_patterns=[
"leader_index*"
],
follow_index_pattern="{{leader_index}}-follower",
settings={
"index.number_of_replicas": 0
},
max_read_request_operation_count=1024,
max_outstanding_read_requests=16,
max_read_request_size="1024k",
max_write_request_operation_count=32768,
max_write_request_size="16k",
max_outstanding_write_requests=8,
max_write_buffer_count=512,
max_write_buffer_size="512k",
max_retry_delay="10s",
read_poll_timeout="30s",
)const response = await client.ccr.putAutoFollowPattern({
name: "my_auto_follow_pattern",
remote_cluster: "remote_cluster",
leader_index_patterns: ["leader_index*"],
follow_index_pattern: "{{leader_index}}-follower",
settings: {
"index.number_of_replicas": 0,
},
max_read_request_operation_count: 1024,
max_outstanding_read_requests: 16,
max_read_request_size: "1024k",
max_write_request_operation_count: 32768,
max_write_request_size: "16k",
max_outstanding_write_requests: 8,
max_write_buffer_count: 512,
max_write_buffer_size: "512k",
max_retry_delay: "10s",
read_poll_timeout: "30s",
});response = client.ccr.put_auto_follow_pattern(
name: "my_auto_follow_pattern",
body: {
"remote_cluster": "remote_cluster",
"leader_index_patterns": [
"leader_index*"
],
"follow_index_pattern": "{{leader_index}}-follower",
"settings": {
"index.number_of_replicas": 0
},
"max_read_request_operation_count": 1024,
"max_outstanding_read_requests": 16,
"max_read_request_size": "1024k",
"max_write_request_operation_count": 32768,
"max_write_request_size": "16k",
"max_outstanding_write_requests": 8,
"max_write_buffer_count": 512,
"max_write_buffer_size": "512k",
"max_retry_delay": "10s",
"read_poll_timeout": "30s"
}
)$resp = $client->ccr()->putAutoFollowPattern([
"name" => "my_auto_follow_pattern",
"body" => [
"remote_cluster" => "remote_cluster",
"leader_index_patterns" => array(
"leader_index*",
),
"follow_index_pattern" => "{{leader_index}}-follower",
"settings" => [
"index.number_of_replicas" => 0,
],
"max_read_request_operation_count" => 1024,
"max_outstanding_read_requests" => 16,
"max_read_request_size" => "1024k",
"max_write_request_operation_count" => 32768,
"max_write_request_size" => "16k",
"max_outstanding_write_requests" => 8,
"max_write_buffer_count" => 512,
"max_write_buffer_size" => "512k",
"max_retry_delay" => "10s",
"read_poll_timeout" => "30s",
],
]);curl -X PUT -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"remote_cluster":"remote_cluster","leader_index_patterns":["leader_index*"],"follow_index_pattern":"{{leader_index}}-follower","settings":{"index.number_of_replicas":0},"max_read_request_operation_count":1024,"max_outstanding_read_requests":16,"max_read_request_size":"1024k","max_write_request_operation_count":32768,"max_write_request_size":"16k","max_outstanding_write_requests":8,"max_write_buffer_count":512,"max_write_buffer_size":"512k","max_retry_delay":"10s","read_poll_timeout":"30s"}' "$ELASTICSEARCH_URL/_ccr/auto_follow/my_auto_follow_pattern"client.ccr().putAutoFollowPattern(p -> p
.followIndexPattern("{{leader_index}}-follower")
.leaderIndexPatterns("leader_index*")
.maxOutstandingReadRequests(16)
.maxOutstandingWriteRequests(8)
.maxReadRequestOperationCount(1024)
.maxReadRequestSize("1024k")
.maxRetryDelay(m -> m
.time("10s")
)
.maxWriteBufferCount(512)
.maxWriteBufferSize("512k")
.maxWriteRequestOperationCount(32768)
.maxWriteRequestSize("16k")
.name("my_auto_follow_pattern")
.readPollTimeout(r -> r
.time("30s")
)
.remoteCluster("remote_cluster")
.settings("index.number_of_replicas", JsonData.fromJson("0"))
);
{
"remote_cluster" : "remote_cluster",
"leader_index_patterns" :
[
"leader_index*"
],
"follow_index_pattern" : "{{leader_index}}-follower",
"settings": {
"index.number_of_replicas": 0
},
"max_read_request_operation_count" : 1024,
"max_outstanding_read_requests" : 16,
"max_read_request_size" : "1024k",
"max_write_request_operation_count" : 32768,
"max_write_request_size" : "16k",
"max_outstanding_write_requests" : 8,
"max_write_buffer_count" : 512,
"max_write_buffer_size" : "512k",
"max_retry_delay" : "10s",
"read_poll_timeout" : "30s"
}{
"acknowledged": true
}Create a cross-cluster replication follower index that follows a specific leader index. When the API returns, the follower index exists and cross-cluster replication starts replicating operations from the leader index to the follower index.
Period to wait for a connection to the master node.
Values are -1 or 0.
Specifies the number of shards to wait on being active before responding. This defaults to waiting on none of the shards to be active. A shard must be restored from the leader index before being active. Restoring a follower shard requires transferring all the remote Lucene segment files to the follower index.
Values are all or index-setting.
If the leader index is part of a data stream, the name to which the local data stream for the followed index should be renamed.
The name of the index in the leader cluster to follow.
The maximum number of outstanding reads requests from the remote cluster.
The maximum number of outstanding write requests on the follower.
The maximum number of operations to pull per read from the remote cluster.
The maximum time to wait before retrying an operation that failed exceptionally. An exponential backoff strategy is employed when retrying.
The maximum number of operations that can be queued for writing. When this limit is reached, reads from the remote cluster will be deferred until the number of queued operations goes below the limit.
The maximum total bytes of operations that can be queued for writing. When this limit is reached, reads from the remote cluster will be deferred until the total bytes of queued operations goes below the limit.
The maximum number of operations per bulk write request executed on the follower.
The maximum time to wait for new operations on the remote cluster when the follower index is synchronized with the leader index. When the timeout has elapsed, the poll for operations will return to the follower so that it can update some statistics. Then the follower will immediately attempt to read from the leader again.
The remote cluster containing the leader index.
Settings to override from the leader index.
PUT /follower_index/_ccr/follow?wait_for_active_shards=1
{
"remote_cluster" : "remote_cluster",
"leader_index" : "leader_index",
"settings": {
"index.number_of_replicas": 0
},
"max_read_request_operation_count" : 1024,
"max_outstanding_read_requests" : 16,
"max_read_request_size" : "1024k",
"max_write_request_operation_count" : 32768,
"max_write_request_size" : "16k",
"max_outstanding_write_requests" : 8,
"max_write_buffer_count" : 512,
"max_write_buffer_size" : "512k",
"max_retry_delay" : "10s",
"read_poll_timeout" : "30s"
}resp = client.ccr.follow(
index="follower_index",
wait_for_active_shards="1",
remote_cluster="remote_cluster",
leader_index="leader_index",
settings={
"index.number_of_replicas": 0
},
max_read_request_operation_count=1024,
max_outstanding_read_requests=16,
max_read_request_size="1024k",
max_write_request_operation_count=32768,
max_write_request_size="16k",
max_outstanding_write_requests=8,
max_write_buffer_count=512,
max_write_buffer_size="512k",
max_retry_delay="10s",
read_poll_timeout="30s",
)const response = await client.ccr.follow({
index: "follower_index",
wait_for_active_shards: 1,
remote_cluster: "remote_cluster",
leader_index: "leader_index",
settings: {
"index.number_of_replicas": 0,
},
max_read_request_operation_count: 1024,
max_outstanding_read_requests: 16,
max_read_request_size: "1024k",
max_write_request_operation_count: 32768,
max_write_request_size: "16k",
max_outstanding_write_requests: 8,
max_write_buffer_count: 512,
max_write_buffer_size: "512k",
max_retry_delay: "10s",
read_poll_timeout: "30s",
});response = client.ccr.follow(
index: "follower_index",
wait_for_active_shards: "1",
body: {
"remote_cluster": "remote_cluster",
"leader_index": "leader_index",
"settings": {
"index.number_of_replicas": 0
},
"max_read_request_operation_count": 1024,
"max_outstanding_read_requests": 16,
"max_read_request_size": "1024k",
"max_write_request_operation_count": 32768,
"max_write_request_size": "16k",
"max_outstanding_write_requests": 8,
"max_write_buffer_count": 512,
"max_write_buffer_size": "512k",
"max_retry_delay": "10s",
"read_poll_timeout": "30s"
}
)$resp = $client->ccr()->follow([
"index" => "follower_index",
"wait_for_active_shards" => "1",
"body" => [
"remote_cluster" => "remote_cluster",
"leader_index" => "leader_index",
"settings" => [
"index.number_of_replicas" => 0,
],
"max_read_request_operation_count" => 1024,
"max_outstanding_read_requests" => 16,
"max_read_request_size" => "1024k",
"max_write_request_operation_count" => 32768,
"max_write_request_size" => "16k",
"max_outstanding_write_requests" => 8,
"max_write_buffer_count" => 512,
"max_write_buffer_size" => "512k",
"max_retry_delay" => "10s",
"read_poll_timeout" => "30s",
],
]);curl -X PUT -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"remote_cluster":"remote_cluster","leader_index":"leader_index","settings":{"index.number_of_replicas":0},"max_read_request_operation_count":1024,"max_outstanding_read_requests":16,"max_read_request_size":"1024k","max_write_request_operation_count":32768,"max_write_request_size":"16k","max_outstanding_write_requests":8,"max_write_buffer_count":512,"max_write_buffer_size":"512k","max_retry_delay":"10s","read_poll_timeout":"30s"}' "$ELASTICSEARCH_URL/follower_index/_ccr/follow?wait_for_active_shards=1"client.ccr().follow(f -> f
.index("follower_index")
.leaderIndex("leader_index")
.maxOutstandingReadRequests(16L)
.maxOutstandingWriteRequests(8)
.maxReadRequestOperationCount(1024)
.maxReadRequestSize("1024k")
.maxRetryDelay(m -> m
.time("10s")
)
.maxWriteBufferCount(512)
.maxWriteBufferSize("512k")
.maxWriteRequestOperationCount(32768)
.maxWriteRequestSize("16k")
.readPollTimeout(r -> r
.time("30s")
)
.remoteCluster("remote_cluster")
.settings(s -> s
.otherSettings("index.number_of_replicas", JsonData.fromJson("0"))
)
.waitForActiveShards(w -> w
.count(1)
)
);
{
"remote_cluster" : "remote_cluster",
"leader_index" : "leader_index",
"settings": {
"index.number_of_replicas": 0
},
"max_read_request_operation_count" : 1024,
"max_outstanding_read_requests" : 16,
"max_read_request_size" : "1024k",
"max_write_request_operation_count" : 32768,
"max_write_request_size" : "16k",
"max_outstanding_write_requests" : 8,
"max_write_buffer_count" : 512,
"max_write_buffer_size" : "512k",
"max_retry_delay" : "10s",
"read_poll_timeout" : "30s"
}{
"follow_index_created" : true,
"follow_index_shards_acked" : true,
"index_following_started" : true
}Remove the cross-cluster replication follower retention leases from the leader.
A following index takes out retention leases on its leader index. These leases are used to increase the likelihood that the shards of the leader index retain the history of operations that the shards of the following index need to run replication. When a follower index is converted to a regular index by the unfollow API (either by directly calling the API or by index lifecycle management tasks), these leases are removed. However, removal of the leases can fail, for example when the remote cluster containing the leader index is unavailable. While the leases will eventually expire on their own, their extended existence can cause the leader index to hold more history than necessary and prevent index lifecycle management from performing some operations on the leader index. This API exists to enable manually removing the leases when the unfollow API is unable to do so.
NOTE: This API does not stop replication by a following index. If you use this API with a follower index that is still actively following, the following index will add back retention leases on the leader. The only purpose of this API is to handle the case of failure to remove the following retention leases after the unfollow API is invoked.
the name of the leader index for which specified follower retention leases should be removed
Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error.
Values are -1 or 0.
POST /<leader_index>/_ccr/forget_follower
{
"follower_cluster" : "<follower_cluster>",
"follower_index" : "<follower_index>",
"follower_index_uuid" : "<follower_index_uuid>",
"leader_remote_cluster" : "<leader_remote_cluster>"
}resp = client.ccr.forget_follower(
index="<leader_index>",
follower_cluster="<follower_cluster>",
follower_index="<follower_index>",
follower_index_uuid="<follower_index_uuid>",
leader_remote_cluster="<leader_remote_cluster>",
)const response = await client.ccr.forgetFollower({
index: "<leader_index>",
follower_cluster: "<follower_cluster>",
follower_index: "<follower_index>",
follower_index_uuid: "<follower_index_uuid>",
leader_remote_cluster: "<leader_remote_cluster>",
});response = client.ccr.forget_follower(
index: "<leader_index>",
body: {
"follower_cluster": "<follower_cluster>",
"follower_index": "<follower_index>",
"follower_index_uuid": "<follower_index_uuid>",
"leader_remote_cluster": "<leader_remote_cluster>"
}
)$resp = $client->ccr()->forgetFollower([
"index" => "<leader_index>",
"body" => [
"follower_cluster" => "<follower_cluster>",
"follower_index" => "<follower_index>",
"follower_index_uuid" => "<follower_index_uuid>",
"leader_remote_cluster" => "<leader_remote_cluster>",
],
]);curl -X POST -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"follower_cluster":"<follower_cluster>","follower_index":"<follower_index>","follower_index_uuid":"<follower_index_uuid>","leader_remote_cluster":"<leader_remote_cluster>"}' "$ELASTICSEARCH_URL/<leader_index>/_ccr/forget_follower"client.ccr().forgetFollower(f -> f
.followerCluster("<follower_cluster>")
.followerIndex("<follower_index>")
.followerIndexUuid("<follower_index_uuid>")
.index("<leader_index>")
.leaderRemoteCluster("<leader_remote_cluster>")
);
{
"follower_cluster" : "<follower_cluster>",
"follower_index" : "<follower_index>",
"follower_index_uuid" : "<follower_index_uuid>",
"leader_remote_cluster" : "<leader_remote_cluster>"
}{
"_shards" : {
"total" : 1,
"successful" : 1,
"failed" : 0,
"failures" : [ ]
}
}Pause a cross-cluster replication auto-follow pattern. When the API returns, the auto-follow pattern is inactive. New indices that are created on the remote cluster and match the auto-follow patterns are ignored.
You can resume auto-following with the resume auto-follow pattern API. When it resumes, the auto-follow pattern is active again and automatically configures follower indices for newly created indices on the remote cluster that match its patterns. Remote indices that were created while the pattern was paused will also be followed, unless they have been deleted or closed in the interim.
manage_ccrPOST /_ccr/auto_follow/my_auto_follow_pattern/pause
resp = client.ccr.pause_auto_follow_pattern(
name="my_auto_follow_pattern",
)const response = await client.ccr.pauseAutoFollowPattern({
name: "my_auto_follow_pattern",
});response = client.ccr.pause_auto_follow_pattern(
name: "my_auto_follow_pattern"
)$resp = $client->ccr()->pauseAutoFollowPattern([
"name" => "my_auto_follow_pattern",
]);curl -X POST -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_ccr/auto_follow/my_auto_follow_pattern/pause"client.ccr().pauseAutoFollowPattern(p -> p
.name("my_auto_follow_pattern")
);
{
"acknowledged" : true
}Pause a cross-cluster replication follower index. The follower index will not fetch any additional operations from the leader index. You can resume following with the resume follower API. You can pause and resume a follower index to change the configuration of the following task.
manage_ccrPOST /follower_index/_ccr/pause_follow
resp = client.ccr.pause_follow(
index="follower_index",
)const response = await client.ccr.pauseFollow({
index: "follower_index",
});response = client.ccr.pause_follow(
index: "follower_index"
)$resp = $client->ccr()->pauseFollow([
"index" => "follower_index",
]);curl -X POST -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/follower_index/_ccr/pause_follow"client.ccr().pauseFollow(p -> p
.index("follower_index")
);
{
"acknowledged" : true
}