Skip navigation.
Downloads | Product Documentation | Support

Building Queries and Data Views

# Schemas and Namespaces in Liquid Data

This chapter describes source and target XML schemas, also called target schemas, as used in the Data View Builder to define queries. It also describes how XML namespaces can be used in your queries.

The following topics are covered:

- Source and Target Schemas
- Schema Import Resolution Rules
- Using Schemas Saved With Projects
- Understanding XML Namespaces

# Source and Target Schemas

XML schemas are used in Liquid Data to represent the hierarchical structure of various data sets and the query structure. The Data View Builder uses XML schema representations as follows:

- Source Schemas. XML schemas that describe the structure of underlying source data.
- Target Schema. An XML schema that describes how the target data is to be structured; that is, the structure of the query result.

For relational databases accessed through JDBC drivers, a schema is automatically generated based on available metadata.

For XML files, views, complex parameter types (CPTs), stored procedures, delimited files, or web services, you first develop and then specify the schema using the WebLogic Administration Console.

Note: For the versions of the XQuery and XML specifications implemented in see Supported XQuery and XML Schema Versions In Liquid Data in the XQuery Reference Guide.

## Source Schemas

The Data View Builder provides graphical representation of source schemas in a tree structure format. The visual representations can be expanded and collapsed for convenience and readability.

Figure 4-1 Sample source schemas

If you are building a query that depends upon more than one data source, you will use multiple source schemas (one for each data source).

#### Searching Text in Schemas and Other Work Area Elements

You can apply a keyword search to any source or target schema, as well as to functions. Simply click the Open search icon at the top of the pane and a search field will appear. Enter any valid search string (case does not matter) and if it exists in the pane the string will be highlighted.

Wildcard symbols (? or *) are not allowed. However, any word or partial word will be found if it appears in the pane. For example, if you search on the string `TAT` the element `STATE` will be found it if exists in the pane.

Text search is circular beginning at the currently highlighted element. In other words, if the search will be satisfied by an element above the currently highlighted line it will eventually be found if you keep clicking the Search button.

### Using Source Schemas Multiple Times in Constructing Queries

In the Data View Builder you can use source schemas as many times as needed, simply by dragging an additional copy of the data source scheme into the work area.

A source is said to be replicated if the source schema appears multiple times in a query. In XQuery, a source is replicated if document_name appears multiple times in the XQuery, usually appearing in two different `for` clauses. Similarly, in SQL a source is said to be replicated if the source (table) appears twice in a `FROM` clause (or in two different `FROM` clauses).

Source replication is necessary whenever you want to use a data source in a way that will require iterating over the source twice. Another way to state this is when two different tuples from a source will be required at the same time.

#### When More Than a Single Copy of a Source Schema is Needed

Sometimes it is helpful to use more than one copy of a data source schema to improve query performance. In other cases, however, having more than one copy of a data source schema is necessary.

Take, for example, a very simple problem: you want to build a target schema that lists product list prices over a certain amount and under a certain amount. XQuery functions exist for the greater-than [`gt`] and less-than-or-equal-to [`le`] test conditions. Using Advanced view you could disable `where` clause conditions to make the query valid (see Sorting Query Results).

But a clearer and cleaner approach would be to use two source instances that each reference the same data source. From the first instance of the source schema, PB-BB, `PRODUCTS` would be projected under Expensive products. From the second instance, PB-BB2, `PRODUCTS` would be projected under Cheap products (Figure 5-34). In both cases, Copy and Paste and Map are used. (See Mapping to Target Schemas for more information on mapping of complex elements to target schemas.)

Figure 4-2 Project Illustrating Use of Two Copies of a Data Source Schema

Then it is a simple matter of creating the [`ge`]/[`lt`] conditions as described in To resolve this problem click Advanced view in the Conditions section. You will notice that instead of the two conditions you created, four are listed. This is because Advanced view shows you the actual where clause conditions used in the query, based on application of the Data View Builder best-guess autoscope rules..

The XQuery generated by this project (Listing 4-1) illustrates this approach.

Listing 4-1 XQuery returning product list prices in two groups

`<results>
<expensive_products>
{
for $PB_BB.PRODUCTS_15 in document("PB-BB")/db/PRODUCTS
where ($PB_BB.PRODUCTS_15/LIST_PRICE gt 100)
return
$PB_BB.PRODUCTS_15
}
</expensive_products>
<cheap_products>
{
for $PB_BB2.PRODUCTS_21 in document("PB-BB")/db/PRODUCTS
where ($PB_BB2.PRODUCTS_21/LIST_PRICE le 100)
return
$PB_BB2.PRODUCTS_21
}
</cheap_products>
</results>`

In the above query `PRODUCTS` with list prices greater than or equal to [`gt`] 100 are returned for the PB_BB data source. Similarly, `PRODUCTS` with list prices less than 100 are returned for the PB_BB2 data source. Of course the underlying data source is the same.

#### The Self-Join

Another example of necessary source replication would be a self-join in SQL. In the classic example of a self-join, the query retrieves all employee names that match a particular manager ID.

>     SELECT emp.name, mgr.name
>     	FROM employee emp, employee mgr
>     	WHERE emp.manager_id = mgr.id

In XQuery, the query would appear similar to that in Listing 4-2.

Listing 4-2 Query retrieves records where employee manager ID field matches a particular manager ID

>     <employee_managers>
>     {
>     for $emp in document("employee")//employee
>     for $mgr in document("employee")//employee
>     where $emp.manager_id eq $mgr.id
>     return
>     <employee_manager>
>     	<employee> {$emp.name} </employee>
>     	<manager> {$mgr.name} </manager>
>     </employee_manager>
>     }
>     </employee_managers>

In both of these examples, given the sources, there is no way to write these queries without replicating the source schemas.

#### Enhancing Readability or Code Efficiency With Duplicate Source Schemas

In ambiguous cases, both replicating and not replicating a source would lead to reasonable queries. For example, a self-join to get employee-manager pairs was shown in a previous example. Without replicating the source, you could:

1. Map name to the target (get the employee name)
2. Join `manager_id` with `id` (join to get the manager)
3. Map name to the target (get the manager name)

Of course, the Data View Builder would interpret this query as: "give me all employees who are their own manager". Under such circumstances the option of creating multiple copies of a source schema reduces possible confusion or confusing results.

## Target Schemas

A target schema describes the structure of a query result that will be produced when the query runs. As with source schemas, the Data View Builder provides a graphical representation of target schemas in a tree structure format.

Figure 4-3 Sample Target Schema

Target schemas have these main purposes:

- Provide a template for the mapping data from source schemas in order to generate a query.
- Provide a schema for Liquid Data Web Service and Data View definitions.
- Determine the structure and order of the XML document generated by the XQuery.

You can specify a target schema in the Data View Builder in the following ways:

- Select a schema from the Liquid Data repository.
- Build a new target schema from scratch (using right-click menu commands).

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.

Figure 4-4 Liquid Data Repository Highlighted in File Browser

If you choose Repository in the Open dialog, the Data View Builder displays target schemas in the Liquid Data repository.

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

Figure 4-5 Schema File Selected

The target schema is displayed and docked on the right side of the Design tab work area.

(You can also choose the menu item File —> Set Selected Source Schema as Target Schema to create a target schema that is, at least initially, based exactly on a source schema.)

### Guidelines for Working With Target Schemas

Use these guidelines when working with target schemas:

1. Make sure the target schema has proper cardinality. For example, if you intend to project customer orders in your result, the target schema should reflect the parent-child relationship between `customer` and `orders`. All examples in Building Queries demonstrate this guideline.
2. Project at least one element from each data source that is part of the query to the target schema.
3. It is generally unnecessary to map every element in a target schema. For example, you could choose the same schema for both the source and target data structure, but then map only some of the source elements to the target schema. The query result will show only those source data elements that are actually mapped to elements in the target schema.
4. Understand how target schema conformity works and use it efficiently. (See Managing Target Schema Properties for details on schema element property settings.)

- A plus sign [+] next to a element indicates that the element is repeatable and required. (In other words, there must be one or more occurrences of this.) Since this setting requires extra checking of the data, most queries that use it pay a performance penalty.
- An asterisk [*] next to an element indicates that the element is repeatable and optional. (In other words, there can be 0 or more occurrences of this.)

Use this setting when possible to avoid unnecessary data checking and the associated performance hit. Use this especially if you know that the underlying data sources enforce referential integrity between parent-child items.

Of the several examples included in this section the following particularly demonstrate these guidelines:

- Example 1: Retrieve All BroadBand Customers, Returning Their Wireless Orders, If Any (ORDER is Repeatable and Optional)
- Example 2: Retrieve Only BroadBand Customers Who Have At Least One Wireless Order; Return Their Wireless orders (ORDER Is Repeatable And Required)

5. If your plan is to create a data view from your query, your target schema should only contain required elements that are utilized in the query. For example, if the `Customer` table contains `first_name`, `last_name`, `email`, and `phone` elements and each of those elements is required in the target schema, then you need to map each element of your query before saving it.

For a detailed description of target schemas, see Schemas and Namespaces in Liquid Data.

### Managing Target Schemas

Target schemas are composed of complex elements, simple elements (child elements), and attributes. You can set element properties using the Properties dialog box, which you access by right-clicking on the element.

Figure 4-6 Properties Dialog

The following properties can be set:

- Local name. Allows you to change the element name.
- Namespace. Allows you to specify a previously created XML namespace. (See Understanding XML Namespaces for a discussion of namespaces.)
- Content type. Allows you to choose a content type such as a string or Boolean from a drop-down list.
- Repeatable attribute. Provides for schema elements and their sub-elements to be repeatable.
- Optional attribute. Provides for schema elements to be optional rather than required.

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

# Schema Import Resolution Rules

If a schema file has an import statement with a relative path to another schema file, Liquid Data resolves the location of the imported files according to the following rules:

1. Attempt to resolve the filename in the `<ldrepository>/schemas` directory.
2. If the file is not found in the `<ldrepository>/schemas` directory, attempt to resolve it relative to the directory in which the schema file (the first one with the import statement) is saved.
3. If imported schema files in turn import other schema files, they are resolved first from the <`ldrepository>/schemas` directory.

In the case of the Liquid Data Server Samples repository, the first attempt to resolve the search will be in the following directory:

>     <WL_HOME>/samples/domain/liquiddata/ldrepository/schemas

and then from the location relative to the original schema file (the first one with the import statement).

For example, if you have a schema file in the following location in the repository:

>     <ldrepository>/schemas/dir1/dir2/s.xsd

and it contains the following import statement:

>     import dir3/file.xsd

then Liquid Data first looks for a schema file named:

>     <ldrepository>/schemas/dir3/file.xsd

and, if it does not find it relative to the root level of the repository, Liquid Data looks for it in:

>     <ldrepository>/schemas/dir1/dir2/dir3/file.xsd

As a further example, assume the `file.xsd` import was resolved in:

>     <ldrepository>/schemas/dir3/file.xsd

If `file.xsd` in turn has the following import statement:

>     import dir4/another.xsd

then Liquid Data first attempts to resolve this import statement relative to the root of the repository:

>     <ldrepository>/schemas/dir4/another.xsd

If the file is not there, it then resolves it relative to the original `<ldrepository>/schemas/dir1/dir2/s.xsd` file, as follows:

>     <ldrepository>/schemas/dir1/dir2/dir4/another.xsd

# Understanding XML Namespaces

XML namespaces are a mechanism by which you can ensure that there are no name conflicts (or ambiguity) when combining XML documents or referencing an XML element.

Liquid Data supports XML namespaces and includes namespaces in the queries generated in Data View Builder.

This section includes the following topics:

- XML Namespace Overview
- Using XML Namespaces in Liquid Data Queries and Schemas
- Migrating Liquid Data 1.0 Queries

## XML Namespace Overview

XML namespaces appear in queries as a string followed by a colon. For example, the `xs:integer` data type uses the XML namespace `xs`. Actually, `xs` is an alias (called a prefix) for the URI name of the namespace. (See Table 4-7 for the full set of predefined XQuery namespaces.)

Prefix | URI Name
--- | ---
`xs` | `http://www.w3.org/2001/XMLSchema`

XML namespaces ensure that names do not collide when combining data from heterogeneous XML documents.

For example, there could be an element `<tires>` in a document related to automobile manufacturers. In a document related to bicycle tire manufacturers, there is also a `<tires>` element. Obviously, combining these elements would be problematic under most circumstances. XML namespaces easily avoid such name collisions by referring to the elements as `<automobile:tires>` and `<bicycle:tires>`.

In a XML schema namespaces — including the target namespace — are declared in the schema tag. Here is an example:

>     <schema	xmlns="http://www.w3.org/2001/XMLSchema"
>     	xmlns:bea="http://www.bea.com/public/schemas"
>     	targetnamespace="http://www.bea.com/public/schemas"
>     	...

The first line of the above schema contains the default namespace, which is the namespace of all the unqualified elements in the schema.

For example, if you see the following element in a schema document:

>     <element name="appliance" type="string"/>

the element `element`, and the attribute `name` and `type` all belong to the default namespace, as do unprefixed types such as `string`.

The second line of the schema contains a namespace declaration — `bea` — which is simply an association of a URI with a prefix. There can be any number of such declarations in a schema.

Lastly, comes the target namespace, declared with the `targetNamespace` attribute. It this case, the target namespace is bound to the namespace declared on the second line, meaning that all element and attribute names declared in this document belong to:

>     http://www.bea.com/public/schemas

References to types declared in this schema document must be prefixed. For example:

>     <complexType name="AddressType">
>     	<sequence>
>     		<element name="street_address" type="string"/>

>     		...

>     	</sequence>
>     </complexType>

>     <element name="address" type="bea:AddressType"/>

### Predefined Namespaces in XQuery

The following table shows predefined namespaces used in XQuery:

Table 4-7 Predefined Namespaces in XQuery

Namespace Prefix | Description | Examples
--- | --- | ---
`xf` | The prefix for XQuery functions. | `xf:data` xf:sum xf:substring
`xfext` | The prefix for Liquid Data-specific extensions to the standard set of XQuery functions. | `xfext:match` xfext:trim
`xs` | The prefix for XML schema types. | `xs:element` xs:string
`xsext` | The prefix for Liquid Data-specific extensions to the standard set of XML schema types. | `xsext:myownstringtype`

### Other XML Namespace References

The following are some Internet links where you can find more information on XML namespaces:

>     http://www.w3.org/TR/REC-xml-names/

See also Supported XQuery and XML Schema Versions In Liquid Data in the XQuery Reference Guide.

## Using XML Namespaces in Liquid Data Queries and Schemas

The Data View Builder automatically generates the correct namespace declarations when generating a query.

However, when a target schema is created in the Data View Builder, its elements and attributes are `unqualified`, meaning that the target namespace is not automatically part of the element or attribute name.

Figure 4-8 Example of a schema with unqualified attributes and elements

If you want elements and attributes appear as qualified, you need to use an editor outside Data View Builder to modify the generated schema for either or both `attributeFormDefault` and `elementFormDefault` to be set to qualified. See Listing 4-3.

Listing 4-3 Schema Tag Setting Elements and Attributes to Qualified (emphasis added)

>     <xsd:schema targetNamespace="urn:schemas-bea-com:ld-cocpt" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:cocpt="urn:schemas-bea-com:ld-cocpt" attributeFormDefault="qualified" elementFormDefault="qualified">

Once attributes and elements have been set to qualified, they will appear as such in the Data View Builder when the target schema is set to your newly edited file.

Figure 4-9 Example of a schema with qualified attributes and elements

Note: If you are hand-coding your queries (not using the Data View Builder as a query generator), you must include the necessary namespace declaration(s) to satisfy Liquid Data server requirements. For a list of data sources that require namespace declarations, see Data Sources that Require Namespace Declarations on page 4-18.

### Namespace Declarations in XQuery Prolog

The beginning portion of an XQuery is known as the prolog. For Liquid Data queries, the namespace declarations appear in the XQuery prolog. There can be zero or more namespace declarations in a query prolog. Each namespace has the following form:

>     namespace <logical_name> = "<URI>"

where <logical_name> is a string used as a prefix in the query and <URI> is a uniform resource indicator.

Consider the following simple query:

>     namespace view = "urn:views"

>     <CustomerOrderID>
>     			{
>     			for $view:MY_VIEW.order_2 in
>              view:MY_VIEW()/results/result/BroadBand/order
>     			return
>     				<ORDER_ID>{ xf:data($view:MY_VIEW.order_2/ORDER_ID) }
>     				</ORDER_ID>
>     			}
>     </CustomerOrderID>

The line in the prolog:

>     namespace view = "urn:views"

is the namespace declaration in this query. Each time the object (in this case, `MY_VIEW`) is referenced in the query, the object name is prefixed with the logical name `view`.

You must define namespaces in the XQuery prolog in order to use them in a query (except for the predefined namespaces described in Predefined Namespaces in XQuery on page 4-15). If you do not define namespaces in the XQuery prolog, the query will fail with a compilation error.

### Defining Namespaces in Target Schema

When you use the Data View Builder to create or modify target schemas, you can specify a namespace for an element or an attribute. Such a specified namespace is added to the XML markup in the query (and therefore to the query results).

You can set or change a target namespace using the Target Namespace menu option, available from the Data View Builder Query menu when in Design mode.

Figure 4-10 Target Namespace Dialog Box

Figure 4-11 shows adding a local name called `db` to an element of the target schema named `crm2` from the Properties dialog box. If multiple namespaces are available, you can select one from the drop-down list box.

You can access the Properties dialog box by right-clicking on an element in your target schema.

Figure 4-11 Properties Dialog Box

The query results for this target schema definition are of a form similar to:

>     <crm2:db xmlns:crm2="urs:schemas-bea-com:ld-crmp"> 100.0 </crm2:db>

### Data Sources that Require Namespace Declarations

All data sources except relational databases and XML files require the namespace declaration in the XQuery prolog. Thus the following data sources require namespace declarations in the XQuery prolog:

- Data Views
- Web Services
- Application Views
- Stored Procedures
- Complex Parameter Types

## Migrating Liquid Data 1.0 Queries

Liquid Data 1.0 did not support XML namespaces, and any queries used in Liquid Data 1.0 must be migrated to work in Liquid Data 8.1. If you have queries that are generated in a Data View Builder project file, you can open the project file in Data View Builder 8.1. When you click the Test tab, the Data View Builder automatically generates the new query with the proper namespace declarations in the query prolog.

If you have stored queries and data views, you must use the `queryMigrate` tool to migrate the queries so they work properly in Liquid Data 8.1. For information on the `queryMigrate` tool, see Migrating from Liquid Data 1.0 to 8.1 in the Liquid Data Migration Guide.