{"id":17656520,"url":"https://github.com/imdrasil/hydrogel","last_synced_at":"2026-05-12T23:35:29.965Z","repository":{"id":81841551,"uuid":"62464525","full_name":"imdrasil/hydrogel","owner":"imdrasil","description":"Ruby Elasticsearch query builder","archived":false,"fork":false,"pushed_at":"2016-07-08T18:00:57.000Z","size":24,"stargazers_count":2,"open_issues_count":0,"forks_count":2,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-02-05T11:47:59.759Z","etag":null,"topics":["elasticsearch","ruby"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/imdrasil.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-07-02T18:23:56.000Z","updated_at":"2023-07-25T14:02:39.000Z","dependencies_parsed_at":null,"dependency_job_id":"52927725-8847-434c-942c-eec7801e5801","html_url":"https://github.com/imdrasil/hydrogel","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/imdrasil%2Fhydrogel","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/imdrasil%2Fhydrogel/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/imdrasil%2Fhydrogel/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/imdrasil%2Fhydrogel/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/imdrasil","download_url":"https://codeload.github.com/imdrasil/hydrogel/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246301954,"owners_count":20755512,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["elasticsearch","ruby"],"created_at":"2024-10-23T14:33:20.712Z","updated_at":"2026-05-12T23:35:29.939Z","avatar_url":"https://github.com/imdrasil.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Hydrogel\n\nA cool query builder for Elasticsearch requests with possibility to use chainable methods. For now it extends possibilities of [elasticsearch-rails gem](https://github.com/elastic/elasticsearch-rails), but in future it'll become standalone powerfull interface fior ElasticSearch search engine.\n\n## Installation\n\n\u003e Gem for now is in developing stage and is on hard working. So first release to Rubygems will be very soon.\n\nAdd this line to your application's Gemfile:\n\n```ruby\ngem 'hydrogel'\n```\n\nAnd then execute:\n\n    $ bundle\n\nOr install it yourself as:\n\n    $ gem install hydrogel\n\n### Dependencies\n\nThere is no hardcoded dependencies on any `elasticsearch-persistence` and `elastisearch-model` gems but it still needs one of them or both to work. \nGem tested on 0.1.9 version of all `elasticsearch-*` gems.\n\nSupported Rubies:\n* 1.9.3 MRI\n* 1.7.19 JRuby\n\n## Usage\n### Introduction\nTo generate something like:\n```json\n{\n   \"query\": {\n        \"filtered\":{\n            \"query\":{\n                \"match\": { \"b\": 'a' }\n            },\n            \"filter\":{\n                \"terms\": { \"c\": [1] }\n            }\n        }\n   },\n   \"filter\":{\n      \"term\": { \"a\": 1 }\n   },\n   \"fields\": [\"f1\", \"f2\"],\n   \"size\": 10,\n   \"from\": 20\n}\n```\nfor searching `Article` we can just write:\n```ruby\nArticle.filter(term: { a: 1 })\n       .query(match: { b: 'a' })\n       .filtered(terms: { c: [1] })\n       .fields(:f1, :f2)\n       .page(2).per_page(10)\n```\nor even more shortly\n```ruby\nArticle.term(:filter, a: 1).match(b: 'a')\n       .terms(c: [1]).fields(:f1, :f2)\n       .page(2).per_page(10)\n```\nwhich is much more like ruby way.\n\n### Basic search methods\n\nFor searching via any index or types without no mapped class you can just write something like this:\n```ruby\nHydrogel.match_all.type('article', 'track').result(extract: :source)\n```\n\nAlso you can extend `Hydrogel::Model` both inside your model or persistence classes:\n```ruby\nrequire 'elasticsearch/model'\nrequire 'elasticsearch/persistence/model'\n\nclass Article \u003c ActiveRecord::Base\n  include Elasticsearch::Model\n  extend Hydrogel::Model\n\n  index_name 'test_index'\nend\n\nclass Track\n  include Elasticsearch::Persistence::Model\n  extend Hydrogel::Model\n\n  index_name 'test_index'\n\n  attribute :title, String\n  attribute :genre, Integer\nend\n```\n\nThis allow you to use search methods on both classes and  get mapped results.\n\nAll requests are lazy - they will be gathered and made only when some iteration will appear. To get results at initialization line you can use `result` method.\n\nAlso you can specify where to put query part (to `must` subpart or `and`, etc.) using `:_op` option.\n```ruby\nTrack.filter(term: { genre: 1 }, terms: { genre: [0] }, _op: :or)\n```\n\nThe only restriction for this time is that you can use only one of `bool` and logical part in `query`, `filter` and `filtered` (but they can be different in each one) suparts of query.\n#### Pagination\n\n**Hydrogel** has no dependencies on any paginator and provides 2 methods for that:\n- `page` - takes needed page number (starting form 1)\n- `per_page` - takes number of records per each page (more or equal to 0; default value is got from configuration).\n\nAlso there is another way to do this task - using from-size arguments of ElasticSearch by hand. This way has higher priority during building query.\n\n### Configuration\n\nThere are several parameters which can be configured:\n- `host` - ElasticSearch host (default is `'http://localhost'`)\n- `port` - ElasticSearch port number (default is `9200`)\n- `many_size` - default number for `size`  attribute while calling `many` method (default is `1000`)\n- `per_page` - default per page count (default is `10`).\n\nYou can specify all of them just adding such initializer:\n```ruby\nHydrogel::Config.config do |conf|\n    conf.port = 9050\n    conf.per_page = 20\nend\n```\n\n### Scoping\n\nAlso you can specify reusable chainable scopes for any model just using `h_scope` method:\n```ruby\nclass Article\n    h_scope :length, -\u003e(a) { size(a) }\nend \n```\n\u003e `Article` has been already initialized previously in [Basic search methods]() section.\n\nAlso you can specify default scope:\n```ruby\nclass Article\n    h_default_scope -\u003e { per_page(100) }\nend\n```\nTo evoid default scope in certain request just call `h_unscoped` before at the very beginning.\n```ruby\nArticle.h_unscoped.match_all\n```\n\n## Methods description\n\nMethods for models and persistences:\n#### result\nGets results of search request.\nArguments: `options = {}`\nAllowed `options` keys:\n- page - page number,\n- per_page - per page size\n- extract - for extracting some data from response(`:hits` - for extracting 'hits' part, `:source` - for extracting only sources, `:fields` - for fields extracting)\n- any valid option for `search` method of `elasticsearch-api` gem\n\n#### query\nAdds hash for `\"query\"` subpart.\n\n#### filter\n\n#### filtered\n\n#### facets\n\n#### aggs\n\n#### multi_match\n\n#### function_score\n\n#### terms\n\n#### term\n\n#### ids\n\n#### range\n\n#### match\n\n#### common\n\n#### prefix\n\n#### wildcard\n\n#### regexp\n\n#### fuzzy\n\n#### count\n\n#### many\n\n#### match_all\n\n#### pluck\n\n#### index\n\n#### type\n\n#### page\n\n#### per_page\n\n#### fields\n\n#### no_fields\n\n#### from \n\n#### size\n\n#### sort_by\n\n#### order\n\n\u003e Descriptions for all these methods will appear in close future.\n\n## Contributing\n\n1. Fork it ( https://github.com/imdrasil/hydrogel/fork )\n2. Create your feature branch (`git checkout -b my-new-feature`)\n3. Commit your changes (`git commit -am 'Add some feature'`)\n4. Push to the branch (`git push origin my-new-feature`)\n5. Create a new Pull Request\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fimdrasil%2Fhydrogel","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fimdrasil%2Fhydrogel","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fimdrasil%2Fhydrogel/lists"}