Administration
|
Key
This line was removed.
This word was removed. This word was added.
This line was added.
|
Changes (41)
View Page History
...
h1. Distributed Common Query Language h1. Overview of DCQL
----
----
DCQL is an XML-based language used to express federated queries. It is an extension to [CQL|dataservices: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' service's 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. ways: 1.) The service that provides the results for a CQL query is not specified in the query and is assumed to be the service that to which the query is sent to. DCQL sent, and 2.) CQL 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.
...h1. Details
----
----
As DCQL is modeled as an extension to [CQL|dataservices:CQL], it mirrors the general structure wherein a target object Cclass 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.
h2. {{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 Oobject type. The {{TargetObject}} element is an instance of the Oobject type.
!DCQL Query.png!
h2. {{Object}} {anchor:Object} Type
h2. {{Object}} {anchor:Object} Type
The {{Object}} type defines the structure of DCQL's 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.
!Object.png!
h2. {{Attribute}} {anchor:Attribute} Element
h2. {{Attribute}} {anchor: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 element's {{name}}, {{predicate}}, and {{value}} attributes. For example\\ 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.
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 character.
* 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 attribute's value.
The value of the {{value}} attribute is used as the value to compare or match with instances' 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.
{warning:title=EQUAL_TO Should not be Assumed}
The {warning:title=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 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.
{warning}\\
h2. {{Association}} Element
h2. {{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|#Object]. The {{Association}} element has a required {{name}} attribute whose value is the name of a class in the data service's 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.
!Association.png!
!Association.png!
{warning:title=roleName Should be Specified}
{warning:title=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 don't have the their {{roleName}} attribute explicitly specified. Therefore, the {{roelName}} {{roleName}} attribute should always be specified.
{warning}\\
h2. {{ForeignAssociation}} Element
h2. {{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}} {{Association}} that uses associations between classes whose instances come from the same data service.
!ForeignAssociation.png!
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.
...h2. {{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.
!JoinCondition.png!
The {{JoinCondition}} element has a {{predicate}} attribute. The set of allowable values for the {{JoinCondition}} element's element's {{predicate}} attribute is the same as for the [{{Attribute}} element's|#Attribute] element's|#Attribute] {{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.
{warning:title=EQUAL_TO Should not be Assumed}
The {warning:title=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 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.
{warning}\\
h2. {{ForeignObject}} Element
h2. {{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|#Object].
A {{ForeignObject}} element is used in a {{ForeignAssociation}} element to describe instances of a class on a remote data service. The {{ForeignObject}} element inherits its structure from the [{{Object}} type|#Object].
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.
!ForeignObject.png!
h2. {{Group}} Element
h2. {{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.
...h1. 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 that 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).
The specification of the target service can be seen on line 18 in the example. In this case, only one service is targeted, though many could have been listed.
A {{ForeignAssociation}} starts on line 6 that restricts which instances of {{Person}} are returned by the query with an association between the containing instances of the {{Person}} class and {{Participant}} objects in a remote data service. The {{JoinCondition}} 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.
!An Example Query^DCQL_Example1.png|align=center!
...