Class CouchRest::Model::Designs::View
In: lib/couchrest/model/designs/view.rb
Parent: Object

A proxy class that allows view queries to be created using chained method calls. After each call a new instance of the method is created based on the original in a similar fashion to ruby‘s Sequel library, or Rails 3‘s Arel.

CouchDB views have inherent limitations, so joins and filters as used in a normal relational database are not possible.

Methods

[]   all   can_reduce?   count   create_model_methods   current_page   database   define   define_and_create   descending   docs   each   empty?   endkey   endkey_doc   execute   first   group   group_level   include_docs   include_docs!   include_docs?   info   key   keys   last   length   limit   limit_value   new   num_pages   offset   offset_value   page   per   proxy   reduce   reset!   rows   skip   stale   startkey   startkey_doc   total_count   total_pages   total_rows   update_query   use_database   values  

Included Modules

Enumerable

Attributes

design_doc  [RW] 
model  [RW] 
name  [RW] 
owner  [RW] 
query  [RW] 
result  [RW] 

Public Class methods

new(design_doc, parent, new_query = {}, name = nil)

Initialize a new View object. This method should not be called from outside CouchRest Model.

Protected Class methods

define(design_doc, name, opts = {})

Simplified view definition. A new view will be added to the provided design document using the name and options.

If the view name starts with "by_" and +:by+ is not provided in the options, the new view‘s map method will be interpreted and generated automatically. For example: 

  View.define(Meeting, design, "by_date_and_name")

Will create a view that searches by the date and name properties. Explicity setting the attributes to use is possible using the +:by+ option. For example: 

  View.define(Meeting, design, "by_date_and_name", :by => [:date, :firstname, :lastname])

The view name is the same, but three keys would be used in the subsecuent index.

By default, a check is made on each of the view‘s keys to ensure they do not contain a nil value (‘null’ in javascript). This is probably what you want in most cases but sometimes in can be useful to create an index where nil is permited. Set the :allow_nil option to true to remove this check.

Conversely, keys are not checked to see if they are empty or blank. If you‘d like to enable this, set the :allow_blank option to false. The default is true, empty strings are permited in the indexes.

Public Instance methods

[](value)

Accept requests as if the view was an array. Used for backwards compatibity with older queries: 

   Model.all(:raw => true, :limit => 0)['total_rows']

In this example, the raw option will be ignored, and the total rows will still be accessible.

all()

Fetch all the documents the view can access. If the view has not already been prepared for including documents in the query, it will be added automatically and reset any previously cached results.

count()

Perform a count operation based on the current view. If the view can be reduced, the reduce will be performed and return the first value. This is okay for most simple queries, but may provide unexpected results if your reduce method does not calculate the total number of documents in a result set.

Trying to use this method with the group option will raise an error.

If no reduce function is defined, a query will be performed to return the total number of rows, this is the equivalant of: 

   view.limit(0).total_rows
database(value)

Specify the database the view should use. If not defined, an attempt will be made to load its value from the model.

descending()

The results should be provided in descending order. If the startkey or endkey query options have already been seen set, calling this method will automatically swap the options around. If you don‘t want this, simply set descending before any other option.

Descending is false by default, and this method cannot be undone once used, it has no inverse option.

docs()

Provide all the documents from the view. If the view has not been prepared with the include_docs option, each document will be loaded individually.

each(&block)

Run through each document provided by the +all+ method. This is also used by the Enumerator mixin to provide all the standard ruby collection directly on the view.

empty?()

Check to see if the array of documents is empty. This will perform the query and return all documents ready to use, if you don‘t want to load anything, use +total_rows+ or +count+ instead.

endkey(value)

The opposite of +startkey+, finds all index entries whose key is before the value specified.

See the +startkey+ method for more details and the +inclusive_end+ option.

endkey_doc(value)

The result set should end at the position of the provided document. The value may be provided as an object that responds to the +id+ call or a string.

first()

If another request has been made on the view, this will return the first document in the set. If not, a new query object will be generated with a limit of 1 so that only the first document is loaded.

group()

Control whether the reduce function reduces to a set of distinct keys or to a single result row.

By default the value is false, and can only be set when the view‘s +reduce+ option has been set.

group_level(value)

Will set the level the grouping should be performed to. As per the CouchDB API, it only makes sense when the index key is an array.

This will automatically set the group option.

info()

No yet implemented. Eventually this will provide a raw hash of the information CouchDB holds about the view.

key(value)

Find all entries in the index whose key matches the value provided.

Cannot be used when the +startkey+ or +endkey+ have been set.

keys(*keys)

Keys is a special CouchDB option that will cause the view request to be POSTed including an array of keys. Only documents with the matching keys will be returned. This is much faster than sending multiple requests for a set non-consecutive documents.

If no values are provided, this method will act as a wrapper around the rows result set, providing an array of keys.

last()

Same as first but will order the view in descending order. This does not however reverse the search keys or the offset, so if you are using a startkey and endkey you might end up with unexpected results.

If in doubt, don‘t use this method!

length()

Return the number of documents in the currently defined result set. Use count for the total number of documents regardless of the current limit defined.

limit(value)

Limit the result set to the value supplied.

num_pages()

Alias for total_pages

offset()

Wrapper for the results offset. As per the CouchDB API, this may be nil if groups are used.

page(page)

Kaminari compatible pagination support

Based on the really simple support for scoped pagination in the the Kaminari gem, we provide compatible methods here to perform the same actions you‘d expect.

proxy(value)

Set the view‘s proxy that will be used instead of the model for any future searches. As soon as this enters the new view‘s initializer it will be removed and set as the model object.

See the Proxyable mixin for more details.

reduce()

Use the reduce function on the view. If none is available this method will fail.

reset!()

Return any cached values to their nil state so that any queries requested later will have a fresh set of data.

rows()

Return each row wrapped in a ViewRow object. Unlike the raw CouchDB request, this will provide an empty array if there are no results.

skip(value = 0)

Skip the number of entries in the index specified by value. This would be the equivilent of an offset in SQL.

The CouchDB documentation states that the skip option should not be used with large data sets as it is inefficient. Use the startkey_doc method instead to skip ranges efficiently.

stale(value)

Allow the results of a query to be provided "stale". Setting to ‘ok’ will disable all view updates for the query. When ‘update_after’ is provided the index will be update after the result has been returned.

startkey(value)

Find all index keys that start with the value provided. May or may not be used in conjunction with the endkey option.

When the +descending+ option is used (not the default), the start and end keys should be reversed, as per the CouchDB API.

Cannot be used if the key has been set.

startkey_doc(value)

The result set should start from the position of the provided document. The value may be provided as an object that responds to the +id+ call or a string.

total_rows()

Wrapper for the total_rows value provided by the query. As per the CouchDB API, this may be nil if groups are used.

values()

Convenience wrapper to provide all the values from the route set without having to go through rows.

Protected Instance methods

[Validate]