You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@lucene.apache.org by is...@apache.org on 2017/07/29 21:59:45 UTC
[08/28] lucene-solr:jira/solr-6630: Merging master
http://git-wip-us.apache.org/repos/asf/lucene-solr/blob/8d00e53b/solr/solr-ref-guide/src/meta-docs/pdf.adoc
----------------------------------------------------------------------
diff --git a/solr/solr-ref-guide/src/meta-docs/pdf.adoc b/solr/solr-ref-guide/src/meta-docs/pdf.adoc
new file mode 100644
index 0000000..9c5cc7f
--- /dev/null
+++ b/solr/solr-ref-guide/src/meta-docs/pdf.adoc
@@ -0,0 +1,145 @@
+= Making Changes to the PDF Version
+// 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
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+The main published artifact of the Solr Reference Guide is a PDF document.
+
+The PDF version of the Ref Guide uses `asciidoctor-pdf` (indirectly) to convert the `.adoc` files to PDF.
+
+In order for all of the various files to be converted into a single, large, PDF file, another `.adoc` file must be created.
+
+== About asciidoctor-pdf
+
+Our PDF build process uses the https://github.com/asciidoctor/asciidoctor-ant[`asciidoctor-ant`] project to integrate Asciidoctor.
+
+The `asciidoctor-ant` project is really an Ant wrapper around https://github.com/asciidoctor/asciidoctorj[`asciidoctorj`]. This is a Java binding of several Asciidoctor projects that produces a .jar that includes Asciidoctor, Asciidoctor PDF and Asciidoctor EPub.
+
+Since it is a binding for the Ruby implementations of these three projects, they each work the same way they would if we were using the Ruby versions.
+
+== Configuring the PDF Theme
+
+Nearly all of the styling and layout of the PDF is controlled by a single YAML file that is called a theme.
+
+See the section <<Modifying the Theme>> for information on how to update the theme.
+
+=== Declaring the Theme to Use
+
+Our theme is `refguide-theme.yml`, found in `solr/solr-ref-guide/pdf/themes`.
+
+New themes must be named to include `-theme.yml` at the end. They must also be in proper YAML format.
+
+The theme to use when generating the PDF is defined with the `pdf-style` attribute. Only the first part of the file name is used. So, a theme file named `refguide-theme.yml` is selected by defining `pdf-style=refguide`.
+
+In the section <<Asciidoctor PDF Attributes>> below, we can see how we've declared this in our Ant target.
+
+=== Modifying the Theme
+
+All of the styling capabilities are described in the https://github.com/asciidoctor/asciidoctor-pdf/blob/master/docs/theming-guide.adoc[Asciidoctor PDF Theming Guide].
+
+== About the Uber-Document
+
+In order for all of the files in `.adoc` format to be compiled into a single PDF, we need to give the process one `.adoc` file (an "uber-document") that includes all of the content we want in the PDF. In other words, there is no command that says "take all the files in this directory and make one PDF".
+
+Asciidoctor has a nice feature called the _include directive_, which allows you to insert content from another file into the current file (more details in the http://asciidoctor.org/docs/user-manual/#include-directive[Asciidoctor documentation]).
+
+We wanted to make sure we didn't add to the burden of maintaining the PDF by asking everyone to update the uber-document or trying to institute some sort of check on if all the pages are included and in the right place in the hierarchy. Instead, the uber-document is build programmatically at build time.
+
+The uber-document is found in `solr/solr-ref-guide/src/pdf/SolrRefGuide-all.adoc`. This document is very simple - it includes only the Apache license statement and a single `include` directive to another file:
+
+[source]
+\include::_data/pdf-main-body.adoc[]
+
+The Ant target `build-pdf` includes a dependency on another target, `build-nav-data-files`. This target looks at each document and builds the `pdf-main-body.adoc` file with the proper hierarchy of all pages.
+
+NOTE: You will not see the `pdf-main-body.adoc` in `solr/solr-ref-guide/src/_data` directory. This file exists only once it has been built, and it is placed in the build directory, at `solr/solr-ref-guide/build/content_data`.
+
+== Configuring the build-pdf Ant Target
+
+Since most of the styling and layout is defined by the theme, the options that must be configured in the Ant target relate to where to find referenced files, font directories, image directories, and similar top-level document settings.
+
+There are two types of settings at work in our Ant target. First are the settings which are part of the `asciidoctor-ant` jar. Second, we are able to declare any Asciidoctor PDF attribute (setting) that we want to apply to the entire PDF.
+
+Our Ant target (`build-pdf`) uses the following settings:
+
+[source,xml]
+----
+<asciidoctor:convert
+ sourceDirectory="${build.content.dir}/pdf"
+ sourceDocumentName="SolrRefGuide-all.adoc"
+ baseDir="${build.content.dir}"
+ outputDirectory="${build.dir}"
+ backend="pdf"
+ extensions="adoc"
+ sourceHighlighter="coderay"
+ embedAssets="true"
+ imagesDir="${build.content.dir}"
+ doctype="book"
+ safemode="unsafe">
+ <attribute key="icons" value="font" />
+ <attribute key="icon-set" value="fa" />
+ <attribute key="pdf-stylesDir" value="./pdf/themes"/>
+ <attribute key="pdf-style" value="refguide"/>
+ <attribute key="pdf-fontsDir" value="./pdf/fonts"/>
+ <attribute key="pagenums" value='' />
+ <attribute key="figure-caption!" value='' />
+ <attribute key="idprefix" value='' />
+ <attribute key="idseparator" value='-' />
+ <!-- attributes used in adoc files -->
+ <!-- NOTE: If you add any attributes here for use in adoc files, you almost certainly need to also add
+ them to the _config.yml.template file for building the jekyll site as well
+ -->
+ <!-- ... -->
+</asciidoctor:convert>
+----
+
+There are a lot of options here. Note that some include the `<attribute>` tag and some do not. Those that do not are options provided by `asciidoctor-ant` so don't need any special syntax. The options with the `<attribute>` tag are not provided by `asciidoctor-ant` but are supported by `asciidoctor-pdf` so will be applied when the target is run. A few of these are custom variables that we have defined ourselves.
+
+=== Asciidoctor Ant Attributes
+
+`sourceDirectory="${build.content.dir}/pdf"`:: Defines where to find the source file to build the PDF. The variable is declared earlier in `build.xml`.
+`sourceDocumentName="SolrRefGuide-all.adoc"`:: The source file name, which in our case will be built as described in the section <<About the Uber-Document>>.
+`baseDir="${build.content.dir}"`:: The root path for any included files.
+`outputDirectory="${build.dir}"`:: Defines where the resulting PDF file should go. In this case, the
+`backend="pdf"`:: The output format. The `asciidoctor-ant` jar is also capable of outputting DocBook format, so we must declare we want a PDF.
+`extensions="adoc"`:: The file extensions to allow for the source document.
+`sourceHighlighter="coderay"`:: The library to use for syntax highlighting source code.
+`imagesDir="${build.content.dir}"`:: The directory to use to find images referenced in the documents.
+`doctype="book"`:: Adds support for book-style format and sections, such as a preface, colophon, glossary, index, etc.
+`safemode="unsafe">`:: Allows including resources that are external to the parent directory of the source file. For example, source examples could be pulled from Solr's source code instead of copied to documentation. This setting allows that to happen.
+
+=== Asciidoctor PDF Attributes
+
+`<attribute key="icons" value="font" />`:: The style of icons.
+`<attribute key="icon-set" value="fa" />`:: The icon set to use. We use the Font Awesome font set.
+`<attribute key="pdf-stylesDir" value="./pdf/themes"/>`:: The directory to find PDF themes. See the section <<Configuring the PDF Theme>> for more details on themes.
+`<attribute key="pdf-style" value="refguide"/>`:: The theme to use. The theme must be saved in the directory referenced with the `pdf-stylesDir` attribute, and must be named `<pdf-style>-theme.yml`.
+`<attribute key="pdf-fontsDir" value="./pdf/fonts"/>`:: The directory where to find fonts declared in the theme.
+`<attribute key="figure-caption!" value='' />`:: Sets caption labels and numbers (such as "Figure 1") to block images. The exclamation at the end of this setting in our config _disables_ figure captioning.
+`<attribute key="idprefix" value='' />`:: Sets the prefix for auto-generated section IDs, such as those from headings in a page. In our config, this is effectively "null", so auto-generated section IDs do not have any prefix.
+`<attribute key="idseparator" value='-' />`:: Sets the separator between words in auto-generated section IDs to a hyphen (`-`).
+
+=== Custom Attributes
+
+These attributes use variables that are inserted by Ant during the PDF creation process. This allows us to pull from standard Lucene/Solr build files, and not have to update several places for any release. The Ant build process updates the `_config.yml` file from the `_config.yml.template`, then these attributes pull the proper value from that file.
+
+`<attribute key="solr-guide-draft-status" value="${solr-guide-draft-status}" />`:: Indicates if this is a `DRAFT` PDF or not.
+`<attribute key="solr-guide-version" value="${solr-guide-version}" />`:: The version of the Guide itself.
+`<attribute key="solr-docs-version" value="${solr-docs-version}" />`:: The version of Solr covered by this guide.
+`<attribute key="solr-javadocs" value="${solr-javadocs}" />`:: Sets the path for Solr javadoc links to include the right path for the current release version.
+`<attribute key="lucene-javadocs" value="${lucene-javadocs}" />`:: Sets the path for Lucene javadoc links to the right path for the current release version.
+`<attribute key="build-date" value="${DSTAMP}" />`:: Sets the date of the build to add the date to the footer of each page of the PDF.
+`<attribute key="build-year" value="${current.year}" />`:: Sets the year of the build to add the date to the copyright notice.
http://git-wip-us.apache.org/repos/asf/lucene-solr/blob/8d00e53b/solr/solr-ref-guide/src/meta-docs/publish.adoc
----------------------------------------------------------------------
diff --git a/solr/solr-ref-guide/src/meta-docs/publish.adoc b/solr/solr-ref-guide/src/meta-docs/publish.adoc
new file mode 100644
index 0000000..5476fc3
--- /dev/null
+++ b/solr/solr-ref-guide/src/meta-docs/publish.adoc
@@ -0,0 +1,215 @@
+= Publication Process
+// 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
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+== About the Formats
+
+The Solr Ref Guide is published in two formats: PDF and HTML.
+
+The PDF version is the *official* release, and requires a vote before release. See <<Publishing PDF Version>> for details on how to generate the PDF and hold a vote.
+
+The HTML version is considered a "convenience" version, and does not require a vote. See <<Publishing HTML Version>> for details on how to publish the HTML.
+
+It's strongly preferred that both PDF and HTML versions are available during the vote for the PDF. However, since the HTML version is not an official release, it is more of an unwritten rule to publish the HTML at the same time as producing a release candidate for the PDF.
+
+== Publishing PDF Version
+The PDF version of the Solr Reference Guide is the *official* version. As such, it is voted on by the community before release, and is treated as an official artifact of the Lucene/Solr project.
+
+=== Prerequisites
+
+* You have checked out the Lucene/Solr source code on the machine you will be doing the release from. You will need scripts in the `dev-tools` directory.
+* You have generated a GPG key. See the Apache documentation on https://www.apache.org/dev/release-signing.html#generate[generating a code signing key].
+* You have Python 3 installed. This is needed to poll the mirrors after release to be sure it's propagated enough to make the announcement.
+
+=== Generate the PDF
+
+No local dependencies are required to build the PDF. The Ant target will download the jars and other items it requires.
+
+The build process generates the PDF, including the page hierarchy, and then runs an optimization script on the PDF to make it smaller.
+
+To build the PDF:
+
+. Run `ant build-pdf -Dsolr-guide-version=X.Y`
+. The resulting PDF will be in `solr/build/solr-ref-guide`.
+
+IMPORTANT: The `-Dsolr-guide-version` system property is optional. By default the build system uses the `version.properties` of the current branch and assumes this is a `DRAFT` build.
+
+=== Prepare and Upload Release Candidate
+
+The `dist/dev` Subversion repository includes a directory for the Solr Ref Guide at https://dist.apache.org/repos/dist/dev/lucene/solr/ref-guide/[`lucene/solr/ref-guide`] which can host the release candidate (RC) during the VOTE stage of the process.
+
+These steps walk through checking out this directory and uploading the Guide to it.
+
+. Checkout the directory: `svn co https://dist.apache.org/repos/dist/dev/lucene/solr/ref-guide solr-ref-guide-rc`
+* If you have already checked out this directory, you can simply update it: `svn update solr-ref-guide-rc`
+. Change directories so `solr-ref-guide-rc` is your working directory (`cd solr-ref-guide-rc`).
+
+IMPORTANT: The next step requires that you have already generated your GPG keys. Your GPG passphrase will be required.
+
+[start=3]
+. Run the Prep Ref Guide script to prepare the RC. This script ensures proper naming of the PDF file, generates `.sha1` and `.asc` files and creates the proper RC sub-directories under `solr-ref-guide-rc`.
+.. The structure of the input is: `prep-solr-ref-guide-rc.sh <path/PDFfilename> <Solrversion-RC#> GPGkey`.
+.. From the `solr-ref-guide-rc` directory, it will look something like this:
++
+[source,bash]
+----
+$ ~/lucene-source/dev-tools/scripts/prep-solr-ref-guide-rc.sh apache-solr-ref-guide-7.0.pdf 7.0-RC0
+
++ mkdir apache-solr-ref-guide-7.0-RC0
++ mv apache-solr-ref-guide-7.0.pdf apache-solr-ref-guide-7.0-RC0/apache-solr-ref-guide-7.0.pdf
++ cd apache-solr-ref-guide-7.0-RC0
++ sha1sum apache-solr-ref-guide-7.0.pdf
++ gpg -u DEADBEEF --armor --output apache-solr-ref-guide-7.0.pdf.asc --detach-sig apache-solr-ref-guide-7.0.pdf
+
+You need a passphrase to unlock the secret key for
+user: "Your Name <yo...@apache.org>"
+4096-bit RSA key, ID DEADBEEF, created 1969-07-04
+----
++
+. Add and commit the new release candidate to the `dist/dev` with these steps:
+.. `svn add apache-solr-ref-guide-7.0-RC0`
+.. `svn commit -m "7.0 ref guide RC0"`
+
+=== Hold a VOTE
+Votes must be sent to the lucene-dev mailing list (`dev@lucene.apache.org`).
+
+. Send an email to `dev@lucene.apache.org` with subject, "VOTE: Release Apache Solr Ref Guide for Solr X.Y".
+. The body of the email should include the full URL of the RC directory in the `dist/dev` repo. Such as: https://dist.apache.org/repos/dist/dev/lucene/solr/ref-guide/apache-solr-ref-guide-7.0-RC0
+. You can add your own +1 to the vote announcement email.
+. If there are issues that need to be resolved, you can start the process over, using RC1, RC2, etc., as needed.
+
+Ideally, the HTML version will also be available for voters to evaluate, see the section <<Publishing HTML Version>> below for details of how to do that.
+
+=== Publish to Production & Archive Old Versions
+
+Once at least three PMC members have voted for release (see https://www.apache.org/foundation/voting.html#ReleaseVotes[Apache Voting Process] for details on the rules for votes), the release candidate can be released.
+
+. Use the Publish Solr Ref Guide script (`publish-solr-ref-guide.sh`) to generate the proper SVN commands to be run to execute a remote move of the RC files to the final `dist/releases` repository.
+.. The script takes only the version and _RC number that passed the vote_ as inputs, such as `7.0-RC0`.
+.. The input and output of the script will look like this:
++
+[source,bash]
+----
+$ ~/lucene-source/dev-tools/scripts/publish-solr-ref-guide-rc.sh X.Y-RCZ
+
+## Run the following commands when ready...
+svn move -m 'publishing apache-solr-ref-guide-X.Y-RCZ' https://dist.apache.org/repos/dist/dev/lucene/solr/ref-guide/apache-solr-ref-guide-X.Y-RCZ/apache-solr-ref-guide-X.Y.pdf https://dist.apache.org/repos/dist/dev/lucene/solr/ref-guide/apache-solr-ref-guide-X.Y-RCZ/apache-solr-ref-guide-X.Y.pdf.asc https://dist.apache.org/repos/dist/dev/lucene/solr/ref-guide/apache-solr-ref-guide-X.Y-RCZ/apache-solr-ref-guide-X.Y.pdf.sha1 https://dist.apache.org/repos/dist/release/lucene/solr/ref-guide/
+
+svn rm -m 'cleaning up apache-solr-ref-guide-X.Y-RCZ' https://dist.apache.org/repos/dist/dev/lucene/solr/ref-guide/apache-solr-ref-guide-X.Y-RCZ
+----
+[start=2]
+. The release should propagate to as many mirrors as possible before announcing the release, generally 24 hours is long enough. Use the Poll Mirrors script (`poll-mirrors.py`) to check the status:
++
+[source,bash]
+python3 -u ~/lucene-source/dev-tools/scripts/poll-mirrors.py -details -p lucene/solr/ref-guide/apache-solr-ref-guide-X.Y.pdf
+
+* This script requires Python 3 to be installed on your machine.
+* If you have over 85% of the mirrors with the file, it's OK to go ahead with the announcement.
+. You may get an automated email about updating the ASF release repository; you can safely ignore this email.
+. The `dist/releases` repo is only meant to keep the latest releases. Shortly after new releases are mirrored, they are copied to `archive.apache.org`, so older releases can safely be deleted from `dist/releases` since they have been backed up in the archives.
+.. Run the Archive Ref Guide script (`archive-solr-ref-guide.sh`) using the X.Y version of the Ref Guide that has just been published. Older RCs will also be removed.
+.. Again, this script doesn't do any direct removal of files, it only outputs SVN commands for you to copy and paste:
++
+[source,bash]
+----
+$ ~/lucene-source/dev-tools/scripts/archive-solr-ref-guide.sh X.Y
+## Run the following commands when ready...
+
+# Delete old releases
+svn rm -m 'removing archived ref guide files prior to X.Y' https://dist.apache.org/repos/dist/release/lucene/solr/ref-guide/apache-solr-ref-guide-A.B.pdf https://dist.apache.org/repos/dist/release/lucene/solr/ref-guide/apache-solr-ref-guide-A.B.pdf.asc https://dist.apache.org/repos/dist/release/lucene/solr/ref-guide/apache-solr-ref-guide-A.B.pdf.sha1
+
+# Delete old RC files
+svn rm -m 'cleaning up old RCs now that X.Y has been released' https://dist.apache.org/repos/dist/dev/lucene/solr/ref-guide/apache-solr-ref-guide-X.Y-RC0/ https://dist.apache.org/repos/dist/dev/lucene/solr/ref-guide/apache-solr-ref-guide-X.Y-RC1/
+----
+
+=== Announce the Release
+
+Announce the availability of the new Ref Guide on `solr-user@lucene.apache.org` and CC `general@lucene.apache.org` and `announce@apache.org`.
+
+WARNING: You must send the announcement email from your @apache.org email address or announce@apache will reject it.
+
+Always use the link to the download redirector for the announcement, as it will automatically direct users to the closest mirror for download: `https://www.apache.org/dyn/closer.cgi/lucene/solr/ref-guide/apache-solr-ref-guide-X.Y.pdf`.
+
+You could also include a link to the HTML version in your announcement, if the publication process for that has finished.
+
+== Publishing HTML Version
+The steps to publish the Guide differ depending on if it is the first time the Guide has been published or if it is an update to an already published Guide.
+
+=== Building the HTML Version
+
+If you have the required dependencies on your local machine, you can build the HTML version with `ant build-site -Dsolr-guide-version=X.Y`. The dependencies are listed in `solr-ref-guide/README.adoc`.
+
+Tip::
++
+//TODO update Jenkins link
+If you do not have the required dependencies, and don't choose to install them, you can download the files from the Jenkins (https://builds.apache.org/job/Solr-reference-guide-jira-SOLR-10290/lastSuccessfulBuild/artifact/solr/build/solr-ref-guide/html-site/[Solr Reference Guide job]). But these HTML pages will have the `DRAFT` status noted in them and will not be suitable for publishing.
+
+=== Publish a New Guide
+// A lot of this was copied from https://wiki.apache.org/lucene-java/ReleaseTodo#Website_.2B-.3D_javadocs. See that section for explanations for why some steps are required.
+
+==== Step 1: Update extpaths.txt in CMS Staging
+
+. Checkout CMS trunk:
++
+[source,bash]
+svn co --depth=immediates https://svn.apache.org/repos/asf/lucene/cms/trunk/content website-source
++
+* If you already have this repo checked out, you can simply `svn up website-source` to update to the latest revision.
+. `cd website-source`
+. Add Guide branch dir: `echo solr/guide/X_Y >> extpaths.txt`
+. Commit changes:
++
+[source,bash]
+svn commit -m "Update CMS production sync exceptions for X_Y_Z Guide" extpaths.txt
+
+==== Step 2: Push Guide to Website Production
+
+Go to the checkout directory where you have built the Guide and push the documentation via subversion import. You must push it to the path you just added to `extpaths.txt`, so if the path you added was `solr/guide/6_5`, you'll use the path as shown in the below example:
+
+[source,bash]
+svn -m "Add Ref Guide for Solr 6.5" import <checkoutroot>/solr/build/solr-ref-guide/html-site https://svn.apache.org/repos/infra/websites/production/lucene/content/solr/guide/6_5
+
+Confirm you can browse to these URLs manually, and especially that solr javadocs link back to lucene's correctly. Example:
+https://lucene.apache.org/solr/guide/6_5
+
+==== Step 3: Push Staging extpaths.txt to Production
+
+The `extpaths.txt` works by listing paths that should be ignored when the CMS syncs the staging and production repositories. Publishing staging to production will only succeed if the paths listed in `extpaths.txt` exist in production. At the same time, if a path exists in production but not in staging it will be deleted unless it is defined in `extpaths.txt`. After pushing the content to production, check that the `extpaths.txt` in production includes the proper path to ensure that the Guide is not deleted incorrectly. If it does not exist in production, try to publish the site again to make sure it is updated.
+
+Production URL: https://lucene.apache.org/extpaths.txt
+
+==== Update Ref Guide Landing Page
+
+Update the landing page at https://lucene.apache.org/solr/guide to link to the newest version.
+
+You can use the CMS system for this since it is a small change, or you can edit the file locally and commit it to the staging repo.
+
+=== Update a Published Guide
+
+If you need to re-publish an existing online copy of the Guide, you will need to checkout the directory in production website repository and overwrite the existing files:
+
+. Build the new HTML files locally (`ant clean build-site`), or download them from Jenkins.
+. Checkout the directory you need to update from the production repo: `svn co https://svn.apache.org/repos/infra/websites/production/lucene/content/solr/guide/<dir>`.
+* This command checks out the Guide version directory into a local subdirectory with the same name as the version (such as "6_5"). You can provide a better name locally if you prefer by adding it to the end of the command shown above.
+* Don't shortcut this and download the whole production website. It will take an incredibly long time and that will feel like _forever_.
+. Copy the files from the build location to the checked out Guide directory. For example, if we needed to replace the current Guide for Solr 6.5, we'd do `cp -r <checkoutroot>/solr/build/html-site 6_5/.`
+. Use `svn status` to see the files modified.
+. If there are any pages added or deleted, use `svn add <file>` or `svn rm <file>` as needed.
+. Commit the changes: `svn commit -m "Update production 6.5 Ref Guide"`
+
+// TODO:
+// - figure out if redirects in .htaccess require any work here (probably)
http://git-wip-us.apache.org/repos/asf/lucene-solr/blob/8d00e53b/solr/solr-ref-guide/src/metrics-reporting.adoc
----------------------------------------------------------------------
diff --git a/solr/solr-ref-guide/src/metrics-reporting.adoc b/solr/solr-ref-guide/src/metrics-reporting.adoc
index 4fa049e..1212bc2 100644
--- a/solr/solr-ref-guide/src/metrics-reporting.adoc
+++ b/solr/solr-ref-guide/src/metrics-reporting.adoc
@@ -390,8 +390,8 @@ Like other request handlers, the Metrics API can also take the `wt` parameter to
Request only "counter" type metrics in the "core" group, returned in JSON:
-`\http://localhost:8983/solr/admin/metrics?wt=json&type=counter&group=core`
+`\http://localhost:8983/solr/admin/metrics?type=counter&group=core`
-Request only "core" group metrics that start with "INDEX", returned in JSON:
+Request only "core" group metrics that start with "INDEX", returned in XML:
-`\http://localhost:8983/solr/admin/metrics?wt=json&prefix=INDEX&group=core`
+`\http://localhost:8983/solr/admin/metrics?wt=xml&prefix=INDEX&group=core`
http://git-wip-us.apache.org/repos/asf/lucene-solr/blob/8d00e53b/solr/solr-ref-guide/src/morelikethis.adoc
----------------------------------------------------------------------
diff --git a/solr/solr-ref-guide/src/morelikethis.adoc b/solr/solr-ref-guide/src/morelikethis.adoc
index e0756cb..a5bdb4f 100644
--- a/solr/solr-ref-guide/src/morelikethis.adoc
+++ b/solr/solr-ref-guide/src/morelikethis.adoc
@@ -28,7 +28,6 @@ The second is to use it as a search component. This is less desirable since it p
The final approach is to use it as a request handler but with externally supplied text. This case, also referred to as the MoreLikeThisHandler, will supply information about similar documents in the index based on the text of the input document.
-[[MoreLikeThis-HowMoreLikeThisWorks]]
== How MoreLikeThis Works
`MoreLikeThis` constructs a Lucene query based on terms in a document. It does this by pulling terms from the defined list of fields ( see the `mlt.fl` parameter, below). For best results, the fields should have stored term vectors in `schema.xml`. For example:
@@ -42,7 +41,6 @@ If term vectors are not stored, `MoreLikeThis` will generate terms from stored f
The next phase filters terms from the original document using thresholds defined with the MoreLikeThis parameters. Finally, a query is run with these terms, and any other query parameters that have been defined (see the `mlt.qf` parameter, below) and a new document set is returned.
-[[MoreLikeThis-CommonParametersforMoreLikeThis]]
== Common Parameters for MoreLikeThis
The table below summarizes the `MoreLikeThis` parameters supported by Lucene/Solr. These parameters can be used with any of the three possible MoreLikeThis approaches.
@@ -77,8 +75,6 @@ Specifies if the query will be boosted by the interesting term relevance. It can
`mlt.qf`::
Query fields and their boosts using the same format as that used by the <<the-dismax-query-parser.adoc#the-dismax-query-parser,DisMax Query Parser>>. These fields must also be specified in `mlt.fl`.
-
-[[MoreLikeThis-ParametersfortheMoreLikeThisComponent]]
== Parameters for the MoreLikeThisComponent
Using MoreLikeThis as a search component returns similar documents for each document in the response set. In addition to the common parameters, these additional options are available:
@@ -89,8 +85,6 @@ If set to `true`, activates the `MoreLikeThis` component and enables Solr to ret
`mlt.count`::
Specifies the number of similar documents to be returned for each result. The default value is 5.
-
-[[MoreLikeThis-ParametersfortheMoreLikeThisHandler]]
== Parameters for the MoreLikeThisHandler
The table below summarizes parameters accessible through the `MoreLikeThisHandler`. It supports faceting, paging, and filtering using common query parameters, but does not work well with alternate query parsers.
@@ -105,7 +99,6 @@ Specifies an offset into the main query search results to locate the document on
Controls how the `MoreLikeThis` component presents the "interesting" terms (the top TF/IDF terms) for the query. Supports three settings. The setting list lists the terms. The setting none lists no terms. The setting details lists the terms along with the boost value used for each term. Unless `mlt.boost=true`, all terms will have `boost=1.0`.
-[[MoreLikeThis-MoreLikeThisQueryParser]]
-== More Like This Query Parser
+== MoreLikeThis Query Parser
The `mlt` query parser provides a mechanism to retrieve documents similar to a given document, like the handler. More information on the usage of the mlt query parser can be found in the section <<other-parsers.adoc#other-parsers,Other Parsers>>.
http://git-wip-us.apache.org/repos/asf/lucene-solr/blob/8d00e53b/solr/solr-ref-guide/src/near-real-time-searching.adoc
----------------------------------------------------------------------
diff --git a/solr/solr-ref-guide/src/near-real-time-searching.adoc b/solr/solr-ref-guide/src/near-real-time-searching.adoc
index fccf7b3..6556398 100644
--- a/solr/solr-ref-guide/src/near-real-time-searching.adoc
+++ b/solr/solr-ref-guide/src/near-real-time-searching.adoc
@@ -26,7 +26,6 @@ With NRT, you can modify a `commit` command to be a *soft commit*, which avoids
However, pay special attention to cache and autowarm settings as they can have a significant impact on NRT performance.
-[[NearRealTimeSearching-CommitsandOptimizing]]
== Commits and Optimizing
A commit operation makes index changes visible to new search requests. A *hard commit* uses the transaction log to get the id of the latest document changes, and also calls `fsync` on the index files to ensure they have been flushed to stable storage and no data loss will result from a power failure. The current transaction log is closed and a new one is opened. See the "transaction log" discussion below for data loss issues.
@@ -45,7 +44,6 @@ The number of milliseconds to wait before pushing documents to the index. It wor
Use `maxDocs` and `maxTime` judiciously to fine-tune your commit strategies.
-[[NearRealTimeSearching-TransactionLogs]]
=== Transaction Logs (tlogs)
Transaction logs are a "rolling window" of at least the last `N` (default 100) documents indexed. Tlogs are configured in solrconfig.xml, including the value of `N`. The current transaction log is closed and a new one opened each time any variety of hard commit occurs. Soft commits have no effect on the transaction log.
@@ -54,7 +52,6 @@ When tlogs are enabled, documents being added to the index are written to the tl
When Solr is shut down gracefully (i.e. using the `bin/solr stop` command and the like) Solr will close the tlog file and index segments so no replay will be necessary on startup.
-[[NearRealTimeSearching-AutoCommits]]
=== AutoCommits
An autocommit also uses the parameters `maxDocs` and `maxTime`. However it's useful in many strategies to use both a hard `autocommit` and `autosoftcommit` to achieve more flexible commits.
@@ -72,7 +69,6 @@ For example:
It's better to use `maxTime` rather than `maxDocs` to modify an `autoSoftCommit`, especially when indexing a large number of documents through the commit operation. It's also better to turn off `autoSoftCommit` for bulk indexing.
-[[NearRealTimeSearching-OptionalAttributesforcommitandoptimize]]
=== Optional Attributes for commit and optimize
`waitSearcher`::
@@ -99,7 +95,6 @@ Example of `commit` and `optimize` with optional attributes:
<optimize waitSearcher="false"/>
----
-[[NearRealTimeSearching-PassingcommitandcommitWithinparametersaspartoftheURL]]
=== Passing commit and commitWithin Parameters as Part of the URL
Update handlers can also get `commit`-related parameters as part of the update URL, if the `stream.body` feature is enabled. This example adds a small test document and causes an explicit commit to happen immediately afterwards:
@@ -132,10 +127,9 @@ curl http://localhost:8983/solr/my_collection/update?commitWithin=10000
-H "Content-Type: text/xml" --data-binary '<add><doc><field name="id">testdoc</field></doc></add>'
----
-WARNING: While the `stream.body` feature is great for development and testing, it should normally not be enabled in production systems, as it lets a user with READ permissions post data that may alter the system state. The feature is disabled by default. See <<requestdispatcher-in-solrconfig.adoc#RequestDispatcherinSolrConfig-requestParsersElement,RequestDispatcher in SolrConfig>> for details.
+WARNING: While the `stream.body` feature is great for development and testing, it should normally not be enabled in production systems, as it lets a user with READ permissions post data that may alter the system state. The feature is disabled by default. See <<requestdispatcher-in-solrconfig.adoc#requestparsers-element,RequestDispatcher in SolrConfig>> for details.
-[[NearRealTimeSearching-ChangingdefaultcommitWithinBehavior]]
-=== Changing default commitWithin Behavior
+=== Changing Default commitWithin Behavior
The `commitWithin` settings allow forcing document commits to happen in a defined time period. This is used most frequently with <<near-real-time-searching.adoc#near-real-time-searching,Near Real Time Searching>>, and for that reason the default is to perform a soft commit. This does not, however, replicate new documents to slave servers in a master/slave environment. If that's a requirement for your implementation, you can force a hard commit by adding a parameter, as in this example:
http://git-wip-us.apache.org/repos/asf/lucene-solr/blob/8d00e53b/solr/solr-ref-guide/src/other-parsers.adoc
----------------------------------------------------------------------
diff --git a/solr/solr-ref-guide/src/other-parsers.adoc b/solr/solr-ref-guide/src/other-parsers.adoc
index 271c33b..db48419 100644
--- a/solr/solr-ref-guide/src/other-parsers.adoc
+++ b/solr/solr-ref-guide/src/other-parsers.adoc
@@ -24,7 +24,6 @@ This section details the other parsers, and gives examples for how they might be
Many of these parsers are expressed the same way as <<local-parameters-in-queries.adoc#local-parameters-in-queries,Local Parameters in Queries>>.
-[[OtherParsers-BlockJoinQueryParsers]]
== Block Join Query Parsers
There are two query parsers that support block joins. These parsers allow indexing and searching for relational content that has been<<uploading-data-with-index-handlers.adoc#uploading-data-with-index-handlers,indexed as nested documents>>.
@@ -55,7 +54,6 @@ The example usage of the query parsers below assumes these two documents and eac
</add>
----
-[[OtherParsers-BlockJoinChildrenQueryParser]]
=== Block Join Children Query Parser
This parser takes a query that matches some parent documents and returns their children.
@@ -80,16 +78,16 @@ Using the example documents above, we can construct a query such as `q={!child o
Note that the query for `someParents` should match only parent documents passed by `allParents` or you may get an exception:
-....
+[literal]
Parent query must not match any docs besides parent filter. Combine them as must (+) and must-not (-) clauses to find a problem doc.
-....
+
In older version the error is:
-....
+
+[literal]
Parent query yields document which is not matched by parents filter.
-....
+
You can search for `q=+(someParents) -(allParents)` to find a cause.
-[[OtherParsers-BlockJoinParentQueryParser]]
=== Block Join Parent Query Parser
This parser takes a query that matches child documents and returns their parents.
@@ -101,13 +99,15 @@ The parameter `allParents` is a filter that matches *only parent documents*; her
The parameter `someChildren` is a query that matches some or all of the child documents.
Note that the query for `someChildren` should match only child documents or you may get an exception:
-....
+
+[literal]
Child query must not match same docs with parent filter. Combine them as must clauses (+) to find a problem doc.
-....
-In older version it's:
-....
+
+In older version the error is:
+
+[literal]
child query must only match non-parent docs.
-....
+
You can search for `q=+(parentFilter) +(someChildren)` to find a cause .
Again using the example documents above, we can construct a query such as `q={!parent which="content_type:parentDocument"}comments:SolrCloud`. We get this document in response:
@@ -133,20 +133,17 @@ A common mistake is to try to filter parents with a `which` filter, as in this b
Instead, you should use a sibling mandatory clause as a filter:
`q= *+title:join* +{!parent which="*content_type:parentDocument*"}comments:SolrCloud`
-
====
-[[OtherParsers-Scoring]]
-=== Scoring
+=== Scoring with the Block Join Parent Query Parser
You can optionally use the `score` local parameter to return scores of the subordinate query. The values to use for this parameter define the type of aggregation, which are `avg` (average), `max` (maximum), `min` (minimum), `total (sum)`. Implicit default is `none` which returns `0.0`.
-[[OtherParsers-BoostQueryParser]]
== Boost Query Parser
`BoostQParser` extends the `QParserPlugin` and creates a boosted query from the input value. The main value is the query to be boosted. Parameter `b` is the function query to use as the boost. The query to be boosted may be of any type.
-Examples:
+=== Boost Query Parser Examples
Creates a query "foo" which is boosted (scores are multiplied) by the function query `log(popularity)`:
@@ -162,7 +159,7 @@ Creates a query "foo" which is boosted by the date boosting function referenced
{!boost b=recip(ms(NOW,mydatefield),3.16e-11,1,1)}foo
----
-[[OtherParsers-CollapsingQueryParser]]
+[[other-collapsing]]
== Collapsing Query Parser
The `CollapsingQParser` is really a _post filter_ that provides more performant field collapsing than Solr's standard approach when the number of distinct groups in the result set is high.
@@ -171,7 +168,6 @@ This parser collapses the result set to a single document per group before it fo
Details about using the `CollapsingQParser` can be found in the section <<collapse-and-expand-results.adoc#collapse-and-expand-results,Collapse and Expand Results>>.
-[[OtherParsers-ComplexPhraseQueryParser]]
== Complex Phrase Query Parser
The `ComplexPhraseQParser` provides support for wildcards, ORs, etc., inside phrase queries using Lucene's {lucene-javadocs}/queryparser/org/apache/lucene/queryparser/complexPhrase/ComplexPhraseQueryParser.html[`ComplexPhraseQueryParser`].
@@ -204,15 +200,13 @@ A mix of ordered and unordered complex phrase queries:
+_query_:"{!complexphrase inOrder=true}manu:\"a* c*\"" +_query_:"{!complexphrase inOrder=false df=name}\"bla* pla*\""
----
-[[OtherParsers-Limitations]]
-=== Limitations
+=== Complex Phrase Parser Limitations
Performance is sensitive to the number of unique terms that are associated with a pattern. For instance, searching for "a*" will form a large OR clause (technically a SpanOr with many terms) for all of the terms in your index for the indicated field that start with the single letter 'a'. It may be prudent to restrict wildcards to at least two or preferably three letters as a prefix. Allowing very short prefixes may result in to many low-quality documents being returned.
Notice that it also supports leading wildcards "*a" as well with consequent performance implications. Applying <<filter-descriptions.adoc#reversed-wildcard-filter,ReversedWildcardFilterFactory>> in index-time analysis is usually a good idea.
-[[OtherParsers-MaxBooleanClauses]]
-==== MaxBooleanClauses
+==== MaxBooleanClauses with Complex Phrase Parser
You may need to increase MaxBooleanClauses in `solrconfig.xml` as a result of the term expansion above:
@@ -221,10 +215,9 @@ You may need to increase MaxBooleanClauses in `solrconfig.xml` as a result of th
<maxBooleanClauses>4096</maxBooleanClauses>
----
-This property is described in more detail in the section <<query-settings-in-solrconfig.adoc#QuerySettingsinSolrConfig-QuerySizingandWarming,Query Sizing and Warming>>.
+This property is described in more detail in the section <<query-settings-in-solrconfig.adoc#query-sizing-and-warming,Query Sizing and Warming>>.
-[[OtherParsers-Stopwords]]
-==== Stopwords
+==== Stopwords with Complex Phrase Parser
It is recommended not to use stopword elimination with this query parser.
@@ -246,12 +239,10 @@ the document is returned. The next query that _does_ use the Complex Phrase Quer
does _not_ return that document because SpanNearQuery has no good way to handle stopwords in a way analogous to PhraseQuery. If you must remove stopwords for your use case, use a custom filter factory or perhaps a customized synonyms filter that reduces given stopwords to some impossible token.
-[[OtherParsers-Escaping]]
-==== Escaping
+==== Escaping with Complex Phrase Parser
Special care has to be given when escaping: clauses between double quotes (usually whole query) is parsed twice, these parts have to be escaped as twice. eg `"foo\\: bar\\^"`.
-[[OtherParsers-FieldQueryParser]]
== Field Query Parser
The `FieldQParser` extends the `QParserPlugin` and creates a field query from the input value, applying text analysis and constructing a phrase query if appropriate. The parameter `f` is the field to be queried.
@@ -265,7 +256,6 @@ Example:
This example creates a phrase query with "foo" followed by "bar" (assuming the analyzer for `myfield` is a text field with an analyzer that splits on whitespace and lowercase terms). This is generally equivalent to the Lucene query parser expression `myfield:"Foo Bar"`.
-[[OtherParsers-FunctionQueryParser]]
== Function Query Parser
The `FunctionQParser` extends the `QParserPlugin` and creates a function query from the input value. This is only one way to use function queries in Solr; for another, more integrated, approach, see the section on <<function-queries.adoc#function-queries,Function Queries>>.
@@ -277,7 +267,6 @@ Example:
{!func}log(foo)
----
-[[OtherParsers-FunctionRangeQueryParser]]
== Function Range Query Parser
The `FunctionRangeQParser` extends the `QParserPlugin` and creates a range query over a function. This is also referred to as `frange`, as seen in the examples below.
@@ -312,15 +301,13 @@ Both of these examples restrict the results by a range of values found in a decl
For more information about range queries over functions, see Yonik Seeley's introductory blog post https://lucidworks.com/2009/07/06/ranges-over-functions-in-solr-14/[Ranges over Functions in Solr 1.4].
-[[OtherParsers-GraphQueryParser]]
== Graph Query Parser
The `graph` query parser does a breadth first, cyclic aware, graph traversal of all documents that are "reachable" from a starting set of root documents identified by a wrapped query.
The graph is built according to linkages between documents based on the terms found in `from` and `to` fields that you specify as part of the query.
-[[OtherParsers-Parameters]]
-=== Parameters
+=== Graph Query Parameters
`to`::
The field name of matching documents to inspect to identify outgoing edges for graph traversal. Defaults to `edge_ids`.
@@ -342,17 +329,15 @@ Boolean that indicates if the results of the query should be filtered so that on
`useAutn`:: Boolean that indicates if an Automatons should be compiled for each iteration of the breadth first search, which may be faster for some graphs. Defaults to `false`.
-[[OtherParsers-Limitations.1]]
-=== Limitations
+=== Graph Query Limitations
The `graph` parser only works in single node Solr installations, or with <<solrcloud.adoc#solrcloud,SolrCloud>> collections that use exactly 1 shard.
-[[OtherParsers-Examples]]
-=== Examples
+=== Graph Query Examples
To understand how the graph parser works, consider the following Directed Cyclic Graph, containing 8 nodes (A to H) and 9 edges (1 to 9):
-image::images/other-parsers/graph_qparser_example.png[image,height=200]
+image::images/other-parsers/graph_qparser_example.png[image,height=100]
One way to model this graph as Solr documents, would be to create one document per node, with mutivalued fields identifying the incoming and outgoing edges for each node:
@@ -426,7 +411,6 @@ http://localhost:8983/solr/my_graph/query?fl=id&q={!graph+from=in_edge+to=out_ed
}
----
-[[OtherParsers-SimplifiedModels]]
=== Simplified Models
The Document & Field modeling used in the above examples enumerated all of the outgoing and income edges for each node explicitly, to help demonstrate exactly how the "from" and "to" params work, and to give you an idea of what is possible. With multiple sets of fields like these for identifying incoming and outgoing edges, it's possible to model many independent Directed Graphs that contain some or all of the documents in your collection.
@@ -469,7 +453,6 @@ http://localhost:8983/solr/alt_graph/query?fl=id&q={!graph+from=id+to=out_edge+m
}
----
-[[OtherParsers-JoinQueryParser]]
== Join Query Parser
`JoinQParser` extends the `QParserPlugin`. It allows normalizing relationships between documents with a join operation. This is different from the concept of a join in a relational database because no information is being truly joined. An appropriate SQL analogy would be an "inner query".
@@ -493,8 +476,7 @@ fq = price:[* TO 12]
The join operation is done on a term basis, so the "from" and "to" fields must use compatible field types. For example: joining between a `StrField` and a `TrieIntField` will not work, likewise joining between a `StrField` and a `TextField` that uses `LowerCaseFilterFactory` will only work for values that are already lower cased in the string field.
-[[OtherParsers-Scoring.1]]
-=== Scoring
+=== Join Parser Scoring
You can optionally use the `score` parameter to return scores of the subordinate query. The values to use for this parameter define the type of aggregation, which are `avg` (average), `max` (maximum), `min` (minimum) `total`, or `none`.
@@ -504,7 +486,6 @@ You can optionally use the `score` parameter to return scores of the subordinate
Specifying `score` local parameter switches the join algorithm. This might have performance implication on large indices, but it's more important that this algorithm won't work for single value numeric field starting from 7.0. Users are encouraged to change field types to string and rebuild indexes during migration.
====
-[[OtherParsers-JoiningAcrossCollections]]
=== Joining Across Collections
You can also specify a `fromIndex` parameter to join with a field from another core or collection. If running in SolrCloud mode, then the collection specified in the `fromIndex` parameter must have a single shard and a replica on all Solr nodes where the collection you're joining to has a replica.
@@ -548,7 +529,6 @@ At query time, the `JoinQParser` will access the local replica of the *movie_dir
For more information about join queries, see the Solr Wiki page on http://wiki.apache.org/solr/Join[Joins]. Erick Erickson has also written a blog post about join performance titled https://lucidworks.com/2012/06/20/solr-and-joins/[Solr and Joins].
-[[OtherParsers-LuceneQueryParser]]
== Lucene Query Parser
The `LuceneQParser` extends the `QParserPlugin` by parsing Solr's variant on the Lucene QueryParser syntax. This is effectively the same query parser that is used in Lucene. It uses the operators `q.op`, the default operator ("OR" or "AND") and `df`, the default field name.
@@ -562,7 +542,6 @@ Example:
For more information about the syntax for the Lucene Query Parser, see the {lucene-javadocs}/queryparser/org/apache/lucene/queryparser/classic/package-summary.html[Classic QueryParser javadocs].
-[[OtherParsers-LearningToRankQueryParser]]
== Learning To Rank Query Parser
The `LTRQParserPlugin` is a special purpose parser for reranking the top results of a simple query using a more complex ranking query which is based on a machine learnt model.
@@ -576,7 +555,6 @@ Example:
Details about using the `LTRQParserPlugin` can be found in the <<learning-to-rank.adoc#learning-to-rank,Learning To Rank>> section.
-[[OtherParsers-MaxScoreQueryParser]]
== Max Score Query Parser
The `MaxScoreQParser` extends the `LuceneQParser` but returns the Max score from the clauses. It does this by wrapping all `SHOULD` clauses in a `DisjunctionMaxQuery` with tie=1.0. Any `MUST` or `PROHIBITED` clauses are passed through as-is. Non-boolean queries, e.g., NumericRange falls-through to the `LuceneQParser` parser behavior.
@@ -588,7 +566,6 @@ Example:
{!maxscore tie=0.01}C OR (D AND E)
----
-[[OtherParsers-MoreLikeThisQueryParser]]
== More Like This Query Parser
`MLTQParser` enables retrieving documents that are similar to a given document. It uses Lucene's existing `MoreLikeThis` logic and also works in SolrCloud mode. The document identifier used here is the unique id value and not the Lucene internal document id. The list of returned documents excludes the queried document.
@@ -638,7 +615,6 @@ Adding more constraints to what qualifies as similar using mintf and mindf.
{!mlt qf=name mintf=2 mindf=3}1
----
-[[OtherParsers-NestedQueryParser]]
== Nested Query Parser
The `NestedParser` extends the `QParserPlugin` and creates a nested query, with the ability for that query to redefine its type via local parameters. This is useful in specifying defaults in configuration and letting clients indirectly reference them.
@@ -662,7 +638,6 @@ If the `q1` parameter is price, then the query would be a function query on the
For more information about the possibilities of nested queries, see Yonik Seeley's blog post https://lucidworks.com/2009/03/31/nested-queries-in-solr/[Nested Queries in Solr].
-[[OtherParsers-PayloadQueryParsers]]
== Payload Query Parsers
These query parsers utilize payloads encoded on terms during indexing.
@@ -672,7 +647,6 @@ The main query, for both of these parsers, is parsed straightforwardly from the
* `PayloadScoreQParser`
* `PayloadCheckQParser`
-[[OtherParsers-PayloadScoreParser]]
=== Payload Score Parser
`PayloadScoreQParser` incorporates each matching term's numeric (integer or float) payloads into the scores.
@@ -695,7 +669,6 @@ If `true`, multiples computed payload factor by the score of the original query.
{!payload_score f=my_field_dpf v=some_term func=max}
----
-[[OtherParsers-PayloadCheckParser]]
=== Payload Check Parser
`PayloadCheckQParser` only matches when the matching terms also have the specified payloads.
@@ -719,7 +692,6 @@ Each specified payload will be encoded using the encoder determined from the fie
{!payload_check f=words_dps payloads="VERB NOUN"}searching stuff
----
-[[OtherParsers-PrefixQueryParser]]
== Prefix Query Parser
`PrefixQParser` extends the `QParserPlugin` by creating a prefix query from the input value. Currently no analysis or value transformation is done to create this prefix query.
@@ -735,7 +707,6 @@ Example:
This would be generally equivalent to the Lucene query parser expression `myfield:foo*`.
-[[OtherParsers-RawQueryParser]]
== Raw Query Parser
`RawQParser` extends the `QParserPlugin` by creating a term query from the input value without any text analysis or transformation. This is useful in debugging, or when raw terms are returned from the terms component (this is not the default).
@@ -751,18 +722,16 @@ Example:
This example constructs the query: `TermQuery(Term("myfield","Foo Bar"))`.
-For easy filter construction to drill down in faceting, the <<OtherParsers-TermQueryParser,TermQParserPlugin>> is recommended.
+For easy filter construction to drill down in faceting, the <<Term Query Parser,TermQParserPlugin>> is recommended.
-For full analysis on all fields, including text fields, you may want to use the <<OtherParsers-FieldQueryParser,FieldQParserPlugin>>.
+For full analysis on all fields, including text fields, you may want to use the <<Field Query Parser,FieldQParserPlugin>>.
-[[OtherParsers-Re-RankingQueryParser]]
== Re-Ranking Query Parser
The `ReRankQParserPlugin` is a special purpose parser for Re-Ranking the top results of a simple query using a more complex ranking query.
Details about using the `ReRankQParserPlugin` can be found in the <<query-re-ranking.adoc#query-re-ranking,Query Re-Ranking>> section.
-[[OtherParsers-SimpleQueryParser]]
== Simple Query Parser
The Simple query parser in Solr is based on Lucene's SimpleQueryParser. This query parser is designed to allow users to enter queries however they want, and it will do its best to interpret the query and return results.
@@ -811,14 +780,12 @@ Defines the default field if none is defined in the Schema, or overrides the def
Any errors in syntax are ignored and the query parser will interpret queries as best it can. However, this can lead to odd results in some cases.
-[[OtherParsers-SpatialQueryParsers]]
== Spatial Query Parsers
There are two spatial QParsers in Solr: `geofilt` and `bbox`. But there are other ways to query spatially: using the `frange` parser with a distance function, using the standard (lucene) query parser with the range syntax to pick the corners of a rectangle, or with RPT and BBoxField you can use the standard query parser but use a special syntax within quotes that allows you to pick the spatial predicate.
All these options are documented further in the section <<spatial-search.adoc#spatial-search,Spatial Search>>.
-[[OtherParsers-SurroundQueryParser]]
== Surround Query Parser
The `SurroundQParser` enables the Surround query syntax, which provides proximity search functionality. There are two positional operators: `w` creates an ordered span query and `n` creates an unordered one. Both operators take a numeric value to indicate distance between two terms. The default is 1, and the maximum is 99.
@@ -838,7 +805,6 @@ This query parser will also accept boolean operators (`AND`, `OR`, and `NOT`, in
The non-unary operators (everything but `NOT`) support both infix `(a AND b AND c)` and prefix `AND(a, b, c)` notation.
-[[OtherParsers-SwitchQueryParser]]
== Switch Query Parser
`SwitchQParser` is a `QParserPlugin` that acts like a "switch" or "case" statement.
@@ -895,7 +861,6 @@ Using the example configuration below, clients can optionally specify the custom
</requestHandler>
----
-[[OtherParsers-TermQueryParser]]
== Term Query Parser
`TermQParser` extends the `QParserPlugin` by creating a single term query from the input value equivalent to `readableToIndexed()`. This is useful for generating filter queries from the external human readable terms returned by the faceting or terms components. The only parameter is `f`, for the field.
@@ -907,14 +872,13 @@ Example:
{!term f=weight}1.5
----
-For text fields, no analysis is done since raw terms are already returned from the faceting and terms components. To apply analysis to text fields as well, see the <<OtherParsers-FieldQueryParser,Field Query Parser>>, above.
+For text fields, no analysis is done since raw terms are already returned from the faceting and terms components. To apply analysis to text fields as well, see the <<Field Query Parser>>, above.
-If no analysis or transformation is desired for any type of field, see the <<OtherParsers-RawQueryParser,Raw Query Parser>>, above.
+If no analysis or transformation is desired for any type of field, see the <<Raw Query Parser>>, above.
-[[OtherParsers-TermsQueryParser]]
== Terms Query Parser
-`TermsQParser` functions similarly to the <<OtherParsers-TermQueryParser,Term Query Parser>> but takes in multiple values separated by commas and returns documents matching any of the specified values.
+`TermsQParser` functions similarly to the <<Term Query Parser,Term Query Parser>> but takes in multiple values separated by commas and returns documents matching any of the specified values.
This can be useful for generating filter queries from the external human readable terms returned by the faceting or terms components, and may be more efficient in some cases than using the <<the-standard-query-parser.adoc#the-standard-query-parser,Standard Query Parser>> to generate an boolean query since the default implementation `method` avoids scoring.
@@ -929,7 +893,6 @@ Separator to use when parsing the input. If set to " " (a single blank space), w
`method`::
The internal query-building implementation: `termsFilter`, `booleanQuery`, `automaton`, or `docValuesTermsFilter`. Defaults to `termsFilter`.
-
*Examples*
[source,text]
@@ -942,7 +905,6 @@ The internal query-building implementation: `termsFilter`, `booleanQuery`, `auto
{!terms f=categoryId method=booleanQuery separator=" "}8 6 7 5309
----
-[[OtherParsers-XMLQueryParser]]
== XML Query Parser
The {solr-javadocs}/solr-core/org/apache/solr/search/XmlQParserPlugin.html[XmlQParserPlugin] extends the {solr-javadocs}/solr-core/org/apache/solr/search/QParserPlugin.html[QParserPlugin] and supports the creation of queries from XML. Example:
@@ -1002,7 +964,6 @@ The XmlQParser implementation uses the {solr-javadocs}/solr-core/org/apache/solr
|<LegacyNumericRangeQuery> |LegacyNumericRangeQuery(Builder) is deprecated
|===
-[[OtherParsers-CustomizingXMLQueryParser]]
=== Customizing XML Query Parser
You can configure your own custom query builders for additional XML elements. The custom builders need to extend the {solr-javadocs}/solr-core/org/apache/solr/search/SolrQueryBuilder.html[SolrQueryBuilder] or the {solr-javadocs}/solr-core/org/apache/solr/search/SolrSpanQueryBuilder.html[SolrSpanQueryBuilder] class. Example solrconfig.xml snippet:
http://git-wip-us.apache.org/repos/asf/lucene-solr/blob/8d00e53b/solr/solr-ref-guide/src/other-schema-elements.adoc
----------------------------------------------------------------------
diff --git a/solr/solr-ref-guide/src/other-schema-elements.adoc b/solr/solr-ref-guide/src/other-schema-elements.adoc
index 029cd64..cd39401 100644
--- a/solr/solr-ref-guide/src/other-schema-elements.adoc
+++ b/solr/solr-ref-guide/src/other-schema-elements.adoc
@@ -20,7 +20,6 @@
This section describes several other important elements of `schema.xml` not covered in earlier sections.
-[[OtherSchemaElements-UniqueKey]]
== Unique Key
The `uniqueKey` element specifies which field is a unique identifier for documents. Although `uniqueKey` is not required, it is nearly always warranted by your application design. For example, `uniqueKey` should be used if you will ever update a document in the index.
@@ -37,7 +36,6 @@ Schema defaults and `copyFields` cannot be used to populate the `uniqueKey` fiel
Further, the operation will fail if the `uniqueKey` field is used, but is multivalued (or inherits the multivalue-ness from the `fieldtype`). However, `uniqueKey` will continue to work, as long as the field is properly used.
-[[OtherSchemaElements-Similarity]]
== Similarity
Similarity is a Lucene class used to score a document in searching.
http://git-wip-us.apache.org/repos/asf/lucene-solr/blob/8d00e53b/solr/solr-ref-guide/src/overview-of-searching-in-solr.adoc
----------------------------------------------------------------------
diff --git a/solr/solr-ref-guide/src/overview-of-searching-in-solr.adoc b/solr/solr-ref-guide/src/overview-of-searching-in-solr.adoc
index 60ae891..4389c5f 100644
--- a/solr/solr-ref-guide/src/overview-of-searching-in-solr.adoc
+++ b/solr/solr-ref-guide/src/overview-of-searching-in-solr.adoc
@@ -54,7 +54,7 @@ Faceting makes use of fields defined when the search applications were indexed.
Solr also supports a feature called <<morelikethis.adoc#morelikethis,MoreLikeThis>>, which enables users to submit new queries that focus on particular terms returned in an earlier query. MoreLikeThis queries can make use of faceting or clustering to provide additional aid to users.
-A Solr component called a <<response-writers.adoc#response-writers,*response writer*>> manages the final presentation of the query response. Solr includes a variety of response writers, including an <<response-writers.adoc#ResponseWriters-TheStandardXMLResponseWriter,XML Response Writer>> and a <<response-writers.adoc#ResponseWriters-JSONResponseWriter,JSON Response Writer>>.
+A Solr component called a <<response-writers.adoc#response-writers,*response writer*>> manages the final presentation of the query response. Solr includes a variety of response writers, including an <<response-writers.adoc#standard-xml-response-writer,XML Response Writer>> and a <<response-writers.adoc#json-response-writer,JSON Response Writer>>.
The diagram below summarizes some key elements of the search process.
http://git-wip-us.apache.org/repos/asf/lucene-solr/blob/8d00e53b/solr/solr-ref-guide/src/pagination-of-results.adoc
----------------------------------------------------------------------
diff --git a/solr/solr-ref-guide/src/pagination-of-results.adoc b/solr/solr-ref-guide/src/pagination-of-results.adoc
index a9c8368..130a6c7 100644
--- a/solr/solr-ref-guide/src/pagination-of-results.adoc
+++ b/solr/solr-ref-guide/src/pagination-of-results.adoc
@@ -24,7 +24,7 @@ In most search applications, the "top" matching results (sorted by score, or som
In many applications the UI for these sorted results are displayed to the user in "pages" containing a fixed number of matching results, and users don't typically look at results past the first few pages worth of results.
== Basic Pagination
-In Solr, this basic paginated searching is supported using the `start` and `rows` parameters, and performance of this common behaviour can be tuned by utilizing the <<query-settings-in-solrconfig.adoc#QuerySettingsinSolrConfig-queryResultCache,`queryResultCache`>> and adjusting the <<query-settings-in-solrconfig.adoc#QuerySettingsinSolrConfig-queryResultWindowSize,`queryResultWindowSize`>> configuration options based on your expected page sizes.
+In Solr, this basic paginated searching is supported using the `start` and `rows` parameters, and performance of this common behaviour can be tuned by utilizing the <<query-settings-in-solrconfig.adoc#queryresultcache,`queryResultCache`>> and adjusting the <<query-settings-in-solrconfig.adoc#queryresultwindowsize,`queryResultWindowSize`>> configuration options based on your expected page sizes.
=== Basic Pagination Examples
@@ -103,7 +103,7 @@ There are a few important constraints to be aware of when using `cursorMark` par
* If `id` is your uniqueKey field, then sort params like `id asc` and `name asc, id desc` would both work fine, but `name asc` by itself would not
. Sorts including <<working-with-dates.adoc#working-with-dates,Date Math>> based functions that involve calculations relative to `NOW` will cause confusing results, since every document will get a new sort value on every subsequent request. This can easily result in cursors that never end, and constantly return the same documents over and over – even if the documents are never updated.
+
-In this situation, choose & re-use a fixed value for the <<working-with-dates.adoc#WorkingwithDates-NOW,`NOW` request param>> in all of your cursor requests.
+In this situation, choose & re-use a fixed value for the <<working-with-dates.adoc#now,`NOW` request param>> in all of your cursor requests.
Cursor mark values are computed based on the sort values of each document in the result, which means multiple documents with identical sort values will produce identical Cursor mark values if one of them is the last document on a page of results. In that situation, the subsequent request using that `cursorMark` would not know which of the documents with the identical mark values should be skipped. Requiring that the uniqueKey field be used as a clause in the sort criteria guarantees that a deterministic ordering will be returned, and that every `cursorMark` value will identify a unique point in the sequence of documents.
http://git-wip-us.apache.org/repos/asf/lucene-solr/blob/8d00e53b/solr/solr-ref-guide/src/performance-statistics-reference.adoc
----------------------------------------------------------------------
diff --git a/solr/solr-ref-guide/src/performance-statistics-reference.adoc b/solr/solr-ref-guide/src/performance-statistics-reference.adoc
index 50bc601..9987850 100644
--- a/solr/solr-ref-guide/src/performance-statistics-reference.adoc
+++ b/solr/solr-ref-guide/src/performance-statistics-reference.adoc
@@ -24,7 +24,7 @@ The same statistics are also exposed via the <<mbean-request-handler.adoc#mbean-
These statistics are per core. When you are running in SolrCloud mode these statistics would co-relate to each performance of an individual replica.
-== Request Handlers
+== Request Handler Statistics
=== Update Request Handler
@@ -93,7 +93,7 @@ Both Update Request Handler and Search Request Handler along with handlers like
|transaction_logs_total_size |Total size of all the TLogs created so far from the beginning of the Solr instance.
|===
-== Caches
+== Cache Statistics
=== Document Cache
http://git-wip-us.apache.org/repos/asf/lucene-solr/blob/8d00e53b/solr/solr-ref-guide/src/phonetic-matching.adoc
----------------------------------------------------------------------
diff --git a/solr/solr-ref-guide/src/phonetic-matching.adoc b/solr/solr-ref-guide/src/phonetic-matching.adoc
index 0e7c81a..6cd419c 100644
--- a/solr/solr-ref-guide/src/phonetic-matching.adoc
+++ b/solr/solr-ref-guide/src/phonetic-matching.adoc
@@ -22,11 +22,9 @@ Phonetic matching algorithms may be used to encode tokens so that two different
For overviews of and comparisons between algorithms, see http://en.wikipedia.org/wiki/Phonetic_algorithm and http://ntz-develop.blogspot.com/2011/03/phonetic-algorithms.html
-
-[[PhoneticMatching-Beider-MorsePhoneticMatching_BMPM_]]
== Beider-Morse Phonetic Matching (BMPM)
-For examples of how to use this encoding in your analyzer, see <<filter-descriptions.adoc#FilterDescriptions-Beider-MorseFilter,Beider Morse Filter>> in the Filter Descriptions section.
+For examples of how to use this encoding in your analyzer, see <<filter-descriptions.adoc#beider-morse-filter,Beider Morse Filter>> in the Filter Descriptions section.
Beider-Morse Phonetic Matching (BMPM) is a "soundalike" tool that lets you search using a new phonetic matching system. BMPM helps you search for personal names (or just surnames) in a Solr/Lucene index, and is far superior to the existing phonetic codecs, such as regular soundex, metaphone, caverphone, etc.
@@ -59,7 +57,7 @@ For more information, see here: http://stevemorse.org/phoneticinfo.htm and http:
== Daitch-Mokotoff Soundex
-To use this encoding in your analyzer, see <<filter-descriptions.adoc#FilterDescriptions-Daitch-MokotoffSoundexFilter,Daitch-Mokotoff Soundex Filter>> in the Filter Descriptions section.
+To use this encoding in your analyzer, see <<filter-descriptions.adoc#daitch-mokotoff-soundex-filter,Daitch-Mokotoff Soundex Filter>> in the Filter Descriptions section.
The Daitch-Mokotoff Soundex algorithm is a refinement of the Russel and American Soundex algorithms, yielding greater accuracy in matching especially Slavic and Yiddish surnames with similar pronunciation but differences in spelling.
@@ -76,13 +74,13 @@ For more information, see http://en.wikipedia.org/wiki/Daitch%E2%80%93Mokotoff_S
== Double Metaphone
-To use this encoding in your analyzer, see <<filter-descriptions.adoc#FilterDescriptions-DoubleMetaphoneFilter,Double Metaphone Filter>> in the Filter Descriptions section. Alternatively, you may specify `encoding="DoubleMetaphone"` with the <<filter-descriptions.adoc#FilterDescriptions-PhoneticFilter,Phonetic Filter>>, but note that the Phonetic Filter version will *not* provide the second ("alternate") encoding that is generated by the Double Metaphone Filter for some tokens.
+To use this encoding in your analyzer, see <<filter-descriptions.adoc#double-metaphone-filter,Double Metaphone Filter>> in the Filter Descriptions section. Alternatively, you may specify `encoding="DoubleMetaphone"` with the <<filter-descriptions.adoc#phonetic-filter,Phonetic Filter>>, but note that the Phonetic Filter version will *not* provide the second ("alternate") encoding that is generated by the Double Metaphone Filter for some tokens.
Encodes tokens using the double metaphone algorithm by Lawrence Philips. See the original article at http://www.drdobbs.com/the-double-metaphone-search-algorithm/184401251?pgno=2
== Metaphone
-To use this encoding in your analyzer, specify `encoding="Metaphone"` with the <<filter-descriptions.adoc#FilterDescriptions-PhoneticFilter,Phonetic Filter>>.
+To use this encoding in your analyzer, specify `encoding="Metaphone"` with the <<filter-descriptions.adoc#phonetic-filter,Phonetic Filter>>.
Encodes tokens using the Metaphone algorithm by Lawrence Philips, described in "Hanging on the Metaphone" in Computer Language, Dec. 1990.
@@ -91,7 +89,7 @@ Another reference for more information is http://www.drdobbs.com/the-double-meta
== Soundex
-To use this encoding in your analyzer, specify `encoding="Soundex"` with the <<filter-descriptions.adoc#FilterDescriptions-PhoneticFilter,Phonetic Filter>>.
+To use this encoding in your analyzer, specify `encoding="Soundex"` with the <<filter-descriptions.adoc#phonetic-filter,Phonetic Filter>>.
Encodes tokens using the Soundex algorithm, which is used to relate similar names, but can also be used as a general purpose scheme to find words with similar phonemes.
@@ -99,7 +97,7 @@ See also http://en.wikipedia.org/wiki/Soundex.
== Refined Soundex
-To use this encoding in your analyzer, specify `encoding="RefinedSoundex"` with the <<filter-descriptions.adoc#FilterDescriptions-PhoneticFilter,Phonetic Filter>>.
+To use this encoding in your analyzer, specify `encoding="RefinedSoundex"` with the <<filter-descriptions.adoc#phonetic-filter,Phonetic Filter>>.
Encodes tokens using an improved version of the Soundex algorithm.
@@ -107,7 +105,7 @@ See http://en.wikipedia.org/wiki/Soundex.
== Caverphone
-To use this encoding in your analyzer, specify `encoding="Caverphone"` with the <<filter-descriptions.adoc#FilterDescriptions-PhoneticFilter,Phonetic Filter>>.
+To use this encoding in your analyzer, specify `encoding="Caverphone"` with the <<filter-descriptions.adoc#phonetic-filter,Phonetic Filter>>.
Caverphone is an algorithm created by the Caversham Project at the University of Otago. The algorithm is optimised for accents present in the southern part of the city of Dunedin, New Zealand.
@@ -115,7 +113,7 @@ See http://en.wikipedia.org/wiki/Caverphone and the Caverphone 2.0 specification
== Kölner Phonetik a.k.a. Cologne Phonetic
-To use this encoding in your analyzer, specify `encoding="ColognePhonetic"` with the <<filter-descriptions.adoc#FilterDescriptions-PhoneticFilter,Phonetic Filter>>.
+To use this encoding in your analyzer, specify `encoding="ColognePhonetic"` with the <<filter-descriptions.adoc#phonetic-filter,Phonetic Filter>>.
The Kölner Phonetik, an algorithm published by Hans Joachim Postel in 1969, is optimized for the German language.
@@ -123,7 +121,7 @@ See http://de.wikipedia.org/wiki/K%C3%B6lner_Phonetik
== NYSIIS
-To use this encoding in your analyzer, specify `encoding="Nysiis"` with the <<filter-descriptions.adoc#FilterDescriptions-PhoneticFilter,Phonetic Filter>>.
+To use this encoding in your analyzer, specify `encoding="Nysiis"` with the <<filter-descriptions.adoc#phonetic-filter,Phonetic Filter>>.
NYSIIS is an encoding used to relate similar names, but can also be used as a general purpose scheme to find words with similar phonemes.
http://git-wip-us.apache.org/repos/asf/lucene-solr/blob/8d00e53b/solr/solr-ref-guide/src/ping.adoc
----------------------------------------------------------------------
diff --git a/solr/solr-ref-guide/src/ping.adoc b/solr/solr-ref-guide/src/ping.adoc
index d8d730d..72ba83f 100644
--- a/solr/solr-ref-guide/src/ping.adoc
+++ b/solr/solr-ref-guide/src/ping.adoc
@@ -44,7 +44,7 @@ This command will ping the core name for a response.
[source,text]
----
- http://localhost:8983/solr/<collection-name>admin/ping?wt=json&distrib=true&indent=true
+ http://localhost:8983/solr/<collection-name>/admin/ping?distrib=true
----
This command will ping all replicas of the given collection name for a response
http://git-wip-us.apache.org/repos/asf/lucene-solr/blob/8d00e53b/solr/solr-ref-guide/src/post-tool.adoc
----------------------------------------------------------------------
diff --git a/solr/solr-ref-guide/src/post-tool.adoc b/solr/solr-ref-guide/src/post-tool.adoc
index 80e74d4..1cbaa92 100644
--- a/solr/solr-ref-guide/src/post-tool.adoc
+++ b/solr/solr-ref-guide/src/post-tool.adoc
@@ -20,7 +20,7 @@
Solr includes a simple command line tool for POSTing various types of content to a Solr server.
-The tool is `bin/post`. The bin/post tool is a Unix shell script; for Windows (non-Cygwin) usage, see the <<PostTool-WindowsSupport,Windows section>> below.
+The tool is `bin/post`. The bin/post tool is a Unix shell script; for Windows (non-Cygwin) usage, see the section <<Post Tool Windows Support>> below.
To run it, open a window and enter:
@@ -31,7 +31,6 @@ bin/post -c gettingstarted example/films/films.json
This will contact the server at `localhost:8983`. Specifying the `collection/core name` is *mandatory*. The `-help` (or simply `-h`) option will output information on its usage (i.e., `bin/post -help)`.
-
== Using the bin/post Tool
Specifying either the `collection/core name` or the full update `url` is *mandatory* when using `bin/post`.
@@ -74,8 +73,7 @@ OPTIONS
...
----
-[[bin_post_examples]]
-== Examples
+== Examples Using bin/post
There are several ways to use `bin/post`. This section presents several examples.
@@ -118,7 +116,7 @@ Index a tab-separated file into `gettingstarted`:
bin/post -c signals -params "separator=%09" -type text/csv data.tsv
----
-The content type (`-type`) parameter is required to treat the file as the proper type, otherwise it will be ignored and a WARNING logged as it does not know what type of content a .tsv file is. The <<uploading-data-with-index-handlers.adoc#UploadingDatawithIndexHandlers-CSVFormattedIndexUpdates,CSV handler>> supports the `separator` parameter, and is passed through using the `-params` setting.
+The content type (`-type`) parameter is required to treat the file as the proper type, otherwise it will be ignored and a WARNING logged as it does not know what type of content a .tsv file is. The <<uploading-data-with-index-handlers.adoc#csv-formatted-index-updates,CSV handler>> supports the `separator` parameter, and is passed through using the `-params` setting.
=== Indexing JSON
@@ -161,8 +159,7 @@ Index a pdf as the user solr with password `SolrRocks`:
bin/post -u solr:SolrRocks -c gettingstarted a.pdf
----
-[[PostTool-WindowsSupport]]
-== Windows Support
+== Post Tool Windows Support
`bin/post` exists currently only as a Unix shell script, however it delegates its work to a cross-platform capable Java program. The <<SimplePostTool>> can be run directly in supported environments, including Windows.
http://git-wip-us.apache.org/repos/asf/lucene-solr/blob/8d00e53b/solr/solr-ref-guide/src/query-re-ranking.adoc
----------------------------------------------------------------------
diff --git a/solr/solr-ref-guide/src/query-re-ranking.adoc b/solr/solr-ref-guide/src/query-re-ranking.adoc
index f05af72..b633064 100644
--- a/solr/solr-ref-guide/src/query-re-ranking.adoc
+++ b/solr/solr-ref-guide/src/query-re-ranking.adoc
@@ -67,4 +67,4 @@ The `ltr` stands for Learning To Rank, please see <<learning-to-rank.adoc#learni
== Combining Ranking Queries with Other Solr Features
-The `rq` parameter and the re-ranking feature in general works well with other Solr features. For example, it can be used in conjunction with the <<collapse-and-expand-results.adoc#collapse-and-expand-results,collapse parser>> to re-rank the group heads after they've been collapsed. It also preserves the order of documents elevated by the <<the-query-elevation-component.adoc#the-query-elevation-component,elevation component>>. And it even has its own custom explain so you can see how the re-ranking scores were derived when looking at <<common-query-parameters.adoc#CommonQueryParameters-ThedebugParameter,debug information>>.
+The `rq` parameter and the re-ranking feature in general works well with other Solr features. For example, it can be used in conjunction with the <<collapse-and-expand-results.adoc#collapse-and-expand-results,collapse parser>> to re-rank the group heads after they've been collapsed. It also preserves the order of documents elevated by the <<the-query-elevation-component.adoc#the-query-elevation-component,elevation component>>. And it even has its own custom explain so you can see how the re-ranking scores were derived when looking at <<common-query-parameters.adoc#debug-parameter,debug information>>.
http://git-wip-us.apache.org/repos/asf/lucene-solr/blob/8d00e53b/solr/solr-ref-guide/src/query-screen.adoc
----------------------------------------------------------------------
diff --git a/solr/solr-ref-guide/src/query-screen.adoc b/solr/solr-ref-guide/src/query-screen.adoc
index e089f4f..3ddffc1 100644
--- a/solr/solr-ref-guide/src/query-screen.adoc
+++ b/solr/solr-ref-guide/src/query-screen.adoc
@@ -27,7 +27,7 @@ image::images/query-screen/query-top.png[image,height=400]
In this example, a query for `genre:Fantasy` was sent to a "films" collection. Defaults were used for all other options in the form, which are explained briefly in the table below, and covered in detail in later parts of this Guide.
-The response is shown to the right of the form. Requests to Solr are simply HTTP requests, and the query submitted is shown in light type above the results; if you click on this it will open a new browser window with just this request and response (without the rest of the Solr Admin UI). The rest of the response is shown in JSON, which is part of the request (see the `wt=json` part at the end).
+The response is shown to the right of the form. Requests to Solr are simply HTTP requests, and the query submitted is shown in light type above the results; if you click on this it will open a new browser window with just this request and response (without the rest of the Solr Admin UI). The rest of the response is shown in JSON, which is the default output format.
The response has at least two sections, but may have several more depending on the options chosen. The two sections it always has are the `responseHeader` and the `response`. The `responseHeader` includes the status of the search (`status`), the processing time (`QTime`), and the parameters (`params`) that were used to process the query.
@@ -54,7 +54,7 @@ fl::
Defines the fields to return for each document. You can explicitly list the stored fields, <<function-queries.adoc#function-queries,functions>>, and <<transforming-result-documents.adoc#transforming-result-documents,doc transformers>> you want to have returned by separating them with either a comma or a space.
wt::
-Specifies the Response Writer to be used to format the query response. Defaults to XML if not specified.
+Specifies the Response Writer to be used to format the query response. Defaults to JSON if not specified.
indent::
Click this button to request that the Response Writer use indentation to make the responses more readable.
http://git-wip-us.apache.org/repos/asf/lucene-solr/blob/8d00e53b/solr/solr-ref-guide/src/query-settings-in-solrconfig.adoc
----------------------------------------------------------------------
diff --git a/solr/solr-ref-guide/src/query-settings-in-solrconfig.adoc b/solr/solr-ref-guide/src/query-settings-in-solrconfig.adoc
index 1a6b315..09a8f0a 100644
--- a/solr/solr-ref-guide/src/query-settings-in-solrconfig.adoc
+++ b/solr/solr-ref-guide/src/query-settings-in-solrconfig.adoc
@@ -29,7 +29,6 @@ These settings are all configured in child elements of the `<query>` element in
</query>
----
-[[QuerySettingsinSolrConfig-Caches]]
== Caches
Solr caches are associated with a specific instance of an Index Searcher, a specific view of an index that doesn't change during the lifetime of that searcher. As long as that Index Searcher is being used, any items in its cache will be valid and available for reuse. Caching in Solr differs from caching in many other applications in that cached Solr objects do not expire after a time interval; instead, they remain valid for the lifetime of the Index Searcher.
@@ -54,7 +53,6 @@ FastLRUCache and LFUCache support `showItems` attribute. This is the number of c
Details of each cache are described below.
-[[QuerySettingsinSolrConfig-filterCache]]
=== filterCache
This cache is used by `SolrIndexSearcher` for filters (DocSets) for unordered sets of all documents that match a query. The numeric attributes control the number of entries in the cache.
@@ -71,7 +69,6 @@ Solr also uses this cache for faceting when the configuration parameter `facet.m
autowarmCount="128"/>
----
-[[QuerySettingsinSolrConfig-queryResultCache]]
=== queryResultCache
This cache holds the results of previous searches: ordered lists of document IDs (DocList) based on a query, a sort, and the range of documents requested.
@@ -87,7 +84,6 @@ The `queryResultCache` has an additional (optional) setting to limit the maximum
maxRamMB="1000"/>
----
-[[QuerySettingsinSolrConfig-documentCache]]
=== documentCache
This cache holds Lucene Document objects (the stored fields for each document). Since Lucene internal document IDs are transient, this cache is not auto-warmed. The size for the `documentCache` should always be greater than `max_results` times the `max_concurrent_queries`, to ensure that Solr does not need to refetch a document during a request. The more fields you store in your documents, the higher the memory usage of this cache will be.
@@ -100,7 +96,6 @@ This cache holds Lucene Document objects (the stored fields for each document).
autowarmCount="0"/>
----
-[[QuerySettingsinSolrConfig-UserDefinedCaches]]
=== User Defined Caches
You can also define named caches for your own application code to use. You can locate and use your cache object by name by calling the `SolrIndexSearcher` methods `getCache()`, `cacheLookup()` and `cacheInsert()`.
@@ -116,10 +111,8 @@ You can also define named caches for your own application code to use. You can l
If you want auto-warming of your cache, include a `regenerator` attribute with the fully qualified name of a class that implements `solr.search.CacheRegenerator`. You can also use the `NoOpRegenerator`, which simply repopulates the cache with old items. Define it with the `regenerator` parameter as`: regenerator="solr.NoOpRegenerator"`.
-[[QuerySettingsinSolrConfig-QuerySizingandWarming]]
== Query Sizing and Warming
-[[QuerySettingsinSolrConfig-maxBooleanClauses]]
=== maxBooleanClauses
This sets the maximum number of clauses allowed in a boolean query. This can affect range or prefix queries that expand to a query with a large number of boolean terms. If this limit is exceeded, an exception is thrown.
@@ -134,7 +127,6 @@ This sets the maximum number of clauses allowed in a boolean query. This can aff
This option modifies a global property that effects all Solr cores. If multiple `solrconfig.xml` files disagree on this property, the value at any point in time will be based on the last Solr core that was initialized.
====
-[[QuerySettingsinSolrConfig-enableLazyFieldLoading]]
=== enableLazyFieldLoading
If this parameter is set to true, then fields that are not directly requested will be loaded lazily as needed. This can boost performance if the most common queries only need a small subset of fields, especially if infrequently accessed fields are large in size.
@@ -144,7 +136,6 @@ If this parameter is set to true, then fields that are not directly requested wi
<enableLazyFieldLoading>true</enableLazyFieldLoading>
----
-[[QuerySettingsinSolrConfig-useFilterForSortedQuery]]
=== useFilterForSortedQuery
This parameter configures Solr to use a filter to satisfy a search. If the requested sort does not include "score", the `filterCache` will be checked for a filter matching the query. For most situations, this is only useful if the same search is requested often with different sort options and none of them ever use "score".
@@ -154,7 +145,6 @@ This parameter configures Solr to use a filter to satisfy a search. If the reque
<useFilterForSortedQuery>true</useFilterForSortedQuery>
----
-[[QuerySettingsinSolrConfig-queryResultWindowSize]]
=== queryResultWindowSize
Used with the `queryResultCache`, this will cache a superset of the requested number of document IDs. For example, if the a search in response to a particular query requests documents 10 through 19, and `queryWindowSize` is 50, documents 0 through 49 will be cached.
@@ -164,7 +154,6 @@ Used with the `queryResultCache`, this will cache a superset of the requested nu
<queryResultWindowSize>20</queryResultWindowSize>
----
-[[QuerySettingsinSolrConfig-queryResultMaxDocsCached]]
=== queryResultMaxDocsCached
This parameter sets the maximum number of documents to cache for any entry in the `queryResultCache`.
@@ -174,7 +163,6 @@ This parameter sets the maximum number of documents to cache for any entry in th
<queryResultMaxDocsCached>200</queryResultMaxDocsCached>
----
-[[QuerySettingsinSolrConfig-useColdSearcher]]
=== useColdSearcher
This setting controls whether search requests for which there is not a currently registered searcher should wait for a new searcher to warm up (false) or proceed immediately (true). When set to "false", requests will block until the searcher has warmed its caches.
@@ -184,7 +172,6 @@ This setting controls whether search requests for which there is not a currently
<useColdSearcher>false</useColdSearcher>
----
-[[QuerySettingsinSolrConfig-maxWarmingSearchers]]
=== maxWarmingSearchers
This parameter sets the maximum number of searchers that may be warming up in the background at any given time. Exceeding this limit will raise an error. For read-only slaves, a value of two is reasonable. Masters should probably be set a little higher.
@@ -194,10 +181,9 @@ This parameter sets the maximum number of searchers that may be warming up in th
<maxWarmingSearchers>2</maxWarmingSearchers>
----
-[[QuerySettingsinSolrConfig-Query-RelatedListeners]]
== Query-Related Listeners
-As described in the section on <<QuerySettingsinSolrConfig-Caches,Caches>>, new Index Searchers are cached. It's possible to use the triggers for listeners to perform query-related tasks. The most common use of this is to define queries to further "warm" the Index Searchers while they are starting. One benefit of this approach is that field caches are pre-populated for faster sorting.
+As described in the section on <<Caches>>, new Index Searchers are cached. It's possible to use the triggers for listeners to perform query-related tasks. The most common use of this is to define queries to further "warm" the Index Searchers while they are starting. One benefit of this approach is that field caches are pre-populated for faster sorting.
Good query selection is key with this type of listener. It's best to choose your most common and/or heaviest queries and include not just the keywords used, but any other parameters such as sorting or filtering requests.