Query Capabilities

You can use the query capabilities to find records that match your search criteria.

The query can be as a set of query filters that are specified by using the oslc.where parameter or as a full text search term specified by using the oslc.searchTerms parameter.

You can specify what fields are returned in the query results by using the oslc.select parameter. Each record type in a database has a query capability that is defined in the service description document. You can use these query capabilities to run queries for records of the corresponding type.

Parameters

oslc.orderBy
oslc.searchTerms
oslc.select
You can use the oslc.select query parameter to specify which immediate and nested properties to include in a query result set. It is like the SELECT clause of an SQL statement. The oslc.select and oslc.properties parameters have the same syntax (see Requesting Specific Properties). If the oslc.select parameter is omitted from a query URL, the resulting output will include references to the records from the query result set but will not include specific field values.
You can use oslc.select to request standard OSLC properties and Rational® ClearQuest® specific properties for retrieved records. The example below returns a collection of result records that contain title and Severity property values.
```
oslc.select=dcterms:title,cq:Severity&oslc.prefix=cq=<http://www.ibm.com/xmlns/prod/rational/clearquest/1.0/>
```
You can also use oslc.select to retrieve nested properties for referenced records. For instance,
```
oslc.select=dcterms:title,cq:customer{cq:Company}&oslc.prefix=cq=<http://www.ibm.com/xmlns/prod/rational/clearquest/1.0/>
```
requests the title for each retrieved record and the Company property of referenced customer records.
The * character is a wildcard that expands to match all properties. To request all properties for each retrieved record and the Company property for each referenced customer record, you can make this request
```
oslc.select=*,cq:customer{cq:Company}&oslc.prefix=cq=<http://www.ibm.com/xmlns/prod/rational/clearquest/1.0/>
```
.
For more information and examples, see the oslc.select section of OSLC Core 2.0 specification.
oslc.where
The oslc.where parameter is used to filter the records that are retrieved by a query operation. If an oslc.where parameter is not passed, then the query will retrieve all records. The oslc.where is similar to the WHERE clause of an SQL statement.
The following example uses an oslc.where parameter to retrieve only those records with a State of "Opened".
```
oslc.where=cq:State="Opened"&oslc.prefix=cq=<http://www.ibm.com/xmlns/prod/rational/clearquest/1.0/>
```
In order to query for null or empty filter values, the "" or oslc_cm:NULL syntax can be used with oslc.where. The wildcard (*) is also available to match all non null values.
The following examples use an oslc.where parameter to retrieve only those records that do not have a project set.
```
oslc.where=cq:project=""
```
or
```
oslc.where=cq:project="oslc_cm:NULL"
```
The following examples use an oslc.where parameter to retrieve only those records that have a project set.
```
oslc.where=cq:project!=""
```
or
```
oslc.where=cq:project!="oslc_cm:NULL"
```
or
```
oslc.where=cq:project="*"
```
The "in" operator can be used to test for equality to any of the values in a list. The query below retrieves records with a State of "Opened" or "Assigned".
```
oslc.where=cq:State in ["Opened","Assigned"]&oslc.prefix=cq=<http://www.ibm.com/xmlns/prod/rational/clearquest/1.0/>
```
It is also possible to specify nested properties in the oslc.where parameter. For example, to retrieve all defect records that contain references to customers from the company named "FooBar Company":
```
oslc.where=cq:customer{cq:Company="FooBar Company"}&oslc.prefix=cq=<http://www.ibm.com/xmlns/prod/rational/clearquest/1.0/>
```
The oslc.where can also refer to referenced resources by using a resource identifier URI. For example, construct an oslc.where like the one below to retrieve defect records that contain references to a specific customer record. URI references are represented in oslc.where by surrounding the URI with < and > symbols.
```
oslc.where=cq:customer=<http://quagmire.rtp.raleigh.ibm.com/cqweb/oslc/repo/7.0.0/db/SAMPL/record/16777937-33554719>
```
Conditions for the oslc.where can be combined by using the Boolean conjunction operator " and ". The example below uses the "and" operator to combine conditions from previous examples into a single oslc.where parameter. The result set for this query includes all records in "Opened" or "Assigned" state that contains references to customers from the company named "FooBar Company".
```
oslc.where=cq:customer{cq:Company="FooBar Company"} and cq:State in ["Opened","Assigned"]&oslc.prefix=cq=<http://www.ibm.com/xmlns/prod/rational/clearquest/1.0/>
```
For additional information and examples, see the oslc.where section of OSLC Core 2.0 specification.

Output

This section lists the output of an OSLC query constructed by using a combination of previously discussed parameters.

oslc.where=cq:customer{cq:Company="FooBar Company"} and cq:State in ["Opened","Assigned"]&oslc.select=dcterms:title,cq:customer{cq:Company,cq:Phone}&oslc.prefix=cq=<http://www.ibm.com/xmlns/prod/rational/clearquest/1.0/>

The query retrieves all records in state "Opened" or "Assigned" that have a reference to a customer from "FooBar Company". The returned records include the title field of the base record and the Company and Phone properties for all customer records that are referenced by retrieved base records. The output also includes an oslc:totalCount property making it easy to determine how many base records were returned by the query.

Request:

GET /cqweb/oslc/repo/7.0.0/db/SAMPL/simpleQuery/16777224?oslc.where%3Dcq%3Acustomer%7Bcq%3ACompany%3D%22FooBar%20Company%22%7D%20and%20cq%3AState%20in%20%5B%22Opened%22%2C%22Assigned%22%5D&oslc.select=dcterms%3Atitle%2Ccq%3Acustomer%7Bcq%3ACompany%2Ccq%3APhone%7D&oslc.prefix=cq=%3Chttp%3A%2F%2Fwww.ibm.com%2Fxmlns%2Fprod%2Frational%2Fclearquest%2F1.0%2F%3E HTTP/1.1
Host: quagmire.rtp.raleigh.ibm.com
OSLC-Core-Version: 2.0
Accept: application/rdf+xml

Response:

Sample output for the query that is returned as RDF/XML.

HTTP/1.1 200 OK
OSLC-Core-Version: 2.0
Transfer-Encoding: chunked
Content-Type: application/rdf+xml; charset=UTF-8

<?xml version="1.0" encoding="UTF-8"?>
<rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" xmlns:rdfs="http://www.w3.org/2000/01/rdf-schema#" xmlns:oslc="http://open-services.net/ns/core#" xmlns:cq="http://www.ibm.com/xmlns/prod/rational/clearquest/1.0/" xmlns:dcterms="http://purl.org/dc/terms/" xmlns:oslc_cm="http://open-services.net/ns/cm#">
<oslc:ResponseInfo rdf:about="http://quagmire/cqweb/oslc/repo/7.0.0/db/SAMPL/simpleQuery/16777224?oslc.where=cq:customer{cq:Company=%22FooBar%20Company%22}%20and%20cq:State%20in%20[%22Opened%22,%22Assigned%22]&amp;oslc.select=dcterms:title,cq:customer{cq:Company,cq:Phone}&amp;oslc.prefix=cq=%3Chttp:/www.ibm.com/xmlns/prod/rational/clearquest/1.0/%3E">
<dcterms:title>cq:customer{cq:Company="FooBar Company"} and cq:State in ["Opened","Assigned"]</dcterms:title>
<oslc:totalCount>3</oslc:totalCount>
</oslc:ResponseInfo>
<rdf:Description rdf:about="http://quagmire/cqweb/oslc/repo/7.0.0/db/SAMPL/simpleQuery/16777224">
<rdfs:member>
<oslc_cm:ChangeRequest rdf:about="http://quagmire/cqweb/oslc/repo/7.0.0/db/SAMPL/record/16777224-33565354">
<dcterms:type>Defect</dcterms:type>
<rdf:type rdf:resource="http://open-services.net/ns/cm#ChangeRequest"/>
<rdf:type rdf:resource="http://www.ibm.com/xmlns/prod/rational/clearquest/1.0/Defect"/>
<oslc:instanceShape rdf:resource="http://quagmire/cqweb/oslc/repo/7.0.0/db/SAMPL/shape/16777224"/>
<dcterms:title>TEST JUnit Test Record Submit TEST</dcterms:title>
<dcterms:identifier>33565354</dcterms:identifier>
<oslc:shortTitle>SAMPL00010922</oslc:shortTitle>
<cq:customer>
<oslc_cm:ChangeRequest rdf:about="http://quagmire/cqweb/oslc/repo/7.0.0/db/SAMPL/record/16777937-33554725">
<dcterms:type>Customer</dcterms:type>
<oslc:shortTitle>Anne Johnson</oslc:shortTitle>
<cq:Phone>(987) 123 - 0123</cq:Phone>
<cq:Company>FooBar Company</cq:Company>
</oslc_cm:ChangeRequest>
</cq:customer>
</oslc_cm:ChangeRequest>
</rdfs:member>
<rdfs:member>
<oslc_cm:ChangeRequest rdf:about="http://quagmire/cqweb/oslc/repo/7.0.0/db/SAMPL/record/16777224-33572254">
<dcterms:type>Defect</dcterms:type>
<rdf:type rdf:resource="http://open-services.net/ns/cm#ChangeRequest"/>
<rdf:type rdf:resource="http://www.ibm.com/xmlns/prod/rational/clearquest/1.0/Defect"/>
<oslc:instanceShape rdf:resource="http://quagmire/cqweb/oslc/repo/7.0.0/db/SAMPL/shape/16777224"/>
<dcterms:title>Demo to Support override price does not work Hope it was good...</dcterms:title>
<dcterms:identifier>33572254</dcterms:identifier>
<oslc:shortTitle>SAMPL00017822</oslc:shortTitle>
<cq:customer>
<oslc_cm:ChangeRequest rdf:about="http://quagmire/cqweb/oslc/repo/7.0.0/db/SAMPL/record/16777937-33554725">
<dcterms:type>Customer</dcterms:type>
<oslc:shortTitle>Anne Johnson</oslc:shortTitle>
<cq:Phone>(987) 123 - 0123</cq:Phone>
<cq:Company>FooBar Company</cq:Company>
</oslc_cm:ChangeRequest>
</cq:customer>
<cq:customer>
<oslc_cm:ChangeRequest rdf:about="http://quagmire/cqweb/oslc/repo/7.0.0/db/SAMPL/record/16777937-33554794">
<dcterms:type>Customer</dcterms:type>
<oslc:shortTitle>Bart Simpson</oslc:shortTitle>
<cq:Phone/>
<cq:Company/>
</oslc_cm:ChangeRequest>
</cq:customer>
</oslc_cm:ChangeRequest>
</rdfs:member>
<rdfs:member>
<oslc_cm:ChangeRequest rdf:about="http://quagmire/cqweb/oslc/repo/7.0.0/db/SAMPL/record/16777224-33579830">
<dcterms:type>Defect</dcterms:type>
<rdf:type rdf:resource="http://open-services.net/ns/cm#ChangeRequest"/>
<rdf:type rdf:resource="http://www.ibm.com/xmlns/prod/rational/clearquest/1.0/Defect"/>
<oslc:instanceShape rdf:resource="http://quagmire/cqweb/oslc/repo/7.0.0/db/SAMPL/shape/16777224"/>
<dcterms:title>Demo to Support override price does not work Hope it was good...</dcterms:title>
<dcterms:identifier>33579830</dcterms:identifier>
<oslc:shortTitle>SAMPL00025398</oslc:shortTitle>
<cq:customer>
<oslc_cm:ChangeRequest rdf:about="http://quagmire/cqweb/oslc/repo/7.0.0/db/SAMPL/record/16777937-33554789">
<dcterms:type>Customer</dcterms:type>
<oslc:shortTitle>Alfred Hitchcock</oslc:shortTitle>
<cq:Phone/>
<cq:Company/>
</oslc_cm:ChangeRequest>
</cq:customer>
<cq:customer>
<oslc_cm:ChangeRequest rdf:about="http://quagmire/cqweb/oslc/repo/7.0.0/db/SAMPL/record/16777937-33554794">
<dcterms:type>Customer</dcterms:type>
<oslc:shortTitle>Bart Simpson</oslc:shortTitle>
<cq:Phone/>
<cq:Company/>
</oslc_cm:ChangeRequest>
</cq:customer>
<cq:customer>
<oslc_cm:ChangeRequest rdf:about="http://quagmire/cqweb/oslc/repo/7.0.0/db/SAMPL/record/16777937-33697154">
<dcterms:type>Customer</dcterms:type>
<oslc:shortTitle>Jonathan Foo</oslc:shortTitle>
<cq:Phone>999-555-2424</cq:Phone>
<cq:Company>FooBar Company</cq:Company>
</oslc_cm:ChangeRequest>
</cq:customer>
</oslc_cm:ChangeRequest>
</rdfs:member>
</rdf:Description>
</rdf:RDF>

The same query result that is returned in JSON format:

HTTP/1.1 200 OK
OSLC-Core-Version: 2.0
Transfer-Encoding: chunked
Content-Type: application/json; charset=UTF-8

{
   "prefixes":{
      "oslc":"http:\/\/open-services.net\/ns\/core#",
      "oslc_cm":"http:\/\/open-services.net\/ns\/cm#",
      "rdf":"http:\/\/www.w3.org\/1999\/02\/22-rdf-syntax-ns#",
      "rdfs":"http:\/\/www.w3.org\/2000\/01\/rdf-schema#",
      "dcterms":"http:\/\/purl.org\/dc\/terms\/",
      "cq":"http:\/\/www.ibm.com\/xmlns\/prod\/rational\/clearquest\/1.0\/"
   },
   "rdf:type":[
      {
         "rdf:resource":"http:\/\/www.w3.org\/1999\/02\/22-rdf-syntax-ns#Description"
      }
   ],
   "rdf:about":"http:\/\/quagmire\/cqweb\/oslc\/repo\/7.0.0\/db\/SAMPL\/simpleQuery\/16777224",
   "oslc:responseInfo":{
      "rdf:type":[
         {
            "rdf:resource":"http:\/\/open-services.net\/ns\/core#ResponseInfo"
         }
      ],
      "dcterms:title":"cq:customer{cq:Company=\"FooBar Company\"} and cq:State in [\"Opened\",\"Assigned\"]",
      "oslc:totalCount":3,
      "oslc:self":"http:\/\/quagmire\/cqweb\/oslc\/repo\/7.0.0\/db\/SAMPL\/simpleQuery\/16777224?oslc.where=cq:customer{cq:Company=%22FooBar%20Company%22}%20and%20cq:State%20in%20[%22Opened%22,%22Assigned%22]&oslc.select=dcterms:title,cq:customer{cq:Company,cq:Phone}&oslc.prefix=cq=%3Chttp:\/www.ibm.com\/xmlns\/prod\/rational\/clearquest\/1.0\/%3E"
   },
   "rdfs:member":[
      {
         "rdf:about":"http:\/\/quagmire\/cqweb\/oslc\/repo\/7.0.0\/db\/SAMPL\/record\/16777224-33565354",
         "dcterms:type":"Defect",
         "rdf:type":[
            {
               "rdf:resource":"http:\/\/open-services.net\/ns\/cm#ChangeRequest"
            },
            {
               "rdf:resource":"http:\/\/www.ibm.com\/xmlns\/prod\/rational\/clearquest\/1.0\/Defect"
            }
         ],
         "dcterms:title":"TEST JUnit Test Record Submit TEST",
         "dcterms:identifier":"33565354",
         "oslc:shortTitle":"SAMPL00010922",
         "cq:customer":[
            {
               "rdf:about":"http:\/\/quagmire\/cqweb\/oslc\/repo\/7.0.0\/db\/SAMPL\/record\/16777937-33554725",
               "dcterms:type":"Customer",
               "rdf:type":[
                  {
                     "rdf:resource":"http:\/\/open-services.net\/ns\/cm#ChangeRequest"
                  },
                  {
                     "rdf:resource":"http:\/\/www.ibm.com\/xmlns\/prod\/rational\/clearquest\/1.0\/Customer"
                  }
               ],
               "dcterms:identifier":"33554725",
               "oslc:shortTitle":"Anne Johnson",
               "cq:Phone":"(987) 123 - 0123",
               "cq:Company":"FooBar Company"
            }
         ]
      },
      {
         "rdf:about":"http:\/\/quagmire\/cqweb\/oslc\/repo\/7.0.0\/db\/SAMPL\/record\/16777224-33572254",
         "dcterms:type":"Defect",
         "rdf:type":[
            {
               "rdf:resource":"http:\/\/open-services.net\/ns\/cm#ChangeRequest"
            },
            {
               "rdf:resource":"http:\/\/www.ibm.com\/xmlns\/prod\/rational\/clearquest\/1.0\/Defect"
            }
         ],
         "dcterms:title":"Demo to Support override price does not work Hope it was good...",
         "dcterms:identifier":"33572254",
         "oslc:shortTitle":"SAMPL00017822",
         "cq:customer":[
            {
               "rdf:about":"http:\/\/quagmire\/cqweb\/oslc\/repo\/7.0.0\/db\/SAMPL\/record\/16777937-33554725",
               "dcterms:type":"Customer",
               "rdf:type":[
                  {
                     "rdf:resource":"http:\/\/open-services.net\/ns\/cm#ChangeRequest"
                  },
                  {
                     "rdf:resource":"http:\/\/www.ibm.com\/xmlns\/prod\/rational\/clearquest\/1.0\/Customer"
                  }
               ],
               "dcterms:identifier":"33554725",
               "oslc:shortTitle":"Anne Johnson",
               "cq:Phone":"(987) 123 - 0123",
               "cq:Company":"FooBar Company"
            },
            {
               "rdf:about":"http:\/\/quagmire\/cqweb\/oslc\/repo\/7.0.0\/db\/SAMPL\/record\/16777937-33554794",
               "dcterms:type":"Customer",
               "rdf:type":[
                  {
                     "rdf:resource":"http:\/\/open-services.net\/ns\/cm#ChangeRequest"
                  },
                  {
                     "rdf:resource":"http:\/\/www.ibm.com\/xmlns\/prod\/rational\/clearquest\/1.0\/Customer"
                  }
               ],
               "dcterms:identifier":"33554794",
               "oslc:shortTitle":"Bart Simpson",
               "cq:Phone":"",
               "cq:Company":""
            }
         ]
      },
      {
         "rdf:about":"http:\/\/quagmire\/cqweb\/oslc\/repo\/7.0.0\/db\/SAMPL\/record\/16777224-33579830",
         "dcterms:type":"Defect",
         "rdf:type":[
            {
               "rdf:resource":"http:\/\/open-services.net\/ns\/cm#ChangeRequest"
            },
            {
               "rdf:resource":"http:\/\/www.ibm.com\/xmlns\/prod\/rational\/clearquest\/1.0\/Defect"
            }
         ],
         "dcterms:title":"Demo to Support override price does not work Hope it was good...",
         "dcterms:identifier":"33579830",
         "oslc:shortTitle":"SAMPL00025398",
         "cq:customer":[
            {
               "rdf:about":"http:\/\/quagmire\/cqweb\/oslc\/repo\/7.0.0\/db\/SAMPL\/record\/16777937-33554789",
               "dcterms:type":"Customer",
               "rdf:type":[
                  {
                     "rdf:resource":"http:\/\/open-services.net\/ns\/cm#ChangeRequest"
                  },
                  {
                     "rdf:resource":"http:\/\/www.ibm.com\/xmlns\/prod\/rational\/clearquest\/1.0\/Customer"
                  }
               ],
               "dcterms:identifier":"33554789",
               "oslc:shortTitle":"Alfred Hitchcock",
               "cq:Phone":"",
               "cq:Company":""
            },
            {
               "rdf:about":"http:\/\/quagmire\/cqweb\/oslc\/repo\/7.0.0\/db\/SAMPL\/record\/16777937-33554794",
               "dcterms:type":"Customer",
               "rdf:type":[
                  {
                     "rdf:resource":"http:\/\/open-services.net\/ns\/cm#ChangeRequest"
                  },
                  {
                     "rdf:resource":"http:\/\/www.ibm.com\/xmlns\/prod\/rational\/clearquest\/1.0\/Customer"
                  }
               ],
               "dcterms:identifier":"33554794",
               "oslc:shortTitle":"Bart Simpson",
               "cq:Phone":"",
               "cq:Company":""
            },
            {
               "rdf:about":"http:\/\/quagmire\/cqweb\/oslc\/repo\/7.0.0\/db\/SAMPL\/record\/16777937-33697154",
               "dcterms:type":"Customer",
               "rdf:type":[
                  {
                     "rdf:resource":"http:\/\/open-services.net\/ns\/cm#ChangeRequest"
                  },
                  {
                     "rdf:resource":"http:\/\/www.ibm.com\/xmlns\/prod\/rational\/clearquest\/1.0\/Customer"
                  }
               ],
               "dcterms:identifier":"33697154",
               "oslc:shortTitle":"Jonathan Foo",
               "cq:Phone":"999-555-2424",
               "cq:Company":"FooBar Company"
            }
         ]
      }
   ]
}

Error Responses

You can tell if a request succeeded or failed by looking at the HTTP status code in the response. Status codes in the 200s indicate success, status codes in the 300s indicate a redirect (not frequently used by CQ OSLC APIs), and status codes 400 and above indicate errors.