This is an automated email from the ASF dual-hosted git repository.
epugh pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/solr.git
The following commit(s) were added to refs/heads/main by this push:
new 91cbb6a343e SOLR-18469: Refine Implicit Request Handlers Ref Guide
page to show all the information a user needs, and not duplicate anything.
(#4928)
91cbb6a343e is described below
commit 91cbb6a343e4436d3b81cdcdf177f43e72c12720
Author: Serhiy Bzhezytskyy <[email protected]>
AuthorDate: Fri Oct 2 19:37:09 2026 +0300
SOLR-18469: Refine Implicit Request Handlers Ref Guide page to show all the
information a user needs, and not duplicate anything. (#4928)
Co-authored-by: Eric Pugh <[email protected]>
---
.../pages/configuration-files.adoc | 19 +
.../pages/implicit-requesthandlers.adoc | 595 ++++++++++++++++-----
.../pages/basic-authentication-plugin.adoc | 22 +-
.../modules/deployment-guide/pages/ping.adoc | 35 ++
4 files changed, 538 insertions(+), 133 deletions(-)
diff --git
a/solr/solr-ref-guide/modules/configuration-guide/pages/configuration-files.adoc
b/solr/solr-ref-guide/modules/configuration-guide/pages/configuration-files.adoc
index 43f47a2eb19..13ed2e03f32 100644
---
a/solr/solr-ref-guide/modules/configuration-guide/pages/configuration-files.adoc
+++
b/solr/solr-ref-guide/modules/configuration-guide/pages/configuration-files.adoc
@@ -105,3 +105,22 @@ Configuration files cannot be edited with this screen, so
a text editor of some
This screen is related to the
xref:indexing-guide:schema-browser-screen.adoc[], in that they both can display
information from the schema.
However, the Schema Browser provides a way to drill into the analysis chain
and displays linkages between field types, fields, and dynamic field rules.
+
+== Restricting File Access
+
+Both the Files Screen above and the `/admin/file` endpoint it's built on are
served by `ShowFileRequestHandler`, which by default exposes every file in
`${solr.home}/conf/`.
+
+To hide specific files, list them as `hidden` invariants in `solrconfig.xml` -
a bare `*` hides everything else, but patterns like `*.xml` are not supported,
only exact filenames:
+
+[source,xml]
+----
+<requestHandler name="/admin/file" class="solr.admin.ShowFileRequestHandler">
+ <lst name="invariants">
+ <str name="hidden">synonyms.txt</str>
+ <str name="hidden">anotherfile.txt</str>
+ <str name="hidden">*</str>
+ </lst>
+</requestHandler>
+----
+
+When fetching a file directly from the endpoint, use the `contentType`
parameter to override the returned `Content-Type`, e.g.
`solr/admin/file?file=schema.xml&contentType=text/plain`.
diff --git
a/solr/solr-ref-guide/modules/configuration-guide/pages/implicit-requesthandlers.adoc
b/solr/solr-ref-guide/modules/configuration-guide/pages/implicit-requesthandlers.adoc
index 6522beb7f10..0aad010ddc9 100644
---
a/solr/solr-ref-guide/modules/configuration-guide/pages/implicit-requesthandlers.adoc
+++
b/solr/solr-ref-guide/modules/configuration-guide/pages/implicit-requesthandlers.adoc
@@ -20,12 +20,15 @@
Solr ships with many out-of-the-box request handlers, which are called
implicit because they do not need to be configured in `solrconfig.xml` before
you are able to use them.
-These handlers have pre-defined default parameters, known as _paramsets_,
which can be modified if necessary.
+Each implicit handler ships with a named bundle of default, invariant, and
appended parameters - a _paramset_ - equivalent to the `<defaults>`,
`<invariants>`, and `<appends>` blocks you'd normally write into a
`<requestHandler>` definition in `solrconfig.xml`.
+Because implicit handlers have no entry in `solrconfig.xml` to edit directly,
their paramset (shown for each handler below, e.g. `_ADMIN_PING` for the Ping
handler) is the only way to override their parameters - see <<How to View
Implicit Handler Paramsets>> and <<How to Edit Implicit Handler Paramsets>>
below.
== Available Implicit Endpoints
NOTE: All endpoint paths listed below should be placed after Solr's host and
port (if a port is used) to construct a URL.
+NOTE: V2 paths that start with `api/collections/` exist only in SolrCloud
mode. In user-managed mode use the `api/cores/<core>/...` form of the same
endpoint.
+
=== Admin Handlers
Many of these handlers are used throughout the Admin UI to show information
about Solr.
@@ -34,83 +37,173 @@ Many of these handlers are used throughout the Admin UI to
show information abou
File:: Return content of files in `${solr.home}/conf/`.
This handler must have a collection name in the path to the endpoint.
+
-[cols="3*.",frame=none,grid=cols,options="header"]
-|===
-|API Endpoint |Class & Javadocs |Paramset
-|`solr/<collection>/admin/file`
|{solr-javadocs}/core/org/apache/solr/handler/admin/ShowFileRequestHandler.html[ShowFileRequestHandler]
|`_ADMIN_FILE`
-|===
+*Documentation*:
xref:configuration-files.adoc#restricting-file-access[Restricting File Access]
++
+[source,bash]
+----
+solr/<collection>/admin/file
+----
++
+Paramset: `_ADMIN_FILE`
-Health:: Report the health of the node, via the `api/node/health` endpoint
({solr-javadocs}/core/org/apache/solr/handler/admin/api/NodeHealth.html[NodeHealth]).
-See xref:deployment-guide:healthcheck.adoc[] for details, parameters, and
examples.
+Health:: Report the health of the node.
++
+*Documentation*: xref:deployment-guide:healthcheck.adoc[]
++
+[tabs#health-endpoint]
+======
+V1 API::
++
+====
+[source,bash]
+----
+solr/admin/info/health
+----
+====
+
+V2 API::
++
+====
+[source,bash]
+----
+api/node/health
+----
+====
+======
++
+Paramset: none
Logging:: Retrieve and modify registered loggers.
+
-[cols="3*.",frame=none,grid=cols,options="header"]
-|===
-|API Endpoints |Class & Javadocs |Paramset
-|v1: `solr/admin/info/logging`
+[tabs#logging-endpoint]
+======
+V1 API::
++
+====
+[source,bash]
+----
+solr/admin/info/logging
+----
+====
-v2: `api/node/logging`
|{solr-javadocs}/core/org/apache/solr/handler/admin/LoggingHandler.html[LoggingHandler]
|`_ADMIN_LOGGING`
-|===
+V2 API::
++
+====
+[source,bash]
+----
+api/node/logging/levels
+----
+====
+======
++
+The log messages kept in memory come from `solr/admin/info/logging?since=0` in
V1 and from `api/node/logging/messages?since=0` in V2.
+In the response, `history` is a document list with the messages under `docs`
in V1, and a plain array of messages in V2.
++
+Paramset: none
Luke:: Expose the internal Lucene index.
This handler must have a collection name in the path to the endpoint.
+
*Documentation*: xref:indexing-guide:luke-request-handler.adoc[]
+
-[cols="3*.",frame=none,grid=cols,options="header"]
-|===
-|API Endpoint |Class & Javadocs |Paramset
-|`solr/<collection>/admin/luke`
|{solr-javadocs}/core/org/apache/solr/handler/admin/LukeRequestHandler.html[LukeRequestHandler]
|`_ADMIN_LUKE`
-|===
+[source,bash]
+----
+solr/<collection>/admin/luke
+----
++
+Paramset: `_ADMIN_LUKE`
-Ping:: Health check.
+Ping:: Health check designed for use by a load balancer.
This handler must have a collection name in the path to the endpoint.
+
-CAUTION: `PingRequestHandler` is deprecated and will be removed in a future
release. Use the `Health` endpoint below instead.
+CAUTION: `PingRequestHandler` is deprecated and will be removed in a future
release. Use the `Health` endpoint above instead.
+
*Documentation*: xref:deployment-guide:ping.adoc[]
+
-[cols="3*.",frame=none,grid=cols,options="header"]
-|===
-|API Endpoint |Class & Javadocs |Paramset
-|`solr/<collection>/admin/ping`
|{solr-javadocs}/core/org/apache/solr/handler/PingRequestHandler.html[PingRequestHandler]
|`_ADMIN_PING`
-|===
+[source,bash]
+----
+solr/<collection>/admin/ping
+----
++
+Paramset: `_ADMIN_PING`
System Properties:: Return JRE system properties.
Secret values are redacted.
+
*Documentation*:
xref:deployment-guide:jvm-settings.adoc#java-properties-screen[Java Properties
Screen]
+
-[cols="3*.",frame=none,grid=cols,options="header"]
-|===
-|API Endpoints |Class & Javadocs |Paramset
-|v1: `solr/admin/info/properties`
+[tabs#properties-endpoint]
+======
+V1 API::
++
+====
+[source,bash]
+----
+solr/admin/info/properties
+----
-v2: `api/node/properties` |v1:
{solr-javadocs}/core/org/apache/solr/handler/admin/PropertiesRequestHandler.html[PropertiesRequestHandler]
+To fetch a single property, use a `name` query parameter:
-v2:
{solr-javadocs}/core/org/apache/solr/handler/admin/api/GetNodeProperties.html[GetNodeProperties]
|`_ADMIN_PROPERTIES`
-|===
+[source,bash]
+----
+solr/admin/info/properties?name=java.version
+----
+====
+
+V2 API::
+
-To fetch a single property, v1 uses a `name` query parameter
(`solr/admin/info/properties?name=java.version`) and v2 uses a path segment
(`api/node/properties/java.version`).
+====
+[source,bash]
+----
+api/node/properties
+----
+
+To fetch a single property, use a path segment:
+
+[source,bash]
+----
+api/node/properties/java.version
+----
+====
+======
++
+Paramset: none
Segments:: Return info on last commit generation Lucene index segments.
+
-[cols="3*.",frame=none,grid=cols,options="header"]
-|===
-|API Endpoint |Class & Javadocs |Paramset
-|`solr/<collection>/admin/segments`
|{solr-javadocs}/core/org/apache/solr/handler/admin/SegmentsInfoRequestHandler.html[SegmentsInfoRequestHandler]
|`_ADMIN_SEGMENTS`
-|===
+[tabs#segments-endpoint]
+======
+V1 API::
++
+====
+[source,bash]
+----
+solr/<collection>/admin/segments
+----
+====
+
+V2 API::
++
+====
+[source,bash]
+----
+api/cores/<core>/segments
+----
+====
+======
++
+Paramset: `_ADMIN_SEGMENTS`
Core Info:: Return core information.
+
*Documentation*: xref:core-info-handler.adoc[]
+
-[cols="3*.",frame=none,grid=cols,options="header"]
-|===
-|API Endpoints |Class & Javadocs |Paramset
-|v1:
`solr/<collection>/admin/info`|{solr-javadocs}/core/org/apache/solr/handler/admin/CoreInfoHandler.html[CoreInfoHandler]
|
-|===
+[source,bash]
+----
+solr/<collection>/admin/info
+----
++
+Paramset: `_ADMIN_CORE`
Threads:: Return info on all JVM threads.
+
@@ -159,33 +252,90 @@ The thread dump is an array of objects, each containing a
`"thread"` property:
====
======
+
-[cols="2*.",frame=none,grid=cols,options="header"]
-|===
-|Class & Javadocs |Paramset
-|{solr-javadocs}/core/org/apache/solr/handler/admin/ThreadDumpHandler.html[ThreadDumpHandler]
|`_ADMIN_THREADS`
-|===
+Paramset: none
=== Analysis Handlers
[horizontal]
Document Analysis:: Return a breakdown of the analysis process of the given
document.
+
-*Documentation*:
https://cwiki.apache.org/confluence/display/solr/AnalysisRequestHandler
+Expects a single content stream shaped like this, where every document
includes a field serving as the unique key (used to associate each analysis
breakdown back to its document):
+
-[cols="3*.",frame=none,grid=cols,options="header"]
-|===
-|API Endpoint |Class & Javadocs |Paramset
-|`solr/<collection>/analysis/document`
|{solr-javadocs}/core/org/apache/solr/handler/DocumentAnalysisRequestHandler.html[DocumentAnalysisRequestHandler]
|`_ANALYSIS_DOCUMENT`
-|===
+[source,xml]
+----
+<docs>
+ <doc>
+ <field name="id">1</field>
+ <field name="name">Running Analyzers</field>
+ </doc>
+ <doc>...</doc>
+ ...
+</docs>
+----
++
+[source,bash]
+----
+curl "http://localhost:8983/solr/<collection>/analysis/document" -H
"Content-type:text/xml" --data-binary @mydoc.xml
+----
++
+The response breaks each field down by analysis stage, alternating the
analyzer/filter class name with the tokens it produced (trimmed here for
brevity):
++
+[source,json]
+----
+{
+ "analysis": {
+ "1": {
+ "name": {
+ "index": {
+ "Running Analyzers": [
+ "org.apache.lucene.analysis.standard.StandardTokenizer",
+ [
+ {"text": "Running", "start": 0, "end": 7, "position": 1},
+ {"text": "Analyzers", "start": 8, "end": 17, "position": 2}
+ ],
+ "org.apache.lucene.analysis.core.LowerCaseFilter",
+ [
+ {"text": "running", "start": 0, "end": 7, "position": 1},
+ {"text": "analyzers", "start": 8, "end": 17, "position": 2}
+ ]
+ ]
+ }
+ }
+ }
+ }
+}
+----
++
+Also supports query-time analysis via an `analysis.query` or `q` parameter,
plus `analysis.showmatch=true` to mark matching field tokens with `"match":
true`.
++
+[source,bash]
+----
+solr/<collection>/analysis/document
+----
++
+Paramset: `_ANALYSIS_DOCUMENT`
Field Analysis:: Return index- and query-time analysis over the given
field(s)/field type(s).
This handler drives the xref:indexing-guide:analysis-screen.adoc[] in Solr's
Admin UI.
+
-[cols="3*.",frame=none,grid=cols,options="header"]
+[cols="2*.",frame=none,grid=cols,options="header"]
|===
-|API Endpoint |Class & Javadocs |Paramset
-|`solr/<collection>/analysis/field`
|{solr-javadocs}/core/org/apache/solr/handler/FieldAnalysisRequestHandler.html[FieldAnalysisRequestHandler]
|`_ANALYSIS_FIELD`
+|Parameter |Description
+|`analysis.fieldname` |Analyze based on this field's type. Accepts a
comma-separated list.
+|`analysis.fieldtype` |Analyze based on this field type. Accepts a
comma-separated list.
+|`analysis.fieldvalue` |Text to analyze, mimicking index-time analysis.
+|`analysis.query` / `q` |Text to analyze, mimicking query-time analysis.
`analysis.query` takes precedence over `q`.
+|`analysis.showmatch` |When `true` and query analysis is performed, marks
field-value tokens that match the query's tokens.
|===
++
+If neither `analysis.fieldname` nor `analysis.fieldtype` is given, the default
search field's analyzer is used; one of `analysis.fieldvalue`,
`analysis.query`, or `q` is required.
++
+[source,bash]
+----
+solr/<collection>/analysis/field
+----
++
+Paramset: `_ANALYSIS_FIELD`
=== Handlers for Configuration
@@ -194,42 +344,79 @@ Config API:: Retrieve and modify Solr configuration.
+
*Documentation*: xref:config-api.adoc[]
+
-[cols="3*.",frame=none,grid=cols,options="header"]
-|===
-|API Endpoint |Class & Javadocs |Paramset
-|v1: `solr/<collection>/config`
+[tabs#config-endpoint]
+======
+V1 API::
++
+====
+[source,bash]
+----
+solr/<collection>/config
+----
+====
-v2: `api/collections/<collection>/config`
|{solr-javadocs}/core/org/apache/solr/handler/SolrConfigHandler.html[SolrConfigHandler]
|`_CONFIG`
-|===
+V2 API::
++
+====
+[source,bash]
+----
+api/collections/<collection>/config
+----
+====
+======
++
+Paramset: `_CONFIG`
Dump:: Echo the request contents back to the client.
+This handler must have a collection name in the path to the endpoint.
+
-[cols="3*.",frame=none,grid=cols,options="header"]
-|===
-|API Endpoint |Class & Javadocs |Paramset
-|`solr/debug/dump`
|{solr-javadocs}/core/org/apache/solr/handler/DumpRequestHandler.html[DumpRequestHandler]
|`_DEBUG_DUMP`
-|===
+[source,bash]
+----
+solr/<collection>/debug/dump
+----
++
+Paramset: `_DEBUG_DUMP`
Replication:: Replicate indexes for SolrCloud recovery and user-managed
cluster index distribution.
This handler must have a core name in the path to the endpoint.
+
-[cols="3*.",frame=none,grid=cols,options="header"]
-|===
-|API Endpoint |Class & Javadocs |Paramset
-|`solr/<core>/replication`
|{solr-javadocs}/core/org/apache/solr/handler/ReplicationHandler.html[ReplicationHandler]
|`_REPLICATION`
-|===
+*Documentation*: xref:deployment-guide:user-managed-index-replication.adoc[]
++
+[source,bash]
+----
+solr/<core>/replication
+----
++
+Paramset: `_REPLICATION`
Schema API:: Retrieve and modify the Solr schema.
+
*Documentation*: xref:indexing-guide:schema-api.adoc[]
+
-[cols="3*.",frame=none,grid=cols,options="header"]
-|===
-|API Endpoint |Class & Javadocs |Paramset
-|v1: `solr/<collection>/schema`, `solr/<core>/schema`
+[tabs#schema-endpoint]
+======
+V1 API::
++
+====
+[source,bash]
+----
+solr/<collection>/schema
+solr/<core>/schema
+----
+====
-v2: `api/collections/<collection>/schema`, `api/cores/<core>/schema`
|{solr-javadocs}/core/org/apache/solr/handler/SchemaHandler.html[SchemaHandler]
|`_SCHEMA`
-|===
+V2 API::
++
+====
+[source,bash]
+----
+api/collections/<collection>/schema
+api/cores/<core>/schema
+----
+====
+======
++
+Paramset: `_SCHEMA`
=== Query Handlers
@@ -238,61 +425,141 @@ Export:: Export full sorted result sets.
+
*Documentation*: xref:query-guide:exporting-result-sets.adoc[]
+
-[cols="3*.",frame=none,grid=cols,options="header"]
-|===
-|API Endpoint |Class & Javadocs |Paramset
-|`solr/<collection>/export`
|{solr-javadocs}/core/org/apache/solr/handler/ExportHandler.html[ExportHandler]
|`_EXPORT`
-|===
+[source,bash]
+----
+solr/<collection>/export
+----
++
+Paramset: `_EXPORT`
RealTimeGet:: Low-latency retrieval of the latest version of a document.
+
*Documentation*: xref:realtime-get.adoc[]
+
-[cols="3*.",frame=none,grid=cols,options="header"]
-|===
-|API Endpoint |Class & Javadocs |Paramset
-|`solr/<collection>/get`
|{solr-javadocs}/core/org/apache/solr/handler/RealTimeGetHandler.html[RealTimeGetHandler]
|`_GET`
-|===
+[tabs#realtime-get-endpoint]
+======
+V1 API::
++
+====
+[source,bash]
+----
+solr/<collection>/get
+----
+====
+
+V2 API::
++
+====
+[source,bash]
+----
+api/collections/<collection>/get
+----
+====
+======
++
+Paramset: `_GET`
Graph Traversal:: Return http://graphml.graphdrawing.org/[GraphML] formatted
output from a `gatherNodes` streaming expression.
+
*Documentation*: xref:query-guide:graph-traversal.adoc[]
+
-[cols="3*.",frame=none,grid=cols,options="header"]
-|===
-|API Endpoint |Class & Javadocs |Paramset
-|`solr/<collection>/graph`
|{solr-javadocs}/core/org/apache/solr/handler/GraphHandler.html[GraphHandler]
|`_ADMIN_GRAPH`
-|===
+[source,bash]
+----
+solr/<collection>/graph
+----
++
+Paramset: `_ADMIN_GRAPH`
SQL:: SQL query support.
+
+This handler is part of the `sql` xref:solr-modules.adoc[Solr Module], which
must be enabled before the endpoint responds.
++
*Documentation*: xref:query-guide:sql-query.adoc#sql-request-handler[SQL
Request Handler]
+
-[cols="3*.",frame=none,grid=cols,options="header"]
-|===
-|API Endpoint |Class & Javadocs |Paramset
-|`solr/<collection>/sql`
|{solr-javadocs}/modules/sql/org/apache/solr/handler/sql/SQLHandler.html[SQLHandler]
|`_SQL`
-|===
+[source,bash]
+----
+solr/<collection>/sql
+----
++
+Paramset: `_SQL`
Streaming Expressions:: Distributed stream processing.
+
*Documentation*:
xref:query-guide:streaming-expressions.adoc#streaming-requests-and-responses[Streaming
Requests and Responses]
+
-[cols="3*.",frame=none,grid=cols,options="header"]
-|===
-|API Endpoint |Class & Javadocs |Paramset
-|`solr/<collection>/stream`
|{solr-javadocs}/core/org/apache/solr/handler/StreamHandler.html[StreamHandler]
|`_STREAM`
-|===
+[source,bash]
+----
+solr/<collection>/stream
+----
++
+Paramset: `_STREAM`
Terms:: Return a field's indexed terms and the number of documents containing
each term.
+
*Documentation*:
xref:query-guide:terms-component.adoc#using-the-terms-component-in-a-request-handler[Using
the Terms Component in a Request Handler]
+
-[cols="3*.",frame=none,grid=cols,options="header"]
-|===
-|API Endpoint |Class & Javadocs |Paramset
-|`solr/<collection>/terms`
|{solr-javadocs}/core/org/apache/solr/handler/component/SearchHandler.html[SearchHandler]
|`_TERMS`
-|===
+[source,bash]
+----
+solr/<collection>/terms
+----
++
+Paramset: `_TERMS`
+
+Task List:: List the active cancellable tasks, or check whether one task is
still active.
+This handler must have a collection name in the path to the endpoint.
++
+*Documentation*: xref:deployment-guide:task-management.adoc[]
++
+[tabs#task-list-endpoint]
+======
+V1 API::
++
+====
+[source,bash]
+----
+solr/<collection>/tasks/list
+----
+====
+
+V2 API::
++
+====
+[source,bash]
+----
+api/collections/<collection>/tasks
+----
+====
+======
++
+Paramset: `_LIST_TASKS`
+
+Task Cancellation:: Cancel an active task by its ID.
+This handler must have a collection name in the path to the endpoint.
++
+*Documentation*: xref:deployment-guide:task-management.adoc[]
++
+[tabs#task-cancel-endpoint]
+======
+V1 API::
++
+====
+[source,bash]
+----
+solr/<collection>/tasks/cancel
+----
+====
+
+V2 API::
++
+====
+[source,bash]
+----
+api/collections/<collection>/tasks/<task_id>
+----
+====
+======
++
+Paramset: `_TASK_CANCELLATION`
=== Update Handlers
@@ -301,41 +568,106 @@ Update:: Add, delete and update indexed documents
formatted as SolrXML, CSV, Sol
+
*Documentation*: xref:indexing-guide:indexing-with-update-handlers.adoc[]
+
-[cols="3*.",frame=none,grid=cols,options="header"]
-|===
-|API Endpoint |Class & Javadocs |Paramset
-|`solr/<collection>/update`
|{solr-javadocs}/core/org/apache/solr/handler/UpdateRequestHandler.html[UpdateRequestHandler]
|`_UPDATE`
-|===
+[tabs#update-endpoint]
+======
+V1 API::
++
+====
+[source,bash]
+----
+solr/<collection>/update
+----
+====
+
+V2 API::
++
+====
+[source,bash]
+----
+api/collections/<collection>/update
+----
+====
+======
++
+Paramset: `_UPDATE`
CSV Updates:: Add and update CSV-formatted documents.
+
*Documentation*:
xref:indexing-guide:indexing-with-update-handlers.adoc#csv-update-convenience-paths[CSV
Update Convenience Paths]
+
-[cols="3*.",frame=none,grid=cols,options="header"]
-|===
-|API Endpoint |Class & Javadocs |Paramset
-|`solr/<collection>/update/csv`
|{solr-javadocs}/core/org/apache/solr/handler/UpdateRequestHandler.html[UpdateRequestHandler]
|`_UPDATE_CSV`
-|===
+[tabs#csv-update-endpoint]
+======
+V1 API::
++
+====
+[source,bash]
+----
+solr/<collection>/update/csv
+----
+====
+
+V2 API::
++
+====
+[source,bash]
+----
+api/collections/<collection>/update/csv
+----
+====
+======
++
+Paramset: `_UPDATE_CSV`
JSON Updates:: Add, delete and update SolrJSON-formatted documents.
+
*Documentation*:
xref:indexing-guide:indexing-with-update-handlers.adoc#json-update-convenience-paths[JSON
Update Convenience Paths]
+
-[cols="3*.",frame=none,grid=cols,options="header"]
-|===
-|API Endpoint |Class & Javadocs |Paramset
-|`solr/<collection>/update/json`
|{solr-javadocs}/core/org/apache/solr/handler/UpdateRequestHandler.html[UpdateRequestHandler]
|`_UPDATE_JSON`
-|===
+[tabs#json-update-endpoint]
+======
+V1 API::
++
+====
+[source,bash]
+----
+solr/<collection>/update/json
+----
+====
+
+V2 API::
++
+====
+[source,bash]
+----
+api/collections/<collection>/update/json
+----
+====
+======
++
+Paramset: `_UPDATE_JSON`
Custom JSON Updates:: Add and update custom JSON-formatted documents.
+
*Documentation*:
xref:indexing-guide:transforming-and-indexing-custom-json.adoc[]
+
-[cols="3*.",frame=none,grid=cols,options="header"]
-|===
-|API Endpoint |Class & Javadocs |Paramset
-|`solr/<collection>/update/json/docs`
|{solr-javadocs}/core/org/apache/solr/handler/UpdateRequestHandler.html[UpdateRequestHandler]
|`_UPDATE_JSON_DOCS`
-|===
+Both the v2 `/update` and `/update/json` endpoints above are internally
rewritten to this path, which is why it has no distinct v2 endpoint of its own.
++
+[source,bash]
+----
+solr/<collection>/update/json/docs
+----
++
+Paramset: `_UPDATE_JSON_DOCS`
+
+CBOR Updates:: Add and update CBOR-formatted documents.
++
+*Documentation*: xref:indexing-guide:indexing-with-cbor.adoc[]
++
+[source,bash]
+----
+solr/<collection>/update/cbor
+----
++
+Paramset: `_UPDATE_CBOR`
== How to View Implicit Handler Paramsets
@@ -402,7 +734,8 @@ The response will look similar to:
== How to Edit Implicit Handler Paramsets
-Because implicit request handlers are not present in `solrconfig.xml`,
configuration of their associated `default`, `invariant` and `appends`
parameters may be edited via the xref:request-parameters-api.adoc[] using the
paramset listed in the above table.
+Because implicit request handlers are not present in `solrconfig.xml`,
configuration of their associated `default`, `invariant` and `appends`
parameters may be edited via the xref:request-parameters-api.adoc[] using the
Paramset listed in each handler's entry above.
+See xref:request-parameters-api.adoc#the-useparams-parameter[The useParams
Parameter] to override a paramset at request time instead of editing it.
However, other parameters, including SearchHandler components, may not be
modified.
The invariants and appends specified in the implicit configuration cannot be
overridden.
diff --git
a/solr/solr-ref-guide/modules/deployment-guide/pages/basic-authentication-plugin.adoc
b/solr/solr-ref-guide/modules/deployment-guide/pages/basic-authentication-plugin.adoc
index 9f1a062feb6..b3cce8cfd39 100644
---
a/solr/solr-ref-guide/modules/deployment-guide/pages/basic-authentication-plugin.adoc
+++
b/solr/solr-ref-guide/modules/deployment-guide/pages/basic-authentication-plugin.adoc
@@ -177,8 +177,26 @@ The API provides an endpoint with specific commands to set
user details or delet
=== API Entry Point
-* v1: `\http://localhost:8983/solr/admin/authentication`
-* v2: `\http://localhost:8983/api/cluster/security/authentication`
+[tabs#authentication-entry-point]
+======
+V1 API::
++
+====
+[source,bash]
+----
+http://localhost:8983/solr/admin/authentication
+----
+====
+
+V2 API::
++
+====
+[source,bash]
+----
+http://localhost:8983/api/cluster/security/authentication
+----
+====
+======
This endpoint is not collection-specific, so users are created for the entire
Solr cluster.
If users need to be restricted to a specific collection, that can be done with
the authorization rules.
diff --git a/solr/solr-ref-guide/modules/deployment-guide/pages/ping.adoc
b/solr/solr-ref-guide/modules/deployment-guide/pages/ping.adoc
index 558dddac292..5edd0ae4efc 100644
--- a/solr/solr-ref-guide/modules/deployment-guide/pages/ping.adoc
+++ b/solr/solr-ref-guide/modules/deployment-guide/pages/ping.adoc
@@ -30,6 +30,41 @@ image::ping/ping.png[image,width=171,height=195]
The search executed by a Ping is configured with the
xref:configuration-guide:request-parameters-api.adoc[].
See xref:configuration-guide:implicit-requesthandlers.adoc[] for the paramset
to use for the `/admin/ping` endpoint.
+== Configuring Ping
+
+`PingRequestHandler` delegates to a configured query, set via `qt`/`q`
invariants, and responds `OK` if that query succeeds, or with the delegated
handler's error if it doesn't:
+
+[source,xml]
+----
+<requestHandler name="/admin/ping" class="solr.PingRequestHandler">
+ <lst name="invariants">
+ <str name="qt">/search</str> <!-- handler to delegate to -->
+ <str name="q">some test query</str>
+ </lst>
+</requestHandler>
+----
+
+You can also configure a `healthcheckFile` to enable or disable the handler
independent of whether Solr itself is healthy - useful for pulling a node out
of load balancer rotation for maintenance:
+
+[source,xml]
+----
+<requestHandler name="/admin/ping" class="solr.PingRequestHandler">
+ <!-- relative paths are resolved against the data dir -->
+ <str name="healthcheckFile">server-enabled.txt</str>
+ <lst name="invariants">
+ <str name="qt">/search</str>
+ </lst>
+</requestHandler>
+----
+
+With `healthcheckFile` configured, an `action` request parameter controls it:
+
+* `action=enable` - creates the health check file if it doesn't already exist
+* `action=disable` - deletes the health check file if it exists
+* `action=status` - reports `enabled`, `disabled`, or `not_configured`
+
+If the file is configured but missing, Ping returns an HTTP error even if the
server is otherwise healthy.
+
The Ping option doesn't open a page, but the status of the request can be seen
on the core overview page shown when clicking on a collection name.
The length of time the request has taken is displayed next to the Ping option,
in milliseconds.
