A sortable and searchable list backed by Redis
Ruby
Switch branches/tags
Nothing to show
Latest commit 347da07 Dec 4, 2014 @saturnine saturnine updated readme 0.5.0

README.md

acts_as_hashish Build Status Coverage Status

A sortable and searchable list backed by Redis. You can use it as a quick actionable workflow queue which you can search/sort and paginate through

How do I install it?

gem install acts_as_hashish

or in your Gemfile

gem 'acts_as_hashish'

Make sure your redis server is running! Redis configuration is outside the scope of this README, but check out the Redis documentation.

How do I configure?

Hashish.configure do |configuration|
  configuration.redis_connection = Redis.new(:host => '127.0.0.1')
  configuration.redis_namespace = 'my_hashish'
end

How do I use it?

Use acts_as_hashish:

require 'acts_as_hashish'

# configure hashish first
Hashish.configure do |configuration|
  configuration.redis_connection = Redis.new(:host => '127.0.0.1')
  configuration.redis_namespace = 'my_hashish'
  configuration.redis_search_keys_ttl = 5 
end

# convert any class into a hashish 
# it is important to specify which key in the hash is your primary key
# special characters will not be allowed as key while inserting data
class MyList
  acts_as_hashish(:key => 'id')
end

# you can specify any number of indexes and define how the index is created using a proc
# or simply point it to the key of the hash that is to be used for creating the index
class MyList
  acts_as_hashish(:key => 'id', 
                  :indexes => {'name' => Proc.new{|x| x['name'].split(' ')},
                               'city' => 'location',
                               'salary' => 'salary'},
                  :sorters => {'join_date' => 'doj'})

end

# insert items into the list, keys must be strings, values can be integer or string
MyList.hashish_insert('id' => 1, 'name' => 'John Doe', 'doj' => Time.mktime(1999, 'feb', 22).to_i, 'salary' => 100, 'location' => 'Mumbai')
MyList.hashish_insert('id' => 2, 'name' => 'John Loe', 'doj' => Time.mktime(1986, 'apr', 15).to_i, 'salary' => 1500, 'location' => 'Goa')
MyList.hashish_insert('id' => 3, 'name' => 'John Foe', 'doj' => Time.mktime(1992, 'dec', 30).to_i, 'salary' => 500, 'location' => 'Lisbon')
MyList.hashish_insert('id' => 4, 'name' => 'John Joe', 'doj' => Time.mktime(1983, 'nov', 23).to_i, 'salary' => 2500, 'location' => 'Birmingham')
MyList.hashish_insert('id' => 5, 'name' => 'John Yoe', 'doj' => Time.mktime(1983, 'sep', 21).to_i, 'salary' => 3500, 'location' => 'London')

Get items from the list

# get the last 10 items (default sorting is based on insert time)
MyList.hashish_list

# use basic pagination
MyList.hashish_list(:page_size => 3, :page_no => 2)

# get the entire list without pagination (use this with caution if you have too much data)
MyList.hashish_list(:page_size => 0)

Using filters

# use filters to search on indexed fields
MyList.hashish_list(:filters => {'city' => 'London'})

# use multiple filters (AND)
MyList.hashish_list(:filters => {'name' => 'John', 'city' => 'Mumbai'})

# use filters with multiple values (OR)
MyList.hashish_list(:filters => {'name' => ['Loe', 'Foe']})

# salary within a range of 2000 to 4000
MyList.hashish_list(:filters => {'salary' => (2000..4000).to_a})

Sorting (applies before pagination)

# use your custom defined sorter  (default is ascending order)
MyList.hashish_list(:sort_by => 'join_date')

# use descending order
MyList.hashish_list(:sort_order => 'DESC')

A complete example

MyList.hashish_list(:filters => {'name' => 'John', 'salary' => (0..2000).to_a},
                    :sort_by => 'join_date', :sort_order => 'DESC',
                    :page_size => 3, :page_no => 1)

Delete items

# delete using the primary key
MyList.hashish_delete(1)

Method Summary

# make a class act_as_hashish
acts_as_hashish(options = {})

# insert an item or items (array) into the list
hashish_insert(data, insert_time = Time.now.to_i)

# delete an item from the list
hashish_delete(primary_key)

# returns the length of the list
hashish_length

# flush/delete the entire list
hashish_flush!

# rebuild and re-index the entire list with existing data or data provided
# the data will be flushed from redis and initialized with the same data or
# the data that is passed to this method (array of hash)
hashish_rebuild(data = nil)

# returns the list, based on filters, sorting and pagination in the options hash
hashish_list(options = {})

Changelog

0.5.0

  • fixed a bug hashish_delete related to removing indexes/sorters
  • new method "hashish_length" which was obviously required

0.4.4

  • fixed a performance issue with hashish_delete
  • new method "hashish_find" which was obviously required

0.4.3

  • minor bugfixes
  • dependency version adjustments

0.4.1

  • first stable release

TODO

  • block for dequeue which is run only if item is dequeued
  • support full text indexes
  • support fuzzy indexes
  • expiry on individual items in list
  • support pub/sub architecture for automatic worker

Copyright

Copyright (c) 2012-2013 Schubert Cardozo. See LICENSE for further details.