elastic-enterprise-search 0.3.0 → 7.13.0.pre

data/Rakefile

@@ -1 +1,48 @@
-require "bundler/gem_tasks"
+# Licensed to Elasticsearch B.V. under one or more contributor
+# license agreements. See the NOTICE file distributed with
+# this work for additional information regarding copyright
+# ownership. Elasticsearch B.V. licenses this file to you under
+# the Apache License, Version 2.0 (the "License"); you may
+# not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+# frozen_string_literal: true
+
+require 'rspec/core/rake_task'
+require 'bundler/gem_tasks'
+
+desc 'Open an irb session preloaded with this library'
+task :console do
+  sh 'irb -r rubygems -I lib -r elastic-enterprise-search.rb'
+end
+
+desc 'Run Elastic Enterprise Search stack'
+task :stack, [:version] do |_, params|
+  sh "STACK_VERSION=#{params[:version]} ./.ci/run-local.sh"
+end
+
+namespace :spec do
+  desc 'Run client tests'
+  task :client do
+    sh 'rspec spec/enterprise-search spec/workplace-search spec/app-search'
+  end
+
+  desc 'Run integration tests'
+  task :integration do
+    sh 'rspec spec/integration'
+  end
+
+  desc 'Run all tests'
+  task :all do
+    sh 'rspec spec'
+  end
+end

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

@@ -0,0 +1,186 @@
+[[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)
+
+# Search with multiple filters
+client.search('parks', {
+  body: {
+    query: "olympic",
+    filters: {
+      all: [
+        { states: "Washington" },
+        { world_heritage_site: "true" }
+      ]
+    }
+  }
+})
+
+# Multi query search
+queries = [{ query: 'Nicanor'}, { query: 'Iain' }]
+
+client.multi_search(engine_name, body: 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')
+----------------------------

data/docs/guide/connecting.asciidoc

@@ -0,0 +1,171 @@
+[[connecting]]
+== Connecting
+
+
+This page contains the information you need to connect and use the Client with Elastic Enterprise Search.
+
+**On this page**
+
+* <<authentication>>
+* <<custom_headers>>
+
+
+[discrete]
+[[authentication]]
+=== Authentication
+
+
+This section contains code snippets to show you how to connect to Enterprise Search, App Search, and Workplace Search.
+
+Each service has its own authentication schemes. Using the `http_auth` property with either a string for a key / token or a tuple of `(username, password)` for basic authentication will set the proper `Authorization` HTTP header on the client instance.
+
+[discrete]
+[[auth-ent]]
+==== Authenticating with Enterprise Search
+
+Enterprise Search supports HTTP basic authentication with a username and password.
+
+HTTP basic authentication uses the `http_auth` parameter by passing in a username and password as a tuple:
+
+[source,rb]
+----------------------------
+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)
+----------------------------
+
+
+[discrete]
+[[auth-as]]
+==== Authenticating with App Search
+
+In your Elastic App Search dashboard, navigate to Credentials and Create a Key for the client to use. Make sure to read https://www.elastic.co/guide/en/app-search/current/authentication.html[the documentation on Authentication] 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.
+
+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.
+
+[source,rb]
+----------------------------
+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)
+----------------------------
+
+[discrete]
+[[signed-search-key]]
+===== Signed search key
+
+App Search also supports https://www.elastic.co/guide/en/app-search/current/authentication.html#authentication-signed[authenticating with signed search keys]. Here's an example on how to use it:
+
+[source,rb]
+----------------------------
+public_search_key = 'search-key-value'
+# This name must match the name of the key above from your App Search dashboard
+public_search_key_name = 'search-key'
+
+# Say we have documents with a title and an author. We want this key to be able
+#  to search by title, but only return the author:
+options = {
+  search_fields: { title: {} },
+  result_fields: { author: { raw: {} } }
+}
+
+signed_search_key = Elastic::EnterpriseSearch::AppSearch::Client.create_signed_search_key(public_search_key, public_search_key_name, options)
+
+client = Elastic::EnterpriseSearch::AppSearch::Client.new(http_auth: signed_search_key)
+
+client.search(engine_name, query: 'jungle')
+----------------------------
+
+[discrete]
+[[auth-ws]]
+==== Authenticating with Workplace Search
+
+Workplace Search supports multiple authentication methods:
+
+[discrete]
+[[access-tokens]]
+===== Workplace Search admin user access tokens
+
+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 an `ID`.
+
+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:
+
+[source,rb]
+----------------------------
+host = 'https://id.ent-search.europe-west2.gcp.elastic-cloud.com'
+access_token = '<access token>'
+content_source_id = '<content source id>'
+
+# 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_id, body: documents)
+
+# On its own
+workplace_search_client = Elastic::EnterpriseSearch::WorkplaceSearch::Client.new(
+  host: host,
+  http_auth: access_token
+)
+----------------------------
+
+[discrete]
+[[basic-auth]]
+===== Basic Authentication
+
+Workplace Search APIs support basic authentication headers to authenticate users. All Workplace Search APIs support basic authentication:
+
+[source,rb]
+----------------------------
+host = 'https://id.ent-search.europe-west2.gcp.elastic-cloud.com'
+basic_auth = { user: 'enterprise_search', password: 'changeme' }
+
+workplace_search_client = Elastic::EnterpriseSearch::WorkplaceSearch::Client.new(
+  host: host,
+  http_auth: basic_auth
+)
+----------------------------
+
+[discrete]
+[[es-tokens]]
+===== Elasticsearch tokens
+
+Workplace Search APIs support Elasticsearch tokens generated by the Elasticsearch Token Service. All Workplace Search APIs support Elasticsearch tokens as an authentication method.
+
+[source,rb]
+----------------------------
+host = 'https://id.ent-search.europe-west2.gcp.elastic-cloud.com'
+access_token = '<access token>'
+
+workplace_search_client = Elastic::EnterpriseSearch::WorkplaceSearch::Client.new(
+  host: host,
+  http_auth: access_token
+)
+----------------------------
+
+[discrete]
+[[ws-oauth]]
+===== Workplace Search OAuth access tokens
+
+The Search API and the Analytics Events API support user access tokens generated by the Workplace Search OAuth Service. The token is acquired via an OAuth authorization flow. User access tokens are meant to be used for Custom Search Experiences. Check <<ws-oauth-authentication>>.
+
+[discrete]
+[[custom_headers]]
+=== Custom HTTP Headers
+
+You can pass in headers as a parameter to any of the API Endpoints to set custom headers for the request:
+
+[source,rb]
+----------------------------
+headers = { 'x-custom-header' => 'Header value' }
+workplace_search_client.index_documents(
+  content_source_id,
+  { body: documents, headers: headers }
+)
+----------------------------

data/docs/guide/development.asciidoc

@@ -0,0 +1,42 @@
+[[development]]
+== Development
+
+[discrete]
+=== Run Stack locally
+
+A rake task is included to run the Elastic Enterprise Search stack locally via Docker:
+
+[source,bash]
+----------------------------
+$ rake stack[7.10.0]
+----------------------------
+
+This will run Elastic Enterprise Search in http://localhost:3002
+- Username: `enterprise_search`
+- Password: `changeme`
+
+[discrete]
+=== Run Tests
+
+Unit tests for the clients:
+
+[source,bash]
+----------------------------
+$ 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:
+
+[source,bash]
+----------------------------
+$ ELASTIC_ENTERPRISE_HOST='http://localhost:3002' \
+  ELASTIC_ENTERPRISE_USER='elastic' \
+  ELASTIC_ENTERPRISE_PASSWORD='changeme' \
+  rake spec:integration
+----------------------------
+
+Run integration tests completely within containers, the way we run them on our CI:
+[source,bash]
+----------------------------
+RUNSCRIPTS=enterprise-search STACK_VERSION=7.10.0 ./.ci/run-tests
+----------------------------