bea.com | products | dev2dev | support | askBEA

Download Docs | Site Map | Glossary
Search

Building Queries and Data Views

Starting the Builder and Touring the GUI

This section describes how to start the Data View Builder tool in BEA Liquid Data for WebLogicTM. It provides a complete GUI reference and explanation of the tools, data sources, schemas, and task flow for designing, optimizing, and testing a Builder-generated query.

The following topics are covered:

- Starting the Data View Builder

- Data View Builder GUI Tour

- Design Tab

- Optimize Tab

- Test Tab

- Working With Projects

- Special Characters: Occurrence Indicators

- Next Steps: Building and Testing Sample Queries

Starting the Data View Builder

To start the Data View Builder, follow these basic steps.

1. Start the Data View Builder.

   - On a Windows platform, choose the menu item:
     Start—>Programs—>BEA WebLogic Platform 7.0—>BEA Liquid Data for WebLogic 1.0—>Launch Data View Builder

   You can also start the Data View Builder by double-clicking on the file: BEA_Home\WL_HOME\liquiddata\DataViewBuilder\bin\DVBuilder.cmd

   A login window is displayed. This is for logging in to a Liquid Data server.

2. Connect to the Liquid Data server on which the data sources you want to use are located.

   1. The username and password for the Data View Builder is specified in the WebLogic Server (WLS) Compatibility Security via the WLS Administration Console for the Liquid Data server to which you want to connect. For more information, see Implementing Security in the Liquid Data Administration Guide. If the server allows guest users, you do not need to enter a username and password—you can leave these fields blank.

   2. Enter the URL for the Liquid Data server. For example, to connect to a server running on your own machine as a local host you would enter the following:

   >     t3://localhost:7001

   3. Click the Login button.

   The Data View Builder work area and tools appear, as shown in Figure 2-1.

   Figure 2-1 Starting Data View Builder

Data View Builder GUI Tour

The Data View Builder consists of three main views or modes that you can get to by clicking on the associated tabs. Each tab represents a phase in the process of designing and testing a query. Generally, you will use the Design and Test tabs to design and run (test) the query, respectively. Some, but not all, queries will require the use of optimization hints and techniques on the Optimize tab.

- Design Tab

- Optimize Tab

- Test Tab

Design Tab

The Design tab is where you construct the query by working with source and target schemas to specify source conditions and source-to-target mappings.

The following sections describe the features available on the Design tab.

- Overview Picture of Design Tab Components

- 1. Menu Bar for the Design Tab

- 2. Toolbar for the Design Tab

- 3. Builder Toolbar

- 4. Source Schemas

- 5. Target Schema

- 6. Conditions Tab

- 7. Mappings Tab

- 8. Sort By Tab

- 9. Status Bar

Overview Picture of Design Tab Components

The following figure and accompanying sections describe the components on the Design tab. (Click the tab to access it.)

Figure 2-2 Design Tab

Note: Although not entirely specific to the Design tab, the menus, horizontal shortcut toolbar and status bar are also covered in detail in this section since this is the first place you encounter them. Although some menu options and toolbar shortcut buttons do stay the same regardless of which tab you are on, there are mode-specific menus and toolbar options for Design, Optimize, and Test tabs which are explained in those topics.

1. Menu Bar for the Design Tab

The Menu Bar provides File, Schema, View, and Window menus as detailed in the following table.

Table 2-1 Menu Bar for the Design Tab

Menu | Description of Menu Options
--- | ---
File Menu | Provides Project-related actions (creating a new project, saving a project, and so on) along with an Exit option that closes the Data View Builder application. For more information on working with projects in the Data View Builder, see Working With Projects. New Project—Creates a new "blank slate" project. When you choose this option while you have an unsaved project in the workspace you are given the option to save your current work to a project. If you choose not to save, the query you had in work along with any associated source conditions and schema mappings will be lost. Open Project—Opens an existing project you specify. Close Project—Closes the current project. If you have not saved your work, you are given an opportunity to do so. Save Project—Saves the current project. Data View Builder projects are saved with a .qpr filename extension. Save Project As—Saves the current project under another file name. Data View Builder projects are saved with a .qpr filename extension. Add Selected Schema—Adds/opens the source schema that is selected in the Builder Toolbar to the current project. Set Target Schema—Brings up a file browser for browsing to and choosing a target schema file from local system, network drive, or Liquid Data server repository. The file you select is added to the current project as the target schema. Set Selected Source Schema as Target Schema—Causes the source schema that is selected on the Builder Toolbar to be set as the target schema in the current project. Save Target Schema—Saves the current target schema to the folder location and filename you choose. You can save the current target schema locally or in the Liquid Data server repository, which makes it available to other Liquid Data users. Save Query—For a description of this option, see Table 2-3. Exit—Closes the Data View Builder application.
Edit Menu | Provides standard edit features. These are activated or deactivated depending on what is selected on the User Interface. For example, you can delete a node in a schema so when any schema node is selected "Delete" is active. Cut Copy Paste Delete Select All
View Menu | As an alternative to using the tabs the View menu lets you navigate to the following UI views: Design—Same as clicking on Design tab. Optimize—Same as clicking on Optimize tab. Test—Same as clicking on Test tab. Sources and Tools—Provides navigation to the tabs (Sources and Toolbox) and panels on the Builder Toolbar. Same as clicking on the associated tab and panel. For example, choosing View—>Sources and Tools—>Relational Databases is the same as clicking on the Sources Tab and then clicking Relational Databases. To help with screen real estate and workspace, the View menu provides toggles to show or hide various windows, tools, and tabs in the Design view. You can show or hide the following: Toolbars—Includes submenu with options to show/hide horizontal shortcut Toolbar or Builder Toolbar. Panels—Includes submenu with options to show/hide various windows and tabs. Messages—Brings up a Messages dialog for you to keep notes on queries. Data Types—Toggle to show/hide data types for all source and target nodes in the schema windows, as well as required function parameter types. Clear the Data Types check box to disable this feature. On the menu, an "x" by an option indicates it is currently displayed. By default, all tools, windows and tabs are shown when you first open the Data View Builder.
Query Menu | Automatic Type Casting—Toggle to turn automatic type casting on/off. (An "X" next to this option indicates that automatic type casting is on.) For more information about using automatic type casting see Using Automatic Type Casting. Condition Targets—>Advanced View—Toggle to turn Advanced View for manual scoping on/off. For more information on using scoping in Advanced View see Understanding Scope in Basic and Advanced Views. For a description of the other options in the Query menu (Run or Stop Query Execution) which are relevant only for running/testing a query, see Table 2-3.
Window Menu | The Window menu provides various options for window management: As you open source schema windows they are listed in the Window menu so that you choose an open schema from the menu to navigate to it.
Help Menu | Provides online documentation for the Data View Builder. Note: For this release Liquid Data, the online help for the Data View Builder simply links into the main topics in online documentation for the Data View Builder.

2. Toolbar for the Design Tab

The toolbar, located directly below the menus, provides shortcuts to a subset of commonly used actions also available from the menus.

Figure 2-3 Toolbar

3. Builder Toolbar

The Builder Toolbar includes two subtabs:

- Sources Tab—Provides access to the XML schema representations for data sources configured in the Liquid Data server. This is where you can get source schema windows for a data source.

- Toolbox Tab—Provides access to functions, constants, query parameters, and other components used in query design.

Sources Tab

The Sources tab on the Builder Toolbar contains the data sources configured on the Liquid Data Server to which you are connected. Note that a data source type only shows up as a button on the Builder Toolbar if it has been configured in the Server to which you are connecting.

- Relational Databases

- XML Files

- Web Services

- Application Views (defined with the Application Integration)

- Data Views

Note: For a detailed introduction to these data sources, see Different Kinds of Data Sources in Overview and Key Concepts.

To open a schema for a data source, click on the data source type (for example Relational Databases) to get a list of configured data sources of that type. Then double-click on the particular data source you want to work with The schema window for that source is displayed in a movable window on the desktop.

Figure 2-4 Builder Toolbar: Sources Tab

Toolbox Tab

The Toolbox tab on the Builder Toolbar provides the following tools to use in query construction:

- Functions (information on The Function Editor is included here)

- Custom Functions (included with Functions in a custom grouping you define)

- Constants

- Query Parameters: Defining

- Components

Note: Any custom functions configured in the Liquid Data Server through the WebLogic Server Administration Console will show up on the Builder Toolbar on the Functions panel along with the standard functions provided.

Figure 2-5 Builder Toolbar: Toolbox Tab

Functions

Functions are built-in code modules that return a value when they run. The Functions panel provides a library of standard W3C functions compliant with the W3C XQuery 1.0 and XPath 2.0 Functions and Operators specification. (See Figure 2-5 for an example of the Functions panel on the Builder Toolbar Toolbox tab.)

In Data View Builder, the Functions are displayed in the Builder Toolbar on the Toolbox tab Functions panel by category names like Aggregate Functions, Boolean Functions, Operator Functions, and so on. To view all the functions in a category or group, expand the group node.

You can double click or drag and drop a function object to the desktop where it appears in a tree format showing the number and type of parameters required.

A copy of any mapped function saves automatically with the project when you close it. The saved function (with associated parameters) appears in the Components panel when you reopen the project. If you do not map the new function and you terminate the session, Data View Builder discards it and it does not appear in the Components panel.

Each function has a specification for required parameters and expected behavior. Some functions cannot be used in the work area, but must appear only on the desktop. For complete information about each function, its parameters, and expected behavior, see Functions Reference. For more detailed information, see the W3C XQuery 1.0 and XPath 2.0 Functions and Operators specification.

The Function Editor

The functions editor gives you a space to create functions using drag-and-drop and to view existing functions in your project.

Figure 2-6 Function Editor

There are two ways to open the Functions Editor:

- When you drag and drop a function into the work area the Function Editor is displayed with the chosen function and anticipates the equation with placeholder values (for example anyValue1 eq anyValue2).

- You can open the Functions Editor to view or modify an existing function by selecting a condition in a particular row and then clicking the edit button.

Figure 2-7 Click Edit Button to Get the Functions Editor

Click Close to close the Functions Editor.

Custom Functions

If you have custom functions configured through the Administration Console, these will show up in the Data View Builder on the Toolbar Functions tree in a custom group. The name of the group is what you specify in the "presentation group" element in the custom functions library definition (.CFLD) file. If no grouping label is specified "Ungrouped". For more information on this, see "Contents of a CFLD File" and "Structure of a CFLD File" in Using Custom Functions in Invoking Queries Programmatically.

Constants

You can use the Constants panel to create function parameters with constant values.

Figure 2-8 Builder Toolbar: Toolbox Tab: Constants

Choose the type of constant based on how you want the data to be considered in the query. Strings are alphanumeric values that typically contain alphabetic letters, special characters, and digits used in non-numeric comparisons. Names, zip codes, phone numbers, and street addresses are typical examples of string values.

Numbers can be integers (positive or negative), decimal values, or floating point expressions. The Empty element enables you to force an element to appear in the query. We expect mapped data elements to appear in the query result, but you may wish to see other data elements appear that are not mapped. If you drag and drop the Empty element onto a node, that node will appear in the query result.

To include a String, Number, or Empty element constant as a function parameter, follow steps similar to those shown in this example:

1. Drag an appropriate function to a row on the Condition tab or to the desktop. For example: choose the startswith function. You get the following placeholder in the Functions Editor:

   >     xf:starts-with(str1,str2)

2. Drag an appropriate source node onto the first string placeholder (str1). For example, choose CustomerID from a source schema.

3. Type a value in the String constant text box. For example, CUS. Drag the Constants icon onto the second string placeholder (str2).

   The condition appears in the Functions Editor as shown in the following figure.

   Figure 2-9 Condition with starts-with Constant in Functions Editor

   Close the Functions Editor by clicking the Close button. The new condition you created is also now displayed in the Source column on the Condition tab.

   Figure 2-10 Condition with starts-with Constant in Row on Conditions Tab

Note: If you design a query with a constant, and then design another query using a query parameter that specifies exactly the same value, the generated XQuery translation is different even though the functionality in each query is exactly the same.

Query Parameters: Defining

Query parameters can be strings, integers, floating point numbers, boolean expressions, or date and time types. They are variables that you define with no static value. On the Test tab, you can supply a different value each time you run the query (see 4. Query Parameters: Submitted at Query Runtime).

The Query Parameter bar has a text box where you can enter a new parameter value to be stored.

- Type a value that is one of the four supported types of parameters and click the drop-down list to select the type of parameter.

- Click Add to save it to the Query Parameter resource tree.

The parameters you add are added to the tree in the Query Parameters panel.

Figure 2-11 Builder Toolbar: Toolbox Tab: Query Parameters

You can invoke these variables when you build conditions. The following table shows examples of supported data type values.

Table 2-2 Query Parameter Types

Parameter Type | Examples
--- | ---
Boolean (xs:boolean) | Boolean expressions test true or false. You can specify that the Boolean Query Parameter has an implicit definition of True or False, then use it as query resource.
Byte (xs:byte) | A positive or negative whole number. The maximum value is 127 and the minimum value is -128. For example: -1 0 126 +100
Date (xs:date) | Input must be in this format: MMM dd, YYYY For example: JUN 12, 2002
Date and Time (xs:dateTime) | Input must be in this format: MMM dd, YYYY HH:MM:SS AM/PM For example: MAY 12, 2002 12:12:11 AM
Decimal (xs:decimal) | A precise real number (negative or positive) that can contain a fractional part. If the fractional part is zero, the period and following zero(s) can be omitted. For example: -1.23 12678967.543233 +100000.00 210.
Double (xs:double) | A real number (negative or positive) that can contain fractional part. For example: 3.159 Liquid Data does not support floating point formats expressed in fractions (½) or IEEE floating point notation (3E-5).
Floating Point (xs:float) | A real number (negative or positive) that can contain a fractional part. For example: 100.0 -100.5 Liquid Data does not support floating point formats expressed in fractions (½) or IEEE floating point notation (3E-5).
Int (xs:int) | A positive or negative whole number. The maximum value is 2147483647 and minimum value is -2147483648. For example: -1 0 126789675 +100000
Integer (xs:integer) | A positive or negative whole number. The maximum value is 2147483647 and minimum value is -2147483648. For example: 1 -100 +100
Long (xs:long) | A positive or negative whole number. The maximum value is 9223372036854775807 and minimum value is -9223372036854775808. For example: -1 0 12678967543233 +100000
Short (xs:short) | A positive or negative whole number. The maximum value is 32767 and minimum is -32768. For example: -1 0 126789 +10000
String (xs:string) | An alphanumeric expression such as: Smith Jones 12345 State St. Note: An unspecified value for a query parameter of type String is considered an empty string.
Time (xs:time) | Input must be in this format: HH:MM:SS AM/PM For example: 01:02:15 AM

You can also do one of the following:

- Right-click a parent node and click Expand to show all child nodes.

- Right-click a child node and click Delete or Rename to complete these tasks.

You can drag and drop a node from an input resource file to an empty row in the work area and then drag and drop a query parameter from the Query Parameter resource tree to specify a condition for the query.

Note: If you design a query with a constant, and then design another query using a query parameter, the generated XQuery translation is different even though the functionality in each query is exactly the same.

Components

The Components panel shows the structure of the current project in Design View. All elements of the query, except the target schema appear in this view of the project, including any data source schemas you are using or functions that you map with parameters.

Figure 2-12 Builder Toolbar: Toolbox Tab: Components

Any component that appears in this panel can be minimized on the desktop by double clicking the appropriate node. Click again and the component reappears on the desktop. The target schema does not appear in the Components panel because you cannot close it while working on the project.

When you save a project by name and reopen it, the project components appear in this window, but minimized on the desktop. You can move them to the desktop by double clicking a selected component. When you reopen a saved project, the output schema appears directly on the desktop instead of in the Components tree.

You can right-click any parent node and click Edit, Delete, or Rename to complete those tasks.

4. Source Schemas

Source schema windows show XML schema representations of the structure of the data in the selected data source. Used to create source conditions and mappings to a target schema. You can have multiple data source schemas open on the desktop as needed.

Note: For a detailed description of the special characters used to identify characteristics of schema nodes, see Special Characters: Occurrence Indicators.

To open a schema for a data source:

1. Click on the Sources tab on the Builder Toolbar (if the Sources tab is not already showing).

2. Click on the data source type (for example Relational Databases) to get a list of configured data sources of that type.

3. Double-click on the particular data source you want to work with.

   The schema window for that source is displayed in a movable window on the desktop.

   Figure 2-13 Source Schemas

5. Target Schema

The Target Schema window shows the XML schema representation for the structure of the target data (query result).

Only one target schema per project is allowed. If you have a target schema open and decide to choose another, the current target schema is closed and the new one replaces it.

Note: For a detailed description of the special characters used to identify characteristics of schema nodes, see Special Characters: Occurrence Indicators.

To open and set a target schema for a project:

1. Choose the menu item File—>Set Target Schema.

   This brings up a file browser.

2. Navigate to the schema you want to use, select the file and click Open in the file browser.

   The target schema is displayed as a docked on the right side of the Design tab.

(You can also choose the menu item File—>Set Selected Source Schema as Target Schema to add a source schema selected on the Builder Toolbar as the target schema.)

Figure 2-14 Target Schema

6. Conditions Tab

The Conditions tab shows:

- In Basic mode, conditions filtering) defined for the source data (see Conditions)

- In Advanced mode, conditions (filtering) defined to force Scope for the target data or query result (see Advanced View for Defining Explicit Scope for Conditions)

The Conditions area functions both as a tracking and reflection tool, and as a workspace that you can manipulate directly. Whenever you do a drag-and-drop operation that causes an update to Conditions, the Conditions tab is automatically displayed.

Figure 2-15 Conditions Tab on the Design tab

Conditions

The Conditions section shows conditions (filters) for source data. As you build up the query by creating drag-and-drop source-to-source node relationships among data source schemas, the implied condition statements are recorded and reflected as joins under the Conditions. Even if you don't drag and drop anything directly into the Conditions tab, you will see the appropriate conditions building up here as a result of your work with the source schemas. (When you drag and drop a source element onto another source element, the equals function is used by default to create a simple join.)

Figure 2-16 Conditions Tab in Basic View

You can also use the Conditions area as a workspace to explicitly drag-and-drop elements of a query statement into the rows under Conditions to build up the query. You can drag-and-drop elements and attributes from source schemas as well as functions, constants, and parameters from the Builder Toolbar "Toolbox" tab directly into the rows under Conditions to craft conditions statements.

This tab includes the following features to facilitate working with conditions:

- Function Editor—To edit an existing condition, select it and click on the Function Editor. You can also drag and drop a function from the Functions panel on the Toolbox panel into an empty row on the Conditions tab. For more about working with the Function Editor, see Functions and The Function Editor.

- Trashcan for Deleting Conditions—To remove a condition, select the row that contains the condition you want to remove and click the trashcan.

- Enabled/Disabled Toggle—For each condition you can use the Enabled/Disabled toggle to include the selected condition in the query or disable it. Select the row that contains the condition you want to enable or disable and then click the Enabled/Disabled toggle for that condition. When a condition is disabled, it will not be used to generate the XQuery. When a condition is enabled it will be included when the XQuery is generated.

Advanced View for Defining Explicit Scope for Conditions

When you click the "Advanced View" toggle, the Conditions tab displays a column for defining explicit scope for each condition.

Figure 2-17 Conditions Tab in Advanced View Showing Explicit Scope

The Scope area on the Conditions tab shows any explicit narrowing conditions (filters) you define for the target data to refine the query result. In basic mode (with Advanced toggle off) Data View Builder creates queries based on the scope implied by the source conditions you create and the structure of the target schema (implicit scope). Another words, by default the implicit scope is auto-generated by the Data View Builder. The auto-generated, implicit scope should be sufficient for most cases. However, there may be situations in which you want to control scoping explicitly. In these cases, you can switch to the Advanced view.

A scope setting affects the placement of a where clause in the XQuery generation. The Data View Builder best guess at implicit scope will satisfy most cases, and you will generally not have to specify scope. For cases where you need to explicitly define scope to force the where clause to the right place in the query or sometimes to force it to be there at all, you can do this directly by dragging the appropriate node in the target schema into a row under Scope.

For more information and examples about when and how to set scope, see Understanding Scope in Basic and Advanced Views in Designing Queries.

Returning to Basic View (Automated Scope)

When you toggle Advanced View off (no X showing next to Advanced View), Data View Builder returns to automatic scoping mode and discards the changes you made in manual mode. The Current Scope text box and the Targets column disappear.

7. Mappings Tab

The Mappings tab shows source-to-target mappings that will define the structure of the query result. As you drag-and-drop source elements onto target elements among the schema windows, the Mappings tab records these relationships, which build up the shape the data will take in the query result. For example, dragging and dropping FIRST_NAME and LAST_NAME elements from CUSTOMER in a source schema to the associated CUSTOMER elements in the target schema specifies that in the query result customers will be identified with first and last names as defined.

Whenever you do a drag-and-drop operation that causes an update to Mappings, the Mappings tab is automatically displayed.

Figure 2-18 Mappings Tab

Deleting a Mapping

To delete a mapping, select the row on the Mappings tab that contains the source-to-target mapping you want to delete (selected mapping is highlighted) and click the trashcan.

8. Sort By Tab

The Sort By tab specifies how the result should be ordered and a list of candidate nodes that you can order. Figure 2-19 shows the order of a repeatable node segment of the target schema. The drop-down list shows all repeatable data nodes in the target schema marked with an asterisk (*) or a plus sign (+). A repeatable node is the parent of child nodes that can appear in the query result once for every instance of a match. A repeatable node is an ancestor to one or more nodes that will represent unique data returned by the query.

The blue arrows move rows up and down. These icons are enabled only when you select a data item that can move up or down. The drop-down list shows the repeatable nodes with subordinate nodes that can be sorted. When you select a repeatable node from the drop-down list, the associated child nodes appear in the Sort By list. Move these child nodes up or down to specify how the result should be sorted. For example, a Customer* element can be sorted first by Last_name and then by First_name by having the Last_name row at the top and the First_name row directly beneath it.

An item can be moved if it is assigned an ascending or descending attribute in the source schema. (The database administrator or data architect who creates the source schema specifies this.) Items with ascending or descending attributes can be moved up only if there is another item above, and they can be moved down only if the next item down also has an ascending or descending attribute.

Figure 2-19 Sort By Tab

9. Status Bar

The Status Bar is a horizontal bar at the bottom of the Data View Builder that provides status information about current actions and processes.

Figure 2-20 Status Bar

Optimize Tab

The Optimize tab is where you can optionally add more information such as "hints" to data sources to improve query performance.

The following sections describe the features available on the Optimize tab.

- Overview Picture of Optimize Tab Components

- 1. Source Order Optimization

- 2. Join Pair Hints

Overview Picture of Optimize Tab Components

The following figure and accompanying sections describe the components on the Optimize tab. (Click the tab to access it.)

Figure 2-21 Optimize Tab

Note: The Optimize tab contains a subset of the menu options and toolbar buttons available on the Design tab. For a full description of these options, see 1. Menu Bar for the Design Tab and 2. Toolbar for the Design Tab.

1. Source Order Optimization

You can re-order source schemas on the top frame on the Optimize tab to improve query performance. To move a schema up or down, select the schema and click the up or down arrow buttons to the right of the list of schemas.

When a query uses data from two sources, the Liquid Data Server brings the two data sources into memory and creates an intermediate result (cross-product) using the two sources. If you specify more than two sources, the Liquid Data Server creates a cross-product of the first two sources, then continues to integrate each additional resource, one at a time, in the order that they appear in FOR clauses. The intermediate result grows with each integration, until all sources are accounted for.

The size of a source is the number of tuples, or records, used in the query from that source. The size of the intermediate result depends on the input size of the first source multiplied by the input size of the second source and so on. A query is generally more efficient when it minimizes the size of intermediate results. You can re-order source schemas in certain situations to improve performance.

For detailed information on how to optimize a query by ordering source schemas, see Optimizing Queries.

2. Join Pair Hints

A query hint is a way to supply more information to the Liquid Data Server about the amount of data each source contains when processing a query. The Join Hints frame contains a drop-down list of data source pairs, and a table that shows all the joins for each pair. Only source pairs that have join conditions across them appear in the drop-down list. For each join condition in the table, you can provide a hint about how to join the data most efficiently.

For detailed information on how to optimize a query by using optimization hints, see Optimizing Queries.

Test Tab

The Test tab is where you view the generated XQuery language interpretation of the query elements you developed on the Design and Optimize tabs, and run the query against your data sources to verify the result and evaluate performance.

From this view, you can provide different parameters to the query before you run it.

The following sections describe the features available on the Test tab.

- Overview Picture of Test Tab Components

- 1. Menu Bar for the Test Tab

- 2. Toolbar for the Test Tab

- 3. Builder-Generated XQuery

- 4. Query Parameters: Submitted at Query Runtime

- 6. Run Query

- 7. Result of a Query

Overview Picture of Test Tab Components

The following figure and accompanying sections describe the components on the Test tab. (Click the tab to access it.)

Figure 2-22 Test Tab

1. Menu Bar for the Test Tab

Table 2-3 Menu Bar for the Test Tab

Menu | Description of Menu Options
--- | ---
File Menu | Provides most of the same options as shown on the Design tab menu bar with one additional menu option as follows: Save Query—Saves the current query to a file you specify. The file must be saved with a .xq extension. (If you do not add a .xq extension, Data View Builder will append it automatically.) If the query is saved into the stored_queries folder in the Liquid Data server Repository, it is considered a stored query in Liquid Data. For more details on saving a query, see Saving a Query in Testing Queries. For a description of the other File menu items available from the Test tab (which are a subset of those on the File menu for the Design tab), see Table 2-1 in Design Tab
Query Menu | Provides the following options related to running a query: Run Query—Runs the query. (See 6. Run Query) Stop Query Execution—Stops a running query. (See Stopping a Running Query.) The Query menu options for Automatic Type Casting and Condition Targets—>Advanced View are more relevant to designing a query and, therefore, are described in 1. Menu Bar for the Design Tab.

2. Toolbar for the Test Tab

The toolbar, located directly below the menus, provides shortcuts to a subset of commonly used actions also available from the menus.

Figure 2-23 Toolbar on the Test Tab

3. Builder-Generated XQuery

The query you developed on the Design and Optimize tabs is shown in XQuery language in the "Query" window on the upper left panel on the Test tab.

Figure 2-24 Builder-Generated XQuery Shown in Query Window

4. Query Parameters: Submitted at Query Runtime

You can use the Query Parameters panel to add variable values to a query each time you run it. The list of variables depends on the number of variables you defined as Query Parameters on the Design tab (see Query Parameters: Defining) and which ones appear as one or more function parameters.

Figure 2-25 Query Parameters Settings on Test Tab

5. Query Results - Large Results

If you anticipate a large set of data coming back in the query result, click Large Results (an X in the box indicates this feature is on). The default is off (no X).

When this option is on, Liquid Data uses swap files to temporarily store results on disk in order to prevent an out-of-memory error when the query is run.

Figure 2-26 Specifying Large Results

6. Run Query

To run a query, click the Run Query button on the toolbar in the upper left of the Test tab. (You can also choose the Run Query option from the Query menu.)

Figure 2-27 Click the "Run Query" Button to Run the Query

The query is run against your data sources and the result is displayed in the Results panel in XML format.

Stopping a Running Query

You can stop a running query before it has finished processing by clicking the Stop Query Execution button in the toolbar. (You can also choose the Stop Query option from the Query menu.)

Figure 2-28 Click the "Stop Query Execution Button" to Stop a Running Query

7. Result of a Query

When you run a query, the result is displayed in the Results window on the Test tab in XML format.

Figure 2-29 Query Result is Shown on Test Tab When Query is Run

Working With Projects

It is a good practice to save the project file immediately once you have chosen and set up a target schema, and started creating conditions and mappings for a query. Save frequently or after you make a significant change to avoid losing your work. To save the project for the first time.

To save a project choose File—>Save Project or File—>Save Project As from the menus (or click the "Save the project" toolbar button). Data View Builder projects are saved with a .qpr filename extension. (For a complete description of options available for handling projects, see Table 2-1 in 1. Menu Bar for the Design Tab.

To Make a Project Portable, Save Target Schema to Repository

For the project to be portable so that other users can open the project and use it, the target schema must be saved to the Liquid Data server repository on the server where the project will be used.

Saving a Project is Not the Same as Saving a Query

Please keep in mind that "saving a project" is not the same as "saving a query". Saving a project creates a Data View Builder .qpr file that includes the conditions and mappings for source and target schemas used in a particular query. You can re-open any project in the Data View Builder, modify the conditions and mappings on the XML schemas, and re-optimize or re-run the query from within the Builder tool.

However, saving a project does not make the query in that project available as a stored query in Liquid Data. To create a stored query, you need to use the Save Query option on the Test tab. For more information on saving a query, see Saving a Query in Testing Queries.

Special Characters: Occurrence Indicators

The Data View Builder uses a set of special characters (occurrence indicators) to indicate the number of items in a sequence. Occurrence indicators are generally used to specify characteristics for elements or attributes in schemas, but are also found elsewhere in the Builder user interface (UI) where they are needed to specify occurrence characteristics. You can apply these characteristics to elements and attributes of schemas that you build or modify by accessing the right-mouse click pop-up menu on schema nodes.

Table 2-4 Occurrence Indicators in Data View Builder

Character | Description
--- | ---
Question mark (?) | Indicates zero items or one single item. The item is optional and does not have to be included or mapped.
Asterisk (*) | Indicates zero or more items. This item is optional and multiple occurrences of it are allowed.
Plus sign (+) | Indicates one or more items. This is a required element of which multiple occurrences are allowed.

Next Steps: Building and Testing Sample Queries

If you have not already done so, we suggest working through the steps in Getting Started, which takes you through the basic tasks of configuring some data sources and using the Data View Builder to design a query using the Order Query example from our Avitek Sample. (For more information about the Avitek Sample and other samples, see the Samples introduction page.) Working through the Getting Started (or even reading through the steps related specifically to using the Data View Builder) is an easy, hands-on way to get familiar with working with schema representations of data sources and using the basic query-building tools, task flow, and workspaces in the Data View Builder.

If you have already worked through the Getting Started topic or if you are ready to get started on building some other basic queries, we suggest you skip to the following topics in this document:

- Examples of Simple Queries (at the end of Designing Queries) provides two example queries that provide practice in some basic techniques such as creating join conditions, using functions, setting scope of the target, using the sort-by feature to specify the order of the result, and running queries.

- Query Cookbook provides several examples of complex queries using more advanced features and functions such as creating unions, using date and time functions, using aggregate functions, using hints to optimize queries, and using data views in queries.