From 18c41fa0089b8459f86aa75028fce0ecdbe204f2 Mon Sep 17 00:00:00 2001 From: jsteemann Date: Tue, 22 Dec 2015 20:06:37 +0100 Subject: [PATCH] updated CHANGELOG --- CHANGELOG | 52 +++++++++++++++++++ .../Users/NewFeatures/NewFeatures28.mdpp | 5 ++ .../Users/Upgrading/UpgradingChanges28.mdpp | 51 ++++++++++++++++++ 3 files changed, 108 insertions(+) diff --git a/CHANGELOG b/CHANGELOG index df477df835..84e15a5093 100644 --- a/CHANGELOG +++ b/CHANGELOG @@ -7,6 +7,58 @@ v3.0.0 (XXXX-XX-XX) v2.8.0 (XXXX-XX-XX) ------------------- +* AQL query optimizer now converts `LENGTH(collection-name)` to an optimized + expression that returns the number of documents in a collection + +* adjusted the behavior of the expansion (`[*]`) operator in AQL for non-array values + + In ArangoDB 2.8, calling the expansion operator on a non-array value will always + return an empty array. Previous versions of ArangoDB expanded non-array values by + calling the `TO_ARRAY()` function for the value, which for example returned an + array with a single value for boolean, numeric and string input values, and an array + with the object's values for an object input value. This behavior was inconsistent + with how the expansion operator works for the array indexes in 2.8, so the behavior + is now unified: + + - if the left-hand side operand of `[*]` is an array, the array will be returned as + is when calling `[*]` on it + - if the left-hand side operand of `[*]` is not an array, an empty array will be + returned by `[*]` + + AQL queries that rely on the old behavior can be changed by either calling `TO_ARRAY` + explicitly or by using the `[*]` at the correct position. + + The following example query will change its result in 2.8 compared to 2.7: + + LET values = "foo" RETURN values[*] + + In 2.7 the query has returned the array `[ "foo" ]`, but in 2.8 it will return an + empty array `[ ]`. To make it return the array `[ "foo" ]` again, an explicit + `TO_ARRAY` function call is needed in 2.8 (which in this case allows the removal + of the `[*]` operator altogether). This also works in 2.7: + + LET values = "foo" RETURN TO_ARRAY(values) + + Another example: + + LET values = [ { name: "foo" }, { name: "bar" } ] + RETURN values[*].name[*] + + The above returned `[ [ "foo" ], [ "bar" ] ] in 2.7. In 2.8 it will return + `[ [ ], [ ] ]`, because the value of `name` is not an array. To change the results + to the 2.7 style, the query can be changed to + + LET values = [ { name: "foo" }, { name: "bar" } ] + RETURN values[* RETURN TO_ARRAY(CURRENT.name)] + + The above also works in 2.7. + The following types of queries won't change: + + LET values = [ 1, 2, 3 ] RETURN values[*] + LET values = [ { name: "foo" }, { name: "bar" } ] RETURN values[*].name + LET values = [ { names: [ "foo", "bar" ] }, { names: [ "baz" ] } ] RETURN values[*].names[*] + LET values = [ { names: [ "foo", "bar" ] }, { names: [ "baz" ] } ] RETURN values[*].names[**] + * slightly adjusted V8 garbage collection strategy so that collection eventually happens in all contexts that hold V8 external references to documents and collections. diff --git a/Documentation/Books/Users/NewFeatures/NewFeatures28.mdpp b/Documentation/Books/Users/NewFeatures/NewFeatures28.mdpp index 2bab003446..86470336ed 100644 --- a/Documentation/Books/Users/NewFeatures/NewFeatures28.mdpp +++ b/Documentation/Books/Users/NewFeatures/NewFeatures28.mdpp @@ -192,6 +192,11 @@ The following AQL functions have been added in 2.8: a human-readable explanation of AQL queries. This function is a shorthand for `require("org/arangodb/aql/explainer").explain(query)`. +* the AQL query optimizer now automatically converts `LENGTH(collection-name)` to an optimized + expression that returns the number of documents in a collection. Previous versions of + ArangoDB returned a warning when using this expression and also enumerated all documents + in the collection, which was inefficient. + * improved performance of skipping over many documents in an AQL query when no indexes and no filters are used, e.g. diff --git a/Documentation/Books/Users/Upgrading/UpgradingChanges28.mdpp b/Documentation/Books/Users/Upgrading/UpgradingChanges28.mdpp index 1223245588..2ea444f9bb 100644 --- a/Documentation/Books/Users/Upgrading/UpgradingChanges28.mdpp +++ b/Documentation/Books/Users/Upgrading/UpgradingChanges28.mdpp @@ -34,6 +34,57 @@ exceptions when invalid parameters are passed that may have not led to exceptions in previous versions. +Additionally, the expansion (`[*]`) operator in AQL has changed its behavior when +handling non-array values: + +In ArangoDB 2.8, calling the expansion operator on a non-array value will always +return an empty array. Previous versions of ArangoDB expanded non-array values by +calling the `TO_ARRAY()` function for the value, which for example returned an +array with a single value for boolean, numeric and string input values, and an array +with the object's values for an object input value. This behavior was inconsistent +with how the expansion operator works for the array indexes in 2.8, so the behavior +is now unified: + +- if the left-hand side operand of `[*]` is an array, the array will be returned as + is when calling `[*]` on it +- if the left-hand side operand of `[*]` is not an array, an empty array will be + returned by `[*]` + +AQL queries that rely on the old behavior can be changed by either calling `TO_ARRAY` +explicitly or by using the `[*]` at the correct position. + +The following example query will change its result in 2.8 compared to 2.7: + + LET values = "foo" RETURN values[*] + +In 2.7 the query has returned the array `[ "foo" ]`, but in 2.8 it will return an +empty array `[ ]`. To make it return the array `[ "foo" ]` again, an explicit +`TO_ARRAY` function call is needed in 2.8 (which in this case allows the removal +of the `[*]` operator altogether). This also works in 2.7: + + LET values = "foo" RETURN TO_ARRAY(values) + +Another example: + + LET values = [ { name: "foo" }, { name: "bar" } ] + RETURN values[*].name[*] + +The above returned `[ [ "foo" ], [ "bar" ] ] in 2.7. In 2.8 it will return +`[ [ ], [ ] ]`, because the value of `name` is not an array. To change the results +to the 2.7 style, the query can be changed to + + LET values = [ { name: "foo" }, { name: "bar" } ] + RETURN values[* RETURN TO_ARRAY(CURRENT.name)] + +The above also works in 2.7. +The following types of queries won't change: + + LET values = [ 1, 2, 3 ] RETURN values[*] + LET values = [ { name: "foo" }, { name: "bar" } ] RETURN values[*].name + LET values = [ { names: [ "foo", "bar" ] }, { names: [ "baz" ] } ] RETURN values[*].names[*] + LET values = [ { names: [ "foo", "bar" ] }, { names: [ "baz" ] } ] RETURN values[*].names[**] + + !SUBSECTION Deadlock handling Client applications should be prepared to handle error 29 (`deadlock detected`)