REST Commands : Object Query Command
Object Query Command
An object query is a DQL query that selects and returns selected fields for objects in the perspective table. With Doradus Logging, all query parameters are passed in the URI of a GET request. The general form is:
GET /{application}/{table}/_query?{params}
where {application} is the application name, {table} is the perspective table to be queried, and {params} are URI parameters, separated by ampersands (&) and encoded as necessary. The following parameters are supported:
•
q=expression (required): A DQL query expression that defines which objects to select. The special expression “*” selects all objects. Examples:
q=* // selects all objects
q=EventID=512
q=Description:(Fail* Error)
•
s=size (optional): Limits the number of objects returned. If absent, the page size defaults to the search_default_page_size option in the doradus.yaml file. The page size can be set to 0 to disable paging, causing all results to be returned in a single page. Examples:
s=50
s=0 // return all objects -- be careful!
•
f=fields (optional): A comma-separated list of fields to return for each selected object. Without this parameter, all scalar fields of each object are returned. This is the same as using the special value * or _all. Examples:
f=*
f=Size,EventID
•
k=count (optional): Causes the first count objects in the query results to be skipped. If the &k parameter is omitted or set to 0, the first page of objects is returned. Examples:
k=100
k=0 // returns first page
•
o=Timestamp [ASC | DESC] (optional): Causes the object query results to be sorted by ascending or descending Timestamp order. By default, object query results are sorted in descending Timestamp order (newest objects first). Specifying o=Timestamp ASC causes oldest objects to be returned first.
•
g=timestamp (optional): Returns a secondary page of objects starting “at” the given timestamp. When a query returns a full page of objects, a continue element is included in the results to indicate what value can be used for this parameter. The objects returned in the secondary page are “greater than or equal to” the continue value. The &g and &e parameters cannot both be used in the same query.
•
e=timestamp (optional): Returns a secondary page of objects “after” the given timestamp. When a query returns a full page of objects, a continue element is included in the results to indicate what value can be used for this parameter. The objects returned in the secondary page are “greater than” the continue value. The &g and &e parameters cannot both be used in the same query.
An object query always returns an output entity even if there are no objects matching the query request. The outer element is results, which contains a single docs element. If the query returns no results, the docs element is empty. In XML:
<results>
<docs/>
</results>
In JSON:
{"results": {
"docs": []
}}
When objects are selected by an object query, each object is returned in a doc element with each requested field. For example:
GET /LogDepot/AppLogs/_query?q=*&f=EventID,Timestamp,UserSID
This query returns all objects in the AppLogs table and produces a result such as this:
<results>
<docs>
<doc>
<field name="EventID">672</field>
<field name="Timestamp">2006-01-13 00:00:00.000</field>
<field name="UserSID">S-1-5-18</field>
</doc>
<doc>
<field name="EventID">538</field>
<field name="Timestamp">2006-01-13 00:00:00.000</field>
<field name="UserSID">S-1-5-21-1874068349-1688302950-636360099-52692</field>
</doc>
...
</docs>
</results>
In JSON:
{"results": {
"docs": [
{"doc": {
"EventID": "672",
"Timestamp": "2006-01-13 00:00:00.000",
"UserSID": "S-1-5-18"
}},
{"doc": {
"EventID": "538",
"Timestamp": "2006-01-13 00:00:00.000",
"UserSID": "S-1-5-21-1874068349-1688302950-636360099-52692"
}},
...
]
}}
Each requested field is returned even if it has no value.
If a query returns a full page of results, a “continue” value is returned, which can be used with the “continue at” or “continue after” parameters to get a secondary page. Example:
{"results": {
"docs": [
...
{"doc": {
"EventID": "673",
"Timestamp": "2006-01-13 00:00:03.000",
"UserSID": "S-1-5-18"
}}
],
"continue": "2006-01-13 00:00:03.000"
}}