Add document-style field blobs to any ActiveRecord object. Keep the ActiveRecord and SQL you want for associations, and toss the bulk of data into an on-object document
Ruby
Switch branches/tags
Nothing to show
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
lib
tasks
README.rdoc
init.rb

README.rdoc

Do Document Fields

Add document-style field blobs to any ActiveRecord object. Keep the ActiveRecord and SQL you want for associations, and toss the bulk of data into an on-object document

Example

To add document_fields to your ActiveRecord object, first add a text column to your class' backing table that will hold your document content. By default, do_document_fields will expect this column to be named “document”, but you can override that easily.

Once you've migrated that change into your model, here's a sample of hold to add document-style blob fields to your object:

class ObjectWithBlob < ActiveRecord::Base

  # Declare that we are using document blobs in a particular column of this object:
  do_document_fields

  # Declare the columns we are adding to our document:
  document_field :name, String
  document_field :phone, String
  document_field :age, Integer

  # Declare the document fields you'd like to track with indexes:
  document_index :name

  # If we wanted to change the name of the column in which we store the document, we'd do this:
  # do_document_fields :something_other_than_document. Like so:

  do_document_fields :settings

  # Changing the name of the column gives you a specifically-formatted field-definition method:

  settings_field :age
  settings_field :sex
  settings_field :location

  # This also provides a customized way to index:

  settings_index :location

end

Now, you can add and remove new fields to this object within the document as simply as adding or removing declarations of “document_field”.

Once you've added any indices to your model's fields, you'll want to be sure to build your supporting index tables. We use separate tables with database-level indexing to support indexed lookups of data in your document_field attributes. Build these tables by running this rake task:

rake db:migrate:document_indexes

Now, you can use strictly-provided finders to find your objects by their document field attributes. Considering the model we described above, you can lookup by any indexed field like so:

obj = ObjectWithBlob.find_by_name("Charlie")
=> [#<ObjectWithBlob id: 412, document: {:name=>"Charlie", :phone=>"212-555-1234", :age=>34}, created_at: "2010-03-22 20:49:03", updated_at: "2010-03-22 20:49:03">]

Finders are only added to document fields that are indexed. Finders also are all “find_all” lookups on equality.

If you'd like to use special sub-searching within any of your document-formatted fields, you can use the hash-based search conditions. Given the “settings” document declared in the example above, we can now also do this:

obj = ObjectWithBlob.find_with_settings(:location=>"San Francisco, CA")
=> [#<ObjectWithBlob id: 412, settings: {:age=>32, :sex=>"Female", :location=>"San Francisco, CA"}, created_at: "2010-03-22 20:49:03", updated_at: "2010-03-22 20:49:03">]

It's simple.

COPYRIGHT

Copyright 2010 Colin McCloskey (mccolin.com/), but, hell, you can use it as you please ;-)