{"id":20904674,"url":"https://github.com/sage/elastic_search_framework","last_synced_at":"2025-05-13T05:30:44.983Z","repository":{"id":47107977,"uuid":"90747293","full_name":"Sage/elastic_search_framework","owner":"Sage","description":null,"archived":false,"fork":false,"pushed_at":"2023-12-18T10:24:26.000Z","size":117,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":17,"default_branch":"master","last_synced_at":"2025-04-18T05:45:30.160Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"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/Sage.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","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":"2017-05-09T13:12:22.000Z","updated_at":"2023-10-23T13:55:04.000Z","dependencies_parsed_at":"2022-09-18T06:14:34.500Z","dependency_job_id":"64f19da5-3bf6-4ad0-bf46-895ae1921848","html_url":"https://github.com/Sage/elastic_search_framework","commit_stats":{"total_commits":69,"total_committers":6,"mean_commits":11.5,"dds":0.7101449275362319,"last_synced_commit":"5e3767ed2d47fbe5400acc0b075d8dd18993ce86"},"previous_names":[],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Sage%2Felastic_search_framework","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Sage%2Felastic_search_framework/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Sage%2Felastic_search_framework/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Sage%2Felastic_search_framework/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Sage","download_url":"https://codeload.github.com/Sage/elastic_search_framework/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253882696,"owners_count":21978537,"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":[],"created_at":"2024-11-18T13:18:27.617Z","updated_at":"2025-05-13T05:30:44.679Z","avatar_url":"https://github.com/Sage.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Elastic Search Framework [![Maintainability](https://api.codeclimate.com/v1/badges/a8de5f956f6e248a30a0/maintainability)](https://codeclimate.com/github/Sage/elastic_search_framework/maintainability) [![Test Coverage](https://api.codeclimate.com/v1/badges/a8de5f956f6e248a30a0/test_coverage)](https://codeclimate.com/github/Sage/elastic_search_framework/test_coverage) [![Gem Version](https://badge.fury.io/rb/elastic_search_framework.svg)](https://badge.fury.io/rb/elastic_search_framework)\n\nWelcome to Elastic Search Framework, this is a light weight framework that provides managers to help with interacting with Elastic Search.\n\n## Installation\n\nAdd this line to your application's Gemfile:\n\n```ruby\ngem 'elastic_search_framework'\n```\n\nAnd then execute:\n\n    $ bundle\n\nOr install it yourself as:\n\n    $ gem install elasticsearch_framework\n\n## Usage\n\n\n## Global Config\n\n### #namespace\nThe namespace is used to set the prefix applied to all table and index names.\n\n\u003e Optional.\n\n    elasticsearchFramework.namespace = 'uat'\n\n\u003e With a namespace of 'uat' and a table name of 'people', the resulting table name would be 'uat.people'\n\n### #namespace_delimiter\nThis is the delimiter used to join the namespace prefix to table/index names.\n\n\u003e DEFAULT = '.'\n\n    elasticsearchFramework.namespace_delimiter = '-'\n\n### #host\nThis is used to set the host that should be used for all connection actions.\n\n    ElasticSearchFramework.host = 'http://elasticsearch'\n\n### #port\nThis is used to set the port that should be used for all connection actions.\n\n    ElasticSearchFramework.port = 9200\n\n\u003e DEFAULT = 9200\n\n# IndexAlias\nTo define an index alias within elasticsearch, create an index alias class that extends from the `ElasticSearchFramework::IndexAlias` module.\n\nExample:\n\n\n```ruby\nclass ExampleIndexAlias\n  extend ElasticSearchFramework::IndexAlias\n\n  index ExampleIndex, active: true\n  index ExampleIndex2, active: false\n\n  name :example\nend\n```\n\n**attributes**\n\n - **index** [Hash] [Required] [Multi] This is used to specify the indexes associated with this alias and which index is the current active index for the alias to point to.\n - **name** [Hash] [Required] [Single] This is used to specify the unique name of the index alias.\n\n---\n\nIndex Aliases are required to decouple your application from a specific index and allow you to handle index updates without downtime.\n\nTo change the mapping of an existing index Create a new version of the index, then associate the new index with the index alias as an inactive index `active: false`. This will allow index writes and deletes to be performed on both indexes so no new data is lost while you perform a `_reindex` operation to move existing data from the old index into the new index.\n\nOnce you have `_reindexed` into your new index you can then de-activate the old index `active: false` and activate the new index `active: true` in your index alias. This will swap all requests to the new index.\n\nDoing the above steps should enable you to seamlessly transition between 1 index and another when mapping/analyzer changes are required.\n\n## #create\nThis method is called to create the index alias within an elastic search instance.\n\u003e This method is idempotent and will modify the index alias if it already exists.\n\n\u003e All associated indexes must exist before this method is called.\n\n    ExampleIndexAlias.create\n\n## Index operation methods\nThe following index operation methods are available for an index alias:\n\n- `#get_item`\n- `#put_item`\n- `#delete_item`\n- `#query`\n\n\u003e `#put_item` calls will be performed against all indexes associated with the alias.\n\n\u003e `#delete_item` calls will be performed against all indexes associated with the alias.\n\n\u003e Details for how to use the above index operation methods can be found below.\n\n# Index\nTo define an index within elasticsearch, create an index definition class that extends from the `ElasticSearchFramework::Index` module.\n\n```ruby\nclass ExampleIndex\n  extend ElasticSearchFramework::Index\n\n  index name: 'example_index', shards: 1\n\n  id :example_id\n\n  mapping name: 'default', field: :name, type: :keyword, index: true\nend\n```\n\n**attributes**\n\n - **index** [Hash] [Required] This is used to specify the name of the index, and the number of shards the index should use.\n - **mapping** [Hash] [Optional] This is used to specify field mappings to control the analyzer used for a given field.\n - **id** [Hash] [Optional] [Default=id] This is used to specify the id field of the index document. (By default this is :id)\n\n## #create\nThis method is called to create the index definition within an elastic search instance.\n\n    ExampleIndex.create\n\n\n## #drop\nThis method is called to drop the index from an elastic search instance.\n\n    ExampleIndex.drop\n\n## #exists?\nThis method is called to determine if an index exists in a elastic search instance.\n\n    ExampleIndex.exists?\n\n\n## #put_item\nThis method is called to store a document/entity within the index.\n\n    ExampleIndex.put_item(item: document)\n\n**Params**\n\n - **item** [Object] [Required] This is the document/entity you want to store in the index.\n - **type** [String] [Optional] [Default='default'] This is used to specify the type of the document within the index.\n\n## #get_item\nThis method is called to fetch a document from within the index.\n\n    ExampleIndex.get_item(id: document_id)\n\n**Params**\n\n - **id** [String/Integer] [Required] This is the unique identifier of the document/entity you want to fetch from the index.\n - **type** [String] [Optional] [Default='default'] This is used to specify the type of the document within the index.\n\n## #delete_item\nThis method is called to delete a document from within the index.\n\n    ExampleIndex.delete_item(id: document_id)\n\n**Params**\n\n - **id** [String/Integer] [Required] This is the unique identifier of the document/entity you want to delete from the index.\n - **type** [String] [Optional] [Default='default'] This is used to specify the type of the document within the index.\n\n\n\n## #query\nThis method is called to query the index for a collection of items.\n\nThe query is then built up using method chaining e.g:\n\n    query = ExampleIndex.query.gender.eq('male').and.age.gt(18)\n\nThe above query chain translates into:\n\n    FROM ExampleIndex WHERE gender == 'male' AND age \u003e 18\n\nTo execute the query you can then call `#execute` on the query:\n\n    query.execute\n\n\u003e Due to method chaining, the #execute method can also be chained to the end of a query directly.\n\n### #execute\nThis method is called to execute a query.\n\n**Params**\n\n - **limit** [Integer] [Optional] This is used to specify a limit to the number of items returned by the query.\n - **count** [Boolean] [Optional] This is used to specify if the query should just return a count of results.\n\n## Query expressions\n\n### #eq(value)\nThis method is used to specify the `==` operator within a query.\n\n### #not_eq(value)\nThis method is called to specify the `!=` operator within a query.\n\n### #gt(value)\nThis method is called to specify the `\u003e` operator within a query.\n\n### #gt_eq(vaue)\nThis method is called to specify the `\u003e=` operator within a query.\n\n### #lt(value)\nThis method is called to specify the `\u003c` operator within a query.\n\n### #lt_eq(value)\nThis method is called to specify the `\u003c=` operator within a query.\n\n### #contains(value)\nThis method is called to check if a field contains a value within a query.\n\n### #exists?\nThis method is called to check if a field exists within a query.\n\n### #and\nThis method is called to combine conditions together in a traditional `\u0026\u0026` method within a query.\n\n### #or\nThis method is called to combine conditions together in a traditional `||` method within a query.\n\n## Testing\n\nTo run the tests locally, we use Docker to provide both a Ruby and JRuby environment along with a reliable Redis container.\n\n### Setup Images:\n\n\u003e This builds the Ruby docker image.\n\n```bash\n./script/setup.sh\n```\n\n### Run Tests:\n\n\u003e This executes the test suite.\n\n```bash\n./script/test.sh\n```\n\n### Cleanup\n\n\u003e This is used to clean down docker image created in the setup script.\n\n```bash\n./script/cleanup.sh\n```\n\n## Development\n\nAfter checking out the repo, run `bin/setup` to install dependencies. You can also run `bin/console` for an interactive prompt that will allow you to experiment.\n\nTo install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).\n\n## Contributing\n\nBug reports and pull requests are welcome on GitHub at https://github.com/sage/elasticsearch_framework. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.\n\n\n## License\n\nThis gem is available as open source under the terms of the [MIT licence](LICENSE).\n\nCopyright (c) 2018 Sage Group Plc. All rights reserved.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsage%2Felastic_search_framework","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsage%2Felastic_search_framework","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsage%2Felastic_search_framework/lists"}