You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@lucene.apache.org by sh...@apache.org on 2017/06/27 05:19:34 UTC
[23/27] lucene-solr:feature/autoscaling: SOLR-10892: Phase 2: large
pages with lots of tables + lots of heading cleanups & TOC placement changes
SOLR-10892: Phase 2: large pages with lots of tables + lots of heading cleanups & TOC placement changes
Project: http://git-wip-us.apache.org/repos/asf/lucene-solr/repo
Commit: http://git-wip-us.apache.org/repos/asf/lucene-solr/commit/93c96b06
Tree: http://git-wip-us.apache.org/repos/asf/lucene-solr/tree/93c96b06
Diff: http://git-wip-us.apache.org/repos/asf/lucene-solr/diff/93c96b06
Branch: refs/heads/feature/autoscaling
Commit: 93c96b06fb8ffa1f4a424356d699820d8e3c4d8f
Parents: 8da926e
Author: Cassandra Targett <ct...@apache.org>
Authored: Mon Jun 26 22:16:40 2017 -0500
Committer: Cassandra Targett <ct...@apache.org>
Committed: Mon Jun 26 22:17:59 2017 -0500
----------------------------------------------------------------------
solr/solr-ref-guide/src/collections-api.adoc | 1044 +++++++++---------
solr/solr-ref-guide/src/coreadmin-api.adoc | 276 +++--
solr/solr-ref-guide/src/format-of-solr-xml.adoc | 174 +--
solr/solr-ref-guide/src/function-queries.adoc | 410 +++++--
solr/solr-ref-guide/src/highlighting.adoc | 299 +++--
solr/solr-ref-guide/src/other-parsers.adoc | 169 +--
solr/solr-ref-guide/src/query-re-ranking.adoc | 15 +-
solr/solr-ref-guide/src/schema-api.adoc | 361 ++----
.../src/solr-control-script-reference.adoc | 520 +++++----
9 files changed, 1747 insertions(+), 1521 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/lucene-solr/blob/93c96b06/solr/solr-ref-guide/src/collections-api.adoc
----------------------------------------------------------------------
diff --git a/solr/solr-ref-guide/src/collections-api.adoc b/solr/solr-ref-guide/src/collections-api.adoc
index 3b8541e..3a43d39 100644
--- a/solr/solr-ref-guide/src/collections-api.adoc
+++ b/solr/solr-ref-guide/src/collections-api.adoc
@@ -1,6 +1,8 @@
= Collections API
:page-shortname: collections-api
:page-permalink: collections-api.html
+:page-toclevels: 1
+:page-tocclass: right
// Licensed to the Apache Software Foundation (ASF) under one
// or more contributor license agreements. See the NOTICE file
// distributed with this work for additional information
@@ -18,59 +20,91 @@
// specific language governing permissions and limitations
// under the License.
-The Collections API is used to enable you to create, remove, or reload collections, but in the context of SolrCloud you can also use it to create collections with a specific number of shards and replicas.
+The Collections API is used to create, remove, or reload collections.
+
+In the context of SolrCloud you can use it to create collections with a specific number of shards and replicas, move replicas or shards, and create or delete collection aliases.
[[CollectionsAPI-create]]
== CREATE: Create a Collection
-`/admin/collections?action=CREATE&name=_name_&numShards=_number_&replicationFactor=_number_&maxShardsPerNode=_number_&createNodeSet=_nodelist_&collection.configName=_configname_`
+`/admin/collections?action=CREATE&name=_name_`
+
+=== CREATE Parameters
-[[CollectionsAPI-Input]]
-=== Input
+The CREATE action allows the following parameters:
-*Query Parameters*
+`name`::
+The name of the collection to be created. This parameter is required.
-// TODO: Change column width to %autowidth.spread when https://github.com/asciidoctor/asciidoctor-pdf/issues/599 is fixed
+`router.name`::
+The router name that will be used. The router defines how documents will be distributed among the shards. Possible values are `implicit` or `compositeId`, which is the default.
++
+The `implicit` router does not automatically route documents to different shards. Whichever shard you indicate on the indexing request (or within each document) will be used as the destination for those documents.
++
+The `compositeId` router hashes the value in the uniqueKey field and looks up that hash in the collection's clusterstate to determine which shard will receive the document, with the additional ability to manually direct the routing.
++
+When using the `implicit` router, the `shards` parameter is required. When using the `compositeId` router, the `numShards` parameter is required.
++
+For more information, see also the section <<shards-and-indexing-data-in-solrcloud.adoc#ShardsandIndexingDatainSolrCloud-DocumentRouting,Document Routing>>.
-[cols="25,10,10,15,40",options="header"]
-|===
-|Key |Type |Required |Default |Description
-|name |string |Yes | |The name of the collection to be created.
-|router.name |string |No |compositeId |The router name that will be used. The router defines how documents will be distributed among the shards. Possible values are *implicit* or *compositeId*.
+`numShards`::
+The number of shards to be created as part of the collection. This is a required parameter when the `router.name` is `compositeId`.
-The 'implicit' router does not automatically route documents to different shards. Whichever shard you indicate on the indexing request (or within each document) will be used as the destination for those documents.
+`shards`::
+A comma separated list of shard names, e.g., `shard-x,shard-y,shard-z`. This is a required parameter when the `router.name` is `implicit`.
-The 'compositeId' router hashes the value in the uniqueKey field and looks up that hash in the collection's clusterstate to determine which shard will receive the document, with the additional ability to manually direct the routing.
+`replicationFactor`::
+The number of replicas to be created for each shard. The default is `1`.
-When using the 'implicit' router, the `shards` parameter is required. When using the 'compositeId' router, the `numShards` parameter is required.
+`maxShardsPerNode`::
+When creating collections, the shards and/or replicas are spread across all available (i.e., live) nodes, and two replicas of the same shard will never be on the same node.
++
+If a node is not live when the CREATE action is called, it will not get any parts of the new collection, which could lead to too many replicas being created on a single live node. Defining `maxShardsPerNode` sets a limit on the number of replicas the CREATE action will spread to each node.
++
+If the entire collection can not be fit into the live nodes, no collection will be created at all. The default `maxShardsPerNode` value is `1`.
-For more information, see also the section <<shards-and-indexing-data-in-solrcloud.adoc#ShardsandIndexingDatainSolrCloud-DocumentRouting,Document Routing>>.
-|numShards |integer |No |empty |The number of shards to be created as part of the collection. This is a required parameter when using the 'compositeId' router.
-|shards |string |No |empty |A comma separated list of shard names, e.g., shard-x,shard-y,shard-z. This is a required parameter when using the 'implicit' router.
-|replicationFactor |integer |No |1 |The number of replicas to be created for each shard.
-|maxShardsPerNode |integer |No |1 |When creating collections, the shards and/or replicas are spread across all available (i.e., live) nodes, and two replicas of the same shard will never be on the same node. If a node is not live when the CREATE operation is called, it will not get any parts of the new collection, which could lead to too many replicas being created on a single live node. Defining `maxShardsPerNode` sets a limit on the number of replicas CREATE will spread to each node. If the entire collection can not be fit into the live nodes, no collection will be created at all.
-|createNodeSet |string |No | |Allows defining the nodes to spread the new collection across. If not provided, the CREATE operation will create shard-replica spread across all live Solr nodes. The format is a comma-separated list of node_names, such as `localhost:8983_solr,` `localhost:8984_solr,` `localhost:8985_solr`. Alternatively, use the special value of `EMPTY` to initially create no shard-replica within the new collection and then later use the <<CollectionsAPI-addreplica,ADDREPLICA>> operation to add shard-replica when and where required.
-|createNodeSet.shuffle |boolean |No |true a|
-Controls wether or not the shard-replicas created for this collection will be assigned to the nodes specified by the createNodeSet in a sequential manner, or if the list of nodes should be shuffled prior to creating individual replicas. A 'false' value makes the results of a collection creation predictible and gives more exact control over the location of the individual shard-replicas, but 'true' can be a better choice for ensuring replicas are distributed evenly across nodes.
-
-Ignored if createNodeSet is not also specified.
-
-|collection.configName |string |No |empty |Defines the name of the configurations (which must already be stored in ZooKeeper) to use for this collection. If not provided, Solr will default to the collection name as the configuration name.
-|router.field |string |No |empty |If this field is specified, the router will look at the value of the field in an input document to compute the hash and identify a shard instead of looking at the `uniqueKey` field. If the field specified is null in the document, the document will be rejected. Please note that <<realtime-get.adoc#realtime-get,RealTime Get>> or retrieval by id would also require the parameter `\_route_` (or `shard.keys`) to avoid a distributed search.
-|property._name_=_value_ |string |No | |Set core property _name_ to _value_. See the section <<defining-core-properties.adoc#defining-core-properties,Defining core.properties>> for details on supported properties and values.
-|autoAddReplicas |boolean |No |false |When set to true, enables auto addition of replicas on shared file systems. See the section <<running-solr-on-hdfs.adoc#RunningSolronHDFS-AutomaticallyAddReplicasinSolrCloud,autoAddReplicas Settings>> for more details on settings and overrides.
-|async |string |No | |Request ID to track this action which will be <<CollectionsAPI-async,processed asynchronously>>.
-|rule |string |No | |Replica placement rules. See the section <<rule-based-replica-placement.adoc#rule-based-replica-placement,Rule-based Replica Placement>> for details.
-|snitch |string |No | |Details of the snitch provider. See the section <<rule-based-replica-placement.adoc#rule-based-replica-placement,Rule-based Replica Placement>> for details.
-|===
-
-[[CollectionsAPI-Output]]
-=== Output
+`createNodeSet`::
+Allows defining the nodes to spread the new collection across. The format is a comma-separated list of node_names, such as `localhost:8983_solr,localhost:8984_solr,localhost:8985_solr`.
++
+If not provided, the CREATE operation will create shard-replicas spread across all live Solr nodes.
++
+Alternatively, use the special value of `EMPTY` to initially create no shard-replica within the new collection and then later use the <<CollectionsAPI-addreplica,ADDREPLICA>> operation to add shard-replicas when and where required.
+
+`createNodeSet.shuffle`::
+Controls wether or not the shard-replicas created for this collection will be assigned to the nodes specified by the `createNodeSet` in a sequential manner, or if the list of nodes should be shuffled prior to creating individual replicas.
++
+A `false` value makes the results of a collection creation predictable and gives more exact control over the location of the individual shard-replicas, but `true` can be a better choice for ensuring replicas are distributed evenly across nodes. The default is `true`.
++
+This parameter is ignored if `createNodeSet` is not also specified.
+
+`collection.configName`::
+Defines the name of the configurations (which *must already be stored in ZooKeeper*) to use for this collection. If not provided, Solr will default to the collection name as the configuration name.
+
+`router.field`::
+If this parameter is specified, the router will look at the value of the field in an input document to compute the hash and identify a shard instead of looking at the `uniqueKey` field. If the field specified is null in the document, the document will be rejected.
++
+Please note that <<realtime-get.adoc#realtime-get,RealTime Get>> or retrieval by document ID would also require the parameter `\_route_` (or `shard.keys`) to avoid a distributed search.
+
+`property._name_=_value_`::
+Set core property _name_ to _value_. See the section <<defining-core-properties.adoc#defining-core-properties,Defining core.properties>> for details on supported properties and values.
+
+`autoAddReplicas`::
+When set to `true`, enables automatic addition of replicas on shared file systems (such as HDFS) only. See the section <<running-solr-on-hdfs.adoc#RunningSolronHDFS-AutomaticallyAddReplicasinSolrCloud,autoAddReplicas Settings>> for more details on settings and overrides. The default is `false`.
+
+`async`::
+Request ID to track this action which will be <<CollectionsAPI-async,processed asynchronously>>.
+
+`rule`::
+Replica placement rules. See the section <<rule-based-replica-placement.adoc#rule-based-replica-placement,Rule-based Replica Placement>> for details.
+
+`snitch`::
+Details of the snitch provider. See the section <<rule-based-replica-placement.adoc#rule-based-replica-placement,Rule-based Replica Placement>> for details.
+
+=== CREATE Response
The response will include the status of the request and the new core names. If the status is anything other than "success", an error message will explain why the request failed.
-[[CollectionsAPI-Examples]]
-=== Examples
+=== Examples using CREATE
*Input*
@@ -112,19 +146,16 @@ http://localhost:8983/solr/admin/collections?action=CREATE&name=newCollection&nu
`/admin/collections?action=MODIFYCOLLECTION&collection=_<collection-name>&<attribute-name>=<attribute-value>&<another-attribute-name>=<another-value>_`
-It's possible to edit multiple attributes at a time. Changing these values only updates the z-node on ZooKeeper, they do not change the topology of the collection. For instance, increasing replicationFactor will _not_ automatically add more replicas to the collection but _will_ allow more ADDREPLICA commands to succeed.
-
-*Query Parameters*
+It's possible to edit multiple attributes at a time. Changing these values only updates the z-node on ZooKeeper, they do not change the topology of the collection. For instance, increasing `replicationFactor` will _not_ automatically add more replicas to the collection but _will_ allow more ADDREPLICA commands to succeed.
-// TODO: Change column width to %autowidth.spread when https://github.com/asciidoctor/asciidoctor-pdf/issues/599 is fixed
+=== MODIFYCOLLECTION Parameters
-[cols="20,15,10,55",options="header"]
-|===
-|Key |Type |Required |Description
-|collection |string |Yes |The name of the collection to be modified.
-|<attribute-name> |string |Yes a|
-Key-value pairs of attribute names and attribute values.
+`collection`::
+The name of the collection to be modified. This parameter is required.
+`_attribute_=_value_`::
+Key-value pairs of attribute names and attribute values. At least one of these is required.
++
The attributes that can be modified are:
* maxShardsPerNode
@@ -133,10 +164,9 @@ The attributes that can be modified are:
* collection.configName
* rule
* snitch
++
+See the <<CollectionsAPI-create,CREATE action>> section above for details on these attributes.
-See the <<CollectionsAPI-create,CREATE>> section above for details on these attributes.
-
-|===
[[CollectionsAPI-reload]]
== RELOAD: Reload a Collection
@@ -145,28 +175,19 @@ See the <<CollectionsAPI-create,CREATE>> section above for details on these attr
The RELOAD action is used when you have changed a configuration in ZooKeeper.
-[[CollectionsAPI-Input.1]]
-=== Input
+=== RELOAD Parameters
-*Query Parameters*
+|`name`::
+The name of the collection to reload. This parameter is required.
+`async`::
+Request ID to track this action which will be <<CollectionsAPI-async,processed asynchronously>>.
-// TODO: Change column width to %autowidth.spread when https://github.com/asciidoctor/asciidoctor-pdf/issues/599 is fixed
-
-[cols="20,15,10,55",options="header"]
-|===
-|Key |Type |Required |Description
-|name |string |Yes |The name of the collection to reload.
-|async |string |No |Request ID to track this action which will be <<CollectionsAPI-async,processed asynchronously>>.
-|===
-
-[[CollectionsAPI-Output.1]]
-=== Output
+=== RELOAD Response
The response will include the status of the request and the cores that were reloaded. If the status is anything other than "success", an error message will explain why the request failed.
-[[CollectionsAPI-Examples.1]]
-=== Examples
+=== Examples using RELOAD
*Input*
@@ -208,41 +229,43 @@ http://localhost:8983/solr/admin/collections?action=RELOAD&name=newCollection
Splitting a shard will take an existing shard and break it into two pieces which are written to disk as two (new) shards. The original shard will continue to contain the same data as-is but it will start re-routing requests to the new shards. The new shards will have as many replicas as the original shard. A soft commit is automatically issued after splitting a shard so that documents are made visible on sub-shards. An explicit commit (hard or soft) is not necessary after a split operation because the index is automatically persisted to disk during the split operation.
-This command allows for seamless splitting and requires no downtime. A shard being split will continue to accept query and indexing requests and will automatically start routing them to the new shards once this operation is complete. This command can only be used for SolrCloud collections created with `numShards` parameter, meaning collections which rely on Solr's hash-based routing mechanism.
+This command allows for seamless splitting and requires no downtime. A shard being split will continue to accept query and indexing requests and will automatically start routing requests to the new shards once this operation is complete. This command can only be used for SolrCloud collections created with `numShards` parameter, meaning collections which rely on Solr's hash-based routing mechanism.
-The split is performed by dividing the original shard's hash range into two equal partitions and dividing up the documents in the original shard according to the new sub-ranges.
+The split is performed by dividing the original shard's hash range into two equal partitions and dividing up the documents in the original shard according to the new sub-ranges. Two parameters discussed below, `ranges` and `split.key` provide further control over how the split occurs.
-One can also specify an optional `ranges` parameter to divide the original shard's hash range into arbitrary hash range intervals specified in hexadecimal. For example, if the original hash range is 0-1500 then adding the parameter: ranges=0-1f4,1f5-3e8,3e9-5dc will divide the original shard into three shards with hash range 0-500, 501-1000 and 1001-1500 respectively.
+Shard splitting can be a long running process. In order to avoid timeouts, you should run this as an <<CollectionsAPI-async,asynchronous call>>.
-Another optional parameter `split.key` can be used to split a shard using a route key such that all documents of the specified route key end up in a single dedicated sub-shard. Providing the 'shard' parameter is not required in this case because the route key is enough to figure out the right shard. A route key which spans more than one shard is not supported. For example, suppose `split.key=A!` hashes to the range 12-15 and belongs to shard 'shard1' with range 0-20 then splitting by this route key would yield three sub-shards with ranges 0-11, 12-15 and 16-20. Note that the sub-shard with the hash range of the route key may also contain documents for other route keys whose hash ranges overlap.
+=== SPLITSHARD Parameters
-Shard splitting can be a long running process. In order to avoid timeouts, you should run this as an <<CollectionsAPI-async,asynchronous call>>.
+`collection`::
+The name of the collection that includes the shard to be split. This parameter is required.
-[[CollectionsAPI-Input.2]]
-=== Input
+`shard`::
+The name of the shard to be split. This parameter is required when `split.key` is not specified.
-*Query Parameters*
+`ranges`::
+A comma-separated list of hash ranges in hexadecimal, such as `ranges=0-1f4,1f5-3e8,3e9-5dc`.
++
+This parameter can be used to divide the original shard's hash range into arbitrary hash range intervals specified in hexadecimal. For example, if the original hash range is `0-1500` then adding the parameter: `ranges=0-1f4,1f5-3e8,3e9-5dc` will divide the original shard into three shards with hash range `0-500`, `501-1000`, and `1001-1500` respectively.
-// TODO: Change column width to %autowidth.spread when https://github.com/asciidoctor/asciidoctor-pdf/issues/599 is fixed
+`split.key`::
+The key to use for splitting the index.
++
+This parameter can be used to split a shard using a route key such that all documents of the specified route key end up in a single dedicated sub-shard. Providing the `shard` parameter is not required in this case because the route key is enough to figure out the right shard. A route key which spans more than one shard is not supported.
++
+For example, suppose `split.key=A!` hashes to the range `12-15` and belongs to shard 'shard1' with range `0-20`. Splitting by this route key would yield three sub-shards with ranges `0-11`, `12-15` and `16-20`. Note that the sub-shard with the hash range of the route key may also contain documents for other route keys whose hash ranges overlap.
-[cols="25,15,10,50",options="header"]
-|===
-|Key |Type |Required |Description
-|collection |string |Yes |The name of the collection that includes the shard to be split.
-|shard |string |Yes |The name of the shard to be split.
-|ranges |string |No |A comma-separated list of hash ranges in hexadecimal, such as `ranges=0-1f4,1f5-3e8,3e9-5dc`.
-|split.key |string |No |The key to use for splitting the index.
-|property._name_=_value_ |string |No |Set core property _name_ to _value_. See the section <<defining-core-properties.adoc#defining-core-properties,Defining core.properties>> for details on supported properties and values.
-|async |string |No |Request ID to track this action which will be <<CollectionsAPI-async,processed asynchronously>>
-|===
+`property._name_=_value_`::
+Set core property _name_ to _value_. See the section <<defining-core-properties.adoc#defining-core-properties,Defining core.properties>> for details on supported properties and values.
-[[CollectionsAPI-Output.2]]
-=== Output
+`async`::
+Request ID to track this action which will be <<CollectionsAPI-async,processed asynchronously>>
+
+=== SPLITSHARD Response
The output will include the status of the request and the new shard names, which will use the original shard as their basis, adding an underscore and a number. For example, "shard1" will become "shard1_0" and "shard1_1". If the status is anything other than "success", an error message will explain why the request failed.
-[[CollectionsAPI-Examples.2]]
-=== Examples
+=== Examples using SPLITSHARD
*Input*
@@ -318,34 +341,36 @@ http://localhost:8983/solr/admin/collections?action=SPLITSHARD&collection=anothe
[[CollectionsAPI-createshard]]
== CREATESHARD: Create a Shard
-Shards can only created with this API for collections that use the 'implicit' router. Use SPLITSHARD for collections using the 'compositeId' router. A new shard with a name can be created for an existing 'implicit' collection.
+Shards can only created with this API for collections that use the 'implicit' router (i.e., when the collection was created, `router.name=implicit`). A new shard with a name can be created for an existing 'implicit' collection.
+
+Use SPLITSHARD for collections created with the 'compositeId' router (`router.key=compositeId`).
`/admin/collections?action=CREATESHARD&shard=_shardName_&collection=_name_`
-[[CollectionsAPI-Input.3]]
-=== Input
+=== CREATESHARD Parameters
+
+`collection`::
+The name of the collection that includes the shard to be split. This parameter is required.
+
+`shard`::
+The name of the shard to be created. This parameter is required.
-*Query Parameters*
+`createNodeSet`::
+Allows defining the nodes to spread the new collection across. If not provided, the CREATESHARD operation will create shard-replica spread across all live Solr nodes.
++
+The format is a comma-separated list of node_names, such as `localhost:8983_solr,localhost:8984_solr,localhost:8985_solr`.
-// TODO: Change column width to %autowidth.spread when https://github.com/asciidoctor/asciidoctor-pdf/issues/599 is fixed
+`property._name_=_value_`::
+Set core property _name_ to _value_. See the section <<defining-core-properties.adoc#defining-core-properties,Defining core.properties>> for details on supported properties and values.
-[cols="25,15,10,50",options="header"]
-|===
-|Key |Type |Required |Description
-|collection |string |Yes |The name of the collection that includes the shard that will be splitted.
-|shard |string |Yes |The name of the shard to be created.
-|createNodeSet |string |No |Allows defining the nodes to spread the new collection across. If not provided, the CREATE operation will create shard-replica spread across all live Solr nodes. The format is a comma-separated list of node_names, such as `localhost:8983_solr,` `localhost:8984_solr,` `localhost:8985_solr`.
-|property._name_=_value_ |string |No |Set core property _name_ to _value_. See the section <<defining-core-properties.adoc#defining-core-properties,Defining core.properties>> for details on supported properties and values.
-|async |string |No |Request ID to track this action which will be <<CollectionsAPI-async,processed asynchronously>>.
-|===
+`async`::
+Request ID to track this action which will be <<CollectionsAPI-async,processed asynchronously>>.
-[[CollectionsAPI-Output.3]]
-=== Output
+=== CREATESHARD Response
The output will include the status of the request. If the status is anything other than "success", an error message will explain why the request failed.
-[[CollectionsAPI-Examples.3]]
-=== Examples
+=== Examples using CREATESHARD
*Input*
@@ -375,29 +400,31 @@ Deleting a shard will unload all replicas of the shard, remove them from `cluste
`/admin/collections?action=DELETESHARD&shard=_shardID_&collection=_name_`
-[[CollectionsAPI-Input.4]]
-=== Input
+=== DELETESHARD Parameters
-*Query Parameters*
+`collection`::
+The name of the collection that includes the shard to be deleted. This parameter is required.
-[cols="25,15,10,50",options="header",]
-|===
-|Key |Type |Required |Description
-|collection |string |Yes |The name of the collection that includes the shard to be deleted.
-|shard |string |Yes |The name of the shard to be deleted.
-|deleteInstanceDir |boolean |No |By default Solr will delete the entire instanceDir of each replica that is deleted. Set this to `false` to prevent the instance directory from being deleted.
-|deleteDataDir |boolean |No |By default Solr will delete the dataDir of each replica that is deleted. Set this to `false` to prevent the data directory from being deleted.
-|deleteIndex |boolean |No |By default Solr will delete the index of each replica that is deleted. Set this to `false` to prevent the index directory from being deleted.
-|async |string |No |Request ID to track this action which will be <<CollectionsAPI-async,processed asynchronously>>.
-|===
+`shard`::
+The name of the shard to be deleted. This parameter is required.
-[[CollectionsAPI-Output.4]]
-=== Output
+`deleteInstanceDir`::
+By default Solr will delete the entire instanceDir of each replica that is deleted. Set this to `false` to prevent the instance directory from being deleted.
+
+`deleteDataDir`::
+By default Solr will delete the dataDir of each replica that is deleted. Set this to `false` to prevent the data directory from being deleted.
+
+`deleteIndex`::
+By default Solr will delete the index of each replica that is deleted. Set this to `false` to prevent the index directory from being deleted.
+
+`async`::
+Request ID to track this action which will be <<CollectionsAPI-async,processed asynchronously>>.
+
+=== DELETESHARD Response
The output will include the status of the request. If the status is anything other than "success", an error message will explain why the request failed.
-[[CollectionsAPI-Examples.4]]
-=== Examples
+=== Examples using DELETESHARD
*Input*
@@ -435,28 +462,24 @@ The `CREATEALIAS` action will create a new alias pointing to one or more collect
`/admin/collections?action=CREATEALIAS&name=_name_&collections=_collectionlist_`
-[[CollectionsAPI-Input.5]]
-=== Input
+=== CREATEALIAS Parameters
-*Query Parameters*
+`name`::
+The alias name to be created. This parameter is required.
-// TODO: Change column width to %autowidth.spread when https://github.com/asciidoctor/asciidoctor-pdf/issues/599 is fixed
+`collections`::
+A comma-separated list of collections to be aliased. The collections must already exist in the cluster. This parameter is required.
-[cols="20,15,10,55",options="header"]
-|===
-|Key |Type |Required |Description
-|name |string |Yes |The alias name to be created.
-|collections |string |Yes |The list of collections to be aliased, separated by commas. They must already exist in the cluster.
-|async |string |No |Request ID to track this action which will be <<CollectionsAPI-async,processed asynchronously>>.
-|===
+`async`::
+Request ID to track this action which will be <<CollectionsAPI-async,processed asynchronously>>.
[[CollectionsAPI-Output.5]]
-=== Output
+=== CREATEALIAS Response
The output will simply be a responseHeader with details of the time it took to process the request. To confirm the creation of the alias, you can look in the Solr Admin UI, under the Cloud section and find the `aliases.json` file.
[[CollectionsAPI-Examples.5]]
-=== Examples
+=== Examples using CREATEALIAS
*Input*
@@ -479,41 +502,53 @@ http://localhost:8983/solr/admin/collections?action=CREATEALIAS&name=testalias&c
</response>
----
-== LISTALIASES: List Collection Aliases
-
-Lists all aliases for each collection.
+[[CollectionsAPI-listaliases]]
+== LISTALIASES: List of all aliases in the cluster
`/admin/collections?action=LISTALIASES`
-// TODO 6.6 examples
+The LISTALIASES action does not take any parameters.
+=== LISTALIASES Response
+
+The output will contain a list of aliases with the corresponding collection names.
+
+=== Examples using LISTALIASES
+
+*Output*
+
+[source,xml]
+----
+<response>
+ <lst name="responseHeader">
+ <int name="status">0</int>
+ <int name="QTime">0</int>
+ </lst>
+ <lst name="aliases">
+ <str name="testalias1">collection1</str>
+ <str name="testalias2">collection2</str>
+ </lst>
+</response>
+----
[[CollectionsAPI-deletealias]]
== DELETEALIAS: Delete a Collection Alias
`/admin/collections?action=DELETEALIAS&name=_name_`
-[[CollectionsAPI-Input.6]]
-=== Input
+=== DELETEALIAS Parameters
-*Query Parameters*
+`name`::
+The name of the alias to delete. This parameter is required.
-// TODO: Change column width to %autowidth.spread when https://github.com/asciidoctor/asciidoctor-pdf/issues/599 is fixed
+`async`::
+Request ID to track this action which will be <<CollectionsAPI-async,processed asynchronously>>.
-[cols="20,15,10,55",options="header"]
-|===
-|Key |Type |Required |Description
-|name |string |Yes |The name of the alias to delete.
-|async |string |No |Request ID to track this action which will be <<CollectionsAPI-async,processed asynchronously>>.
-|===
-
-[[CollectionsAPI-Output.6]]
-=== Output
+=== DELETEALIAS Response
The output will simply be a responseHeader with details of the time it took to process the request. To confirm the removal of the alias, you can look in the Solr Admin UI, under the Cloud section, and find the `aliases.json` file.
-[[CollectionsAPI-Examples.6]]
-=== Examples
+=== Examples using DELETEALIAS
*Input*
@@ -536,62 +571,24 @@ http://localhost:8983/solr/admin/collections?action=DELETEALIAS&name=testalias
</response>
----
-[[CollectionsAPI-listaliases]]
-== LISTALIASES: List of all aliases in the cluster
-
-`/admin/collections?action=LISTALIASES`
-
-[[CollectionsAPI-Output.27]]
-=== Output
-
-The output will contain a list of aliases with the corresponding collection names.
-
-[[CollectionsAPI-Examples.27]]
-=== Examples
-
-*Output*
-
-[source,xml]
-----
-<response>
- <lst name="responseHeader">
- <int name="status">0</int>
- <int name="QTime">0</int>
- </lst>
- <lst name="aliases">
- <str name="testalias1">collection1</str>
- <str name="testalias2">collection2</str>
- </lst>
-</response>
-----
-
-
[[CollectionsAPI-delete]]
== DELETE: Delete a Collection
`/admin/collections?action=DELETE&name=_collection_`
-[[CollectionsAPI-Input.7]]
-=== Input
-
-*Query Parameters*
+=== DELETE Parameters
-// TODO: Change column width to %autowidth.spread when https://github.com/asciidoctor/asciidoctor-pdf/issues/599 is fixed
+`name`::
+The name of the collection to delete. This parameter is required.
-[cols="20,15,10,55",options="header"]
-|===
-|Key |Type |Required |Description
-|name |string |Yes |The name of the collection to delete.
-|async |string |No |Request ID to track this action which will be <<CollectionsAPI-async,processed asynchronously>>.
-|===
+`async`::
+Request ID to track this action which will be <<CollectionsAPI-async,processed asynchronously>>.
-[[CollectionsAPI-Output.7]]
-=== Output
+=== DELETE Response
The response will include the status of the request and the cores that were deleted. If the status is anything other than "success", an error message will explain why the request failed.
-[[CollectionsAPI-Examples.7]]
-=== Examples
+=== Examples using DELETE
*Input*
@@ -631,33 +628,46 @@ http://localhost:8983/solr/admin/collections?action=DELETE&name=newCollection
[[CollectionsAPI-deletereplica]]
== DELETEREPLICA: Delete a Replica
-Delete a named replica from the specified collection and shard. If the corresponding core is up and running the core is unloaded, the entry is removed from the clusterstate, and (by default) delete the instanceDir and dataDir. If the node/core is down, the entry is taken off the clusterstate and if the core comes up later it is automatically unregistered.
+Deletes a named replica from the specified collection and shard.
+
+If the corresponding core is up and running the core is unloaded, the entry is removed from the clusterstate, and (by default) delete the instanceDir and dataDir. If the node/core is down, the entry is taken off the clusterstate and if the core comes up later it is automatically unregistered.
`/admin/collections?action=DELETEREPLICA&collection=_collection_&shard=_shard_&replica=_replica_`
-[[CollectionsAPI-Input.8]]
-=== Input
+=== DELETEREPLICA Parameters
+
+`collection`::
+The name of the collection. This parameter is required.
+
+`shard`::
+The name of the shard that includes the replica to be removed. This parameter is required.
+
+`replica`::
+The name of the replica to remove.
++
+If `count` is used instead, this parameter is not required. Otherwise, this parameter must be supplied.
+
+`count`::
+The number of replicas to remove. If the requested number exceeds the number of replicas, no replicas will be deleted. If there is only one replica, it will not be removed.
++
+If `replica` is used instead, this parameter is not required. Otherwise, this parameter must be supplied.
+
+`deleteInstanceDir`::
+By default Solr will delete the entire instanceDir of the replica that is deleted. Set this to `false` to prevent the instance directory from being deleted.
-*Query Parameters*
+`deleteDataDir`::
+By default Solr will delete the dataDir of the replica that is deleted. Set this to `false` to prevent the data directory from being deleted.
-// TODO: Change column width to %autowidth.spread when https://github.com/asciidoctor/asciidoctor-pdf/issues/599 is fixed
+`deleteIndex`::
+By default Solr will delete the index of the replica that is deleted. Set this to `false` to prevent the index directory from being deleted.
-[cols="20,15,10,55",options="header"]
-|===
-|Key |Type |Required |Description
-|collection |string |Yes |The name of the collection.
-|shard |string |Yes |The name of the shard that includes the replica to be removed.
-|replica |string |No |The name of the replica to remove. Not required if `count` is used instead.
-|count |integer |No |The number of replicas to remove. If the requested number exceeds the number of replicas, no replicas will be deleted. If there is only one replica, it will not be removed. This parameter is not required if `replica` is used instead.
-|deleteInstanceDir |boolean |No |By default Solr will delete the entire instanceDir of the replica that is deleted. Set this to `false` to prevent the instance directory from being deleted.
-|deleteDataDir |boolean |No |By default Solr will delete the dataDir of the replica that is deleted. Set this to `false` to prevent the data directory from being deleted.
-|deleteIndex |boolean |No |By default Solr will delete the index of the replica that is deleted. Set this to `false` to prevent the index directory from being deleted.
-|onlyIfDown |boolean |No |When set to 'true' will not take any action if the replica is active. Default 'false'
-|async |string |No |Request ID to track this action which will be <<CollectionsAPI-async,processed asynchronously>>.
-|===
+`onlyIfDown`::
+When set to `true`, no action will be taken if the replica is active. Default `false`.
-[[CollectionsAPI-Examples.8]]
-=== Examples
+`async`::
+Request ID to track this action which will be <<CollectionsAPI-async,processed asynchronously>>.
+
+=== Examples using DELETEREPLICA
*Input*
@@ -685,36 +695,36 @@ Add a replica to a shard in a collection. The node name can be specified if the
`/admin/collections?action=ADDREPLICA&collection=_collection_&shard=_shard_&node=_nodeName_`
-[[CollectionsAPI-Input.9]]
-=== Input
-
-*Query Parameters*
+=== ADDREPLICA Parameters
-// TODO: Change column width to %autowidth.spread when https://github.com/asciidoctor/asciidoctor-pdf/issues/599 is fixed
+`collection`::
+The name of the collection where the replica should be created. This parameter is required.
-[cols="25,15,10,50",options="header"]
-|===
-|Key |Type |Required |Description
-|collection |string |Yes |The name of the collection.
-|shard |string |Yes* a|
+`shard`::
The name of the shard to which replica is to be added.
++
+If `shard` is not specified, then `\_route_` must be.
+
+`\_route_`::
+If the exact shard name is not known, users may pass the `\_route_` value and the system would identify the name of the shard.
++
+Ignored if the `shard` param is also specified.
+
+`node`::
+The name of the node where the replica should be created.
-If shard is not specified, then _route_ must be.
+`instanceDir`::
+The instanceDir for the core that will be created
-|_route_ |string |No* a|
-If the exact shard name is not known, users may pass the _route_ value and the system would identify the name of the shard.
+`dataDir`::
+The directory in which the core should be created
-Ignored if the shard param is also specified.
+`property._name_=_value_`::
+Set core property _name_ to _value_. See <<defining-core-properties.adoc#defining-core-properties,Defining core.properties>> for details about supported properties and values.
-|node |string |No |The name of the node where the replica should be created
-|instanceDir |string |No |The instanceDir for the core that will be created
-|dataDir |string |No |The directory in which the core should be created
-|property._name_=_value_ |string |No |Set core property _name_ to _value_. See <<defining-core-properties.adoc#defining-core-properties,Defining core.properties>>.
-|async |string |No |Request ID to track this action which will be <<CollectionsAPI-async,processed asynchronously>>
-|===
+`async`:: string |No |Request ID to track this action which will be <<CollectionsAPI-async,processed asynchronously>>
-[[CollectionsAPI-Examples.9]]
-=== Examples
+=== Examples using ADDREPLICA
*Input*
@@ -751,27 +761,19 @@ Add, edit or delete a cluster-wide property.
`/admin/collections?action=CLUSTERPROP&name=_propertyName_&val=_propertyValue_`
-[[CollectionsAPI-Input.10]]
-=== Input
+=== CLUSTERPROP Parameters
-*Query Parameters*
+`name`::
+The name of the property. Supported properties names are `urlScheme` and `autoAddReplicas and location`. Other names are rejected with an error.
-// TODO: Change column width to %autowidth.spread when https://github.com/asciidoctor/asciidoctor-pdf/issues/599 is fixed
+`val`::
+The value of the property. If the value is empty or null, the property is unset.
-[cols="20,15,10,55",options="header"]
-|===
-|Key |Type |Required |Description
-|name |string |Yes |The name of the property. The supported properties names are `urlScheme` and `autoAddReplicas and location`. Other names are rejected with an error.
-|val |string |Yes |The value of the property. If the value is empty or null, the property is unset.
-|===
-
-[[CollectionsAPI-Output.8]]
-=== Output
+=== CLUSTERPROP Response
The response will include the status of the request and the properties that were updated or removed. If the status is anything other than "0", an error message will explain why the request failed.
-[[CollectionsAPI-Examples.10]]
-=== Examples
+=== Examples using CLUSTERPROP
*Input*
@@ -797,41 +799,41 @@ http://localhost:8983/solr/admin/collections?action=CLUSTERPROP&name=urlScheme&v
`/admin/collections?action=MIGRATE&collection=_name_&split.key=_key1!_&target.collection=_target_collection_&forward.timeout=60`
-The MIGRATE command is used to migrate all documents having the given routing key to another collection. The source collection will continue to have the same data as-is but it will start re-routing write requests to the target collection for the number of seconds specified by the forward.timeout parameter. It is the responsibility of the user to switch to the target collection for reads and writes after the ‘migrate’ command completes.
+The MIGRATE command is used to migrate all documents having a given routing key to another collection. The source collection will continue to have the same data as-is but it will start re-routing write requests to the target collection for the number of seconds specified by the `forward.timeout` parameter. It is the responsibility of the user to switch to the target collection for reads and writes after the MIGRATE action completes.
The routing key specified by the `split.key` parameter may span multiple shards on both the source and the target collections. The migration is performed shard-by-shard in a single thread. One or more temporary collections may be created by this command during the ‘migrate’ process but they are cleaned up at the end automatically.
-This is a long running operation and therefore using the `async` parameter is highly recommended. If the async parameter is not specified then the operation is synchronous by default and keeping a large read timeout on the invocation is advised. Even with a large read timeout, the request may still timeout due to inherent limitations of the Collection APIs but that doesn’t necessarily mean that the operation has failed. Users should check logs, cluster state, source and target collections before invoking the operation again.
+This is a long running operation and therefore using the `async` parameter is highly recommended. If the `async` parameter is not specified then the operation is synchronous by default and keeping a large read timeout on the invocation is advised. Even with a large read timeout, the request may still timeout but that doesn’t necessarily mean that the operation has failed. Users should check logs, cluster state, source and target collections before invoking the operation again.
+
+This command works only with collections using the compositeId router. The target collection must not receive any writes during the time the MIGRATE command is running otherwise some writes may be lost.
+
+Please note that the MIGRATE API does not perform any de-duplication on the documents so if the target collection contains documents with the same uniqueKey as the documents being migrated then the target collection will end up with duplicate documents.
-This command works only with collections having the compositeId router. The target collection must not receive any writes during the time the migrate command is running otherwise some writes may be lost.
+=== MIGRATE Parameters
-Please note that the migrate API does not perform any de-duplication on the documents so if the target collection contains documents with the same uniqueKey as the documents being migrated then the target collection will end up with duplicate documents.
+`collection`::
+The name of the source collection from which documents will be split. This parameter is required.
-[[CollectionsAPI-Input.11]]
-=== Input
+`target.collection`::
+The name of the target collection to which documents will be migrated. This parameter is required.
-*Query Parameters*
+`split.key`::
+The routing key prefix. For example, if the uniqueKey of a document is "a!123", then you would use `split.key=a!`. This parameter is required.
-// TODO: Change column width to %autowidth.spread when https://github.com/asciidoctor/asciidoctor-pdf/issues/599 is fixed
+`forward.timeout`::
+The timeout, in seconds, until which write requests made to the source collection for the given `split.key` will be forwarded to the target shard. The default is 60 seconds.
-[cols="25,15,10,50",options="header"]
-|===
-|Key |Type |Required |Description
-|collection |string |Yes |The name of the source collection from which documents will be split.
-|target.collection |string |Yes |The name of the target collection to which documents will be migrated.
-|split.key |string |Yes |The routing key prefix. For example, if uniqueKey is a!123, then you would use `split.key=a!`.
-|forward.timeout |int |No |The timeout, in seconds, until which write requests made to the source collection for the given `split.key` will be forwarded to the target shard. The default is 60 seconds.
-|property._name_=_value_ |string |No |Set core property _name_ to _value_. See the section <<defining-core-properties.adoc#defining-core-properties,Defining core.properties>> for details on supported properties and values.
-|async |string |No |Request ID to track this action which will be <<CollectionsAPI-async,processed asynchronously>>.
-|===
+`property._name_=_value_`::
+Set core property _name_ to _value_. See the section <<defining-core-properties.adoc#defining-core-properties,Defining core.properties>> for details on supported properties and values.
-[[CollectionsAPI-Output.9]]
-=== Output
+`async`::
+Request ID to track this action which will be <<CollectionsAPI-async,processed asynchronously>>.
+
+=== MIGRATE Response
The response will include the status of the request.
-[[CollectionsAPI-Examples.11]]
-=== Examples
+=== Examples using MIGRATE
*Input*
@@ -991,29 +993,23 @@ http://localhost:8983/solr/admin/collections?action=MIGRATE&collection=test1&spl
`/admin/collections?action=ADDROLE&role=_roleName_&node=_nodeName_`
-Assign a role to a given node in the cluster. The only supported role as of 4.7 is 'overseer'. Use this API to dedicate a particular node as Overseer. Invoke it multiple times to add more nodes. This is useful in large clusters where an Overseer is likely to get overloaded. If available, one among the list of nodes which are assigned the 'overseer' role would become the overseer. The system would assign the role to any other node if none of the designated nodes are up and running.
+Assigns a role to a given node in the cluster. The only supported role is `overseer`.
-[[CollectionsAPI-Input.12]]
-=== Input
+Use this command to dedicate a particular node as Overseer. Invoke it multiple times to add more nodes. This is useful in large clusters where an Overseer is likely to get overloaded. If available, one among the list of nodes which are assigned the 'overseer' role would become the overseer. The system would assign the role to any other node if none of the designated nodes are up and running.
-*Query Parameters*
+=== ADDROLE Parameters
-// TODO: Change column width to %autowidth.spread when https://github.com/asciidoctor/asciidoctor-pdf/issues/599 is fixed
+`role`::
+The name of the role. The only supported role as of now is `overseer`. This parameter is required.
-[cols="20,15,10,55",options="header"]
-|===
-|Key |Type |Required |Description
-|role |string |Yes |The name of the role. The only supported role as of now is _overseer_.
-|node |string |Yes |The name of the node. It is possible to assign a role even before that node is started.
-|===
+`node`::
+|The name of the node that will be assigned the role. It is possible to assign a role even before that node is started. This parameter is started.
-[[CollectionsAPI-Output.10]]
-=== Output
+=== ADDROLE Response
The response will include the status of the request and the properties that were updated or removed. If the status is anything other than "0", an error message will explain why the request failed.
-[[CollectionsAPI-Examples.12]]
-=== Examples
+=== Examples using ADDROLE
*Input*
@@ -1041,27 +1037,21 @@ Remove an assigned role. This API is used to undo the roles assigned using ADDRO
`/admin/collections?action=REMOVEROLE&role=_roleName_&node=_nodeName_`
-[[CollectionsAPI-Input.13]]
-=== Input
+=== REMOVEROLE Parameters
-*Query Parameters*
+`role`::
+The name of the role. The only supported role as of now is `overseer`. This parameter is required.
-// TODO: Change column width to %autowidth.spread when https://github.com/asciidoctor/asciidoctor-pdf/issues/599 is fixed
+`node`::
+The name of the node where the role should be removed.
-[cols="20,15,10,55",options="header"]
-|===
-|Key |Type |Required |Description
-|role |string |Yes |The name of the role. The only supported role as of now is _overseer_.
-|node |string |Yes |The name of the node.
-|===
[[CollectionsAPI-Output.11]]
-=== Output
+=== REMOVEROLE Response
The response will include the status of the request and the properties that were updated or removed. If the status is anything other than "0", an error message will explain why the request failed.
-[[CollectionsAPI-Examples.13]]
-=== Examples
+=== Examples using REMOVEROLE
*Input*
@@ -1089,8 +1079,7 @@ Returns the current status of the overseer, performance statistics of various ov
`/admin/collections?action=OVERSEERSTATUS`
-[[CollectionsAPI-Examples.14]]
-=== Examples
+=== Examples using OVERSEERSTATUS
*Input:*
@@ -1164,28 +1153,23 @@ Fetch the cluster status including collections, shards, replicas, configuration
`/admin/collections?action=CLUSTERSTATUS`
-[[CollectionsAPI-Input.14]]
-=== Input
+=== CLUSTERSTATUS Parameters
-*Query Parameters*
+`collection`::
+The collection name for which information is requested. If omitted, information on all collections in the cluster will be returned.
-// TODO: Change column width to %autowidth.spread when https://github.com/asciidoctor/asciidoctor-pdf/issues/599 is fixed
+`shard`::
+The shard(s) for which information is requested. Multiple shard names can be specified as a comma-separated list.
-[cols="20,15,10,55",options="header"]
-|===
-|Key |Type |Required |Description
-|collection |string |No |The collection name for which information is requested. If omitted, information on all collections in the cluster will be returned.
-|shard |string |No |The shard(s) for which information is requested. Multiple shard names can be specified as a comma separated list.
-|_route_ |string |No |This can be used if you need the details of the shard where a particular document belongs to and you don't know which shard it falls under.
-|===
+`\_route_`::
+This can be used if you need the details of the shard where a particular document belongs to and you don't know which shard it falls under.
-[[CollectionsAPI-Output.12]]
-=== Output
+=== CLUSTERSTATUS Response
The response will include the status of the request and the status of the cluster.
[[CollectionsAPI-Examples.15]]
-=== Examples
+=== Examples using CLUSTERSTATUS
*Input*
@@ -1270,23 +1254,14 @@ Request the status and response of an already submitted <<CollectionsAPI-async,A
`/admin/collections?action=REQUESTSTATUS&requestid=_request-id_`
-[[CollectionsAPI-Input.15]]
-=== Input
-
-*Query Parameters*
+=== REQUESTSTATUS Parameters
-// TODO: Change column width to %autowidth.spread when https://github.com/asciidoctor/asciidoctor-pdf/issues/599 is fixed
+`requestid`::
+The user defined request ID for the request. This can be used to track the status of the submitted asynchronous task. This parameter is required.
-[cols="20,15,10,55",options="header"]
-|===
-|Key |Type |Required |Description
-|requestid |string |Yes |The user defined request-id for the request. This can be used to track the status of the submitted asynchronous task.
-|===
+=== Examples using REQUESTSTATUS
-[[CollectionsAPI-Examples.16]]
-=== Examples
-
-*Input: Valid Request Status*
+*Input: Valid Request ID*
[source,text]
----
@@ -1309,7 +1284,7 @@ http://localhost:8983/solr/admin/collections?action=REQUESTSTATUS&requestid=1000
</response>
----
-*Input: Invalid RequestId*
+*Input: Invalid Request ID*
[source,text]
----
@@ -1335,28 +1310,21 @@ http://localhost:8983/solr/admin/collections?action=REQUESTSTATUS&requestid=1004
[[CollectionsAPI-deletestatus]]
== DELETESTATUS: Delete Status
-Delete the stored response of an already failed or completed <<CollectionsAPI-async,Asynchronous Collection API>> call.
+Deletes the stored response of an already failed or completed <<CollectionsAPI-async,Asynchronous Collection API>> call.
`/admin/collections?action=DELETESTATUS&requestid=_request-id_`
-[[CollectionsAPI-Input.16]]
-=== Input
-
-*Query Parameters*
+=== DELETESTATUS Parameters
-// TODO: Change column width to %autowidth.spread when https://github.com/asciidoctor/asciidoctor-pdf/issues/599 is fixed
+`requestid`::
+The request ID of the asynchronous call whose stored response should be cleared.
-[cols="20,15,10,55",options="header"]
-|===
-|Key |Type |Required |Description
-|requestid |string |No |The request-id of the async call we need to clear the stored response for.
-|flush |boolean |No |Set to true to clear all stored completed and failed async request responses.
-|===
+`flush`::
+Set to `true` to clear all stored completed and failed async request responses.
-[[CollectionsAPI-Examples.17]]
-=== Examples
+=== Examples using DELETESTATUS
-*Input: Valid Request Status*
+*Input: Valid Request ID*
[source,text]
----
@@ -1376,7 +1344,7 @@ http://localhost:8983/solr/admin/collections?action=DELETESTATUS&requestid=foo
</response>
----
-*Input: Invalid RequestId*
+*Input: Invalid Request ID*
[source,text]
----
@@ -1396,7 +1364,7 @@ http://localhost:8983/solr/admin/collections?action=DELETESTATUS&requestid=bar
</response>
----
-*Input: Clear all the stored statuses*
+*Input: Clear All Stored Statuses*
[source,text]
----
@@ -1423,8 +1391,7 @@ Fetch the names of the collections in the cluster.
`/admin/collections?action=LIST`
-[[CollectionsAPI-Example]]
-=== Example
+=== Examples using LIST
*Input*
@@ -1453,44 +1420,47 @@ Assign an arbitrary property to a particular replica and give it the value speci
`/admin/collections?action=ADDREPLICAPROP&collection=collectionName&shard=shardName&replica=replicaName&property=propertyName&property.value=value`
-[[CollectionsAPI-Input.17]]
-=== Input
+=== ADDREPLICAPROP Parameters
-*Query Parameters*
+`collection`::
+The name of the collection the replica belongs to. This parameter is required.
-// TODO: Change column width to %autowidth.spread when https://github.com/asciidoctor/asciidoctor-pdf/issues/599 is fixed
+`shard`::
+The name of the shard the replica belongs to. This parameter is required.
-[cols="20,15,10,55",options="header"]
-|===
-|Key |Type |Required |Description
-|collection |string |Yes |The name of the collection this replica belongs to.
-|shard |string |Yes |The name of the shard the replica belongs to.
-|replica |string |Yes |The replica, e.g. core_node1.
-|property |string |Yes a|
-The property to add. Note: this will have the literal 'property.' prepended to distinguish it from system-maintained properties. So these two forms are equivalent:
+`replica`::
+The replica, e.g., `core_node1`. This parameter is required.
+`property`::
+The name of the property to add. This property is required.
++
+This will have the literal `property.` prepended to distinguish it from system-maintained properties. So these two forms are equivalent:
++
`property=special`
-
++
and
-
++
`property=property.special`
-|property.value |string |Yes |The value to assign to the property.
-|shardUnique |Boolean |No |default: false. If true, then setting this property in one replica will remove the property from all other replicas in that shard.
-There is one pre-defined property `preferredLeader` for which `shardUnique` is forced to 'true' and an error returned if `shardUnique` is explicitly set to 'false'. `PreferredLeader` is a boolean property, any value assigned that is not equal (case insensitive) to 'true' will be interpreted as 'false' for `preferredLeader`.
-|===
+`property.value`::
+The value to assign to the property. This parameter is required.
-[[CollectionsAPI-Output.13]]
-=== Output
+`shardUnique`::
+If `true`, then setting this property in one replica will remove the property from all other replicas in that shard. The default is `false`.
++
+There is one pre-defined property `preferredLeader` for which `shardUnique` is forced to `true` and an error returned if `shardUnique` is explicitly set to `false`.
++
+`PreferredLeader` is a boolean property. Any value assigned that is not equal (case insensitive) to `true` will be interpreted as `false` for `preferredLeader`.
+
+=== ADDREPLICAPROP Response
The response will include the status of the request. If the status is anything other than "0", an error message will explain why the request failed.
-[[CollectionsAPI-Examples.18]]
-=== Examples
+=== Examples using ADDREPLICAPROP
*Input*
-This command would set the preferredLeader (`property.preferredLeader`) to true on core_node1, and remove that property from any other replica in the shard.
+This command would set the "preferredLeader" property (`property.preferredLeader`) to "true" on "core_node1", and remove that property from any other replica in the shard.
[source,text]
----
@@ -1511,7 +1481,7 @@ http://localhost:8983/solr/admin/collections?action=ADDREPLICAPROP&shard=shard1&
*Input*
-This pair of commands will set the "testprop" (`property.testprop`) to 'value1' and 'value2' respectively for two nodes in the same shard.
+This pair of commands will set the "testprop" property (`property.testprop`) to 'value1' and 'value2' respectively for two nodes in the same shard.
[source,text]
----
@@ -1522,7 +1492,7 @@ http://localhost:8983/solr/admin/collections?action=ADDREPLICAPROP&shard=shard1&
*Input*
-This pair of commands would result in core_node_3 having the testprop (`property.testprop`) value set because the second command specifies `shardUnique=true`, which would cause the property to be removed from core_node_1.
+This pair of commands would result in "core_node_3" having the "testprop" property (`property.testprop`) value set because the second command specifies `shardUnique=true`, which would cause the property to be removed from "core_node_1".
[source,text]
----
@@ -1538,36 +1508,31 @@ Deletes an arbitrary property from a particular replica.
`/admin/collections?action=DELETEREPLICAPROP&collection=collectionName&shard=_shardName_&replica=_replicaName_&property=_propertyName_`
-[[CollectionsAPI-Input.18]]
-=== Input
+=== DELETEREPLICAPROP Parameters
-*Query Parameters*
+`collection`::
+The name of the collection the replica belongs to. This parameter is required.
-// TODO: Change column width to %autowidth.spread when https://github.com/asciidoctor/asciidoctor-pdf/issues/599 is fixed
+`shard`::
+The name of the shard the replica belongs to. This parameter is required.
-[cols="20,15,10,55",options="header"]
-|===
-|Key |Type |Required |Description
-|collection |string |Yes |The name of the collection this replica belongs to
-|shard |string |Yes |The name of the shard the replica belongs to.
-|replica |string |Yes |The replica, e.g. core_node1.
-|property |string |Yes a|
-The property to add. Note: this will have the literal 'property.' prepended to distinguish it from system-maintained properties. So these two forms are equivalent:
+`replica`::
+The replica, e.g. `core_node1`. This parameter is required.
+`property`::
+The property to add. This will have the literal `property.` prepended to distinguish it from system-maintained properties. So these two forms are equivalent:
++
`property=special`
-
++
and
-
++
`property=property.special`
-|===
-[[CollectionsAPI-Output.14]]
-=== Output
+=== DELETEREPLICAPROP Response
The response will include the status of the request. If the status is anything other than "0", an error message will explain why the request failed.
-[[CollectionsAPI-Examples.19]]
-=== Examples
+=== Examples using DELETEREPLICAPROP
*Input*
@@ -1597,29 +1562,25 @@ http://localhost:8983/solr/admin/collections?action=DELETEREPLICAPROP&shard=shar
Insures that a particular property is distributed evenly amongst the physical nodes that make up a collection. If the property already exists on a replica, every effort is made to leave it there. If the property is *not* on any replica on a shard, one is chosen and the property is added.
-[[CollectionsAPI-Input.19]]
-=== Input
+=== BALANCESHARDUNIQUE Parameters
+
+`collection`::
+The name of the collection to balance the property in. This parameter is required.
-*Query Parameters*
+`property`::
+The property to balance. The literal `property.` is prepended to this property if not specified explicitly. This parameter is required.
-// TODO: Change column width to %autowidth.spread when https://github.com/asciidoctor/asciidoctor-pdf/issues/599 is fixed
+`onlyactivenodes`::
+Defaults to `true`. Normally, the property is instantiated on active nodes only. If this parameter is specified as `false`, then inactive nodes are also included for distribution.
-[cols="20,15,10,55",options="header"]
-|===
-|Key |Type |Required |Description
-|collection |string |Yes |The name of the collection to balance the property in.
-|property |string |Yes |The property to balance. The literal "property." is prepended to this property if not specified explicitly.
-|onlyactivenodes |boolean |No |Defaults to true. Normally, the property is instantiated on active nodes only. If this parameter is specified as "false", then inactive nodes are also included for distribution.
-|shardUnique |boolean |No |Something of a safety valve. There is one pre-defined property (preferredLeader) that defaults this value to "true". For all other properties that are balanced, this must be set to "true" or an error message is returned.
-|===
+`shardUnique`::
+Something of a safety valve. There is one pre-defined property (`preferredLeader`) that defaults this value to `true`. For all other properties that are balanced, this must be set to `true` or an error message will be returned.
-[[CollectionsAPI-Output.15]]
-=== Output
+=== BALANCESHARDUNIQUE Response
The response will include the status of the request. If the status is anything other than "0", an error message will explain why the request failed.
-[[CollectionsAPI-Examples.20]]
-=== Examples
+=== Examples using BALANCESHARDUNIQUE
*Input*
@@ -1649,38 +1610,38 @@ Examining the clusterstate after issuing this call should show exactly one repli
[[CollectionsAPI-rebalanceleaders]]
== REBALANCELEADERS: Rebalance Leaders
-Reassign leaders in a collection according to the preferredLeader property across active nodes.
+Reassigns leaders in a collection according to the preferredLeader property across active nodes.
`/admin/collections?action=REBALANCELEADERS&collection=collectionName`
-Assigns leaders in a collection according to the preferredLeader property on active nodes. This command should be run after the preferredLeader property has been assigned via the BALANCESHARDUNIQUE or ADDREPLICAPROP commands. NOTE: it is not _required_ that all shards in a collection have a preferredLeader property. Rebalancing will only attempt to reassign leadership to those replicas that have the preferredLeader property set to "true" _and_ are not currently the shard leader _and_ are currently active.
+Leaders are assigned in a collection according to the `preferredLeader` property on active nodes. This command should be run after the preferredLeader property has been assigned via the BALANCESHARDUNIQUE or ADDREPLICAPROP commands.
-[[CollectionsAPI-Input.20]]
-=== Input
+NOTE: It is not _required_ that all shards in a collection have a `preferredLeader` property. Rebalancing will only attempt to reassign leadership to those replicas that have the `preferredLeader` property set to `true` _and_ are not currently the shard leader _and_ are currently active.
-*Query Parameters*
+=== REBALANCELEADERS Parameters
-// TODO: Change column width to %autowidth.spread when https://github.com/asciidoctor/asciidoctor-pdf/issues/599 is fixed
+`collection`::
+The name of the collection to rebalance `preferredLeaders` on. This parameter is required.
-[cols="20,15,10,55",options="header"]
-|===
-|Key |Type |Required |Description
-|collection |string |Yes |The name of the collection to rebalance preferredLeaders on.
-|maxAtOnce |string |No |The maximum number of reassignments to have queue up at once. Values \<=0 are use the default value Integer.MAX_VALUE. When this number is reached, the process waits for one or more leaders to be successfully assigned before adding more to the queue.
-|maxWaitSeconds |string |No |Defaults to 60. This is the timeout value when waiting for leaders to be reassigned. NOTE: if maxAtOnce is less than the number of reassignments that will take place, this is the maximum interval that any _single_ wait for at least one reassignment. For example, if 10 reassignments are to take place and maxAtOnce is 1 and maxWaitSeconds is 60, the upper bound on the time that the command may wait is 10 minutes.
-|===
+`maxAtOnce`::
+The maximum number of reassignments to have queue up at once. Values \<=0 are use the default value Integer.MAX_VALUE.
++
+When this number is reached, the process waits for one or more leaders to be successfully assigned before adding more to the queue.
-[[CollectionsAPI-Output.16]]
-=== Output
+`maxWaitSeconds`::
+Defaults to `60`. This is the timeout value when waiting for leaders to be reassigned. If `maxAtOnce` is less than the number of reassignments that will take place, this is the maximum interval that any _single_ wait for at least one reassignment.
++
+For example, if 10 reassignments are to take place and `maxAtOnce` is `1` and `maxWaitSeconds` is `60`, the upper bound on the time that the command may wait is 10 minutes.
+
+=== REBALANCELEADERS Response
The response will include the status of the request. If the status is anything other than "0", an error message will explain why the request failed.
-[[CollectionsAPI-Examples.21]]
-=== Examples
+=== Examples using REBALANCELEADERS
*Input*
-Either of these commands would cause all the active replicas that had the "preferredLeader" property set and were _not_ already the preferred leader to become leaders.
+Either of these commands would cause all the active replicas that had the `preferredLeader` property set and were _not_ already the preferred leader to become leaders.
[source,text]
----
@@ -1690,7 +1651,9 @@ http://localhost:8983/solr/admin/collections?action=REBALANCELEADERS&collection=
*Output*
-In this example, two replicas in the "alreadyLeaders" section already had the leader assigned to the same node as the preferredLeader property so no action was taken. The replica in the "inactivePreferreds" section had the preferredLeader property set but the node was down and no action was taken. The three nodes in the "successes" section were made leaders because they had the preferredLeader property set but were not leaders and they were active.
+In this example, two replicas in the "alreadyLeaders" section already had the leader assigned to the same node as the `preferredLeader` property so no action was taken.
+
+The replica in the "inactivePreferreds" section had the `preferredLeader` property set but the node was down and no action was taken. The three nodes in the "successes" section were made leaders because they had the `preferredLeader` property set but were not leaders and they were active.
[source,xml]
----
@@ -1744,7 +1707,7 @@ In this example, two replicas in the "alreadyLeaders" section already had the le
</response>
----
-Examining the clusterstate after issuing this call should show that every live node that has the "preferredLeader" property should also have the "leader" property set to _true_.
+Examining the clusterstate after issuing this call should show that every live node that has the `preferredLeader` property should also have the "leader" property set to _true_.
[[CollectionsAPI-FORCELEADER_ForceShardLeader]]
@@ -1752,28 +1715,19 @@ Examining the clusterstate after issuing this call should show that every live n
[[CollectionsAPI-forceleader]]
== FORCELEADER: Force Shard Leader
-In the unlikely event of a shard losing its leader, this command can be invoked to force the election of a new leader
+In the unlikely event of a shard losing its leader, this command can be invoked to force the election of a new leader.
`/admin/collections?action=FORCELEADER&collection=<collectionName>&shard=<shardName>`
-[[CollectionsAPI-Input.21]]
-=== Input
+=== FORCELEADER Parameters
-*Query Parameters*
+`collection`::
+The name of the collection. This parameter is required.
-// TODO: Change column width to %autowidth.spread when https://github.com/asciidoctor/asciidoctor-pdf/issues/599 is fixed
+`shard`::
+The name of the shard where leader election should occur. This parameter is required.
-[cols="20,15,10,55",options="header"]
-|===
-|Key |Type |Required |Description
-|collection |string |Yes |The name of the collection
-|shard |string |Yes |The name of the shard
-|===
-
-[IMPORTANT]
-====
-This is an expert level command, and should be invoked only when regular leader election is not working. This may potentially lead to loss of data in the event that the new leader doesn't have certain updates, possibly recent ones, which were acknowledged by the old leader before going down.
-====
+WARNING: This is an expert level command, and should be invoked only when regular leader election is not working. This may potentially lead to loss of data in the event that the new leader doesn't have certain updates, possibly recent ones, which were acknowledged by the old leader before going down.
[[CollectionsAPI-migratestateformat]]
== MIGRATESTATEFORMAT: Migrate Cluster State
@@ -1782,41 +1736,38 @@ A expert level utility API to move a collection from shared `clusterstate.json`
`/admin/collections?action=MIGRATESTATEFORMAT&collection=<collection_name>`
-// TODO: Change column width to %autowidth.spread when https://github.com/asciidoctor/asciidoctor-pdf/issues/599 is fixed
+=== MIGRATESTATEFORMAT Parameters
+
+`collection`::
+The name of the collection to be migrated from `clusterstate.json` to its own `state.json` ZooKeeper node. This parameter is required.
-[cols="20,15,10,55",options="header"]
-|===
-|Key |Type |Required |Description
-|collection |string |Yes |The name of the collection to be migrated from `clusterstate.json` to its own `state.json` zookeeper node
-|async |string |No |Request ID to track this action which will be <<CollectionsAPI-async,processed asynchronously>>.
-|===
+`async`::
+Request ID to track this action which will be <<CollectionsAPI-async,processed asynchronously>>.
This API is useful in migrating any collections created prior to Solr 5.0 to the more scalable cluster state format now used by default. If a collection was created in any Solr 5.x version or higher, then executing this command is not necessary.
[[CollectionsAPI-backup]]
== BACKUP: Backup Collection
-Backup Solr collections and it's associated configurations to a shared filesystem - for example a Network File System
+Backs up Solr collections and associated configurations to a shared filesystem - for example a Network File System.
`/admin/collections?action=BACKUP&name=myBackupName&collection=myCollectionName&location=/path/to/my/shared/drive`
-The backup command will backup Solr indexes and configurations for a specified collection. The backup command takes one copy from each shard for the indexes. For configurations it backs up the configSet that was associated with the collection and metadata.
+The BACKUP command will backup Solr indexes and configurations for a specified collection. The BACKUP command takes one copy from each shard for the indexes. For configurations, it backs up the configSet that was associated with the collection and metadata.
-[[CollectionsAPI-Input.22]]
-=== Input
+=== BACKUP Parameters
-*Query Parameters*
+`collection`::
+The name of the collection to be backed up. This parameter is required.
-// TODO: Change column width to %autowidth.spread when https://github.com/asciidoctor/asciidoctor-pdf/issues/599 is fixed
+`location`::
+The location on a shared drive for the backup command to write to. Alternately it can be set as a <<CollectionsAPI-clusterprop,cluster property>>.
-[cols="20,15,10,55",options="header"]
-|===
-|Key |Type |Required |Description
-|collection |string |Yes |The name of the collection that needs to be backed up
-|location |string |No |The location on the shared drive for the backup command to write to. Alternately it can be set as a <<CollectionsAPI-clusterprop,cluster property>>
-|async |string |No |Request ID to track this action which will be <<CollectionsAPI-async,processed asynchronously>>
-|repository |string |No |The name of the repository to be used for the backup. If no repository is specified then the local filesystem repository will be used automatically.
-|===
+`async`::
+Request ID to track this action which will be <<CollectionsAPI-async,processed asynchronously>>.
+
+`repository`::
+The name of a repository to be used for the backup. If no repository is specified then the local filesystem repository will be used automatically.
[[CollectionsAPI-restore]]
== RESTORE: Restore Collection
@@ -1825,43 +1776,48 @@ Restores Solr indexes and associated configurations.
`/admin/collections?action=RESTORE&name=myBackupName&location=/path/to/my/shared/drive&collection=myRestoredCollectionName`
-The restore operation will create a collection with the specified name in the collection parameter. You cannot restore into the same collection the backup was taken from and the target collection should not be present at the time the API is called as Solr will create it for you.
+The RESTORE operation will create a collection with the specified name in the collection parameter. You cannot restore into the same collection the backup was taken from. Also the target collection should not be present at the time the API is called as Solr will create it for you.
+
+The collection created will be have the same number of shards and replicas as the original collection, preserving routing information, etc. Optionally, you can override some parameters documented below.
-The collection created will be of the same number of shards and replicas as the original collection, preserving routing information, etc. Optionally, you can override some parameters documented below. While restoring, if a configSet with the same name exists in ZooKeeper then Solr will reuse that, or else it will upload the backed up configSet in ZooKeeper and use that.
+While restoring, if a configSet with the same name exists in ZooKeeper then Solr will reuse that, or else it will upload the backed up configSet in ZooKeeper and use that.
-You can use the collection <<CollectionsAPI-createalias,alias>> API to make sure client's don't need to change the endpoint to query or index against the newly restored collection.
+You can use the collection <<CollectionsAPI-createalias,CREATEALIAS>> command to make sure clients don't need to change the endpoint to query or index against the newly restored collection.
-[[CollectionsAPI-Input.23]]
-=== Input
+=== RESTORE Parameters
-*Query Parameters*
+`collection`::
+The collection where the indexes will be restored into. This parameter is required.
-// TODO: Change column width to %autowidth.spread when https://github.com/asciidoctor/asciidoctor-pdf/issues/599 is fixed
+`location`::
+The location on a shared drive for the RESTORE command to read from. Alternately it can be set as a <<CollectionsAPI-clusterprop,cluster property>>.
-[cols="20,15,10,55",options="header"]
-|===
-|Key |Type |Required |Description
-|collection |string |Yes |The collection where the indexes will be restored into.
-|location |string |No |The location on the shared drive for the restore command to read from. Alternately it can be set as a <<CollectionsAPI-clusterprop,cluster property>>.
-|async |string |No |Request ID to track this action which will be <<CollectionsAPI-async,processed asynchronously>>.
-|repository |string |No |The name of the repository to be used for the backup. If no repository is specified then the local filesystem repository will be used automatically.
-|===
+`async`::
+Request ID to track this action which will be <<CollectionsAPI-async,processed asynchronously>>.
-Additionally, there are several parameters that can be overridden:
+`repository`::
+The name of a repository to be used for the backup. If no repository is specified then the local filesystem repository will be used automatically.
*Override Parameters*
-// TODO: Change column width to %autowidth.spread when https://github.com/asciidoctor/asciidoctor-pdf/issues/599 is fixed
+Additionally, there are several parameters that may have been set on the original collection that can be overridden when restoring the backup:
+
+`collection.configName`::
+Defines the name of the configurations to use for this collection. These must already be stored in ZooKeeper. If not provided, Solr will default to the collection name as the configuration name.
+
+`replicationFactor`::
+The number of replicas to be created for each shard.
+
+`maxShardsPerNode`::
+When creating collections, the shards and/or replicas are spread across all available (i.e., live) nodes, and two replicas of the same shard will never be on the same node.
++
+If a node is not live when the CREATE operation is called, it will not get any parts of the new collection, which could lead to too many replicas being created on a single live node. Defining `maxShardsPerNode` sets a limit on the number of replicas CREATE will spread to each node. If the entire collection can not be fit into the live nodes, no collection will be created at all.
+
+`autoAddReplicas`::
+When set to `true`, enables auto addition of replicas on shared file systems. See the section <<running-solr-on-hdfs.adoc#RunningSolronHDFS-AutomaticallyAddReplicasinSolrCloud,Automatically Add Replicas in SolrCloud>> for more details on settings and overrides.
-[cols="25,15,10,50",options="header"]
-|===
-|Key |Type |Required |Description
-|collection.configName |String |No |Defines the name of the configurations to use for this collection. These must already be stored in ZooKeeper. If not provided, Solr will default to the collection name as the configuration name.
-|replicationFactor |Integer |No |The number of replicas to be created for each shard.
-|maxShardsPerNode |Integer |No |When creating collections, the shards and/or replicas are spread across all available (i.e., live) nodes, and two replicas of the same shard will never be on the same node. If a node is not live when the CREATE operation is called, it will not get any parts of the new collection, which could lead to too many replicas being created on a single live node. Defining `maxShardsPerNode` sets a limit on the number of replicas CREATE will spread to each node. If the entire collection can not be fit into the live nodes, no collection will be created at all.
-|autoAddReplicas |Boolean |No |When set to true, enables auto addition of replicas on shared file systems. See the section <<running-solr-on-hdfs.adoc#RunningSolronHDFS-AutomaticallyAddReplicasinSolrCloud,Automatically Add Replicas in SolrCloud>> for more details on settings and overrides.
-|property._name_=_value_ |String |No |Set core property _name_ to _value_. See the section <<defining-core-properties.adoc#defining-core-properties,Defining core.properties>> for details on supported properties and values.
-|===
+`property._name_=_value_`::
+Set core property _name_ to _value_. See the section <<defining-core-properties.adoc#defining-core-properties,Defining core.properties>> for details on supported properties and values.
[[CollectionsAPI-deletenode]]
== DELETENODE: Delete Replicas in a Node
@@ -1870,43 +1826,38 @@ Deletes all replicas of all collections in that node. Please note that the node
`/admin/collections?action=DELETENODE&node=nodeName`
-[[CollectionsAPI-Input.24]]
-=== Input
+=== DELETENODE Parameters
-*Query Parameters*
+`node`:: string |Yes |The node to be removed. This parameter is required.
-// TODO: Change column width to %autowidth.spread when https://github.com/asciidoctor/asciidoctor-pdf/issues/599 is fixed
-
-[cols="20,15,10,55",options="header"]
-|===
-|Key |Type |Required |Description
-|node |string |Yes |The node to be cleaned up
-|async |string |No |Request ID to track this action which will be <<CollectionsAPI-async,processed asynchronously>>.
-|===
+`async`::
+Request ID to track this action which will be <<CollectionsAPI-async,processed asynchronously>>.
[[CollectionsAPI-replacenode]]
== REPLACENODE: Move All Replicas in a Node to Another
-This command recreates replicas in the source node to the target node. After each replica is copied, the replicas in the source node are deleted. For source replicas that are also shard leaders the operation will wait for "timeout" seconds to make sure there's an active replica that can become a leader (either an existing replica becoming a leader or the new replica completing the recovery and becoming a leader).
+This command recreates replicas in one node (the source) to another node (the target). After each replica is copied, the replicas in the source node are deleted.
+
+For source replicas that are also shard leaders the operation will wait for the number of seconds set with the `timeout` parameter to make sure there's an active replica that can become a leader (either an existing replica becoming a leader or the new replica completing recovery and becoming a leader).
`/admin/collections?action=REPLACENODE&source=_source-node_&target=_target-node_`
-[[CollectionsAPI-Input.25]]
-=== Input
+=== REPLACENODE Parameters
+
+`source`::
+The source node from which the replicas need to be copied from. This parameter is required.
+
+`target`::
+The target node where replicas will be copied. This parameter is required.
-*Query Parameters*
+`parallel`::
+If this flag is set to `true`, all replicas are created in separate threads. Keep in mind that this can lead to very high network and disk I/O if the replicas have very large indices. The default is `false`.
-// TODO: Change column width to %autowidth.spread when https://github.com/asciidoctor/asciidoctor-pdf/issues/599 is fixed
+`async`::
+Request ID to track this action which will be <<CollectionsAPI-async,processed asynchronously>>.
-[cols="20,15,10,55",options="header"]
-|===
-|Key |Type |Required |Description
-|source |string |Yes |The source node from which the replicas need to be copied from
-|target |string |Yes |The target node
-|parallel |boolean |No |default=false. if this flag is set to true, all replicas are created inseparatee threads. Keep in mind that this can lead to very high network and disk I/O if the replicas have very large indices.
-|async |string |No |Request ID to track this action which will be <<CollectionsAPI-async,processed asynchronously>>.
-|timeout |int |No |default is 300. Timeout in seconds to wait until new replicas are created, and until leader replicas are fully recovered.
-|===
+`timeout`::
+Time in seconds to wait until new replicas are created, and until leader replicas are fully recovered. The default is `300`, or 5 minutes.
[IMPORTANT]
====
@@ -1914,39 +1865,40 @@ This operation does not hold necessary locks on the replicas that belong to on t
====
[[CollectionsAPI-movereplica]]
-== MOVEREPLICA: Move a Replica to a New node
+== MOVEREPLICA: Move a Replica to a New Node
-This command move a replica from a node to a new node, in case of shared-file systems the `dataDir` will be reused.
+This command moves a replica from one node to a new node. In case of shared filesystems the `dataDir` will be reused.
`/admin/collections?action=MOVEREPLICA&collection=collection&shard=shard&replica=replica&node=nodeName&toNode=nodeName`
-[[CollectionsAPI-Input.26]]
-=== Input
+=== MOVEREPLICA Parameters
+
+`collection`::
+The name of the collection. This parameter is required.
+
+`shard`::
+The name of the shard that the replica belongs to. This parameter is required.
+
+`replica`::
+The name of the replica. This parameter is required.
-*Query Parameters*
+`node`::
+The name of the node that contains the replica. This parameter is required.
-// TODO: Change column width to %autowidth.spread when https://github.com/asciidoctor/asciidoctor-pdf/issues/599 is fixed
+`toNode`::
+The name of the destination node. This parameter is required.
-[cols="20,15,10,55",options="header"]
-|===
-|Key |Type |Required |Description
-|collection |string |Yes |The name of the collection.
-|shard |string |Yes |The name of shard that replica belong to.
-|replica |string |Yes |The name of the replica.
-|node |string |Yes |The name of the node that contains the replica.
-|toNode |string |Yes |The name of the destination node.
-|async |string |No |Request ID to track this action which will be <<CollectionsAPI-async,processed asynchronously>>.
-|===
+`async`::
+Request ID to track this action which will be <<CollectionsAPI-async,processed asynchronously>>.
[[CollectionsAPI-async]]
== Asynchronous Calls
-Since some collection API calls can be long running tasks e.g. Shard Split, you can optionally have the calls run asynchronously. Specifying `async=<request-id>` enables you to make an asynchronous call, the status of which can be requested using the <<CollectionsAPI-requeststatus,REQUESTSTATUS>> call at any time.
+Since some collection API calls can be long running tasks (such as SPLITSHARD), you can optionally have the calls run asynchronously. Specifying `async=<request-id>` enables you to make an asynchronous call, the status of which can be requested using the <<CollectionsAPI-requeststatus,REQUESTSTATUS>> call at any time.
As of now, REQUESTSTATUS does not automatically clean up the tracking data structures, meaning the status of completed or failed tasks stays stored in ZooKeeper unless cleared manually. DELETESTATUS can be used to clear the stored statuses. However, there is a limit of 10,000 on the number of async call responses stored in a cluster.
-[[CollectionsAPI-Example.1]]
-=== Example
+=== Examples of Async Requests
*Input*