Bookmark and Share Share

<join>

This statement defines how the data from disparate variables should be joined. Variable data should have repetitive structures that are related based on some criteria in those structures - the foreign keys that define the relation. Optionally, you can also select specific nodes from the result and modify them to build the resulting document structure.

The <join> statement is comparable to inner joins for databases. Only nodes that have values that match the criteria for all variables are included. You can obtain outer joins in mashups using XQuery. See Using XQuery for Outer Joins for an example.

You must define at least one join condition, as shown in Defining Join Conditions. You can also, optionally, select which nodes to include in the joined items, as shown in Selecting Nodes for Joined Items with <select>. See also Valid Join Operators and Defining Multiple Conditions.

Can Contain ( select? )
Allowed In mashup, else, elseif, for, foreach, if, macro, operation, sequence, while,

Attributes

Name Required Description
outputvariable yes

The required variable to accept the output of this statement.
joincondition yes

An XPath 2.0 expression defining the variables to join and one or more conditions to apply to determine how variables are joined.

<select>

Optionally, defines the literal XML structure and specific nodes or computations to include in the result of the join. If this is omitted, all nodes matching the join condition are included in the result.

Note: The structure inside <select> must be well-formed, starting with a root node, that is repeated for each included node. Elements in the structure should use a namespace, so that they are clearly separated from EMML markup.

Can Contain

Can contain text and any well-formed literal XML. Data can be literal text or assigned with dynamic mashup expressions.

Attributes

Name Required Description
name yes

The name to assign to the root node enclosing all selected results for the join.

<join> Examples

Defining Join Conditions

You use the joincondition attribute and outputvariable to define a basic <join> statement.

The following example is a simple join of two variables based on a single condition. For clarity, the data for the variables is shown directly. The joincondition attribute contains an XPath expression that defines the single condition:

<variable name="movies" type="document"> 
  <movies> 
    <movie id="Stargate" ... /> 
    <movie id="Lassie" ... /> 
    ... 
  </movies> 
</variable> 
<variable name="reviews" type="document"> 
  <reviews> 
    <review> 
     <title>Encounters of the Third Kind</title> 
     <rating>4</rating> 
     ... 
    </review> 
    <review> 
     <title>Stargate</title> 
     <rating>4.5</rating> 
     ... 
    </review> 
     ... 
  </reviews> 
</variable> 
<join outputvariable="$joinResult" 
    joincondition="$movies/movies/movie/@id = 
    $reviews/reviews/review/movie/title"/>

Each condition consists of an XPath expression, identifying a node for one item, a comparison operator and another XPath expression, identify the node for a related item to be joined. You can also use XPath functions in these XPath expressions.

Valid Join Operators

You can use any of the basic math comparison operators (= , !=, <, <=, >, and >=). For string comparisons, you can also use ~ to express a partial match relationship. Comparisons with ~ are not case sensitive.

You must use XML escaping with operators that include < or > characters. See XML Escaping in URLs and Expressions for more information.

The following example would join an item from the location variable to items in the companyProfiles variable as long as the location city name is contained within the company profile address:

<join outputvariable="$joinResult" 
    joincondition="$location/county/city/name ~ $companyProfiles/profiles/profile/address"/>

Defining Multiple Conditions

You can combine two or more conditions in the joincondition attribute using the logical XPath keywords and or or. You cannot use parentheses or other grouping symbols to define precedence, however. The joincondition attribute only supports very straightforward joins.

Selecting Nodes for Joined Items with <select>

The <select> element is an optional child for <join>. It allows you to define the structure of the joined items to return and selectively choose which nodes to include. If you omit <select> all the nodes from the join data are included in the output.

To define the resulting structure for the output variable:

  • Define the name of the root node that encloses all results in the name attribute of <select>.

  • Define the structure for each row or item in the result as literal XML in the body of <select>. This structure must contain:

    • The root node to wrap each repeating item from the <join> operation.

    • The descendant nodes to include within each item.

    This result structure also contains mashup expressions that determine what joined data will be selected to fill the result. See Dynamic Mashup Expressions for more information.

In the next example, the output variable will contain a <res:recommendations> element with a repeating set of <res:movie> children - the repeating items. Each <res:movie> contains a <res:movietitle> child with data from the variable named movies and <res:rating> and <res:comment> children with data from the variable named reviews.

<join outputvariable="$joinResult" 
  joincondition="$movies/movie/@id = $reviews/review/movie/title"> 
  <select name="res:recommendations"> 
      <res:movie> 
        <res:movietitle>{$movies/title}</res:movietitle> 
        <res:rating>{$reviews/rating}</res:rating> 
        <res:comment>{$reviews/comment}</res:comment> 
      </res:movie> 
  </select> 
</join>