X-Git-Url: https://git.tokkee.org/?a=blobdiff_plain;f=doc%2Fsysdbql.7.txt;h=88ce0974bf93eb6aca70d25ecd2071ce3c9d1493;hb=8a5c48548731dc07c3370432dc8f951b8e4bef9f;hp=f1993cb339d146883d2f758b106e0963d3f7bc39;hpb=5703edf70261173a482692ad5dcaa37b27eab64e;p=sysdb.git diff --git a/doc/sysdbql.7.txt b/doc/sysdbql.7.txt index f1993cb..88ce097 100644 --- a/doc/sysdbql.7.txt +++ b/doc/sysdbql.7.txt @@ -4,22 +4,26 @@ sysdbql(7) NAME ---- -sysdbql - the SysDB query language +sysdbql - the SysDB query language (SysQL) SYNOPSIS -------- - LIST; + LIST hosts; + LIST services; - LOOKUP hosts MATCHING attribute.architecture = 'amd64'; + FETCH host 'some.host.name'; + + LOOKUP hosts MATCHING attribute[architecture] = 'amd64' + FILTER .age < 5 * .interval; DESCRIPTION ----------- 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 @@ -27,25 +31,43 @@ QUERY COMMANDS Each command is terminated by a semicolon. The following commands are available to retrieve information from SysDB: -*LIST*:: -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* '':: +*LIST* hosts|services|metrics [*FILTER* '']:: +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. + +*FETCH* host '' [*FILTER* '']:: 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 *MATCHING* '' [*FILTER* '']:: 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. -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. +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. + +*TIMESERIES* ''.'' [START ''] [END '']:: +Retrieve a time-series for the specified host's metric. The data is retrieved +from a backend data-store based on information provided by the respective +query plugin. The return value includes the actual start and end time of the +time-series and one or multiple sequences of time-stamp / value pairs. If the +metric does not exist or if the backend data-store is not supported, an error +is returned. MATCHING clause ~~~~~~~~~~~~~~~ @@ -77,14 +99,17 @@ The following fields may be queried: *attribute*:: The full name of a host attribute. -*attribute.*'':: +*attribute[*''*]*:: 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. + name 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. '' 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 @@ -113,9 +138,9 @@ The following operators may be used, in addition, to match attribute values: 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 check for existence using the *IS NULL* -and *IS NOT NULL* expressions. An attribute is considered to be *NULL* if it -is not set for a host. +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 ~~~~~~~~~~~~~ @@ -126,21 +151,22 @@ 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 common fields of stored objects may be queried: +The following fields (core properties) of stored objects may be queried: -*:last_update*:: - The timestamp of the last update of the object. +*.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*:: +*.age*:: The amount of time since the last update of the object. -*:interval*:: +*.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*:: +*.backend*:: The name of the backend (plugin) providing the data. The type of the *last_update*, *age*, and *interval* fields is date-time and @@ -150,6 +176,41 @@ 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. +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 @@ -160,8 +221,8 @@ EXAMPLES 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; - {"hosts":[{ + LIST hosts; + [{ "name": "host1.example.com", "last_update": "2001-02-03 04:05:06 +0700", "update_interval": "5m4s" @@ -169,9 +230,9 @@ replies look like. The replies are pretty-printed to more easily follow them. "name": "host2.example.com", "last_update": "2001-02-03 04:05:06 +0700", "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", @@ -192,7 +253,7 @@ replies look like. The replies are pretty-printed to more easily follow them. ... }]} - LOOKUP hosts MATCHING attribute.architecture = 'amd64'; + LOOKUP hosts MATCHING attribute[architecture] = 'amd64'; [{ "name": "host1.example.com", "last_update": "2001-02-03 04:05:06 +0700", @@ -219,7 +280,7 @@ SEE ALSO -------- manpage:sysdb[1], manpage:sysdb[7] -The SysDB homepage: http://sysdb.io/ +The SysDB homepage: https://sysdb.io/ AUTHOR ------