Object Query Commands (Spider)

[Table of Contents](https://github.com/dell-oss/Doradus/wiki/Spider Databases: Table-of-Contents) | [Previous](https://github.com/dell-oss/Doradus/wiki/Get Object-Command (Spider)) | Next
Spider REST Commands: Object Query Commands

---

Doradus Spider supports two commands for submitting object queries. Details of object query parameters and the output formats returned by object queries are described in the section Spider Object Queries.

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 value limits in square brackets. Examples:

    f=*
    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. Without this parameter, 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>
	<totalobjects>2</totalobjects>
	<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>
</results>

The same result in JSON:

{"results": {
	"totalobjects": "2",
	"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=="
				}}
			]
		}}
	]
}}

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.

Object Query via Entity

An object query can be performed by passing all parameters in an input entity. Because some clients do not support HTTP GET-with-entity, the PUT method can be used instead, even though no modifications are made. Both these examples are equivalent:

GET /{application}/{table}/_query
PUT /{application}/{table}/_query

The entity passed in the command must be a JSON or XML document whose root element is search. The query parameters are given as child elements. URI query parameters map to the following element names:

URI Parameter	Element name
e	continue-at
f	fields
g	continue-after
k	skip
o	order
q	query
s	size

Here is an example search document in XML:

<search>
	<query>LastName=Powell</query>
	<fields>Name,Manager(Name),DirectReports(Name)</fields>
	<size>2</size>
</search>

The same example in JSON:

{"search": {
	"query": "LastName=Powell",
	"fields": "Name,Manager(Name),DirectReports(Name)",
	"size": "2"
}}