Spider REST Commands : Object Query Commands : Object Query via URI
Object Query via URI
An object query can submit all query parameters 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=text (required): A DQL query expression that defines which objects to select. Examples:
q=* // selects all objects
q=FirstName:Doug
q=NONE(InternalRecipients.Person.WHERE(LastName=Smith)).Department=Sales
•
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
•
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. Link paths can use parenthetical or dotted qualification. Link fields can use WHERE filtering and per-object maximum value limits in square brackets. Examples:
f=*
f=_local
f=_all
f=Size,Sender.Person.*
f=InternalRecipients[3].Person.DirectReports.WHERE(LastName=Smith)[5].FirstName
f=Name,Manager(Name,Manager(Name))
•
o=field [ASC|DESC] (optional): Orders the results by the specified field, which must be a scalar field belonging to the perspective table. Without this parameter, objects are returned in an internally-defined order. When an order field is specified, by default objects are sorted in ascending of the field’s value. Optionally, the field name can be followed by ASC to explicitly request ascending order or DESC to request descending order. Examples:
o=FirstName
o=LastName DESC
•
k=count (optional): Causes the first count objects in the query results to be skipped. This parameter can only be used in conjunction with the &o (order) parameter. If the &k parameter is omitted or 0, the first page of objects is returned. Examples:
k=100
k=0 // returns first page
•
g=token (optional): Returns a secondary page of objects starting with the first object greater than the given continuation token. The continuation token must be one return in a previous query. The &g parameter can only be used for queries that are not sorted (no &o parameter). The &g and &e parameters cannot both be used in the same query.
•
e=token (optional): Returns a secondary page of objects starting with the first object equal to the given continuation token. The continuation token must be one return in a previous query. The &e parameter can only be used for queries that are not sorted (no &o parameter). The &g and &e parameters cannot both be used in the same query.
Query results are paged using either of two methods depending on whether or not the results are sorted with the &o parameter:
•
Sorted queries: To retrieve a secondary page, the same query text should be submitted along with the &k parameter to specify the number of objects to skip. Doradus Spider will re-execute the query and skip the specified number of objects.
•
Unsorted queries: To retrieve a secondary page, the same query text should be submitted using either the &g or &e parameter to pass the continuation token from the previous page. This form of paging is more efficient since Doradus Spider does not re-execute the entire query but instead continues the query from the continuation object.
The following object query selects people whose LastName is Powell and returns their full name, their manager's name, and their direct reports' name. The query is limited to 2 results:
GET /Msgs/Person/_query?q=LastName=Powell&f=Name,Manager(Name),DirectReports(Name)&s=2
A typical result in XML is shown below:
<results>
<docs>
<doc>
<field name="Name">Karen Powell</field>
<field name="_ID">gfNqhYF7LgBAtKTdIx3BKw==</field>
<field name="DirectReports">
<doc>
<field name="Name">PartnerMarketing EMEA</field>
<field name="_ID">mKjYJmmLPoTVxJu2xdFmUg==</field>
</doc>
</field>
<field name="Manager">
<doc>
<field name="Name">David Cuss</field>
<field name="_ID">nLOCpa7aH/Y3zDrnMqG6Fw==</field>
</doc>
</field>
</doc>
<doc>
<field name="Name">Rob Powell</field>
<field name="_ID">sHUm0PEKu3gQDDNIHHWv1g==</field>
<field name="DirectReports"/>
<field name="Manager">
<doc>
<field name="Name">Bill Stomiany</field>
<field name="_ID">tkSQlrRqaeHsGvRU65g9HQ==</field>
</doc>
</field>
</doc>
</docs>
<continue>sHUm0PEKu3gQDDNIHHWv1g==</continue>
</results>
The same result in JSON:
{"results": {
"docs": [
{"doc": {
"Name": "Karen Powell",
"_ID": "gfNqhYF7LgBAtKTdIx3BKw==",
"DirectReports": [
{"doc": {
"Name": "PartnerMarketing EMEA",
"_ID": "mKjYJmmLPoTVxJu2xdFmUg=="
}}
],
"Manager": [
{"doc": {
"Name": "David Cuss",
"_ID": "nLOCpa7aH/Y3zDrnMqG6Fw=="
}}
]
}},
{"doc": {
"Name": "Rob Powell",
"_ID": "sHUm0PEKu3gQDDNIHHWv1g==",
"DirectReports" :[],
"Manager": [
{"doc": {
"Name": "Bill Stomiany",
"_ID": "tkSQlrRqaeHsGvRU65g9HQ=="
}}
]
}},
"continue": "sHUm0PEKu3gQDDNIHHWv1g=="
]
}}
As shown, requested link fields are returned even if when they are empty. Because the query results were limited via the &s parameter, a continue token is provided for retrieving the next page.