![[tokkee]](http://tokkee.org/images/avatar.png){kind=avatar}
diff --git a/doc/sysdbql.7.txt b/doc/sysdbql.7.txt
index 5c3c29179f3c249a0ddce29db1b9027d6a3bbbde..396b55b263d233ad49c9394d729f171cb20609b0 100644 (file)
--- a/doc/sysdbql.7.txt
+++ b/doc/sysdbql.7.txt
NAME
----
-sysdbql - the SysDB query language
+sysdbql - the SysDB query language (SysQL)
SYNOPSIS
--------
LIST hosts;
+ LIST services;
FETCH host 'some.host.name';
-----------
include::sysdb-description.txt[]
-The SysDB query language is a human-readable format for describing a request
-to retrieve data from a SysDB daemon. It is very remotely similar to the
-Standard Query Language (SQL) supported by relational database management
+The SysDB query language (SysQL) is a human-readable format for describing a
+request to retrieve data from a SysDB daemon. It is very remotely similar to
+the Standard Query Language (SQL) supported by relational database management
systems (RDBMS) but specialized for SysDB's use-case.
QUERY COMMANDS
Each command is terminated by a semicolon. The following commands are
available to retrieve information from SysDB:
-*LIST* hosts [*FILTER* '<filter_condition>']::
-Retrieve a sorted (by name) list of all hosts currently stored in SysDB. The
-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
+*LIST* hosts|services|metrics [*FILTER* '<filter_condition>']::
+Retrieve a sorted (by name) list of all hosts currently stored in SysDB along
+with their services or metrics if requested. The 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. When listing services or metrics, the
+respective objects will be included for each host as well. 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.
'<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, decimal number, or a date-time value
-(booleans and binary data are not supported by the frontend yet).
+(booleans and binary data are not supported by the frontend yet). See the
+section "DATA TYPES" for more details about how specify each data-type.
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
may be provided by multiple backends. The filter matches if the specified
value matches any of them.
+DATA TYPES
+----------
+The SysDB query language natively supports various data-types. Constants of
+all types may be used in any place where a value is expected.
+
+*String constants*::
+ A string constant is an arbitrary sequence of characters enclosed in
+ single quotes ('''). Single quotes may be included in a string constant by
+ specifying two adjacent single quotes.
+
+*Integer constants*::
+ An integer constant may be specified either as a sequence of digits or in
+ scientific notation written in the form "'a' E 'b'" (without spaces) where
+ 'a' and 'b' are integers. A leading plus or minus sign specifies the sign
+ of the constant.
+
+*Floating-point constants*::
+ A floating-point constant is a sequence of digits containing a decimal
+ point. Digits before or after the decimal point (but not both) are
+ optional. Floating-point constants may also be specified in scientific
+ notation by appending the letter "E" and a positive or negative integer
+ exponent. A leading plus or minus sign specifies the sign of the constant.
+
+*Date and time constants*::
+ A date constant may be specified as 'YYYY-MM-DD' and time constants may be
+ specified as 'HH:MM:SS.nnnnnnnnn' where seconds and nanoseconds are
+ optional.
+
+*Interval constants*::
+ An interval may be specified by one or multiple quantity and unit pairs.
+ The quantity may be any integer constant and the unit may be any of the
+ following: *Y* (years), *M* (months), *D* (days), *h* (hours), *m*
+ (minutes), *s* (seconds), *ms* (milliseconds), *us* (microseconds), or
+ *ns* (nanoseconds). Note that years and months are approximations.
+
RESPONSE FORMAT
---------------
The JavaScript Object Notation (JSON) format, as specified in RFC 4627, is
--------
manpage:sysdb[1], manpage:sysdb[7]
-The SysDB homepage: http://sysdb.io/
+The SysDB homepage: https://sysdb.io/
AUTHOR
------