elastic-app-search 7.4.0 → 7.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 23ca08f1c2392f7be42177b5b3d8574b41949eaacffa31699d2b46b482a84021
-  data.tar.gz: 267e8bac44dfd815e42a9d6e6971de0b342feb1a2982887028adfebd83faf0d3
+  metadata.gz: 3ace14a91577b5aa735c0fa0949830c7c79e02fba58ed7cf3c51b2189a74abbd
+  data.tar.gz: 3af818ab74bd2485069f2f3adcdb7edd595d91a23960fd4a68cce7f1fbc52f3e
 SHA512:
-  metadata.gz: '0019c22322850583ed5f3e1062365998511e31200a7fe938eb7a3a63ff2a35540977541f666a8144d8cd9ed5cff91307d7f2bb90224859610a94ea99cd5f1ef2'
-  data.tar.gz: 4b22ee129457885c0084d5e6bb931fb78e37b8e0f15f697e650e7804aa075eead085ef7f36729d26634d2f7419f9d4e2a7939592970d0e48d939a83745e2775a
+  metadata.gz: 7f4a064d8e3e556f746cfcb9c7fe50753951aa2d7b75a05d91f5073b36520c019d1f8e1ea0d73927730193cfa0e7c75d73fa9dde9f8f3a8f24aff0ef7d26b8e1
+  data.tar.gz: c87f7b6b9a72115bcc76d5f903bc5d7dafd00c680670ed2fcf15faef7dcc9b7dd59d6b2e7df6a9d2a66d6c91fcca81c75cfc1b8b12dfb4529d3ed3991b5c141e

data/README.md

@@ -2,7 +2,7 @@
 
 <p align="center"><a href="https://circleci.com/gh/elastic/app-search-ruby"><img src="https://circleci.com/gh/elastic/app-search-ruby.svg?style=svg" alt="CircleCI build"></a></p>
 
-> A first-party Ruby client for building excellent, relevant search experiences with Elastic App Search.
+> A first-party Ruby client for building excellent, relevant search experiences with [Elastic App Search](https://www.elastic.co/products/app-search).
 
 ## Contents
 
@@ -25,7 +25,7 @@ To install the gem, execute:
 gem install elastic-app-search
 ```
 
-Or place `gem 'elastic-app-search', '~> 7.4.0'` in your `Gemfile` and run `bundle install`.
+Or place `gem 'elastic-app-search', '~> 7.8.0'` in your `Gemfile` and run `bundle install`.
 
 ## Versioning
 
@@ -35,34 +35,37 @@ To guarantee compatibility, use the most recent version of this library within t
 
 For example, for App Search `7.3`, use `7.3` of this library or above, but not `8.0`.
 
-If you are a [SaaS](https://app.swiftype.com/as) user, simply use the most recent version of this library.
+If 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.
 
 ## Usage
 
-### Setup: Configuring the client and authentication
+#### Setup: Configuring the client and authentication
 
-Create a new instance of the Elastic App Search Client. This requires your `[HOST_IDENTIFIER]`, which
-identifies the unique hostname of the App Search API that is associated with your App Search account.
-It also requires a valid `[API_KEY]`, which authenticates requests to the API. You can use any key type with the client, however each has a different scope. For more information on keys, check out the [documentation](https://swiftype.com/documentation/app-search/credentials).
+Using this client assumes that you have already an instance of [Elastic App Search](https://www.elastic.co/products/app-search) up and running.
 
-You can find your `[API_KEY]` and your `[HOST_IDENTIFIER]` within the [Credentials](https://app.swiftype.com/as/credentials) menu:
+Once done, a client can be instantiated using the `[API_KEY]` and the `[API_ENDPOINT]` URL of your App Search setup:
 
 ```ruby
 require 'elastic-app-search'
 
-client = Elastic::AppSearch::Client.new(:host_identifier => 'host-c5s2mj', :api_key => 'private-mu75psc5egt9ppzuycnc2mc3')
+client = Elastic::AppSearch::Client.new(:api_key => 'private-xxxxxxxxxxxxxxxxxxx', :api_endpoint => 'http://localhost:3002/api/as/v1/')
 ```
 
-### Using with App Search Managed Deploys
+Note:
 
-The client can be configured to use a managed deploy by using the
-`api_endpoint` parameter. Since managed deploys do not rely on a `[HOST_IDENTIFIER]`
-, it can be omitted.
+The `[API_KEY]` authenticates requests to the API.
+You can use any key type with the client, however each has a different scope.
+For more information on keys, check out the [documentation](https://swiftype.com/documentation/app-search/api/credentials).
+
+##### Swiftype.com App Search users:
+
+When 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]`.
+The `[HOST_IDENTIFIER]` can be found within the [Credentials](https://app.swiftype.com/as#/credentials) menu.
 
 ```ruby
 require 'elastic-app-search'
 
-client = Elastic::AppSearch::Client.new(:api_key => 'private-mu75psc5egt9ppzuycnc2mc3', :api_endpoint => 'http://localhost:3002/api/as/v1/')
+client = Elastic::AppSearch::Client.new(:host_identifier => 'host-c5s2mj', :api_key => 'private-xxxxxxxxxxxxxxxxxxx')
 ```
 
 ### API Methods
@@ -176,6 +179,33 @@ engine_name = 'favorite-videos'
 client.destroy_engine(engine_name)
 ```
 
+#### Creating Meta Engines
+
+```ruby
+engine_name = 'videos-engine'
+sources_engines = ['favorite-videos', 'all-videos']
+
+client.create_meta_engine(engine_name, source_engines)
+```
+
+#### Adding Meta Engines Source
+
+```ruby
+engine_name = 'videos-engine'
+sources_engines = ['fun-videos', 'cat-videos']
+
+client.add_meta_engine_sources(engine_name, source_engines)
+```
+
+#### Adding Meta Engines Source
+
+```ruby
+engine_name = 'videos-engine'
+sources_engines = ['nsfw-videos']
+
+client.delete_meta_engine_sources(engine_name, source_engines)
+```
+
 #### Searching
 
 ```ruby
@@ -192,7 +222,6 @@ client.search(engine_name, query, options)
 
 ```ruby
 engine_name = 'favorite-videos'
-
 queries = [{
   :query => 'cat',
   :options => { :search_fields => { :title => {} }}
@@ -208,7 +237,6 @@ client.multi_search(engine_name, queries)
 
 ```ruby
 engine_name = 'favorite-videos'
-
 options = {
   :size => 3,
   :types => {
@@ -233,30 +261,29 @@ client.show_settings(engine_name)
 
 ```ruby
 engine_name = 'favorite-videos'
-
 settings = {
-  "search_fields" => {
-    "id" => {
-      "weight" => 1
+  'search_fields' => {
+    'id' => {
+      'weight' => 1
     },
-    "url" => {
-      "weight" => 1
+    'url' => {
+      'weight' => 1
     },
-    "title" => {
-      "weight" => 1
+    'title' => {
+      'weight' => 1
     },
-    "body" => {
-      "weight" => 1
+    'body' => {
+      'weight' => 1
     },
   },
-  "boosts" => {
-    "title" => [
+  'boosts' => {
+    'title' => [
       {
-        "type" => "value",
-        "factor" => 9.5,
-        "operation" => "multiply",
-        "value" => [
-          "Titanic"
+        'type' => 'value',
+        'factor' => 9.5,
+        'operation' => 'multiply',
+        'value' => [
+          'Titanic'
         ]
       }
     ]
@@ -288,14 +315,284 @@ enforced_options = {
 
 signed_search_key = Elastic::AppSearch::Client.create_signed_search_key(public_search_key, public_search_key_name, enforced_options)
 
-client = Elastic::AppSearch::Client.new(host_identifier: 'host-c5s2mj', api_key: signed_search_key)
+client = Elastic::AppSearch::Client.new(:api_key => signed_search_key, :api_endpoint => 'http://localhost:3002/api/as/v1/')
+
 client.search('national-parks-demo', 'everglade')
 ```
 
+#### Log click-through
+
+Logging a click through
+
+```ruby
+engine_name = 'favorite-videos'
+options = {
+  :query => 'cat videos',
+  :document_id => 'INscMGmhmX4',
+  :request_id => 'e4c4dea0bd7ad3d2f676575ef16dc7d2',
+  :tags => ['firefox', 'web browser']
+}
+
+client.log_click_through(engine_name, options)
+```
+
+#### Analytics - Number of clicks-throughs received by a document
+
+```ruby
+engine_name = 'favorite-videos'
+options = {
+  :query => 'cats',
+  :page => {
+    :size => 20,
+  },
+  :filters => {
+    :date => {
+      :from => '2019-04-11T00:00:00+00:00',
+      :to => '2019-04-13T00:00:00+00:00'
+    }
+  }
+}
+
+client.get_top_clicks_analytics(engine_name, options)
+```
+
+#### Analytics - Queries, number of queries, and clicks received
+
+```ruby
+engine_name = 'favorite-videos'
+options = {
+  :page => {
+    :size => 20
+  },
+  :filters => {
+    :date => {
+      :from => '2019-04-11T00:00:00+00:00',
+      :to => '2019-04-13T00:00:00+00:00'
+    }
+  }
+}
+
+client.get_top_queries_analytics(engine_name, options)
+```
+
+#### Analytics - Number of clicks and total number of queries
+
+```ruby
+engine_name = 'favorite-videos'
+options = {
+  :filters => {
+    :all => [
+      {
+        :tag => ['mobile', 'web']
+      },{
+        :query => 'cats'
+      }, {
+        :document_id => '163'
+      }, {
+        :date => {
+          :from => '2018-07-05T12:00:00+00:00',
+          :to => '2018-07-05T14:00:00+00:00'
+        }
+      }
+    ]
+  },
+  :interval => 'hour'
+}
+
+client.get_count_analytics(engine_name, options)
+```
+
+#### Creating Synonym Sets
+
+```ruby
+engine_name = 'us-national-parks'
+
+client.create_synonym_set(engine_name, :synonyms => ['park', 'trail'])
+```
+
+#### Retrieving Synonym Sets
+
+```ruby
+engine_name = 'us-national-parks'
+
+client.get_synonym_set(engine_name, 'syn-5d8e6b5d40caae7dcb6e1b9c')
+```
+
+#### Listing Synonym Sets
+
+```ruby
+engine_name = 'us-national-parks'
+
+client.list_synonym_sets(engine_name, :current => 1, :size => 20)
+```
+
+#### Updating Synonym Sets
+
+```ruby
+engine_name = 'us-national-parks'
+
+client.update_synonym_set(engine_name, 'syn-5d8e6b5d40caae7dcb6e1b9c', :synonyms => ['park', 'trail', 'ground'])
+```
+
+#### Destroying Synonym Sets
+
+```ruby
+engine_name = 'us-national-parks'
+
+client.destroy_synonym_set(engine_name, 'syn-5d8e6b5d40caae7dcb6e1b9c')
+```
+
+#### Listing Credentials
+
+```ruby
+client.list_credentials(:current => 1, :size => 20)
+```
+
+#### Retrieving Credentials
+
+```ruby
+client.get_credential('reading-private-key')
+```
+
+#### Creating Credentials
+
+```ruby
+client.create_credential({
+  :name => 'reading-private-key',
+  :type => 'private',
+  :read => true,
+  :write => false,
+  :access_all_engines => false,
+  :engines => [
+    'favorite-videos'
+  ]
+})
+```
+
+#### Updating Credentials
+
+```ruby
+client.update_credential('reading-private-key', {
+  :name => 'reading-private-key',
+  :type => 'private',
+  :read => true,
+  :write => true,
+  :access_all_engines => false,
+  :engines => [
+    'favorite-videos'
+  ]
+})
+```
+
+#### Destroying Credentials
+
+```ruby
+client.destroy_credential('reading-private-key')
+```
+
+#### Retrieving an Engine's Schema
+
+```ruby
+engine_name = 'us-national-parks'
+
+client.get_schema(engine_name)
+```
+
+#### Updating an Engine's Schema or Creating a New Schema Field
+
+```ruby
+engine_name = 'us-national-parks'
+
+client.update_schema(engine_name, 'square_km' => 'number')
+```
+
+#### Creating Curations
+
+```ruby
+engine_name = 'us-national-parks'
+options = {
+  'queries' => [
+    'zion'
+  ],
+  'promoted' => [
+    'doc-5d8e413b40caaedab76e3c96'
+  ],
+  'hidden' => [
+    'doc-5d8e413d40caae335e06c374'
+  ]
+}
+
+client.create_curation(engine_name, options)
+```
+
+#### Retrieving Curations
+
+```ruby
+engine_name = 'us-national-parks'
+
+client.get_curation(engine_name, 'cur-5d9240d640caaeca6506b600')
+```
+
+#### Listing Curations
+
+```ruby
+engine_name = 'us-national-parks'
+
+client.list_curations(engine_name, current: 1, size: 20)
+```
+
+#### Updating Curations
+
+```ruby
+engine_name = 'us-national-parks'
+id = 'cur-5d9240d640caaeca6506b600'
+options = {
+  'queries' => [
+    'zion'
+  ],
+  'promoted' => [
+    'doc-5d8e413b40caaedab76e3c96'
+  ]
+}
+
+client.update_curation(engine_name, id, options)
+```
+
+#### Destroying Curations
+
+```ruby
+engine_name = 'us-national-parks'
+
+client.destroy_curation(engine_name, 'cur-5d9240d640caaeca6506b600')
+```
+
+#### Retrieving API Logs
+
+```ruby
+engine_name = 'us-national-parks'
+options = {
+  'filters' => {
+    'date' => {
+      'from' => '2019-09-23T00:00:00+00:00',
+      'to' => '2019-09-28T00:00:00+00:00'
+    }
+  },
+  'page' => {
+    'total_results' => 100,
+    'size' => 20
+  },
+  'query' => 'search',
+  'sort_direction' => 'desc'
+}
+
+client.get_api_logs(engine_name, options)
+```
+
 ## Running Tests
 
 ```bash
 export AS_API_KEY="[API_KEY]"
+export AS_ADMIN_KEY="[ADMIN_API_KEY]"
 export AS_HOST_IDENTIFIER="[HOST_IDENTIFIER]"
 bundle exec rspec
 ```
@@ -304,6 +601,7 @@ You can also run tests against a local environment by passing a `AS_API_ENDPOINT
 
 ```bash
 export AS_API_KEY="[API_KEY]"
+export AS_ADMIN_KEY="[ADMIN_API_KEY]"
 export AS_API_ENDPOINT="http://[HOST_IDENTIFIER].api.127.0.0.1.ip.es.io:3002/api/as/v1"
 bundle exec rspec
 ```