updated CHANGELOG

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.

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.
 

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`)