sysdb(1), sysdbd(1): Document client authentication.

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

diff --git a/doc/sysdbql.7.txt b/doc/sysdbql.7.txt
index 5e9fb8558141763f4238fe1e0df4808bd62c1f5a..c0cecba8dfe55cbaafe839139c6ecd19510fcadf 100644 (file)
--- 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
@@ -213,6 +220,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 '<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
@@ -248,10 +282,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 ('[<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
 --------
@@ -262,11 +304,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';
@@ -274,18 +318,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']
         },{
           ...
         }]}
@@ -295,18 +342,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']
         },{
           ...
     }]},{