couchdb-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Antony Blakey <>
Subject Re: Changing rev to _rev in view results (Was: Re: newbie question #1)
Date Mon, 29 Dec 2008 10:41:29 GMT

On 29/12/2008, at 7:20 PM, Christopher Lenz wrote:

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

It's not even a released product yet. Preserving accidental  
implementation artifacts to satisfy early pre-release clients is a  
very sad idea.

> 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).

Why have any rule about 'inside' or 'outside' a document - just use  
the same name everywhere.

> 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.

By using a consistent name for fields you reduce confusion and  
emphasise that they have the same semantic type. Your argument is  
based on the underscore not actually being part of the name, but  
rather a removable qualifier that is used to reduce the chances of  
collision. Contextually sensitive name transformations in an API are  
an unnecessary complication.

> 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

Both key and value never appear in a couch-metadata role within a  
document. I think _rev in the query string parameter is a good idea  
for consistency. Whenever a _rev appears, it's name should be _rev.  
Same for the _id of a document.

> 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.

It's not about *substantial* confusion - I'd like to see as much  
consistency and regularity in the API as possible before a 1.0  
release; said release being IMO a point at which backwards compatible  
cost-benefit concerns become appropriate.

> 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.

I really like this idea.

> 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?

I think it should either be in every view result that has an id, or in  
none. In so many cases you need the id and the rev to represent point- 
in-time identity, I think they should be supplied together whenever  

Antony Blakey
CTO, Linkuistics Pty Ltd
Ph: 0438 840 787

A Buddhist walks up to a hot-dog stand and says, "Make me one with  
everything". He then pays the vendor and asks for change. The vendor  
says, "Change comes from within".

View raw message