databbix User manual Español

A XML quick reference

This appendix summarises, for each query type, which elements and attributes are mandatory, which are optional and which are not accepted. In the outlines, square brackets mark optional parts and the vertical bar separates alternatives.

A.1 <Queries> level (all engines)#

<Queries [engine="Database|Webservice|MQTT"] [query="2.5.0"] [databbix="2.5.0"]>
  <environment name="VAR" default="value"/>                   <!-- all -->
  <script language="Javascript|Python"> ... </script>         <!-- all -->
  <context name="Database" module="MOD" default="value"/>     <!-- Database -->
  <authentication type="RESTToken|HTTPAuth" name="N"> ...     <!-- Webservice -->
  <query ...> ... </query>
</Queries>

In all queries, name and module are mandatory, and maxCache, maxExecTime and <script> are optional. <field> elements are only accepted in discovery queries.

A.2 Constant query (all engines)#

<query name="..." module="..." type="Constant">
  <item name="key" value="value"/>
</query>
Mandatory: type="Constant"; one or more <item> with name and value.
Optional: transform on the <item> elements.
Not accepted: <sql>, <url>, <parameter>, <field>.

A.3 Database engine#

A.3.1 Basic query#

<query name="..." module="...">
  <sql> text </sql>
  [<default context="C" value="v"/>]
  [<parameter context="C" order="N"/>]
  <item name="key" column="COL" [transform="L:f"]/>
  [<item name="key" built_in="exec_time|exec_success"/>]
</query>
Mandatory: one <sql>; one or more <item> with column (or built_in).
Optional: <default>; context <parameter>; transform on items.
Not accepted: select; <parameter> with column or bind; <field>; <sql context>.

The statement must return exactly one row.

A.3.2 Filter query#

<query name="..." module="..." select="FILTER">
  <sql> text </sql>
  [<default context="C" value="v"/>]
  [<parameter context="C" order="1"/>]
  <parameter column="COL" order="N" [type="STRING|INT"]/>
  <item name="key" column="COL" [default="v"] [transform="L:f"]/>
</query>
Mandatory: select="FILTER"; one <sql>; at least one <parameter> with column; one or more <item> with column (or built_in).
Optional: <default>; context <parameter>; default and transform on items.
Not accepted: <parameter> with bind; <field>; <sql context>.

A.3.3 Bind variable query#

<query name="..." module="..." select="BIND">
  <sql> text with :var </sql>
  [<default context="C" value="v"/>]
  [<parameter context="C" order="1"/>]
  <parameter bind=":var" order="N" [type="STRING|INT"]/>
  <item name="key" column="COL" [transform="L:f"]/>
</query>
Mandatory: select="BIND"; one <sql>; at least one <parameter> with bind; one or more <item> with column (or built_in).
Optional: <default>; context <parameter>; transform on items.
Not accepted: <parameter> with column; <field>; <sql context>.

The statement must return exactly one row for each key.

A.3.4 Discovery query#

<query name="..." module="..." discovery="yes">
  [<sql context="C"> text </sql>]
  <sql> text </sql>
  [<default context="C" value="v"/>]
  [<parameter context="C" order="N"/>]
  <item name="key" [transform="L:f"]/>
  <field name="MACRO" column="COL" | context="C"/>
</query>
Mandatory: discovery="yes"; one main <sql>; at least one <field> with column or context; one or more <item> with name only.
Optional: <sql context> (one per context iterated); <default>; context <parameter>; transform on items.
Not accepted: select; <parameter> with column or bind; column, built_in and default on items.

A.4 Webservice engine#

A.4.1 REST query#

<query name="..." module="..." type="REST" transport="GET|POST" encode="Json">
  <url>relative/path</url>
  [<transform language="L" function="f"/>]
  [<parameter urlparameter="name" order="N" [type="STRING|INT"]/>]
  <item name="key" path="a:b:[0]:c" type="INT|STRING" [default="v"]/>
</query>
Mandatory: type="REST"; transport; encode="Json"; one <url>; one or more <item> with path and type (or built_in).
Optional: <transform>; <parameter> with urlparameter; default and transform on items.
Not accepted: <sql>; <field>; <parameter> with column, bind or context.

A.4.2 REST filter query#

<query name="..." module="..." type="REST" transport="GET|POST" encode="Json">
  <url>relative/path</url>
  <base path="list:[]"/>
  [<transform language="L" function="f"/>]
  <parameter path="field" order="N" [type="STRING|INT"]/>
  [<parameter urlparameter="name" order="M"/>]
  <item name="key" path="field" type="INT|STRING" [default="v"]/>
</query>
Mandatory: the same as a REST query, plus <base> and at least one <parameter> with path.
Optional: <transform>; <parameter> with urlparameter; default and transform on items.
Not accepted: <field>. Item paths are relative to the selected element.

A.4.3 REST discovery query#

<query name="..." module="..." type="REST" transport="GET|POST" encode="Json"
       discovery="yes">
  <url>relative/path</url>
  [<transform language="L" function="f"/>]
  [<parameter urlparameter="name" order="N"/>]
  <item name="key" path="list:[]" [transform="L:f"]/>
  <field name="MACRO" path="field"/>
</query>
Mandatory: discovery="yes"; type="REST"; transport; encode="Json"; one <url>; one or more <item> with path (with [] or *); <field> with path.
Optional: <transform>; <parameter> with urlparameter; transform on items.
Not accepted: type, built_in and default on items.

A.4.4 SOAP query#

<query name="..." module="..." type="SOAP" transport="POST">
  <url>service/path</url>
  <method uri="name:space" name="method" [action="action"]>
    [<argument name="arg" type="string|int" value="value"/>]
  </method>
  [<transform language="L" function="f"/>]
  <item name="key" path="a:b" type="INT|STRING" [default="v"]/>
</query>
Mandatory: type="SOAP"; transport="POST"; one <url>; one <method> with name; one or more <item> with path and type (or built_in).
Optional: <argument>; <transform>; default and transform on items.
Not accepted: discovery; <field>. <parameter> elements are accepted but have no effect in this version.

A.5 MQTT engine#

A.5.1 Value reading#

<query name="..." module="...">
  <parameter order="1" [type="STRING"]/>
  <item name="ts.mqtt.getvalue"/>
</query>
Mandatory: one <parameter> (the topic); the <item> ts.mqtt.getvalue.
Optional: —
Not accepted: attributes on the <item> other than name; <field>.

A.5.2 Topic discovery#

<query name="..." module="..." discovery="yes">
  <parameter order="1" [type="STRING"]/>
  <item name="ts.mqtt.discovery"/>
  <field name="MACRO"/>
</query>
Mandatory: discovery="yes"; exactly one <parameter> (the pattern); the <item> ts.mqtt.discovery; exactly one <field>, with name only.
Optional: —
Not accepted: attributes on the <item> or <field> other than name.