Added an error message for when child mapping is not properly configured (incorrect type)
# Distance scoring

It might sometimes be desirable to have a tool available that allows to multiply the original score for a document with a function that decays depending on the distance of a numeric field value of the document from a user given reference.

To use distance scoring on a query that has numerical fields, the user has to define

 1. a reference and
 2. a scale

for each field you want the function applied on. A reference is needed to define a distance for the document and a scale to define the rate of decay.

For each field in each found document, a decay function is be computed. The original score of the query is then be multiplied with the individual function values computed for the fields. Distance scoring in this case behaves like a range query with smoothed box edges.

Distance scoring can be applied for an arbitrary number of numeric fields.

## Example

Suppose you are searching for a hotel in a certain town. Your budget is limited. Also, you would like the hotel to be close to the town center, so the farther the hotel is from the desired location the less likely you are to check in.
You would like the query results that match your criterion (for example, "hotel, Nancy, non-smoker") to be scored with respect to distance to the town center and also the price.

Intuitively, you would like to define the town center as the origin and maybe you are willing to walk 2km to the town center from the hotel.
In this case your *reference* for the location field is the town center and the *scale* is ~2km.

If your budget is low, you would probably prefer something cheap above something expensive.
For the price field, the *reference* would be 0 Euros and the *scale* depends on how much you are willing to pay, for example 20 Euros.

## Usage

In the above example, the fields might be called "price" for the price of the hotel and "location" for the coordinates of this hotel.

T apply distance scoring, embed any query in a distance_score query like this:

	curl 'localhost:9200/hotels/_search/' -d '{
		"query" : {
			"distance_score" : {
				"query" : {
    				 "match": { "properties": "balcony" }
                },
 				"gauss" : {
    				"location" : {
						"reference": "11, 12",
						"scale" : "2km"
					},
					"price" : {
						"reference": "0",
						"scale" : "20"
					}
				}
			}
 		}
	}'

The parameters (reference and scale) for the function (here is is "gauss") are given after the query for each field. Three different functions can be applied

## Decay Functions

### Normal decay ("gauss")

A contour plot for the normal decay for two fields looks like this:

![gausscontour](https://f.cloud.github.com/assets/4320215/768157/cd0e18a6-e898-11e2-9b3c-f0145078bd6f.png)
![gausssurf](https://f.cloud.github.com/assets/4320215/768160/ec43c928-e898-11e2-8e0d-f3c4519dbd89.png)

Suppose your original search results matches three hotels : "Backback Nap", "Drink n Drive" and "BnB Bellevue".
"Drink n Drive" is pretty far from your defined location (nealy 2 km) and is not too cheap (about 13 Euros) so its original score is multiplied with a factor of 0.56. "BnB Bellevue" and "Backback Nap" are both pretty close to the location you want too book but "BnB Bellevue" is cheaper, so it gets a multiplier of 0.86 whereas "Backpack Nap" gets a value of 0.66."

The function used for rescoring is

<a href="http://www.codecogs.com/eqnedit.php?latex=\exp(-\frac{(x-\mu)^2}{\sigma^2})" target="_blank"><img src="http://latex.codecogs.com/gif.latex?\mathcal{S}(doc)=\exp(-\frac{(location_{doc}-\mu_l)^2}{2\sigma^2_l})\exp(-\frac{(price_{doc}-\mu_p)^2}{2\sigma^2_p})," title="\exp(-\frac{x-\mu}{2\sigma^2})" /></a>

where <a href="http://www.codecogs.com/eqnedit.php" ><img src="http://latex.codecogs.com/gif.latex?\mu_l"  /></a> is the town center, <a href="http://www.codecogs.com/eqnedit.php" ><img src="http://latex.codecogs.com/gif.latex?\sigma_l"  /></a> is the scale of the location (2km in this case), <a href="http://www.codecogs.com/eqnedit.php" ><img src="http://latex.codecogs.com/gif.latex?\mu_p"  /></a> is the price reference (0 Euros since your budget is low) and <a href="http://www.codecogs.com/eqnedit.php" ><img src="http://latex.codecogs.com/gif.latex?\sigma_p"  /></a> is the scale of the price (20 Euros in this case).
### Exponential decay ("exp")

A contour plot for the exponential decay for two fields looks like this:

![expcontour](https://f.cloud.github.com/assets/4320215/768161/082975c0-e899-11e2-86f7-174c3a729d64.png)
![expsurf](https://f.cloud.github.com/assets/4320215/768162/0b606884-e899-11e2-907b-aefc77eefef6.png)

The function used for rescoring is

<a href="http://www.codecogs.com/eqnedit.php?latex=\exp(-\frac{abs(x-\mu)^2}{\sigma})" target="_blank"><img src="http://latex.codecogs.com/gif.latex?\mathcal{S}(doc)=\exp(-\frac{|location_{doc}-\mu_l|}{\sigma_l})\exp(-\frac{|price_{doc}-\mu_p|}{\sigma_p})," title="\exp(-\frac{x-\mu}{2\sigma^2})" /></a>

where again <a href="http://www.codecogs.com/eqnedit.php" ><img src="http://latex.codecogs.com/gif.latex?\mu_l"  /></a> is the town center, <a href="http://www.codecogs.com/eqnedit.php" ><img src="http://latex.codecogs.com/gif.latex?\sigma_l"  /></a> is the scale of the location (2km in this case), <a href="http://www.codecogs.com/eqnedit.php" ><img src="http://latex.codecogs.com/gif.latex?\mu_p"  /></a> is the price reference (0 Euros since your budget is low) and <a href="http://www.codecogs.com/eqnedit.php" ><img src="http://latex.codecogs.com/gif.latex?\sigma_p"  /></a> is the scale of the price (20 Euros in this case).

###  'Linear' decay ("lin")

A contour plot for the 'linear' decay for two fields looks like this:

![lincontour](https://f.cloud.github.com/assets/4320215/768164/1775b0ca-e899-11e2-9f4a-776b406305c6.png)
![linsurf](https://f.cloud.github.com/assets/4320215/768165/19d8b1aa-e899-11e2-91bc-6b0553e8d722.png)

The function used for rescoring is

<a href="http://www.codecogs.com/eqnedit.php?latex=\frac{abs(x-\mu)^2}{\sigma})" target="_blank"><img src="http://latex.codecogs.com/gif.latex?\mathcal{S}(doc)=\max(\frac{\sigma_l-(location_{doc}-\mu_l)}{\sigma_l},0)\max(\frac{\sigma_p-(price_{doc}-\mu_p)}{\sigma_p},0)," title="\exp(-\frac{x-\mu}{2\sigma^2})" /></a>

where again <a href="http://www.codecogs.com/eqnedit.php" ><img src="http://latex.codecogs.com/gif.latex?\mu_l"  /></a> is the town center, <a href="http://www.codecogs.com/eqnedit.php" ><img src="http://latex.codecogs.com/gif.latex?\sigma_l"  /></a> is the scale of the location (2km in this case), <a href="http://www.codecogs.com/eqnedit.php" ><img src="http://latex.codecogs.com/gif.latex?\mu_p"  /></a> is the price reference (0 Euros since your budget is low) and <a href="http://www.codecogs.com/eqnedit.php" ><img src="http://latex.codecogs.com/gif.latex?\sigma_p"  /></a> is the scale of the price (20 Euros in this case).

In contrast to the normal and exponential decay, this function actually sets the score to 0 if the field value exceeds the user gived scale value.

## Supported fields
Only single valued numeric fields, including time and geo locations, are be supported.

## What is a field is missing?

Is the numeric field is missing in the document, that field will not be taken into account at all for this document.