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 MATCHING clause
  62 ~~~~~~~~~~~~~~~
  63 The *MATCHING* clause in a query specifies a boolean expression which is used
  64 to match host objects based on their names, their attributes, or services
  65 referenced by the host. Each *MATCHING* clause may be made up of one or
  66 multiple subexpressions each matching on one criteria. The following
  67 subexpressions are supported by SysDB:
  68
  69 '<field>' '<operator>' '<value>'::
  70         Match a named field against the specified value. See below for what fields
  71         and operators are supported.
  72
  73 *NOT* '<subexpression>'::
  74         Invert the boolean result of the specified subexpression.
  75
  76 '<subexpression>' *AND* '<subexpression>'::
  77 '<subexpression>' *OR* '<subexpression>'::
  78         Combine multiple subexpressions using logical AND or logical OR.
  79
  80 The following fields may be queried:
  81
  82 *host*::
  83         The full name of the host.
  84
  85 *service*::
  86         The full service name as referenced by the host.
  87
  88 *attribute*::
  89         The full name of a host attribute.
  90
  91 *attribute.*'<name>'::
  92         The value of the named host attribute. If an attribute of the specified
  93         does not exist, each comparison is treated as if the value does not match.
  94         See the documentation for the *IS NULL* and *IS NOT NULL* operators for
  95         ways to check if an attribute exists.
  96
  97 '<value>' may either be a string (when matching by object names) or match the
  98 type of the attribute's value (when matching attribute values). Attribute
  99 values may either be a string, integer, decimal number, or a date-time value
 100 (booleans and binary data are not supported by the frontend yet).
 101
 102 When comparing an attribute's value using a regular expression matcher, the
 103 value will be cast to a string before doing so. No other casts are supported
 104 at this time.
 105
 106 The following operators may be used to match field values:
 107
 108 *=*::
 109         Evaluates to true if the field value exactly matches the specified value.
 110
 111 *!=*::
 112         Evaluates to true if the field value does not match the exact specified
 113         value.
 114
 115 *=~*::
 116         Evaluates to true if the field value matches the specified regular
 117         expression. SysDB uses POSIX extended regular expressions.
 118
 119 *!~*::
 120         Evalues to true if the field value does not match the specified regular
 121         expression.
 122
 123 The following operators may be used, in addition, to match attribute values:
 124
 125 *<*, *\<=*, *>=*, *>*::
 126         Evaluates to true if the attribute value is less than, less than or equal
 127         to, greater than or equal to or greater than the specified value.
 128
 129 In addition, a named attribute may be checked for existence using the *IS
 130 NULL* and *IS NOT NULL* operators. An attribute is considered to be *NULL* if
 131 it is not set for a host.
 132
 133 FILTER clause
 134 ~~~~~~~~~~~~~
 135 The *FILTER* clause in a query specifies a boolean expression which is used to
 136 filter objects included in the query's response. The filter is applied to
 137 hosts, services, and attributes alike and, thus, will usually be based on the
 138 core properties of the stored objects. The basic syntax for filter clauses is
 139 the same as for matching clauses (see the description about subexpressions
 140 above).
 141
 142 The following fields (core properties) of stored objects may be queried:
 143
 144 *:last_update*::
 145         The timestamp of the last update of the object. This value is based on
 146         information provided by the queried backend if possible.
 147
 148 *:age*::
 149         The amount of time since the last update of the object.
 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.
 156
 157 *:backend*::
 158         The name of the backend (plugin) providing the data.
 159
 160 The type of the *last_update*, *age*, and *interval* fields is date-time and
 161 the type of the *backend* field is string. All conditional operators may be
 162 used to compare the date-time fields (but not regular expression or *IS NULL*
 163 operators). The backend field may only be matched by (in)equality. Each object
 164 may be provided by multiple backends. The filter matches if the specified
 165 value matches any of them.
 166
 167 RESPONSE FORMAT
 168 ---------------
 169 The JavaScript Object Notation (JSON) format, as specified in RFC 4627, is
 170 used in all replies from the server. http://www.ietf.org/rfc/rfc4627.txt
 171
 172 EXAMPLES
 173 --------
 174 The following examples illustrate the use of the commands and what their
 175 replies look like. The replies are pretty-printed to more easily follow them.
 176
 177   LIST hosts;
 178   {"hosts":[{
 179       "name": "host1.example.com",
 180       "last_update": "2001-02-03 04:05:06 +0700",
 181       "update_interval": "5m4s"
 182     },{
 183       "name": "host2.example.com",
 184       "last_update": "2001-02-03 04:05:06 +0700",
 185       "update_interval": "5m4s"
 186     }]}
 187
 188   FETCH host 'host1.example.com';
 189   {
 190       "name": "host1.example.com",
 191       "last_update": "2001-02-03 04:05:06 +0700",
 192       "update_interval": "5m4s",
 193       "attributes": [{
 194           "name": "architecture",
 195           "value": "amd64",
 196           "last_update": "2001-02-03 04:05:06 +0700",
 197           "update_interval": "5m4s"
 198         },{
 199           ...
 200         }],
 201       "services": [{
 202           "name": "some service",
 203           "last_update": "2001-02-03 04:05:06 +0700",
 204           "update_interval": "5m4s"
 205         },{
 206           ...
 207         }]}
 208
 209   LOOKUP hosts MATCHING attribute.architecture = 'amd64';
 210   [{
 211       "name": "host1.example.com",
 212       "last_update": "2001-02-03 04:05:06 +0700",
 213       "update_interval": "5m4s",
 214       "attributes": [{
 215           "name": "architecture",
 216           "value": "amd64",
 217           "last_update": "2001-02-03 04:05:06 +0700",
 218           "update_interval": "5m4s"
 219         },{
 220           ...
 221         }],
 222       "services": [{
 223           "name": "some service",
 224           "last_update": "2001-02-03 04:05:06 +0700",
 225           "update_interval": "5m4s"
 226         },{
 227           ...
 228     }]},{
 229       ...
 230     }]
 231
 232 SEE ALSO
 233 --------
 234 manpage:sysdb[1], manpage:sysdb[7]
 235
 236 The SysDB homepage: http://sysdb.io/
 237
 238 AUTHOR
 239 ------
 240 SysDB was written by Sebastian "tokkee" Harl <sh@tokkee.org>.
 241
 242 COPYRIGHT
 243 ---------
 244 Copyright (C) 2012-2014 Sebastian "tokkee" Harl <sh@tokkee.org>
 245
 246 This is free software under the terms of the BSD license, see the source for
 247 copying conditions. There is NO WARRANTY; not even for MERCHANTABILITY or
 248 FITNESS FOR A PARTICULAR PURPOSE.
 249
 250 // vim: set tw=78 sw=4 ts=4 noexpandtab spell spelllang=en_us :
 251