ArangoDB Logo

ArangoDB v3.13 is under development and not released yet. This documentation is not final and potentially incomplete.

Query debug packages

If you have an issue with a specific AQL query, you can create a debug package to provide all necessary information to others for investigating the issue

Query debug packages, or debug dumps, facilitate the debugging of issues you might find after executing AQL queries. A debug package is a JSON file that contains information about the query and the environment to make it possible to reproduce the issue:

  • General information about the server including the exact version
  • The properties of the involved database, collections, Views, and graphs
  • The query, its bind variables, and options
  • The query execution plan
  • Storage engine statistics
  • Optionally samples of your data, with the option to obfuscate all string values in a non-reversible way
Before sharing a debug package, open the file locally and check if it contains anything that you are not allowed or willing to share and obfuscate it.

Create a query debug package in the web interface

  1. In Queries section of the web interface, enter an AQL query into the editor and provide the bind parameters if necessary.
  2. Click Create Debug Package below the text area.
  3. The download of a compressed debug package starts.
  4. Unzip the downloaded file if you want to inspect its content.

Create a query debug package with arangosh

Connect to the server with the ArangoDB shell and call the debugDump() method of the explainer module. You can specify the output file path, the AQL query, any bind parameters if necessary, as well as options for the query, including two additional options to include sample documents, examples and anonymize:

var examples = require("@arangodb/graph-examples/example-graph");
var g = examples.loadGraph("worldCountry");
var query = `FOR v, e, p IN 0..10 INBOUND "worldVertices/continent-europe" GRAPH "worldCountry" FILTER v._key != @country RETURN CONCAT_SEPARATOR(" -- ", p.vertices)`;
var bindVars = { country: "country-denmark" };
var options = { examples: 10, anonymize: true }
var explainer = require("@arangodb/aql/explainer"); 
explainer.debugDump("/tmp/debugDumpFilename", query, bindVars, options);
Show output
2024-03-11T19:04:40Z [1461] INFO [99d80] {general} stored query debug information in file '/tmp/debugDumpFilename'

See Gathering debug information about a query for details.

Inspect a query debug package with arangosh

The debug package JSON is compactly formatted. To get a more readable output, you can use a tool for pretty-printing like jq , or use the inspectDump() method of the explainer module for formatting.

var explainer = require("@arangodb/aql/explainer"); 
explainer.inspectDump("/tmp/debugDumpFilename");
Show output
/* original data is from 3.12.0-nightly.20240305, enterprise */
/* original data gathered from database {"name":"_system"} */

/* graphs */
try { db._graphs.remove("worldCountry"); } catch (err) {}
db._graphs.insert({"_key":"worldCountry","_id":"_graphs/worldCountry","_rev":"_hg5lEC2--_","edgeDefinitions":[{"collection":"worldEdges","from":["worldVertices"],"to":["worldVertices"]}],"orphanCollections":[]});

/* collections and indexes setup */
try { db._drop("worldEdges"); } catch (err) { print(String(err)); }
try { db._drop("worldVertices"); } catch (err) { print(String(err)); }
db._create("worldVertices", {"globallyUniqueId":"h7F0F0D5E4468/82634","isSystem":false,"waitForSync":false,"keyOptions":{"allowUserKeys":true,"type":"traditional","lastValue":0},"writeConcern":1,"cacheEnabled":false,"computedValues":null,"syncByRevision":true,"schema":null});

db._createEdgeCollection("worldEdges", {"globallyUniqueId":"h7F0F0D5E4468/82635","isSystem":false,"waitForSync":false,"keyOptions":{"allowUserKeys":true,"type":"traditional","lastValue":82905},"writeConcern":1,"cacheEnabled":false,"computedValues":null,"syncByRevision":true,"schema":null});
/* example data */
db["worldVertices"].insert({"_key":"world","_id":"worldVertices/world","_rev":"_hg5lEC6---","name":"XXXXX11","type":"XXXX12"});
db["worldVertices"].insert({"_key":"continent-africa","_id":"worldVertices/continent-africa","_rev":"_hg5lEC6--_","name":"XXXXXX13","type":"XXXXXXXXX14"});
db["worldVertices"].insert({"_key":"continent-asia","_id":"worldVertices/continent-asia","_rev":"_hg5lEC6--A","name":"XXXX15","type":"XXXXXXXXX16"});
db["worldVertices"].insert({"_key":"continent-australia","_id":"worldVertices/continent-australia","_rev":"_hg5lEC6--B","name":"XXXXXXXXX17","type":"XXXXXXXXX18"});
db["worldVertices"].insert({"_key":"continent-europe","_id":"worldVertices/continent-europe","_rev":"_hg5lEC6--C","name":"XXXXXX19","type":"XXXXXXXXX20"});
db["worldVertices"].insert({"_key":"continent-north-america","_id":"worldVertices/continent-north-america","_rev":"_hg5lED----","name":"XXXXXXXXXXXXX21","type":"XXXXXXXXX22"});
db["worldVertices"].insert({"_key":"continent-south-america","_id":"worldVertices/continent-south-america","_rev":"_hg5lED---_","name":"XXXXXXXXXXXXX23","type":"XXXXXXXXX24"});
db["worldVertices"].insert({"_key":"country-afghanistan","_id":"worldVertices/country-afghanistan","_rev":"_hg5lED---A","name":"XXXXXXXXXXX25","type":"XXXXXXX26","code":"XXX27"});
db["worldVertices"].insert({"_key":"country-albania","_id":"worldVertices/country-albania","_rev":"_hg5lED---B","name":"XXXXXXX28","type":"XXXXXXX29","code":"XXX30"});
db["worldVertices"].insert({"_key":"country-algeria","_id":"worldVertices/country-algeria","_rev":"_hg5lED---C","name":"XXXXXXX31","type":"XXXXXXX32","code":"XXX33"});
/* collection 'worldVertices' needs 77 more document(s) */

db["worldEdges"].insert({"_key":"82735","_id":"worldEdges/82735","_from":"worldVertices/continent-africa","_to":"worldVertices/world","_rev":"_hg5lEEO--B","type":"XXXXX1"});
db["worldEdges"].insert({"_key":"82737","_id":"worldEdges/82737","_from":"worldVertices/continent-asia","_to":"worldVertices/world","_rev":"_hg5lEEO--C","type":"XXXXX2"});
db["worldEdges"].insert({"_key":"82739","_id":"worldEdges/82739","_from":"worldVertices/continent-australia","_to":"worldVertices/world","_rev":"_hg5lEEO--D","type":"XXXXX3"});
db["worldEdges"].insert({"_key":"82741","_id":"worldEdges/82741","_from":"worldVertices/continent-europe","_to":"worldVertices/world","_rev":"_hg5lEES---","type":"XXXXX4"});
db["worldEdges"].insert({"_key":"82743","_id":"worldEdges/82743","_from":"worldVertices/continent-north-america","_to":"worldVertices/world","_rev":"_hg5lEES--_","type":"XXXXX5"});
db["worldEdges"].insert({"_key":"82745","_id":"worldEdges/82745","_from":"worldVertices/continent-south-america","_to":"worldVertices/world","_rev":"_hg5lEES--A","type":"XXXXX6"});
db["worldEdges"].insert({"_key":"82747","_id":"worldEdges/82747","_from":"worldVertices/country-afghanistan","_to":"worldVertices/continent-asia","_rev":"_hg5lEES--B","type":"XXXXX7"});
db["worldEdges"].insert({"_key":"82749","_id":"worldEdges/82749","_from":"worldVertices/country-albania","_to":"worldVertices/continent-europe","_rev":"_hg5lEES--C","type":"XXXXX8"});
db["worldEdges"].insert({"_key":"82751","_id":"worldEdges/82751","_from":"worldVertices/country-algeria","_to":"worldVertices/continent-africa","_rev":"_hg5lEES--D","type":"XXXXX9"});
db["worldEdges"].insert({"_key":"82753","_id":"worldEdges/82753","_from":"worldVertices/country-andorra","_to":"worldVertices/continent-europe","_rev":"_hg5lEES--E","type":"XXXXX10"});
/* collection 'worldEdges' needs 76 more document(s) */
/* views */

/* explain result */
// Query String (152 chars, cacheable: true):
//  FOR v, e, p IN 0..10 INBOUND "worldVertices/continent-europe" GRAPH "worldCountry" FILTER v._key != 
//  @country RETURN CONCAT_SEPARATOR(" -- ", p.vertices)
// 
// Execution plan:
//  Id   NodeType          Par   Est.   Comment
//   1   SingletonNode              1   * ROOT
//   2   TraversalNode       ✓      1     - FOR v  /* vertex */, p  /* paths: vertices */ IN 0..10  /* min..maxPathDepth */ INBOUND 'worldVertices/continent-europe' /* startnode */  GRAPH 'worldCountry' /* order: dfs */
//   3   CalculationNode     ✓      1       - LET #4 = (v.`_key` != "XXXXXXXXXXXXXXX0")   /* simple expression */
//   4   FilterNode          ✓      1       - FILTER #4
//   5   CalculationNode     ✓      1       - LET #5 = CONCAT_SEPARATOR(" -- ", p.`vertices`)   /* simple expression */
//   6   ReturnNode                 1       - RETURN #5
// 
// Indexes used:
//  By   Name   Type   Collection   Unique   Sparse   Cache   Selectivity   Fields      Stored values   Ranges
//   2   edge   edge   worldEdges   false    false    false      100.00 %   [ `_to` ]   [  ]            base INBOUND
// 
// Functions used:
//  Name               Deterministic   Cacheable   Uses V8
//  CONCAT_SEPARATOR   true            true        false  
// 
// Traversals on graphs:
//  Id  Depth  Vertex collections  Edge collections  Options                                              Filter / Prune Conditions
//  2   0..10  worldVertices       worldEdges        uniqueVertices: none, uniqueEdges: path, order: dfs  FILTER (v.`_key` != "XXXXXXXXXXXXXXX0")
// 
// Optimization rules applied:
//  Id   Rule Name                         Id   Rule Name                         Id   Rule Name                
//   1   move-calculations-up               4   move-filters-up-2                  7   async-prefetch           
//   2   move-filters-up                    5   optimize-traversals      
//   3   move-calculations-up-2             6   remove-redundant-path-var
// 
// 52 rule(s) executed, 1 plan(s) created, peak mem [b]: 0, exec time [s]: 0.00033

/* explain command */
db._explain({"query":"FOR v, e, p IN 0..10 INBOUND \"worldVertices/continent-europe\" GRAPH \"worldCountry\" FILTER v._key != @country RETURN CONCAT_SEPARATOR(\" -- \", p.vertices)","bindVars":{"country":"XXXXXXXXXXXXXXX0"},"options":{"explainRegisters":true,"explainInternals":false,"verbosePlans":true,"profile":2}});

On this page