![[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'
FETCH host 'some.host.name';
LOOKUP hosts MATCHING attribute['architecture'] = 'amd64'
+ AND 'backend::collectd::unixsock' in backend
FILTER age < 5 * interval;
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[]
DESCRIPTION
-----------
include::sysdb-description.txt[]
the Standard Query Language (SQL) supported by relational database management
systems (RDBMS) but specialized for SysDB's use-case.
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
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.
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>' *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
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.
Parentheses ('()') may be used around subexpressions to group them and enforce
precedence.
*||*::
Concatenate string or array values.
*||*::
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
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.
(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
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
--------
EXAMPLES
--------
[{
"name": "host1.example.com",
"last_update": "2001-02-03 04:05:06 +0700",
[{
"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",
},{
"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';
}]
FETCH host 'host1.example.com';
"name": "host1.example.com",
"last_update": "2001-02-03 04:05:06 +0700",
"update_interval": "5m4s",
"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",
"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",
},{
...
}],
"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",
"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",
"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",
},{
...
}],
"services": [{
"name": "some service",
"last_update": "2001-02-03 04:05:06 +0700",
- "update_interval": "5m4s"
+ "update_interval": "5m4s",
+ "backend": ['backend::mk-livestatus']
},{
...
}]},{
},{
...
}]},{