mirror of https://gitee.com/bigwinds/arangodb
262 lines
9.8 KiB
Plaintext
262 lines
9.8 KiB
Plaintext
!CHAPTER Incompatible changes in ArangoDB 2.3
|
|
|
|
It is recommended to check the following list of incompatible changes **before**
|
|
upgrading to ArangoDB 2.3, and adjust any client programs if necessary.
|
|
|
|
|
|
!SECTION Default configuration file changes
|
|
|
|
With ArangoDB 2.3, the number of server threads can be configured independently of
|
|
the number of V8 contexts. The configuration option `--javascript.v8-contexts` was
|
|
added to arangod to provide better control over the number of V8 contexts created
|
|
in arangod.
|
|
|
|
Previously, the number of V8 contexts arangod created at startup was equal
|
|
to the number of server threads (as specified by option `--server.threads`).
|
|
|
|
In some situations it may be more sensible to create different amounts of threads
|
|
and V8 contexts. This is because each V8 contexts created will consume memory
|
|
and requires CPU resources for periodic garbage collection. Contrary, server
|
|
threads do not have such high memory or CPU footprint.
|
|
|
|
If the option `--javascript.v8-contexts` is not specified, the number of V8
|
|
contexts created at startup will remain equal to the number of server threads.
|
|
Thus no change in configuration is required to keep the same behavior as in
|
|
previous ArangoDB versions.
|
|
|
|
However, the default configuration files shipped with ArangoDB have been changed.
|
|
The number of server threads has been increased in the configuration files, and
|
|
the number of V8 contexts is now explicitly set in the configuration files (to
|
|
the same value as the number of server threads was set to in 2.2).
|
|
|
|
If you are using the default config files or merge them with your local config files,
|
|
please review if the higher default number of server threads is okay in your
|
|
environment. Additionally you should verify that the number of V8 contexts
|
|
created (as specified in option `--javascript.v8-contexts`) is okay.
|
|
|
|
|
|
!SECTION AQL
|
|
|
|
!SUBSECTION AQL queries throw less exceptions
|
|
|
|
ArangoDB 2.3 contains a completely rewritten AQL query optimizer and execution
|
|
engine. This means that AQL queries will be executed with a different engine than
|
|
in ArangoDB 2.2 and earlier. Parts of AQL queries might be executed in different
|
|
order than before because the AQL optimizer has more freedom to move things
|
|
around in a query.
|
|
|
|
In previous versions of ArangoDB, AQL queries aborted with an exception in many
|
|
situations and threw a runtime exception. Exceptions were thrown when trying to
|
|
find a value using the `IN` operator in a non-list element, when trying to use
|
|
non-boolean values with the logical operands `&&` or `||` or `!`, when using non-numeric
|
|
values in arithmetic operations, when passing wrong parameters into functions etc.
|
|
|
|
In ArangoDB 2.3 this has been changed in many cases to make AQL more user-friendly
|
|
and to allow the optimization to perform much more query optimizations.
|
|
|
|
Here is a summary of changes:
|
|
- when a non-list value is used on the right-hand side of the `IN` operator, the
|
|
result will be `false` in ArangoDB 2.3, and no exception will be thrown.
|
|
- the boolean operators `&&` and `||` do not throw in ArangoDB 2.3 if any of the
|
|
operands is not a boolean value. Instead, they will perform an implicit cast of
|
|
the values to booleans. Their result will be as follows:
|
|
- `lhs && rhs` will return `lhs` if it is `false` or would be `false` when converted
|
|
into a boolean. If `lhs` is `true` or would be `true` when converted to a boolean,
|
|
`rhs` will be returned.
|
|
- `lhs || rhs` will return `lhs` if it is `true` or would be `true` when converted
|
|
into a boolean. If `lhs` is `false` or would be `false` when converted to a boolean,
|
|
`rhs` will be returned.
|
|
- `! value` will return the negated value of `value` converted into a boolean
|
|
- the arithmetic operators (`+`, `-`, `*`, `/`, `%`) can be applied to any value and
|
|
will not throw exceptions when applied to non-numeric values. Instead, any value used
|
|
in these operators will be casted to a numeric value implicitly. If no numeric result
|
|
can be produced by an arithmetic operator, it will return `null` in ArangoDB 2.3. This
|
|
is also true for division by zero.
|
|
- passing arguments of invalid types into AQL functions does not throw a runtime
|
|
exception in most cases, but may produce runtime warnings. Built-in AQL functions that
|
|
receive invalid arguments will then return `null`.
|
|
|
|
|
|
!SUBSECTION Changed return values in ArangoQueryCursor.getExtra()
|
|
|
|
The return value of `ArangoQueryCursor.getExtra()` has been changed in ArangoDB 2.3.
|
|
It now contains a `stats` attribute with statistics about the query previously executed.
|
|
It also contains a `warnings` attribute with warnings that happened during query
|
|
execution. The return value structure has been unified in 2.3 for both read-only and
|
|
data-modification queries.
|
|
|
|
The return value looks like this for a read-only query:
|
|
|
|
```
|
|
arangosh> stmt = db._createStatement("FOR i IN mycollection RETURN i"); stmt.execute().getExtra()
|
|
{
|
|
"stats" : {
|
|
"writesExecuted" : 0,
|
|
"writesIgnored" : 0,
|
|
"scannedFull" : 2600,
|
|
"scannedIndex" : 0
|
|
},
|
|
"warnings" : [ ]
|
|
}
|
|
```
|
|
|
|
For data-modification queries, ArangoDB 2.3 retuns a result with the same structure:
|
|
|
|
```
|
|
arangosh> stmt = db._createStatement("FOR i IN xx REMOVE i IN xx"); stmt.execute().getExtra()
|
|
{
|
|
"stats" : {
|
|
"writesExecuted" : 2600,
|
|
"writesIgnored" : 0,
|
|
"scannedFull" : 2600,
|
|
"scannedIndex" : 0
|
|
},
|
|
"warnings" : [ ]
|
|
}
|
|
```
|
|
|
|
In ArangoDB 2.2, the return value of `ArangoQueryCursor.getExtra()` was empty for read-only
|
|
queries and contained an attribute `operations` with two sub-attributes for data-modification
|
|
queries:
|
|
|
|
```
|
|
arangosh> stmt = db._createStatement("FOR i IN mycollection RETURN i"); stmt.execute().getExtra()
|
|
{
|
|
}
|
|
```
|
|
|
|
```
|
|
arangosh> stmt = db._createStatement("FOR i IN mycollection REMOVE i IN mycollection"); stmt.execute().getExtra()
|
|
{
|
|
"operations" : {
|
|
"executed" : 2600,
|
|
"ignored" : 0
|
|
}
|
|
}
|
|
```
|
|
|
|
!SUBSECTION Changed return values in HTTP method `POST /_api/cursor`
|
|
|
|
The previously mentioned change also leads to the statistics being returned in the
|
|
HTTP REST API method `POST /_api/cursor`. Previously, the return value contained
|
|
an optional `extra` attribute that was filled only for data-modification queries and in
|
|
some other cases as follows:
|
|
|
|
```
|
|
{
|
|
"result" : [ ],
|
|
"hasMore" : false,
|
|
"extra" : {
|
|
"operations" : {
|
|
"executed" : 2600,
|
|
"ignored" : 0
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
With the changed result structure in ArangoDB 2.3, the `extra` attribute in the result
|
|
will look like this:
|
|
|
|
```
|
|
{
|
|
"result" : [],
|
|
"hasMore" : false,
|
|
"extra" : {
|
|
"stats" : {
|
|
"writesExecuted" : 2600,
|
|
"writesIgnored" : 0,
|
|
"scannedFull" : 0,
|
|
"scannedIndex" : 0
|
|
},
|
|
"warnings" : [ ]
|
|
}
|
|
}
|
|
```
|
|
|
|
If the query option `fullCount` is requested, the `fullCount` result value will also
|
|
be returned inside the `stats` attribute of the `extra` attribute, and not directly
|
|
as an attribute inside the `extra` attribute as in 2.2. Note that a `fullCount` will
|
|
only be present in `extra`.`stats` if it was requested as an option for the query.
|
|
|
|
The result in ArangoDB 2.3 will also contain a `warnings` attribute with the list of
|
|
warnings that happened during query execution.
|
|
|
|
|
|
!SUBSECTION Changed return values in ArangoStatement.explain()
|
|
|
|
The return value of `ArangoStatement.explain()` has changed significantly in
|
|
ArangoDB 2.3. The new return value structure is not compatible with the structure
|
|
returned by 2.2.
|
|
|
|
In ArangoDB 2.3, the full execution plan for an AQL query is returned alongside all
|
|
applied optimizer rules, optimization warnings etc. It is also possible to have the
|
|
optimizer return all execution plans. This required a new data structure.
|
|
|
|
Client programs that use `ArangoStatement.explain()` or the HTTP REST API method
|
|
`POST /_api/explain` may need to be adjusted to use the new return format.
|
|
|
|
|
|
The return value of `ArangoStatement.parse()` has been extended in ArangoDB 2.3.
|
|
In addition to the existing attributes, ArangoDB 2.3 will also return an `ast` attribute
|
|
containing the abstract syntax tree of the statement. This extra attribute can
|
|
safely be ignored by client programs.
|
|
|
|
|
|
!SUBSECTION Variables not updatable in queries
|
|
|
|
Previous versions of ArangoDB allowed the modification of variables inside AQL
|
|
queries, e.g.
|
|
|
|
```
|
|
LET counter = 0
|
|
FOR i IN 1..10
|
|
LET counter = counter + 1
|
|
RETURN counter
|
|
```
|
|
|
|
While this is admittedly a convenient feature, the new query optimizer design did not
|
|
allow to keep it. Additionally, updating variables inside a query would prevent a lot
|
|
of optimizations to queries that we would like the optimizer to make. Additionally,
|
|
updating variables in queries that run on different nodes in a cluster would like cause
|
|
non-deterministic behavior because queries are not executed linearly.
|
|
|
|
|
|
!SUBSECTION New AQL keywords
|
|
|
|
The following keywords have been added to AQL in ArangoDB 2.3:
|
|
|
|
- *NOT*
|
|
- *AND*
|
|
- *OR*
|
|
|
|
Unquoted usage of these keywords for attribute names in AQL queries will likely
|
|
fail in ArangoDB 2.3. If any such attribute name needs to be used in a query, it
|
|
should be enclosed in backticks to indicate the usage of a literal attribute
|
|
name.
|
|
|
|
|
|
!SECTION Removed features
|
|
|
|
!SUBSECTION Bitarray indexes
|
|
|
|
Bitarray indexes were only half-way documented and integrated in previous versions
|
|
of ArangoDB so their benefit was limited. The support for bitarray indexes has
|
|
thus been removed in ArangoDB 2.3. It is not possible to create indexes of type
|
|
"bitarray" with ArangoDB 2.3.
|
|
|
|
When a collection is openend that contains a bitarray index definition created
|
|
with a previous version of ArangoDB, ArangoDB will ignore it and log the following
|
|
warning:
|
|
|
|
index type 'bitarray' is not supported in this version of ArangoDB and is ignored
|
|
|
|
Future versions of ArangoDB may automatically remove such index definitions so the
|
|
warnings will eventually disappear.
|
|
|
|
|
|
!SUBSECTION Other removed features
|
|
|
|
The HTTP REST API method at `POST /_admin/modules/flush` has been removed.
|
|
|