Skip to main content

AQL Troubleshooting

This is one of three documents aimed at helping answer common questions about AQL:

  1. Troubleshooting (this guide)
  2. AQL Error Reference

This guide covers two main topics:

Identify the Source of an Error​

When faced with an AQL error, your first step should be to identify the exact source of the problem. Most errors can be traced to a specific field (metric or dimension) in your code.

The problematic code will typically be highlighted in red, within the definition of the field causing the error, as shown in this example:

AQL error trace example showing highlighted error in code

This visual indication should provide enough information to help you fix most errors. If you need additional context or the error message isn't clear, consult the resources listed below.

Helpful Resources​

Documentation Resources​

Troubleshooting Errors​

If your visualization returns an error, consult:

  • AQL Error Reference: A comprehensive guide to AQL error codes with explanations and solutions. Error messages in AQL include direct links to relevant sections of this guide.

Unexpected Results​

If your visualization runs without errors but produces unexpected results, consider these common causes:

  • Ambiguous relationships: Your dataset may have multiple possible relationship interpretations. The system's chosen interpretation might differ from your intended logic.
  • Unconnected models: If metrics remain unchanged when adding dimensions or filters, or if values repeat across rows, your dimension/filter models may not be properly connected to the metric's model. This prevents them from affecting the results.
  • Level of Details: Using LOD functions can alter how metrics respond to dimensions and filters. Review your LOD expressions to ensure they align with your analysis goals.

Testing and Reproduction​

AMQL Online Sandbox​

If the documentation doesn't resolve your issue, the AMQL online sandbox can be invaluable for troubleshooting:

  • Create a minimal reproduction of your problem
  • Isolate specific AQL code segments to identify issues
  • Test potential fixes in a controlled environment

Using the sandbox allows you to simplify complex queries and focus on the specific components causing errors, making it easier to find solutions.

Let us know what you think about this document :)