doc/sysdbql.7.txt

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