You are viewing a plain text version of this content. The canonical link for it is here.
Posted to solr-commits@lucene.apache.org by yo...@apache.org on 2009/10/25 22:59:38 UTC
svn commit: r829663 - in /lucene/solr/trunk: site/tutorial.html
site/tutorial.pdf src/site/src/documentation/content/xdocs/tutorial.xml
Author: yonik
Date: Sun Oct 25 21:59:38 2009
New Revision: 829663
URL: http://svn.apache.org/viewvc?rev=829663&view=rev
Log:
docs - solr tutorial updates
Modified:
lucene/solr/trunk/site/tutorial.html
lucene/solr/trunk/site/tutorial.pdf
lucene/solr/trunk/src/site/src/documentation/content/xdocs/tutorial.xml
Modified: lucene/solr/trunk/site/tutorial.html
URL: http://svn.apache.org/viewvc/lucene/solr/trunk/site/tutorial.html?rev=829663&r1=829662&r2=829663&view=diff
==============================================================================
--- lucene/solr/trunk/site/tutorial.html (original)
+++ lucene/solr/trunk/site/tutorial.html Sun Oct 25 21:59:38 2009
@@ -5,7 +5,7 @@
<meta content="Apache Forrest" name="Generator">
<meta name="Forrest-version" content="0.8">
<meta name="Forrest-skin-name" content="lucene">
-<title>Solr tutorial (version 1.3.0.2009.08.25.11.23.42)</title>
+<title>Solr tutorial (version 1.4.0.2009.10.23.15.03.16)</title>
<link type="text/css" href="skin/basic.css" rel="stylesheet">
<link media="screen" type="text/css" href="skin/screen.css" rel="stylesheet">
<link media="print" type="text/css" href="skin/print.css" rel="stylesheet">
@@ -157,7 +157,7 @@
</div>
<div id="credit">
<hr>
- This document is for Apache Solr version 1.3.0.2009.08.25.11.23.42. If you are using a different version of Solr, please consult the documentation that was distributed with the version you are using.
+ This document is for Apache Solr version 1.4.0.2009.10.23.15.03.16. If you are using a different version of Solr, please consult the documentation that was distributed with the version you are using.
</div>
<div id="roundbottom">
<img style="display: none" class="corner" height="15" width="15" alt="" src="skin/images/rc-b-l-15-1body-2menu-3menu.png"></div>
@@ -181,7 +181,7 @@
</div>
<h1>Solr tutorial</h1>
<div id="motd-area">
- This document is for Apache Solr version 1.3.0.2009.08.25.11.23.42. If you are using a different version of Solr, please consult the documentation that was distributed with the version you are using.
+ This document is for Apache Solr version 1.4.0.2009.10.23.15.03.16. If you are using a different version of Solr, please consult the documentation that was distributed with the version you are using.
</div>
<div id="minitoc-area">
<ul class="minitoc">
@@ -214,6 +214,12 @@
</ul>
</li>
<li>
+<a href="#Highlighting">Highlighting</a>
+</li>
+<li>
+<a href="#Faceted+Search">Faceted Search</a>
+</li>
+<li>
<a href="#Text+Analysis">Text Analysis</a>
<ul class="minitoc">
<li>
@@ -247,26 +253,23 @@
<ol>
<li>Java 1.5 or greater. Some places you can get it are from
+ <a href="http://java.sun.com/j2se/downloads.html">OpenJDK</a>,
<a href="http://java.sun.com/j2se/downloads.html">Sun</a>,
- <a href="http://www-106.ibm.com/developerworks/java/jdk/">IBM</a>, or
- <a href="http://www.bea.com/jrockit/">BEA</a>.
+ <a href="http://www.ibm.com/developerworks/java/jdk/">IBM</a>, or
+ <a href="http://www.oracle.com/technology/products/jrockit/index.html">Oracle</a>.
<br>
Running <span class="codefrag">java -version</span> at the command line should indicate a version
- number starting with 1.5.
+ number starting with 1.5. Gnu's GCJ is not supported and does not work with Solr.
</li>
<li>A <a href="http://www.apache.org/dyn/closer.cgi/lucene/solr/">Solr release</a>.
</li>
-
-<li>FireFox or Mozilla is the preferred browser to view the admin pages, as
- the current stylesheet doesn't look good on Internet Explorer.
- </li>
</ol>
</div>
-<a name="N10042"></a><a name="Getting+Started"></a>
+<a name="N10043"></a><a name="Getting+Started"></a>
<h2 class="boxed">Getting Started</h2>
<div class="section">
<p>
@@ -276,33 +279,32 @@
</p>
<p>
Begin by unziping the Solr release and changing your working directory
-to be the "<span class="codefrag">example</span>" directory. (Note that the base directory name may vary with the version of Solr downloaded.)
+to be the "<span class="codefrag">example</span>" 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>
<pre class="code">
-chrish@asimov:~solr$ ls
+user:~solr$ <strong>ls</strong>
solr-nightly.zip
-chrish@asimov:~solr$ unzip -q solr-nightly.zip
-chrish@asimov:~solr$ cd solr-nightly/example/
+user:~solr$ <strong>unzip -q solr-nightly.zip</strong>
+user:~solr$ <strong>cd solr-nightly/example/</strong>
+
</pre>
<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. In order to compile JSPs, this version of Jetty requires that you run "java" from a JDK, not from a JRE.
+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 <span class="codefrag">start.jar</span> ...
</p>
<pre class="code">
-chrish@asimov:~/solr/example$ java -jar start.jar
-1 [main] INFO org.mortbay.log - Logging to org.slf4j.impl.SimpleLogger@1f436f5 via org.mortbay.log.Slf4jLog
-334 [main] INFO org.mortbay.log - Extract jar:file:/home/chrish/solr/example/webapps/solr.war!/ to /tmp/Jetty__solr/webapp
-Feb 24, 2006 5:54:52 PM org.apache.solr.servlet.SolrServlet init
-INFO: user.dir=/home/chrish/solr/example
-Feb 24, 2006 5:54:52 PM org.apache.solr.core.SolrConfig <clinit>
-INFO: Loaded Config solrconfig.xml
+user:~/solr/example$ <strong>java -jar start.jar</strong>
+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.3
...
-1656 [main] INFO org.mortbay.log - Started SelectChannelConnector @ 0.0.0.0:8983
+Oct 23, 2009 4:41:56 PM org.apache.solr.core.SolrCore registerSearcher
+INFO: [] Registered new searcher Searcher@7c3885 main
+
</pre>
<p>
This will start up the Jetty application server on port 8983, and use your terminal to display the logging information from Solr.
@@ -315,24 +317,27 @@
-<a name="N1006E"></a><a name="Indexing+Data"></a>
+<a name="N1007B"></a><a name="Indexing+Data"></a>
<h2 class="boxed">Indexing Data</h2>
<div class="section">
<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.
-</p>
-<p>
-The <span class="codefrag">exampledocs</span> directory contains samples of the types of instructions Solr expects, as well as a java utility for posting
-them from the command line (a <span class="codefrag">post.sh</span> shell script is also available, but for this tutorial we'll use the cross-platform Java
-client).
+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.
</p>
<p>
-To try this, open a new terminal window, enter the exampledocs directory, and run "<span class="codefrag">java -jar post.jar</span>" on some of the
-XML files in that directory, indicating the URL of the Solr server:
+The <span class="codefrag">exampledocs</span> directory contains samples of the types of
+instructions Solr expects, as well as a java utility for posting them from the
+command line (a <span class="codefrag">post.sh</span> shell script is also available, but for
+this tutorial we'll use the cross-platform Java client). </p>
+<p> To try this,
+open a new terminal window, enter the exampledocs directory, and run
+"<span class="codefrag">java -jar post.jar</span>" on some of the XML files in that directory,
+indicating the URL of the Solr server:
</p>
<pre class="code">
-chrish@asimov:~/solr/example/exampledocs$ java -jar post.jar solr.xml monitor.xml
+user:~/solr/example/exampledocs$ <strong>java -jar post.jar solr.xml monitor.xml</strong>
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..
@@ -347,14 +352,14 @@
</p>
<p>
-<a href="http://localhost:8983/solr/select/?stylesheet=&q=solr&version=2.1&start=0&rows=10&indent=on">http://localhost:8983/solr/select/?stylesheet=&q=solr&version=2.1&start=0&rows=10&indent=on</a>
+<a href="http://localhost:8983/solr/select/?q=solr&version=2.2&start=0&rows=10&indent=on">http://localhost:8983/solr/select/?q=solr&version=2.2&start=0&rows=10&indent=on</a>
</p>
<p>
You can index all of the sample data, using the following command (assuming your shell supports the *.xml notation):
</p>
<pre class="code">
-chrish@asimov:~/solr/example/exampledocs$ java -jar post.jar *.xml
+ user:~/solr/example/exampledocs$ <strong>java -jar post.jar *.xml</strong>
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..
@@ -373,30 +378,56 @@
SimplePostTool: COMMITting Solr index changes..
</pre>
<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> (an extension of the Lucene QueryParser)...
+ ...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/?version=2.1&indent=on&q=video">video</a>
+<a href="http://localhost:8983/solr/select/?q=video">video</a>
</li>
<li>
-<a href="http://localhost:8983/solr/select/?version=2.1&indent=on&q=name:video">name:video</a>
+<a href="http://localhost:8983/solr/select/?q=name:video">name:video</a>
</li>
<li>
-<a href="http://localhost:8983/solr/select/?version=2.1&indent=on&q=%2Bvideo+%2Bprice%3A[*+TO+400]">+video +price:[* TO 400]</a>
+<a href="http://localhost:8983/solr/select/?q=%2Bvideo+%2Bprice%3A[*+TO+400]">+video +price:[* TO 400]</a>
</li>
</ul>
+<p></p>
+<p>
+ There are many other different ways to import your data into Solr... one can
+</p>
+<ul>
+
+<li>Import records from a database using the
+ <a href="http://wiki.apache.org/solr/DataImportHandler">Data Import Handler (DIH)</a>.
+ </li>
+
+<li>
+<a href="http://wiki.apache.org/solr/UpdateCSV">Load a CSV file</a> (comma separated values),
+ including those exported by Excel or MySQL.
+ </li>
+
+<li>Index binary documents such as Word and PDF with
+ <a href="http://wiki.apache.org/solr/ExtractingRequestHandler">Solr Cell</a> (ExtractingRequestHandler).
+ </li>
+
+<li>
+ 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.
+ </li>
+
+
+</ul>
</div>
-<a name="N100B5"></a><a name="Updating+Data"></a>
+<a name="N100EB"></a><a name="Updating+Data"></a>
<h2 class="boxed">Updating Data</h2>
<div class="section">
<p>
@@ -405,23 +436,30 @@
"solr". This is because the example schema.xml specifies a "uniqueKey" field
called "<span class="codefrag">id</span>". Whenever you POST instructions to Solr to add a
document with the same value for the uniqueKey as an existing document, it
-automaticaly replaces it for you. You can see that that has happened by
+automatically replaces it for you. You can see that that has happened by
looking at the values for <span class="codefrag">numDocs</span> and <span class="codefrag">maxDoc</span> in the
-"CORE" section of the statistics page... </p>
+"CORE"/searcher section of the statistics page... </p>
<p>
<a href="http://localhost:8983/solr/admin/stats.jsp">http://localhost:8983/solr/admin/stats.jsp</a>
</p>
<p>
-numDoc should be 16 (because some of our 11 example XML files contain more than one <span class="codefrag"><doc></span>), but maxDoc 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.
+
+<strong>numDocs</strong> 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 <span class="codefrag"><doc></span>). <strong>maxDoc</strong>
+ 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 <span class="codefrag">java -jar post.jar</span> command, you'll see your changes reflected in subsequent searches.
+Go ahead and edit the existing XML files to change some of the data, and re-run
+the <span class="codefrag">java -jar post.jar</span> command, you'll see your changes reflected
+in subsequent searches.
</p>
-<a name="N100DD"></a><a name="Deleting+Data"></a>
+<a name="N10119"></a><a name="Deleting+Data"></a>
<h3 class="boxed">Deleting Data</h3>
<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
@@ -430,9 +468,9 @@
<p>Execute the following command to delete a document</p>
<pre class="code">java -Ddata=args -Dcommit=no -jar post.jar "<delete><id>SP2514N</id></delete>"</pre>
<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 "<span class="codefrag">deletesPending : 1</span>"</p>
+ to the UPDATE_HANDLERS section and verify that "<span class="codefrag">deletesById : 1</span>"</p>
<p>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 changes are flushed to disk, and a new searcher is opened. To cause
+ 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>
<pre class="code">java -jar post.jar</pre>
<p>Now re-execute the previous search and verify that no matching documents are found. Also revisit the
@@ -440,7 +478,7 @@
<p>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>
<pre class="code">java -Ddata=args -jar post.jar "<delete><query>name:DDR</query></delete>"</pre>
-<p>Commit can be a very expensive operation so it's best to make many changes to an index in a batch and
+<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>.
@@ -450,7 +488,7 @@
</div>
-<a name="N10123"></a><a name="Querying+Data"></a>
+<a name="N1015F"></a><a name="Querying+Data"></a>
<h2 class="boxed">Querying Data</h2>
<div class="section">
<p>
@@ -471,14 +509,17 @@
<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) </li>
<li>
-<a href="http://localhost:8983/solr/select/?indent=on&q=video&sort=price desc&fl=name,id">q=video&sort=price desc&fl=name,id</a> (add sort specification: sort by price descending) </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) </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>
-<a name="N10152"></a><a name="Sorting"></a>
+<a name="N10194"></a><a name="Sorting"></a>
<h3 class="boxed">Sorting</h3>
<p>
Solr provides a simple method to sort on one or more indexed fields.
@@ -514,12 +555,99 @@
</ul>
<p>
- If no sort is specified, the default is <span class="codefrag">score desc</span>, the same as in the Lucene search APIs.
+ If no sort is specified, the default is <span class="codefrag">score desc</span> to return the matches having the highest relevancy.
</p>
</div>
-<a name="N10185"></a><a name="Text+Analysis"></a>
+
+<a name="N101C7"></a><a name="Highlighting"></a>
+<h2 class="boxed">Highlighting</h2>
+<div class="section">
+<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 <span class="codefrag">video card</span> and requests
+ highlighting on the fields <span class="codefrag">name,features</span>. This causes a
+ <span class="codefrag">highlighting</span> section to be added to the response with the
+ words to highlight surrounded with <span class="codefrag"><em></span> (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>
+</div> <!-- highlighting -->
+
+
+
+<a name="N101F0"></a><a name="Faceted+Search"></a>
+<h2 class="boxed">Faceted Search</h2>
+<div class="section">
+<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 (<span class="codefrag">*:*</span>) and
+ requests counts by the category field <span class="codefrag">cat</span>.
+ </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 multile ways at the same time. The following example adds in a facet on the
+ boolean <span class="codefrag">inStock</span> 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 <span class="codefrag">ipod</span> 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 (<span class="codefrag">manufacturedate_dt</span> 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>
+</div> <!-- faceted search -->
+
+
+
+<a name="N10241"></a><a name="Text+Analysis"></a>
<h2 class="boxed">Text Analysis</h2>
<div class="section">
<p>
@@ -539,16 +667,14 @@
<li>A search for
- <a href="http://localhost:8983/solr/select/?indent=on&q=name:printers&fl=name">name:printers</a>
- matches <span class="codefrag">Printer</span>, and
<a href="http://localhost:8983/solr/select/?indent=on&q=features:recharging&fl=name,features">features:recharging</a>
matches <span class="codefrag">Rechargeable</span> due to stemming with the EnglishPorterFilter.
</li>
<li>A search for
- <a href="http://localhost:8983/solr/select/?indent=on&q=%221+gigabyte%22&fl=name">"1 gigabyte"</a>
- matches things with <span class="codefrag">GB</span>, and
+ <a href="http://localhost:8983/solr/select/?indent=on&q=%221 gigabyte%22&fl=name">"1 gigabyte"</a>
+ matches things with <span class="codefrag">GB</span>, and the misspelled
<a href="http://localhost:8983/solr/select/?indent=on&q=pixima&fl=name">pixima</a>
matches <span class="codefrag">Pixma</span> due to use of a SynonymFilter.
</li>
@@ -563,7 +689,7 @@
<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>
-<a name="N101DC"></a><a name="Analysis+Debugging"></a>
+<a name="N10291"></a><a name="Analysis+Debugging"></a>
<h3 class="boxed">Analysis Debugging</h3>
<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,
@@ -571,17 +697,17 @@
</p>
<p>
-<a href="http://localhost:8983/solr/admin/analysis.jsp?name=name&val=Canon+PowerShot+SD500">This</a>
- shows how "<span class="codefrag">Canon PowerShot SD500</span>" would be indexed as a value in the name field. Each row of
+<a href="http://localhost:8983/solr/admin/analysis.jsp?name=name&val=Canon+Power-Shot+SD500">This</a>
+ shows how "<span class="codefrag">Canon Power-Shot SD500</span>" 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 <span class="codefrag">name</span> field.
Notice how both <span class="codefrag">powershot</span> and <span class="codefrag">power</span>, <span class="codefrag">shot</span> are indexed. Tokens generated at the same position
are shown in the same column, in this case <span class="codefrag">shot</span> and <span class="codefrag">powershot</span>.
</p>
-<p>Selecting <a href="http://localhost:8983/solr/admin/analysis.jsp?name=name&verbose=on&val=Canon+PowerShot+SD500">verbose output</a>
+<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+PowerShot+SD500&qval=power-shot">highlight matches</a>
+<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>
@@ -592,11 +718,14 @@
</div>
-<a name="N1021B"></a><a name="Conclusion"></a>
+<a name="N102D0"></a><a name="Conclusion"></a>
<h2 class="boxed">Conclusion</h2>
<div class="section">
<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:
+ 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>
@@ -608,6 +737,18 @@
</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/">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>
Modified: lucene/solr/trunk/site/tutorial.pdf
URL: http://svn.apache.org/viewvc/lucene/solr/trunk/site/tutorial.pdf?rev=829663&r1=829662&r2=829663&view=diff
==============================================================================
Binary files - no diff available.
Modified: lucene/solr/trunk/src/site/src/documentation/content/xdocs/tutorial.xml
URL: http://svn.apache.org/viewvc/lucene/solr/trunk/src/site/src/documentation/content/xdocs/tutorial.xml?rev=829663&r1=829662&r2=829663&view=diff
==============================================================================
--- lucene/solr/trunk/src/site/src/documentation/content/xdocs/tutorial.xml (original)
+++ lucene/solr/trunk/src/site/src/documentation/content/xdocs/tutorial.xml Sun Oct 25 21:59:38 2009
@@ -46,18 +46,16 @@
<ol>
<li>Java 1.5 or greater. Some places you can get it are from
+ <a href="http://java.sun.com/j2se/downloads.html">OpenJDK</a>,
<a href="http://java.sun.com/j2se/downloads.html">Sun</a>,
- <a href="http://www-106.ibm.com/developerworks/java/jdk/">IBM</a>, or
- <a href="http://www.bea.com/jrockit/">BEA</a>.
+ <a href="http://www.ibm.com/developerworks/java/jdk/">IBM</a>, or
+ <a href="http://www.oracle.com/technology/products/jrockit/index.html">Oracle</a>.
<br/>
Running <code>java -version</code> at the command line should indicate a version
- number starting with 1.5.
+ number starting with 1.5. Gnu's GCJ is not supported and does not work with Solr.
</li>
<li>A <a href="http://www.apache.org/dyn/closer.cgi/lucene/solr/">Solr release</a>.
</li>
- <li>FireFox or Mozilla is the preferred browser to view the admin pages, as
- the current stylesheet doesn't look good on Internet Explorer.
- </li>
</ol>
</section>
@@ -68,35 +66,33 @@
</strong></p>
<p>
Begin by unziping the Solr release and changing your working directory
-to be the "<code>example</code>" directory. (Note that the base directory name may vary with the version of Solr downloaded.)
+to be the "<code>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>
<source>
-chrish@asimov:~solr$ ls
+user:~solr$ <strong>ls</strong>
solr-nightly.zip
-chrish@asimov:~solr$ unzip -q solr-nightly.zip
-chrish@asimov:~solr$ cd solr-nightly/example/
+user:~solr$ <strong>unzip -q solr-nightly.zip</strong>
+user:~solr$ <strong>cd solr-nightly/example/</strong>
</source>
<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. In order to compile JSPs, this version of Jetty requires that you run "java" from a JDK, not from a JRE.
+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>start.jar</code> ...
</p>
<source>
-chrish@asimov:~/solr/example$ java -jar start.jar
-1 [main] INFO org.mortbay.log - Logging to org.slf4j.impl.SimpleLogger@1f436f5 via org.mortbay.log.Slf4jLog
-334 [main] INFO org.mortbay.log - Extract jar:file:/home/chrish/solr/example/webapps/solr.war!/ to /tmp/Jetty__solr/webapp
-Feb 24, 2006 5:54:52 PM org.apache.solr.servlet.SolrServlet init
-INFO: user.dir=/home/chrish/solr/example
-Feb 24, 2006 5:54:52 PM org.apache.solr.core.SolrConfig <clinit>
-INFO: Loaded Config solrconfig.xml
+user:~/solr/example$ <strong>java -jar start.jar</strong>
+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.3
...
-1656 [main] INFO org.mortbay.log - Started SelectChannelConnector @ 0.0.0.0:8983
+Oct 23, 2009 4:41:56 PM org.apache.solr.core.SolrCore registerSearcher
+INFO: [] Registered new searcher Searcher@7c3885 main
+
</source>
<p>
This will start up the Jetty application server on port 8983, and use your terminal to display the logging information from Solr.
@@ -114,21 +110,23 @@
<title>Indexing Data</title>
<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.
-</p>
-<p>
-The <code>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>post.sh</code> shell script is also available, but for this tutorial we'll use the cross-platform Java
-client).
+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.
</p>
<p>
-To try this, open a new terminal window, enter the exampledocs directory, and run "<code>java -jar post.jar</code>" on some of the
-XML files in that directory, indicating the URL of the Solr server:
+The <code>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>post.sh</code> shell script is also available, but for
+this tutorial we'll use the cross-platform Java client). </p> <p> To try this,
+open a new terminal window, enter the exampledocs directory, and run
+"<code>java -jar post.jar</code>" on some of the XML files in that directory,
+indicating the URL of the Solr server:
</p>
<source>
-chrish@asimov:~/solr/example/exampledocs$ java -jar post.jar solr.xml monitor.xml
+user:~/solr/example/exampledocs$ <strong>java -jar post.jar solr.xml monitor.xml</strong>
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..
@@ -143,7 +141,7 @@
Clicking the "Search" button should take you to the following URL...
</p>
<p>
-<a href="http://localhost:8983/solr/select/?stylesheet=&q=solr&version=2.1&start=0&rows=10&indent=on">http://localhost:8983/solr/select/?stylesheet=&q=solr&version=2.1&start=0&rows=10&indent=on</a>
+<a href="http://localhost:8983/solr/select/?q=solr&version=2.2&start=0&rows=10&indent=on">http://localhost:8983/solr/select/?q=solr&version=2.2&start=0&rows=10&indent=on</a>
</p>
<p>
@@ -151,7 +149,7 @@
</p>
<source>
-chrish@asimov:~/solr/example/exampledocs$ java -jar post.jar *.xml
+ user:~/solr/example/exampledocs$ <strong>java -jar post.jar *.xml</strong>
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..
@@ -171,12 +169,33 @@
</source>
<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> (an extension of the Lucene QueryParser)...
+ ...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></p>
+<p>
+ There are many other different ways to import your data into Solr... one can
</p>
<ul>
- <li><a href="http://localhost:8983/solr/select/?version=2.1&indent=on&q=video">video</a></li>
- <li><a href="http://localhost:8983/solr/select/?version=2.1&indent=on&q=name:video">name:video</a></li>
- <li><a href="http://localhost:8983/solr/select/?version=2.1&indent=on&q=%2Bvideo+%2Bprice%3A[*+TO+400]">+video +price:[* TO 400]</a></li>
+ <li>Import records from a database using the
+ <a href="http://wiki.apache.org/solr/DataImportHandler">Data Import Handler (DIH)</a>.
+ </li>
+ <li><a href="http://wiki.apache.org/solr/UpdateCSV">Load a CSV file</a> (comma separated values),
+ including those exported by Excel or MySQL.
+ </li>
+ <li>Index binary documents such as Word and PDF with
+ <a href="http://wiki.apache.org/solr/ExtractingRequestHandler">Solr Cell</a> (ExtractingRequestHandler).
+ </li>
+ <li>
+ 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.
+ </li>
</ul>
@@ -193,20 +212,26 @@
"solr". This is because the example schema.xml specifies a "uniqueKey" field
called "<code>id</code>". Whenever you POST instructions to Solr to add a
document with the same value for the uniqueKey as an existing document, it
-automaticaly replaces it for you. You can see that that has happened by
+automatically replaces it for you. You can see that that has happened by
looking at the values for <code>numDocs</code> and <code>maxDoc</code> in the
-"CORE" section of the statistics page... </p>
+"CORE"/searcher section of the statistics page... </p>
<p>
<a href="http://localhost:8983/solr/admin/stats.jsp">http://localhost:8983/solr/admin/stats.jsp</a>
</p>
<p>
-numDoc should be 16 (because some of our 11 example XML files contain more than one <code><doc></code>), but maxDoc 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.
+ <strong>numDocs</strong> 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><doc></code>). <strong>maxDoc</strong>
+ 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>java -jar post.jar</code> command, you'll see your changes reflected in subsequent searches.
+Go ahead and edit the existing XML files to change some of the data, and re-run
+the <code>java -jar post.jar</code> command, you'll see your changes reflected
+in subsequent searches.
</p>
<section>
@@ -218,9 +243,9 @@
<p>Execute the following command to delete a document</p>
<source>java -Ddata=args -Dcommit=no -jar post.jar "<delete><id>SP2514N</id></delete>"</source>
<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>deletesPending : 1</code>"</p>
+ to the UPDATE_HANDLERS section and verify that "<code>deletesById : 1</code>"</p>
<p>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 changes are flushed to disk, and a new searcher is opened. To cause
+ 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>
<source>java -jar post.jar</source>
<p>Now re-execute the previous search and verify that no matching documents are found. Also revisit the
@@ -229,7 +254,7 @@
<a href="http://localhost:8983/solr/select?q=name:DDR&fl=name">DDR</a> in the name:</p>
<source>java -Ddata=args -jar post.jar "<delete><query>name:DDR</query></delete>"</source>
- <p>Commit can be a very expensive operation so it's best to make many changes to an index in a batch and
+ <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>.
@@ -256,7 +281,8 @@
<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) </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) </li>
- <li><a href="http://localhost:8983/solr/select/?indent=on&q=video&sort=price desc&fl=name,id">q=video&sort=price desc&fl=name,id</a> (add sort specification: sort by price descending) </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) </li>
</ul>
<p>
@@ -287,13 +313,94 @@
</ul>
<p>
- If no sort is specified, the default is <code>score desc</code>, the same as in the Lucene search APIs.
+ If no sort is specified, the default is <code>score desc</code> to return the matches having the highest relevancy.
</p>
</section>
</section>
+
+<section>
+ <title>Highlighting</title>
+ <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>video card</code> and requests
+ highlighting on the fields <code>name,features</code>. This causes a
+ <code>highlighting</code> section to be added to the response with the
+ words to highlight surrounded with <code><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>
+
+</section> <!-- highlighting -->
+
+
+<section>
+ <title>Faceted Search</title>
+ <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>*:*</code>) and
+ requests counts by the category field <code>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 multile ways at the same time. The following example adds in a facet on the
+ boolean <code>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>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>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>
+
+</section> <!-- faceted search -->
+
+
<section>
<title>Text Analysis</title>
@@ -313,15 +420,13 @@
</li>
<li>A search for
- <a href="http://localhost:8983/solr/select/?indent=on&q=name:printers&fl=name">name:printers</a>
- matches <code>Printer</code>, and
<a href="http://localhost:8983/solr/select/?indent=on&q=features:recharging&fl=name,features">features:recharging</a>
matches <code>Rechargeable</code> due to stemming with the EnglishPorterFilter.
</li>
<li>A search for
- <a href="http://localhost:8983/solr/select/?indent=on&q="1+gigabyte"&fl=name">"1 gigabyte"</a>
- matches things with <code>GB</code>, and
+ <a href="http://localhost:8983/solr/select/?indent=on&q="1 gigabyte"&fl=name">"1 gigabyte"</a>
+ matches things with <code>GB</code>, and the misspelled
<a href="http://localhost:8983/solr/select/?indent=on&q=pixima&fl=name">pixima</a>
matches <code>Pixma</code> due to use of a SynonymFilter.
</li>
@@ -348,17 +453,17 @@
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+PowerShot+SD500">This</a>
- shows how "<code>Canon PowerShot SD500</code>" would be indexed as a value in the name field. Each row of
+ <a href="http://localhost:8983/solr/admin/analysis.jsp?name=name&val=Canon+Power-Shot+SD500">This</a>
+ shows how "<code>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>name</code> field.
Notice how both <code>powershot</code> and <code>power</code>, <code>shot</code> are indexed. Tokens generated at the same position
are shown in the same column, in this case <code>shot</code> and <code>powershot</code>.
</p>
- <p>Selecting <a href="http://localhost:8983/solr/admin/analysis.jsp?name=name&verbose=on&val=Canon+PowerShot+SD500">verbose output</a>
+ <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+PowerShot+SD500&qval=power-shot">highlight matches</a>
+ <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>
@@ -371,7 +476,10 @@
<section>
<title>Conclusion</title>
<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:
+ 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="mailing_lists.html">mailing lists</a>!</li>
@@ -380,6 +488,19 @@
</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/">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>
Re: svn commit: r829663 - in /lucene/solr/trunk: site/tutorial.html
site/tutorial.pdf src/site/src/documentation/content/xdocs/tutorial.xml
Posted by Yonik Seeley <yo...@lucidimagination.com>.
While some of this could hypothetically be confusing, I don't think it
will be in reality.
Surprising, yes, but I don't think in a bad way.
I'm against cluttering the examples with all of the parameters... but
prepending "..." to show that some parameters have been omitted seems
OK.
I'll do it now.
-Yonik
http://www.lucidimagination.com
On Mon, Oct 26, 2009 at 11:58 AM, Chris Hostetter
<ho...@fucit.org> wrote:
>
> : These are realy URL fragments... none of the other examples show the
> : indent=on or the rest of the URL either, and when we get down to
>
> indent=on doesn't really affect the structure of the response docs
> (especially since people following the tutorial are likely to be using a
> browser that pretty prints the XML) ... if you set indent aside, all
> of the demo links in the previous versions of the tutorial were either...
>
> 1) full URLs (starting with http://...)
> 2) SolrQuerySyntax (w/o any url escaping or metacharacters) when the
> text arround them made it clear they were query sytnax examples not
> URL fragments
> 3) full /select URL query parts (ie: everything after the "?")
>
> ...the new sections you've added (highlighting & faceting) *look* like
> they are type#3, expcet that they leave out params that change the
> functionality. If the link text left out *all* params except the
> ones being showcased and contained elipses or soemthing to indicate that
> they were partial...
>
> THIS: "...&hl=true&hl.fl=name,features"
> INSTEAD OF: "q=video card&fl=name,id&hl=true&hl.fl=name,features"
>
> ...then it would probably be less confusing when other params besides the
> ones in the link text were acctually used in the link href (and would draw
> attention to the fact that we are building off of other params already
> seen)
>
> : faceting, the "fl" is also hidden. Showing all of the parameters
>
> i missed that you added that fl there as well (the json formating made it
> less obvious when looking at the result page) but it's just another
> example of my point.
>
> Ultimately my concern is just that we try to be consistent with our
> exmaple URLs,
> and your point about indent illustrates that we weren't really that good
> about it before, but let's try to be at least as good as 1.3 or better.
>
> So the question is: should the links in the tutorial focus on being
> completely transparent (ie: show everything) or should they focus just on
> illustrating the new params we're introducing in that section? and if
> the later, what's the best way to make it clear that's what we're doing?
>
> : As you point out, the wt=json parameter was explicitly presented
> : earlier, so it seems fair game for not calling it out explicitly.
>
> But it's presented more as an asside that in that one link we're using
> JSON ... for the entire "Sorting" section that follows we don't use it
> again, so it's kind of confusing when the results start popuing up in json
> form in the highlighting section. (if we had some verbage when we
> introduce "wt=json" about the remainder of the links using that format for
> readability, and then we add it to all of the href's in the Sorting
> section itwould be a lot less suprising.
>
> : JSON prevents highlighter markup from being escaped... didn't want
> : anyone seeing <em>
> : The other benefit is vertical size - the XML format often consumed
>
> Like i said: i'm totally fine with using the JSON format in the tutorial,
> i just want to make it more transparent.
>
>
>
>
> -Hoss
>
>
Re: svn commit: r829663 - in /lucene/solr/trunk: site/tutorial.html
site/tutorial.pdf src/site/src/documentation/content/xdocs/tutorial.xml
Posted by Chris Hostetter <ho...@fucit.org>.
: These are realy URL fragments... none of the other examples show the
: indent=on or the rest of the URL either, and when we get down to
indent=on doesn't really affect the structure of the response docs
(especially since people following the tutorial are likely to be using a
browser that pretty prints the XML) ... if you set indent aside, all
of the demo links in the previous versions of the tutorial were either...
1) full URLs (starting with http://...)
2) SolrQuerySyntax (w/o any url escaping or metacharacters) when the
text arround them made it clear they were query sytnax examples not
URL fragments
3) full /select URL query parts (ie: everything after the "?")
...the new sections you've added (highlighting & faceting) *look* like
they are type#3, expcet that they leave out params that change the
functionality. If the link text left out *all* params except the
ones being showcased and contained elipses or soemthing to indicate that
they were partial...
THIS: "...&hl=true&hl.fl=name,features"
INSTEAD OF: "q=video card&fl=name,id&hl=true&hl.fl=name,features"
...then it would probably be less confusing when other params besides the
ones in the link text were acctually used in the link href (and would draw
attention to the fact that we are building off of other params already
seen)
: faceting, the "fl" is also hidden. Showing all of the parameters
i missed that you added that fl there as well (the json formating made it
less obvious when looking at the result page) but it's just another
example of my point.
Ultimately my concern is just that we try to be consistent with our
exmaple URLs,
and your point about indent illustrates that we weren't really that good
about it before, but let's try to be at least as good as 1.3 or better.
So the question is: should the links in the tutorial focus on being
completely transparent (ie: show everything) or should they focus just on
illustrating the new params we're introducing in that section? and if
the later, what's the best way to make it clear that's what we're doing?
: As you point out, the wt=json parameter was explicitly presented
: earlier, so it seems fair game for not calling it out explicitly.
But it's presented more as an asside that in that one link we're using
JSON ... for the entire "Sorting" section that follows we don't use it
again, so it's kind of confusing when the results start popuing up in json
form in the highlighting section. (if we had some verbage when we
introduce "wt=json" about the remainder of the links using that format for
readability, and then we add it to all of the href's in the Sorting
section itwould be a lot less suprising.
: JSON prevents highlighter markup from being escaped... didn't want
: anyone seeing <em>
: The other benefit is vertical size - the XML format often consumed
Like i said: i'm totally fine with using the JSON format in the tutorial,
i just want to make it more transparent.
-Hoss
Re: svn commit: r829663 - in /lucene/solr/trunk: site/tutorial.html
site/tutorial.pdf src/site/src/documentation/content/xdocs/tutorial.xml
Posted by Yonik Seeley <yo...@lucidimagination.com>.
On Mon, Oct 26, 2009 at 2:33 AM, Chris Hostetter
<ho...@fucit.org> wrote:
>
> Whoa ... Typos are nothing new to the Solr documentation, but i think
> this is the first time I've been the one to notice a type in something
> someone else wrote...
>
> : + We can facet multile ways at the same time. The following example adds in a facet on the
Heh... I had even spell-checked it... but that still requires a visual
scan for misspellings :-)
> Also, the URLs in the highlighting & faceting sections are a little
> confusing...
>
> : + <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>
>
> ...the href's all contain "wt=json&indent=on" but the visible text
> doesn't, which makes it kind of suprising when you click on them since all
> the previous examples have produced an XML response
These are realy URL fragments... none of the other examples show the
indent=on or the rest of the URL either, and when we get down to
faceting, the "fl" is also hidden. Showing all of the parameters
would serve to obscure the important ones that are pertinent to the
section.
Surprising, yes... but not in a bad way I think. It's not the type of
API surprise that causes bugs, and it should be immediately obvious
when they look at the URL.
> (except for one which
> has "wt=json" in the text and explicit says "(return response in JSON
> format)" next to it.
As you point out, the wt=json parameter was explicitly presented
earlier, so it seems fair game for not calling it out explicitly.
> If people think the json output is easier to read, then i'm cool with
> using it, but the link text should match the link href.
JSON prevents highlighter markup from being escaped... didn't want
anyone seeing <em>
The other benefit is vertical size - the XML format often consumed
enough that the extra response info (highlighting or faceting) was
pushed completely off the page, and would require the user to scroll
down to see the start of it.
-Yonik
http://www.lucidimagination.com
Re: svn commit: r829663 - in /lucene/solr/trunk: site/tutorial.html
site/tutorial.pdf src/site/src/documentation/content/xdocs/tutorial.xml
Posted by Chris Hostetter <ho...@fucit.org>.
Whoa ... Typos are nothing new to the Solr documentation, but i think
this is the first time I've been the one to notice a type in something
someone else wrote...
: + We can facet multile ways at the same time. The following example adds in a facet on the
Also, the URLs in the highlighting & faceting sections are a little
confusing...
: + <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>
...the href's all contain "wt=json&indent=on" but the visible text
doesn't, which makes it kind of suprising when you click on them since all
the previous examples have produced an XML response (except for one which
has "wt=json" in the text and explicit says "(return response in JSON
format)" next to it.
If people think the json output is easier to read, then i'm cool with
using it, but the link text should match the link href.
-Hoss