swiftype-app-search

⚠️ This repository is deprecated ⚠️

Please visit https://github.com/elastic/app-search-ruby for the up to date version. Thank you! - Elastic

A first-party Ruby client for building excellent, relevant search experiences with Elastic App Search.

Contents

• Getting started
• Usage
• Running Tests
• Debugging API Calls
• FAQ
• Contribute
• License

Getting started 🐣

To install the gem, execute:

gem install swiftype-app-search

Or place gem 'swiftype-app-search', '~> 0.6.1' in your Gemfile and run bundle install.

Usage

Setup: Configuring the client and authentication

Create a new instance of the Swiftype App Search Client. This requires your [HOST_IDENTIFIER], which identifies the unique hostname of the Swiftype API that is associated with your Swiftype 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.

You can find your [API_KEY] and your [HOST_IDENTIFIER] within the Credentials menu:

client = SwiftypeAppSearch::Client.new(:host_identifier => 'host-c5s2mj', :api_key => 'private-mu75psc5egt9ppzuycnc2mc3')

Using with App Search Managed Deploys

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.

client = SwiftypeAppSearch::Client.new(:api_key => 'private-mu75psc5egt9ppzuycnc2mc3', :api_endpoint => 'http://localhost:3002/api/as/v1/')

API Methods

This client is a thin interface to the Swiftype App Search Api. Additional details for requests and responses can be found in the documentation.

Indexing: Creating or Updating a Single Document

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)

Indexing: Creating or Replacing Documents

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)

Indexing: Updating Documents (Partial Updates)

engine_name = 'favorite-videos'
documents = [
  {
    :id => 'INscMGmhmX4',
    :title => 'Updated title'
  }
]

client.update_documents(engine_name, documents)

Retrieving Documents

engine_name = 'favorite-videos'
document_ids = ['INscMGmhmX4', 'JNDFojsd02']

client.get_documents(engine_name, document_ids)

Listing Documents

engine_name = 'favorite-videos'

client.list_documents(engine_name)

Destroying Documents

engine_name = 'favorite-videos'
document_ids = ['INscMGmhmX4', 'JNDFojsd02']

client.destroy_documents(engine_name, document_ids)

Listing Engines

client.list_engines

Retrieving Engines

engine_name = 'favorite-videos'

client.get_engine(engine_name)

Creating Engines

engine_name = 'favorite-videos'

client.create_engine(engine_name)

Destroying Engines

engine_name = 'favorite-videos'

client.destroy_engine(engine_name)

Searching

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)

Multi-Search

engine_name = 'favorite-videos'

queries = [{
  :query => 'cat',
  :options => { :search_fields => { :title => {} }}
},{
  :query => 'dog',
  :options => { :search_fields => { :body => {} }}
}]

client.multi_search(engine_name, queries)

Query Suggestion

engine_name = 'favorite-videos'

options = {
  :size => 3,
  :types => {
    :documents => {
      :fields => ['title']
    }
  }
}

client.query_suggestion(engine_name, 'cat', options)

Show Search Settings

engine_name = 'favorite-videos'

client.show_settings(engine_name)

Update Search Settings

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)

Reset Search Settings

engine_name = 'favorite-videos'

client.reset_settings(engine_name)

Running Tests

export AS_API_KEY="[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_API_ENDPOINT="http://[HOST_IDENTIFIER].api.127.0.0.1.ip.es.io:3002/api/as/v1"
bundle exec rspec

Debugging API calls

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 Swiftype Customer Support to help us quickly find your API request and help you troubleshoot your issues.

FAQ 🔮

Where do I report issues with the client?

If something is not working as expected, please open an issue.

Where can I learn more about App Search?

Your best bet is to read the documentation.

Where else can I go to get help?

You can checkout the Elastic App Search community discuss forums.

Contribute 🚀

We welcome contributors to the project. Before you begin, a couple notes...

• Before opening a pull request, please create an issue to discuss the scope of your proposal.
• Please write simple code and concise documentation, when appropriate.

License 📗

MIT © Elastic

Thank you to all the contributors!