Change /{db}/_design/{ddoc}/_view/{viewname} semantics for views with defined reduces

[alxndrsn]

Expected Behavior

View queries should always default to responding with a map if no value for the reduce parameter is supplied.

Current Behavior

scenario	query	reduce function defined	result
1	http://couch-instance/db-name/_design/ddoc_name/_view/view_name	no	map
2	http://couch-instance/db-name/_design/ddoc_name/_view/view_name	yes	reduce
3	http://couch-instance/db-name/_design/ddoc_name/_view/view_name?reduce=false	no	map
4	http://couch-instance/db-name/_design/ddoc_name/_view/view_name?reduce=false	yes	map
5	http://couch-instance/db-name/_design/ddoc_name/_view/view_name?reduce=true	no	error
6	http://couch-instance/db-name/_design/ddoc_name/_view/view_name?reduce=true	yes	reduce

IMO scenario number 2 is surprising and unhelpful.

Adding a reduce to an existing ddoc that is used in application code will break all existing calls to a view which do not define reduce=false. It's not possible to define a view which has a reduce function but not a map function, so the inverse does not apply.

Possible Solution

Change the default for reduce to false.

This change would affect a lot of existing users, so would need to be well documented and coincide with a major release version.

A couple of alternatives to this change might be:

1. Instead of defaulting, reject view queries which do not specify the reduce parameter

2. Update the docs at http://docs.couchdb.org/en/2.0.0/api/ddoc/views.html

Currently they read:

reduce (boolean) – Use the reduction function. Default is true

But might be clearer if they read:

reduce (boolean) – Use the reduction function. Default is true if a reduce function is defined, or false otherwise.

ref pouchdb/pouchdb#7127

[SCdF]

I also found this very confusing. I think because (at least for me) the vast majority of view usage is without a corresponding reduce, it's not something that you come across much, and it's a pretty radical change that is only passively documented in the query param list.

I think it might be worth modifying the documentation to pull this effect[1] into a warning documentation block to highlight it, and include an explanation to get everyone on the same page.

Something like:

Warning
By default, querying a view runs its reduce function if it has one. This can be confusing if you are used to just using map functions, and are adding a reduce function to an existing view. This happens because explanation_goes_here

[1] That all view queries automatically become reduce queries when you add a reduce

[wohali]

This is a backwards-compatibility breaking change and can not be introduced easily. The earliest such a change can be considered is 3.0.0.

[alxndrsn]

@wohali Any opinion on the documentation update suggestions?

[wohali]

I would say it's better to mention this in the gentle intro to views here. If I had to guess at a reason, it might be because views are CouchDB's implementation of MapReduce, which suggests if both are defined, you want both.

I don't think it warrants a call-out box in the API reference section, we already say:

reduce (boolean) – Use the reduction function. Default is true when a reduce function is defined.

With the increasing focus on Mango (and reduce coming soon to Mango) it might be best to ensure the user interface for Mango does something friendly and compatible here. /cc @tonysun83 @nickva

[alxndrsn]

reduce (boolean) – Use the reduction function. Default is true when a reduce function is defined.

This isn't quite what I see at http://docs.couchdb.org/en/2.1.1/api/ddoc/views.html - definitely an improvement.

[wohali]

Compare with http://docs.couchdb.org/en/latest/api/ddoc/views.html

Looks like @flimzy is ahead of you: apache/couchdb-documentation@bdfa864

I'll leave this open as an enhancement request, and edit the title to match.

[janl]

I understand why this is confusing, but I don’t see this changing going forward. We are happy to break BC for good reason, but this doesn’t warrant one IMHO.

[wohali]

Personally, I agree, and I expect most of the rest of the core developers would agree as well.

We can always re-open this; going to close for now as wontfix.