elastic-enterprise-search 7.10.0.beta.1 → 7.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 44f9e978a08756f49fb8e41f7e87b456c0eb07f0296f276777502008bce5f6be
-  data.tar.gz: 76a990ce960e215850f041bd12facbf1d2d49041957117c2462be861cba49a23
+  metadata.gz: 4088e21d195caeed0c05e7374d8317903d1784a71e1e21de3e7d11f0fea30b32
+  data.tar.gz: c6cc664ab8b1a388b49809aafeb1e5395284e33912b0864a591bd354e72dc3f0
 SHA512:
-  metadata.gz: 1b794b281d4fe0936f9e8025f8b2f1c7309f31d68bcfbaee43181e983f8a155a359de54b81b70d4eba2bbe581c8f8ea90e66d6b704e99678dbb5f82858a50251
-  data.tar.gz: 8c39a543c9a41574a6632148f242ff860077e01f7d52004e82c2224f35e028839b740315fbb1276b7562e2fa8026697d214222d857e178b4f5d1cf9f7d77f4db
+  metadata.gz: 8e471a1602e19cf80d8b28014d2266405cc17fb19dc1d11c5a0a290cc06199cfd9c0407f6fd946e9e28afeb83d8d48cbb2b4eb82e6e9d43942b49b8ddbaf3285
+  data.tar.gz: c36ecb6be8ec8d91e6827715f166119532c7e61887a300941506b79be0d1a3f666f2f8374155d671650ca97359883b1bd6af9dab47fe520f3d30294c9e62c642

data/.ci/jobs/elastic+enterprise-search-ruby+7.10.0.beta.1.yml

@@ -0,0 +1,12 @@
+---
+- job:
+    name: elastic+enterprise-search-ruby+7.10.0.beta.1
+    display-name: 'elastic / enterprise-search-ruby # 7.10.0.beta.1'
+    description: Testing the enterprise-search-ruby 7.10.0.beta.1 branch.
+    junit_results: "*-junit.xml"
+    parameters:
+    - string:
+        name: branch_specifier
+        default: refs/heads/7.10.0.beta.1
+        description: the Git branch specifier to build (<branchName>, <tagName>,
+          <commitId>, etc.)

data/.ci/test-matrix.yml

@@ -1,11 +1,12 @@
 ---
 RUBY_VERSION:
+  - 3.0
   - 2.7
   - 2.6
   - 2.5
 
 STACK_VERSION:
-  - 7.10-SNAPSHOT
+  - 7.x-SNAPSHOT
 
 TEST_SUITE:
   - xpack

data/.github/workflows/testing.yml

@@ -7,7 +7,7 @@ jobs:
       ENDPOINT: http://localhost:8080
     strategy:
       matrix:
-        ruby: [ 2.5, 2.6, 2.7 ]
+        ruby: [ 2.5, 2.6, 2.7, 3.0 ]
 
     runs-on: ubuntu-latest
     steps:

data/.gitignore

@@ -11,3 +11,4 @@ doc
 .#*
 *junit.xml
 .byebug_history
+coverage

data/CONTRIBUTING.md

@@ -0,0 +1,43 @@
+# Contributing to enterprise-search-ruby
+
+## Contributing Code Changes
+
+1. Please make sure you have signed the [Contributor License
+   Agreement](http://www.elastic.co/contributor-agreement/). We are not
+   asking you to assign copyright to us, but to give us the right to distribute
+   your code without restriction. We ask this of all contributors in order to
+   assure our users of the origin and continuing existence of the code. You only
+   need to sign the CLA once.
+ 
+2. Run rubocop and the test suite to ensure your changes do not break existing
+   code:
+   
+   ```
+   $ bundle exec rubocop
+   ```
+   
+   Check [Running
+   tests](https://github.com/elastic/enterprise-search-ruby/#run-tests) on the
+   README for instructions on how to run all the tests.
+
+3. Rebase your changes. Update your local repository with the most recent code
+   from the main `enterprise-search-ruby` repository and rebase your branch
+   on top of the latest `master` branch. All of your changes will be squashed
+   into a single commit so don't worry about pushing multiple times.
+   
+4. Submit a pull request. Push your local changes to your forked repository
+   and [submit a pull request](https://github.com/elastic/enterprise-search-python/pulls)
+   and mention the issue number if any (`Closes #123`) Make sure that you
+   add or modify tests related to your changes so that CI will pass.
+   
+5. Sit back and wait. There may be some discussion on your pull request and
+   if changes are needed we would love to work with you to get your pull request
+   merged into enterprise-search-ruby.
+
+## API Code Generation
+
+All the API methods within
+`lib/elastic/[app-search|enterprise-search|workplace-search]/api/*.rb` are
+generated from an API specification that is not available publicly currently.
+Because these files are generated, changes should instead be suggested in an
+issue or as part of the description in your Pull Request.

data/Gemfile

@@ -23,3 +23,4 @@ source 'https://rubygems.org'
 gemspec
 
 gem 'rake'
+gem 'simplecov', require: false, group: :test

data/README.md

@@ -4,232 +4,11 @@
 ![rubocop](https://github.com/elastic/enterprise-search-ruby/workflows/rubocop/badge.svg)
 [![Ruby Style Guide](https://img.shields.io/badge/code_style-rubocop-brightgreen.svg)](https://github.com/rubocop-hq/rubocop)
 
-This project is in development and in a beta state.
+Official Ruby API client for [Elastic Enterprise Search](https://www.elastic.co/enterprise-search). Use this gem to integrate App Search and Workplace Search into your Ruby code.
 
-## Contents
-- [Installation](https://github.com/elastic/enterprise-search-ruby#installation)
-- [Getting Started](https://github.com/elastic/enterprise-search-ruby#getting-started)
-  - [Enterprise Search](https://github.com/elastic/enterprise-search-ruby#enterprise-search)
-  - [Workplace Search](https://github.com/elastic/enterprise-search-ruby#workplace-search)
-  - [App Search](https://github.com/elastic/enterprise-search-ruby#app-search)
-- [HTTP Layer](https://github.com/elastic/enterprise-search-ruby#http-layer)
-  - [Setting the host and port](https://github.com/elastic/enterprise-search-ruby#setting-the-host-and-port)
-  - [Logging](https://github.com/elastic/enterprise-search-ruby#logging)
-- [Development](https://github.com/elastic/enterprise-search-ruby#development)
-  - [Run stack locally](https://github.com/elastic/enterprise-search-ruby#run-stack-locally)
-  - [Run tests](https://github.com/elastic/enterprise-search-ruby#run-tests)
-- [License](https://github.com/elastic/enterprise-search-ruby#license)
+## Documentation
 
-## Installation
-
-Install the gem:
-
-```
-$ gem install elastic-enterprise-search --pre
-```
-
-Or add it to your project's Gemfile:
-
-```
-gem 'elastic-enterprise-search'
-```
-
-The version follows the Elastic Stack version so 7.10.0 is compatible with Enterprise Search released in Elastic Stack 7.10.0.
-
-## Getting Started
-
-### Enterprise Search
-
-The Enterprise Search API uses basic auth with credentials from an Elasticsearch user. You can read about the API, authentication and privileges needed [on the official docs](https://www.elastic.co/guide/en/enterprise-search/current/management-apis.html).
-
-#### Example usage:
-
-```ruby
-http_auth = {user: 'elastic', password: 'password'}
-host = 'https://id.ent-search.europe-west2.gcp.elastic-cloud.com'
-
-ent_client = Elastic::EnterpriseSearch::Client.new(host: host, http_auth: http_auth)
-```
-
-#### Health API
-
-```ruby
-> response = ent_client.health
-> response.body
- => {"name"=>"...",
-     "version"=>{"number"=>"7.10.0", "build_hash"=>"...", "build_date"=>"..."},
-     "jvm"=>{...},
-     "filebeat"=>{...},
-     "system"=>{...}
-    }
-```
-
-#### Version API
-
-```ruby
-> response = ent_client.version
-> response.body
- => {"number"=>"7.10.0", "build_hash"=>"...", "build_date"=>"..."}
-```
-
-#### Managing Read-Only mode:
-
-```ruby
-# Set read-only flag state
-ent_client.put_read_only(enabled: false)
-
-# Get read-only flag state
-ent_client.read_only
-```
-
-#### Stats API
-```ruby
-> ent_client.stats.body
- => {"app"=>{"pid"=>1, "start"=>"...", "end"=>"", "metrics"=>{...}},
-     "queues"=>{"connectors"=>{...}, "document_destroyer"=>{...}, "engine_destroyer"=>{...}, "index_adder"=>{...}, ...},
-     "connectors"=>{"alive"=>true, "pool"=>{...}, "job_store"=>{...}}}}
-
-```
-
-### Workplace Search
-
-In your Elastic Workplace Search dashboard navigate to _Sources/Add a Shared Content Source_ and select _Custom API Source_ to create a new source. Name your source (e.g. `Enterprise Search Ruby Client`) and once it's created you'll get an `access token` and a `key`. You'll need these in the following steps.
-
-#### Instantiation
-
-The Workplace Search client can be accessed from an existing Enterprise Search Client, or you can initialize a new one. If you instantiate the Workplace Search client from an existing Enterprise Search Client, it's going to share the HTTP transport instance, so it's going to connect to the same host, which is a common scenario. However, if you want to connect to a different host, you should instantiate a new Workplace Client on its own:
-
-```ruby
-# Prerequisites
-host = 'https://id.ent-search.europe-west2.gcp.elastic-cloud.com'
-access_token = '<access token>'
-content_source_key = '<content source key>'
-
-# From the Enterprise Search client:
-ent_client = Elastic::EnterpriseSearch::Client.new(host: host)
-ent_client.workplace_search.http_auth = access_token
-ent_client.workplace_search.index_documents(content_source_key, body: documents)
-
-# On its own
-workplace_search_client = Elastic::EnterpriseSearch::WorkplaceSearch::Client.new(
-  host: host,
-  http_auth: access_token
-)
-```
-
-### App Search
-
-In your Elastic App Search dashboard, navigate to Credentials and Create a Key for the client to use. Make sure to read [the documentation on Authentication](https://www.elastic.co/guide/en/app-search/current/authentication.html) to understand which key you want to use. Once you've created your key, you need to copy the key value to use on your client:
-
-#### Instantiation
-
-The App Search client can be accessed from an existing Enterprise Search Client, or you can initialize a new one. If you instantiate the App Search client from an existing Enterprise Search Client, it's going to share the HTTP transport instance, so it's going to connect to the same host which is a common scenario. However, if you want to connect to a different host, you should instantiate a new App Search Client on its own.
-
-```ruby
-# Prerequisites
-host = 'https://id.ent-search.europe-west2.gcp.elastic-cloud.com'
-api_key = 'private-api-key'
-
-# From the Enterprise Search client:
-ent_client = Elastic::EnterpriseSearch::Client.new(host: host)
-ent_client.app_search.http_auth = api_key
-
-# On its own
-client = Elastic::EnterpriseSearch::AppSearch::Client.new(host: host, http_auth: api_key)
-```
-
-#### Engines
-
-```ruby
-# Create an engine
-client.create_engine(name: 'videogames')
-
-# List all engines
-client.list_engines
-
-# Get an engine
-client.engine('videogames')
-
-# Delete an engine
-client.delete_engine('videogames')
-```
-
-#### Documents
-
-```ruby
-engine_name = 'videogames'
-document = {
-  id: 'Mr1064',
-  name: 'Super Luigi 64',
-  body: 'A classic 3D videogame'
-}
-
-# Index documents
-client.index_documents(engine_name, body: document)
-
-# List documents
-client.list_documents(engine_name)
-
-# Delete a document
-client.delete_documents(engine_name, body: [document_id])
-
-# Update a document
-client.put_documents(engine_name, body: [{id: document_id, key: value}])
-```
-
-#### Search
-
-```ruby
-query = {
-  query: 'luigi'
-}
-
-client.search(engine_name, query)
-```
-
-#### Other API Endpoints
-
-```ruby
-
-# Count analytics - Returns the number of clicks and total number of queries over a period
-client.count_analytics(engine_name)
-
-# Schema - Retrieve current schema for the engine
-client.schema(engine_name)
-
-# Logs - The API Log displays API request and response data at the Engine level
-client.api_logs(engine_name, from_date: Date.new(2020, 10, 01), to_date: Date.new(2020, 11, 05))
-
-# Queries Analytics - Returns queries analytics by usage count
-client.top_queries_analytics(engine_name)
-
-# Clicks Analytics - Returns the number of clicks received by a document in descending order
-client.top_clicks_analytics(engine_name, query: {})
-
-```
-
-## HTTP Layer
-
-This library uses [elasticsearch-transport](https://github.com/elastic/elasticsearch-ruby/tree/master/elasticsearch-transport), the low-level Ruby client for connecting to an Elasticsearch cluster - also used in the official [Elasticsearch Ruby Client](https://github.com/elastic/elasticsearch-ruby).
-
-All requests, if successful, will return an `Elasticsearch::Transport::Transport::Response` instance. You can access the response `body`, `headers` and `status`.
-
-`elasticsearch-transport` defines a [number of exception classes](https://github.com/elasticsearch/elasticsearch-ruby/blob/master/elasticsearch-transport/lib/elasticsearch/transport/transport/errors.rb) for various client and server errors, as well as unsuccessful HTTP responses, making it possible to rescue specific exceptions with desired granularity. More details [here](https://github.com/elastic/elasticsearch-ruby/tree/master/elasticsearch-transport#exception-handling). You can find the full documentation for `elasticsearch-transport` at [RubyDoc](https://rubydoc.info/gems/elasticsearch-transport).
-
-The clients pass different options to transport, you can check them out [in the source code](https://github.com/elastic/enterprise-search-ruby/blob/master/lib/elastic/enterprise-search/client.rb) while we set up RubyDocs.
-
-### Setting the host and port
-
-If you don't specify a host and port, the client will default to `http://localhost:3002`. Otherwise pass in the `:host` parameter as a String.
-
-### Logging
-
-You can enable logging with the default logger by passing `log: true` as a parameter to the client's initializer, or pass in a Logger object with the `:logger` parameter:
-
-```ruby
-logger = MyLogger.new
-client = Elastic::EnterpriseSearch::Client.new(logger: logger)
-```
+[See the documentation](https://www.elastic.co/guide/en/enterprise-search-clients/ruby/current/index.html) for compatibility info, configuring, and an API reference.
 
 ## Development
 
@@ -245,7 +24,9 @@ This will run Elastic Enterprise Search in http://localhost:3002
 - Username: `enterprise_search`
 - Password: `changeme`
 
-### Run Tests
+The version of the Elastic Enterprise Search Stack to use should be the same as tags of `https://www.docker.elastic.co/r/enterprise-search`. You can also use SNAPSHOT builds such as `8.0.0-SNAPSHOT`, `7.11-SNAPSHOT`, etc.
+
+### Running Tests
 
 Unit tests for the clients:
 
@@ -254,6 +35,7 @@ $ rake spec:client
 ```
 
 Integration tests: you need to have an instance of Enterprise Search running either locally or remotely, and specify the host and credentials in environment variables (see below for a complete dockerized setup). If you're using the included rake task `rake stack[:version]`, you can run the integration tests with the following command:
+
 ```
 $ ELASTIC_ENTERPRISE_HOST='http://localhost:3002' \
   ELASTIC_ENTERPRISE_USER='elastic' \

data/Rakefile

@@ -18,30 +18,7 @@
 # frozen_string_literal: true
 
 require 'rspec/core/rake_task'
-require_relative './lib/generator/endpoint_generator'
-
-SPECS = [:workplace, :enterprise, :app].freeze
-
-desc 'Generate code from JSON API spec - rake generate[wokplace||enterprise||app]'
-task :generate, [:files] do |_, params|
-  if params[:files].nil?
-    SPECS.each do |spec|
-      generate_specs(spec)
-    end
-  else
-    params[:files].split(' ').each do |arg|
-      unless SPECS.include?(arg.to_sym)
-        raise "Available parameters are #{SPECS.map(&:to_s).join(', ')}. No spec for #{arg}"
-      end
-
-      generate_specs(arg)
-    end
-  end
-end
-
-def generate_specs(name)
-  Elastic::Generator::EndpointGenerator.new(name.to_sym).generate
-end
+require 'bundler/gem_tasks'
 
 desc 'Open an irb session preloaded with this library'
 task :console do

data/docs/guide/app-search-api.asciidoc

@@ -0,0 +1,172 @@
+[[app-search-api]]
+== App Search API
+
+=== Engines
+
+[source,rb]
+----------------------------
+# Create an engine
+client.create_engine(name: 'videogames')
+
+# List all engines
+client.list_engines
+
+# Get an engine
+client.engine('videogames')
+
+# Delete an engine
+client.delete_engine('videogames')
+----------------------------
+
+=== Meta engines
+
+[source,rb]
+----------------------------
+# Create a meta engine:
+body = {
+  name: engine_name,
+  type: 'meta',
+  source_engines: [ 'books', 'videogames' ]
+}
+client.create_engine(name: engine_name, body: body)
+
+# Add a source engine to a meta engine:
+client.add_meta_engine_source(meta_engine_name, source_engines: ['engine1', 'engine2'])
+
+# Remove a source enginge from a meta engine:
+client.delete_meta_engine_source(meta_engine_name, source_engines: ['engine1', 'engine2'])
+----------------------------
+
+=== Documents
+
+[source,rb]
+----------------------------
+engine_name = 'videogames'
+document = {
+  id: 'Mr1064',
+  name: 'Super Luigi 64',
+  body: 'A classic 3D videogame'
+}
+
+# Index documents
+client.index_documents(engine_name, documents: document)
+
+# List documents
+client.list_documents(engine_name)
+
+# Get document(s) by ID:
+client.documents(engine_name, document_ids: [id1, id2])
+
+# Delete a document
+client.delete_documents(engine_name, document_ids: [document_id])
+
+# Update a document
+client.put_documents(engine_name, documents: [{id: document_id, key: value}])
+----------------------------
+
+=== Search
+
+[source,rb]
+----------------------------
+# Single Search
+query = {
+  query: 'luigi'
+}
+
+client.search(engine_name, query)
+
+# Multi query search
+queries = [{ query: 'Nicanor'}, { query: 'Iain' }]
+
+client.multi_search(engine_name, queries: queries)
+----------------------------
+
+=== Synonym Sets
+
+[source,rb]
+----------------------------
+# Create a synonym set
+client.create_synonym_set(engine_name, body: {['synonym1', 'synonym2']})
+
+# List synonym sets
+client.list_synonym_sets(engine_name)
+
+# Retrieve a synonym set by id
+client.synonym_set(engine_name, synonym_set_id: 'id')
+
+# Update a synonym set by id
+client.put_synonym_set(engine_name, synonym_set_id: 'id', body: {synonyms: ['synonym2', 'synonym3']})
+
+# Delete a synonym set
+client.delete_synonym_set(engine_name, synonym_set_id: id)
+----------------------------
+
+=== Curations
+
+[source,rb]
+----------------------------
+# Create a curation
+client.create_curation(
+         engine_name,
+         queries: ['query1'],
+         promoted: ['doc-id1'],
+         hidden: ['doc-id2']
+       )
+
+# Retrieve a curation by id:
+client.curation(engine_name, curation_id: 'cur-id')
+
+# Update an existing curation:
+client.put_curation(
+  engine_name,
+  curation_id: 'cur-id',
+  queries: ['query1'],
+  promoted: ['doc-id2'],
+  hidden: ['doc-id1']
+)
+
+# List existing curations:
+client.list_curations(engine_name)
+
+# Delete a curation:
+client.delete_curation(engine_name, curation_id: 'cur-id')
+----------------------------
+
+=== Other API Endpoints
+
+[source,rb]
+----------------------------
+# Count analytics - Returns the number of clicks and total number of queries over a period
+client.count_analytics(engine_name)
+
+# Schema - Retrieve current schema for the engine
+client.schema(engine_name)
+
+# Update schema for an engine
+client.put_schema(engine_name, schema: {field: 'type'})
+
+# Logs - The API Log displays API request and response data at the Engine level
+client.api_logs(engine_name, from_date: Date.new(2020, 10, 01), to_date: Date.new(2020, 11, 05))
+
+# Queries Analytics - Returns queries analytics by usage count
+client.top_queries_analytics(engine_name)
+
+# Clicks Analytics - Returns the number of clicks received by a document in descending order
+client.top_clicks_analytics(engine_name, query: {})
+
+# Search Settings - Returns current search settings for an engine
+client.search_settings(engine_name)
+
+# Update Search Settings
+client.put_search_settings(engine_name, body: body)
+
+# Reset search settings
+# Warning: This means your settings are wiped! Back them up!
+client.reset_search_settings(engine_name)
+
+# Click - Send data about clicked results
+client.log_clickthrough(engine_name, query_text: 'query', document_id: 'doc-id')
+
+# Query Suggestion - Provide relevant query suggestions for incomplete queries
+client.query_suggestion(engine_name, query: 'incomplete_query')
+----------------------------