Preferences

Setting preferences

You may need to change how the SDK behaves or set some option that is not directly exposed. These types of modifications are done by setting preferences.

There are several ways to set preferences; the approach you choose depends on whether you're using the pre-built driver, or using the SDK to build your own driver. For the pre-built driver, setting the preferences can only be done using an external preferences file specified as a job parameter.

All methods for setting preferences are supported when you build your own driver. You can use more than one method, and it is valid to set the preferences differently in each one. If you use more than one method, there is an order of precedence - higher order overrides lower order(s) as follows:

Using an external preferences file
Setting the Preferences object in the UDF builder
Modifying the default preferences file in addressing.yaml

Using an external preferences file

Specify the preferences file to the Spark job using the --preferences-filepath parameter or use .withPreferencesFile(“path-to-yaml”) in the UDF builder. The specified file should have the preferences file contain the desired preference set. When using Download Manager, this file can be resolved from HDFS/S3. An example preference file is provided for references in the distribution at:

<sdk>/resources/config/preferences.yaml

Building preferences in the API

Use .withPreferences(PreferenceObject) in the UDF builder. The Preference instance should have the desired preference set. For more information about creating the Preference object, see PreferencesBuilder in the Addressing API Javadocs.

Modifying defaults in addressing.yaml

For some advanced installations, the default preferences can be specified in addressing.yaml in the configuration directory. If you choose this method you must ensure that the reference data is configured using addressing.yaml as well. When the reference data is configured this way, that reference data cannot be automatically downloaded and must be manually downloaded and configured on every node in the cluster. Refer to the Addressing SDK information in the Geo Addressing SDK Developer Guide if you require additional guidance for this advanced scenario.

Preferences options and descriptions

For the complete list of preferences, refer to the Preferences class in the Addressing API Javadocs. For the country-specific custom preferences, refer to the Geo Addressing SDK Developer Guide. The javadocs and developer guide are also available on the Geo Spatial Big Data SDK documentation landing page.

Commonly used preferences

This section describes some of the commonly used preferences.

PreciselyID

Master Location Data datasets support a unique feature called PreciselyID (PB_KEY field). This is an identifier attached to every address record that facilitates data enrichment for faster and more informed decision making.

To return PreciselyID, set the preference returnAllInfo to 'true':

Add the following key-value pair to the preferences element in the preferences file:
```
---
config:
  default:
    preferences:
      returnAllInfo: true
```
Request the output field:
```
customFields['PB_KEY']
```