You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@lucene.apache.org by ct...@apache.org on 2017/08/03 20:50:25 UTC
lucene-solr:jira/solr-10842: SOLR-10842: remove running-solr.adoc;
move starting solr content to installing-solr; move pages to improve flow;
final readthrough
Repository: lucene-solr
Updated Branches:
refs/heads/jira/solr-10842 0f7b6f1af -> 1cf8f149f
SOLR-10842: remove running-solr.adoc; move starting solr content to installing-solr; move pages to improve flow; final readthrough
Project: http://git-wip-us.apache.org/repos/asf/lucene-solr/repo
Commit: http://git-wip-us.apache.org/repos/asf/lucene-solr/commit/1cf8f149
Tree: http://git-wip-us.apache.org/repos/asf/lucene-solr/tree/1cf8f149
Diff: http://git-wip-us.apache.org/repos/asf/lucene-solr/diff/1cf8f149
Branch: refs/heads/jira/solr-10842
Commit: 1cf8f149f4ed2f6067ea0959abdf18ca55aca804
Parents: 0f7b6f1
Author: Cassandra Targett <ct...@apache.org>
Authored: Thu Aug 3 15:49:21 2017 -0500
Committer: Cassandra Targett <ct...@apache.org>
Committed: Thu Aug 3 15:49:21 2017 -0500
----------------------------------------------------------------------
solr/solr-ref-guide/src/a-quick-overview.adoc | 6 +-
solr/solr-ref-guide/src/getting-started.adoc | 15 +-
solr/solr-ref-guide/src/index.adoc | 11 +-
solr/solr-ref-guide/src/installing-solr.adoc | 84 +++++-
solr/solr-ref-guide/src/running-solr.adoc | 290 -------------------
.../src/solr-configuration-files.adoc | 11 +-
.../src/solr-control-script-reference.adoc | 2 +-
.../src/solr-system-requirements.adoc | 14 +-
solr/solr-ref-guide/src/solr-tutorial.adoc | 184 ++++++------
9 files changed, 208 insertions(+), 409 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/lucene-solr/blob/1cf8f149/solr/solr-ref-guide/src/a-quick-overview.adoc
----------------------------------------------------------------------
diff --git a/solr/solr-ref-guide/src/a-quick-overview.adoc b/solr/solr-ref-guide/src/a-quick-overview.adoc
index 0509928..a88e1a0 100644
--- a/solr/solr-ref-guide/src/a-quick-overview.adoc
+++ b/solr/solr-ref-guide/src/a-quick-overview.adoc
@@ -18,7 +18,7 @@
// specific language governing permissions and limitations
// under the License.
-Having had some fun with Solr, you will now learn about all the cool things it can do.
+Solr is a search server built on top of Apache Lucene, an open source, Java-based, information retrieval library. It is designed to drive powerful document retrieval applications - wherever you need to serve data to users based on their queries, Solr can work for you.
Here is a example of how Solr might be integrated into an application:
@@ -29,13 +29,11 @@ In the scenario above, Solr runs along side other server applications. For examp
Solr makes it easy to add the capability to search through the online store through the following steps:
-// TODO SOLR-10842 this needs a reconsideration - we don't have to define a schema, and we probably don't want to "deploy" before indexing
. Define a _schema_. The schema tells Solr about the contents of documents it will be indexing. In the online store example, the schema would define fields for the product name, description, price, manufacturer, and so on. Solr's schema is powerful and flexible and allows you to tailor Solr's behavior to your application. See <<documents-fields-and-schema-design.adoc#documents-fields-and-schema-design,Documents, Fields, and Schema Design>> for all the details.
-. Deploy Solr.
. Feed Solr documents for which your users will search.
. Expose search functionality in your application.
-Because Solr is based on open standards, it is highly extensible. Solr queries are RESTful, which means, in essence, that a query is a simple HTTP request URL and the response is a structured document: mainly XML, but it could also be JSON, CSV, or some other format. This means that a wide variety of clients will be able to use Solr, from other web applications to browser clients, rich client applications, and mobile devices. Any platform capable of HTTP can talk to Solr. See <<client-apis.adoc#client-apis,Client APIs>> for details on client APIs.
+Because Solr is based on open standards, it is highly extensible. Solr queries are simple HTTP request URLs and the response is a structured document: mainly JSON, but it could also be XML, CSV, or other formats. This means that a wide variety of clients will be able to use Solr, from other web applications to browser clients, rich client applications, and mobile devices. Any platform capable of HTTP can talk to Solr. See <<client-apis.adoc#client-apis,Client APIs>> for details on client APIs.
Solr offers support for the simplest keyword searching through to complex queries on multiple fields and faceted search results. <<searching.adoc#searching,Searching>> has more information about searching and queries.
http://git-wip-us.apache.org/repos/asf/lucene-solr/blob/1cf8f149/solr/solr-ref-guide/src/getting-started.adoc
----------------------------------------------------------------------
diff --git a/solr/solr-ref-guide/src/getting-started.adoc b/solr/solr-ref-guide/src/getting-started.adoc
index c1c0221..4369864 100644
--- a/solr/solr-ref-guide/src/getting-started.adoc
+++ b/solr/solr-ref-guide/src/getting-started.adoc
@@ -1,7 +1,7 @@
= Getting Started
:page-shortname: getting-started
:page-permalink: getting-started.html
-:page-children: a-quick-overview, solr-system-requirements, installing-solr, solr-configuration-files, running-solr, taking-solr-to-production, solr-upgrade-notes, upgrading-a-solr-cluster
+:page-children: a-quick-overview, solr-system-requirements, installing-solr, solr-configuration-files, solr-upgrade-notes, taking-solr-to-production, upgrading-a-solr-cluster
// 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
@@ -19,9 +19,8 @@
// specific language governing permissions and limitations
// under the License.
-Solr makes it easy for programmers to develop sophisticated, high-performance search applications with advanced features such as faceting (arranging search results in columns with numerical counts of key terms).
-
-Solr builds on Lucene, an open source Java library that provides indexing and search technology, as well as spellchecking, hit highlighting and advanced analysis/tokenization capabilities. Both Solr and Lucene are managed by the Apache Software Foundation (http://www.apache.org/[www.apache.org)].
+[.lead]
+Solr makes it easy for programmers to develop sophisticated, high-performance search applications with advanced features.
This section introduces you to the basic Solr architecture and features to help you get up and running quickly. It covers the following topics:
@@ -31,12 +30,10 @@ This section introduces you to the basic Solr architecture and features to help
<<solr-configuration-files.adoc#solr-configuration-files,Solr Configuration Files>>: Overview of the installation layout and major configuration files.
-<<running-solr.adoc#running-solr,Running Solr>>: An introduction to running Solr. Includes information on starting up the servers, adding documents, and running queries.
-
-<<taking-solr-to-production.adoc#taking-solr-to-production,Taking Solr to Production>>
+<<solr-upgrade-notes.adoc#solr-upgrade-notes,Solr Upgrade Notes>>: Information about changes made in Solr releases.
-<<solr-upgrade-notes.adoc#solr-upgrade-notes,Solr Upgrade Notes>>
+<<taking-solr-to-production.adoc#taking-solr-to-production,Taking Solr to Production>>: Detailed steps to help you install Solr as a service and take your application to production.
-<<upgrading-a-solr-cluster.adoc#upgrading-a-solr-cluster,Upgrading a Solr Cluster>>
+<<upgrading-a-solr-cluster.adoc#upgrading-a-solr-cluster,Upgrading a Solr Cluster>>: Information for upgrading a production SolrCloud cluster.
TIP: Solr includes a Quick Start tutorial which will be helpful if you are just starting out with Solr. You can find it in this Guide at <<solr-tutorial.adoc#solr-tutorial,Solr Tutorial>>.
http://git-wip-us.apache.org/repos/asf/lucene-solr/blob/1cf8f149/solr/solr-ref-guide/src/index.adoc
----------------------------------------------------------------------
diff --git a/solr/solr-ref-guide/src/index.adoc b/solr/solr-ref-guide/src/index.adoc
index a156a32..13cad02 100644
--- a/solr/solr-ref-guide/src/index.adoc
+++ b/solr/solr-ref-guide/src/index.adoc
@@ -1,7 +1,7 @@
= Apache Solr Reference Guide
:page-shortname: index
:page-permalink: index.html
-:page-children: about-this-guide, solr-tutorial, getting-started, using-the-solr-administration-user-interface, documents-fields-and-schema-design, understanding-analyzers-tokenizers-and-filters, indexing-and-basic-data-operations, searching, the-well-configured-solr-instance, managing-solr, solrcloud, legacy-scaling-and-distribution, client-apis, major-changes-from-solr-5-to-solr-6, further-assistance, solr-glossary, errata, how-to-contribute
+:page-children: about-this-guide, solr-tutorial, getting-started, solr-control-script-reference, using-the-solr-administration-user-interface, documents-fields-and-schema-design, understanding-analyzers-tokenizers-and-filters, indexing-and-basic-data-operations, searching, the-well-configured-solr-instance, managing-solr, solrcloud, legacy-scaling-and-distribution, client-apis, major-changes-from-solr-5-to-solr-6, further-assistance, solr-glossary, errata, how-to-contribute
// 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
@@ -19,12 +19,17 @@
// specific language governing permissions and limitations
// under the License.
-This reference guide describes Apache Solr, the open source solution for search. You can download Apache Solr from the Solr website at http://lucene.apache.org/solr/.
+[.lead]
+This reference guide describes Apache Solr, the open source solution for search.
-This Guide contains the following sections:
+Solr builds on Lucene, an open source Java library that provides indexing and search technology, as well as spellchecking, hit highlighting and advanced analysis/tokenization capabilities. Both Solr and Lucene are managed by the Apache Software Foundation (http://www.apache.org/[www.apache.org)]. You can download Apache Solr from the Solr website at http://lucene.apache.org/solr/.
+
+This Guide contains the following main sections:
*<<getting-started.adoc#getting-started,Getting Started>>*: This section guides you through the installation and setup of Solr.
+*<<solr-control-script-reference#solr-control-script-reference,Solr Control Script Reference>>*: This section provides information about all of the options available to the `bin/solr` / `bin\solr.cmd` scripts, which can start and stop Solr, configure authentication, and create or remove collections and cores.
+
*<<using-the-solr-administration-user-interface.adoc#using-the-solr-administration-user-interface,Using the Solr Administration User Interface>>*: This section introduces the Solr Web-based user interface. From your browser you can view configuration files, submit queries, view logfile settings and Java environment settings, and monitor and control distributed configurations.
*<<documents-fields-and-schema-design.adoc#documents-fields-and-schema-design,Documents, Fields, and Schema Design>>*: This section describes how Solr organizes its data for indexing. It explains how a Solr schema defines the fields and field types which Solr uses to organize data within the document files it indexes.
http://git-wip-us.apache.org/repos/asf/lucene-solr/blob/1cf8f149/solr/solr-ref-guide/src/installing-solr.adoc
----------------------------------------------------------------------
diff --git a/solr/solr-ref-guide/src/installing-solr.adoc b/solr/solr-ref-guide/src/installing-solr.adoc
index 09b88ef..ca3eed0 100644
--- a/solr/solr-ref-guide/src/installing-solr.adoc
+++ b/solr/solr-ref-guide/src/installing-solr.adoc
@@ -19,9 +19,9 @@
// specific language governing permissions and limitations
// under the License.
-Installation of Solr on Unix-compatible or Windows servers is straightforward.
+Installation of Solr on Unix-compatible or Windows servers generally requires simply extracting (or, unzipping) the download package.
-This section assumes you have reviewed the <<solr-system-requirements.adoc#solr-system-requirements,Solr System Requirements>>.
+Please be sure to review the <<solr-system-requirements.adoc#solr-system-requirements,Solr System Requirements>> before starting Solr.
== Available Solr Packages
@@ -60,7 +60,7 @@ cd ~/
tar zxf solr-{solr-docs-version}.0.tgz
----
-Once extracted, you are now ready to run Solr using the instructions provided in the <<running-solr.adoc#running-solr,Running Solr>> section.
+Once extracted, you are now ready to run Solr using the instructions provided in the <<Starting Solr>> section below.
== Directory Layout
@@ -103,7 +103,7 @@ This directory is where the heart of the Solr application resides. A README in t
== Solr Examples
-Solr includes a set of example documents and configurations to use when getting started. If you ran through the <<solr-tutorial.adoc#solr-tutorial,Solr Tutorial>>, you have already interacted with some of these files.
+Solr includes a number of example documents and configurations to use when getting started. If you ran through the <<solr-tutorial.adoc#solr-tutorial,Solr Tutorial>>, you have already interacted with some of these files.
Here are the examples included with Solr:
@@ -118,3 +118,79 @@ The `files` directory provides a basic search UI for documents such as Word or P
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.
+
+== Starting Solr
+
+Solr includes a command line interface tool called `bin/solr` (Linux/MacOS) or `bin\solr.cmd` (Windows). This tool allows you to start and stop Solr, create cores and collections, configure authentication, and check the status of your system.
+
+To use it to start Solr you can simply enter:
+
+[source,bash]
+----
+bin/solr start
+----
+
+If you are running Windows, you can start Solr by running `bin\solr.cmd` instead.
+
+[source,plain]
+----
+bin\solr.cmd start
+----
+
+This will start Solr in the background, listening on port 8983.
+
+When you start Solr in the background, the script will wait to make sure Solr starts correctly before returning to the command line prompt.
+
+TIP: All of the options for the Solr CLI are described in the section <<solr-control-script-reference.adoc#solr-control-script-reference,Solr Control Script Reference>>.
+
+=== Start Solr with a Specific Bundled Example
+
+Solr also provides a number of useful examples to help you learn about key features. You can launch the examples using the `-e` flag. For instance, to launch the "techproducts" example, you would do:
+
+[source,bash]
+----
+bin/solr -e techproducts
+----
+
+Currently, the available examples you can run are: techproducts, dih, schemaless, and cloud. See the section <<solr-control-script-reference.adoc#running-with-example-configurations,Running with Example Configurations>> for details on each example.
+
+.Getting Started with SolrCloud
+NOTE: Running the `cloud` example starts Solr in <<solrcloud.adoc#solrcloud,SolrCloud>> mode. For more information on starting Solr in cloud mode, see the section <<getting-started-with-solrcloud.adoc#getting-started-with-solrcloud,Getting Started with SolrCloud>>.
+
+=== Check if Solr is Running
+
+If you're not sure if Solr is running locally, you can use the status command:
+
+[source,bash]
+----
+bin/solr status
+----
+
+This will search for running Solr instances on your computer and then gather basic information about them, such as the version and memory usage.
+
+That's it! Solr is running. If you need convincing, use a Web browser to see the Admin Console.
+
+`\http://localhost:8983/solr/`
+
+.The Solr Admin interface.
+image::images/running-solr/SolrAdminDashboard.png[image,width=900,height=456]
+
+If Solr is not running, your browser will complain that it cannot connect to the server. Check your port number and try again.
+
+=== Create a Core
+
+If you did not start Solr with an example configuration, you would need to create a core in order to be able to index and search. You can do so by running:
+
+[source,bash]
+----
+bin/solr create -c <name>
+----
+
+This will create a core that uses a data-driven schema which tries to guess the correct field type when you add documents to the index.
+
+To see all available options for creating a new core, execute:
+
+[source,bash]
+----
+bin/solr create -help
+----
http://git-wip-us.apache.org/repos/asf/lucene-solr/blob/1cf8f149/solr/solr-ref-guide/src/running-solr.adoc
----------------------------------------------------------------------
diff --git a/solr/solr-ref-guide/src/running-solr.adoc b/solr/solr-ref-guide/src/running-solr.adoc
deleted file mode 100644
index eb4a42d..0000000
--- a/solr/solr-ref-guide/src/running-solr.adoc
+++ /dev/null
@@ -1,290 +0,0 @@
-= Running Solr
-:page-shortname: running-solr
-:page-permalink: running-solr.html
-// 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.
-
-// TODO SOLR-10842 this entire page is essentially Solr Tutorial-lite...is it valuable?
-This section describes how to run Solr with an example schema, how to add documents, and how to run queries.
-
-[[RunningSolr-StarttheServer]]
-== Start the Server
-
-If you didn't start Solr after installing it, you can start it by running `bin/solr` from the Solr directory.
-
-[source,bash]
-----
-bin/solr start
-----
-
-If you are running Windows, you can start Solr by running `bin\solr.cmd` instead.
-
-[source,plain]
-----
-bin\solr.cmd start
-----
-
-This will start Solr in the background, listening on port 8983.
-
-When you start Solr in the background, the script will wait to make sure Solr starts correctly before returning to the command line prompt.
-
-The `bin/solr` and `bin\solr.cmd` scripts allow you to customize how you start Solr. Let's work through a few examples of using the `bin/solr` script (if you're running Solr on Windows, the `bin\solr.cmd` works the same as what is shown in the examples below):
-
-[[RunningSolr-SolrScriptOptions]]
-=== Solr Script Options
-
-The `bin/solr` script has several options.
-
-[[RunningSolr-ScriptHelp]]
-==== Script Help
-
-To see how to use the `bin/solr` script, execute:
-
-[source,bash]
-----
-bin/solr -help
-----
-
-For specific usage instructions for the *start* command, do:
-
-[source,bash]
-----
-bin/solr start -help
-----
-
-[[RunningSolr-StartSolrintheForeground]]
-==== Start Solr in the Foreground
-
-Since Solr is a server, it is more common to run it in the background, especially on Unix/Linux. However, to start Solr in the foreground, simply do:
-
-[source,bash]
-----
-bin/solr start -f
-----
-
-If you are running Windows, you can run:
-
-[source,plain]
-----
-bin\solr.cmd start -f
-----
-
-[[RunningSolr-StartSolrwithaDifferentPort]]
-==== Start Solr with a Different Port
-
-To change the port Solr listens on, you can use the `-p` parameter when starting, such as:
-
-[source,bash]
-----
-bin/solr start -p 8984
-----
-
-[[RunningSolr-StopSolr]]
-==== Stop Solr
-
-When running Solr in the foreground (using -f), then you can stop it using `Ctrl-c`. However, when running in the background, you should use the *stop* command, such as:
-
-[source,bash]
-----
-bin/solr stop -p 8983
-----
-
-The stop command requires you to specify the port Solr is listening on or you can use the `-all` parameter to stop all running Solr instances.
-
-[[RunningSolr-StartSolrwithaSpecificBundledExample]]
-==== Start Solr with a Specific Bundled Example
-
-Solr also provides a number of useful examples to help you learn about key features. You can launch the examples using the `-e` flag. For instance, to launch the "techproducts" example, you would do:
-
-[source,bash]
-----
-bin/solr -e techproducts
-----
-
-Currently, the available examples you can run are: techproducts, dih, schemaless, and cloud. See the section <<solr-control-script-reference.adoc#running-with-example-configurations,Running with Example Configurations>> for details on each example.
-
-.Getting Started with SolrCloud
-[NOTE]
-====
-Running the `cloud` example starts Solr in <<solrcloud.adoc#solrcloud,SolrCloud>> mode. For more information on starting Solr in cloud mode, see the section <<getting-started-with-solrcloud.adoc#getting-started-with-solrcloud,Getting Started with SolrCloud>>.
-====
-
-[[RunningSolr-CheckifSolrisRunning]]
-==== Check if Solr is Running
-
-If you're not sure if Solr is running locally, you can use the status command:
-
-[source,bash]
-----
-bin/solr status
-----
-
-This will search for running Solr instances on your computer and then gather basic information about them, such as the version and memory usage.
-
-That's it! Solr is running. If you need convincing, use a Web browser to see the Admin Console.
-
-`\http://localhost:8983/solr/`
-
-.The Solr Admin interface.
-image::images/running-solr/SolrAdminDashboard.png[image,width=900,height=456]
-
-If Solr is not running, your browser will complain that it cannot connect to the server. Check your port number and try again.
-
-[[RunningSolr-CreateaCore]]
-== Create a Core
-
-If you did not start Solr with an example configuration, you would need to create a core in order to be able to index and search. You can do so by running:
-
-[source,bash]
-----
-bin/solr create -c <name>
-----
-
-This will create a core that uses a data-driven schema which tries to guess the correct field type when you add documents to the index.
-
-To see all available options for creating a new core, execute:
-
-[source,bash]
-----
-bin/solr create -help
-----
-
-[[RunningSolr-AddDocuments]]
-== Add Documents
-
-Solr is built to find documents that match queries. Solr's schema provides an idea of how content is structured (more on the schema <<documents-fields-and-schema-design.adoc#documents-fields-and-schema-design,later>>), but without documents there is nothing to find. Solr needs input before it can do much.
-
-You may want to add a few sample documents before trying to index your own content. The Solr installation comes with different types of example documents located under the sub-directories of the `example/` directory of your installation.
-
-In the `bin/` directory is the post script, a command line tool which can be used to index different types of documents. Do not worry too much about the details for now. The <<indexing-and-basic-data-operations.adoc#indexing-and-basic-data-operations,Indexing and Basic Data Operations>> section has all the details on indexing.
-
-To see some information about the usage of `bin/post`, use the `-help` option. Windows users, see the section for <<post-tool.adoc#post-tool-windows-support,Post Tool on Windows>>.
-
-`bin/post` can post various types of content to Solr, including files in Solr's native XML and JSON formats, CSV files, a directory tree of rich documents, or even a simple short web crawl. See the examples at the end of `bin/post -help` for various commands to easily get started posting your content into Solr.
-
-Go ahead and add all the documents in some example XML files:
-
-[source,plain]
-----
-$ bin/post -c gettingstarted example/exampledocs/*.xml
-SimplePostTool version 5.0.0
-Posting files to [base] url http://localhost:8983/solr/gettingstarted/update...
-Entering auto mode. File endings considered are xml,json,csv,pdf,doc,docx,ppt,pptx,xls,xlsx,odt,odp,ods,ott,otp,ots,rtf,htm,html,txt,log
-POSTing file gb18030-example.xml (application/xml) to [base]
-POSTing file hd.xml (application/xml) to [base]
-POSTing file ipod_other.xml (application/xml) to [base]
-POSTing file ipod_video.xml (application/xml) to [base]
-POSTing file manufacturers.xml (application/xml) to [base]
-POSTing file mem.xml (application/xml) to [base]
-POSTing file money.xml (application/xml) to [base]
-POSTing file monitor.xml (application/xml) to [base]
-POSTing file monitor2.xml (application/xml) to [base]
-POSTing file mp500.xml (application/xml) to [base]
-POSTing file sd500.xml (application/xml) to [base]
-POSTing file solr.xml (application/xml) to [base]
-POSTing file utf8-example.xml (application/xml) to [base]
-POSTing file vidcard.xml (application/xml) to [base]
-14 files indexed.
-COMMITting Solr index changes to http://localhost:8983/solr/gettingstarted/update...
-Time spent: 0:00:00.153
-----
-
-That's it! Solr has indexed the documents contained in those files.
-
-[[RunningSolr-AskQuestions]]
-== Ask Questions
-
-Now that you have indexed documents, you can perform queries. The simplest way is by building a URL that includes the query parameters. This is exactly the same as building any other HTTP URL.
-
-For example, the following query searches all document fields for "video":
-
-`\http://localhost:8983/solr/gettingstarted/select?q=video`
-
-Notice how the URL includes the host name (`localhost`), the port number where the server is listening (`8983`), the application name (`solr`), the request handler for queries (`select`), and finally, the query itself (`q=video`).
-
-The results are contained in an XML document, which you can examine directly by clicking on the link above. The document contains two parts. The first part is the `responseHeader`, which contains information about the response itself. The main part of the reply is in the result tag, which contains one or more doc tags, each of which contains fields from documents that match the query. You can use standard XML transformation techniques to mold Solr's results into a form that is suitable for displaying to users. Alternatively, Solr can output the results in JSON, PHP, Ruby and even user-defined formats.
-
-Just in case you are not running Solr as you read, the following screen shot shows the result of a query (the next example, actually) as viewed in Mozilla Firefox. The top-level response contains a `lst` named `responseHeader` and a result named response. Inside result, you can see the three docs that represent the search results.
-
-.An XML response to a query.
-image::images/running-solr/solr34_responseHeader.png[image,width=600,height=634]
-
-Once you have mastered the basic idea of a query, it is easy to add enhancements to explore the query syntax. This one is the same as before but the results only contain the ID, name, and price for each returned document. If you don't specify which fields you want, all of them are returned.
-
-`\http://localhost:8983/solr/gettingstarted/select?q=video&fl=id,name,price`
-
-Here is another example which searches for "black" in the `name` field only. If you do not tell Solr which field to search, it will search default fields, as specified in the schema.
-
-`\http://localhost:8983/solr/gettingstarted/select?q=name:black`
-
-You can provide ranges for fields. The following query finds every document whose price is between $0 and $400.
-
-`\http://localhost:8983/solr/gettingstarted/select?q=price:[0%20TO%20400]&fl=id,name,price`
-
-<<faceting.adoc#faceting,Faceted browsing>> is one of Solr's key features. It allows users to narrow search results in ways that are meaningful to your application. For example, a shopping site could provide facets to narrow search results by manufacturer or price.
-
-Faceting information is returned as a third part of Solr's query response. To get a taste of this power, take a look at the following query. It adds `facet=true` and `facet.field=cat`.
-
-`\http://localhost:8983/solr/gettingstarted/select?q=price:[0%20TO%20400]&fl=id,name,price&facet=true&facet.field=cat`
-
-In addition to the familiar `responseHeader` and response from Solr, a `facet_counts` element is also present. Here is a view with the `responseHeader` and response collapsed so you can see the faceting information clearly.
-
-*An XML Response with faceting*
-
-[source,xml]
-----
-<response>
-<lst name="responseHeader">
-...
-</lst>
-<result name="response" numFound="9" start="0">
- <doc>
- <str name="id">SOLR1000</str>
- <str name="name">Solr, the Enterprise Search Server</str>
- <float name="price">0.0</float></doc>
-...
-</result>
-<lst name="facet_counts">
- <lst name="facet_queries"/>
- <lst name="facet_fields">
- <lst name="cat">
- <int name="electronics">6</int>
- <int name="memory">3</int>
- <int name="search">2</int>
- <int name="software">2</int>
- <int name="camera">1</int>
- <int name="copier">1</int>
- <int name="multifunction printer">1</int>
- <int name="music">1</int>
- <int name="printer">1</int>
- <int name="scanner">1</int>
- <int name="connector">0</int>
- <int name="currency">0</int>
- <int name="graphics card">0</int>
- <int name="hard drive">0</int>
- <int name="monitor">0</int>
- </lst>
- </lst>
- <lst name="facet_dates"/>
- <lst name="facet_ranges"/>
-</lst>
-</response>
-----
-
-The facet information shows how many of the query results have each possible value of the `cat` field. You could easily use this information to provide users with a quick way to narrow their query results. You can filter results by adding one or more filter queries to the Solr request. This request constrains documents with a category of "software".
-
-`\http://localhost:8983/solr/gettingstarted/select?q=price:0%20TO%20400&fl=id,name,price&facet=true&facet.field=cat&fq=cat:software`
http://git-wip-us.apache.org/repos/asf/lucene-solr/blob/1cf8f149/solr/solr-ref-guide/src/solr-configuration-files.adoc
----------------------------------------------------------------------
diff --git a/solr/solr-ref-guide/src/solr-configuration-files.adoc b/solr/solr-ref-guide/src/solr-configuration-files.adoc
index b4f562f..98edb93 100644
--- a/solr/solr-ref-guide/src/solr-configuration-files.adoc
+++ b/solr/solr-ref-guide/src/solr-configuration-files.adoc
@@ -18,7 +18,11 @@
// specific language governing permissions and limitations
// under the License.
-== Solr Home & Configuration Files
+Solr has several configuration files that you will interact with during your implementation.
+
+Many of these files are in XML format, although APIs that interact with configuration settings tend to accept JSON for programmatic access as needed.
+
+== Solr Home
When Solr runs, it needs access to a home directory.
When you first install Solr, your home directory is `server/solr`. However, some examples may change this location (such as, if you run `bin/solr start -e cloud`, your home directory will be `example/cloud`).
@@ -59,7 +63,10 @@ The crucial parts of the Solr home directory are shown in these examples:
data/
----
-You may see other files, but the main ones you need to know are:
+You may see other files, but the main ones you need to know are discussed in the next section.
+
+== Configuration Files
+Inside Solr's Home, you'll find these files:
* `solr.xml` specifies configuration options for your Solr server instance. For more information on `solr.xml` see <<solr-cores-and-solr-xml.adoc#solr-cores-and-solr-xml,Solr Cores and solr.xml>>.
* Per Solr Core:
http://git-wip-us.apache.org/repos/asf/lucene-solr/blob/1cf8f149/solr/solr-ref-guide/src/solr-control-script-reference.adoc
----------------------------------------------------------------------
diff --git a/solr/solr-ref-guide/src/solr-control-script-reference.adoc b/solr/solr-ref-guide/src/solr-control-script-reference.adoc
index 5888671..294adeb 100644
--- a/solr/solr-ref-guide/src/solr-control-script-reference.adoc
+++ b/solr/solr-ref-guide/src/solr-control-script-reference.adoc
@@ -25,7 +25,7 @@ You can start and stop Solr, create and delete collections or cores, perform ope
You can find the script in the `bin/` directory of your Solr installation. The `bin/solr` script makes Solr easier to work with by providing simple commands and options to quickly accomplish common goals.
-More examples of `bin/solr` in use are available throughout the Solr Reference Guide, but particularly in the sections <<running-solr.adoc#running-solr,Running Solr>> and <<getting-started-with-solrcloud.adoc#getting-started-with-solrcloud,Getting Started with SolrCloud>>.
+More examples of `bin/solr` in use are available throughout the Solr Reference Guide, but particularly in the sections <<installing-solr.adoc#starting-solr,Starting Solr>> and <<getting-started-with-solrcloud.adoc#getting-started-with-solrcloud,Getting Started with SolrCloud>>.
== Starting and Stopping
http://git-wip-us.apache.org/repos/asf/lucene-solr/blob/1cf8f149/solr/solr-ref-guide/src/solr-system-requirements.adoc
----------------------------------------------------------------------
diff --git a/solr/solr-ref-guide/src/solr-system-requirements.adoc b/solr/solr-ref-guide/src/solr-system-requirements.adoc
index 4416d53..77230c7 100644
--- a/solr/solr-ref-guide/src/solr-system-requirements.adoc
+++ b/solr/solr-ref-guide/src/solr-system-requirements.adoc
@@ -19,7 +19,9 @@
// specific language governing permissions and limitations
// under the License.
-You can install Solr in any system where a suitable Java Runtime Environment (JRE) is available, as detailed below. Currently this includes Linux, OS X, and Microsoft Windows. The instructions in this section should work for any platform, with a few exceptions for Windows as noted.
+You can install Solr in any system where a suitable Java Runtime Environment (JRE) is available, as detailed below.
+
+Currently this includes Linux, MacOS/OS X, and Microsoft Windows.
== Installation Requirements
@@ -35,16 +37,12 @@ Java(TM) SE Runtime Environment (build 1.8.0_60-b27)
Java HotSpot(TM) 64-Bit Server VM (build 25.60-b23, mixed mode)
----
-// TODO SOLR-10842 add info on Oracle vs OpenJDK?
+The exact output will vary, but you need to make sure you meet the minimum version requirement. We also recommend choosing a version that is not end-of-life from its vendor. Oracle or OpenJDK are the most tested JREs and are recommended. It's also recommended to use the latest available official release when possible.
-The exact output will vary, but you need to make sure you meet the minimum version requirement. We also recommend choosing a version that is not end-of-life from its vendor.
+Some versions of Java VM have bugs that may impact your implementation. To be sure, check the page https://wiki.apache.org/lucene-java/JavaBugs[Lucene JavaBugs].
If you don't have the required version, or if the `java` command is not found, download and install the latest version from Oracle at http://www.oracle.com/technetwork/java/javase/downloads/index.html.
=== Supported Operating Systems
-// TODO SOLR-10842 fill in OS flavors here.
-
-Solr is tested on several flavors of Linux operating systems.
-
-Tests are also run on Windows.
+Solr is tested on several versions of Linux, MacOS, and Windows.
http://git-wip-us.apache.org/repos/asf/lucene-solr/blob/1cf8f149/solr/solr-ref-guide/src/solr-tutorial.adoc
----------------------------------------------------------------------
diff --git a/solr/solr-ref-guide/src/solr-tutorial.adoc b/solr/solr-ref-guide/src/solr-tutorial.adoc
index 1730b70..c7437de 100644
--- a/solr/solr-ref-guide/src/solr-tutorial.adoc
+++ b/solr/solr-ref-guide/src/solr-tutorial.adoc
@@ -41,10 +41,12 @@ If you'd like to know more about Solr's directory layout before moving to the fi
== Exercise 1: Index Techproducts Example Data
+This exercise will walk you through how to start Solr as a two-node cluster (both nodes on the same machine) and create a collection during startup. Then you will index some sample data that ships with Solr and do some basic searches.
+
=== Launch Solr in SolrCloud Mode
To launch Solr, run: `bin/solr start -e cloud` on Unix or MacOS; `bin\solr.cmd start -e cloud` on Windows.
-This will start an interactive session that will start two Solr "servers" on your machine. This command has an option to run without prompting you for input (`-noprompt`), but we want to modify two of the defaults so we will not use that option in this example.
+This will start an interactive session that will start two Solr "servers" on your machine. This command has an option to run without prompting you for input (`-noprompt`), but we want to modify two of the defaults so we won't use that option now.
[source,subs="verbatim,attributes+"]
----
@@ -55,14 +57,14 @@ Welcome to the SolrCloud example!
This interactive session will help you launch a SolrCloud cluster on your local workstation.
To begin, how many Solr nodes would you like to run in your local cluster? (specify 1-4 nodes) [2]:
----
-The default in this case is "2", which is what we want for this example, so you can simply press kbd:[enter].
+The first prompt asks how many nodes we want to run. Note the `[2]` at the end of the last line; that is the default number of nodes. Two is what we want for this example, so you can simply press kbd:[enter].
[source,subs="verbatim,attributes+"]
----
Ok, let's start up 2 Solr nodes for your example SolrCloud cluster.
Please enter the port for node1 [8983]:
----
-This will be the port that one of our nodes runs on. Unless you know you have something else running on port 8983 on your machine, accept this default option also by pressing kbd:[enter]. If something is already using that port, you will be asked to choose another port.
+This will be the port that the first node runs on. Unless you know you have something else running on port 8983 on your machine, accept this default option also by pressing kbd:[enter]. If something is already using that port, you will be asked to choose another port.
[source,subs="verbatim,attributes+"]
----
@@ -70,7 +72,7 @@ Please enter the port for node2 [7574]:
----
This is the port the second node will run on. Again, unless you know you have something else running on port 8983 on your machine, accept this default option also by pressing kbd:[enter]. If something is already using that port, you will be asked to choose another port.
-Solr will now initialize itself and start running on those two nodes.
+Solr will now initialize itself and start running on those two nodes. The script will print the commands it uses for your reference.
[source,subs="verbatim,attributes+"]
----
@@ -96,39 +98,43 @@ Started Solr server on port 7574 (pid=35036). Happy searching!
INFO - 2017-07-27 12:28:02.835; org.apache.solr.client.solrj.impl.ZkClientClusterStateProvider; Cluster at localhost:9983 ready
----
-Notice that it has started two instances of Solr on two nodes. It prints the commands it uses for your reference. Because we are starting in SolrCloud mode, and did not define any details about an external ZooKeeper cluster, Solr launches its own ZooKeeper and connects both nodes to it.
+Notice that two instances of Solr have started on two nodes. Because we are starting in SolrCloud mode, and did not define any details about an external ZooKeeper cluster, Solr launches its own ZooKeeper and connects both nodes to it.
-After startup is complete, you'll be prompted to create a collection to use for indexing data:
+After startup is complete, you'll be prompted to create a collection to use for indexing data.
[source,subs="verbatim,attributes+"]
----
Now let's create a new collection for indexing documents in your 2-node cluster.
Please provide a name for your new collection: [gettingstarted]
----
-Here's the first place where we'll deviate from the default options. This tutorial will ask you to index some sample data included with Solr, called the "techproducts" data. Let's name our collection that so it's easy to differentiate from other collections we'll create later. Enter `techproducts` at the prompt and hit kbd:[enter].
+
+Here's the first place where we'll deviate from the default options. This tutorial will ask you to index some sample data included with Solr, called the "techproducts" data. Let's name our collection "techproducts" so it's easy to differentiate from other collections we'll create later. Enter `techproducts` at the prompt and hit kbd:[enter].
[source,subs="verbatim,attributes+"]
----
How many shards would you like to split techproducts into? [2]
----
-This is asking how you want to split your index across the two nodes. Choosing two means we will split the index relatively evenly across both nodes, which is a good way to start. Accept the default by hitting kbd:[enter].
+
+This is asking how you want to split your index across the two nodes. Choosing "2" (the default) means we will split the index relatively evenly across both nodes, which is a good way to start. Accept the default by hitting kbd:[enter].
[source,subs="verbatim,attributes+"]
----
How many replicas per shard would you like to create? [2]
----
-A replica is a copy of the index that's used for failover. Two is fine to start with here also, so accept the default again by hitting kbd:[enter].
+
+A replica is a copy of the index that's used for failover. Again, the default of "2" is fine to start with here also, so accept the default by hitting kbd:[enter].
[source,subs="verbatim,attributes+"]
----
Please choose a configuration for the techproducts collection, available options are:
_default or sample_techproducts_configs [_default]
----
-We've reached another point where we will deviate from the default option. Solr has two sample sets of configuration files (called a configSet) available out-of-the-box.
-A collection must have a configSet, which at a minimum includes the two main configuration files for Solr - the schema file (named either `managed-schema` or `schema.xml`) and `solrconfig.xml`. The question here is which configSet you would like to start with. The `_default` is a bare-bones option, but note there's one whose name includes "techproducts", the same as we named our collection. This configSet is specifically designed to support the sample data we want to use, so enter `sample_techproducts_configs` at the prompt and hit kbd:[enter].
+We've reached another point where we will deviate from the default option. Solr has two sample sets of configuration files (called a _configSet_) available out-of-the-box.
-At this point, Solr will create the collection and again output to the screen the commands it issues:
+A collection must have a configSet, which at a minimum includes the two main configuration files for Solr: the schema file (named either `managed-schema` or `schema.xml`), and `solrconfig.xml`. The question here is which configSet you would like to start with. The `_default` is a bare-bones option, but note there's one whose name includes "techproducts", the same as we named our collection. This configSet is specifically designed to support the sample data we want to use, so enter `sample_techproducts_configs` at the prompt and hit kbd:[enter].
+
+At this point, Solr will create the collection and again output to the screen the commands it issues.
[source,subs="verbatim,attributes+"]
----
@@ -165,9 +171,10 @@ Successfully set-property updateHandler.autoSoftCommit.maxTime to 3000
SolrCloud example running, please visit: http://localhost:8983/solr
----
+
*Congratulations!* Solr is ready for data!
-You can see that the Solr is running by loading the Solr Admin UI in your web browser: http://localhost:8983/solr/. This is the main starting point for administering Solr.
+You can see that Solr is running by launching the Solr Admin UI in your web browser: http://localhost:8983/solr/. This is the main starting point for administering Solr.
Solr will now be running two "nodes", one on port 7574 and one on port 8983. There is one collection created automatically, `gettingstarted`, a two shard collection, each with two replicas.
@@ -182,11 +189,11 @@ Your Solr server is up and running, but it doesn't contain any data yet, so we c
Solr includes the `bin/post` tool in order to facilitate indexing various types of documents easily. We'll use this tool for the indexing examples below.
-You'll need a command shell to run these examples, rooted in the Solr install directory; the shell from where you launched Solr works just fine.
+You'll need a command shell to run some of the following examples, rooted in the Solr install directory; the shell from where you launched Solr works just fine.
NOTE: Currently the `bin/post` tool does not have a comparable Windows script, but the underlying Java program invoked is available. We'll show examples below for Windows, but you can also see the <<post-tool.adoc#post-tool-windows-support,Windows section>> of the Post Tool documentation for more details.
-The data we will index is in the `example/exampledocs` directory. The documents are in a mix of document formats, but fortunately we can index them all at once:
+The data we will index is in the `example/exampledocs` directory. The documents are in a mix of document formats (JSON, CSV, etc.), and fortunately we can index them all at once:
.Linux/Mac
[source,subs="verbatim,attributes+"]
@@ -240,7 +247,7 @@ Now we're ready to start searching.
[[tutorial-searching]]
=== Basic Searching
-Solr can be queried via REST clients, cURL, wget, Chrome POSTMAN, etc., as well as via native clients available for many programming languages.
+Solr can be queried via REST clients, curl, wget, Chrome POSTMAN, etc., as well as via native clients available for many programming languages.
The Solr Admin UI includes a query builder interface via the Query tab for the `techproducts` collection (at http://localhost:8983/solr/#/techproducts/query). If you click the btn:[Execute Query] button without changing anything in the form, you'll get 10 documents in JSON format:
@@ -249,19 +256,21 @@ image::images/solr-quick-start/quickstart-query-screen.png[Solr Quick Start: tec
The URL sent by the Admin UI to Solr is shown in light grey near the top right of the above screenshot. If you click on it, your browser will show you the raw response.
-To use cURL, give the same URL shown in your browser in quotes on the command line:
+To use curl, give the same URL shown in your browser in quotes on the command line:
`curl "http://localhost:8983/solr/techproducts/select?indent=on&q=\*:*"`
-What's happening here is that we are using Solr's query parameter (`q`) with a special syntax that requests all documents in the index (`\*:*`). We don't get all the documents, however, because of the default for a parameter called `rows`, which you can see in the form is `10`. You can change the parameter in the UI or in the defaults if you wish.
+What's happening here is that we are using Solr's query parameter (`q`) with a special syntax that requests all documents in the index (`\*:*`). All of the documents are not returned to us, however, because of the default for a parameter called `rows`, which you can see in the form is `10`. You can change the parameter in the UI or in the defaults if you wish.
Solr has very powerful search options, and this tutorial won't be able to cover all of them. But we can cover some of the most common types of queries.
==== Search for a Single Term
-To search for a term, enter it as the `q` param value in box in the Solr Admin UI Query screen, replacing `\*:*` with the term you want to find. Enter "foundation" and hit btn:[Execute Query] again.
+To search for a term, enter it as the `q` param value in box in the Solr Admin UI Query screen, replacing `\*:*` with the term you want to find.
+
+Enter "foundation" and hit btn:[Execute Query] again.
-If you prefer cURL, enter something like this:
+If you prefer curl, enter something like this:
`curl "http://localhost:8983/solr/techproducts/select?q=foundation"`
@@ -292,13 +301,13 @@ You'll see something like this:
"price_c____l_ns":799}]
}}
-The response indicates that there are 4 hits (`"numFound":4`). We've only included one document here, but since 4 hits is lower than the `rows` parameter default of 10 to be returned, you should see all of them.
+The response indicates that there are 4 hits (`"numFound":4`). We've only included one document the above sample output, but since 4 hits is lower than the `rows` parameter default of 10 to be returned, you should see all 4 of them.
Note the `responseHeader` before the documents. This header will include the parameters you have set for the search. By default it shows only the parameters _you_ have set for this query, which in this case is only your query term.
The documents we got back include all the fields for each document that were indexed. This is, again, default behavior. If you want to restrict the fields in the response, you can use the `fl` param, which takes a comma-separated list of field names. This is one of the available fields on the query form in the Admin UI.
-Put "id" (without quotes) in the "fl" box and hit btn:[Execute Query] again. Or, to specify it with cURL:
+Put "id" (without quotes) in the "fl" box and hit btn:[Execute Query] again. Or, to specify it with curl:
`curl "http://localhost:8983/solr/techproducts/select?q=foundation&fl=id"`
@@ -306,7 +315,7 @@ You should only see the IDs of the matching records returned.
==== Field Searches
-All Solr queries look for documents using some field. Often you want to query across multiple fields at the same time, and this is what we've done so far with the "foundation" query. This is possible with the use of copy fields, which are set up already with this set of configurations. We'll cover that more later.
+All Solr queries look for documents using some field. Often you want to query across multiple fields at the same time, and this is what we've done so far with the "foundation" query. This is possible with the use of copy fields, which are set up already with this set of configurations. We'll cover copy fields a little bit more in Exercise 2.
Sometimes, though, you want to limit your query to a single field. This can make your queries more efficient and the results more relevant for users.
@@ -372,15 +381,15 @@ Update your query in the `q` field of the Admin UI so it's `cat:electronics`. No
"price_c____l_ns":9200}]
}}
-Using cURL this query would look like this:
+Using curl, this query would look like this:
`curl "http://localhost:8983/solr/techproducts/select?q=cat:electronics"`
==== Phrase Search
-To search for a multi-term phrase, enclose it in double quotes: `q="multiple terms here"`. For example, to search for "CAS latency" by entering that phrase in quotes to the `q` box in the Admin UI.
+To search for a multi-term phrase, enclose it in double quotes: `q="multiple terms here"`. For example, search for "CAS latency" by entering that phrase in quotes to the `q` box in the Admin UI.
-If you're following along with cURL, note that the space between terms must be converted to "+" in a URL, as so:
+If you're following along with curl, note that the space between terms must be converted to "+" in a URL, as so:
`curl "http://localhost:8983/solr/techproducts/select?q=\"CAS+latency\""`
@@ -436,13 +445,13 @@ You can require that a term or phrase is present by prefixing it with a `+`; con
To find documents that contain both terms "electronics" and "music", enter `+electronics +music` in the `q` box in the Admin UI Query tab.
-If you're using cURL, you must encode the `+` character because it has a reserved purpose in URLs (encoding the space character). The encoding for `+` is `%2B`:
+If you're using curl, you must encode the `+` character because it has a reserved purpose in URLs (encoding the space character). The encoding for `+` is `%2B`:
`curl "http://localhost:8983/solr/techproducts/select?q=%2Belectronics%20%2Bmusic"`
You should only get a single result.
-To search for documents that contain the term "electronics" but *don't* contain the term "music", enter `+electronics -music` in the `q` box in the Admin UI. For cURL, again, URL encode "+" as "%2B":
+To search for documents that contain the term "electronics" but *don't* contain the term "music", enter `+electronics -music` in the `q` box in the Admin UI. For curl, again, URL encode "+" as "%2B":
`curl "http://localhost:8983/solr/techproducts/select?q=%2Belectronics+-music"`
@@ -462,7 +471,7 @@ If you decide not to continue with this tutorial, the data we've indexed so far
And then create a new collection:
-`bin/solr create -c <yourCollection>`
+`bin/solr create -c <yourCollection> -s 2 -rf 2`
To stop both of the Solr nodes we started, issue the command:
@@ -472,7 +481,7 @@ For more information on start/stop and collection options with `bin/solr`, see <
== Exercise 2: Modify the Schema and Index Films Data
-This section of the tutorial will build on the last one and introduce you to the index schema and Solr's powerful faceting features.
+This exercise will build on the last one and introduce you to the index schema and Solr's powerful faceting features.
=== Restart Solr
@@ -490,23 +499,25 @@ This starts the first node. When it's done start the second node, and tell it ho
We're going to use a whole new data set in this exercise, so it would be better to have a new collection instead of trying to reuse the one we had before.
-One reason for this is we're going to use a feature in Solr called "field guessing", where Solr makes a best attempt at guessing what type of data is in a field while it's indexing it. It also creates new fields in the schema for new fields that it finds. This mode is called "Schemaless". We'll see the benefits and limitations of this approach to help you decide how and where to use it in your real application.
+One reason for this is we're going to use a feature in Solr called "field guessing", where Solr attempts to guess what type of data is in a field while it's indexing it. It also automatically creates new fields in the schema for new fields that appear in incoming documents. This mode is called "Schemaless". We'll see the benefits and limitations of this approach to help you decide how and where to use it in your real application.
-.What is a Schema and Why Do I Need One?
+.What is a "schema" and why do I need one?
[sidebar]
+****
Solr's schema is a single file (in XML) that stores the details about the fields and field types Solr is expected to understand. The schema defines not only the field or field type names, but also any modifications that should happen to a field before it is indexed. For example, if you want to ensure that a user who enters "abc" and a user who enters "ABC" can both find a document containing the term "ABC", you will want to normalize (lower-case it, in this case) "ABC" when it is indexed, and normalize the user query to be sure of a match. These rules are defined in your schema.
-+
+
Earlier in the tutorial we mentioned copy fields, which are fields made up of data that originated from other fields. You can also define dynamic fields, which use wildcards (such as `*_t` or `*_s`) to dynamically create fields of a specific field type. These types of rules are also defined in the schema.
+****
-When you initially started Solr in the first exercise, you had a choice of a configSet to use. The one you chose had a schema that was pre-defined for the data you later indexed. This time, you're going to use a configSet that has a very minimal schema and let Solr figure out from our data what fields to add.
+When you initially started Solr in the first exercise, we had a choice of a configSet to use. The one we chose had a schema that was pre-defined for the data we later indexed. This time, we're going to use a configSet that has a very minimal schema and let Solr figure out from the data what fields to add.
-The data you're going to index is related to films, so start by creating a collection named "films" that uses the `_default` configSet:
+The data you're going to index is related to movies, so start by creating a collection named "films" that uses the `_default` configSet:
`bin/solr create -c films -s 2 -rf 2`
-Whoa, wait. You didn't specify a configSet! That's fine, the `_default` is appropriately named, since it's the default and is used if you don't specify one at all.
+Whoa, wait. We didn't specify a configSet! That's fine, the `_default` is appropriately named, since it's the default and is used if you don't specify one at all.
-You did, however, set two parameters `-s` and `-rf`. Those are the number of shards to split the collection across (2) and how many replicas to create (2). This is the same as the options we chose with the interactive example from the first exercise.
+We did, however, set two parameters `-s` and `-rf`. Those are the number of shards to split the collection across (2) and how many replicas to create (2). This is equivalent to the options we had during the interactive example from the first exercise.
You should see output like:
@@ -548,24 +559,26 @@ Otherwise, though, the collection should be created. If we go to the Admin UI at
==== Preparing Schemaless for the Films Data
-There are two parallel things happening with our schema.
+There are two parallel things happening with the schema that comes with the `_default` configSet.
-First, we are using a "managed schema", which is configured to only be modified by Solr's Schema API. That means we should not hand-edit it. Solr's Schema API allows us to make changes to fields, field types, and other types of schema rules.
+First, we are using a "managed schema", which is configured to only be modified by Solr's Schema API. That means we should not hand-edit it so there isn't confusion about which edits come from which source. Solr's Schema API allows us to make changes to fields, field types, and other types of schema rules.
-Second, we are using "field guessing", which is configured in the `solrconfig.xml` file, which has most of Solr's various configuration settings. This field guessing is designed to allow us to start using Solr without having to define all the fields we think will be in our documents before trying to index them. This is why we call it "schemaless", because you can start quickly and let Solr create fields for you as it encounters fields in documents.
+Second, we are using "field guessing", which is configured in the `solrconfig.xml` file (and includes most of Solr's various configuration settings). Field guessing is designed to allow us to start using Solr without having to define all the fields we think will be in our documents before trying to index them. This is why we call it "schemaless", because you can start quickly and let Solr create fields for you as it encounters them in documents.
-Sounds great! Well, not really, there are limitations. It's a bit brute force, and if it guesses wrong, you can't change much about a field after data has been indexed without having to reindex. If we only have a few thousand documents that might not be bad, but if you have millions and millions of documents, or worse don't have access to the original data anymore, this can be a real problem.
+Sounds great! Well, not really, there are limitations. It's a bit brute force, and if it guesses wrong, you can't change much about a field after data has been indexed without having to reindex. If we only have a few thousand documents that might not be bad, but if you have millions and millions of documents, or, worse, don't have access to the original data anymore, this can be a real problem.
For these reasons, the Solr community does not recommend going to production without a schema that you have defined yourself. By this we mean that the schemaless features are fine to start with, but you should still always make sure your schema matches your expectations for how you want your data indexed and how users are going to query it.
It is possible to mix schemaless features with a defined schema. Using the Schema API, you can define a few fields that you know you want to control, and let Solr guess others that are less important or which you are confident (through testing) will be guessed to your satisfaction. That's what we're going to do here.
===== Create the "names" Field
-The films data we are going to index has a small number of fields for each movie: an ID, director name(s), film name, release date, and genre(s). If you look at one of the files in `example/films`, you'll see the first film is named _.45_, released in 2006. As the first document in the dataset, Solr is going to guess the field type based on the data in the record. If we go ahead and index this data, that first film name is going to indicate to Solr that that field type is a "float" numeric field, and will create a "name" field with a type `FloatPointField`. All data after this record will be expected to be a float.
+The films data we are going to index has a small number of fields for each movie: an ID, director name(s), film name, release date, and genre(s).
-Well, that's not going to work. We have titles like _A Mighty Wind_ and _Chicken Run_, which are strings - decidedly not numeric and not floats. What will happen is later titles will cause an error and indexing will fail. That's not a great way to start.
+If you look at one of the files in `example/films`, you'll see the first film is named _.45_, released in 2006. As the first document in the dataset, Solr is going to guess the field type based on the data in the record. If we go ahead and index this data, that first film name is going to indicate to Solr that that field type is a "float" numeric field, and will create a "name" field with a type `FloatPointField`. All data after this record will be expected to be a float.
-What we can do is set up the "name" field in Solr before we index the data to be sure that it always interprets it as a string. At the command line, enter this curl command:
+Well, that's not going to work. We have titles like _A Mighty Wind_ and _Chicken Run_, which are strings - decidedly not numeric and not floats. If we let Solr guess the "name" field is a float, what will happen is later titles will cause an error and indexing will fail. That's not going to get us very far.
+
+What we can do is set up the "name" field in Solr before we index the data to be sure Solr always interprets it as a string. At the command line, enter this curl command:
[source,bash]
curl -X POST -H 'Content-type:application/json' --data-binary '{"add-field": {"name":"name", "type":"text_general", "multiValued":false, "stored":true}}' http://localhost:8983/solr/films/schema
@@ -578,7 +591,7 @@ There's one more change to make before we start indexing.
In the first exercise when we queried the documents we had indexed, we didn't have to specify a field to search because the configuration we used was set up to copy fields into a `text` field, and that field was the default when no other field was defined in the query.
-The configuration we're using now is missing part of that configuration. We would need to define a field to search on for every one of our queries. We can, however, set up what we call a catchall field by defining a copy field that will take all data from all fields and index it into a field named `\_text_`. Let's do that now.
+The configuration we're using now doesn't have that rule. We would need to define a field to search for every query. We can, however, set up a "catchall field" by defining a copy field that will take all data from all fields and index it into a field named `\_text_`. Let's do that now.
At the command line, use the Schema API again to define a copy field:
@@ -593,7 +606,7 @@ OK, now we're ready to index the data and start playing around with it.
=== Index Sample Film Data
-The films data we will index is located in the `example/films` directory of your installation. It comes in three formats: JSON, XML and CSV. Pick one of the formats and index it into the "films" collection:
+The films data we will index is located in the `example/films` directory of your installation. It comes in three formats: JSON, XML and CSV. Pick one of the formats and index it into the "films" collection (in each example, one command is for Unix/MacOS and the other is for Windows):
.To Index JSON Format
[source,subs="verbatim,attributes+"]
@@ -619,7 +632,7 @@ bin/post -c films example/films/films.csv -params "f.genre.split=true&f.directed
C:\solr-{solr-docs-version}.0> java -jar -Dc=films -Dparams=f.genre.split=true&f.directed_by.split=true&f.genre.separator=|&f.directed_by.separator=| -Dauto example\exampledocs\post.jar example\films\*.csv
----
-Each commands includes these main parameters:
+Each command includes these main parameters:
* `-c films`: this is the Solr collection to index data to.
* `example/films/films.json` (or `films.xml` or `films.csv`): this is the path to the data file to index. You could simply supply the directory where this file resides, but since you know the format you want to index, specifying the exact file for that format is more efficient.
@@ -643,9 +656,9 @@ Time spent: 0:00:00.878
Hooray!
-If you go to the Query screen in the Admin UI for films (http://localhost:8983/solr/#/films/query) and hit kbd:[Execute Query] you should see 1100 results, with the first 10 returned to the screen.
+If you go to the Query screen in the Admin UI for films (http://localhost:8983/solr/#/films/query) and hit btn:[Execute Query] you should see 1100 results, with the first 10 returned to the screen.
-Let's do a query to see if the "catchall" field worked properly. Enter "comedy" in the `q` box and hit kbd:[Execute Query] again. You should see get 417 results. Feel free to play around with other searches before we move on to faceting.
+Let's do a query to see if the "catchall" field worked properly. Enter "comedy" in the `q` box and hit btn:[Execute Query] again. You should see get 417 results. Feel free to play around with other searches before we move on to faceting.
[[tutorial-faceting]]
=== Faceting
@@ -663,7 +676,7 @@ image::images/solr-quick-start/quickstart-admin-ui-facet-options.png[Solr Quick
To see facet counts from all documents (`q=\*:*`): turn on faceting (`facet=true`), and specify the field to facet on via the `facet.field` param. If you only want facets, and no document contents, specify `rows=0`. The `curl` command below will return facet counts for the `genre_str` field:
-`curl '\http://localhost:8983/solr/gettingstarted/select?q=*:*&rows=0&facet=true&facet.field=genre_str'`
+`curl "http://localhost:8983/solr/gettingstarted/select?q=*:*&rows=0&facet=true&facet.field=genre_str"`
In your terminal, you'll see something like:
@@ -699,7 +712,7 @@ We've truncated the output here a little bit, but in the `facet_counts` section,
If you wanted to control the number of items in a bucket, you could do something like this:
-`curl \http://localhost:8983/solr/films/select?=&q=*:*&facet.field=genre_str&facet.mincount=200&facet=on&rows=0`
+`curl "http://localhost:8983/solr/films/select?=&q=*:*&facet.field=genre_str&facet.mincount=200&facet=on&rows=0"`
You should only see 4 facets returned.
@@ -714,15 +727,17 @@ image::images/solr-quick-start/quickstart-range-facet.png[Solr Quick Start: Rang
The films data includes the release date for films, and we could use that to create date range facets, which are another common use for range facets.
+The Solr Admin UI doesn't yet support range facet options, so you will need to use curl or similar command line tool for the following examples.
+
If we construct a query that looks like this:
[source,bash]
-curl 'http://localhost:8983/solr/films/select?q=*:*&rows=0' \
+curl "http://localhost:8983/solr/films/select?q=*:*&rows=0' \
'&facet=true' \
'&facet.range=initial_release_date' \
'&facet.range.start=NOW-20YEAR' \
'&facet.range.end=NOW' \
- '&facet.range.gap=%2B1YEAR'
+ '&facet.range.gap=%2B1YEAR"
This will request all films and ask for them to be grouped by year starting with 20 years ago (our earliest release date is in 2000) and ending today. Note that this query again URL encodes a `+` as `%2B`.
@@ -779,9 +794,9 @@ In the terminal you will see:
==== Pivot Facets
-Another faceting type is pivot facets, also known as "decision trees", allowing two or more fields to be nested for all the various possible combinations. Using the example films data, pivot facets can be used to see how many of the films in the "Drama" category (the `genre_str` field) are directed by a director. Here's how to get at the raw data for this scenario:
+Another faceting type is pivot facets, also known as "decision trees", allowing two or more fields to be nested for all the various possible combinations. Using the films data, pivot facets can be used to see how many of the films in the "Drama" category (the `genre_str` field) are directed by a director. Here's how to get at the raw data for this scenario:
-`curl 'http://localhost:8983/solr/films/select?q=*:*&rows=0&facet=on&facet.pivot=genre_str,directed_by_str'`
+`curl "http://localhost:8983/solr/films/select?q=*:*&rows=0&facet=on&facet.pivot=genre_str,directed_by_str"`
This results in the following response (trimmed to just the book category output), which says out of 14 items in the "book" category, 12 are in stock and 2 are not in stock:
@@ -827,13 +842,15 @@ We've truncated this output as well - you will see a lot of genres and directors
In this exercise, we learned a little bit more about how Solr organizes data in the indexes, and how to work with the Schema API to manipulate the schema file. We also learned a bit about facets in Solr, including range facets and pivot facets. In both of these things, we've only scratched the surface of the available options. If you can dream it, it might be possible!
-Like our previous exercise, this data may not be relevant to your needs. We can clean up our work by deleting the collection:
+Like our previous exercise, this data may not be relevant to your needs. We can clean up our work by deleting the collection. To do that, issue this command at the command line:
`bin/solr delete -c films`
== Exercise 3: Index Your Own Data
-For this last exercise, you will work with a dataset you choose. This can be files on your local hard drive, a set of data you have worked with before, or maybe a sample of the data you intend to index to Solr for your production application. This exercise is intended to get you thinking about what you will need to do for your application:
+For this last exercise, work with a dataset of your choice. This can be files on your local hard drive, a set of data you have worked with before, or maybe a sample of the data you intend to index to Solr for your production application.
+
+This exercise is intended to get you thinking about what you will need to do for your application:
* What sorts of data do you need to index?
* What will you need to do to prepare Solr for your data (such as, create specific fields, set up copy fields, determine analysis rules, etc.)
@@ -842,7 +859,7 @@ For this last exercise, you will work with a dataset you choose. This can be fil
=== Create Your Own Collection
-Before you get started, create a new collection, named whatever you'd like. In this example, the collection will be named "localDocs"; replace that value with whatever name you choose.
+Before you get started, create a new collection, named whatever you'd like. In this example, the collection will be named "localDocs"; replace that name with whatever name you choose if you want to.
`./bin/solr create -c localDocs -s 2 -rf 2`
@@ -854,14 +871,14 @@ Solr has lots of ways to index data. Choose one of the approaches below and try
Local Files with bin/post::
If you have a local directory of files, the Post Tool (`bin/post`) can index a directory of files. We saw this in action in our first exercise.
-
++
We used only JSON, XML and CSV in our exercises, but the Post Tool can also handle HTML, PDF, Microsoft Office formats (such as MS Word), plain text, and more.
-
-In this example, assume there is a directory named "Documents" locally. To index it, we would issue a command like this:
-
++
+In this example, assume there is a directory named "Documents" locally. To index it, we would issue a command like this (correcting the collection name after the `-c` parameter as needed):
++
`./bin/post -c localDocs ~/Documents`
-
-You may get errors as it works through your documents. These might be caused by the field guessing, or the file type may not be supported. Indexing content such as this demonstrates the need to plan Solr for your data, which requires understanding it and perhaps also some trial & error.
++
+You may get errors as it works through your documents. These might be caused by the field guessing, or the file type may not be supported. Indexing content such as this demonstrates the need to plan Solr for your data, which requires understanding it and perhaps also some trial and error.
DataImportHandler::
Solr includes a tool called the <<uploading-structured-data-store-data-with-the-data-import-handler.adoc#uploading-structured-data-store-data-with-the-data-import-handler,Data Import Handler (DIH)>> which can connect to databases (if you have a jdbc driver), mail servers, or other structured data sources. There are several examples included for feeds, GMail, and a small HSQL database.
@@ -872,11 +889,13 @@ SolrJ::
SolrJ is a Java-based client for interacting with Solr. Use <<using-solrj.adoc#using-solrj,SolrJ>> for JVM-based languages or other <<client-apis.adoc#client-apis,Solr clients>> to programmatically create documents to send to Solr.
Documents Screen::
-Use the Admin UI <<documents-screen.adoc#documents-screen,Documents tab>> (at http://localhost:8983/solr/#/gettingstarted/documents) to paste in a document to be indexed, or select `Document Builder` from the `Document Type` dropdown to build a document one field at a time. Click on the kbd:[Submit Document] button below the form to index your document.
+Use the Admin UI <<documents-screen.adoc#documents-screen,Documents tab>> (at http://localhost:8983/solr/#/gettingstarted/documents) to paste in a document to be indexed, or select `Document Builder` from the `Document Type` dropdown to build a document one field at a time. Click on the btn:[Submit Document] button below the form to index your document.
=== Updating Data
-You may notice that even if you index content in this tutorial more than once, it does not duplicate the results found. This is because the example Solr schema (a file named either `managed-schema` or `schema.xml`) specifies a `uniqueKey` field called `id`. Whenever you POST commands to Solr to add a document with the same value for the `uniqueKey` as an existing document, it automatically replaces it for you. You can see that that has happened by looking at the values for `numDocs` and `maxDoc` in the core-specific Overview section of the Solr Admin UI.
+You may notice that even if you index content in this tutorial more than once, it does not duplicate the results found. This is because the example Solr schema (a file named either `managed-schema` or `schema.xml`) specifies a `uniqueKey` field called `id`. Whenever you POST commands to Solr to add a document with the same value for the `uniqueKey` as an existing document, it automatically replaces it for you.
+
+You can see that that has happened by looking at the values for `numDocs` and `maxDoc` in the core-specific Overview section of the Solr Admin UI.
`numDocs` represents the number of searchable documents in the index (and will be larger than the number of XML, JSON, or CSV files since some files contained more than one document). The `maxDoc` value may be larger as the `maxDoc` count includes logically deleted documents that have not yet been physically removed from the index. You can re-post the sample files over and over again as much as you want and `numDocs` will never increase, because the new documents will constantly be replacing the old.
@@ -886,7 +905,7 @@ Go ahead and edit any of the existing example data files, change some of the dat
If you need to iterate a few times to get your schema right, you may want to delete documents to clear out the collection and try again. Note, however, that merely removing documents doesn't change the underlying field definitions. Essentially, this will allow you to reindex your data after making changes to fields for your needs.
-You can delete data by POSTing a delete command to the update URL and specifying the value of the document's unique key field, or a query that matches multiple documents (be careful with that one!). Since these commands are smaller, we specify them right on the command line rather than reference a JSON or XML file.
+You can delete data by POSTing a delete command to the update URL and specifying the value of the document's unique key field, or a query that matches multiple documents (be careful with that one!). We can use `bin/post` to delete documents also if we structure the request properly.
Execute the following command to delete a specific document:
@@ -906,14 +925,16 @@ Jump ahead to the overall <<Wrapping Up,wrap up>> when you're ready to stop Solr
== Spatial Queries
-Solr has sophisticated geospatial support, including searching within a specified distance range of a given location (or within a bounding box), sorting by distance, or even boosting results by the distance. Some of the example tech products documents in `example/exampledocs/*.xml` have locations associated with them to illustrate the spatial capabilities. To run the tech products example, see the [techproducts example section](#techproducts). Spatial queries can be combined with any other types of queries, such as in this example of querying for "ipod" within 10 kilometers from San Francisco:
+Solr has sophisticated geospatial support, including searching within a specified distance range of a given location (or within a bounding box), sorting by distance, or even boosting results by the distance.
+
+Some of the example techproducts documents we indexed in Exercise 1 have locations associated with them to illustrate the spatial capabilities. To re-index this data, see <<index-the-techproducts-data,Exercise 1>>.
+
+Spatial queries can be combined with any other types of queries, such as in this example of querying for "ipod" within 10 kilometers from San Francisco:
.Spatial queries and results
image::images/solr-quick-start/quickstart-spatial.png[Solr Quick Start: spatial search]
-The URL to this example is
-<http://localhost:8983/solr/techproducts/browse?q=ipod&pt=37.7752%2C-122.4232&d=10&sfield=store&fq=%7B%21bbox%7D&queryOpts=spatial&queryOpts=spatial>,
-leveraging the `/browse` UI to show a map for each item and allow easy selection of the location to search near.
+This is from Solr's example search UI (called `/browse`), which has a nice feature to show a map for each item and allow easy selection of the location to search near. You can see this yourself by going to <http://localhost:8983/solr/techproducts/browse?q=ipod&pt=37.7752%2C-122.4232&d=10&sfield=store&fq=%7B%21bbox%7D&queryOpts=spatial&queryOpts=spatial> in a browser.
To learn more about Solr's spatial capabilities, see the section <<spatial-search.adoc#spatial-search,Spatial Search>>.
@@ -927,22 +948,7 @@ If you've run the full set of commands in this quick start guide you have done t
* Opened the admin console, used its query interface to get results
* Opened the /browse interface to explore Solr's features in a more friendly and familiar interface
-Nice work! The script (see below) to run all of these items took under two minutes! (Your run time may vary, depending on your computer's power and resources available.)
-
-Here's a Unix script for convenient copying and pasting in order to run the key commands for this quick start guide:
-
-[source,bash]
-date
-bin/solr start -e cloud -noprompt
- open http://localhost:8983/solr
- bin/post -c gettingstarted docs/
- open http://localhost:8983/solr/gettingstarted/browse
- bin/post -c gettingstarted example/exampledocs/*.xml
- bin/post -c gettingstarted example/exampledocs/books.json
- bin/post -c gettingstarted example/exampledocs/books.csv
- bin/post -c gettingstarted -d "<delete><id>SP2514N</id></delete>"
- bin/solr healthcheck -c gettingstarted
-date
+Nice work!
== Cleanup
@@ -952,4 +958,6 @@ As you work through this tutorial, you may want to stop Solr and reset the envir
== Where to next?
-This Guide will be your best resource for learning more about Solr. But Solr also has a robust community. For more information, check out the Solr website's http://lucene.apache.org/solr/resources.html[Resources page].
+This Guide will be your best resource for learning more about Solr.
+
+Solr also has a robust community made up of people happy to help you get started. For more information, check out the Solr website's http://lucene.apache.org/solr/resources.html[Resources page].