Incompatible changes in ArangoDB 2.8

It is recommended to check the following list of incompatible changes beforeupgrading to ArangoDB 2.8, and adjust any client programs if necessary.

AQL

Keywords added

The following AQL keywords were added in ArangoDB 2.8:

  • GRAPH
  • OUTBOUND
  • INBOUND
  • ANY
  • ALL
  • NONE
  • AGGREGATEUsage of these keywords for collection names, variable names or attribute namesin AQL queries will not be possible without quoting. For example, the followingAQL query will still work as it uses a quoted collection name and a quotedattribute name:
  1. FOR doc IN `OUTBOUND`
  2.   RETURN doc.`any`

Changed behavior

The AQL functions NEAR and WITHIN now have stricter validationsfor their input parameters limit, radius and distance. They may now throwexceptions when invalid parameters are passed that may have not ledto exceptions in previous versions.

Additionally, the expansion ([*]) operator in AQL has changed its behavior whenhandling non-array values:

In ArangoDB 2.8, calling the expansion operator on a non-array value will alwaysreturn an empty array. Previous versions of ArangoDB expanded non-array values bycalling 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 arraywith the object’s values for an object input value. This behavior was inconsistentwith how the expansion operator works for the array indexes in 2.8, so the behavioris 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 bereturned by []AQL queries that rely on the old behavior can be changed by either calling TO_ARRAYexplicitly or by using the [*] at the correct position.

The following example query will change its result in 2.8 compared to 2.7:

  1. LET values = "foo" RETURN values[*]

In 2.7 the query has returned the array [ "foo" ], but in 2.8 it will return anempty array [ ]. To make it return the array [ "foo" ] again, an explicitTO_ARRAY function call is needed in 2.8 (which in this case allows the removalof the [*] operator altogether). This also works in 2.7:

  1. LET values = "foo" RETURN TO_ARRAY(values)

Another example:

  1. LET values = [ { name: "foo" }, { name: "bar" } ]
  2. 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 resultsto the 2.7 style, the query can be changed to

  1. LET values = [ { name: "foo" }, { name: "bar" } ]
  2. RETURN values[* RETURN TO_ARRAY(CURRENT.name)]

The above also works in 2.7. The following types of queries won’t change:

  1. LET values = [ 1, 2, 3 ] RETURN values[*] 
  2. LET values = [ { name: "foo" }, { name: "bar" } ] RETURN values[*].name
  3. LET values = [ { names: [ "foo", "bar" ] }, { names: [ "baz" ] } ] RETURN values[*].names[*]
  4. LET values = [ { names: [ "foo", "bar" ] }, { names: [ "baz" ] } ] RETURN values[*].names[**]

Deadlock handling

Client applications should be prepared to handle error 29 (deadlock detected)that ArangoDB may now throw when it detects a deadlock across multiple transactions.When a client application receives error 29, it should retry the operation thatfailed.

The error can only occur for AQL queries or user transactions that involve more than a single collection.

Optimizer

The AQL execution node type IndexRangeNode was replaced with a new more capableexecution node type IndexNode. That means in execution plan explain output therewill be no more IndexRangeNodes but only IndexNode. This affects explain outputthat can be retrieved via require("org/arangodb/aql/explainer").explain(query),db._explain(query), and the HTTP query explain API.

The optimizer rule that makes AQL queries actually use indexes was also renamedfrom use-index-range to use-indexes. Again this affects explain outputthat can be retrieved via require("org/arangodb/aql/explainer").explain(query),db._explain(query), and the HTTP query explain API.

The query optimizer rule remove-collect-into was renamed to remove-collect-variables.This affects explain output that can be retrieved via require("org/arangodb/aql/explainer").explain(query),db._explain(query), and the HTTP query explain API.

HTTP API

When a server-side operation got canceled due to an explicit client cancel request via HTTP DELETE /_api/job, previous versions of ArangoDB returned an HTTP statuscode of 408 (request timeout) for the response of the canceled operation.

The HTTP return code 408 has caused problems with some client applications. Some browsers (e.g. Chrome) handled a 408 response by resending the original request, which is the opposite of what is desired when a job should be canceled.

Therefore ArangoDB will return HTTP status code 410 (gone) for canceled operationsfrom version 2.8 on.

Foxx

Model and Repository

Due to compatibility issues the Model and Repository types are no longer implemented as ES2015 classes.

The pre-2.7 “extend” style subclassing is supported again and will not emit any deprecation warnings.

  1. var Foxx = require('org/arangodb/foxx');
  2. var MyModel = Foxx.Model.extend({
  3.   // ...
  4.   schema: {/* ... */}
  5. });

Module resolution

The behavior of the JavaScript module resolution used by the require function hasbeen modified to improve compatibility with modules written for Node.js.

Specifically

  • absolute paths (e.g. /some/absolute/path) are now always interpreted as absolutefile system paths, relative to the file system root

  • global names (e.g. global/name) are now first intepreted as references to modulesresiding in a relevant node_modules folder, a built-in module or a matchingdocument in the internal _modules collection, and only resolved to local file pathsif no other match is found

Previously the two formats were treated interchangeably and would be resolved to localfile paths first, leading to problems when local files used the same names as othermodules (e.g. a local file chai.js would cause problems when trying to load thechai module installed in node_modules).

For more information see the blog announcement of this changeand the upgrade guide.

Module org/arangodb/request

The module now always returns response bodies, even for error responses. In versionsprior to 2.8 the module would silently drop response bodies if the response headerindicated an error.

The old behavior of not returning bodies for error responses can be restored byexplicitly setting the option returnBodyOnError to false:

  1. let response = request({
  2.   //...
  3.   returnBodyOnError: false
  4. });

Garbage collection

The V8 garbage collection strategy was slightly adjusted so that it eventuallyhappens in all V8 contexts that hold V8 external objects (references to ArangoDBdocuments and collections). This enables a better cleanup of these resources andprevents other processes such as compaction being stalled while waiting for theseresources to be released.

In this context the default value for the JavaScript garbage collection frequency(—javascript.gc-frequency) was also increased from 10 seconds to 15 seconds, as less internal operations in ArangoDB are carried out in JavaScript.

Client tools

arangodump will now fail by default when trying to dump edges thatrefer to already dropped collections. This can be circumvented by specifying the option —force true when invoking arangodump