(Quick Reference)

3 Mapping - Reference Documentation

Authors: Manuarii Stein, Stephane Maldini, Serge P. Nekoval

Version: 0.18.7.1-SNAPSHOT

3.1QuickStart

3.2Class mapping

3.3Properties mapping

3.4Searchable Component-Reference

3.4.1Searchable Reference

3.4.2Searchable Component

3 Mapping

3.1 QuickStart

Default mapping

To declare a domain class to be searchable, the simpliest way is to define the following static property in the code:

static searchable = true

The plugin will generate a default mapping for each properties of the domain.

Custom mapping

You can customize how each properties are mapped to the index using a closure. The syntax is similar to GORM's mapping DSL.

static searchable = {
    // mapping DSL…
}

See below for more details on the mapping DSL.

Limit properties with only/except

only and except are used to limit the properties that are made searchable. You may not define both except & only settings at the same time.

The following code will only map the 'message' property, any others will be ignored.

class Tweet {
    static searchable = {
        only = 'message'
    }
    String message
    String someUselessField
}

The following code will map all properties except the one specified.

class Tweet {
    static searchable = {
        except = 'someUselessField'
    }
    String message
    String someUselessField
}

You can use a Collection to specify several properties.

class Tweet {
    static searchable = {
        except = ['someUselessField', 'userName']
    }
    String message
    String userName
    String someUselessField
}

The properties that are ignored will not be sent to ElasticSearch. It also means that when you will get back a domain from ElasticSearch, some fields that are not supposed to be null, may still be null.

3.2 Class mapping

root

Determine if the domain class will have its own index or not. Take a boolean as parameter, and is set to true by default.

class Preference {
    static searchable = {
        root false
    }
    // …
}class Tag {
    static searchable = true
    // …
}
class Tweet {
    static searchable = {
        message boost:2.0
    }
    // …
}

In this code, the classes Tweet and Tag are going to have their own index. The class Preference will not. It also mean that any search request will never return a Preference-type hit. The dynamic method search will not be injected in the Preference domain class. The domains not root-mapped can still be considered searchable, as they can be components of another domain which is root-mapped. For example, considered the following domain:

class User {
    static searchable = {
        userPreferences component:true
    }    Preference userPreferences
}

When searching, any matches in the userPreferences property will be considered as a User match.

3.3 Properties mapping

You can customize the mapping for each domain properties using the closure mapping. The syntax is simple:

static searchable = {
    propertyName option1:value, option2:value, …
}

Available options

Option name	Description
boost	A decimal boost value. With a positive value, promotes search results for hits in this property; with a negative value, demotes search results that hit this property.
component	To use only on domain (or collection of domains), make the property a searchable component.
converter	A `Class` to use as a converter during the marshalling/unmarshalling process for that peculiar property. That class must extends the `PropertyEditorSupport` java class.
excludeFromAll	A boolean, determines if the property is to append in the `"_all"` field. Default to `true`.
index	How or if the property is made into searchable element. One of `"no"`, `"not_analyzed"` or `"analyzed"`.
reference	To use only on domain (or collection of domains), make the property a searchable reference.

3.4 Searchable Component-Reference

The plugin support a similar searchable-component & searchable-reference behavior from Compass when you are dealing with domain association. See below to find out about the difference between both mapping modes.

3.4.1 Searchable Reference

The searchable-reference mapping mode is the default mode used for association, and requires the searchable class of the association to be root-mapped in order to have its own index. With this mode, the associated domains are not completely marshalled in the resulting JSON document: only the id and the type of the instances are kept. When the document is retrieved from the index, the plugin will automatically rebuild the association from the indices using the stored id.

Example

class MyDomain {
    // odom is an association with the OtherDomain class, set as a reference
    OtherDomain odom    static searchable = {
        odom reference:true
    }
}
// The OtherDomain definition, with default searchable configuration
class OtherDomain {
    static searchable = true
    String field1 = "val1"
    String field2 = "val2"
    String field3 = "val3"
    String field4 = "val4"
}

When indexing an instance of MyDomain, the resulting JSON documents will be sent to ElasticSearch:

{
    "mydomain": {
        "_id":1,
        "odom": { "id":1 }
    }
}{
    "otherdomain": {
        "_id":1,
        "field1":"val1",
        "field2":"val2",
        "field3":"val3",
        "field4":"val4"
    }
}

3.4.2 Searchable Component

The searchable-component mapping mode must be explicitly set, and does not require the searchable class of the association to be root-mapped. With this mode, the associated domains are nested in the parent document.

Example

class MyDomain {
    // odom is an association with the OtherDomain class, set as a reference
    OtherDomain odom    static searchable = {
        odom component:true
    }
}
// The OtherDomain definition, with default searchable configuration
class OtherDomain {
    static searchable = true
    String field1 = "val1"
    String field2 = "val2"
    String field3 = "val3"
    String field4 = "val4"
}

When indexing an instance of MyDomain, the resulting JSON document will be sent to ElasticSearch:

{
    "mydomain": {
        "_id":1,
        "odom": {
            "_id":1,
            "field1":"val1",
            "field2":"val2",
            "field3":"val3",
            "field4":"val4"
        }
    }
}

<< 2Configuration

4Indexing >>