mirror of https://gitee.com/bigwinds/arangodb
252 lines
16 KiB
HTML
252 lines
16 KiB
HTML
<html><head><title>ArangoDB Manual</title> <style media="screen" type="text/css" style="display:none">body{background-color:white;font:13px Helvetica,arial,freesans,clean,sans-serif;line-height:1.4;color:#333;}#access{font-size:16px;margin-left:12px;display:block;margin-left:10px;margin-right:10px;background-color:#F3F1EE!important;}#access a{border-right:1px solid #DBDEDF;color:#A49F96;display:block;line-height:38px;padding:0 10px;text-decoration:none;}#navigation ul{text-transform:uppercase;list-style:none;margin:0;}#navigation li{float:left;position:relative;}#container{width:920px;margin:0 auto;}a{color:#4183C4;text-decoration:none;}.contents h2{font-size:24px;border-bottom:1px solid #CCC;color:black;}.contents h1{font-size:33px;border-bottom:1px solid #CCC;color:black;}.clearfix:after{content:".";display:block;clear:both;font-size:0;height:0;visibility:hidden;}/**/ *:first-child+html .clearfix{min-height:0;}/**/ * html .clearfix{height:1%;}</style></head><body><div id="container"><img src="images/logo_arangodb.png" width="397" height="67" alt="ArangoDB"><div id="access" role="navigation"><div id="navigation"><ul id="menu-ahome" class="menu"><li><a href="Home.html">Table of contents</a></li> <li><a href="http://www.arangodb.org">ArangoDB homepage</a></li></ul></div><div class="clearfix"></div></div><div>
|
|
<!-- Generated by Doxygen 1.7.5.1 -->
|
|
</div>
|
|
<div class="header">
|
|
<div class="headertitle">
|
|
<h1>Handling Documents </h1> </div>
|
|
</div>
|
|
<div class="contents">
|
|
<div class="textblock"><p>This is an introduction to ArangoDB's interface for documents and how handle documents from the JavaScript shell <code>arangosh</code>. For other languages see the corresponding language API.</p>
|
|
<hr/>
|
|
<ul>
|
|
<li>
|
|
<a class="el" href="ShellDocument.html">Handling Documents</a> <ul>
|
|
<li>
|
|
<a class="el" href="ShellDocument.html#ShellDocumentIntro">Documents, Identifiers, Handles</a> </li>
|
|
<li>
|
|
<a class="el" href="ShellDocument.html#ShellDocumentResource">Address and ETag of an Document</a> </li>
|
|
<li>
|
|
<a class="el" href="ShellDocument.html#ShellDocumentShell">Working with Documents</a> <ul>
|
|
<li>
|
|
<a class="el" href="ShellDocument.html#ShellDocumentCollectionMethods">Collection Methods</a> <ul>
|
|
<li>
|
|
<a class="el" href="ShellDocument.html#ShellDocumentRead">collection.document</a> </li>
|
|
<li>
|
|
<a class="el" href="ShellDocument.html#ShellDocumentCreate">collection.save</a> </li>
|
|
<li>
|
|
<a class="el" href="ShellDocument.html#ShellDocumentUpdate">collection.replace</a> </li>
|
|
<li>
|
|
<a class="el" href="ShellDocument.html#ShellDocumentDelete">collection.remove</a> </li>
|
|
</ul>
|
|
</li>
|
|
<li>
|
|
<a class="el" href="ShellDocument.html#ShellDocumentDatabaseMethods">Database Methods</a> <ul>
|
|
<li>
|
|
<a class="el" href="ShellDocument.html#ShellDocumentDbRead">db._document</a> </li>
|
|
<li>
|
|
<a class="el" href="ShellDocument.html#ShellDocumentDbUpdate">db._replace</a> </li>
|
|
<li>
|
|
<a class="el" href="ShellDocument.html#ShellDocumentDbDelete">db._remove</a> </li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
<hr/>
|
|
<h2><a class="anchor" id="ShellDocumentIntro"></a>
|
|
Documents, Identifiers, Handles</h2>
|
|
<p><b>Document</b>: Documents in ArangoDB are JSON objects. These objects can be nested (to any depth) and may contains lists. Each document is unique identified by its document handle. </p>
|
|
<p>For example:</p>
|
|
<div class="fragment"><pre class="fragment">{
|
|
"_id" : "1234567/2345678",
|
|
"_rev" : "3456789",
|
|
"firstName" : "Hugo",
|
|
"lastName" : "Schlonz",
|
|
"address" : {
|
|
"street" : "Strasse 1",
|
|
"city" : "Hier"
|
|
},
|
|
"hobbies" : [
|
|
"swimming",
|
|
"biking",
|
|
"programming"
|
|
]
|
|
}
|
|
</pre></div><p>All documents contain two special fields, the document handle in <code>_id</code> and the etag aka document revision in <code>_rev</code>.</p>
|
|
<p><b>Document Handle</b>: A document handle uniquely identifies a document in the database. It is a string and consists of a collection identifier and a document identifier separated by <code>/</code>. </p>
|
|
<p><b>Document Identifier</b>: A document identifier identifies a document in a given collection. It is an integer and is unique within the collection of the document. </p>
|
|
<p><b>Document Revision</b>: As AvocaodDB supports MVCC, documents can exist in more than one revision. The document revision is the MVCC token used to identify a particular revision of a document. It is an integer and unique within the list of document revision for a single document. Earlier revision of a document have smaller numbers. In order to find a particular revision of a document, you need the document handle and the document revision. </p>
|
|
<p><b>Document Etag</b>: The document revision enclosed in double quotes. </p>
|
|
<h2><a class="anchor" id="ShellDocumentResource"></a>
|
|
Address and ETag of an Document</h2>
|
|
<p>All documents in ArangoDB have a document handle. This handle uniquely defines a document and is managed by ArangoDB. The interface allows you to access the documents of a collection as:</p>
|
|
<p><code>db.<em>collection</em>.documet(<em>document-handle</em>)</code></p>
|
|
<p>For example: Assume that the document handle, which is stored in the <code>_id</code> field of the document, is <code>7254820/362549736</code> and the document lives in a collection named <em>demo</em>, then that document can be accessed as:</p>
|
|
<p><code>db.demo.document("7254820/362549736")</code></p>
|
|
<p>Because the document handle is unique within the database, you can leave out the <em>collection</em> and use the shortcut:</p>
|
|
<p><code>db._document("7254820/362549736")</code></p>
|
|
<p>Each document also has a document revision or etag with is returned in the <code>_rev</code> field when requesting a document.</p>
|
|
<h2><a class="anchor" id="ShellDocumentShell"></a>
|
|
Working with Documents</h2>
|
|
<h3><a class="anchor" id="ShellDocumentCollectionMethods"></a>
|
|
Collection Methods</h3>
|
|
<p><a class="anchor" id="ShellDocumentRead"></a> <hr/>
|
|
<code><b><em>collection</em>.document(<em>document</em>)</b></code><hr/>
|
|
The <code>document</code> method finds a document given it's identifier. It returns the document. Note that the returned document contains two pseudo-attributes, namely <code>_id</code> and <code>_rev</code>. <code>_id</code> contains the document-handle and <code>_rev</code> the revision of the document.</p>
|
|
<p>An error is thrown if there <code>_rev</code> does not longer match the current revision of the document.</p>
|
|
<p>An error is thrown if the document does not exist.</p>
|
|
<p>The document must be part of the <em>collection</em>; otherwise, an error is thrown.</p>
|
|
<hr/>
|
|
<code><b><em>collection</em>.document(<em>document-handle</em>)</b></code><hr/>
|
|
As before. Instead of document a <em>document-handle</em> can be passed as first argument.</p>
|
|
<p><b>Examples</b><br/>
|
|
</p>
|
|
<p>Returns the document for a document-handle:</p>
|
|
<div class="fragment"><pre class="fragment">arango> db.example.document("1432124/2873916");
|
|
{ "_id" : "1432124/2873916", "_rev" : 2873916, "Hallo" : "World" }
|
|
</pre></div> <p>An error is raised if the document is unknown:</p>
|
|
<div class="fragment"><pre class="fragment">arango> db.example.document("1432124/123456");
|
|
JavaScript exception in file '(arango)' at 1,12:
|
|
[ArangoError 1202: document not found: document not found]
|
|
!db.example.document("1432124/123456");
|
|
! ^
|
|
</pre></div> <p>An error is raised if the handle is invalid:</p>
|
|
<div class="fragment"><pre class="fragment">arango> db.example.document("12345");
|
|
JavaScript exception in file '(arango)' at 1,12:
|
|
[ArangoError 10: bad parameter: <document-idenifier> must be a document identifier]
|
|
!db.example.document("12345");
|
|
! ^
|
|
</pre></div> <p><a class="anchor" id="ShellDocumentCreate"></a> <p>This function makes the distinction between document and edge collections and dispatches the request to the collection's specialised save function </p>
|
|
<p><a class="anchor" id="ShellDocumentUpdate"></a> <hr/>
|
|
<code><b><em>collection</em>.replace(<em>document</em>, <em>data</em>)</b></code><hr/>
|
|
Replaces an existing <em>document</em>. The <em>document</em> must be a document in the current collection. This document is then replaced with the <em>data</em> given as second argument.</p>
|
|
<p>The method returns a document with the attributes <code>_id</code>, <code>_rev</code> and <code>_oldRev</code>. The attribute <code>_id</code> contains the document handle of the updated document, the attribute <code>_rev</code> contains the document revision of the updated document, the attribute <code>_oldRev</code> contains the revision of the old (now replaced) document.</p>
|
|
<p>If there is a conflict, i. e. if the revision of the <code>document</code> does not match the revision in the collection, then an error is thrown.</p>
|
|
<hr/>
|
|
<code><b><em>collection</em>.replace(<em>document</em>, <em>data</em>, true)</b></code><hr/>
|
|
As before, but in case of a conflict, the conflict is ignored and the old document is overwritten.</p>
|
|
<hr/>
|
|
<code><b><em>collection</em>.replace(<em>document-handle</em>, <em>data</em>)</b></code><hr/>
|
|
As before. Instead of document a <em>document-handle</em> can be passed as first argument.</p>
|
|
<p><b>Examples</b><br/>
|
|
</p>
|
|
<p>Create and update a document:</p>
|
|
<div class="fragment"><pre class="fragment">arango> a1 = db.example.save({ a : 1 });
|
|
{ "_id" : "1432124/3903044", "_rev" : 3903044 }
|
|
arango> a2 = db.example.replace(a1, { a : 2 });
|
|
{ "_id" : "1432124/3903044", "_rev" : 3968580, "_oldRev" : 3903044 }
|
|
arango> a3 = db.example.replace(a1, { a : 3 });
|
|
JavaScript exception in file '(arango)' at 1,17: [ArangoError 1200: conflict: cannot replace document]
|
|
!a3 = db.example.replace(a1, { a : 3 })
|
|
! ^
|
|
arango> a4 = db.example.replace(a1, { a : 4 }, true);
|
|
{ "_id" : "1432124/3903044", "_rev" : 4034116, "_oldRev" : 3968580 }
|
|
</pre></div> <p>Use a document handle:</p>
|
|
<div class="fragment"><pre class="fragment">arango> a5 = db.example.replace("1432124/3903044", { a : 5 });
|
|
{ "_id" : "1432124/3903044", "_rev" : 4099652, "_oldRev" : 4034116 }
|
|
</pre></div> <p><a class="anchor" id="ShellDocumentDelete"></a> <hr/>
|
|
<code><b><em>collection</em>.remove(<em>document</em>)</b></code><hr/>
|
|
Deletes a document. If there is revision mismatch, then an error is thrown.</p>
|
|
<hr/>
|
|
<code><b><em>collection</em>.remove(<em>document</em>, true)</b></code><hr/>
|
|
Deletes a document. If there is revision mismatch, then mismatch is ignored and document is deleted. The function returns <code>true</code> if the document existed and was deleted. It returns <code>false</code>, if the document was already deleted.</p>
|
|
<hr/>
|
|
<code><b><em>collection</em>.remove(<em>document-handle</em>, <em>data</em>)</b></code><hr/>
|
|
As before. Instead of document a <em>document-handle</em> can be passed as first argument.</p>
|
|
<p><b>Examples</b><br/>
|
|
</p>
|
|
<p>Delete a document:</p>
|
|
<div class="fragment"><pre class="fragment">arango> a1 = db.example.save({ a : 1 });
|
|
{ "_id" : "116308/3449537", "_rev" : 3449537 }
|
|
arango> db.example.document(a1);
|
|
{ "_id" : "116308/3449537", "_rev" : 3449537, "a" : 1 }
|
|
arango> db.example.delete(a1);
|
|
true
|
|
arango> db.example.document(a1);
|
|
JavaScript exception in file '(arango)' at 1,12: [ArangoError 1202: document not found: document not found]
|
|
!db.example.document(a1);
|
|
! ^
|
|
</pre></div> <p>Delete a document with a conflict:</p>
|
|
<div class="fragment"><pre class="fragment">arango> a1 = db.example.save({ a : 1 });
|
|
{ "_id" : "116308/3857139", "_rev" : 3857139 }
|
|
arango> a2 = db.example.replace(a1, { a : 2 });
|
|
{ "_id" : "116308/3857139", "_rev" : 3922675, "_oldRev" : 3857139 }
|
|
arango> db.example.delete(a1);
|
|
JavaScript exception in file '(arango)' at 1,18: [ArangoError 1200: conflict: cannot delete document]
|
|
!db.example.delete(a1);
|
|
! ^
|
|
arango> db.example.delete(a1, true);
|
|
true
|
|
arango> db.example.document(a1);
|
|
JavaScript exception in file '(arango)' at 1,12: [ArangoError 1202: document not found: document not found]
|
|
!db.example.document(a1);
|
|
! ^
|
|
</pre></div> <h3><a class="anchor" id="ShellDocumentDatabaseMethods"></a>
|
|
Database Methods</h3>
|
|
<p><a class="anchor" id="ShellDocumentDbRead"></a> <hr/>
|
|
<code><b><em>db</em>._document(<em>document</em>)</b></code><hr/>
|
|
The <code>document</code> method finds a document given it's identifier. It returns the document. Note that the returned document contains two pseudo-attributes, namely <code>_id</code> and <code>_rev</code>. <code>_id</code> contains the document handle and <code>_rev</code> the revision of the document.</p>
|
|
<p>An error is thrown if there <code>_rev</code> does not longer match the current revision of the document.</p>
|
|
<hr/>
|
|
<code><b><em>db</em>._document(<em>document-handle</em>)</b></code><hr/>
|
|
As before. Instead of document a <em>document-handle</em> can be passed as first argument.</p>
|
|
<p><b>Examples</b><br/>
|
|
</p>
|
|
<p>Returns the document:</p>
|
|
<div class="fragment"><pre class="fragment">arango> db._document("1432124/3053939");
|
|
{ "_id" : "1432124/3053939", "_rev" : 3053939, "Hallo" : "World" }
|
|
</pre></div> <p><a class="anchor" id="ShellDocumentDbUpdate"></a> <hr/>
|
|
<code><b><em>db</em>._replace(<em>document</em>, <em>data</em>)</b></code><hr/>
|
|
The method returns a document with the attributes <code>_id</code>, <code>_rev</code> and <code>_oldRev</code>. The attribute <code>_id</code> contains the document handle of the updated document, the attribute <code>_rev</code> contains the document revision of the updated document, the attribute <code>_oldRev</code> contains the revision of the old (now replaced) document.</p>
|
|
<p>If there is a conflict, i. e. if the revision of the <code>document</code> does not match the revision in the collection, then an error is thrown.</p>
|
|
<hr/>
|
|
<code><b><em>db</em>._replace(<em>document</em>, <em>data</em>, true)</b></code><hr/>
|
|
As before, but in case of a conflict, the conflict is ignored and the old document is overwritten.</p>
|
|
<hr/>
|
|
<code><b><em>db</em>._replace(<em>document-handle</em>, <em>data</em>)</b></code><hr/>
|
|
As before. Instead of document a <em>document-handle</em> can be passed as first argument.</p>
|
|
<p><b>Examples</b><br/>
|
|
</p>
|
|
<p>Create and update a document:</p>
|
|
<div class="fragment"><pre class="fragment">arango> a1 = db.example.save({ a : 1 });
|
|
{ "_id" : "116308/1717678", "_rev" : 1717678 }
|
|
arango> a2 = db._replace(a1, { a : 2 });
|
|
{ "_id" : "116308/1717678", "_rev" : 1783214, "_oldRev" : 1717678 }
|
|
arango> a3 = db._replace(a1, { a : 3 });
|
|
JavaScript exception in file '(arango)' at 1,9: [ArangoError 1200: conflict: cannot replace document]
|
|
!a3 = db._replace(a1, { a : 3 });
|
|
! ^
|
|
arango> a4 = db.example.replace(a1, { a : 4 }, true);
|
|
{ "_id" : "116308/1717678", "_rev" : 1848750, "_oldRev" : 1783214 }
|
|
</pre></div> <p><a class="anchor" id="ShellDocumentDbDelete"></a> <hr/>
|
|
<code><b><em>db</em>._remove(<em>document</em>)</b></code><hr/>
|
|
Deletes a document. If there is revision mismatch, then an error is thrown.</p>
|
|
<hr/>
|
|
<code><b><em>db</em>._remove(<em>document</em>, true)</b></code><hr/>
|
|
Deletes a document. If there is revision mismatch, then mismatch is ignored and document is deleted. The function returns <code>true</code> if the document existed and was deleted. It returns <code>false</code>, if the document was already deleted.</p>
|
|
<hr/>
|
|
<code><b><em>db</em>._remove(<em>document-handle</em>, <em>data</em>)</b></code><hr/>
|
|
As before. Instead of document a <em>document-handle</em> can be passed as first argument.</p>
|
|
<p><b>Examples</b><br/>
|
|
</p>
|
|
<p>Delete a document:</p>
|
|
<div class="fragment"><pre class="fragment">arango> a1 = db.example.save({ a : 1 });
|
|
{ "_id" : "116308/4214943", "_rev" : 4214943 }
|
|
arango> db._delete(a1);
|
|
true
|
|
arango> db._delete(a1);
|
|
JavaScript exception in file '(arango)' at 1,4: [ArangoError 1202: document not found: cannot delete document]
|
|
!db._delete(a1);
|
|
! ^
|
|
arango> db._delete(a1, true);
|
|
false
|
|
</pre></div> <p>Delete a document with a conflict:</p>
|
|
<div class="fragment"><pre class="fragment">arango> a1 = db.example.save({ a : 1 });
|
|
{ "_id" : "116308/4042634", "_rev" : 4042634 }
|
|
arango> a2 = db._replace(a1, { a : 2 });
|
|
{ "_id" : "116308/4042634", "_rev" : 4108170, "_oldRev" : 4042634 }
|
|
arango> db._delete(a1);
|
|
JavaScript exception in file '(arango)' at 1,4: [ArangoError 1200: conflict: cannot delete document]
|
|
!db._delete(a1);
|
|
! ^
|
|
arango> db._delete(a1, true);
|
|
true
|
|
arango> db._document(a1);
|
|
JavaScript exception in file '(arango)' at 1,4: [ArangoError 1202: document not found: document not found]
|
|
!db._document(a1);
|
|
! ^
|
|
</pre></div> </div></div>
|
|
</div></body></html>
|