![[tokkee]](http://tokkee.org/images/avatar.png){kind=avatar}
diff --git a/doc/sysdbql.7.txt b/doc/sysdbql.7.txt
index 3ef41c12bd0166fd8d2e0d131943bfacff80584a..9c8b3057cf062eea4ca7fe9720bd9483cdbe5e39 100644 (file)
--- a/doc/sysdbql.7.txt
+++ b/doc/sysdbql.7.txt
FETCH host 'some.host.name';
LOOKUP hosts MATCHING attribute['architecture'] = 'amd64'
+ AND 'backend::collectd::unixsock' in backend
FILTER age < 5 * interval;
+ STORE host attribute 'some.host.name'.'key' 123.45
+ LAST UPDATE 2001-02-03 04:05:06;
+
DESCRIPTION
-----------
include::sysdb-description.txt[]
the Standard Query Language (SQL) supported by relational database management
systems (RDBMS) but specialized for SysDB's use-case.
+Besides querying data, SysQL may also be used to store or update objects in
+SysDB.
+
QUERY COMMANDS
--------------
Each command is terminated by a semicolon. The following commands are
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
-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
~~~~~~~~~~~~~~~
match except for a few cases as noted in the documentation of the
respective operator.
-*ANY* '<object_type>' '<cmp>' '<expression>'::
- Compares the objects of an iterable child using any compare operator.
- Evaluates to true if any of those child objects matches or false if no
- such children exist. Otherwise, the same rules as for other comparison
- operations apply.
+*ANY* '<iterable>' '<cmp>' '<expression>'::
+ Compares each element of an iterable using any compare operator. Evaluates
+ to true if any of the elements matches or false if no such elements exist.
+ Otherwise, the same rules as for other comparison operations apply.
+ Attributes, a host's services and metrics, and arrays are iterables.
-*ALL* '<object_type>' '<cmp>' '<expression>'::
- *ALL* is similar to the *ANY* operator but matches if all child objects
- match or if no children exist.
+*ALL* '<iterable>' '<cmp>' '<expression>'::
+ *ALL* is similar to the *ANY* operator but matches if all elements match
+ or if no elements exist.
'<expression>' *IS NULL*::
'<expression>' *IS NOT NULL*::
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
- of the second expression which has to be an array value (e.g., *backend*
- field). If the second value is not an array or if the type of the first
- value does not match the array's element type, the expression always
- evaluates to false.
+ of the second expression (or not). The second value has to be an array
+ value (e.g., *backend* field) and the type of the first value has to match
+ the array's element type. The first value may also be an array. In this
+ case, the expression evaluates to true if all elements of that array are
+ included in the second array where order does not matter.
Parentheses ('()') may be used around subexpressions to group them and enforce
precedence.
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.
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.
*+*::
*||*::
Concatenate string or array values.
+STORING DATA
+------------
+The *STORE* command may be used to store or update an object in SysDB. Each
+command is terminated by a semicolon. The following variants are available for
+storing the different data types:
+
+*STORE* host '<name>' [*LAST UPDATE* '<datetime>']::
+*STORE* service|metric '<hostname>'.'<name>' [*LAST UPDATE* '<datetime>']::
+*STORE* host attribute '<hostname>'.'<key>' '<value>' [*LAST UPDATE* '<datetime>']::
+*STORE* service|metric attribute '<hostname>'.'<name>'.'<key>' '<value>' [*LAST UPDATE* '<datetime>']::
+ Store an object of the specified type and name. For services, metrics, and
+ attributes, the name is prepended with the parent object name separated by
+ a dot ('.'). Optionally, the time-stamp of the object's last update may be
+ provided as well. If omitted, the current time on the server will be used
+ instead.
+
+*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
+ the manpage:sysdb[7] manpage for details.
+.
+ Note that the metric store information will be forwarded to the server
+ unmodified. That is, they need to be specified in a way such that the
+ server can make sense out of them. Else, retrieval of time-series data
+ will fail.
+
DATA TYPES
----------
The SysDB query language natively supports various data-types. Constants of
(minutes), *s* (seconds), *ms* (milliseconds), *us* (microseconds), or
*ns* (nanoseconds). Note that years and months are approximations.
+*Array constants*::
+ An array stores of one or more values of the same type. It may be
+ specified as a comma-separated list of constant values enclosed in square
+ brackets ('[<elem1>,<elem2>,...]'). For each value, the same rules apply
+ as for a regular constant value of that type.
+
RESPONSE FORMAT
---------------
The JavaScript Object Notation (JSON) format, as specified in RFC 4627, is
-used in all replies from the server. http://www.ietf.org/rfc/rfc4627.txt
+used in all query replies from the server. http://www.ietf.org/rfc/rfc4627.txt
+
+For all other commands, the reply will be a message string.
EXAMPLES
--------
[{
"name": "host1.example.com",
"last_update": "2001-02-03 04:05:06 +0700",
- "update_interval": "5m4s"
+ "update_interval": "5m4s",
+ "backend": ['backend::mk-livestatus']
},{
"name": "host2.example.com",
"last_update": "2001-02-03 04:05:06 +0700",
- "update_interval": "5m4s"
+ "update_interval": "10s",
+ "backend": ['backend::mk-livestatus','backend::collectd::unixsock']
}]
FETCH host 'host1.example.com';
"name": "host1.example.com",
"last_update": "2001-02-03 04:05:06 +0700",
"update_interval": "5m4s",
+ "backend": ['backend::mk-livestatus'],
"attributes": [{
"name": "architecture",
"value": "amd64",
"last_update": "2001-02-03 04:05:06 +0700",
- "update_interval": "5m4s"
+ "update_interval": "5m4s",
+ "backend": ['backend::mk-livestatus']
},{
...
}],
"services": [{
"name": "some service",
"last_update": "2001-02-03 04:05:06 +0700",
- "update_interval": "5m4s"
+ "update_interval": "5m4s",
+ "backend": ['backend::mk-livestatus']
},{
...
}]}
"name": "host1.example.com",
"last_update": "2001-02-03 04:05:06 +0700",
"update_interval": "5m4s",
+ "backend": ['backend::mk-livestatus'],
"attributes": [{
"name": "architecture",
"value": "amd64",
"last_update": "2001-02-03 04:05:06 +0700",
- "update_interval": "5m4s"
+ "update_interval": "5m4s",
+ "backend": ['backend::mk-livestatus']
},{
...
}],
"services": [{
"name": "some service",
"last_update": "2001-02-03 04:05:06 +0700",
- "update_interval": "5m4s"
+ "update_interval": "5m4s",
+ "backend": ['backend::mk-livestatus']
},{
...
}]},{