7 XML query files: common part

7.1 What is common and what depends on the engine#

An XML query file always has the same structure: a root element <Queries> with global declarations and a list of queries. Each query combines common elements with engine-specific ones:

<Queries engine="...">                        <!-- common -->

    <environment name="..." default="..."/>   <!-- common -->
    <script language="...">...</script>       <!-- common -->
    <context .../>                            <!-- Database only -->
    <authentication ...>...</authentication>  <!-- Webservice only -->

    <query name="..." module="..." ...>       <!-- common + engine attributes -->
        <sql>...</sql>                        <!-- Database only -->
        <url>...</url>                        <!-- Webservice only -->
        <parameter order="..." .../>          <!-- common + engine attributes -->
        <item name="..." .../>                <!-- common + engine attributes -->
        <field name="..." .../>               <!-- common + engine attributes -->
        <script>...</script>                  <!-- common -->
    </query>

</Queries>

Table 7.1 summarises which elements and attributes exist in each engine.

Table 7.1. Elements and attributes per engine

7.2 General rules#

• Element and attribute names are case-insensitive (<Queries> and <queries> are equivalent).

• An unknown attribute or element, or one that does not belong to the engine, is an error: the monitor does not start and the error appears in its log.

• It is advisable to write query and script text inside a <![CDATA[ ... ]]> section so that <, > and & need not be escaped.

• If a monitor loads several files (several QueryFile lines), all of them must belong to the same engine. Query and item names must be unique across all the files.

7.3 The <Queries> element#

It is the root element and accepts these attributes:

If the installed version is lower than the required one, the monitor does not start and says so in the log.

7.4 Environment variables: <environment>#

Environment variables make it possible to parametrise an XML file and reuse it in several installations: schema names, databases, contexts…

<environment name="SvmSchema" default="svm920"/>

They are used with the syntax ${Name}. Where they are substituted depends on the engine: in Database, in the SQL text, in the attributes of contexts, <default> and <parameter>, and in <when> conditions with environment(’Name’); in Webservice, in the text of the <header> elements of HTTPAuth authentication methods.

<sql><![CDATA[
    select count(*) as n from ${SvmSchema}.f986110
    ]]>
</sql>

The value of a variable is taken from the first of these sources that defines it:

1. Environment in the monitor’s .conf file.

2. Environment in databbix.conf.

3. The default attribute of the <environment> in the XML file.

For example, to make a monitor use the svm910 schema:

[General]
Environment = SvmSchema=svm910

An undefined variable is replaced by an empty string.

7.5 Scripts: <script>#

A <script> contains JavaScript or Python functions used to transform values or responses. It can be placed at <Queries> level, and then it is available to all queries, or inside a <query>, and then it is only available to that query.

<script language="Javascript"><![CDATA[
    function toUnix(date) {
        return Math.round(Date.parse(date) / 1000);
    }
    ]]>
</script>

All scripts in a query collection must use the same language. Chapter 12 explains how to write them.

7.6 The query: <query>#

7.7 The <item> element#

Each <item> declares a Zabbix item produced by the query. These are its common attributes; each engine adds the attributes that say where the value comes from (column in Database, path and type in Webservice).

The same piece of data can feed several items with different names, for example to keep an old key and a new one at the same time:

<item name="tez.ora.queryversion" column="version"/>
<item name="ts.db.queryversion"   column="version"/>

7.8 The <parameter> element#

Links each parameter of the Zabbix key to the query. These are the common attributes; the attribute that says what for the parameter is used depends on the engine (column, bind or context in Database; path or urlparameter in Webservice).

Key parameters are separated by commas only and leading and trailing spaces are removed. Quotes are not interpreted, so a parameter cannot contain commas.

7.9 Discovery queries#

In every engine, a query with discovery="yes" produces the JSON of a Zabbix low-level discovery rule:

{"data":[ {"{#MACRO1}":"value", "{#MACRO2}":"value"}, ... ]}

• Each discovered entity (a row, an element of a JSON array, a topic) is an element of data.

• Each <field> defines a macro: the name attribute is the macro name without {# and }, and the engine-specific attribute says where its value comes from.

• The <item> elements of a discovery only have name and, optionally, transform; in that case the function receives the whole JSON (section 12.5).

7.10 Constant queries#

With type="Constant", the query does not access the data source: each <item> returns the value of its value attribute. They work with any engine and are typically used to publish the version of the query file:

<query name="JDEVersion" module="JDE" type="Constant">
    <item name="ts.jde.queryversion" value="$Id: manual-databbix-en.tex 2699 2026-10-28 12:19:58Z bruno $"/>
</query>