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;
  13
  14   LOOKUP hosts MATCHING attribute.architecture = 'amd64';
  15
  16 DESCRIPTION
  17 -----------
  18 include::sysdb-description.txt[]
  19
  20 The SysDB query language is a human-readable format for describing a request
  21 to retrieve data from a SysDB daemon. It is very remotely similar to the
  22 Standard Query Language (SQL) supported by relational database management
  23 systems (RDBMS) but specialized for SysDB's use-case.
  24
  25 QUERY COMMANDS
  26 --------------
  27 Each command is terminated by a semicolon. The following commands are
  28 available to retrieve information from SysDB:
  29
  30 *LIST*::
  31 Retrieve a sorted (by name) list of all hosts currently stored in SysDB. The
  32 return value is a list of hosts where each host description includes its name,
  33 the timestamp of the last update of the object in SysDB and an approximation
  34 of the interval with which the host was updated.
  35
  36 *FETCH* '<hostname>'::
  37 Retrieve detailed information about the specified host object. The return
  38 value includes the hostname, a list of services referenced by the host, and a
  39 list of attributes for the host and each service. If the host does not exist,
  40 an error is returned.
  41
  42 *LOOKUP* hosts *MATCHING* '<search_condition>' [*FILTER* '<filter_condition>']::
  43 Retrieve detailed information about all host objects matching the specified
  44 search condition. The return value is a list of detailed information for each
  45 matching host providing the same details as returned by the *FETCH* command.
  46 If a filter condition is specified, only objects matching that filter will be
  47 included in the reply. See the sections "MATCHING clause" and "FILTER clause"
  48 for more details about how to specify the search and filter conditions.
  49
  50 MATCHING clause
  51 ~~~~~~~~~~~~~~~
  52 The *MATCHING* clause in a query specifies a boolean expression which is used
  53 to match host objects based on their names, their attributes, or services
  54 referenced by the host. Each *MATCHING* clause may be made up of one or
  55 multiple subexpressions each matching on one criteria. The following
  56 subexpressions are supported by SysDB:
  57
  58 '<field>' '<operator>' '<value>'::
  59         Match a named field against the specified value. See below for what fields
  60         and operators are supported.
  61
  62 *NOT* '<subexpression>'::
  63         Invert the boolean result of the specified subexpression.
  64
  65 '<subexpression>' *AND* '<subexpression>'::
  66 '<subexpression>' *OR* '<subexpression>'::
  67         Combine multiple subexpressions using logical AND or logical OR.
  68
  69 The following fields may be queried:
  70
  71 *host*::
  72         The full name of the host.
  73
  74 *service*::
  75         The full service name as referenced by the host.
  76
  77 *attribute*::
  78         The full name of a host attribute.
  79
  80 *attribute.*'<name>'::
  81         The value of the named host attribute. If an attribute of the specified
  82         does not exist, each comparison is treated as if the value does not match.
  83
  84 '<value>' may either be a string (when matching by object names) or match the
  85 type of the attribute's value (when matching attribute values). Attribute
  86 values may either be a string, integer, decimal number, or a date-time value
  87 (booleans and binary data are not supported by the frontend yet).
  88
  89 When comparing an attribute's value using a regular expression matcher, the
  90 value will be cast to a string before doing so. No other casts are supported
  91 at this time.
  92
  93 The following operators may be used to match field values:
  94
  95 *=*::
  96         Evaluates to true if the field value exactly matches the specified value.
  97
  98 *!=*::
  99         Evaluates to true if the field value does not match the exact specified
 100         value.
 101
 102 *=~*::
 103         Evaluates to true if the field value matches the specified regular
 104         expression. SysDB uses POSIX extended regular expressions.
 105
 106 *!~*::
 107         Evalues to true if the field value does not match the specified regular
 108         expression.
 109
 110 The following operators may be used, in addition, to match attribute values:
 111
 112 *<*, *\<=*, *>=*, *>*::
 113         Evaluates to true if the attribute value is less than, less than or equal
 114         to, greater than or equal to or greater than the specified value.
 115
 116 In addition, a named attribute may be check for existence using the *IS NULL*
 117 and *IS NOT NULL* expressions. An attribute is considered to be *NULL* if it
 118 is not set for a host.
 119
 120 FILTER clause
 121 ~~~~~~~~~~~~~
 122 The *FILTER* clause in a query specifies a boolean expression which is used to
 123 filter objects included in the query's response. The filter is applied to
 124 hosts, services, and attributes alike and, thus, will usually be based on the
 125 core properties of the stored objects. The basic syntax for filter clauses is
 126 the same as for matching clauses (see the description about subexpressions
 127 above).
 128
 129 The following common fields of stored objects may be queried:
 130
 131 *:last_update*::
 132         The timestamp of the last update of the object.
 133
 134 *:age*::
 135         The amount of time since the last update of the object.
 136
 137 *:interval*::
 138         The interval with which the object gets updated. This value is determined
 139         automatically based on a moving average determined from the update
 140         timestamps of an object. It depends on the update timestamps as provided
 141         by the backend (if available) and SysDB's query interval.
 142
 143 *:backend*::
 144         The name of the backend (plugin) providing the data.
 145
 146 The type of the *last_update*, *age*, and *interval* fields is date-time and
 147 the type of the *backend* field is string. All conditional operators may be
 148 used to compare the date-time fields (but not regular expression or *IS NULL*
 149 operators). The backend field may only be matched by (in)equality. Each object
 150 may be provided by multiple backends. The filter matches if the specified
 151 value matches any of them.
 152
 153 RESPONSE FORMAT
 154 ---------------
 155 The JavaScript Object Notation (JSON) format, as specified in RFC 4627, is
 156 used in all replies from the server. http://www.ietf.org/rfc/rfc4627.txt
 157
 158 EXAMPLES
 159 --------
 160 The following examples illustrate the use of the commands and what their
 161 replies look like. The replies are pretty-printed to more easily follow them.
 162
 163   LIST;
 164   {"hosts":[{
 165       "name": "host1.example.com",
 166       "last_update": "2001-02-03 04:05:06 +0700",
 167       "update_interval": "5m4s"
 168     },{
 169       "name": "host2.example.com",
 170       "last_update": "2001-02-03 04:05:06 +0700",
 171       "update_interval": "5m4s"
 172     }]}
 173
 174   FETCH 'host1.example.com';
 175   {
 176       "name": "host1.example.com",
 177       "last_update": "2001-02-03 04:05:06 +0700",
 178       "update_interval": "5m4s",
 179       "attributes": [{
 180           "name": "architecture",
 181           "value": "amd64",
 182           "last_update": "2001-02-03 04:05:06 +0700",
 183           "update_interval": "5m4s"
 184         },{
 185           ...
 186         }],
 187       "services": [{
 188           "name": "some service",
 189           "last_update": "2001-02-03 04:05:06 +0700",
 190           "update_interval": "5m4s"
 191         },{
 192           ...
 193         }]}
 194
 195   LOOKUP hosts MATCHING attribute.architecture = 'amd64';
 196   [{
 197       "name": "host1.example.com",
 198       "last_update": "2001-02-03 04:05:06 +0700",
 199       "update_interval": "5m4s",
 200       "attributes": [{
 201           "name": "architecture",
 202           "value": "amd64",
 203           "last_update": "2001-02-03 04:05:06 +0700",
 204           "update_interval": "5m4s"
 205         },{
 206           ...
 207         }],
 208       "services": [{
 209           "name": "some service",
 210           "last_update": "2001-02-03 04:05:06 +0700",
 211           "update_interval": "5m4s"
 212         },{
 213           ...
 214     }]},{
 215       ...
 216     }]
 217
 218 SEE ALSO
 219 --------
 220 manpage:sysdb[1], manpage:sysdb[7]
 221
 222 The SysDB homepage: http://sysdb.io/
 223
 224 AUTHOR
 225 ------
 226 SysDB was written by Sebastian "tokkee" Harl <sh@tokkee.org>.
 227
 228 COPYRIGHT
 229 ---------
 230 Copyright (C) 2012-2014 Sebastian "tokkee" Harl <sh@tokkee.org>
 231
 232 This is free software under the terms of the BSD license, see the source for
 233 copying conditions. There is NO WARRANTY; not even for MERCHANTABILITY or
 234 FITNESS FOR A PARTICULAR PURPOSE.
 235
 236 // vim: set tw=78 sw=4 ts=4 noexpandtab spell spelllang=en_us :
 237