start on create index from source

Author: parkertimmins

docs/reference/indices/create-index-from-source.asciidoc

@@ -0,0 +1,256 @@
+[[indices-create-index-from-source]]
+=== Create index from source API
+++++
+<titleabbrev>Create index from source</titleabbrev>
+++++
+
+.New API reference
+[sidebar]
+--
+For the most up-to-date API details, refer to {api-es}/group/endpoint-indices[Index APIs].
+--
+
+Creates a new index.
+
+[source,console]
+--------------------------------------------------
+POST /_create_from/my-index/another-index/
+--------------------------------------------------
+
+[[indices-create-index-from-source-api-request]]
+==== {api-request-title}
+
+`PUT /_create_from/<source>/<dest>`
+
+`POST/_create_from/<source>/<dest>`
+
+[[indices-create-index-from-source-api-prereqs]]
+==== {api-prereq-title}
+
+* If the {es} {security-features} are enabled, you must have the `create_index`
+or `manage` <<privileges-list-indices,index privilege>> for the target index. To
+add the index to an alias, you must have the `manage` index privilege for the
+alias.
+
+[[indices-create-index-from-source-api-desc]]
+==== {api-description-title}
+This api allows you to add a new index to an {es} cluster, using an existing source index as a basis for the new index.
+The settings and mappings from the source index will copied over to the destination index.  You can also provide
+override settings and mappings which will be combined with the source settings and mappings when creating the
+destination index.
+
+[[indices-create-index-from-source-api-path-params]]
+==== {api-path-parms-title}
+
+`<source>`::
+(Required, string) Name of the existing source index which will be used as a basis.
+
+`<dest>`::
+(Required, string) Name of the destination index which will be created.
+
+
+
+[role="child_attributes"]
+[[indices-create-api-request-body]]
+==== {api-request-body-title}
+
+`aliases`::
+(Optional, object of objects) Aliases for the index.
++
+--
+// tag::aliases-props[]
+[%collapsible%open]
+.Properties of `aliases` objects
+=======
+`<alias>`::
+(Required, object) The key is the alias name. Index alias names support
+<<api-date-math-index-names,date math>>.
++
+The object body contains options for the alias. Supports an empty object.
++
+.Properties of `<alias>`
+[%collapsible%open]
+======
+`filter`::
+(Optional, <<query-dsl,Query DSL object>>) Query used to limit documents the
+alias can access.
+
+`index_routing`::
+(Optional, string) Value used to route indexing operations to a specific shard.
+If specified, this overwrites the `routing` value for indexing operations.
+
+`is_hidden`::
+(Optional, Boolean) If `true`, the alias is <<multi-hidden,hidden>>. Defaults to
+`false`. All indices for the alias must have the same `is_hidden` value.
+
+`is_write_index`::
+(Optional, Boolean) If `true`, the index is the <<write-index,write index>> for
+the alias. Defaults to `false`.
+
+`routing`::
+(Optional, string) Value used to route indexing and search operations to a
+specific shard.
+
+`search_routing`::
+(Optional, string) Value used to route search operations to a specific shard. If
+specified, this overwrites the `routing` value for search operations.
+======
+=======
+// end::aliases-props[]
+--
+
+include::{es-ref-dir}/rest-api/common-parms.asciidoc[tag=mappings]
+
+include::{es-ref-dir}/rest-api/common-parms.asciidoc[tag=settings]
+
+[[indices-create-api-example]]
+==== {api-examples-title}
+
+[[create-index-settings]]
+===== Index settings
+
+Each index created can have specific settings
+associated with it, defined in the body:
+
+[source,console]
+--------------------------------------------------
+PUT /my-index-000001
+{
+  "settings": {
+    "index": {
+      "number_of_shards": 3,  <1>
+      "number_of_replicas": 2 <2>
+    }
+  }
+}
+--------------------------------------------------
+
+<1> Default for `number_of_shards` is 1
+<2> Default for `number_of_replicas` is 1 (ie one replica for each primary shard)
+
+or more simplified
+
+[source,console]
+--------------------------------------------------
+PUT /my-index-000001
+{
+  "settings": {
+    "number_of_shards": 3,
+    "number_of_replicas": 2
+  }
+}
+--------------------------------------------------
+
+[NOTE]
+You do not have to explicitly specify `index` section inside the
+`settings` section.
+
+For more information regarding all the different index level settings
+that can be set when creating an index, please check the
+<<index-modules,index modules>> section.
+
+[[mappings]]
+===== Mappings
+
+The create index API allows for providing a mapping definition:
+
+[source,console]
+--------------------------------------------------
+PUT /test
+{
+  "settings": {
+    "number_of_shards": 1
+  },
+  "mappings": {
+    "properties": {
+      "field1": { "type": "text" }
+    }
+  }
+}
+--------------------------------------------------
+
+[[create-index-aliases]]
+===== Aliases
+
+The create index API allows also to provide a set of <<aliases,aliases>>:
+
+[source,console]
+--------------------------------------------------
+PUT /test
+{
+  "aliases": {
+    "alias_1": {},
+    "alias_2": {
+      "filter": {
+        "term": { "user.id": "kimchy" }
+      },
+      "routing": "shard-1"
+    }
+  }
+}
+--------------------------------------------------
+
+Index alias names also support <<api-date-math-index-names,date math>>.
+
+[source,console]
+----
+PUT /logs
+{
+  "aliases": {
+    "<logs_{now/M}>": {}
+  }
+}
+----
+
+[[create-index-wait-for-active-shards]]
+===== Wait for active shards
+
+By default, index creation will only return a response to the client when the primary copies of
+each shard have been started, or the request times out. The index creation response will indicate
+what happened:
+
+[source,console-result]
+--------------------------------------------------
+{
+  "acknowledged": true,
+  "shards_acknowledged": true,
+  "index": "logs"
+}
+--------------------------------------------------
+
+`acknowledged` indicates whether the index was successfully created in the cluster, while
+`shards_acknowledged` indicates whether the requisite number of shard copies were started for
+each shard in the index before timing out. Note that it is still possible for either
+`acknowledged` or `shards_acknowledged` to be `false`, but the index creation was successful.
+These values simply indicate whether the operation completed before the timeout. If
+`acknowledged` is `false`, then we timed out before the cluster state was updated with the
+newly created index, but it probably will be created sometime soon. If `shards_acknowledged`
+is `false`, then we timed out before the requisite number of shards were started (by default
+just the primaries), even if the cluster state was successfully updated to reflect the newly
+created index (i.e. `acknowledged=true`).
+
+We can change the default of only waiting for the primary shards to start through the index
+setting `index.write.wait_for_active_shards` (note that changing this setting will also affect
+the `wait_for_active_shards` value on all subsequent write operations):
+
+[source,console]
+--------------------------------------------------
+PUT /test
+{
+  "settings": {
+    "index.write.wait_for_active_shards": "2"
+  }
+}
+--------------------------------------------------
+// TEST[skip:requires two nodes]
+
+or through the request parameter `wait_for_active_shards`:
+
+[source,console]
+--------------------------------------------------
+PUT /test?wait_for_active_shards=2
+--------------------------------------------------
+// TEST[skip:requires two nodes]
+
+A detailed explanation of `wait_for_active_shards` and its possible values can be found
+<<index-wait-for-active-shards,here>>.