= chimera

* http://github.com/benmyles/chimera

== DESCRIPTION:

Chimera is an object mapper for Riak and Redis. The idea is to mix the advantages of Riak
(scalability, massive data storage) with Redis (atomicity, performance, data structures).
You should store the bulk of your data in Riak, and then use Redis data structures where
appropriate (for example, a counter or set of keys).

Internally, Chimera uses Redis for any indexes you define as well as some default indexes
that are automatically created. There's no built in sharding for Redis, but since it's
only being used for key storage and basic data elements you should be able to go a long
way with one Redis server (especially if you use the new Redis VM).

!! Chimera is alpha. It's not production tested and needs a better test suite. !!
!! It's also only tested in Ruby 1.9. !!

== FEATURES:

* Uses Riak (http://riak.basho.com/) for your primary storage.
* Uses Redis for indexes and also allows you to define Redis objects on a model.
* Supports unique and non-unique indexes, as well as basic search indexes (words are stemmed,
  uses set intersection so you can get an AND/OR search).
* Supports a geospatial index type for simple storage and lookup of coordinates.
* Uses Typhoeus for communicating with Riak.
* Surfaces siblings from Riak so that conflicts can be managed and resolved.

== ISSUES/NOTES:

* Experimental. Not yet tested in production environment, use at your own risk.
* Only tested with Ruby 1.9. Why not upgrade?
* Test coverage needs to be improved.
* Documentation is lacking. At the moment reading the tests and sample test/models.rb
  file are your best bet.

== SYNOPSIS:

  require "rubygems"
  require "chimera"

  Chimera.config_path = "path/to/your/config.yml"

  class Car < Chimera::Base
    attribute :vin
    attribute :make
    attribute :model
    attribute :year
    attribute :description

    index :year, :type => :find
    index :description, :type => :search
    index :vin, :type => :unique

    validates_presence_of :vin, :make, :model, :year
  end

  c = Car.new
  c.id = Car.new_uuid
  c.vin = 12345
  c.make = "Pagani"
  c.model = "Zonda Cinque Roadster"
  c.year = 2010
  c.description = "The Roadster will have specs as the Cinque Coupé, and will likely maintain the same rigidity or more, as it was for the Roadster F and F Coupé."
  c.save

  Car.find_with_index(:year, 2010)
  => [c]

  Car.find_with_index(:description, :q => "rigid boat", :type => :union)
  => [c]

  Car.find_with_index(:description, :q => "rigid boat", :type => :intersect)
  => []

* See tests for more usage examples

== REQUIREMENTS:

* Riak Server
* Redis Server

* Ruby 1.9

* ActiveSupport+ActiveModel 3.0.0.beta

* uuidtools 2.1.1
* yajl-ruby 0.7.4
* fast-stemmer 1.0.0

== INSTALL:

  $ gem install tzinfo builder memcache-client rack rack-test rack-mount erubis mail text-format thor bundler i18n
  $ gem install rails --pre
  $ gem install chimera
  
== USEFUL LINKS:

* Discussion: http://groups.google.com/group/chimera-lib
* Email: ben dot myles at gmail dot com
* Twitter: benmyles

== LICENSE:

(The MIT License)

Copyright (c) 2010 Ben Myles

Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the
'Software'), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:

The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.