1 Introduction

The plugin focus on exposing Grails domain classes for the moment. It highly takes the existing Searchable Plugin as reference for its syntax and behavior.

Note that the plugin is still under development, so you may not be able to use all the features of ElasticSearch yet.

In addition to this document, you may want to read the official ElasticSearch documentation here.

1.1 Features

• Maps domain classes to their corresponding index in ElasticSearch
• Provides an ElasticSearch service for cross-domain searching
• Injects domain class methods for specific domain searching, indexing and unindexing
• Automatically mirrors any changes made through GORM to the index
• Allow to use the Groovy Content Builder DSL for search queries
• Support for term highlighting

1.2 History

History

• June 30, 2015
• 0.0.4.5
• Upgrade to ElasticSearch 1.6.0
• Support the return of aggregation results
• June 15, 2015
• 0.0.4.5
• Add the ability to define property names that are excluded by default
• Fix NPE
• Add the attachment type
• March 5, 2015
• 0.0.4.4
• Upgrade to Elasticsearch-Groovy 1.4.4
• February 22, 2015
• 0.0.4.3
• Add mapping configuration support for '_all'
• Fix issue with indexing nested GeoPoint
• Add support for transient properties
• February 10, 2015
• 0.0.4.2
• Reduce severity of non-searchable property in index document when unmarshalling domain
• February 03, 2015
• 0.0.4.1
• Upgrade to Elasticsearch 1.4.2
• Enable configuration of the number of replicas created per shard
• January 28, 2015
• 0.0.4.0
• Included Mapping migrations
• Included read and write aliases to indices to deal with migrations on multinode deployments
• December 14, 2014
• 0.0.3.8
• Upgrade to ElasticSearch 1.4.1
• Support the min_score query parameter.
• Try to detect the MongoDB without using the plugin manager.
• December 01, 2014
• 0.0.3.7
• Create separate SimpleTypeConverter per-thread
• November 06, 2014
• 0.0.3.6
• Upgrade to ElasticSearch 1.4.0
• October 28, 2014
• 0.0.3.5
• Fix the bulk index query iteration.
• October 14, 2014
• 0.0.3.4
• Upgrade to latest version of ElasticSearch and remove the Groovy client dependency.
• August 28, 2014
• 0.0.3.3
• Configure a component field to act as an inner object instead of a nested object.
• August 3, 2014
• 0.0.3.2
• Add the ability to mark fields with aliases
• Support ES client HTTP configuration parameters
• Improve Hibernate 4 support
• June 9, 2014
• 0.0.3.1
• Upgrade to ElasticSearch 1.2.x
• Add special treatment for MongoDB ObjectId data types
• Return raw result objects when now class mapping is found
• Fix integration-test NPE
• May 25, 2014
• 0.0.3.0
• Upgrade to Grails dependency 2.2.x
• Upgrade to Grails runtime 2.3.x
• Upgrade to ElasticSearch 1.x
• Apply ElasticSearch 1.x compatibility fixes
• Enable customization of index name types when mapping classes
• May 15, 2014
• 0.0.2.6
• Use 'grails.util.Holders' instead of ApplicationHolder
• April 2, 2014
• 0.0.2.5
• Start releasing the plugin as 'elasticsearch' instead of 'elasticsearch-gorm'
• Fix NPE when marshalling JSONObject fields
• March 24, 2014
• 0.0.2.4
• GeoPoint mapping
• Injected service now supports filters (e.g. geo_reference) and sort builders (e.g. for geo_distance sorting)
• Marshalled date values are now with correct time zone
• Removed dependency on Java 7
• Fix support of BigDecimal
• Searchable mapping property name and Elasticsearch plugin path are now configurable.
• February 4, 2014
• 0.0.2.3 Bugfix release
• January 19, 2014
• 0.0.2.2 Bugfix release
• November 24, 2013
• 0.0.2.1 Bugfix release
• November 12, 2013
• 0.0.2 release
• November 2, 2013
• initial 0.0.1 release

Authors and Contributors

Noam Y. Tenne, Stefan Rother-Stübs (Dating Cafe), Sven Kiesewetter (Dating Cafe), Michael Schwartz (Dating Cafe)

Authors and Contributors of the original plugin

Manuarii Stein (doc4web consulting), Stephane Maldini (doc4web consulting), Serge P. Nekoval

Get the full and updated list of contributors on the github repository.

License

Copyright 2013-2014 the original author or authors.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Previous work

Graeme Rocher started the first draft which this plugin is based on.

2 Configuration

Client mode

elasticSearch.client.mode = '<mode>'

Possible values:

"Transport" mode needs you to provide the host address and port. You can define one or multiple hosts with the following config key:

elasticSearch.client.hosts = [
       [host:'192.168.0.3', port:9300],
       [host:'228.168.0.4', port:9300]
]

Mapping Migration properties

Define the application's behaviour when a conflict is found while installing Elasticsearch mappings on startup. For a detailed explanation, see Mapping Migrations.

• elasticSearch.migration.strategy

Defines the behaviour to follow if an error occurs on startup when the application is installing new mappings on ElasticSearch due to conflicting mappings.

The default is 'alias'.

• elasticSearch.migration.aliasReplacesIndex

Deals with a special conflict case using the 'alias' strategy. When the 'alias' migration strategy is chosen and there's a mapping conflict on an index, defines whether to replace the index with a versioned index (<indexName>_vX) and an alias (<indexName>). This is required when applying the alias strategy on top of existing indices for the first time as indices cannot be renamed (from <indexName> to <indexName>_vX) and an alias cannot exist with the same name as an index.

The default is true.

• elasticSearch.migration.disableAliasChange

In some cases the developer may prefer not to upgrade the alias to the new version of the index until some other tasks are performed. This allows them to disable automatically pointing the alias to a new version of the index when this is created. Aliases can be changed later on manually or programatically using elasticSearchAdminService

The default is false.

Others properties

• elasticSearch.datastoreImpl

Only required when enabling the auto-index feature. This property specifies which GORM datastore implementation should be watched for storage events. The value should be the name of the datastore bean as it is configured in the Spring context; some possible values:

• elasticSearch.bootstrap.config.file

When using then plugin to construct a local node, the default Elasticsearch configuration is used by default. If you use a modified Elasticsearch configuration, you can use this property to specify the location of the file (as an application resource).

• elasticSearch.bootstrap.transportSettings.file

When choosing transport mode this configuration will be used to set up the TransportClient settings (used by some cloud providers).

• elasticSearch.client.transport.sniff

Only usable in with a transport client. Allows to sniff the rest of the cluster, and add those into its list of machines to use. In this case, the ip addresses used will be the ones that the other nodes were started with (the “publish” address)

• elasticSearch.cluster.name

The name of the cluster for the client to join.

• elasticSearch.date.formats

List of date formats used by the JSON unmarshaller to parse any date field properly. Note : future version of the plugin may change how formats are manipulated.

• elasticSearch.defaultExcludedProperties

List of domain class properties to automatically ignore (will not be indexed) if their name match one of those. This will apply to both the default-mapped domain class, with the static searchable property set to "true", and when using closure mapping. To override this setting on a specific class, it can be added to the only property of the searchable closure.

• elasticSearch.disableAutoIndex

A boolean determining if the plugin should reflect any database save/update/delete automatically on the indices. Default to false.

• elasticSearch.bulkIndexOnStartup

Determines whether the application should launch a bulk index operation upon startup.

• elasticSearch.index.name

A string indicating which ElasticSearch index should be used. If not present, will default to the package name of the domain in question.

• elasticSearch.index.compound_format

Should the compound file format be used (boolean setting). Set to false by default (really applicable for file system based index storage). More details on this setting on the ElasticSearch Documentation.

• elasticSearch.index.store.type

Determine how the indices will be stored. More details on the possible values on the ElasticSearch Documentation.

• elasticSearch.index.numberOfReplicas

Sets the number of replicas created for each shard of the index. If not present, will default to zero.

• elasticSearch.gateway.type

Determine the gateway type to be used. More details on the possible values are in the ElasticSearch Documentation. Using a setting of "none" (possibly in combination with index.store.type set to "memory") can be useful for tests.

• elasticSearch.maxBulkRequest

Max number of requests to process at once. Reduce this value if you have memory issue when indexing a big amount of data at once. If this setting is not specified, 500 will be use by default.

• elasticSearch.path.data

The location of the data files of each index / shard allocated on the node.

• elasticSearch.path.plugins

The location of plugin files such as native scripts. Each plugin will be contained in a subdirectory.

• elasticSearch.searchableProperty.name

The name of the ElasticSearch mapping configuration property that annotates domain classes. The default is 'searchable'.

• elasticSearch.includeTransients

Whether to index and search all non excluded transient properties. All explicitly included transients in only will be indexed regardless. Default is false.

Default configuration script

elasticSearch {
  /**
   * Date formats used by the unmarshaller of the JSON responses
   */
  date.formats = ["yyyy-MM-dd'T'HH:mm:ss'Z'"]
  /**
   * Hosts for remote ElasticSearch instances.
   * Will only be used with the "transport" client mode.
   * If the client mode is set to "transport" and no hosts are defined, ["localhost", 9300] will be used by default.
   */
  client.hosts = [
          [host:'localhost', port:9300]
  ]
  /**
   * Default mapping property exclusions
   *
   * No properties matching the given names will be mapped by default
   * ie, when using "searchable = true"
   *
   * This does not apply for classes using mapping by closure
   */
  defaultExcludedProperties = ["password"]
  /**
   * Determines if the plugin should reflect any database save/update/delete automatically
   * on the ES instance. Default to false.
   */
  disableAutoIndex = false
  /**
   * Should the database be indexed at startup.
   *
   * The value may be a boolean true|false.
   * Indexing is always asynchronous (compared to Searchable plugin) and executed after BootStrap.groovy.
   */
  bulkIndexOnStartup = true
  /**
   *  Max number of requests to process at once. Reduce this value if you have memory issue when indexing a big amount of data
   *  at once. If this setting is not specified, 500 will be use by default.
   */
  maxBulkRequest = 500

  /**
   * The name of the ElasticSearch mapping configuration property that annotates domain classes. The default is 'searchable'.
   */
  searchableProperty.name = 'searchable'
}
environments {
  development {
    /**
     * Possible values : "local", "node", "dataNode", "transport"
     * If set to null, "node" mode is used by default.
     */
    elasticSearch.client.mode = 'local'
  }
  test {
      elasticSearch {
          client.mode = 'local'
          index.store.type = 'memory' // store local node in memory and not on disk
      }
  }
  production {
    elasticSearch.client.mode = 'node'
  }
}

3 Mapping

3.1 QuickStart

Default mapping

static searchable = true

Custom mapping

static searchable = {
    // mapping DSL…
}

Limit properties with only/except

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.

Including transients

How the plugin manages transient properties is controlled by the elasticSearch.includeTransients configuration property. If this is set to false only transient properties explictly included in only will be mapped and searchable, if set to true, all domain class properties will be mapped, including transients.

The following are valid examples

//assert grailsApplication.config.elasticSearch.includeTransients == false
class Person {
    String firstName
    String lastName
    String getFullName() {
        firstName + " " + lastName
    }
    static transients = ['fullName']
    static searchable = {
        only = ['fullName']
    }
}
// new Person(firstNameme: "Nikola", lastName: "Tesla")
// can be found using:
// def tesla = Person.search("Nikola Tesla").searchResults.first()

//assert grailsApplication.config.elasticSearch.includeTransients == true
class Multiplication {
    int opA
    int opB
    int getResult() {
        opA * opB
    }
    static transients = ['result']
    static searchable = true
}
// new Multiplication(opA: 2, opB: 3)
// can be found using:
// def multiplication = Multiplication.search("2").searchResults.first()
// def multiplication = Multiplication.search("3").searchResults.first()
// def multiplication = Multiplication.search("6").searchResults.first()

From the examples above, once the domain object is found, its transient values will be calculated from the information stored on ElasticSearch: multiplication.result == 6, but tesla.fullName == "null null", as firstName and lastName where not indexed. This behaviour can be prevented by creating convenient setters for the transient properties.

Transients and collections

When transient properties are collections the only way the plugin can define the correct ElasticSearch mapping during boot is if the element types are explicitly defined on the grails domain object. For instances of Collection this can be achieved by defining its type on the hasMany property (otherwise the ElasticSearch type will be defined as object). This is not required for arrays.

Some valid examples:

class Tweet {
    String message
    List getHashtags() { … }
    static transients = ['hashtags']
    static hasMany = [hashtags: String]
    static searchable = {only = 'hashtags' }
}

class FamilyGuy {
    String wife
    String son
    String daughter
    String baby
    String[] getRelatives() { … }
    static transients = ['relatives']
    static searchable = { only = 'relatives' }
}

3.2 Class Mapping

root

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

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

all

static searchable = {
  all = [analyzer: 'russian_morphology']
}

static searchable = {
  all = false
}

When disabling the all field, it is a good practice to set index.query.default_field to a different value (for example, if you have a main 'message' field in your data, set it to message).

3.3 Properties mapping

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

Available options

3.3.1 Parent-Child

Example

class ParentElement {
…
}
class EmbeddingChild {
    ParentElement parentElement
    static searchable = {
        parentElement parent: true, component: true
    }
}
class ReferencingChild {
    ParentElement parentElement
    static searchable = {
        parentElement parent: true, reference: true
    }
}

3.3.2 GeoPoint

Example

class GeoPoint {
    Double lat
    Double lon
    static searchable = {
        root false
    }
}
class Building {
    String name
    GeoPoint location
    static searchable = {
        location geoPoint: true, component: true
    }
}

3.3.3 Alias

Example

class Session {
    Date loginTime
    static searchable = {
        loginTime alias:'@timestamp'
    }
}

3.3.4 Dynamic

Example

class Session {
    String jsonData
    static searchable = {
        dynamic: true
    }
}
Session session = new Session()
session.jsonData = ([foo: 'bar'] as JSON).toString()

The default mapping would make the jsonData field an escaped String field and a search for jsonData.foo = bar would result in no result. With dynamic mapping enabled for this field, we enable JSON handling of this field and tell elasticsearch to map this field dynamicly. The result is that a search for jsonData.foo=bar would result in a search hit. Attention: This will only work on String fields and will result in an error if the String is no valid json

3.4 Searchable Component-Reference

3.4.1 Searchable Reference

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

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"
        }
    }
}

If you'd rather that the reference object be mapped with type 'inner' rather than the default 'nested', set the 'component' key with a value of 'inner' rather than 'true':

class MyDomain {
    // odom is an association with the OtherDomain class, set as a reference
    OtherDomain odom
    static searchable = {
        odom component: 'inner'
    }
}

3.5 Mapping Migrations

It is important to highlight that not all type mapping changes will result on a conflict. Ie. adding a new field to a mapping does not result in a conflict whilst changing a property from component:'inner' to nested or viceversa, will. These strategies will only be needed and applied when a conflicting mapping is found.

Migration Strategies

• 'none'
• 'delete'
• 'alias'

The default strategy is 'alias' as it is the only strategy that can achieve zero-downtime migrations and thus recommended by Elasticsearch

These values are described on more detail further ahead

Migration Strategy 'none'

This option keeps the original behaviour the plugin used before the Migration Strategies were implemented. When a Mapping Merge conflict id identified the event will be logged and an Exception will be logged. It will be responsability for the application administrator to manually fix the problem. This configuration was left as a backwards compatibility and it will prevent the application from booting successfully, therefore we discourage teams from using this option.

Migration Strategy 'delete'

When choosing this option, when a conflict occurs installing mapping, the application will delete the existing mapping for the type, alongside with all content indexed on that index and type and recreated the mapping. There are a couple of important details on this information:

• Only documents indexed on the conflicting mapping will be deleted, any other document on a different mapping on the same (or other) index will remain untouched.
• Deleted documents can be automatically reindexed on startup by using the elasticSearch.bulkIndexOnStartup configuration property (See below)
• Using this configuration there will always be a time window (between deletion and reindexation) where documents can't be found by search, therefore this option cannot achieve a zero-downtime deployment

See Dealing with deleted content below for more details on automatic indexing.

Migration Strategy 'alias'

This is the migration strategy recommended by Elasticsearch.

To better understand this strategy we will describe a typical 'alias' migration.

Elasticsearch contains
  index 'myapplication.store_v27' with types 'car' and 'motorbike'
  alias 'myapplication.store' pointing to 'myapplication.store_v27'
  'myapplication.store_v27/car' contains 520 documents
  'myapplication.store_v27/motorbike' contains 12 documents
  index 'myapplication.admin_v0' with type 'quote'
  alias 'myapplication.admin' pointing to 'myapplication.admin_v0'
  'myapplication.admin_v0/quote' contains 3200 documents
The application is configured to use indexes based on package names 'myapplication.store' and 'myapplication.admin'
(which as we already explained are actually aliases that point to versioned indices)
The team introduced a change on the Car domain that results in a conflict on the 'car' mapping
The application starts up
    Tries to install the mapping for 'motorbike', it detects the conflict
    Creates a new index called 'myapplication.store_v28'
    Creates mappings 'myapplication.store_v28/car' and 'myapplication.store_v28/motorbike'
    Points all indexing requests for Car and Motorbike to the new index, while queries still happen on 'myapplication.store'
On Boostrap (bulkIndexOnStartup)
    It indexes 520 cars into 'myapplication.store_v28/car'
    It indexes 12 motorbikes into 'myapplication.store_v28/motorbike'
    Switches the 'myapplication.store' alias to point to 'myapplication.store_v28'
    Now all cars are indexed according to the new mapping
    Now all motorbikes are indexed according to the new mapping

All content can be queried at all times, during Bootstrap bulkIndexOnStartup content will be retrieved from the old index.

Eventhough there wasn't a conflict on 'car', all cars needed to be reindexed as they lived on the same index.

There are three potential scenarios when using the 'alias' strategy:

In the case you wanted to create a new version of an index, but not change where the alias points to (ie. for testing or if you wanted to perform extra tasks on the index before updating the alias), the elasticSearch.migration.disableAliasChange configuration property can be used

Aliases will only point to the new version of the index once all content is reindexed (if chosen to). Meanwhile, all index requests, either by elasticSearchService or using dynamic finders will go to the new version of the index, whilst queries will go to the old version of the index.

See Dealing with deleted content below for more details on automatic indexing.

Dealing with deleted content

Using the 'delete' or 'alias' strategy may lead to deleting content stored on Elasticsearch. This content can be automatically reindexed using the elasticSearch.bulkIndexOnStartup. The duration of this process will depend on the amount of content to index.

When this property is set to true all content will be deleted. When set to 'deleted' only the domain classes which documents where deleted will be indexed. In either case, when using the 'alias' strategy, once all content is indexed all aliases will point to the latest version of the index.

4 Indexing

The plugin is providing a few injected methods in the domain or in the ElasticSearchService to allow that.

Index examples

// Index all searchable instances
elasticSearchService.index()
// Index a specific domain instance
MyDomain md = new MyDomain(value:'that')
md.save()
elasticSearchService.index(md)
// Index a collection of domain instances
def ds = [new MyDomain(value:'that'), new MyOtherDomain(name:'this'), new MyDomain(value:'thatagain')]
ds*.save()
elasticSearchService.index(ds)
// Index all instances of the specified domain class
elasticSearchService.index(MyDomain)
elasticSearchService.index(class:MyDomain)
elasticSearchService.index(MyDomain, MyOtherDomain)
elasticSearchService.index([MyDomain, MyOtherDomain])

Unindex examples

// Unindex all searchable instances
elasticSearchService.unindex()
// Unindex a specific domain instance
MyDomain md = new MyDomain(value:'that')
md.save()
elasticSearchService.unindex(md)
// Unindex a collection of domain instances
def ds = [new MyDomain(value:'that'), new MyOtherDomain(name:'this'), new MyDomain(value:'thatagain')]
ds*.save()
elasticSearchService.unindex(ds)
// Unindex all instances of the specified domain class
elasticSearchService.unindex(MyDomain)
elasticSearchService.unindex(class:MyDomain)
elasticSearchService.unindex(MyDomain, MyOtherDomain)
elasticSearchService.unindex([MyDomain, MyOtherDomain])

5 Searching

• You can use the elasticSearchService and its public search method for cross-domain searching, meaning that ElasticSearch

may analyze multiple indices and return hits of different types (=different domains).

def res = elasticSearchService.search("${params.query}")
// 'res' search results may contains multiple types of results

• You can use the injected dynamic method in the domain for domain-specific searching.

def res = Tweet.search("${params.query}")
// 'res' search results contains only Tweet instances

These search methods return a Map containing 3 entries:

• a total entry, representing the total number of hits found
• a searchResults entry, containing the hits
• a scores entry, containing the hits scores

Example

def res = Tweet.search("${params.query}")
println "Found ${res.total} result(s)"
res.searchResults.each {
    println it.message
}
def res = elasticSearchService.search("${params.query}")
println "Found ${res.total} result(s)"
res.searchResults.each {
    if(it instanceof Tweet) {
        println it.message
    } else {
        println it.toString()
    }
}

If you're willing to retrieve only the number of hits for a peculiar query, you can use the countHits() method. It will only return an Integer representing the total hits matching your query.

Example

def res = Tweet.countHits("${params.query}")
println "Found ${res} result(s)"
def res = elasticSearchService.countHits("${params.query}", [indices:'test'])
println "Found ${res} result(s)"

5.1 Query Strings

You can find out about the syntax on the Apache Lucene website.

Example

def results = elasticSearchService.search("${params.query}")
def resultsTweets = Tweet.search("message:${params.query}")

5.2 Query Closure

Example

def result = elasticSearchService.search(searchType:'dfs_query_and_fetch') {
  bool {
      must {
          query_string(query: params.query)
      }
      if (params.firstname) {
          must {
              term(firstname: params.firstname)
          }
      }
  }
}

5.3 Query QueryBuilder

Example

QueryBuilder query = QueryBuilders.matchAllQuery()
def result = elasticSearchService.search(query)

5.4 Filter Closure

Example

def result = elasticSearchService.search(
    [indices: Building, types: Building, sort: sortBuilder],
    null as Closure,
    {
        geo_distance(
            'distance': '5km',
            'location': [lat: 48.141, lon: 11.57]
        )
    })

5.5 Filter FilterBuilder

Example

FilterBuilder filter = FilterBuilders.rangeFilter("price").gte(1.99).lte(2.3)
def result = elasticSearchService.search(
    [indices: Building, types: Building, sort: sortBuilder],
    null as Closure,
    filter)

5.6 Highlighting

Example

// Define the pre & post tag that will wrap each term matched in the document.
def highlighter = {
  field 'message'
  field 'tags.name'
  preTags '<strong>'
  postTags '</strong>'
}
def results = Tweet.search("${params.query}", [highlight: highlightSettings])

Highlight results

def results = Tweet.search("${params.query}", [highlight: { field 'message' }])
def highlighted = results.highlight
results?.searchResults?.eachWithIndex { hit, index ->
    // Retrieve the 'message' field fragments for the current hits
    def fragments = highlighted[index].message?.fragments
    // Print the fragment
    println fragments?.size() ? fragments[0] : ''
}

Highlighted fields

Signature

field <fieldName>[, <fragmentSize>[, <numberOfFragment>]]

Examples

def highlightSettings = {
    field 'message'                    // Add the 'message' field in the highlighted fields list
    field 'tags.name'                  // Add the 'name' field contained in the 'tags' field of
                                       // the document in the highlighted fields list
    field 'thatAwesomeField', 0, 20    // Add the 'thatAwesomeField' field with
                                       // some values fixed for fragmentSize and numberOfFragment parameters
}
def highlightSettings2 = {
    field '_all'                       // Add the special '_all' field in the highlighted fields list
}
def results = Tweet.search("${params.query}", [highlight: highlightSettings])
def results2 = Tweet.search("${params.query}", [highlight: highlightSettings2])

Highlighting tags

def highlightSettings = {
    field 'message'
    preTags '<myAweSomeTag>'
    postTags '</myAweSomeTag>'
}

5.7 Sorting

Returned sort values

The sort values are not part of the search results themselves but are part of result.sort. sort contains all search values calculated by the ElasticSearch server as a list mapped to the id of the respective domain objects

Example

assert [1:[23, 42], 2: [24, 40]] == result.sort

5.7.1 geoDistanceSorting

Example

def sortBuilder = SortBuilders.geoDistanceSort("location")
    .point(48.141, 11.57)
    .unit(DistanceUnit.KILOMETERS)
    .order(SortOrder.ASC)
def result = elasticSearchService.search(
    [indices: Building, types: Building, sort: sortBuilder],
    null as Closure,
    {
        geo_distance(
            'distance': '5km',
            'location': [lat: 48.141, lon: 11.57]
        )
    })

The calculated distances are not part of the search results themselves but are part of result.sort. sort contains all search values calculated by the ElasticSearch server as a list mapped to the id of the respective domain objects

assert [1:[2.34567], 2: [2.4402342]] == result.sort

6 Admin

6.1 Refresh

elasticSearchService.index(domain)
// Some code…
// …
elasticSearchService.index(domain2)
// Some code…
// …
elasticSearchService.index(domain3)
// Some code…
// …
elasticSearchAdminService.refresh() // Ensure that the 3 previous index requests have been made searchable by ES

6.2 Delete Index

The method can be limited to one or more specific indices or applied to all indices at once (called with no parameter).

elasticSearchAdminService.deleteIndex()

7 Low level API

class MySearchService {
    static transactional = true
    def elasticSearchHelper
    def myMethod(indexName, settings) {
        elasticSearchHelper.withElasticSearch { client ->
            // Do some stuff with the ElasticSearch client
            client.admin()
                .indices()
                .prepareCreate(indexName)
                .setSettings(settings)
                .execute()
                .actionGet()
        }
    }
}

Please refers to the Elastic Search API for more information on the methods and properties available on the client.

8 Example

8.1 Tweets

8.1.1 The domains

class Tweet {
  static searchable = {
    message boost:2.0
  }
  static belongsTo = [
          user:User
  ]
  static hasMany = [
          tags:Tag
  ]
  static constraints = {
    tags nullable:true, cascade:'save, update'
  }
  String message = ''
  Date dateCreated = new Date()
}

class User {
  static searchable = {
    except = 'password'
    lastname boost:20
    firstname boost:15, index:'not_analyzed'
    listOfThings index:'no'
    someThings index:'no'
    tweets component:true
  }
  static constraints = {
    tweets cascade:'all'
  }
  static hasMany = [
          tweets:Tweet
  ]
  static mappedBy = [
          tweets:'user'
  ]
  String lastname
  String firstname
  String password
  String activity = 'Evildoer'
  String someThings = 'something'
  ArrayList<String> listOfThings = ['this', 'that', 'andthis']
}

class Tag {
  static searchable = {
    except=['boostValue']
  }
  String name
  Integer boostValue = 1
}

8.1.2 The controller

A action triggering indexation

class ElasticSearchController {
  def elasticSearchService
  def testCaseService
  def postTweet = {
    if(!params.user?.id) {
      flash.notice = "No user selected."
      redirect(action: 'index')
      return
    }
    User u = User.get(params.user.id)
    if (!u) {
      flash.notice = "User not found"
      redirect(action: 'index')
      return
    }
    // Create tweet
    testCaseService.addTweet(params.tweet?.message, u, params.tags)
    flash.notice = "Tweet posted"
    redirect(action: 'index')
  }
}

Searching for Tweets

def searchForUserTweets = {
    def tweets = Tweet.search("${params.message.search}").searchResults
    def tweetsMsg = 'Messages : '
    tweets.each {
      tweetsMsg += "<br />Tweet from ${it.user?.firstname} ${it.user?.lastname} : ${it.message} "
      tweetsMsg += "(tags : ${it.tags?.collect{t -> t.name}})"
    }
    flash.notice = tweetsMsg
    redirect(action: 'index')
}

Searching for anything

def searchAll = {
    def res = elasticSearchService.search("${params.query}").searchResults
    def resMsg = '<strong>Global search result(s):</strong><br />'
    res.each {
      switch(it){
        case Tag:
          resMsg += "<strong>Tag</strong> ${it.name}<br />"
          break
        case Tweet:
          resMsg += "<strong>Tweet</strong> "${it.message}" from ${it.user.firstname} ${it.user.lastname}<br />"
          break
        case User:
          resMsg += "<strong>User</strong> ${it.firstname} ${it.lastname}<br />"
          break
        default:
          resMsg += "<strong>Other</strong> ${it}<br />"
          break
      }
    }
    flash.notice = resMsg
    redirect(action:'index')
 }

8.2 Geo Distance Search

8.2.1 Domains

class GeoPoint {
    Double lat
    Double lon
    static searchable = {
        root false
    }
}

class Building {
    String name
    GeoPoint location
    static searchable = {
        location geoPoint: true, component: true
    }
}

The location of the building is mapped to an ElasticSearch geo_point.

8.2.2 Service Methods

def searchForBuildings() {
    Closure filter = {
        geo_distance(
            'distance': '5km',
            'location': [lat: 48.141, lon: 11.57]
        )
    }
    def sortBuilder = SortBuilders.geoDistanceSort("location").
        point(48.141, 11.57).
        unit(DistanceUnit.KILOMETERS).
        order(SortOrder.ASC)
    def result = elasticSearchService.search(
        [indices: Building, types: Building, sort: sortBuilder],
        null as Closure,
        filter)
    return [results: result.searchResults, distances: result.sort]
}

The calculated distances are not part of the search results themselves but are part of result.sort. sort contains all search values calculated by the ElasticSearch server as a list mapped to the id of the respective domain objects

Example

assert [1:[23, 42], 2: [24, 40]] == result.sort

8.3 Parent/Child mapping

class Store {
    String name
    String description = "A description of a store"
    String owner = "Shopowner"
    static searchable = true
    static constraints = {
        name blank: false
        description nullable: true
        owner nullable: false
    }
}
class Department {
    String name
    Long numberOfProducts
    Store store
    static constraints = {
        numberOfProducts nullable: true
    }
    static searchable = {
        store parent: true, component:true
    }
}

Search for all departments which are childs of a store with the owner "Shopowner"

def result = elasticSearchService.search(
    QueryBuilders.hasParentQuery("store", QueryBuilders.matchQuery("owner", "Shopowner")),
    null as Closure,
    [indices: Department, types: Department]
)