Skip navigation.
Downloads | Product Documentation | Support

Building Queries and Data Views

# Data View Builder GUI Reference

This chapter provides a graphical interface reference for the Data View Builder, including menus and other visual components used in accessing data sources, target XML schemas, query parameters, constants, XQuery functions and other features that are used in designing, optimizing, testing, and deploying a Builder-generated query and saving any resulting projects.

The following topics are covered:

- Starting the Data View Builder
- Data View Builder GUI Tour

- Design Tab
- Optimize Tab
- Test Tab

- Working With Liquid Data Projects
- Next Steps: Building and Testing Sample Queries

# Starting the Data View Builder

Note: The Liquid Data Getting Started guide contains detailed instructions on starting and using the Data View Builder to create a sample query and then use that query in a WebLogic Workshop application.

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

1. Start the Data View Builder.

- On a Windows platform, choose the menu item:
  Star t —> Programs —> BEA WebLogic Platform 8.1 —> BEA Liquid Data for WebLogic 8.1 —> 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 where your data sources are located. Initially you may want to connect to the Liquid Data Samples server. See the Liquid Data Getting Started guide for details.

1. The username and password for the Data View Builder is specified in the WebLogic Server (WLS) Compatibility Security via the Liquid Data node of the WebLogic Administration Console for the 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 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 the query, respectively. Some queries benefit from optimization, available 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 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 numerically-coded sections describe the components on the Design tab.

Figure 2-2 Design Tab

Note: Menus, horizontal shortcut toolbar and status bar are also covered in detail in this section. Although most menu options and shortcuts are available in all modes, others are mode specific and described in the appropriate section.

### 1. Menu Bar for the Design Tab

The menus provide File, Schema, View, and Window menus as detailed inTable 2-3.

Table 2-3 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, see Working With Liquid Data Projects.) Connect... Resets your connection to a Liquid Data Server. Choosing this command closes any open projects or schemas. New Project. Creates a new project. If you choose this option when you have an unsaved project in the workspace you are given the option to first save your current work to a project. If you choose not to save, any previously generated query and associated conditions and schema mappings will be lost. Open Project. Opens an existing project that you specify through the file browser. Close Project. Closes the current project. If you have not saved your work, you are given an opportunity to do so. Open Query. Opens an existing saved query. When you open a saved query, you only see the Test Tab; the Design and Optimize tabs are not available. You can then edit, run, and save the query. Save Project. Saves the current project. Data View Builder projects are saved with a `.qpr` filename extension and may be saved to any directory. Save Project As. Saves the current project under a different file name. Add Selected Schema. Adds/opens the source schema that is selected in the Builder Toolbar to the current project. This is the same as dragging a data source schema into the work area. Set Target Schema. Brings up a file browser from which you can select a schema file from your local system, a network drive, or a 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 from the list of data sources (Builder Toolbar) to be set as the target schema in the current project. (A right-click short-cut "Set as target schema" is also available when you click on a data source.) Save Target Schema. Saves the current target schema to the Liquid Data repository or to a folder location and filename you choose. If you choose Repository when saving a target schema, a relative path to the file is saved in the project file. This makes the target schema available to other Liquid Data users and servers. If you save a target schema to a local file, the fully qualified path is saved in the project file, making the schema accessible only on the local machine. Save Query. For a description of this option, see Table 2-18. Exit. Closes the Data View Builder application.
Edit Menu | Provides standard edit features. Availability of these commands is based on previous actions you may have takes and what item is selected. For example, if you highlight an element in a target schema and select Delete, the highlighted element will be deleted. Cut Copy Paste Delete Select All
View Menu | As an alternative to using the Design mode tabs the View menu provides a means for you to 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 attach notes to particular queries. Data Types. Toggle to show/hide data types for all source and target elements 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. Lines. Includes a submenu of options to show: all lines between data sources and your target schema no lines only lines of a selected data source If the Show lines option is enabled and you highlight a schema element that is mapped to a target schema (or highlight a target schema element), a dashed yellow line will show the correction and the names of the elements will be highlighted. Lines are drawn only for mappings where the source and target elements are both visible. A solid gray lines represents a mapping from a source element whose containing window is in the background on the desktop.
Query Menu | Compile Query. Compiles the current query without executing it. This is particularly useful when trying to validate large queries. If you do not see an error message after running Compile Query, it means that your query has compiled successfully and can be run at your convenience.The Compile Query option can also be accessed through a button on the menu bar. After you compile a query it will be cached. The query will be recompiled if it does not exactly match the text in the cache. Run Query. Runs the current query. (See Table ) Stop Query Execution. Stops a running query. (See Table .) Allow Existential Condition Generation. Toggle to turn existential condition generation on or off. A checkmark next to this option indicates that existential condition generation is on. For more information see Using Existential Condition Checking in Queries. Automatic Type Casting. Toggle to turn automatic type casting on or off. A checkmark next to this option indicates that automatic type casting is on. For more information see Using Automatic Type Casting. Automatic Treat-as. Toggle to turn automatic treat-as on or off. A checkmark next to this option indicates that automatic treat-as is on. When automatic treat-as is on, `treat` functions are automatically placed in the query whenever there is a type mismatch. For details on the treat functions, see Treat Functions in the Functions Reference section of the XQuery Reference Guide. Condition Targets —> Advanced View. Toggle to turn Advanced View for manual scoping on/off. For more information on using scoping in Advanced View see Managing Target Schema Properties. Target Namespace. Opens a dialog box where you can enter a prefix and URI for the target schema. For a description of the other options in the Query menu (Compile Query, Run Query, or Stop Query Execution) that are relevant only for running/testing a query, see Table 2-3.
Window Menu | The Window menu provides various options for window management such as next, previous, close, and close all. Source schema windows that you open are listed in the Window menu.
Help Menu | Provides links to Data View Builder online documentation.

### 2. Toolbar for the Design Tab

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

Figure 2-4 Toolbar

### 3. Builder Toolbar

The Builder Toolbar includes two subtabs:

- Sources. 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. 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 Liquid Data Server to which you are connecting. Potentially available data sources include:

- XML Files
- Delimited Files
- Web Services
- Application Views
- Data Views
- SQL Calls
- Delimited Files

Note: For a detailed introduction to Liquid Data data sources, see Data Sources. See also Schemas and Namespaces in Liquid Data, for details on using data source schemas in constructing queries.

Figure 2-5 Builder Toolbar: Sources Tab

#### Toolbox Tab

The Toolbox tab on the Builder Toolbar provides the following tools you can use in constructing and tailoring your query:

- XQuery Functions (information on the Function Editor is included here)
- Custom Functions
- Constants
- Query Parameters
- Complex Parameter Types
- Components

Figure 2-6 Builder Toolbar: Toolbox Tab

#### XQuery Functions

XQuery Functions are built-in code modules that return a value when they run. The XQuery 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-6, Builder Toolbar: Toolbox Tab, on page 2-13 for an example of the Functions panel.)

In the Data View Builder, Functions are displayed in the Builder Toolbar on the Toolbox tab XQuery Functions panel by category names such as Aggregate Functions, Boolean Functions, Cast Functions, and so on. To view all the functions in a category or group, expand the group element. For details on using XQuery functions see Using XQuery Functions.

#### Function Editor

The functions editor provides the ability to create functions using drag-and-drop and to view existing functions in your project.

Figure 2-7 Function Editor

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-8 Button to Access the Functions Editor

For details see Using the Function Editor.

#### Custom Functions

If you have custom functions configured through the Liquid Data node of the WebLogic Administration Console, these will appear in the Custom Functions section of the Data View Builder toolbar. For details on creating queries by using custom functions, see Using Custom Functions in the Application Developer's Guide.

#### Constants

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

Figure 2-9 Setting Constants Dialog Box

For details see Creating and Using Constants.

#### Query Parameters

You can create named query parameters and associate them with a data type. For details see Creating and Using Query Parameters.

#### Complex Parameter Types

If you have complex parameter types configured through the WebLogic Administration Console, these will appear in the Data View Builder on the Toolbar Functions tree under Complex Parameter Types. For more information, see Using Complex Parameter Types in Queries and Configuring Access to Complex Parameter Types in the Administration Guide.

#### 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.

If a particular component schema is unavailable when a project is re-opened, the schema will still be listed, but it will be flagged as unavailable (off-line) and a red mark will appear over the schema name.

Figure 2-10 Builder Toolbar: Toolbox Tab: Components

Any component that appears in this panel can be minimized on the Liquid Data desktop by double- clicking the appropriate node. Click again and the component reappears on the desktop.

You can hide the Builder Toolbar using a checkbox located under View —-> Toolbars.

### 4. Source Schemas

Source schema windows show XML schema representations of the structure of the data in the selected data source. Source schemas are used in creating conditions and mappings to a target XML schema. You can have as many data source schemas open on the Liquid Data desktop as needed.

Figure 2-11 Sample Source Schemas

### 5. Target Schema

The Target Schema window shows the XML schema representation for the structure of the target data (query result). For additional information see Source and Target Schemas.

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-12 Target Schema

The Target Schema can be hidden using a checkbox in View —> Panels.

### 6. Conditions Tab

The Conditions tab shows:

- In Basic mode, conditions defined for the source data (see Conditions Section)
- In Advanced mode, conditions defined that potentially define Scope for the target data or query result (see Advanced View (Setting Condition Scope Manually))

The Conditions area lists underlying query conditions that can inspect or change. Whenever you do a drag-and-drop operation that changes query conditions, the Conditions tab is automatically updated and displayed.

The Conditions tab includes the following features:

- Conditions Section. List of conditions (filters) that can optionally be applied when the query is generated.
- Function editor. To edit an existing condition, select it and click on the Function editor icon, to the right of the Trashcan. You can also access the Functions editor by dragging and dropping a function from the Functions panel on the Toolbox panel into an empty Conditions row. See also XQuery Functions and Function Editor.
- Trashcan. To remove a condition, select the row that contains the condition you want to remove and click the Trashcan.
- Enabled checkbox. Each query condition can be enabled (or disabled) using an Enabled checkbox. By default all conditions are enabled. To disable a condition click the checkbox.

Disabled conditions are not part of the query.

Figure 2-13 Conditions Tab on the Design tab

#### Conditions Section

The Conditions section displays conditions for source data. As you build up the query by creating drag-and-drop source-to-source element relationships among data source schemas, the implied condition statements are recorded and reflected as equality joins (eq) under the Conditions.

Figure 2-14 Conditions Tab in Basic View

For details on using the query Conditions section in basic and Advanced View mode see Managing Target Schema Properties on page 5-26.

### 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.

A checkbox below the list of query conditions allows you to optionally show or hide the full path to the mapping elements.

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

Figure 2-15 Mappings Tab

The Conditions Tab can be hidden using a checkbox in View —> Panels.

### 8. Sort By Tab

Target schema elements associated with complex elements with the repeatable attribute set can be sorted in ascending or descending order. In addition, the order that elements are sorted can be easily changed. See Sorting Query Results for details.

### 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. The Status Bar can optionally be hidden using a checkbox in View —> Panels.

Figure 2-16 Status Bar

## Optimize Tab

Use the Optimize tab to add clarifying hints to improve query performance.

Figure 2-17 Optimize Tab

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

## Test Tab

The Test tab is where you view the generated XQuery from the query elements you developed on the Design and Optimize tabs. From this view, you can provide different parameters to the query before you run it.The following sections (numerically keyed to Figure 2-1, Data View Builder Test Mode, on page 2-24) describe the graphical features available on the Test tab:

1. Menu Bar for the Test Tab

2. Toolbar for the Test Tab

3. Builder-Generated XQuery

4. Query Parameters: Submitted at Query Runtime

5. Query Results - Large Results

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-1 Data View Builder Test Mode

### 1. Menu Bar for the Test Tab

Table 2-18 Menu Bar for the Test Tab

Menu | Description of Menu Options
--- | ---
File Menu | Many of the File menu commands available in Test mode, including: Connect... New Project Open Project Open Query Save Query Exit For a complete description of File menu items, including the above, see Menu Bar for the Design Tab.
Edit Menu | Provides standard edit features. Cut Copy Paste Delete Select All For a complete description of File menu items, including the above, see Menu Bar for the Design Tab.
View Menu | As an alternative to using the tabs the View menu lets you navigate to the following UI views. For a complete description of View menu items, including the above, see Menu Bar for the Design Tab.
Query Menu | Provides the following options related to running a query: Compile Query. Compiles the current query without executing it. This is particularly useful when trying to validate large queries. If you do not see an error message after running Compile Query, it means that your query has compiled successfully and is ready to be run.The Compile Query option can also be accessed through a button on the menu bar. Run Query. Runs the query. (See 6. Run Query) Stop Query Execution. Stops a running query. (See Stopping a Running Query.) Deploy Query... Stores the current query with its target schema in the `stored_query` directory. Options allow simultaneous deployment as a data view. See Deploying Your Query. Note: If Liquid Data security is enabled, you must log into the Data View Builder as a user who is a member of either the LDConsoleUsers or LDAdministrators group. If the user is not a member of one of these groups, attempts to deploy a query will fail with a security error. The Query menu options for Automatic Type Casting and Condition Targets—>Advanced View are described in 1. Menu Bar for the Design Tab.
Window Menu | The Window menu provides various options for window management such as next, previous, close, and close all. 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 links to online documentation for the Data View Builder.

### 2. Toolbar for the Test Tab

The toolbar, located directly below the menus, provides shortcuts to commonly used actions also available from the menus in addition to Undo and Redo commands.

Figure 2-19 Test Tab Toolbar Icons

### 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-20 Builder-Generated XQuery Shown in Query Window

### 4. Query Parameters: Submitted at Query Runtime

You can use the Query Parameters panel (located below the Query area) to change 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 (see Creating and Using Query Parameters).

Figure 2-21 Query Parameters Settings on Test Tab

Note: Complex Parameter Type data sources are also identified in the Query Parameter Settings area. For more information, see Using Complex Parameter Types in Queries and Configuring Access to Complex Parameter Types in the Administration Guide.

### 5. Query Results - Large Results

If you anticipate a large set of data coming back when the query is run, 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 errors.

Figure 2-22 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-23 Run Query Button

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 completed by clicking the Stop Query Execution button in the Toolbar. (Alternatively choose the Stop Query option from the Query menu.)

Figure 2-24 Stop Query Execution Button

### 7. Result of a Query

Query results are reported in several forms. By default, results appear in structure XML.You can also view the query plan and statistics on the query once it has been run. For details see Running, Saving, and Deploying Queries.

# Working With Liquid Data Projects

It is a good practice to save your project file frequently since it will allow you to immediately restore your query and the schemas and other relationships that were defined to create it.

To save a project choose File —> Save Project or File —> Save Project As 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 1. Menu Bar for the Design Tab.

Notes:

- 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. However, saving a project does not make the query in that project available as a stored query. For more information on stored queries see Using the stored_queries Folder.
- A copy of any mapped function is saved automatically with the project. The saved function (with associated parameters) appears in the Components panel when you reopen the project.
- If you are working with a project that was last saved under Liquid Data 8.1 SP1 or earlier, the Query menu's Allow Existential Condition Generation option will be selected. For more information see Using Existential Condition Checking in Queries.

## Using Schemas Saved With Projects

When you save a project, the schema definitions of all source and target schemas that you mapped in the project are saved. When you reopen the project, Data View Builder first looks for the schema definitions in the Liquid Data repository.

If a schema definition is unavailable, the schema definition saved in the project file is used. Data View Builder adds the schema to the list of available resources, but flags it as offline by putting a red mark over the schema name. A warning is also generated in the WebLogic Administration Console log that queries using this schema will not run.

Offline resources are available only to the previously associated project.

## Save Target Schema to Repository

In order for your project to be portable you should save your target schema to the Liquid Data Server repository on the server where the project will be used.

# Next Steps: Building and Testing Sample Queries

If you have not already done so, consider 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 an Order Query sample. (For more information about Liquid Data samples, see the Samples introduction page.) Working through the sample in Getting Started is a good, 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 are ready to get started on building some other basic queries see Liquid Data by Example. It provides examples of queries of 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.