X-Git-Url: https://git.tokkee.org/?p=sysdb.git;a=blobdiff_plain;f=doc%2Fsysdbql.7.txt;h=587cd6cc72bee0fe71d2f046480bea47aa9f59de;hp=3ef41c12bd0166fd8d2e0d131943bfacff80584a;hb=0a3dd5b9b97e25156412a95bcecf25f8d75c72fc;hpb=69b354e9c3e5358666dad1a97bc17b52f8869ed3 diff --git a/doc/sysdbql.7.txt b/doc/sysdbql.7.txt index 3ef41c1..587cd6c 100644 --- a/doc/sysdbql.7.txt +++ b/doc/sysdbql.7.txt @@ -15,8 +15,12 @@ SYNOPSIS 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[] @@ -26,6 +30,9 @@ request to retrieve data from a SysDB daemon. It is very remotely similar to 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 @@ -106,15 +113,15 @@ Boolean expressions may use the following operators: match except for a few cases as noted in the documentation of the respective operator. -*ANY* '' '' '':: - 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* '' '' '':: + 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* '' '' '':: - *ALL* is similar to the *ANY* operator but matches if all child objects - match or if no children exist. +*ALL* '' '' '':: + *ALL* is similar to the *ANY* operator but matches if all elements match + or if no elements exist. '' *IS NULL*:: '' *IS NOT NULL*:: @@ -122,12 +129,21 @@ 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). +'' *IS TRUE*:: +'' *IS NOT TRUE*:: +'' *IS FALSE*:: +'' *IS NOT FALSE*:: + Check whether an expression evaluates to a boolean *true* or *false* value + (or not). + '' *IN* '':: +'' *NOT IN* '':: 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. @@ -168,6 +184,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. +*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[*''*]* 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.'':: + 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. @@ -191,7 +227,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. -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. *+*:: @@ -211,6 +247,33 @@ 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 '' [*LAST UPDATE* '']:: +*STORE* service|metric ''.'' [*LAST UPDATE* '']:: +*STORE* host attribute ''.'' '' [*LAST UPDATE* '']:: +*STORE* service|metric attribute ''.''.'' '' [*LAST UPDATE* '']:: + 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 ''.'' STORE '' '' [''] [*LAST UPDATE* '']:: + 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 @@ -246,10 +309,18 @@ all types may be used in any place where a value is expected. (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 ('[,,...]'). 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 -------- @@ -260,11 +331,13 @@ replies look like. The replies are pretty-printed to more easily follow them. [{ "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'; @@ -272,18 +345,21 @@ replies look like. The replies are pretty-printed to more easily follow them. "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'] },{ ... }]} @@ -293,18 +369,21 @@ replies look like. The replies are pretty-printed to more easily follow them. "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'] },{ ... }]},{