You are viewing a plain text version of this content. The canonical link for it is here.
Posted to issues@lucene.apache.org by GitBox <gi...@apache.org> on 2021/02/20 03:31:33 UTC
[GitHub] [lucene-solr] gerlowskija commented on a change in pull request #2401: SOLR-11646: Add v2 examples for collections API
gerlowskija commented on a change in pull request #2401:
URL: https://github.com/apache/lucene-solr/pull/2401#discussion_r579481691
##########
File path: solr/solr-ref-guide/src/collection-management.adoc
##########
@@ -22,7 +22,42 @@ A collection is a single logical index that uses a single Solr configuration fil
[[create]]
== CREATE: Create a Collection
-`/admin/collections?action=CREATE&name=_name_`
+The CREATE action is used to create new collection of data.
+
+[.dynamic-tabs]
+--
+[example.tab-pane#v1createcollection]
+====
+[.tab-label]*V1 API*
+
+With the v1 API, the `create` command must be capitalized as `CREATE`:
+
+[source,bash]
+----
+http://localhost:8983/solr/admin/collections?action=CREATE&name=newCollection
+
+----
+====
+
+[example.tab-pane#v2createcollection]
+====
+[.tab-label]*V2 API*
+
+With the v2 API, the `create` command is provided as part of the JSON data that contains the required parameters:
+
+[source,bash]
+----
+curl -X POST http://localhost:8983/api/collections?omitHeader=true -H 'Content-Type: application/json' -d'
+ {
+ "create": {
+ "name": "newCollection",
+ "numShards": 1
Review comment:
[0] This is small potatoes, but should we pass the same parameters in the v2 request and v1 requests, so that they're equivalent to one another?
##########
File path: solr/solr-ref-guide/src/collection-management.adoc
##########
@@ -156,14 +191,62 @@ http://localhost:8983/solr/admin/collections?action=CREATE&name=newCollection&nu
[[reload]]
== RELOAD: Reload a Collection
-`/admin/collections?action=RELOAD&name=_name_`
+The RELOAD action is used when you have changed a configuration file in ZooKeeper, like uploading a new `schema.xml`.
+Solr automatically reloads collections when certain files, monitored via a watch in ZooKeeper are changed,
+such as `security.json`. However, for changes to files in configsets, like uploading a new `schema.xml`, you
+will need to manually trigger the RELOAD.
+
+[.dynamic-tabs]
+--
+[example.tab-pane#v1reloadcollection]
+====
+[.tab-label]*V1 API*
+
+With the v1 API, the `reload` command must be capitalized as `RELOAD`:
Review comment:
Is this true? lower-case "reload" appears to work for me on master:
```
➜ solr-9.0.0-SNAPSHOT git:(master) curl -ilk -X GET "http://localhost:8983/solr/admin/collections?action=reload&name=foo"
HTTP/1.1 200 OK
...
{
"responseHeader":{
"status":0,
"QTime":486},
"success":{
"localhost:8983_solr":{
"responseHeader":{
"status":0,
"QTime":447}}}}
```
##########
File path: solr/solr-ref-guide/src/collection-management.adoc
##########
@@ -264,16 +381,33 @@ processing of updates and reloads the collection.
Fetch the names of the collections in the cluster.
-`/admin/collections?action=LIST`
-
-=== Examples using LIST
+[.dynamic-tabs]
+--
+[example.tab-pane#v1listcollection]
+====
+[.tab-label]*V1 API*
-*Input*
+With the v1 API, the `list` command must be capitalized as `LIST`:
Review comment:
Is this true? Lowercase works for me on master...
```
➜ solr-9.0.0-SNAPSHOT git:(master) curl -k -X GET "http://localhost:8983/solr/admin/collections?action=list"
{
"responseHeader":{
"status":0,
"QTime":0},
"collections":["foo"]}
```
##########
File path: solr/solr-ref-guide/src/collection-management.adoc
##########
@@ -350,31 +506,46 @@ update commands, which are directed now to `collection2`.
[[delete]]
== DELETE: Delete a Collection
-`/admin/collections?action=DELETE&name=_collection_`
+The DELETE action is used to delete a collection.
+
+[.dynamic-tabs]
+--
+[example.tab-pane#v1deletecollection]
+====
+[.tab-label]*V1 API*
+
+With the v1 API, the `delete` command must be capitalized as `DELETE`:
Review comment:
Is this true? Lowercase works for me on master:
```
➜ solr-9.0.0-SNAPSHOT git:(master) curl -k -X GET "http://localhost:8983/solr/admin/collections?action=delete&name=baz"
{
"responseHeader":{
"status":0,
"QTime":528},
"success":{
"localhost:8983_solr":{
"responseHeader":{
"status":0,
"QTime":288}}}}
```
##########
File path: solr/solr-ref-guide/src/collection-management.adoc
##########
@@ -350,31 +506,46 @@ update commands, which are directed now to `collection2`.
[[delete]]
== DELETE: Delete a Collection
-`/admin/collections?action=DELETE&name=_collection_`
+The DELETE action is used to delete a collection.
+
+[.dynamic-tabs]
+--
+[example.tab-pane#v1deletecollection]
+====
+[.tab-label]*V1 API*
+
+With the v1 API, the `delete` command must be capitalized as `DELETE`:
+
+[source,bash]
+----
+http://localhost:8983/solr/admin/collections?action=DELETE&name=newCollection
+----
+====
+
+[example.tab-pane#v2deletecollection]
+====
+[.tab-label]*V2 API*
+
+
+[source,bash]
+----
+curl -X DELETE http://localhost:8983/api/collections/newCollection?omitHeader=true
+----
+====
+--
=== DELETE Parameters
`name`::
The name of the collection to delete. This parameter is required.
`async`::
-Request ID to track this action which will be <<collections-api.adoc#asynchronous-calls,processed asynchronously>>.
+Request ID to track this action which will be <<collections-api.adoc#asynchronous-calls,processed asynchronously>> and is a V1 API only parameter.
Review comment:
I wonder if this was done intentionally or is just something that Noble or whoever forgot to put in the apispec file. It's a real shame to have to document stuff that's almost surely just accidental oversight. 🤷
But I respect that you don't want to bundle in any actual API changes to this PR.
##########
File path: solr/solr-ref-guide/src/collection-management.adoc
##########
@@ -210,12 +293,46 @@ http://localhost:8983/solr/admin/collections?action=RELOAD&name=newCollection&wt
[[modifycollection]]
== MODIFYCOLLECTION: Modify Attributes of a Collection
-`/admin/collections?action=MODIFYCOLLECTION&collection=_<collection-name>_&__<attribute-name>__=__<attribute-value>__&__<another-attribute-name>__=__<another-value>__&__<yet_another_attribute_name>__=`
-
-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.
+It's possible to edit multiple attributes at a time. Changing these values only updates the znode 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.
An attribute can be deleted by passing an empty value. For example, `yet_another_attribute_name=` (with no value) will delete the `yet_another_attribute_name` parameter from the collection.
+[.dynamic-tabs]
+--
+[example.tab-pane#v1modifycollection]
+====
+[.tab-label]*V1 API*
+
+With the v1 API, the `modifycollection` command must be capitalized as `MODIFYCOLLECTION`:
+
+[source,bash]
+----
+http://localhost:8983/solr/admin/collections?action=MODIFYCOLLECTION&collection=newCollection&<attribute-name>=<attribute-value>&<another-attribute-name>=<another-value>&<yet_another_attribute_name>=
+
+----
+====
+
+[example.tab-pane#v2modifycollection]
+====
+[.tab-label]*V2 API*
+
+With the v2 API, the `modify` command is provided as part of the JSON data that contains the required parameters:
+
+[source,bash]
+----
+curl -X POST http://localhost:8983/api/collections/newCollection?omitHeader=true -H 'Content-Type: application/json' -d'
+ {
+ "modify": {
+ "replicationFactor": 2
Review comment:
[0] ditto re: my comment above about the v1 and v2 requests being as equivalent as possible
##########
File path: solr/solr-ref-guide/src/collection-management.adoc
##########
@@ -309,6 +441,30 @@ Aliases that refer to more than 1 collection are not supported.
* the existing name must not be a Routed Alias.
* the target name must not be an existing alias.
+[.dynamic-tabs]
+--
+[example.tab-pane#v1renamecollection]
+====
+[.tab-label]*V1 API*
+
+With the v1 API, the `rename` command must be capitalized as `RENAME`:
Review comment:
I don't think this is true? Lowercase works for me on master...
```
➜ solr-9.0.0-SNAPSHOT git:(master) curl -k -X GET "http://localhost:8983/solr/admin/collections?action=rename&name=foo&target=bar"
{
"responseHeader":{
"status":0,
"QTime":81}}
```
##########
File path: solr/solr-ref-guide/src/collection-management.adoc
##########
@@ -350,31 +506,46 @@ update commands, which are directed now to `collection2`.
[[delete]]
== DELETE: Delete a Collection
-`/admin/collections?action=DELETE&name=_collection_`
+The DELETE action is used to delete a collection.
+
+[.dynamic-tabs]
+--
+[example.tab-pane#v1deletecollection]
+====
+[.tab-label]*V1 API*
+
+With the v1 API, the `delete` command must be capitalized as `DELETE`:
+
+[source,bash]
+----
+http://localhost:8983/solr/admin/collections?action=DELETE&name=newCollection
Review comment:
> name=newCollection
This is a real nitpick, there's not much danger of confusion here idt. But the collection name `newCollection` might confuse readers, as this API call has nothing to do with creating new collections.
##########
File path: solr/solr-ref-guide/src/collection-management.adoc
##########
@@ -264,16 +381,33 @@ processing of updates and reloads the collection.
Fetch the names of the collections in the cluster.
-`/admin/collections?action=LIST`
-
-=== Examples using LIST
+[.dynamic-tabs]
+--
+[example.tab-pane#v1listcollection]
+====
+[.tab-label]*V1 API*
-*Input*
+With the v1 API, the `list` command must be capitalized as `LIST`:
-[source,text]
+[source,bash]
----
http://localhost:8983/solr/admin/collections?action=LIST
----
+====
+
+[example.tab-pane#v2listcollection]
+====
+[.tab-label]*V2 API*
+
+With the v2 API, the `modify` command is provided as part of the JSON data that contains the required parameters:
Review comment:
> the `modify` command
Copy/paste error maybe?
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@lucene.apache.org
For additional commands, e-mail: issues-help@lucene.apache.org