Understanding Scope in Basic and Advanced Views

Adding Scope to a condition is a way to specify the extent that the condition applies to the result. It helps you specify which part of a data view is the focal point for a particular condition in the query. A scope setting affects the placement of a "where" clause in the XQuery generation.

When you add a condition, the Data View Builder makes a best guess as to where the condition should appear in the query. The Data View Builder draws information from the structure of the target schema, the mappings from source schemas to the target schema, and the conditions.

In most cases, scope is implicit and the query generator can determine what the desired result should be. In other cases, it makes a very conservative assumption about the resulting scope of the condition. You can communicate your objectives more efficiently if you specify exactly what you want the query to return. By toggling to the Advanced view in the Data View Builder (Advanced View for Defining Explicit Scope for Conditions) and setting scope you explicitly indicate what part of the output, or query result, is affected by the condition.

The following sections are included here:

• Where Does Scope Apply?
• Basic View (Automatic Scope Settings)
• Advanced View (Setting the Scope Manually)
• When to Use Advanced View to Set Scope Manually
• Task Flow Model for Advanced View Manual Scoping
• Returning to Basic View

Where Does Scope Apply?

There are three candidate areas where Liquid Data sets scope. Scope candidates are:

• All repeatable elements in the target schema
• All repeatable input elements in functions
• The root of the target schema

Remember that a repeatable element always appears with an asterisk (*) or plus sign (+) occurrence indicator.

Basic View (Automatic Scope Settings)

The default setting in the Data View Builder is the basic view. In this view, when you add a condition to any query, the Data View Builder applies an automatic scope setting using internal rules that specify where the condition should appear in the query.

In most cases, the scope setting that Data View Builder chooses for each condition is the correct setting. When you have complex conditions, or a particular result in mind, you may want to switch to the Advanced mode where you can change scope settings as you wish.

Advanced View (Setting the Scope Manually)

Data View Builder enables you to override the automatic scope setting by using an Advanced view of the existing scope settings. When you switching to an Advanced view, Data View Builder displays the setting it selected for automatic scoping. You can change any or all of the individual scope settings or allow them to retain their original values.

When you switch to the Advanced view, it is not necessary to change any of the explicit scope settings selected by Data View Builder. However, if you add new conditions when you are in Advanced view, or change existing conditions, you must set the new scope manually for each condition.

To switch to the Advanced view, click Advanced view toggle so that an X is displayed next to Advanced view. The Conditions tab expands to show more information about the condition targets.

• The Current Scope initially shows the target schema root. Before you map schema sections and create conditions, you can drag a repeatable target schema or function input node to set the scope for a complete section of the target schema. Thereafter, the value in the Current Scope text box determines what will appear automatically in a Scope column cell for any new condition that you create. For more information about this technique, see Task Flow Model for Advanced View Manual Scoping.
• The Enabled column contains a switch to include or exclude a condition when the query runs.
• The Condition column shows the source node, condition, and condition target node.
• The Scope column shows which node Liquid Data automatically selected in the target schema to focus the result. You can also drag a repeatable target schema node directly to a cell in this column to change the scope for that condition.
• The Reset button in the upper right recalculates all scope settings and returns them to the automatic settings selected by Liquid Data.

Figure 3-10 Advanced View Showing Explicit Scope on Conditions Tab




 

Condition and Target pairs appear row by row. If there are multiple scope settings for a condition, the condition reappears in separate rows to display each unique scope setting.

Figure 3-11 Advanced View

 

The Current Scope text box shows the default scope setting for every condition that you add. Remember that the Basic view settings will continue to appear until you change them. If you add a new condition in Advanced view, the default scope is the target schema root until you change that value.

When to Use Advanced View to Set Scope Manually

Data View Builder automatically scopes conditions wherever it is most logical, possibly in more than one place. However, occasionally it may not put the automatic scope setting where you think it should be. In these cases, you can switch to the Advanced view to overwrite the automatic scope setting.

The most common case occurs when a condition logically applies in two places, but you want it to appear in only one place. You can diagnose this by examining the XQuery translation for where clauses, or do a test run of the query to view the result. If you are not satisfied, switch to the Advanced view to determine where the condition appears. Remember that Data View Builder lists the same condition more than once if it has more than one scope setting. Change the scope setting that you do not want by following the directions in Task Flow Model for Advanced View Manual Scoping.

A less common case is when you want to create an assertion. For example, the Liquid Data Server should return a result only when a certain condition occurs. You can accomplish this if you switch to the Advanced view, create the condition, and set the scope for the condition to be the root of the target schema.

Note: It is a good idea to run the query using the automatic scope settings first to ensure that it is necessary to revise the scope setting.

Task Flow Model for Advanced View Manual Scoping

If you decide to override automatic scope settings, there is a workflow model that will help you design the query, create conditions, and determine the scope. By following this methodology, you will find it is easy to create a query where you control the scope. Consider the example shown in Figure  3-12 of two source schemas: PB-BB and PB-WL, and the target schema customerLineItems.xsd.

Figure 3-12 Schemas for Manual Scope Example

 

The target schema, customerLineItems.xsd, has a hierarchical structure. There are three distinct sections in the schema that represent repeatable data. customer and order each have an asterisk (*) as the occurrence indicator. line_item has a plus sign (+) as the occurrence indicator. This means that the child nodes without an asterisk or plus are non-repeating. For each customer, there is one occurrence of first_name, last_name, and id. Each customer may have zero or more orders. When an order exists, each order has one id, date, and amount. If an order exists, there must be at least one line_item. Work on sections that appear under a repeatable node.

This workflow model assumes that you can build your query in steps, focusing on each section in the target schema as you go. Follow these steps for each section in the target schema where you want a result to appear.

1. Choose a repeatable section of the target schema for our scope. A section is a repeatable node (parent) and its children. It is recommended that you work from the outside in. In this case, the outermost section is the customer* section. (For this example we want to collect the first_name, last_name, and id in the result.)

2. Set the highest repeatable node in this section as the default scope, which in this case is customer*. Drag that element from the target schema onto the Current Scope text box on the Conditions tab. (For this example we drag and drop customerLineItems.xsd onto the Current Scope text box.)

   

   
    

3. Map selected source elements/attributes to that repeatable section in the target schema.

   For this example, we do the following mappings:

   • Map [PB-WL]/db/CUSTOMER*/FIRST_NAME to [customerLineItems.xsd]/customers/customer*/first_name.
   • Map [PB-WL]/db/CUSTOMER*/LAST_NAME to [customerLineItems.xsd]/customers/customer*/last_name.
   • Map [PB-WL]/db/CUSTOMER*/CUSTOMER_ID to [customerLineItems.xsd]/customers/customer*/id.

4. Set any conditions that connect and filter the mapped sources.

   By setting the default scope before creating the condition, Data View Builder sets the condition scope to that value.

   By mapping one section at a time and using the repetitive ancestor node as the default scope, your conditions will apply exactly where you need them to appear in the result.

   For our example, we set as a condition a join between CUSTOMER_ID in the PB-BB schema and CUSTOMER_ID in the PB-WL schema as shown in the figure below.

   

   
    

   
    

5. Repeat these steps for each section of the target schema where you want data to appear in the result. Work on one section at a time and work from the outside (more general) to the inside (most specific). Ensure that you set the default target, map, and define the conditions, before you move to the next section. The general rule is that any mapping with an associated condition requires a scope setting.

In a small number of cases, you may apply a condition on the argument (input) to a function that requires choosing the function as the default scope. This is not common but will occur when you choose a complex aggregate function.

Returning to Basic View

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.

Saving Projects from Basic or Advanced View

If you save a project from Basic view, the project file discards scope information. When you reopen this project, Liquid Data once again applies automatic scope using its internal algorithms.

If you save a project from the Advanced view, all conditions retain current scope settings. When you reopen this project, all Advanced view settings appear.

Version Control

Liquid Data assigns a version attribute to the project file. If you open a project file created with an earlier version of Liquid Data, the project opens in the Advanced view if all conditions have explicit scope settings.

Scope Recursion Errors

It is possible to create a query where a condition depends on the values returned by a function, but the function input depends on the condition. For example:

• Select the xf:count function and map a source node to be the input of xf:count.
• Create a condition that uses the output of the xf:count function.
• In the Advanced view, set the condition target to the input of the xf:count function.

The xf:count function input must be filtered by applying the condition, but the condition input is the output of xf:count.

Data View Builder does not allow this to happen when automatic scoping is enabled. However, if you clear the Auto-Select Targets check box and set scope manually, it is possible for you to set the scope of a condition to a function input that creates a circular dependency. Data View Builder cancels the action and generates an error message:

Setting Scope/Target of condition {condition} to {scope node} creates circular dependency

Recommended Action

Basic view should generally support most scenarios—we expect that only a few users and/or queries will require use of the Advanced view manual scoping feature. You can assume that Liquid Data can interpret the scope requirements correctly for most types of queries. If you do choose to set scope manually, examine the generated XQuery to ensure the condition targets meet your expectations. If the recursion error message appears, consider resetting all condition scope targets. Override the automatic settings one at a time, switch to Test view to examine the query, run it, and assess the results.