Administration
Portal 2.0 Users Guide
 |
 |
 |
 |
Table of Contents |
 |
 |
 |
 |
Data Service Query Portlet
Building a Query
To execute a CQL query, the user needs two things:
- The URL of the caGrid data service to which the query will be sent.
- The CQL query itself.
The portal provides several approaches for specifying each of these. To specify the service URL, one can use the discovery portlet to locate the desired service, and then select it for querying. Or, one can enter the service URL directly. To specify the CQL query, the user can use a graphical query building tool, or enter the CQL query text directly.
Scenario 1
User does not have URL or CQL query.
- Locate a service using either the Directory or Search tab of the Discovery portlet
- Data services have a "Query..." link in the List View of discovery results.
- Clicking on this link causes the Data Service Query portlet to display the list of available UML classes for that service in the Select UML Class tab.
- The service URL is also automatically populated in the Service URL field of that tab.
- Clicking on a UML class selects that service and UML class for query
- A working query is displayed in the Query > CQL Builder sub tab of the Daa Service Query portlei.
Scenario 1a
User does not have URL or CQL query and wants to view metadata of UML classes before deciding which class to query.
- Locate a service using either the Directory or Search tab of the Discovery portlet
- Click "More Details..." link for a data service in the List View
- Navigate to the Domain Model and find the desired UML class by view associated metadata
- Click the Select for Query button in the desired UML class node
- A working query is displayed in Query > CQL Builder sub tab of the Daa Service Query portlet.
Scenario 2
User has URL, but no CQL query.
- Go to the Select UML Class tab of the Data Service Query portlet
- Enter the URL in the Service URL field
- Press Select button
- Click on UML class from list that appears
- A working query is displayed in the Query > CQL Builder sub tab of the Daa Service Query portlet.
Scenario 3
User has URL and CQL query.
- Go to the Query > CQL XML sub tab of the Data Service Query portlet
- Enter service URL in the URL field
- Enter CQL query in the Query textarea
CQL Builder
The Query > CQL Builder sub tab provides a graphical interface for building CQL Queries. While you can use this tool without any knowledge of CQL, it helps to understand the concepts. To use this tool, you must first select the service and UML class to query by following the steps described in Scenario 1 or Scenario 1a, above.
You can do the following from this sub tab:
- Edit Query Modifiers: Specifying what kind of results to return (e.g. count, distinct, etc.).
- Add Criterion: Constraining the query.
- Export to XML: Export to the CQL XML format
- Submit Query: Send the query to the target data service.
Edit Query Modifiers
When you press this button, you are presented with four choices:
- Object
- Count Only
- Distinct Attribute
- Selected Attributes
Selecting Object means that the full results should be returned from the data service. Selecting Count Only means that only the count of the objects that match the given criteria should be returned. Selecting Distinct Attribute means that only the unique values of a particular attribute of the instances of the UML class that you are querying should be returned. When you select the option, you'll be presented with a list of radio buttons, from which you can choose exactly one. Selecting Selected Attributes means that only certain attribute values will be returned for each object in the results. When you select this option, you'll be presented with a list of check boxes, from which you can choose at least one. The selected check boxes indicate which attribute values will be returned.
Add Criterion
When you press this button, you are presented with a list of the UML class' attributes and associations. You can click on any attribute of the target UML class, or an associated UML class, in order to specify a criterion. When you click on an attribute link, you'll see a form in which you can specify the predicate and value to be used for this criterion. For example, you can specify that the attribute should be equaly to 'xyz'. You can specify multiple values by separating them with commas. When you click the Update button, the criterion is added to the query.
You can add multiple criteria to a query. All criteria are ANDed together. If multiple values are specified for a particular criterion, multiple criteria are created and ORed together.
Export To XML
The CQL Builder tool does not currently allow the user to create all possible CQL queries. For example, the tool will group all criteria in a logical AND. So, it is impossible to create logical OR groupings other than for multiple values specified for the same criterion.
But, queries created through the CQL Builder tool can be exported to the CQL XML format, which can be further edited by the user.
NOTE: While CQL queries can be exported to XML, they cannot currently be imported back into the builder tool after editing.
Submit Query
Pressing the Submit Query button causes the CQL query to be sent to the target data service.
CQL XML
The Query > CQL XML sub tab allows the user to enter a data service URL and CQL query directly and then execute or share the query.
Executing Queries and Viewing Results
After pressing the Submit Query button from either the CQL Builder or CQL XML sub tabs, the History tab is displayed. This tab shows all of the queries that the user has executed. If the user is authenticated, this list will include all queries the user has ever executed. If the user is not authenticate, then only those queries that have been executed during the user's session (i.e. until the browser is closed) will be displayed. The most recent query is displayed first.
The query history list displays the following for each query:
- Operations: The list of operations that can be performed on the query.
- State: The state of the query (e.g. RUNNING, COMPLETE, ERROR, etc.)
- Start Time
- Finish Time
- Service: The name of the target service.
Queries can be in the following states:
- RUNNING: the query is still running
- COMPLETE: the query completed successfully
- ERROR: the query failed
- CANCELED: the user chose to cancel the query
- TIMED OUT: the system cancelled the query
Based on the state of the query, the user can perform different operations:
- RUNNING: cancel, delete
- COMPLETE: view results, reload, delete
- ERROR: view error, reload, delete
- CANCELED: reload, delete
- TIMED OUT: reload, delete
Reloading a query causes it to be loaded into the CQL XML query sub tab, where the user can edit it, or run it again. Deleting the query will remove it from the query history. Selecting view results will cause the results to be displayed in the Results > Tabular sub tab.
From the Results tab, query results can be viewed in tabular or XML form. From the Results > Tabular sub tab, the user can export query results to MS Excel fomat.
Working with Shared Queries
The portal allows any authenticated portal users to create, annotate, and share CQL queries. Other users (even un-authenticated users) can search for these queries based on the target service, the target UML class, or the creator of the query.
Sharing Queries
New queries or queries that have already been executed can be shared. If you are logged in, you will see a Share Query button in both the CQL Builder and CQL XML*tabs. Pressing this button presents a form into which you can specify a name and description for the query. To share a query that has already been executed, select the *Re-load operation on that query from the History tab. The query will be loaded into the CQL XML tab where you will see the Share Query button.
Finding Shared Queries
The Shared Queries > Find Shared Queries sub tab presents a search form which is used to find shared queries. The user can perform a keyword search for queries based on the target service, the target UML class, or the creator of the query. The results of a search are displayed in a paginated list. The user can choose to view or load any shared query.
My Queries
The Shared Queries > My Queries sub tab is visible to authenticated portal users. Here the user can view, edit and delete shared queries.