XML VDB

XML based metadata may be deployed in a single xml file deployment or a zip file containing at least the xml file. The contents of the xml file will be similar either way. See Developing a Virtual Database for a discussion of the .vdb zip packaging. The XML may embedded or reference DDL.

XML File Deployment

You can simply create a SOME-NAME-vdb.xml file. The XML file captures information about the VDB, the sources it integrate, and preferences for importing metadata. The format of the XML file need to adhere to vdb-deployer.xml file, which is available in the schema folder under the docs with the Teiid distribution.

Important

The VDB name pattern must adhere to "-vdb.xml" for the Teiid VDB deployer to recognize this file when deployed in Teiid Server.

Tip	if you have existing VDB in combination of XML & DDL format, you can migrate to all DDL version using the "teiid-convert-vdb.bat" or "teiid-convert-vdb.sh" utility in the "bin" directory of the installation.

XML File Format

Example VDB XML Template

<vdb name="${name}" version="${version}">

    <!-- Optional description -->
    <description>...</description>

    <!-- Optional connection-type -->
    <connection-type>...</connection-type>

    <!-- VDB properties -->
    <property name="${property-name}" value="${property-value}" />

    <!-- UDF defined in an AS module,  see Developers Guide -->
    <property name ="lib" value ="{module-name}"></property>

    <import-vdb name="..." version="..." import-data-policies="true|false"/>

    <!-- define a model fragment for each data source -->
    <model visible="true" name="${model-name}" type="${model-type}" >

        <property name="..." value="..." />

        <source name="${source-name}" translator-name="${translator-name}"
            connection-jndi-name="${deployed-jndi-name}">

        <metadata type="${repository-type}">raw text</metadata>

        <!-- additional metadata
        <metadata type="${repository-type}">raw text</metadata>
        -->
    </model>

   <!-- define a model with multiple sources - see Multi-Source Models -->
   <model name="${model-name}" path="/Test/Customers.xmi">
        <property name="multisource" value="true"/>
        . . .
        <source name="${source-name}"
            translator-name="${translator-name}" connection-jndi-name="${deployed-jndi-name}"/>
        <source . . . />
        <source . . . />
    </model>

    <!-- see Reference Guide - Data Roles -->
    <data-role name="${role-name}">
        <description>${role-description}</description>
        ….
    </data-role>

    <!-- create translator instances that override default properties -->
    <translator name="${translator-name}" type="${translator-type}" />
        <property name="..." value="..." />
    </translator>
</vdb>

Note	Property Substitution - If a -vdb.xml file has defined property values like ${my.property.name.value}, these can be replaced by actual values that are defined through JAVA system properties. To define system properties on a WildFly server, please consult WildFly documentation.

Warning

You may choose to locally name vdb artifacts as you wish, but the runtime names of deployed VDB artifacts must either be *.vdb for a zip file or \*-vdb.xml for an xml file. Failure to name the deployment properly will result in a deployment failure as the Teiid subsystem will not know how to properly handle the artifact.

VDB Element

Attributes

name

The name of the VDB. The VDB name referenced through the driver or datasource during the connection time.

version

The version of the VDB. Provides an explicit versioning mechanism to the VDB name - see VDB Versioning.

Description Element

Optional text element to describe the VDB.

Connection Type Element

Determines how clients can connect to the VDB. Can be one of BY_VERSION, ANY, or NONE. Defaults to BY_VERSION. See VDB Versioning.

Properties Element

see VDB Properties for properties that can be set at VDB level.

import-vdb Element

VDBs may reuse other VDBs deployed in the same server instance by using an "import-vdb" declaration in the vdb.xml file. An imported VDB can have it’s tables and procedures referenced by views and procedures in the importing VDB as if they are part of the VDB. Imported VDBs are required to exist before an importing VDB may start. If an imported VDB is undeployed, then any importing VDB will be stopped.+

An imported VDB includes all of its models and may not conflict with any model, data policy, or source already defined in the importing VDB. Once a VDB is imported it is mostly operationally independent from the base VDB. Only cost related metadata may be updated for an object from an imported VDB in the scope of the importing VDB. All other updates must be made through the original VDB, but they will be visible in all imported VDBs. Even materialized views are separately maintained for an imported VDB in the scope of each importing VDB.

Example reuse VDB XML

<vdb name="reuse" version="1">
    <import-vdb name="common" version="1" import-data-policies="false"/>
    <model visible="true" type="VIRTUAL" name="new-model">
         <metadata type = "DDL"><![CDATA[
              CREATE VIEW x (
                y varchar
                ) AS
                  select * from old-model.tbl;
         ]]>
         </metadata>
    </model>
</vdb>

Attributes

name

The name of the VDB to be imported.

version

The version of the VDB to be imported (should be an positive integer).

import-data-policies

Optional attribute to indicate whether the data policies should be imported as well. Defaults to "true".

Model Element

Attributes

name

The name of the model is used as a top level schema name for all of the metadata imported from the connector. The name should be unique among all Models in the VDB and should not contain the '.' character.

visible

By default this value is set to "true", when the value is set to "false", this model will not be visible to when JDBC metadata queries. Usually it is used to hide a model from client applications that should not directly issue queries against it. However, this does not prohibit either client application or other view models using this model, if they knew the schema for this model.

Property Elements

All properties are available as extension metadata on the corresponding Schema object that is accessible via the metadata API.

cache-metadata

Can be "true" or "false". defaults to "false" for -vdb.xml deployments otherwise "true". If "false", Teiid will obtain metadata once for every launch of the vdb. "true" will save a file containing the metadata into the PROFILE/data/teiid directory Can be used to override the vdb level cache-metadata property.

teiid_rel:DETERMINISM

Can be one of: DETERMINISM NONDETERMINISTIC COMMAND_DETERMINISTIC SESSION_DETERMINISTIC USER_DETERMINISTIC VDB_DETERMINISTIC DETERMINISTIC

Will influence the cache scope for result set cache entries formed from accessing this model. Alternatively the scope may be influenced through the Translator API or via table/procedure extension metadata.

Source Element

A source is a named binding of a translator and connection source to a model.

name

The name of the source to use for this model. This can be any name you like, but will typically be the same as the model name. Having a name different than the model name is only useful in multi-source scenarios. In multi-source, the source names under a given model must be unique. If you have the same source bound to multiple models it may have the same name for each. An exception will be raised if the same source name is used for different sources.

translator-name

The name or type of the Teiid Translator to use. Possible values include the built-in types (ws, file, ldap, oracle, sqlserver, db2, derby, etc.) and translators defined in the translators section.

connection-jndi-name

The JNDI name of this source’s connection factory. There should be a corresponding datasource that defines the connection factory in the JBoss AS. Check out the deploying VDB dependencies section for info. You also need to define these connection factories before you can deploy the VDB.

Property Elements

importer.<propertyname>

Property to be used by the connector importer for the model for purposes importing metadata. See possible property name/values in the Translator specific section. Note that using these properties you can narrow or widen the data elements available for integration.

Metadata Element

The optional metadata element defines the metadata repository type and optional raw metadata to be consumed by the metadata repository.

type

The metadata repository type. Defaults to INDEX for Designer VDBs and NATIVE for non-Designer VDB source models. For all other deployments/models a value must be specified. Built-in types include DDL, NATIVE, INDEX, and DDL-FILE. The usage of the raw text varies with the by type. NATIVE and INDEX (only for Designer VDBs) metadata repositories do not use the raw text. The raw text for DDL is expected to be be a series of DDL statements that define the schema. Note that, since <model> element means schema, you only use linke:DDL_Metadata.adoc[Schema Object DDL]. Rest of DDL statements can NOT be used in the artifact mode, as those constructs are defined by the XML file. Like <Model> element is similar to "CREATE SCHEMA …". Due to backwards compatibility Teiid supports both modes as both have their advantages.

DDL-FILE (used only with zip deployments) is similar to DDL, except that the raw text specifies an absolute path relative to the vdb root of the location of a file containing the DDL. See Metadata Repositories for more information and examples

Translator Element

Attributes

name

The name of the the Translator. Referenced by the source element.

type

The base type of the Translator. Can be one of the built-in types (ws, file, ldap, oracle, sqlserver, db2, derby, etc.).

Property Elements

Set a value that overrides a translator default property. See possible property name/values in the Translator specific section.

VDB Reuse

VDBs may reuse other VDBs deployed in the same server instance by using an "import-vdb" declaration. An imported VDB can have it’s tables and procedures referenced by views and procedures in the importing VDB as if they are part of the VDB. Imported VDBs are required to exist before an importing VDB may start. If an imported VDB is undeployed, then any importing VDB will be stopped.

Example reuse VDB XML

<vdb name="reuse" version="1">

    <property name="imported-model.visible" value="false"/>

    <import-vdb name="common" version="1" import-data-policies="false"/>

    <model visible="true" type="VIRTUAL" name="new-model">
         <metadata type = "DDL"><![CDATA[
              CREATE VIEW x (
                y varchar
                ) AS
                  select * from imported-model.tbl;
         ]]>
         </metadata>
    </model>
</vdb>

In the above example the reuse VDB will have access to all of the models defined in the common VDB and adds in the "new-model". The visibility of imported models may be overridden via boolean vdb properties using the key model.visible - shown above as imported-model.visible with a value of false.

Using XML & DDL

XML VDB

XML File Deployment

XML File Format

VDB Element

import-vdb Element

Model Element

Translator Element

VDB Reuse

results matching ""

No results matching ""