This is an automated email from the ASF dual-hosted git repository. dsmiley pushed a commit to branch branch_10x in repository https://gitbox.apache.org/repos/asf/solr.git
commit 12d77e63d16cba6dbe5434a20c9687ef2f86cb3a Author: Eric Pugh <[email protected]> AuthorDate: Sat Oct 17 09:09:55 2026 -0400 Fix ref guide bugs: stale versions, broken tabs, dead references, duplicate examples (#5176) (cherry picked from commit 70aa8d75bd3e5ed7e3f817b9cea8e2a2ada2c06b) --- .../configuration-guide/pages/collections-api.adoc | 2 - .../pages/cluster-node-management.adoc | 28 +----------- .../deployment-guide/pages/enabling-ssl.adoc | 2 +- .../deployment-guide/pages/installing-solr.adoc | 8 +--- .../deployment-guide/pages/jvm-settings.adoc | 4 +- .../modules/deployment-guide/pages/node-roles.adoc | 13 ++---- .../pages/system-requirements.adoc | 18 ++++---- .../pages/user-managed-index-replication.adoc | 53 ++++++++++++---------- .../indexing-guide/pages/date-formatting-math.adoc | 3 -- .../modules/indexing-guide/pages/filters.adoc | 3 -- .../query-guide/pages/json-combined-query-dsl.adoc | 27 +++++++---- 11 files changed, 65 insertions(+), 96 deletions(-) diff --git a/solr/solr-ref-guide/modules/configuration-guide/pages/collections-api.adoc b/solr/solr-ref-guide/modules/configuration-guide/pages/collections-api.adoc index 57597e9b847..4d30104e067 100644 --- a/solr/solr-ref-guide/modules/configuration-guide/pages/collections-api.adoc +++ b/solr/solr-ref-guide/modules/configuration-guide/pages/collections-api.adoc @@ -45,8 +45,6 @@ However, there is a limit of 10,000 on the number of async call responses stored === Examples of Async Requests -*Input* - [tabs#asyncexample] ====== V1 API:: diff --git a/solr/solr-ref-guide/modules/deployment-guide/pages/cluster-node-management.adoc b/solr/solr-ref-guide/modules/deployment-guide/pages/cluster-node-management.adoc index 8028a4d7d5e..96177f17436 100644 --- a/solr/solr-ref-guide/modules/deployment-guide/pages/cluster-node-management.adoc +++ b/solr/solr-ref-guide/modules/deployment-guide/pages/cluster-node-management.adoc @@ -137,13 +137,6 @@ The response will include the status of the request and the status of the cluste === Examples using CLUSTERSTATUS -*Input* - -[source,text] ----- -http://localhost:8983/solr/admin/collections?action=CLUSTERSTATUS ----- - *Output* [source,json] @@ -436,13 +429,6 @@ curl http://localhost:8983/api/cluster/properties ==== ====== -*Input* - -[source,bash] ----- -curl http://localhost:8983/api/cluster/properties ----- - *Output* [source,json] @@ -480,13 +466,6 @@ curl http://localhost:8983/api/cluster/properties/urlScheme ==== ====== -*Input* - -[source,bash] ----- -curl http://localhost:8983/api/cluster/properties/urlScheme ----- - *Output* [source,json] @@ -1138,12 +1117,7 @@ curl http://localhost:8983/api/cluster/overseer === Examples using OVERSEERSTATUS -*Input:* - -[source,text] ----- -http://localhost:8983/solr/admin/collections?action=OVERSEERSTATUS ----- +*Output:* [source,json] ---- diff --git a/solr/solr-ref-guide/modules/deployment-guide/pages/enabling-ssl.adoc b/solr/solr-ref-guide/modules/deployment-guide/pages/enabling-ssl.adoc index 27b02b71415..97a52184ef9 100644 --- a/solr/solr-ref-guide/modules/deployment-guide/pages/enabling-ssl.adoc +++ b/solr/solr-ref-guide/modules/deployment-guide/pages/enabling-ssl.adoc @@ -319,7 +319,7 @@ curl -E solr-ssl.pem:secret --cacert solr-ssl.pem "https://localhost:8984/solr/m === Index a Document using CloudSolrClient From a java client using SolrJ, index a document. -In the code below, the `javax.net.ssl.*` system properties are set programmatically, but you could instead specify them on the java command line, as in the `post.jar` example above: +In the code below, the `javax.net.ssl.*` system properties are set programmatically, but you could instead specify them on the java command line, as in the `bin/solr post` example above: [source,java] ---- diff --git a/solr/solr-ref-guide/modules/deployment-guide/pages/installing-solr.adoc b/solr/solr-ref-guide/modules/deployment-guide/pages/installing-solr.adoc index 5808c53dbd7..ea296cc2712 100644 --- a/solr/solr-ref-guide/modules/deployment-guide/pages/installing-solr.adoc +++ b/solr/solr-ref-guide/modules/deployment-guide/pages/installing-solr.adoc @@ -84,9 +84,7 @@ This directory includes several important scripts that will make using Solr easi solr and solr.cmd::: This is xref:solr-control-script-reference.adoc[Solr's Control Script], also known as `bin/solr` (*nix) / `bin/solr.cmd` (Windows). This script is the preferred tool to start and stop Solr. -You can also create collections or cores, configure authentication, and work with configuration files when running in SolrCloud mode. - -post::: The xref:indexing-guide:post-command.adoc[], which provides a simple command line interface for POSTing content to Solr. +You can also create collections or cores, configure authentication, work with configuration files when running in SolrCloud mode, and xref:indexing-guide:post-command.adoc[post content to Solr] using the `bin/solr post` subcommand. solr.in.sh and solr.in.cmd::: These are property files for *nix and Windows systems, respectively. @@ -149,10 +147,6 @@ exampledocs:: This is a small set of simple CSV, XML, and JSON files that can be used with `bin/solr post` when first getting started with Solr. For more information about using `bin/solr post` with these files, see xref:indexing-guide:post-command.adoc[]. -files:: -The `files` directory provides a basic search UI for documents such as Word or PDF that you may have stored locally. -See the README there for details on how to use this example. - films:: The `films` directory includes a robust set of data about movies in three formats: CSV, XML, and JSON. See the README there for details on how to use this dataset. diff --git a/solr/solr-ref-guide/modules/deployment-guide/pages/jvm-settings.adoc b/solr/solr-ref-guide/modules/deployment-guide/pages/jvm-settings.adoc index 5c9dc071163..f943bfd1ceb 100644 --- a/solr/solr-ref-guide/modules/deployment-guide/pages/jvm-settings.adoc +++ b/solr/solr-ref-guide/modules/deployment-guide/pages/jvm-settings.adoc @@ -44,7 +44,7 @@ Therefore, as much memory as possible should be left for the operating system to * The heap allocated should be as small as possible while maintaining good performance. 8-16Gb is quite common, and larger heaps are sometimes used. When heaps grow to larger sizes, it is imperative to test extensively before going to production. -* The G1GC garbage collector is currently preferred when using a JVM that supports it (Java 9 and later). +* The G1GC garbage collector is currently preferred. * Modern hardware can be configured with hundreds of gigabytes of physical RAM and many CPUs. It is often better in these cases to run multiple JVMs, each with a limited amount of memory allocated to their heaps. One way to achieve this is to run Solr as a https://hub.docker.com/_/solr?tab=tags[Docker container]. @@ -52,7 +52,7 @@ One way to achieve this is to run Solr as a https://hub.docker.com/_/solr?tab=ta * Solr will run with an option that causes the JVM to crash on OutOfMemoryError exceptions. This will forcefully stop Solr when a system resource is exhausted rather than continue in an indeterminate state. You can additionally request a heap dump on OOME through the values in `solr.in.sh` -* All current (Java 11) garbage collectors can hit "stop the world" collections, which suspend the JVM until completed. +* All current garbage collectors can hit "stop the world" collections, which suspend the JVM until completed. If, through monitoring, these garbage collections are frequent and greater than your application can tolerate, additional tuning should be considered. "Stop the world" pauses greater than 5 seconds are rarely acceptable, and having them be less than 1 second is desirable. diff --git a/solr/solr-ref-guide/modules/deployment-guide/pages/node-roles.adoc b/solr/solr-ref-guide/modules/deployment-guide/pages/node-roles.adoc index ae4825a988a..1151f3c5c7c 100644 --- a/solr/solr-ref-guide/modules/deployment-guide/pages/node-roles.adoc +++ b/solr/solr-ref-guide/modules/deployment-guide/pages/node-roles.adoc @@ -106,7 +106,6 @@ Dedicated *`coordinator`* nodes can be provisioned with enough memory but very l Fetches the list of supported roles and their supported modes for this cluster. -*Input* [source,bash] ---- curl http://localhost:8983/api/cluster/node-roles/supported @@ -134,7 +133,6 @@ curl http://localhost:8983/api/cluster/node-roles/supported Fetches the current node roles assignment for all the nodes in the cluster. -*Input* [source,bash] ---- curl http://localhost:8983/api/cluster/node-roles @@ -162,10 +160,9 @@ curl http://localhost:8983/api/cluster/node-roles Fetches the current node roles assignment for a specified role. -*Input* -[source,text] +[source,bash] ---- -http://localhost:8983/api/cluster/node-roles/role/data +curl http://localhost:8983/api/cluster/node-roles/role/data ---- *Output* @@ -181,10 +178,9 @@ http://localhost:8983/api/cluster/node-roles/role/data } ---- -*Input* -[source,text] +[source,bash] ---- -http://localhost:8983/api/cluster/node-roles/role/data/off +curl http://localhost:8983/api/cluster/node-roles/role/data/off ---- *Output* @@ -205,7 +201,6 @@ http://localhost:8983/api/cluster/node-roles/role/data/off Fetches the current node roles assignment for the specified node. -*Input* [source,bash] ---- curl http://localhost:8983/api/cluster/node-roles/node/solr1:8983_solr diff --git a/solr/solr-ref-guide/modules/deployment-guide/pages/system-requirements.adoc b/solr/solr-ref-guide/modules/deployment-guide/pages/system-requirements.adoc index 7413835fde4..ca5645ebf83 100644 --- a/solr/solr-ref-guide/modules/deployment-guide/pages/system-requirements.adoc +++ b/solr/solr-ref-guide/modules/deployment-guide/pages/system-requirements.adoc @@ -33,9 +33,9 @@ At a command line, check your Java version like this: [source,console] ---- $ java -version -openjdk version "11.0.14.1" 2022-02-08 -OpenJDK Runtime Environment Temurin-11.0.14.1+1 (build 11.0.14.1+1) -OpenJDK 64-Bit Server VM Temurin-11.0.14.1+1 (build 11.0.14.1+1, mixed mode) +openjdk version "21.0.5" 2024-10-15 +OpenJDK Runtime Environment Temurin-21.0.5+11 (build 21.0.5+11) +OpenJDK 64-Bit Server VM Temurin-21.0.5+11 (build 21.0.5+11, mixed mode, sharing) ---- The exact output will vary, but you need to make sure you meet the minimum version requirement. @@ -48,7 +48,7 @@ To be sure, check the page https://cwiki.apache.org/confluence/display/LUCENE/Ja === Sources for Java Java is available from a number of providers. -The official Docker image for Solr uses the Temurin distribution of OpenJDK 17 from the https://adoptium.net/[Adoptium project]. +The official Docker image for Solr uses the Temurin distribution of OpenJDK 25 from the https://adoptium.net/[Adoptium project]. Solr regularly test with https://adoptium.net/temurin/releases[Temurin], https://jdk.java.net/[OpenJDK] and Oracle versions of Java. Some distributions are free, others have a cost, some provide security patches and support, others do not. We recommend you read the article https://medium.com/@javachampions/java-is-still-free-2-0-0-6b9aa8d6d244[Java is still free by Java Champions] to help you decide. @@ -78,9 +78,9 @@ For this reason, Java 17 is preferred when upgrading Java. Solr and Lucene run a continuous integration model, running automated unit and integration tests using several versions of Java. In addition, some organizations also maintain their own test infrastructure and feed their results back to the community. -Our continuous testing is against the two code lines under active development, Solr 9x and the future Solr 10.0: +Our continuous testing is against the two code lines under active development, Solr 10.x and the future Solr 11.0: -* Solr 9.x is the current stable release line and will have "point releases", i.e., 9.1, 9.2, etc., until Solr 10.0 is released. -** Solr 9.x is continuously tested against Java 11, 17, 21 and also newer versions. -* There is also development and testing with the future Solr 10.x release line. -* Solr 8.x and earlier release lines are not tested on a continuous basis. +* Solr 10.x is the current stable release line and will have "point releases", i.e., 10.1, 10.2, etc., until Solr 11.0 is released. +** Solr 10.x is continuously tested against Java 21 and also newer versions. +* There is also development and testing with the future Solr 11.x release line. +* Solr 9.x and earlier release lines are not tested on a continuous basis. diff --git a/solr/solr-ref-guide/modules/deployment-guide/pages/user-managed-index-replication.adoc b/solr/solr-ref-guide/modules/deployment-guide/pages/user-managed-index-replication.adoc index 259ce3d0430..60513c1470a 100644 --- a/solr/solr-ref-guide/modules/deployment-guide/pages/user-managed-index-replication.adoc +++ b/solr/solr-ref-guide/modules/deployment-guide/pages/user-managed-index-replication.adoc @@ -1,4 +1,5 @@ -= User-Managed Index Replication Index Replication += User-Managed Index Replication +:tabs-sync-option: // 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 @@ -378,25 +379,26 @@ http://{leaderHost}:{port}/solr/{coreName}/replication?command=disablereplicatio `indexversion`:: Return the version of the latest replicatable index on the specified leader or follower. + +[tabs#indexversion-request] +====== +V1 API:: ++ ==== -[.tab-label]*V1 API* - [source,bash] ---- http://{host}:{port}/solr/{coreName}/replication?command=indexversion - ---- ==== + +V2 API:: + ==== -[.tab-label]*V2 API* - [source,bash] ---- http://{host}:{port}/api/cores/{coreName}/replication/indexversion - ---- ==== +====== `fetchindex`:: Force the specified follower to fetch a copy of the index from its leader. @@ -434,52 +436,54 @@ http://{followerHost}:{port}/solr/{coreName}/replication?command=details `filelist`:: Retrieve a list of Lucene files present in the specified host's index. ++ +[tabs#filelist-request] +====== +V1 API:: + ==== -[.tab-label]*V1 API* - [source,bash] ---- http://{host}:{port}/solr/{coreName}/replication?command=filelist&generation={generationNumber} - ---- ==== + +V2 API:: + ==== -[.tab-label]*V2 API* - [source,bash] ---- http://{host}:{port}/api/cores/{coreName}/replication/files?generation={generationNumber} - ---- ==== +====== + You can discover the generation number of the index by running the `indexversion` command. `filecontent`:: Retrieve a stream of a specific file path of a core. ++ +[tabs#filecontent-request] +====== +V1 API:: + ==== -[.tab-label]*V1 API* - [source,bash] ---- http://{host}:{port}/solr/{coreName}/replication?command=filecontent&{directoryType}={filePath}&wt=filestream - ---- ==== + +V2 API:: + ==== -[.tab-label]*V2 API* - [source,bash] ---- http://{host}:{port}/api/cores/{coreName}/replication/files/{filePath}&dirType={directoryType} - ---- ==== +====== + Directory type is required for both V1 and V2 with these supported types: @@ -594,23 +598,26 @@ Use a small positive value (for example `2`) for production monitoring unless yo Use the health endpoint as follows: +[tabs#health-request] +====== +V1 API:: ++ ==== -[.tab-label]*V1 API* - [source,bash] ---- http://{followerHost}:{port}/solr/admin/info/health?maxGenerationLag={maxLag} ---- ==== +V2 API:: ++ ==== -[.tab-label]*V2 API* - [source,bash] ---- http://{followerHost}:{port}/api/node/health?maxGenerationLag={maxLag} ---- ==== +====== A healthy response looks like: diff --git a/solr/solr-ref-guide/modules/indexing-guide/pages/date-formatting-math.adoc b/solr/solr-ref-guide/modules/indexing-guide/pages/date-formatting-math.adoc index f7679b6584f..d56094a50d0 100644 --- a/solr/solr-ref-guide/modules/indexing-guide/pages/date-formatting-math.adoc +++ b/solr/solr-ref-guide/modules/indexing-guide/pages/date-formatting-math.adoc @@ -230,8 +230,6 @@ Let's add a date range field to the schema.xml, so that we could index the infor Next, we will add two restaurants to the index: -==== -[.tab-label]*JSON* [source,json] ---- [{ "id": "r01", @@ -248,7 +246,6 @@ Next, we will add two restaurants to the index: "[2016-02-07T12:00Z TO 2016-02-07T16:00Z]" ]} ] ---- -==== Each restaurant can have multiple opening hours in a single day, and the opening hours can be different on different days. diff --git a/solr/solr-ref-guide/modules/indexing-guide/pages/filters.adoc b/solr/solr-ref-guide/modules/indexing-guide/pages/filters.adoc index 4321ca83891..167fbb0acae 100644 --- a/solr/solr-ref-guide/modules/indexing-guide/pages/filters.adoc +++ b/solr/solr-ref-guide/modules/indexing-guide/pages/filters.adoc @@ -3286,8 +3286,6 @@ lion => panthera leo|0.9, simba|0.8, kimba|0.75 *Example:* -==== -[.tab-label]*With name* [source,xml] ---- <analyzer type="query"> @@ -3296,7 +3294,6 @@ lion => panthera leo|0.9, simba|0.8, kimba|0.75 <filter name="delimitedBoost"/> </analyzer> ---- -==== *In:* "lion" diff --git a/solr/solr-ref-guide/modules/query-guide/pages/json-combined-query-dsl.adoc b/solr/solr-ref-guide/modules/query-guide/pages/json-combined-query-dsl.adoc index 33f841cd2cc..ee56007dfea 100644 --- a/solr/solr-ref-guide/modules/query-guide/pages/json-combined-query-dsl.adoc +++ b/solr/solr-ref-guide/modules/query-guide/pages/json-combined-query-dsl.adoc @@ -30,9 +30,10 @@ This feature is currently unsupported for grouping and Cursors. This feature works in both Standalone and SolrCloud modes and always performs distributed search execution. In Standalone (user-managed) mode, shard URLs must be explicitly allow-listed using the *allowUrls* parameter, otherwise Solr returns HTTP 403. For example: -``` +[source,bash] +---- "-Dsolr.security.allow.urls=http://localhost:8983/solr/"; -``` +---- ==== @@ -40,18 +41,21 @@ In Standalone (user-managed) mode, shard URLs must be explicitly allow-listed us Combined Query Feature has a separate handler with class `solr.CombinedQuerySearchHandler` which can be configured as below: -``` +[source,xml] +---- <requestHandler name="/search" class="solr.CombinedQuerySearchHandler"> ..... </requestHandler> -``` +---- In addition, the `QueryComponent` has been extended to create a new `CombinedQueryComponent`, which must be declared as a search component: -``` + +[source,xml] +---- <searchComponent class="solr.CombinedQueryComponent" name="combined_query"> <int name="maxCombinerQueries">2</int> </searchComponent> -``` +---- The Search Component also accepts parameters as below: @@ -150,7 +154,9 @@ The class to implement the custom logic has to extend `org.apache.solr.handler.c The Combined Query Component definition takes the `combiners` parameter, where the custom class can be declared by specifying a name and the custom parameters required by the custom algorithm. Example of the Search Component as below: -``` + +[source,xml] +---- <searchComponent class="solr.CombinedQueryComponent" name="combined_query"> <int name="maxCombinerQueries">2</int> <lst name="combiners"> @@ -161,11 +167,12 @@ Example of the Search Component as below: </lst> </lst> </searchComponent> -``` +---- Then, when executing the combined query, the only thing that changes in the JSON query payload is the value specified in the `combiner.algorithm` parameter: -``` +[source,json] +---- ... "params": { "combiner": true, @@ -173,7 +180,7 @@ Then, when executing the combined query, the only thing that changes in the JSON "combiner.algorithm": "customAlgorithm" } ... -``` +---- In this case, `customAlgorithm` is specified which is the name defined in the configuration; the RRF-specific parameters do not need to be provided.
