doc/sysdbql.7.txt

   1 sysdbdql(7)
   2 ===========
   3 Sebastian "tokkee" Harl <sh@tokkee.org>
   4 version {package_version}, {build_date}
   5 :doctype: manpage
   6
   7 NAME
   8 ----
   9 sysdbql - the SysDB query language
  10
  11 SYNOPSIS
  12 --------
  13
  14   LIST;
  15
  16   QUERY hosts WHERE attribute.architecture = 'amd64';
  17
  18 DESCRIPTION
  19 -----------
  20 SysDB stores system and inventory information about hardware and software
  21 systems. This information is stored in a graph-like hierarchy of generic
  22 objects. The central object type is a host, which generally represents a
  23 physical or virtual machine or any other type of physical resource. Hosts, in
  24 turn, may reference a list of services which represent any kind of logical
  25 resource like a software system. Both, hosts and services, may reference a
  26 list of attributes which represent further information about the respective
  27 host or service object. For example, attributes may specify static information
  28 like a host's architecture or the software version or snapshots of performance
  29 data like the current memory utilization or much more.
  30
  31 The SysDB query language is a human-readable format for describing a request
  32 to retrieve data from a SysDB daemon. It is very remotely similar to the
  33 Standard Query Language (SQL) supported by relational database management
  34 systems (RDBMS) but specialized for SysDB's use-case.
  35
  36 QUERY COMMANDS
  37 --------------
  38 Each command is terminated by a semicolon. The following commands are
  39 available to retrieve information from SysDB:
  40
  41 *LIST*::
  42 Retrieve a sorted (by name) list of all hosts currently stored in SysDB. The
  43 return value is a list of hosts where each host description includes its name,
  44 the timestamp of the last update of the object in SysDB and an approximation
  45 of the interval with which the host was updated.
  46
  47 *FETCH* '<hostname>'::
  48 Retrieve detailed information about the specified host object. The return
  49 value includes the hostname, a list of services referenced by the host, and a
  50 list of attributes for the host and each service. If the host does not exist,
  51 an error is returned.
  52
  53 *LOOKUP* hosts *WHERE* '<search_condition>'::
  54 Retrieve detailed information about all host objects matching the specified
  55 search condition. The return value is a list of detailed information for each
  56 matching host providing the same details as returned by the *FETCH* command.
  57 See the section "WHERE clause" for more details about how to specify the
  58 search condition.
  59
  60 WHERE clause
  61 ~~~~~~~~~~~~
  62 The *WHERE* clause in a query specifies a boolean expression which is used to
  63 match host objects based on their names, their attributes, or services
  64 referenced by the host. Each *WHERE* clause may be made up of one or multiple
  65 subexpressions each matching on one criteria. The following subexpressions
  66 are supported by SysDB:
  67
  68 '<field>' '<operator>' '<value>'::
  69         Match a named field against the specified value. See below for what fields
  70         and operators are supported.
  71
  72 *NOT* '<subexpression>'::
  73         Invert the boolean result of the specified subexpression.
  74
  75 '<subexpression>' *AND* '<subexpression>'::
  76 '<subexpression>' *OR* '<subexpression>'::
  77         Combine multiple subexpressions using logical AND or logical OR.
  78
  79 The following fields may be queried:
  80
  81 *host.name*::
  82         The full name of the host.
  83
  84 *service.name*::
  85         The full service name as referenced by the host.
  86
  87 *attribute.name*::
  88         The full name of a host attribute.
  89
  90 *attribute.*'<name>'::
  91         The value of the named host attribute. If an attribute of the specified
  92         does not exist, each comparison is treated as if the value does not match.
  93
  94 The following operators may be used to match field values:
  95
  96 *=*::
  97         Evaluates to true if the field value exactly matches the specified value.
  98
  99 *!=*::
 100         Evaluates to true if the field value does not match the exact specified
 101         value.
 102
 103 *=~*::
 104         Evaluates to true if the field value matches the specified regular
 105         expression. SysDB uses POSIX extended regular expressions.
 106
 107 *!~*::
 108         Evalues to true if the field value does not match the specified regular
 109         expression.
 110
 111 RESPONSE FORMAT
 112 ---------------
 113 The JavaScript Object Notation (JSON) format, as specified in RFC 4627, is
 114 used in all replies from the server. http://www.ietf.org/rfc/rfc4627.txt
 115
 116 EXAMPLES
 117 --------
 118 The following examples illustrate the use of the commands and what their
 119 replies look like. The replies are pretty-printed to more easily follow them.
 120
 121   LIST;
 122   {"hosts":[{
 123       "name": "host1.example.com",
 124       "last_update": "2001-02-03 04:05:06 +0700",
 125       "update_interval": "5m4s"
 126     },{
 127       "name": "host2.example.com",
 128       "last_update": "2001-02-03 04:05:06 +0700",
 129       "update_interval": "5m4s"
 130     }]}
 131
 132   FETCH 'host1.example.com';
 133   {
 134       "name": "host1.example.com",
 135       "last_update": "2001-02-03 04:05:06 +0700",
 136       "update_interval": "5m4s",
 137       "attributes": [{
 138           "name": "architecture",
 139           "value": "amd64",
 140           "last_update": "2001-02-03 04:05:06 +0700",
 141           "update_interval": "5m4s"
 142         },{
 143           ...
 144         }],
 145       "services": [{
 146           "name": "some service",
 147           "last_update": "2001-02-03 04:05:06 +0700",
 148           "update_interval": "5m4s"
 149         },{
 150           ...
 151         }]}
 152
 153   LOOKUP hosts WHERE attribute.architecture = 'amd64';
 154   [{
 155       "name": "host1.example.com",
 156       "last_update": "2001-02-03 04:05:06 +0700",
 157       "update_interval": "5m4s",
 158       "attributes": [{
 159           "name": "architecture",
 160           "value": "amd64",
 161           "last_update": "2001-02-03 04:05:06 +0700",
 162           "update_interval": "5m4s"
 163         },{
 164           ...
 165         }],
 166       "services": [{
 167           "name": "some service",
 168           "last_update": "2001-02-03 04:05:06 +0700",
 169           "update_interval": "5m4s"
 170         },{
 171           ...
 172     }]},{
 173       ...
 174     }]
 175
 176 SEE ALSO
 177 --------
 178 *sysdb*(1)
 179
 180 AUTHOR
 181 ------
 182 SysDB was written by Sebastian "tokkee" Harl <sh@tokkee.org>.
 183
 184 COPYRIGHT
 185 ---------
 186 Copyright (C) 2012-2014 Sebastian "tokkee" Harl <sh@tokkee.org>
 187
 188 This is free software under the terms of the BSD license, see the source for
 189 copying conditions. There is NO WARRANTY; not even for MERCHANTABILITY or
 190 FITNESS FOR A PARTICULAR PURPOSE.
 191
 192 // vim: set tw=78 sw=4 ts=4 noexpandtab spell spelllang=en_us :
 193