You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@lucene.apache.org by bu...@apache.org on 2012/04/12 22:53:08 UTC
svn commit: r812587 - in /websites/staging/lucene/trunk/content: ./
solr/tutorial.html
Author: buildbot
Date: Thu Apr 12 20:53:08 2012
New Revision: 812587
Log:
Staging update by buildbot for lucene
Modified:
websites/staging/lucene/trunk/content/ (props changed)
websites/staging/lucene/trunk/content/solr/tutorial.html
Propchange: websites/staging/lucene/trunk/content/
------------------------------------------------------------------------------
--- cms:source-revision (original)
+++ cms:source-revision Thu Apr 12 20:53:08 2012
@@ -1 +1 @@
-1325488
+1325509
Modified: websites/staging/lucene/trunk/content/solr/tutorial.html
==============================================================================
--- websites/staging/lucene/trunk/content/solr/tutorial.html (original)
+++ websites/staging/lucene/trunk/content/solr/tutorial.html Thu Apr 12 20:53:08 2012
@@ -226,369 +226,14 @@
<div id="main">
<h1 class="title"></h1>
- <div><!--
-
-- DO NOT MAKE SUBSTANTIVE EDITS TO THIS PAGE
--
-- This page is currently just a placeholder so that we
-- have _some_ version of the tutorial on the website.
--
-- Once 3.6 is released this page will become a simple
-- launch point linking to the canonical URLs for the
-- version specific tutorials for 3.6 and 4.x ...
--
-- https://issues.apache.org/jira/browse/SOLR-3210
--
-- If you have any substantive changes to make to the
-- contents of the tutorial, you should make them
-- to the definitive (versioned) copies in the solr
-- src tree...
--
-- https://svn.apache.org/repos/asf/lucene/dev/trunk/solr/core/src/java/doc-files/tutorial.html
-- https://svn.apache.org/repos/asf/lucene/dev/branches/branch_3x/solr/core/src/java/doc-files/tutorial.html
-
--->
-
-<!-- aparently you really can't have this div be the first
- thing on the line, it must have a space before it or
- the markdown formatter freaks out -->
-
-<div class="tutorial">
-
-<h1 id="solr-tutorial">Solr Tutorial</h1>
-<h2 id="overview">Overview</h2>
-<p>This document covers the basics of running Solr using an example
-schema, and some sample data.</p>
-<h2 id="requirements">Requirements</h2>
-<p>To follow along with this tutorial, you will need...</p>
-<ul>
-<li>
-<p>Java 1.6 or greater. Some places you can get it are from
-<a href="http://www.oracle.com/technetwork/java/javase/downloads/index.html">Oracle</a>,
-<a href="http://openjdk.java.net/">Open JDK</a>,
-<a href="http://www.ibm.com/developerworks/java/jdk/">IBM</a>, or
-<br/>
-Running <code class="inline">java -version</code> at the command line should indicate a version
-number starting with 1.6. Gnu's GCJ is not supported and does not work with Solr.</p>
-</li>
-<li>
-<p>A <a href="http://www.apache.org/dyn/closer.cgi/lucene/solr/">Solr release</a>.</p>
-</li>
-</ul>
-<h2 id="getting-started">Getting Started</h2>
-<p><em>
-Please run the browser showing this tutorial and the Solr server on the same machine so tutorial links will correctly point to your Solr server.
-</em></p>
-<p>Begin by unziping the Solr release and changing your working directory
-to be the "<code class="inline">example</code>" directory. (Note that the base directory name may vary with the version of Solr downloaded.) For example, with a shell in UNIX, Cygwin, or MacOS:</p>
-<div class="cmd">
- user:~solr$ ls
- solr-nightly.zip
- user:~solr$ unzip -q solr-nightly.zip
- user:~solr$ cd solr-nightly/example/
-</div>
-
-<p>Solr can run in any Java Servlet Container of your choice, but to simplify
-this tutorial, the example index includes a small installation of Jetty.</p>
-<p>To launch Jetty with the Solr WAR, and the example configs, just run the <code class="inline">start.jar</code> ...</p>
-<div class="cmd">
- user:~/solr/example$ java -jar start.jar
- 2009-10-23 16:42:53.816::INFO: Logging to STDERR via org.mortbay.log.StdErrLog
- 2009-10-23 16:42:53.907::INFO: jetty-6.1.26
-
- ...
-
- Oct 23, 2009 4:41:56 PM org.apache.solr.core.SolrCore registerSearcher
- INFO: [] Registered new searcher Searcher@7c3885 main
-</div>
-
-<p>This will start up the Jetty application server on port 8983, and use your terminal to display the logging information from Solr.</p>
-<p>You can see that the Solr is running by loading <a href="http://localhost:8983/solr/admin/">http://localhost:8983/solr/admin/</a> in your web browser. This is the main starting point for Administering Solr.</p>
-<h2 id="indexing-data">Indexing Data</h2>
-<p>Your Solr server is up and running, but it doesn't contain any data. You can
-modify a Solr index by POSTing XML Documents containing instructions to add (or
-update) documents, delete documents, commit pending adds and deletes, and
-optimize your index.<br />
-</p>
-<p>The <code class="inline">exampledocs</code> directory contains samples of the types of
-instructions Solr expects, as well as a java utility for posting them from the
-command line (a <code class="inline">post.sh</code> shell script is also available, but for
-this tutorial we'll use the cross-platform Java client). To try this,
-open a new terminal window, enter the exampledocs directory, and run
-"<code class="inline">java -jar post.jar</code>" on some of the XML files in that directory,
-indicating the URL of the Solr server:</p>
-<div class="cmd">
- user:~/solr/example/exampledocs$ java -jar post.jar solr.xml monitor.xml
- SimplePostTool: version 1.2
- SimplePostTool: WARNING: Make sure your XML documents are encoded in UTF-8, \
- other encodings are not currently supported
- SimplePostTool: POSTing files to http://localhost:8983/solr/update..
- SimplePostTool: POSTing file solr.xml
- SimplePostTool: POSTing file monitor.xml
- SimplePostTool: COMMITting Solr index changes..
-</div>
-
-<p>You have now indexed two documents in Solr, and committed these changes.<br />
-You can now search for "solr" using the "Make a Query" interface on the Admin screen, and you should get one result.<br />
-Clicking the "Search" button should take you to the following URL...</p>
-<p><a href="http://localhost:8983/solr/select/?q=solr&start=0&rows=10&indent=on">http://localhost:8983/solr/select/?q=solr&start=0&rows=10&indent=on</a></p>
-<p>You can index all of the sample data, using the following command (assuming your command line shell supports the *.xml notation):</p>
-<div class="cmd">
- user:~/solr/example/exampledocs$ java -jar post.jar *.xml
- SimplePostTool: version 1.2
- SimplePostTool: WARNING: Make sure your XML documents are encoded in UTF-8, \
- other encodings are not currently supported
- SimplePostTool: POSTing files to http://localhost:8983/solr/update..
- SimplePostTool: POSTing file hd.xml
- SimplePostTool: POSTing file ipod_other.xml
- SimplePostTool: POSTing file ipod_video.xml
- SimplePostTool: POSTing file mem.xml
- SimplePostTool: POSTing file monitor.xml
- SimplePostTool: POSTing file monitor2.xml
- SimplePostTool: POSTing file mp500.xml
- SimplePostTool: POSTing file sd500.xml
- SimplePostTool: POSTing file solr.xml
- SimplePostTool: POSTing file spellchecker.xml
- SimplePostTool: POSTing file utf8-example.xml
- SimplePostTool: POSTing file vidcard.xml
- SimplePostTool: COMMITting Solr index changes..
-</div>
-
-<p>...and now you can search for all sorts of things using the default <a href="http://wiki.apache.org/solr/SolrQuerySyntax">Solr Query Syntax</a> (a superset of the Lucene query syntax)...</p>
-<ul>
-<li><a href="http://localhost:8983/solr/select/?q=video">video</a></li>
-<li><a href="http://localhost:8983/solr/select/?q=name:video">name:video</a></li>
-<li><a href="http://localhost:8983/solr/select/?q=%2Bvideo+%2Bprice%3A[*+TO+400]">+video +price:[* TO 400]</a></li>
-</ul>
-<p>There are many other different ways to import your data into Solr... one can</p>
-<ul>
-<li>
-<p>Import records from a database using the
-<a href="http://wiki.apache.org/solr/DataImportHandler">Data Import Handler (DIH)</a>.</p>
-</li>
-<li>
-<p><a href="http://wiki.apache.org/solr/UpdateCSV">Load a CSV file</a> (comma separated values),
-including those exported by Excel or MySQL.</p>
-</li>
-<li>
-<p><a href="http://wiki.apache.org/solr/UpdateJSON">POST JSON documents</a></p>
-</li>
-<li>
-<p>Index binary documents such as Word and PDF with
-<a href="http://wiki.apache.org/solr/ExtractingRequestHandler">Solr Cell</a> (ExtractingRequestHandler).</p>
-</li>
-<li>
-<p>Use <a href="http://wiki.apache.org/solr/Solrj">SolrJ</a> for Java or other Solr clients to
-programatically create documents to send to Solr.</p>
-</li>
-</ul>
-<h2 id="updating-data">Updating Data</h2>
-<p>You may have noticed that even though the file <code class="inline">solr.xml</code> has now
-been POSTed to the server twice, you still only get 1 result when searching for
-"solr". This is because the example schema.xml specifies a "uniqueKey" field
-called "<code class="inline">id</code>". Whenever you POST instructions 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 <code class="inline">numDocs</code> and <code class="inline">maxDoc</code> in the
-"CORE"/searcher section of the statistics page...<br />
-</p>
-<p><a href="http://localhost:8983/solr/admin/stats.jsp">http://localhost:8983/solr/admin/stats.jsp</a></p>
-<p><em>numDocs</em> represents the number of searchable documents in the
-index (and will be larger than the number of XML files since some files
-contained more than one <code class="inline"><doc></code>). <em>maxDoc</em>
-may be larger as the maxDoc count includes logically deleted documents that
-have not yet been removed from the index. You can re-post the sample XML
-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.</p>
-<p>Go ahead and edit the existing XML files to change some of the data, and re-run
-the <code class="inline">java -jar post.jar</code> command, you'll see your changes reflected
-in subsequent searches.</p>
-<h2 id="deleting-data">Deleting Data</h2>
-<p>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 will specify them right on the command line rather than reference an XML file.</p>
-<p>Execute the following command to delete a document</p>
-<div class="cmd">
-java -Ddata=args -Dcommit=no -jar post.jar "<delete><id>SP2514N</id></delete>"
-</div>
-
-<p>Now if you go to the <a href="http://localhost:8983/solr/admin/stats.jsp">statistics</a> page and scroll down
- to the UPDATE_HANDLERS section and verify that "<code class="inline">deletesById : 1</code>"
-If you search for <a href="http://localhost:8983/solr/select?q=id:SP2514N">id:SP2514N</a> it will still be found,
- because index changes are not visible until, and a new searcher is opened. To cause
- this to happen, send a commit command to Solr (post.jar does this for you by default):</p>
-<div class="cmd">
-java -jar post.jar
-</div>
-
-<p>Now re-execute the previous search and verify that no matching documents are found. Also revisit the
-statistics page and observe the changes in both the UPDATE_HANDLERS section and the CORE section.
-Here is an example of using delete-by-query to delete anything with
- <a href="http://localhost:8983/solr/select?q=name:DDR&fl=name">DDR</a> in the name:</p>
-<div class="cmd">
-java -Ddata=args -jar post.jar "<delete><query>name:DDR</query></delete>"
-</div>
-
-<p>Commit can be an expensive operation so it's best to make many changes to an index in a batch and
- then send the commit command at the end. There is also an optimize command that does the same thing as commit,
- in addition to merging all index segments into a single segment, making it faster to search and causing any
- deleted documents to be removed. All of the update commands are documented <a href="http://wiki.apache.org/solr/UpdateXmlMessages">here</a>.</p>
-<p>To continue with the tutorial, re-add any documents you may have deleted by going to the <code class="inline">exampledocs</code> directory and executing</p>
-<div class="cmd">
-java -jar post.jar *.xml
-</div>
-
-<h2 id="querying-data">Querying Data</h2>
-<p>Searches are done via HTTP GET on the select URL with the query string in the q parameter.
-You can pass a number of optional <a href="http://wiki.apache.org/solr/StandardRequestHandler">request parameters</a>
-to the request handler to control what information is returned. For example, you can use the "fl" parameter
-to control what stored fields are returned, and if the relevancy score is returned...</p>
-<ul>
-<li><a href="http://localhost:8983/solr/select/?indent=on&q=video&fl=name,id">q=video&fl=name,id</a> (return only name and id fields) <br />
-</li>
-<li><a href="http://localhost:8983/solr/select/?indent=on&q=video&fl=name,id,score">q=video&fl=name,id,score</a> (return relevancy score as well) </li>
-<li><a href="http://localhost:8983/solr/select/?indent=on&q=video&fl=*,score">q=video&fl=*,score</a> (return all stored fields, as well as relevancy score)<br />
-</li>
-<li><a href="http://localhost:8983/solr/select/?indent=on&q=video&sort=price desc&fl=name,id,price">q=video&sort=price desc&fl=name,id,price</a> (add sort specification: sort by price descending) </li>
-<li><a href="http://localhost:8983/solr/select/?indent=on&q=video&wt=json">q=video&wt=json</a> (return response in JSON format)<br />
-</li>
-</ul>
-<p>Solr provides a <a href="http://localhost:8983/solr/admin/form.jsp">query form</a> within the web admin interface
-that allows setting the various request parameters and is useful when trying out or debugging queries.</p>
-<h2 id="sorting">Sorting</h2>
-<p>Solr provides a simple method to sort on one or more indexed fields.
- Use the 'sort' parameter to specify "field direction" pairs...</p>
-<ul>
-<li><a href="http://localhost:8983/solr/select/?indent=on&q=video&sort=price+desc">q=video&sort=price desc</a></li>
-<li><a href="http://localhost:8983/solr/select/?indent=on&q=video&sort=price+asc">q=video&sort=price asc</a></li>
-<li><a href="http://localhost:8983/solr/select/?indent=on&q=video&sort=inStock+asc,price+desc">q=video&sort=inStock asc, price desc</a></li>
-</ul>
-<p>"score" can also be used as a field name when specifying a sort...</p>
-<ul>
-<li><a href="http://localhost:8983/solr/select/?indent=on&q=video&sort=score+desc">q=video&sort=score desc</a></li>
-<li><a href="http://localhost:8983/solr/select/?indent=on&q=video&sort=inStock+asc,score+desc">q=video&sort=inStock asc, score desc</a></li>
-</ul>
-<p>Complex functions may also be used to sort results...</p>
-<ul>
-<li><a href="http://localhost:8983/solr/select/?indent=on&q=video&sort=div(popularity,add(price,1))+desc">q=video&sort=div(popularity,add(price,1)) desc</a></li>
-</ul>
-<p>If no sort is specified, the default is <code class="inline">score desc</code> to return the matches having the highest relevancy.</p>
-<h2 id="highlighting">Highlighting</h2>
-<p>Hit highlighting returns relevent snippets of each returned document, and highlights
-keywords from the query within those context snippets.</p>
-<p>The following example searches for <code class="inline">video card</code> and requests
-highlighting on the fields <code class="inline">name,features</code>. This causes a
-<code class="inline">highlighting</code> section to be added to the response with the
-words to highlight surrounded with <code class="inline"><em></code> (for emphasis)
-tags.</p>
-<p><a href="http://localhost:8983/solr/select/?wt=json&indent=on&q=video+card&fl=name,id&hl=true&hl.fl=name,features">...&q=video card&fl=name,id&hl=true&hl.fl=name,features</a></p>
-<p>More request parameters related to controlling highlighting may be found
-<a href="http://wiki.apache.org/solr/HighlightingParameters">here</a>.</p>
-<!-- highlighting -->
-
-<h2 id="faceted-search">Faceted Search</h2>
-<p>Faceted search takes the documents matched by a query and generates counts for various
-properties or categories. Links are usually provided that allows users to "drill down" or
-refine their search results based on the returned categories.</p>
-<p>The following example searches for all documents (<code class="inline">*:*</code>) and
-requests counts by the category field <code class="inline">cat</code>.</p>
-<p><a href="http://localhost:8983/solr/select/?wt=json&indent=on&q=*:*&fl=name&facet=true&facet.field=cat">...&q=*:*&facet=true&facet.field=cat</a></p>
-<p>Notice that although only the first 10 documents are returned in the results list,
-the facet counts generated are for the complete set of documents that match the query.</p>
-<p>We can facet multiple ways at the same time. The following example adds a facet on the
-boolean <code class="inline">inStock</code> field:</p>
-<p><a href="http://localhost:8983/solr/select/?wt=json&indent=on&q=\*:\*&fl=name&facet=true&facet.field=cat&facet.field=inStock">...&q=*:*&facet=true&facet.field=cat&facet.field=inStock</a></p>
-<p>Solr can also generate counts for arbitrary queries. The following example
-queries for <code class="inline">ipod</code> and shows prices below and above 100 by using
-range queries on the price field.</p>
-<p><a href="http://localhost:8983/solr/select/?wt=json&indent=on&q=ipod&fl=name&facet=true&facet.query=price:[0+TO+100]&facet.query=price:[100+TO+*]">...&q=ipod&facet=true&facet.query=price:[0 TO 100]&facet.query=price:[100 TO *]</a></p>
-<p>One can even facet by date ranges. This example requests counts for the manufacture date (<code class="inline">manufacturedate_dt</code> field) for each year between 2004 and 2010.</p>
-<p><a href="http://localhost:8983/solr/select/?wt=json&indent=on&q=*:*&fl=name,manufacturedate_dt&facet=true&facet.date=manufacturedate_dt&facet.date.start=2004-01-01T00:00:00Z&facet.date.end=2010-01-01T00:00:00Z&facet.date.gap=%2b1YEAR">...&q=*:*&facet=true&facet.date=manufacturedate_dt&facet.date.start=2004-01-01T00:00:00Z&facet.date.end=2010-01-01T00:00:00Z&facet.date.gap=+1YEAR</a></p>
-<p>More information on faceted search may be found on the
-<a href="http://wiki.apache.org/solr/SolrFacetingOverview">faceting overview</a>
-and
-<a href="http://wiki.apache.org/solr/SimpleFacetParameters">faceting parameters</a>
-pages.</p>
-<!-- faceted search -->
-
-<h2 id="search-ui">Search UI</h2>
-<p>Solr includes an example search interface built with velocity templating
-that demonstrates many features, including searching, faceting, highlighting,
-autocomplete, and geospatial searching. </p>
-<p>Try it out at
-<a href="http://localhost:8983/solr/browse">http://localhost:8983/solr/browse</a></p>
-<!-- Search UI -->
-
-<h2 id="text-analysis">Text Analysis</h2>
-<p>Text fields are typically indexed by breaking the field into words and applying various transformations such as
-lowercasing, removing plurals, or stemming to increase relevancy. The same text transformations are normally
-applied to any queries in order to match what is indexed.</p>
-<p>Example queries demonstrating relevancy improving transformations:</p>
-<ul>
-<li>
-<p>A search for
- <a href="http://localhost:8983/solr/select/?indent=on&q=power-shot&fl=name">power-shot</a>
- matches <code class="inline">PowerShot</code>, and
- <a href="http://localhost:8983/solr/select/?indent=on&q=adata&fl=name">adata</a>
- matches <code class="inline">A-DATA</code> due to the use of WordDelimiterFilter and LowerCaseFilter.</p>
-</li>
-<li>
-<p>A search for
- <a href="http://localhost:8983/solr/select/?indent=on&q=features:recharging&fl=name,features">features:recharging</a>
- matches <code class="inline">Rechargeable</code> due to stemming with the EnglishPorterFilter.</p>
-</li>
-<li>
-<p>A search for
- <a href="http://localhost:8983/solr/select/?indent=on&q="1 gigabyte"&fl=name">"1 gigabyte"</a>
- matches things with <code class="inline">GB</code>, and the misspelled
- <a href="http://localhost:8983/solr/select/?indent=on&q=pixima&fl=name">pixima</a>
- matches <code class="inline">Pixma</code> due to use of a SynonymFilter.</p>
-</li>
-</ul>
-<p>The <a href="http://wiki.apache.org/solr/SchemaXml">schema</a> defines
-the fields in the index and what type of analysis is applied to them. The current schema your server is using
-may be accessed via the <code class="inline">[SCHEMA]</code> link on the <a href="http://localhost:8983/solr/admin/">admin</a> page.</p>
-<p>A full description of the analysis components, Analyzers, Tokenizers, and TokenFilters
-available for use is <a href="http://wiki.apache.org/solr/AnalyzersTokenizersTokenFilters">here</a>.</p>
-<h2 id="analysis-debugging">Analysis Debugging</h2>
-<p>There is a handy <a href="http://localhost:8983/solr/admin/analysis.jsp">analysis</a>
- debugging page where you can see how a text value is broken down into words,
- and shows the resulting tokens after they pass through each filter in the chain.</p>
-<p><a href="http://localhost:8983/solr/admin/analysis.jsp?name=name&val=Canon+Power-Shot+SD500">This</a>
- shows how "<code class="inline">Canon Power-Shot SD500</code>" would be indexed as a value in the name field. Each row of
- the table shows the resulting tokens after having passed through the next TokenFilter in the Analyzer for the <code class="inline">name</code> field.
- Notice how both <code class="inline">powershot</code> and <code class="inline">power</code>, <code class="inline">shot</code> are indexed. Tokens generated at the same position
- are shown in the same column, in this case <code class="inline">shot</code> and <code class="inline">powershot</code>.</p>
-<p>Selecting <a href="http://localhost:8983/solr/admin/analysis.jsp?name=name&verbose=on&val=Canon+Power-Shot+SD500">verbose output</a>
-will show more details, such as the name of each analyzer component in the chain, token positions, and the start and end positions
-of the token in the original text.</p>
-<p>Selecting <a href="http://localhost:8983/solr/admin/analysis.jsp?name=name&highlight=on&val=Canon+Power-Shot+SD500&qval=Powershot sd-500">highlight matches</a>
-when both index and query values are provided will take the resulting terms from the query value and highlight
-all matches in the index value analysis.</p>
-<p><a href="http://localhost:8983/solr/admin/analysis.jsp?name=text&highlight=on&val=Four+score+and+seven+years+ago+our+fathers+brought+forth+on+this+continent+a+new+nation%2C+conceived+in+liberty+and+dedicated+to+the+proposition+that+all+men+are+created+equal.+&qval=liberties+and+equality">Here</a>
-is an example of stemming and stop-words at work.</p>
-<h2 id="conclusion">Conclusion</h2>
-<p>Congratulations! You successfully ran a small Solr instance, added some
-documents, and made changes to the index. You learned about queries, text
-analysis, and the Solr admin interface. You're ready to start using Solr on
-your own project! Continue on with the following steps:</p>
-<ul>
-<li>Subscribe to the Solr <a href="discussion.html">mailing lists</a>!</li>
-<li>Make a copy of the Solr example directory as a template for your project.</li>
-<li>Customize the schema and other config in solr/conf/ to meet your needs. </li>
-</ul>
-<p>Solr as a ton of other features that we haven't touched on here, including
-<a href="http://wiki.apache.org/solr/DistributedSearch">distributed search</a>
-to handle huge document collections,
-<a href="http://wiki.apache.org/solr/FunctionQuery">function queries</a>,
-<a href="http://wiki.apache.org/solr/StatsComponent">numeric field statistics</a>,
-and
-<a href="http://wiki.apache.org/solr/ClusteringComponent">search results clustering</a>.
-Explore the <a href="http://wiki.apache.org/solr/FrontPage">Solr Wiki</a> to find out
-more details about Solr's many
-<a href="features.html">features</a>.</p>
-<p>Have Fun, and we'll see you on the Solr mailing lists!</p>
-</div></div>
+ <div><p>A copy of the tutorial for each version of Solr is included
+in the documentation for that release.</p>
+<p>Copies of the tutorial for the most recent releas of each
+major branch can also be found online:</p>
+<ul>
+<li><a href="api/doc-files/tutorial.html">Solr 3.6 Tutorial</a></li>
+<li><a href="https://builds.apache.org/job/Solr-trunk/javadoc/doc-files/tutorial.html">Solr 4x trunk tutorial (unreleased, for developers only)</a></li>
+</ul></div>