I’ve been playing a lot with CouchDB lately and if you’re on OS X there’s really no easier way to do so than by using CouchDBX, a self-contained application that includes CouchDB, Erlang, and all of the dependencies you need to run Couch.
However, recently I wanted to try the power and functionality of couchdb-lucene for full-text indexing of a CouchDB application on which I was working. It wasn’t immediately obvious to me how to make that happen, so I thought I’d share how I got it working for those who might want to do the same. For the record, I am using the following versions of things:
- Mac OS X 10.6 (Snow Leopard)
- CouchDBX 0.9.1 R13B pl2
- CouchDB Lucene v0.4
Unpacking CouchDB Lucene
You will need to place CouchDB Lucene in a convenient location, but first you’ll need to unpack the gZip file. Note that, at least for me, the default Mac unarchiver did not provide a suitable .jar file. Instead, extract it using the following command:
unpack200 couchdb-lucene-0.4-jar-with-dependencies.jar.gz couchdb-lucene-0.4-jar-with-dependencies.jar
It doesn’t particularly matter where you put it (I put mine in /usr/local/etc) so long as you remember the location.
Editing the CouchDBX .ini File
Next you will need to edit the CouchDBX local.ini file to add the external for full-text indexing. To access the file, right-click CouchDBX and select “Show Package Contents” then navigate to Contents/Resources/couchdbx-core/couchdb/etc/couchdb/local.ini and open it up in your favorite text editor. You will need to add the following lines to this file, taking note to change the directory to match where you stored your Lucene .jar file.
[couchdb] os_process_timeout=60000 ; increase the timeout from 5 seconds. [external] fti=/usr/bin/java -server -Xmx1g -jar /path/to/couchdb-lucene-0.4-jar-with-dependencies.jar -search [update_notification] indexer=/usr/bin/java -server -Xmx1g -jar /path/to/couchdb-lucene-0.4-jar-with-dependencies.jar -index [httpd_db_handlers] _fti = {couch_httpd_external, handle_external_req, <<"fti">>}
All right, that’s all the setup you need to be running CouchDB Lucene! Now you can start up CouchDBX and set up your first search indexes.
Creating a Full-Text Index View
To create a full-text index view, you simply need to add a “fulltext” field to one of your design documents. The URL structure for accessing CouchDB Lucene searches is as follows:
http://localhost:5984/database_name/_fti/design_doc_name/index_name?q=your+query+here
Where database_name is any database you have on your system, design_doc_name is any design document in your database, and index_name is a fulltext index you defined. For instance, if I had a CouchRest generated design doc for a bunch of music, I might have a design document that looks something like this:
{ "_id":"_design/Song", "_rev":"af12a4b12af1b24afbf244f1", "fulltext":{ "my_search":{ "index":"function(doc) { if (!doc['couchrest-type'] == 'Song') return null; var ret = new Document(); ret.add(doc.title); ret.add(doc.artist); return ret; }" } } }
I would then be able to access the search results with this URL:
http://localhost:5984/myapp/_fti/Song/my_search?q=Ben+Folds
Awesome! We now have full-text indexing up and running on CouchDBX!
Bonus: CouchRest Lucene
I use CouchRest extensively in my Ruby CouchDB projects, and I wanted to be able to integrate the new Lucene searches easily. I found this post that added a bit of functionality, but I wanted to be able to integrate with ExtendedDocument (and the snippet was also slightly outdated), so I’ve updated it. Just add this sometime after you include CouchRest:
class CouchRest::Database def search(design, index, query, options={}) CouchRest.get CouchRest.paramify_url("#{@root}/_fti/#{design}/#{index}", options.merge(:q => query)) end end class CouchRest::ExtendedDocument def self.search(index, query, options={}) options[:include_docs] = true ret = self.database.search(self.to_s, index, query, options) ret['rows'].collect!{|r| self.new(r['doc'])} ret end end
What this snippet does is allows you to perform searches on a database directly or by calling a search method on an extended document. Let’s look at a couple examples to see how it would work:
@db = CouchRest.database!("http://localhost:5984/myapp") @db.search('Song','my_search', 'Ben Folds', :include_docs => true) # The following is equivalent to the above, but will automatically # include the docs and cast the result rows into ExtendedDocuments Song.search('my_search', 'Ben Folds')
Now that we have this set up, we’re ready to go forth and build full-text search into our CouchDB apps. I hope this is helpful to some who have become somewhat familiar with CouchDB but are looking to push it a little further and try out some of the more advanced usages of CouchDB in their applications.
