Mailing-List: contact user-help@couchdb.apache.org; run by ezmlm
Precedence: bulk
Reply-To: user@couchdb.apache.org
Received-SPF: pass (athena.apache.org: domain of paul.joseph.davis@gmail.com
 designates 209.85.198.233 as permitted sender)
DomainKey-Signature: a=rsa-sha1; c=nofws;
        d=gmail.com; s=gamma;
        h=message-id:date:from:to:subject:in-reply-to:mime-version
         :content-type:content-transfer-encoding:content-disposition
         :references;
        b=QXba6TLSBplhwRE7azKFYMzgdhXF8Ik6BsjqapJRVPEQIl82kSxojbevoDghWijc4z
         9KBvx37DCepxmCx2nDjimk5FRyfqlLveYAwTXXi23DmGxg59l4vutZShzB+c8YEx1oLE
         4E/tLz+OMg95T+Phc/TdU+X78IZcwSwE4nfAs=
Message-ID: <e2111bbb0812280600v50a1f34cxd03d9a25868946de@mail.gmail.com>
Date: Sun, 28 Dec 2008 09:00:53 -0500
From: "Paul Davis" <paul.joseph.davis@gmail.com>
To: user@couchdb.apache.org
Subject: Re: newbie question #1
In-Reply-To: <7127C806-65EA-4C3E-94A4-EE9E1390C38C@pobox.com>
MIME-Version: 1.0
Content-Type: text/plain; charset=ISO-8859-1
Content-Transfer-Encoding: 7bit
Content-Disposition: inline
References: <98979283-BB61-4D15-AF05-196979FA42BC@pobox.com>
	 <e2111bbb0812280526q2766d197ld38f250d25d8e890@mail.gmail.com>
	 <7127C806-65EA-4C3E-94A4-EE9E1390C38C@pobox.com>

On Sun, Dec 28, 2008 at 8:47 AM, Geir Magnusson Jr. <geir@pobox.com> wrote:
>
> On Dec 28, 2008, at 8:26 AM, Paul Davis wrote:
>
>> On Sun, Dec 28, 2008 at 8:12 AM, Geir Magnusson Jr. <geir@pobox.com>
>> wrote:
>
> [SNIP]
>>
>> Also check out http://planet.couchdb.com for related blog posts. I
>> also find a google alert for CouchDB to be pretty useful.
>>
>
> Thanks
>
>
>>> First newbie question :
>>>
>>> Looking at http://wiki.apache.org/couchdb/HTTP_Document_API, I understand
>>> that _id and _rev are reserved fields in the document**.  Now, looking at
>>> the _all_docs example, I see I get back a list of docs :
>>>
>>> {
>>> "total_rows": 3, "offset": 0, "rows": [
>>>  {"id": "doc1", "key": "doc1", "value": {"rev": "4324BB"}},
>>>  {"id": "doc2", "key": "doc2", "value": {"rev":"2441HF"}},
>>>  {"id": "doc3", "key": "doc3", "value": {"rev":"74EC24"}}
>>> ]
>>> }
>>>
>>> what is "id"?  is that supposed to be "_id"?  what is "key"?  I see that
>>> in
>>> futon as well - how does it relate to "_id" or "id" for that matter?
>>>  Also,
>>> I assume that "rev" is the "_rev" of the document.  Why not make it
>>> "_rev"?
>>>
>>> I'm guessing that "id" is "_id", as I can see similar things in the PUT
>>> example, but I guess then the question changes to why not just be
>>> consistent
>>> and use "_id" everywhere, especially since I'm allowed to use "id" in my
>>> document?
>>>
>>> I'm sorry if this is a stupid question - I just don't understand.  I'm
>>> happy
>>> to update the wiki when I understand :)
>>>
>>
>> You're pretty much spot on here. "id" and "key" both refer to the
>> "_id" field in a document. And the "rev" does indeed refer to the
>> "_rev" attribute. 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.
>
> Ok, cool.  So... can key be something else?  Or should I assume that "key"
> is a synonym for "_id"?
>

Its a bit misleading because you chose _all_docs as the first view you
looked at. Really _all_docs is a special internal view that CouchDB
provides. When you get to defining your own views, you learn that
views are created by emit'ing key/value pairs that are arbitrary JSON
objects (no _id/_rev complaints even). So yes, key can be whatever you
want when defining a custom view.

> [SNIP]
>
>>> {
>>>   _id : whatever
>>>   _rev : whatever
>>>   doc : { ..... the full user document that can have _id, _rev and
>>> whatever....}
>>> }
>>>
>>>
>>
>> Like Noah says, reserving underscore prefixed fields as private to
>> CouchDB doesn't make it not JSON. I'd argue that putting the document
>> stuff inside a doc member would probably be a annoyance in that every
>> operation on the doc would require doc.doc.foo instead of just doc.foo
>
> I certainly understand that there are tradeoffs.  We do the same thing at
> 10gen - modify the user's document for storage.  Some random thoughts :
>
> 1) doing an insert requires that the user document be deserialized (maybe
> only partially?), the additional fields inserted, and then re-serialized for
> storage.  Have a metadata envelope means that the user document keyspace and
> the server's metadata keyspace are totally decoupled.
>

I fail to see how these two points are related, but at the moment
partial de/serialization is not done in CouchDB. Its been discussed
(extensively) and has been more or less put on hold until there is a
JSON community supported diff format. Though, come to think of it,
that'll still require a full de/serialization round trip.

> 2) It prevents, or at least makes harder, any document security - any hash
> function would have to account for the fact that there may be external keys
> injected into the document ("_*").  This is doable, but now makes your code
> - which was handling "generic JSON" - now have to know that it's working w/
> a couchdb store....
>

I don't follow.

> 3) the doc.doc.foo problem - Is that really a problem?  I haven't worked w/
> couch yet to understand the common access patterns, but it seems that the
> different calls to the rest API return things of different "shape" anyway...
>  if you are accessing by document id, you could just get the user doc back,
> and it seems that other queries return metadata anyway (e.g. _all_docs) so
> people must be used to pulling the user doc out of the framing data....  You
> could solve the issue in MR easily as well.
>

Its not a *problem* it'd just annoy me to have to type doc.doc.foo
instead of doc.foo.

> Anyway, I don't want this to distract :)  It's just a subject I'm interested
> in, as it's a personal pet peeve...
>
> geir
>
>
>>
>>
>> HTH,
>> Paul Davis
>
>

Apologies if I seem confused. I haven't been to sleep since a long time ago.

HTH,
Paul Davis