view¶

API module for interacting with a view in a design document.

class cloudant.view.QueryIndexView(ddoc, view_name, map_fields, reduce_func, **kwargs)¶

Bases: cloudant.view.View

A view that defines a JSON query index in a design document.

If you wish to manage a view that represents a JSON query index it is strongly recommended that create_query_index() and delete_query_index() are used.

__call__(**kwargs)¶: QueryIndexView objects are not callable. If you wish to execute a query using a query index, use get_query_result() instead.

custom_result(**options)¶: This method overrides the View base class custom_result() method with the sole purpose of disabling it. Since QueryIndexView objects are not callable, there is no reason to wrap their output in a Result. If you wish to execute a query using a query index, use get_query_result() instead.

map¶

Provides a map property accessor and setter.

Parameters:	map_func (dict) – A dictionary of fields defining the index.
Returns:	Fields defining the index

reduce¶

Provides a reduce property accessor and setter.

Parameters:	reduce_func (str) – A string representation of the reduce function used in part to define the index.
Returns:	Reduce function as a string

class cloudant.view.View(ddoc, view_name, map_func=None, reduce_func=None, partition_key=None, **kwargs)¶

Bases: dict

Encapsulates a view as a dictionary based object, exposing the map and reduce functions as attributes and supporting query/data access through the view. A View object is instantiated with a reference to a DesignDocument and is typically used as part of the DesignDocument view management API.

A View object provides a key accessible, sliceable, and iterable default result collection that can be used to query the view data through the result attribute.

For example:

# Access result collection through individual keys
view.result[100]
view.result['foo']

# Access result collection through index slicing:
view.result[100: 200]
view.result[: 200]
view.result[100: ]
view.result[: ]

# Access result collection through key slicing:
view.result['bar': 'foo']
view.result['bar': ]
view.result[: 'foo']

# Iterate over the result collection:
for doc in view.result:
    print doc

The default result collection provides basic functionality, which can be customized with other arguments using the custom_result() context manager.

For example:

# Including documents as part of a custom result
with view.custom_result(include_docs=True) as rslt:
    rslt[100: 200]                       # slice by result
    rslt[['2013', '10']: ['2013', '11']] # slice by startkey/endkey

    # Iteration
    for doc in rslt:
        print doc

# Iteration over a view within startkey/endkey range:
with view.custom_result(startkey='2013', endkey='2014') as rslt:
    for doc in rslt:
        print doc

Note: A view must exist as part of a design document remotely in order to access result content as depicted in the above examples.

Parameters:

ddoc (DesignDocument) – DesignDocument instance used in part to identify the view.
view_name (str) – Name used in part to identify the view.
map_func (str) – Optional Javascript map function.
reduce_func (str) – Optional Javascript reduce function.
partition_key (str) – Optional. Specify a view partition key. Defaults to None resulting in global queries.

__call__(**kwargs)¶

Makes the View object callable and retrieves the raw JSON content from the remote database based on the View definition on the server, using the kwargs provided as query parameters.

For example:

# Construct a View
view = View(ddoc, 'view001')
# Assuming that 'view001' exists as part of the
# design document ddoc in the remote database...
# Use view as a callable
for row in view(include_docs=True, limit=100, skip=100)['rows']:
    # Process view data (in JSON format).

Note: Rather than using the View callable directly, if you wish to retrieve view results in raw JSON format use raw_result=True with the provided database API of get_view_result() instead.

Parameters:

descending (bool) – Return documents in descending key order.
endkey – Stop returning records at this specified key.
endkey_docid (str) – Stop returning records when the specified document id is reached.
group (bool) – Using the reduce function, group the results to a group or single row.
group_level – Only applicable if the view uses complex keys: keys that are JSON arrays. Groups reduce results for the specified number of array fields.
include_docs (bool) – Include the full content of the documents.
inclusive_end (bool) – Include rows with the specified endkey.
key (str) – Return only documents that match the specified key.
keys (list) – Return only documents that match the specified keys.
limit (int) – Limit the number of returned documents to the specified count.
reduce (bool) – True to use the reduce function, false otherwise.
skip (int) – Skip this number of rows from the start.
stale (str) – Allow the results from a stale view to be used. This makes the request return immediately, even if the view has not been completely built yet. If this parameter is not given, a response is returned only after the view has been built.
startkey – Return records starting with the specified key.
startkey_docid (str) – Return records starting with the specified document ID.

Returns:

View result data in JSON format

custom_result(**options)¶

Customizes the Result behavior and provides a convenient context manager for the Result. Result customizations can be made by providing extra options to the result call using this context manager. Depending on how you are accessing, slicing or iterating through your result collection certain query parameters are not permitted. See Result for additional details.

For example:

with view.custom_result(include_docs=True, reduce=False) as rslt:
    data = rslt[100: 200]

Parameters:

descending (bool) – Return documents in descending key order.
endkey – Stop returning records at this specified key. Not valid when used with Result key access and key slicing.
endkey_docid (str) – Stop returning records when the specified document id is reached.
group (bool) – Using the reduce function, group the results to a group or single row.
group_level – Only applicable if the view uses complex keys: keys that are JSON arrays. Groups reduce results for the specified number of array fields.
include_docs (bool) – Include the full content of the documents.
inclusive_end (bool) – Include rows with the specified endkey.
key – Return only documents that match the specified key. Not valid when used with Result key access and key slicing.
keys (list) – Return only documents that match the specified keys. Not valid when used with Result key access and key slicing.
limit (int) – Limit the number of returned documents to the specified count. Not valid when used with Result iteration.
page_size (int) – Sets the page size for result iteration.
reduce (bool) – True to use the reduce function, false otherwise.
skip (int) – Skip this number of rows from the start. Not valid when used with Result iteration.
stale (str) – Allow the results from a stale view to be used. This makes the request return immediately, even if the view has not been completely built yet. If this parameter is not given, a response is returned only after the view has been built.
startkey – Return records starting with the specified key. Not valid when used with Result key access and key slicing.
startkey_docid (str) – Return records starting with the specified document ID.

Returns:

View result data wrapped in a Result instance

map¶

Provides an map property accessor and setter.

For example:

# Set the View map property
view.map = 'function (doc) {\n  emit(doc._id, 1);\n}'
print view.map

Parameters:	js_func (str) – Javascript function.
Returns:	Codified map function

reduce¶

Provides an reduce property accessor and setter.

For example:

# Set the View reduce property
view.reduce = '_count'
# Get and print the View reduce property
print view.reduce

Parameters:	js_func (str) – Javascript function.
Returns:	Codified reduce function

url¶

Constructs and returns the View URL.

Returns:	View URL