1 sysdbql(7)
2 ==========
3 :doctype: manpage
5 NAME
6 ----
7 sysdbql - the SysDB query language
9 SYNOPSIS
10 --------
12 LIST;
14 QUERY hosts WHERE attribute.architecture = 'amd64';
16 DESCRIPTION
17 -----------
18 include::sysdb-description.txt[]
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.
25 QUERY COMMANDS
26 --------------
27 Each command is terminated by a semicolon. The following commands are
28 available to retrieve information from SysDB:
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.
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.
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.
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:
57 '<field>' '<operator>' '<value>'::
58 Match a named field against the specified value. See below for what fields
59 and operators are supported.
61 *NOT* '<subexpression>'::
62 Invert the boolean result of the specified subexpression.
64 '<subexpression>' *AND* '<subexpression>'::
65 '<subexpression>' *OR* '<subexpression>'::
66 Combine multiple subexpressions using logical AND or logical OR.
68 The following fields may be queried:
70 *host.name*::
71 The full name of the host.
73 *service.name*::
74 The full service name as referenced by the host.
76 *attribute.name*::
77 The full name of a host attribute.
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.
83 The following operators may be used to match field values:
85 *=*::
86 Evaluates to true if the field value exactly matches the specified value.
88 *!=*::
89 Evaluates to true if the field value does not match the exact specified
90 value.
92 *=~*::
93 Evaluates to true if the field value matches the specified regular
94 expression. SysDB uses POSIX extended regular expressions.
96 *!~*::
97 Evalues to true if the field value does not match the specified regular
98 expression.
100 RESPONSE FORMAT
101 ---------------
102 The JavaScript Object Notation (JSON) format, as specified in RFC 4627, is
103 used in all replies from the server. http://www.ietf.org/rfc/rfc4627.txt
105 EXAMPLES
106 --------
107 The following examples illustrate the use of the commands and what their
108 replies look like. The replies are pretty-printed to more easily follow them.
110 LIST;
111 {"hosts":[{
112 "name": "host1.example.com",
113 "last_update": "2001-02-03 04:05:06 +0700",
114 "update_interval": "5m4s"
115 },{
116 "name": "host2.example.com",
117 "last_update": "2001-02-03 04:05:06 +0700",
118 "update_interval": "5m4s"
119 }]}
121 FETCH 'host1.example.com';
122 {
123 "name": "host1.example.com",
124 "last_update": "2001-02-03 04:05:06 +0700",
125 "update_interval": "5m4s",
126 "attributes": [{
127 "name": "architecture",
128 "value": "amd64",
129 "last_update": "2001-02-03 04:05:06 +0700",
130 "update_interval": "5m4s"
131 },{
132 ...
133 }],
134 "services": [{
135 "name": "some service",
136 "last_update": "2001-02-03 04:05:06 +0700",
137 "update_interval": "5m4s"
138 },{
139 ...
140 }]}
142 LOOKUP hosts WHERE attribute.architecture = 'amd64';
143 [{
144 "name": "host1.example.com",
145 "last_update": "2001-02-03 04:05:06 +0700",
146 "update_interval": "5m4s",
147 "attributes": [{
148 "name": "architecture",
149 "value": "amd64",
150 "last_update": "2001-02-03 04:05:06 +0700",
151 "update_interval": "5m4s"
152 },{
153 ...
154 }],
155 "services": [{
156 "name": "some service",
157 "last_update": "2001-02-03 04:05:06 +0700",
158 "update_interval": "5m4s"
159 },{
160 ...
161 }]},{
162 ...
163 }]
165 SEE ALSO
166 --------
167 manpage:sysdb[1]
169 AUTHOR
170 ------
171 SysDB was written by Sebastian "tokkee" Harl <sh@tokkee.org>.
173 COPYRIGHT
174 ---------
175 Copyright (C) 2012-2014 Sebastian "tokkee" Harl <sh@tokkee.org>
177 This is free software under the terms of the BSD license, see the source for
178 copying conditions. There is NO WARRANTY; not even for MERCHANTABILITY or
179 FITNESS FOR A PARTICULAR PURPOSE.
181 // vim: set tw=78 sw=4 ts=4 noexpandtab spell spelllang=en_us :