You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@lucene.apache.org by sh...@apache.org on 2017/06/27 05:19:33 UTC
[22/27] lucene-solr:feature/autoscaling: SOLR-10892: Phase 2: large
pages with lots of tables + lots of heading cleanups & TOC placement changes
http://git-wip-us.apache.org/repos/asf/lucene-solr/blob/93c96b06/solr/solr-ref-guide/src/coreadmin-api.adoc
----------------------------------------------------------------------
diff --git a/solr/solr-ref-guide/src/coreadmin-api.adoc b/solr/solr-ref-guide/src/coreadmin-api.adoc
index fef4929..a4a8ea9 100644
--- a/solr/solr-ref-guide/src/coreadmin-api.adoc
+++ b/solr/solr-ref-guide/src/coreadmin-api.adoc
@@ -1,6 +1,7 @@
= CoreAdmin API
:page-shortname: coreadmin-api
:page-permalink: coreadmin-api.html
+:page-toclevels: 1
// Licensed to the Apache Software Foundation (ASF) under one
// or more contributor license agreements. See the NOTICE file
// distributed with this work for additional information
@@ -35,19 +36,13 @@ The `STATUS` action returns the status of all running Solr cores, or status for
`admin/cores?action=STATUS&core=_core-name_`
-[[CoreAdminAPI-Input]]
-=== *Input*
+=== STATUS Parameters
-*Query Parameters*
+`core`::
+The name of a core, as listed in the "name" attribute of a `<core>` element in `solr.xml`.
-// TODO: Change column width to %autowidth.spread when https://github.com/asciidoctor/asciidoctor-pdf/issues/599 is fixed
-
-[cols="15,10,10,10,55",options="header"]
-|===
-|Parameter |Type |Required |Default |Description
-|core |string |No | |The name of a core, as listed in the "name" attribute of a `<core>` element in `solr.xml`.
-|indexInfo |boolean |No |true |If **false**, information about the index will not be returned with a core STATUS request. In Solr implementations with a large number of cores (i.e., more than hundreds), retrieving the index information for each core can take a lot of time and isn't always required.
-|===
+`indexInfo`::
+If `false`, information about the index will not be returned with a core STATUS request. In Solr implementations with a large number of cores (i.e., more than hundreds), retrieving the index information for each core can take a lot of time and isn't always required. The default is `true`.
[[CoreAdminAPI-CREATE]]
== CREATE
@@ -65,52 +60,60 @@ Note that this command is the only one of the Core Admin API commands that *does
====
Your CREATE call must be able to find a configuration, or it will not succeed.
-When you are running SolrCloud and create a new core for a collection, the configuration will be inherited from the collection. Each collection is linked to a configName, which is stored in the ZooKeeper database. This satisfies the config requirement. There is something to note, though – if you're running SolrCloud, you should *NOT* be using the CoreAdmin API at all. Use the Collections API.
+When you are running SolrCloud and create a new core for a collection, the configuration will be inherited from the collection. Each collection is linked to a configName, which is stored in ZooKeeper. This satisfies the config requirement. There is something to note, though – if you're running SolrCloud, you should *NOT* be using the CoreAdmin API at all. Use the <<collections-api.adoc#collections-api,Collections API>>.
-When you are not running SolrCloud, if you have <<config-sets.adoc#config-sets,Config Sets>> defined, you can use the configSet parameter as documented below. If there are no config sets, then the instanceDir specified in the CREATE call must already exist, and it must contain a `conf` directory which in turn must contain `solrconfig.xml`, your schema, which is usually named either `managed-schema` or `schema.xml`, and any files referenced by those configs.
+When you are not running SolrCloud, if you have <<config-sets.adoc#config-sets,Config Sets>> defined, you can use the configSet parameter as documented below. If there are no config sets, then the `instanceDir` specified in the CREATE call must already exist, and it must contain a `conf` directory which in turn must contain `solrconfig.xml`, your schema (usually named either `managed-schema` or `schema.xml`), and any files referenced by those configs.
-The config and schema filenames can be specified with the config and schema parameters, but these are expert options. One thing you could do to avoid creating the conf directory is use config and schema parameters that point at absolute paths, but this can lead to confusing configurations unless you fully understand what you are doing.
+The config and schema filenames can be specified with the `config` and `schema` parameters, but these are expert options. One thing you could do to avoid creating the `conf` directory is use `config` and `schema` parameters that point at absolute paths, but this can lead to confusing configurations unless you fully understand what you are doing.
====
-.CREATE and the core.properties file
+.CREATE and the `core.properties` file
[IMPORTANT]
====
-The core.properties file is built as part of the CREATE command. If you create a core.properties file yourself in a core directory and then try to use CREATE to add that core to Solr, you will get an error telling you that another core is already defined there. The core.properties file must NOT exist before calling the CoreAdmin API with the CREATE command.
+The `core.properties` file is built as part of the CREATE command. If you create a `core.properties` file yourself in a core directory and then try to use CREATE to add that core to Solr, you will get an error telling you that another core is already defined there. The `core.properties` file must NOT exist before calling the CoreAdmin API with the CREATE command.
====
-[[CoreAdminAPI-Input.1]]
-=== *Input*
+=== CREATE Core Parameters
-*Query Parameters*
+`name`::
+The name of the new core. Same as `name` on the `<core>` element. This parameter is required.
-// TODO: Change column width to %autowidth.spread when https://github.com/asciidoctor/asciidoctor-pdf/issues/599 is fixed
+`instanceDir`::
+The directory where files for this core should be stored. Same as `instanceDir` on the `<core>` element. The default is the value specified for the `name` parameter if not supplied.
-[cols="15,10,10,10,55",options="header"]
-|===
-|Parameter |Type |Required |Default |Description
-|name |string |Yes |N/A |The name of the new core. Same as "name" on the `<core>` element.
-|instanceDir |string |No |The value specified for "name" parameter |The directory where files for this SolrCore should be stored. Same as `instanceDir` on the `<core>` element.
-|config |string |No | |Name of the config file (i.e., `solrconfig.xml`) relative to `instanceDir`.
-|schema |string |No | |Name of the schema file to use for the core. Please note that if you are using a "managed schema" (the default behavior) then any value for this property which does not match the effective `managedSchemaResourceName` will be read once, backed up, and converted for managed schema use. See <<schema-factory-definition-in-solrconfig.adoc#schema-factory-definition-in-solrconfig,Schema Factory Definition in SolrConfig>> for details.
-|dataDir |string |No | |Name of the data directory relative to `instanceDir`.
-|configSet |string |No | |Name of the configset to use for this core. For more information, see the section <<config-sets.adoc#config-sets,Config Sets>>.
-|collection |string |No | |The name of the collection to which this core belongs. The default is the name of the core. `collection.<param>=<value>` causes a property of `<param>=<value>` to be set if a new collection is being created. Use `collection.configName=<configname>` to point to the configuration for a new collection.
-|shard |string |No | |The shard id this core represents. Normally you want to be auto-assigned a shard id.
-|property.__name__=__value__ |string |No | |Sets the core property _name_ to __value__. See the section on defining <<defining-core-properties.adoc#Definingcore.properties-core.properties_files,core.properties file contents>>.
-|async |string |No | |Request ID to track this action which will be processed asynchronously
-|===
+`config`::
+Name of the config file (i.e., `solrconfig.xml`) relative to `instanceDir`.
-Use `collection.configName=<configname>` to point to the config for a new collection.
+`schema`::
+Name of the schema file to use for the core. Please note that if you are using a "managed schema" (the default behavior) then any value for this property which does not match the effective `managedSchemaResourceName` will be read once, backed up, and converted for managed schema use. See <<schema-factory-definition-in-solrconfig.adoc#schema-factory-definition-in-solrconfig,Schema Factory Definition in SolrConfig>> for details.
-[[CoreAdminAPI-Example]]
-=== Example
+`dataDir`::
+Name of the data directory relative to `instanceDir`.
-`\http://localhost:8983/solr/admin/cores?action=CREATE&name=my_core&collection=my_collection&shard=shard2`
+`configSet`::
+Name of the configset to use for this core. For more information, see the section <<config-sets.adoc#config-sets,Config Sets>>.
+
+`collection`::
+The name of the collection to which this core belongs. The default is the name of the core. `collection._param_=_value_` causes a property of `_param_=_value_` to be set if a new collection is being created. Use `collection.configName=_config-name_` to point to the configuration for a new collection.
++
+WARNING: While it's possible to create a core for a non-existent collection, this approach is not supported and not recommended. Always create a collection using the <<collections-api.adoc#collections-api,Collections API>> before creating a core directly for it.
+
+`shard`::
+The shard id this core represents. Normally you want to be auto-assigned a shard id.
+
+`property._name_=_value_`::
+Sets the core property _name_ to _value_. See the section on defining <<defining-core-properties.adoc#Definingcore.properties-core.properties_files,core.properties file contents>>.
+
+`async`::
+Request ID to track this action which will be processed asynchronously.
+
+Use `collection.configName=_configname_` to point to the config for a new collection.
+
+=== CREATE Example
+
+[source,bash]
+http://localhost:8983/solr/admin/cores?action=CREATE&name=my_core&collection=my_collection&shard=shard2
-[WARNING]
-====
-While it's possible to create a core for a non-existent collection, this approach is not supported and not recommended. Always create a collection using the <<collections-api.adoc#collections-api,Collections API>> before creating a core directly for it.
-====
[[CoreAdminAPI-RELOAD]]
== RELOAD
@@ -126,18 +129,10 @@ This is useful when you've made changes to a Solr core's configuration on disk,
RELOAD performs "live" reloads of SolrCore, reusing some existing objects. Some configuration options, such as the `dataDir` location and `IndexWriter`-related settings in `solrconfig.xml` can not be changed and made active with a simple RELOAD action.
====
-[[CoreAdminAPI-Input.2]]
-=== Input
-
-*Query Parameters*
+=== RELOAD Core Parameters
-// TODO: Change column width to %autowidth.spread when https://github.com/asciidoctor/asciidoctor-pdf/issues/599 is fixed
-
-[cols="15,10,10,10,55",options="header"]
-|===
-|Parameter |Type |Required |Default |Description
-|core |string |Yes |N/A |The name of the core, as listed in the "name" attribute of a `<core>` element in `solr.xml`.
-|===
+`core`::
+The name of the core, as listed in the "name" attribute of a `<core>` element in `solr.xml`. This parameter is required.
[[CoreAdminAPI-RENAME]]
== RENAME
@@ -146,20 +141,17 @@ The `RENAME` action changes the name of a Solr core.
`admin/cores?action=RENAME&core=_core-name_&other=_other-core-name_`
-[[CoreAdminAPI-Input.3]]
-=== Input
+=== RENAME Parameters
+
+`core`::
+The name of the Solr core to be renamed. This parameter is required.
-**Query Parameters**
+`other`::
+The new name for the Solr core. If the persistent attribute of `<solr>` is `true`, the new name will be written to `solr.xml` as the `name` attribute of the `<core>` attribute. This parameter is required.
-// TODO: Change column width to %autowidth.spread when https://github.com/asciidoctor/asciidoctor-pdf/issues/599 is fixed
+`async`::
+Request ID to track this action which will be processed asynchronously.
-[cols="15,10,10,10,55",options="header"]
-|===
-|Parameter |Type |Required |Default |Description
-|core |string |Yes | |The name of the Solr core to be renamed.
-|other |string |Yes | |The new name for the Solr core. If the persistent attribute of `<solr>` is `true`, the new name will be written to `solr.xml` as the `name` attribute of the `<core>` attribute.
-|async |string |No | |Request ID to track this action which will be processed asynchronously
-|===
[[CoreAdminAPI-SWAP]]
== SWAP
@@ -175,20 +167,17 @@ Do not use `SWAP` with a SolrCloud node. It is not supported and can result in t
====
-[[CoreAdminAPI-Input.4]]
-=== Input
+=== SWAP Parameters
+
+`core`::
+The name of one of the cores to be swapped. This parameter is required.
-*Query Parameters*
+`other`::
+The name of one of the cores to be swapped. This parameter is required.
-// TODO: Change column width to %autowidth.spread when https://github.com/asciidoctor/asciidoctor-pdf/issues/599 is fixed
+`async`::
+Request ID to track this action which will be processed asynchronously.
-[cols="15,10,10,10,55",options="header"]
-|===
-|Parameter |Type |Required |Default |Description
-|core |string |Yes | |The name of one of the cores to be swapped.
-|other |string |Yes | |The name of one of the cores to be swapped.
-|async |string |No | |Request ID to track this action which will be processed asynchronously
-|===
[[CoreAdminAPI-UNLOAD]]
== UNLOAD
@@ -204,22 +193,23 @@ The `UNLOAD` action requires a parameter (`core`) identifying the core to be rem
Unloading all cores in a SolrCloud collection causes the removal of that collection's metadata from ZooKeeper.
====
-[[CoreAdminAPI-Input.5]]
-=== Input
+=== UNLOAD Parameters
-*Query Parameters*
+`core`::
+The name of a core to be removed. This parameter is required.
-// TODO: Change column width to %autowidth.spread when https://github.com/asciidoctor/asciidoctor-pdf/issues/599 is fixed
+`deleteIndex`::
+If `true`, will remove the index when unloading the core. The default is `false`.
+
+`deleteDataDir`::
+If `true`, removes the `data` directory and all sub-directories. The default is `false`.
+
+`deleteInstanceDir`::
+If `true`, removes everything related to the core, including the index directory, configuration files and other related files. The default is `false`.
+
+`async`::
+Request ID to track this action which will be processed asynchronously.
-[cols="15,10,10,10,55",options="header"]
-|===
-|Parameter |Type |Required |Default |Description
-|core |string |Yes | |The name of one of the cores to be removed.
-|deleteIndex |boolean |No |false |If true, will remove the index when unloading the core.
-|deleteDataDir |boolean |No |false |If true, removes the `data` directory and all sub-directories.
-|deleteInstanceDir |boolean |No |false |If true, removes everything related to the core, including the index directory, configuration files and other related files.
-|async |string |No | |Request ID to track this action which will be processed asynchronously
-|===
[[CoreAdminAPI-MERGEINDEXES]]
== MERGEINDEXES
@@ -238,21 +228,20 @@ This approach allows us to define cores that may not have an index path that is
We can make this call run asynchronously by specifying the `async` parameter and passing a request-id. This id can then be used to check the status of the already submitted task using the REQUESTSTATUS API.
-[[CoreAdminAPI-Input.6]]
-=== Input
+=== MERGEINDEXES Parameters
+
+`core`::
+The name of the target core/index. This parameter is required.
-*Query Parameters*
+`indexDir`::
+Multi-valued, directories that would be merged.
-// TODO: Change column width to %autowidth.spread when https://github.com/asciidoctor/asciidoctor-pdf/issues/599 is fixed
+`srcCore`::
+Multi-valued, source cores that would be merged.
+
+`async`::
+Request ID to track this action which will be processed asynchronously
-[cols="15,10,10,10,55",options="header"]
-|===
-|Parameter |Type |Required |Default |Description
-|core |string |Yes | |The name of the target core/index.
-|indexDir |string | | |Multi-valued, directories that would be merged.
-|srcCore |string | | |Multi-valued, source cores that would be merged.
-|async |string | | |Request ID to track this action which will be processed asynchronously
-|===
[[CoreAdminAPI-SPLIT]]
== SPLIT
@@ -261,55 +250,56 @@ The `SPLIT` action splits an index into two or more indexes. The index being spl
The `SPLIT` action supports five parameters, which are described in the table below.
-[[CoreAdminAPI-Input.7]]
-=== Input
+=== SPLIT Parameters
-*Query Parameters*
+`core`::
+The name of the core to be split. This parameter is required.
-// TODO: Change column width to %autowidth.spread when https://github.com/asciidoctor/asciidoctor-pdf/issues/599 is fixed
+`path`::
+Multi-valued, the directory path in which a piece of the index will be written. Either this parameter or `targetCore` must be specified. If this is specified, the `targetCore` parameter may not be used.
-[cols="15,10,10,10,55",options="header"]
-|===
-|Parameter |Type |Required |Default |Description
-|core |string |Yes | |The name of the core to be split.
-|path |string | | |Multi-valued, the directory path in which a piece of the index will be written.
-|targetCore |string | | |Multi-valued, the target Solr core to which a piece of the index will be merged
-|ranges |string |No | |A comma-separated list of hash ranges in hexadecimal format
-|split.key |string |No | |The key to be used for splitting the index
-|async |string |No | |Request ID to track this action which will be processed asynchronously
-|===
+`targetCore`::
+Multi-valued, the target Solr core to which a piece of the index will be merged. Either this parameter or `path` must be specified. If this is specified, the `path` parameter may not be used.
+
+`ranges`::
+A comma-separated list of hash ranges in hexadecimal format. If this parameter is used, `split.key` should not be. See the <<SPLIT Examples>> below for an example of how this parameter can be used.
+
+`split.key`::
+The key to be used for splitting the index. If this parameter is used, `ranges` should not be. See the <<SPLIT Examples>> below for an example of how this parameter can be used.
+
+`async`::
+Request ID to track this action which will be processed asynchronously.
-[IMPORTANT]
-====
-Either `path` or `targetCore` parameter must be specified but not both. The ranges and split.key parameters are optional and only one of the two should be specified, if at all required.
-====
-[[CoreAdminAPI-Examples]]
-=== Examples
+=== SPLIT Examples
The `core` index will be split into as many pieces as the number of `path` or `targetCore` parameters.
==== Usage with two targetCore parameters:
-`\http://localhost:8983/solr/admin/cores?action=SPLIT&core=core0&targetCore=core1&targetCore=core2`
+[source,bash]
+http://localhost:8983/solr/admin/cores?action=SPLIT&core=core0&targetCore=core1&targetCore=core2
Here the `core` index will be split into two pieces and merged into the two `targetCore` indexes.
==== Usage with two path parameters:
-`\http://localhost:8983/solr/admin/cores?action=SPLIT&core=core0&path=/path/to/index/1&path=/path/to/index/2`
+[source,bash]
+http://localhost:8983/solr/admin/cores?action=SPLIT&core=core0&path=/path/to/index/1&path=/path/to/index/2
The `core` index will be split into two pieces and written into the two directory paths specified.
==== Usage with the split.key parameter:
-`\http://localhost:8983/solr/admin/cores?action=SPLIT&core=core0&targetCore=core1&split.key=A!`
+[source,bash]
+http://localhost:8983/solr/admin/cores?action=SPLIT&core=core0&targetCore=core1&split.key=A!
Here all documents having the same route key as the `split.key` i.e. 'A!' will be split from the `core` index and written to the `targetCore`.
==== Usage with ranges parameter:
-`\http://localhost:8983/solr/admin/cores?action=SPLIT&core=core0&targetCore=core1&targetCore=core2&targetCore=core3&ranges=0-1f4,1f5-3e8,3e9-5dc`
+[source,bash]
+http://localhost:8983/solr/admin/cores?action=SPLIT&core=core0&targetCore=core1&targetCore=core2&targetCore=core3&ranges=0-1f4,1f5-3e8,3e9-5dc
This example uses the `ranges` parameter with hash ranges 0-500, 501-1000 and 1001-1500 specified in hexadecimal. Here the index will be split into three pieces with each targetCore receiving documents matching the hash ranges specified i.e. core1 will get documents with hash range 0-500, core2 will receive documents with hash range 501-1000 and finally, core3 will receive documents with hash range 1001-1500. At least one hash range must be specified. Please note that using a single hash range equal to a route key's hash range is NOT equivalent to using the `split.key` parameter because multiple route keys can hash to the same range.
@@ -324,22 +314,17 @@ Request the status of an already submitted asynchronous CoreAdmin API call.
`admin/cores?action=REQUESTSTATUS&requestid=_id_`
-[[CoreAdminAPI-Input.8]]
-=== Input
+=== Core REQUESTSTATUS Parameters
-*Query Parameters*
+The REQUESTSTATUS command has only one parameter.
-// TODO: Change column width to %autowidth.spread when https://github.com/asciidoctor/asciidoctor-pdf/issues/599 is fixed
+`requestid`::
+The user defined request-id for the asynchronous request. This parameter is required.
-[cols="15,10,10,10,55",options="header"]
-|===
-|Parameter |Type |Required |Default |Description
-|requestid |string |Yes | |The user defined request-id for the Asynchronous request.
-|===
+The call below will return the status of an already submitted asynchronous CoreAdmin call.
-The call below will return the status of an already submitted Asynchronous CoreAdmin call.
-
-`\http://localhost:8983/solr/admin/cores?action=REQUESTSTATUS&requestid=1`
+[source,bash]
+http://localhost:8983/solr/admin/cores?action=REQUESTSTATUS&requestid=1
[[CoreAdminAPI-REQUESTRECOVERY]]
== REQUESTRECOVERY
@@ -348,22 +333,15 @@ The `REQUESTRECOVERY` action manually asks a core to recover by synching with th
`admin/cores?action=REQUESTRECOVERY&core=_core-name_`
-[[CoreAdminAPI-Input.9]]
-=== Input
-
-*Query Parameters*
-
-// TODO: Change column width to %autowidth.spread when https://github.com/asciidoctor/asciidoctor-pdf/issues/599 is fixed
+=== REQUESTRECOVERY Parameters
-[cols="15,10,10,10,55",options="header"]
-|===
-|Parameter |Type |Required |Default |Description
-|core |string |Yes | |The name of the core to re-sync.
-|===
+`core`::
+The name of the core to re-sync. This parameter is required.
[[CoreAdminAPI-Examples.1]]
-=== Examples
+=== REQUESTRECOVERY Examples
-`\http://localhost:8981/solr/admin/cores?action=REQUESTRECOVERY&core=gettingstarted_shard1_replica1`
+[source,bash]
+http://localhost:8981/solr/admin/cores?action=REQUESTRECOVERY&core=gettingstarted_shard1_replica1
The core to specify can be found by expanding the appropriate ZooKeeper node via the admin UI.
http://git-wip-us.apache.org/repos/asf/lucene-solr/blob/93c96b06/solr/solr-ref-guide/src/format-of-solr-xml.adoc
----------------------------------------------------------------------
diff --git a/solr/solr-ref-guide/src/format-of-solr-xml.adoc b/solr/solr-ref-guide/src/format-of-solr-xml.adoc
index 28dc3c4..98f21d1 100644
--- a/solr/solr-ref-guide/src/format-of-solr-xml.adoc
+++ b/solr/solr-ref-guide/src/format-of-solr-xml.adoc
@@ -55,66 +55,98 @@ As you can see, the discovery Solr configuration is "SolrCloud friendly". Howeve
There are no attributes that you can specify in the `<solr>` tag, which is the root element of `solr.xml`. The tables below list the child nodes of each XML element in `solr.xml`.
-// TODO: Change column width to %autowidth.spread when https://github.com/asciidoctor/asciidoctor-pdf/issues/599 is fixed
-
-[cols="30,70",options="header"]
-|===
-|Node |Description
-|`adminHandler` |If used, this attribute should be set to the FQN (Fully qualified name) of a class that inherits from CoreAdminHandler. For example, `<str name="adminHandler">com.myorg.MyAdminHandler</str>` would configure the custom admin handler (MyAdminHandler) to handle admin requests. If this attribute isn't set, Solr uses the default admin handler, `org.apache.solr.handler.admin.CoreAdminHandler`. For more information on this parameter, see the Solr Wiki at http://wiki.apache.org/solr/CoreAdmin#cores.
-|`collectionsHandler` |As above, for custom CollectionsHandler implementations.
-| `infoHandler` |As above, for custom InfoHandler implementations.
-|`coreLoadThreads` |Specifies the number of threads that will be assigned to load cores in parallel.
-|`coreRootDirectory` |The root of the core discovery tree, defaults to `$SOLR_HOME`.
-|`managementPath` |Currently non-operational.
-|`sharedLib` |Specifies the path to a common library directory that will be shared across all cores. Any JAR files in this directory will be added to the search path for Solr plugins. This path is relative to `$SOLR_HOME`. Custom handlers may be placed in this directory.
-|`shareSchema` |This attribute, when set to true, ensures that the multiple cores pointing to the same Schema resource file will be referring to the same IndexSchema Object. Sharing the IndexSchema Object makes loading the core faster. If you use this feature, make sure that no core-specific property is used in your Schema file.
-|`transientCacheSize` |Defines how many cores with transient=true that can be loaded before swapping the least recently used core for a new core.
-|`configSetBaseDir` |The directory under which configsets for Solr cores can be found. Defaults to `$SOLR_HOME/configsets`.
-|===
+`adminHandler`::
+This attribute does not need to be set.
++
+If used, this attribute should be set to the FQN (Fully qualified name) of a class that inherits from CoreAdminHandler. For example, `<str name="adminHandler">com.myorg.MyAdminHandler</str>` would configure the custom admin handler (MyAdminHandler) to handle admin requests.
++
+If this attribute isn't set, Solr uses the default admin handler, `org.apache.solr.handler.admin.CoreAdminHandler`.
+
+`collectionsHandler`::
+As above, for custom CollectionsHandler implementations.
+
+`infoHandler`::
+As above, for custom InfoHandler implementations.
+
+`coreLoadThreads`::
+Specifies the number of threads that will be assigned to load cores in parallel.
+
+`coreRootDirectory`::
+The root of the core discovery tree, defaults to `$SOLR_HOME` (by default, `server/solr`).
+
+`managementPath`::
+Currently non-operational.
+
+`sharedLib`::
+Specifies the path to a common library directory that will be shared across all cores. Any JAR files in this directory will be added to the search path for Solr plugins. This path is relative to `$SOLR_HOME`. Custom handlers may be placed in this directory.
+
+`shareSchema`::
+This attribute, when set to `true`, ensures that the multiple cores pointing to the same Schema resource file will be referring to the same IndexSchema Object. Sharing the IndexSchema Object makes loading the core faster. If you use this feature, make sure that no core-specific property is used in your Schema file.
+
+`transientCacheSize`::
+Defines how many cores with `transient=true` that can be loaded before swapping the least recently used core for a new core.
+
+`configSetBaseDir`::
+The directory under which configSets for Solr cores can be found. Defaults to `$SOLR_HOME/configsets`.
+
=== The <solrcloud> Element
This element defines several parameters that relate so SolrCloud. This section is ignored unless theSolr instance is started with either `-DzkRun` or `-DzkHost`
-// TODO: Change column width to %autowidth.spread when https://github.com/asciidoctor/asciidoctor-pdf/issues/599 is fixed
-
-[cols="30,70",options="header"]
-|===
-|Node |Description
-|`distribUpdateConnTimeout` |Used to set the underlying "connTimeout" for intra-cluster updates.
-|`distribUpdateSoTimeout` |Used to set the underlying "socketTimeout" for intra-cluster updates.
-|`host` |The hostname Solr uses to access cores.
-|`hostContext` |The url context path.
-|`hostPort` |The port Solr uses to access cores. In the default `solr.xml` file, this is set to `${jetty.port:8983`}, which will use the Solr port defined in Jetty, and otherwise fall back to 8983.
-|`leaderVoteWait` |When SolrCloud is starting up, how long each Solr node will wait for all known replicas for that shard to be found before assuming that any nodes that haven't reported are down.
-|`leaderConflictResolveWait` |When trying to elect a leader for a shard, this property sets the maximum time a replica will wait to see conflicting state information to be resolved; temporary conflicts in state information can occur when doing rolling restarts, especially when the node hosting the Overseer is restarted. Typically, the default value of 180000 (ms) is sufficient for conflicts to be resolved; you may need to increase this value if you have hundreds or thousands of small collections in SolrCloud.
-|`zkClientTimeout` |A timeout for connection to a ZooKeeper server. It is used with SolrCloud.
-|`zkHost` |In SolrCloud mode, the URL of the ZooKeeper host that Solr should use for cluster state information.
-|`genericCoreNodeNames` |If `TRUE`, node names are not based on the address of the node, but on a generic name that identifies the core. When a different machine takes over serving that core things will be much easier to understand.
-|`zkCredentialsProvider` & ` zkACLProvider` |Optional parameters that can be specified if you are using <<zookeeper-access-control.adoc#zookeeper-access-control,ZooKeeper Access Control>>.
-|===
+`distribUpdateConnTimeout`::
+Used to set the underlying `connTimeout` for intra-cluster updates.
+
+`distribUpdateSoTimeout`::
+Used to set the underlying `socketTimeout` for intra-cluster updates.
+
+`host`::
+The hostname Solr uses to access cores.
+
+`hostContext`::
+The url context path.
+
+`hostPort`::
+The port Solr uses to access cores.
++
+In the default `solr.xml` file, this is set to `${jetty.port:8983}`, which will use the Solr port defined in Jetty, and otherwise fall back to 8983.
+
+`leaderVoteWait`::
+When SolrCloud is starting up, how long each Solr node will wait for all known replicas for that shard to be found before assuming that any nodes that haven't reported are down.
+
+`leaderConflictResolveWait`::
+When trying to elect a leader for a shard, this property sets the maximum time a replica will wait to see conflicting state information to be resolved; temporary conflicts in state information can occur when doing rolling restarts, especially when the node hosting the Overseer is restarted.
++
+Typically, the default value of `180000` (ms) is sufficient for conflicts to be resolved; you may need to increase this value if you have hundreds or thousands of small collections in SolrCloud.
+
+`zkClientTimeout`::
+A timeout for connection to a ZooKeeper server. It is used with SolrCloud.
+
+`zkHost`::
+In SolrCloud mode, the URL of the ZooKeeper host that Solr should use for cluster state information.
+
+`genericCoreNodeNames`::
+If `TRUE`, node names are not based on the address of the node, but on a generic name that identifies the core. When a different machine takes over serving that core things will be much easier to understand.
+
+`zkCredentialsProvider` & `zkACLProvider`::
+Optional parameters that can be specified if you are using <<zookeeper-access-control.adoc#zookeeper-access-control,ZooKeeper Access Control>>.
+
=== The <logging> Element
-// TODO: Change column width to %autowidth.spread when https://github.com/asciidoctor/asciidoctor-pdf/issues/599 is fixed
+`class`::
+The class to use for logging. The corresponding JAR file must be available to Solr, perhaps through a `<lib>` directive in `solrconfig.xml`.
-[cols="30,70",options="header"]
-|===
-|Node |Description
-|`class` |The class to use for logging. The corresponding JAR file must be available to Solr, perhaps through a `<lib>` directive in `solrconfig.xml`.
-|`enabled` |true/false - whether to enable logging or not.
-|===
+`enabled`::
+true/false - whether to enable logging or not.
==== The <logging><watcher> Element
-// TODO: Change column width to %autowidth.spread when https://github.com/asciidoctor/asciidoctor-pdf/issues/599 is fixed
+`size`::
+The number of log events that are buffered.
-[cols="30,70",options="header"]
-|===
-|Node |Description
-|`size` |The number of log events that are buffered.
-|`threshold` |The logging level above which your particular logging implementation will record. For example when using log4j one might specify DEBUG, WARN, INFO, etc.
-|===
+`threshold`::
+The logging level above which your particular logging implementation will record. For example when using log4j one might specify DEBUG, WARN, INFO, etc.
=== The <shardHandlerFactory> Element
@@ -127,26 +159,40 @@ Custom shard handlers can be defined in `solr.xml` if you wish to create a custo
Since this is a custom shard handler, sub-elements are specific to the implementation. The default and only shard handler provided by Solr is the HttpShardHandlerFactory in which case, the following sub-elements can be specified:
-// TODO: Change column width to %autowidth.spread when https://github.com/asciidoctor/asciidoctor-pdf/issues/599 is fixed
-
-[cols="30,70",options="header"]
-|===
-|Node |Description
-|`socketTimeout` |The read timeout for intra-cluster query and administrative requests. The default is the same as the `distribUpdateSoTimeout` specified in the `<solrcloud>` section.
-|`connTimeout` |The connection timeout for intra-cluster query and administrative requests. Defaults to the `distribUpdateConnTimeout` specified in the `<solrcloud>` section
-|`urlScheme` |URL scheme to be used in distributed search
-|`maxConnectionsPerHost` |Maximum connections allowed per host. Defaults to 20
-|`maxConnections` |Maximum total connections allowed. Defaults to 10000
-|`corePoolSize` |The initial core size of the threadpool servicing requests. Default is 0.
-|`maximumPoolSize` |The maximum size of the threadpool servicing requests. Default is unlimited.
-|`maxThreadIdleTime` |The amount of time in seconds that idle threads persist for in the queue, before being killed. Default is 5 seconds.
-|`sizeOfQueue` |If the threadpool uses a backing queue, what is its maximum size to use direct handoff. Default is to use a SynchronousQueue.
-|`fairnessPolicy` |A boolean to configure if the threadpool favours fairness over throughput. Default is false to favor throughput.
-|===
+`socketTimeout`::
+The read timeout for intra-cluster query and administrative requests. The default is the same as the `distribUpdateSoTimeout` specified in the `<solrcloud>` section.
+
+`connTimeout`::
+The connection timeout for intra-cluster query and administrative requests. Defaults to the `distribUpdateConnTimeout` specified in the `<solrcloud>` section.
+
+`urlScheme`::
+The URL scheme to be used in distributed search.
+
+`maxConnectionsPerHost`::
+Maximum connections allowed per host. Defaults to `20`.
+
+`maxConnections`::
+Maximum total connections allowed. Defaults to `10000`.
+
+`corePoolSize`::
+The initial core size of the threadpool servicing requests. Default is `0`.
+
+`maximumPoolSize`::
+The maximum size of the threadpool servicing requests. Default is unlimited.
+
+`maxThreadIdleTime`::
+The amount of time in seconds that idle threads persist for in the queue, before being killed. Default is `5` seconds.
+
+`sizeOfQueue`::
+If the threadpool uses a backing queue, what is its maximum size to use direct handoff. Default is to use a SynchronousQueue.
+
+`fairnessPolicy`::
+A boolean to configure if the threadpool favors fairness over throughput. Default is false to favor throughput.
+
=== The <metrics> Element
-The `<metrics>` element in `solr.xml` allows you to customize the metrics reported by Solr. You can define system properties that should not be returned, or define custom suppliers and reporters.
+The `<metrics>` element in `solr.xml` allows you to customize the metrics reported by Solr. You can define system properties that should not be returned, or define custom suppliers and reporters.
In a default `solr.xml` you will not see any `<metrics>` configuration. If you would like to customize the metrics for your installation, see the section <<metrics-reporting.adoc#metrics-configuration,Metrics Configuration>>.
http://git-wip-us.apache.org/repos/asf/lucene-solr/blob/93c96b06/solr/solr-ref-guide/src/function-queries.adoc
----------------------------------------------------------------------
diff --git a/solr/solr-ref-guide/src/function-queries.adoc b/solr/solr-ref-guide/src/function-queries.adoc
index 86a7d02..29cca9c 100644
--- a/solr/solr-ref-guide/src/function-queries.adoc
+++ b/solr/solr-ref-guide/src/function-queries.adoc
@@ -1,6 +1,7 @@
= Function Queries
:page-shortname: function-queries
:page-permalink: function-queries.html
+:page-tocclass: right
// Licensed to the Apache Software Foundation (ASF) under one
// or more contributor license agreements. See the NOTICE file
// distributed with this work for additional information
@@ -80,57 +81,90 @@ Only functions with fast random access are recommended.
The table below summarizes the functions available for function queries.
-// TODO: Change column width to %autowidth.spread when https://github.com/asciidoctor/asciidoctor-pdf/issues/599 is fixed
+=== abs Function
+Returns the absolute value of the specified value or function.
-[cols="20,40,40",options="header"]
-|===
-|Function |Description |Syntax Examples
-|abs |Returns the absolute value of the specified value or function. |`abs(x)` `abs(-5)`
+*Syntax Example*
-|childfield(field) |Returns the value of the given field for one of the matched child docs when searching by <<other-parsers.adoc#OtherParsers-BlockJoinParentQueryParser,{!parent}>>. It can be used only in `sort` parameter. a|
-* `sort=childfield(name) asc` implies `$q` as a second argument and therefor it assumes `q={!parent ..}..`;
+* `abs(x)` `abs(-5)`
+
+=== childfield(field) Function
+Returns the value of the given field for one of the matched child docs when searching by <<other-parsers.adoc#OtherParsers-BlockJoinParentQueryParser,{!parent}>>. It can be used only in `sort` parameter.
+
+*Syntax Examples*
+
+* `sort=childfield(name) asc` implies `$q` as a second argument and therefore it assumes `q={!parent ..}..`;
* `sort=childfield(field,$bjq) asc` refers to a separate parameter `bjq={!parent ..}..`;
* `sort=childfield(field,{!parent of=...}...) desc` allows to inline block join parent query
-|concat(v,f..)|concatenates the given string fields, literals and other functions |`concat(name," ",$param,def(opt,"-"))`
+=== concat Function
+Concatenates the given string fields, literals and other functions.
+
+*Syntax Example*
+
+* `concat(name," ",$param,def(opt,"-"))`
+
+=== "constant" Function
+
+Specifies a floating point constant.
+
+*Syntax Example*
+
+* `1.5`
-|"constant" |Specifies a floating point constant. |`1.5`
+=== def Function
+`def` is short for default. Returns the value of field "field", or if the field does not exist, returns the default value specified. Yields the first value where `exists()==true`.
-|def |`def` is short for default. Returns the value of field "field", or if the field does not exist, returns the default value specified. and yields the first value where `exists()==true`.) |`def(rating,5):` This `def()` function returns the rating, or if no rating specified in the doc, returns 5 `def(myfield, 1.0):` equivalent to `if(exists(myfield),myfield,1.0)`
+*Syntax Example*
-|div |Divides one value or function by another. div(x,y) divides x by y. a|`div(1,y)`
+* `def(rating,5)`: This `def()` function returns the rating, or if no rating specified in the doc, returns 5 `def(myfield, 1.0):` equivalent to `if(exists(myfield),myfield,1.0)`
-`div(sum(x,100),max(y,1))`
+=== div Function
+Divides one value or function by another. `div(x,y)` divides `x` by `y`.
-|dist |Return the distance between two vectors (points) in an n-dimensional space. Takes in the power, plus two or more ValueSource instances and calculates the distances between the two vectors. Each ValueSource must be a number. There must be an even number of ValueSource instances passed in and the method assumes that the first half represent the first vector and the second half represent the second vector. a|`dist(2, x, y, 0, 0):` calculates the Euclidean distance between (0,0) and (x,y) for each document.
+*Syntax Examples*
-`dist(1, x, y, 0, 0)`: calculates the Manhattan (taxicab) distance between (0,0) and (x,y) for each document.
+* `div(1,y)`
+* `div(sum(x,100),max(y,1))`
-`dist(2, x,y,z,0,0,0):` Euclidean distance between (0,0,0) and (x,y,z) for each document.
+=== dist Function
+Returns the distance between two vectors (points) in an n-dimensional space. Takes in the power, plus two or more ValueSource instances and calculates the distances between the two vectors. Each ValueSource must be a number.
-`dist(1,x,y,z,e,f,g)`: Manhattan distance between (x,y,z) and (e,f,g) where each letter is a field name.
+There must be an even number of ValueSource instances passed in and the method assumes that the first half represent the first vector and the second half represent the second vector.
-|docfreq(field,val) |Returns the number of documents that contain the term in the field. This is a constant (the same value for all documents in the index).
+*Syntax Examples*
-You can quote the term if it's more complex, or do parameter substitution for the term value. a|`docfreq(text,'solr')`
+* `dist(2, x, y, 0, 0)`: calculates the Euclidean distance between (0,0) and (x,y) for each document.
+* `dist(1, x, y, 0, 0)`: calculates the Manhattan (taxicab) distance between (0,0) and (x,y) for each document.
+* `dist(2, x,y,z,0,0,0):` Euclidean distance between (0,0,0) and (x,y,z) for each document.
+* `dist(1,x,y,z,e,f,g)`: Manhattan distance between (x,y,z) and (e,f,g) where each letter is a field name.
-`...&defType=func` `&q=docfreq(text,$myterm)&myterm=solr`
+=== docfreq(field,val) Function
+Returns the number of documents that contain the term in the field. This is a constant (the same value for all documents in the index).
-|field[[FunctionQueries-field]] a|
+You can quote the term if it's more complex, or do parameter substitution for the term value.
+
+*Syntax Examples*
+
+* `docfreq(text,'solr')`
+* `...&defType=func` `&q=docfreq(text,$myterm)&myterm=solr`
+
+[[FunctionQueries-field]]
+=== field Function
Returns the numeric docValues or indexed value of the field with the specified name. In its simplest (single argument) form, this function can only be used on single valued fields, and can be called using the name of the field as a string, or for most conventional field names simply use the field name by itself with out using the `field(...)` syntax.
-When using docValues, an optional 2nd argument can be specified to select the "`min"` or "```max```" value of multivalued fields.
+When using docValues, an optional 2nd argument can be specified to select the `min` or `max` value of multivalued fields.
0 is returned for documents without a value in the field.
- a|
+*Syntax Examples*
These 3 examples are all equivalent:
* `myFloatFieldName`
* `field(myFloatFieldName)`
* `field("myFloatFieldName")`
-The last form is convinient when your field name is atypical:
+The last form is convenient when your field name is atypical:
* `field("my complex float fieldName")`
@@ -139,11 +173,21 @@ For multivalued docValues fields:
* `field(myMultiValuedFloatField,min)`
* `field(myMultiValuedFloatField,max)`
-|hsin |The Haversine distance calculates the distance between two points on a sphere when traveling along the sphere. The values must be in radians. `hsin` also take a Boolean argument to specify whether the function should convert its output to radians. |`hsin(2, true, x, y, 0, 0)`
+=== hsin Function
+The Haversine distance calculates the distance between two points on a sphere when traveling along the sphere. The values must be in radians. `hsin` also take a Boolean argument to specify whether the function should convert its output to radians.
+
+*Syntax Example*
-|idf |Inverse document frequency; a measure of whether the term is common or rare across all documents. Obtained by dividing the total number of documents by the number of documents containing the term, and then taking the logarithm of that quotient. See also `tf`. |`idf(fieldName,'solr')`: measures the inverse of the frequency of the occurrence of the term `'solr'` in `fieldName`.
+* `hsin(2, true, x, y, 0, 0)`
-|if a|
+=== idf Function
+Inverse document frequency; a measure of whether the term is common or rare across all documents. Obtained by dividing the total number of documents by the number of documents containing the term, and then taking the logarithm of that quotient. See also `tf`.
+
+*Syntax Example*
+
+* `idf(fieldName,'solr')`: measures the inverse of the frequency of the occurrence of the term `'solr'` in `fieldName`.
+
+=== if Function
Enables conditional function queries. In `if(test,value1,value2)`:
* `test` is or refers to a logical value or expression that returns a logical value (TRUE or FALSE).
@@ -152,174 +196,312 @@ Enables conditional function queries. In `if(test,value1,value2)`:
An expression can be any function which outputs boolean values, or even functions returning numeric values, in which case value 0 will be interpreted as false, or strings, in which case empty string is interpreted as false.
- a|`if(termfreq` `(cat,'electronics'),` `popularity,42)`: This function checks each document for the to see if it contains the term "```electronics```" in the `cat` field. If it does, then the value of the `popularity` field is returned, otherwise the value of `42` is returned.
+*Syntax Example*
+
+* `if(termfreq (cat,'electronics'),popularity,42)`: This function checks each document for to see if it contains the term "electronics" in the `cat` field. If it does, then the value of the `popularity` field is returned, otherwise the value of `42` is returned.
-|linear |Implements `m*x+c` where `m` and `c` are constants and `x` is an arbitrary function. This is equivalent to `sum(product(m,x),c)`, but slightly more efficient as it is implemented as a single function. a|`linear(x,m,c)`
+=== linear Function
+Implements `m*x+c` where `m` and `c` are constants and `x` is an arbitrary function. This is equivalent to `sum(product(m,x),c)`, but slightly more efficient as it is implemented as a single function.
-`linear(x,2,4)` returns `2*x+4`
+*Syntax Examples*
-|log |Returns the log base 10 of the specified function. a|
-`log(x)`
+* `linear(x,m,c)`
+* `linear(x,2,4)`: returns `2*x+4`
-`log(sum(x,100))`
+=== log Function
+Returns the log base 10 of the specified function.
-|map |Maps any values of an input function x that fall within min and max inclusive to the specified target. The arguments min and max must be constants. The arguments `target` and `default` can be constants or functions. If the value of x does not fall between min and max, then either the value of x is returned, or a default value is returned if specified as a 5th argument. a|
-`map(x,min,max,target)` `map(x,0,0,1)` - changes any values of 0 to 1. This can be useful in handling default 0 values.
+*Syntax Examples*
-`map(x,min,max,target,default)` `map(x,0,100,1,-1)` - changes any values between `0` and `100` to `1`, and all other values to` -1`.
+* `log(x)`
+* `log(sum(x,100))`
-`map(x,0,100,` `sum(x,599),` `docfreq(text,solr))` - changes any values between `0` and `100` to x+599, and all other values to frequency of the term 'solr' in the field text.
+=== map Function
+Maps any values of an input function `x` that fall within `min` and `max` inclusive to the specified `target`. The arguments `min` and `max` must be constants. The arguments `target` and `default` can be constants or functions.
-|max a|
-Returns the maximum numeric value of multiple nested functions or constants, which are specified as arguments: `max(x,y,...)`. The max function can also be useful for "bottoming out" another function or field at some specified constant.
+If the value of `x` does not fall between `min` and `max`, then either the value of `x` is returned, or a default value is returned if specified as a 5th argument.
-(Use the `field(myfield,max)` syntax for <<FunctionQueries-field,selecting the maximum value of a single multivalued field>>)
+*Syntax Examples*
- |`max(myfield,myotherfield,0)`
+* `map(x,min,max,target)`
+** `map(x,0,0,1)`: Changes any values of 0 to 1. This can be useful in handling default 0 values.
+* `map(x,min,max,target,default)`
+** `map(x,0,100,1,-1)`: Changes any values between `0` and `100` to `1`, and all other values to` -1`.
+* `map(x,0,100,sum(x,599),docfreq(text,solr))`: Changes any values between `0` and `100` to x+599, and all other values to frequency of the term 'solr' in the field text.
-|maxdoc |Returns the number of documents in the index, including those that are marked as deleted but have not yet been purged. This is a constant (the same value for all documents in the index). |`maxdoc()`
+=== max Function
+Returns the maximum numeric value of multiple nested functions or constants, which are specified as arguments: `max(x,y,...)`. The `max` function can also be useful for "bottoming out" another function or field at some specified constant.
-|min a|
-Returns the minimum numeric value of multiple nested functions of constants, which are specified as arguments: `min(x,y,...)`. The min function can also be useful for providing an "upper bound" on a function using a constant.
+Use the `field(myfield,max)` syntax for <<FunctionQueries-field,selecting the maximum value of a single multivalued field>>.
-(Use the `field(myfield,min)` <<FunctionQueries-field,syntax for selecting the minimum value of a single multivalued field>>)
+*Syntax Example*
- |`min(myfield,myotherfield,0)`
+* `max(myfield,myotherfield,0)`
-|ms a|
-Returns milliseconds of difference between its arguments. Dates are relative to the Unix or POSIX time epoch, midnight, January 1, 1970 UTC. Arguments may be the name of an indexed `TrieDateField`, or date math based on a <<working-with-dates.adoc#working-with-dates,constant date or `NOW`>>.
+=== maxdoc Function
+Returns the number of documents in the index, including those that are marked as deleted but have not yet been purged. This is a constant (the same value for all documents in the index).
+
+*Syntax Example*
+
+* `maxdoc()`
+
+=== min Function
+Returns the minimum numeric value of multiple nested functions of constants, which are specified as arguments: `min(x,y,...)`. The `min` function can also be useful for providing an "upper bound" on a function using a constant.
+
+Use the `field(myfield,min)` <<FunctionQueries-field,syntax for selecting the minimum value of a single multivalued field>>.
+
+*Syntax Example*
+
+* `min(myfield,myotherfield,0)`
+
+=== ms Function
+Returns milliseconds of difference between its arguments. Dates are relative to the Unix or POSIX time epoch, midnight, January 1, 1970 UTC.
+
+Arguments may be the name of an indexed `TrieDateField`, or date math based on a <<working-with-dates.adoc#working-with-dates,constant date or `NOW`>>.
* `ms()`: Equivalent to `ms(NOW)`, number of milliseconds since the epoch.
* `ms(a):` Returns the number of milliseconds since the epoch that the argument represents.
-* `ms(a,b)` : Returns the number of milliseconds that b occurs before a (that is, a - b) a|`ms(NOW/DAY)`
+* `ms(a,b)` : Returns the number of milliseconds that b occurs before a (that is, a - b)
-`ms(2000-01-01T00:00:00Z)`
+*Syntax Examples*
-`ms(mydatefield)`
+* `ms(NOW/DAY)`
+* `ms(2000-01-01T00:00:00Z)`
+* `ms(mydatefield)`
+* `ms(NOW,mydatefield)`
+* `ms(mydatefield, 2000-01-01T00:00:00Z)`
+* `ms(datefield1, datefield2)`
-`ms(NOW,mydatefield)`
+=== norm(_field_) Function
+Returns the "norm" stored in the index for the specified field. This is the product of the index time boost and the length normalization factor, according to the {lucene-javadocs}/core/org/apache/lucene/search/similarities/Similarity.html[Similarity] for the field.
-`ms(mydatefield, 2000-01-01T00:00:00Z)`
+*Syntax Example*
-`ms(datefield1, datefield2)`
+* `norm(fieldName)`
-|norm(_field_) |Returns the "norm" stored in the index for the specified field. This is the product of the index time boost and the length normalization factor, according to the {lucene-javadocs}/core/org/apache/lucene/search/similarities/Similarity.html[Similarity] for the field. |`norm(fieldName)`
+=== numdocs Function
+Returns the number of documents in the index, not including those that are marked as deleted but have not yet been purged. This is a constant (the same value for all documents in the index).
-|numdocs |Returns the number of documents in the index, not including those that are marked as deleted but have not yet been purged. This is a constant (the same value for all documents in the index). |`numdocs()`
+*Syntax Example*
-|ord a|
-Returns the ordinal of the indexed field value within the indexed list of terms for that field in Lucene index order (lexicographically ordered by unicode value), starting at 1. In other words, for a given field, all values are ordered lexicographically; this function then returns the offset of a particular value in that ordering. The field must have a maximum of one value per document (not multi-valued). 0 is returned for documents without a value in the field.
+* `numdocs()`
-[IMPORTANT]
-====
-`ord()` depends on the position in an index and can change when other documents are inserted or deleted.
-====
+=== ord Function
+Returns the ordinal of the indexed field value within the indexed list of terms for that field in Lucene index order (lexicographically ordered by unicode value), starting at 1.
+
+In other words, for a given field, all values are ordered lexicographically; this function then returns the offset of a particular value in that ordering. The field must have a maximum of one value per document (not multi-valued). `0` is returned for documents without a value in the field.
+
+IMPORTANT: `ord()` depends on the position in an index and can change when other documents are inserted or deleted.
See also `rord` below.
- a|`ord(myIndexedField)`
+*Syntax Example*
+
+* `ord(myIndexedField)`
+
+* If there were only three values ("apple","banana","pear") for a particular field X, then `ord(X)` would be `1` for documents containing "apple", `2` for documents containing "banana", etc.
-Example: If there were only three values ("apple","banana","pear") for a particular field X, then `ord(X)` would be `1` for documents containing "apple", `2` for documents containing "banana", etc.
+=== payload Function
+Returns the float value computed from the decoded payloads of the term specified.
-|payload a|
-Returns the float value computed from the decoded payloads of the term specified. The return value is computed using the `min`, `max`, or `average` of the decoded payloads. A special `first` function can be used instead of the others, to short-circuit term enumeration and return only the decoded payload of the first term. The field specified must have float or integer payload encoding capability (via `DelimitedPayloadTokenFilter` or `NumericPayloadTokenFilter`). If no payload is found for the term, the default value is returned.
+The return value is computed using the `min`, `max`, or `average` of the decoded payloads. A special `first` function can be used instead of the others, to short-circuit term enumeration and return only the decoded payload of the first term.
+
+The field specified must have float or integer payload encoding capability (via `DelimitedPayloadTokenFilter` or `NumericPayloadTokenFilter`). If no payload is found for the term, the default value is returned.
* `payload(field_name,term)`: default value is 0.0, `average` function is used.
* `payload(field_name,term,default_value)`: default value can be a constant, field name, or another float returning function. `average` function used.
-* `payload(field_name,term,default_value,function)`: function values can be `min`, `max`, `average`, or `first`. |`payload(payloaded_field_dpf,term,0.0,first)`
+* `payload(field_name,term,default_value,function)`: function values can be `min`, `max`, `average`, or `first`.
+
+*Syntax Example*
+
+* `payload(payloaded_field_dpf,term,0.0,first)`
+
+=== pow Function
-|pow |Raises the specified base to the specified power. `pow(x,y)` raises x to the power of y. a|`pow(x,y)`
+Raises the specified base to the specified power. `pow(x,y)` raises `x` to the power of `y`.
-`pow(x,log(y))`
+*Syntax Examples*
-`pow(x,0.5):` the same as `sqrt`
+* `pow(x,y)`
+* `pow(x,log(y))`
+* `pow(x,0.5):` the same as `sqrt`
-|product |Returns the product of multiple values or functions, which are specified in a comma-separated list. `mul(...)` may also be used as an alias for this function. |`product(x,y,...)` `product(x,2)` `product(x,y)mul(x,y)`
+=== product Function
+Returns the product of multiple values or functions, which are specified in a comma-separated list. `mul(...)` may also be used as an alias for this function.
-|query |Returns the score for the given subquery, or the default value for documents not matching the query. Any type of subquery is supported through either parameter de-referencing `$otherparam` or direct specification of the query string in the <<local-parameters-in-queries.adoc#local-parameters-in-queries,Local Parameters>> through the `v` key. a|`query(subquery, default)`
+*Syntax Examples*
-`q=product` `(popularity,` `query({!dismax v='solr rocks'})`: returns the product of the popularity and the score of the DisMax query.
+* `product(x,y,...)`
+* `product(x,2)`
+* `product(x,y)mul(x,y)`
-`q=product` `(popularity,` `query($qq))&qq={!dismax}solr rocks`: equivalent to the previous query, using parameter de-referencing.
+=== query Function
+Returns the score for the given subquery, or the default value for documents not matching the query. Any type of subquery is supported through either parameter de-referencing `$otherparam` or direct specification of the query string in the <<local-parameters-in-queries.adoc#local-parameters-in-queries,Local Parameters>> through the `v` key.
-`q=product` `(popularity,` `query($qq,0.1))` `&qq={!dismax}` `solr rocks`: specifies a default score of 0.1 for documents that don't match the DisMax query.
-|recip a|
+*Syntax Examples*
+
+* `query(subquery, default)`
+* `q=product (popularity,query({!dismax v='solr rocks'})`: returns the product of the popularity and the score of the DisMax query.
+* `q=product (popularity,query($qq))&qq={!dismax}solr rocks`: equivalent to the previous query, using parameter de-referencing.
+* `q=product (popularity,query($qq,0.1))&qq={!dismax}solr rocks`: specifies a default score of 0.1 for documents that don't match the DisMax query.
+
+=== recip Function
Performs a reciprocal function with `recip(x,m,a,b)` implementing `a/(m*x+b)` where `m,a,b` are constants, and `x` is any arbitrarily complex function.
-When a and b are equal, and x>=0, this function has a maximum value of 1 that drops as x increases. Increasing the value of a and b together results in a movement of the entire function to a flatter part of the curve. These properties can make this an ideal function for boosting more recent documents when x is `rord(datefield)`.
+When `a` and `b` are equal, and `x>=0`, this function has a maximum value of `1` that drops as `x` increases. Increasing the value of `a` and `b` together results in a movement of the entire function to a flatter part of the curve. These properties can make this an ideal function for boosting more recent documents when x is `rord(datefield)`.
+
+*Syntax Examples*
+
+* `recip(myfield,m,a,b)`
+* `recip(rord` `(creationDate), 1,1000,1000)`
+
+=== rord Function
+Returns the reverse ordering of that returned by `ord`.
+
+*Syntax Example*
+
+* `rord(myDateField)`
+
+=== scale Function
+Scales values of the function `x` such that they fall between the specified `minTarget` and `maxTarget` inclusive. The current implementation traverses all of the function values to obtain the min and max, so it can pick the correct scale.
+
+The current implementation cannot distinguish when documents have been deleted or documents that have no value. It uses `0.0` values for these cases. This means that if values are normally all greater than `0.0`, one can still end up with `0.0` as the `min` value to map from. In these cases, an appropriate `map()` function could be used as a workaround to change `0.0` to a value in the real range, as shown here: `scale(map(x,0,0,5),1,2)`
-a|`recip(myfield,m,a,b)`
+*Syntax Examples*
-`recip(rord` `(creationDate), 1,1000,1000)`
+* `scale(x, minTarget, maxTarget)`
+* `scale(x,1,2)`: scales the values of x such that all values will be between 1 and 2 inclusive.
-|rord |Returns the reverse ordering of that returned by `ord`. |`rord(myDateField)`
+=== sqedist Function
+The Square Euclidean distance calculates the 2-norm (Euclidean distance) but does not take the square root, thus saving a fairly expensive operation. It is often the case that applications that care about Euclidean distance do not need the actual distance, but instead can use the square of the distance. There must be an even number of ValueSource instances passed in and the method assumes that the first half represent the first vector and the second half represent the second vector.
-|scale a|
-Scales values of the function x such that they fall between the specified `minTarget` and `maxTarget` inclusive. The current implementation traverses all of the function values to obtain the min and max, so it can pick the correct scale.
+*Syntax Example*
-The current implementation cannot distinguish when documents have been deleted or documents that have no value. It uses 0.0 values for these cases. This means that if values are normally all greater than 0.0, one can still end up with 0.0 as the min value to map from. In these cases, an appropriate map() function could be used as a workaround to change 0.0 to a value in the real range, as shown here: `scale(map(x,0,0,5),1,2)` a|`scale(x, minTarget, maxTarget)`
+* `sqedist(x_td, y_td, 0, 0)`
-`scale(x,1,2)`: scales the values of x such that all values will be between 1 and 2 inclusive.
+=== sqrt Function
+Returns the square root of the specified value or function.
-|sqedist |The Square Euclidean distance calculates the 2-norm (Euclidean distance) but does not take the square root, thus saving a fairly expensive operation. It is often the case that applications that care about Euclidean distance do not need the actual distance, but instead can use the square of the distance. There must be an even number of ValueSource instances passed in and the method assumes that the first half represent the first vector and the second half represent the second vector. |`sqedist(x_td, y_td, 0, 0)`
+*Syntax Example*
-|sqrt |Returns the square root of the specified value or function. |`sqrt(x)sqrt(100)sqrt(sum(x,100))`
+* `sqrt(x)sqrt(100)sqrt(sum(x,100))`
-|strdist a|Calculate the distance between two strings. Uses the Lucene spell checker `StringDistance` interface and supports all of the implementations available in that package, plus allows applications to plug in their own via Solr's resource loading capabilities. `strdist` takes (string1, string2, distance measure).
+=== strdist Function
+Calculate the distance between two strings. Uses the Lucene spell checker `StringDistance` interface and supports all of the implementations available in that package, plus allows applications to plug in their own via Solr's resource loading capabilities. `strdist` takes (string1, string2, distance measure).
Possible values for distance measure are:
* jw: Jaro-Winkler
* edit: Levenstein or Edit distance
* ngram: The NGramDistance, if specified, can optionally pass in the ngram size too. Default is 2.
-* FQN: Fully Qualified class Name for an implementation of the StringDistance interface. Must have a no-arg constructor. |`strdist("SOLR",id,edit)`
+* FQN: Fully Qualified class Name for an implementation of the StringDistance interface. Must have a no-arg constructor.
-|sub |Returns `x-y` from `sub(x,y)`. a|`sub(myfield,myfield2)`
+*Syntax Example*
-`sub(100, sqrt(myfield))`
+* `strdist("SOLR",id,edit)`
-|sum |Returns the sum of multiple values or functions, which are specified in a comma-separated list. `add(...)` may be used as an alias for this function a|`sum(x,y,...) sum(x,1)`
+=== sub Function
+Returns `x-y` from `sub(x,y)`.
-`sum(x,y)`
+*Syntax Examples*
-`sum(sqrt(x),log(y),z,0.5)`
+* `sub(myfield,myfield2)`
+* `sub(100, sqrt(myfield))`
-`add(x,y)`
+=== sum Function
+Returns the sum of multiple values or functions, which are specified in a comma-separated list. `add(...)` may be used as an alias for this function.
-|sumtotaltermfreq |Returns the sum of `totaltermfreq` values for all terms in the field in the entire index (i.e., the number of indexed tokens for that field). (Aliases `sumtotaltermfreq` to `sttf`.) a|If doc1:(fieldX:A B C) and doc2:(fieldX:A A A A):
+*Syntax Examples*
-`docFreq(fieldX:A)` = 2 (A appears in 2 docs)
+* `sum(x,y,...) sum(x,1)`
+* `sum(x,y)`
+* `sum(sqrt(x),log(y),z,0.5)`
+* `add(x,y)`
-`freq(doc1, fieldX:A)` = 4 (A appears 4 times in doc 2)
+=== sumtotaltermfreq Function
+Returns the sum of `totaltermfreq` values for all terms in the field in the entire index (i.e., the number of indexed tokens for that field). (Aliases `sumtotaltermfreq` to `sttf`.)
-`totalTermFreq(fieldX:A)` = 5 (A appears 5 times across all docs)
+*Syntax Example*
+If doc1:(fieldX:A B C) and doc2:(fieldX:A A A A):
-`sumTotalTermFreq(fieldX)` = 7 in `fieldX`, there are 5 As, 1 B, 1 C
+* `docFreq(fieldX:A)` = 2 (A appears in 2 docs)
+* `freq(doc1, fieldX:A)` = 4 (A appears 4 times in doc 2)
+* `totalTermFreq(fieldX:A)` = 5 (A appears 5 times across all docs)
+* `sumTotalTermFreq(fieldX)` = 7 in `fieldX`, there are 5 As, 1 B, 1 C
-|termfreq |Returns the number of times the term appears in the field for that document. |`termfreq(text,'memory')`
+=== termfreq Function
+Returns the number of times the term appears in the field for that document.
-|tf |Term frequency; returns the term frequency factor for the given term, using the {lucene-javadocs}/core/org/apache/lucene/search/similarities/Similarity.html[Similarity] for the field. The `tf-idf` value increases proportionally to the number of times a word appears in the document, but is offset by the frequency of the word in the document, which helps to control for the fact that some words are generally more common than others. See also `idf`. |`tf(text,'solr')`
+*Syntax Example*
-|top a|
+* `termfreq(text,'memory')`
+
+=== tf Function
+Term frequency; returns the term frequency factor for the given term, using the {lucene-javadocs}/core/org/apache/lucene/search/similarities/Similarity.html[Similarity] for the field. The `tf-idf` value increases proportionally to the number of times a word appears in the document, but is offset by the frequency of the word in the document, which helps to control for the fact that some words are generally more common than others. See also `idf`.
+
+*Syntax Examples*
+
+* `tf(text,'solr')`
+
+=== top Function
Causes the function query argument to derive its values from the top-level IndexReader containing all parts of an index. For example, the ordinal of a value in a single segment will be different from the ordinal of that same value in the complete index.
-The `ord()` and `rord()` functions implicitly use `top()`, and hence `ord(foo)` is equivalent to `top(ord(foo))`. |
+The `ord()` and `rord()` functions implicitly use `top()`, and hence `ord(foo)` is equivalent to `top(ord(foo))`.
-|totaltermfreq |Returns the number of times the term appears in the field in the entire index. (Aliases `totaltermfreq` to `ttf`.) |`ttf(text,'memory')`
-|===
+=== totaltermfreq Function
+Returns the number of times the term appears in the field in the entire index. (Aliases `totaltermfreq` to `ttf`.)
+*Syntax Example*
+
+* `ttf(text,'memory')`
+
+== Boolean Functions
The following functions are boolean – they return true or false. They are mostly useful as the first argument of the `if` function, and some of these can be combined. If used somewhere else, it will yield a '1' or '0'.
-[width="100%",options="header",]
-|===
-|Function |Description |Syntax Examples
-|and |Returns a value of true if and only if all of its operands evaluate to true. |`and(not` `(exists` `(popularity)),` `exists` `(price)):` returns `true` for any document which has a value in the `price` field, but does not have a value in the `popularity` field
-|or |A logical disjunction. |`or(value1,value2):` TRUE if either `value1` or `value2` is true.
-|xor |Logical exclusive disjunction, or one or the other but not both. |`xor(field1,field2)` returns TRUE if either `field1` or `field2` is true; FALSE if both are true.
-|not |The logically negated value of the wrapped function. |`not(exists(author))`: TRUE only when `exists(author)` is false.
-|exists |Returns TRUE if any member of the field exists. |`exists(author)` returns TRUE for any document has a value in the "author" field. `exists(query(price:5.00))` returns TRUE if "price" matches "5.00".
-|gt, gte, lt, lte, eq |5 comparison functions: Greater Than, Greater Than or Equal, Less Than, Less Than or Equal, Equal |`if(lt(ms(mydatefield),315569259747),0.8,1)` translates to this pseudocode: `if mydatefield < 315569259747 then 0.8 else 1`
-|===
+=== and Function
+Returns a value of true if and only if all of its operands evaluate to true.
+
+*Syntax Example*
+
+* `and(not(exists(popularity)),exists(price))`: returns `true` for any document which has a value in the `price` field, but does not have a value in the `popularity` field.
+
+=== or Function
+A logical disjunction.
+
+*Syntax Example*
+
+* `or(value1,value2):` `true` if either `value1` or `value2` is true.
+
+=== xor Function
+Logical exclusive disjunction, or one or the other but not both.
+
+*Syntax Example*
+
+* `xor(field1,field2)` returns `true` if either `field1` or `field2` is true; FALSE if both are true.
+
+=== not Function
+The logically negated value of the wrapped function.
+
+*Syntax Example*
+
+* `not(exists(author))`: `true` only when `exists(author)` is false.
+
+=== exists Function
+Returns `true` if any member of the field exists.
+
+*Syntax Example*
+
+* `exists(author)`: returns `true` for any document has a value in the "author" field.
+* `exists(query(price:5.00))`: returns `true` if "price" matches "5.00".
+
+=== Comparison Functions
+`gt`, `gte`, `lt`, `lte`, `eq`
+
+5 comparison functions: Greater Than, Greater Than or Equal, Less Than, Less Than or Equal, Equal
+
+*Syntax Example*
+* `if(lt(ms(mydatefield),315569259747),0.8,1)` translates to this pseudocode: `if mydatefield < 315569259747 then 0.8 else 1`
+
[[FunctionQueries-ExampleFunctionQueries]]
== Example Function Queries