parser: Let the TIMESERIES command accept optional data-source names.

[sysdb.git] / doc / sysdbql.7.txt

diff --git a/doc/sysdbql.7.txt b/doc/sysdbql.7.txt
index 7ed9a11ec61baf7ad6b9db02b70b7d26465cb639..9c8b3057cf062eea4ca7fe9720bd9483cdbe5e39 100644 (file)
--- a/doc/sysdbql.7.txt
+++ b/doc/sysdbql.7.txt
@@ -68,12 +68,14 @@ objects matching that filter will be included in the reply. See the sections
 the search and filter conditions.
 
 *TIMESERIES* '<hostname>'.'<metric>' [START '<datetime>'] [END '<datetime>']::
 the search and filter conditions.
 
 *TIMESERIES* '<hostname>'.'<metric>' [START '<datetime>'] [END '<datetime>']::

+*TIMESERIES* '<hostname>'.'<metric>'\[<data-source, ...\] [START '<datetime>'] [END '<datetime>']::

 Retrieve a time-series for the specified host's metric. The data is retrieved
 from a backend data-store based on information provided by the respective
 query plugin. The return value includes the actual start and end time of the
 Retrieve a time-series for the specified host's metric. The data is retrieved
 from a backend data-store based on information provided by the respective
 query plugin. The return value includes the actual start and end time of the

-time-series and one or multiple sequences of time-stamp / value pairs. If the
-metric does not exist or if the backend data-store is not supported, an error
-is returned.
+time-series and one or multiple sequences of time-stamp / value pairs. If any
+data-source names have been specified, only those data-sources will be
+returned. If the metric or a specified data-source does not exist or if the
+backend data-store is not supported, an error is returned.

 
 MATCHING clause
 ~~~~~~~~~~~~~~~
 
 MATCHING clause
 ~~~~~~~~~~~~~~~


@@ -129,6 +131,13 @@ Boolean expressions may use the following operators:
        expression evaluates to NULL if the queried object does not exist (e.g.,
        when accessing an attribute value).
 
        expression evaluates to NULL if the queried object does not exist (e.g.,
        when accessing an attribute value).
 

+'<expression>' *IS TRUE*::
+'<expression>' *IS NOT TRUE*::
+'<expression>' *IS FALSE*::
+'<expression>' *IS NOT FALSE*::
+       Check whether an expression evaluates to a boolean *true* or *false* value
+       (or not).
+

 '<expression>' *IN* '<expression>'::
 '<expression>' *NOT IN* '<expression>'::
        Checks whether the value of the first expression is included in the value
 '<expression>' *IN* '<expression>'::
 '<expression>' *NOT IN* '<expression>'::
        Checks whether the value of the first expression is included in the value


@@ -177,6 +186,26 @@ The following fields may be queried:
        an attribute value with some other value, the two values will be cast to
        strings before comparing them.
 
        an attribute value with some other value, the two values will be cast to
        strings before comparing them.
 

+*value*::
+       *(Attributes only)* The value of an attribute. Attributes may be accessed
+       by iterating the values of the parent object and this field provides
+       access to its value in that case. See *attribute[*'<name>'*]* above for
+       details about how to handle attribute values.
+
+*timeseries*::
+       *(Metrics only)* A boolean value indicating whether a backend data-store
+       for fetching time-series information is known to SysDB. See the section
+       "Metrics and Time-Series" in manpage:sysdb[7] for details.
+
+Field expressions may be applied to parent or child nodes. For example, a
+host's services are child objects and the host is the parent of the service
+objects. This is done using typed expressions:
+
+host|service|metric.'<field>'::
+       Evaluate the field in the context of the respective parent or child.
+       Currently, this is limited to services or metrics referencing their parent
+       host.
+

 The following logical operators are supported by SysDB. Unless otherwise
 noted, the data types of the left hand and right hand side have to match.
 
 The following logical operators are supported by SysDB. Unless otherwise
 noted, the data types of the left hand and right hand side have to match.
 


@@ -200,7 +229,7 @@ noted, the data types of the left hand and right hand side have to match.
        Checks whether a value compares less than, less than or equal to, greater
        than or equal, or greater than some other value.
 
        Checks whether a value compares less than, less than or equal to, greater
        than or equal, or greater than some other value.
 

-The following arithmetic operators are supported by SysDB. Unless otherwise 
+The following arithmetic operators are supported by SysDB. Unless otherwise

 noted, the data types of the left hand and right hand side have to match.
 
 *+*::
 noted, the data types of the left hand and right hand side have to match.
 
 *+*::


@@ -236,7 +265,7 @@ storing the different data types:
        provided as well. If omitted, the current time on the server will be used
        instead.
 
        provided as well. If omitted, the current time on the server will be used
        instead.
 

-*STORE* metric '<hostname>'.'<name>' STORE '<type>' '<id>' [*LAST UPDATE* '<datetime>']::
+*STORE* metric '<hostname>'.'<name>' STORE '<type>' '<id>' ['<datetime>'] [*LAST UPDATE* '<datetime>']::

        Store a metric and provide information about the metric store associated
        with it. A metric store describes how to access a metric's data and can be
        used to retrieve time-series information associated with the metric. See
        Store a metric and provide information about the metric store associated
        with it. A metric store describes how to access a metric's data and can be
        used to retrieve time-series information associated with the metric. See