⚠️ This client is deprecated ⚠️
As of Enterprise Search version 7.10.0, we are directing users to the new Enterprise Search Ruby Client and deprecating this client.
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 be limited to bug fixes. All future enhancements will be focused on the Enterprise Search Ruby Client.
Thank you! - Elastic
A first-party Ruby client for building excellent, relevant search experiences with Elastic App Search.
To install the gem, execute:
gem install elastic-app-search
Or place gem 'elastic-app-search', '~> 7.10.0' in your Gemfile and run bundle install.
This client is versioned and released alongside App Search.
To guarantee compatibility, use the most recent version of this library within the major version of the corresponding App Search implementation.
For example, for App Search 7.3, use 7.3 of this library or above, but not 8.0.
If you are using the SaaS version available on swiftype.com of App Search, you should use the version 7.5.x of the client.
Using this client assumes that you have already an instance of Elastic App Search up and running.
Once done, a client can be instantiated using the [API_KEY] and the [API_ENDPOINT] URL of your App Search setup:
require 'elastic-app-search'
client = Elastic::AppSearch::Client.new(:api_key => 'private-xxxxxxxxxxxxxxxxxxx', :api_endpoint => 'http://localhost:3002/api/as/v1/')
Note:
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.
When using the SaaS version available on swiftype.com 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 menu.
require 'elastic-app-search'
client = Elastic::AppSearch::Client.new(:host_identifier => 'host-c5s2mj', :api_key => 'private-xxxxxxxxxxxxxxxxxxx')
This client is a thin interface to the Elastic App Search Api. Additional details for requests and responses can be found in the documentation.
engine_name = 'favorite-videos'
document = {
:id => 'INscMGmhmX4',
:url => 'https://www.youtube.com/watch?v=INscMGmhmX4',
:title => 'The Original Grumpy Cat',
:body => 'A wonderful video of a magnificent cat.'
}
client.index_document(engine_name, document)
engine_name = 'favorite-videos'
documents = [
{
:id => 'INscMGmhmX4',
:url => 'https://www.youtube.com/watch?v=INscMGmhmX4',
:title => 'The Original Grumpy Cat',
:body => 'A wonderful video of a magnificent cat.'
},
{
:id => 'JNDFojsd02',
:url => 'https://www.youtube.com/watch?v=dQw4w9WgXcQ',
:title => 'Another Grumpy Cat',
:body => 'A great video of another cool cat.'
}
]
client.index_documents(engine_name, documents)
engine_name = 'favorite-videos'
documents = [
{
:id => 'INscMGmhmX4',
:title => 'Updated title'
}
]
client.update_documents(engine_name, documents)
engine_name = 'favorite-videos'
document_ids = ['INscMGmhmX4', 'JNDFojsd02']
client.get_documents(engine_name, document_ids)
engine_name = 'favorite-videos'
client.list_documents(engine_name)
engine_name = 'favorite-videos'
document_ids = ['INscMGmhmX4', 'JNDFojsd02']
client.destroy_documents(engine_name, document_ids)
client.list_engines
engine_name = 'favorite-videos'
client.get_engine(engine_name)
engine_name = 'favorite-videos'
client.create_engine(engine_name)
engine_name = 'favorite-videos'
client.destroy_engine(engine_name)
engine_name = 'videos-engine'
sources_engines = ['favorite-videos', 'all-videos']
client.create_meta_engine(engine_name, source_engines)
engine_name = 'videos-engine'
sources_engines = ['fun-videos', 'cat-videos']
client.add_meta_engine_sources(engine_name, source_engines)
engine_name = 'videos-engine'
sources_engines = ['nsfw-videos']
client.delete_meta_engine_sources(engine_name, source_engines)
engine_name = 'favorite-videos'
query = 'cat'
search_fields = { :title => {} }
result_fields = { :title => { :raw => {} } }
options = { :search_fields => search_fields, :result_fields => result_fields }
client.search(engine_name, query, options)
engine_name = 'favorite-videos'
queries = [{
:query => 'cat',
:options => { :search_fields => { :title => {} }}
},{
:query => 'dog',
:options => { :search_fields => { :body => {} }}
}]
client.multi_search(engine_name, queries)
engine_name = 'favorite-videos'
options = {
:size => 3,
:types => {
:documents => {
:fields => ['title']
}
}
}
client.query_suggestion(engine_name, 'cat', options)
engine_name = 'favorite-videos'
client.show_settings(engine_name)
engine_name = 'favorite-videos'
settings = {
'search_fields' => {
'id' => {
'weight' => 1
},
'url' => {
'weight' => 1
},
'title' => {
'weight' => 1
},
'body' => {
'weight' => 1
},
},
'boosts' => {
'title' => [
{
'type' => 'value',
'factor' => 9.5,
'operation' => 'multiply',
'value' => [
'Titanic'
]
}
]
}
}
client.update_settings(engine_name, settings)
engine_name = 'favorite-videos'
client.reset_settings(engine_name)
Creating a search key that will only return the title field.
public_search_key = 'search-xxxxxxxxxxxxxxxxxxxxxxxx'
# This name must match the name of the key above from your App Search dashboard
public_search_key_name = 'search-key'
enforced_options = {
result_fields: { title: { raw: {} } },
filters: { world_heritage_site: 'true' }
}
signed_search_key = Elastic::AppSearch::Client.create_signed_search_key(public_search_key, public_search_key_name, enforced_options)
client = Elastic::AppSearch::Client.new(:api_key => signed_search_key, :api_endpoint => 'http://localhost:3002/api/as/v1/')
client.search('national-parks-demo', 'everglade')
Logging a click through
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)
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)
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)
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)
engine_name = 'us-national-parks'
client.create_synonym_set(engine_name, :synonyms => ['park', 'trail'])
engine_name = 'us-national-parks'
client.get_synonym_set(engine_name, 'syn-5d8e6b5d40caae7dcb6e1b9c')
engine_name = 'us-national-parks'
client.list_synonym_sets(engine_name, :current => 1, :size => 20)
engine_name = 'us-national-parks'
client.update_synonym_set(engine_name, 'syn-5d8e6b5d40caae7dcb6e1b9c', :synonyms => ['park', 'trail', 'ground'])
engine_name = 'us-national-parks'
client.destroy_synonym_set(engine_name, 'syn-5d8e6b5d40caae7dcb6e1b9c')
client.list_credentials(:current => 1, :size => 20)
client.get_credential('reading-private-key')
client.create_credential({
:name => 'reading-private-key',
:type => 'private',
:read => true,
:write => false,
:access_all_engines => false,
:engines => [
'favorite-videos'
]
})
client.update_credential('reading-private-key', {
:name => 'reading-private-key',
:type => 'private',
:read => true,
:write => true,
:access_all_engines => false,
:engines => [
'favorite-videos'
]
})
client.destroy_credential('reading-private-key')
engine_name = 'us-national-parks'
client.get_schema(engine_name)
engine_name = 'us-national-parks'
client.update_schema(engine_name, 'square_km' => 'number')
engine_name = 'us-national-parks'
options = {
'queries' => [
'zion'
],
'promoted' => [
'doc-5d8e413b40caaedab76e3c96'
],
'hidden' => [
'doc-5d8e413d40caae335e06c374'
]
}
client.create_curation(engine_name, options)
engine_name = 'us-national-parks'
client.get_curation(engine_name, 'cur-5d9240d640caaeca6506b600')
engine_name = 'us-national-parks'
client.list_curations(engine_name, current: 1, size: 20)
engine_name = 'us-national-parks'
id = 'cur-5d9240d640caaeca6506b600'
options = {
'queries' => [
'zion'
],
'promoted' => [
'doc-5d8e413b40caaedab76e3c96'
]
}
client.update_curation(engine_name, id, options)
engine_name = 'us-national-parks'
client.destroy_curation(engine_name, 'cur-5d9240d640caaeca6506b600')
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)
export AS_API_KEY="[API_KEY]"
export AS_ADMIN_KEY="[ADMIN_API_KEY]"
export AS_HOST_IDENTIFIER="[HOST_IDENTIFIER]"
bundle exec rspec
You can also run tests against a local environment by passing a AS_API_ENDPOINT environment variable
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
If you need to debug an API call made by the client, there are a few things you could do:
Setting AS_DEBUG environment variable to true would enable HTTP-level debugging and you would
see all requests generated by the client on your console.
You could use our API logs feature in App Search console to see your requests and responses live.
In your debug logs you could find a X-Request-Id header value. That could be used when talking
to Elastic Customer Support to help us quickly find your API request and help you troubleshoot
your issues.
If something is not working as expected, please open an issue.
Your best bet is to read the documentation.
You can checkout the Elastic App Search community discuss forums.
We welcome contributors to the project. Before you begin, a couple notes...
Thank you to all the contributors!
FAQs
Unknown package
We found that elastic-app-search demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Fluent Assertions is facing backlash after dropping the Apache license for a commercial model, leaving users blindsided and questioning contributor rights.
Research
Security News
Socket researchers uncover the risks of a malicious Python package targeting Discord developers.
Security News
The UK is proposing a bold ban on ransomware payments by public entities to disrupt cybercrime, protect critical services, and lead global cybersecurity efforts.