Query language: Changed 'LOOKUP .. WHERE' to 'LOOKUP .. MATCHING'.

[sysdb.git] / doc / sysdbql.7.txt

diff --git a/doc/sysdbql.7.txt b/doc/sysdbql.7.txt
index 335918ab59d3473f93f685379b600fe0d51843e6..447950d37ec00ad11c8dbd403212895e2be346a1 100644 (file)
--- a/doc/sysdbql.7.txt
+++ b/doc/sysdbql.7.txt
@@ -1,7 +1,5 @@
 sysdbql(7)
 ==========
-Sebastian "tokkee" Harl <sh@tokkee.org>
-version {package_version}, {build_date}
 :doctype: manpage
 
 NAME
@@ -13,20 +11,11 @@ SYNOPSIS
 
   LIST;
 
-  QUERY hosts WHERE attribute.architecture = 'amd64';
+  LOOKUP hosts MATCHING attribute.architecture = 'amd64';
 
 DESCRIPTION
 -----------
-SysDB stores system and inventory information about hardware and software
-systems. This information is stored in a graph-like hierarchy of generic
-objects. The central object type is a host, which generally represents a
-physical or virtual machine or any other type of physical resource. Hosts, in
-turn, may reference a list of services which represent any kind of logical
-resource like a software system. Both, hosts and services, may reference a
-list of attributes which represent further information about the respective
-host or service object. For example, attributes may specify static information
-like a host's architecture or the software version or snapshots of performance
-data like the current memory utilization or much more.
+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
@@ -50,20 +39,20 @@ 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.
 
-*LOOKUP* hosts *WHERE* '<search_condition>'::
+*LOOKUP* hosts *MATCHING* '<search_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.
-See the section "WHERE clause" for more details about how to specify the
+See the section "MATCHING 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:
+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
@@ -78,19 +67,28 @@ are supported by SysDB:
 
 The following fields may be queried:
 
-*host.name*::
+*host*::
        The full name of the host.
 
-*service.name*::
+*service*::
        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.
 
+'<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).
+
+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
+at this time.
+
 The following operators may be used to match field values:
 
 *=*::
@@ -108,6 +106,16 @@ The following operators may be used to match field values:
        Evalues to true if the field value does not match the specified regular
        expression.
 
+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.
+
 RESPONSE FORMAT
 ---------------
 The JavaScript Object Notation (JSON) format, as specified in RFC 4627, is
@@ -150,7 +158,7 @@ replies look like. The replies are pretty-printed to more easily follow them.
           ...
         }]}
 
-  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",
@@ -175,7 +183,9 @@ replies look like. The replies are pretty-printed to more easily follow them.
 
 SEE ALSO
 --------
-*sysdb*(1)
+manpage:sysdb[1], manpage:sysdb[7]
+
+The SysDB homepage: http://sysdb.io/
 
 AUTHOR
 ------