Skip to content

Commit a4e7fed

Browse files
estolfoestolfo
committed
[COMMON] Move docs files from elasticsearch repo to here
1 parent f8e3476 commit a4e7fed

File tree

5 files changed

+334
-0
lines changed

5 files changed

+334
-0
lines changed

‎docs/client.asciidoc‎

Lines changed: 115 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,115 @@
1+
[[ruby_client]]
2+
== The Ruby Client
3+
4+
The `elasticsearch` http://rubygems.org/gems/elasticsearch[Rubygem] provides a low-level client
5+
for communicating with an Elasticsearch cluster, fully compatible with other official clients.
6+
7+
Full documentation is hosted at https://github.com/elastic/elasticsearch-ruby[Github]
8+
and http://rubydoc.info/gems/elasticsearch[RubyDoc]
9+
-- this documentation provides only an overview of features.
10+
11+
=== Elasticsearch and Ruby Version Compatibility
12+
13+
The Elasticsearch client is compatible with Ruby 1.9 and higher.
14+
15+
The client's API is compatible with Elasticsearch's API versions from 0.90 till current,
16+
just use a release matching major version of Elasticsearch.
17+
18+
| Gem Version | | Elasticsearch |
19+
|:-------------:|:-:| :-----------: |
20+
| 0.90 | → | 0.90 |
21+
| 1.x | → | 1.x |
22+
| 2.x | → | 2.x |
23+
| 5.x | → | 5.x |
24+
| 6.x | → | 6.x |
25+
| 7.x | → | 7.x |
26+
| master | → | master |
27+
28+
=== Installation
29+
30+
Install the Ruby gem for the latest Elasticsearch version:
31+
32+
[source,sh]
33+
------------------------------------
34+
gem install elasticsearch
35+
------------------------------------
36+
37+
...or add it do your Gemfile:
38+
39+
[source,ruby]
40+
------------------------------------
41+
gem 'elasticsearch'
42+
------------------------------------
43+
44+
Install the Ruby gem for a specific Elasticsearch version:
45+
46+
[source,sh]
47+
------------------------------------
48+
gem install elasticsearch -v 6.0.0
49+
------------------------------------
50+
51+
...or add it do your Gemfile:
52+
53+
[source,ruby]
54+
------------------------------------
55+
gem 'elasticsearch', '~> 6.0'
56+
------------------------------------
57+
58+
=== Example Usage
59+
60+
[source,ruby]
61+
------------------------------------
62+
require 'elasticsearch'
63+
64+
client = Elasticsearch::Client.new log: true
65+
66+
client.cluster.health
67+
68+
client.index index: 'my-index', type: 'my-document', id: 1, body: { title: 'Test' }
69+
70+
client.indices.refresh index: 'my-index'
71+
72+
client.search index: 'my-index', body: { query: { match: { title: 'test' } } }
73+
------------------------------------
74+
75+
76+
=== Features at a Glance
77+
78+
* Pluggable logging and tracing
79+
* Pluggable connection selection strategies (round-robin, random, custom)
80+
* Pluggable transport implementation, customizable and extendable
81+
* Pluggable serializer implementation
82+
* Request retries and dead connections handling
83+
* Node reloading (based on cluster state) on errors or on demand
84+
* Modular API implementation
85+
* 100% REST API coverage
86+
87+
88+
=== Transport and API
89+
90+
The `elasticsearch` gem combines two separate Rubygems:
91+
92+
* https://github.com/elastic/elasticsearch-ruby/tree/master/elasticsearch-transport[`elasticsearch-transport`]
93+
provides an HTTP Ruby client for connecting to the Elasticsearch cluster,
94+
95+
* https://github.com/elastic/elasticsearch-ruby/tree/master/elasticsearch-api[`elasticsearch-api`]
96+
provides a Ruby API for the Elasticsearch RESTful API.
97+
98+
Please see their respective documentation for configuration options and technical details.
99+
100+
Notably, the documentation and comprehensive examples for all the API methods is contained in the source,
101+
and available online at http://rubydoc.info/gems/elasticsearch-api/Elasticsearch/API/Actions[Rubydoc].
102+
103+
Keep in mind, that for optimal performance, you should use an HTTP library which supports
104+
persistent ("keep-alive") HTTP connections.
105+
106+
107+
=== Extensions
108+
109+
The https://github.com/elastic/elasticsearch-ruby/tree/master/elasticsearch-extensions[`elasticsearch-extensions`]
110+
Rubygem provides a number of extensions to the core client, such as an API to programmatically launch
111+
Elasticsearch clusters (eg. for testing purposes), and more.
112+
113+
Please see its
114+
https://github.com/elastic/elasticsearch-ruby/tree/master/elasticsearch-extensions[documentation]
115+
for more information.

‎docs/index.asciidoc‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
= Ruby And Rails Integrations
2+
3+
include::client.asciidoc[]
4+
5+
include::model.asciidoc[]
6+
7+
include::rails.asciidoc[]
8+
9+
include::persistence.asciidoc[]

‎docs/model.asciidoc‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
[[activemodel_activerecord]]
2+
== ActiveModel / ActiveRecord
3+
4+
The `elasticsearch-model` http://rubygems.org/gems/elasticsearch-model[Rubygem]
5+
provides integration with Ruby domain objects ("models"), commonly found e.g. in Ruby on Rails applications.
6+
7+
It uses the `elasticsearch` Rubygem as the client communicating with the Elasticsearch cluster.
8+
9+
10+
=== Features at a Glance
11+
12+
* ActiveModel integration with adapters for ActiveRecord and Mongoid
13+
* Enumerable-based wrapper for search results
14+
* ActiveRecord::Relation-based wrapper for returning search results as records
15+
* Convenience model methods such as `search`, `mapping`, `import`, etc
16+
* Support for Kaminari and WillPaginate pagination
17+
* Extension implemented via proxy object to shield model namespace from collisions
18+
* Convenience methods for (re)creating the index, setting up mappings, indexing documents, ...
19+
20+
21+
=== Usage
22+
23+
Add the library to your Gemfile:
24+
25+
[source,ruby]
26+
------------------------------------
27+
gem 'elasticsearch-rails'
28+
------------------------------------
29+
30+
Include the extension module in your model class:
31+
32+
[source,ruby]
33+
------------------------------------
34+
class Article < ActiveRecord::Base
35+
include Elasticsearch::Model
36+
end
37+
------------------------------------
38+
39+
Import some data and perform a search:
40+
41+
[source,ruby]
42+
------------------------------------
43+
Article.import
44+
45+
response = Article.search 'fox dog'
46+
response.took
47+
# => 3
48+
------------------------------------
49+
50+
It is possible to either return results as model instances, or decorated documents from Elasticsearch,
51+
with the `records` and `results` methods, respectively:
52+
53+
[source,ruby]
54+
------------------------------------
55+
response.records.first
56+
# Article Load (0.4ms) SELECT "articles".* FROM "articles" WHERE ...
57+
=> #<Article id: 3, title: "Foo " ...>
58+
59+
response.results.first._score
60+
# => 0.02250402
61+
62+
response.results.first._source.title
63+
# => "Quick brown fox"
64+
------------------------------------
65+
66+
Please see the full https://github.com/elastic/elasticsearch-rails/tree/master/elasticsearch-model[documentation]
67+
for more information.

‎docs/persistence.asciidoc‎

Lines changed: 126 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,126 @@
1+
[[persistence]]
2+
== Persistence
3+
4+
The `elasticsearch-persistence` http://rubygems.org/gems/elasticsearch-persistence[Rubygem]
5+
provides persistence layer for Ruby domain objects.
6+
7+
It supports the repository design patterns. Versions before 6.0 also supported the _active record_ design pattern.
8+
9+
=== Repository
10+
11+
The `Elasticsearch::Persistence::Repository` module provides an implementation of the repository pattern and allows to save, delete, find and search objects stored in Elasticsearch, as well as configure mappings and settings for the index.
12+
13+
==== Features At a Glance
14+
15+
* Access to the Elasticsearch client
16+
* Setting the index name, document type, and object class for deserialization
17+
* Composing mappings and settings for the index
18+
* Creating, deleting or refreshing the index
19+
* Finding or searching for documents
20+
* Providing access both to domain objects and hits for search results
21+
* Providing access to the Elasticsearch response for search results (aggregations, total, ...)
22+
* Defining the methods for serialization and deserialization
23+
24+
[[persistence]]
25+
== Persistence
26+
27+
The `elasticsearch-persistence` http://rubygems.org/gems/elasticsearch-persistence[Rubygem]
28+
provides persistence layer for Ruby domain objects.
29+
30+
It supports the repository design patterns. Versions before 6.0 also supported the _active record_ design pattern.
31+
32+
=== Repository
33+
34+
The `Elasticsearch::Persistence::Repository` module provides an implementation of the repository pattern and allows to save, delete, find and search objects stored in Elasticsearch, as well as configure mappings and settings for the index.
35+
36+
==== Features At a Glance
37+
38+
* Access to the Elasticsearch client
39+
* Setting the index name, document type, and object class for deserialization
40+
* Composing mappings and settings for the index
41+
* Creating, deleting or refreshing the index
42+
* Finding or searching for documents
43+
* Providing access both to domain objects and hits for search results
44+
* Providing access to the Elasticsearch response for search results (aggregations, total, ...)
45+
* Defining the methods for serialization and deserialization
46+
47+
==== Usage
48+
49+
Let's have a simple plain old Ruby object (PORO):
50+
51+
[source,ruby]
52+
------------------------------------
53+
class Note
54+
attr_reader :attributes
55+
56+
def initialize(attributes={})
57+
@attributes = attributes
58+
end
59+
60+
def to_hash
61+
@attributes
62+
end
63+
end
64+
------------------------------------
65+
66+
Let's create a default, "dumb" repository, as a first step:
67+
68+
[source,ruby]
69+
------------------------------------
70+
require 'elasticsearch/persistence'
71+
class MyRepository; include Elasticsearch::Persistence::Repository; end
72+
repository = MyRepository.new
73+
------------------------------------
74+
75+
We can save a `Note` instance into the repository...
76+
77+
[source,ruby]
78+
------------------------------------
79+
note = Note.new id: 1, text: 'Test'
80+
81+
repository.save(note)
82+
# PUT http://localhost:9200/repository/_doc/1 [status:201, request:0.210s, query:n/a]
83+
# > {"id":1,"text":"Test"}
84+
# < {"_index":"repository","_type":"note","_id":"1","_version":1,"created":true}
85+
------------------------------------
86+
87+
...find it...
88+
89+
[source,ruby]
90+
------------------------------------
91+
n = repository.find(1)
92+
# GET http://localhost:9200/repository/_doc/1 [status:200, request:0.003s, query:n/a]
93+
# < {"_index":"repository","_type":"note","_id":"1","_version":2,"found":true, "_source" : {"id":1,"text":"Test"}}
94+
=> <Note:0x007fcbfc0c4980 @attributes={"id"=>1, "text"=>"Test"}>
95+
------------------------------------`
96+
97+
...search for it...
98+
99+
[source,ruby]
100+
------------------------------------
101+
repository.search(query: { match: { text: 'test' } }).first
102+
# GET http://localhost:9200/repository/_search [status:200, request:0.005s, query:0.002s]
103+
# > {"query":{"match":{"text":"test"}}}
104+
# < {"took":2, ... "hits":{"total":1, ... "hits":[{ ... "_source" : {"id":1,"text":"Test"}}]}}
105+
=> <Note:0x007fcbfc1c7b70 @attributes={"id"=>1, "text"=>"Test"}>
106+
------------------------------------
107+
108+
...or delete it:
109+
110+
[source,ruby]
111+
------------------------------------
112+
repository.delete(note)
113+
# DELETE http://localhost:9200/repository/_doc/1 [status:200, request:0.014s, query:n/a]
114+
# < {"found":true,"_index":"repository","_type":"note","_id":"1","_version":3}
115+
=> {"found"=>true, "_index"=>"repository", "_type"=>"note", "_id"=>"1", "_version"=>2}
116+
------------------------------------
117+
118+
The repository module provides a number of features and facilities to configure and customize the behaviour,
119+
as well as support for extending your own, custom repository class.
120+
121+
Please refer to the
122+
https://github.com/elastic/elasticsearch-rails/tree/master/elasticsearch-persistence#the-repository-pattern[documentation]
123+
for more information.
124+
125+
Also, check out the
126+
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.

‎docs/rails.asciidoc‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
[[ruby_on_rails]]
2+
== Ruby On Rails
3+
4+
The `elasticsearch-rails` http://rubygems.org/gems/elasticsearch-rails[Rubygem]
5+
provides features suitable for Ruby on Rails applications.
6+
7+
=== Features at a Glance
8+
9+
* Rake tasks for importing data from application models
10+
* Integration with Rails' instrumentation framework
11+
* Templates for generating example Rails application
12+
13+
=== Example applications
14+
15+
You can generate a fully working example Ruby on Rails application with templates provides.
16+
17+
Please refer to the https://github.com/elastic/elasticsearch-rails/tree/master/elasticsearch-rails[documentation] for more information.

0 commit comments

Comments
 (0)