The query sub-command and the underlying pygcam.query.runBatchQuery() function allow you to specify an XML file that describes a sequence of query to execute. The queries can reference named sets of label rewrite statements that allow results to be renamed, aggregated, or ignored. Here we document the format of the two XML files.

See also

See pygcam.query for more information about run-time behavior. Command-line usage is described on the gt query page.

Some elements of the query.xml file can contain <CONDITIONAL> elements, as described below. See Conditional XML for further details.

queries.xml

The queries.xml file defines a set of queries to execute. It’s elements are described below, followed by a short example.

XML elements

The elements that comprise the queries.xml file are described below.

<queries>

The top-most element, <queries>, encloses one or more <query> elements. The <queries> element may also contain <CONDITIONAL> elements. The <query> element takes the following attributes:

Attribute	Required	Default	Values
varName	depends	(none)	text
defaultMap	no	(none)	text
delete	no	“1”	boolean

The varName is required for <queries> defined in the project.xml file; it defines a variable name which is assigned the path of a temporary file into which the <queries> element and sub-elements are copied. If an external queries file is used, the varName is ignored.

The defaultMap defines a default rewrite set to use with all queries, which can be overridden for any single query by explicitly specifying useDefault="0".

The delete attribute defines whether the temporary file generated from the <queries> element in the project.xml file should be deleted. This is primarily for debugging.

<query>

The <query> element specifies a query to run. The required name attribute must match the name of a query found on the Query Path, which is specified as an argument to the function pygcam.query.runBatchQuery(), on the command-line to the query sub-command, or by the value of the config variable GCAM.QueryPath.

The <query> element can contain zero or more <rewriter> elements and may contain <CONDITIONAL> elements.

Attribute	Required	Default	Values
name	yes	(none)	text
saveAs	no	name	text
useDefault	no	“1”	boolean

By default, the results for the query are saved to a file based on name and the scenario name. However, using the saveAs option allows you to save results to a different name, allowing a single query to be run multiple times with different rewrites to produce multiple CSV files.

The useDefault attribute provides a way to override any defaultMap specified in the surrounding <queries> element. Set useDefault="0" to prevent the default rewrite map from applying to this <query>.

<rewriter>

This element identifies a rewrite set by name. The rewrite set must be defined in a file identified as an argument to the pygcam.query.runBatchQuery(), on the command-line to the query sub-command, or by setting a value for the config variable GCAM.RewriteSetsFile.

The query named in the <query> node is extracted into a temporary file and the specified rewrites are inserted into the query. If a level is specified, it identifies the variable in the query output that should be rewritten according to the <rewrite> elements in the corresponding rewrite set.

If no level is specified, the level giving in the query definition itself is used. In most cases, the user will not need to specify a level in the <rewriter> statement, but the option is available to override the default.

Attribute	Required	Default	Values
name	yes	(none)	text
level	no	(none)	text

Example

This is an example of a query specification file.

<queries varName="queryXmlFile" defaultMap="eightRegions">
   <query name="land_cover">
       <rewriter name="eightRegions"/>
       <rewriter name="landCover"/>
   </query>

   <query name="Aggregated Land Allocation"/>

   <query name="luc_emissions"/>

   <query name="ag_production" useDefault="0">
       <rewriter name="GTAP-BIO-ADV"/>
       <rewriter name="food" level="input"/>
   </query>

   <query name="nonco2"/>
   <query name="Climate_forcing"/>
   <query name="Global_mean_temperature"/>
</queries>