![[tokkee]](http://tokkee.org/images/avatar.png){kind=avatar}
diff --git a/doc/sysdbql.7.txt b/doc/sysdbql.7.txt
index 011da144fc734ab9c005156506b59d523e35fbb3..aa3add33085e74d8b03b3968fd7afb83bdcf7270 100644 (file)
--- a/doc/sysdbql.7.txt
+++ b/doc/sysdbql.7.txt
SYNOPSIS
--------
SYNOPSIS
--------
- LIST;
+ LIST hosts;
- QUERY hosts WHERE attribute.architecture = 'amd64';
+ FETCH host 'some.host.name';
+
+ LOOKUP hosts MATCHING attribute.architecture = 'amd64'
+ FILTER :age < 5 * :interval;
DESCRIPTION
-----------
DESCRIPTION
-----------
Each command is terminated by a semicolon. The following commands are
available to retrieve information from SysDB:
Each command is terminated by a semicolon. The following commands are
available to retrieve information from SysDB:
-*LIST*::
+*LIST* hosts [*FILTER* '<filter_condition>']::
Retrieve a sorted (by name) list of all hosts currently stored in SysDB. The
Retrieve a sorted (by name) list of all hosts currently stored in SysDB. The
-return value is a list of hosts where each host description includes its name,
-the timestamp of the last update of the object in SysDB and an approximation
-of the interval with which the host was updated.
-
-*FETCH* '<hostname>'::
+return value is a list of hosts where each host specification includes its
+name, the timestamp of the last update of the object known to SysDB and an
+approximation of the interval with which the host was updated. If a filter
+condition is specified, only objects matching that filter will be included in
+the reply. See the section "FILTER clause" for more details about how to
+specify the search and filter conditions.
+
+*FETCH* host '<hostname>' [*FILTER* '<filter_condition>']::
Retrieve detailed information about the specified host object. The return
value includes the hostname, a list of services referenced by the host, and a
list of attributes for the host and each service. If the host does not exist,
Retrieve detailed information about the specified host object. The return
value includes the hostname, a list of services referenced by the host, and a
list of attributes for the host and each service. If the host does not exist,
-an error is returned.
+an error is returned. If a filter condition is specified, only objects
+matching that filter will be included in the reply. See the section "FILTER
+clause" for more details about how to specify the search and filter
+conditions.
-*LOOKUP* hosts *WHERE* '<search_condition>'::
+*LOOKUP* hosts *MATCHING* '<search_condition>' [*FILTER* '<filter_condition>']::
Retrieve detailed information about all host objects matching the specified
search condition. The return value is a list of detailed information for each
matching host providing the same details as returned by the *FETCH* command.
Retrieve detailed information about all host objects matching the specified
search condition. The return value is a list of detailed information for each
matching host providing the same details as returned by the *FETCH* command.
-See the section "WHERE clause" for more details about how to specify the
-search condition.
-
-WHERE clause
-~~~~~~~~~~~~
-The *WHERE* clause in a query specifies a boolean expression which is used to
-match host objects based on their names, their attributes, or services
-referenced by the host. Each *WHERE* clause may be made up of one or multiple
-subexpressions each matching on one criteria. The following subexpressions
-are supported by SysDB:
+If no host matches the search criteria, it's not considered an error. Instead,
+an empty list is returned. If a filter condition is specified, only objects
+matching that filter will be included in the reply. See the sections "MATCHING
+clause" and "FILTER clause" for more details about how to specify the search
+and filter conditions.
+
+MATCHING clause
+~~~~~~~~~~~~~~~
+The *MATCHING* clause in a query specifies a boolean expression which is used
+to match host objects based on their names, their attributes, or services
+referenced by the host. Each *MATCHING* clause may be made up of one or
+multiple subexpressions each matching on one criteria. The following
+subexpressions are supported by SysDB:
'<field>' '<operator>' '<value>'::
Match a named field against the specified value. See below for what fields
'<field>' '<operator>' '<value>'::
Match a named field against the specified value. See below for what fields
The following fields may be queried:
The following fields may be queried:
-*host.name*::
+*host*::
The full name of the host.
The full name of the host.
-*service.name*::
+*service*::
The full service name as referenced by the host.
The full service name as referenced by the host.
-*attribute.name*::
+*attribute*::
The full name of a host attribute.
*attribute.*'<name>'::
The value of the named host attribute. If an attribute of the specified
does not exist, each comparison is treated as if the value does not match.
The full name of a host attribute.
*attribute.*'<name>'::
The value of the named host attribute. If an attribute of the specified
does not exist, each comparison is treated as if the value does not match.
+ See the documentation for the *IS NULL* and *IS NOT NULL* operators for
+ ways to check if an attribute exists.
'<value>' may either be a string (when matching by object names) or match the
type of the attribute's value (when matching attribute values). Attribute
'<value>' may either be a string (when matching by object names) or match the
type of the attribute's value (when matching attribute values). Attribute
-values may either be a string, integer, or decimal number (booleans and binary
-data are not supported by the frontend yet).
+values may either be a string, integer, decimal number, or a date-time value
+(booleans and binary data are not supported by the frontend yet).
When comparing an attribute's value using a regular expression matcher, the
value will be cast to a string before doing so. No other casts are supported
When comparing an attribute's value using a regular expression matcher, the
value will be cast to a string before doing so. No other casts are supported
Evaluates to true if the attribute value is less than, less than or equal
to, greater than or equal to or greater than the specified value.
Evaluates to true if the attribute value is less than, less than or equal
to, greater than or equal to or greater than the specified value.
+In addition, a named attribute may be checked for existence using the *IS
+NULL* and *IS NOT NULL* operators. An attribute is considered to be *NULL* if
+it is not set for a host.
+
+FILTER clause
+~~~~~~~~~~~~~
+The *FILTER* clause in a query specifies a boolean expression which is used to
+filter objects included in the query's response. The filter is applied to
+hosts, services, and attributes alike and, thus, will usually be based on the
+core properties of the stored objects. The basic syntax for filter clauses is
+the same as for matching clauses (see the description about subexpressions
+above).
+
+The following fields (core properties) of stored objects may be queried:
+
+*:last_update*::
+ The timestamp of the last update of the object. This value is based on
+ information provided by the queried backend if possible.
+
+*:age*::
+ The amount of time since the last update of the object.
+
+*:interval*::
+ The interval with which the object gets updated. This value is determined
+ automatically based on a moving average determined from the update
+ timestamps of an object. It depends on the update timestamps as provided
+ by the backend (if available) and SysDB's query interval.
+
+*:backend*::
+ The name of the backend (plugin) providing the data.
+
+The type of the *last_update*, *age*, and *interval* fields is date-time and
+the type of the *backend* field is string. All conditional operators may be
+used to compare the date-time fields (but not regular expression or *IS NULL*
+operators). The backend field may only be matched by (in)equality. Each object
+may be provided by multiple backends. The filter matches if the specified
+value matches any of them.
+
RESPONSE FORMAT
---------------
The JavaScript Object Notation (JSON) format, as specified in RFC 4627, is
RESPONSE FORMAT
---------------
The JavaScript Object Notation (JSON) format, as specified in RFC 4627, is
The following examples illustrate the use of the commands and what their
replies look like. The replies are pretty-printed to more easily follow them.
The following examples illustrate the use of the commands and what their
replies look like. The replies are pretty-printed to more easily follow them.
- LIST;
+ LIST hosts;
{"hosts":[{
"name": "host1.example.com",
"last_update": "2001-02-03 04:05:06 +0700",
{"hosts":[{
"name": "host1.example.com",
"last_update": "2001-02-03 04:05:06 +0700",
"update_interval": "5m4s"
}]}
"update_interval": "5m4s"
}]}
- FETCH 'host1.example.com';
+ FETCH host 'host1.example.com';
{
"name": "host1.example.com",
"last_update": "2001-02-03 04:05:06 +0700",
{
"name": "host1.example.com",
"last_update": "2001-02-03 04:05:06 +0700",
...
}]}
...
}]}
- LOOKUP hosts WHERE attribute.architecture = 'amd64';
+ LOOKUP hosts MATCHING attribute.architecture = 'amd64';
[{
"name": "host1.example.com",
"last_update": "2001-02-03 04:05:06 +0700",
[{
"name": "host1.example.com",
"last_update": "2001-02-03 04:05:06 +0700",
SEE ALSO
--------
SEE ALSO
--------
-manpage:sysdb[1]
+manpage:sysdb[1], manpage:sysdb[7]
+
+The SysDB homepage: http://sysdb.io/
AUTHOR
------
AUTHOR
------