= DoesKeyValue

Bring the fun of NoSQL into your SQL-backed Active Record objects in a compartmentalized way. Turns 
any text field on your objects into a schema-less key value store.


== Installation

Do the usual, of course:

  gem install doeskeyvalue

And add a gem dependency to your Gemfile:

  gem "doeskeyvalue", ">=0.1.0"


== Example 

Quick and simple. First, add the declaration to your ActiveRecord model:

  doeskeyvalue :settings
  
In this invocation, "settings" is the name of TEXT or BLOB field on your model's database table. Think
of it as something you'd typically serialize, but would prefer solid accessor and finding behavior on.

To add keys to your document, using the name of the field you provided, before (in this case 
"settings"), add keys individually like so:

  settings_key :uid
  settings_key :email
  settings_key :name
  
This adds a uid, email, and name field to your record. You can use these fields just like regular 
columns on your ActiveRecord object, but they're happily stored within your TEXT/BLOB column at the
database level. Check it out:

  mod = Model.new
  
  mod.uid = "mccolin"
  => "mccolin"
  
  mod.uid
  => "mccolin"
  
You can see the serialized key-value structure at any time, as well. Just access your old filed:

  mod.settings
  => {:uid=>"mccolin"}
  
At this point, we have a fancy serialized Hash on our hands. What we really want to be able to do is
search for objects of type Model that have certain values. That's possible, too. First, generate the
necessary migration:

  rails g doeskeyvalue
  
This creates db/migrate/XXX_create_key_value_index.rb for you. Migrate your database:

  rake db:migrate
  
Now, you can declare keys that you'd like to be searchable within Model like so:

  settings_index :uid
  settings_index :email
  
Now, you've added powerful finders to your objects. As your objects are created, accessed, and updated,
metadata in your index table will be updated that allows you to search against those objects similarly
to how you'd perform lookups with a regular finder. Like so:

  Model.find_all_by_uid(123)
  => [#<Model:0x000001016b51a0 @settings=>{:uid=>123}>, #<Model:0x000001016b51a0 @settings=>{:uid=>123}>, ...]
  
  Model.find_all_with_settings(:email=>"foo@bar.com")
  => [#<Model:0x000001016b51a0 @settings=>{:email=>"foo@bar"}>, ...]

You can only run finds on keys for which you've added an index, but you can add and remove indexes as
necessary simply by removing the index declaration from your model.

Likewise, you can remove keys from any model by removing the key declaration. This allows you to add
and remove keys from every ActiveRecord object at will, without having to build any migrations, but you
can still reap the benefits of whatever SQL-backed relational database you've chosen for the bulk of
your application's heavy lifting.


== Prior Versions

DoesKeyValue is a much newer and cleaner version of the old "do_document_fields" plugin for prior versions
of Rails. Check that out at http://github.com/mccolin/do_document_fields


== Contributions
 
* Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet
* Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it
* Fork the project
* Start a feature/bugfix branch
* Commit and push until you are happy with your contribution
* Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
* Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.

== Copyright

Copyright (c) 2011 Awexome Labs, LLC. http://awexomelabs.com/