1. Supported versions of Apache Solr
Explain.solr.pl supports the following versions of Apache Solr search server:
 * 3.x
 * 4.0 (beta)
 
We plan to support Apache Solr 3.6 and newer, but support for versions older
than 3.0 is not planned.

2. Adding a new query - 10 seconds tutorial
In order to add Your query explain information and visualise it, please add the
following to your query debugQuery=true and paste the raw Solr response. So if
your query looks like q=hd&bf=pow(sold,1.5)&qf=name,description,attributes you
should re-run a query which looks like the following:
q=hd&bf=pow(sold,1.5)&qf=name,description,attributes&debugQuery=true.

3. Adding a new query - detailed tutorial
In order to add Your query explain information and visualise it, please add the
following parameters to your query:
 * debugQuery=true (required)
 * indent=true (optional)
 * explainOther=... (optional)
After adding those parameters please re-run the query. After that paste raw Solr
response and click "Create Explain" button.
In order for explain.solr.pl to work the best way, please ensure that one of the
fields you return in the documents is your unique identifier (You can add this
by modifying with the fl parameter).

The meaning of the additional parameters is:
 * debugQuery=true - when debugQuery parameter is present the debuging
   information will be added to the response. Please remember that the debuging
   can affect performance, so don't use this parameter with your every query.
 * indent=true - when this parameter is added to the query, the raw Solr
   response is indented with whitespaces.
 * explainOther=... - if you want explain.solr.pl to visualise explain for some
   additional documents that are not in the result list you should add the
   unique identifiers of those documents as the value of the explainOther
   parameter. This will make Solr return explain for those documents and let
   explain.solr.pl visualise it.

4. Hidding your explain visualisation
If you want to make your explain information visualisation private please
uncheck the "I want this explain to be visible on history page." checkbox on the
"New explain" page. In order to get back to your explain information you will
need to remember its identifier and visit the following URL:
http://explain.solr.pl/explains/[ID]. For example, if explain.solr.pl generated
53827fty identifier for Your explain, You should visit
http://explain.solr.pl/explains/53827fty.

5. Available information
Explain.solr.pl application can show you the following information regarding your
query results:
a) RETURNED TAB
 * Unique identifier
   On the top of the explain visualisation page, you can see the unique
   identifier of Your explain visualisation. You will need that identifier to
   get back to the explain visualisation later.
 * Public availability
   This sections of explain visualisation page tells you about the public
   availability of your query explain. If you see a sentence like "This explain
   is available to public." your explain is visible by other users. In other
   case, to see your explain visualisation, you will need to know its unique
   identifier.
 * Fields returned
   This section contain information about the value of the fields that were
   returned by Solr (this are usually the fields defined in the fl parameter).
 * Score decomposition
   One of the main sections of explain visualisation which shows which elements
   of the scoring influenced the score and how. This section shows percentages
   of each debug query information.
 * Explain components
   This is the visualisation of the data that is presented in the "Score
   decomposition" section of the explain visualisation. You can see the same
   numbers that are presented in the mentioned section, but visualised in a form
   of pie chart.
b) PERFORMANCE tab
This tab presents the simple performance information about query components of
the query connected to the explain information you've sent to explain.solr.pl.

6. Common errors
Here are some common error that You can see while using explain.solr.pl:
 * "XML parse error. Check the XML document you've pasted and the quality of
   your copy & paste engine ;) Make sure you pasted the COMPLETE xml document
   returned from Solr." - There was an error during XML file parsing, please
   ensure that you've pasted the correct XML file, that You are using supported
   Solr version and the You have pasted raw Solr response (ie. page source is
   You are using web browser).
 * "Cannot determine unique key field. Connection doc/explain may be inaccurate.
   Check the existence of the unique key field in the 'fl' parameter." - Could
   not determine unique identifier of the result documents. Please ensure that
   you fetch the unique identifier in Your query - check the fl parameter
 * "No debug section in the data. Make sure that you use debugQuery option." -
   Debug section was not found in the XML file. Please check if the
   debugQuery=true parameter was added to the query.
 * "No debugOther section in the data." - Debug other section was not found in
   the XML file. Please check if the explainOther parameter was added to the
   query.
 * "XML parse error. 'numFound' attribute not found" - There was an error
   parsing XML file - numFound attribute was not found.
 * "Empty result list. Your explainOther parameter didn't match doocuments
   either." - There are no results in the response you submited.
 * "Empty result list. Use explainOther to check why concrete document wasn't
   found." - There are no results in the response you submited. Please look at
   the explainOther parameter to submit documents that are not a part of the
   result list.

7. Handling issues
If You find error in Solr Explain tool please send us a mail to [email protected]
or create an issue on Github (https://github.com/solrpl/explain/issues).

                                                     Solr.pl team (2012)
                                                     Rafał Kuć
                                                     Marek Rogoziński