You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@lucene.apache.org by "Noble Paul (Confluence)" <co...@apache.org> on 2013/09/15 09:43:00 UTC
[CONF] Apache Solr Reference Guide > Collections API
Space: Apache Solr Reference Guide (https://cwiki.apache.org/confluence/display/solr)
Page: Collections API (https://cwiki.apache.org/confluence/display/solr/Collections+API)
Edited by Noble Paul:
---------------------------------------------------------------------
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 base URL for all API calls below is {{http://<hostname>:<port>/solr}}.
{toc}
h2. API Entry Points
{{/admin/collections?action=CREATE}}: [create|#api1] a collection
{{/admin/collections?action=RELOAD}}: [reload|#api2] a collection
{{/admin/collections?action=SPLITSHARD}}: [split|#api3] a shard into two new shards
{{/admin/collections?action=DELETESHARD}}: [delete|#api7] an inactive shard
{{/admin/collections?action=CREATEALIAS}}: [create an alias|#api4] for a collection
{{/admin/collections?action=DELETEALIAS}}: [delete an alias|#api5] for a collection
{{/admin/collections?action=DELETE}}: [delete|#api6] a collection
{anchor:api1}
h2. Create a Collection
{{/admin/collections?action=CREATE&name=_name_&numShards=_number_&replicationFactor=_number_&maxShardsPerNode=_number_&createNodeSet=_nodelist_&collection.configName=_configname_}}
h4. {bgcolor:#FEECC4}{*}Input{*}{bgcolor}
*Query Parameters*
|| Key || Type || Required || Default || Description ||
| name | string | Yes | | The name of the collection to be created. |
| router | string | No | compositeId |The router name. allowed values are 'implicit' and 'compositeId'. For 'implicit router 'shards' param is required and for 'compositeId' router 'numShards' param is required|
| numShards | integer | No | null | The number of shards to be created as part of the collection. This is a required param for 'compositeId' router |
| shards | string | No | | This is a comma separated list of shard names e.g : shard-x,shard-y,shard-z . This is a required param for 'implicit' router|
| replicationFactor | integer | Yes | null | 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 | null | 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}}. |
| collection.configName | string | No | the collection name | 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. |
h4. {bgcolor:#FEECC4}{*}Output{*}{bgcolor}
*Output Content*
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.
h4. {bgcolor:#FEECC4}{*}Examples{*}{bgcolor}
*Input*
{code:borderStyle=solid|borderColor=#666666}
http://localhost:8983/solr/admin/collections?action=CREATE&name=newCollection&numShards=2&replicationFactor=1
{code}
*Output*
{code:borderStyle=solid|borderColor=#666666}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<lst name="responseHeader">
<int name="status">0</int>
<int name="QTime">3764</int>
</lst>
<lst name="success">
<lst>
<lst name="responseHeader">
<int name="status">0</int>
<int name="QTime">3450</int>
</lst>
<str name="core">newCollection_shard1_replica1</str>
<str name="saved">/Applications/solr-4.3.0/example/solr/solr.xml</str>
</lst>
<lst>
<lst name="responseHeader">
<int name="status">0</int>
<int name="QTime">3597</int>
</lst>
<str name="core">newCollection_shard2_replica1</str>
<str name="saved">/Applications/solr-4.3.0/example/solr/solr.xml</str>
</lst>
</lst>
</response>
{code}
{anchor:api2}
h2. Reload a Collection
{{/admin/collections?action=RELOAD&name=_name_}}
The RELOAD action is used when you have changed a configuration in ZooKeeper.
h4. {bgcolor:#FEECC4}{*}Input{*}{bgcolor}
*Query Parameters*
|| Key || Type || Required || Description ||
| name | string | Yes | The name of the collection to reload. |
h4. {bgcolor:#FEECC4}{*}Output{*}{bgcolor}
*Output Content*
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.
h4. {bgcolor:#FEECC4}{*}Examples{*}{bgcolor}
*Input*
{code:borderStyle=solid|borderColor=#666666}
http://localhost:8983/solr/admin/collections?action=RELOAD&name=newCollection
{code}
*Output*
{code:borderStyle=solid|borderColor=#666666}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<lst name="responseHeader">
<int name="status">0</int>
<int name="QTime">1551</int>
</lst>
<lst name="success">
<lst name="10.0.1.6:8983_solr">
<lst name="responseHeader">
<int name="status">0</int>
<int name="QTime">761</int>
</lst>
</lst>
<lst name="10.0.1.4:8983_solr">
<lst name="responseHeader">
<int name="status">0</int>
<int name="QTime">1527</int>
</lst>
</lst>
</lst>
</response>
{code}
{anchor:api3}
h2. Split a Shard
Splitting a shard will take an existing shard and break it into two pieces. 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. After splitting a shard, you should issue a commit to make the documents visible, and then you can remove the original shard (with the Core API or Solr Admin UI) when ready.
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 i.e. 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.
Note that this is a synchronous operation and it can take some time to split a large shard. Therefore, a read timeout does not necessarily imply failure and a retry should be made after verifying the state of the cluster.
{{/admin/collections?action=SHARDSPLIT&collection=_name_&shard=_shardID_}}
h4. {bgcolor:#FEECC4}{*}Input{*}{bgcolor}
*Query Parameters*
|| 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. |
h4. {bgcolor:#FEECC4}{*}Output{*}{bgcolor}
*Output Content*
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.
h4. {bgcolor:#FEECC4}{*}Examples{*}{bgcolor}
*Input*
Split shard1 of the "anotherCollection" collection.
{code:borderStyle=solid|borderColor=#666666}
http://10.0.1.6:8983/solr/admin/collections?action=SPLITSHARD&collection=anotherCollection&shard=shard1
{code}
*Output*
{code:borderStyle=solid|borderColor=#666666}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<lst name="responseHeader">
<int name="status">0</int>
<int name="QTime">6120</int>
</lst>
<lst name="success">
<lst>
<lst name="responseHeader">
<int name="status">0</int>
<int name="QTime">3673</int>
</lst>
<str name="core">anotherCollection_shard1_1_replica1</str>
<str name="saved">/Applications/solr-4.3.0/example/solr/solr.xml</str>
</lst>
<lst>
<lst name="responseHeader">
<int name="status">0</int>
<int name="QTime">3681</int>
</lst>
<str name="core">anotherCollection_shard1_0_replica1</str>
<str name="saved">/Applications/solr-4.3.0/example/solr/solr.xml</str>
</lst>
<lst>
<lst name="responseHeader">
<int name="status">0</int>
<int name="QTime">6008</int>
</lst>
</lst>
<lst>
<lst name="responseHeader">
<int name="status">0</int>
<int name="QTime">6007</int>
</lst>
</lst>
<lst>
<lst name="responseHeader">
<int name="status">0</int>
<int name="QTime">71</int>
</lst>
</lst>
<lst>
<lst name="responseHeader">
<int name="status">0</int>
<int name="QTime">0</int>
</lst>
<str name="core">anotherCollection_shard1_1_replica1</str>
<str name="status">EMPTY_BUFFER</str>
</lst>
<lst>
<lst name="responseHeader">
<int name="status">0</int>
<int name="QTime">0</int>
</lst>
<str name="core">anotherCollection_shard1_0_replica1</str>
<str name="status">EMPTY_BUFFER</str>
</lst>
</lst>
</response>
{code}
{anchor:api7}
h2. Delete a Shard
Deleting a shard will unload all replicas of the shard and remove them from {{clusterstate.json}}. It will only remove shards that are inactive, or which have no range given for custom sharding.
{{/admin/collections?action=DELETESHARD&shard=_shardID_&collection=_name_}}
h4. {bgcolor:#FEECC4}{*}Input{*}{bgcolor}
*Query Parameters*
|| 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. |
h4. {bgcolor:#FEECC4}{*}Output{*}{bgcolor}
*Output Content*
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.
h4. {bgcolor:#FEECC4}{*}Examples{*}{bgcolor}
*Input*
Delete 'shard1' of the "anotherCollection" collection.
{code:borderStyle=solid|borderColor=#666666}
http://10.0.1.6:8983/solr/admin/collections?action=DELETESHARD&collection=anotherCollection&shard=shard1
{code}
*Output*
{code:borderStyle=solid|borderColor=#666666}
<response>
<lst name="responseHeader">
<int name="status">0</int>
<int name="QTime">558</int>
</lst>
<lst name="success">
<lst name="10.0.1.4:8983_solr">
<lst name="responseHeader">
<int name="status">0</int>
<int name="QTime">27</int>
</lst>
</lst>
</lst>
</response>
{code}
{anchor:api4}
h2. Create an Alias for a Collection
{{/admin/collections?action=CREATEALIAS&name=_name_&collections=_collectionlist_}}
h4. {bgcolor:#FEECC4}{*}Input{*}{bgcolor}
*Query Parameters*
|| 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. |
h4. {bgcolor:#FEECC4}{*}Output{*}{bgcolor}
*Output Content*
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.
h4. {bgcolor:#FEECC4}{*}Examples{*}{bgcolor}
*Input*
Create an alias named "testalias" and link it to the collections named "anotherCollection" and "testCollection".
{code:borderStyle=solid|borderColor=#666666}
http://10.0.1.6:8983/solr/admin/collections?action=CREATEALIAS&name=testalias&collections=anotherCollection,testCollection
{code}
*Output*
{code:borderStyle=solid|borderColor=#666666}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<lst name="responseHeader">
<int name="status">0</int>
<int name="QTime">122</int>
</lst>
</response>
{code}
{anchor:api5}
h2. Delete a Collection Alias
{{/admin/collections?action=DELETEALIAS&name=_name_}}
h4. {bgcolor:#FEECC4}{*}Input{*}{bgcolor}
*Query Parameters*
|| Key || Type || Required || Description ||
| name | string | Yes | The name of the alias to delete. |
h4. {bgcolor:#FEECC4}{*}Output{*}{bgcolor}
*Output Content*
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.
h4. {bgcolor:#FEECC4}{*}Examples{*}{bgcolor}
*Input*
Remove the alias named "testalias".
{code:borderStyle=solid|borderColor=#666666}
http://10.0.1.6:8983/solr/admin/collections?action=DELETEALIAS&name=testalias
{code}
*Output*
{code:borderStyle=solid|borderColor=#666666}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<lst name="responseHeader">
<int name="status">0</int>
<int name="QTime">117</int>
</lst>
</response>
{code}
{anchor:api6}
h2. Delete a Collection
{{/admin/collections?action=DELETE&name=_collection_}}
h4. {bgcolor:#FEECC4}{*}Input{*}{bgcolor}
*Query Parameters*
|| Key || Type || Required || Description ||
| name | string | Yes | The name of the collection to delete. |
h4. {bgcolor:#FEECC4}{*}Output{*}{bgcolor}
*Output Content*
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.
h4. {bgcolor:#FEECC4}{*}Examples{*}{bgcolor}
*Input*
Delete the collection named "newCollection".
{code:borderStyle=solid|borderColor=#666666}
http://10.0.1.6:8983/solr/admin/collections?action=DELETE&name=newCollection
{code}
*Output*
{code:borderStyle=solid|borderColor=#666666}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<lst name="responseHeader">
<int name="status">0</int>
<int name="QTime">603</int>
</lst>
<lst name="success">
<lst name="10.0.1.6:8983_solr">
<lst name="responseHeader">
<int name="status">0</int>
<int name="QTime">19</int>
</lst>
<str name="saved">/Applications/solr-4.3.0/example/solr/solr.xml</str>
</lst>
<lst name="10.0.1.4:8983_solr">
<lst name="responseHeader">
<int name="status">0</int>
<int name="QTime">67</int>
</lst>
<str name="saved">/Applications/solr-4.3.0/example/solr/solr.xml</str>
</lst>
</lst>
</response>
{code}
{scrollbar}
Stop watching space: https://cwiki.apache.org/confluence/users/removespacenotification.action?spaceKey=solr
Change email notification preferences: https://cwiki.apache.org/confluence/users/editmyemailsettings.action