The query
sub-command and the underlying :pypygcam.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
pygcam.query
for more information about run-time behavior. Command-line usage is described on thegt query<query>
page.Some elements of the
query.xml
file can contain<CONDITIONAL>
elements, as described below. Seeconditional-xml
for further details.
The queries.xml
file defines a set of queries to execute. It's elements are described below, followed by a short example.
The elements that comprise the queries.xml
file are described below.
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 <rewrites-xml>
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.
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 :pypygcam.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>
.
This element identifies a rewrite set <rewrites-xml>
by name. The rewrite set must be defined in a file identified as an argument to the :pypygcam.query.runBatchQuery
, on the command-line to the query sub-command <query>
, 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 |
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>