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   QUERY hosts WHERE 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 *WHERE* '<search_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 See the section "WHERE clause" for more details about how to specify the
  47 search condition.
  48
  49 WHERE clause
  50 ~~~~~~~~~~~~
  51 The *WHERE* clause in a query specifies a boolean expression which is used to
  52 match host objects based on their names, their attributes, or services
  53 referenced by the host. Each *WHERE* clause may be made up of one or multiple
  54 subexpressions each matching on one criteria. The following subexpressions
  55 are supported by SysDB:
  56
  57 '<field>' '<operator>' '<value>'::
  58         Match a named field against the specified value. See below for what fields
  59         and operators are supported.
  60
  61 *NOT* '<subexpression>'::
  62         Invert the boolean result of the specified subexpression.
  63
  64 '<subexpression>' *AND* '<subexpression>'::
  65 '<subexpression>' *OR* '<subexpression>'::
  66         Combine multiple subexpressions using logical AND or logical OR.
  67
  68 The following fields may be queried:
  69
  70 *host*::
  71         The full name of the host.
  72
  73 *service*::
  74         The full service name as referenced by the host.
  75
  76 *attribute*::
  77         The full name of a host attribute.
  78
  79 *attribute.*'<name>'::
  80         The value of the named host attribute. If an attribute of the specified
  81         does not exist, each comparison is treated as if the value does not match.
  82
  83 '<value>' may either be a string (when matching by object names) or match the
  84 type of the attribute's value (when matching attribute values). Attribute
  85 values may either be a string, integer, or decimal number (booleans and binary
  86 data are not supported by the frontend yet).
  87
  88 When comparing an attribute's value using a regular expression matcher, the
  89 value will be cast to a string before doing so. No other casts are supported
  90 at this time.
  91
  92 The following operators may be used to match field values:
  93
  94 *=*::
  95         Evaluates to true if the field value exactly matches the specified value.
  96
  97 *!=*::
  98         Evaluates to true if the field value does not match the exact specified
  99         value.
 100
 101 *=~*::
 102         Evaluates to true if the field value matches the specified regular
 103         expression. SysDB uses POSIX extended regular expressions.
 104
 105 *!~*::
 106         Evalues to true if the field value does not match the specified regular
 107         expression.
 108
 109 The following operators may be used, in addition, to match attribute values:
 110
 111 *<*, *\<=*, *>=*, *>*::
 112         Evaluates to true if the attribute value is less than, less than or equal
 113         to, greater than or equal to or greater than the specified value.
 114
 115 In addition, a named attribute may be check for existence using the *IS NULL*
 116 and *IS NOT NULL* expressions. An attribute is considered to be *NULL* if it
 117 is not set for a host.
 118
 119 RESPONSE FORMAT
 120 ---------------
 121 The JavaScript Object Notation (JSON) format, as specified in RFC 4627, is
 122 used in all replies from the server. http://www.ietf.org/rfc/rfc4627.txt
 123
 124 EXAMPLES
 125 --------
 126 The following examples illustrate the use of the commands and what their
 127 replies look like. The replies are pretty-printed to more easily follow them.
 128
 129   LIST;
 130   {"hosts":[{
 131       "name": "host1.example.com",
 132       "last_update": "2001-02-03 04:05:06 +0700",
 133       "update_interval": "5m4s"
 134     },{
 135       "name": "host2.example.com",
 136       "last_update": "2001-02-03 04:05:06 +0700",
 137       "update_interval": "5m4s"
 138     }]}
 139
 140   FETCH 'host1.example.com';
 141   {
 142       "name": "host1.example.com",
 143       "last_update": "2001-02-03 04:05:06 +0700",
 144       "update_interval": "5m4s",
 145       "attributes": [{
 146           "name": "architecture",
 147           "value": "amd64",
 148           "last_update": "2001-02-03 04:05:06 +0700",
 149           "update_interval": "5m4s"
 150         },{
 151           ...
 152         }],
 153       "services": [{
 154           "name": "some service",
 155           "last_update": "2001-02-03 04:05:06 +0700",
 156           "update_interval": "5m4s"
 157         },{
 158           ...
 159         }]}
 160
 161   LOOKUP hosts WHERE attribute.architecture = 'amd64';
 162   [{
 163       "name": "host1.example.com",
 164       "last_update": "2001-02-03 04:05:06 +0700",
 165       "update_interval": "5m4s",
 166       "attributes": [{
 167           "name": "architecture",
 168           "value": "amd64",
 169           "last_update": "2001-02-03 04:05:06 +0700",
 170           "update_interval": "5m4s"
 171         },{
 172           ...
 173         }],
 174       "services": [{
 175           "name": "some service",
 176           "last_update": "2001-02-03 04:05:06 +0700",
 177           "update_interval": "5m4s"
 178         },{
 179           ...
 180     }]},{
 181       ...
 182     }]
 183
 184 SEE ALSO
 185 --------
 186 manpage:sysdb[1], manpage:sysdb[7]
 187
 188 The SysDB homepage: http://sysdb.io/
 189
 190 AUTHOR
 191 ------
 192 SysDB was written by Sebastian "tokkee" Harl <sh@tokkee.org>.
 193
 194 COPYRIGHT
 195 ---------
 196 Copyright (C) 2012-2014 Sebastian "tokkee" Harl <sh@tokkee.org>
 197
 198 This is free software under the terms of the BSD license, see the source for
 199 copying conditions. There is NO WARRANTY; not even for MERCHANTABILITY or
 200 FITNESS FOR A PARTICULAR PURPOSE.
 201
 202 // vim: set tw=78 sw=4 ts=4 noexpandtab spell spelllang=en_us :
 203