diff --git a/Documentation/Books/AQL/CommonErrors.md b/Documentation/Books/AQL/CommonErrors.md index 13a75ba9d1..ca5950a7d8 100644 --- a/Documentation/Books/AQL/CommonErrors.md +++ b/Documentation/Books/AQL/CommonErrors.md @@ -29,6 +29,69 @@ RETURN CONCAT("foo", 123) // [ "foo123" ] RETURN CONCAT("123", 200) // [ "123200" ] ``` +Unexpected long running queries +------------------------------- + +Slow queries can have various reasons and be legitimate for queries with a high +computational complexity or if they touch a lot of data. Use the *Explain* +feature to inspect execution plans and verify that appropriate indexes are +utilized. Also check for mistakes such as references to the wrong variables. + +A literal collection name, which is not part of constructs like `FOR`, +`UPDATE ... IN` etc., stands for an array of all documents of that collection +and can cause an entire collection to be materialized before further +processing. It should thus be avoided. + +Check the execution plan for `/* all collection documents */` and verify that +it is intended. You should also see a warning if you execute such a query: + +> collection 'coll' used as expression operand + +For example, instead of: + +```js +RETURN coll[* LIMIT 1] +``` + +... with the execution plan ... + +``` +Execution plan: + Id NodeType Est. Comment + 1 SingletonNode 1 * ROOT + 2 CalculationNode 1 - LET #2 = coll /* all collection documents */[* LIMIT 0, 1] /* v8 expression */ + 3 ReturnNode 1 - RETURN #2 +``` + +... you can use the following equivalent query: + +```js +FOR doc IN coll + LIMIT 1 + RETURN doc +``` + +... with the (better) execution plan: + +``` +Execution plan: + Id NodeType Est. Comment + 1 SingletonNode 1 * ROOT + 2 EnumerateCollectionNode 44 - FOR doc IN Characters /* full collection scan */ + 3 LimitNode 1 - LIMIT 0, 1 + 4 ReturnNode 1 - RETURN doc +``` + +Similarly, make sure you have not confused any variable names with collection +names by accident: + +```js +LET names = ["John", "Mary", ...] +// supposed to refer to variable "names", not collection "Names" +FOR name IN Names + ... +``` +