Building Queries and Data Views
Running, Saving, and Deploying Queries
This topic describes how to run BEA Liquid Data for WebLogic queries, as well as how to save and deploy queries. The following sections are included:
Test mode in the Data View Builder allows you to:
- View the generated XQuery that is based upon your mapping and optimization inputs
- Enter any needed query parameters
- Enter complex parameter type (CPT) reference file names
- View and analyze the query plan
- Run your query against data sources and verify the result
- Get statistical information on the query after it has run
- Experiment with hand editing a generated query or write and test a query from scratch
Click the Test tab to switch to the Test mode.
Figure 6-1 Test Tab
Viewing a Generated Query
Whenever you enter Test mode an XQuery is automatically created based upon the input provided through the Design and Optimize tabs. (See Target Schemas for details.)
The query appears in the upper-left pane of the Test tab (Figure 6-1). Whenever you save a query, it is saved exactly as it appears.
Editing a Generated Query
Although queries are generally automatically generated, you can make changes to the generated query or create one from scratch. In addition to standard Cut, Copy, and Paste, and Delete editing functions, buffered Undo and Redo editing commands are available through the Test tab toolbar (Figure 6-2).
Figure 6-2 Click the Run Query Button to Run the Query
Running a Query
To run your query, click the Run Query button on the Toolbar or select Run Query from the Query menu.
Figure 6-3 Run Query Button
Queries are run against available data sources made available through a Liquid Data Server. Results appear in the Results panel as an XML tree (Figure 6-3).
Figure 6-4 Expanded Query Results
Alternatively, you can view the query results as XML source (Figure 6-5). To view as XML select the checkbox at the bottom of the query Results panel. You can also right-click on the results pane to change the results format to XML source.
Figure 6-5 Query Result in XML Source Format
Once generated in XML, query results can easily be formatted in a variety of printed reports or displayed in web pages. For an example of the use of Liquid Data data as part of a web application see the Getting Started Demo and Understanding the Avitek Customer Service Sample Application in Liquid Data by Example.
Stopping a Running Query
You can stop a running query before it has finished by clicking the Stop Query Execution button in the Toolbar (Figure 6-6).
Figure 6-6 Stop Query Execution Button
Specifying Large Results Sets
If you expect your query to produce a result set that may exceed available memory, choose the Large Results option, available from the Test mode page (lower left, Figure 6-1) prior to running your query.
If the Large Results option is selected for a query, Liquid Data will use swap files to temporarily store intermediate results. Although your query will run more slowly, this option will avoid possible out-of-memory errors.
Note: Before using this option, increase heap size on the server. This is further discussed in the chapter Tuning Performance in the Liquid Data Deployment Guide.
You can explicitly specify a directory for swap files using the Administration Console. For more information, see Configuring Liquid Data Server Settings in the Administration Guide.
Specifying Query Parameters
You can use the Query Parameters panel (located below the generated query area) to enter or change variable values prior to running a query.
The types of variables that may appear include:
Setting and Changing Query Parameters
To set or change query parameters click in a cell in the Value column. You can either delete what is currently there or edit it using simple character insert and delete commands.
For examples of using query parameters see the following example queries in Liquid Data by Example.
- Example 1: Simple Joins
- Example 2: Aggregates
- Example 3: Date and Time Duration
Saving a Query
From the Test tab, you can save a query by choosing File —> Save Query or by clicking on the Save Query button on the toolbar.
Figure 6-8 Click the Save Query Button
In order to save or update files to a Liquid Data repository that has security restrictions in place, you need to either belong to the proper security group or specifically have appropriate access permissions granted to you by your Liquid Data administrator.
If you have such permissions, whenever you start the Data View Builder you need to enter the exact, case-sensitive user name and password that was assigned to you by your Liquid Data administrator.
Liquid Data security is based on the WebLogic Server security policy system. For details see Security in Liquid Data in the Administration Guide which contains additional references to WebLogic Server security documentation.
Note: By default, the Liquid Data Samples repository does not have any security restrictions so you can freely create or delete items, including queries in the
stored_queries repository directory without having to enter a user name or password.
Query Naming Conventions
There are a few Liquid Data query naming conventions:
- Stored queries always have an .xq
extension. Queries saved to the Liquid Data repository much have an
.xq extension. If you save the query via the Data View Builder, the
.xq extension is automatically appended.
- Names of queries to be generated as Web services must follow W3C XML tag naming conventions. If you want to use Liquid Data to generate a web service from a query, the query name must adhere to the same naming conventions as an XML tag. This is because the query name is converted to an XML tag in the web service-generation process. (For information on how to generate a web service from a stored query, see Generating and Publishing Web Services in the Liquid Data Administration Guide.)
XML naming conventions require that a name (which will be converted to an XML tag name) must be alphanumeric and must begin with an alphabetic character (letter) — not a number. No special characters (such as a hyphen) are allowed in the name. For example,
my12query.xq are both query names that will work with web services generation, whereas
12query.xq will not.
For a complete description of naming conventions for schema tags see W3C XML Schema document at http://www.w3.org/XML/Schema
Using the stored_queries Folder
The advantages of saving your queries to the
stored_queries folder of the Liquid Data repository include:
- Providing the Liquid Data administrator with the ability to create access control at the stored query level
- The query can be used in a WebLogic Workshop
- The query can be turned into a web service
- The query can be turned into a data view
Caching Query Results
When your query resides in the Liquid Data repository you also have the option to configure caching on the query result. Caching of query results for stored queries is configurable through the Liquid Data node of the WebLogic Administration Console (see Configuring the Query Results Cache in the Liquid Data Administration Guide).
Steps to Save a Query to the Repository
If the query is saved into the
<ld_repository>/stored_queries folder, it becomes a stored query in Liquid Data.
To save a query follow these steps:
- On the Test tab, choose File —> Save Query from the menus. (The File —> Save Query menu option is available only from the Test view.)
- Use the file browser to navigate to the Liquid Data Repository; it is the topmost directory listed.
- Enter a name for the query in the File name field of the file browser and click Save. The query is saved to the
stored_queries folder in the Repository with a
You can reload a stored query using the Liquid Data File —> Open Query command after navigating to the directory containing your stored queries.
Once a stored query has been loaded, it is ready to be run. See Running a Query.
Deploying a Query
In a Liquid Data query, data is drawn from heterogeneous sources and then normalized (through automatic and manual casting) to elements in the Data View Builder target XML schema. This information is automatically available when a query is run from the Data View Builder. However, in order for it to be available to applications such as the WebLogic Workshop Liquid Data Control the relationship must be formalized in the Liquid Data Server.
A deployed query is a query that has been saved to the Liquid Data repository and then associated with a target schema that is also in the repository. See To Configure (Deploy) a Stored Query in the Administration Guide.
A query can be deployed through the Data View Builder or the Liquid Data node of the WebLogic Administration Console. In the Administration Console this operation is known as query configuration.
A data view is functionally identical to a deployed query. The difference is that a data views function as data sources for other queries. See Using Data Views.
Deploy Query Command
The Deploy Query command is available from the Query menu when in Test mode. There are two requirements for deploying queries:
- You can only deploy a query if you have adequate permissions. See Security Considerations.
- You cannot "re-deploy" a query. In essence deploying a stored query means that the stored query has been configured to be associated with a specific target schema. The Liquid Data Server tracks the association of these two Liquid Data repository components: a query and a schema, using the name of the query. The association is dynamic so any changes you make to the schema or query file in the repository will automatically be available to the consuming application.
Note: Data views follow the same "no re-deployment" model. You can always delete and recreate a data view of the same name with different components.
To redeploy a stored query or data view, use the Liquid Data node of the WebLogic Administration Console. See "Configuring Stored Queries" in the Liquid Data Administration Guide for additional information on managing stored queries.
Saving the Current Schema and Current Query
When you initially select the Deploy Query menu option, you are asked if you want to save your current target schema and query since only saved target schemas and queries can be part of a deployed query.
Figure 6-9 Schema is Current Confirmation
- Answer Yes unless you do not want your current schema to be part of the deployed query.
If you select Yes a file browser will appear, open to the
<LD_REPOSITORY>/schemas directory. Select a current schema or save the schema under a new name.
If you select No you will be able to select a schema file in the Deploy Query dialog box.
Figure 6-10 Save Schema Dialog Box
Follow the same approach in deciding whether to save your query to your
Note: Queries can be stored in subdirectories of the
stored_queries folder and accessed similarly to a path expression. For example, if a query is saved under, for example:
it could be executed from a
Although a query can be deployed immediately upon entering Test mode, it is a good practice to first run the query to make sure that the results match your expectations.
Deploying Your Query
The Deploy Stored Query dialog box gives you the option of creating a data view at the same time you deploy your query.
Figure 6-11 Deploy Query Dialog
Follow these steps to deploy your query:
- Select Your Query. If you selected to save your query, the Query field will already contain the name of the query you saved. Optionally, browse to another query in the
stored_query directory of the repository.
- Select a Schema. If you selected to save your schema, the Schema field will contain the name of the schema you saved. Optionally, you can use the Select... button to browse to a different schema.
- Deploy Your Query. Click the Deploy button to resave your query with schema information.
Note: Once you have deployed a query to a particular name, you cannot "redeploy" to the same name from the Data View Builder. There is also no need to do this. As long as you are happy with the particular schema you have associated with the stored query, any changes made to these files will automatically be made available from the Liquid Data Server to the application program, including the Data View Builder.See "Configuring Stored Queries" in the Liquid Data Administration Guide for additional information on managing stored queries.
Deploying a Stored Query with a Data View
When you deploy a query, you can optionally create a data view. (The difference between a deployed query and a Data View is that your Data View can be used as a data source in the Data View Builder. See Understanding Data Views, for additional information.)
Figure 6-12 Deploy Query Dialog with Create Data View Option Enabled
The additional steps to deploying a query and a Data View are:
- Check the Also Deploy As View checkbox.
- Enter a name for your Data View (choose a name that is not already in use).
- Click the Deploy button. In addition to deploying your stored query, a Data View will be created in the Liquid Data
For information on creating and managing data views see Configuring Access to Data Views in the Liquid Data Administration Guide.