Learn to configure the <table_ref> element for Pull Reports™ Ad Hoc report and data service software.

A <table_ref> references a global <table>. A <table_ref> may be used in place of a <table> element as a <report>'s base table or <relationship>'s join table. Use <table_ref>s to reuse global <table> configuration within one <catalog>.

<table_ref>s may define their own <relationship>s and <pre_filter>s which are added to any <relationship>s and <pre_filter>s of the referenced global table.

If a <table_ref> defines a child <description> element, its value overrides any description defined in the referenced global table.


See the the section called “Catalog with multiple <report>s using <table_ref> for example usage.

Warning: <relationship> table id collision

It is an XML parsing error if any child <relationship> from the referenced global table has a child <table> with an id value matching any <table> id of a <table_ref>'s <relationship>s. The error occurs because child <relationship> <table>s of the same parent must have identical <table> ids in order to keep table resource path unique.

This means the following Pull Reports™ XML Catalog file will error when parsed:

<?xml version="1.0" encoding="UTF-8"?>
<catalog xmlns="http://www.pullreports.com/catalog-1.5.0" id="id" name="name">
    <report id="test" name="Test">
        <table_ref id="details" displayName="Details" ref="global">
            <relationship cardinality="many">
                <join_table name="foo_bar">
                    <join_columns><join_column columnName="details_id" referencedColumnName="id" /></join_columns>
                    <inverse_join_columns><join_column columnName="same_id" referencedColumnName="id" /></inverse_join_columns>
                <table id="same" displayName="Same" name="same">
                    <column id="id" name="id" displayName="ID"/> 
    <table id="global" displayName="Global" name="global">
        <column id="details_id" name="id" displayName="ID"/> 
        <relationship cardinality="many">
            <join_table name="foo_bar2">
                <join_columns><join_column columnName="details_id" referencedColumnName="d" /></join_columns>
                <inverse_join_columns><join_column columnName="same_2_id" referencedColumnName="id" /></inverse_join_columns>
            <!--  Invalid: Even though the two relationship tables reference database tables with different names, 
                  "same" vs "same_2", the fact that the <table> id attributes are both "same" causes an error. -->
            <table id="same" displayName="Same" name="same_2">
                <column id="id" name="id" displayName="ID"/> 

Infinite recursion protection

A global table <table> that contains a <table_ref> to itself within a nested <relationship> element creates an join tree that recurses to infinite size. Pull Reports™ detects this recursion and stops the join tree relationship nesting on the second instance of a global <table>.

This means that if global table A has a <relationship> child <table> B, and <table> B in turn has a <relationship> child which <table_ref> references back to global <table> A, Pull Reports™ will prevent the second, nested table A from having relationship children. This effectively stops the join tree at path /A/B/A instead of permitting the infinitely recursive /A/B/A/B/... join tree path.







Specifies the id of the <table_ref> within table resource path statements.

All <table>s and <table_ref>s nested within <relationship>s with the same <table> join parent must have unique id values between themselves. This requirement ensures that each table resource path uniquely identifies one <table> or <table_ref> within a <report>.

displayName (Optional)

The human readable name. If not specified, uses the displayName attribute of the referenced global <table>.


Specifies the id of the referenced global <table>.