JBoss.orgCommunity Documentation

Chapter 1. Introduction

1.1. What is Teiid Designer?
1.2. Metadata Overview
1.2.1. What is Metadata
1.2.2. Business and Technical Metadata
1.2.3. Source and View Metadata
1.3. It's all in the Modeling...
1.3.1. What Are Models?
1.3.2. How is a Model Defined?
1.3.3. Guiding through the process
1.3.4. Targeting Your Teiid Submoduler
1.3.5. Model Classes and Types
1.3.6. The Virtual Database
1.3.7. Model Validation
1.3.8. Testing Your Models
1.3.9. Model Object Extensions

The Teiid Designer User's Guide provides detailed descriptions of Teiid Designer features and functionality.

Teiid Designer is an Eclipse-based graphical modeling tool for modeling, analyzing, integrating and testing multiple data sources to produce Relational, XML and Web Service Views that expose your business data.

Why Use Teiid Designer?

Teiid Designer is a visual tool that enables rapid, model-driven definition, integration and testing of data services without programming. With Teiid Designer , not only do you map from data sources to target formats using a visual tool, but you can also:

  • resolve semantic differences

  • create virtual data structures at a physical or logical level

  • use declarative interfaces to integrate, aggregate, and transform the data on its way from source to a target format which is compatible and optimized for consumption by your applications

This allows you to abstract the structure of the information you expose to and use in your applications from the underlying physical data structures. With Teiid Designer, data services are defined quickly, the resulting artifacts are easy to maintain and reuse, and all the valuable work and related metadata are saved for later reference.

You can use Teiid Designer to integrate multiple sources, and access them using the common data access standards:

  • Web Services / SOAP / XML

  • JDBC / SQL

  • ODBC / SQL

Metadata is data about data. A piece of metadata, called a meta object in the Teiid Designer, contains information about a specific information structure, irrespective of whatever individual data fields that may comprise that structure.

Let’s use the example of a very basic database, an address book. Within your address book you certainly have a field or column for the ZIP code (or postal code number). Assuming that the address book services addresses within the United States, you can surmise the following about the column or field for the ZIP code:

This definition represents metadata about the ZIP code data in the address book database. It abstracts information from the database itself and becomes useful to describe the content of your enterprise information systems and to determine how a column in one enterprise information source relates to another, and how those two columns could be used together for a new purpose

You can think of this metadata in several contexts:

Editing Metadata vs. Editing Data

The Teiid Designer helps you to create and describe an abstract graphic representation of your data structure of your data in the original data sources. It also describes whether those data sources are composed of Relational databases, text files, data streams, legacy database systems, or some other information type.

The Teiid Designer allows you to create, edit, and link these graphically-represented meta objects that are really a description of your data, and not the data itself.

So when this documentation describes the process of creating, deleting, or editing these meta objects, remember that you are not, in fact, modifying the underlying data.

Metadata Models

A metadata model represents a collection of metadata information that describes a complete structure of data.

In a previous example we described the field ZIPCode as a metadata object in an address book database. This meta object represents a single distinct bit of metadata information. We alluded to its parent table, StreetAddress. These meta objects, and others that would describe the other tables and columns within the database, would all combine to form a Source Metadata model for whichever enterprise information system hosts all the objects.

You can have Source Models within your collection of metadata models These model physical data storage locations. You can also have View Models, which model the business view of the data. Each contains one type of metadata or another. For more information about difference between Source and View metadata, (see Section 1.2.3, “Source and View Metadata”).


For detailed information about creating models from your metadata, see Section 1.3, “It's all in the Modeling...”

Metadata can include different types of information about a piece of data.

Technical Metadata

Technical metadata represents information that describes how to access the data in its original native data storage. Technical metadata includes things such as datatype, the name of the data in the enterprise information system, and other information that describes the way the native enterprise information system identifies the meta object

Using our example of an address book database, the following represent the technical metadata we know about the ZIP code column:

  • Named ZIPCode

  • Nine characters long

  • A string

  • Located in the StreetAddress table

  • Uses SQL Query Language

These bits of information describe the data and information required to access and process the data in the enterprise information system.

Business Metadata

Business metadata represents additional information about a piece of data, not necessarily related to its physical storage in the enterprise information system or data access requirements. It can also represent descriptions, business rules, and other additional information about a piece of data.

Continuing with our example of the ZIP Code column in the address book database, the following represents business metadata we may know about the ZIP code:

  • The first five characters represent the five ZIP code numbers, the final four represent the ZIP Plus Four digits if available, or 0000 if not

  • The application used to populate this field in the database strictly enforces the integrity of the data format

Although the first might seem technical, it does not directly relate to the physical storage of the data. It represents a business rule applied to the contents of the column, not the contents themselves.

The second, of course, represents some business information about the way the column was populated. This information, although useful to associate with our definition of the column, does not reflect the physical storage of the data.

In addition to the distinction between business and technical metadata, you should know the difference between Source Metadata and View Metadata.

Source and View metadata refer to what the metadata represents, not its content.

Source Metadata directly represents metadata for an enterprise information system and captures exactly where and how the data is maintained. Source Metadata sounds similar to technical metadata, but Source Metadata can contain both technical and business metadata. When you model Source Metadata, you are modeling the data that your enterprise information systems contain.

View Metadata, on the other hand, represent tailored views that transform the Source Metadata into the terminology and domain of different applications. View Metadata, too, can contain both technical and business metadata. When you model View Metadata, you’re modeling the data as your applications (and your enterprise) ultimately use it.

Modeling Your Source Metadata

When you model the Source Metadata within your enterprise information systems, you capture some detailed information, including:

The Source Metadata captures this detailed technical metadata to provide a map of the data, the location of the data, and how you access it.

This collection of Source Metadata comprises a direct mapping of the information sources within your enterprise. If you use the Teiid Designer Server for information integration, this technical metadata plays an integral part in query resolution.

For example, our ZIPCode column and its parent table StreetAddress map directly to fields within our hypothetical address book database.

To extend our example, we might have a second source of information, a comma-separated text file provided by a marketing research vendor. This text file can supply additional demographic information based upon address or ZIP code. This text file would represent another Enterprise Information System (EIS), and the meta objects in its Source Model would describe each comma-separated value.

Modeling Your View Metadata

When you create View Metadata, you are not describing the nature of your physical data storage. Instead, you describe the way your enterprise uses the information in its day-to-day operations.

View Metadata derives its classes and attributes from other metadata. You can derive View Metadata from Source Metadata that describes the ultimate sources for the metadata or even from other View Metadata. However, when you model View Metadata, you create special “views” on your existing enterprise information systems that you can tailor to your business use or application expectations. This View Metadata offers many benefits:

Our example enterprise information sources, the address book database, and the vendor-supplied comma-delimited text file, reside in two different native storage formats and therefore have two Source Metadata models. However, they can represent one business need: a pool of addresses for a mass mailing.

By creating a View Metadata model, we could accurately show that this single View Table, the AddressPool, contains information from the two enterprise information systems. The View Metadata model not only shows from where it gets the information, but also the SQL operations it performs to select its information from its source models.

This View Metadata can not only reflect and describe how your organization uses that information, but, if your enterprise uses the Teiid Designer Server, your applications can use the View Metadata to resolve queries.

To create this View Metadata, you create a view and define a transformation for that view, a special query that enables you to select information from the source (or even other view) metadata models. For more information, see “Section 6.3.1, “Transformation Editor”.”

Metadata Transformations

By modeling View Metadata, you can illustrate the business view of your enterprise information sources. View Metadata models not only describe that business view, but also illustrate how the meta objects within the View Metadata models derive their information from other metadata models.

Let’s return to the example of our address book database and the vendor’s comma-separated list. We want to generate the View Metadata model, Address Pool, from these enterprise information systems.

The transformation that joins these metadata models to create the virtual Address Pool metadata model contains a SQL query, called a union, that determines what information to draw from the source metadata and what to do with it.

The resulting Address Pool contains not only the address information from our Address Book database, but also that from our vendor-supplied text file.

SQL in Transformations

Transformations contain SQL queries that SELECT the appropriate attributes from the information sources.

For example, from the sources the transformation could select relevant address columns, including first name, last name, street address, city, state, and ZIP code. Although the metadata models could contain other columns and tables, such as phone number, fax number, e-mail address, and Web URL, the transformation acts as a filter and populates the Address Pool metadata model with only the data essential to building our Address Pool.

You can add other SQL logic to the transformation query to transform the data information. For example, the address book database uses a nine-character string that represents the ZIP Plus Four. The transformation could perform any SQL-supported logic upon the ZIPCode column to substring this information into the format we want for the Address Pool View metadata model.

Mapping XML Transformations

When you model View Metadata, you can also create a View XML Document model. This View Document lets you select information from within your other data sources, just like a regular View Metadata model, but you can also map the results to tags within an XML document.

In this example, the Address Pool View Metadata model still selects its information from the Address Book Database and the Vendor Text File, but it also maps the resulting columns into tags in the Address XML document.

A model is a representation of a set of information constructs. A familiar model is the relational model, which defines tables composed of columns and containing records of data. Another familiar model is the XML model, which defines hierarchical data sets.

In Teiid Designer, models are used to define the entities, and relationships between those entities, required to fully define the integration of information sets so that they may be accessed in a uniform manner, using a single API and access protocol. The file extension used for these models is .xmi ( Example: NorthwindOracle.xmi ) which adheres to the XMI syntax defined by the OMG.

Below is an example of the partial contents of a model file.


Model files should never be modified "by hand". While it is possible to do so, there is the possibility that you may corrupt the file such that it cannot be used within Teiid Designer system.

The fundamental models in Teiid Designer define the structural and data characteristics of the information contained in data sources. These are referred to as source models (represented by ). Teiid Designer uses the information in source models to federate the information in multiple sources, so that from a user's viewpoint these all appear to be in a single source.

In addition to source models, Teiid Designer provides the ability to define a variety of view models(represented by ). These can be used to define a layer of abstraction above the physical (or source) layer, so that information can be presented to end users and consuming applications in business terms rather than as it is physically stored. Views are mapped to sources using transformations between models. These business views can be in a variety of forms:

  • Relational Tables and Views

  • XML

  • Web services

  • Functions

For full list of supported model types see Chapter 4, New Model Wizards

A third model type, logical, provides the ability to define models from a logical or structural perspective.

To make the process of using Teiid Designer to build models more as easy as posssible, a guides view (Section D.2.13, “Guides View”) has been introduced. It provides action sets which bring together the actions necessary to develop models for specific use-cases. Action sets are available for the following scenerios:

  • Consume a SOAP Web Service
  • Create a REST Web Service
  • Model Flat File Source (a text file)
  • Model JDBC Data Source
  • Model Local XML File Source
  • Model Remote XML File Source
  • Modell Teiid Data Source (deployed on server)
  • Teiid Server Actions

The critical artifact that Teiid Designer is intended to manage is the VDB, or Virtual DataBase. Through the Teiid server, VDB's behave like standard relational database schema which can be connected to, queried and updated based on how the VDB is configured. Since VDB's are just databases once they are deployed, they can be used as sources to other view model transformations. This allows creating and deploying re-usable or common VDB's in multiple layers depending on your business needs.

Starting in Teiid Designer 9.0, support was added for converting between archive (ZIP) VDBs and simple Dynamic VDB XML files. Dynamic VDBs provide users to define their source and view metadata via Teiid DDL statements. This capability allows some users to maintain a simpler version of their VDBs in a source control system. (See the Section 10.8, “Working with Dynamic VDBs” section for more details)

In Designer, the VDB file names use a ".vdb" file extension. VDBs are structurally just ZIP archive files containing 3 folders:

    • contains "vdb.xml" definition file

  • runtime-inf

    • contains a binary INDEX file for each model included in your VDB. Note that these INDEX files represent the actual runtime metadata and is an optimized subset of data from your design-time metadata in your models.

  • <project folder name>

    • contains of the models you will be adding in the VDB Editor (i.e. *.xmi and *.xsd files)

When deployed, the metadata is consumed by Teiid in order to create the necessary runtime metadata for your model definitions.

The vdb.xml file contains:

  • VDB name, version, properties

  • contained model information (name, translator name, connection info)

  • translator info

  • data role definitions for the referenced models

  • import VDB references

The vdb.xml file example below highlights the basic model information.


The VIRTUAL and PHYSICAL <model> elements containing property references to the INDEX files as well as the <source> element info for the PHYSICAL (aka source) model EU_CustomerAccounts.xmi.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<vdb version="1" name="Financials">
    <model visible="true" type="VIRTUAL" name="US_CustomerAccounts" path="/Financials/US_CustomerAccounts.xmi">
        <property value="4097408696" name="checksum"/>
        <property value="Relational" name="modelClass"/>
        <property value="false" name="builtIn"/>
        <property value="1592679058.INDEX" name="indexName"/>
        <property value="/Financials/US_CustomerAccounts.xmi" name="imports"/>
    <model visible="true" type="PHYSICAL" name="EU_CustomerAccounts" path="/Financials/EU_CustomerAccounts.xmi">
        <property value="525566235" name="checksum"/>
        <property value="Relational" name="modelClass"/>
        <property value="false" name="builtIn"/>
        <property value="1119071590.INDEX" name="indexName"/>
        <source translator-name="postgresql" connection-jndi-name="EU_CustomerAccounts" name="EU_CustomerAccounts"/>

Fortunately, Teiid Designer simplifies the management of your VDBs by providing a dedicated VDB Editor which maintains a consistent, valid vdb.xml file for you and assists in synchronizing your workspace models with any related models in your VDB. (See the Section D.3.2, “VDB Editor” section)

Designing and working with data is often much easier when you can see the information you're working with. The Teiid Designer's Preview Data feature makes this possible and allows you to instantly preview the information described by any object, whether it's a physical table or a virtual view. In other words, you can test the views with actual data by simply selecting the table, view, procedure or XML document. The preview functionality insures that data access behavior in Teiid Designer will reliably match when the VDB is deployed to the Server. For more info on server management see Chapter 3, Server Management

Previewing information is a fast and easy way to sample the data. Of course, to run more complicated queries like what your application likely uses, simply execute the VDB in Teiid Designer and type in any query or SQL statement.

After creating your models, you can test them by using the Preview Data action . By selecting a desired table object and executing the action, the results of a simple query will be displayed in the Data Tools SQL Results view. This action is accessible throughout the Teiid Designer in various view toolbars and context menus.

Previewable objects include:

  • Relational table or view, including tables involving access patterns.

  • Relational procedure.

  • Web Service operation.

  • XML Document staging table.


If attempting to preview a relational access pattern, a web service operation or a relational procedure with input parameters, a dialog will request values for required parameters.

Teiid Designer in conjunction with Teiid provides an extensible framework to define custom properties for model objects over-and-above what is defined in the metamodel. These custom property values are added to your VDB and included in your runtime metadata. This additional metadata is available to use in your custom translators for both source query manipulation as well as adjusting your result set data being returned.

In the 7.6 release, Teiid Designer introduces a new Model Extension Definition (MED) framework that will replace the current EMF-based Model Extension metamodel in a later 8.0 release.

This new MED framework provides the following improvements:

Also see: Section 6.4, “Managing Model Object Extensions” and Section D.3.3, “Model Extension Definition Editor”.

The purpose of a MED is to define one or more sets of extension properties. Each set of extension properties pertains to one model object type (or metaclass). Each MED consists of the following:

A MED file is an XML file with an extension of "mxd." A MED schema file (see attached modelExtension.xsd file) is used to validate a MED file. Here is a sample MED file:

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<modelExtension xmlns:p="http://org.teiid.modelExtension/2011"
    	namespacePrefix="mymodelextension" namespaceUri="org.my.extension.mymodelextension"
    	xsi:schemaLocation="http://org.teiid.modelExtension/2011 modelExtension.xsd"
    <p:description>This is my model extension</p:description>
    <p:extendedMetaclass name="com.metamatrix.metamodels.relational.impl.BaseTableImpl">
        <p:property advanced="false" index="true" masked="false" name="copyable" required="false" type="boolean">
            <p:description locale="en_US">Indicates if table can be copied</p:description>
            <p:display locale="en_US">Copyable</p:display>

The MED Registry is where the MEDs used by Designer are stored. MED files can be edited by opening the .mxd file in the Section D.3.3, “Model Extension Definition Editor”.