From 94a7978ef615fb53bdc5d739846e721a93fa6c84 Mon Sep 17 00:00:00 2001 From: Areek Zillur Date: Wed, 8 Jun 2016 18:32:22 -0400 Subject: [PATCH] add documentation --- .../admin/indices/rollover/Condition.java | 13 ++- .../indices/rollover/MaxAgeCondition.java | 4 + .../indices/rollover/MaxDocsCondition.java | 4 + .../indices/rollover/RolloverRequest.java | 55 +++++++----- .../rollover/RolloverRequestBuilder.java | 3 - .../indices/rollover/RolloverResponse.java | 18 ++++ .../rollover/TransportRolloverAction.java | 2 +- docs/reference/indices.asciidoc | 1 + .../reference/indices/rollover-index.asciidoc | 84 +++++++++++++++++++ 9 files changed, 159 insertions(+), 25 deletions(-) create mode 100644 docs/reference/indices/rollover-index.asciidoc diff --git a/core/src/main/java/org/elasticsearch/action/admin/indices/rollover/Condition.java b/core/src/main/java/org/elasticsearch/action/admin/indices/rollover/Condition.java index 12c3ef45993..8d9b48f2000 100644 --- a/core/src/main/java/org/elasticsearch/action/admin/indices/rollover/Condition.java +++ b/core/src/main/java/org/elasticsearch/action/admin/indices/rollover/Condition.java @@ -27,12 +27,17 @@ import org.elasticsearch.common.xcontent.ObjectParser; import java.util.Set; +/** + * Base class for rollover request conditions + */ public abstract class Condition implements NamedWriteable { + public static ObjectParser, ParseFieldMatcherSupplier> PARSER = new ObjectParser<>("conditions", null); static { PARSER.declareString((conditions, s) -> - conditions.add(new MaxAgeCondition(TimeValue.parseTimeValue(s, MaxAgeCondition.NAME))), new ParseField(MaxAgeCondition.NAME)); + conditions.add(new MaxAgeCondition(TimeValue.parseTimeValue(s, MaxAgeCondition.NAME))), + new ParseField(MaxAgeCondition.NAME)); PARSER.declareLong((conditions, value) -> conditions.add(new MaxDocsCondition(value)), new ParseField(MaxDocsCondition.NAME)); } @@ -51,6 +56,9 @@ public abstract class Condition implements NamedWriteable { return "[" + name + ": " + value + "]"; } + /** + * Holder for index stats used to evaluate conditions + */ public static class Stats { public final long numDocs; public final long indexCreated; @@ -61,6 +69,9 @@ public abstract class Condition implements NamedWriteable { } } + /** + * Holder for evaluated condition result + */ public static class Result { public final Condition condition; public final boolean matched; diff --git a/core/src/main/java/org/elasticsearch/action/admin/indices/rollover/MaxAgeCondition.java b/core/src/main/java/org/elasticsearch/action/admin/indices/rollover/MaxAgeCondition.java index 0a7e85bb129..ee0641bbe18 100644 --- a/core/src/main/java/org/elasticsearch/action/admin/indices/rollover/MaxAgeCondition.java +++ b/core/src/main/java/org/elasticsearch/action/admin/indices/rollover/MaxAgeCondition.java @@ -25,6 +25,10 @@ import org.elasticsearch.common.unit.TimeValue; import java.io.IOException; +/** + * Condition for index maximum age. Evaluates to true + * when the index is at least {@link #value} old + */ public class MaxAgeCondition extends Condition { public final static String NAME = "max_age"; diff --git a/core/src/main/java/org/elasticsearch/action/admin/indices/rollover/MaxDocsCondition.java b/core/src/main/java/org/elasticsearch/action/admin/indices/rollover/MaxDocsCondition.java index e1c599c23d4..8b327929124 100644 --- a/core/src/main/java/org/elasticsearch/action/admin/indices/rollover/MaxDocsCondition.java +++ b/core/src/main/java/org/elasticsearch/action/admin/indices/rollover/MaxDocsCondition.java @@ -24,6 +24,10 @@ import org.elasticsearch.common.io.stream.StreamOutput; import java.io.IOException; +/** + * Condition for maximum index docs. Evaluates to true + * when the index has at least {@link #value} docs + */ public class MaxDocsCondition extends Condition { public final static String NAME = "max_docs"; diff --git a/core/src/main/java/org/elasticsearch/action/admin/indices/rollover/RolloverRequest.java b/core/src/main/java/org/elasticsearch/action/admin/indices/rollover/RolloverRequest.java index a16a6db83ca..abae56cb5fb 100644 --- a/core/src/main/java/org/elasticsearch/action/admin/indices/rollover/RolloverRequest.java +++ b/core/src/main/java/org/elasticsearch/action/admin/indices/rollover/RolloverRequest.java @@ -45,24 +45,18 @@ import java.util.Set; import static org.elasticsearch.action.ValidateActions.addValidationError; /** - * Request class to swap index under an alias given some predicates - * TODO: documentation + * Request class to swap index under an alias upon satisfying conditions */ public class RolloverRequest extends AcknowledgedRequest implements IndicesRequest { - private String alias; - private boolean simulate; - private Set conditions = new HashSet<>(2); - private CreateIndexRequest createIndexRequest = new CreateIndexRequest("_na_"); - public static ObjectParser PARSER = new ObjectParser<>("conditions", null); static { PARSER.declareField((parser, request, parseFieldMatcherSupplier) -> - Condition.PARSER.parse(parser, request.conditions, parseFieldMatcherSupplier), + Condition.PARSER.parse(parser, request.conditions, parseFieldMatcherSupplier), new ParseField("conditions"), ObjectParser.ValueType.OBJECT); PARSER.declareField((parser, request, parseFieldMatcherSupplier) -> - request.createIndexRequest.settings(parser.map()), + request.createIndexRequest.settings(parser.map()), new ParseField("settings"), ObjectParser.ValueType.OBJECT); PARSER.declareField((parser, request, parseFieldMatcherSupplier) -> { for (Map.Entry mappingsEntry : parser.map().entrySet()) { @@ -71,10 +65,15 @@ public class RolloverRequest extends AcknowledgedRequest implem } }, new ParseField("mappings"), ObjectParser.ValueType.OBJECT); PARSER.declareField((parser, request, parseFieldMatcherSupplier) -> - request.createIndexRequest.aliases(parser.map()), + request.createIndexRequest.aliases(parser.map()), new ParseField("aliases"), ObjectParser.ValueType.OBJECT); } + private String alias; + private boolean simulate; + private Set conditions = new HashSet<>(2); + private CreateIndexRequest createIndexRequest = new CreateIndexRequest("_na_"); + RolloverRequest() {} public RolloverRequest(String alias) { @@ -128,42 +127,58 @@ public class RolloverRequest extends AcknowledgedRequest implem return IndicesOptions.strictSingleIndexNoExpandForbidClosed(); } + /** + * Sets the alias to rollover to another index + */ public void setAlias(String alias) { this.alias = alias; } + /** + * Sets if the rollover should not be executed when conditions are met + */ public void simulate(boolean simulate) { this.simulate = simulate; } + /** + * Adds condition to check if the index is at least age old + */ public void addMaxIndexAgeCondition(TimeValue age) { this.conditions.add(new MaxAgeCondition(age)); } - public void addMaxIndexDocsCondition(long docs) { - this.conditions.add(new MaxDocsCondition(docs)); + /** + * Adds condition to check if the index has at least numDocs + */ + public void addMaxIndexDocsCondition(long numDocs) { + this.conditions.add(new MaxDocsCondition(numDocs)); } - public boolean isSimulate() { + /** + * Sets rollover index creation request to override index settings when + * the rolled over index has to be created + */ + public void setCreateIndexRequest(CreateIndexRequest createIndexRequest) { + this.createIndexRequest = Objects.requireNonNull(createIndexRequest, "create index request must not be null");; + } + + boolean isSimulate() { return simulate; } - public Set getConditions() { + Set getConditions() { return conditions; } - public String getAlias() { + String getAlias() { return alias; } - public CreateIndexRequest getCreateIndexRequest() { + CreateIndexRequest getCreateIndexRequest() { return createIndexRequest; } - public void setCreateIndexRequest(CreateIndexRequest createIndexRequest) { - this.createIndexRequest = Objects.requireNonNull(createIndexRequest, "create index request must not be null");; - } - public void source(BytesReference source) { XContentType xContentType = XContentFactory.xContentType(source); if (xContentType != null) { diff --git a/core/src/main/java/org/elasticsearch/action/admin/indices/rollover/RolloverRequestBuilder.java b/core/src/main/java/org/elasticsearch/action/admin/indices/rollover/RolloverRequestBuilder.java index dd6e22dae70..cfce9d24ad4 100644 --- a/core/src/main/java/org/elasticsearch/action/admin/indices/rollover/RolloverRequestBuilder.java +++ b/core/src/main/java/org/elasticsearch/action/admin/indices/rollover/RolloverRequestBuilder.java @@ -25,9 +25,6 @@ import org.elasticsearch.common.settings.Settings; import org.elasticsearch.common.unit.TimeValue; -/** - * TODO: Documentation - */ public class RolloverRequestBuilder extends MasterNodeOperationRequestBuilder { public RolloverRequestBuilder(ElasticsearchClient client, RolloverAction action) { diff --git a/core/src/main/java/org/elasticsearch/action/admin/indices/rollover/RolloverResponse.java b/core/src/main/java/org/elasticsearch/action/admin/indices/rollover/RolloverResponse.java index fbca8af99cc..14feec0248f 100644 --- a/core/src/main/java/org/elasticsearch/action/admin/indices/rollover/RolloverResponse.java +++ b/core/src/main/java/org/elasticsearch/action/admin/indices/rollover/RolloverResponse.java @@ -56,26 +56,44 @@ public final class RolloverResponse extends ActionResponse implements ToXContent .collect(Collectors.toSet()); } + /** + * Returns the name of the index that the request alias was pointing to + */ public String getOldIndex() { return oldIndex; } + /** + * Returns the name of the index that the request alias currently points to + */ public String getNewIndex() { return newIndex; } + /** + * Returns the statuses of all the request conditions + */ public Set> getConditionStatus() { return conditionStatus; } + /** + * Returns if the rollover execution was skipped even when conditions were met + */ public boolean isSimulate() { return simulate; } + /** + * Returns if the rollover was not simulated and the conditions were met + */ public boolean isRolledOver() { return rolledOver; } + /** + * Returns if the rollover index had to be explicitly created + */ public boolean isRolloverIndexCreated() { return rolloverIndexCreated; } diff --git a/core/src/main/java/org/elasticsearch/action/admin/indices/rollover/TransportRolloverAction.java b/core/src/main/java/org/elasticsearch/action/admin/indices/rollover/TransportRolloverAction.java index 61ae2852f68..0cd29b84056 100644 --- a/core/src/main/java/org/elasticsearch/action/admin/indices/rollover/TransportRolloverAction.java +++ b/core/src/main/java/org/elasticsearch/action/admin/indices/rollover/TransportRolloverAction.java @@ -51,7 +51,7 @@ import java.util.regex.Pattern; import java.util.stream.Collectors; /** - * Main class to swap the index pointed to by an alias, given some predicates + * Main class to swap the index pointed to by an alias, given some conditions */ public class TransportRolloverAction extends TransportMasterNodeAction { diff --git a/docs/reference/indices.asciidoc b/docs/reference/indices.asciidoc index e49340fe15f..cad1a1477bd 100644 --- a/docs/reference/indices.asciidoc +++ b/docs/reference/indices.asciidoc @@ -16,6 +16,7 @@ index settings, aliases, mappings, and index templates. * <> * <> * <> +* <> [float] [[mapping-management]] diff --git a/docs/reference/indices/rollover-index.asciidoc b/docs/reference/indices/rollover-index.asciidoc new file mode 100644 index 00000000000..2c553a4e0f1 --- /dev/null +++ b/docs/reference/indices/rollover-index.asciidoc @@ -0,0 +1,84 @@ +[[indices-rollover-index]] +== Rollover Index + +The rollover index API allows to switch the index pointed to by an alias given some predicates. +In order to rollover an index, the provided alias has to point to a single index. Upon satisfying +any of the predicates, the alias is switched to point to a new index, creating the index if it +does not exist. The rollover API requires the old concrete index name to have `{index_prefix}-{num}` +format, as rollover index name is generated following `{index_prefix}-{num+1}` format. + +This API is syntactic sugar for changing the index pointed to by an alias given some predicate. + +The rollover API must be used against an alias that points to a single index: + +[source,js] +-------------------------------------------------- +$ curl -XPUT 'http://localhost:9200/index-1/' -d '{ + "aliases" : { + "index_alias": {} + } +}' +-------------------------------------------------- + +To rollover `index_alias` to point to a new index: + +[source,js] +-------------------------------------------------- +$ curl -XPOST 'http://localhost:9200/index_alias/_rollover' -d '{ + "conditions" : { + "max_age": "7d", <1> + "max_docs": 1000 <2> + } +}' +-------------------------------------------------- +<1> Sets a condition that the index has to be at least 7 days old +<2> Sets a condition that the index has to have at least a 1000 documents + +The API call above switches the index pointed to by `index_alias` from `index-1` to `index-2`, if any +of the conditions are met. If `index-2` does not exist, it is created (using matching <> +if available). The API call returns immediately if none of the conditions are met. + +The `_rollover` API is similar to <> and accepts `settings`, `mappings` and `aliases` +to override the index create request for a non-existent rolled over index. + +[source,js] +-------------------------------------------------- +$ curl -XPOST 'http://localhost:9200/index_alias/_rollover' -d '{ + "conditions" : { + "max_age": "7d", + "max_docs": 1000 + }, + "settings": { <1> + "index.number_of_shards": 2 + } +}' +-------------------------------------------------- +<1> Set settings to override matching index template, `mappings` and `aliases` can also be provided. + +Using the http `GET` method for the API runs the rollover in simulated mode, where request conditions can be +checked without performing the actual rollover. Setting `simulate=true` as a request parameter also runs +the request in simulated mode. + +An example response for the index rollover API: + +[source,js] +-------------------------------------------------- +{ + "old_index": "index-1", <1> + "new_index": "index-2", <2> + "rolled_over": true, <3> + "simulated": false, <4> + "rollover_index_created": true, <5> + "conditions": { <6> + "[max_age: 7d]": true, + "[max_docs: 1000]": true + } +} +-------------------------------------------------- +<1> name of the index the alias was pointing to +<2> name of the index the alias currently points to +<3> whether the alias switch was successful +<4> whether the rollover was dry run +<5> whether the rolled over index had to be explicitly created +<6> status of the evaluated request conditions +