[[persistence]]
=== Persistence

The `elasticsearch-persistence` 
http://rubygems.org/gems/elasticsearch-persistence[Rubygem] provides persistence 
layer for Ruby domain objects.

It supports the repository design patterns. Versions before 6.0 also supported 
the _active record_ design pattern.


[discrete]
==== Repository

The `Elasticsearch::Persistence::Repository` module provides an implementation 
of the repository pattern and allows to save, delete, find and search objects 
stored in {es}, as well as configure mappings and settings for the index.


[discrete]
===== Features

* Access to the {es} client
* Setting the index name, document type, and object class for deserialization
* Composing mappings and settings for the index
* Creating, deleting or refreshing the index
* Finding or searching for documents
* Providing access both to domain objects and hits for search results
* Providing access to the {es} response for search results
* Defining the methods for serialization and deserialization


[discrete]
===== Usage

Let's have a simple plain old Ruby object (PORO):

[source,ruby]
------------------------------------
class Note
  attr_reader :attributes

  def initialize(attributes={})
    @attributes = attributes
  end

  def to_hash
    @attributes
  end
end
------------------------------------

Create a default, "dumb" repository, as a first step:

[source,ruby]
------------------------------------
require 'elasticsearch/persistence'
class MyRepository; include Elasticsearch::Persistence::Repository; end
repository = MyRepository.new
------------------------------------

Save a `Note` instance into the repository:

[source,ruby]
------------------------------------
note = Note.new id: 1, text: 'Test'

repository.save(note)
# PUT http://localhost:9200/repository/_doc/1 [status:201, request:0.210s, query:n/a]
# > {"id":1,"text":"Test"}
# < {"_index":"repository","_type":"note","_id":"1","_version":1,"created":true}
------------------------------------

Find it:

[source,ruby]
------------------------------------
n = repository.find(1)
# GET http://localhost:9200/repository/_doc/1 [status:200, request:0.003s, query:n/a]
# < {"_index":"repository","_type":"note","_id":"1","_version":2,"found":true, "_source" : {"id":1,"text":"Test"}}
=> <Note:0x007fcbfc0c4980 @attributes={"id"=>1, "text"=>"Test"}>
------------------------------------

Search for it:

[source,ruby]
------------------------------------
repository.search(query: { match: { text: 'test' } }).first
# GET http://localhost:9200/repository/_search [status:200, request:0.005s, query:0.002s]
# > {"query":{"match":{"text":"test"}}}
# < {"took":2, ... "hits":{"total":1, ... "hits":[{ ... "_source" : {"id":1,"text":"Test"}}]}}
=> <Note:0x007fcbfc1c7b70 @attributes={"id"=>1, "text"=>"Test"}>
------------------------------------

Delete it:

[source,ruby]
------------------------------------
repository.delete(note)
# DELETE http://localhost:9200/repository/_doc/1 [status:200, request:0.014s, query:n/a]
# < {"found":true,"_index":"repository","_type":"note","_id":"1","_version":3}
=> {"found"=>true, "_index"=>"repository", "_type"=>"note", "_id"=>"1", "_version"=>2}
------------------------------------

The repository module provides a number of features and facilities to configure 
and customize the behaviour, as well as support for extending your own, custom 
repository class.

Please refer to the
https://github.com/elastic/elasticsearch-rails/tree/master/elasticsearch-persistence#the-repository-pattern[documentation]
for more information.

Also, check out the
https://github.com/elastic/elasticsearch-rails/tree/master/elasticsearch-persistence#example-application[example application] 
which demonstrates the usage patterns of the _repository_ approach to 
persistence.
