![[tokkee]](http://tokkee.org/images/avatar.png){kind=avatar}
diff --git a/doc/sysdbql.7.txt b/doc/sysdbql.7.txt
index 5f967c63f492ff19aa179857528c04597d1047dc..f1993cb339d146883d2f758b106e0963d3f7bc39 100644 (file)
--- a/doc/sysdbql.7.txt
+++ b/doc/sysdbql.7.txt
LIST;
- QUERY hosts WHERE attribute.architecture = 'amd64';
+ LOOKUP hosts MATCHING attribute.architecture = 'amd64';
DESCRIPTION
-----------
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>' [*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.
-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 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
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, 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
+at this time.
+
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.
+
+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 common fields of stored objects may be queried:
+
+*:last_update*::
+ The timestamp of the last update of the object.
+
+*: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
...
}]}
- 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",
SEE ALSO
--------
-manpage:sysdb[1]
+manpage:sysdb[1], manpage:sysdb[7]
+
+The SysDB homepage: http://sysdb.io/
AUTHOR
------