Hawkin
/
arangodb
mirror of https://gitee.com/bigwinds/arangodb
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
arangodb/Doxygen/doc/HttpCollection.html

509 lines
20 KiB
HTML
Raw Blame History

<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>HTTP Interface for Collections </h1> </div>
</div>
<div class="contents">
<div class="textblock"><p>This is an introduction to ArangoDB's Http interface for collections.</p>
<hr/>
<ul>
<li>
<a class="el" href="HttpCollection.html">HTTP Interface for Collections</a> <ul>
<li>
<a class="el" href="HttpCollection.html#HttpCollectionIntro">Collections</a> </li>
<li>
<a class="el" href="HttpCollection.html#HttpCollectionResource">Address of a Collection</a> </li>
<li>
<a class="el" href="HttpCollection.html#HttpCollectionHttp">Working with Collections using HTTP</a> <ul>
<li>
<a class="el" href="HttpCollection.html#HttpCollectionConstructor">Creating and Deleting Collections</a> <ul>
<li>
<a class="el" href="HttpCollection.html#HttpCollectionCreate">POST /_api/collection</a> </li>
<li>
<a class="el" href="HttpCollection.html#HttpCollectionDelete">DELETE /_api/collection/collection-identifier</a> </li>
<li>
<a class="el" href="HttpCollection.html#HttpCollectionTruncate">PUT /_api/collection/collection-identifier/truncate</a> </li>
</ul>
</li>
<li>
<a class="el" href="HttpCollection.html#HttpCollectionReading">Getting Information about a Collection</a> <ul>
<li>
<a class="el" href="HttpCollection.html#HttpCollectionRead">GET /_api/collection/collection-identifier</a> </li>
<li>
<a class="el" href="HttpCollection.html#HttpCollectionRead">GET /_api/collection/collection-identifier/properties</a> </li>
<li>
<a class="el" href="HttpCollection.html#HttpCollectionRead">GET /_api/collection/collection-identifier/count</a> </li>
<li>
<a class="el" href="HttpCollection.html#HttpCollectionRead">GET /_api/collection/collection-identifier/figures</a> </li>
<li>
<a class="el" href="HttpCollection.html#HttpCollectionRead">GET /_api/collection/collection-identifier</a> </li>
<li>
<a class="el" href="HttpCollection.html#HttpCollectionReadAll">GET /_api/collection/</a> </li>
</ul>
</li>
<li>
<a class="el" href="HttpCollection.html#HttpCollectionChanging">Modifying a Collection</a> <ul>
<li>
<a class="el" href="HttpCollection.html#HttpCollectionLoad">PUT /_api/collection/collection-identifier/load</a> </li>
<li>
<a class="el" href="HttpCollection.html#HttpCollectionUnload">PUT /_api/collection/collection-identifier/unload</a> </li>
<li>
<a class="el" href="HttpCollection.html#HttpCollectionProperties">PUT /_api/collection/collection-identifier/properties</a> </li>
<li>
<a class="el" href="HttpCollection.html#HttpCollectionRename">PUT /_api/collection/collection-identifier/rename</a> </li>
</ul>
</li>
</ul>
</li>
</ul>
</li>
</ul>
<hr/>
<h2><a class="anchor" id="HttpCollectionIntro"></a>
Collections</h2>
<p><b>Collection</b>: A collection consists of documents. It is uniquely identified by it's collection identifier. It also has a unique name. </p>
<p><b>Collection Identifier</b>: A collection identifier identifies a collection in a database. It is an integer and is unique within the database. </p>
<p><b>Collection Name</b>: A collection name identifies a collection in a database. It is an string and is unique within the database. Unlike the collection identifier it is supplied by the creator of the collection. The collection name can consist of letters, digits and the characters <code>_</code> (underscore) and <code>-</code> (dash). However, the first character must be a letter. </p>
<p>The basic operations (create, read, update, delete) for documents are mapped to the standard HTTP methods (POST, GET, PUT, DELETE).</p>
<h2><a class="anchor" id="HttpCollectionResource"></a>
Address of a Collection</h2>
<p>All collections in ArangoDB have an unique identifier. This collection identifier identifies a collection and is managed by ArangoDB. All collections are found under the URI</p>
<p><code><a href="http://">http://</a><em>server</em>:<em>port</em>/_api/collection/<em>collection-identifier</em></code></p>
<p>For example: Assume that the collection identifier is <code>7254820</code>, then the URL of that collection is:</p>
<p><code><a href="http://localhost:8529/_api/collection/7254820">http://localhost:8529/_api/collection/7254820</a></code></p>
<h2><a class="anchor" id="HttpCollectionHttp"></a>
Working with Collections using HTTP</h2>
<h3><a class="anchor" id="HttpCollectionConstructor"></a>
Creating and Deleting Collections</h3>
<p><a class="anchor" id="HttpCollectionCreate"></a> <hr/>
<em>POST /_api/collection</em> (creates a collection)<hr/>
<br/>
<code><b>POST /_api/collection</b></code></p>
<p>Creates an new collection with a given name. The request must contain an object with the following attributes.</p>
<ul>
<li><code>name</code>: The name of the collection.</li>
</ul>
<ul>
<li><code>waitForSync</code> (optional, default: false): If <code>true</code> then the data is synchronised to disk before returning from a create or update of an document.</li>
</ul>
<ul>
<li><code>journalSize</code> (optional, default is a <a class="el" href="CommandLine.html#CommandLineArango">configuration parameter</a>): The maximal size of a journal or datafile. Note that this also limits the maximal size of a single object. Must be at least 1MB.</li>
</ul>
<ul>
<li><code>isSystem</code> (optional, default is <code>false</code>): If true, create a system collection. In this case <em>collection-name</em> should start with an underscore.</li>
</ul>
<p><b>Examples</b><br/>
</p>
<div class="fragment"><pre class="fragment">&gt; curl --data @- -X POST --dump - http://localhost:8529/_api/collection
{ "name" : "UnitTestsCollectionBasics" }
HTTP/1.1 200 OK
content-type: application/json
location: /_api/collection/179665369
{
"name": "UnitTestsCollectionBasics",
"code": 200,
"waitForSync": false,
"id": 179665369,
"status": 3,
"error": false
}
</pre></div> <p><a class="anchor" id="HttpCollectionDelete"></a> <hr/>
<em>DELETE /_api/collection</em> (deletes a collection)<hr/>
<br/>
<code><b>DELETE /_api/collection/<em>collection-identifier</em></b></code></p>
<p>Deletes a collection identified by <em>collection-identified</em>.</p>
<p>If the collection was successfully deleted then, an object is returned with the following attributes:</p>
<ul>
<li><code>error</code>: <code>false</code></li>
</ul>
<ul>
<li><code>id</code>: The identifier of the deleted collection.</li>
</ul>
<p>If the <em>collection-identifier</em> is missing, then a <code>HTTP 400</code> is returned. If the <em>collection-identifier</em> is unknown, then a <code>HTTP 404</code> is returned.</p>
<p>It is possible to specify a name instead of an identifier.</p>
<p><b>Examples</b><br/>
</p>
<p>Using an identifier:</p>
<div class="fragment"><pre class="fragment">&gt; curl -X DELETE --dump - http://localhost:8529/_api/collection/101711425
HTTP/1.1 200 OK
content-type: application/json
{
"code": 200,
"id": 101711425,
"error": false
}
</pre></div><p>Using a name:</p>
<div class="fragment"><pre class="fragment">&gt; curl -X DELETE --dump - http://localhost:8529/_api/collection/UnitTestsCollectionBasics
HTTP/1.1 200 OK
content-type: application/json
{
"code": 200,
"id": 103022145,
"error": false
}
</pre></div> <p><a class="anchor" id="HttpCollectionTruncate"></a> <hr/>
<em>PUT /_api/collection/.../truncate</em> (truncates a collection)<hr/>
<br/>
<code><b>PUT /_api/collection/<em>collection-identifier</em>/truncate</b></code></p>
<p>Removes all documents from the collection, but leaves the indexes intact.</p>
<p><b>Examples</b><br/>
</p>
<div class="fragment"><pre class="fragment">&gt; curl -X PUT --dump - http://localhost:8529/_api/collection/56478340/truncate
HTTP/1.1 200 OK
content-type: application/json
{
"name": "UnitTestsCollectionBasics",
"code": 200,
"id": 56478340,
"status": 3,
"error": false
}
</pre></div> <h3><a class="anchor" id="HttpCollectionReading"></a>
Getting Information about a Collection</h3>
<p><a class="anchor" id="HttpCollectionRead"></a> <hr/>
<em>GET /_api/collection</em> (reads a collection)<hr/>
<br/>
<code><b>GET /_api/collection/<em>collection-identifier</em></b></code></p>
<p>The result is an objects describing the collection with the following attributes:</p>
<ul>
<li><code>id</code>: The identifier of the collection.</li>
</ul>
<ul>
<li><code>name</code>: The name of the collection.</li>
</ul>
<ul>
<li><code>status</code>: The status of the collection as number.<ul>
<li>1: new born collection</li>
<li>2: unloaded</li>
<li>3: loaded</li>
<li>4: in the process of being unloaded</li>
<li>5: deleted</li>
</ul>
</li>
</ul>
<p>Every other status indicates a corrupted collection.</p>
<ul>
<li><code>type</code>: The type of the collection as number.<ul>
<li>2: document collection (normal case)</li>
<li>3: edges collection</li>
</ul>
</li>
</ul>
<p>If the <em>collection-identifier</em> is unknown, then a <code>HTTP 404</code> is returned.</p>
<p>It is possible to specify a name instead of an identifier. In this case the response will contain a field "Location" which contains the correct location.</p>
<p><code><b>GET /_api/collection/<em>collection-identifier</em>/properties</b></code></p>
<p>In addition to the above, the result will always contain the <code>waitForSync</code> and the <code>journalSize</code> properties. This is achieved by forcing a load of the underlying collection.</p>
<ul>
<li><code>waitForSync</code>: If <code>true</code> then creating or changing a document will wait until the data has been synchronised to disk.</li>
</ul>
<ul>
<li><code>journalSize</code>: The maximal size of a journal / datafile.</li>
</ul>
<p><code><b>GET /_api/collection/<em>collection-identifier</em>/count</b></code></p>
<p>In addition to the above, the result also contains the number of documents. Note that this will always load the collection into memory.</p>
<ul>
<li><code>count</code>: The number of documents inside the collection.</li>
</ul>
<p><code><b>GET /_api/collection/<em>collection-identifier</em>/figures</b></code></p>
<p>In addition to the above, the result also contains the number of documents and additional statistical information about the collection. Note that this will always load the collection into memory.</p>
<ul>
<li><code>count</code>: The number of documents inside the collection.</li>
</ul>
<ul>
<li><code>figures.alive.count</code>: The number of living documents.</li>
</ul>
<ul>
<li><code>figures.alive.size</code>: The total size in bytes used by all living documents.</li>
</ul>
<ul>
<li><code>figures.dead.count</code>: The number of dead documents.</li>
</ul>
<ul>
<li><code>figures.dead.size</code>: The total size in bytes used by all dead documents.</li>
</ul>
<ul>
<li><code>figures.dead.deletion</code>: The total number of deletion markers.</li>
</ul>
<ul>
<li><code>figures.datafiles.count</code>: The number of active datafiles.</li>
<li><code>figures.datafiles.fileSize</code>: The total filesize of datafiles.</li>
</ul>
<ul>
<li><code>figures.journals.count</code>: The number of journal files.</li>
<li><code>figures.journals.fileSize</code>: The total filesize of journal files.</li>
</ul>
<ul>
<li><code>journalSize</code>: The maximal size of the journal in bytes.</li>
</ul>
<p>Note: the filesizes of shapes and compactor files are not reported.</p>
<p><b>Examples</b><br/>
</p>
<p>Using an identifier:</p>
<div class="fragment"><pre class="fragment">&gt; curl -X GET --dump - http://localhost:8529/_api/collection/73482
HTTP/1.1 200 OK
content-type: application/json
location: /_api/collection/73482
{
"name": "UnitTestsCollectionBasics",
"code": 200,
"waitForSync": true,
"id": 73482,
"status": 3,
"error": false
}
</pre></div><p>Using a name:</p>
<div class="fragment"><pre class="fragment">&gt; curl -X GET --dump - http://localhost:8529/_api/collection/UnitTestsCollectionBasics
HTTP/1.1 200 OK
content-type: application/json
location: /_api/collection/73482
{
"name": "UnitTestsCollectionBasics",
"code": 200,
"waitForSync": true,
"id": 73482,
"status": 3,
"error": false
}
</pre></div><p>Using an identifier and requesting the number of documents:</p>
<div class="fragment"><pre class="fragment">&gt; curl -X GET --dump - http://localhost:8529/_api/collection/73482/count
HTTP/1.1 200 OK
content-type: application/json
location: /_api/collection/73482/count
{
"name": "UnitTestsCollectionBasics",
"code": 200,
"waitForSync": true,
"id": 73482,
"count": 0,
"status": 3,
"error": false
}
</pre></div><p>Using an identifier and requesting the figures of the collection:</p>
<div class="fragment"><pre class="fragment">&gt; curl -X GET --dump - http://localhost:8529/_api/collection/73482/figures
HTTP/1.1 200 OK
content-type: application/json
location: /_api/collection/73482/figures
{
"name": "UnitTestsCollectionBasics",
"code": 200,
"figures": {
"datafiles": {
"count": 0,
"fileSize": 0
},
"journals": {
"count": 0,
"fileSize": 33554432
},
"alive": {
"size": 0,
"count": 0
},
"dead": {
"size": 2384,
"count": 149
}
},
"waitForSync": true,
"id": 73482,
"journalSize": 134217728,
"count": 0,
"status": 3,
"error": false
}
</pre></div> <p><a class="anchor" id="HttpCollectionReadAll"></a> <hr/>
<em>GET /_api/collection</em> (reads all collections)<hr/>
<br/>
<code><b>GET /_api/collection</b></code></p>
<p>Returns an object with an attribute <code>collections</code> containing a list of all collection descriptions. The same information is also available in the <code>names</code> as hash map with the collection names as keys.</p>
<p><b>Examples</b><br/>
</p>
<p>Return information about all collections:</p>
<div class="fragment"><pre class="fragment">&gt; curl -X GET --dump - http://localhost:8529/_api/collection
HTTP/1.1 200 OK
content-type: application/json
{
"collections": [
{
"name": "employees",
"waitForSync": true,
"id": 64091684,
"status": 3
},
{
"name": "units",
"waitForSync": true,
"id": 63043108,
"status": 3
}
],
"code": 200,
"names": {
"units": {
"name": "units",
"waitForSync": true,
"id": 63043108,
"status": 3
},
"employees": {
"name": "employees",
"waitForSync": true,
"id": 64091684,
"status": 3
}
},
"error": false
}
</pre></div> <h3><a class="anchor" id="HttpCollectionChanging"></a>
Modifying a Collection</h3>
<p><a class="anchor" id="HttpCollectionLoad"></a> <hr/>
<em>PUT /_api/collection/.../load</em> (loads a collection)<hr/>
<br/>
<code><b>PUT /_api/collection/<em>collection-identifier</em>/load</b></code></p>
<p>Loads a collection into memory. On success an object with the following</p>
<ul>
<li><code>id</code>: The identifier of the collection.</li>
</ul>
<ul>
<li><code>name</code>: The name of the collection.</li>
</ul>
<ul>
<li><code>count</code>: The number of documents inside the collection.</li>
</ul>
<ul>
<li><code>status</code>: The status of the collection as number.</li>
</ul>
<p>If the <em>collection-identifier</em> is missing, then a <code>HTTP 400</code> is returned. If the <em>collection-identifier</em> is unknown, then a <code>HTTP 404</code> is returned.</p>
<p>It is possible to specify a name instead of an identifier.</p>
<p><b>Examples</b><br/>
</p>
<div class="fragment"><pre class="fragment">&gt; curl -X PUT --dump - http://localhost:8529/_api/collection/55144253/load
HTTP/1.1 200 OK
content-type: application/json
{
"name": "UnitTestsCollectionBasics",
"code": 200,
"id": 55144253,
"count": 0,
"status": 3,
"error": false
}
</pre></div> <p><a class="anchor" id="HttpCollectionUnload"></a> <hr/>
<em>PUT /_api/collection/.../unload</em> (unloads a collection)<hr/>
<br/>
<code><b>PUT /_api/collection/<em>collection-identifier</em>/unload</b></code></p>
<p>Removes a collection from memory. This call does not delete any documents. You can use the collection afterwards; in which case it will be loaded into memory, again. On success an object with the following</p>
<ul>
<li><code>id</code>: The identifier of the collection.</li>
</ul>
<ul>
<li><code>name</code>: The name of the collection.</li>
</ul>
<ul>
<li><code>status</code>: The status of the collection as number.</li>
</ul>
<p>If the <em>collection-identifier</em> is missing, then a <code>HTTP 400</code> is returned. If the <em>collection-identifier</em> is unknown, then a <code>HTTP 404</code> is returned.</p>
<p><b>Examples</b><br/>
</p>
<div class="fragment"><pre class="fragment">&gt; curl -X PUT --dump - http://localhost:8529/_api/collection/57765693/unload
HTTP/1.1 200 OK
content-type: application/json
{
"name": "UnitTestsCollectionBasics",
"code": 200,
"id": 57765693,
"status": 4,
"error": false
}
</pre></div> <p><a class="anchor" id="HttpCollectionProperties"></a> <hr/>
<em>PUT /_api/collection/.../properties</em> (changes the properties of a collection)<hr/>
<br/>
<code><b>PUT /_api/collection/<em>collection-identifier</em>/properties</b></code></p>
<p>Changes the properties of a collection. Expects an object with the attribute(s)</p>
<ul>
<li><code>waitForSync</code>: If <code>true</code> then creating or changing a document will wait until the data has been synchronised to disk.</li>
</ul>
<p>If returns an object with the attributes</p>
<ul>
<li><code>id</code>: The identifier of the collection.</li>
</ul>
<ul>
<li><code>name</code>: The name of the collection.</li>
</ul>
<ul>
<li><code>waitForSync</code>: The new value.</li>
</ul>
<p><b>Examples</b><br/>
</p>
<div class="fragment"><pre class="fragment">&gt; curl --data @- -X PUT --dump - http://localhost:8529/_api/collection/70109828/properties
{ "waitForSync" : true }
HTTP/1.1 200 OK
content-type: application/json
{
"name": "UnitTestsCollectionBasics",
"code": 200,
"waitForSync": true,
"id": 70109828,
"journalSize": 134217728,
"status": 3,
"error": false
}
</pre></div> <p><a class="anchor" id="HttpCollectionRename"></a> <hr/>
<em>PUT /_api/collection/.../rename</em> (renames a collection)<hr/>
<br/>
<code><b>PUT /_api/collection/<em>collection-identifier</em>/rename</b></code></p>
<p>Renames a collection. Expects an object with the attribute(s)</p>
<ul>
<li><code>name</code>: The new name.</li>
</ul>
<p>If returns an object with the attributes</p>
<ul>
<li><code>id</code>: The identifier of the collection.</li>
</ul>
<ul>
<li><code>name</code>: The new name of the collection.</li>
</ul>
<p><b>Examples</b><br/>
</p>
<div class="fragment"><pre class="fragment">&gt; curl --data @- -X PUT --dump - http://localhost:8529/_api/collection/59230852/rename
{ "name" : "UnitTestsCollectionBasics2" }
HTTP/1.1 200 OK
content-type: application/json
{
"name": "UnitTestsCollectionBasics2",
"code": 200,
"id": 59230852,
"status": 3,
"error": false
}
</pre></div> </div></div>
</div></body></html>
Reference in New Issue View Git Blame Copy Permalink