This tool may be used to compile new or updated query files to speed up future analyses. The
analyzeSnapshot command automatically calls this before analyzing snapshots. All queries in the specified locations are reviewed and all new or updated queries are compiled (creating a
.qlo file for each query). The primary use of this tool is to compile custom queries so that they are ready for use for analysis.
This tool is run from the command line as follows:
Preparing queries for use in dashboards
When you use the tool to pre-compile queries that you plan to run using the analyzeSnapshot command, it is important to use the default values for the results columns to output. If you override the default results columns by setting one or more of
--icon-paths, queries will be re-compiled before they are run. Specifying the
--local-checking flags will also result in re-compilation when the query is run by
prepareQueries tool supports the following flags:
Optional. Output more detailed information about actions. This increases the verbosity to level 4.
Optional. Define the precise level of reporting required where
Default: the internal identifier for each result is reported.
Optional. Disable the inclusion of URLs in the results. When the query is run results will not include a column of URLs. This information is required for results to be interpreted correctly.
Default: URLs are included for any result columns that have them.
Optional. Enable this option to include all results, whether or not they have a valid URL. Create a fake URL for any results that without a valid URL.
Default: any results without a valid URL are suppressed.
Optional. If query compilation is required, perform a quick compilation, omitting some optimizations.
Default: any compilation of queries includes all possible optimizations.
Optional. If query compilation is required, restrict error checking to the parts of the QL program that are used. Any areas of the imported QL libraries that are not used by the query are ignored.
Default: any error checking covers the full QL program, including all areas of the QL libraries that are imported.
Optional. Any warnings reported during compilation are treated as an error and the compilation fails.
Default: any warnings are ignored. The process only fails if an error is detected.
Optional. Use to define an alternative directory to use for the compilation cache.
Default: the directory defined by the
Optional. Defines the number of threads to use.
Optional. The auto-detected query language (based on the QL file's associated queries.xml file) is used in preference to this. If a query file does not have an associated
The language should be a valid language from the following list:
Click to show valid languages...
The other supported option is
Default: an error is reported if the query language cannot be detected and this option is undefined.
Optional. Defines the location of the default query libraries.
Optional. Defines the location of a query suite. All queries defined in the suite are compiled, in addition to any defined by specifying a location for the command.
Default: if this is undefined and no location is defined, then all queries under the
Optional. Don't validate query metadata and results patterns.
Default: query compilation will fail if any queries have
Optional. Defines the name of a file to output the log messages to.
Default: none; debug logs are normally not produced.
Optional. Defines a subset of the queries to compile. The queries are divided into
Default: all queries in the specified directories or files are compiled (equivalent to
Optional. Defines the amount of memory to use.
The value is assumed to be defined in 1024-based megabytes unless a unit is specified. Units are case insensitive.
Show valid units...
Optional. Validate the queries and exit without performing any compilation.
Default: any queries that have not been compiled or that have been edited since their last compilation, are compiled.
Optional. Use to save the QLO files generated by the tool alongside the queries.
Default: The compiled queries are not saved.
Optional. Defines the query files or directories of query files that you want to search for queries that need to be compiled. Specify
Default: if this is undefined and the
prepareQueries is complete, all queries that were successfully compiled have a valid, associated
*.qlo file. Running the prepared queries via analyzeSnapshot will not result in recompilation unless you have specified one or more of the following flags:
analyzeSnapshot normally compiles
*.ql files to
*.qlo files automatically, so this command is rarely used directly. A common use case is to pre-compile a set of custom queries before distributing them to several installations, so that the compilation only needs to happen once.
The exit code of
prepareQueries is 0 on success. Otherwise, the exit code is the number of queries that failed to compile (capped at a maximum of 255).