[25/26] lucene-solr:jira/solr-10290: SOLR-10290: Add .adoc files

[ct...@apache.org]

http://git-wip-us.apache.org/repos/asf/lucene-solr/blob/45a148a7/solr/solr-ref-guide/src/choosing-an-output-format.adoc
----------------------------------------------------------------------
diff --git a/solr/solr-ref-guide/src/choosing-an-output-format.adoc b/solr/solr-ref-guide/src/choosing-an-output-format.adoc
new file mode 100644
index 0000000..133bed8
--- /dev/null
+++ b/solr/solr-ref-guide/src/choosing-an-output-format.adoc
@@ -0,0 +1,9 @@
+= Choosing an Output Format
+:page-shortname: choosing-an-output-format
+:page-permalink: choosing-an-output-format.html
+
+Many programming environments are able to send HTTP requests and retrieve responses. Parsing the responses is a slightly more thorny problem. Fortunately, Solr makes it easy to choose an output format that will be easy to handle on the client side.
+
+Specify a response format using the `wt` parameter in a query. The available response formats are documented in <<response-writers.adoc#response-writers,Response Writers>>.
+
+Most client APIs hide this detail for you, so for many types of client applications, you won't ever have to specify a `wt` parameter. In JavaScript, however, the interface to Solr is a little closer to the metal, so you will need to add this parameter yourself.

http://git-wip-us.apache.org/repos/asf/lucene-solr/blob/45a148a7/solr/solr-ref-guide/src/client-api-lineup.adoc
----------------------------------------------------------------------
diff --git a/solr/solr-ref-guide/src/client-api-lineup.adoc b/solr/solr-ref-guide/src/client-api-lineup.adoc
new file mode 100644
index 0000000..fc0e2cd
--- /dev/null
+++ b/solr/solr-ref-guide/src/client-api-lineup.adoc
@@ -0,0 +1,27 @@
+= Client API Lineup
+:page-shortname: client-api-lineup
+:page-permalink: client-api-lineup.html
+
+The Solr Wiki contains a list of client APIs at http://wiki.apache.org/solr/IntegratingSolr.
+
+Here is the list of client APIs, current at this writing (November 2011):
+
+[width="100%",cols="34%,33%,33%",options="header",]
+|===
+|Name |Environment |URL
+|SolRuby |Ruby |https://github.com/rsolr/rsolr
+|DelSolr |Ruby |https://github.com/avvo/delsolr
+|acts_as_solr |Rails |http://acts-as-solr.rubyforge.org/, http://rubyforge.org/projects/background-solr/
+|Flare |Rails |http://wiki.apache.org/solr/Flare
+|SolPHP |PHP |http://wiki.apache.org/solr/SolPHP
+|SolrJ |Java |http://wiki.apache.org/solr/SolJava
+|Python API |Python |http://wiki.apache.org/solr/SolPython
+|PySolr |Python |http://code.google.com/p/pysolr/
+|SolPerl |Perl |http://wiki.apache.org/solr/SolPerl
+|Solr.pm |Perl |http://search.cpan.org/~garafola/Solr-0.03/lib/Solr.pm
+|SolrForrest |Forrest/Cocoon |http://wiki.apache.org/solr/SolrForrest
+|SolrSharp |C# |http://www.codeplex.com/solrsharp
+|SolColdfusion |ColdFusion |http://solcoldfusion.riaforge.org/
+|SolrNet |.NET |https://github.com/mausch/SolrNet
+|AJAX Solr |AJAX |http://github.com/evolvingweb/ajax-solr/wiki
+|===

http://git-wip-us.apache.org/repos/asf/lucene-solr/blob/45a148a7/solr/solr-ref-guide/src/client-apis.adoc
----------------------------------------------------------------------
diff --git a/solr/solr-ref-guide/src/client-apis.adoc b/solr/solr-ref-guide/src/client-apis.adoc
new file mode 100644
index 0000000..9272520
--- /dev/null
+++ b/solr/solr-ref-guide/src/client-apis.adoc
@@ -0,0 +1,22 @@
+= Client APIs
+:page-shortname: client-apis
+:page-permalink: client-apis.html
+:page-children: introduction-to-client-apis, choosing-an-output-format, client-api-lineup, using-javascript, using-python, using-solrj, using-solr-from-ruby
+
+This section discusses the available client APIs for Solr. It covers the following topics:
+
+<<introduction-to-client-apis.adoc#introduction-to-client-apis,Introduction to Client APIs>>: A conceptual overview of Solr client APIs.
+
+<<choosing-an-output-format.adoc#choosing-an-output-format,Choosing an Output Format>>: Information about choosing a response format in Solr.
+
+<<using-javascript.adoc#using-javascript,Using JavaScript>>: Explains why a client API is not needed for JavaScript responses.
+
+<<using-python.adoc#using-python,Using Python>>: Information about Python and JSON responses.
+
+<<client-api-lineup.adoc#client-api-lineup,Client API Lineup>>: A list of all Solr Client APIs, with links.
+
+<<using-solrj.adoc#using-solrj,Using SolrJ>>: Detailed information about SolrJ, an API for working with Java applications.
+
+<<using-solr-from-ruby.adoc#using-solr-from-ruby,Using Solr From Ruby>>: Detailed information about using Solr with Ruby applications.
+
+<<mbean-request-handler.adoc#mbean-request-handler,MBean Request Handler>>: Describes the MBean request handler for programmatic access to Solr server statistics and information.

http://git-wip-us.apache.org/repos/asf/lucene-solr/blob/45a148a7/solr/solr-ref-guide/src/cloud-screens.adoc
----------------------------------------------------------------------
diff --git a/solr/solr-ref-guide/src/cloud-screens.adoc b/solr/solr-ref-guide/src/cloud-screens.adoc
new file mode 100644
index 0000000..a74e2f2
--- /dev/null
+++ b/solr/solr-ref-guide/src/cloud-screens.adoc
@@ -0,0 +1,32 @@
+= Cloud Screens
+:page-shortname: cloud-screens
+:page-permalink: cloud-screens.html
+
+When running in <<solrcloud.adoc#solrcloud,SolrCloud>> mode, a "Cloud" option will appear in the Admin UI between <<logging.adoc#logging,Logging>> and <<collections-core-admin.adoc#collections-core-admin,Collections/Core Admin>> which provides status information about each collection & node in your cluster, as well as access to the low level data being stored in <<using-zookeeper-to-manage-configuration-files.adoc#using-zookeeper-to-manage-configuration-files,Zookeeper>>.
+
+.Only Visible When using SolrCloud
+[NOTE]
+====
+
+The "Cloud" menu option is only available on Solr instances running in <<getting-started-with-solrcloud.adoc#getting-started-with-solrcloud,SolrCloud mode>>. Single node or master/slave replication instances of Solr will not display this option.
+
+====
+
+Click on the Cloud option in the left-hand navigation, and a small sub-menu appears with options called "Tree", "Graph", "Graph (Radial)" and "Dump". The default view ("Graph") shows a graph of each collection, the shards that make up those collections, and the addresses of each replica for each shard.
+
+This example shows the very simple two-node cluster created using the "`bin/solr -e cloud -noprompt`" example command. In addition to the 2 shard, 2 replica "gettingstarted" collection, there is an additional "films" collection consisting of a single shard/replica:
+
+image::images/cloud-screens/cloud-graph.png[image,width=512,height=250]
+
+
+The "Graph (Radial)" option provides a different visual view of each node. Using the same example cluster, the radial graph view looks like:
+
+image::images/cloud-screens/cloud-radial.png[image,width=478,height=250]
+
+
+The "Tree" option shows a directory structure of the data in ZooKeeper, including cluster wide information regarding the `live_nodes` and `overseer` status, as well as collection specific information such as the `state.json`, current shard leaders, and configuration files in use. In this example, we see the `state.json` file definition for the "films" collection:
+
+image::images/cloud-screens/cloud-tree.png[image,width=487,height=250]
+
+
+The final option is "Dump", which returns a JSON document containing all nodes, their contents and their children (recursively). This can be used to export a snapshot of all the data that Solr has kept inside ZooKeeper and can aid in debugging SolrCloud problems.

http://git-wip-us.apache.org/repos/asf/lucene-solr/blob/45a148a7/solr/solr-ref-guide/src/codec-factory.adoc
----------------------------------------------------------------------
diff --git a/solr/solr-ref-guide/src/codec-factory.adoc b/solr/solr-ref-guide/src/codec-factory.adoc
new file mode 100644
index 0000000..f4326eb
--- /dev/null
+++ b/solr/solr-ref-guide/src/codec-factory.adoc
@@ -0,0 +1,21 @@
+= Codec Factory
+:page-shortname: codec-factory
+:page-permalink: codec-factory.html
+
+A `codecFactory` can be specified in `solrconfig.xml` to determine which Lucene {lucene-javadocs}/core/org/apache/lucene/codecs/Codec.html[`Codec`] is used when writing the index to disk.
+
+If not specified, Lucene's default codec is implicitly used, but a {solr-javadocs}/solr-core/org/apache/solr/core/SchemaCodecFactory.html[`solr.SchemaCodecFactory`] is also available which supports 2 key features:
+
+* Schema based per-fieldtype configuration for `docValuesFormat` and `postingsFormat` - see the <<field-type-definitions-and-properties.adoc#FieldTypeDefinitionsandProperties-GeneralProperties,Field Type Definitions and Properties>> section for more details.
+* A `compressionMode` option:
+** `BEST_SPEED` (default) is optimized for search speed performance
+** `BEST_COMPRESSION` is optimized for disk space usage
+
+Example:
+
+[source,xml]
+----
+<codecFactory class="solr.SchemaCodecFactory">
+  <str name="compressionMode">BEST_COMPRESSION</str>
+</codecFactory>
+----

http://git-wip-us.apache.org/repos/asf/lucene-solr/blob/45a148a7/solr/solr-ref-guide/src/collapse-and-expand-results.adoc
----------------------------------------------------------------------
diff --git a/solr/solr-ref-guide/src/collapse-and-expand-results.adoc b/solr/solr-ref-guide/src/collapse-and-expand-results.adoc
new file mode 100644
index 0000000..a9c0ce5
--- /dev/null
+++ b/solr/solr-ref-guide/src/collapse-and-expand-results.adoc
@@ -0,0 +1,135 @@
+= Collapse and Expand Results
+:page-shortname: collapse-and-expand-results
+:page-permalink: collapse-and-expand-results.html
+
+The Collapsing query parser and the Expand component combine to form an approach to grouping documents for field collapsing in search results. The Collapsing query parser groups documents (collapsing the result set) according to your parameters, while the Expand component provides access to documents in the collapsed group for use in results display or other processing by a client application. Collapse & Expand can together do what the older <<result-grouping.adoc#result-grouping,Result Grouping>> (`group=true`) does for _most_ use-cases but not all. Generally, you should prefer Collapse & Expand.
+
+[IMPORTANT]
+====
+
+In order to use these features with SolrCloud, the documents must be located on the same shard. To ensure document co-location, you can define the `router.name` parameter as `compositeId` when creating the collection. For more information on this option, see the section <<shards-and-indexing-data-in-solrcloud.adoc#ShardsandIndexingDatainSolrCloud-DocumentRouting,Document Routing>>.
+
+====
+
+[[CollapseandExpandResults-CollapsingQueryParser]]
+== Collapsing Query Parser
+
+The `CollapsingQParser` is really a _post filter_ that provides more performant field collapsing than Solr's standard approach when the number of distinct groups in the result set is high. This parser collapses the result set to a single document per group before it forwards the result set to the rest of the search components. So all downstream components (faceting, highlighting, etc...) will work with the collapsed result set.
+
+The CollapsingQParser accepts the following local parameters:
+
+// TODO: This table has cells that won't work with PDF: https://github.com/ctargett/refguide-asciidoc-poc/issues/13
+
+[width="100%",cols="34%,33%,33%",options="header",]
+|===
+|Parameter |Description |Default
+|field |The field that is being collapsed on. The field must be a single valued String, Int or Float |none
+|min | max a|
+Selects the group head document for each group based on which document has the min or max value of the specified numeric field or <<function-queries.adoc#function-queries,function query>>.
+
+At most only one of the min, max, or sort (see below) parameters may be specified.
+
+If none are specified, the group head document of each group will be selected based on the highest scoring document in that group.
+
+ |none
+|sort a|
+Selects the group head document for each group based on which document comes first according to the specified <<common-query-parameters.adoc#CommonQueryParameters-ThesortParameter,sort string>>.
+
+At most only one of the min, max, (see above) or sort parameters may be specified.
+
+If none are specified, the group head document of each group will be selected based on the highest scoring document in that group.
+
+ |none
+|nullPolicy a|
+There are three null policies:
+
+* **ignore**: removes documents with a null value in the collapse field. This is the default.
+* **expand**: treats each document with a null value in the collapse field as a separate group.
+* **collapse**: collapses all documents with a null value into a single group using either highest score, or minimum/maximum.
+
+ |ignore
+|hint |Currently there is only one hint available "```top_fc```", which stands for top level FieldCache. The top_fc hint is only available when collapsing on String fields. top_fc usually provides the best query time speed but takes the longest to warm on startup or following a commit. top_fc will also result in having the collapsed field cached in memory twice if it's used for faceting or sorting. For very high cardinality (high distinct count) fields, top_fc may not fare so well. |none
+|size |Sets the initial size of the collapse data structures when collapsing on a **numeric field only**. The data structures used for collapsing grow dynamically when collapsing on numeric fields. Setting the size above the number of results expected in the result set will eliminate the resizing cost. |100,000
+|===
+
+*Sample Syntax:*
+
+Collapse on `group_field` selecting the document in each group with the highest scoring document:
+
+[source,java]
+----
+fq={!collapse field=group_field}
+----
+
+Collapse on `group_field` selecting the document in each group with the minimum value of `numeric_field`:
+
+[source,java]
+----
+fq={!collapse field=group_field min=numeric_field} 
+----
+
+Collapse on `group_field` selecting the document in each group with the maximum value of `numeric_field`:
+
+[source,java]
+----
+fq={!collapse field=group_field max=numeric_field} 
+----
+
+Collapse on `group_field` selecting the document in each group with the maximum value of a function. Note that the *cscore()* function can be used with the min/max options to use the score of the current document being collapsed.
+
+[source,java]
+----
+fq={!collapse field=group_field max=sum(cscore(),numeric_field)} 
+----
+
+Collapse on `group_field` with a null policy so that all docs that do not have a value in the `group_field` will be treated as a single group. For each group, the selected document will be based first on a `numeric_field`, but ties will be broken by score:
+
+[source,java]
+----
+fq={!collapse field=group_field nullPolicy=collapse sort='numeric_field asc, score desc'} 
+----
+
+Collapse on `group_field` with a hint to use the top level field cache:
+
+[source,java]
+----
+fq={!collapse field=group_field hint=top_fc} 
+----
+
+The CollapsingQParserPlugin fully supports the QueryElevationComponent.
+
+[[CollapseandExpandResults-ExpandComponent]]
+== Expand Component
+
+The ExpandComponent can be used to expand the groups that were collapsed by the http://heliosearch.org/the-collapsingqparserplugin-solrs-new-high-performance-field-collapsing-postfilter/[CollapsingQParserPlugin].
+
+Example usage with the CollapsingQParserPlugin:
+
+[source,java]
+----
+q=foo&fq={!collapse field=ISBN}
+----
+
+In the query above, the CollapsingQParserPlugin will collapse the search results on the _ISBN_ field. The main search results will contain the highest ranking document from each book.
+
+The ExpandComponent can now be used to expand the results so you can see the documents grouped by ISBN. For example:
+
+[source,java]
+----
+q=foo&fq={!collapse field=ISBN}&expand=true
+----
+
+The \u201cexpand=true\u201d parameter turns on the ExpandComponent. The ExpandComponent adds a new section to the search output labeled \u201cexpanded\u201d.
+
+Inside the expanded section there is a _map_ with each group head pointing to the expanded documents that are within the group. As applications iterate the main collapsed result set, they can access the _expanded_ map to retrieve the expanded groups.
+
+The ExpandComponent has the following parameters:
+
+[cols=",,",options="header",]
+|===
+|Parameter |Description |Default
+|expand.sort |Orders the documents within the expanded groups |score desc
+|expand.rows |The number of rows to display in each group |5
+|expand.q |Overrides the main q parameter, determines which documents to include in the main group. |main q
+|expand.fq |Overrides main fq's, determines which documents to include in the main group. |main fq's
+|===

http://git-wip-us.apache.org/repos/asf/lucene-solr/blob/45a148a7/solr/solr-ref-guide/src/collection-specific-tools.adoc
----------------------------------------------------------------------
diff --git a/solr/solr-ref-guide/src/collection-specific-tools.adoc b/solr/solr-ref-guide/src/collection-specific-tools.adoc
new file mode 100644
index 0000000..ef847ef
--- /dev/null
+++ b/solr/solr-ref-guide/src/collection-specific-tools.adoc
@@ -0,0 +1,31 @@
+= Collection-Specific Tools
+:page-shortname: collection-specific-tools
+:page-permalink: collection-specific-tools.html
+:page-children: analysis-screen, dataimport-screen, documents-screen, files-screen, query-screen, stream-screen, schema-browser-screen
+
+In the left-hand navigation bar, you will see a pull-down menu titled "Collection Selector" that can be used to access collection specific administration screens.
+
+.Only Visible When using SolrCloud
+[NOTE]
+====
+
+The "Collection Selector" pull-down menu is only available on Solr instances running in <<solrcloud.adoc#solrcloud,SolrCloud mode>>.
+
+Single node or master/slave replication instances of Solr will not display this menu, instead the Collection specific UI pages described in this section will be available in the <<core-specific-tools.adoc#core-specific-tools,Core Selector pull-down menu>>.
+
+====
+
+Clicking on the Collection Selector pull-down menu will show a list of the collections in your Solr cluster, with a search box that can be used to find a specific collection by name. When you select a collection from the pull-down, the main display of the page will display some basic metadata about the collection, and a secondary menu will appear in the left nav with links to additional collection specific administration screens.
+
+image::images/collection-specific-tools/collection_dashboard.png[image,width=482,height=250]
+
+
+The collection-specific UI screens are listed below, with a link to the section of this guide to find out more:
+
+* <<analysis-screen.adoc#analysis-screen,Analysis>> - lets you analyze the data found in specific fields.
+* <<dataimport-screen.adoc#dataimport-screen,Dataimport>> - shows you information about the current status of the Data Import Handler.
+* <<documents-screen.adoc#documents-screen,Documents>> - provides a simple form allowing you to execute various Solr indexing commands directly from the browser.
+* <<files-screen.adoc#files-screen,Files>> - shows the current core configuration files such as `solrconfig.xml`.
+* <<query-screen.adoc#query-screen,Query>> - lets you submit a structured query about various elements of a core.
+* <<stream-screen.adoc#stream-screen,Stream>> - allows you to submit streaming expressions and see results and parsing explanations.
+* <<schema-browser-screen.adoc#schema-browser-screen,Schema Browser>> - displays schema data in a browser window.