From 4ddec997033e27175e1f85d39a75db3a88bac330 Mon Sep 17 00:00:00 2001 From: Karel Minarik Date: Thu, 10 Jul 2014 11:20:37 +0200 Subject: [PATCH] [DOC] Added comprehensive documentation for the Ruby and Rails integrations --- docs/ruby/client.asciidoc | 109 ++++++++++++++++ docs/ruby/copyright.asciidoc | 5 + docs/ruby/index.asciidoc | 87 +------------ docs/ruby/model.asciidoc | 66 ++++++++++ docs/ruby/persistence.asciidoc | 226 +++++++++++++++++++++++++++++++++ docs/ruby/rails.asciidoc | 16 +++ 6 files changed, 428 insertions(+), 81 deletions(-) create mode 100644 docs/ruby/client.asciidoc create mode 100644 docs/ruby/copyright.asciidoc create mode 100644 docs/ruby/model.asciidoc create mode 100644 docs/ruby/persistence.asciidoc create mode 100644 docs/ruby/rails.asciidoc diff --git a/docs/ruby/client.asciidoc b/docs/ruby/client.asciidoc new file mode 100644 index 00000000000..ac6566bf227 --- /dev/null +++ b/docs/ruby/client.asciidoc @@ -0,0 +1,109 @@ +== The Ruby Client + +The `elasticsearch` http://rubygems.org/gems/elasticsearch[Rubygem] provides a low-level client +for communicating with an Elasticsearch cluster, fully compatible with other official clients. + +Full documentation is hosted at http://github.com/elasticsearch/elasticsearch-ruby[Github] +and http://rubydoc.info/gems/elasticsearch[RubyDoc] +-- this documentation provides only an overview of features. + +=== Elasticsearch Version Compatibility + +The Ruby API is compatible with both Elasticsearch 0.90.x and 1.0.x versions, you have to install +a matching http://rubygems.org/gems/elasticsearch/versions[gem version], though: + +[cols="<,<",options="header",] +|========================================= +| Elasticsearch version | Ruby gem version +| 0.90.x | 0.4.x +| 1.x | 1.x +|========================================= + +=== Installation + +Install the Ruby gem for Elasticsearch *1.x*: + +[source,sh] +------------------------------------ +gem install elasticsearch +------------------------------------ + +...or add it do your Gemfile: + +[source,ruby] +------------------------------------ +gem 'elasticsearch' +------------------------------------ + +Install the Ruby gem for Elasticsearch *0.90.x*: + +[source,sh] +------------------------------------ +gem install elasticsearch -v 0.4.10 +------------------------------------ + +...or add it do your Gemfile: + +[source,ruby] +------------------------------------ +gem 'elasticsearch', '~> 0.4' +------------------------------------ + +=== Example Usage + +[source,ruby] +------------------------------------ +require 'elasticsearch' + +client = Elasticsearch::Client.new log: true + +client.cluster.health + +client.index index: 'my-index', type: 'my-document', id: 1, body: { title: 'Test' } + +client.indices.refresh index: 'my-index' + +client.search index: 'my-index', body: { query: { match: { title: 'test' } } } +------------------------------------ + + +=== Features at a Glance + +* Pluggable logging and tracing +* Plugabble connection selection strategies (round-robin, random, custom) +* Pluggable transport implementation, customizable and extendable +* Pluggable serializer implementation +* Request retries and dead connections handling +* Node reloading (based on cluster state) on errors or on demand +* Modular API implementation +* 100% REST API coverage + + +=== Transport and API + +The `elasticsearch` gem combines two separate Ruybygems: + +* https://github.com/elasticsearch/elasticsearch-ruby/tree/master/elasticsearch-transport[`elasticsearch-transport`] +provides a HTTP Ruby client for connecting to the Elasticsearch cluster, + +* https://github.com/elasticsearch/elasticsearch-ruby/tree/master/elasticsearch-api[`elasticsearch-api`] +provides a Ruby API for the Elasticsearch RESTful API. + +Please see their respective documentation for configuration options and technical details. + +Notably, the documentation and comprehensive examples for all the API methods is contained in the source, +and available online at http://rubydoc.info/gems/elasticsearch-api/Elasticsearch/API/Actions[Rubydoc]. + +Keep in mind, that for optimal performance, you should use a HTTP library which supports +persistent ("keep-alive") HTTP connections. + + +=== Extensions + +The https://github.com/elasticsearch/elasticsearch-ruby/tree/master/elasticsearch-extensions[`elasticsearch-extensions`] +Rubygem provides a number of extensions to the core client, such as an API to programatically launch +Elasticsearch clusters (eg. for testing purposes), and more. + +Please see its +https://github.com/elasticsearch/elasticsearch-ruby/tree/master/elasticsearch-extensions[documentation] +for more information. diff --git a/docs/ruby/copyright.asciidoc b/docs/ruby/copyright.asciidoc new file mode 100644 index 00000000000..22312055a26 --- /dev/null +++ b/docs/ruby/copyright.asciidoc @@ -0,0 +1,5 @@ +== Copyright and License + +This software is Copyright (c) 2013 by Elasticsearch BV. + +This is free software, licensed under The Apache License Version 2.0. diff --git a/docs/ruby/index.asciidoc b/docs/ruby/index.asciidoc index 553b931cab2..cc1defcd304 100644 --- a/docs/ruby/index.asciidoc +++ b/docs/ruby/index.asciidoc @@ -1,86 +1,11 @@ -= elasticsearch-ruby += Ruby And Rails Integrations -== Overview +include::client.asciidoc[] -There's a suite of official Ruby libraries for Elasticsearch, which provide a client for connecting -to Elasticsearch clusters, Ruby interface to the REST API, and more. +include::model.asciidoc[] -See the full documentation at http://github.com/elasticsearch/elasticsearch-ruby. +include::rails.asciidoc[] -=== Elasticsearch Version Compatibility +include::persistence.asciidoc[] -The Ruby libraries are compatible with both Elasticsearch 0.90.x and 1.0.x versions, -but you have to install a matching http://rubygems.org/gems/elasticsearch/versions[gem version]: - -[cols="<,<",options="header",] -|========================================= -| Elasticsearch version | Ruby gem version -| 0.90.x | 0.4.x -| 1.0.x | 1.x -|========================================= - -=== Installation - -Install the Ruby gem for Elasticsearch *1.x*: - -[source,sh] ------------------------------------- -gem install elasticsearch ------------------------------------- - -...or add it do your Gemfile: - -[source,ruby] ------------------------------------- -gem 'elasticsearch' ------------------------------------- - -Install the Ruby gem for Elasticsearch *0.90.x*: - -[source,sh] ------------------------------------- -gem install elasticsearch -v 0.4.10 ------------------------------------- - -...or add it do your Gemfile: - -[source,ruby] ------------------------------------- -gem 'elasticsearch', '~> 0.4' ------------------------------------- - -=== Example Usage - -[source,ruby] ------------------------------------- -require 'elasticsearch' - -client = Elasticsearch::Client.new log: true - -client.cluster.health - -client.index index: 'my-index', type: 'my-document', id: 1, body: { title: 'Test' } - -client.indices.refresh index: 'my-index' - -client.search index: 'my-index', body: { query: { match: { title: 'test' } } } ------------------------------------- - - -=== Features at a Glance - -* Pluggable logging and tracing -* Plugabble connection selection strategies (round-robin, random, custom) -* Pluggable transport implementation, customizable and extendable -* Pluggable serializer implementation -* Request retries and dead connections handling -* Node reloading (based on cluster state) on errors or on demand -* Modular API implementation -* 100% REST API coverage - - -== Copyright and License - -This software is Copyright (c) 2013 by Elasticsearch BV. - -This is free software, licensed under The Apache License Version 2.0. +include::copyright.asciidoc[] diff --git a/docs/ruby/model.asciidoc b/docs/ruby/model.asciidoc new file mode 100644 index 00000000000..27298c23dfd --- /dev/null +++ b/docs/ruby/model.asciidoc @@ -0,0 +1,66 @@ +== ActiveModel / ActiveRecord + +The `elasticsearch-model` http://rubygems.org/gems/elasticsearch-model[Rubygem] +provides integration with Ruby domain objects ("models"), commonly found e.g. in Ruby on Rails applications. + +It uses the `elasticsearch` Rubygem as the client communicating with the Elasticsearch cluster. + + +=== Features at a Glance + +* ActiveModel integration with adapters for ActiveRecord and Mongoid +* Enumerable-based wrapper for search results +* ActiveRecord::Relation-based wrapper for returning search results as records +* Convenience model methods such as `search`, `mapping`, `import`, etc +* Support for Kaminari and WillPaginate pagination +* Extension implemented via proxy object to shield model namespace from collisions +* Convenience methods for (re)creating the index, setting up mappings, indexing documents, ... + + +=== Usage + +Add the library to your Gemfile: + +[source,ruby] +------------------------------------ +gem 'elasticsearch-rails' +------------------------------------ + +Include the extension module in your model class: + +[source,ruby] +------------------------------------ +class Article < ActiveRecord::Base + include Elasticsearch::Model +end +------------------------------------ + +Import some data and perform a search: + +[source,ruby] +------------------------------------ +Article.import + +response = Article.search 'fox dog' +response.took +# => 3 +------------------------------------ + +It is possible to either return results as model instances, or decorated documents from Elasticsearch, +with the `records` and `results` methods, respectively: + +[source,ruby] +------------------------------------ +response.records.first +# Article Load (0.4ms) SELECT "articles".* FROM "articles" WHERE ... +=> #
+ +response.results.first._score +# => 0.02250402 + +response.results.first._source.title +# => "Quick brown fox" +------------------------------------ + +Please see the full https://github.com/elasticsearch/elasticsearch-rails/tree/master/elasticsearch-model[documentation] +for more information. diff --git a/docs/ruby/persistence.asciidoc b/docs/ruby/persistence.asciidoc new file mode 100644 index 00000000000..3d2d807e709 --- /dev/null +++ b/docs/ruby/persistence.asciidoc @@ -0,0 +1,226 @@ +== Persistence + +The `elasticsearch-persistence` http://rubygems.org/gems/elasticsearch-persistence[Rubygem] +provides persistence layer for Ruby domain objects. + +It supports two design patterns for integrating with your objects: _repository_ and _active record_. + +=== Repository + +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. + +==== Features At a Glance + +* Access to the Elasticsearch 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 Elasticsearch response for search results (aggregations, total, ...) +* Defining the methods for serialization and deserialization + +==== 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 +------------------------------------ + + +Let's create a default, "dumb" repository, as a first step: + +[source,ruby] +------------------------------------ +require 'elasticsearch/persistence' +repository = Elasticsearch::Persistence::Repository.new +------------------------------------ + +We can save a `Note` instance into the repository, find it, search it, delete it: + +[source,ruby] +------------------------------------ +note = Note.new id: 1, text: 'Test' + +repository.save(note) +# PUT http://localhost:9200/repository/note/1 +# > {"id":1,"text":"Test"} +# < {"_index":"repository","_type":"note","_id":"1","_version":1,"created":true} + +n = repository.find(1) +# GET http://localhost:9200/repository/_all/1 +# < {"_index":"repository","_type":"note","_id":"1","_version":2,"found":true, "_source" : {"id":1,"text":"Test"}} +=> 1, "text"=>"Test"}> + +repository.search(query: { match: { text: 'test' } }).first +# GET http://localhost:9200/repository/_search +# > {"query":{"match":{"text":"test"}}} +# < {"took":2, ... "hits":{"total":1, ... "hits":[{ ... "_source" : {"id":1,"text":"Test"}}]}} +=> 1, "text"=>"Test"}> + +repository.delete(note) +# DELETE http://localhost:9200/repository/note/1 +# < {"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/elasticsearch/elasticsearch-rails/tree/master/elasticsearch-persistence#the-repository-pattern[documentation] +for more information. + +Also, check out the +https://github.com/elasticsearch/elasticsearch-rails/tree/master/elasticsearch-persistence#example-application[example application] which demonstrates the usage patterns of the _repository_ approach to persistence. + +=== Active Record + +The `Elasticsearch::Persistence::Model` module provides an implementation of the active record pattern, with +a familiar interface for using Elasticsearch as a persistence layer in Ruby on Rails applications. The model +is fully compatible with Rails' conventions and helpers, such as `url_for`. + +All the methods are documented with comprehensive examples in the source code, available also +http://rubydoc.info/gems/elasticsearch-persistence/Elasticsearch/Persistence/Model[online]. + +==== Features At a Glance + +* Familiar interface for persistence methods from ActiveRecord +* Common model features such as validations and callbacks +* Methods for defining model attributes, including Elasticsearch mappings +* Support for fetching data in bulk (`find_in_batches`, `find_each`) +* Decorated search results for easy access to model instances and meta data (such as highlights or aggregations) +* Easy access to the underlying gateway and client + +==== Usage + +To use the library in a Rails application, add it to your Gemfile with a require statement: + +[source,ruby] +------------------------------------ +gem "elasticsearch-persistence", require: 'elasticsearch/persistence/model' +------------------------------------ + +Include the module in a plain Ruby class, and set up the properties, mappings, etc: + +[source,ruby] +------------------------------------ +class Article + include Elasticsearch::Persistence::Model + + # Define a plain `title` attribute + # + attribute :title, String + + # Define an `author` attribute, with multiple analyzers for this field + # + attribute :author, String, mapping: { fields: { + author: { type: 'string'}, + raw: { type: 'string', analyzer: 'keyword' } + } } + + + # Define a `views` attribute, with default value + # + attribute :views, Integer, default: 0, mapping: { type: 'integer' } + + # Validate the presence of the `title` attribute + # + validates :title, presence: true + + # Execute code after saving the model. + # + after_save { puts "Successfuly saved: #{self}" } +end +------------------------------------ + +The model attribute definition support is implemented with the https://github.com/solnic/virtus[_Virtus_] Rubygem, +and the naming, validation, etc. features with the https://github.com/rails/rails/tree/master/activemodel[_ActiveModel_] Rubygem. + +Attribute validations work like for any other ActiveModel-compatible implementation: + +[source,ruby] +------------------------------------ +article = Article.new # => #
+ +article.valid? +# => false + +article.errors.to_a +# => ["Title can't be blank"] +------------------------------------ + +We can create a new article in the database and find it: + +[source,ruby] +------------------------------------ +Article.create id: 1, title: 'Test', author: 'John' +# PUT http://localhost:9200/articles/article/1 [status:201, request:0.015s, query:n/a] + +article = Article.find(1) +# => #
+ +article._index +# => "articles" + +article.id +# => "1" + +article.title +# => "Test" +------------------------------------ + +To update the model, either update the attribute and save the model or use the `update_attributes` method: + +[source,ruby] +------------------------------------ +article.title = 'Updated' + +article.save +# => {"_index"=>"articles", "_type"=>"article", "_id"=>"1", "_version"=>2, "created"=>false} + +article.update_attributes title: 'Test', author: 'Mary' +# => {"_index"=>"articles", "_type"=>"article", "_id"=>"1", "_version"=>3} +------------------------------------ + +The implementation supports the familiar interface for updating model timestamps and numeric attributes: + +[source,ruby] +------------------------------------ +article.touch +# => => { ... "_version"=>4} + +article.views +# => 0 + +article.increment :views +article.views +# => 1 +------------------------------------ + +Any callbacks defined in the model will be triggered during the persistence operations: + +[source,ruby] +------------------------------------ +article.save +# Successfuly saved: #
+------------------------------------ + +Please see the extensive documentation in the library +https://github.com/elasticsearch/elasticsearch-rails/tree/master/elasticsearch-persistence#the-activerecord-pattern[README] +for detailed information. + +Also, check out the +https://github.com/elasticsearch/elasticsearch-rails/tree/master/elasticsearch-persistence#example-application-1[example application] which demonstrates the usage patterns of the _active record_ approach to persistence. diff --git a/docs/ruby/rails.asciidoc b/docs/ruby/rails.asciidoc new file mode 100644 index 00000000000..fdb4818011d --- /dev/null +++ b/docs/ruby/rails.asciidoc @@ -0,0 +1,16 @@ +== Ruby On Rails + +The `elasticsearch-rails` http://rubygems.org/gems/elasticsearch-rails[Rubygem] +provides features suitable for Ruby on Rails applications. + +=== Features at a Glance + +* Rake tasks for importing data from application models +* Integration with Rails' instrumentation framework +* Templates for generating example Rails application + +=== Example applications + +You can generate a fully working example Ruby on Rails application with templates provides. + +Please refer to the https://github.com/elasticsearch/elasticsearch-rails/tree/master/elasticsearch-rails[documentation] for more information.