Building Queries and Data Views
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:
Click the Test tab to switch to the Test mode.
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.
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
To run your query, click the Run Query button on the Toolbar or select Run Query from the Query menu.
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.
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
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.
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:
Figure 6-7 Sample Query Parameter and Complex Parameter Type (CPT) Settings
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.
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.
There are a few Liquid Data query naming conventions:
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.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, myquery.xq
and 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
The advantages of saving your queries to the stored_queries
folder of the Liquid Data repository include:
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).
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:
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.
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.
The Deploy Query command is available from the Query menu when in Test mode. There are two requirements for deploying queries:
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.
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
Follow the same approach in deciding whether to save your query to your <LD_REPOSITORY>/stored_queries
directory.
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:
stored_queries/uCustomer/custQuery.xq
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.
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:
stored_query
directory of the repository.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.
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:
For information on creating and managing data views see Configuring Access to Data Views in the Liquid Data Administration Guide.