Incompatible changes in ArangoDB 3.1

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

Communication Layer

The internal commication layer is now based on Boost ASIO. A few optionsregarding threads and communication have been changed.

There are no longer two different threads pools (—scheduler.threads and—server.threads). The option —scheduler.threads has been removed. Thenumber of threads is now controlled by the option —server.threads only.By default —server.threads is set to the number of hyper-cores.

As a consequence of the change, the following (hidden) startup options havebeen removed:

• —server.extra-threads
• —server.aql-threads
• —server.backend
• —server.show-backends
• —server.thread-affinity

AQL

The behavior of the AQL array comparison operators has changed for empty arrays:

• ALL and ANY now always return false when the left-hand operand is anempty array. The behavior for non-empty arrays does not change:
  • [] ALL == 1 will return false
  • [1] ALL == 1 will return true
  • [1, 2] ALL == 1 will return false
  • [2, 2] ALL == 1 will return false
  • [] ANY == 1 will return false
  • [1] ANY == 1 will return true
  • [1, 2] ANY == 1 will return true
  • [2, 2] ANY == 1 will return false
• NONE now always returns true when the left-hand operand is an empty array.The behavior for non-empty arrays does not change:
  • [] NONE == 1 will return true
  • [1] NONE == 1 will return false
  • [1, 2] NONE == 1 will return false
  • [2, 2] NONE == 1 will return true
• WITH in cluster traversals is now mandatory in order to avoid deadlocks.

Data format changes

The attribute maximalSize has been renamed to journalSize in collectionmeta-data files (“parameter.json”). Files containing the maximalSize attributewill still be picked up correctly for not-yet adjusted collections.

The format of the revision values stored in the _rev attribute of documentshas been changed in 3.1. Up to 3.0 they were strings containing largish decimal numbers. With 3.1, revision values are still strings, but are actually encoded time stamps of the creation date of the revision of the document. The time stamps are acquired using a hybrid logical clock (HLC) on the DBserver that holds therevision (for the concept of a hybrid logical clock seethis paper).See this manual section for details.

ArangoDB >= 3.1 can ArangoDB 3.0 database directories and will simply continueto use the old _rev attribute values. New revisions will be written withthe new time stamps.

It is highly recommended to backup all your data before loading a databasedirectory that was written by ArangoDB <= 3.0 into an ArangoDB >= 3.1.

To change all your old _rev attributes into new style time stamps youhave to use arangodump to dump all data out (using ArangoDB 3.0), anduse arangorestore into the new ArangoDB 3.1, which is the safestway to upgrade.

The change also affects the return format of _rev values and other revisionvalues in HTTP APIs (see below).

HTTP API changes

APIs added

The following HTTP REST APIs have been added for online log level adjustment ofthe server:

• GET /_admin/log/level returns the current log level settings
• PUT /_admin/log/level modifies the current log level settings

APIs changed

• the following REST APIs that return revision ids now make use of the new revisionid format introduced in 3.1. All revision ids returned will be strings as in 3.0, buthave a different internal format.

The following APIs are affected:

• GET /_api/collection/{collection}/checksum: revision attribute
• GET /_api/collection/{collection}/revision: revision attribute
• all other APIs that return documents, which may include the documents’ _rev attributeClient applications should not try to interpret the internals of revision values, but onlyuse revision values for checking whether two revision strings are identical.

• the replication REST APIs will now use the attribute name journalSize instead ofmaximalSize when returning information about collections.

• the default value for keepNull has been changed from false to true forthe following partial update operations for vertices and edges in /_api/gharial:

  • PATCH /_api/gharial/{graph}/vertex/{collection}/{key}
  • PATCH /_api/gharial/{graph}/edge/{collection}/{key}The value for keepNull can still be set explicitly to false by setting theURL parameter keepNull to a value of false.

• the REST API for dropping collections (DELETE /_api/collection) now accepts anoptional query string parameter isSystem, which can set to true in order todrop system collections. If the parameter is not set or not set to true, the RESTAPI will refuse to drop system collections. In previous versions of ArangoDB, theisSystem parameter did not exist, and there was no distinction between systemand non-system collections when dropping collections.

• the REST API for retrieving AQL query results (POST /_api/cursor) will now return anadditional sub-attribute loading collections that will contain the total timerequired for loading and locking collections during the AQL query when profiling isenabled. The attribute can be found in the extra result attribute in sub-attributeloading collections. The attribute will only be set if profiling was enabled forthe query.

• the REST API for retrieving AQL query results (POST /_api/cursor) will now accept the optional attribute memoryLimit.

Foxx Testing

The QUnit interface to Mocha has been removed. This affects the behavior of the suite, test, before, after, beforeEach and afterEach functions in Foxx test suites. The suite and test functions are now provided by the TDD interface. The before, after, beforeEach and afterEach functions are now provided by the BDD interface.

This should not cause any problems with existing tests but may result in failures in test cases that previously passed for the wrong reasons. Specifically the execution order of the before, after, etc functions now follows the intended order and is no longer arbitrary.

For details on the expected behavior of these functions see the testing chapter in the Foxx documentation.