doc/sysdbql.7.txt

   1 sysdbql(7)
   2 ==========
   3 :doctype: manpage
   4
   5 NAME
   6 ----
   7 sysdbql - the SysDB query language
   8
   9 SYNOPSIS
  10 --------
  11
  12   LIST hosts;
  13
  14   FETCH host 'some.host.name';
  15
  16   LOOKUP hosts MATCHING attribute.architecture = 'amd64'
  17                FILTER :age < 5 * :interval;
  18
  19 DESCRIPTION
  20 -----------
  21 include::sysdb-description.txt[]
  22
  23 The SysDB query language is a human-readable format for describing a request
  24 to retrieve data from a SysDB daemon. It is very remotely similar to the
  25 Standard Query Language (SQL) supported by relational database management
  26 systems (RDBMS) but specialized for SysDB's use-case.
  27
  28 QUERY COMMANDS
  29 --------------
  30 Each command is terminated by a semicolon. The following commands are
  31 available to retrieve information from SysDB:
  32
  33 *LIST* hosts [*FILTER* '<filter_condition>']::
  34 Retrieve a sorted (by name) list of all hosts currently stored in SysDB. The
  35 return value is a list of hosts where each host specification includes its
  36 name, the timestamp of the last update of the object known to SysDB and an
  37 approximation of the interval with which the host was updated. If a filter
  38 condition is specified, only objects matching that filter will be included in
  39 the reply. See the section "FILTER clause" for more details about how to
  40 specify the search and filter conditions.
  41
  42 *FETCH* host '<hostname>' [*FILTER* '<filter_condition>']::
  43 Retrieve detailed information about the specified host object. The return
  44 value includes the hostname, a list of services referenced by the host, and a
  45 list of attributes for the host and each service. If the host does not exist,
  46 an error is returned. If a filter condition is specified, only objects
  47 matching that filter will be included in the reply. See the section "FILTER
  48 clause" for more details about how to specify the search and filter
  49 conditions.
  50
  51 *LOOKUP* hosts *MATCHING* '<search_condition>' [*FILTER* '<filter_condition>']::
  52 Retrieve detailed information about all host objects matching the specified
  53 search condition. The return value is a list of detailed information for each
  54 matching host providing the same details as returned by the *FETCH* command.
  55 If no host matches the search criteria, it's not considered an error. Instead,
  56 an empty list is returned. If a filter condition is specified, only objects
  57 matching that filter will be included in the reply. See the sections "MATCHING
  58 clause" and "FILTER clause" for more details about how to specify the search
  59 and filter conditions.
  60
  61 *TIMESERIES* '<hostname>'.'<metric>' [START '<datetime>'] [END '<datetime>']::
  62 Retrieve a time-series for the specified host's metric. The data is retrieved
  63 from a backend data-store based on information provided by the respective
  64 query plugin. The return value includes the actual start and end time of the
  65 time-series and one or multiple sequences of time-stamp / value pairs. If the
  66 metric does not exist or if the backend data-store is not supported, an error
  67 is returned.
  68
  69 MATCHING clause
  70 ~~~~~~~~~~~~~~~
  71 The *MATCHING* clause in a query specifies a boolean expression which is used
  72 to match host objects based on their names, their attributes, or services
  73 referenced by the host. Each *MATCHING* clause may be made up of one or
  74 multiple subexpressions each matching on one criteria. The following
  75 subexpressions are supported by SysDB:
  76
  77 '<field>' '<operator>' '<value>'::
  78         Match a named field against the specified value. See below for what fields
  79         and operators are supported.
  80
  81 *NOT* '<subexpression>'::
  82         Invert the boolean result of the specified subexpression.
  83
  84 '<subexpression>' *AND* '<subexpression>'::
  85 '<subexpression>' *OR* '<subexpression>'::
  86         Combine multiple subexpressions using logical AND or logical OR.
  87
  88 The following fields may be queried:
  89
  90 *host*::
  91         The full name of the host.
  92
  93 *service*::
  94         The full service name as referenced by the host.
  95
  96 *attribute*::
  97         The full name of a host attribute.
  98
  99 *attribute.*'<name>'::
 100         The value of the named host attribute. If an attribute of the specified
 101         does not exist, each comparison is treated as if the value does not match.
 102         See the documentation for the *IS NULL* and *IS NOT NULL* operators for
 103         ways to check if an attribute exists.
 104
 105 '<value>' may either be a string (when matching by object names) or match the
 106 type of the attribute's value (when matching attribute values). Attribute
 107 values may either be a string, integer, decimal number, or a date-time value
 108 (booleans and binary data are not supported by the frontend yet). See the
 109 section "DATA TYPES" for more details about how specify each data-type.
 110
 111 When comparing an attribute's value using a regular expression matcher, the
 112 value will be cast to a string before doing so. No other casts are supported
 113 at this time.
 114
 115 The following operators may be used to match field values:
 116
 117 *=*::
 118         Evaluates to true if the field value exactly matches the specified value.
 119
 120 *!=*::
 121         Evaluates to true if the field value does not match the exact specified
 122         value.
 123
 124 *=~*::
 125         Evaluates to true if the field value matches the specified regular
 126         expression. SysDB uses POSIX extended regular expressions.
 127
 128 *!~*::
 129         Evalues to true if the field value does not match the specified regular
 130         expression.
 131
 132 The following operators may be used, in addition, to match attribute values:
 133
 134 *<*, *\<=*, *>=*, *>*::
 135         Evaluates to true if the attribute value is less than, less than or equal
 136         to, greater than or equal to or greater than the specified value.
 137
 138 In addition, a named attribute may be checked for existence using the *IS
 139 NULL* and *IS NOT NULL* operators. An attribute is considered to be *NULL* if
 140 it is not set for a host.
 141
 142 FILTER clause
 143 ~~~~~~~~~~~~~
 144 The *FILTER* clause in a query specifies a boolean expression which is used to
 145 filter objects included in the query's response. The filter is applied to
 146 hosts, services, and attributes alike and, thus, will usually be based on the
 147 core properties of the stored objects. The basic syntax for filter clauses is
 148 the same as for matching clauses (see the description about subexpressions
 149 above).
 150
 151 The following fields (core properties) of stored objects may be queried:
 152
 153 *:last_update*::
 154         The timestamp of the last update of the object. This value is based on
 155         information provided by the queried backend if possible.
 156
 157 *:age*::
 158         The amount of time since the last update of the object.
 159
 160 *:interval*::
 161         The interval with which the object gets updated. This value is determined
 162         automatically based on a moving average determined from the update
 163         timestamps of an object. It depends on the update timestamps as provided
 164         by the backend (if available) and SysDB's query interval.
 165
 166 *:backend*::
 167         The name of the backend (plugin) providing the data.
 168
 169 The type of the *last_update*, *age*, and *interval* fields is date-time and
 170 the type of the *backend* field is string. All conditional operators may be
 171 used to compare the date-time fields (but not regular expression or *IS NULL*
 172 operators). The backend field may only be matched by (in)equality. Each object
 173 may be provided by multiple backends. The filter matches if the specified
 174 value matches any of them.
 175
 176 DATA TYPES
 177 ----------
 178 The SysDB query language natively supports various data-types. Constants of
 179 all types may be used in any place where a value is expected.
 180
 181 *String constants*::
 182         A string constant is an arbitrary sequence of characters enclosed in
 183         single quotes ('''). Single quotes may be included in a string constant by
 184         specifying two adjacent single quotes.
 185
 186 *Integer constants*::
 187         An integer constant may be specified either as a sequence of digits or in
 188         scientific notation written in the form "'a' E 'b'" (without spaces) where
 189         'a' and 'b' are integers. A leading plus or minus sign specifies the sign
 190         of the constant.
 191
 192 *Floating-point constants*::
 193         A floating-point constant is a sequence of digits containing a decimal
 194         point. Digits before or after the decimal point (but not both) are
 195         optional. Floating-point constants may also be specified in scientific
 196         notation by appending the letter "E" and a positive or negative integer
 197         exponent. A leading plus or minus sign specifies the sign of the constant.
 198
 199 *Date and time constants*::
 200         A date constant may be specified as 'YYYY-MM-DD' and time constants may be
 201         specified as 'HH:MM:SS.nnnnnnnnn' where seconds and nanoseconds are
 202         optional.
 203
 204 *Interval constants*::
 205         An interval may be specified by one or multiple quantity and unit pairs.
 206         The quantity may be any integer constant and the unit may be any of the
 207         following: *Y* (years), *M* (months), *D* (days), *h* (hours), *m*
 208         (minutes), *s* (seconds), *ms* (milliseconds), *us* (microseconds), or
 209         *ns* (nanoseconds). Note that years and months are approximations.
 210
 211 RESPONSE FORMAT
 212 ---------------
 213 The JavaScript Object Notation (JSON) format, as specified in RFC 4627, is
 214 used in all replies from the server. http://www.ietf.org/rfc/rfc4627.txt
 215
 216 EXAMPLES
 217 --------
 218 The following examples illustrate the use of the commands and what their
 219 replies look like. The replies are pretty-printed to more easily follow them.
 220
 221   LIST hosts;
 222   {"hosts":[{
 223       "name": "host1.example.com",
 224       "last_update": "2001-02-03 04:05:06 +0700",
 225       "update_interval": "5m4s"
 226     },{
 227       "name": "host2.example.com",
 228       "last_update": "2001-02-03 04:05:06 +0700",
 229       "update_interval": "5m4s"
 230     }]}
 231
 232   FETCH host 'host1.example.com';
 233   {
 234       "name": "host1.example.com",
 235       "last_update": "2001-02-03 04:05:06 +0700",
 236       "update_interval": "5m4s",
 237       "attributes": [{
 238           "name": "architecture",
 239           "value": "amd64",
 240           "last_update": "2001-02-03 04:05:06 +0700",
 241           "update_interval": "5m4s"
 242         },{
 243           ...
 244         }],
 245       "services": [{
 246           "name": "some service",
 247           "last_update": "2001-02-03 04:05:06 +0700",
 248           "update_interval": "5m4s"
 249         },{
 250           ...
 251         }]}
 252
 253   LOOKUP hosts MATCHING attribute.architecture = 'amd64';
 254   [{
 255       "name": "host1.example.com",
 256       "last_update": "2001-02-03 04:05:06 +0700",
 257       "update_interval": "5m4s",
 258       "attributes": [{
 259           "name": "architecture",
 260           "value": "amd64",
 261           "last_update": "2001-02-03 04:05:06 +0700",
 262           "update_interval": "5m4s"
 263         },{
 264           ...
 265         }],
 266       "services": [{
 267           "name": "some service",
 268           "last_update": "2001-02-03 04:05:06 +0700",
 269           "update_interval": "5m4s"
 270         },{
 271           ...
 272     }]},{
 273       ...
 274     }]
 275
 276 SEE ALSO
 277 --------
 278 manpage:sysdb[1], manpage:sysdb[7]
 279
 280 The SysDB homepage: https://sysdb.io/
 281
 282 AUTHOR
 283 ------
 284 SysDB was written by Sebastian "tokkee" Harl <sh@tokkee.org>.
 285
 286 COPYRIGHT
 287 ---------
 288 Copyright (C) 2012-2014 Sebastian "tokkee" Harl <sh@tokkee.org>
 289
 290 This is free software under the terms of the BSD license, see the source for
 291 copying conditions. There is NO WARRANTY; not even for MERCHANTABILITY or
 292 FITNESS FOR A PARTICULAR PURPOSE.
 293
 294 // vim: set tw=78 sw=4 ts=4 noexpandtab spell spelllang=en_us :
 295