lucene-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Cassandra Targett (Confluence)" <conflue...@apache.org>
Subject [CONF] Apache Solr Reference Guide > Collections API
Date Mon, 16 Sep 2013 19:19:00 GMT
Space: Apache Solr Reference Guide (https://cwiki.apache.org/confluence/display/solr)
Page: Collections API (https://cwiki.apache.org/confluence/display/solr/Collections+API)

Change Comment:
---------------------------------------------------------------------
small typo fixes

Edited by Cassandra Targett:
---------------------------------------------------------------------
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=CREATESHARD}}: [create|#api8] create a new shard
{{/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. The value can be either *implicit*
or *compositeId*. When using the 'implicit' router, the {{shards}} parameter is required.
When using the 'compositeId' router, the {{numShards}} parameter is required. | 
| numShards | integer | No | null | 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 | | 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 | 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, 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.

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:api8}
h2. Create a Shard
This is only applicable for collections which have the 'implicit' router. Use SPLITSHARD for
collections with the 'compositeId' router. A new shard with a name can be created for an existing
'implicit' collection.

{{/admin/collections?action=CREATEESHARD&shard=_shardName_&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 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}}.
|

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*
Create 'shard-z' for the "anImplicitCollection" collection.

{code:borderStyle=solid|borderColor=#666666}
http://10.0.1.6:8983/solr/admin/collections?action=CREATESHARD&collection=anImplicitCollection&shard=shard-z
{code}

*Output*

{code:borderStyle=solid|borderColor=#666666}
<response>
   <lst name="responseHeader">
      <int name="status">0</int>
      <int name="QTime">558</int>
   </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


    

Mime
View raw message