implemented first() and last()

Documentation/UserManual/SimpleQueries.md

@@ -60,6 +60,14 @@ is specified, the server will pick a reasonable default value.
 @anchor SimpleQueryToArray
 @copydetails JSF_ArangoCollection_prototype_toArray
 
+@CLEARPAGE
+@anchor SimpleQueryFirst
+@copydetails JSF_ArangoCollection_prototype_first
+
+@CLEARPAGE
+@anchor SimpleQueryLast
+@copydetails JSF_ArangoCollection_prototype_last
+
 @CLEARPAGE
 Geo Queries {#SimpleQueriesGeoQueries}
 ======================================

Documentation/UserManual/SimpleQueriesTOC.md

@@ -10,6 +10,8 @@ TOC {#SimpleQueriesTOC}
     - @ref SimpleQueryAny "collection.any"
     - @ref SimpleQueryCollectionCount "collection.count"
     - @ref SimpleQueryToArray "collection.toArray"
+    - @ref SimpleQueryFirst "collection.first"
+    - @ref SimpleQueryLast "collection.last"
   - @ref SimpleQueriesGeoQueries
     - @ref SimpleQueryNear "collection.near"
     - @ref SimpleQueryWithin "collection.within"

arangod/V8Server/v8-query.cpp

@@ -2445,43 +2445,15 @@ static v8::Handle<v8::Value> JS_InEdgesQuery (v8::Arguments const& argv) {
  
 ////////////////////////////////////////////////////////////////////////////////
 /// @brief selects the n first documents in the collection
-///
-/// @FUN{@FA{collection}.first(@FA{count})}
-///
-/// The @FN{first} method returns the n first documents from the collection, in 
-/// order of document insertion/update time. 
-///
-/// If called with the @FA{count} argument, the result is a list of up to
-/// @FA{count} documents. If @FA{count} is bigger than the number of documents
-/// in the collection, then the result will contain as many documents as there
-/// are in the collection.
-/// The result list is ordered, with the "oldest" documents being positioned at 
-/// the beginning of the result list.
-///
-/// When called without an argument, the result is the first document from the
-/// collection. If the collection does not contain any documents, the result 
-/// returned is @LIT{null}.
-///
-/// @EXAMPLES
-///
-/// @code
-/// arangod> db.example.first(1)
-/// [ { "_id" : "example/222716379559", "_rev" : "222716379559", "Hello" : "World" } ]
-/// @endcode
-///
-/// @code
-/// arangod> db.example.first()
-/// { "_id" : "example/222716379559", "_rev" : "222716379559", "Hello" : "World" }
-/// @endcode
 ////////////////////////////////////////////////////////////////////////////////
 
 static v8::Handle<v8::Value> JS_FirstQuery (v8::Arguments const& argv) {
   v8::HandleScope scope;
   
   if (argv.Length() > 1) {
-    TRI_V8_EXCEPTION_USAGE(scope, "first(<count>)");
+    TRI_V8_EXCEPTION_USAGE(scope, "FIRST(<count>)");
   }
-
+  
   int64_t count = 1;
   bool returnList = false;
 
@@ -2501,8 +2473,6 @@ static v8::Handle<v8::Value> JS_FirstQuery (v8::Arguments const& argv) {
   if (col == 0) {
     TRI_V8_EXCEPTION_INTERNAL(scope, "cannot extract collection");
   }
-  
-  TRI_SHARDING_COLLECTION_NOT_YET_IMPLEMENTED(scope, col);
 
   TRI_barrier_t* barrier = 0;
 
@@ -2730,41 +2700,13 @@ static v8::Handle<v8::Value> JS_FulltextQuery (v8::Arguments const& argv) {
 
 ////////////////////////////////////////////////////////////////////////////////
 /// @brief selects the n last documents in the collection
-///
-/// @FUN{@FA{collection}.last(@FA{count})}
-///
-/// The @FN{first} method returns the n last documents from the collection, in 
-/// order of document insertion/update time. 
-///
-/// If called with the @FA{count} argument, the result is a list of up to
-/// @FA{count} documents. If @FA{count} is bigger than the number of documents
-/// in the collection, then the result will contain as many documents as there
-/// are in the collection.
-/// The result list is ordered, with the "latest" documents being positioned at 
-/// the beginning of the result list.
-///
-/// When called without an argument, the result is the last document from the
-/// collection. If the collection does not contain any documents, the result 
-/// returned is @LIT{null}.
-///
-/// @EXAMPLES
-///
-/// @code
-/// arangod> db.example.last(1)
-/// [ { "_id" : "example/222716379559", "_rev" : "222716379559", "Hello" : "World" } ]
-/// @endcode
-///
-/// @code
-/// arangod> db.example.last()
-/// { "_id" : "example/222716379559", "_rev" : "222716379559", "Hello" : "World" }
-/// @endcode
 ////////////////////////////////////////////////////////////////////////////////
 
 static v8::Handle<v8::Value> JS_LastQuery (v8::Arguments const& argv) {
   v8::HandleScope scope;
   
   if (argv.Length() > 1) {
-    TRI_V8_EXCEPTION_USAGE(scope, "last(<count>)");
+    TRI_V8_EXCEPTION_USAGE(scope, "LAST(<count>)");
   }
 
   int64_t count = 1;
@@ -3129,10 +3071,10 @@ void TRI_InitV8Queries (v8::Handle<v8::Context> context) {
   TRI_AddMethodVocbase(rt, "BY_EXAMPLE_SKIPLIST", JS_ByExampleSkiplist);
   TRI_AddMethodVocbase(rt, "checksum", JS_ChecksumCollection);
   TRI_AddMethodVocbase(rt, "edges", JS_EdgesQuery);
-  TRI_AddMethodVocbase(rt, "first", JS_FirstQuery);
+  TRI_AddMethodVocbase(rt, "FIRST", JS_FirstQuery);
   TRI_AddMethodVocbase(rt, "FULLTEXT", JS_FulltextQuery);
   TRI_AddMethodVocbase(rt, "inEdges", JS_InEdgesQuery);
-  TRI_AddMethodVocbase(rt, "last", JS_LastQuery);
+  TRI_AddMethodVocbase(rt, "LAST", JS_LastQuery);
   TRI_AddMethodVocbase(rt, "NEAR", JS_NearQuery);
 
   // internal method. not intended to be used by end-users

js/actions/api-simple.js

@@ -1031,19 +1031,13 @@ actions.defineHttp({
 /// @fn JSA_put_api_simple_first
 /// @brief returns the first document(s) of a collection
 ///
-/// @RESTHEADER{PUT /_api/simple/first,executes simple query first}
+/// @RESTHEADER{PUT /_api/simple/first,returns the first document(s) of a collection}
 ///
 /// @RESTBODYPARAM{query,json,required}
 /// Contains the query.
 ///
 /// @RESTDESCRIPTION
 ///
-/// The request body must be a JSON object with the following attributes:
-/// - `collection`: the name of the collection
-/// 
-/// - `count`: the number of documents to return at most. Specifiying count is 
-///   optional. If it is not specified, it defaults to 1.
-///
 /// This will return the first documents from the collection, in the order of
 /// insertion/update time. When the `count` argument is supplied, the result
 /// will be a list of documents, with the "oldest" document being first in the
@@ -1051,6 +1045,15 @@ actions.defineHttp({
 /// If the `count` argument is not supplied, the result is the "oldest" document
 /// of the collection, or `null` if the collection is empty.
 ///
+/// The request body must be a JSON object with the following attributes:
+/// - `collection`: the name of the collection
+/// 
+/// - `count`: the number of documents to return at most. Specifiying count is 
+///   optional. If it is not specified, it defaults to 1.
+///
+/// Note: this method is not supported for sharded collections with more than 
+/// one shard.
+/// 
 /// @RESTRETURNCODES
 ///
 /// @RESTRETURNCODE{200}
@@ -1146,27 +1149,30 @@ actions.defineHttp({
 /// @fn JSA_put_api_simple_last
 /// @brief returns the last document(s) of a collection
 ///
-/// @RESTHEADER{PUT /_api/simple/last,executes simple query last}
+/// @RESTHEADER{PUT /_api/simple/last,returns the last document(s) of a collection}
 ///
 /// @RESTBODYPARAM{query,json,required}
 /// Contains the query.
 ///
 /// @RESTDESCRIPTION
 ///
+/// This will return the last documents from the collection, in the order of
+/// insertion/update time. When the `count` argument is supplied, the result
+/// will be a list of documents, with the "latest" document being first in the
+/// result list.
+///
 /// The request body must be a JSON object with the following attributes:
 /// - `collection`: the name of the collection
 /// 
 /// - `count`: the number of documents to return at most. Specifiying count is 
 ///   optional. If it is not specified, it defaults to 1.
 ///
-/// This will return the last documents from the collection, in the order of
-/// insertion/update time. When the `count` argument is supplied, the result
-/// will be a list of documents, with the "latest" document being first in the
-/// result list.
-///
 /// If the `count` argument is not supplied, the result is the "latest" document
 /// of the collection, or `null` if the collection is empty.
 ///
+/// Note: this method is not supported for sharded collections with more than
+/// one shard.
+/// 
 /// @RESTRETURNCODES
 ///
 /// @RESTRETURNCODE{200}

js/server/modules/org/arangodb/arango-collection.js

@@ -253,6 +253,161 @@ ArangoCollection.prototype.any = function () {
   return this.ANY();
 };
 
+////////////////////////////////////////////////////////////////////////////////
+/// @brief selects the n first documents in the collection
+///
+/// @FUN{@FA{collection}.first(@FA{count})}
+///
+/// The @FN{first} method returns the n first documents from the collection, in 
+/// order of document insertion/update time. 
+///
+/// If called with the @FA{count} argument, the result is a list of up to
+/// @FA{count} documents. If @FA{count} is bigger than the number of documents
+/// in the collection, then the result will contain as many documents as there
+/// are in the collection.
+/// The result list is ordered, with the "oldest" documents being positioned at 
+/// the beginning of the result list.
+///
+/// When called without an argument, the result is the first document from the
+/// collection. If the collection does not contain any documents, the result 
+/// returned is @LIT{null}.
+///
+/// Note: this method is not supported on sharded collections with more than
+/// one shard.
+///
+/// @EXAMPLES
+///
+/// @code
+/// arangod> db.example.first(1)
+/// [ { "_id" : "example/222716379559", "_rev" : "222716379559", "Hello" : "World" } ]
+/// @endcode
+///
+/// @code
+/// arangod> db.example.first()
+/// { "_id" : "example/222716379559", "_rev" : "222716379559", "Hello" : "World" }
+/// @endcode
+////////////////////////////////////////////////////////////////////////////////
+
+ArangoCollection.prototype.first = function (count) {
+  var cluster = require("org/arangodb/cluster");
+
+  if (cluster.isCoordinator()) {
+    var dbName = require("internal").db._name();
+    var shards = cluster.shardList(dbName, this.name());
+
+    if (shards.length !== 1) {
+      var err = new ArangoError();
+      err.errorNum = internal.errors.ERROR_NOT_IMPLEMENTED.code;
+      err.errorMessage = "operation is not supported in clustered collections with multiple shards";
+
+      throw err;
+    }
+
+    var coord = { coordTransactionID: ArangoClusterInfo.uniqid() };
+    var options = { coordTransactionID: coord.coordTransactionID, timeout: 360 };
+    var shard = shards[0];
+
+    ArangoClusterComm.asyncRequest("put", 
+                                   "shard:" + shard, 
+                                   dbName, 
+                                   "/_api/simple/first", 
+                                   JSON.stringify({ 
+                                     collection: shard,
+                                     count: count 
+                                   }), 
+                                   { }, 
+                                   options);
+
+    var results = cluster.wait(coord, shards), i;
+
+    if (results.length) {
+      var body = JSON.parse(results[i].body);
+      return body.result || null;
+    }
+    return null;
+  }
+  else {
+    return this.FIRST(count);
+  } 
+};
+
+////////////////////////////////////////////////////////////////////////////////
+/// @brief selects the n last documents in the collection
+///
+/// @FUN{@FA{collection}.last(@FA{count})}
+///
+/// The @FN{first} method returns the n last documents from the collection, in 
+/// order of document insertion/update time. 
+///
+/// If called with the @FA{count} argument, the result is a list of up to
+/// @FA{count} documents. If @FA{count} is bigger than the number of documents
+/// in the collection, then the result will contain as many documents as there
+/// are in the collection.
+/// The result list is ordered, with the "latest" documents being positioned at 
+/// the beginning of the result list.
+///
+/// When called without an argument, the result is the last document from the
+/// collection. If the collection does not contain any documents, the result 
+/// returned is @LIT{null}.
+///
+/// Note: this method is not supported on sharded collections with more than
+/// one shard.
+///
+/// @EXAMPLES
+///
+/// @code
+/// arangod> db.example.last(1)
+/// [ { "_id" : "example/222716379559", "_rev" : "222716379559", "Hello" : "World" } ]
+/// @endcode
+///
+/// @code
+/// arangod> db.example.last()
+/// { "_id" : "example/222716379559", "_rev" : "222716379559", "Hello" : "World" }
+/// @endcode
+////////////////////////////////////////////////////////////////////////////////
+
+ArangoCollection.prototype.last = function (count) {
+  var cluster = require("org/arangodb/cluster");
+
+  if (cluster.isCoordinator()) {
+    var dbName = require("internal").db._name();
+    var shards = cluster.shardList(dbName, this.name());
+
+    if (shards.length !== 1) {
+      var err = new ArangoError();
+      err.errorNum = internal.errors.ERROR_NOT_IMPLEMENTED.code;
+      err.errorMessage = "operation is not supported in clustered collections with multiple shards";
+
+      throw err;
+    }
+
+    var coord = { coordTransactionID: ArangoClusterInfo.uniqid() };
+    var options = { coordTransactionID: coord.coordTransactionID, timeout: 360 };
+    var shard = shards[0];
+
+    ArangoClusterComm.asyncRequest("put", 
+                                   "shard:" + shard, 
+                                   dbName, 
+                                   "/_api/simple/last", 
+                                   JSON.stringify({ 
+                                     collection: shard,
+                                     count: count 
+                                   }), 
+                                   { }, 
+                                   options);
+
+    var results = cluster.wait(coord, shards), i;
+
+    if (results.length) {
+      var body = JSON.parse(results[i].body);
+      return body.result || null;
+    }
+  }
+  else {
+    return this.LAST(count);
+  } 
+};
+
 ////////////////////////////////////////////////////////////////////////////////
 /// @brief constructs a query-by-example for a collection
 ///