Working with Currencies and Exchange Rates

The currency FieldType provides support for monetary values to Solr/Lucene with query-time currency conversion and exchange rates. The following features are supported:

  • Point queries

  • Range queries

  • Function range queries

  • Sorting

  • Currency parsing by either currency code or symbol

  • Symmetric & asymmetric exchange rates (asymmetric exchange rates are useful if there are fees associated with exchanging the currency)

  • Range faceting (using either facet.range or type:range in json.facet) as long as the start and end values are specified in the same Currency.

Configuring Currencies

CurrencyField has been Deprecated

CurrencyField has been deprecated in favor of CurrencyFieldType; all configuration examples below use CurrencyFieldType.

The currency field type is defined in schema.xml. This is the default configuration of this type.

<fieldType name="currency" class="solr.CurrencyFieldType"
           amountLongSuffix="_l_ns" codeStrSuffix="_s_ns"
           defaultCurrency="USD" currencyConfig="currency.xml" />

In this example, we have defined the name and class of the field type, and defined the defaultCurrency as "USD", for U.S. Dollars. We have also defined a currencyConfig to use a file called "currency.xml". This is a file of exchange rates between our default currency to other currencies. There is an alternate implementation that would allow regular downloading of currency data. See Exchange Rates below for more.

Many of the example schemas that ship with Solr include a dynamic field that uses this type, such as this example:

    <dynamicField name="*_c"   type="currency" indexed="true"  stored="true"/>

This dynamic field would match any field that ends in _c and make it a currency typed field.

At indexing time, money fields can be indexed in a native currency. For example, if a product on an e-commerce site is listed in Euros, indexing the price field as "1000,EUR" will index it appropriately. The price should be separated from the currency by a comma, and the price must be encoded with a floating point value (a decimal point).

During query processing, range and point queries are both supported.

Sub-field Suffixes

You must specify parameters amountLongSuffix and codeStrSuffix, corresponding to dynamic fields to be used for the raw amount and the currency dynamic sub-fields, for example:

<fieldType name="currency" class="solr.CurrencyFieldType"
           amountLongSuffix="_l_ns" codeStrSuffix="_s_ns"
           defaultCurrency="USD" currencyConfig="currency.xml" />

In the above example, the raw amount field will use the "*_l_ns" dynamic field, which must exist in the schema and use a long field type, i.e., one that extends LongValueFieldType. The currency code field will use the "*_s_ns" dynamic field, which must exist in the schema and use a string field type, i.e., one that is or extends StrField.

Atomic Updates won’t work if dynamic sub-fields are stored

As noted on Updating Parts of Documents, stored dynamic sub-fields will cause indexing to fail when you use Atomic Updates. To avoid this problem, specify stored="false" on those dynamic fields.

Exchange Rates

You configure exchange rates by specifying a provider. Natively, two provider types are supported: FileExchangeRateProvider or OpenExchangeRatesOrgProvider.

FileExchangeRateProvider

This provider requires you to provide a file of exchange rates. It is the default, meaning that to use this provider you only need to specify the file path and name as a value for currencyConfig in the definition for this type.

There is a sample currency.xml file included with Solr, found in the same directory as the schema.xml file. Here is a small snippet from this file:

<currencyConfig version="1.0">
  <rates>
    <!-- Updated from http://www.exchangerate.com/ at 2011-09-27 -->
    <rate from="USD" to="ARS" rate="4.333871" comment="ARGENTINA Peso" />
    <rate from="USD" to="AUD" rate="1.025768" comment="AUSTRALIA Dollar" />
    <rate from="USD" to="EUR" rate="0.743676" comment="European Euro" />
    <rate from="USD" to="CAD" rate="1.030815" comment="CANADA Dollar" />

    <!-- Cross-rates for some common currencies -->
    <rate from="EUR" to="GBP" rate="0.869914" />
    <rate from="EUR" to="NOK" rate="7.800095" />
    <rate from="GBP" to="NOK" rate="8.966508" />

    <!-- Asymmetrical rates -->
    <rate from="EUR" to="USD" rate="0.5" />
  </rates>
</currencyConfig>

OpenExchangeRatesOrgProvider

You can configure Solr to download exchange rates from OpenExchangeRates.Org, with updates rates between USD and 170 currencies hourly. These rates are symmetrical only.

In this case, you need to specify the providerClass in the definitions for the field type and sign up for an API key. Here is an example:

<fieldType name="currency" class="solr.CurrencyFieldType"
           amountLongSuffix="_l_ns" codeStrSuffix="_s_ns"
           providerClass="solr.OpenExchangeRatesOrgProvider"
           refreshInterval="60"
           ratesFileLocation="http://www.openexchangerates.org/api/latest.json?app_id=yourPersonalAppIdKey"/>

The refreshInterval is minutes, so the above example will download the newest rates every 60 minutes. The refresh interval may be increased, but not decreased.