{"id":15152128,"url":"https://github.com/elastic/app-search-ruby","last_synced_at":"2025-09-29T23:31:14.663Z","repository":{"id":56483255,"uuid":"198862336","full_name":"elastic/app-search-ruby","owner":"elastic","description":"Elastic App Search Official Ruby Client","archived":true,"fork":false,"pushed_at":"2020-11-24T15:07:49.000Z","size":357,"stargazers_count":7,"open_issues_count":0,"forks_count":4,"subscribers_count":25,"default_branch":"master","last_synced_at":"2024-09-22T23:04:44.444Z","etag":null,"topics":["api-client","elastic","elastic-app-search","ruby","search","swiftype"],"latest_commit_sha":null,"homepage":"https://www.elastic.co/products/app-search","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/elastic.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}},"created_at":"2019-07-25T16:01:33.000Z","updated_at":"2023-01-28T06:50:08.000Z","dependencies_parsed_at":"2022-08-15T19:40:13.003Z","dependency_job_id":null,"html_url":"https://github.com/elastic/app-search-ruby","commit_stats":null,"previous_names":[],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elastic%2Fapp-search-ruby","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elastic%2Fapp-search-ruby/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elastic%2Fapp-search-ruby/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elastic%2Fapp-search-ruby/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/elastic","download_url":"https://codeload.github.com/elastic/app-search-ruby/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":219874706,"owners_count":16554610,"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":["api-client","elastic","elastic-app-search","ruby","search","swiftype"],"created_at":"2024-09-26T15:42:31.362Z","updated_at":"2025-09-29T23:31:09.353Z","avatar_url":"https://github.com/elastic.png","language":"Ruby","readme":"\u003e **⚠️ This client is deprecated ⚠️**\n\u003e\n\u003e As of Enterprise Search version 7.10.0, we are directing users to the new [Enterprise Search Ruby Client](https://github.com/elastic/enterprise-search-ruby) and\n\u003e deprecating this client.\n\u003e\n\u003e This client will be compatible with all Enterprise Search 7.x releases, but will not be compatible with 8.x releases. Our development effort on this project will\n\u003e be limited to bug fixes. All future enhancements will be focused on the Enterprise Search Ruby Client.\n\u003e\n\u003e Thank you! - Elastic\n\n\u003cp align=\"center\"\u003e\u003cimg src=\"https://github.com/elastic/app-search-ruby/blob/master/logo-app-search.png?raw=true\" alt=\"Elastic App Search Logo\"\u003e\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\u003ca href=\"https://circleci.com/gh/elastic/app-search-ruby\"\u003e\u003cimg src=\"https://circleci.com/gh/elastic/app-search-ruby.svg?style=svg\" alt=\"CircleCI build\"\u003e\u003c/a\u003e\u003c/p\u003e\n\n\u003e A first-party Ruby client for building excellent, relevant search experiences with [Elastic App Search](https://www.elastic.co/products/app-search).\n\n## Contents\n\n- [Getting started](#getting-started-)\n- [Versioning](#versioning)\n- [Usage](#usage)\n- [Running Tests](#running-tests)\n- [Debugging API Calls](#debugging-api-calls)\n- [FAQ](#faq-)\n- [Contribute](#contribute-)\n- [License](#license-)\n\n---\n\n## Getting started 🐣\n\nTo install the gem, execute:\n\n```bash\ngem install elastic-app-search\n```\n\nOr place `gem 'elastic-app-search', '~\u003e 7.10.0'` in your `Gemfile` and run `bundle install`.\n\n## Versioning\n\nThis client is versioned and released alongside App Search.\n\nTo guarantee compatibility, use the most recent version of this library within the major version of the corresponding App Search implementation.\n\nFor example, for App Search `7.3`, use `7.3` of this library or above, but not `8.0`.\n\nIf you are using the [SaaS version available on swiftype.com](https://app.swiftype.com/as) of App Search, you should use the version 7.5.x of the client.\n\n## Usage\n\n#### Setup: Configuring the client and authentication\n\nUsing this client assumes that you have already an instance of [Elastic App Search](https://www.elastic.co/products/app-search) up and running.\n\nOnce done, a client can be instantiated using the `[API_KEY]` and the `[API_ENDPOINT]` URL of your App Search setup:\n\n```ruby\nrequire 'elastic-app-search'\n\nclient = Elastic::AppSearch::Client.new(:api_key =\u003e 'private-xxxxxxxxxxxxxxxxxxx', :api_endpoint =\u003e 'http://localhost:3002/api/as/v1/')\n```\n\nNote:\n\nThe `[API_KEY]` authenticates requests to the API.\nYou can use any key type with the client, however each has a different scope.\nFor more information on keys, check out the [documentation](https://swiftype.com/documentation/app-search/api/credentials).\n\n##### Swiftype.com App Search users:\n\nWhen using the [SaaS version available on swiftype.com](https://app.swiftype.com/as) of App Search, you can configure the client using your `[HOST_IDENTIFIER]` instead of the `[API_ENDPOINT]`.\nThe `[HOST_IDENTIFIER]` can be found within the [Credentials](https://app.swiftype.com/as#/credentials) menu.\n\n```ruby\nrequire 'elastic-app-search'\n\nclient = Elastic::AppSearch::Client.new(:host_identifier =\u003e 'host-c5s2mj', :api_key =\u003e 'private-xxxxxxxxxxxxxxxxxxx')\n```\n\n### API Methods\n\nThis client is a thin interface to the Elastic App Search Api. Additional details for requests and responses can be\nfound in the [documentation](https://swiftype.com/documentation/app-search).\n\n#### Indexing: Creating or Updating a Single Document\n\n```ruby\nengine_name = 'favorite-videos'\ndocument = {\n  :id =\u003e 'INscMGmhmX4',\n  :url =\u003e 'https://www.youtube.com/watch?v=INscMGmhmX4',\n  :title =\u003e 'The Original Grumpy Cat',\n  :body =\u003e 'A wonderful video of a magnificent cat.'\n}\n\nclient.index_document(engine_name, document)\n```\n\n#### Indexing: Creating or Replacing Documents\n\n```ruby\nengine_name = 'favorite-videos'\ndocuments = [\n  {\n    :id =\u003e 'INscMGmhmX4',\n    :url =\u003e 'https://www.youtube.com/watch?v=INscMGmhmX4',\n    :title =\u003e 'The Original Grumpy Cat',\n    :body =\u003e 'A wonderful video of a magnificent cat.'\n  },\n  {\n    :id =\u003e 'JNDFojsd02',\n    :url =\u003e 'https://www.youtube.com/watch?v=dQw4w9WgXcQ',\n    :title =\u003e 'Another Grumpy Cat',\n    :body =\u003e 'A great video of another cool cat.'\n  }\n]\n\nclient.index_documents(engine_name, documents)\n```\n\n#### Indexing: Updating Documents (Partial Updates)\n\n```ruby\nengine_name = 'favorite-videos'\ndocuments = [\n  {\n    :id =\u003e 'INscMGmhmX4',\n    :title =\u003e 'Updated title'\n  }\n]\n\nclient.update_documents(engine_name, documents)\n```\n\n#### Retrieving Documents\n\n```ruby\nengine_name = 'favorite-videos'\ndocument_ids = ['INscMGmhmX4', 'JNDFojsd02']\n\nclient.get_documents(engine_name, document_ids)\n```\n\n#### Listing Documents\n\n```ruby\nengine_name = 'favorite-videos'\n\nclient.list_documents(engine_name)\n```\n\n#### Destroying Documents\n\n```ruby\nengine_name = 'favorite-videos'\ndocument_ids = ['INscMGmhmX4', 'JNDFojsd02']\n\nclient.destroy_documents(engine_name, document_ids)\n```\n\n#### Listing Engines\n\n```ruby\nclient.list_engines\n```\n\n#### Retrieving Engines\n\n```ruby\nengine_name = 'favorite-videos'\n\nclient.get_engine(engine_name)\n```\n\n#### Creating Engines\n\n```ruby\nengine_name = 'favorite-videos'\n\nclient.create_engine(engine_name)\n```\n\n#### Destroying Engines\n\n```ruby\nengine_name = 'favorite-videos'\n\nclient.destroy_engine(engine_name)\n```\n\n#### Creating Meta Engines\n\n```ruby\nengine_name = 'videos-engine'\nsources_engines = ['favorite-videos', 'all-videos']\n\nclient.create_meta_engine(engine_name, source_engines)\n```\n\n#### Adding Meta Engines Source\n\n```ruby\nengine_name = 'videos-engine'\nsources_engines = ['fun-videos', 'cat-videos']\n\nclient.add_meta_engine_sources(engine_name, source_engines)\n```\n\n#### Adding Meta Engines Source\n\n```ruby\nengine_name = 'videos-engine'\nsources_engines = ['nsfw-videos']\n\nclient.delete_meta_engine_sources(engine_name, source_engines)\n```\n\n#### Searching\n\n```ruby\nengine_name = 'favorite-videos'\nquery = 'cat'\nsearch_fields = { :title =\u003e {} }\nresult_fields = { :title =\u003e { :raw =\u003e {} } }\noptions = { :search_fields =\u003e search_fields, :result_fields =\u003e result_fields }\n\nclient.search(engine_name, query, options)\n```\n\n#### Multi-Search\n\n```ruby\nengine_name = 'favorite-videos'\nqueries = [{\n  :query =\u003e 'cat',\n  :options =\u003e { :search_fields =\u003e { :title =\u003e {} }}\n},{\n  :query =\u003e 'dog',\n  :options =\u003e { :search_fields =\u003e { :body =\u003e {} }}\n}]\n\nclient.multi_search(engine_name, queries)\n```\n\n#### Query Suggestion\n\n```ruby\nengine_name = 'favorite-videos'\noptions = {\n  :size =\u003e 3,\n  :types =\u003e {\n    :documents =\u003e {\n      :fields =\u003e ['title']\n    }\n  }\n}\n\nclient.query_suggestion(engine_name, 'cat', options)\n```\n\n#### Show Search Settings\n\n```ruby\nengine_name = 'favorite-videos'\n\nclient.show_settings(engine_name)\n```\n\n#### Update Search Settings\n\n```ruby\nengine_name = 'favorite-videos'\nsettings = {\n  'search_fields' =\u003e {\n    'id' =\u003e {\n      'weight' =\u003e 1\n    },\n    'url' =\u003e {\n      'weight' =\u003e 1\n    },\n    'title' =\u003e {\n      'weight' =\u003e 1\n    },\n    'body' =\u003e {\n      'weight' =\u003e 1\n    },\n  },\n  'boosts' =\u003e {\n    'title' =\u003e [\n      {\n        'type' =\u003e 'value',\n        'factor' =\u003e 9.5,\n        'operation' =\u003e 'multiply',\n        'value' =\u003e [\n          'Titanic'\n        ]\n      }\n    ]\n  }\n}\n\nclient.update_settings(engine_name, settings)\n```\n\n#### Reset Search Settings\n\n```ruby\nengine_name = 'favorite-videos'\n\nclient.reset_settings(engine_name)\n```\n\n#### Create a Signed Search Key\n\nCreating a search key that will only return the title field.\n\n```ruby\npublic_search_key = 'search-xxxxxxxxxxxxxxxxxxxxxxxx'\n# This name must match the name of the key above from your App Search dashboard\npublic_search_key_name = 'search-key'\nenforced_options = {\n  result_fields: { title: { raw: {} } },\n  filters: { world_heritage_site: 'true' }\n}\n\nsigned_search_key = Elastic::AppSearch::Client.create_signed_search_key(public_search_key, public_search_key_name, enforced_options)\n\nclient = Elastic::AppSearch::Client.new(:api_key =\u003e signed_search_key, :api_endpoint =\u003e 'http://localhost:3002/api/as/v1/')\n\nclient.search('national-parks-demo', 'everglade')\n```\n\n#### Log click-through\n\nLogging a click through\n\n```ruby\nengine_name = 'favorite-videos'\noptions = {\n  :query =\u003e 'cat videos',\n  :document_id =\u003e 'INscMGmhmX4',\n  :request_id =\u003e 'e4c4dea0bd7ad3d2f676575ef16dc7d2',\n  :tags =\u003e ['firefox', 'web browser']\n}\n\nclient.log_click_through(engine_name, options)\n```\n\n#### Analytics - Number of clicks-throughs received by a document\n\n```ruby\nengine_name = 'favorite-videos'\noptions = {\n  :query =\u003e 'cats',\n  :page =\u003e {\n    :size =\u003e 20,\n  },\n  :filters =\u003e {\n    :date =\u003e {\n      :from =\u003e '2019-04-11T00:00:00+00:00',\n      :to =\u003e '2019-04-13T00:00:00+00:00'\n    }\n  }\n}\n\nclient.get_top_clicks_analytics(engine_name, options)\n```\n\n#### Analytics - Queries, number of queries, and clicks received\n\n```ruby\nengine_name = 'favorite-videos'\noptions = {\n  :page =\u003e {\n    :size =\u003e 20\n  },\n  :filters =\u003e {\n    :date =\u003e {\n      :from =\u003e '2019-04-11T00:00:00+00:00',\n      :to =\u003e '2019-04-13T00:00:00+00:00'\n    }\n  }\n}\n\nclient.get_top_queries_analytics(engine_name, options)\n```\n\n#### Analytics - Number of clicks and total number of queries\n\n```ruby\nengine_name = 'favorite-videos'\noptions = {\n  :filters =\u003e {\n    :all =\u003e [\n      {\n        :tag =\u003e ['mobile', 'web']\n      },{\n        :query =\u003e 'cats'\n      }, {\n        :document_id =\u003e '163'\n      }, {\n        :date =\u003e {\n          :from =\u003e '2018-07-05T12:00:00+00:00',\n          :to =\u003e '2018-07-05T14:00:00+00:00'\n        }\n      }\n    ]\n  },\n  :interval =\u003e 'hour'\n}\n\nclient.get_count_analytics(engine_name, options)\n```\n\n#### Creating Synonym Sets\n\n```ruby\nengine_name = 'us-national-parks'\n\nclient.create_synonym_set(engine_name, :synonyms =\u003e ['park', 'trail'])\n```\n\n#### Retrieving Synonym Sets\n\n```ruby\nengine_name = 'us-national-parks'\n\nclient.get_synonym_set(engine_name, 'syn-5d8e6b5d40caae7dcb6e1b9c')\n```\n\n#### Listing Synonym Sets\n\n```ruby\nengine_name = 'us-national-parks'\n\nclient.list_synonym_sets(engine_name, :current =\u003e 1, :size =\u003e 20)\n```\n\n#### Updating Synonym Sets\n\n```ruby\nengine_name = 'us-national-parks'\n\nclient.update_synonym_set(engine_name, 'syn-5d8e6b5d40caae7dcb6e1b9c', :synonyms =\u003e ['park', 'trail', 'ground'])\n```\n\n#### Destroying Synonym Sets\n\n```ruby\nengine_name = 'us-national-parks'\n\nclient.destroy_synonym_set(engine_name, 'syn-5d8e6b5d40caae7dcb6e1b9c')\n```\n\n#### Listing Credentials\n\n```ruby\nclient.list_credentials(:current =\u003e 1, :size =\u003e 20)\n```\n\n#### Retrieving Credentials\n\n```ruby\nclient.get_credential('reading-private-key')\n```\n\n#### Creating Credentials\n\n```ruby\nclient.create_credential({\n  :name =\u003e 'reading-private-key',\n  :type =\u003e 'private',\n  :read =\u003e true,\n  :write =\u003e false,\n  :access_all_engines =\u003e false,\n  :engines =\u003e [\n    'favorite-videos'\n  ]\n})\n```\n\n#### Updating Credentials\n\n```ruby\nclient.update_credential('reading-private-key', {\n  :name =\u003e 'reading-private-key',\n  :type =\u003e 'private',\n  :read =\u003e true,\n  :write =\u003e true,\n  :access_all_engines =\u003e false,\n  :engines =\u003e [\n    'favorite-videos'\n  ]\n})\n```\n\n#### Destroying Credentials\n\n```ruby\nclient.destroy_credential('reading-private-key')\n```\n\n#### Retrieving an Engine's Schema\n\n```ruby\nengine_name = 'us-national-parks'\n\nclient.get_schema(engine_name)\n```\n\n#### Updating an Engine's Schema or Creating a New Schema Field\n\n```ruby\nengine_name = 'us-national-parks'\n\nclient.update_schema(engine_name, 'square_km' =\u003e 'number')\n```\n\n#### Creating Curations\n\n```ruby\nengine_name = 'us-national-parks'\noptions = {\n  'queries' =\u003e [\n    'zion'\n  ],\n  'promoted' =\u003e [\n    'doc-5d8e413b40caaedab76e3c96'\n  ],\n  'hidden' =\u003e [\n    'doc-5d8e413d40caae335e06c374'\n  ]\n}\n\nclient.create_curation(engine_name, options)\n```\n\n#### Retrieving Curations\n\n```ruby\nengine_name = 'us-national-parks'\n\nclient.get_curation(engine_name, 'cur-5d9240d640caaeca6506b600')\n```\n\n#### Listing Curations\n\n```ruby\nengine_name = 'us-national-parks'\n\nclient.list_curations(engine_name, current: 1, size: 20)\n```\n\n#### Updating Curations\n\n```ruby\nengine_name = 'us-national-parks'\nid = 'cur-5d9240d640caaeca6506b600'\noptions = {\n  'queries' =\u003e [\n    'zion'\n  ],\n  'promoted' =\u003e [\n    'doc-5d8e413b40caaedab76e3c96'\n  ]\n}\n\nclient.update_curation(engine_name, id, options)\n```\n\n#### Destroying Curations\n\n```ruby\nengine_name = 'us-national-parks'\n\nclient.destroy_curation(engine_name, 'cur-5d9240d640caaeca6506b600')\n```\n\n#### Retrieving API Logs\n\n```ruby\nengine_name = 'us-national-parks'\noptions = {\n  'filters' =\u003e {\n    'date' =\u003e {\n      'from' =\u003e '2019-09-23T00:00:00+00:00',\n      'to' =\u003e '2019-09-28T00:00:00+00:00'\n    }\n  },\n  'page' =\u003e {\n    'total_results' =\u003e 100,\n    'size' =\u003e 20\n  },\n  'query' =\u003e 'search',\n  'sort_direction' =\u003e 'desc'\n}\n\nclient.get_api_logs(engine_name, options)\n```\n\n## Running Tests\n\n```bash\nexport AS_API_KEY=\"[API_KEY]\"\nexport AS_ADMIN_KEY=\"[ADMIN_API_KEY]\"\nexport AS_HOST_IDENTIFIER=\"[HOST_IDENTIFIER]\"\nbundle exec rspec\n```\n\nYou can also run tests against a local environment by passing a `AS_API_ENDPOINT` environment variable\n\n```bash\nexport AS_API_KEY=\"[API_KEY]\"\nexport AS_ADMIN_KEY=\"[ADMIN_API_KEY]\"\nexport AS_API_ENDPOINT=\"http://[HOST_IDENTIFIER].api.127.0.0.1.ip.es.io:3002/api/as/v1\"\nbundle exec rspec\n```\n\n## Debugging API calls\n\nIf you need to debug an API call made by the client, there are a few things you could do:\n\n1. Setting `AS_DEBUG` environment variable to `true` would enable HTTP-level debugging and you would\n   see all requests generated by the client on your console.\n\n2. You could use our API logs feature in App Search console to see your requests and responses live.\n\n3. In your debug logs you could find a `X-Request-Id` header value. That could be used when talking\n   to Elastic Customer Support to help us quickly find your API request and help you troubleshoot\n   your issues.\n\n## FAQ 🔮\n\n### Where do I report issues with the client?\n\nIf something is not working as expected, please open an [issue](https://github.com/elastic/app-search-ruby/issues/new).\n\n### Where can I learn more about App Search?\n\nYour best bet is to read the [documentation](https://swiftype.com/documentation/app-search).\n\n### Where else can I go to get help?\n\nYou can checkout the [Elastic App Search community discuss forums](https://discuss.elastic.co/c/app-search).\n\n## Contribute 🚀\n\nWe welcome contributors to the project. Before you begin, a couple notes...\n\n- Before opening a pull request, please create an issue to [discuss the scope of your proposal](https://github.com/elastic/app-search-ruby/issues).\n- Please write simple code and concise documentation, when appropriate.\n\n## License 📗\n\n[Apache 2.0](https://github.com/elastic/app-search-ruby/blob/master/LICENSE.txt) © [Elastic](https://github.com/elastic)\n\nThank you to all the [contributors](https://github.com/elastic/app-search-ruby/graphs/contributors)!\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Felastic%2Fapp-search-ruby","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Felastic%2Fapp-search-ruby","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Felastic%2Fapp-search-ruby/lists"}