![[tokkee]](http://tokkee.org/images/avatar.png){kind=avatar}
diff --git a/doc/sysdbql.7.txt b/doc/sysdbql.7.txt
index 3ef41c12bd0166fd8d2e0d131943bfacff80584a..c0cecba8dfe55cbaafe839139c6ecd19510fcadf 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
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*::
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.
+ evaluates to false. 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.
*||*::
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>' [*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']
},{
...
}]},{