{"_id":"567af4a493919f0d00c97a72","version":{"_id":"5633ec007e9e880d00af1a56","project":"5633ebff7e9e880d00af1a53","__v":16,"createdAt":"2015-10-30T22:15:28.105Z","releaseDate":"2015-10-30T22:15:28.105Z","categories":["5633ec007e9e880d00af1a57","5633f072737ea01700ea329d","5637a37d0704070d00f06cf4","5637cf4e7ca5de0d00286aeb","564503082c74cf1900da48b4","564503cb7f1fff210078e70a","567af26cb56bac0d0019d87d","567afeb8802b2b17005ddea0","567aff47802b2b17005ddea1","567b0005802b2b17005ddea3","568adfffcbd4ca0d00aebf7e","56ba80078cf7c9210009673e","574d127f6f075519007da3d0","574fde60aef76a0e00840927","57a22ba6cd51b22d00f623a0","5a062c15a66ae1001a3f5b09"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"1.0.0","version":"1.0"},"category":{"_id":"567afeb8802b2b17005ddea0","project":"5633ebff7e9e880d00af1a53","pages":["56b3cd7ac25dea2b00b0caf6"],"version":"5633ec007e9e880d00af1a56","__v":1,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2015-12-23T20:06:16.013Z","from_sync":false,"order":1,"slug":"quickstart-guides-1","title":"Quickstart Guides"},"project":"5633ebff7e9e880d00af1a53","user":"5633ec9b35355017003ca3f2","parentDoc":null,"__v":15,"updates":["5755e824eb85290e0069ac3f","584721274a6a0a25006ea529"],"next":{"pages":[],"description":""},"createdAt":"2015-12-23T19:23:16.460Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":0,"body":"Getting started with Ruby on Rails and Bonsai Elasticsearch is fast and easy. Simply [sign up](https://app.bonsai.io/signup) and create your first cluster to get started.\n\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"Note\",\n  \"body\": \"These instructions are for users who want to use the official Elasticsearch Rails client. If you're using something like [SearchKick](https://github.com/ankane/searchkick), refer to the SearchKick documentation.\"\n}\n[/block]\n## First steps\n\nWe recommend adding your Bonsai Elasticsearch cluster URL to your environment as a variable, so that you don't introduce security concerns by hard-coding it into your app. Running something like this should be all you need:\n\n```\nexport BONSAI_URL=\"<YOUR BONSAI URL>\"\n```\n\nNext, add the bonsai-elasticsearch-rails gem to your Gemfile:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"gem 'bonsai-elasticsearch-rails'\",\n      \"language\": \"ruby\",\n      \"name\": \"Ruby\"\n    }\n  ]\n}\n[/block]\nRun `bundle install` to complete this step.\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"Protip\",\n  \"body\": \"The `bonsai-elasticsearch-rails` gem is a wrapper to include and and initialize the `elasticsearch-rails` and `elasticsearch-model` gems in your app. You can always use those gems directly and initialize a client with something like the following:\\n\\n```\\n    Elasticsearch::Model.client = Elasticsearch::Client.new url: ENV['BONSAI_URL']\\n```\\n\\nNote that you need *either* the bonsai-elasticsearch-rails gem OR an initializer, but not both. Setting up both is likely to cause confusion at some point.\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Prepare your app\"\n}\n[/block]\nYou'll need to prepare your models to be indexed and searched by Bonsai. So if you have a User model, it would look something like this:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"require 'elasticsearch/model'\\n\\nclass User < ActiveRecord::Base\\n  include Elasticsearch::Model\\n  include Elasticsearch::Model::Callbacks\\n\\n  ... # whatever else is in the model\\n\\nend\\n\\nUser.import # This ensures that new users will be auto-indexed.\",\n      \"language\": \"ruby\"\n    }\n  ]\n}\n[/block]\nYou will want to do this for any model you want to be searchable. You should also create a rake task for importing documents. Create a file, `lib/tasks/elasticsearch.rake`, with the contents:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"require 'elasticsearch/rails/tasks/import'\",\n      \"language\": \"ruby\"\n    }\n  ]\n}\n[/block]\nThis will let you index searchable records via rake tasks.\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Protip\",\n  \"body\": \"The `elasticsearch-rails gem` will create a new index for every searchable model.\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Index your documents\"\n}\n[/block]\nBonsai does not support \"lazy\" index creation. In other words, **you will need to explicitly create your index before you can put documents there.** There are a few ways to do this. The best way is to use the rake task you (should have) set up in the last step. The first time you index your content, you'll want to set the `FORCE` parameter like so:\n\n`rake environment elasticsearch:import:all FORCE=y`\n\nThe `FORCE` parameter will explicitly delete and recreate indices, so you probably don't want to use it frequently. Subsequent indexing tasks can drop this parameter.\n\nIf rake tasks aren't possible for some reason, you could also create your indices with with `curl`. So if you have a User model, then you could use the following command to create the index:\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -XPUT http://username:password:::at:::redwood-12345.us-east-1.bonsai.io/users\",\n      \"language\": \"curl\",\n      \"name\": \"bash\"\n    }\n  ]\n}\n[/block]\nYou would need to repeat this for every model you plan to index.\n\n\n## Quick commands\n\n- To import the records from a specific model, run:\n   `rake environment elasticsearch:import:model CLASS='User'`\n\n- To limit the scope of the records imported, run:\n   `rake environment elasticsearch:import:model CLASS='User' SCOPE='active'`\n\n- Force rebuilding the index (delete and create):\n   `rake environment elasticsearch:import:model CLASS='Article' FORCE=y`\n\n- Customize the batch size:\n   `rake environment elasticsearch:import:model CLASS='Article' BATCH=100`\n\n- Set target index name:\n   `rake environment elasticsearch:import:model CLASS='Article' INDEX='articles-new'`\n\n## Further reading\n\n**Elasticsearch Rails gem:**\n\n* [README](https://github.com/elasticsearch/elasticsearch-rails)\n* [Documentation](http://www.rubydoc.info/gems/elasticsearch-rails)\n\n\n**Elasticsearch-model gem:**\n\n* [Elasticsearch-model README](https://github.com/elasticsearch/elasticsearch-rails/tree/master/elasticsearch-model)\n* [Elasticsearch-model Documentation](http://www.rubydoc.info/gems/elasticsearch-model/)","excerpt":"","slug":"ruby-on-rails","type":"basic","title":"Ruby on Rails"}
Getting started with Ruby on Rails and Bonsai Elasticsearch is fast and easy. Simply [sign up](https://app.bonsai.io/signup) and create your first cluster to get started. [block:callout] { "type": "warning", "title": "Note", "body": "These instructions are for users who want to use the official Elasticsearch Rails client. If you're using something like [SearchKick](https://github.com/ankane/searchkick), refer to the SearchKick documentation." } [/block] ## First steps We recommend adding your Bonsai Elasticsearch cluster URL to your environment as a variable, so that you don't introduce security concerns by hard-coding it into your app. Running something like this should be all you need: ``` export BONSAI_URL="<YOUR BONSAI URL>" ``` Next, add the bonsai-elasticsearch-rails gem to your Gemfile: [block:code] { "codes": [ { "code": "gem 'bonsai-elasticsearch-rails'", "language": "ruby", "name": "Ruby" } ] } [/block] Run `bundle install` to complete this step. [block:callout] { "type": "warning", "title": "Protip", "body": "The `bonsai-elasticsearch-rails` gem is a wrapper to include and and initialize the `elasticsearch-rails` and `elasticsearch-model` gems in your app. You can always use those gems directly and initialize a client with something like the following:\n\n```\n Elasticsearch::Model.client = Elasticsearch::Client.new url: ENV['BONSAI_URL']\n```\n\nNote that you need *either* the bonsai-elasticsearch-rails gem OR an initializer, but not both. Setting up both is likely to cause confusion at some point." } [/block] [block:api-header] { "type": "basic", "title": "Prepare your app" } [/block] You'll need to prepare your models to be indexed and searched by Bonsai. So if you have a User model, it would look something like this: [block:code] { "codes": [ { "code": "require 'elasticsearch/model'\n\nclass User < ActiveRecord::Base\n include Elasticsearch::Model\n include Elasticsearch::Model::Callbacks\n\n ... # whatever else is in the model\n\nend\n\nUser.import # This ensures that new users will be auto-indexed.", "language": "ruby" } ] } [/block] You will want to do this for any model you want to be searchable. You should also create a rake task for importing documents. Create a file, `lib/tasks/elasticsearch.rake`, with the contents: [block:code] { "codes": [ { "code": "require 'elasticsearch/rails/tasks/import'", "language": "ruby" } ] } [/block] This will let you index searchable records via rake tasks. [block:callout] { "type": "info", "title": "Protip", "body": "The `elasticsearch-rails gem` will create a new index for every searchable model." } [/block] [block:api-header] { "type": "basic", "title": "Index your documents" } [/block] Bonsai does not support "lazy" index creation. In other words, **you will need to explicitly create your index before you can put documents there.** There are a few ways to do this. The best way is to use the rake task you (should have) set up in the last step. The first time you index your content, you'll want to set the `FORCE` parameter like so: `rake environment elasticsearch:import:all FORCE=y` The `FORCE` parameter will explicitly delete and recreate indices, so you probably don't want to use it frequently. Subsequent indexing tasks can drop this parameter. If rake tasks aren't possible for some reason, you could also create your indices with with `curl`. So if you have a User model, then you could use the following command to create the index: [block:code] { "codes": [ { "code": "curl -XPUT http://username:password@redwood-12345.us-east-1.bonsai.io/users", "language": "curl", "name": "bash" } ] } [/block] You would need to repeat this for every model you plan to index. ## Quick commands - To import the records from a specific model, run: `rake environment elasticsearch:import:model CLASS='User'` - To limit the scope of the records imported, run: `rake environment elasticsearch:import:model CLASS='User' SCOPE='active'` - Force rebuilding the index (delete and create): `rake environment elasticsearch:import:model CLASS='Article' FORCE=y` - Customize the batch size: `rake environment elasticsearch:import:model CLASS='Article' BATCH=100` - Set target index name: `rake environment elasticsearch:import:model CLASS='Article' INDEX='articles-new'` ## Further reading **Elasticsearch Rails gem:** * [README](https://github.com/elasticsearch/elasticsearch-rails) * [Documentation](http://www.rubydoc.info/gems/elasticsearch-rails) **Elasticsearch-model gem:** * [Elasticsearch-model README](https://github.com/elasticsearch/elasticsearch-rails/tree/master/elasticsearch-model) * [Elasticsearch-model Documentation](http://www.rubydoc.info/gems/elasticsearch-model/)