From 9f69aae986208bce1646d72ad5b42fdd52ffe902 Mon Sep 17 00:00:00 2001 From: Jan Steemann Date: Fri, 17 Jan 2014 22:39:04 +0100 Subject: [PATCH] issue #736: AQL function to parse collection and key from document handle --- CHANGELOG | 2 + Documentation/UserManual/Aql.md | 13 ++++ arangod/Ahuacatl/ahuacatl-functions.c | 1 + js/server/modules/org/arangodb/ahuacatl.js | 31 ++++++++ js/server/tests/ahuacatl-functions.js | 84 ++++++++++++++++++++++ 5 files changed, 131 insertions(+) diff --git a/CHANGELOG b/CHANGELOG index 4ed039a6a4..345fc3bc8d 100644 --- a/CHANGELOG +++ b/CHANGELOG @@ -3,6 +3,8 @@ v1.5.0 (XXXX-XX-XX) * issue #738: added __dirname, __filename pseudo-globals. Fixes #733. (@by pluma) +* issue #736: AQL function to parse collection and key from document handle + * allow `\n` (as well as `\r\n`) as line terminator in batch requests sent to `/_api/batch` HTTP API. diff --git a/Documentation/UserManual/Aql.md b/Documentation/UserManual/Aql.md index 7495f60647..61dc1c2ab2 100644 --- a/Documentation/UserManual/Aql.md +++ b/Documentation/UserManual/Aql.md @@ -1259,6 +1259,19 @@ AQL supports the following functions to operate on document values: RETURN KEEP(doc, 'firstname', 'name', 'likes') +- @FN{PARSE_IDENTIFIER(@FA{document-handle})}: parses the document handle specified in + @FA{document-handle} and returns a the handle's individual parts a separate attributes. + This function can be used to easily determine the collection name and key from a given document. + The @FA{document-handle} can either be a regular document from a collection, or a document + identifier string (e.g. `_users/1234`). Passing either a non-string or a non-document or a + document without an `_id` attribute will result in an error. + + RETURN PARSE_IDENTIFIER('_users/my-user') + [ { "collection" : "_users", "key" : "my-user" } ] + + RETURN PARSE_IDENTIFIER({ "_id" : "mycollection/mykey", "value" : "some value" }) + [ { "collection" : "mycollection", "key" : "mykey" } ] + @subsubsection AqlFunctionsGeo Geo functions AQL offers the following functions to filter data based on geo indexes: diff --git a/arangod/Ahuacatl/ahuacatl-functions.c b/arangod/Ahuacatl/ahuacatl-functions.c index 0ccf47ebf1..5cd4c90bc9 100644 --- a/arangod/Ahuacatl/ahuacatl-functions.c +++ b/arangod/Ahuacatl/ahuacatl-functions.c @@ -714,6 +714,7 @@ TRI_associative_pointer_t* TRI_CreateFunctionsAql (void) { REGISTER_FUNCTION("NOT_NULL", "NOT_NULL", true, false, ".|+", NULL); REGISTER_FUNCTION("FIRST_LIST", "FIRST_LIST", true, false, ".|+", NULL); REGISTER_FUNCTION("FIRST_DOCUMENT", "FIRST_DOCUMENT", true, false, ".|+", NULL); + REGISTER_FUNCTION("PARSE_IDENTIFIER", "PARSE_IDENTIFIER", true, false, ".", NULL); if (! result) { TRI_FreeFunctionsAql(functions); diff --git a/js/server/modules/org/arangodb/ahuacatl.js b/js/server/modules/org/arangodb/ahuacatl.js index 6b7cc3fc29..c601ed9526 100644 --- a/js/server/modules/org/arangodb/ahuacatl.js +++ b/js/server/modules/org/arangodb/ahuacatl.js @@ -3254,6 +3254,36 @@ function FIRST_DOCUMENT () { return null; } +//////////////////////////////////////////////////////////////////////////////// +/// @brief return the parts of a document identifier separately +/// +/// returns a document with the attributes `collection` and `key` or fails if +/// the individual parts cannot be determined. +//////////////////////////////////////////////////////////////////////////////// + +function PARSE_IDENTIFIER (value) { + "use strict"; + + if (TYPEWEIGHT(value) === TYPEWEIGHT_STRING) { + var parts = value.split('/'); + if (parts.length === 2) { + return { + collection: parts[0], + key: parts[1] + }; + } + // fall through intentional + } + else if (TYPEWEIGHT(value) === TYPEWEIGHT_DOCUMENT) { + if (value.hasOwnProperty('_id')) { + return PARSE_IDENTIFIER(value._id); + } + // fall through intentional + } + + THROW(INTERNAL.errors.ERROR_QUERY_FUNCTION_ARGUMENT_TYPE_MISMATCH, "PARSE_IDENTIFIER"); +} + //////////////////////////////////////////////////////////////////////////////// /// @brief check whether a document has a specific attribute //////////////////////////////////////////////////////////////////////////////// @@ -4048,6 +4078,7 @@ exports.GRAPH_NEIGHBORS = GRAPH_NEIGHBORS; exports.NOT_NULL = NOT_NULL; exports.FIRST_LIST = FIRST_LIST; exports.FIRST_DOCUMENT = FIRST_DOCUMENT; +exports.PARSE_IDENTIFIER = PARSE_IDENTIFIER; exports.HAS = HAS; exports.ATTRIBUTES = ATTRIBUTES; exports.UNSET = UNSET; diff --git a/js/server/tests/ahuacatl-functions.js b/js/server/tests/ahuacatl-functions.js index 8d6e6f12bc..78928f3467 100644 --- a/js/server/tests/ahuacatl-functions.js +++ b/js/server/tests/ahuacatl-functions.js @@ -1869,6 +1869,90 @@ function ahuacatlFunctionsTestSuite () { assertEqual(expected, actual); }, +//////////////////////////////////////////////////////////////////////////////// +/// @brief test parse identifier function +//////////////////////////////////////////////////////////////////////////////// + + testParseIdentifier : function () { + var actual; + + actual = getQueryResults("RETURN PARSE_IDENTIFIER('foo/bar')"); + assertEqual([ { collection: 'foo', key: 'bar' } ], actual); + + actual = getQueryResults("RETURN PARSE_IDENTIFIER('this-is-a-collection-name/and-this-is-an-id')"); + assertEqual([ { collection: 'this-is-a-collection-name', key: 'and-this-is-an-id' } ], actual); + + actual = getQueryResults("RETURN PARSE_IDENTIFIER('MY_COLLECTION/MY_DOC')"); + assertEqual([ { collection: 'MY_COLLECTION', key: 'MY_DOC' } ], actual); + + actual = getQueryResults("RETURN PARSE_IDENTIFIER('_users/AbC')"); + assertEqual([ { collection: '_users', key: 'AbC' } ], actual); + + actual = getQueryResults("RETURN PARSE_IDENTIFIER({ _id: 'foo/bar', value: 'baz' })"); + assertEqual([ { collection: 'foo', key: 'bar' } ], actual); + + actual = getQueryResults("RETURN PARSE_IDENTIFIER({ ignore: true, _id: '_system/VALUE', value: 'baz' })"); + assertEqual([ { collection: '_system', key: 'VALUE' } ], actual); + + actual = getQueryResults("RETURN PARSE_IDENTIFIER({ value: 123, _id: 'Some-Odd-Collection/THIS_IS_THE_KEY' })"); + assertEqual([ { collection: 'Some-Odd-Collection', key: 'THIS_IS_THE_KEY' } ], actual); + }, + +//////////////////////////////////////////////////////////////////////////////// +/// @brief test parse identifier function +//////////////////////////////////////////////////////////////////////////////// + + testParseIdentifierCollection : function () { + var cn = "UnitTestsAhuacatlFunctions"; + + internal.db._drop(cn); + var cx = internal.db._create(cn); + cx.save({ "title" : "123", "value" : 456, "_key" : "foobar" }); + cx.save({ "_key" : "so-this-is-it", "title" : "nada", "value" : 123 }); + + var expected, actual; + + expected = [ { collection: cn, key: "foobar" } ]; + actual = getQueryResults("RETURN PARSE_IDENTIFIER(DOCUMENT(CONCAT(@cn, '/', @key)))", { cn: cn, key: "foobar" }); + assertEqual(expected, actual); + + expected = [ { collection: cn, key: "foobar" } ]; + actual = getQueryResults("RETURN PARSE_IDENTIFIER(DOCUMENT(CONCAT(@cn, '/', @key)))", { cn: cn, key: "foobar" }); + assertEqual(expected, actual); + + expected = [ { collection: cn, key: "foobar" } ]; + actual = getQueryResults("RETURN PARSE_IDENTIFIER(DOCUMENT(CONCAT(@cn, '/', 'foobar')))", { cn: cn }); + assertEqual(expected, actual); + + expected = [ { collection: cn, key: "foobar" } ]; + actual = getQueryResults("RETURN PARSE_IDENTIFIER(DOCUMENT([ @key ])[0])", { key: "UnitTestsAhuacatlFunctions/foobar" }); + assertEqual(expected, actual); + + expected = [ { collection: cn, key: "so-this-is-it" } ]; + actual = getQueryResults("RETURN PARSE_IDENTIFIER(DOCUMENT([ 'UnitTestsAhuacatlFunctions/so-this-is-it' ])[0])"); + assertEqual(expected, actual); + + internal.db._drop(cn); + }, + +//////////////////////////////////////////////////////////////////////////////// +/// @brief test parse identifier function +//////////////////////////////////////////////////////////////////////////////// + + testParseIdentifier : function () { + assertQueryError(errors.ERROR_QUERY_FUNCTION_ARGUMENT_NUMBER_MISMATCH.code, "RETURN PARSE_IDENTIFIER()"); + assertQueryError(errors.ERROR_QUERY_FUNCTION_ARGUMENT_NUMBER_MISMATCH.code, "RETURN PARSE_IDENTIFIER('foo', 'bar')"); + assertQueryError(errors.ERROR_QUERY_FUNCTION_ARGUMENT_TYPE_MISMATCH.code, "RETURN PARSE_IDENTIFIER(null)"); + assertQueryError(errors.ERROR_QUERY_FUNCTION_ARGUMENT_TYPE_MISMATCH.code, "RETURN PARSE_IDENTIFIER(false)"); + assertQueryError(errors.ERROR_QUERY_FUNCTION_ARGUMENT_TYPE_MISMATCH.code, "RETURN PARSE_IDENTIFIER(3)"); + assertQueryError(errors.ERROR_QUERY_FUNCTION_ARGUMENT_TYPE_MISMATCH.code, "RETURN PARSE_IDENTIFIER(\"foo\")"); + assertQueryError(errors.ERROR_QUERY_FUNCTION_ARGUMENT_TYPE_MISMATCH.code, "RETURN PARSE_IDENTIFIER('foo bar')"); + assertQueryError(errors.ERROR_QUERY_FUNCTION_ARGUMENT_TYPE_MISMATCH.code, "RETURN PARSE_IDENTIFIER('foo/bar/baz')"); + assertQueryError(errors.ERROR_QUERY_FUNCTION_ARGUMENT_TYPE_MISMATCH.code, "RETURN PARSE_IDENTIFIER([ ])"); + assertQueryError(errors.ERROR_QUERY_FUNCTION_ARGUMENT_TYPE_MISMATCH.code, "RETURN PARSE_IDENTIFIER({ })"); + assertQueryError(errors.ERROR_QUERY_FUNCTION_ARGUMENT_TYPE_MISMATCH.code, "RETURN PARSE_IDENTIFIER({ foo: 'bar' })"); + }, + //////////////////////////////////////////////////////////////////////////////// /// @brief test document function ////////////////////////////////////////////////////////////////////////////////