Mailing-List: contact dev-help@couchdb.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@couchdb.apache.org
Received-SPF: pass (nike.apache.org: domain of cmlenz@gmx.de designates
 213.165.64.20 as permitted sender)
Cc: user@couchdb.apache.org
Message-Id: <E86032A3-C830-4360-AC91-7E3C81BA1E6F@gmx.de>
From: Christopher Lenz <cmlenz@gmx.de>
To: dev@couchdb.apache.org
In-Reply-To: <A67E2901-CD92-4C24-B4E3-7955F2477766@apache.org>
Content-Type: text/plain; charset=US-ASCII; format=flowed; delsp=yes
Content-Transfer-Encoding: 7bit
Mime-Version: 1.0 (Apple Message framework v930.3)
Subject: Re: Changing rev to _rev in view results (Was: Re: newbie question
 #1)
Date: Mon, 29 Dec 2008 09:50:21 +0100
References: <98979283-BB61-4D15-AF05-196979FA42BC@pobox.com>
 <e2111bbb0812280526q2766d197ld38f250d25d8e890@mail.gmail.com>
 <49C5583B-254D-4D4D-A4F7-AD7306E758F1@gmail.com>
 <A67E2901-CD92-4C24-B4E3-7955F2477766@apache.org>

On 28.12.2008, at 20:21, Jan Lehnardt wrote:
> On 28 Dec 2008, at 14:32, Antony Blakey wrote:
>> On 28/12/2008, at 11:56 PM, Paul Davis wrote:
>>
>>> Why "id" and "rev" are used instead of "_id" and
>>> "_rev" I couldn't really tell you. I hate to say "historical  
>>> reasons"
>>> but I'm guessing that when Damien designed the view output he just
>>> labeled then "id" and "rev" without the underscore because it's not
>>> needed to distinguish from the rest of the doc.
>>
>> Desirable to change that (and any other inconsistencies) before a 1.0
>
> This keeps coming up and I've been advocating this for a while now:
>
> +1 for changing view result rows `rev` to `_rev` to avoid confusion.


(The following assumes that you'd also want to change "id" to "_id"...)

-1

This would break all substantial client code out there for  
questionable benefit.

I don't think there's anything inconsistent here, or anything to be  
confused about. The rule is simple: reserved fields *inside* documents  
have a leading underscore as to not clash with user fields (as user  
fields must not have a leading underscore at the top-level of the  
document). There are a couple of meta-data fields that are packed into  
documents, such as "id" and "rev". Now just because those fields get  
the leading-underscore treatment in documents doesn't mean they need a  
leading underscore whenever they appear in other places, such as view  
results.

Then the question is, where would you stop? Would you also rename  
"key" to "_key", "value" to "_value", and so on, for consistency? What  
about the "?rev=1234" query-string parameter? We could get to a point  
where every term used in the API will have a leading underscore just  
"to be safe" :P

I think this is the wrong direction. If these naming issues really are  
generating substantial confusion (which I doubt), we should rather be  
looking into changing the mechanism for including meta-information  
with documents so that the leading underscores could be dropped across  
the board. Maybe something like:


   {
     "_meta": {
       "id": "foo",
       "rev": "1234"
     },
     "title": "Foo",
     ...
   }

This would also cause client breakage, but at least we wouldn't be  
scattering more underscores around the API.


Oh, and if this thread was actually only about the "rev" field in the  
review results of _all_docs (note it's *not* in all view results), why  
not just drop it instead? Is there any practical reason it's in there?

Cheers,
Chris
--
Christopher Lenz
   cmlenz at gmx.de
   http://www.cmlenz.net/