sysdbql(7): Updated documentation to keep up with the latest changes.

diff --git a/doc/sysdbql.7.txt b/doc/sysdbql.7.txt
index f1993cb339d146883d2f758b106e0963d3f7bc39..aa3add33085e74d8b03b3968fd7afb83bdcf7270 100644 (file)
--- a/doc/sysdbql.7.txt
+++ b/doc/sysdbql.7.txt
@@ -9,9 +9,12 @@ sysdbql - the SysDB query language
 SYNOPSIS
 --------
 
 SYNOPSIS
 --------
 

-  LIST;
+  LIST hosts;

 
 

-  LOOKUP hosts MATCHING attribute.architecture = 'amd64';
+  FETCH host 'some.host.name';
+
+  LOOKUP hosts MATCHING attribute.architecture = 'amd64'
+               FILTER :age < 5 * :interval;

 
 DESCRIPTION
 -----------
 
 DESCRIPTION
 -----------


@@ -27,25 +30,33 @@ QUERY COMMANDS
 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 *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.
 
 *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.

-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.

 
 MATCHING clause
 ~~~~~~~~~~~~~~~
 
 MATCHING clause
 ~~~~~~~~~~~~~~~


@@ -80,6 +91,8 @@ The following fields may be queried:
 *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.
 *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


@@ -113,9 +126,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.
 
        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
 ~~~~~~~~~~~~~
 
 FILTER clause
 ~~~~~~~~~~~~~


@@ -126,10 +139,11 @@ 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 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*::
 
 *:last_update*::

-       The timestamp of the last update of the object.
+       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.
 
 *:age*::
        The amount of time since the last update of the object.


@@ -160,7 +174,7 @@ 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.
 
 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",


@@ -171,7 +185,7 @@ replies look like. The replies are pretty-printed to more easily follow them.
       "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",