Troubleshooting
Trace AQL errors to their source, diagnose unexpected results (ambiguous joins, unconnected models, LOD), and use the AMQL sandbox to isolate and test fixes.
This is one of three documents aimed at helping answer common questions about AQL:
- Troubleshooting (this guide)
- AQL Error Reference
This guide covers two main topics:
- How to identify the source of an error when you're stuck
- How to resolve common issues and get unstuck
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 error message names the field whose definition failed, and an editor with AMQL support highlights the offending span inside that definition.
That 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 a query 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 a query 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.
Semi-Additive Calculation
Some metrics aggregate correctly across most dimensions but not time, and this walks through two AQL approaches using a bank balance as the worked example.
AQL Validation Rules
Hard constraints that AQL expressions must follow. Violating these either fails validation or produces deterministically wrong results.