Using AQL with Axonshell
What is AQL?
AQL, Axonius query language, is a language specific to the Axonius platform that represents it's complex queries through compounding logic operators and descriptive filter statements.
When you generate a query via the wizard using the Axonius GUI, the AQL statement is what gets generated and displayed at the top of your page in the query input field.
Ths AQL statement can be used directly with Axonshell to return the same data subset that is shown in the GUI.
Why would we want to use AQL?
Simply put, AQL is the back-bone of our platform. Every query, saved query, dashboard, etc, is at the end of the day, ran from AQL. Knowing how to utilize AQL and how to work around some of the gotchas is an important skill.
With that said, knowing when not to use AQL is also just as important. When it comes to creating saved queries from the python library or Axonshell, it is not recommended to use AQL. For that, we recommend using the wizard. Yes the python library and Axonshell has a built-in wizard much like the GUI does.
When you create a saved query using AQL, it will not generate something called "wizard expressions". These are the expressions that tell the GUI how to display the AQL in the GUI's wizard which is also what provides the ability to update a saved query from the GUI. With out these you cannot.
Creating a saved query using the wizard that is built into the python library and Axonshell, will generate the needed expressions.
How would we use AQL with Axonshell?
Using AQL directly is one of three ways to query your Axonius data using the python library. For more information on getting started with the python library, please look here: https://support.axonius.com/hc/en-us/community/posts/4413939753111-Getting-Started-with-the-Python-Library.
Axonshell itself is a command line script that comes bundled with the python library. For an introduction to using Axonshell please review: https://support.axonius.com/hc/en-us/community/posts/4786941189143-Getting-Started-with-Axonshell.
AQL is supported anywhere there is a "--query" parameter.
axonshell devices get --query AQL
axonshell users get --query AQL
Lets take a look at a full example:
We can generate an AQL statement using the GUI as noted above. Lets do that now:
You will see on the right, the wizard where I built the statement and then on the left, highlighted in red, the AQL that the Axonius platform generated. Lets use this with Axonshell.
axonshell devices get --query '("specific_data.data.hostname" == regex("test", "i"))'
This query is going to look for and return all devices who's name contains "test". However, I did make one modification to it. Can you spot it?
I wrapped the full statement inside of single quotes, eg. 'AQL'. Why did I do that?
When you use complex statements on the command line, sometimes some characters in those statements are interpreted as special characters and can cause the shell to error because it thinks we are trying to do something else. For example if I run the same statement but remove the single quotes it will error:
axonshell devices get --query ("specific_data.data.hostname" == regex("test", "i"))
zsh: no matches found: (specific_data.data.hostname == regex(test, i))
To rectify this we have three options.
- Escape any character that may cause issues with the shell. This is fine for simple queries, but... for longer more complex queries this can be complicated.
- Surround the whole statement in quotes, on the systems that allow it, and be done with it. This is the method I usually use. It's pretty simple and takes only moments.
What about option three?
Right! So sometimes the first two options do not work. It isn't that they couldn't work. But more that sometimes the queries will be so big, it's hard to get everything escaped correctly. This is where option three comes in:
-qf, --query-file QUERY_FILE Path to a file to override --query [env
This option is simple, but effective and can be a life saver in some situations. It also makes for a good debugging option when you are trying to figure out WHY something isn't running from the command line as it should.
This option simply loads the AQL statement from the specified file, bypassing the shell all together. By bypassing the shell, we no longer have to worry about any sort of escaping issues and can put the same exact AQL statement into a file to have loaded that the GUI generated.