HoundSleuth Hosted Search

This add-on is operated by HoundSleuth

Scalable full-text search built on BigTable. Index 15,000 documents for free!

HoundSleuth Hosted Search

Last Updated: 24 March 2014

The HoundSleuth Hosted Search add-on is currently in beta.

Table of Contents

HoundSleuth is an add-on that provides hosted full-text search.

HoundSleuth allows developers to easily add search to their applications, without having to deal with Solr or Lucene, and without the hassle of configuring and hosting your own search infrastructure. HoundSleuth is fast. Most search queries will be answered in under 100 milliseconds. HoundSleuth offers true real-time search, so documents added are immediately searchable. HoundSleuth is a drop-in replacement for existing IndexTank users.

HoundSleuth has client libraries for Ruby, Python, Java, and others, all of which communicate with HoundSleuth’s REST API.

HoundSleuth Dashboard

Installing the add-on

HoundSleuth can be installed using the following addons:add command, and replacing <PLAN> with the name of the HoundSleuth plan desired:

HoundSleuth offers plans based on the number of documents stored. A list of all plans available can be found on the HoundSleuth add-on page.

$ heroku addons:add HoundSleuth:<PLAN>
-----> Adding HoundSleuth:<PLAN> to mycoolapp... done

This will create an account on HoundSleuth associated with the Heroku user, with one empty index called “idx”. You may use this “idx” index or delete it and create a new one anytime.

Once HoundSleuth has been added, a HOUNDSLEUTH_URL setting will be available in the app configuration, and will contain the private API URL used to access the newly-provisioned HoundSleuth service from within your application.

$ heroku config | grep HOUNDSLEUTH_URL
HOUNDSLEUTH_URL    => http://:secret@xyz.api.houndsleuth.com

Local workstation setup

To test the service in a local development environment, retrieve the environment variables from heroku using the following command:

$ heroku config -s | grep HOUNDSLEUTH_URL >> .env
$ more .env

The HOUNDSLEUTH_URL is the private URL used to access the HoundSleuth service from within a local environment. Typically developers will create one search index for testing and one for production.

Credentials and other sensitive configuration values should not be committed to source-control. In Git exclude the .env file with: echo .env >> .gitignore.

The next step is to install the appropriate language client library to develop locally with HoundSleuth.

Using with Ruby/Rails

Ruby/Rails applications should add the following entry into their Gemfile specifying the IndexTank client library required to access HoundSleuth:

gem 'indextank'

For local development, install the indextank gem:

$ gem install indextank

Now the client can be used to add documents to your index and perform searches. The following code sample demonstrates basic document indexing and searching, and may be copied for use in apps you develop. Remember: <API_URL> must be replaced with the value of the HOUNDSLEUTH_URL value from the previous step, and <INDEX_NAME> with the name of an index (such as the “idx” index initially created):

require 'rubygems'
require 'indextank'

# Obtain an IndexTank client
client = IndexTank::Client.new(ENV['HOUNDSLEUTH_URL'] || '<API_URL>')
index = client.indexes('<INDEX_NAME>')

begin
    # Add documents to the index
    index.document("1").add({ :text => "some text here" })
    index.document("2").add({ :text => "some other text" })
    index.document("3").add({ :text => "something else here" })

    # Search the index
    results = index.search("some")

    print "#{results['matches']} documents found\\n"
    results['results'].each { |doc|
      print "docid: #{doc['docid']}\\n"
    }
rescue
    print "Error: ",$!,"\\n"
end

Using with Python

Python applications should add the following entry into their requirements.txt specifying the IndexTank client library required to access HoundSleuth:

anyjson==0.3.1
indextank==1.0.6

For local development, install the indextank client library for HoundSleuth:

$ pip install indextank

If you are using Virtualenv like in the Python tutorial here, you can simple use pip to install into your Virtualenv then do the typical:

$ pip freeze > requirements.txt

Now the client can be used to add documents to your index and perform searches. The following code sample demonstrates basic document indexing and searching, and may be copied for use in apps you develop. Remember: <API_URL> must be replaced with the value of the HOUNDSLEUTH_URL value from the previous step, and <INDEX_NAME> with the name of an index (such as the “idx” index initially created):

import os
from indextank.client import ApiClient

# Obtain an IndexTank client
client = ApiClient(os.environ.get('HOUNDSLEUTH_URL', '<API_URL>')
index = api.get_index('<INDEX_NAME>')

try:
    index.add_document('1', { 'text': 'Blah blah blah', 'author':'Joe' })

    result = index.search('blah')
    for item in results['results']:
        print item['docid']
except Exception, e:
    print "Error adding documents: %s" % e

Using with other languages

HoundSleuth supports any language via our REST api:

[http://www.houndsleuth.com/docs/](http://www.houndsleuth.com/docs/)

There are client libraries available for:

Testing your application

Using the code pattern above, you should be able to test applications both locally and running on Heroku. Keep in mind that your tests affect the live index. An index may be deleted and re-created anytime to clean it up, either from code as shown below or from HoundSleuth’s dashboard:

Deleting an index (Ruby)

client = IndexTank::Client.new(ENV['HOUNDSLEUTH_URL'] || '<API_URL>')
index = client.indexes('<INDEX_NAME>')
index.delete()

Creating a new index

client = IndexTank::Client.new(ENV['HOUNDSLEUTH_URL'] || '<API_URL>')
index = client.indexes('<INDEX_NAME>')
index.add()

print "Waiting for index to be ready"
while not index.running?
    print "."
    STDOUT.flush
    sleep 0.5
end
print "\\n"
STDOUT.flush

Migrating between plans

If you require a plan larger than those listed, we can provide custom plans. Please contact us at support@houndsleuth.com.

If you outgrow the limits of your current HoundSleuth plan, it’s easy to change to a larger plan. Any data in your search indexes is preserved – no data is lost.

Use the CLI to migrate to a new plan.

$ heroku addons:upgrade HoundSleuth:Starter
-----> Upgrading HoundSleuth:plus to myapp... done ($49/mo)
       Your plan has been updated to: HoundSleuth:Starter

Dashboard

The HoundSleuth dashboard allows you to manage indexes, allowing you to create, delete, and search indexes. Custom scoring functions can also be configured. The dashboard can be accessed by visiting the Heroku apps web interface and selecting HoundSleuth from the add-ons menu.

HoundSleuth Add-ons Dropdown

HoundSleuth Dashboard

Further reading

For more information on the features available from HoundSleuth, including faceting, geolocation, snippets, autocomplete, and custom scoring functions, please see the documentation at www.houndsleuth.com/docs/.