Access Keys:
Skip to content (Access Key - 0)

Federated Query Processor
You are viewing an old version of this page. View the current version. Compare with Current  |   View Page History
<< Previous Version 32 Next >>

Distributed Common Query Language

Table of Contents

Overview of DCQL

DCQL is an XML-based language used to express federated queries. It is an extension to CQL, the language used to query individual data services.

Both CQL and DCQL describe queries in a declarative, non-procedural way that is based on the data services' UML-based domain model. That is, a query can be seen as a request for instances of a class in a model. The query identifies this class as its target class.

Queries can request all instances of the target class by not placing any restrictions on which instances should be returned. However, it is common for queries to include restrictions on which instances of the target class should be returned. These restrictions can take two forms.

Firstly the returned instances of the target class can be restricted to those that have an association with an instances of another (or possibly the same) class. The instances of those classes can be further restricted to those that have other associations. There is no limit to how deeply the requirements for associations can be nested.

The other way that a DCQL or CQL query can restrict which instances are returned is by requiring the values of their attributes to have certain values. For example, a query might specify that instances of a target class must have a version attribute that is equal to 3. The query might further specify that the returned instances of the target class must be associated with an instance of a class named Subscription that has an expiration date that is less than January 31, 2011.

DCQL extends CQL in two ways. The service that provides the results for a CQL query is not specified in the query and is assumed to be the service that the query is sent to. DCQL queries include a list of target services to be queried.

The associations specified in a CQL query are all withing a single data service. DCQL allows virtual associations (joins) to be specified between data services.

Services accepting DCQL (such as the FQP service), generally don't expose any local data.

Details

As DCQL is modeled as an extension to CQL, it mirrors the general structure wherein a target object Class is identified, and instances are specified by restrictions over its attributes and associated objects. The specifics of each component of a DCQL query are described below.

DCQLQuery Element

The top-level XML element of a DCQL Query is the DCQLQuery element. A DCQLQuery element contains a TargetObject element that describes the instances to be returned. A DCQLQuery element also contains one or more targetServiceURL elements that each contains the URL of a data service that should be queried.

This mechanism provides the basic support for simple aggregation queries. Each identified service is queried for the identified data, and the results are aggregated and returned to the client.

DCQL is a recursively defined language. Queries are descriptions of instance objects. The objects they are associated with can be described using the same mechanism. That is, just as the target object is described by restrictions of its attributes and associations to other objects, the associated objects are defined using the same syntax. This structure is defined by the Object type. The TargetObject element is an instance of the Object type.

Object Type

The Object type defines the structure of DCQL's TargetObject, Association and ForeignObject elements. They all have a required name attribute. The value of the name attribute should be a fully qualified name of a class in the data service's domain model. When name attribute appears in a TargetObject element, it describes the class of objects that will be the the results of the query.

Conforming to the Object type, TargetObject, Association and ForeignObject elements may contain an Attribute, Association, ForeignAssociation or Group element to further constrain the instances they match. Because Association and ForeignObject elements can contain Association and ForeignObject elements, DCQL queries have a recursive structure.

Attribute Element

The Attribute element is the simplest type of restriction. DCQL simply makes use of the CQL Attribute element; its syntax and semantics are the same.

The Attribute element restricts instances of a class based on the value of a single attribute. The restriction is expressed using the Attribute element's name, predicate, and value attributes. For example
    <Attribute name="age" predicate="GREATER_THAN" value="18"/>
will restrict its enclosing object to match only instances whose age attribute has a value greater than 18.

The value of the name attribute is the name of the instance attribute to be used. The name attribute is required.

The value of the predicate attribute is the operator that should be used to determine whether or not a given instance should be included in a query. The permitted predicate values for comparing the value of an attribute to a constant value are EQUAL_TO, NOT_EQUAL_TO, LESS_THAN, LESS_THAN_EQUAL_TO, GREATER_THAN, and GREATER_THAN_EQUAL_TO.

The predicate value LIKE means that the value of the named attribute of each instance will be matched against a pattern. This matching will be similar to EQUAL_TO for strings, except that

  • question mark (?) characters in the pattern are treated as a wild card that matches any single character and
  • percent sign (%) characters in the pattern are treated as a wild card character that matches any sequence of characters.

There are just two other permitted values for the predicate attribute. The values IS_NULL and IS_NOT_NULL check only for the presence or absence, respectively, of an instance attribute's value.

The value of the value attribute is used as the value to compare or match with instances' attribute values. If the value of the predicate attribute is IS_NULL or IS_NOT_NULL then the value of the value attribute is ignore, since it is not needed. However, since the schema for DCQL specifies that the value attribute is required, it should be specified.

EQUAL_TO Should not be Assumed
The schema for DCQL specifies that the predicate attribute is optional with a default value of EQUAL_TO. However, some implementations of the DCQL will reject a query if it contains any Attribute elements that don't have the value of their predicate attribute explicitly specified. Therefore, if the intended value of the predicate attribute is EQUAL_TO, then the value of the predicate attribute should be explicitly specified rather than relying on the default.


Association Element

The Association element is used to describe a connection or association, between the containing class and the class identified by the Association element. The Association element inherits the structure of the Object type. The Association element has a required name attribute whose value is the name of a class in the data service's domain model. Association elements may contain an Attribute, Association, ForeignAssociation or Group element to further constrain the instances they match.

The containing class is considered to be the source end of the UML association; the class described by the Association element is considered to be the target end of the association.

In addition to the structure it inherits from the Object type, the Association element has an optional roleName attribute. The value of the {{roleName)) attribute is the name of the role that the target object plays in the UML association. If more than one association between the two classes is present in the model, then the roleName must be used to disambiguate the relationship. The query is considered invalid if the roleName is omitted and multiple associations between the two classes exist in the model.

roleName Should be Specified
The schema for DCQL specifies that the roleName attribute is optional, some implementations of the DCQL will reject a query if it contains any Association elements that don't have the their roleName attribute explicitly specified. Therefore, the roelName attribute should always be specified.


ForeignAssociation Element

A ForeignAssociation elements restricts which instances of its enclosing class will be used in a query by describing a connection or virtual association with instances of a class on a remote data service. This element is similar to the Assocaition that uses assocations between classes whose instances come from the same data service.

A ForeignAssociation element has a required targetServiceURL attribute whose value should be the URL of the remote data service.

A ForeignAssociation element contains a JoinCondition element and a ForeignObject element. The JoinCondition element describes the logic to use for associating instances of the enclosing class with instances of the class in the remote data service that is described by the ForeignObject element.

JoinCondition Element

A JoinCondition element is used in a ForeignAssociation element to describe the logic to use for associating instances of a class in the local data service with instances of a class in a remote data service

This element is similar to the Attribute element, in that a predicate is used to identify a relationship between values, but differs by comparing the value of two instance attributes, rather than comparing an instance value to a constant value.

The JoinCondition element has a predicate attribute. The set of allowable values for the JoinCondition element's predicate attribute is the same as for the Attribute element's predicate attribute, with the exception of that IS_NULL and IS_NOT_NULL are not allowed.

The value of the localAttributeName attribute is the name of the instance attribute to use when applying the named predicate to local instances.

The value of the foreignAttributeName attribute is the name of the instance attribute to use when applying the named predicate to remote instances.

EQUAL_TO Should not be Assumed
The schema for DCQL specifies that the predicate attribute is optional with a default value of EQUAL_TO. However, some implementations of the DCQL will reject a query if it contains any JoinCondition elements that don't have the value of their predicate attribute explicitly specified. Therefore, if the intended value of the predicate attribute is EQUAL_TO, then the value of the predicate attribute should be explicitly specified rather than relying on the default.


ForeignObject Element

A ForeignObject element is used in a ForeignAssociation element to describe instances of a class on a remote data service. The ForeignObject element inherits is structure from the Object type.

A ForeignObject element has a required name attribute whose value is the fully qualified name of the class. A ForeignObject element may contain an Attribute, Association, ForeignAssociation or Group element to further constrain the instances it matches.

Group Element

The Group element provides the capability to express two or more restrictions. Whenever a multiple restrictions (Association, Attribute, or ForeignAssociation) need to be combined in the same Object, a Group element must be used to combine them.

A Group element contains two or more of these restrictions. The restrictions can be combined using either "AND" or "OR" logic. The combining logic used for a Group element is determined by the value of its logicalRelation attribute. The value of the logicalRelation attribute must be either OR or AND. If the value of the logicalRelation attribute is "AND" all of the contained restrictions must be met for the Group restriction to be met. If the value is "OR" only one restriction must be met for the Group restriction to be met.

In addition to grouping other constraints, the Group type can also contain nested Groups. This simple construct allows for arbitrarily complex constraints to be modeled.

An Example Query

An example DCQL query, represented in XML, is shown below. In this fictitious example, a PersonRegistry Data Service is joined with a StudyRegistry Data Service. The query specifies Persons in the PersonRegistry should be returned which have an "ssn" that is equal to that of a Participant's "patientSSN" and the Participant should have an "age" greater than 18. The specification of the target service can be seen on line 18 in the example (in this case only one service is targeted, though may could have been listed). Additionally, the "join" is specified starting on line 6, wherein the second target service is identified, and the join condition is defined. The join condition creates a link between the containing Object (in this case, Person), and an Object (in this case Participant, as defined on line 10) in the second target service. The condition specifies a predicate to be evaluated against an attribute in each of the two linked Objects (in this case Person.ssn and Participant.patientSSN). It is worth noting that as DCQL is a recursive language, the ForeignObject defined on line 10 could have also specified a join to a third Data Service, or other more complex criteria.

Unable to render embedded object: File (DCQL_Example1.png) not found.

Schema

*http://caGrid.caBIG/1.0/gov.nih.nci.cagrid.dcql*

NOTE: The schema for CQL (http://CQL.caBIG/1/gov.nih.nci.cagrid.CQLQuery) may be found on the CQL Schemas Page
<xsd:schema targetNamespace="http://caGrid.caBIG/1.0/gov.nih.nci.cagrid.dcql" xmlns:xsd="http://www.w3.org/2001/XMLSchema"
	xmlns:dcql="http://caGrid.caBIG/1.0/gov.nih.nci.cagrid.dcql" xmlns:cql="http://CQL.caBIG/1/gov.nih.nci.cagrid.CQLQuery" elementFormDefault="qualified"
	attributeFormDefault="unqualified">
	<xsd:import namespace="http://CQL.caBIG/1/gov.nih.nci.cagrid.CQLQuery" schemaLocation="./xsd/Data/1_gov.nih.nci.cagrid.CQLQuery.xsd"/>
	<xsd:element name="DCQLQuery">
		<xsd:annotation>
			<xsd:documentation>caGrid Distributed CQL Query, the desired result objects are described by the TargetObject, and the CQL query resulting from the processing is sent to each data service identified by the targetServiceURLs</xsd:documentation>
		</xsd:annotation>
		<xsd:complexType>
			<xsd:sequence>
				<xsd:element name="TargetObject" type="dcql:Object"/>
				<xsd:element name="targetServiceURL" type="xsd:string" maxOccurs="unbounded">
					<xsd:annotation>
						<xsd:documentation>The URL of a data service which should be sent the resulting CQL query.</xsd:documentation>
					</xsd:annotation>
				</xsd:element>
			</xsd:sequence>
		</xsd:complexType>
	</xsd:element>
	<xsd:complexType name="Object">
		<xsd:annotation>
			<xsd:documentation>Description of an Object instance</xsd:documentation>
		</xsd:annotation>
		<xsd:choice>
			<xsd:element name="Attribute" type="cql:Attribute" minOccurs="0">
				<xsd:annotation>
					<xsd:documentation>The description of the object being targeted by the query; the return type.</xsd:documentation>
				</xsd:annotation>
			</xsd:element>
			<xsd:element name="Association" type="dcql:Association" minOccurs="0"/>
			<xsd:element name="ForeignAssociation" type="dcql:ForeignAssociation" minOccurs="0"/>
			<xsd:element name="Group" type="dcql:Group" minOccurs="0"/>
		</xsd:choice>
		<xsd:attribute name="name" type="xsd:string" use="required"/>
	</xsd:complexType>
	<xsd:complexType name="Association">
		<xsd:annotation>
			<xsd:documentation>Describes an optionally (role-)named relationship from this Object to another.</xsd:documentation>
		</xsd:annotation>
		<xsd:complexContent>
			<xsd:extension base="dcql:Object">
				<xsd:attribute name="roleName" type="xsd:string" use="optional"/>
			</xsd:extension>
		</xsd:complexContent>
	</xsd:complexType>
	<xsd:complexType name="Group">
		<xsd:annotation>
			<xsd:documentation>A collection of two or more sub-constraints, grouped together by the logicalRelation.</xsd:documentation>
		</xsd:annotation>
		<xsd:choice minOccurs="2" maxOccurs="unbounded">
			<xsd:element name="Association" type="dcql:Association" maxOccurs="unbounded"/>
			<xsd:element name="Attribute" type="cql:Attribute" maxOccurs="unbounded"/>
			<xsd:element name="ForeignAssociation" type="dcql:ForeignAssociation" maxOccurs="unbounded"/>
			<xsd:element name="Group" type="dcql:Group" maxOccurs="unbounded"/>
		</xsd:choice>
		<xsd:attribute name="logicRelation" type="cql:LogicalOperator" use="required"/>
	</xsd:complexType>
	<xsd:complexType name="ForeignAssociation">
		<xsd:annotation>
			<xsd:documentation>An association or relationship defined between this Object and an Object defined by the ForeignObject, located on the data service located at the targetServiceURL.</xsd:documentation>
		</xsd:annotation>
		<xsd:sequence>
			<xsd:element name="JoinCondition" type="dcql:JoinCondition"/>
			<xsd:element name="ForeignObject" type="dcql:Object"/>
		</xsd:sequence>
		<xsd:attribute name="targetServiceURL" type="xsd:string" use="required"/>
	</xsd:complexType>
	<xsd:complexType name="JoinCondition">
		<xsd:annotation>
			<xsd:documentation>Specifies a relationship, defined by the predicate, between a local attribute and a remote attribute.</xsd:documentation>
		</xsd:annotation>
		<xsd:attribute name="predicate" type="dcql:ForeignPredicate" use="optional" default="EQUAL_TO"/>
		<xsd:attribute name="localAttributeName" type="xsd:string" use="required"/>
		<xsd:attribute name="foreignAttributeName" type="xsd:string" use="required"/>
	</xsd:complexType>
	<xsd:simpleType name="ForeignPredicate">
		<xsd:annotation>
			<xsd:documentation>Predicate types used for attribute comparisons</xsd:documentation>
		</xsd:annotation>
		<xsd:restriction base="xsd:string">
			<xsd:enumeration value="EQUAL_TO" id="equal_to">
				<xsd:annotation>
					<xsd:documentation>Two values are equivalent.</xsd:documentation>
				</xsd:annotation>
			</xsd:enumeration>
			<xsd:enumeration value="NOT_EQUAL_TO" id="not_equal_to">
				<xsd:annotation>
					<xsd:documentation>Two values are not equivalent.</xsd:documentation>
				</xsd:annotation>
			</xsd:enumeration>
			<xsd:enumeration value="LESS_THAN" id="less_than">
				<xsd:annotation>
					<xsd:documentation>The first value is less than the second.</xsd:documentation>
				</xsd:annotation>
			</xsd:enumeration>
			<xsd:enumeration value="LESS_THAN_EQUAL_TO" id="less_than_equal_to">
				<xsd:annotation>
					<xsd:documentation>The first value is less than, or equivalent to, the second.</xsd:documentation>
				</xsd:annotation>
			</xsd:enumeration>
			<xsd:enumeration value="GREATER_THAN" id="greater_than">
				<xsd:annotation>
					<xsd:documentation>The first value is greater than the second.</xsd:documentation>
				</xsd:annotation>
			</xsd:enumeration>
			<xsd:enumeration value="GREATER_THAN_EQUAL_TO" id="greater_than_equal_to">
				<xsd:annotation>
					<xsd:documentation>The first value is greater than, or equivalent to, the second.</xsd:documentation>
				</xsd:annotation>
			</xsd:enumeration>
		</xsd:restriction>
	</xsd:simpleType>
</xsd:schema>
Last edited by
Sarah Honacki (970 days ago) , ...
Adaptavist Theme Builder Powered by Atlassian Confluence