table of contentsteiid.github.io/teiid-documents/9.0.x/teiid-documents.pdfreference guide data...

1.1

1.2

1.3

1.3.1

1.3.2

1.3.2.1

1.3.2.1.1

1.3.2.1.2

1.3.2.1.3

1.3.2.1.4

1.3.2.1.5

1.3.2.1.6

1.3.2.1.7

1.3.2.1.8

1.3.2.1.9

1.3.2.1.10

1.3.2.1.11

1.3.2.1.12

1.3.2.1.13

1.3.2.1.14

1.3.2.1.14.1

1.3.2.1.14.2

1.3.2.1.15

1.3.2.2

1.3.3

1.3.4

1.3.5

1.3.6

1.3.6.1

1.3.6.2

1.3.6.3

1.3.6.4

1.3.6.5

1.3.6.6

1.3.7

1.3.8

1.3.8.1

TableofContentsIntroduction

LegalNotice

Administrator’sGuide

InstallationGuide

DeployingVDBs

DeployingVDBDependencies

AccumuloDataSources

AmazonSimpleDBDataSources

CassandraDataSources

FileDataSources

GoogleSpreadsheetDataSources

InfinispanLibraryModeDataSources

InfinispanHotRodDataSources

JDBCDataSources

LDAPDataSources

MongoDBDataSources

PhoenixDataSources

SalesforceDataSources

SolrDataSources

WebServiceDataSources

KerberoswithRESTbasedServices

OAuthAuthenticationWithRESTBasedServices

CoherenceDataSources

VDBVersioning

Logging

ClusteringinTeiid

Monitoring

PerformanceTuning

MemoryManagement

Threading

CacheTuning

SocketTransports

LOBs

OtherConsiderations

TeiidConsole

AdminShell

GettingStarted

1

1.3.8.2

1.3.8.3

1.3.8.4

1.3.8.5

1.3.8.6

1.3.9

1.3.10

1.3.11

1.3.12

1.3.13

1.4

1.4.1

1.4.2

1.4.2.1

1.4.2.2

1.4.3

1.4.4

1.4.5

1.4.6

1.5

1.5.1

1.5.2

1.5.2.1

1.5.3

1.5.4

1.5.5

1.5.5.1

1.5.5.2

1.5.5.3

1.5.5.4

1.5.6

1.5.6.1

1.5.6.2

1.5.6.3

1.5.6.4

1.5.7

1.5.7.1

1.5.7.1.1

1.5.7.1.2

1.5.7.1.3

Executingascriptfile

LogFileandRecordedScriptfile

DefaultConnectionProperties

HandlingMultipleConnections

InteractiveShellNuances

OtherScriptingEnvironments

SystemProperties

TeiidManagementCLI

DiagnosingIssues

MigrationGuideFromTeiid8.x

CachingGuide

ResultsCaching

MaterializedViews

ExternalMaterialization

InternalMaterialization

CodeTableCaching

TranslatorResultsCaching

HintsandOptions

ProgrammaticControl

ClientDeveloper’sGuide

Reauthentication

ExecutionProperties

XMLextensions

SETStatement

SHOWStatement

Transactions

LocalTransactions

RequestLevelTransactions

UsingGlobalTransactions

Restrictions

ODBCSupport

InstallingtheODBCDriverClient

ConfiguringtheDataSourceName(DSN)

DSNLessConnection

ODBCConnectionProperties

JDBCSupport

ConnectingtoaTeiidServer

DriverConnection

DataSourceConnection

StandaloneApplication

2

1.5.7.1.4

1.5.7.1.5

1.5.7.1.6

1.5.7.1.7

1.5.7.2

1.5.7.3

1.5.7.4

1.5.7.4.1

1.5.7.4.2

1.5.7.4.3

1.5.7.4.4

1.5.7.4.5

1.5.7.5

1.5.7.5.1

1.5.7.5.2

1.5.8

1.5.8.1

1.5.8.2

1.5.9

1.5.10

1.6

1.6.1

1.6.1.1

1.6.1.1.1

1.6.1.1.2

1.6.1.2

1.6.1.2.1

1.6.1.3

1.6.1.3.1

1.6.1.4

1.6.2

1.6.2.1

1.6.2.1.1

1.6.2.1.2

1.6.2.2

1.6.2.2.1

1.6.2.2.2

1.6.2.2.3

1.6.2.2.4

1.6.2.2.5

WildFlyDataSource

UsingMultipleHosts

SSLClientConnections

AdditionalSocketClientSettings

PreparedStatements

ResultSetLimitations

JDBCExtensions

StatementExtensions

PartialResultsMode

blockingStatementExecution

ResultSetExtensions

ConnectionExtensions

UnsupportedJDBCMethods

UnsupportedClassesandMethodsin"java.sql"

UnsupportedClassesandMethodsin"javax.sql"

ODataSupport

ODataVersion2.0Support


UsingTeiidwithHibernate

UsingTeiidwithEclipseLink

Developer’sGuide

DevelopingJEEConnectors

ConnectorEnvironmentSetup

BuildEnvironment

ArchetypeTemplateConnectorProject

ImplementingtheTeiidFramework

ra.xmlfileTemplate

PackagingtheAdapter

AddingDependentLibraries

DeployingtheAdapter

TranslatorDevelopment

EnvironmentSetup

Settingupthebuildenvironment

ArchetypeTemplateTranslatorProject

ImplementingtheFramework

CachingAPI

CommandLanguage

ConnectionstoSource

DependentJoinPushdown

ExecutingCommands

3

1.6.2.2.6

1.6.2.2.7

1.6.2.2.8

1.6.2.2.9

1.6.2.3

1.6.2.4

1.6.2.5

1.6.2.5.1

1.6.2.6

1.6.3

1.6.3.1

1.6.3.2

1.6.4

1.6.5

1.6.6

1.6.7

1.6.8

1.7

1.7.1

1.7.2

1.8

1.8.1

1.8.2

1.8.2.1

1.8.2.2

1.8.2.3

1.8.2.4

1.8.2.4.1

1.8.2.4.2

1.8.2.4.3

1.8.2.4.4

1.8.2.4.5

1.8.2.4.6

1.8.2.4.7

1.8.2.4.8

1.8.2.4.9

1.8.2.4.10

1.8.2.4.11

1.8.2.4.12

1.8.2.4.13

ExtendingtheExecutionFactoryClass

LargeObjects

TranslatorCapabilities

TranslatorProperties

ExtendingTheJDBCTranslator

DelegatingTranslator

Packaging

AddingDependentModules

Deployment

UserDefinedFunctions

SourceSupportedFunctions

SupportforUser-DefinedFunctions(Non-Pushdown)

AdminAPI

CustomLogging

RuntimeUpdates

CustomMetadataRepository

PreParser

EmbeddedGuide

LogginginTeiidEmbedded

SecureEmbeddedwithPicketBox

ReferenceGuide

DataSources

SQLSupport

Identifiers

Expressions

Criteria

ScalarFunctions

NumericFunctions

StringFunctions

Date_TimeFunctions

TypeConversionFunctions

ChoiceFunctions

DecodeFunctions

LookupFunction

SystemFunctions

XMLFunctions

JSONFunctions

SecurityFunctions

SpatialFunctions

MiscellaneousFunctions

4

1.8.2.4.14

1.8.2.5

1.8.2.5.1

1.8.2.5.2

1.8.2.5.3

1.8.2.5.4

1.8.2.5.5

1.8.2.5.5.1

1.8.2.5.5.2

1.8.2.5.5.3

1.8.2.5.5.4

1.8.2.5.6

1.8.2.5.7

1.8.2.5.8

1.8.2.5.9

1.8.2.5.10

1.8.2.5.11

1.8.2.5.12

1.8.2.6

1.8.2.6.1

1.8.2.6.2

1.8.2.6.3

1.8.2.6.4

1.8.2.7

1.8.2.7.1

1.8.2.7.2

1.8.2.8

1.8.2.8.1

1.8.2.8.2

1.8.2.8.3

1.8.2.9

1.8.3

1.8.3.1

1.8.3.2

1.8.3.3

1.8.3.4

1.8.4

1.8.4.1

1.8.5

1.8.5.1

NondeterministicFunctionHandling

DMLCommands

SetOperations

Subqueries

WITHClause

SELECTClause

FROMClause

XMLTABLE

ARRAYTABLE

OBJECTTABLE

TEXTTABLE

WHEREClause

GROUPBYClause

HAVINGClause

ORDERBYClause

LIMITClause

INTOClause

OPTIONClause

DDLCommands

TempTables

AlterView

AlterProcedure

AlterTrigger

XMLSELECTCommand

QueryStructure

DocumentGeneration

Procedures

ProcedureLanguage

VirtualProcedures

UpdateProcedures

Comments

Datatypes

SupportedTypes

TypeConversions

SpecialConversionCases

EscapedLiteralSyntax

UpdatableViews

preservedTable

TransactionSupport

AutoCommitTxnExecutionProperty

5

1.8.5.2

1.8.5.3

1.8.5.4

1.8.5.5

1.8.6

1.8.6.1

1.8.6.2

1.8.6.3

1.8.6.4

1.8.7

1.8.7.1

1.8.7.2

1.8.8

1.8.8.1

1.8.8.2

1.8.8.3

1.8.8.4

1.8.8.5

1.8.8.6

1.8.8.7

1.8.9

1.8.9.1

1.8.9.2

1.8.9.3

1.8.9.4

1.8.9.5

1.8.9.6

1.8.9.7

1.8.9.8

1.8.9.9

1.8.9.10

1.8.9.11

1.8.9.11.1

1.8.9.11.2

1.8.9.11.3

1.8.9.11.4

1.8.9.11.5

1.8.9.11.6

1.8.9.11.7

1.8.9.11.8

UpdatingModelCount

JDBCandTransactions

TransactionalBehaviorwithJBossDataSourceTypes

LimitationsandWorkarounds

DataRoles

Permissions

RoleMapping

XMLDefinition

Customizing

SystemSchema

SYS

SYSADMIN

VDBs

VDBDefinition

VDBsWithoutTooling

MultisourceModels

DDLMetadata

VDBReuse

RESTServiceThroughVDB

MetadataRepositories

Translators

AmazonSimpleDBTranslator

ApacheAccumuloTranslator

ApacheSOLRTranslator

CassandraTranslator

CoherenceCacheTranslator

DelegatingTranslators

FileTranslator

GoogleSpreadsheetTranslator

InfinispanHotRodTranslator

InfinispanLibraryModeTranslator

JDBCTranslators

ActianVectorTranslator

ApacheHBaseTranslator

ClouderaImpalaTranslator

DB2Translator

DerbyTranslator

GreenplumTranslator

H2Translator

HiveTranslator

6

1.8.9.11.9

1.8.9.11.10

1.8.9.11.11

1.8.9.11.12

1.8.9.11.13

1.8.9.11.14

1.8.9.11.15

1.8.9.11.16

1.8.9.11.17

1.8.9.11.18

1.8.9.11.19

1.8.9.11.20

1.8.9.11.21

1.8.9.11.22

1.8.9.11.23

1.8.9.11.24

1.8.9.11.25

1.8.9.11.26

1.8.9.11.27

1.8.9.11.28

1.8.9.11.29

1.8.9.11.30

1.8.9.11.31

1.8.9.11.32

1.8.9.12

1.8.9.13

1.8.9.14

1.8.9.15

1.8.9.16

1.8.9.17

1.8.9.18

1.8.9.19

1.8.9.20

1.8.9.21

1.8.9.22

1.8.9.23

1.8.9.24

1.8.10

1.8.10.1

1.8.10.2

HSQLTranslator

InformixTranslator

IngresTranslators

IntersystemsCacheTranslator

JDBCANSITranslator

JDBCSimpleTranslator

MetaMatrixTranslator

MicrosoftAccessTranslators

MicrosoftExcel-ODBCTranslator

MicrosoftSQLServerTranslator

ModeShapeTranslator

MySQLTranslators

NetezzaTranslator

OracleTranslator

OSISoftPITranslator

PostgreSQLTranslator

PrestoDBTranslator

RedshiftTranslator

SAPHanaTranslator

SybaseIQTranslator

SybaseTranslator

TeiidTranslator

TeradataTranslator

VerticaTranslator

JPATranslator

LDAPTranslator

LoopbackTranslator

MicrosoftExcelTranslator

MongoDBTranslator

ObjectTranslator

ODataTranslator

ODataV4Translator

SwaggerTranslator

OLAPTranslator

SalesforceTranslators

SAPGatewayTranslator

WebServicesTranslator

FederatedPlanning

PlanningOverview

QueryPlanner

7

1.8.10.3

1.8.10.4

1.8.10.5

1.8.10.6

1.8.10.7

1.8.10.8

1.8.11

1.8.11.1

1.8.11.2

1.8.11.3

1.8.11.4

1.8.12

1.9

1.9.1

1.9.2

1.9.3

1.9.4

1.9.5

1.9.6

1.9.7

1.9.8

1.9.9

QueryPlans

FederatedOptimizations

SubqueryOptimization

XQueryOptimization

FederatedFailureModes

ConformedTables

Architecture

Terminology

DataManagement

QueryTermination

Processing

BNFforSQLGrammar

SecurityGuide

LoginModules

TeiidServerTransportSecurity

JDBC/ODBCSSLconnectionusingself-signedSSLcertificates

DataSourceSecurity

KerberossupportthroughGSSAPI

CustomAuthorizationValidator

SAMLBasedSecurityForOData

OAuth2BasedSecurityForODataUsingKeyCloak

SAMLBasedSecurityForODataUsingKeyCloak

8

LegalNotice

ContributetoTeiidDocumentation

Thepagesthemselveshavecommentingenabled.Youshouldbeabletoclickonanytextareatoaddacomment.

ThedocumentationprojectishostedonGitHubat(teiid/teiid-documents).

ForsimplechangesyoucanjustusetheonlineeditingcapabilitiesofGitHubbynavigatingtotheappropriatesourcefileandselectingfork/edit.

Forlargerchangesfollowthese3steps:

Step.1clonethesources

[email protected]:teiid/teiid-documents.git

Step.2doedit

Useanytexteditortoedittheadocfiles,AsciiDocSyntaxQuickReferencecanhelpyouinAsciiDocSyntax.

Step.3submityourchange

Onceyoufinishedthissteps,thecontentofdocumentswillupdatedautomatically.

Testlocally

Youmayneedtestlocally,tomakesurethechangesarecorrect,todothisinstallgitbook,thenexecutethefollowingcommandsfromthecheckoutlocation:

$gitbookinstall

$gitbookserve-w

Onceabovecommandsexecutessuccessfully,thehttpformatdocumentcanbetestlocallyviahttp://localhost:4000/.

Introduction

9

https://github.com/teiid/teiid-documents

http://asciidoctor.org/docs/asciidoc-syntax-quick-reference/

https://teiid.gitbooks.io/documents/content/

https://github.com/GitbookIO/gitbook

Generatehtml/pdf/epub/mobi

Youmaylocallycreaterenderedformsofthedocumentation.Todothisinstallgitbookandebook-convert,thenexecutethefollowingcommandsfromthecheckoutlocation:

$gitbookbuild./teiid-documents

$gitbookpdf./teiid-documents.pdf

$gitbookepub./teiid-documents.epub

$gitbookmobi./teiid-documents.mobi

Onceabovecommandsexecutessuccessfully,theteiid-documentsfolder,teiid-documents.pdf,teiid-documents.epub,andteiid-documents.mobiwillbegenerated.

Introduction

10

https://github.com/GitbookIO/gitbook

https://help.gitbook.com/build/ebookconvert.html

LegalNotice

1801VarsityDriveRaleigh,NC27606-2072USAPhone:+19197543700Phone:8887334281Fax:+19197543701POBox13588ResearchTrianglePark,NC27709USA

Copyright©2016byRedHat,Inc.Thiscopyrightedmaterialismadeavailabletoanyonewishingtouse,modify,copy,orredistributeitsubjecttothetermsandconditionsoftheGNULesserGeneralPublicLicense,aspublishedbytheFreeSoftwareFoundation.

RedHatandtheRedHat"ShadowMan"logoareregisteredtrademarksofRedHat,Inc.intheUnitedStatesandothercountries.

Allothertrademarksreferencedhereinarethepropertyoftheirrespectiveowners.

[email protected]:

CA2086862BD69DFC65F6ECC4219180CDDB42A60E

LegalNotice

11

mailto:[email protected]

Administrator’sGuideThisguideisintendedforanyuserwhoassumesroleofadeveloper/administratorofTeiidinstance.ThisguideguidesuserthroughinstallationofTeiidServer,configurationofdifferentservicesanddeploymentofTeiidartifactssuchasVDBs.BeforeonecandelveintoTeiiditisveryimportanttolearnfewbasicconstructsofTeiid,likewhatisVDB?whatisModel?etc.Forthatpleasereadtheshortintroductionherehttp://teiid.jboss.org/basics/

Administrator’sGuide

12

http://teiid.jboss.org/basics/

InstallationGuideTeiidneedstobeinstalledintoanexistingWildFly9.0.2installation.

Note Teiidprovidesanembeddedkit,howeveritshouldbeconsideredatechpreviewasitsAPIswilllikelyevolveandthereissparsedocumentation.

StepstoinstallTeiid

DownloadtheWildFlyapplicationserver.Installtheserverbyunzippingintoaknownlocation.Ex:/apps/jboss-install

Note YoumayalsochoosetouseanexistingASinstallation.HoweverifapreviousversionofTeiidwasalreadyinstalled,youmustremovetheoldTeiiddistributionartifactsbeforeinstallingthenewversion.

DownloadTeiid.UnzipthedownloadedartifactinsidetheWildFlyinstallation.Teiid9.0directorystructurematchesWildFlydirectly-itisjustanoverlay.ThiswilladdnecessarymodulesandconfigurationfilestoinstallTeiidinWildFly9.0.2inbothStandaloneandDomainmodes.Teiidprovidesseparateconfigurationfilesforbothstandalonemodeanddomainmode.BasedonmodetypeyouselectedtorunWildFly9.0.2,youmayhavetorunaCLIscripttocompletetheTeiidinstallation.

The"Domain"moderecommendedinaclusteredenvironmenttotakeadvantageofclusteredcachingandclustersafedistributionofevents.Teiid’sdefaultconfigurationforDomainmodethroughCLIscriptconfiguredforhighavailabilityandclusteredcaching.

StandaloneMode

ifyouwanttostartthe"standalone"profile,executethefollowingcommand

<jboss-install>/bin/standalone.sh-c=standalone-teiid.xml

InstallingTeiidusingCLIscript

TheaboveisstartingWildFlyinaseparateTeiidspecificconfigurationthatisbasedstandalone.xml.However,ifyoualreadyworkingwithapredefinedconfigurationforexampledefaultstandalone.xmlandwouldliketoinstallTeiidintothatconfiguration,thenyoucanexecutethefollowingJBossCLIscript.First,starttheserver

<jboss-install>/bin/standalone.sh

theninaseparateconsolewindowexecute

<jboss-install>/bin/jboss-cli.sh--file=bin/scripts/teiid-standalone-mode-

install.cli

thiswillinstallTeiidsubsystemintotherunningconfigurationoftheWildFly9.0.2instandalonemode.

DomainMode

Tostarttheserverin"Domain"mode,installWildFly9.0.2andTeiid9.0onalltheserversthataregoingtobepartofthecluster.Selectoneoftheserversasthe"master"domaincontroller,therestoftheserverswillbeslavesthatconnecttothe"master"domaincontrollerforalltheadministrativeoperations.PleaserefertoWildFly9.0.2provideddocumentationforfulldetails.

InstallationGuide

13

http://wildfly.org/downloads/

http://www.jboss.org/teiid/downloads.html

https://docs.jboss.org/author/display/WFLY9/WildFly+9+Cluster+Howto

Onceyouconfiguredalltheservers,startthe"master"nodewithfollowingcommand

<jboss-install>/bin/domain.sh

andon"slave"nodes

<jboss-install>/bin/domain.sh

Theslavenodesfetchtheirdomainconfigurationfromthe"master"node.

Oncealltheserversareup,completetheinstallationtorunindomainmodebyexecutingthefollowingcommandagainstthe"master"node.Notethatthisonlyneedstoberunonceperdomain(i.e.cluster)install.ThisscriptwillinstallTeiidintheHAprofile.Itwillalsore-configuremain-server-grouptostarttheHAprofile.Onceindomainmode,youcannotstaticallydeployresourcesbydroppingtheminthedomain/deploymentsfolder,sothisscriptwilldeploythedefaultresources(file,ldap,salesforceandwsconnectors)usingtheCLIinterface.

<jboss-install>/bin/jboss-cli.sh--file=scripts/teiid-domain-mode-install.cli

NoteInstalling"Teiid"inotherprofiles-IfTeiidneedstobeinstalledinprofilesotherthanHA,beforeexecutingedittheteiid-domain-mode-install.clifile,makingtheappropriatechangestoprofile,socket-bindings,andserver-groups.

Thatsit!.WildFlyandTeiidarenowinstalledandrunning.Seebelowinstructionstocustomizevariousothersettings.

OnceVDBshavebeendeployed,userscannowconnecttheirJDBCapplicationstoTeiid.IfyouneedhelponconnectingyourapplicationtoTeiidusingJDBCcheckouttheClientDeveloper’sGuide.

DirectoryStructureExplained

ThisshowsthecontentsoftheTeiid9.0deployment.ThedirectorystructureisexactlythesameunderanyJBossprofile.

DirectoryStructure

/bin

/scripts

/docs

/teiid

/datsources

/schema

/examples

/domain

/configuration

/modules

/system

/layers

/base

/org/jboss/teiid/*

/standalone

/configuration

standalone-teiid.xml

InstallationGuide

14

Name Description

bin/scripts ContainsinstallationandutilityCLIscriptsforsettingupTeiidindifferentconfigurations.

docs/teiid Containsdocuments,examples,sampledatasourceXMLfragmentsandschemafiles.

/standalone/configurationstandalone-teiid.xml-MasterconfigurationfilefortheTeiidsystem.ThisfilecontainstheTeiidsubsystem,inadditiontothestandardWildFlywebprofilesubsystems

/domain/configuration/ -

/modules/system/layers/base/org/jboss/teiid/* ThisdirectorycontainstheTeiidmodulesforWildFly9.0.2system

/modules/system/layers/base/org/jboss/teiid/client

ThisdirectorycontainsTeiidclientlibraries.IthastheTeiidJDBCdriverjar,"teiid-9.0.0.Final-jdbc.jar",andalsocontains"teiid-hibernate-dialect-9.0.0.Final.jar"thatcontainsTeiid’sHibernatedialect.

\{standaloneordomain}/tmp/teiid

Thisdirectoryunderstandaloneordomain,containstemporaryfilescreatedbyTeiid.Thesearemostlycreatedbythebuffermanager.ThesefilesarenotneededacrossaVMrestart.CreationofTeiidlobvalues(forexamplethroughSQL/XML)willtypicallycreateonefileperlobonceitexceedstheallowableinmemorysizeof8KB.Inheavyusagescenarios,considerpointingthebufferdirectoryatapartitionthatisroutinelydefragmented.

\{standaloneordomain}/data/teiid-data Thisdirectoryunderstandaloneordomain,containscachedvdbmetadatafiles.Donoteditthemmanually.

InstallationGuide

15

DeployingVDBsAVDBistheprimarymeanstodefineaVirtualDatabaseinTeiid.AusercancreateaVDBusingTeiidDesigner-http://www.jboss.org/teiiddesigner/-orfollowtheinstructionsintheReferenceGuidetocreateaVDBwithoutTeiidDesigner.

Onceyouhavea"VDB"builtitcanbedeployed/undeployedinTeiidruntimeindifferentways.

WarningIfVDBversioningisnotusedtogivedistinctversionnumbers,overwritingaVDBofthesamenamewillterminateallconnectionstotheoldVDB.ItisrecommendedthatVDBversioningbeusedforproductionsystems.

Caution RemovinganexistingVDBwillimmediatelycleanupVDBfileresources,andwillautomaticallyterminateexistingsessions.

CautionTheruntimenamesofdeployedVDBartifactsmusteitherbe*.vdbforazipfileor*-vdb.xmlforanxmlfile.FailuretonamethedeploymentproperlywillresultinadeploymentfailureastheTeiidsubsystemwillnotknowhowtoproperlyhandletheartifact.

DirectFileDeploymentCopytheVDBfileintothe

<jboss-install>/standalone/deployments

directory.ThencreateanemptymarkerfilewithsamenameastheVDBwithextension".dodeploy"inthesamedirectory.Forexample,ifyourvdbnameis"enterprise.vdb",thenmarkerfilenamemustbe"enterprise.vdb.dodeploy".MakesurethattherearenootherVDBfileswiththesamename.IfaVDBalreadyexistswiththesamename,thenthisVDBwillbereplacedwiththenewVDB.ThisisthesimplestwaytodeployaVDB.Thisismostlydesignedforquickdeploymentduringdevelopment,whentheTeiidserverisavailablelocallyonthedeveloper’smachine.

Note ThisonlyworksintheStandalonemode.ForDomainmode,youmustuseoneoftheotheravailablemethods.

AdminConsoleDeployment(Web)Usetheadminwebconsoleat:

http://<host>:<port>/console

MoredetailsforthiscanbefoundintheAdminConsoleVDBdeploymentsection.ThisistheeasiestwaytodeployaVDBtoaremoteserver.

CLIbasedDeployment

~~

WildFly9.0.2providescommandlineinterface(CLI)fordoinganykindofadministrativetask.Execute

bin/jboss-cli.sh--connect

~~~~~~

DeployingVDBs

16

http://www.jboss.org/teiid/basics/virtualdatabases.html

http://www.jboss.org/teiiddesigner/

commandandrun

#instandalonemode

deploy/path/to/my.vdb

#indomainmode

deploy/path/to/my.vdb--server-groups=main-server-group

todeploytheVDB.Notethatindomainmode,youneedtoeitherselectaparticular"server-group"orallavailableservergroupsaredeploymentoptions.CheckoutCLIdocumentationformoregeneralusageoftheCLI.

AdminShellDeploymentTeiidprovidesagroovybasedAdminShellscriptingtool,whichcanbeusedtodeployaVDB.Seethe"deploy"method.ConsulttheAdminShelldocumentationformoreinformation.NotethatusingtheAdminShellscripting,youcanautomatedeploymentofartifactsinyourenvironment.WhenusingAdminShell,indomainmode,theVDBisdeployedtoalltheavailableservers.

AdminAPIDeploymentTheAdminAPI(lookinorg.teiid.adminpi.*)providesJavaAPImethodsthatletsauserconnecttoaTeiidruntimeanddeployaVDB.IfyouneedtoprogramaticallydeployaVDBusethismethod.ThismethodispreferableforOEMusers,whoaretryingtoextendtheTeiid’scapabilitiesthroughtheirapplications.WhenusingAdminAPI,indomainmode,theVDBisdeployedtoalltheservers.

DeployingVDBs

17

https://docs.jboss.org/author/display/WFLY9/Admin+Guide

DeployingVDBDependenciesApartfromdeployingtheVDB,theuserisalsoresponsibleforprovidingallthenecessarydependentlibraries,configurationforcreatingthedatasourcesthatareneededbythemodels(schemas)definedin"META-INF/vdb.xml"fileinsideyourVDB.Forexample,ifyouaretryingtointegratedatafromOracleRDBMSandFilesourcesinyourVDB,thenyouareresponsibleforprovidingtheJDBCdriverfortheOraclesourceandanynecessarydocumentsandconfigurationthatareneededbytheFileTranslator.

DatasourceinstancesmaybeusedbysingleVDB,ormaybesharedwithasotherVDBsorotherapplications.Considersharingconnectionstodatasourcesthathaveheavy-weightandresourceconstrained.

WiththeexceptionofJDBCsources,othersupporteddatasourceshaveacorrespondingJCAconnectorintheTeiidkit.Eitherdirectlyeditthestandalone-teiid.xmloruseCLItocreatetherequireddatasourcesbytheVDB.Exampleconfigurationsareprovidedforallthesourcesin"<jboss-install>/docs/teiid/datasources"directory.NotethatintheDomainmode,youmustuseCLIoradmin-consoleorAdminShelltoconfigurethedatasources.

Somedatasourcesmaycontainpasswordsorothersensitiveinformation.SeetheWIKIarticleEncryptingDataSourcePasswordstonotstorepasswordsinplaintext.

OncetheVDBanditsdependenciesaredeployed,thenclientapplicationscanconnectusingtheJDBCAPI.Ifthereareanyerrorsinthedeployment,aconnectionattemptwillnotbesuccessfulandamessagewillbelogged.Youcanusetheadmin-consoletoolorcheckthelogfilesforerrorsandcorrectthembeforeproceeding.CheckClientDeveloper’sGuideonhowtouseJDBCtoconnecttoyourVDB.


18

https://community.jboss.org/wiki/JBossAS7SecuringPasswords

ApacheAccumuloDataSourcesAccumulodatasourcesuseaTeiidspecificJCAconnectorthatisdeployedintoWildFly9.0.2duringinstallation.TherearemanywaystocreateaAccumulodatasource,usingCLI,AdminShell,admin-console,etc.TheexampleshownbelowusestheCLItool,asthisworksinbothStandaloneandDomainmodes.

ExecutethefollowingcommandusingtheCLIonceyouconnectedtotheServer.MakesureyouprovidethecorrectURLandusercredentials.Addanyadditionalpropertiesrequiredbytheconnectorbyduplicatingthe"connection-definitions"commandbelow.EdittheJNDInametomatchtheJNDInameyouusedinVDB.

batch

/subsystem=resource-adapters/resource-adapter=accumulo/connection-definitions=teiid:add(jndi-name=java:/accumul

o-ds,class-name=org.teiid.resource.adapter.accumulo.AccumuloManagedConnectionFactory,enabled=true,use-java-c

ontext=true)

/subsystem=resource-adapters/resource-adapter=accumulo/connection-definitions=teiid/config-properties=ZooKeeper

ServerList:add(value=localhost:2181)

/subsystem=resource-adapters/resource-adapter=accumulo/connection-definitions=teiid/config-properties=Username:

add(value=user)

/subsystem=resource-adapters/resource-adapter=accumulo/connection-definitions=teiid/config-properties=Password:

add(value=password)

/subsystem=resource-adapters/resource-adapter=accumulo/connection-definitions=teiid/config-properties=InstanceN

ame:add(value=instancename)

/subsystem=resource-adapters/resource-adapter=accumulo/connection-definitions=teiid/config-properties=Roles:add

(value=public)

/subsystem=resource-adapters/resource-adapter=accumulo:activate

runbatch

AllthepropertiesthataredefinedontheRARfileare

PropertyName Description Required Default

ZooKeeperServerList

Acommaseparatedlistofzookeeperserverlocations.Eachlocationcancontainanoptionalport,oftheformathost:port

true none

Username ConnectionUser’sName true none

Password ConnectionUser’spassword true none

InstanceName Accumuloinstancename true none

Rolesoptionalvisibilityforuser,supplymultiplewithcommaseparated

false none

TofindoutallthepropertiesthataresupportedbythisAccumuloConnectorexecutethefollowingcommandintheCLI.

/subsystem=teiid:read-rar-description(rar-name=accumulo)

Tip

Developer’sTip-IfWildFly9.0.2isrunninginstandalonemode,youcanalsomanuallyeditthe"<jboss-install>/standalone/configuration/standalone-teiid.xml"fileandaddtheXMLconfigurationdefinedin"<jboss-install>/docs/teiid/datasources/accumulo"directoryunder"resource-adapters"subsystem.Shutdowntheserver


19

https://docs.jboss.org/author/display/WFLY9/Admin+Guide#AdminGuide-RunningtheCLI

beforeyoueditthisfile,andrestartafterthemodificationsaredone.


20

AmazonSimpleDBDataSourcesSimpleDBdatasourcesuseaTeiidspecificJCAconnectorthatisdeployedintoWildFly9.0.2duringinstallation.TherearemanywaystocreateaSimpleDBdatasource,usingCLI,AdminShell,admin-console,etc.TheexampleshownbelowusestheCLItool,asthisworksinbothStandaloneandDomainmodes.

ExecutethefollowingcommandusingtheCLIonceyouconnectedtotheServer.Makesureyouprovidethecorrectaccesskeys.Addanyadditionalpropertiesrequiredbytheconnectorbyduplicatingthe"connection-definitions"commandbelow.EdittheJNDInametomatchtheJNDInameyouusedinVDB.

batch

/subsystem=resource-adapters/resource-adapter=simpledb/connection-definitions=simpledbDS:add(jndi-name=java:/si

mpledbDS,class-name=org.teiid.resource.adapter.simpledb.SimpleDBManagedConnectionFactory,enabled=true,use-ja

va-context=true)

/subsystem=resource-adapters/resource-adapter=simpledb/connection-definitions=simpledbDS/config-properties=Acce

ssKey:add(value=xxx)

/subsystem=resource-adapters/resource-adapter=simpledb/connection-definitions=simpledbDS/config-properties=Secr

etAccessKey:add(value=xxx)

/subsystem=resource-adapters/resource-adapter=simpledb:activate

runbatch

TofindoutallthepropertiesthataresupportedbythisSimpleDBConnectorexecutethefollowingcommandintheCLI.

/subsystem=teiid:read-rar-description(rar-name=simpledb)

Tip

Developer’sTip-IfWildFly9.0.2isrunninginstandalonemode,youcanalsomanuallyeditthe"<jboss-install>/standalone/configuration/standalone-teiid.xml"fileandaddtheXMLconfigurationdefinedin"<jboss-install>/docs/teiid/datasources/simpledb"directoryunder"resource-adapters"subsystem.Shutdowntheserverbeforeyoueditthisfile,andrestartafterthemodificationsaredone.


21


CassandraDataSourcesCassandradatasourcesuseaTeiidspecificJCAconnectorthatisdeployedintoWildFly9.0.2duringinstallation.TherearemanywaystocreateaCassandradatasource,usingCLI,AdminShell,admin-console,etc.TheexampleshownbelowusestheCLItool,asthisworksinbothStandaloneandDomainmodes.


batch

/subsystem=resource-adapters/resource-adapter=cassandra/connection-definitions=cassandraDS:add(jndi-name=java:/

cassandraDS,class-name=org.teiid.resource.adapter.cassandra.CassandraManagedConnectionFactory,enabled=true,u

se-java-context=true)

/subsystem=resource-adapters/resource-adapter=cassandra/connection-definitions=cassandraDS/config-properties=Ad

dress:add(value=127.0.0.1)

/subsystem=resource-adapters/resource-adapter=cassandra/connection-definitions=cassandraDS/config-properties=Ke

yspace:add(value=my-keyspace)

/subsystem=resource-adapters/resource-adapter=cassandra:activate

runbatch

TofindoutallthepropertiesthataresupportedbythisCassandraConnectorexecutethefollowingcommandintheCLI.

/subsystem=teiid:read-rar-description(rar-name=cassandra)

Tip

Developer’sTip-IfWildFly9.0.2isrunninginstandalonemode,youcanalsomanuallyeditthe"<jboss-install>/standalone/configuration/standalone-teiid.xml"fileandaddtheXMLconfigurationdefinedin"<jboss-install>/docs/teiid/datasources/cassandra"directoryunder"resource-adapters"subsystem.Shutdowntheserverbeforeyoueditthisfile,andrestartafterthemodificationsaredone.


22


FileDataSourcesFiledatasourcesuseaTeiidspecificJCAconnectorthatisdeployedintoWildFly9.0.2duringinstallation.Therearemanywaystocreatethefiledatasource,usingCLI,AdminShell,admin-console,etc.TheexampleshownbelowusestheCLItool,asthisworksinbothStandaloneandDomainmodes.

ExecutefollowingcommandusingtheCLIonceyouconnectedtotheServer.Makesureyouprovidethecorrectdirectorynameandotherpropertiesbelow.Addanyadditionalpropertiesrequiredbytheconnectorbyduplicatingthe"connection-definitions"commandbelow.EdittheJNDInametomatchtheJNDInameyouusedinVDB.

batch

/subsystem=resource-adapters/resource-adapter=file/connection-definitions=fileDS:add(jndi-name=java:/fileDS,cl

ass-name=org.teiid.resource.adapter.file.FileManagedConnectionFactory,enabled=true,use-java-context=true)

/subsystem=resource-adapters/resource-adapter=file/connection-definitions=fileDS/config-properties=Parentdirect

ory:add(value=/home/rareddy/testing/)

/subsystem=resource-adapters/resource-adapter=file/connection-definitions=fileDS/config-properties=AllowParentP

aths:add(value=true)

/subsystem=resource-adapters/resource-adapter=file:activate

runbatch

TofindoutallthepropertiesthataresupportedbythisFileConnectorexecutethefollowingcommandintheCLI.

/subsystem=teiid:read-rar-description(rar-name=file)

Tip

Developer’sTip-IfWildFly9.0.2isrunninginstandalonemode,youcanalsomanuallyeditthe"<jboss-install>/standalone/configuration/standalone-teiid.xml"fileandaddtheXMLconfigurationdefinedin"<jboss-install>/docs/teiid/datasources/file"directoryunder"resource-adapters"subsystem.Shutdowntheserverbeforeyoueditthisfile,andrestartafterthemodificationsaredone.


23


GoogleSpreadsheetDataSources

Authenticationtoyourgoogleaccountmaybedoneintwoways.ClientLogin(requiresloginandpassword)orOAuth(morecomplicated,requiresusertosupplyrefreshtoken).

GoogleJCAconnectorisnamedteiid-connector-google.rar.Theexamplesincludeasamplegoogle.xmlfile.TheJCAconnectorhasnumberofconfig-propertiestodriveauthentication.TheJCAconnectorconnectstoexactlyonespreadsheet.

Configproperty Description

AuthMethod MethodtoaccessGoogle.ThispropertycanonlybeOAuth2.

RefreshToken UseguidebelowtoretrieveRefreshToken.RequestaccesstoGoogleDriveandSpreadsheetAPI.

SpreadsheetName RequiredpropertywithnameoftheSpreadsheetthatisdatasourceforthisconnector.

BatchSize Maximumnumberofrowsthatcanbefetchedatatime.Defaultsto4096.

GettinganOAuthRefreshTokenUsethisrequest:

https://accounts.google.com/o/oauth2/auth?scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fdrive+https%3A%2F%2Fspreadsheets.google.com%2Ffeeds&redirect_uri=urn:ietf:wg:oauth:2.0:oob&response_type=code&client_id=217138521084.apps.googleusercontent.com

ThencopytheauthorizationcodeintofollowingPOSTrequestandrunitincommandline:

curl\--data-urlencodecode=<AUTH_CODE>\

--data-urlencodeclient_id=217138521084.apps.googleusercontent.com\

--data-urlencodeclient_secret=gXQ6-lOkEjE1lVcz7giB4Poy\

--data-urlencoderedirect_uri=urn:ietf:wg:oauth:2.0:oob\

--data-urlencodegrant_type=authorization_codehttps://accounts.google.com/o/oauth2/token

Therefreshtokenwillbeintheresponse

ImplementationDetails

GoogleTranslatorisimplementedusingGDataAPI[1](javalibraryfor[4])andGoogleVisualizationProtocol[2].AuthenticationisimplementedusingOAuth2fordevices[3].1.https://developers.google.com/google-apps/spreadsheets/2.https://developers.google.com/chart/interactive/docs/querylanguage3.https://developers.google.com/accounts/docs/OAuth2ForDevices4.https://developers.google.com/google-apps/spreadsheets


24

https://accounts.google.com/o/oauth2/auth?scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fdrive+https%3A%2F%2Fspreadsheets.google.com%2Ffeeds&redirect_uri=urn:ietf:wg:oauth:2.0:oob&response_type=code&client_id=217138521084.apps.googleusercontent.com

https://developers.google.com/google-apps/spreadsheets/

https://developers.google.com/chart/interactive/docs/querylanguage

https://developers.google.com/accounts/docs/OAuth2ForDevices

https://developers.google.com/google-apps/spreadsheets

InfinispanLibraryModeDataSourcesInfinispanLibaryModedatasourcesuseaTeiidspecificJCAconnectorthatisdeployedintoWildFly9.0.2duringinstallation.ThisconnectorhasthefollowingoptionsthatcanbeconfiguredtoaccessanInfinispancacherunninginlibrarymode:

UsingJNDI

Usingconfigurationfile

Configuration

PojoJar

Thepojoclassistheobjectthatwillbeusedtostorethedatainthecache.Itshouldbebuiltaccordingly:

Totakeadvantageofthecachebeingindexedenabled,shouldannotatetheclass.See[JDGdocumentation|https://access.redhat.com/documentation/en-US/Red_Hat_JBoss_Data_Grid/6.6/html-single/Infinispan_Query_Guide/index.html#chap-Annotating_Objects_and_Querying]

Theclassshouldbepackagedintoajarsothatitcanbedeployedasamodule

Toconfiguretheuseofthepojo,dothefollowing:

Deploythepojojarasamoduleinthejboss-asserver.Thendefinethe"lib"propertyinthe-vdb.xmlandassignthecorrectmodulename.Thiscanbedoneusingthefollowingtemplate:

<propertyname="lib"value="{pojo_module_name}"></property>

TheJDGcommonsmodule,org.infinispan.commons,slot="jdg-6.x"orslotforversioninstalled,needstohavethepojodependencyadded:

<modulename="{pojo_module_name}"export="true"/>

ReadandWritetotheCache

Thefollowingaretherequiredproperties:

PropertyName PropertyTemplate Description

CacheTypeMap cacheName:className[;pkFieldName[:cacheKeyJavaType]]

Fortheindicatedcache,maptherootJavaObjectclassname.Optionally,butrequiredforupdates,identifywhichclassattributeistheprimarykeytothecache.Identifyprimarykeyjavatypewhendifferentthanclassattributetype

ThefollowingarethepropertyoptionsfordefininghowtheCacheManagerwillbecreated/accessed:

PropertyName Req. Description


25

module N SpecifytheWildFlymodulethatcontainsthecacheclassesthatweredefinedinCacheTypeMap

CacheJndiName N JNDInametofinetheCacheContainer

ConfigurationFileNameForLocalCache N TheInfinispanConfigurationxmlfileforconfiguringalocalcache

UsingCacheforExternalMaterialization

ThefollowingaretheadditionalpropertiesthatneedtobeconfiguredifusingtheRemoteCacheforexternalmaterialization:


StagingCacheName Y Cachenameforthestagingcacheusedinmaterialization

AliasCacheName YCachenameforthealiascacheusedintrackingaliasingofthecachesusedinmaterialization

ServerConfiguration

Therearemanywaystocreatethedatasource;usingCLI,AdminShell,admin-consoleetc.TheexampleshownbelowusestheCLItool,asthisworksinbothStandaloneandDomainmodes.

ExecutefollowingcommandusingCLIonceyouconnectedtotheServer.Makesureyouprovidethecorrectdirectorynameandotherpropertiesbelow.Addanyadditionalpropertiesrequiredbytheconnectorbyduplicatingthe"connection-definitions"commandbelow.EdittheJNDInametomatchtheJNDInameyouusedinVDB.

batch

/subsystem=resource-adapters/resource-adapter=infinispan/connection-definitions=infinispanDS:add(jndi-name=java

:/infinispanDS,class-name=org.teiid.resource.adapter.infinispan.libmode.InfinispanManagedConnectionFactory,en

abled=true,use-java-context=true)

/subsystem=resource-adapters/resource-adapter=infinispan/connection-definitions=infinispanDS/config-properties=

CacheTypeMap:add(value=trades:org.somewhere.Trade;tradeId)


Module:add(value=org.somewhere)


CacheJndiName:add(value=java:/myCache)

runbatch

TofindoutallthepropertiesthataresupportedbythisInfinispanConnectorexecutethefollowingcommandintheCLI.

/subsystem=teiid:read-rar-description(rar-name=infinispan)

Tip

Developer’sTip-IfWildFly9.0.2isrunninginstandalonemode,youcanalsomanuallyeditthe"<jboss-install>/standalone/configuration/standalone-teiid.xml"fileandaddtheXMLconfigurationdefinedin*"<jboss-install>/docs/teiid/datasources/infinispan"directoryunder"resource-adapters"subsystem.Shutdowntheserverbeforeyoueditthisfile,andrestartafterthemodificationsaredone.

NoteAvoidClassloadingIssues:IfyouareusingaservletorothertypeofwebapplicationtocreatetheDefaultCacheManagerforthecache,besurenottoincludetheInfinispanjardependenciesintheapplication,butaddtheirmoduledependencies.


26



27

InfinispanHotRodDataSourcesInfinispanHotRoddatasourcesuseaTeiidspecificJCAconnectorthatisdeployedintoWildFly9.0.2duringinstallation.ThisconnectorcanbeconfiguredtosupportthefollowingmodesofInfinispancachesthatwillbeaccessedusingtheHotRodclient:

CacheType PropertyName ObtainCacheBy

RemoteCache CacheJndiName usingJNDI

RemoteCache RemoteServerList Serverlist,specify1ormorehost:port’s

RemoteCache HotRodClientPropertiesFile HotRodclientpropertiesfile

Requirement

(option1)Minimum,JDG6.2-thisrequiresyouprovideaprotobufdefinitionfileandpojomarsharllerforthepojotobecached

(option2)Minimum,JDG6.6-thiscanbeusedwhenthepojohasprotobufannotationswhichtriggerthecreationoftheprotobufdefinitionandpojomarshallerbyJDG.

Configuration

PojoJar


Totakeadvantageofthecachebeingindexedenabled,shouldannotatetheclass.SeeJDGProtobufAnnotationsathttps://access.redhat.com/documentation/en-US/Red_Hat_JBoss_Data_Grid/6.6/html-single/Infinispan_Query_Guide/index.html#Custom_Fields_Indexing_with_Protobuf





ReadingandWritingtotheCache

Thefollowingaretherequiredproperties:

PropertyName PropertyTemplate Description

CacheTypeMap cacheName:className[;pkFieldName[:cacheKeyJavaType]]

Fortheindicatedcache,maptherootJavaObjectclassname.Optionally,butrequiredforupdates,identifywhichclass


28

https://access.redhat.com/documentation/en-US/Red_Hat_JBoss_Data_Grid/6.6/html-single/Infinispan_Query_Guide/index.html#Custom_Fields_Indexing_with_Protobuf

CacheTypeMap cacheName:className[;pkFieldName[:cacheKeyJavaType]] attributeistheprimarykeytothecache.Identifyprimarykeyjavatypewhendifferentthanclassattributetype

ThefollowingarethepropertyoptionsfordefininghowtheRemoteCacheManagerwillbecreated/accessed:

PropertyName Req. PropertyTemplate Description

CacheJndiName N JNDInametofindtheCacheContainer

RemoteServerList N host:port\[;host:port….\]

Specifythehostandportsthatwillbeclusteredtogethertoaccessthecaches

HotRodClientPropertiesFile N

TheHotRodpropertiesfileforconfiguringaconnectiontoaremotecache

Thefollowingpropertiesarerequiredwhenthepojoisnotannotated:


ProtobinFile YPathtotheGoogleProtobinfilethat’spackagedinajar(ex:/quickstart/addressbook.protobin)

MessageMarshallers Y marshaller\[,marshaller,..\]

ContainsClassnamesmappeditsrespectivemessagemarshaller,(class:marshaller,\[class:marshaller,..\]),thataretoberegisteredforserialization

MessageDescriptor Y Messagedescriptorclassnamefortherootobjectincache

Thefollowingareoptionalproperties:


module N

SpecifytheWildFlymodulethatcontainsthecacheclassesthatneedtobeloaded

UsingRemoteCacheforExternalMaterialization

ThefollowingaretheadditionalpropertiesthatneedtobeconfiguredifusingtheRemoteCacheforexternalmaterialization:


StagingCacheName Y Cachenameforthestagingcacheusedinmaterialization


29

AliasCacheName Y Cachenameforthealiascacheusedintrackingaliasingofthecachesusedinmaterialization

Examples

Therearemanywaystocreatethedatasource,usingCLI,AdminShell,admin-consoleetc.Thefirstexampleisanxmlsnippetofaresource-adapterthatisusedtoconnecttotheJDGremote-queryquickstart:me

SampleResourceAdapter

<resource-adapterid="infinispanRemQS">

<moduleslot="main"id="org.jboss.teiid.resource-adapter.infinispan.hotrod"/>

<connection-definitions>

<connection-definitionclass-name="org.teiid.resource.adapter.infinispan.hotrod.Infinis

panManagedConnectionFactory"jndi-name="java:/infinispanRemote"enabled="true"use-java-context="true"pool-name

="infinispanDS">

<config-propertyname="CacheTypeMap">

addressbook:org.jboss.as.quickstarts.datagrid.hotrod.query.domain.Person;id

</config-property>

<config-propertyname="ProtobinFile">

/quickstart/addressbook.protobin

</config-property>

<config-propertyname="MessageDescriptor">

quickstart.Person

</config-property>

<config-propertyname="Module">

com.client.quickstart.pojos

</config-property>

<config-propertyname="MessageMarshallers">org.jboss.

as.quickstarts.datagrid.hotrod.query.domain.Person:org.jboss.as.quickstarts.datagrid.hotrod.query.marshallers.P

ersonMarshaller,org.jboss.as.quickstarts.datagrid.hotrod.query.domain.PhoneNumber:org.jboss.as.quickstarts.data

grid.hotrod.query.marshallers.PhoneNumberMarshaller,org.jboss.as.quickstarts.datagrid.hotrod.query.domain.Phone

Type:org.jboss.as.quickstarts.datagrid.hotrod.query.marshallers.PhoneTypeMarshaller

</config-property>

<config-propertyname="RemoteServerList">

127.0.0.1:11322

</config-property>

</connection-definition>

</connection-definitions>

</resource-adapter>

Thefollowingisanexamplewhenconfiguredforexternalmaterialization:

<resource-adapterid="infinispanRemQSDSL">

<moduleslot="main"id="org.jboss.teiid.resource-adapter.infinispan.hotrod"/>


<connection-definitionclass-name="org.teiid.resource.adapter.infinispan.hotrod.Infinis

panManagedConnectionFactory"jndi-name="java:/infinispanRemoteDSL"enabled="true"use-java-context="true"pool-

name="infinispanRemoteDSL">

<config-propertyname="CacheTypeMap">

addressbook_indexed:org.jboss.as.quickstarts.datagrid.hotrod.query.domain.Perso

n;id

</config-property>

<config-propertyname="StagingCacheName">

addressbook_indexed_mat

</config-property>

<config-propertyname="AliasCacheName">

aliasCache

</config-property>

<config-propertyname="Module">

com.client.quickstart.addressbook.pojos

</config-property>

<config-propertyname="RemoteServerList">

127.0.0.1:11322


30

</config-property>



</resource-adapter>


31

JDBCDataSourcesThefollowingisanexamplehighlightingconfiguringanOracledatasource.Theprocessisnearlyidenticalregardlessofthedatabasevendor.TypicallytheJDBCjarandtheconfigurationlikeconnectionURLandusercredentialschange.

Thereareconfigurationtemplatesforallthedatasourcesinthe"<jboss-install>/docs/teiid/datasources"directory.AcompletedescriptionhowadatasourcecanbeaddedintoWildFlyisalsodescribedhere.Thebelowwepresenttwodifferentwaystocreateadatasource.

DeployingasingleJDBCJarFile

FirststepinconfiguringthedatasourceisdeployingtherequiredJDBCjarfile.Forexample,ifyouaretryingtocreateaOracledatasource,firstyouneedtodeploythe"ojdbc6.jar"filefirst.ExecutefollowingcommandusingtheCLIonceyouconnectedtotheServer.

deploy/path/to/ojdbc6.jar

Tip Developer’sTip-IfWildFly9.0.2isrunninginstandalonemode,youcanalsomanuallycopythis’ojdbc6.jar"tothe"<jboss-install>/standalone/deployments"directory,toautomaticallydeploywithoutusingtheCLItool.

CreatingamodulefortheDriver

Youmayalsocreateamoduletohavemorecontroloverthehandlingofthedriver.Incaseswherethedriverisnotcontainedinasinglefile,thismaybepreferabletocreatinga"uber"jarasthedependenciescanbemanagedseparately.

Creatingamoduleforadriverisnodifferentthananyothercontainermodule.Youjustincludethenecessaryjarsasresourcesinthemoduleandreferenceothermodulesasdependencies.

<modulexmlns="urn:jboss:module:1.0"name="com.mysql">

<resources>

<resource-rootpath="mysql-connector-java-5.1.21.jar"/>

</resources>

<dependencies>

<modulename="javax.api"/>

...

</dependencies>

</module>

CreateDataSourceNowthatyouhavetheJDBCdriverdeployedorthemodulecreated,itistimetocreateadatasourceusingthisdriver.TherearemanywaystocreatethedatasourceusingCLI,AdminShell,admin-consoleetc.TheexampleshownbelowusestheCLItool,asthisworksinbothStandaloneandDomainmodes.

ExecutefollowingcommandusingCLIonceyouconnectedtotheServer.MakesureyouprovidethecorrectURLandusercredentialsandedittheJNDInametomatchtheJNDInameyouusedinVDB.

/subsystem=datasources/data-source=oracel-ds:add(jndi-name=java:/OracleDS,driver-name=ojdbc6.jar,connection-u

rl=jdbc:oracle:thin:{host}:1521:orcl,user-name={user},password={password})

/subsystem=datasources/data-source=oracel-ds:enable


32

https://docs.jboss.org/author/display/WFLY10/DataSource+configuration



Thedriver-namewillmatchthenameofjarormodulethatyoudeployedforthedriver.

Tip

Developer’sTip-IfWildFly9.0.2isrunninginstandalonemode,youcanalsomanuallyeditthe"<jboss-install>/standalone/configuration/standalone-teiid.xml"fileandaddtheXMLconfigurationdefinedin*"<jboss-install>/docs/teiid/datasources/oracle"directoryunder"datasources"subsystem.Shutdowntheserverbeforeyoueditthisfile,andrestartafterthemodificationsaredone.


33

LDAPDataSourcesLDAPdatasourcesuseaTeiidspecificJCAconnectorwhichisdeployedintoWildFly9.0.2duringinstallation.Therearemanywaystocreatetheldapdatasource,usingCLI,AdminShell,admin-consoleetc.TheexampleshownbelowusestheCLItool,asthisworksinbothStandaloneandDomainmodes.

ExecutefollowingcommandusingCLIonceyouconnectedtotheServer.MakesureyouprovidethecorrectURLandusercredentials.Addanyadditionalpropertiesrequiredbytheconnectorbyduplicatingthe"connection-definitions"commandbelow.EdittheJNDInametomatchtheJNDInameyouusedinVDB.

batch

/subsystem=resource-adapters/resource-adapter=ldap/connection-

definitions=ldapDS:add(jndi-name=java:/ldapDS,class-

name=org.teiid.resource.adapter.ldap.LDAPManagedConnectionFactory,enabled=true,

use-java-context=true)


definitions=ldapDS/config-properties=LdapUrl:add(value=ldap://ldapServer:389)


definitions=ldapDS/config-properties=LdapAdminUserDN:add(value=

{cn=???,ou=???,dc=???})


definitions=ldapDS/config-properties=LdapAdminUserPassword:add(value={pass})


definitions=ldapDS/config-properties=LdapTxnTimeoutInMillis:add(value=-1)

/subsystem=resource-adapters/resource-adapter=ldap:activate

runbatch

TofindoutallthepropertiesthataresupportedbythisLDAPConnectorexecutethefollowingcommandintheCLI.

/subsystem=teiid:read-rar-description(rar-name=ldap)

Tip

Developer’sTip-IfWildFly9.0.2isrunninginstandalonemode,youcanalsomanuallyeditthe"<jboss-install>/standalone/configuration/standalone-teiid.xml"fileandaddtheXMLconfigurationdefinedin*"<jboss-install>/docs/teiid/datasources/ldap"directoryunder"resource-adapters"subsystem.Shutdowntheserverbeforeyoueditthisfile,andrestartafterthemodificationsaredone.

Note Touseananonymousbind,settheLdapAdminUserDNandLdapAdminUserPasswordtoemptyvalues.


34


MongoDBDataSourcesMongoDBdatasourcesuseaTeiidspecificJCAconnectorthatisdeployedintoWildFly9.0.2duringinstallation.TherearemanywaystocreateaMongoDBdatasource,usingCLI,AdminShell,admin-console,etc.TheexampleshownbelowusestheCLItool,asthisworksinbothStandaloneandDomainmodes.


batch

/subsystem=resource-adapters/resource-adapter=mongodb/connection-definitions=mongodbDS:add(jndi-name="java:/mon

goDS",class-name=org.teiid.resource.adapter.mongodb.MongoDBManagedConnectionFactory,enabled=true,use-java-co

ntext=true)

/subsystem=resource-adapters/resource-adapter=mongodb/connection-definitions=mongodbDS/config-properties=Remote

ServerList:add(value="{host}:27017")

/subsystem=resource-adapters/resource-adapter=mongodb/connection-definitions=mongodbDS/config-properties=Databa

se:add(value="{db-name}")

/subsystem=resource-adapters/resource-adapter=mongodb:activate

runbatch

AllthepropertiesthataredefinedontheRARfileare


RemoteServerList

Acommaseparatedlistofserverlocations.Eachlocationcancontainanoptionalport,oftheformathost:port

Username ConnectionUser’sName false none

Password ConnectionUser’spassword false none

Database MongoDBdatabasename true none

TofindoutallthepropertiesthataresupportedbythisMongoDBConnectorexecutethefollowingcommandintheCLI.

/subsystem=teiid:read-rar-description(rar-name=mongodb)

Tip

Developer’sTip-IfWildFly9.0.2isrunninginstandalonemode,youcanalsomanuallyeditthe"<jboss-install>/standalone/configuration/standalone-teiid.xml"fileandaddtheXMLconfigurationdefinedin"<jboss-install>/docs/teiid/datasources/mongodb"directoryunder"resource-adapters"subsystem.Shutdowntheserverbeforeyoueditthisfile,andrestartafterthemodificationsaredone.


35


PhoenixDataSourcesThefollowingisaexampleforsettingupPhoenixDataSources,whichispreconditionforApacheHBaseTranslator.InadditiontotheDataSourcessetup,thisarticlealsocovermappingPhoenixtabletoanexistingHBasetableandcreatinganewPhoenixtable.

ThereareconfigurationtemplatesforPhoenixdatasourcesinthe"<jboss-install>/docs/teiid/datasources"directory.AcompletedescriptionhowadatasourcecanbeaddedintoWildFlyisalsodescribedhere.

ConfiguringaPhoenixdatasourceinWildFly

ConfiguringaPhoenixdatasourceisnearlyidenticaltoconfiguringJDBCDataSources.ThefirststepisdeployingthePhoenixdriverjar.UsingbelowCLIcommandtodeployPhoenixdriver:

moduleadd--name=org.apache.phoenix--resources=/path/to/phoenix-[version]-client.jar--dependencies=javax.a

pi,sun.jdk,org.apache.log4j,javax.transaction.api

/subsystem=datasources/jdbc-driver=phoenix:add(driver-name=phoenix,driver-module-name=org.apache.phoenix,driver-

class-name=org.apache.phoenix.jdbc.PhoenixDriver)

TheDriverjarcanbedownloadfromphoenixdocument.

ThesecondstepsiscreatingtheDataSourcebaseonabovedeployeddriver,whichisalsolikecreatingJDBCDataSource.UsingbelowCLIcommandtocreateDataSource:

/subsystem=datasources/data-source=phoenixDS:add(jndi-name=java:/phoenixDS,driver-name=phoenix,connection-ur

l=jdbc:phoenix:{zookeeperquorumserver},enabled=true,use-java-context=true,user-name={user},password={pass

word})

/subsystem=datasources/data-source=phoenixDS/connection-properties=phoenix.connection.autoCommit:add(value=true)

PleasemakesuretheURL,Driver,andotherpropertiesareconfiguredcorrectly:

jndi-name-TheJNDInameneedtomatchtheJNDInameyouusedinVDB

driver-name-TheDrivernameneedtomatchthedriveryoudeployedinabovesteps

connection-url-TheURLneedtomatchtheHBasezookeeperquorumserver,theformatlikejdbc:phoenix[:<zookeeperquorum>[:<portnumber>][:<rootnode>]],’jdbc:phoenix:127.0.0.1:2181’isaexample

user-name/password-TheusercredentialsforPhoenixConnection

ThePhoenixConnectionAutoCommitdefaultisfalse.Setphoenix.connection.autoCommittotrueifyouwillbeexecutingINSERT/UPDATE/DELETEstatementsagainstPhoenix.

MappingPhoenixtabletoanexistingHBasetable

MappingPhoenixtabletoanexistingHBasetablehas2steps.Thefirststepisinstallingphoenix-[version]-server.jartotheclasspathofeveryHBaseregionserver.AneasywaytodothisistocopyitintotheHBaselib-formoredetailspleaserefertothephoenixdocumentation.

ThesecondstepisexecutingtheDDLtomapaPhoenixtabletoanexistingHBasetable.TheDDLcaneitherbeexecutedviaPhoenixCommandLine,orexecutedbyJDBC.


36

https://docs.jboss.org/author/display/WFLY10/DataSource+configuration

http://phoenix.apache.org/

http://phoenix.apache.org/download.html

http://phoenix.apache.org/download.html

TheFollowingisaexampleformappinganexistingHBaseCustomerwiththefollowingstructure:

Asdepictedabove,theHBaseCustomertablehave2columnfamilies,customerandsales,andeachhas2columnqualifiers,name,city,productandamountrespectively.WecanmapthisTabletoPhoenixviaDDL:

CREATETABLEIFNOTEXISTS"Customer"("ROW_ID"VARCHARPRIMARYKEY,"customer"."city"VARCHAR,"customer"."name"

VARCHAR,"sales"."amount"VARCHAR,"sales"."product"VARCHAR)

FormoreaboutmappingPhoenixtabletoanexistingHBasetablepleaserefertothephoenixdocumentation.

CreatinganewPhoenixtable

CreatinganewPhoenixtableisjustlikemappingtoanexistingHBasetable.Phoenixwillcreateanymetadata(table,columnfamilies)thatdonotexist.SimilartotheaboveexampletheDDLtocreatethePhoenix/HBaseCustomertablewouldbe:

CREATETABLEIFNOTEXISTS"Customer"("ROW_ID"VARCHARPRIMARYKEY,"customer"."city"VARCHAR,"customer"."name"

VARCHAR,"sales"."amount"VARCHAR,"sales"."product"VARCHAR)

DefiningForeignTableinVDBFinally,weneeddefineaForeignTableinVDBthatmaptoPhoenixtable,thefollowingprinciplesshouldbeconsideredindefiningForeignTable:

nameinsourceoptioninTableusedtomatchPhoenixtablename

nameinsourceoptioninColumnusedtomatchHBaseTable’sColumns

createaprimarykeyisrecommended,theprimarykeycolumnshouldmatchPhoenixtable’sprimarykey/HBaserowid.

With"MappingPhoenixtabletoanexistingHBasetable"section’s`Customer'table,belowisaexample:

CREATEFOREIGNTABLECustomer(

PKstringOPTIONS(nameinsource'ROW_ID'),

citystringOPTIONS(nameinsource'"city"'),

namestringOPTIONS(nameinsource'"name"'),

amountstringOPTIONS(nameinsource'"amount"'),

productstringOPTIONS(nameinsource'"product"'),

CONSTRAINTPK0PRIMARYKEY(PK)

)OPTIONS(nameinsource'"Customer"',"UPDATABLE"'TRUE');

Note "Constraintviolation.Xmaynotbenull"exceptionmaythrownifupdatingatablewithoutdefiningaprimarykey.


37

http://phoenix.apache.org/faq.html#How_I_map_Phoenix_table_to_an_existing_HBase_table

SalesforceDataSourcesSalesforcedatasourcesuseaTeiidspecificJCAconnectorthatisdeployedintoWildFly9.0.2duringinstallation.Therearetwoversionsofthesalesforceresourceadapter-salesforce,whichcurrentlyprovidesconnectivitytothe22.0SalesforceAPIandsalesforce-34,whichprovidesconnectivitytothe34.0SalesforceAPI.Theversion22.0supporthasbeendeprecated.

IfyouneedconnectivitytoanAPIversionotherthanwhatisbuiltin,pleaseutilizetheprojecthttps://github.com/teiid/salesforcetogeneratenewresourceadapter/translatorpair.

Therearemanywaystocreatethesalesforcedatasource,usingCLI,AdminShell,admin-consoleetc.TheexampleshownbelowusestheCLItool,asthisworksinbothStandaloneandDomainmodes.

ExecutefollowingcommandusingtheCLIonceyouconnectedtotheServer.MakesureyouprovidethecorrectURLandusercredentials.Addanyadditionalpropertiesrequiredbytheconnectorbyduplicatingthe"connection-definitions"commandbelow.EdittheJNDInametomatchtheJNDInameyouusedinVDB.

batch

/subsystem=resource-adapters/resource-adapter=salesforce/connection-definitions=sfDS:add(jndi-name=java:/sfDS,

class-name=org.teiid.resource.adapter.salesforce.SalesForceManagedConnectionFactory,enabled=true,use-java-con

text=true)

/subsystem=resource-adapters/resource-adapter=salesforce/connection-definitions=sfDS/config-properties=URL:add(

value=https://www.salesforce.com/services/Soap/u/22.0)

/subsystem=resource-adapters/resource-adapter=salesforce/connection-definitions=sfDS/config-properties=username

:add(value={user})

/subsystem=resource-adapters/resource-adapter=salesforce/connection-definitions=sfDS/config-properties=password

:add(value={password})

/subsystem=resource-adapters/resource-adapter=salesforce:activate

runbatch

Thesalesforce-34connectiondefinitionconfigurationissimilartotheabove.Theresourceadapternamewouldinsteadbesalesforce-34,andtheurlwouldpointto34.0instead.

TofindoutallthepropertiesthataresupportedbythisSalesforceConnectorexecutethefollowingcommandintheCLI.

/subsystem=teiid:read-rar-description(rar-name=salesforce)

Tip

Developer’sTip-IfWildFly9.0.2isrunninginstandalonemode,youcanalsomanuallyeditthe"<jboss-install>/standalone/configuration/standalone-teiid.xml"fileandaddtheXMLconfigurationdefinedin*"<jboss-install>/docs/teiid/datasources/salesforce"directoryunder"resource-adapters"subsystem.Shutdowntheserverbeforeyoueditthisfile,andrestartafterthemodificationsaredone.

MutualAuthentication

IfyouneedtoconnecttoSalesforceusingMutualAuthentication,followthedirectionstosetupSalesforceathttps://help.salesforce.com/apex/HTViewHelpDoc?id=security_keys_uploading_mutual_auth_cert.htm&language=en_USthenconfigurethebelowCXFconfigurationfileontheresource-adapterbyaddingfollowingpropertytoabovecliscript

/subsystem=resource-adapters/resource-adapter=salesforce/connection-definitions=sfDS/config-properties=ConfigFi

le:add(value=${jboss.server.config.dir}/cxf-https.xml)

cxf-https.xml

<beansxmlns="http://www.springframework.org/schema/beans"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"


38

https://github.com/teiid/salesforce


https://help.salesforce.com/apex/HTViewHelpDoc?id=security_keys_uploading_mutual_auth_cert.htm&language=en_US

xmlns:sec="http://cxf.apache.org/configuration/security"

xmlns:http-conf="http://cxf.apache.org/transports/http/configuration"

xmlns:jaxws="http://java.sun.com/xml/ns/jaxws"

xsi:schemaLocation="http://cxf.apache.org/transports/http/configurationhttp://cxf.apache.org/schemas/confi

guration/http-conf.xsdhttp://www.springframework.org/schema/beanshttp://www.springframework.org/schema/beans/

spring-beans-2.0.xsdhttp://cxf.apache.org/configuration/securityhttp://cxf.apache.org/schemas/configuration/s

ecurity.xsd">

<http-conf:conduitname="*.http-conduit">

<http-conf:clientConnectionTimeout="120000"ReceiveTimeout="240000"/>

<http-conf:tlsClientParameterssecureSocketProtocol="SSL">

<sec:trustManagers>

<sec:keyStoretype="JKS"password="changeit"file="/path/to/truststore.jks"/>

</sec:trustManagers>

</http-conf:tlsClientParameters>

</http-conf:conduit>

</beans>

moreinformationaboutCXFconfigurationfilecanbefoundathttp://cxf.apache.org/docs/client-http-transport-including-ssl-support.html#ClientHTTPTransport(includingSSLsupport)-ConfiguringSSLSupport


39

http://cxf.apache.org/docs/client-http-transport-including-ssl-support.html#ClientHTTPTransport(includingSSLsupport)-ConfiguringSSLSupport

SolrDataSourcesSolrdatasourcesuseaTeiidspecificJCAconnectorthatisdeployedintoWildFly9.0.2duringinstallation.TherearemanywaystocreateaSolrdatasource,usingCLI,AdminShell,admin-console,etc.TheexampleshownbelowusestheCLItool,asthisworksinbothStandaloneandDomainmodes.


batch

/subsystem=resource-adapters/resource-adapter=solr/connection-definitions=solrDS:add(jndi-name=java:/solrDS,cl

ass-name=org.teiid.resource.adapter.solr.SolrManagedConnectionFactory,enabled=true,use-java-context=true)

/subsystem=resource-adapters/resource-adapter=solr/connection-definitions=solrDS/config-properties=url:add(valu

e=http://localhost:8983/solr/)

/subsystem=resource-adapters/resource-adapter=solr/connection-definitions=solrDS/config-properties=CoreName:add

(value=collection1)

/subsystem=resource-adapters/resource-adapter=solr:activate

runbatch

TofindoutallthepropertiesthataresupportedbythisSolrConnectorexecutethefollowingcommandintheCLI.

/subsystem=teiid:read-rar-description(rar-name=solr)

Tip

Developer’sTip-IfWildFly9.0.2isrunninginstandalonemode,youcanalsomanuallyeditthe"<jboss-install>/standalone/configuration/standalone-teiid.xml"fileandaddtheXMLconfigurationdefinedin"<jboss-install>/docs/teiid/datasources/solr"directoryunder"resource-adapters"subsystem.Shutdowntheserverbeforeyoueditthisfile,andrestartafterthemodificationsaredone.


40


WebServiceDataSourcesWebservicedatasourcesuseaTeiidspecificJCAconnectorthatisdeployedintoWildFly9.0.2duringinstallation.Therearemanywaystocreatethefiledatasource,usingCLI,AdminShell,admin-consoleetc.TheexampleshownbelowusestheCLItool,asthisworksinbothStandaloneandDomainmodes.

ExecutefollowingcommandusingtheCLIonceyouconnectedtotheServer.Makesureyouprovidethecorrectendpointandotherpropertiesbelow.Addanyadditionalpropertiesrequiredbytheconnectorbyduplicatingthe"connection-definitions"commandbelow.EdittheJNDInametomatchtheJNDInameyouusedinVDB.

batch

/subsystem=resource-adapters/resource-adapter=webservice/connection-definitions=wsDS:add(jndi-name=java:/wsDS,

class-name=org.teiid.resource.adapter.ws.WSManagedConnectionFactory,enabled=true,use-java-context=true)

/subsystem=resource-adapters/resource-adapter=webservice/connection-definitions=wsDS/config-properties=EndPoint

:add(value={end_point})

/subsystem=resource-adapters/resource-adapter=webservice:activate

runbatch

TofindoutallthepropertiesthataresupportedbythisWebServiceConnectorexecutethefollowingcommandintheCLI.

/subsystem=teiid:read-rar-description(rar-name=webservice)

TheWebServiceDataSourcesupportsspecifyingaWSDLusingtheWsdlproperty.IftheWsdlpropertyisset,thentheServiceName,EndPointName,andNamespaceUripropertiesshouldalsobeset.TheWsdlpropertymaybeaURLorfilelocationortheWSDLtouse.

Tip

Developer’sTip-IfWildFly9.0.2isrunninginstandalonemode,youcanalsomanuallyeditthe"<jboss-install>/standalone/configuration/standalone-teiid.xml"fileandaddtheXMLconfigurationdefinedin*"<jboss-install>/docs/teiid/datasources/web-service"directoryunder"resource-adapters"subsystem.Shutdowntheserverbeforeyoueditthisfile,andrestartafterthemodificationsaredone.

Allavailableconfigurationpropertiesofwebresource-adapter

PropertyName appliesto Required DefaultValue Description

EndPoint HTTP&SOAP true n/a URLforHTTP,ServiceEndpointfor

SOAP

SecurityType HTTP&SOAP false none

TypeofAuthenticationtousedwiththewebservice.Allowedvalues["None","HTTPBasic","WSSecurity","Kerberos","OAuth"]

AuthUserName HTTP&SOAP false n/a Namevalueforauthentication,used

inHTTPBasicandWsSecurity

AuthPassword HTTP&SOAP false n/a Passwordvalueforauthentication,

usedinHTTPBasicandWsSecurity

ConfigFile HTTP&SOAP false n/a CXFclientconfigurationFileorURL

EndPointNameHTTP&

false teiidLocalpartoftheendpointQNameto


41


ServiceName SOAP false n/a LocalpartoftheserviceQNametousewiththisconnection

NamespaceUri SOAP false http://teiid.org NamespaceURIoftheserviceQNametousewiththisconnection

RequestTimeout HTTP&SOAP false n/a Timeoutforrequest

ConnectTimeout HTTP&SOAP false n/a Timeoutforconnection

Wsdl SOAP false n/a WSDLfileorURLforthewebservice

CXFConfiguration

EachwebservicedatasourcemaychooseaparticularCXFconfigfileandportconfiguration.TheConfigFileconfigpropertyspecifiestheSpringXMLconfigurationfilefortheCXFBusandportconfigurationtobeusedbyconnections.Ifnoconfigfileisspecifiedthenthesystemdefaultconfigurationwillbeused.

Only1portconfigurationcanbeusedbythisdatasource.YoumayexplicitlysetthelocalnameoftheportQNametouseviatheConfigNameproperty.ThenamespaceURIfortheQNameinyourconfigfileshouldmatchyourWSDL/namespacesettingonthedatasourceorusethedefaultofhttp://teiid.org.SeetheCXFDocumentationandthesectionsbelowonWS-Security,Logging,etc.forexamplesofusingtheCXFconfigurationfile.

SampleSpringXMLConfigurationToSetTimeouts




xsi:schemaLocation="http://cxf.apache.org/transports/http/configuration

http://cxf.apache.org/schemas/configuration/http-conf.xsd

http://www.springframework.org/schema/beans

http://www.springframework.org/schema/beans/spring-beans.xsd">

<http-conf:conduitname="{http://teiid.org}configName.http-conduit">



</beans>

Intheconduitname\{http://teiid.org[http://teiid.org]}configName.http-conduit,thenamespace,\{http://teiid.org[http://teiid.org]},maybesetviathenamespacedatasourceproperty.Typicallythatwillonlyneeddonewhenalsosupplyingthewsdlsetting.Thelocalnameisfollowedby.http-conduit.ItwillbebasedupontheconfigNamesetting,withadefaultvalueofteiid.

SeetheCXFdocumentationforallpossibleconfigurationoptions.

Note ItisnotrequiredtousetheSpringconfigurationtosetjusttimeouts.TheConnectionTimeoutandReceiveTimeoutcanbesetviatheresourceadapterconnectTimeoutandrequestTimeoutpropertiesrespectively.

Security


42

http://teiid.org

http://teiid.org

http://cxf.apache.org/docs/configuration.html

http://teiid.org

http://teiid.org

http://cxf.apache.org/docs/

ToenabletheuseofWS-Security,theSecurityTypeshouldbesettoWSSecurity.AtthistimeTeiiddoesnotexpectaWSDLtodescribetheservicebeingused.ThusaSpringXMLconfigurationfileisnotonlyrequired,itmustinsteadcontainalloftherelevantpolicyconfiguration.Andjustaswiththegeneralconfiguration,eachdatasourceislimitedtospecifyingonlyasingleportconfigurationtouse.

batch

/subsystem=resource-adapters/resource-adapter=webservice/connection-definitions=wsDS:add(jndi-name=java:/wsDS,

class-name=org.teiid.resource.adapter.ws.WSManagedConnectionFactory,enabled=true,use-java-context=true)

/subsystem=resource-adapters/resource-adapter=webservice/connection-definitions=wsDS/config-properties=ConfigFi

le:add(value=${jboss.server.home.dir}/standalone/configuration/xxx-jbossws-cxf.xml)

/subsystem=resource-adapters/resource-adapter=webservice/connection-definitions=wsDS/config-properties=ConfigNa

me:add(value=port_x)

/subsystem=resource-adapters/resource-adapter=webservice/connection-definitions=wsDS/config-properties=Security

Type:add(value=WSSecurity)


runbatch

Thecorrespondingxxx-jbossws-cxf.xmlfilethataddsatimestamptotheSOAPheader

ExampleWS-Securityenableddatasource



xmlns:jaxws="http://cxf.apache.org/jaxws"

xsi:schemaLocation="http://www.springframework.org/schema/beans

http://www.springframework.org/schema/beans/spring-beans.xsd

http://cxf.apache.org/jaxws

http://cxf.apache.org/schemas/jaxws.xsd">

<jaxws:clientname="{http://teiid.org}port_x"

createdFromAPI="true">

<jaxws:outInterceptors>

<bean/>

<refbean="Timestamp_Request"/>

</jaxws:outInterceptors>

</jaxws:client>

<bean

id="Timestamp_Request">

<constructor-arg>

<map>

<entrykey="action"value="Timestamp"/>

<map>

</constructor-arg>

</bean>

</beans>

NotethattheclientportconfigurationismatchedtothedatasourceinstancebytheQName\{http://teiid.org[http://teiid.org]}port_x,wherethenamespacewillmatchyournamespacesettingorthedefaultofhttp://teiid.org.Theconfigurationmaycontainotherportconfigurationswithdifferentlocalnames.

FormoreinformationonconfiguringCXFinterceptors,pleaseconsulttheCXFdocumentation

KerberosWS-SecurityKerberosisonlysupportedwhentheWSDLpropertyisdefinedinresource-adapterconnectionconfigurationandonlywhenWSDLBasedProceduresareused.WSDLfilemustcontainWS-Policysection,thenWS-Policysectioniscorrectlyinterpretedandenforcedontheendpoint.ThesampleCXFconfigurationwilllooklike


43

http://teiid.org

http://teiid.org

http://cxf.apache.org/docs/security.html

<?xmlversion="1.0"encoding="UTF-8"?>



xmlns:http="http://cxf.apache.org/transports/http/configuration"


xmlns:cxf="http://cxf.apache.org/core"

xmlns:p="http://cxf.apache.org/policy"


xsi:schemaLocation="http://www.springframework.org/schema/beanshttp://www.springframework.org/sc

hema/beans/spring-beans.xsdhttp://cxf.apache.org/jaxwshttp://cxf.apache.o

rg/schemas/jaxws.xsdhttp://cxf.apache.org/transports/http/configurationhttp://cxf.apache.org/sche

mas/configuration/http-conf.xsdhttp://cxf.apache.org/configuration/securityhttp://cxf.apac

he.org/schemas/configuration/security.xsdhttp://cxf.apache.org/corehttp://cxf.apache.org/schemas/co

re.xsdhttp://cxf.apache.org/policyhttp://cxf.apache.org/schemas/policy.xsd">

<beanclass="org.springframework.beans.factory.config.PropertyPlaceholderConfigurer"/>

<cxf:bus>

<cxf:features>

<p:policies/>

<cxf:logging/>

</cxf:features>

</cxf:bus>

<jaxws:clientname="{http://webservices.samples.jboss.org/}HelloWorldPort"createdFromAPI="true">

<jaxws:properties>

<entrykey="ws-security.kerberos.client">

<beanclass="org.apache.cxf.ws.security.kerberos.KerberosClient">

<constructor-argref="cxf"/>

<propertyname="contextName"value="alice"/>

<propertyname="serviceName"value="[email protected]"/>

</bean>

</entry>

</jaxws:properties>

</jaxws:client>

</beans>

andyouwouldneedtoconfigurethesecurity-domaininthestandalone-teiid.xmlfileunder`security'subsystemas

<security-domainname="alice"cache-type="default">

<authentication>

<login-modulecode="Kerberos"flag="required">

<module-optionname="storeKey"value="true"/>

<module-optionname="useKeyTab"value="true"/>

<module-optionname="keyTab"value="/home/alice/alice.keytab"/>

<module-optionname="principal"value="[email protected]"/>

<module-optionname="doNotPrompt"value="true"/>

<module-optionname="debug"value="true"/>

<module-optionname="refreshKrb5Config"value="true"/>

</login-module>

</authentication>

</security-domain>

forcompletelistofkerberospropertiespleaserefertothistestcase

LoggingTheCXFconfigpropertymayalsobeusedtocontroltheloggingofrequestsandresponsesforspecificorallports.Logging,whenenabled,willbeperformedatanINFOleveltotheorg.apache.cxf.interceptorcontext.

Exampleloggingdatasource

batch

/subsystem=resource-adapters/resource-adapter=webservice/connection-


44

http://anonsvn.jboss.org/repos/jbossws/stack/cxf/trunk/modules/testsuite/cxf-spring-tests/src/test/java/org/jboss/test/ws/jaxws/samples/wsse/kerberos/KerberosTestCase.java

definitions=wsDS:add(jndi-name=java:/wsDS,class-

name=org.teiid.resource.adapter.ws.WSManagedConnectionFactory,enabled=true,use-

java-context=true)


definitions=wsDS/config-

properties=ConfigFile:add(value=${jboss.server.home.dir}/standalone/configuration/x

xx-jbossws-cxf.xml)


definitions=wsDS/config-properties=ConfigName:add(value=port_x)


runbatch

Correspondingxxx-jbossws-cxf.xml

Exampleloggingdatasource




xsi:schemaLocation="http://www.springframework.org/schema/beans

http://www.springframework.org/schema/beans/spring-beans.xsd

http://cxf.apache.org/jaxws

http://cxf.apache.org/schemas/jaxws.xsd">

<jaxws:clientname="{http://teiid.org}port_y"

createdFromAPI="true">

<jaxws:features>

<beanclass="org.apache.cxf.feature.LoggingFeature"/>

</jaxws:features>

</jaxws:client>

</beans>

TransportSettings

TheCXFconfigpropertymayalsobeusedtocontrollowlevelaspectsoftheHTTPtransport.SeetheCXFdocumentationforallpossibleoptions.

ExampleDisablingHostnameVerification




xsi:schemaLocation="http://cxf.apache.org/transports/http/configuration

http://cxf.apache.org/schemas/configuration/http-conf.xsd

http://www.springframework.org/schema/beans

http://www.springframework.org/schema/beans/spring-beans.xsd">

<http-conf:conduitname="{http://teiid.org}port_z.http-conduit">



<http-conf:tlsClientParametersdisableCNcheck="true"/>


</beans>

ConfiguringSSLSupport(Https)ForusingtheHTTPS,youcanconfigureCXFfileasbelow


45

http://cxf.apache.org/docs/client-http-transport-including-ssl-support.html





xmlns:jaxws="http://java.sun.com/xml/ns/jaxws"

xsi:schemaLocation="http://cxf.apache.org/transports/http/configurationhttp://cxf.apache.org/schemas/confi

guration/http-conf.xsdhttp://www.springframework.org/schema/beanshttp://www.springframework.org/schema/beans/

spring-beans-2.0.xsdhttp://cxf.apache.org/configuration/securityhttp://cxf.apache.org/schemas/configuration/s

ecurity.xsd">



<http-conf:tlsClientParameterssecureSocketProtocol="SSL">

<sec:trustManagers>

<sec:keyStoretype="JKS"password="changeit"file="/path/to/truststore.jks"/>

</sec:trustManagers>

</http-conf:tlsClientParameters>


</beans>

forallthehttp-conduitbasedconfigurationseehttp://cxf.apache.org/docs/client-http-transport-including-ssl-support.html.YoucanalsoconfigureforHTTPBasic,kerberos,etc.


46

http://cxf.apache.org/docs/client-http-transport-including-ssl-support.html

KerberoswithRESTbasedServices

Note "Kerberosinws-securitywithSOAPservices"-

CheckoutthecxfconfigurationtoallowKerberosinSOAPwebservicesathttp://cxf.apache.org/docs/security.html

ThekerberossupportisbasedSPNEGOasdescribedinhttp://cxf.apache.org/docs/client-http-transport-including-ssl-support.html#ClientHTTPTransport%28includingSSLsupport%29-SpnegoAuthentication%28Kerberos%29.Theretwotypesofkerberossupport

Negotiation

Withthisconfiguration,RESTserviceisconfiguredwithKerberosJAASdomain,tonegotiateatoken,thenuseitaccessthewebservice.Forthisfirstcreateasecuritydomaininstandalone.xmlfileasbelow

<security-domainname="MY_REALM"cache-type="default">

<authentication>




<module-optionname="keyTab"value="/home/username/service.keytab"/>

<module-optionname="principal"value="host/testserver@MY_REALM"/>


<module-optionname="debug"value="false"/>

</login-module>

</authentication>

</security-domain>

andthejboss-cxf-xxx.xmlfileneedstobesetas





xsi:schemaLocation="http://cxf.apache.org/transports/http/configurationhttp://cxf.apache.org/schemas/c

onfiguration/http-conf.xsdhttp://www.springframework.org/schema/beanshttp://www.springframework.org/schema/be

ans/spring-beans-2.0.xsdhttp://cxf.apache.org/configuration/securityhttp://cxf.apache.org/schemas/configurati

on/security.xsd">


<http-conf:authorization>

<sec:AuthorizationType>Negotiate</sec:AuthorizationType>

<sec:Authorization>MY_REALM</sec:Authorization>

</http-conf:authorization>


</beans>

Theresourceadaptercreationneedstodefinethefollowingproperties

<config-propertyname="ConfigFile">path/to/jboss-cxf-xxxx.xml</config-property>

<config-propertyname="ConfigName">test</config-property>

NoteEventhoughaboveconfigurationconfiguresthevalueof"ConfigName",thecxfframeworkcurrentlyinthecaseofJAX-RSclientdoesnotgiveoptiontouseit.Forthatreasonuse"*.http-conduit"whichwillapplytoalltheHTTPcommunicationsunderthisresourceadapter.


47

http://cxf.apache.org/docs/security.html

http://cxf.apache.org/docs/client-http-transport-including-ssl-support.html#ClientHTTPTransport%28includingSSLsupport%29-SpnegoAuthentication%28Kerberos%29

Delegation

IfincasetheuserisalreadyloggedintoTeiidusingKerberosusingJDBC/ODBCorusedSPNEGOinweb-tierandusedpass-throughauthenticationintoTeiid,thenthereisnoneedtonegotiateanewtokenfortheKerberos.Thesystemcandelegatetheexistingtoken.

Toconfigurefordelegation,setupsecuritydomaindefinedexactlyasdefinedin"negotiation",andjboss-cxf-xxx.xmlfile,howeverremovethefollowinglinefromjboss-cxf-xxx.xmlfile,asitisnotgoingtonegotiatenewtoken.

<sec:Authorization>MY_REALM</sec:Authorization>

Addthefollowingpropertiesinwebserviceresourceadaptercreation.Oneconfiguresthat"kerberos"securitybeingused,theseconddefinesasecuritydomaintobeusedatthedatasource,inthiscasewewanttouseasecuritydomainthatpassesthroughaloggedinuser

<config-propertyname="SecurityType">Kerberos</config-property>

<security>

<security-domain>passthrough-security</security-domain>

</security>

Toconfigurein"passthrough-security"securitydomain,the"security"subsystemaddfollowingXMLfragment

<security-domainname="passthrough-security"cache-type="default">

<authentication>

<login-modulecode="org.teiid.jboss.PassthroughIdentityLoginModule"flag="required"module="org.jboss.t

eiid">

<module-optionname="username"value="guest"/>

<module-optionname="password"value="guest"/>

</login-module>

</authentication>

</security-domain>

Theusername,passwordareoptional,ifincasethereisnoauthenticatedsubjectavailableinthecontext,thesecanhelpcreateasimplestaticuser,butthatuserwillnotworkwithkerberosauthenticationasthesubjectwillnothavethekerberostokenrequired.


48

OAuthAuthenticationWithRESTBasedServices

SingleuserOAuthauthentication

WebServicesresource-adaptercanbeconfiguredtoparticipateinOAuth1.0aandOAuth2authenticationschemes.UsingTeiidalongwith"ws"translatorand"web-services"resourceadapteroncewriteapplicationscommunicatingwithwebsiteslikeGoogleandTwitter.

InordertosupportOAuthauthentication,thereissomepreparationandconfigurationworkinvolved.IndividualwebsitestypicallyprovidedeveloperfacingRESTbasedAPIsforaccessingtheircontentonthewebsitesandalsoprovidewaystoregistercustomapplicationsonuser’sbehalf,wheretheycanmanagetheAuthorizationofservicesofferedbythewebsite.Thefirststepistoregisterthiscustomapplicationonthewebsiteandcollectconsumer/APIkeysandsecrets.Theweb-siteswillalsolisttheURLS,wheretorequestforvariousdifferenttypesoftokensforauthorizationusingthesecredentials.AtypicalOAuthauthenticationflowisdefinedasbelow

Theaboveimagetakenfromhttps://developers.google.com/accounts/docs/OAuth2

Toaccommodateabovedefinedflow,Teiidprovidesautilitycalled"teiid-oauth-util.sh"or"teiid-oauth-util.bat"forwindowsinthe"bin"directoryofyourserverinstallation.Byexecutingthisutility,itwillaskforvariouskeys/secretsandURLsforthegeneratingtheAccessTokenthatisusedintheOAuthauthenticationandintheendoutputaXMLfragmentlikebelow.

$./teiid-oauth-util.sh

SelecttypeofOAuthauthentication

1)OAuth1.0A

2)OAuth2.0

2

===OAuth2.0Workflow===


49

http://oauth.org

http://google.com

http://twitter.com

https://developers.google.com/accounts/docs/OAuth2

EntertheClientID=10-xxxjb.apps.googleusercontent.com

EntertheClientSecret=3L6-xxx-v9xxDlznWq-o

EntertheUserAuthorizationURL=https://accounts.google.com/o/oauth2/auth

Enterscope(hitenterfornone)=profile

Cut&PastetheURLinawebbrowser,andAuthticate

AuthorizeURL=https://accounts.google.com/o/oauth2/auth?client_id=10-

xxxjb.apps.googleusercontent.com&scope=profile&response_type=code&redirect_uri=urn%

3Aietf%3Awg%3Aoauth%3A2.0%3Aoob&state=Auth+URL

EnterTokenSecret(AuthCode,Pin)frompreviousstep=4/z-RT632cr2hf_vYoXd06yIM-

xxxxx

EntertheAccessTokenURL=https://www.googleapis.com/oauth2/v3/token

RefreshToken=1/xxxx_5qzAF52j-EmN2U

AddthefollowingXMLintoyourstandalone-teiid.xmlfileinsecurity-domains

subsystem,

andconfiguredatasourcesecurtytothisdomain

<security-domainname="oauth2-security">

<authentication>

<login-modulecode="org.teiid.jboss.oauth.OAuth20LoginModule"

flag="required"module="org.jboss.teiid.web.cxf">

<module-optionname="client-id"value="10-

xxxjb.apps.googleusercontent.com"/>

<module-optionname="client-secret"value="3L6-xxx-v9xxDlznWq-o"/>

<module-optionname="refresh-token"value="1/xxxx_5qzAF52j-EmN2U"/>

<module-optionname="access-token-uri"

value="https://www.googleapis.com/oauth2/v3/token"/>

</login-module>

</authentication>

</security-domain>

TheXMLfragmentattheenddefinestheJAASLoginModuleconfiguration,editthestandalone-teiid.xmlandadditunder"security-domains"subsystem.Userneedstousethissecurity-domainintheirresourceadapterasthesecurityproviderforthisdatasource.Anexampleresource-adapterconfigurationtodefinethedatasourcetothewebsiteinstandalone-teiid.xmlfilelookslike

<resource-adapterid="webservice3">

<moduleslot="main"id="org.jboss.teiid.resource-adapter.webservice"/>

<transaction-support>NoTransaction</transaction-support>


<connection-definitionclass-name="org.teiid.resource.adapter.ws.WSManagedConnectionFactory"jndi-name=

"java:/googleDS"enabled="true"use-java-context="true"pool-name="teiid-ws-ds">

<config-propertyname="SecurityType">

OAuth

</config-property>


50

<security>

<security-domain>oauth2-security</security-domain>

</security>



</resource-adapter>

---

Then,anyquerywrittenusingthe"ws"translatorandaboveresource-adapterwillbeautomaticallyAuthorizedw

iththetargetwebsiteusingOAuth,whenyouaccessaprotectedURL.

===OAuthwithDelegation

Intheaboveconfigurationasingleuserisconfiguredtoaccessthewebsite,howeverifyouwanttodelegate

loggedinuser’scredentialasOAuthauthentication,thenuserneedstoextendtheaboveLoginModule

_(org.teiid.jboss.oauth.OAuth20LoginModuleororg.teiid.jboss.oauth.OAuth10LoginModule)_andautomatetheproce

ssdefinedinthe"teiid-oauth-util.sh"todefinetheAccessToken

detailsdynamically.Sincethisprocesswillbedifferentfordifferentwebsites(itinvolvesloginandauthen

tication),Teiidwillnotbeabletoprovidesinglesolution.However,usercanextendtheloginmoduletoprov

idethisfeaturemuchmoreeasilysincetheywillbeworkingwithtargetedwebsites.


51

CoherenceDataSourcesCoherencedatasourcesuseaTeiidspecificJCAconnectorthatisdeployedintoWildFly9.0.2duringinstallation.ThisconnectorcanbeconfiguredtosupportrunningCoherencewithinthesameVMasTeiidorasaremotecache.

Thefollowingaretheconfigurationpropertiesthatcanbeconfiguredforthisconnector:


CacheName Y NameoftheCoherenceCachetoreadandwriteto

CacheClassName Y NameoftheClassstoredintheCoherenceCache

PrimaryKeyFieldName YThenameoftheattributethatidentifiestheprimarykeytotheCache

PrimaryKeyFieldClassName N

[Optional]Theprimarykeyclassnamethatidentifieshowthekeyisstoredinthecache,ifdifferentthantheobjecttypeoftheprimarykeyfield

Therearemanywaystocreatethedatasource,usingCLI,AdminShell,admin-consoleetc.TheexampleshownbelowusestheCLItool,asthisworksinbothStandaloneandDomainmodes.

ExecutefollowingcommandusingCLIonceyouconnectedtotheServer.Makesureyouprovidethecorrectdirectorynameandotherpropertiesbelow.Addanyadditionalpropertiesrequiredbytheconnectorbyduplicatingthe"connection-definitions"commandbelow.EdittheJNDInametomatchtheJNDInameyouusedinVDB.Thisscriptcanbefoundinthegithubrepository.

batch

/subsystem=resource-adapters/resource-adapter=coherence:add(module=org.jboss.teiid.resource-adapter.coherence)

/subsystem=resource-adapters/resource-adapter=coherence/connection-definitions=coherenceDS:add(jndi-name="java:

/coherenceDS",class-name=org.teiid.resource.adapter.coherence.CoherenceManagedConnectionFactory,enabled="true

",use-java-context="true")

/subsystem=resource-adapters/resource-adapter=coherence/connection-definitions=coherenceDS/config-properties=Ca

cheName:add(value="class.name")

/subsystem=resource-adapters/resource-adapter=coherence/connection-definitions=coherenceDS/config-properties=Ca

cheClassName:add(value="cache.class.name")

/subsystem=resource-adapters/resource-adapter=coherence/connection-definitions=coherenceDS/config-properties=Pr

imaryKeyFieldName:add(value="key.name")

#/subsystem=resource-adapters/resource-adapter=coherence/connection-definitions=coherenceDS/config-properties=P

rimaryKeyFieldClassName:add(value="${key.field.class.name}")

/subsystem=resource-adapters/resource-adapter=coherence:activaterunbatch

TofindoutallthepropertiesthataresupportedbythisCoherenceConnectorexecutethefollowingcommandintheCLI.

/subsystem=teiid:read-rar-description(rar-name=coherence)

Tip

Developer’sTip-IfWildFly9.0.2isrunninginstandalonemode,youcanalsomanuallyeditthe"<jboss-install>/standalone/configuration/standalone-teiid.xml"fileandaddtheXMLconfiguration.Anexampleofwhatcanbecopyandpastedcanbefoundinthegithubrepository.Shutdowntheserverbeforeyoueditthisfile,andrestartafterthemodificationsaredone.


52


https://github.com/teiid/teiid-coherence/blob/master/connector-coherence/kits/jboss-as7/docs/teiid/datasources/coherence/create-coherence-ds.cli

https://github.com/teiid/teiid-coherence/blob/master/connector-coherence/kits/jboss-as7/docs/teiid/datasources/coherence/coherence-ds.xml


53

VDBVersioningVDBVersioningisafeaturethatallowsmultipleversionsofaVDBtobedeployedatthesametimewithadditionalsupporttodeterminewhichversionwillbeused.Ifaspecificversionisrequested,thenonlythatVDBmaybeconnectedto.Ifnoversionisset,thenthedeployedVDBsaresearchedfortheappropriateversion.Thisfeaturehelpssupportmorefluidmigrationscenarios.

VersionProperty

WhenauserconnectstoTeiidthedesiredVDBversioncanbesetasaconnectionproperty(SeetheClientDeveloper’sGuide)inJDBCorusedaspartoftheVDBnameforODataandODBCaccess.

Thevdbversionissetineitherthevdb.xml,whichisusefulforanxmlfiledeployment,orthroughanamingconventionofthedeploymentname-vdbname.version.vdb,e.g.marketdata.2.vdb.Thedeployerisresponsibleforchoosinganappropriateversionnumber.IfthereisalreadyaVDBname/versionthatmatchesthecurrentdeployment,thenconnectionstothepreviousVDBwillbeterminatedanditscacheentrieswillbeflushed.AnynewconnectionswillthenbemadetothenewVDB.

AsimpleintegerversionactuallytreatedasthesemanticversionX.0.0.Ifdesiredafullsemanticversioncanbeusedinstead.Asemanticversionisuptothreeintegersseparatedbyperiods.

Trailingversioncomponentsthataremissingaretreatedaszeros-version1isthesameas1.0.0andversion1.1isthesameas1.1.0.

JDBCandODBCclientsmayuseaversionrestriction--vdbname.X.orvdbname.X.X.-notethetrailing'.'whichmeansaVDBthatmustmatchthepartialversionspecified.Forexamplevdbname.1.2.couldmatchany1.2.Xversion,butwouldnotallow1.3+or1.1andearlier.

ConnectionTypeOncedeployedaVDBhasanupdatablepropertycalledconnectiontype,whichisusedtodeterminewhatconnectionscanbemadetotheVDB.Theconnectiontypecanbeoneof:

NONE-disallownewconnections.

BY_VERSION-thedefaultsetting.AllowconnectionsonlyiftheversionisspecifiedorifthisistheearliestBY_VERSIONvdbandtherearenovdbsmarkedasANY.

ANY-allowconnectionswithorwithoutaversionspecified.

TheconnectiontypemaybechangedeitherthroughtheAdminConsoleortheAdminAPI.

DeploymentScenarios

IfonlyaselectfewapplicationsaretomigratetothenewVDBversion,thenafreshlydeployedVDBwouldbeleftasBY_VERSION.Thisensuresthatonlyapplicationsthatknowthenewversionmayuseit.

IfonlyaselectfewapplicationsaretoremainonthecurrentVDBversion,thentheirconnectionsettingswouldneedtobeupdatedtoreferencethecurrentVDBbyitsversion.ThenthenewlydeployedvdbwouldhaveitsconnectiontypesettoANY,whichallowsallnewconnectionstobemadeagainstthenewerversion.Ifarollbackisneededinthisscenario,thenthenewlydeployedvdbwouldhaveitsconnectiontypesettoNONEorBY_VERSIONaccordingly.

VDBVersioning

54

VDBVersioning

55

LoggingTheTeiidsystemprovidesawealthofinformationvialogging.Tocontrollogginglevel,contexts,andloglocations,youshouldbefamiliarwithlog4jandthecontainer’sstandalone-teiid.xmlordomain-teiid.xmlconfigurationfilesdependinguponthestartupmodeofWildFly.

AllthelogsproducedbyTeiidareprefixedby"org.teiid".ThismakesitextremelyeasytocontrolofofTeiidloggingfromasinglecontext.Notehoweverthatchangestothelogconfigurationfilemanuallyrequirearestarttotakeaffect.CLIbasedlogcontextmodificationsarepossible,howeverdetailsarebeyondthescopeofthisdocument.

Ifyouexpectahighvolumeoflogginginformationoruseexpensivecustomaudit/commandloggers,itisagoodideatouseanaynchappendertominimizetheperformanceimpact.Forexampleyoucanuseaconfigurationsnippetliketheonebelowtoinsertanasynchhandlerinfrontofthetargetappender.

<periodic-rotating-file-handlername="COMMAND_FILE">

<levelname="DEBUG"/>

<formatter>

<pattern-formatterpattern="%d{HH:mm:ss,SSS}%-5p[%c](%t)%s%E%n"/>

</formatter>

<filerelative-to="jboss.server.log.dir"path="command.log"/>

<suffixvalue=".yyyy-MM-dd"/>

</periodic-rotating-file-handler>

<async-handlername="ASYNC">


<queue-lengthvalue="1024"/>

<overflow-actionvalue="block"/>

<subhandlers>

<handlername="COMMAND_FILE"/>

</subhandlers>

</async-handler>

<loggercategory="org.teiid.COMMAND_LOG">


<handlers>

<handlername="ASYNC"/>

</handlers>

</logger>

LoggingContextsWhileallofTeiid’slogsareprefixedwith"org.teiid",therearemorespecificcontextsdependingonthefunctionalareaofthesystem.Notethatlogsoriginatingfromthird-partycode,includingintegratedorg.jbosscomponents,willbeloggedthroughtheirrespectivecontextsandnotthrough"org.teiid".SeethetablebelowforinformationoncontextsrelevanttoTeiid.Seethecontainer’sstandalone-teiid.xmlforamorecompletelistingofloggingcontextsusedinthecontainer.

Context Description

com.arjuna Third-partytransactionmanager.Thiswillincludeinformationaboutalltransactions,notjustthoseforTeiid.

org.teiidRootcontextforallTeiidlogs.Note:therearepotentiallyothercontextsusedunderorg.teiidthanareshowninthistable.

org.teiid.PROCESSOR Queryprocessinglogs.Seealsoorg.teiid.PLANNERforqueryplanninglogs.

Logging

56

http://logging.apache.org/log4j/

org.teiid.PLANNER Queryplanninglogs.

org.teiid.SECURITY Session/Authenticationevents-seealsoAUDITlogging

org.teiid.TRANSPORT Eventsrelatedtothesockettransport.

org.teiid.RUNTIME Eventsrelatedtoworkmanagementandsystemstart/stop.

org.teiid.CONNECTOR Connectorlogs.

org.teiid.BUFFER_MGR Bufferandstoragemanagementlogs.

org.teiid.TXN_LOG Detaillogofalltransactionoperations.

org.teiid.COMMAND_LOG Seecommandlogging

org.teiid.AUDIT_LOG Seeauditlogging

org.teiid.ADMIN_API AdminAPIlogs.

org.teiid.ODBC ODBClogs.

CommandLogging

CommandloggingcapturesexecutingcommandsintheTeiidSystem.Thisincludesusercommands(thathavebeensubmittedtoTeiidatanINFOlevel),datasourcecommands(thatarebeingexecutedbytheconnectorsataDEBUGlevel),andqueryplancommands(forwhenthequeryplanningisperformedataTRACElevel)aretrackedthroughcommandlogging.

Theusercommand,"STARTUSERCOMMAND",isloggedwhenTeiidstartsworkingonthequeryforthefirsttime.Thisdoesnotincludethetimethequerywaswaitinginthequeue.Andacorrespondingusercommand,"ENDUSERCOMMAND",isloggedwhentherequestiscomplete(i.e.whenstatementisclosedorallthebatchesareretrieved).Thereisonlyonepairoftheseforeveryuserquery.

Thequeryplancommand,"PLANUSERCOMMAND",isloggedwhenTeiidfinishesthequeryplanningprocess.Thereisnocorrespondingendinglogentry.

Thedatasourcecommand,"STARTDATASRCCOMMAND",isloggedwhenaqueryissenttothedatasource.Andacorrespondingdatasourcecommand,"ENDSRCCOMMAND",isloggedwhentheexecutionisclosed(i.ealltherowshasbeenread).TherecanbeonepairforeachdatasourcequerythathasbeenexecutedbyTeiid,andtherecanbenumberofpairsdependinguponyourquery.

Withthisinformationbeingcaptured,theoverallqueryexecutiontimeinTeiidcanbecalculated.Additionally,eachsourcequeryexecutiontimecanbecalculated.Iftheoverallqueryexecutiontimeisshowingaperformanceissue,thenlookateachdatasourceexecutiontimetoseewheretheissuemaybe.

Toenablecommandloggingtothedefaultloglocation,simplyenabletheDETAILlevelofloggingfortheorg.teiid.COMMAND_LOGcontext.

Note "Wanttologtoadatabase?"-IfyouwouldliketologCommandlogmessagestoanydatabase,thenlookatthehttps://github.com/teiid/teiid-extensionsproject.TheinstallationzipfileisavailableinTeiiddownloadspage.

Logging

57

https://github.com/teiid/teiid-extensions

Toenablecommandloggingtoanalternativefilelocation,configureaseparatefileappenderfortheDETAILloggingoftheorg.teiid.COMMAND_LOGcontext.Anexampleofthisisshownbelowandcanalsobefoundinthestandalone-teiid.xmldistributedwithTeiid.

<periodic-rotating-file-handlername="COMMAND_FILE">


<formatter>

<pattern-formatterpattern="%d{HH:mm:ss,SSS}%-5p[%c](%t)%s%E%n"/>

</formatter>

<filerelative-to="jboss.server.log.dir"path="command.log"/>

<suffixvalue=".yyyy-MM-dd"/>

</periodic-rotating-file-handler>



<handlers>

<handlername="COMMAND_FILE"/>

</handlers>

</logger>

SeetheDeveloper’sGuidetodevelopacustomloggingsolutioniffilebasedlogging,oranyotherbuilt-inLog4jlogging,isnotsufficient.

Thefollowingisanexampleofadatasourcecommandandwhatonewouldlooklikewhenprintedtothecommandlog:

2012-02-2216:01:53,712DEBUG[org.teiid.COMMAND_LOG](Worker1_QueryProcessorQueue11STARTDATASRCCOMMAND:st

artTime=2012-02-2216:01:53.712

requestID=Ku4/dgtZPYk0.5sourceCommandID=4txID=nullmodelName=DTHCPtranslatorName=jdbc-simplesessionID=Ku4/d

gtZPYk0

principal=user@teiid-security

sql=HCP_ADDR_XREF.HUB_ADDR_ID,CPN_PROMO_HIST.PROMO_STAT_DTFROMCPN_PROMO_HIST,HCP_ADDRESS,HCP_ADDR_XREF

WHERE(HCP_ADDRESS.ADDR_ID=CPN_PROMO_HIST.SENT_ADDR_ID)AND(HCP_ADDRESS.ADDR_ID=HCP_ADDR_XREF.ADDR_ID)AND

(CPN_PROMO_HIST.PROMO_STAT_CDNOTLIKE'EMAIL%')AND(CPN_PROMO_HIST.PROMO_STAT_CD<>'SENT_EM')AND

(CPN_PROMO_HIST.PROMO_STAT_DT>{ts'2010-02-2216:01:52.928'})

Notethefollowingpiecesofinformation:

modelName:thisrepresentsthephysicalmodelforthedatasourcethatthequeryisbeingissued.

translatorName:showstypeoftranslatorusedtocommunicatetothedatasource.

principal:showstheuseraccountwhosubmittedthequery

startTime/endTime:thetimeoftheaction,whichisbasedonthetypecommandbeingexecuted.

sql:isthecommandsubmittedtotheengineortothetranslatorforexecution-whichisNOTnecessarilythefinalsqlcommandsubmittedtotheactualdatasource.Butitdoesshowwhatthequeryenginedecidedtopushdown.

ENDeventswilladditionallycontain:

finalRowCount:thenumberofrowsreturnedtotheenginebythesourcequery.

cpuTime:thenumberofnanosecondsofcputimeusedbythesourcecommand.Canbecomparedtothestart/endwallclocktimestodeterminecpuvs.idletime.

AuditLogging

Auditloggingcapturesimportantsecurityevents.Thisincludestheenforcementofpermissions,authenticationsuccess/failures,etc.

Logging

58

Toenableauditloggingtothedefaultloglocation,simplyenabletheDEBUGlevelofloggingfortheorg.teiid.AUDIT_LOGcontext.

Note"Wanttologtoadatabase?"-IfyouwouldliketologAuditlogmessagestoanydatabase,thenlookatthehttps://github.com/teiid/teiid-extensionsproject.TheinstallationzipfilewillbeavailableinTeiiddownloadspage.

Toenableauditloggingtoanalternativefilelocation,configureaseparatefileappenderfortheDETAILloggingoftheorg.teiid.AUDIT_LOGcontext.SeetheDeveloper’sGuidetodevelopacustomloggingsolutioniffilebased,oranyotherbuilt-inLog4j,loggingisnotsufficient.

AdditionalLoggingInformationOnceasessionhasbeencreated,eachlogmadebyTeiidwillincludethesessionidandvdbname/versionintheMDC(mappeddiagnosticcontext)withkeysofteiid-sessionandteiid-vdbrespectively.

AnyloginthescopeofaquerywillincludetherequestidintheMDCwithkeyofteiid-request.

Customloggers,orformatpatterns,cantakeadvantageofthisinformationtobettercorrelatelogentries.SeeforexampleTeiiddefaultstandalone-teiid.xmlthatusesapatternformatwhichincludesthesessionidpriortothemessage:

<pattern-formatterpattern="%d{HH:mm:ss,SSS}%-5p[%c](%t)%X{teiid-session}%s%E%n"/>

Logging

59

https://github.com/teiid/teiid-extensions

ClusteringinTeiidSinceTeiidisinstalledinWildFly,thereisnoadditionalconfigurationneededbeyondwhatwasperformedwhenTeiidissetupinDomainMode.SeetheDomainModesectionintheTeiidInstallationGuide.JustmakesurethatyouinstalledTeiidineveryWildFlynodeandstartedallWildFlyinstancesintheDomainmodethattobeapartofthecluster.

Typicallyuserscreateclusterstoimprovetheperformanceofthesystemthrough:

LoadBalancing:TakelookattheClientDeveloper’sGuideonhowtouseloadbalancingbetweenmultiplenodes.

FailOver:TakelookattheClientDeveloper’sGuideonhowtousefailoverbetweenmultiplenodes.

DistributedCaching:Thisisautomaticallydoneforyouonceyouconfigureitasspecifiedabove.

Eventdistribution:metadataanddatamodificationswillbedistributedtoallclustermembers.

IntheDomainmode,theonlywayausercandeployanyartifactsisusingeitherCLIorusingtheAdminAPIorAdminShell.CopyingVDBdirectlyintothe"deployments"directoryisnotsupported.

ClusteringinTeiid

60

MonitoringTeiidprovidesinformationaboutitscurrentoperationalstate.Thisinformationcanbeusefulintuning,monitoring,andmanagingloadandthrough-put.Theruntimedatacanbeaccessedusingadministrativetools(i.e.AdminConsole,AdminShellorAdminAPI).

Query/Sessiondetails:

Name Description

CurrentSessions Listcurrentconnectedsessions

CurrentRequest Listcurrentexecutingrequests

CurrentTransactions Listcurrentexecutingtransactions

QueryPlan Retrievesthequeryplanforaspecificrequest

Thereareadministrativeoptionsforterminatingsessions,queries,andtransactions.

Metrics:

Session/Query

Name Property Description Comment

SessionCount sessionCountIndicatesthenumberofuserconnectionscurrentlyactive

Toensurenumberofsessionsarenotrestrictedatpeaktimes,checkmax-sessions-allowed(default5000)issetaccordinglyandreviewsessions-expiration-timelimit

QueryCount queryCount Indicatesthenumberofqueriescurrentlyactive.

ActiveQueryPlanCount

ENGINE_STATISTIC.active-plans-count

Numberofqueryplanscurrentlybeingprocessed

Toensuremaximumthrough-put,seetheQueryEnginesectioninThreadingontuning.

WaitingQueryPlanCount

ENGINE_STATISTIC.waiting-plans-count

Numberofqueryplanscurrentlywaiting

MaxWaitingQueryPlanWatermark

ENGINE_STATISTIC.max-waitplan-watermark

Themaximumnumberofqueryplansthathavebeenwaitingatonetime,sincethelasttimetheserverstarted

Monitoring

61

LongRunningQueries longRunningQueries

Listcurrentexecutingqueriesthathavesurpassedthequerythreshold(query-threshold-in-seconds).

Setupalerttowarnwhenoneormorequeriesareconsumingresourcesforanextendedperiodoftime.Ifrunningtoolong,anoptionistocancelrequestorincreasethreshold.

BufferManager

Fortuningsuggestions,seeMemoryManagement.

Name Property Description Comment

DiskWriteCount ENGINE_STATISTIC.buffermgr-disk-write-count

Diskwritecountforthebuffermanager.

DiskReadCount ENGINE_STATISTIC.buffermgr-disk-read-count

Diskreadcountforthebuffermanager.

CacheWriteCount ENGINE_STATISTIC.buffermgr-cache-write-count

Cachewritecountforthebuffermanager.

CacheReadCount ENGINE_STATISTIC.buffermgr-cache-read-count

Cachereadcountforthebuffermanager.

DiskSpaceUsed(MB) ENGINE_STATISTIC.buffermgr-diskspace-used-mb

Indicatesamountofstoragespacecurrentlyusedbybufferfiles

Setupalerttowarnwhenusedbufferspaceisatanunacceptablelevel,basedonthesettingofmax-buffer-space

Totalmemoryinuse(KB)

ENGINE_STATISTIC.total-memory-inuse-kb

Estimateofthecurrentmemoryusageinkilobytes.

Totalmemoryinusebyactiveplans(KB)

ENGINE_STATISTIC.total-memory-inuse-active-plans-kb

Estimateofthecurrentmemoryusagebyactiveplansinkilobytes

Plan/ResultCache

Fortuningsuggestions,seeCacheTuning.

Name Property Description

PreparedPlanCacheSize PREPARED_PLAN_CACHE.total-entries Currentnumberofentriesincache.

PreparedPlanCache#ofRequests PREPARED_PLAN_CACHE.request-count Totalnumberofrequests

madeagainstcache.

PreparedPlanCacheHitRatio% PREPARED_PLAN_CACHE.hit-ratio Percentageofpositivecache

hits

ResultSetCacheSizeQUERY_SERVICE_RESULT_SET_CACHE.total-entries

Currentnumberofentriesincache.

Monitoring

62

ResultSetCache#ofRequests

QUERY_SERVICE_RESULT_SET_CACHE.request-count

Totalnumberofrequestsmadeagainstcache.

ResultSetCacheHitRatio% QUERY_SERVICE_RESULT_SET_CACHE.hit-ratio Percentageofpositivecache

hits.

Monitoring

63

PerformanceTuningPerformancetuningcanbedonebychangingthepropertysettingsdefinedintheteiidsubsystemanditssubcomponents.

ExecutethefollowingcommandonCLItoseethepossiblesettingsattherootoftheteiidsubsystem:

/subsystem=teiid:read-resource-description

Thereareseveralcategoriesofproperties:

1. MemoryManagement

2. BufferManager:allpropertiesthatstartwith"buffer-service"

3. CacheTuning:allpropertiesthatstartwith"resultset-cache"or"preparedplan-cache"

4. Threading

5. LOBs

6. OtherConsiderations

SocketTransportsettingsforoneofthesupportedtransporttypes(i.e.,jdbc,odbc,embedded)canbeviewedbyexecutingthefollowingcommand:

/subsystem=teiid/transport={jdbc|odbc|embedded}:read-resource-description

PerformanceTuning

64

MemoryManagementTheBufferManagerisresponsiblefortrackingbothmemoryanddiskusagebyTeiid.ConfiguringtheBufferManagerproperlyalongwithdatasourcesandthreadingensureshighperformance.InmostinstancesthoughthedefaultsettingsaresufficientastheywillscalewiththeJVMandconsiderotherpropertiessuchasthesettingformaxactiveplans.

ExecutefollowingcommandonCLItofindallpossiblesettingsonBufferManager:

/subsystem=teiid:read-resource

Allthepropertiesthatstartwith"buffer-service"usedtoconfigureBufferManager.ShownbelowaretheCLIwriteattributecommandstochangeBufferManager’ssettings(allshowthedefaultsetting):

/subsystem=teiid:write-attribute(name=buffer-service-use-disk,value=true)

/subsystem=teiid:write-attribute(name=buffer-service-encrypt-files,value=false)

/subsystem=teiid:write-attribute(name=buffer-service-processor-batch-size,value=256)

/subsystem=teiid:write-attribute(name=buffer-service-max-open-files,value=64)

/subsystem=teiid:write-attribute(name=buffer-service-max-file-size,value=2048)

/subsystem=teiid:write-attribute(name=buffer-service-max-processing-kb,value=-1)

/subsystem=teiid:write-attribute(name=buffer-service-max-reserve-kb,value=-1)

/subsystem=teiid:write-attribute(name=buffer-service-max-buffer-space,value=51200)

/subsystem=teiid:write-attribute(name=buffer-service-max-inline-lobs,value=true)

/subsystem=teiid:write-attribute(name=buffer-service-memory-buffer-space,value=-1)

/subsystem=teiid:write-attribute(name=buffer-service-max-storage-object-size,value=8388608)

/subsystem=teiid:write-attribute(name=buffer-service-memory-buffer-off-heap,value=false)

Note Notethatitisnotrecommendthattochangethesepropertiesuntilthereisanunderstandingoftheproperties(elaboratedbelow)andanypotentialissuethatisbeingexperienced.

SomeofBufferManager’spropertiesaredescribedbelow.Notethattheperformancetuningadviceishighlightedininfoboxes.

max-reserve-kb(default-1)-settingdeterminesthetotalsizeinkilobytesofbatchesthatcanbeheldbytheBufferManagerinmemory.Thisnumberdoesnotaccountforpersistentbatchesheldbysoft(suchasindexpages)orweakreferences.Thedefaultvalueof-1willauto-calculateatypicalmaxbaseduponthemaxheapavailabletotheVM.Theauto-calculatedvalueassumesa64bitarchitectureandwilllimitbufferusageto40%ofthefirstgigabyteofmemorybeyondthefirst300megabytes(whichareassumedforusebytheASandotherTeiidpurposes)and50%ofthememorybeyondthat.Theadditionalcaveathereisthatifthesizeofthememorybufferspaceisnotspecified,thenitwilleffectivelybeallocatedoutofthemaxreservespace.Asmalladjustmentisalsomadetothemaxreservetoaccountforbatchtrackingoverhead.

Note Withdefaultsettingsandan8GBVMsize,thenmax-reserve-kbwillatamaxuse:(1024-300)*0.4)+(7*1024*0.5=4373.6MBor4,478,566KB

TheBufferManagerautomaticallytriggerstheuseofacanonicalvaluecacheifenabledwhenmorethan25%ofthereserveisinuse.ThiscandramaticallycutthememoryusageinsituationswheresimilarvaluesetsarebeingreadthroughTeiid,butdoesintroducealookupcost.IfyouareprocessingsmallorhighlysimilardatasetsthroughTeiid,andwishtoconservememory,youshouldconsiderenablingvaluecaching.

Warning

Memoryconsumptioncanbesignificantlymoreorlessthanthenominaltargetdependinguponactualcolumnvaluesandwhethervaluecachingisenabled.Largenonbuilt-intypeobjectscanexceedtheirdefaultsizeestimate.Ifanoutofmemoryerrorsoccur,thensetalowermax-reserve-kbvalue.Alsonotethatsourcelobvaluesareheldbymemoryreferencesthatarenotclearedwhenabatchispersisted.Withheavylobusageyoushouldensurethatbuffersofothermemoryassociatedwithlobreferencesareappropriatelysized.

MemoryManagement

65

max-processing-kb(default-1)-settingdeterminesthetotalsizeinkilobytesofbatchesthatcanbeguaranteedforusebyoneactiveplanandmaybeinadditiontothememoryheldbasedonmax-reserve-kb.TypicalminimummemoryrequiredbyTeiidwhenalltheactiveplansareactiveis#active-plans*max-processing-kb.Thedefaultvalueof-1willauto-calculateatypicalmaxbaseduponthemaxheapavailabletotheVMandmaxactiveplans.Theauto-calculatedvalueassumesa64bitarchitectureandwilllimitnominalprocessingbatchusagetolessthan10%oftotalmemory.

Note

Withdefaultsettingsincluding20active-plansandan8GBVMsize,thenmax-processing-kbwillbe:(.07*8*1024)/20^.8=537.4MB/11=52.2MBor53,453KBperplan.Thisimpliesanominalrangebetween0and1060MBthatmaybereservedwithroughly53MBperplan.Youshouldbecautiousinadjustingmax-processing-kbonyourown.Typicallyitwillnotneedadjustedunlessyouareseeingsituationswhereplansseemmemoryconstrainedwithlowperforminglargesorts.

max-file-size(default2GB)-Eachintermediateresultbuffer,temporaryLOB,andtemporarytableisstoredinitsownsetofbufferfiles,whereanindividualfileislimitedtomax-file-sizemegabytes.Considerincreasingthestoragespaceavailabletoallsuchfilesbyincreasingmax-buffer-space,ifyourinstallationmakesuseofinternalmaterialization,makesheavyuseofSQL/XML,orprocesseslargerowcounts.

processor-batch-size(default256)-Specifiesthetargetrowcountofabatchofthequeryprocessor.Abatchisusedtorepresentbothlineardatastores,suchassavedresults,andtemporarytablepages.Teiidwilladjusttheprocessor-batch-sizetoaworkingsizebaseduponanestimateofthedatawidthofarowrelativetoanominalexpectationof2KB.Thebasevaluecanbedoubledorhalveduptothreetimesdependinguponthedatawidthestimation.Forexampleasinglesmallfixedwidth(suchasaninteger)columnbatchwillhaveaworkingsizeofprocessor-batch-size*8rows.Abatchwithhundredsofvariablewidthdata(suchasstring)willhaveaworkingsizeofprocessor-batch-size/8rows.Anyincreaseintheprocessorbatchsizebeyondthefirstdoublingshouldbeaccompaniedwithaproportionalincreaseinthemax-storage-object-sizetoaccommodatethelargerstoragesizeofthebatches.

Note

AdditionalconsiderationsareneedediflargeVMsizesand/ordatasetsarebeingused.Teiidhasanon-negligibleamountofoverheadperbatch/tablepageontheorderof100-200bytes.IfyouaredealingwithdatasetswithbillionsofrowsandyourunintoOutOfMemoryissues,considerincreasingtheprocessor-batch-sizetoforcetheallocationoflargerbatchesandtablepages.Ageneralguidelinewouldbetodoubleprocessor-batch-sizeforeverydoublingoftheeffectiveheapforTeiidbeyond4GB-processor-batch-size=512foran8GBheap,processor-batch-size=1024fora16GBheap,etc.

max-storage-object-size(default8288608or8MB)-Themaximumsizeofabufferedmanagedobjectinbytesandrepresentstheindividualbatchpagesize.Iftheprocessor-batch-sizeisincreasedand/oryouaredealingwithextremelywideresultsets(severalhundredcolumns),thenthedefaultsettingof8MBforthemax-storage-object-sizemaybetoolow.Theinline-lobssettingalsocanincreasethesizeofbatchescontainingsmalllobs.Thesizingformax-storage-object-sizeisintermsofserializedsize,whichwillbemuchclosertotherawdatasizethantheJavamemoryfootprintestimationusedformax-reserved-kb.max-storage-object-sizeshouldnotbesettoolargerelativetomemory-buffer-spacesinceitwillreducetheperformanceofthememorybuffer.Thememorybuffersupportsonly1concurrentwriterforeachmax-storage-object-sizeofthememory-buffer-space.Notethatthisvaluedoesnottypicallyneedtobeadjustedunlesstheprocessor-batch-sizeisadjusted,inwhichcaseconsideradjustingitinproportiontotheincreaseoftheprocessor-batch-size.

NoteIfexceptionsoccurrelatedtomissingbatchesand"TEIID30001Maxblocknumberexceeded"isseenintheserverlog,thenincreasethemax-storage-object-sizetosupportlargerstorageobjects.Alternativelyyoucouldmaketheprocessor-batch-sizesmaller.

memory-buffer-space(default-1)-ThiscontrolstheamountofonoroffheapmemoryallocatedasbytebuffersforusebytheTeiidbuffermanagermeasuredinmegabytes.Thissettingdefaultsto-1,whichautomaticallydeterminesasettingbaseduponwhetheritisonoroffheapandthevalueformax-reserve-kb.Thememorybuffersupportsonly1concurrentwriterforeachmax-storage-object-sizeofthememory-buffer-space.Anyadditionalspaceservesasacachefortheserializedforofbatches.

Note

Whenleftatthedefaultsettingthecalculatedmemorybufferspacewillbeapproximately40%ofthemax-reserve-kbsize.Ifthememorybufferisonheapandthemax-reserve-kbisautomaticallycalculated,thenthememorybufferspacewillbesubtractedoutoftheeffectivemax-reserve-kb.Ifthememorybufferisoffheapandthemax-reserve-kbisautomaticallycalculated,thenit’ssizewillbereducedslightlytoallowforeffectivelymoreworkingmemoryinthevm.

MemoryManagement

66

memory-buffer-off-heap(defaultfalse)-TakeadvantageoftheBufferManagermemorybuffertoaccesssystemmemorywithoutallocatingittotheheap.Settingmemory-buffer-off-heapto"true"willallocatetheTeiidmemorybufferoffheap.DependingonwhetheryourinstallationisdedicatedtoTeiidandtheamountofsystemmemoryavailable,thismaybepreferabletoon-heapallocation.TheprimarybenefitisadditionalmemoryusageforTeiidwithoutadditionalgarbagecollectiontuning.Thisbecomesespeciallyimportantinsituationswheremorethan32GBofmemoryisdesiredfortheVM.Notethatwhenusingoff-heapallocation,thememorymuststillbeavailabletothejavaprocessandthatsettingthevalueofmemory-buffer-spacetoohighmaycausetheVMtoswapratherthanresideinmemory.Withlargeoff-heapbuffersizes(greaterthanseveralgigabytes)youmayalsoneedtoadjustVMsettings.

Note

Oracle/SunVM-therelevantVMsettingsareMaxDirectMemorySizeandUseLargePages.Forexampleadding:'-XX:MaxDirectMemorySize=12g-XX:+UseLargePages'totheVMprocessargumentswouldallowforaneffectiveallocationofapproximatelyan11GBTeiidmemorybuffer(thememory-buffer-spacesetting)accountingforanyadditionaldirectmemorythatmaybeneededbytheASorapplicationsrunningintheAS.

DiskUsage

max-buffer-space(default-1)-Fortablepageandresultbatchesthebuffermanagerwillhavealimitednumberoffilesthatarededicatedtoaparticularstoragesize.However,asmentionedintheinstallation,creationofTeiidlobvalues(forexamplethroughSQL/XML)willtypicallycreateonefileperloboncethelobexceedstheallowableinmemorysizeof32KB.Inheavyusagescenarios,considerpointingthebufferdirectoryonapartitionthatisroutinelydefragmented.BydefaultTeiidwilluseupto50GBofdiskspace.ThisistrackedintermsofthenumberofbyteswrittenbyTeiid.Forlargedatasets,youmayneedtoincreasethemax-buffer-spacesetting.

Limitations

It’salsoimportanttokeepinmindthatTeiidhasmemoryandotherhardlimitswhichbreaksdownalongseverallinesintermsof#ofstorageobjectstracked,diskstorage,streamingdatasize/rowlimits,etc.

1. Thebuffermanagerhasamaxaddressablespaceof16terabytes-butduetofragmentationyou’dexpectthatthemaxusablewouldbeless.ThisisthemaximumamountofstorageavailabletoTeiidforalltemporarylobs,internaltables,intermediateresults,etc.

2. Themaxsizeofanobject(batchortablepage)thatcanbeserializedbythebuffermanageris32GB-butyoushouldapproachthatlimit(thedefaultlimitis8MB).Abatch/pageissetorrowsthatareflowingthroughTeiidengineandisdynamicallyscaledbasedupontheestimateddatawidthsothattheexpectedmemorysizeisconsistent.

3. Themax-processing-kbandmax-reserve-kbarebaseduponmemoryfootprintestimationsandnotexactsizes-actualmemoryusageandgarbagecollectioncyclesareinfluencedbyalotofotherfactors.

Handlingasourcethathastera/petabytesofdatadoesn’tbyitselfimpactTeiidinanyway.Whatmattersistheprocessingoperationsthatarebeingperformedand/orhowmuchofthatdatadoweneedtostoreonatemporarybasisinTeiid.Withasimpleforward-onlyquery,Teiidwillreturnapetabytesofdatawithminimalmemoryusage.

OtherConsiderationsforSizing

Eachbatch/tablepagerequiresaninmemorycacheentryofapproximately~128bytes-thusthetotaltrackedmaxbatchesarelimitedbytheheapandisalsowhywerecommendtoincreasetheprocessingbatchsizeonlargermemoryorscenariosmakinguseoflargeinternalmaterializations.Theactualbatch/tableitselfismanagedbybuffermanager,whichhaslayeredmemorybufferstructurewithspilloverfacilitytodisk.

UsinginternalmaterializationisbasedontheBufferManager.BufferManagersettingsmayneedtobeupdatedbaseduponthedesiredamountofinternalmaterializationperformedbydeployedvdbs.

MemoryManagement

67

Ifanoutofmemoryerroroccursitisbesttofirstcaptureaheapdumptodeterminewherememoryisbeingheld-tweakingtheBufferManagersettingsmaynotbenecessarydependinguponthecause.

CommonConfigurationScenarios

Inadditiontoscenariosoutlinedabove,acommonscenariowouldbetominimizetheamountofonheapspaceconsumedbyTeiid.Thiscanbedonebymovingthememorybuffertooffheapwiththememory-buffer-off-heapsettingorbyrestrictingthemax-reserve-kbsetting.Reducingthemax-processing-kbsettingshouldgenerallynotbenecessary,unlessthereisaneedtoseverlyrestricttheheapusagebeyondthemax-reserve-kbsetting.

MemoryManagement

68

Transport

max-socket-threads(default0)-Themaxnumberofthreadsdedicatedtotheinitialrequestprocessing.Zeroindicatestousethesystemdefaultofmaxavailableprocessors.AlltheaccesstoTeiid(JDBC,ODBC,etc)iscontrolledby"transport"elementintheconfiguration.Socketthreadsareconfiguredforeachtransport.TheyhandleNIOnon-blockingIOoperationsaswellasdirectlyservicinganyoperationthatcanrunwithoutblocking.Forlongerrunningoperations,thesocketthreadsqueuewithworkthequeryengine.

QueryEngine

max-threads(default64)-Thequeryenginehasseveralsettingsthatdetermineitsthreadutilization.max-threadssetsthetotalnumberofthreadsavailableintheprocesspoolforqueryenginework(processingplans,transactioncontroloperations,processingsourcequeries,etc.).Youshouldconsiderincreasingthemaximumthreadsonsystemswithalargenumberofavailableprocessorsand/orwhenit’scommontoissuenon-transactionalqueriesthatissuealargenumberofconcurrentsourcerequests.

max-active-plans(default20)-Shouldalwaysbesmallerthanmax-threads.Bydefault,thread-count-for-source-concurrencyiscalculatedby(max-threads/max_active_plans)*2todeterminethethreadsavailableforprocessingconcurrentsourcerequestsforeachuserquery.Increasingthemax-active-plansshouldbeconsideredforworkloadswithahighnumberoflongrunningqueriesand/orsystemswithalargenumberofavailableprocessors.Ifmemoryissuesarisefromincreasingthemax-threadsandmax-active-plans,thenconsiderdecreasingtheamountofheapheldbythebuffermanagerordecreasingtheprocessor-batch-sizetolimitthebasenumberofmemoryrowsconsumedbyeachplan.

thread-count-for-source-concurrency(default0)-Shouldalwaysbesmallerthanmax-threads,setsthenumberofconcurrentlyexecutingsourcequeriesperuserrequest.0indicatestousethedefaultcalculatedvaluebasedon2*(max-threads/max-active-plans).Settingthisto1forcesserialexecutionofallsourcequeriesbytheprocessingthread.Anynumbergreaterthan1limitsthemaximumnumberofconcurrentlyexecutionsourcerequestsaccording.Usingtherespectivedefaults,thismeansthateachuserrequestwouldbeallowed6concurrentlyexecutingsourcequeries.Ifthedefaultcalculatedvalueisnotapplicabletoyourworkload,forexample,ifyouhavequeriesthatgeneratemoreconcurrentlongrunningsourcequeries,youshouldadjustthisvalue.

time-slice-in-milliseconds(default2000)-Providescourseschedulingoflongrunningprocessorplans.Planswhoseexecutionexceedatimeslicewillbere-queuedforadditionalprocessingtoallowforotherplanstobeinitiated.Thetimesliceisfromtheperspectiveoftheengineprocessingthread.Thisvalueisnothonoredexactlyastheplanmaynotbeatare-startablepointwhenthetimesliceexpires.ThisisnotareplacementforthethreadschedulingperformedbyJavaandtheoperatingsystem,ratheritjustensuresthatTeiidallowsotherworktobestartedifthecurrentsetofactiveplansincludeslongrunningqueries.

Threading

69

CacheTuningCachingcanbetunedforcachedresults(includinguserqueryresultsandprocedureresults)andpreparedplans(includinguserandstoredprocedureplans).Eventhoughitispossibletodisableorotherwiseseverelyconstrainthesecaches,thiswouldprobablyneverbedoneinpracticeasitwouldleadtopoorperformance.

CachestatisticscanbeobtainedthroughtheAdminConsoleorAdminshell.Thestatisticscanbeusedtohelptunecacheparametersandensureahitratio.

Plansarecurrentlyfullyheldinmemoryandmayhaveasignificantmemoryfootprint.Whenmakingextensiveuseofpreparedstatementsand/orvirtualprocedures,thesizeoftheplancachemaybeincreasedproportionallytonumberofgigabytesintendedforusebyTeiid.

Whiletheresultcacheparameterscontrolthecacheresultentries(maxnumber,eviction,etc.),theresultbatchesthemselvesareaccessedthroughtheBufferManager.Ifthesizeoftheresultcacheisincreased,youmayneedtotunetheBufferManagerconfigurationtoensurethereisenoughbufferspace.

Resultsetandpreparedplancacheshavetheirentriesinvalidatedbydataandmetadataevents.BydefaulttheseeventsarecapturedbyrunningcommandsthroughTeiid.SeetheDevelopersGuideforfurthercustomization.Teiidstorescompiledformsofupdateplansortriggeractionswiththepreparedplan,sothatifmetadatachanges,forexamplebydisablingatrigger,changesmaytakeeffectimmediately.Thedefaultmax-stalenessforresultsetcachingis60secondstoimproveefficiencywithrapidlychangingsources.Considerdecreasingthisvaluetomaketheresultsetcachemoreconsistentwiththeunderlyingdata.Evenwithasettingof0,fulltransactionalconsistencyisnotguaranteed.

CacheTuning

70

SocketTransportsTeiidseparatestheconfigurationofitssockettransportsforJDBCandODBC.Typicalinstallationswillnotneedtoadjustthedefaultthreadandbuffersizesettings.Thedefaultvaluesforinput-buffer-sizeandoutput-buffer-sizearesetto0,whichwillusethesystemdefault.Beforeadjustingthesevalues,keepinmindthateachJDBC/ODBCconnectionwillcreateanewsocket.Settingthesevaluestoalargebuffersizeshouldonlybedoneifthenumberofclientsareconstrained.AllJDBC/ODBCsocketoperationsarenon-blocking,sosettingthenumberofmax-socket-threadshigherthanthemaximumeffectiveparallelismofthemachineshouldnotresultingreaterperformance.Thedefaultvalue0indicatesthesystemdefaultof2*availableprocessorswillbeused.

NoteIfyouareusingmorethanthe2defaultsockettransportsonamachinewithahighnumberofactualorvirtualcores,youmayneedtoconsidermanuallyconfiguringthemaxthreadsforeachtotransporttocutdownonthenumberofthreadscreated.

JDBCclientsmayneedtoadjustlow-leveltransportvalues,inadditiontoSSLClientConnectionpropertiesviaateiid-client-settings.propertiesfile.Thisfilealsocontainsbuffer,socketpooling,andmaxObjectSize(effectivelythemaximumresponsesize)settings.

SocketTransports

71

LOBsLOBsandXMLdocumentsarestreamedfromtheTeiidServertotheTeiidJDBCAPI.Normally,thesevaluesarenotmaterializedintheservermemory-avoidingpotentialout-of-memoryissues.Whenusingstylesheetsandnon-streamingXQuerywholeXMLdocumentsmustbematerializedontheserver.EvenwhenusingtheXMLQueryorXMLTablefunctionsanddocumentprojectionisapplied,memoryissuesmayoccurforlargedocuments.

LOBsarebrokenintopieceswhenbeingcreatedandstreamed.Themaximumsizeofeachpiecewhenfetchedbytheclientcanbeconfiguredwiththe"lob-chunk-size-in-kb"propertyonTeiidconfiguration.Thedefaultvalueis100KB.WhendealingwithextremelylargeLOBs,youmayconsiderincreasingthisvaluetodecreasetheamountofround-tripstostreamtheresult.Settingthevaluetoohighmaycausetheserverorclienttohavememoryissues.

SourceLOBvalues(LOBsfromphysicalsources)aretypicallyaccessedbyreference,ratherthanhavingthevaluecopiedtoatemporarylocation.ThuscaremustbetakentoensurethatsourceLOBsarereturnedinamemory-safemanner.ThiscautionismoreforthesourcedrivervendorstonottoconsumeVMmemoryforLOBs.TranslatorsviathecopyLobspropertycaninsteadcopylobvaluestoatemporarylocation.

Cachedlobswillbecopiedratherthanrelyingonthereferencetothesourcelob.

TemporarylobscreatedbyTeiidwillbecleanedupwhentheresultsetorstatementisclosed.Torelyonimplicitgarbagecollectionbasedcleanupinsteadofstatementclose,theTeiidsessionvariableclean_lobs_onclosecanbesettofalse(byissuingthequery"SELECTteiid_session_set(’clean_lobs_onclose’,false)"-whichcanbedoneforexampleviathenewconnectionsqlinthedatasourcedefinition).Thiscanbeusedforlocalclientscenariosthatreliedontheimplicitbehavior,suchasDesignergeneratedRESTVDBs.

LOBs

72

OtherConsiderationsWhenusingTeiidinadevelopmentenvironment,youmayconsidersettingthemax-source-rows-allowedpropertytoreasonablysmalllevelvalue(e.g.10000)topreventlargeamountsofdatafrombeingpulledfromsources.Leavingtheexception-on-max-source-rowssetto"true"willalertthedeveloperthroughanexceptionthatanattemptwasmadetoretrievemorethanthespecifiednumberofrows.

OtherConsiderations

73

TeiidConsoleTeiidConsoleisawebbasedadministrativeandmonitoringtoolforTeiid.TeiidConsoleisextensionofWildFlyconsolethatisbuiltusingGWTbasedtechnologies.TheTeiidkitdoesnotincludefilesforTeiidConsole.ThisisseparatedownloadyoucandownloadfromTeiidDownloads.

Installation

OnceyoudownloadtheTeiidConsole,unzipthecontentsovertheWildFlyrootdirectoryandalltherequiredfileswillbeoverlayedcorrectlytoinstallTeiidConsole.TheTeiidConsole,bydefaultissecured,soyouwouldneedamanagementrealmuseridandpasswordtologin.Inthe<install>/bindirectory,use

Addingamanagementuserinlinux

./add-user.sh

AddingamanagementuserinWindows

add-user.bat

thenfollowthepromptstocreateManagementRealmuser.Onceyouhavecreatedamanagementuser,youneedtousethesecredentialstologintotheTeiidConsole.IfyouhavestartedyourWildFlyindefaultmode,thenyoucanaccesstheTeiidConsoleathttp://localhost:9990/console/App.html.Ifyouhavealteredthebindingorportnumbersthenmodifytheaddressaccordingly.

ProfileView

Profileviewisforconfiguration.Clickon"profile"ontoprighthandcornerofthemainconsolescreen,togotoProfileView.Youcanclickon"Teiid"inleftnavigationtreetogotoTeiidconfiguration.Thereyouhavethreechoices

QueryEngine-viewandconfigurecoreTeiidengineproperties.

Translators-view,addandremovetheTranslatorsconfiguredinTeiid.

Transports-view,addandremovetransportstotheTeiidengine.

UsingthisviewyoucanchangeanyconfigurationvalueofTeiid.Notethatvariousdifferentconfigurationpropertiesaresub-dividedintodifferenttabs.Youcanclick"NeedHelp"linkonthesepagestoseethedescriptionofeachfieldonthepage.

Note ServerRestart-Notethatsomepropertiesrequireyoutorestarttheserverbeforetheycantakeeffect.

RuntimeView

RuntimeviewshowsruntimeinformationaboutAS7andTeiidsubsystem.RuntimeinformationaboutTeiidcanbeviewedbyselecting"VirtualDatabases"onlefthandnavigationaltree.

TeiidConsole

74

http://www.jboss.org/teiid/downloads

http://localhost:9990/console/App.html

UsingthispageusercanviewmanydifferentsettingsinthecontextaVDB.AlltheVDBsdeployedintheserverareshownintopleveltable.WhenyouselectandhighlightaVDB,moredetailsaboutthatVDBaredisplayedinthesub-tabsbelow.Eachofthesesub-tabsaredividedintogroupingofthefunctionality.

Summary

ThistabshowsthedescriptionandanypropertiesassociatedwithVDB,alongwithanyotherVDBsthisVDBimports.ThistabisdesignedtogiveaquickoverviewoftheVDBstatus.

Models

ThispanelshowsallthemodelsthataredefinedinagivenVDB,andshowseachmodelstranslatornameandsourceconnectionJNDIname.Italsoshowsthetypeofmodelsandifitismulti-sourceornot.Whenaparticularmodelisselecteditwillshowallpropertiesofthatmodelthataredefinedandalsoshowsanyerrorsassociatedwiththemodel.WhenyourVDBisnotdeployedinthe"active"status,youwouldneedtoverifytheseerrorsandfixtoresolveanydeploymentissues.

The"DDL"buttonshowstheschemaforthegivenmodel.NotethatthisdoesnotworkforXMLbasedmodelsthataredesignedusingTeiidDesigner.

ThetoolletstheusereditthetranslatornameorJNDInamebydoubleclickingonthemandmodifyingthem.ThisusefulifyouwouldliketochangetheJNDInameinagivenenvironment.

Overrides

IfyouhaveoverriddenanytranslatorsintheTeiidDesigner,thispanelwillshowthealltheoverriddentranslatorsandtheirproperties.

Caching

Cachingpanelshowscachingstatisticsofresultsetcacheastohoweffectivelythecacheisbeingused.ItalsoshowsalltheinternalmaterializedviewsintheVDBandtheirloadstatusastowhentheywereloaded.ItalsogivesoptionstoinvalidateaspecificvieworalltheviewsinaVDB,sothattheycanrefresh/reloadthecontentsfromsource.

ThispanelalsoprovidesaUItoflushtheentiretheresultsetcachecontentsorpreparedplancachecontentsfortheselectedVDB.

DataRoles

DataRolespanelshowstheallthepoliciesthatdefinedintheVDBusingtheTeiidDesignerorhandcodedinthevdb.xmlfile.Foreachselectedpolicy,itwillalsolistthe"permissions"forthatpolicyastowhatkindofauthorizationsuserhasandshowsthemappedenterpriseroleassignmentstothatpolicy.Youcanevenadd/removeaenterpriseroletothepolicyusingthethisUI.

Requests

ThispanelshowsallthecurrentrequestsagainsttheselectedVDBatthetimeofVDBselection.Youcanclick"refresh"togetamoreuptodaterequests.Thetoptableinthepanelshowstheusersubmittedrequeststotheteiidengine,whenoneofthoserequestsareselected,thenthebottomtableshowsallthesourcelevelqueriesthataresubmittedtothephysicalsourcesbyTeiidengine.

UsingthisUI,usercanalsosubmita"cancel"requesttoauserlevelquery.Since"cancel"asynchronousoperation,theoperationisnotguaranteedasquerymayalreadybeenfinished,bythetimecancelissubmitted.

Sessions

TeiidConsole

75

ThispanelshowsalltheactivesessionsthatareconnectedtotheselectedVDB.Itshowstheirconnectionpropertiesandalsogivesanoptiontoterminateeitheraselectedsessionorallthesessions.

FAQ

HowtodeployaVDBinstandalonemode?

IntheDeploymentsview,clickaddandselecttheVDBtodeploy.AlsomakesureyouenabletheVDBonceitisdeployed.

HowtocreateDatasource?

IntheConfigurationview,gotoSubsystem→Datasources→XA/Non-XA,clickaddandfollowthewizardtocreateJDBCdatasource.

IfyoutryingtocreateconnectiontoTeiidbasedFile,SalesforceorWSbasedconnections,selectSubsystem→ResourceAdaptorsandclickadd.

HowtoaddCOMMANDLogging?

IntheConfigurationview,gotoSubsystem→Logging,clickview,onLogCategoriestab,clickaddorg.teiid.COMMAND_LOGinDEBUGmode.ThedefaultlogwillbeintheFILEhandler.Youcanevenaddotherhandlerifchoosetodoso.

ChangeTeiidJDBCPortinstandalonemode?

IntheConfigurationview,gotoSocketBindingclickView,viewthestandard-socketsselectteiid-jdbcandedit.

TeiidConsole

76

AdminShellTheAdminShelltoolingprovidesscriptingbasedprogrammingenvironmentsthatenableusertoaccess,monitorandcontrolaTeiidServer.BoththecommandlineandgraphicalconsoletoolsarebuiltonfunctionalityprovidebytheGroovy(http://groovy.codehaus.org/)project.TheAdminShelltoolscanbeusedinad-hocscriptingmodeortorunpre-definedscripts.

AdminShellfeatures:

1. fullyfunctionalprogrammingenvironmentwithresourceflowcontrolandexceptionmanagement.SeeGroovydocsforthefullpowerofthelanguage.

2. quickadministrativetool.TheusercanconnecttoarunningTeiidServerandinvokeanyoftheAdminAPImethods,suchas"deploy"or"createDataSource",tocontroltheTeiidSystem.Sincethiscanbescriptdriven,thesetaskscanbeautomatedandre-runatalatertime.

3. simplifieddataaccesstool.TheusercanconnecttoaVDB,issueanySQLcommands,andviewtheresultsofthequeryviaGroovySqlextensions.

4. migrationtool.ThiscanbeusedtodevelopscriptslikemovingtheVirtualDatabases(VDB),ConnectionFactories,andConfigurationfromonedevelopmentenvironmenttoanother.Thiswillenableuserstotestandautomatetheirmigrationscriptsbeforeproductiondeployments.

5. testingtool.TheJUnit(http://junit.org)testframeworkisbuiltin,seeGroovyUnitTests.Usercanwriteregressiontestsforcheckingsystemhealth,ordataintegritythatcanbeusedtovalidateasystemfunctionalityautomaticallyinsteadofmanualverificationbyQApersonnel.

Download

AdminShellisdistributedalongwithotherTeiiddownloadsunder"teiid-{version}-adminshell-dist.zip"name.Downloadandunzipthisfiletoanydirectory.Onceyouhaveunzippedthefile,inrootdirectoryyouwillfind"adminshell"and"adminshell-console"executablescriptstolaunchthecommandlineandgraphicaltoolsrespectively.

Windows:Doubleclickorexecute"adminshell.cmd"

nix:Executethe"adminshell.sh"script

AdminShell

77

http://groovy.codehaus.org/


http://groovy.codehaus.org/Database+features

http://junit.org/

http://groovy.codehaus.org/Unit+Testing

GettingStartedTolearnthebasicsofGroovytakealookattheirdocumentsandtutorialsontheirwebsite.

BasicknowledgeoftheJavaprogramminglanguageandtypesisrequiredinordertoeffectivelydesignanddevelopscriptsusingtheAdminShell.TolearnJavalanguagefindlearningresourcesathttp://java.sun.com.

YoucanlearnabouttheTeiidAdminAPIeitherusing"adminHelp()"functionorbyusingtheJavaDocs.

AdminShellisaspecializedversionofGroovywhichworksinseveraldifferentmodes:interactiveshell,graphicalconsole,orscriptrunmode.Ininteractiveshellmode(launchedviaadminshell),theusercaninvokeconnecttoaliveTeiidsystemandissueanyad-hoccommandstocontrolthesystem.Theinteractivebuffercanbeusedtodevelopascriptandtheinteractivesessioninputandoutputcanbecapturedintoalogfile,moreonthislaterinthedocument.

Ingraphicalmode(lanchedviaadminshell-console),theusercandevelopandrunscriptsusingatexteditorthatsupportssyntaxhighlighting.

Inthescriptrunmode,theusercanexecute/playbackpreviouslydevelopedscripts.Thismodeespeciallyusefultoautomateanytestingortoperformanyrepeatedconfigurations/migrationschangestoaTeiidsystem.

EssentialRules

TouseAdminShellsuccessfully,therearesomebasicsyntacticalrulestokeepinmind.

1. Ininteractiveshellmode,mostcommands(asseenbythehelpcommand)areusedtocontrolshellbehaviorandarenotgeneralGroovyscriptingconstructs.Adminmethodswilltypicallybecalledusingfunctionalnotation:

connectAsAdmin()

1. Allcommandsandfunctionsarecasesensitive.

2. AnendingsemicolonisoptionalforGroovystatements.

3. Ifafunctionrequiresinputparameter(s),theyshouldbedeclaredinside"("and")".Afunctionmayhavemorethanoneparameter.Stringparameterscanbewrappedindoubleorsinglequotes.Example:

connectAsAdmin("localhost","9990","user","password","conn1")

1. Localadminconnectionmaynotrequireapassword.Remoteconnectionswilltypicallybeoverthe9993httpsportinstead.OtherJavamethodsandclassescanbeusedfromyourscripts,iftherequiredJavaclasslibrariesarealreadyinclasspath.Youmayplaceadditionaljarsinthelibdirectorytohavebeautomaticallypartoftheclasspath.Anexampleshowinganimport:

importmy.package.*;

myObject=newMyClass();

myObject.doSomething();

Toexecutethecommandsandarbitraryscriptininteractivemodeyouenterthemfirstandpressentertoexecute,thenenterthenextline,soon.

Toexitthetoolintheinteractivemode,firstdisconnectifyouareconnectedtotheTeiidsystembyexecuting"disconnect();"thentype"exit".Inthescriptmode,whenexecutionofthescriptfinishesthetoolwillexitautomatically,howeveryoustillhavetodisconnectfromTeiidsysteminthescript.

GettingStarted

78


http://java.sun.com/

Note IfSSListurnedontheTeiidserver,youwouldneedtoadjusttheconnectionURLandtheclientSSLsettingsasnecessary(typicallythiswillonlybeneededfor2-waySSL).

Help

TheadminHelp()methodslistsalltheavailableadministrativeAPImethodsintheAdminShell.PleasenotethatnoneoftheGroovyShellcommandsorotheravailablefunctioncallswillbeshowninthislist

adminHelp();

Togetaspecificdefinitionaboutamethodandit’srequiredinputparameters,useadminHelp("method")

adminHelp("deploy");

/*

*DeployaVDBfromfile

*/

voiddeploy(

String/*filename*/)

throwsAdminException

throwsFileNotFoundException

ThesqlHelp()methodslistsallSqlextensionmethods.

sqlHelp();

Togetaspecificdefinitionaboutamethodandit’srequiredinputparameters,usesqlHelp("method")

BasicCommands

ThelistbelowcontainssomecommoncommandsusedinAdminShell.

BasicCommands

println"xxx";//printsomethingtoconsole

adminHelp();//showsalltheavailableadmincommands;

sql=connect();//getanextendedGroovySqlconnectionusingconnection.propertiesfile

sql.execute(<SQL>);//runanySQLcommand.

connectAsAdmin();//connectasadmin;noneedhavethevdbname.SQLcommandswillnotworkunderthisconnect

ion

printlngetConnectionName();//returnsthecurrentconnectionname

useConnection(<connectionname>);//switchestousingthegivenconnectionsettings

disconnect();//disconnectsthecurrentconnectioninthecontext

Someexamples

ExampleofDeployingaVDB

connectAsAdmin();

deploy("/path/to/<name>.vdb");

GettingStarted

79

//checktovalidatethedeployment

VDBvdb=getVDB("<name>",1);

if(vdb!=null){

print(vdb.getName()+"."+vdb.getVersion()+"isdeployed";

}

else{

print("<name>.vdbfailedtodeploy";

}

CreateaDatasource(oracle)

connectAsAdmin();

//firstdeploytheJDBCjarfileforOracle

deploy("ojdbc6.jar");

props=newProperties();

props.setProperty("connection-url","jdbc:oracle:thin:@<host>:1521:<sid>");

props.setProperty("user-name","scott");

props.setProperty("password","tiger");

createDataSource("oracleDS","ojdbc6.jar",props);

CreateaResourceAdapter(file)basedDatasource

connectAsAdmin();

props=newProperties();

props.setProperty("jndi-name","java:/fileDS");

props.setProperty("ParentDirectory","${jboss.server.base.dir}/myData");

props.setProperty("AllowParentPaths","true");

//NOTE:the2ndargument,template-name,mustmatchthe'id'ofoneoftheresource-adaptersthatarecurrent

lydefinedintheserver

createDataSource("MyFile","file",props);

ExecuteSQLQueryagainstTeiid

sql=connect("jdbc:teiid:<vdb>@mm://<host>:31000","user","user");

//select

sql.eachRow("select*fromsys.tables"){println"${it}"}

//update,insert,delete

sql.execute(<sqlcommand>);

Note LearnmoreaboutGroovySQL

GettingStarted

80

http://groovy.codehaus.org/Tutorial+6+-+Groovy+SQL

ExecutingascriptfileToexecuteascriptfile"foo.groovy"inadirectory"some/directory"intheinteractivecomamndlinetool,executeasfollowing

.some/directory/foo.groovy

"foo.groovy"isreadintocurrentcontextoftheshellasifyoutypedinthewholedocument.Ifyourscriptonlycontainedmethodcalls,youcanexplicitlyinvokethecalltoexecute.

Fullexecutesyntaxmayalsobeused,andisrequiredoutsideoftheinteractivecommandlinetool:

evaluate("some/directory/foo.groovy"asFile)

Toexecutethesamefilewithoutenteringinteractivemode,run

./adminshell.sh.some/directory/foo.groovy

ParameterscanbepassedinasJavaSystemproperties.Forexample

./adminshell.sh-Dparam=value.some/directory/foo.groovy

Insidethescriptfile,youcanaccessthesepropertiesusingSystem.getProperty

value=System.getProperty(“param”);//willreturn"value"

Executingascriptfile

81


Duringtheinteractivemode,inputisrecordedinahistoryfile.Thisfilecanbeaccessedviatheuparrowintheinteractiveshell.

Usercanalsocapturethecommandsenteredduringainteractivesessiontotheirownscriptfilebyusing"startRecording"and"stopRecording"commands.Forexample,

recordstartdirectory/filename.txt

<commandsandscript..>

recordstop

Allinputandoutputbetweenthestartandstoparecapturedinthe"directory/filename.txt"file.Thisgivestheuseranoptiontocaptureonlycertainportionsoftheinteractivesessionandtolaterrefineascriptoutofrecordedfile.


82

DefaultConnectionPropertiesThefile"connection.properties"intheinstallationdirectoryoftheAdminShelldefinesthedefaultconnectionpropertieswithwhichusercanconnecttoTeiidsystem.Thefollowingpropertiescanbedefinedusingthisfile

jdbc.user=user

jdbc.password=user

jdbc.url=jdbc:teiid:admin@mm://localhost:31000;

admin.host=localhost

admin.port=9990

admin.user=admin

admin.password=admin

Acallto"connect()"or"connectionAsAdmin()"withoutanyinputparameters,willconnecttotheTeiidsystemusingthepropertiesdefinedinpropertiesfile.However,ausercanalwayspassinparametersintheconnectmethodtoconnecttoasameordifferentserverthanonementionedinthe"connection.properties".Lookalltheallthedifferentconnectmethodsusingthe"adminHelp()"method.

NoteNotethatitisnotsecuretoleavethepasswordsincleartext,asdefinedabove.Pleasetakenecessarymeasurestosecurethepropertiesfile,ordonotusethisfeatureandalwayspassinpasswordinteractivelyorsomeothersecureway.

NoteAtanygiventimeusercanbeactivelyconnectedtomorethanonesystemorhavemorethanoneconnectiontosamesystem.Tomanagetheconnectionscorrectlyeachconnectioniscreatedgivenauniqueconnectionname.TolearnmoreaboutthislookatHandlingMultipleConnections.

DefaultConnectionProperties

83

HandlingMultipleConnectionsUsingAdminShell,ausercanactivelymanagemorethanoneconnectiontoasingleormultipleTeiidsystems.Forexample,twoseparateconnectionscanbemaintained,onetothedevelopmentserverandonetotheintegrationserveratthesametime.ThisispossiblebecauseAdminShellsupportsafeaturecallednamedconnections.

Everytimeaconnectionismade,theconnectionhasanexplicitoranimplicitlyassignedname.Ifanotherconnectcommandisexecutedthenanewconnectionismadewithauniquenameandexecutionwillbeswitchedtousethenewconnection.Thepreviousconnectionwillbeheldasitisinitscurrentstate,andwillnotbeclosed.

Youcanusethefollowingcommandtofindoutthecurrentconnection’sname

name=getConnectionName();

Knowingthenamesoftheconnectionthatuserisworkingwithisimportanttoswitchtheactiveconnectiontoapreviousconnection.Toswitchtheactiveconnection,usethefollowingcommandandsupplythenameoftheconnectiontobeused

useConnection("name");

Ifusersuppliesthesamenameastheactiveconnectionastheyarecurrentlyparticipatingin,thenthisoperationwillsimplyreturnwithoutanymodifications.Thereisnolimitationthenumberofsimultaneousconnections.

Thefollowingshowsanexampleofusingandswitchingbetweentwoconnections.

//createsaconnection

connectAsAdmin();

//capturetheconnectionname

conn1=getConnectionName();

deploy("file.vdb")

//createsasecondconnection

connectAsAdmin();

conn2=getConnectionName();

deploy("file.vdb")

//switchtheconnectionto"conn1"

useConnection(conn1);

//closetheconnectioninthe"conn1"

disconnectAll();

HandlingMultipleConnections

84

InteractiveShellNuancesTheinteractiveshellusesaspecialshellinterpretterandthereforehasdifferentbehaviorthanjustwrittingascriptinGroovy.SeetheGroovyShellDocumentationformoreonitsusage.Notabledifferences:

DefstatementsdonotdefineavariableinthecontextoftheShell,e.g.donotusedefx=1,usex=1

Shellcommands(asseenthroughhelp)usingthenon-functionalshellsyntaxareonlyavailableintheshell.

GroovyclassesusingannotationscannotbeparsedintheShell.

InteractiveShellNuances

85

http://groovy.codehaus.org/Groovy+Shell

OtherScriptingEnvironmentsTheAdminShellmethods(namedcontextualconnections,AdminAPIwrapper,andhelpsystem)havenodirectdependenciesonGroovyandcanbeusedinotherscriptinglanguages.

TousetheAdminShellmethodsinanotherlanguage,simplyimportthestaticmethodsandAdminclassesintoyourscript.Youwillalsoneedtoensurethatthe<adminshelldist>/lib/teiid-7.6-client.jarand<adminshelldist>/lib/teiid-adminshell-7.6.jarareinyourclasspath.ThesnippetbelowshowimportstatementsthatwouldworkinJava,BeanShell,Groovy,etc.

importstaticorg.teiid.adminshell.AdminShell.*;

importstaticorg.teiid.adminshell.GroovySqlExtensions.*;

importorg.teiid.adminapi.*;

Notethattheprovidedshellandconsoleexecutablesautomaticallyhavetheproperclasspathsetandinjecttheproperimportsintorunningscripts.Ifyouwishtousescriptsinanon-TeiidGroovyenvironment,youwillneedtomanuallyaddtheseimportsandaddtheadmin/clientjarstotheclasspath.

OtherScriptingEnvironments

86

SystemPropertiesSomeofTeiid’slow-levelbehaviorcanbeconfiguredviasystemproperties,ratherthanthroughconfigurationfiles.AtypicalplacetosetsystempropertiesforWildFlylaunchesisinthe<install>/bin/<mode>.conf.Apropertysettinghastheformat-Dproperty=value.

General

org.teiid.allowNanInfinity-defaultstofalse.SettotruetoallownumericfunctionstoreturnNaN(NotANumber)and+-Infinity.NotethatthesevaluesarenotcoveredbytheSQLspecification.

org.teiid.useValueCache-defaultstofalse.Settotruetoenablethecanonicalvaluecache.ValuecachingisuseddynamicallywhenbuffermemoryisconsumedtoreuseidenticalvaluesandthusreducethememoryconsumedbyTeiid.Thereisacomputationcostassociatedwiththecachelookup,soenablingthissettingisnotappropriateforinstallationshandlinglargevolumesofdissimilardata.

org.teiid.ansiQuotedIdentifiers-defaultstotrue.SettofalsetoemulateTeiid6.xandpriorbehavioroftreatingdoublequotedvalueswithoutleadingidentifierpartsasstringliterals,whichisnotexpectedbytheSQLspecification.

org.teiid.subqueryUnnestDefault-defaultstofalse.Iftrue,theoptimizerwillaggressivelyunnestsubqueriesinWHEREpredicates.Ifpossiblethepredicatewillbeunnestedtoatraditionaljoinandwillbeeligiblefordependentjoinplanning.

org.teiid.ODBCPacketSize-defaultsto307200.TargetsizeinbytesoftheODBCresultsbuffer.Thisisnotahardmaximum,lobsandwiderowsmayuselargerbuffers.

org.teiid.decimalAsDouble-defaultstofalse.Settotruetoparseexactfixedpointliterals,e.g.1.0,asdoublevaluesratherthanasdecimal/BigDecimalvaluesandtoreturnadoublevaluefromtheAVGfunctionforintegralvaluesinthesamewayasreleasesearlierthan8.0.

org.teiid.comparableLobs-defaultstofalse.SettotruetoallowblobandclobcolumnvaluestobecomparableinTeiid.Sourcetypemetadatawilldetermineifthecomparisoncanbepusheddown.

org.teiid.comparableObject-defaultstofalse.SettotruetoallowobjectcolumnvaluestobecomparableinTeiid.Sourcetypemetadatawilldetermineifthecomparisoncanbepusheddown.Theobjectinstancesareexpectedtocorrectlyimplementjava.lang.Comparable.compareTo.IftheinstanceobjectisnotComparable,thenClassCastExceptionsmaythethrown.

org.teiid.padSpace-defaultstofalse.SettotruetocomparestringsasifPADSPACEcollationisbeingused,thatisstringsareeffectivelyrightpaddedtothesamelengthforcomparison.Ifthispropertyisset,itisnotnecessarytousethetrimStringstranslatoroption.

org.teiid.collationLocale-notsetbydefault,whichmeansthatJava’snatural(UTF-16)stringcomparisonwillbeused.SettoaJavalocalestringlanguage[_country[_varient]],wherelanguage,country,andvariantaretwolettercodes-seejava.util.Localeformoreonvalidcodes.Notethateveniforg.teiid.comparableLobsisset,clobvalueswillnotbecomparedusingthelocalecollator.

org.teiid.clientVdbLoadTimeoutMillis-defaultsto5minutes.Thedefaultamountoftimeaclient(currentlyonlylocalclients)willwaittomakeaconnectiontoanactiveVDBbeforethrowinganexception.ClientsmayoverridethissettingviatheloginTimeoutconnectionproperty.

org.teiid.enDateNames-defaultstofalse.SettotruetouseEnglishmonthanddaynamesforthesystemfunctiondayNameandmonthName,ratherthanreturningnamesfromtheJavadefaultlocale.Priorto8.2dayNameandmonthNamealwaysreturnedEnglishnames.

org.teiid.pushdownDefaultNullOrder-defaultstofalse.Settotruetomimic8.1andpriorreleasebehaviorofpushingtheTeiid’sdefaultnullorderofnullslowifthesourcehasadifferentdefaultnullorderandsupportsexplicitnullordering.

SystemProperties

87

http://docs.oracle.com/javase/6/docs/api/java/util/Locale.html

org.teiid.requireTeiidCollation-defaultstofalse.SettotruetoforceallsortstobeinTeiid’scollation(seeorg.teiid.collationLocale).

org.teiid.implicitMultiSourceJoin-defaultstotrue.SettofalsetodisableTeiid8.2andpriorreleasebehaviorofimplicitlypartitioningjoinsbetweenmulti-sourcetables.Whensettofalseandexplicitpredicatesuchastbl1.source_name=tbl2.source_nameisrequiredtopartitiontheresultsofthejoin.

org.teiid.maxStringLength-defaultsto4000.SetsthenominalmaximumlengthofstringsinTeiid-mostoperationsinTeiidwilltruncatestringsthatarelargerthanthisvalue.Settingthisvaluecanalsoadjustthemaxsizeoflobbytesheldinmemory.NOTE:sourcesmaynotappropriatelyhandlestringvaluesthatarelargerthanthesourcesupports.

Note Stringsarealwaysfullyheldinmemory.Donotsetthisvaluetoohighasyoumayexperienceoutofmemoryerrors.

org.teiid.calendarTimestampDiff-defaultstotrue.SettofalsetousetheTeiid8.2andoldcomputationoftimestampdiff.notethat:usingtheoldbehaviorcanresultindifferingresultsbetweenpushedandnon-pushedversionsoftimestampdiffforintervalsgreaterthansecondsassourcesusedatepartandnotapproximateintervaldifferences.

org.teiid.compactBufferFiles-defaultstofalse.SettotruetohaveTeiidkeepthebufferfilesmorecompact(minimizingsparseregions).

org.teiid.maxMessageSize-defaultsto2097152.Themaximumsizeofmessagesinbytesthatareallowedfromclients.Increaseonlyifclientsroutinelyuselargequeriesand/ornon-lobbindvalues.

org.teiid.maxStreamingLobSize-defaultsto4294967296.Themaximumsizeoflobsinbytesthatareallowedtobestreamedaspartofthemessagefromclients.

org.teiid.defaultIndependentCardinality-defaultsto10.Thenumberofindependentrowsorlessthatcanautomaticallytriggeradependentjoin.Increasewhentablestypicallyonlyhavecardinalitysetandmoredependentjoinsaredesired.

org.teiid.checkPing-defaultstotrue.CanbesettofalsetodisablepingcheckingforremoteJDBCconnections.Pingcheckingshouldonlybedisabledinspecificcircumstances,suchaswhenusinganexternalloadbalancerandnotutilizingtheTeiiddefaultloadbalancinglogic.

org.teiid.defaultNullOrder-defaultstoLOW.CanbeoneofLOW,FIRST,HIGH,LAST.SetsthedefaultnullorderfortheTeiidengine.Thiswillnotbeusedforsourceorderingunlessorg.teiid.pushdownDefaultNullOrderisalsoset.

org.teiid.iso8601Week-defaultstotrue.SettotruetouseISO8601rulesforweekcalculationsregardlessofthelocale.Whentruetheweekfunctionwillrequirethatweek1ofayearcontainstheyear’sfirstThursday.PushdownweekvalueswillbecalculatedasISOregardlessofthissetting.

org.teiid.widenComparisonToString-defaultstofalse.Settotruetoenablewideningofvaluestostringincomparisons,whichwasthedefaultbehaviorpriortoTeiid9.Forexamplewiththissettingasfalsetimestamp_col<'a'willproduceanexceptionwhereaswhensettotrueitwouldeffectivelyevaluatecast(timestamp_colasstring)<`a'.

Security

org.teiid.allowCreateTemporaryTablesByDefault-defaultstofalse.Settotruetousethepre-8.0behaviorofallowinganyauthenticatedusertocreatetemptableswithoutanexplicitpermission.

org.teiid.allowFunctionCallsByDefault-defaultstofalse.Settotruetousethepre-8.0behaviorofallowinganyauthenticatedusertocallanynon-systemfunctionwithoutanexplicitpermission.

org.teiid.ignoreUnauthorizedAsterisk-defaultstofalse.Iftrueunauthorizedcolumns(asdeterminedbydatarolechecking)arenotpartofselectallorqualifiedselectallexpansion.Iffalse,theclientmaysetthesessionvariableignore_unauthorized_asterisktotruetoachievethesamebehavior.

SystemProperties

88

org.teiid.sanitizeMessages-defaultstofalse.IftruequeryrelatedexceptionandwarningswillhavetheirmessagesreplacedwithjusttheTeiidcode.Serversidestacktraceswillalsoberemovedwhensenttotheclient.ThisshouldbeenabledifthereisaconcernaboutSQLorvaluesbeingpresentintheexception/logs.Iftheloglevelisincreasedtodebugfortherelevantlogger,thenthesanitizeMessagessettingwillhavenoeffect.

org.teiid.ODBCRequireSecure-defaultstotrue.IftruesettingtheSSLconfigtologinorenabledwillrequireclientstoconnectappropriatelywitheitheraGSSloginorSSLrespectively.SettingthepropertytofalsewillallowclienttouseanyauthenticationandnoSSL(whichwasthebehaviorofthepgtransportpriorto8.9CR2).

PostgreSQLCompatibility

Note TheseaffectTeiidglobally,andnotjustthroughtheODBCtransport.

org.teiid.backslashDefaultMatchEscape-defaultstofalse.Settotruetouse'\'asthedefaultescapecharacterforLIKEandSIMILARTOpredicateswhennoescapeisspecified.OtherwiseTeiidassumestheSQLspecificationcompliantbehavioroftreatingeachnon-wildcardcharacterasanexactmatchcharacter.

org.teiid.addPGMetadata-defaultstotrue.Whensettofalse,theVDBwillnotincludePostgresqlbasedsystemmetadata.

org.teiid.honorDeclareFetchTxn-defaultstofalse.Whenfalsethewrappingbegin/commitofaUseDeclareFetchcursorwillbeignoredasTeiiddoesnotrequireatransaction.

Client

SystempropertiescanalsobesetforclientVMs.SeeAdditionalSocketClientSettings.

SystemProperties

89

TeiidManagementCLITheWildFlyCLIisacommandlinebasedadministrativeandmonitoringtoolforTeiid.ManysnippetsofCLIscriptingareshownthroughouttheAdminGuide-especiallyaroundmanagingdatasources.AdminShellprovidesabindingintotheGroovyscriptinglanguageandhigherlevelmethodsthatareoftenneededwheninteractingwithTeiid.ItisstillusefultoknowtheunderlyingCLIcommandsinmanycircumstances.ThebelowisaseriesusefulCLIcommandsforadministeringaTeiidServer.PleasealsorefertotheASdocumentationformoreoninteractingwiththeCLI-includinghowtonavigate,listoperations,etc.

VDBOperations

deployadminapi-test-vdb.xml

undeployadminapi-test-vdb.xml

/subsystem=teiid:restart-vdb(vdb-name=AdminAPITestVDB,vdb-version=1,model-

names=TestModel)

/subsystem=teiid:list-vdbs()

/subsystem=teiid:get-vdb(vdb-name=AdminAPITestVDB,vdb-version=1)

/subsystem=teiid:change-vdb-connection-type(vdb-name=AdminAPITestVDB,vdb-

version=1,connection-type=ANY)

/subsystem=teiid:add-data-role(vdb-name=AdminAPITestVDB,vdb-version=1,data-

role=TestDataRole,mapped-role=test)

/subsystem=teiid:remove-data-role(vdb-name=AdminAPITestVDB,vdb-version=1,data-

role=TestDataRole,mapped-role=test)

SourceOperations

/subsystem=teiid:add-source(vdb-name=AdminAPITestVDB,vdb-version=1,source-

name=text-connector-test,translator-name=file,model-name=TestModel,ds-

name=java:/test-file)

/subsystem=teiid:remove-source(vdb-name=AdminAPITestVDB,vdb-version=1,source-

name=text-connector-test,model-name=TestModel)

/subsystem=teiid:update-source(vdb-name=AdminAPITestVDB,vdb-version=1,source-

name=text-connector-test,translator-name=file,ds-name=java:/marketdata-file)

TranslatorOperations

/subsystem=teiid:list-translators()

/subsystem=teiid:get-translator(translator-name=file)

/subsystem=teiid:read-translator-properties(translator-name=file,type=OVERRIDE)

/subsystem=teiid:read-rar-description(rar-name=file)

TeiidManagementCLI

90

RuntimeOperations

/subsystem=teiid:workerpool-statistics()

/subsystem=teiid:cache-types()

/subsystem=teiid:clear-cache(cache-type=PREPARED_PLAN_CACHE)

/subsystem=teiid:clear-cache(cache-type=QUERY_SERVICE_RESULT_SET_CACHE)

/subsystem=teiid:clear-cache(cache-type=PREPARED_PLAN_CACHE,vdb-

name=AdminAPITestVDB,vdb-version=1)

/subsystem=teiid:clear-cache(cache-type=QUERY_SERVICE_RESULT_SET_CACHE,vdb-

name=AdminAPITestVDB,vdb-version=1)

/subsystem=teiid:cache-statistics(cache-type=PREPARED_PLAN_CACHE)

/subsystem=teiid:cache-statistics(cache-type=QUERY_SERVICE_RESULT_SET_CACHE)

/subsystem=teiid:engine-statistics()

/subsystem=teiid:list-sessions()

/subsystem=teiid:terminate-session(session=sessionid)

/subsystem=teiid:list-requests()

/subsystem=teiid:cancel-request(session=sessionId,execution-id=1)

/subsystem=teiid:list-requests-per-session(session=sessionId)

/subsystem=teiid:list-transactions()

/subsystem=teiid:mark-datasource-available(ds-name=java:/accounts-ds)

/subsystem=teiid:get-query-plan(session=sessionid,execution-id=1)

TeiidManagementCLI

91

DiagnosingIssuesYoumayexperiencesituationswhereyouincurperformanceissuesorunexpectedresults/exceptions.Therestofthischapterwillfocusonqueryplanningandprocessingissues.Configurationoroperationalissuesrelatedtothecontaineraretypicallymoreisolatedandeasiertoresolve.

GeneralDiagnosticProcess

Whenthereisanissue,startbyisolatingaproblemqueryasmuchaspossible.IfaccessingthroughODBCorOData,doesasimilarissueoccurjustthroughJDBC.Inwhateverscenariotheissueoccurs,theparticularsmatter-whatsources,ifthereisatransaction,load,etc.

Don’tmaketoomanyassumptions

Forexamplememoryconsumptionforexamplecanbeheavilydependentupondrivers,andaresultingoutofmemoryissuemayonlybeindirectlyrelatedtoTeiid

Startwiththequeryplan-especiallywithperformanceissues

Theremaybesimplificationsorchangespossibletoviewsandproceduresutilizedbytheuserquery.

UtilizeLogging

Planningissuesmaybeunderstoodwiththedebugplan

Thecommandlog

Afulldebug/tracelevellogcanshedevenmorelight–butitmaynotbeeasytofollow.

Youcancorrelatewhatishappeningbycontext,thread,sessionid,andrequestid.

Ifnoresolutionisfound,engagethecommunityandutilizeprofessionalsupport

QueryPlans

Oncetheproblemhasbeenisolatedasmuchaspossible,youshouldfurtherexaminethequeryplan.Theonlycircumstancewhenthisisnotpossibleiswhenthereareplanningerrors.Inthiscasethelogs,eitherfulldebugorjustthedebugplan,isstillusefultothenloganissuewiththecommunityorwithsupport.

Ifyouhaven’tdonesoalready,youshouldstartbyfamiliarizingyourselfwithFederatedPlanning-especiallythesectionsonthequeryplan.

Thefinalprocessorplanisgenerallywhatismeantwhenreferringtoby“thequeryplan”.TheplancanbeviewedinanXMLoraplaintextformat.

Designeristypicallythefirstplacetolookatqueryplansfromthequeryexecutionview.It’seasiesttolookatusingDesigneroranXMLawareviewerastheplantreescangetlarge.

YoucanalsouseTeiidExtensionsorSQLstatementstogettheplan:

SETSHOWPLANON

SELECT...

SHOWPLAN

Onceyouhavetheplan,youcan:

DiagnosingIssues

92

Doublecheckthathintsaretakingeffect

Makesurethingsseemcorrect

Lookfirstatallofthesourcequeriesontheaccessnodes.Generallyamissingpushdown,suchaspredicateiseasytospot

Focusonproblemsourcequeriesandtheirparentnodesifyoualreadyhaveexecutiontimes

It’salsoagoodideatovalidatequeryplansduringthedevelopmentandtestingofaVDB.Alsoanyengagementwiththecommunityorsupportwilllikelyneedthequeryplanaswell.

Iftheplanisobtainedfromanexecutedquery,thentheplanwillalsoshowexecutionstatistics.Itisespeciallyusefultoseethestatswhenprocessinghasfinishedandallrowshavebeenfetched.Whileseveralstatsarecollected,it’smostusefultosee“NodeOutputRows”and“NodeNextBatchProcessTime”.

Exampletextformofaqueryplanshowingstats:

ProjectNode

+RelationalNodeID:6

+OutputColumns:x(double)

+Statistics:

0:NodeOutputRows:6

1:NodeNextBatchProcessTime:2

2:NodeCumulativeNextBatchProcessTime:2

3:NodeCumulativeProcessTime:2

4:NodeNextBatchCalls:8

5:NodeBlocks:7

+CostEstimates:EstimatedNodeCardinality:-1.0

+Child0:

AccessNode

+RelationalNodeID:7

+OutputColumns

+Statistics:

0:NodeOutputRows:6

1:NodeNextBatchProcessTime:0

2:NodeCumulativeNextBatchProcessTime:0

3:NodeCumulativeProcessTime:0

4:NodeNextBatchCalls:2

5:NodeBlocks:1

...

Inadditiontotheexecutionstats,notetherearealsocostestimates.Thevaluesforthecostestimatesarederivedfromthestatisticvaluessetofeachtable/columnabouttherowcount,numberofdistinctvalues,numberofnullvalues,etc.Unlikesystemsthatownthedata,wearenotattemptingtobuildhistogramsorotherin-depthmodelsofthedata.Thesesvaluesaremeanttobeapproximationswithnominallydistributionassumptions.Thecostinginformationfromthemetadataonlymattersforphysicalentitiesaswe’llrecomputethehighervaluesinplanningaftermergevirtualandotherplanmodifications.Ifyouseethatjoinisbeingimplementedinefficiently,thenfirstmakesurereasonablecostingvaluesarebeingsetonthetablesinvolved.Statisticscanbegatheredforsomesourcesatdesigntimeordeploytime.Inenvironmentsthatfluctuaterapidly,youmayneedtoissueruntimecostingupdatesviasystemprocedures.

PushdownInhibited

Oneofthemostcommonissuesthatcausesperformanceproblemsiswhennotenoughoftheplanispushedtoagivensourceleadingtotoomanyrowsbeingfetchedand/ortoomuchprocessinginTeiid.

Pushdownproblemsfallintotwocategories:

Somethingthatcannotbepusheddown.Forexamplenotallsystemfunctionsaresupportedbyeachsource.Formattingfunctionsinparticulararenotbroadlysupported.

DiagnosingIssues

93

Aplanningorotherissuethatpreventsotherconstructsfrombeingpusheddown

Temptablesormaterializationcaninhibitpushdownwhenjoining

Windowfunctionsandaggregationwhennotpushedcanpreventfurtherpushdown

Ifpushdownisinhibitedthentheconstructwillbemissingfromtheaccessnodeissuingthesourcequery,andwillinsteadbebeatahighernode:

<nodename="SelectNode">...<propertyname="Criteria"><value>pm1.g1.e2=1</value>

<nodename="AccessNode">...<propertyname="Query"><value>SELECTpm1.g1.e1,pm1.g1.e2FROMpm1.g1</value>

Whenpushdownisinhibitedbythesource,itshouldbeeasytospotinthedebugplanwithloglinesimilarto:

LOWRelationalPlannerSubqueryInisnotsupportedbysourcepm1-e1IN/*+NO_UNNEST*/(SELECTe1FROMpm2.g

1)wasnotpushed

CommonIssues

Beyondpushdownbeinginhibited,othercommonissuesare:

SlightdifferencesinTeiid/Pushdownresults

forexampleTeiidproducesadifferentforagivenfunctionthanthesource

Sourcequeryformisnotoptimalorincorrect

Thereisanunaccountedfortypeconversion

forexamplethereisnochar(n)typeinTeiid

Acastmaycauseasourceindexnottobeused

JoinPerformance

Costingvaluesnotsetleadingtoanon-performantplan.

Usehintsifneeded.

Teiidwillreplaceouterwithinnerjoinswhenpossible,butjustincasereviewouterjoinusageintheuserqueryandviewlayers

XQuery

XQuery/XPathcanbedifficulttogetcorrectwhennotassistedbytooling.Havinganincorrectnamespaceforexamplecouldsimplyresultinnoresultsratherthanexception.

WithXMLQUERY/XMLTABLEeachXPath/XQueryexpressioncanhavealargeimpactonperformance.Inparticulardescendantaccess'//'canbecostly.Justaccessingelementsinthedirectparentageisefficientthough.

Thelargerthedocumentbeingprocessed,themorecarefulyouneedtobetoensurethatdocumentprojectionandstreamprocessingcanbeused.Streamingtypicallyrequiresasimplecontextpath-'a/b/c'

Logging

Thequeryplanalonedoesnotprovideafullaccountingofprocessing.Somedecisionsaredelayeduntilexecutionorcanonlybeseenintheserverlogs:

DiagnosingIssues

94

TheENAHANCEDSORTJOINnodemayexecutecanexecuteoneofthreedifferentjoinstrategiesdependingontheactuallyrowcountsfound,thiswillnotbeseenunlessthequeryplanisobtainedattheendofexecution.

Theeffectoftranslationisnotyetaccountedforastheplanshowstheengineformofthequery

Thefulltranslationcanbeseeninwithcommandloggingatatracelevelorwithdebug/traceloggingingeneral.

Thequeryplandoesn’tshowtheexecutionstatsofindividualthesourcequeries,whichisshowninthecommandlog

Theforfullpictureofexecutiondowntoallthebatchfetches,you’lljustneedthefullserverdebug/tracelog

PlanDebugLog

Thelogicalplanoptimizationisrepresentedbytheplanningdebuglogandismoreusefultounderstandwhyplanningdecisionsweremade.

SETSHOWPLANDEBUG

SELECT...

SHOWPLAN

Youwilltypicallynotneedtousethislevelofdetailtodiagnoseissues,butitisusefultoprovidetheplandebuglogtosupportwhenplanningissuesoccur.

DiagnosingIssues

95

MigrationGuideFromTeiid8.xTeiidstrivestomaintainconsistencybetweenallversions,butwhennecessarybreakingconfigurationandVDB/sqlchangesaremade-andthentypicallyonlyformajorreleases.

Youshouldconsultthereleasenotesforcompatibilityandconfigurationchangesfromeachminorversionthatyouareupgradingover.Thisguideexpandsuponthereleasenotesincludedinthekittocoverchangessince8.x.

IfpossibleyoushouldmakeyourmigrationtoTeiid9byfirstusingTeiid8.13.8.13isanon-featuretransitionalreleasethatiseffectivelyTeiid8.12runningonWildFly9.0.2.Seealso8.13MigrationGuide

JRESupportWildFly9+isexpectedtouseJava1.7orlater.BoththeserverkitandusageofTeiidEmbeddedwillrequireJava1.7+.Theclientdrivermaystillusea1.6runtime.

ConfigurationChangesYouwillneedtoapplyyourTeiidandotherconfigurationchangesstartingwithanewbaseconfigurationforWildFly,suchasthestandalone-teiid.xmlincludedinthekit.Notethat9999porthasbeenremovedbydefault.Adminconnectionsareexpectedtouseeither9990(http)or9993(https).

SecurityRelated

Thereisnowasinglesessionservice.Sessionservicerelatedproperties,prefixedbyauthentication,arenolongerspecifiedpertransport.Insteadtheynowappearasasinglesiblingtothetransports.

Oldstandalone.xmlConfiguration

<transportname="local"/>

<transportname="odata">

<authenticationsecurity-domain="teiid-security"/>

</transport>

<transportname="jdbc"protocol="teiid"socket-binding="teiid-jdbc">


</transport>

<transportname="odbc"protocol="pg"socket-binding="teiid-odbc">


<sslmode="disabled"/>

</transport>

Newstandalone.xmlConfiguration


<transportname="local"/>

<transportname="odata"/>

<transportname="jdbc"protocol="teiid"socket-binding="teiid-jdbc"/>

<transportname="odbc"protocol="pg"socket-binding="teiid-odbc">

<sslmode="disabled"/>

</transport>

Thedefaultmaximumnumberofsessionswasincreasedto10000toaccommodateforthischange.


96

https://docs.jboss.org/author/display/teiid813final/Migration+Guide+From+Teiid+8.12

Inadditionthereisanewpropertytrust-all-localthatdefaultstotrueandallowsunauthenticatedaccessbylocalpass-throughconnectionsovertheembeddedtransport-thiswaseffectivelythedefaultbehaviorof8.xandbeforewhennosecurity-domainwassetontheembeddedtransport.Youmaychoosetodisallowthattypeofaccessbysettingthepropertytofalseinstead.

RoleBasedCredentialMapIdentityLoginModule

TheRoleBasedCredentialMapIdentityLoginModuleclasshasbeenremoved.ConsideralternativeloginmoduleswithrolesassignmentstorestrictaccesstotheVDB.

LocalTransport

TheembeddedtransportwasrenamedtolocaltoavoidconfusionwithTeiidembedded.

Behavioral

widenComparisonToString

Theresolver’sdefaultbehaviorwastowidencomparisonstostring,but9.0nowdefaultsorg.teiid.widenComparisonToStringtofalse.Forexamplewiththissettingasfalseacomparisonsuchas"timestamp_col<'a'"willproduceanexceptionwhereaswhensettotrueitwouldeffectivelyevaluate"cast(timestamp_colasstring)<'a'".Ifyouexperienceresolvingerrorswhenavdbisdeployedyoushouldupdatethevdbifpossiblebeforerevertingtotheoldresolvingbehavior.

reportAsViews

TheJDBCclientwillreportTeiidviewsinthemetadataastabletypeVIEWratherthanTABLEbydefault.UsetheconnectionpropertyreportAsViews=falsetousepre-9.0behavior.

CompatibilityChanges

SystemMetadata

Withdatarolesenabledsystemtables(SYS,SYSADMIN,andpg_catalog)willonlyexposetables,columns,procedures,etc.forwhichtheuserisentitledtoaccess.AREADpermissionisexpectedfortables/columns,whileanEXECUTEpermissionisexpectedforfunctions/procedures.Allnon-hiddenschemaswillstillbevisiblethough.

TheOIDcolumnshasbeenremoved.TheUIDcolumnshouldbeusedinsteadorthecorrespondingpg_catalogtablewillcontainanOIDvalues.

ParentuidcolumnshavebeenaddedtotheSYSTables,Procedures,KeyColumns,andColumnstables.

Kitting/BuildChanges

AdminJAR

For8.13theentrypointforcreatingremoteadminconnection,AdminFactory,wasmovedintotheteiid-jboss-adminjarratherthanbeinglocatedinteiid-admin.

APIChanges

TheAuthorizationValidatorandPolicyDeciderinterfaceshadminorchanges.AuthorizationValidatorhasanadditionalmethodtodeterminemetadatafiltering,andPolicyDeciderhadisTempAccessablecorrectedtoisTempAccessible.


97

SemanticversioningrequiredthechangeoftheVDBversionfieldfromanintegertoastring.Thisaffectedthefollowingpublicclasses:

VDBSessionEventListenerVDBImportExecutionContextMetadataRepository

Therearealsoduplicate/deprecatedmethodson:

EventDistributorAdmin

UsingtheTranslatorPropertyannotationwithoutasetternowrequiresthatreadOnly=truebesetontheannotation.

EmbeddedKit

TheEmbeddedKithasbeenremoved.YoushouldfollowtheEmbeddedExamplestousemaventopullthedependenciesyouneedforyourproject.

Therewereextensivechangesindependencymanagementforhowtheprojectisbuilt.Thesechangesallowedustoremovetheneedforresourceadapterjarsbuiltwiththelibclassifier.Ifyouneedtoreferencetheseartifactsfrommaven,justomittheclassifier.

LegacyDrivers

ThedriversforJRE1.4/1.5systemshavebeendiscontinued.Ifyoustillneedaclientforthoseplatforms,youshouldusetheappropriate8.xdriver.

OData

TheODatav2warbaseduponodata4jhasbeendeprecated.YoushouldutilizetheODatav4warserviceinstead.

Thenamesofthewarshavebeenchangedtostripversioninformation-thismakesiteasiertocaptureadeployment-overlayintheconfigurationsuchthatitwon’tbechangedfromoneTeiidversiontothenext.

teiid-odata-odata2.warhasbecometeiid-odata.warteiid-olingo-odata4.warhasbecometeiid-olingo-odata4.war

Tochangepropertiesinanweb.xmlfileoraddotherfilestothedefaultodatawar,youshoulduseadeploymentoverlayinstead.

Materialization

Thesemanticversioningchangerequiresthematerializationstatustablestochangetheirversioncolumnfromanintegertostring.Boththesourceandthesourcemodelwillneedtobeupdatedwiththecolumntypechange.


98

https://github.com/teiid/teiid-embedded-examples

https://docs.jboss.org/author/display/WFLY9/Deployment+Overlays

CachingGuideTeiidprovidesseveralcapabilitiesforcachingdataincluding:

1. Materializedviews

2. ResultSetcaching

3. Codetablecaching

Thesetechniquescanbeusedtosignificantlyimproveperformanceinmanysituations.

Withtheexceptionofexternalmaterializedviews,thecacheddataisaccessedthroughtheBufferManager.ForbetterperformancetheBufferManagersettingshouldbeadjustedtothememoryconstraintsofyourinstallation.SeetheCacheTuningformoreonparametertuning.

CachingGuide

99

ResultsCachingTeiidprovidesthecapabilitytocachetheresultsofspecificuserqueriesandvirtualprocedurecalls.Thiscachingtechniquecanyieldsignificantperformancegainsifusersofthesystemsubmitthesamequeriesorexecutethesameproceduresoften.

SupportSummary

CachingofuserqueryresultsincludingXMLdocumentmodelresults.

Cachingofvirtualprocedureresults.

ScopingofresultsisautomaticallydeterminedtobeVDB/user(replicated)orsessionlevel.Thedefaultlogicwillbeinfluencedbyeveryfunctionevaluated,considertheDETERMINISMpropertyonallsourcemodels/tables/procedures,andtheScopefromtheExecutionContextorCacheDirective.

Configurablenumberofcacheentriesandtimetolive.

Administrativeclearing.

UserInteraction

UserQueryCache

UserqueryresultsetcachingwillcacheresultsetsbasedonanexactmatchoftheincomingSQLstringandPreparedStatementparametervaluesifpresent.CachingonlyappliestoSELECT,setquery,andstoredprocedureexecutionstatements;itdoesnotapplytoSELECTINTOstatements,orINSERT,UPDATE,orDELETEstatements.

Endusersorclientapplicationsexplicitlystatewhethertouseresultsetcaching.ThiscanbedonebysettingtheJDBCResultSetCacheModeexecutionpropertytotrue(defaultfalse)

Propertiesinfo=newProperties();

…

info.setProperty("ResultSetCacheMode","true");

Connectionconn=DriverManager.getConnection(url,info);

orbyaddingaCacheHinttothequery.Notethatifeitherofthesemechanismsareused,Teiidmustalsohaveresultsetcachingenabled(thedefaultisenabled).

Themostbasicformofthecachehint,/*+cache*/,issufficienttoinformtheenginethattheresultsofthenon-updatecommandshouldbecached.

PreparedStatementResultSetCaching

PreparedStatementps=connection.prepareStatement("/*+cache*/selectcolfromtwherecol2=?");

ps.setInt(1,5);

ps.execute();

TheresultswillbecachedwiththedefaultttlandusetheSQLstringandtheparametervalueaspartofthecachekey.

Thepref_memandttloptionsofthecachehintmayalsobeusedforresultsetcachequeries.Ifacachehintisnotspecified,thenthedefaulttimetoliveoftheresultsetcachingconfigurationwillbeused.

AdvancedResultSetCaching

ResultsCaching

100

/*+cache(pref_memttl:60000)*/selectcolfromt

Inthisexamplethememorypreferencehasbeenenabledandthetimetoliveissetto60000millisecondsor1minute.Thettlforanentryisactuallytreatedasit’smaximumageandtheentrymaybepurgedsoonerifthemaximumnumberofcacheentrieshasbeenreached.

Note Eachqueryisre-checkedforauthorizationusingthecurrentuser’spermissions,regardlessofwhetherornottheresultshavebeencached.

ProcedureResultCache

Similartomaterializedviews,cachedvirtualprocedureresultsareusedautomaticallywhenamatchingsetofparametervaluesisdetectedforthesameprocedureexecution.UsageofthecachedresultsmaybebypassedwhenusedwiththeOPTIONNOCACHEclause.UsageiscoveredinHintsandOptions.

CachedVirtualProcedureDefinitionToindicatethatavirtualprocedureshouldbecached,it’sdefinitionshouldincludeaCacheHint.

ProcedureCaching

/*+cache*/

BEGIN

...

END

Resultswillbecachedwiththedefaultttl.

Thepref_memandttloptionsofthecachehintmayalsobeusedforprocedurecaching.

Procedureresultscachekeysincludetheinputparametervalues.Topreventoneprocedurefromfillingthecache,atmost256cachekeysmaybecreatedperprocedureperVDB.

Acachedprocedurewillalwaysproduceallofitsresultspriortoallowingthoseresultstobeconsumedandplacedinthecache.Thisdiffersfromnormalprocedureexecutionwhichinsomesituationsallowsthereturnedresultstobeconsumedinastreamingmanner.

CacheConfigurationBydefaultresultsetcachingisenabledwith1024maximumentrieswithamaximumentryageof2hours.Thereareactually2cachesconfiguredwiththesesettings.OnecacheholdsresultsthatarespecifictosessionsandislocaltoeachTeiidinstance.TheothercacheholdsVDBscopedresultsandcanbereplicated.Seetheteiidsubsystemconfigurationfortuning.TheusermayalsooverridethedefaultmaximumentryageviatheCacheHint.

Resultsetcachingisnotlimitedtomemory.Thereisnoexplicitlimitonthesizeoftheresultsthatcanbecached.CachedresultsareprimarilystoredintheBufferManagerandaresubjecttoit’sconfiguration-includingtherestrictionofmaximumbufferspace.

Whiletheresultdataisnotheldinmemory,cachekeys-includingparametervalues-maybeheldinmemory.Thusthecacheshouldnotbegivenanunlimitedmaximumsize.

Resultsetcacheentriescanbeinvalidatedbydatachangeevents.Themax-stalenesssettingdetermineshowlonganentrywillremaininthecaseafteroneofthetablesthatcontributedtotheresultshasbeenchanged.SeetheDeveloper’sGuideforfurthercustomization.

ResultsCaching

101

ExtensionMetadata

Youcanusetheextensionmetadataproperty

{http://www.teiid.org/ext/relational/2012}data-ttl

asamodelpropertyoronasourcetabletoindicateadefaultTTL.AnegativevaluemeansnoTTL,0meansdonotcache,andapositivenumberindicatesthetimetoliveinmilliseconds.IfnoTTLisspecifiedonthetable,thentheschemawillbechecked.TheTTLforthecacheentrywillbetakenastheleastpositivevalueamongallTTLs.Thussettingthisvalueasamodelpropertycanquicklydisableanycachingagainstaparticularsource.

Forexample,settingthepropertyinthevdb.xml:

<vdbname="vdbname"version="1">

<modelname="Customers">

<propertyname="teiid_rel:data-ttl"value="0"/>

...

CacheAdministration

TheresultsetcachecanbeclearedthroughtheAdminAPIusingtheclearCachemethod.Theexpectedcachekeyis"QUERY_SERVICE_RESULT_SET_CACHE".

ClearingtheResultSetCacheinAdminShell

connectAsAdmin()

clearCache("QUERY_SERVICE_RESULT_SET_CACHE")

SeetheAdministrator’sGuideformoreonusingtheAdminAPIandAdminShell.

Limitations

XML,BLOB,CLOB,andOBJECTtypecannotbeusedaspartofthecachekeyforpreparedstatementofprocedurecachekeys.

TheexactSQLstring,includingthecachehintifpresent,mustmatchthecachedentryfortheresultstobereused.Thisallowscacheusagetoskipparsingandresolvingforfasterresponses.

ResultsetcachingistransactionalbydefaultusingtheNON_XAtransactionmode.IfyouwantfullXAsupport,thenchangetheconfigurationtouseNON_DURABLE_XA.

ClearingtheresultscacheclearsallcacheentriesforallVDBs.

ResultsCaching

102

MaterializedViewsTeiidsupportsmaterializedviews.Materializedviewsarejustlikeotherviews,buttheirtransformationsarepre-computedandstoredjustlikearegulartable.WhenqueriesareissuedagainsttheviewsthroughtheTeiidServer,thecachedresultsareused.Thissavesthecostofaccessingalltheunderlyingdatasourcesandre-computingtheviewtransformationseachtimeaqueryisexecuted.

Materializedviewsareappropriatewhentheunderlyingdatadoesnotchangerapidly,orwhenitisacceptabletoretrievedatathatis"stale"withinsomeperiodoftime,orwhenitispreferredforend-userqueriestoaccessstageddataratherthanplacingadditionalqueryloadonoperationalsources.

SupportSummary

Cachingofrelationaltableorviewrecords(pre-computingalltransformations)

Model-baseddefinitionofvirtualgroupstocache

UserabilitytooverrideuseofmaterializedviewcacheforspecificqueriesthroughHintsandOptions

Approach

Theoverallstrategytowardmaterializationshouldbetoworkontheintegrationmodelfirst,thenoptimizeasneededfromthetopdown.

Resultsetcaching,ideallyhintdriven,shouldbeusediftherelotsofrepeateduserqueries.Ifresultsetcachingisinsufficient,thenmoveontointernalmaterializationforviewsthatareclosesttoconsumers(minimallyornotlayered)thatareintroducingperformanceissues.Keepinmindthattheuseofmaterializationinlinesaccesstothematerializationtableratherthantheviewsoscenariosthatintegrateontopofthematerializationmaysufferiftheywererelyingonpushing/optimizingtheworkoftheviewwithsurroundingconstructs.

Baseduponthelimitationsofinternalmaterialization,thenswitchtoexternalmaterializationasneeded.

MaterializedViewDefinition

Materializedviewsaredefinedinbysettingthematerializedpropertyonatableorviewinavirtual(view)relationalmodel.Settingthisproperty’svaluetotrue(thedefaultisfalse)allowsthedatageneratedforthisvirtualtabletobetreatedasamaterializedview.

Important Itisimportanttoensurethatallkey/indexinformationispresentasthesewillbeusedbythematerializationprocesstoenhancetheperformanceofthematerializedtable.

Thetargetmaterializedtablemayalsobesetintheproperties.Ifthevalueisleftblank,thedefault,theninternalmaterializationwillbeused.Otherwiseforexternalmaterialization,thevalueshouldreferencethefullyqualifiednameofatable(orpossiblyview)withthesamecolumnsasthematerializedview.Formostbasicscenariosthesimplicityofinternalmaterializationmakesitthemoreappealingoption.

Reasonstouseexternalmaterialization

Thecacheddataneedstobefullydurable.Internalmaterializationdoesnotsurviveaclusterrestart.

MaterializedViews

103

Fullcontrolisneededofloadingandrefresh.Internalmaterializationdoesofferseveralsystemsupportedmethodsforrefreshing,butdoesnotgivefullaccesstothematerializedtable.

Controlisneededoverthematerializedtabledefinition.InternalmaterializationdoessupportIndexes,buttheycannotbedirectlycontrolled.Constraintsorotherdatabasefeaturescannotbeaddedtointernalmaterializationtables.

Thedatavolumeislarge.Internalmaterialization(andtemptablesingeneral)havememoryoverheadforeachpage.Aroughguidelineisthattherecanbe100millionrowsinallmaterializedtablesacrossallVDBsforeverygigabyteofheap.

Important

MaterializedviewtablesdefaulttotheVDBscope.Bydefaultifamaterializedviewdefinitiondirectlyortransitivelycontainsanon-deterministicfunctioncall,suchasrandomorhasRole,theresultingtablewillcontainonlytheinitiallyevaluatedvalues.Inmostinstancesyoushouldconsidernestingamaterializedviewwithoutthedeterministicresultsthatisjoinedwithrelevantnon-deterministicvaluesinaparentview.Youmayalsoscopethematerializedviewtobesessionspecific,butthatmaylimitthereuseoftheresultsinmanysituations.

MaterializedViews

104

ExternalMaterializationThisdocumentwillexplainwhatTeiidExternalMaterializationisandhowtouseit.

TableofContentsWhatisitExternalMaterializedDataSourceSystems

RDBMSSystemsJBossDataGrid(JDG)

ViewOptionsMaterializationViewLoading

MaterializationManagementTypicalRDBMSUsageStepsTypicalJDGUsageStepsLoadingAndRefreshingAsampleVDBwithexternalmaterializedviewoptions

DefineMaterializedViewinDesignerMaterializationwithEmbeddedServerAppendix-1:DDLforcreatingMatViewStatusTable

Whatisit

InTeiid,aviewisavirtualtablebasedonthecomputing(loading/transforming/federating)ofacomplexSQLstatementacrossheterogeneousdatasources.TeiidExternalMaterializationcachestheviewdatatoanexternalphysicaldatabasesystem.Whenanewsessionissuesaqueryagainstthisview,therequestwillberedirectedtotheexternalphysicaldatabasesystemandthecachedresultswillbereturned,ratherthanre-computing.Thiscanprovetime-savingandcpu-savingifyourquerysentencesarecomplexandacrossmultiple,heterogeneousdatastores.


105

MaterializedView-Materializedviewisjustlikeotherviews,withadditionaloptionsinViewOptions,toenablepre-computingandcachingdatatoanexternaldatabasesystem.

MaterializedTable-MaterializedtablerepresentsthetargettablefortheMaterializedview,hasthesamestructureastheMaterializedview,butlivesonthephysicaldatabasesystem,needtocreatemanuallyandreferencedwiththeMaterializedviewsviaMATERIALIZED_TABLEoptionindesigning.ThedatabetweenMaterializedtableandphysicaltableiskeptsynchronizedbyteiidsystemwithatimeinterval.

MatViewStatusTable-EachMaterializedviewhastoreferenceastatustable,usedtosavetheMaterializedviews'status,thestatustableusuallylivesonthesamephysicalsourcewiththeMaterializedTable,needtocreatemanuallyandreferencedwiththeMaterializedviewviateiid_rel:MATVIEW_STATUS_TABLEindesigning.

MaterializedStageTable-EachMaterializedviewcanhaveastagetable,ithasthesamestructurewithMaterializedViewandMaterializedTable,needtocreatemanuallyandreferencedwiththeMaterializedviewviateiid_rel:MATERIALIZED_STAGE_TABLEindesigning.Primarypurposeofstagetableisforbettermanagement.Ifstagetabledefined,thesourcedataisfirstpopulatedtothestagetable,thenstagetablewillberenamedtoMaterializedTable.

Anexternalmaterializedviewgivestheadministratorfullcontrolovertheloadingandrefreshstrategies.RefertoMaterializationManagementfordetails.

ExternalMaterializedDataSourceSystemsThefollowingarethetypesofdatasourcesthathavebeentestedtoworkintheexternalmaterializationprocess:

RDBMSSystems

RDBMS-arelationaldatabaseshouldwork,aslongastheuserhasthecorrectpermissionstorenameatable.Exampledatabases;Oracle,Postgresql,MySQL,MSSqlServer,SAPHana,etc.

JBossDataGrid(JDG)

JBossDataGrid(JDG)-forin-memorycachingofresults.

ViewOptionsThefollowingViewoptions,whichstartwithteiid_rel:prefix,areextensionpropertiesusedinthemanagementoftheMaterializedView.

PropertyName Description Optional Default

MATERIALIZED Setthevalueto'TRUE'fortheviewtobematerialized false n/a

MATERIALIZED_TABLEDefinethenameoftargetsourcetable,thisalsohintsthematerializationisexternal

false n/a

UPDATABLE AllowupdatingMaterializedViewviaDMLUPDATE true false

teiid_rel:ALLOW_MATVIEW_MANAGEMENT AllowTeiidbasedmanagement true false

teiid_rel:MATVIEW_STATUS_TABLE fullyqualifiedStatusTableNamedefinedabove false n/a


106

teiid_rel:MATVIEW_BEFORE_LOAD_SCRIPTDDL/DMLcommandtorunbeforetheactualloadofthecache,typicallyusedtotruncatestagingtable

true

Whennotdefined,noscriptwillberun

teiid_rel:MATVIEW_LOAD_SCRIPT commandtorunforloadingofthecache true

willbedeterminedbasedonviewtransformation

teiid_rel:MATVIEW_AFTER_LOAD_SCRIPT

DDL/DMLcommandtorunaftertheactualloadofthecache.Typicallyusedtorenamestagingtabletoactualcachetable.RequiredwhenMATVIEW_LOAD_SCRIPTnotdefinedtocopydatafromteiid_rel:MATVIEW_STAGE_TABLEtoMATVIEWtable

true

Whennotdefined,noscriptwillberun

teiid_rel:MATVIEW_SHARE_SCOPE

Allowedvaluesare\{NONE,VDB,SCHEMA},whichdefineifthecachedcontentsaresharedamongdifferentVDBversionsanddifferentVDBsaslongasschemanamesmatch

true NONE

teiid_rel:MATERIALIZED_STAGE_TABLE

WhenMATVIEW_LOAD_SCRIPTpropertynotdefined,Teiidloadsthecachecontentsintothistable.RequiredwhenMATVIEW_LOAD_SCRIPTnotdefined

true n/a

teiid_rel:ON_VDB_START_SCRIPT DDL/DMLcommandtorunstartofvdb true n/a

teiid_rel:ON_VDB_DROP_SCRIPTDDL/DMLcommandtorunatVDBun-deploy;typicallyusedforcleaningthecache/statustables

true n/a

teiid_rel:MATVIEW_ONERROR_ACTION

Actiontobetakenwhenmatviewcontentsarerequestedbutcacheisinvalid.Allowedvaluesare(THROW_EXCEPTION=throwsanexception,IGNORE=ignoresthewarningandsuppliedinvalidateddata,WAIT=waitsuntilthedataisrefreshedandvalidthenprovidestheupdateddata)

true WAIT

teiid_rel:MATVIEW_TTL

timetoliveinmilliseconds.Providepropertyorcachehintonviewtransformation-propertytakesprecedence.

true

2^63milliseconds-effectivelythetablewillnotrefresh,butwillbeloadedasingletimeinitially

Tip forscriptsthatneedmorethanonestatementexecuted,useaprocedureblockBEGINstatement;statement;…END


107

SettheMATERIALIZEDto'TRUE'andtheMATERIALIZED_TABLEpointtoatargettableisnecessaryforexternalmaterialization,UPDATABLEisoptional,setitto'TRUE'ifwanttheexternalmaterializedviewbeupdatable.

Theaboveoptionsareusedinthemanagementbasedsystemprocedure.OnceaView,whichisdefinedwiththeaboveproperties,isdeployed,thefollowingsequenceofeventswilltakeplace:

1. UpontheVDBdeployment,teiid_rel:ON_VDB_START_SCRIPTwillberunoncompletionofthedeployment.

2. Basedontheteiid_rel:MATVIEW_TTLdefinedttl,aSchedulerrun/queueJobTaskbecreated,whichkeepsthecachecontentssynchronizedwithsourcetable.JobTaskwillfirstrunSYSADMIN.matViewStatusprocedure,refinethenextJobTask’sdeplaybyretrivedMaterializedviewstatusandthettl,thenrunSYSADMIN.loadMatViewprocedure,whichloadsthecachecontents.MoredetailsrefertoMaterializationViewLoading.

3. WhenVDBisun-deployed(notwhenserverisrestarted)theteiid_rel:ON_VDB_DROP_SCRIPTscriptwillberun.

Tip Thestart/stopscriptsarenotclusteraware-thatistheywillrunoneachclustermemberastheVDBisdeployed.Whendeployingintoaclusteredenvironment,thescriptsshouldbewritteninsuchawayastobeclustersafe.

MaterializationViewLoading

SYSADMIN.loadMatViewusedtoperformacompleterefreshofmaterializedtable,it’sbaseonextensionpropertiesinViewOptions:

1. Inserts/updatesaentryinteiid_rel:MATVIEW_STATUS_TABLE,whichindicatesthatthecacheisbeingloaded.

2. Initializesteiid_rel:MATVIEW_LOAD_SCRIPTtoinsertintostage_tableselect*frommatviewoptionnocachematviewifnotdefined.

3. Executesteiid_rel:MATVIEW_BEFORE_LOAD_SCRIPTifdefined.

4. Executesteiid_rel:MATVIEW_LOAD_SCRIPT.

5. Executesteiid_rel:MATVIEW_AFTER_LOAD_SCRIPTifdefined.

6. Updatesteiid_rel:MATVIEW_STATUS_TABLEentrytosetmaterializedviewstatusstatusto"LOADED"andvalid.

MaterializationManagement

Users,whentheyaredesigningtheirviews,candefineadditionalmetadataandextensionproperties(refertoabovesection)ontheirviewstocontroltheloadingandrefreshingofexternalmaterializationcache.Thisoptionprovidesalimited,butapowerfulwaytomanagethematerializationviews.Forthispurpose,SYSADMINSchemadefinesthreeprocedures(loadMatView,updateMatView,matViewStatus)tocooperatewiththeMaterializationManagement.

Basedonthedefinedmetadata,extensionproperties(refertoabovesection)ontheview,andmanagementsystemprocedures,aSchedulerautomaticallystartsduringtheVDBdeploymentandwillloadandkeepthecachefreshed.

TypicalRDBMSUsageSteps

1.CreateTables

Tomanageandreporttheloadingandrefreshingactivityofmaterializationview,aMaterializedTable,aMatViewStatusTableandaMaterializedStageTableneedbebedefinedinanyoneofthesourcemodels.Createthesetablesonthephysicaldatabase,beforeyoustartdesigningMaterializedView.


108

TheMaterializedTableandMatViewStatusTableisnecessary,MaterializedStageTableisoptional.TheMaterializedTableandMaterializedStageTableshouldhavethesamestructurewiththeMaterializedView.TheMatViewStatusTablemustcreatewithbelowschema:

CREATETABLEstatus

(

VDBNamevarchar(50)notnull,

VDBVersionvarchar(50)notnull,

SchemaNamevarchar(50)notnull,

Namevarchar(256)notnull,

TargetSchemaNamevarchar(50),

TargetNamevarchar(256)notnull,

Validbooleannotnull,

LoadStatevarchar(25)notnull,

Cardinalitylong,

Updatedtimestampnotnull,

LoadNumberlongnotnull,

PRIMARYKEY(VDBName,VDBVersion,SchemaName,Name)

);

Appendix-1:DDLforcreatingMatViewStatusTablecontainsaseriesofverifiedschemasagainstdiversephysicalsources.

2.CreateMaterializedView

Forbettermanagementandcontroloftheloadingandrefreshingstrategiesofthematerializedview,theextensionpropertiesinViewOptions,thiscanbedoneeitherthroughDesigner,oredittheDDL.RefertoDefineMaterializedViewinDesignerifthroughDesigner.

Theloadingandrefreshingstrategiescontroledbyloadscripts,therearetwokindsofloadscripts:

VDBScopeScripts-VDBstartscriptandVDBstopscriptwhichdefinedbyteiid_rel:ON_VDB_START_SCRIPTandteiid_rel:ON_VDB_DROP_SCRIPTcorrespondently,itsexecutedinVDBdeployingandremoving.

ProcedureScopeScripts-beforeloadscript,loadscriptandafterloadscriptwhichdefinedbyteiid_rel:MATVIEW_BEFORE_LOAD_SCRIPT,teiid_rel:MATVIEW_LOAD_SCRIPTandteiid_rel:MATVIEW_AFTER_LOAD_SCRIPTcorrespondently,thesescriptsbeexecutedinasequencebySYSADMIN.loadMatView,refertoMaterializationViewLoadingfordetails.

Torefresh/loadthematerializedview,thebasicprinciplestodefineloadscriptis:

Definetruncatetarget/stagingtablesqlinteiid_rel:MATVIEW_BEFORE_LOAD_SCRIPT

Defineinsertintotarget/stagingtablesqlinteiid_rel:MATVIEW_LOAD_SCRIPT

Definealterstagetabletotargettablelogicinteiid_rel:MATVIEW_AFTER_LOAD_SCRIPT.

Ifstagetableisdefined,youcandefinetruncatestagingtableinbeforeloadscript,defineinsertstagingtableinloadscript(ifnotdefined,insertintostageTableselect*frommatviewoptionnocachematviewwillbesetinruntime),definealterstagingtabletomaterializedtableinafterloadscript:

"teiid_rel:MATVIEW_BEFORE_LOAD_SCRIPT"'executeaccounts.native(''truncatetablestageTable'');',

"teiid_rel:MATVIEW_AFTER_LOAD_SCRIPT"'beginexecuteaccounts.native(''ALTERTABLEmatTableRENAMETOmatTable

_temp'');executeaccounts.native(''ALTERTABLEstageTableRENAMETOmatTable'');executeaccounts.native(''ALTER

TABLEmatTable_tempRENAMETOstageTable'');end',

Ifstagetableisnotdefined,youcandefinetruncatetargettableinbeforeloadscriptanddefineinserttargettableinloadscript:

"teiid_rel:MATVIEW_BEFORE_LOAD_SCRIPT"'executeaccounts.native(''truncatetablematTable'');',

"teiid_rel:MATVIEW_LOAD_SCRIPT"'insertintomatTableselect*frommatviewoptionnocachematview',


109

Note

Thathowevermaybetoosimplisticbecauseyourindexcreationmaybemoreperformantifdeferreduntilafterthetablehasbeencreated.Alsofullsnapshotrefreshesarebestdonetoastagingtablethenswappingitfortheexistingphysicaltabletoensurethattherefreshdoesnotimpactuserqueriesandtoensurethatthetableisvalidpriortouse.

3.UseMaterializedView

OncetheMaterializedViewiscompletelydefined,deployittoaTeiidServer.ThencreateanewsessionandissueaqueryagainstMaterializedView.Youwillfindit’stime-savingandcpu-savingifyourquerysentencesarecomplexandacrossmultiple,heterogeneousdatastores.

TypicalJDGUsageSteps

1.DefineJDGCaches

ThetypicalusageofJDGinmaterializationistoconfigureaJDGserver,whichcanbeclusteraware,thatwillbeaccessedusingtheJDGHotRodClient.SeetheJDGHotRodDataSourceforhowtoconfigureaccessingtheremotecache.

2.CreateMaterializedView

Toconfigureforexternalmaterialization,seetheHotRodTranslator.ThisexplainshowtoconfigureMaterializationManagementthatisspecificforusingJDGremotecacheandisessentialformanagingtheunderlyingmultiplecachesneededinordertoperformmaterialization.

3.UseMaterializedView

OncetheMaterializedViewiscompletelydefined,deployittoaTeiidServer.ThencreateanewsessionandissueaqueryagainstMaterializedView.Youwillfindit’stime-savingandcpu-savingifyourquerysentencesarecomplexandacrossmultiple,heterogeneousdatastores.

LoadingAndRefreshing

SystemProceduresareusedtoLoadingAndRefreshingMaterializedviewinanytime:

SYSADMIN.loadMatView-completerefreshthecachecontents,reloadthematerializedtable.

SYSADMIN.updateMatView-topartiallyupdatethecachecontents,updateasubsetofthematerializedtable.WhenpartialupdateisrunthecacheexpirationtimeisrenewedfornewtermbasedonCacheHintagain.

InTeiid,onceaVDBbestarted,allExternalMaterializedViewswillberefreshedbySYSADMIN.loadMatViewperiodicallywithatimeinterval.

AsampleVDBwithexternalmaterializedviewoptions

teiid-mat-example-vdb.xmlisasampleVDBdefinitionwhichcontainssixmaterializedview:

Model_A.VIEW_A-demonstratesMATVIEW_BEFORE_LOAD_SCRIPT,MATVIEW_AFTER_LOAD_SCRIPTwithMATERIALIZED_STAGE_TABLE

Model_B.VIEW_B-demonstratesMATVIEW_LOAD_SCRIPTwithMATERIALIZED_STAGE_TABLE

Model_C.VIEW_C-demonstratesMATVIEW_BEFORE_LOAD_SCRIPT,MATVIEW_LOAD_SCRIPTwithoutMATERIALIZED_STAGE_TABLE

Model_D.VIEW_D-demonstratesMATVIEW_AFTER_LOAD_SCRIPTwithMATERIALIZED_STAGE_TABLE


110

https://raw.githubusercontent.com/teiid/teiid-embedded-examples/master/embedded-caching/src/main/resources/teiid-mat-example-vdb.xml

Model_E.VIEW_E-demonstratestheminmumoptionsinmaterializedview

Model_F.VIEW_F-demonstratesthemaxmumoptionsinmaterializedview

DefineMaterializedViewinDesigner

TypicalUsageSteps

CreatematerializedviewsandcorrespondingphysicalmaterializedtargettablesinDesigner.Thiscanbedonethroughsettingthematerializedandtargettablemanually,orbyselectingthedesiredviews,rightclicking,thenselectingModeling→"CreateMaterializedViews"

GeneratetheDDLforyourphysicalmodelmaterializationtargettables.Thiscanbedonebyselectingthemodel,rightclicking,thenchoosingExport→"MetadataModeling"→"DataDefinitionLanguage(DDL)File".Thisscriptcanbeusedtocreatethedesiredschemaforyourmaterializationtargetonwhateversourceyouchoose.

Determinealoadandrefreshstrategy.Withtheschemacreatedthemostsimplisticapproachistojustloadthedata.TheloadcanevenbedonethroughTeiidwith

insertintotarget_tableselect*frommatviewoptionnocachematview

Note TheDesignertoolingforthisfeatureislackingatthismomentbutthiswillbeaddedincomingreleases.

MaterializationwithEmbeddedServer

ViewswithextensionpropertiesinViewOptionsandloadscriptsinMaterializationManagementdefined,youcansetupExternalMaterializationwithEmbeddedServerasbelow

EmbeddedServerserver=newEmbeddedServer();

…

server.addConnectionFactory("name",Object);

…

server.addTranslator("name",ExecutionFactory);

EmbeddedConfigurationconfig=newEmbeddedConfiguration();

config.setTransactionManager(EmbeddedHelper.getTransactionManager());

server.start(config);

server.deployVDB("matView-vdb.xml");

AnUsageExample

Appendix-1:DDLforcreatingMatViewStatusTable

h2

CREATETABLEstatus

(


VDBVersionvarchar(50)notnull,







Cardinalitylong,



111

https://raw.githubusercontent.com/teiid/teiid-embedded-examples/master/embedded-caching/src/main/java/org/teiid/example/ExternalMaterializationExample.java

LoadNumberlongnotnull,


);

MariaDB

CREATETABLEstatus

(


VDBVersionintegernotnull,







Cardinalitybigint,


LoadNumberbigintnotnull,


);


112

InternalMaterializationInternalmaterializationcreatesTeiidtemporarytablestoholdthematerializedtable.Whilethesetablesarenotfullydurable,theyperformwellinmostcircumstancesandthedataispresentateachTeiidinstancewhichremovesthesinglepointoffailureandnetworkoverheadofanexternaldatabase.Internalmaterializationalsoprovidesbuilt-infacilitiesforrefreshingandmonitoring.SeeMemoryLimitationsregardingsizelimitations.

TableofContentsViewOptionsLoadingAndRefreshing

UsingSystemProcedureUsingTTLSnapshotRefresh

UpdatableIndexesClusteringConsiderations

ViewOptions

Thematerializedoptionmustbesetfortheviewtobematerialized.TheCacheHint,whenusedinthecontextofaninternalmaterializedviewtransformationquery,providestheabilitytofinetunethematerializedtable.Thecachingoptionsarealsosettableviaextensionmetadata:

PropertyName Description Optional Default

materialized Setfortheviewtobematerialized false true

UPDATABLEAllowupdatingMaterializedViewviaDMLUPDATE

true false

teiid_rel:ALLOW_MATVIEW_MANAGEMENT

AllowTeiidbasedmanagementofthettlandinitialloadratherthantheimplicitbehavior.

true false

teiid_rel:MATVIEW_PREFER_MEMEORY Sameasthepref_memcachehintoption. true false

teiid_rel:MATVIEW_TTL

TriggeraScheduledExecutorServicewhichexecuterefreshMatViewrepeatedlywithaspecifiedtimetolive

true null

teiid_rel:MATVIEW_UPDATABLE

AllowupdatingMaterializedViewviarefreshMatView,refreshMatViewRow,refreshMatViewRows

true false.

teiid_rel:MATVIEW_SCOPE true VDB


113

teiid_rel:MATVIEW_SCOPE Sameasthescopecachehintoption.

true VDB

Thepref_memoptionalsoappliestointernalmaterializedviews.Internaltableindexpagesalreadyhaveamemorypreference,sotheperf_memoptionindicatesthatthedatapagesshouldprefermemoryaswell.

Allinternalmaterializedviewrefreshandupdateshappenatomically.InternalmaterializedviewssupportREAD_COMMITTED(usedalsoforREAD_UNCOMMITED)andSERIALIZABLE(usedalsoforREPEATABLE_READ)transactionisolationlevels.

AsampleVDBdefininganinternalmaterialization

<?xmlversion="1.0"encoding="UTF-8"standalone="yes"?>

<vdbname="sakila"version="1">

<modelname="pg">

<sourcename="pg"translator-name="postgresql"connection-jndi-name="java:/sakila-ds"/>

</model>

<modelname="sakila"type="VIRTUAL">

<metadatatype="DDL"><![CDATA[

CREATEVIEWactor(

actor_idinteger,

first_namevarchar(45)NOTNULL,

last_namevarchar(45)NOTNULL,

last_updatetimestampNOTNULL

)OPTIONS(materializedtrue,

UPDATABLE'TRUE',

"teiid_rel:MATVIEW_TTL"120000,

"teiid_rel:MATVIEW_PREFER_MEMORY"'true',

"teiid_rel:ALLOW_MATVIEW_MANAGEMENT"'true',

"teiid_rel:MATVIEW_UPDATABLE"'true',

"teiid_rel:MATVIEW_SCOPE"'vdb')

ASSELECTactor_id,first_name,last_name,last_updatefrompg."public".actor;

]]>

</metadata>

</model>

</vdb>

LoadingAndRefreshingAninternalmaterializedviewtableisinitiallyinaninvalidstate(thereisnodata).

Ifteiid_rel:ALLOW_MATVIEW_MANAGEMENTisspecifiedastrue,thentheinitialloadwilloccuronvdbstartup.

Ifteiid_rel:ALLOW_MATVIEW_MANAGEMENTisnotspecifiedorfalse,thentheloadofthematerializationtablewilloccuronimplicitonthefirstquerythataccessesthetable.

Whenarefreshhappenswhilethematerializationtableisinvalidallotherqueriesagainstthematerializedviewwillblockuntiltheloadcompletes.

UsingSystemProcedure

InsomesituationsadministratorsmaywishtobettercontrolwhenthecacheisloadedwithacalltoSYSADMIN.refreshMatView.Theinitialloadmayitselftriggertheinitialloadofdependentmaterializedviews.Aftertheinitialloaduserqueriesagainstthematerializedviewtablewillonlyblockifitisinaninvalidstate.ThevalidstatemayalsobecontrolledthroughtheSYSADMIN.refreshMatViewprocedure.

InvalidatingRefresh

CALLSYSADMIN.refreshMatView(viewname=>'schema.matview',invalidate=>true)


114

matviewwillberefreshedanduserquerieswillblockuntiltherefreshiscomplete(orfails).

Whiletheinitialloadmaytriggeratransitiveloadingofdependentmaterializedviews,subsequentrefreshesperformedwithrefreshMatViewwillusedependentmaterializedviewtablesiftheyexist.Onlyoneloadmayoccuratatime.IfaloadisalreadyinprogresswhentheSYSADMIN.refreshMatViewprocedureiscalled,itwillreturn-1immediatelyratherthanpreemptingthecurrentload.

UsingTTLSnapshotRefresh

TheCacheHintorextensionpropertiesmaybeusedtoautomaticallytriggerafullsnapshotrefreshafteraspecifiedtimetolive(ttl).Thebehaviorisdifferentdependingonwhetherthematerializationismanagedornon-managed.

Fornon-managedviewsthettlstartsfromthetimethetableisfinishedloadingandtherefreshwillbeinitiatedafterthettlhasexpiredonaviewaccess.

Formanagedviewsthettlisafixedintervalandrefresheswillbetriggeredregardlessofviewusage.

IneithercasetherefreshisequivalenttoCALLSYSADMIN.refreshMatView('viewname',*),wheretheinvalidationbehavior*isdeterminedbythevdbpropertylazy-invalidate.Bydefaultttlrefreshesareinvalidating,whichwillcauseotheruserqueriestoblockwhileloading.Thatisoncethettlhasexpired,thenextaccesswillberequiredtorefreshthematerializedtableinablockingmanner.Ifyouwouldratherthatthettlisenforcedlazily,suchthatthecurrentcontentsarenotreplaceduntiltherefreshcompletes,setthevdbpropertylazy-invalidate=true.

Auto-refreshTransformationQuery*

/*+cache(ttl:3600000)*/selectt.col,t1.colfromt,t1wheret.id=t1.id

Theresultingmaterializedviewwillbereloadedeveryhour(3600000milliseconds).

TTLSnapshotRefreshLimitations

Theautomaticttlrefreshmaynotbesuitableforcomplexloadingscenariosasnestedmaterializedviewswillbeusedbytherefreshquery.

Thenon-managedttlrefreshisperformedlazily,thatisitisonlytriggerbyusingthetableafterthettlhasexpired.Forinfrequentlyusedtableswithlongloadtimes,thismeansthatdatamaybeusedwellpasttheintendedttl.

UpdatableInadvanceduse-casesthecachehintmayalsobeusedtomarkaninternalmaterializedviewasupdatable.AnupdatableinternalmaterializedviewmayusetheSYSADMIN.refreshMatViewRowproceduretoupdateasinglerowinthematerializedtable.Ifthesourcerowexists,thematerializedviewtablerowwillbeupdated.Ifthesourcerowdoesnotexist,thecorrepsondingmaterializedrowwillbedeleted.Tobeupdatablethematerializedviewmusthaveasinglecolumnprimarykey.CompositekeysarenotyetsupportedbySYSADMIN.refreshMatViewRow.TransformationQuery:

/*+cache(updatable)*/selectt.col,t1.colfromt,t1wheret.id=t1.id

UpdateSQL:

CALLSYSADMIN.refreshMatViewRow(viewname=>'schema.matview',key=>5)

Giventhattheschema.matviewdefinesanintegercolumncolasitsprimarykey,theupdatewillcheckthelivesource(s)fortherowvalues.


115

Theupdatequerywillnotusedependentmaterializedviewtables,socareshouldbetakentoensurethatgettingasinglerowfromthistransformationqueryperformswell.SeetheReferenceGuideforinformationoncontrollingdependentjoins,whichmaybeapplicabletoincreasingtheperformanceofretrievingasinglerow.Therefreshquerydoesusenestedcaches,sothisrefreshmethodshouldbeusedwithcaution.

Whentheupdatableoptionisnotspecified,accessingthematerializedviewtableismoreefficientbecausemodificationsdonotneedtobeconsidered.Therefore,onlyspecifytheupdatableoptionifrowbasedincrementalupdatesareneeded.Evenwhenperformingrowupdates,fullsnapshotrefreshesmaybeneededtoensureconsistency.

TheEventDistributoralsoexposestheupdateMatViewRowasalowerlevelAPIforProgrammaticControl-careshouldbetakenwhenusingthisupdatemethod.

IndexesInternalmaterializedviewtableswillautomaticallycreateauniqueindexforeachuniqueconstraintandanon-uniqueindexforeachindexdefinedonthematerializedview.Theprimarykey(ifitexists)oftheviewwillautomaticallybepartofaclusteredindex.

Thesecondaryindexesarealwayscreatedasorderedtrees-bitmaporhashindexesarenotsupported.Teiid’smetadataforindexesiscurrentlylimited.Wearenotcurrentlyabletocaptureadditionalinformation,sortdirection,additionalcolumnstocover,etc.Youmayworkaroundsomeoftheselimitationsthough.

Functionbasedindexaresupported,butcanonlybespecifiedthroughDDLmetadata.IfyouarenotusingDDLmetadata,consideraddinganothercolumntotheviewthatprojectsthefunctionexpression,thenplaceanindexonthatnewcolumn.Queriestotheviewwillneedtobemodifiedasappropriatethoughtomakeuseofthenewcolumn/index.

Ifadditionalcoveredcolumnsareneeded,theymaysimplybeaddedtotheindexcolumns.Thishoweverisonlyapplicabletocomparabletypes.Addingadditionalcolumnswillincreasetheamountofspaceusedbytheindex,butmayallowitsusagetoresultinhigherperformancewhenonlythecoveredcolumnsareusedandthemaintableisnotconsulted.

ClusteringConsiderations

Eachmemberinaclustermaintainsitsowncopyofeachmaterializedtableandassociatedindexes.Anattemptismadetoensureeachmemberreceivesthesamefullrefresheventsastheothers.Fullconsistencyforupdatablematerializedviewshoweverisnotguaranteed.Periodicfullrefreshesofupdatablematerializedviewtableshelpsensureconsistencyamongmembers.


116

CodeTableCachingTeiidprovidesashortcuttocreatinganinternalmaterializedviewtableviathelookupfunction.

Thelookupfunctionprovidesawaytoaccelerategettingavalueoutofatablewhenakeyvalueisprovided.Thefunctionautomaticallycachesallofthekey/returnpairsforthereferencedtable.Thiscachingisperformedondemand,butwillproactivelyloadtheresultstoothermembersinacluster.Subsequentlookupsagainstthesametableusingthesamekeyandreturncolumnswillusethecachedinformation.

Thiscachingsolutionisappropriateforintegrationof"referencedata"withtransactionaloroperationaldata.Referencedataisusuallystaticandsmalldatasetsthatareusedfrequently.ExamplesareISOcountrycodes,statecodes,anddifferenttypesoffinancialinstrumentidentifiers.

UsageThiscachingmechanismisautomaticallyinvokedwhenthelookupscalarfunctionisused.Thelookupfunctionreturnsascalarvalue,soitmaybeusedanywhereanexpressionisexpected.Eachtimethisfunctioniscalledwithauniquecombinationofreferencedtable,returncolumn,andkeycolumn(thefirst3argumentstothefunction).

SeetheLookupFunctionintheReferenceGuideformoreinformationonuseofthelookupfunction.

CountryCodeLookup

lookup('ISOCountryCodes','CountryCode','CountryName','UnitedStates')

Limitations

Theuseofthelookupfunctionautomaticallyperformscaching;thereisnooptiontousethelookupfunctionandnotperformcaching.

Nomechanismisprovidedtorefreshcodetables

Onlyasinglekey/returncolumniscached-valueswillnotbesession/userspecific.

MaterializedViewAlternative

Thelookupfunctionisashortcuttocreateaninternalmaterializedviewwithanappropriateprimarykey.Inmanysituations,itmaybebettertodirectlycreatetheanalogousmaterializedviewratherthantouseacodetable.

CountryCodeLookupAgainstAMatView

SELECT(SELECTCountryCodeFromMatISOCountryCodesWHERECountryName=tbl.CountryName)asccFROMtbl

HereMatISOCountryCodesisaviewselectingfromISOCountryCodesthathasbeenmarkedasmaterializedandhasaprimarykeyandindexonCountryName.Thescalarsubquerywillusetheindextolookupthecountrycodeforeachcountrynameintbl.

Reasonstouseamaterializedview:

Morecontrolofthepossiblereturncolumns.Codetableswillcreateamaterializedviewforeachkey/valuepair.Iftherearemultiplereturncolumnsitwouldbebettertohaveasinglematerializedview.

Propermaterializedviewshavebuilt-insystemprocedure/tablesupport.

CodeTableCaching

117

Morecontrolviathecachehint.

TheabilitytouseOPTIONNOCACHE.

Thereisalmostnoperformancedifference.

Stepstocreateamaterializedview:

1. Createaviewselectingtheappropriatecolumnsfromthedesiredtable.Ingeneral,thisviewmayhaveanarbitrarilycomplicatedtransformationquery.

2. Designatetheappropriatecolumn(s)astheprimarykey.Additionalindexescanbeaddedifneeded.

3. Setthematerializedpropertytotrue.

4. Addacachehinttothetransformationquery.Tomimicthebehavioroftheimplicitinternalmaterializedviewcreatedbythelookupfunction,usetheHintsandOptions/*+cache(pref_mem)*/toindicatethatthetabledatapagesshouldprefertoremaininmemory.

Justaswiththelookupfunction,thematerializedviewtablewillbecreatedonfirstuseandreusedsubsequently.SeetheMaterializedViewsformore.

CodeTableCaching

118

TranslatorResultsCachingTranslatorscancontributecacheentriesintotheresultsetcacheviatheuseoftheCacheDirectiveobject.Theresultingcacheentriesbehavejustasiftheywerecreatedbyauserquery.SeetheTranslatorCachingAPIformoreonthisfeature.

TranslatorResultsCaching

119

CacheHint

Aquerycachehintcanbeusedto:

Indicatethatauserqueryiseligibleforresultsetcachingandsetthecacheentrymemorypreference,timetolive,etc.

Setthematerializedviewmemorypreference,timetolive,orupdatablity.

Indicatethatavirtualprocedureshouldbecachableandsetthecacheentrymemorypreference,timetolive,etc.

/*+cache[([pref_mem][ttl:n][updatable][scope:session|user|vdb])]*/sql...

ThecachehintshouldappearatthebeginningoftheSQL.Itcanbeappearasanyoneoftheleadingcomments.ItwillnothaveanyaffectonINSERT/UPDATE/DELETEstatementsorINSTEADOFTRIGGERS.

pref_mem-ifpresentindicatesthatthecachedresultsshouldprefertoremaininmemory.Theresultsmaystillbepagedoutbaseduponmemorypressure.

Note

Careshouldbetakentonotoverusethepref_memoption.ThememorypreferenceisimplementedwithJavasoftreferences.Whilesoftreferencesareeffectiveatpreventingoutofmemoryconditions.Toomuchmemoryheldbysoftreferencescanlimittheeffectiveworkingmemory.ConsultyourJVMoptionsforclearingsoftreferencesifyouneedtotunetheirbehavior.

ttl:n-ifpresentnindicatesthetimetolivevalueinmilliseconds.ThedefaultvalueforresultsetcachingisthedefaultexpirationforthecorrespondingInfinispancache.Thereisnodefaulttimetoliveformaterializedviews.

updatable-ifpresentindicatesthatthecachedresultscanbeupdated.Thisdefaultstofalseformaterializedviewsandtotrueforresultsetcacheentries.

scope-Therearethreedifferentcachescopes:session-cachedonlyforcurrentsession,user-cachedforanysessionbythecurrentuser,vdb-cachedforanyuserconnectedtothesamevdb.Forcachedqueriesthepresenceofthescopeoverridesthecomputedscope.Materializedviewsontheotherhanddefaulttothevdbscope.Formaterializedviewsexplicitlysettingthesessionoruserscopeswillresultinanon-replicatedsessionscopedmaterializedview.

Thepref_mem,ttl,updatable,andscopevaluesforamaterializedviewmayalsobesetviaextensionpropertiesontheview-usingtheteiid_relnamespacewithMATVIEW_PREFER_MEMORY,MATVIEW_TTL,MATVIEW_UPDATABLE,andMATVIEW_SCOPErespectively.Ifbotharepresent,theuseofanextensionpropertysupersedestheusageofthecachehint.

Limitations

Theformofthequeryhintmustbematchedexactlyforthehinttohaveaffect.Forauserqueryifthehintisnotspecifiedcorrectly,e.g./*+cach(pref_mem)*/,itwillnotbeusedbytheenginenorwilltherebeaninformationallog.Itiscurrentlyrecommendedthatyouverify(seeClientDevelopersGuide)inyourtestingthattheusercommandinthequeryplanhasretainedtheproperhint.

OPTIONNOCACHE

IndividualqueriesmayoverridetheuseofcachedresultsbyspecifyingOPTIONNOCACHEonthequery.0ormorefullyqualifiedvieworprocedurenamesmaybespecifiedtoexcludeusingtheircachedresults.Ifnonamesarespecified,cachedresultswillnotbeusedtransitively.

FullNOCACHE

HintsandOptions

120

SELECT*fromvg1,vg2,vg3WHERE…OPTIONNOCACHE

Nocachedresultswillbeusedatall.

SpecificNOCACHE

SELECT*fromvg1,vg2,vg3WHERE…OPTIONNOCACHEvg1,vg3

Onlythevg1andvg3cacheswillbeskipped,vg2oranycachedresultsnestedundervg1andvg3willbeused.

OPTIONNOCACHEmaybespecifiedinprocedureorviewdefinitions.Inthatway,transformationscanspecifytoalwaysusereal-timedataobtaineddirectlyfromsources.

HintsandOptions

121

ProgrammaticControlTeiidexposesabeanthatimplementstheorg.teiid.events.EventDistributorinterface.ItcanbelookedupinJNDIunderthenameteiid/event-distributor-factory.TheEventDistributorexposesmethodslikedataModification(whichaffectsresultsetcaching)orupdateMatViewRow(whichaffectsinternalmaterialization)toalerttheTeiidenginethattheunderlyingsourcedatahasbeenmodified.Theseoperations,whichworkclusterwidewillinvalidatethecacheentriesappropriatelyandreloadthenewcachecontents.

NoteChangeDataCapture-Ifyoursourcesystemhasanybuilt-inchangedatacapturefacilitiesthatcanscrapelogs,installtriggers,etc.tocapturedatachangeevents,theycancapturedandcanbepropagatedtoTeiidenginethroughapojobean/MDB/SessionBeandeployedinWildFlyengine.

ThebelowshowsacodeexampleashowusercanuseEventDistributorinterfaceintheirowncodethatisdeployedinthesameWildFlyVMusingaPojo/MDB/SessionBean.ConsultWildFlydocumentsdeployingasbeanastheyoutofscopeforthisdocument.

*EventDistributorCodeExample

publicclassChangeDataCapture{

publicvoidinvalidate(){

InitialContextic=newInitialContext();

EventDistributored=((EventDistributorFactory)ic.lookup("teiid/event-distributor-factory")).getEventD

istributor();

//thisbelowlineindicatesthatCustomertableinthe"model-name"schemahasbeenchanged.

//thisresultincachereload.

ed.dataModification("vdb-name","version","model-name","Customer");

}

}

NoteUpdatingCostinginformation-TheEventDistributorinterfacealsoexposesmanymethodsthatcanbeusedtoupdatethecostinginformationonyoursourcemodelsforoptimizedqueryplanning.Notethatthesevaluesvolatileandwillbelostduringaclusterre-start,asthereisnorepositorytopersist.

ProgrammaticControl

122

ClientDeveloper’sGuideThisguideintendedfordevelopersthataretryingtowrite3rdpartyapplicationsthatinteractwithTeiid.Thiswillguideyouthroughconnectionmechanisms,extensionstoJDBCAPI,ODBC,SSLetc.BeforeonecandelveintoTeiiditisveryimportanttolearnfewbasicconstructsofTeiid,likewhatisVDB?whatisModel?etc.Forthatpleasereadtheshortintroductionherehttp://teiid.jboss.org/basics/

ClientDeveloper’sGuide

123


ReauthenticationTeiidallowsforconnectionstobereauthenticatedsothattheidentityontheconnectioncanbechangedratherthancreatingawholenewconnection.IfusingJDBC,seethechangeUserConnectionextension.IfusingODBC,orsimplyneedastatementbasedmechanismforreauthentication,seealsotheSETStatementforSESSIONAUTHORIZATION.

Reauthentication

124

ExecutionPropertiesExecutionpropertiesmaybesetonaperstatementbasisthroughtheTeiidStatementinterfaceorontheconnectionviatheSETStatement.Forconvenience,thepropertykeysaredefinedbyconstantsontheorg.teiid.jdbc.ExecutionPropertiesinterface.

Table1.ExecutionProperties

PropertyName/StringConstant Description

PROP_TXN_AUTO_WRAP/autoCommitTxn Sameastheconnectionproperty.

PROP_PARTIAL_RESULTS_MODE/partialResultsMode SeethePartialResultsMode

PROP_XML_FORMAT/XMLFormat

DeterminestheformattingofXMLdocumentsreturnedbyXMLdocumentmodels.SeetheXMLextensions#Documentformattingsection.

PROP_XML_VALIDATION/XMLValidation

DetermineswhetherXMLdocumentsreturnedbyXMLdocumentmodelswillbevalidatedagainsttheirschemaafterprocessing.SeetheReferenceGuide’s"XMLSELECTCommand"chapterand"documentvalidation"section.

RESULT_SET_CACHE_MODE/resultSetCacheMode Sameastheconnectionproperty.

SQL_OPTION_SHOWPLAN/SHOWPLAN Sameastheconnectionproperty.

NOEXEC/NOEXEC Sameastheconnectionproperty.

JDBC4COLUMNNAMEANDLABELSEMANTICS/

useJDBC4ColumnNameAndLabelSemanticsSameastheconnectionproperty.

ExecutionProperties

125

XMLextensionsTheXMLextensionsapplyontoXMLresutlsfromqueriestoXMLdocumentmodels,andnottoXMLproducedbySQL/XMLorreadfromsomeothersource.

Documentformatting

ThePROP_XML_FORMATexecutionpropertycanbesettomodifythewaythatXMLdocumentsareformattedfromXMLdocumentmodels.ValidvaluesfortheconstantaredefinedinthesameExecutionPropertiesinterface:

1. XML_TREE_FORMAT-ReturnsaversionoftheXMLformattedfordisplay.TheXMLwilluselinebreaksandtabsasappropriatetoformattheXMLasatree.Thisformatisslowerduetotheformattingtimeandthelargerdocumentsize.

2. XML_COMPACT_FORMAT-ReturnsaversionoftheXMLformattedforoptimalperformance.TheXMLisasinglelongstringwithoutanyunnecessarywhitespace.

3. NotSet-Ifnoformatisset,theformattingflagontheXMLdocumentintheoriginalmodelishonored.Thismayproduceeitherthe"tree"or"compact"formofthedocumentdependingonthedocumentsetting.

Schemavalidation

ThePROP_XML_VALIDATIONexecutionpropertycanbesettoindicatethattheservershouldvalidateXMLdocumentmodeldocumentsagainsttheirschemabeforereturningthemtotheclient.Ifschemavalidationison,thentheserversendaSQLWarningifthedocumentdoesnotconformtotheschemaitisassociatedwith.UsingschemavalidationwillreducetheperformanceofyourXMLqueries.

XMLextensions

126

SETStatementExecutionpropertiesmayalsobesetontheconnectionbyusingtheSETstatement.TheSETstatementisnotyetalanguagefeatureofTeiidandishandledonlyintheJDBCclient.

SETSyntax:

SET[PAYLOAD](parameter|SESSIONAUTHORIZATION)value

SETSESSIONCHARACTERISTICSASTRANSACTIONISOLATIONLEVEL(READUNCOMMITTED|READCOMMITTED|REPEATABLEREAD|SERIALIZABLE)

SyntaxRules:

Theparametermustbeanidentifier-itcancontainspacesorotherspecialcharactersonlyifquoted.

Thevaluemaybeeitheranon-quotedidentifieroraquotedstringliteralvalue.

Ifpayloadisspecified,e.g."SETPAYLOADxy",thenasessionscopedpayloadpropertiesobjectwillhavethecorrespondingnamevaluepairset.Thepayloadobjectisnotfullysessionscoped.ItwillberemovedfromthesessionwhentheXAConnectionhandleisclosed/returnedtothepool(assumestheuseofTeiidDataSource).ThesessionscopedpayloadissupersededbytheusageofTeiidStatement.setPayload.

UsingSETSESSIONCHARACTERISTICSASTRANSACTIONISOLATIONLEVELisequivalenttocallingConnection.setTransactionIsolationwiththecorrespondinglevel.

TheSETstatementismostcommonlyusedtocontrolplanningandexecution.

SETSHOWPLAN(ON|DEBUG|OFF)

SETNOEXEC(ON|OFF)

EnablingPlanDebug

Statements=connection.createStatement();

s.execute("SETSHOWPLANDEBUG");

...

Statements1=connection.createStatement();

ResultSetrs=s1.executeQuery("selectcolfromtable");

ResultSetplanRs=s1.exeuteQuery("SHOWPLAN");

planRs.next();

StringdebugLog=planRs.getString("DEBUG_LOG");

QueryPlanwithoutexecutingthequery

s.execute("SETNOEXECON");

s.execute("SETSHOWPLANDEBUG");

...

e.execute("SETNOEXECOFF");

TheSETstatementmayalsobeusedtocontrolauthorization.ASETSESSIONAUTHORIZATIONstatementwillperformaReauthenticationgiventhecredentialscurrentlysetontheconnection.TheconnectioncredentialsmaybechangedbyissuingaSETPASSWORDstatement.ASETPASSWORDstatementdoesnotperformareauthentication.

ChangingSessionAuthorization

Statements=connection.createStatement();

s.execute("SETPASSWORD'someval'");

s.execute("SETSESSIONAUTHORIZATION'newuser'");

SETStatement

127

SETStatement

128

SHOWStatementTheSHOWstatementcanbeusedtoseeavariteyofinformation.TheSHOWstatementisnotyetalanguagefeatureofTeiidandishandledonlyintheJDBCclient.

SHOWUsage:

SHOWPLAN-returnsaresultsetwithaclobcolumnPLAN_TEXT,anxmlcolumnPLAN_XML,andaclobcolumnDEBUG_LOGwitharowcontainingthevaluesfromthepreviouslyexecutedquery.IfSHOWPLANisOFFornoplanisavailable,norowsarereturned.IfSHOWPLANisnotsettoDEBUG,thenDEBUG_LOGwillreturnanullvalue.

SHOWANNOTATIONS-returnsaresultsetwithstringcolumnsCATEGORY,PRIORITY,ANNOTATION,RESOLUTIONandarowforeachannotationonthepreviouslyexecutedquery.IfSHOWPLANisOFFornoplanisavailable,norowsarereturned.

SHOW<property>-theinverseofSET,showsthepropertyvalueforthegivenproperty,returnsaresultsetwithasinglestringcolumnwithanamematchingthepropertykey.

SHOWALL-returnsaresultsetwithaNAMEstringcolumnandaVALUEstringcolumnwitharowentryforeverypropertyvalue.TheSHOWstatementismostcommonlyusedtoretrievethequeryplan,seetheplandebugexample.

SHOWStatement

129

TransactionsTeiidsupportsthreetypesoftransactionsfromaclientperspective–global,local,andrequestlevel.AllareimplementedbytheTeiidServerasXAtransactions.SeetheJTAspecificationformoreonXATransactions.

Transactions

130

http://java.sun.com/javaee/technologies/jta/index.jsp

LocalTransactionsALocaltransactionfromaclientperspectiveaffectsonlyasingleresource,butcancoordinatemultiplestatements.

JDBCSpecific

TheConnectionclassusesthe"autoCommit"flagtoexplicitlycontrollocaltransactions.Bydefault,autoCommitissetto"true",whichindicatesrequestlevelorimplicittransactioncontrol.exampleofhowtouselocaltransactionsbysettingtheautoCommitflagtofalse.

LocaltransactioncontrolusingautoCommit

//Setautocommittofalseandstartatransaction

connection.setAutoCommit(false);

try{

//Executemultipleupdates

Statementstatement=connection.createStatement();

statement.executeUpdate(“INSERTINTOAccounts(ID,Name)VALUES(10,‘Mike’)”);

statement.executeUpdate(“INSERTINTOAccounts(ID,Name)VALUES(15,‘John’)”);

statement.close();

//Committhetransaction

connection.commit();

}catch(SQLExceptione){

//Ifanerroroccurs,rollbackthetransaction

connection.rollback();

}

Thisexampledemonstratesseveralthings:

1. SettingautoCommitflagtofalse.Thiswillstartatransactionboundtotheconnection.

2. Executingmultipleupdateswithinthecontextofthetransaction.

3. Whenthestatementsarecomplete,thetransactioniscommittedbycallingcommit().

4. Ifanerroroccurs,thetransactionisrolledbackusingtherollback()method.

Anyofthefollowingoperationswillendalocaltransaction:

1. Connection.setAutoCommit(true)–ifpreviouslysettofalse

2. Connection.commit()

3. Connection.rollback()

4. Atransactionwillberolledbackautomaticallyifittimesout.

TurningOffJDBCLocalTransactionControls

Insomecases,toolsorframeworksaboveTeiidwillcallsetAutoCommit(false),commit()androllback()evenwhenallaccessisread-onlyandnotransactionsarenecessary.InthescopeofalocaltransactionTeiidwillstartandattempttocommitanXAtransaction,possiblycomplicatingconfigurationorcausingperformancedegradation.

Inthesecases,youcanoverridethedefaultJDBCbehaviortoindicatethatthesemethodsshouldperformnoactionregardlessofthecommandsbeingexecuted.Toturnofftheuseoflocaltransactions,addthispropertytotheJDBCconnectionURL

LocalTransactions

131

disableLocalTxn=true

TipTurningofflocaltransactionscanbedangerousandcanresultininconsistentresults(ifreadingdata)orinconsistentdataindatastores(ifwritingdata).Forsafety,thismodeshouldbeusedonlyifyouarecertainthatthecallingapplicationdoesnotneedlocaltransactions.

TransactionStatements

Transactioncontrolstatements,whicharealsoapplicabletoODBCclients,explicitlycontrolthelocaltransactionboundaries.Therelevantstatementsare:

STARTTRANSACTION-synonymforconnection.setAutoCommit(false)

COMMIT-synonymforconnection.setAutoCommit(true)

ROLLBACK-synonymforconnection.rollback()andreturningtoautocommitmode.

LocalTransactions

132

RequestLevelTransactionsRequestleveltransactionsareusedwhentherequestisnotinthescopeofaglobalorlocaltransaction,whichimplies"autoCommit"is"true".Inarequestleveltransaction,yourapplicationdoesnotneedtoexplicitlycallcommitorrollback,rathereverycommandisassumedtobeitsowntransactionthatwillautomaticallybecommittedorrolledbackbytheserver.

TheTeiidServercanperformupdatesthroughvirtualtables.Theseupdatesmightresultinanupdateagainstmultiplephysicalsystems,eventhoughtheapplicationissuestheupdatecommandagainstasinglevirtualtable.Often,ausermightnotknowwhetherthequeriedtablesactuallyupdatemultiplesourcesandrequireatransaction.

Forthatreason,theTeiidServerallowsyourapplicationtoautomaticallywrapcommandsintransactionswhennecessary.Becausethiswrappingincursaperformancepenaltyforyourqueries,youcanchoosefromanumberofavailablewrappingmodestosuityourenvironment.Youneedtochoosebetweenthehighestdegreeofintegrityandperformanceyourapplicationneeds.Forexample,ifyourdatasourcesarenottransaction-compliant,youmightturnthetransactionwrappingoff(completely)tomaximizeperformance.

Youcansetyourtransactionwrappingtooneofthefollowingmodes:

1. ON:Thismodealwayswrapseverycommandinatransactionwithoutcheckingwhetheritisrequired.Thisisthesafestmode.

2. OFF:Thismodeneverautomaticallywrapsacommandinatransactionorcheckwhetheritneedstowrapacommand.Thismodecanbedangerousasitwillallowmultiplesourceupdatesoutsideofatransactionwithoutanerror.Thismodehasbestperformanceforapplicationsthatdonotuseupdatesortransactions.

3. DETECT:Thismodeassumesthattheuserdoesnotknowtoexecutemultiplesourceupdatesinatransaction.TheTeiidServercheckseverycommandtoseewhetheritisamultiplesourceupdateandwrapsitinatransaction.Ifitissinglesourcethenusesthesourcelevelcommandtransaction.YoucansetthetransactionmodeasapropertywhenyouestablishtheConnectionoronaper-querybasisusingtheexecutionproperties.Formoreinformationonexecutionproperties,seethesectionExecutionProperties

MultipleInsertBatches

WhenissuinganINSERTwithaqueryexpression(orthedeprecatedSELECTINTO),multipleinsertbatcheshandledbyseparatesourceINSERTSmaybeprocessedbytheTeiidserver.CareshouldbetakentoensurethattargetedsourcessupportXAorthatcompensatingactionsaretakenintheeventofafailure.

RequestLevelTransactions

133

UsingGlobalTransactionsGlobalorclientXAtransactionsareonlyapplicabletoJDBCclients.Theyalltheclienttocoordinatemultipleresourcesinasingletransaction.TotakeadvantageofXAtransactionsontheclientside,usetheTeiidDataSource(orTeiidEmbeddedwithtransactiondetectionenabled).

WhenanXAConnectionisusedinthecontextofaUserTransactioninanapplicationserver,suchasJBoss,WebSphere,orWeblogic,theresultingconnectionwillalreadybeassociatedwiththecurrentXAtransaction.NoadditionalclientJDBCcodeisnecessarytointeractwiththeXAtransaction.

UsagewithUserTransaction

UserTransactionut=context.getUserTransaction();

try{

ut.begin();

Datasourceoracle=lookup(...)

Datasourceteiid=lookup(...)

Connectionc1=oracle.getConnection();

Connectionc2=teiid.getConnection();

//dosomethingwithOracleconnection

//dosomethingwithTeiidconnection

c1.close();

c2.close();

ut.commit();

}catch(Exceptionex){

ut.rollback();

}

InthecasethatyouarenotrunninginaJEEcontainerenvironmentandyouhaveyourowntransactionmangertoco-ordinatetheXAtransactions,codewilllooksomewhatlikebelow.

ManualUsageofXAtransactions

XAConnectionxaConn=null;

XAResourcexaRes=null;

Connectionconn=null;

Statementstmt=null;

try{

xaConn=<XADataSourceinstance>.getXAConnection();

xaRes=xaConn.getXAResource();

Xidxid=<newXidinstance>;

conn=xaConn.getConnection();

stmt=conn.createStatement();

xaRes.start(xid,XAResource.TMNOFLAGS);

stmt.executeUpdate("insertinto…");

<otherstatementsonthisconnectionorotherresourcesenlistedinthistransaction>

xaRes.end(xid,XAResource.TMSUCCESS);

if(xaRes.prepare(xid)==XAResource.XA_OK){

xaRes.commit(xid,false);

}

}

catch(XAExceptione){

xaRes.rollback(xid);

}

finally{

<cleanup>

}


134

WiththeuseofglobaltransactionsmultipleTeiidXAConnectionsmayparticipateinthesametransaction.TheTeiidJDBCXAResource"isSameRM"methodreturns"true"onlyifconnectionsaremadetothesameserverinstanceinacluster.IftheTeiidconnectionsaretodifferentserverinstancesthentransactionalbehaviormaynotbethesameasiftheyweretothesameclustermember.Forexample,iftheclienttransactionmanagerusesthesameXIDforeachconnection(whichitshouldnotsinceisSameRMwillreturnfalse),duplicateXIDexceptionsmayarisefromthesamephysicalsourceaccessedthroughdifferentclustermembers.Morecommonlyiftheclienttransactionmanagerusesadifferentbranchidentifierforeachconnection,issuesmayarisewithsourcesthatlockorisolatechangesbaseduponbranchidentifiers.


135

Restrictions

ApplicationRestrictions

Theuseofglobal,local,andrequestleveltransactionsareallmutuallyexclusive.Requestleveltransactionsonlyapplywhennotinaglobalorlocaltransaction.Anyattempttomixglobalandlocaltransactionsconcurrentlywillresultinanexception.

EnterpriseInformationSystem(EIS)Support

TheunderlyingresourceadaptorsthatrepresenttheEISsystemandtheEISsystemitselfmustsupportXAtransactionsiftheywanttoparticipateindistributedXAtransactionthroughTeiid.IfsourcesystemdoesnotsupporttheXA,thenitcannotparticipateinthedistributedtransaction.However,thesourceisstilleligibletoparticipateindataintegrationwithouttheXAsupport.

TheparticipationintheXAtransactionisautomaticallydeterminedbasedontheresourceadaptorsXAcapability.Itisuser’sresponsibilitytomakesurethattheyconfigureaXAresourcewhentheyrequirethemtoparticipateindistributedtransaction.

Restrictions

136

ODBCSupportOpenDatabaseConnectivity(ODBC)isastandarddatabaseaccessmethoddevelopedbytheSQLAccessgroupin1992.ODBC,justlikeJDBCinJava,allowsconsistentclientaccessregardlessofwhichdatabasemanagementsystem(DBMS)ishandlingthedata.ODBCusesadrivertotranslatetheapplication’sdataqueriesintocommandsthattheDBMSunderstands.Forthistowork,boththeapplicationandtheDBMSmustbeODBC-compliant–thatis,theapplicationmustbecapableofissuingODBCcommandsandtheDBMSmustbecapableofrespondingtothem.

TeiidcanprovideODBCaccesstodeployedVDBsintheTeiidruntimethroughPostgreSQL’sODBCdriver.ThisispossiblebecauseTeiidhasaPostgreSQLserveremulationlayeraccessibleviasocketclients.

Note Bydefault,ODBCisenabledandrunningononport35432.

Thepgemulationisnotcomplete.TheintentionoftheODBCaccessistoprovidenon-JDBCconnectivitytoissueTeiidqueries-notpgsqlqueries.WhilemanyPostgreSQLconstructsaresupportedthedefaultbehaviorforqueriesmatchesTeiid’sexpectations.SeeSystemPropertiesforoptionalpropertiesthatfurtheremulatepgsqlhandling.

KnownLimitations:

Updateablecursorsarenotsupported.Youwillreceiveparsingerrorscontainingthepgsystemcolumnctidifthisfeatureisnotdisabled.

LOsupportisnotavailable.LOBswillbereturnedasstringorbyteaasappropriateusingthetransportmaxlobsizesetting.

TheTeiidobjecttypewillmaptothePostgreSQLUNKNOWNtype,whichcannotbeserializedbytheODBClayer.Cast/Convertshouldbeusedtoprovideatypehintwhenappropriate-forexampleteiid_session_setreturnsanobjectvalue."SELECTteiid_session_set('x','y')"willfail,but"SELECTcast(teiid_session_set('x','y')asstring)"willsucceed.

Multi-dimensionalarraysarenotsupported.

Installation

BeforeanapplicationcanuseODBC,youmustfirstinstalltheODBCdriveronsamemachinethattheapplicationisrunningonandthencreateaDataSourceName(DSN)thatrepresentsaconnectionprofileforyourTeiidVDB.

Forawindowsclient,seetheWindowsInstallationGuide.

Configuration

Warning

BydefaultTeiidsupportsplaintextpasswordauthenticationforODBC.Iftheclient/serverarenotconfiguredtouseSSLorGSSauthentication,thepasswordwillbesentinplaintextoverthenetwork.IfyouneedsecurepasswordsintransitandarenotusingSSL,thenconsiderinstallingasecuritydomainthatwillacceptsafepasswordvaluesfromtheclient(forexampleencryptedorhashed).

SeetheSecurityGuidefordetailsonconfiguringSSLforandusingKerberoswiththepgtransport.

Forawindowsclient,seetheConfiguringtheDataSourceName.

SeealsoDSNLessConnection.

ConnectionSettings

ODBCSupport

137

http://www.postgresql.org/

Alltheavailablepgdriverconnectionoptionswiththeirdescriptionsthatcanbeusedaredefinedherehttp://psqlodbc.projects.pgfoundry.org/docs/config.html.Whenusingthesepropertiesontheconnectionstring,theirpropertynamesaredefinedherehttp://psqlodbc.projects.pgfoundry.org/docs/config-opt.html.

HoweverTeiiddoesnothonorallproperties,andsome,suchasUpdatableCursors,willcausequeryfailures.

Table1.PrimaryODBCSettingsForTeiid

Name Description

UpdateableCursors&RowVersioning Shouldnotbeused.

Useserversideprepare&ParseStatements&DisallowPremature

Itisrecommendedthat"Useserversideprepare"isenabledand"ParseStatements"/"DisallowPremature"arediabled

SSLmode SeeSecurityGuide

UseDeclare/Fetchcursors&FetchMaxCount Shouldbeusedtobettermanageresourceswhenlargeresultsetsareused

Logging/debugsettingscanbeutilizedasneeded.

Settingsthatmanipulatedatatypes,metadata,oroptimizationssuchas"ShowSystemTables","Trueis-1","Backendeneticoptimizer","ByteaasLongVarBinary","BoolsasChar",etc.areignoredbytheTeiidserverandhavenoclientsideeffect.Ifthereisaneedfortheseoranyothersettingstohaveadefinedaffect,pleaseopenanissuewiththeproduct/project.

Anyothersettingthatdoeshaveaclientsideaffect,suchas"LF<→CR/LFconversion",maybeusedifdesiredbutthereiscurrentlynoserversideusageofthesetting.

TeiidConnectionSettings

MostTeiidspecificconnectionpropertiesdonotmaptoODBCclientconnectionsettings.IfyoufindyourselfinthissituationandcannotusepostconnectionSETstatements,thentheVDBitselfmaytakedefaultconnectionpropertiesforODBC.UseVDBpropertiesoftheformconnection.XXXtocontrolthingslikepartialresultsmode,resultsetcaching,etc.

ODBCSupport

138

http://psqlodbc.projects.pgfoundry.org/docs/config.html

http://psqlodbc.projects.pgfoundry.org/docs/config-opt.html

InstallingtheODBCDriverClientAPostgreSQLODBCdriverneededtomaketheODBCconnectiontoTeiidisnotbundledwiththeTeiiddistribution.TheappropriatedriverneedsbedownloadeddirectlyfromthePostgreSQLwebsite.Wehavetestedwith8.04.200versionoftheODBCdriver.

MicrosoftWindows

1. DownloadtheODBC8.4driverfromPostgreSQLdownloadsite.Ifyouarelookingfor64-bitWindowsdriverdownloadthedriverfromhere.Laterversionsofthedrivermaybeused,butarenotconsideredfullysupported.

2. ExtractthecontentsoftheZIPfileintoatemporarylocationonyoursystem.Forexample:"c:\temp\pgodbc"

3. Doubleclickon"psqlodbc.msi"fileor(.exefileinthecaseof64bit)tostartinstallationofthedriver.

4. TheWizardappearsas

Click"Next".5.Thenextstepofthewizarddisplays.


139

http://www.postgresql.org/ftp/odbc/versions/

http://ftp.postgresql.org/pub/odbc/versions/msi/psqlodbc_08_04_0200.zip

http://code.google.com/p/visionmap/wiki/psqlODBC

Carefullyreadit,andcheckthe"IacceptthetermsintheLicenseAgreement",ifyouareagreeingtothelicensingterms.Thenclick"Next".6.Thenextstepofthewizarddisplays.

Ifyouwanttoinstallinadifferentdirectorythanthedefaultthatisalreadyselected,clickthe"Browse"buttonandselectadirectory.Click"Next"tostartinstallingintheselecteddirectory.7.Thenextstepofthewizarddisplays.


140

Thisstepsummarizesthechoicesyouhavemadeinthewizard.Reviewthisinformation.Ifyouneedtochangeanything,youcanusetheBackbuttontoreturntoprevioussteps.Click"Install"toproceed.8.1.Theinstallationwizardcopiesthenecessaryfilestothelocationyouspecified.Whenitfinishes,thefollowingscreendisplays.

Click"Finish"tocomplete.

Other*nixPlatformInstallations


141

ForallotherplatformsotherthanMicrosoftWindows,theODBCdriverneedsbuiltfromthesourcefilesprovided.DownloadtheODBCdriversourcefilesfromthePostgreSQLdownloadsite.Untarthefilestoatemporarylocation.Forexample:"~/tmp/pgodbc".Buildandinstallthedriverbyrunningthecommandsbelow.

Note Youshouldusesuperuseraccountoruse"sudo"commandforrunningthe"makeinstall"command.

%tar-zxvfpsqlodbc-xx.xx.xxxx.tar.gz

%cdpsqlodbc-xx.xx.xxxx

%./configure

%make

%makeinstall

Some*nixdistributionsmayalreadyprovidebinaryformsoftheappropriatedriver,whichcanbeusedasanalternativetobuildingfromsource.


142

http://wwwmaster.postgresql.org/download/mirrors-ftp/odbc/versions/src/psqlodbc-08.04.0200.tar.gz

ConfiguringtheDataSourceName(DSN)SeeTeiidsupportedoptionsforadescriptionoftheclientconfiguration.

WindowsInstallation

OnceyouhaveinstalledtheODBCDriverClientsoftwareonyourworkstation,youhavetoconfigureittoconnecttoaTeiidRuntime.NotethatthefollowinginstructionsarespecifictotheMicrosoftWindowsPlatform.

Todothis,youmusthaveloggedintotheworkstationwithadministrativerights,andyouneedtousetheControlPanel’sDataSources(ODBC)applettoaddanewdatasourcename.

EachdatasourcenameyouconfigurecanonlyaccessoneVDBwithinaTeiidSystem.TomakemorethanoneVDBavailable,youneedtoconfiguremorethanonedatasourcename.

Followthebelowstepsincreatingadatasourcename(DSN)

1. FromtheStartmenu,selectSettings>ControlPanel.

2. TheControlPaneldisplays.DoubleclickAdministrativeTools.

3. ThenDouble-clickDataSources(ODBC).

4. TheODBCDataSourceAdministratorappletdisplays.ClickthetabassociatedwiththetypeofDSNyouwanttoadd.

5. TheCreateNewDataSourcedialogboxdisplays.IntheSelectadriverforwhichyouwanttosetupadatasourcetable,selectPostgreSQLUnicode.

6. ClickFinish

7. ThePostgreSQLODBCDSNSetupdialogboxdisplays.

IntheDataSourceNameeditbox,typethenameyouwanttoassigntothisdatasource.IntheDatabaseeditbox,typethenameofthevirtualdatabaseyouwanttoaccessthroughthisdatasource.IntheServereditbox,typethehostnameorIPaddressofyourTeiidruntime.IfconnectingviaafirewallorNATaddress,thefirewalladdressorNATaddressshouldbeentered.InthePorteditbox,typetheportnumbertowhichtheTeiidSystemlistensforODBCrequests.Bydefault,TeiidlistenesforODBCrequestsonport35432IntheUserNameandPasswordeditboxes,supplytheusernameandpasswordfortheTeiidruntimeaccess.ProvideanydescriptionaboutthedatasourceintheDescriptionfield.

1. ClickontheDatasourcebutton,youwillseethisbelowfigure.Configureoptionsasshown.


143

Clickon"page2"andmakesuretheoptionsareselectedasshown

1. Click"save"andyoucanoptionallyclick"test"tovalidateyourconnectioniftheTeiidisrunning.YouhaveconfiguredaTeiid’svirtualdatabaseasadatasourceforyourODBCapplications.NowyoucanuseapplicationssuchasExcel,AccesstoquerythedataintheVDB


144

Other*nixPlatformInstallations

BeforeyoucanaccessTeiidusingODBConany*nixplatforms,youneedtoeitherinstallaODBCdrivermanagerorverifythatonealreadyexists.AstheODBCDrivermanagerTeiidrecommendsunixODBC.IfyouareworkingwithRedHatLinuxorFedorayoucancheckthegraphical"yum"installertosearch,findandinstallunixODBC.OtherwiseyoucandownloadtheunixODBCmanagerhere.Toinstall,simplyuntarthecontentsofthefiletoatemporarylocationandexecutethefollowingcommandsassuperuser.

./configure

make

makeinstall

CheckunixODBCwebsitesiteformoreinformation,ifyourunintoanyissuesduringtheinstallation.

Now,tooverifythatPostgreSQLdriverinstalledcorrectlyfromearlierstep,executethefollowingcommand

odbcinst-q-d

ThatshouldshowyoualltheODBCdriversinstalledinyoursystem.NowitistimetocreateaDSN.Edit"/etc/odbc.ini"fileandaddthefollowing

[<DSNname>]

Driver=/usr/lib/psqlodbc.so

Description=PostgreSQLDataSource

Servername=<TeiidHostnameorip>

Port=35432

Protocol=7.4-1

UserName=<user-name>

Password=<password>

Database=<vdb-name>

ReadOnly=no

ServerType=Postgres

ConnSettings=

UseServerSidePrepare=1

Debug=0

Fetch=10000

#enablebelowwhendealinglargeresultsetstoenablecursoring

#UseDeclareFetch=1

Notethatyouneed"sudo"permissionstoeditthe"/etc/odbc.ini"file.ForalltheavailableconfigurableoptionsthatyoucanuseindefiningaDSNcanbefoundhereonpostgreSQLODBCpage.

OnceyouaredonewithdefiningtheDSN,youcanverifyyourDSNusingthefollowingcommand

isql<DSN-name>[<user-name><password>]<commands.sql

where"commands.sql"filecontainstheSQLcommandsyouwouldliketoexecute.Youcanalsoomitthecommands.sqlfile,thenyouwillbeprovidedwithainteractiveshell.

Tip YoucanalsouselanguageslikePerl,Python,C/C++withODBCportstoPostgres,oriftheyhavedirectPostgresconnectionmodulesyoucanusethemtootoconnectTeiidandissuequeriesanretrieveresults.


145

http://www.unixodbc.org/

http://www.unixodbc.org/unixODBC-2.3.0.tar.gz

http://www.unixodbc.org/

http://psqlodbc.projects.postgresql.org/config.html


146

DSNLessConnectionYoucanalsoconnecttoTeiidVDBusingODBCwithoutexplicitlycreatingaDSN.However,inthesescenariosyourapplicationneeds,whatiscalledas"DSNlessconnectionstring".Thebelowisasampleconnectionstring

ForWindows:

ODBC;DRIVER={PostgreSQLUnicode};DATABASE=<vdb-name>;SERVER=<host-name>;PORT=

<port>;Uid=<username>;Pwd=<password>;c4=0;c8=1;

For*nix:

ODBC;DRIVER={PostgreSQL};DATABASE=<vdb-name>;SERVER=<host-name>;PORT=<port>;Uid=

<username>;Pwd=<password>;c4=0;c8=1;

SeetheTeiidsupportedoptions.

DSNLessConnection

147

ConfiguringConnectionPropertieswithODBCWhenworkingwithODBCconnection,usercansettheconnectionpropertiesDriverConnection#URLConnectionPropertiesthatareavailableinTeiidbyexecutingthecommandlikebelow.

SET<property-name>TO<property-value>

forexampletoturnontheresultsetcachingyoucanissue

SETresultSetCacheModeTO'true'

AnotheroptionistosetthisasVDBpropertyinvdb.xmlfileas

<vdbname="...">

<propertyname="connection.resultSetCacheMode"value="true"/>

...

</vdb>

ODBCConnectionProperties

148

JDBCSupportTeiidprovidesarobustJDBCdriverthatimplementsmostoftheJDBCAPIaccordingtothelatestspecificationandsupportedJavaversion.MosttoolingdesignedtoworkwithJDBCshouldworkseamlesslywiththeTeiiddriver.Whenindoubt,seeUnsupportedJDBCMethodsforfunctionalitythathasyettobeimplemented.

Ifyou’reneedsgobeyondJDBC,TeiidhasalsoprovidedJDBCExtensionsforasynchhandling,federation,andotherfeatures.

GeneratedKeys

TeiidsupportsreturninggeneratedkeysforJDBCsourcesandfromTeiidtemptableswithSERIALprimarykeycolumns.Howeverthecurrentimplementationwillreturnonlythelastsetofkeysgeneratedandwillreturnthekeyresultsdirectlyfromthesource-noviewprojectionofotherintermediatehandlingisperformed.Formostscenarios(singlesourceinserts)thishandlingissufficient.AcustomsolutionmayneedtobedevelopedifyouareusingaFOREACHROWinsteadoftriggertoprocessyourinsertsandtargetmultipletablesthateachreturngeneratedkeys.ItispossibletodevelopaUDFthatalsomanipulatesthereturnedgeneratedkeys-seetheorg.teiid.CommandContextmethodsdealingwithgeneratedkeysformore.

JDBCSupport

149

ConnectingtoaTeiidServerTheTeiidJDBCAPIprovidesJavaDatabaseConnectivity(JDBC)accesstoanyVirtualDatabase(VDB)deployedonaTeiidServer.TheTeiidJDBCAPIiscompatiblewiththeJDBC4.0specification;however,itdoesnotfullysupportallmethods.Advancedfeatures,suchasupdatableresultsetsorSQL3datatypes,arenotsupported.

JavaclientapplicationsconnectingtoaTeiidServerwillneedtouseJava1.6JDK.PreviousversionsofJavaarenotsupported.

BeforeyoucanconnecttotheTeiidServerusingtheTeiidJDBCAPI,pleasedofollowingtasksfirst.

1. InstalltheTeiidServer.Seethe"AdminGuide"forinstructions.

2. BuildaVirtualDatabase(VDB).YoucanbuildaVDBwithoutaDesigner,oryoucanusetheEclipsebasedGUItoolDesigner.Checkthe"ReferenceGuide"forinstructionsonhowtobuildaVDB.IfyoudonotknowwhatVDBis,thenstartwiththisdocument.

3. DeploytheVDBintoTeiidServer.CheckAdministrator’sGuideforinstructions.

4. StarttheTeiidServer(WildFly),ifitisnotalreadyrunning.

NowthatyouhavetheVDBdeployedintheTeiidServer,clientapplicationscanconnecttotheTeiidServerandissueSQLqueriesagainstdeployedVDBusingJDBCAPI.IfyouarenewtoJDBC,seeJava’sdocumentationaboutJDBC.Teiidshipswithteiid-9.0.0.Final-jdbc.jarthatcanbefoundinthedownloads.

YoucanalsoobtaintheTeiidJDBCfromtheJBossPublicMavenRepositoryhttp://repository.jboss.org/nexus/content/groups/public/usingthecoordinates:

<dependency>

<groupId>org.jboss.teiid</groupId>

<artifactId>teiid</artifactId>

<classifier>jdbc</classifier>

<version>9.0.0.Final</version>

</dependency>

Against

MainclassesintheclientJAR:

org.teiid.jdbc.TeiidDriver-allowsJDBCconnectionsusingtheDriverManagerclass.

org.teiid.jdbc.TeiidDatasource-allowsJDBCconnectionsusingtheDataSourceXADataSourceclass.YoushouldusethisclasstocreatemanagedorXAconnections.

OnceyouhaveestablishedaconnectionwiththeTeiidServer,youcanusestandardJDBCAPIclassestointerrogatemetadataandexecutequeries.


150

http://www.jboss.org/teiiddesigner.html

http://www.jboss.org/teiid/basics/virtualdatabases.html

http://docs.oracle.com/javase/tutorial/jdbc/index.html


http://repository.jboss.org/nexus/content/groups/public/

https://docs.oracle.com/javase/7/docs/api/java/sql/DriverManager.html

https://docs.oracle.com/javase/7/docs/api/javax/sql/DataSource.html

https://docs.oracle.com/javase/7/docs/api/javax/sql/XADataSource.html

DriverConnectionUseorg.teiid.jdbc.TeiidDriverasthedriverclass.

UsethefollowingURLformatforJDBCconnections:

jdbc:teiid:<vdb-name>@mm[s]://<host>:<port>;[prop-name=prop-value;]*

NoteTheJDBCclientwillhavebothJREandservercompatibilityconsiderations.Unlessotherwisestatedaclientjarwilltypicallybeforwardandbackwardscompatiblewithonemajorversionoftheserver.Youshouldattempttokeeptheclientup-to-datethoughasfixesandfeaturesaremadeontotheclient.

URLComponents

1. <vdb-name>-NameoftheVDByouareconnectingto.OptionallyVDBnamecanalsocontainversioninformationinsideit.Forexample:"myvdb.2",thisisequivalenttosupplyingthe"version=2"connectionpropertydefinedbelow.However,useofvdbnameinthisformatandthe"version"propertyatthesametimeisnotallowed.

2. mm-definesTeiidJDBCprotocol,mmsdefinesasecurechannel(seeSSLClientConnectionsformore)

3. <host>-definestheserverwheretheTeiidServerisinstalled.IfyouareusingIPv6bindingaddressasthehostname,placeitinsquarebrackets.ex:[::1]

4. <port>-definestheportonwhichtheTeiidServerislisteningforincomingJDBCconnections.

5. [prop-name=prop-value]-additionallyyoucansupplyanynumberofnamevaluepairsseparatedbysemi-colon[;].AllsupportedURLpropertiesaredefinedintheconnectionpropertiessection.PropertyvaluesshouldbeURLencodediftheycontainreservedcharacters,e.g.(’?’,'=',';',etc.)

URLConnectionPropertiesThefollowingtableshowsallthesupportedconnectionpropertiesthatcanusedwithTeiidJDBCDriverURLconnectionstring,orontheTeiidJDBCDataSourceclass.

Table1.ConnectionProperties

PropertyName Type Description

ApplicationName StringNameoftheclientapplication;allowstheadministratortoidentifytheconnections

FetchSize intSizeoftheresultset;Thedefaultsizeif500.⇐0indicatesthatthedefaultshouldbeused.

partialResultsMode booleanEnable/disablesupportpartialresultsmode.Defaultfalse.SeethePartialResultsModesection.

autoCommitTxn String

Onlyappliesonlywhen"autoCommit"issetto"true".ThisdetermineshowaexecutedcommandneedstobetransactionallywrappedinsidetheTeiidenginetomaintainthedataintegrity.

ON-Alwayswrapcommandindistributedtransaction

OFF-Neverwrapcommandindistributedtransaction


151

DETECT(default)-Iftheexecutedcommandisspanningmorethanonesourceitautomaticallyusesdistributedtransaction.Transactionsformoreinformation.

disableLocalTxn boolean

If"true",theautoCommitsetting,commitandrollbackwillbeignoredforlocaltransactions.Defaultfalse.

user String Username

Password String Credentialforuser

ansiQuotedIdentifiers boolean

SetstheparsingbehaviorfordoublequotedentriesinSQL.Thedefault,true,parsesdobuledquotedentriesasidentifiers.Ifsettofalse,thendoublequotedvaluesthatarevalidstringliteralswillbeparsedasstringliterals.

version integer VersionnumberoftheVDB

resultSetCacheMode boolean ResultSetcachingisturnedon/off.Defaultfalse.

autoFailover boolean

Iftrue,willautomaticallyselectanewserverinstanceafteracommunicationexception.Defaultfalse.Thisistypicallynotneededwhenconnectionsaremanaged,astheconnectioncanbepurgedfromthepool.

SHOWPLAN String

(typicallynotsetasaconnectionproperty)CanbeON,OFF,DEBUG;

ONreturnsthequeryplanalongwiththeresults

DEBUGadditionallyprintsthequeryplannerdebuginformationinthelogandreturnsitwiththeresults.BoththeplanandthelogareavailablethroughJDBCAPIextensions.

DefaultOFF.

NoExec String

(typicallynotsetasaconnectionproperty)CanbeON,OFF;ONpreventsqueryexecution,butparsingandplanningwillstilloccur.DefaultOFF.

PassthroughAuthentication boolean

Onlyappliesto"local"connections.Whenthisoptionissetto"true",thenTeiidlooksforalreadyauthenticatedsecuritycontextonthecallingthread.Ifonefounditusesthatuserscredentialstocreatesession.Teiidalsoverifiesthatthesameuserisusingthisconnectionduringthelifeoftheconnection.ifitfindsadifferentsecuritycontextonthecallingthread,itswitchestheidentityontheconnection,ifthenewuserisalsoeligibletologintoTeiidotherwiseconnectionfailstoexecute.

useCallingThread boolean

Onlyappliesto"local"connections.Whenthisoptionissetto"true"(thedefault),thenthecallingthreadwillbeusedtoprocessthequery.Iffalse,thenanenginethreadwillbeused.


152

QueryTimeout integer Defaultquerytimeoutinseconds.Mustbe>=0.0indicatesnotimeout.CanbeoverridenbyStatement.setQueryTimeout.Default0.

useJDBC4ColumnNameAndLabelSemantics boolean

AchangewasmadeinJDBC4toreturnunaliasedcolumnnamesastheResultSetMetadatacolumnname.Priortothis,ifacolumnaliaswereuseditwasreturnedasthecolumnname.SettingthispropertytofalsewillenablebackwardscompatibilitywhenJDBC3andoldersupportisstillrequired.Defaultstotrue.

jaasName String

JAASconfigurationname.OnlyapplieswhenconfiguringaGSSauthentication.DefaultstoTeiid.SeetheSecurityGuideforconfigurationrequiredforGSS.

kerberosServicePrincipleName String

Kerberosauthenticatedprinciplename.OnlyapplieswhenconfiguringaGSSauthentication.SeetheSecurityGuideforconfigurationrequiredforGSS

encryptRequest boolean

Onlyappliestonon-SSLsocketconnections.When"true"therequestmessageandanyassociatepayloadwillbeencryptedusingtheconnectioncryptor.Defaultfalse.

disableResultSetFetchSize boolean

Insomesituationstoolingmaychooseundesirablefetchsizesforprocessingresults.SettotruetodisablehonoringResultSet.setFetchSize.Defaultfalse.

loginTimeout integer

Thelogintimeoutinseconds.Mustbe>=0.0indicatesnotimeout.Ifaconnectioncannotbecreatedinapproximatelythethetimeoutvalueanexceptionwillbethrown.Default0,notimeout.

reportAsViews boolean

IfDatabaseMetaDatawillreportTeiidviewsasaVIEWtabletype.IffalsethenTeiidviewswillbereportedasaTABLE.Defaulttrue.


153

DataSourceConnectionTouseadatasourcebasedconnection,useorg.teiid.jdbc.TeiidDataSourceasthedatasourceclass.TheTeiidDataSourceisalsoanXADatasource.TeiidDataSourceclassisalsoSerializable,soitpossibleforittobeusedwithJNDInamingservices.

TeiidsupportstheXAprotocol,XAtransactionswillbeextendedtoTeiidsourcesthatalsosupportXA.

Alltheproperties(exceptforversion,whichisknownonTeiidDataSourceasDatabaseVersion)definedintheDriverConnection#URLConnectionPropertieshavecorresponding"set"methodsontheorg.teiid.jdbc.TeiidDataSource.PropertiesthatareassumedfromtheURLstringhaveadditional"set"methods,whicharedescribedinthefollowingtable.

Table1.DatasourceProperties

PropertyName Type Description

DatabaseName String

Thenameofavirtualdatabase(VDB)deployedtoTeiid.OptionallyDatabasenamecanalsocontain"DatabaseVersion"informationinsideit.Forexample:"myvdb.2",thisisequivalenttosupplyingthe"DatabaseVersion"propertysettovalueof2.However,useofDatabasenameinthisformatanduseofDatabaseVersionpropertyatthesametimeisnotallowed.

ServerName String

ServerhostnamewheretheTeiidruntimeinstalled.IfyouareusingIPv6bindingaddressasthehostname,placeitinsquarebrackets.ex:[::1]

AlternateServers String

Optionaldelimitedlistofhost:portentries.SeetheUsingMultipleHostsformoreinformation.IfyouareusingIPv6bindingaddressasthehostname,placetheminsquarebrackets.ex:[::1]

AdditionalProperties String

OptionalsettingofpropertiesthathasthesameformatasthepropertystringinaconnectionURL.

PortNumber integerPortnumberonwhichtheServerprocessislisteningon.

secure boolean

Secureconnection.FlagtoindicatetouseSSL(mms)basedconnectionbetweenclientandserver

DatabaseVersion integer VDBversion

DataSourceName String Namegiventothisdatasource

LoadBalance boolean

Settofalsetodisablethedefaultloadbalancingbehaviorofselectinganewserverwhenapooledconnectionisreturnedtothepool.


154

NoteAddtionalProperties-AllthepropertiesfromURLConnectionPropertiescanbeusedonDataSourceusingtheAdditionalPropertiessettermethodifthecorrespondingsettermethodisnotalreadyavailable.Forexample,youcanadd"useCallingThread"propertyas<xa-datasource-propertyname="AdditionalProperties">useCallingThread=false</xa-datasource-property>


155

StandaloneApplicationTouseeitherDriverorDataSourcebasedconnections,addtheclientJARtoyourJavaclientapplication’sclasspath.SeethesimpleclientexampleinthekitforafullJavasampleofthefollowing.

DriverConnection

SampleCode:

publicclassTeiidClient{

publicConnectiongetConnection(Stringuser,Stringpassword)throwsException{

Stringurl="jdbc:teiid:myVDB@mm://localhost:31000;ApplicationName=myApp";

returnDriverManager.getConnection(url,user,password);

}

}

DatasourceConnection

SampleCode:

publicclassTeiidClient{

publicConnectiongetConnection(Stringuser,Stringpassword)throwsException{

TeiidDataSourceds=newTeiidDataSource();

ds.setUser(user);

ds.setPassword(password);

ds.setServerName("localhost");

ds.setPortNumber(31000);

ds.setDatabaseName("myVDB");

returnds.getConnection();

}

}


156

WildFlyDataSourceTeiidcanbeconfiguredasaJDBCdatasourceinaWildFlyServertobeaccessedfromJNDIorinjectedintoyourJEEapplications.DeployingTeiidasdatasourceinWildFlyisexactlysameasdeployinganyotherRDBMSresourceslikeOracleorDB2.

DefiningasdatasourceisnotlimitedtoWildFly,youcanalsodeployasdatasourceinGlassfish,Tomcat,Websphere,Weblogicetcservers,howevertheirconfigurationfilesaredifferentthanWildFly.Consulttherespectivedocumentationoftheenvironmentinwhichyouaredeploying.

AspecialcaseexistsiftheTeiidinstanceyouareconnectingtoisinthesameVMastheWildFlyinstance.Ifthatmatchesyoudeployment,thenfollowtheLocalJDBCConnectioninstructions

InstallationSteps

1. IfyouareworkingwithanASinstancethatalreadyhasTeiidinstalledthenrequiredmodule/jarfilesarealreadyinstalled.IftheASinstancedoesnothaveTeiidinstalled,thenyoushouldcreateamodulefortheclientjar.Underthepathmodule/org/jboss/teiid/clientaddtheclientjarandamodule.xmldefinedas:

SampleTeiidClientModule

<modulexmlns="urn:jboss:module:1.1"name="org.jboss.teiid.client">

<resources>

<resource-rootpath="teiid-{version}-jdbc.jar"/>

</resources>

<dependencies>


<modulename="javax.transaction.api"/>

</dependencies>

</module>

Note PriortoTeiid8.12.3amoduledependencyonsun.jdkwasalsorequired.

1. UsetheCLIoreditthestandalone-teiid.xmlordomain-teiid.xmlfileandaddadatasourceintothe"datasources"subsystem.

Basedonthetypeofdeployment(XA,driver,orlocal),thecontentsofthiswillbedifferent.Seethefollowingsectionsformore.ThedatasourcewillthenbeaccessiblethroughtheJNDInamespecifiedinthebelowconfiguration.

DataSourceConnection

MakesureyouknowthecorrectDatabaseName,ServerName,Portnumberandcredentialsthatarespecifictoyourdeploymentenvironment.

SampleXADataSourceintheWildFlyusingtheTeiidDataSourceclassorg.teiid.jdbc.TeiidDataSource

<datasources>

<xa-datasourcejndi-name="java:/teiidDS"pool-name="teiidDS"enabled="true"use-java-context="true"use

-ccm="true">

<xa-datasource-propertyname="PortNumber">31000</xa-datasource-property>

<xa-datasource-propertyname="DatabaseName">{db-name}</xa-datasource-property>

<xa-datasource-propertyname="ServerName">{host}</xa-datasource-property>

<driver>teiid</driver>

<xa-pool>

<min-pool-size>10</min-pool-size>


157

<max-pool-size>20</max-pool-size>

<is-same-rm-override>true</is-same-rm-override>

<prefill>false</prefill>

<use-strict-min>false</use-strict-min>

<flush-strategy>FailingConnectionOnly</flush-strategy>

<no-tx-separate-pools/>

</xa-pool>

<security>

<user-name>{user}</user-name>

<password>{password}</password>

</security>

</xa-datasource>

<drivers>

<drivername="teiid"module="org.jboss.teiid.client">

<driver-class>org.teiid.jdbc.TeiidDriver</driver-class>

<xa-datasource-class>org.teiid.jdbc.TeiidDataSource</xa-datasource-class>

</driver>

</drivers>

</datasources>

DriverbasedconnectionYoucanalsouseTeiid’sJDBCdriverclassorg.teiid.jdbc.TeiidDrivertocreateadatasource

<datasources>

<datasourcejndi-name="java:/teiidDS"pool-name="teiidDS">

<connection-url>jdbc:teiid:{vdb}@mm://{host}:31000</connection-url>


<pool>




</pool>

<security>



</security>

</datasource>

<drivers>




</driver>

</drivers>

</datasources>

LocalJDBCConnectionIfyouaredeployingyourclientapplicationonthesameWildFlyinstanceastheTeiidruntimeisinstalled,thenyouwillwanttoconfiguretheconnectiontoby-passmakingasocketbasedJDBCconnection.Byusingaslightlydifferentdatasourceconfigurationtomakea"local"connection,theJDBCAPIwilllookupalocalTeiidruntimeinthesameVM.

WarningSinceDataSourcesstartbeforeTeiidVDBsaredeployed,leavetheminpoolsizeof0forlocalconnections.OtherwiseerrorsmayoccuronthestartupoftheTeiidDataSource.AlsonotethatlocalconnectionsspecifyingaVDBversionwillwaitfortheirVDBtobeloadedbeforeallowingaconnection.

WarningDonotincludeanyadditionalcopyofTeiidjarsintheapplicationclassloadthatisutilizingthelocalconnection.Eveniftheexactsameversionoftheclientjarisincludedinyourapplicationclassloader,youwillfailtoconnecttothelocalconnectionwithaclasscastexception.


158

NoteBydefaultlocalconnectionsusetheircallingthreadtoperformprocessingoperationsratherthanusinganenginethreadwhilethecallingthreadisblocked.TodisablethisbehaviorsettheconnectionpropertyuseCallingThreads=false.Thedefaultistrue,andisrecommendedintransactionalqueries.

Note LocalconnectionsthatspecifyaVDBversionwillwaitfortheVDBloadtofinishbeforeallowingtheconnectiontocontinue.

Localdatasource

<datasources>


<connection-url>jdbc:teiid:{vdb}</connection-url>

<driver>teiid-local</driver>

<pool>




</pool>

<security>



</security>

</datasource>

<drivers>

<drivername="teiid-local"module="org.jboss.teiid">



</driver>

</drivers>

</datasources>

ThisisessentiallythesameastheXAconfiguration,but"ServerName"and"PortNumber"arenotspecified.LocalconnectionshaveadditionalfeaturessuchasusingPassthroughAuthentication


159

UsingMultipleHostsAgroupofTeiidServersinthesameWildFlyclustermaybeconnectedusingfailoverandload-balancingfeatures.Toenablethesesfeaturesintheirsimplestform,theclientneedstospecifymultiplehostnameandportnumbercombinationsontheURLconnectionstring.

ExampleURLconnectionstring

jdbc:teiid:<vdb-name>@mm://host1:31000,host1:31001,host2:31000;version=2

IfyouareusingaDataSourcetoconnecttoTeiidServer,usethe"AlternateServers"property/methodtodefinethefailoverservers.Theformatisalsoacommaseparatedlistofhost:portcombinations.

TheclientwillrandomlypickonetheTeiidserverfromthelistandestablishasessionwiththatserver.Ifthatservercannotbecontacted,thenaconnectionwillbeattemptedtoeachoftheremainingserversinrandomorder.Thisallowsforbothconnectiontimefail-overandrandomserverselectionloadbalancing.

FailOver

Postconnectionfailoverwillbeused,iftheautoFailoverconnectionpropertyonJDBCURLissettotrue.Postconnectionfailoverworksbysendingaping,atmosteverysecond,totesttheconnectionpriortouse.Ifthepingfails,anewinstancewillbeselectedpriortotheoperationbeingattempted.Thisisnottrue"transparentapplicationfailover"astheclientwillnotrestartthetransaction/query/recreatesessionscopedtemptables,etc.Sothisfeatureshouldbeusedwithcaution.

LoadBalancing

Postconnectionloadbalancingcanbeutilizedinoneoftwoways.FirstifyouareusingTeiidDataSourceandtheConnectionsreturnedbyTeiidPooledConnectionshavetheirclosemethodcalled,thenanewserverinstancewillbeselectedautomatically.HoweverwhenusingdriverbasedconnectionsorevenwhenusingTeiidDataSourceinaconnectionpool(suchasWildFly),theautomaticloadbalancingwillnothappen.Secondyoucanexplicitlytriggerloadbalancingthroughtheuseofthesetstatement:

SETNEWINSTANCETRUE

Typicallyyouwillnotneedwanttoissuethisstatementmanually,butinsteaduseitastheconnectiontestqueryonyourDataSourceconfiguration.

WildFlyDataSourceWithPostConnectionLoadBalancing

<datasources>


<connection-url>jdbc:teiid:{vdb}@mm://{host}:31000</connection-url>


<pool>




<check-valid-connection-sql>SETNEWINSTANCETRUE</check-valid-connection-sql>

</pool>

<security>



</security>


160

</datasource>

<drivers>




</driver>

</drivers>

</datasources>

Teiidbydefaultmaintiansapoolofextrasocketconnectionsthatarereused.Forloadbalancing,thisreducesthepotentialcostofswitchingaconnectiontoanotherserverinstance.Thedefaultsettingistomaintain16connections(canbesetviaorg.teiid.sockets.maxCachedInstancesinateiid-client-settings.propertiesfile).Ifyou’reclientisconnectingtolargenumbersofTeiidinstancesandyou’reusingpostconnectiontimeloadbalancing,thenconsiderincreasingthenumberofcachedinstances.Youmayeithersetananalogoussystempropertyorcreateateiid-client-settings.properties(seetheteiid-client-settings.orig.propertiesfileintheclientjar)fileandplaceitintotheclasspathaheadoftheclientjar.

Note

Sessionleveltemporarytables,currentlyrunningtransactions,sessionlevelcacheentries,andPreparedPlansforagivensessionwillnotbeavailableonotherclustermembers.Therefore,itisrecommendedthatpostconnectiontimeloadbalancingisonlyusedwhenthelogicalconnectioncouldhavebeenclosed,buttheactualconnectionisreused(thetypicalconnectionpoolpattern).

AdvancedConfigurationServerdiscovery,loadbalancing,failover,retry,retrydelay,etc.maybecustomizeifthedefaultpolicyisnotsufficient.Seetheorg.teiid.net.socket.ServerDiscoveryinterfaceanddefaultimplementaionorg.teiid.net.socket.UrlServerDiscoveryforhowtostartwithyourcustomization.TheUrlServerDiscoveryimplemenationprovidesthefollowing:discoveryofserversfromtheURLhosts(DataSourceserver/alternativeServers),randomselectionforloadbalancingandfailover,1connectionattemptperhost,nobiasing,blacklisting,orotheradvancedfeatures.Typicallyyou’llwanttoextendtheUrlServerDiscoverysothatitcanbeusedasthefallbackstrategyandtoonlyimplementthenecessarychangedmethods.It’simportanttoconsiderthat1ServerDiscoveryinstancewillbecreatedforeachconnection.Anysharingofinformationbetweeninstancesshouldbedonethroughstaticstateorsomeothersharedlookup.

YourcustomizedserverdiscoveryclasswillthenneedtobereferencedbythediscoveryStategyconnection/DataSourcepropertybyitsfullclassname.

Youmayalsochoosetouseanexternaltcploadbalancer,suchashaproxy.TheTeiiddriver/DataSourceshouldthentypicallybeconfiguredtojustusethesinglehost/portofyourloadbalancer.


161

http://haproxy.1wt.eu/

ClientSSLSettings

ThefollowingsectionsdefinethepropertiesrequiredforeachSSLmode.NotethatwhenconnectingtoTeiidServerwithSSLenabled,youMUSTusethe"mms"protocol,insteadof"mm"intheJDBCconnectionURL,forexample

Note AnonymousSSLmodeisnotsupportedforsomeJREs,seetheTeiidServerTransportSecurityforalternatives.

jdbc:teiid:<myVdb>@mms://<host>:<port>

Therearetwodifferentsetsofpropertiesthataclientcanconfiguretoenable1-wayor2-waySSL.SeealsotheTeiidServerTransportSecuritychapterifyouareresponsibleforconfiguringtheserveraswell.

Option1:JavaSSLproperties

ThesearestandardJavadefinedsystempropertiestoconfiguretheSSLunderanyJVM,TeiidisnotuniqueinitsuseofSSL.ProvidethefollowingsystempropertiestotheclientVMprocess.

1-waySSL

-Djavax.net.ssl.trustStore=<dir>/server.truststore(required)

-Djavax.net.ssl.trustStorePassword=<password>(optional)

-Djavax.net.ssl.keyStoreType(optional)

2-waySSL

-Djavax.net.ssl.keyStore=<dir>/client.keystore(required)

-Djavax.net.ssl.keyStrorePassword=<password>(optional)

-Djavax.net.ssl.trustStore=<dir>/server.truststore(required)

-Djavax.net.ssl.trustStorePassword=<password>(optioanl)

-Djavax.net.ssl.keyStroreType=<keystoretype>(optional)

Option2:TeiidSpecificProperties

Usethisoptionwhentheabove"javax"basedpropertiesarealreadyinusebythehostprocess.ForexampleifyourclientapplicationisaTomcatprocessthatisconfiguredforhttpsprotocolandtheaboveJavabasedpropertiesarealreadyinuse,andimportingTeiid-specificcertificatekeysintothosehttpscertificatekeystoresisnotallowed.

Inthisscenario,adifferentsetofTeiid-specificSSLpropertiescanbesetassystempropertiesordefinedinsidethea"teiid-client-settings.properties"file.Asample"teiid-client-settings.properties"filecanbefoundinsidethe"teiid-<version>-client.jar"fileattherootcalled"teiid-client-settings.orig.properties".Extractthisfile,makeacopy,changethepropertyvaluesrequiredforthechosenSSLmode,andplacethisfileintheclientapplication’sclasspathbeforethe"teiid-<version>-client.jar"file.

SSLpropertiesanddefinitionsthatcanbesetina"teiid-client-settings.properties"fileareshownbelow.

########################################

#SSLSettings

########################################

#

#Thekeystoretype.DefaultstoJKS

#

org.teiid.ssl.keyStoreType=JKS

#

#Thekeystorealgorithm,defaultsto


162

link:../security/Teiid_Server_Transport_Security.adoc

#thesystemproperty"ssl.TrustManagerFactory.algorithm"

#

#org.teiid.ssl.algorithm=

#

#Theclasspathorfilesystemlocationofthe

#keystore.

#

#Thispropertyisrequiredonlyifperforming2-way

#authenticationthatrequiresaspecificprivate

#key.

#

#org.teiid.ssl.keyStore=

#

#Thekeystorepassword(notrequired)

#

#org.teiid.ssl.keyStorePassword=

#

#Thekeyalias(notrequired,ifgivennamedcertificateisused)

#

#org.teiid.ssl.keyAlias=

#

#Thekeypassword(notrequired,usedifthekeypasswordisdifferentthanthekeystorepassword)

#

#org.teiid.ssl.keyPassword=

#

#Theclasspathorfilesystemlocationofthe

#truststore.

#

#Thispropertyisrequiredifperforming1-way

#authenticationthatrequirestrustnotprovided

#bythesystemdefaults.

#

#org.teiid.ssl.trustStore=

#

#Thetruststorepassword(notrequired)

#

#org.teiid.ssl.trustStorePassword=

#

#Thecipherprotocol,defaultstoTLSv3

#

org.teiid.ssl.protocol=TLSv1

#

#WhethertoallowanonymousSSL

#(theTLS_DH_anon_WITH_AES_128_CBC_SHAciphersuite)

#defaultstotrue

#

org.teiid.ssl.allowAnon=true

##Whethertoallowtrustallservercertificates#defaultstofalse#

#org.teiid.ssl.trustAll=false


163

##Whethertocheckforexpiredservercertificates(noaffectinanonymousmodeorwithtrustAll=true)#defaultstofalse#

#org.teiid.ssl.checkExpired=false

1-waySSL

org.teiid.ssl.trustStore=<dir>/server.truststore(required)

2-waySSL

org.teiid.ssl.keyStore=<dir>/client.keystore(required)

org.teiid.ssl.trustStore=<dir>/server.truststore(required)


164

AdditionalSocketClientSettingsA"teiid-client-settings.properties"filecanbeusedtoconfigureTeiidlowlevelandSSLsocketconnectionproperties.Currentlyonlyasinglepropertiesfileisexpectedperdriver/classloadercombination.Asample"teiid-client-settings.properties"filecanbefoundinsidethe"teiid-<version>-client.jar"fileattherootcalled"teiid-client-settings.orig.properties".Tocustomizethesettings,extractthisfile,makeacopy,changethepropertyvaluesaccordingly,andplacethisfileintheclientapplication’sclasspathbeforethe"teiid-<version>-client.jar"file.Typicallyclientswillnotneedtoadjustthenon-SSLproperties.Forreferencethepropertiesare:

########################################

#MiscSocketConfiguration

########################################

#

#Thetimeinmillisecondsforsockettimeouts.

#Timeoutsduringtheinitialization,handshake,or

#aserverpingmaybetreatedasanerror.

#

#Thisisthelowerboundforallothertimeouts

#theJDBClogintimeout.

#

#Typicallythisshouldbeleftatthedefaultof1000

#(1second).Settingthisvaluetoolowmaycauseread

#errors.

#

org.teiid.sockets.soTimeout=1000

#

#Themaxnumberofcachedserverinstances

#toreuse.Aserverinstanceisaconnected

#sockettoaparticularclustermemberwith

#clientencryptionandorSSLalreadyestablished.

#

#Cachinginstanceshelpsin2circumstances:

#-whenConnectionpoolingisnotbeingused.

#-load-balancingperformancetoacluster

#whenusingConnectionpoolingoftheDataSource.

#

#Thisvalueshouldtypicallybeamultipleofthe

#clustersize.

#

#Setto0todisableinstancecaching.

#

org.teiid.sockets.maxCachedInstances=16

#

#Setthemaxtimetolive(inmilliseconds)fornon-execution

#synchronouscalls.

#

org.teiid.sockets.synchronousttl=240000

#

#Setthesocketreceivebuffersize(inbytes)

#0indicatesthatthedefaultsocketsettingwillbeused.

#

org.teiid.sockets.receiveBufferSize=0

#

#Setthesocketsendbuffersize(inbytes)


165

#0indicatesthatthedefaultsocketsettingwillbeused.

#

org.teiid.sockets.sendBufferSize=0

#

#SettotruetoenableNagle'salgorithmtoconservebandwidth

#byminimizingthenumberofsegmentsthataresent.

#

org.teiid.sockets.conserveBandwidth=false

#

#Maximumnumberofbytesperservermessage.

#Mayneedtobeincreasedwhenusingcustomtypesand/orlargebatchsizes.

#

org.teiid.sockets.maxObjectSize=33554432

#

#Settotruetodisableclientping.

#Defaultvalueis'false'thatmeansclientpingisenable.Theclientpingkeepstherelevantserverfromter

minatingsessions.

#Ifthedefaultloadbalancingstrategyisused,thenclientpingisnecessary.

#

org.teiid.sockets.DisablePing=false

Note Allpropertieslistedin"teiid-client-settings.properties"canalsobesetasSystemproperties.


166

PreparedStatementsTeiidprovidesastandardimplementationofjava.sql.PreparedStatement.PreparedStatementscanbeveryimportantinspeedingupcommonstatementexecution,sincetheyallowtheservertoskipparsing,resolving,andplanningofthestatement.SeetheJavadocumentationformoreinformationonPreparedStatementusage.

PreparedStatementConsiderations

ItisnotnecessarytopoolclientsideTeiidPreparedStatements,sinceTeiidperformsplancachingontheserverside.

Thenumberofcachedplansisconfigurable(seetheAdminGuide),andarepurgedbytheleastrecentlyused(LRU).

Cachedplansarenotdistributedthroughacluster.Anewplanmustbecreatedforeachclustermember.

PlansarecachedfortheentireVDBorforjustaparticularsession.Thescopeofaplanisdetectedautomaticallybaseduponthefunctionsevaluatedduringit’splanningprocess.

StoredproceduresexecutedthroughaCallableStatementhavetheirplanscachedjustasaPreparedStatement.

Bindvariabletypesinfunctionsignatures,e.g."wheret.col=abs(?)"canbedeterminedifthefunctionhasonlyonesignatureorifthefunctionisusedinapredicatewherethereturntypecanbedetermined.Inmorecomplexsituationsitmaybenecessarytoaddatypehintwithacastorconvert,e.g.upper(convert(?,string)).

PreparedStatements

167

http://download.oracle.com/javase/6/docs/technotes/guides/jdbc/getstart/preparedstatement.html#1000039

ResultSetLimitationsTYPE_SCROLL_SENSITIVEisnotsupported.

UPDATABLEResultSetsarenotsupported.

ReturningmultipleResultSetsfromProcedureexecutionisnotsupported.

ResultSetLimitations

168

JDBCExtensionsThesearecustomextensionstoJDBCAPIfromTeiidtosupportvariousfeatures.

JDBCExtensions

169

StatementExtensionsTheTeiidstatementextensioninterface,org.teiid.jdbc.TeiidStatement,providesfunctionalitybeyondtheJDBCstandard.Tousetheextensioninterface,simplycastorunwapthestatementreturnedbytheConnection.Thefollowingmethodsareprovidedontheextensioninterface:


MethodName Description

getAnnotations

GetthequeryengineannotationsifthestatementwaslastexecutedwithSHOWPLANON/DEBUG.Eachorg.teiid.client.plan.Annotationcontainsadescription,acategory,aseverity,andpossiblyaresolutionofnotesrecordedduringqueryplanningthatcanbeusedtounderstandchoicesmadebythequeryplanner.

getDebugLogGetthedebuglogifthestatementwaslastexecutedwithSHOWPLANDEBUG.

getExecutionPropertyGetthecurrentvalueofanexecutionpropertyonthisstatementobject.

getPlanDescription

GetthequeryplandescriptionifthestatementwaslastexecutedwithSHOWPLANON/DEBUG.Theplanisatreemadeupoforg.teiid.client.plan.PlanNodeobjects.TypicallyPlanNode.toString()orPlanNode.toXml()willbeusedtoconverttheplanintoatextualform.

getRequestIdentifier

Getanidentifierforthelastcommandexecutedonthisstatement.Ifnocommandhasbeenexecutedyet,nullisreturned.

setExecutionProperty

Settheexecutionpropertyonthisstatement.SeetheExecutionPropertiessectionformoreinformation.ItisgenerallypreferabletousetheSETStatementunlesstheexecutionpropertyappliesonlytothestatementbeingexecuted.

setPayload

Setaper-commandpayloadtopasstotranslators.Currentlytheonlybuilt-inuseisforsendinghintsforOracledatasource.

JDBCExtensions

170

PartialResultsModeTheTeiidServersupportsa"partialresults"querymode.Thismodechangesthebehaviorofthequeryprocessorsotheserverreturnsresultsevenwhensomedatasourcesareunavailable.

Forexample,supposethattwodatasourcesexistfordifferentsuppliersandyourdataDesignershavecreatedavirtualgroupthatcreatesaunionbetweentheinformationfromthetwosuppliers.Ifyourapplicationsubmitsaquerywithoutusingpartialresultsquerymodeandoneofthesuppliers’databasesisdown,thequeryagainstthevirtualgroupreturnsanexception.However,ifyourapplicationrunsthesamequeryin"partialresults"querymode,theserverreturnsdatafromtherunningdatasourceandnodatafromthedatasourcethatisdown.

Whenusing"partialresults"mode,ifasourcethrowsanexceptionduringprocessingitdoesnotcausetheuser’squerytofail.Rather,thatsourceistreatedasreturningnomorerowsafterthefailurepoint.Mostcommonly,thatsourcewillreturn0rows.

ThisbehaviorismostusefulwhenusingUNIONorOUTERJOINqueriesastheseoperationshandlemissinginformationinausefulway.Mostotherkindsofquerieswillsimplyreturn0rowstotheuserwhenusedinpartialresultsmodeandthesourceisunavailable.

Foreachsourcethatisexcludedfromthequery,awarningwillbegenerateddescribingthesourceandthefailure.ThesewarningscanbeobtainedfromtheStatement.getWarnings()method.ThismethodreturnsaSQLWarningobjectbutinthecaseof"partialresults"warnings,thiswillbeanobjectoftypeorg.teiid.jdbc.PartialResultsWarningclass.Thisclasscanbeusedtoobtainalistofallthefailedsourcesbynameandtoobtainthespecificexceptionthrownbyeachresourceadaptor.

Note

SinceTeiidsupportscursoringbeforetheentireresultisformed,itispossiblethatadatasourcefailurewillnotbedetermineduntilafterthefirstbatchofresultshavebeenreturnedtotheclient.Thiscanhappeninthecaseofunions,butnotjoins.Toensurethatallwarningshavebeenaccumulated,thestatementshouldbecheckedaftertheentireresultsethasbeenread.

Note Ifotherwarningsarereturnedbyexecution,thenthepartialresultswarningsmayoccurafterthefirstwarninginthewarningchain.

PartialresultsmodeisoffbydefaultbutcanbeturnedonforallqueriesinaConnectionwitheithersetPartialResultsMode("true")onaDataSourceorpartialResultsMode=trueonaJDBCURL.Ineithercase,partialresultsmodemaybetoggledlaterwithaSETStatement.

SettingPartialResultsMode

Statementstatement=...obtainstatementfromConnection...

statement.execute("setpartialResultsModetrue");

GettingPartialResultsWarnings

statement.execute("setpartialResultsModetrue");

ResultSetresults=statement.executeQuery("SELECTNameFROMAccounts");

while(results.next()){

...//processtheresultset

}

SQLWarningwarning=statement.getWarnings();

while(warning!=null){

if(warninginstanceofPartialResultsWarning){

PartialResultsWarningpartialWarning=(PartialResultsWarning)warning;

CollectionfailedConnectors=partialWarning.getFailedConnectors();

Iteratoriter=failedConnectors.iterator();

while(iter.hasNext()){

StringconnectorName=(String)iter.next();

SQLExceptionconnectorException=partialWarning.getConnectorException(connectorName);

System.out.println(connectorName+":"+connectorException.getMessage());

}

JDBCExtensions

171

}

warning=warning.getNextWarning();

}

Warning

Insomeinstances,typicallyJDBCsources,thesourcenotbeinginitiallyavailablewillpreventTeiidfromautomaticallydeterminingtheappropriatesetofsourcecapabilities.Ifyougetanexceptionindicatingthatthecapabilitiesforanunavailablesourcearenotvalidinpartialresultsmode,thenitmaybenecessarytomanuallysetthedatabaseversionorsimilarpropertyonthetranslatortoensurethatthecapabilitiesareknownevenifthesourceisnotavailable.

JDBCExtensions

172

blockingStatementExecutionJDBCqueryexecutioncanindefinitelyblockthecallingthreadwhenastatementisexecutedoraresultsetisbeingiterated.Insomesituationsyoumaynotwishtohaveyourcallingthreadsheldintheseblockedstates.Whenusingembedded/localconnections,youmayoptionallyusetheorg.teiid.jdbc.TeiidStatementandorg.teiid.jdbc.TeiidPreparedStatementinterfacestoexecutequerieswithacallbackorg.teiid.jdbc.StatementCallbackthatwillbenotifiedofstatementevents,suchasanavailablerow,anexception,orcompletion.Yourcallingthreadwillbefreetoperformotherwork.Thecallbackwillbeexecutedbyanengineprocessingthreadasneeded.Ifyourresultsprocessingisitselfblockingandyouwantqueryprocessingtobeconcurrentwithresultsprocessing,thenyourcallbackshouldimplementonRowhandlinginamulti-threadedmannertoallowtheenginethreadtocontinue.

Non-blockingPreparedStatementExecution

PreparedStatemntstmt=connection.preparedStatement(sql);

TeiidPreparedStatementtStmt=stmt.unwrap(TeiidPreparedStatement.class);

tStmt.submitExecute(newStatementCallback(){

@Override

publicvoidonRow(Statements,ResultSetrs){

//anylogicthataccessesthecurrentrow...

System.out.println(rs.getString(1));

}

@Override

publicvoidonException(Statements,Exceptione)throwsException{

s.close();

}

@Override

publicvoidonComplete(Statements)throwsException{

s.close();

},newRequestOptions()

});

Thenon-blockinglogicislimitedtostatementexecutiononly.OtherJDBCoperations,suchasconnectioncreationorbatchedexecutionsdonotyethavenon-blockingoptions.

IfyouaccessforwardpositionsintheonRowmethod(callingnext,isLast,isAfterLast,absolute),theymaynotyetbevalidandaorg.teiid.jdbc.AsynchPositioningExceptionwillbethrown.ThatexceptionisrecoverableifcaughtorcanbeavoidedbycallingTeiidResultSet.available()todetermineifyourdesiredpositioningwillbevalid.

ContinuousExecution

TheRequestOptionsobjectmaybeusedtospecifyaspecialtypeofcontinuousasynchexecutionviathecontinuousorsetContinuousmethods.Incontinuousmodethestatementwillbecontinuouslyre-executed.Thisisintendedforconsumingreal-timeorotherdatastreamsprocessedthroughaSQLplan.Acontinuousquerywillonlyterminateonanerrororwhenthestatementisexplicitlyclosed.TheSQLforacontinuousqueryisnodifferentthananyotherstatement.Careshouldbetakentoensurethatretrievalsfromnon-continuoussourcesisappropriatelycachedforreuse,suchasbyusingmaterializedviewsorsessionscopedtemptables.

Acontinuousquerymustdothefollowing:

returnaresultset

beexecutedwithaforward-onlyresultset

cannotbeusedinthescopeofatransaction

JDBCExtensions

173

Sinceresourceconsumptionisexpectedtobedifferentinacontinuousplan,itdoesnotcountagainsttheservermaxactiveplanlimit.Typicallycustomsourceswillbeusedtoprovidedatastreams.SeetheDeveloper’sGuide,inparticularthesectiononReusableExecutionsformore.

Whentheclientwishestoendthecontinuousquery,theStatement.close()orStatement.cancel()methodshouldbecalled.Typicallyyourcallbackwillclosewheneveritnolongneedstoprocessresults.

SeealsotheContinuousStatementCallbackforuseastheStatementCallbackforadditionalmethodsrelatedtocontinuousprocessing.

JDBCExtensions

174

ResultSetExtensionsTheTeiidresultsetextensioninterface,org.teiid.jdbc.TeiidResultSet,providesfunctionalitybeyondtheJDBCstandard.Tousetheextensioninterface,simplycastorunwaparesultsetreturnedbyaTeiidstatement.Thefollowingmethodsareprovidedontheextensioninterface:


MethodName Description

available

Returnsanestimateoftheminimumnumberofrowsthatcanberead(afterthecurrent)withoutblockingortheendoftheResultSetisreached.

JDBCExtensions

175

ConnectionExtensionsTeiidconnections(definedbytheorg.teiid.jdbc.TeiidConnectioninterface)supportthechangeUsermethodtoreauthenticateagivenconnection.Ifthereauthenticationissuccessfulthecurrentconnectionmybeusedwiththegivenidentity.Existingstatements/resultsetsarestillavailableforuseundertheoldidentity.SeetheJBossASissueJBAS-1429formoreonusingreauthenticationsupportwithJCA.

JDBCExtensions

176

https://issues.jboss.org/browse/JBAS-1429

UnsupportedJDBCMethodsBasedupontheJDBCinJDK1.6,thisappendixdetailsonlythoseJDBCmethodsthatTeiiddoesnotsupport.Unlessspecifiedbelow,TeiidsupportsallotherJDBCMethods.

ThosemethodslistedwithoutcommentsthrowaSQLExceptionstatingthatitisnotsupported.

Wherespecified,somelistedmethodsdonotthrowanexception,butpossiblyexhibitunexpectedbehavior.Ifnoargumentsarespecified,thenallrelated(overridden)methodsarenotsupported.Ifanargumentislistedthenonlythoseformsofthemethodspecifiedarenotsupported.


177

UnsupportedClassesandMethodsin"java.sql"

Classname Methods

Blob

[source,java]----getBinaryStream(long,long)-throwsSQLFeatureNotSupportedExceptionsetBinaryStream(long)--throwsSQLFeatureNotSupportedExceptionsetBytes--throwsSQLFeatureNotSupportedExceptiontruncate(long)-throwsSQLFeatureNotSupportedException----

CallableStatement

[source,java]----getObject(intparameterIndex,Map<String,Class<?>>map)-throwsSQLFeatureNotSupportedExceptiongetRef-throwsSQLFeatureNotSupportedExceptiongetRowId-throwsSQLFeatureNotSupportedExceptiongetURL(StringparameterName)-throwsSQLFeatureNotSupportedExceptionregisterOutParameter-ignoresregisterOutParameter(StringparameterName,*)-throwsSQLFeatureNotSupportedExceptionsetRowId(StringparameterName,RowIdx)-throwsSQLFeatureNotSupportedExceptionsetURL(StringparameterName,URLval)-throwsSQLFeatureNotSupportedException----

Clob

[source,java]----getCharacterStream(longarg0,longarg1)-throwsSQLFeatureNotSupportedExceptionsetAsciiStream(longarg0)-throwsSQLFeatureNotSupportedExceptionsetCharacterStream(longarg0)-throwsSQLFeatureNotSupportedExceptionsetString-throwsSQLFeatureNotSupportedExceptiontruncate-throwsSQLFeatureNotSupportedException----

Connection

[source,java]----createBlob-throwsSQLFeatureNotSupportedExceptioncreateClob-throwsSQLFeatureNotSupportedExceptioncreateNClob-throwsSQLFeatureNotSupportedExceptioncreateSQLXML-throwsSQLFeatureNotSupportedExceptioncreateStruct(StringtypeName,Object[]attributes)-throwsSQLFeatureNotSupportedExceptiongetClientInfo-throwsSQLFeatureNotSupportedExceptionreleaseSavepoint-throwsSQLFeatureNotSupportedExceptionrollback(Savepointsavepoint)-throwsSQLFeatureNotSupportedExceptionsetHoldability-throwsSQLFeatureNotSupportedExceptionsetSavepoint-throwsSQLFeatureNotSupportedExceptionsetTypeMap-throwsSQLFeatureNotSupportedExceptionsetRealOnly-effectivelyignored----

DatabaseMetaData

[source,java]----getAttributes-throwsSQLFeatureNotSupportedExceptiongetClientInfoProperties-throwsSQLFeatureNotSupportedExceptiongetRowIdLifetime-throwsSQLFeatureNotSupportedException----

NClob NotSupported

PreparedStatement

[source,java]----setRef-throwsSQLFeatureNotSupportedExceptionsetRowId-throwsSQLFeatureNotSupportedExceptionsetUnicodeStream-


178

throwsSQLFeatureNotSupportedException----

Ref NotImplemented

ResultSet

[source,java]----deleteRow-throwsSQLFeatureNotSupportedExceptiongetHoldability-throwsSQLFeatureNotSupportedExceptiongetObject(,Map<String,Class<?>>map)-throwsSQLFeatureNotSupportedExceptiongetRef-throwsSQLFeatureNotSupportedExceptiongetRowId-throwsSQLFeatureNotSupportedExceptiongetUnicodeStream-throwsSQLFeatureNotSupportedExceptiongetURL-throwsSQLFeatureNotSupportedExceptioninsertRow-throwsSQLFeatureNotSupportedExceptionmoveToInsertRow-throwsSQLFeatureNotSupportedExceptionrefreshRow-throwsSQLFeatureNotSupportedExceptionrowDeleted-throwsSQLFeatureNotSupportedExceptionrowInserted-throwsSQLFeatureNotSupportedExceptionrowUpdated-throwsSQLFeatureNotSupportedExceptionsetFetchDirection-throwsSQLFeatureNotSupportedExceptionupdate-throwsSQLFeatureNotSupportedException----

RowId NotSupported

Savepoint notSupported

SQLData NotSupported

SQLInput notSupported

SQLOutput NotSupported


179

UnsupportedClassesandMethodsin"javax.sql"

Classname Methods

RowSet* NotSupported


180

ODataSupport

WhatisOData

TheOpenDataProtocol(OData)isaWebprotocolforqueryingandupdatingdatathatprovidesawaytounlockyourdataandfreeitfromsilosthatexistinapplicationstoday.ODatadoesthisbyapplyingandbuildinguponWebtechnologiessuchasHTTP,AtomPublishingProtocol(AtomPub)andJSONtoprovideaccesstoinformationfromavarietyofapplications,services,andstores.TheprotocolemergedfromexperiencesimplementingAtomPubclientsandserversinavarietyofproductsoverthepastseveralyears.ODataisusedtoexposeandaccessinformationfromavarietyofsourcesincluding,butnotlimitedto,relationaldatabases,filesystems,contentmanagementsystemsandtraditionalWebsites.

ODataisconsistentwiththewaytheWebworks-itmakesadeepcommitmenttoURIsforresourceidentificationandcommitstoanHTTP-based,uniforminterfaceforinteractingwiththoseresources(justliketheWeb).ThiscommitmenttocoreWebprinciplesallowsODatatoenableanewlevelofdataintegrationandinteroperabilityacrossabroadrangeofclients,servers,services,andtools.

copiedfromhttp://odata.org

TeiidSupportforOData

WhenausersuccessfullydeploysaVDBintoaTeiidServer,theODataprotocolsupportisimplicitlyprovidedbytheTeiidserverwithoutanyfurtherconfiguration.

ODatasupportiscurrentlynotavailableintheTeiidEmbeddedprofile.

ODatasupportisimplementedanddeployedthroughWARfile(s).Accessissimilartoaccessingtoanywebresourcesdeployedonthecontainer.Thewarfile(s)arelocatedat<containerroot>/modules/org/jboss/teiid/deployments/*.war.

TeiidprovidesODataVersion2.0andODataVersion4.0support.

Important ODataVersion2.0supportisdeprecated.

ODataSupport

181

http://odata.org


Important ODataVersion2.0supportisdeprecated.

TeiidstrivestobecompliantwiththeODataspecification.TherestofthischapterhighlightsomespecificsofODataandTeiid’ssupport,butyoushouldalsoconsultthespecification.

HowtoAccessthedata?

Forexample,ifyouhaveavdbbynamenorthwinddeployedthathasacustomerstableinaNWmodel,thenyoucanaccessthattablewithanHTTPGETviatheURL:

http://localhost:8080/odata/northwind.1/NW.customers

thiswouldbeakintomakingaJDBC/ODBCconnectionandissuingtheSQL:

SELECT*FROMNW.customers

Note Notethatyoushouldfullyqualifythetablenamealongwiththemodelname.Also,usecorrectcase(upperorlower)asusedintheVDB.

thereturnedresultsfromODataquerycanbeinAtom/AtomPubXMLorJSONformat.AtomPubXMLresultsarereturnedbydefault.

Seeing"EdmEntitySetNotFound"error?

Whenyouissuetheabovequeryareyouseeingamessagesimilartobelow?

<errorxmlns="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata">

<code>NotFoundException</code>

<messagelang="en-US">EdmEntitySetNW.customerisnotfound</message>

</error>

Then,itmeansthateitheryousuppliedthemodel-name.table-namecombinationwrong,checkspellingandcase.OryourtabledidnothaveanyPRIMARYKEYorUNIQUEKEY(s)onthem.SinceODataaccessismorekeyoriented,itis*MANDATORY*thateverytableTeiidexposesthroughODatamusthaveaPKoratleastoneUNIQUEkey.NotethatTeiiddoessupportcompositePRIMARYKEYs.

Notseeingalltherows?Seetheconfigurationsectionbelowformoredetails.IssueanothercallwiththesameURL,butwiththe$skiptokenqueryoptionspecifiedfromthepreviousresult:

http://localhost:8080/odata/northwind.1/NW.customers?$skiptoken=xxx

Userscansubmitcriteriawithalongtheirquerytofiltertheresults:

http://localhost:8080/odata/northwind.1/NW.customers?$filter=nameeq'bob'


182

http://www.odata.org/documentation/odata-version-2-0/

thiswouldbesimilartomakingaJDBC/ODBCconnectionandissuingtheSQL

SELECT*FROMNW.customerswherename='bob'

TorequesttheresulttobeformattedinJSON,addthequeryoption$format=json

http://localhost:8080/odata/northwind.1/NW.customers?$format=JSON

Queryoptionscanbecombinedasneeded.Forexampleformatwithafilter:

http://localhost:8080/odata/northwind.1/NW.customers?$filter=name+eq+'bob'&$format=JSON

ODataallowsforqueryingnavigationsfromoneentitytoanother.Anavigationissimilartotheforeignkeyrelationshipsinrelationaldatabases.Forexample,ifthecustomerstablehasanassociationwiththeorderstableonthecustomersprimarykeyid,thenanODataGETcouldbeissuedlike:

http://localhost:8080/odata/northwind.1/NW.customers(1234)/NW.orders?$filter=orderdate+gt+datetime'2012-12-31T2

1:23:38Z'


SELECTo.*FROMNW.ordersojoinNW.customerscono.customer_id=c.idwherec.id=1234ando.orderdate>{ts'

2012-12-3121:23:38'}

NoteMoreComprehensiveDocumentationaboutODATA-Fordetailedprotocolaccessyoucanreadthespecificationathttp://odata.org.YoucanalsoreadthisveryusefulwebresourceforanexampleofaccessinganODataserver.

Howtoupdateyourdata?

UsingtheODataprotocolitispossibletoperformCREATE/UPDATE/DELETEoperationsalongwithREADoperationsshownabove.TheseoperationsusedifferentHTTPmethods.

INSERT/CREATEisaccomplishedthroughanHTTPmethod"POST".

ExamplePOST

POST/service.svc/CustomersHTTP/1.1

Host:host

Content-Type:application/atom+xml

Accept:application/atom+xml

Content-Length:nnn

<?xmlversion="1.0"encoding="utf-8"?>

<entryxml:base="http://host/service.svc/"

xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices"

xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata"

xmlns="http://www.w3.org/2005/Atom">

<id>http://host/service.svc/Customers('ASDFG')</id>

<titletype="text"/>

<updated>2008-12-07T8:00:00Z</updated>

<author>

<name/>

</author>

<linkrel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/Orders"href="Orders(1)"/>

<linkrel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/Orders"href="Orders(2)"/>


183

http://odata.org

http://msdn.microsoft.com/en-us/library/ff478141.aspx

<contenttype="application/xml">

<m:properties>

<d:CustomerID>ASDFG</d:CustomerID>

<d:CompanyName>ContosoWidgets</d:CompanyName>

<d:Address>

<d:Street>58ContosoSt</d:Street>

<d:City>Seattle</d:City>

</d:Address>

</m:properties>

</content>

</entry>

AnUPDATEisperformedwithanHTTP"PUT".

ExamplePUTUpdateofCustomer

PUT/service.svc/Customers('ALFKI')HTTP/1.1

Host:host



Content-Length:nnn

DataServiceVersion:1.0

MaxDataServiceVersion:3.0

Prefer:return-content

<?xmlversion="1.0"encoding="utf-8"?>

<entryxmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices"xmlns:m="http://schemas.microsoft.com/ad

o/2007/08/dataservices/metadata"xmlns="http://www.w3.org/2005/Atom">

<contenttype="application/xml">

<m:properties>

<d:CustomerID>ALFKI</d:CustomerID>

<d:CompanyName>UpdatedCompanyName</d:CompanyName>

<d:Address>

<d:Street>UpdatedStreet</d:Street>

</d:Address>

</m:properties>

</content>

</entry>

TheDELETEoperationusestheHTTP"DELETE"method.

ExampleDelete

DELETE/service.svc/Customers('ALFKI')HTTP/1.1

Host:host



Content-Length:nnn

DataServiceVersion:1.0

Security

BydefaultODataaccessissecuredusingHTTPBasicauthentication.TheuserwillbeauthenticatedagainstTeiid’sdefaultsecuritydomain"teiid-security".Usersareexpectedtohavetheodatarole.

However,ifyouwishtochangethesecuritydomainuseadeployment-overlaytooverridetheweb.xmlfileintheodata4fileinthe<modules>/org/jboss/teiid/main/deploymentsdirectory.

InfutureversionsmoreWS-Securitybasedconfigurationswillbeprovided.

Note SAMLBasedSecurity-ToprovideSingle-Sign-On(SSO)usingSAML2forODataaccess,pleasetakealookintheSecurityGuideforSAMLBasedSecurityForODatasection.


184

Configuration

TheODataWARfilecanbeconfiguredwithfollowingpropertiesintheweb.xmlfile.

PropertyName Description DefaultValue

batch-size Numberofrowstosendbackeachtime,-1returnsallrows 256

skiptoken-cache-timeTimeintervalbetweentheresultsbeingrecycled/expiredbetween$skiptokenrequests

300000

local-transport-name TeiidLocaltransportnameforconnection odata

invalid-xml10-character-replacement

ReplacementstringifaninvalidXML1.0characterappearsinthedata-notethatthisreplacementwilloccurevenifJSONisrequested.Novalue(thedefault)meansthatanexceptionwillbethrownwithXMLresultsifsuchacharacterisencountered.

proxy-base-uri Definestheproxyserver’sURItobeusedinODataresponses. n/a

connection.XXX

SetsXXXasanexecutionpropertyonthelocalconnection.Canbeusedforexampletoenableresultsetcachemode.

n/a

Note

"BehindProxyorInCloudEnvironments?"-IftheTeiidserverisconfiguredbehindaproxyserverordeployedincloudenvironment,orusingaload-balancerthentheURIoftheserverwhichishandlingtheODatarequestisdifferentfromURIofproxy.TogeneratevalidlinksintheODataresponsesconfigure"proxy-base-uri"propertyintheweb.xml.Ifthisvalueisavailableassystempropertythendefinethepropertyvaluelikebelow

<context-param>

<param-name>proxy-base-uri</param-name>

<param-value>${system-property-name}</param-value>

</context-param>

TeiidODataserver,implementscursoringlogicwhentheresultrowsexceedtheconfiguredbatchsize.Oneveryrequest,onlybatch-sizenumberofrowsarereturned.Eachsuchrequestisconsideredanactivecursor,withaspecifiedamountofidletimespecifiedbyskip-token-cache-time.Afterthecursoristimedout,thecursorwillbeclosedandremainingresultswillbecleanedup,andwillnolongerbeavailableforfurtherqueries.Sincethereisnosessionbasedtrackingofthesecursors,iftherequestforskiptokencomesaftertheexpiredtime,theoriginalquerywillbeexecutedagainandtriestorepositionthecursortorelativeabsolutepotion,howevertheresultsarenotguaranteedtobesameastheunderlyingsourcesmayhavebeenupdatedwithnewinformationmeanwhile.

LimitationsThefollowingfeaturelimitationscurrentlyapply.

Blobsupportformediatypesarenotsupported.


185

"$value"constructtoretrieveindividualcolumnvalueisnotsupported.

create/update/delete$linksisnotsupported.

$expandsupportislimitedtoasingleparent/child.

ClientToolsforAccessODataaccessisreallywheretheusercomesin,dependinguponyourprogrammingmodelandneedstherearevariouswaysyouwriteyouraccesslayerintoOData.Thefollowingaresomesuggestions:

YourBrowser:TheODataExplorerisanonlinetoolforbrowsinganODatadataservice.

Microsoft.NETFramework3.51:theWCFDataServicesframeworkisavailableasaseparatedownloadfor.NET3.x.

Microsoft.NETFramework4.0:theWCFDataServicesframeworkbuiltinto.NET4.0(inreleasecandidateasofthiswriting).

Silverlight3:theDataServicesclientlibraryforSilverlightisavailablefordownload.

Java:theRestlet2.0libraryforJava(includingJavaonyourAndroidphone)supportstheODataprotocol.

Java:UsealibrarylikeOData4JforJavabasedaccess,oranyRestbasedframework

JavaScript:theXMLHttpRequestobjectisstandardinmodernbrowsersoryoucanusejQuery,whichcomesoutoftheboxwith.NET4.0orisavailablefordownload.

PHP:theToolkitforPHPprovidesODatasupportforPHPclients.

AJAX:ifyou’reusingAJAXforASP.NET,MicrosoftprovidestheASP.NETAjaxLibraryforgettingtoOData.

Excel2010PowerPivot:PowerPivotcomeswithODatasupportbuiltrightin.

WindowsDesktop:LINQPadisawonderfultoolforbuildingODataqueriesinteractively.

ShellScripts:useCURLtool

HowTeiidexposesschemaforODataODatadefinesitsschemausingConceptualSchemaDefinitionLanguage(CSDL).EveryVDB,thatisdeployedinanACTIVEstateinTeiidserverexposesitsmetadatainCSDLformat.Forexampleifyouwantretrievemetadataforyourvdbnorthwind,youneedtoissueaquerylike

http://localhost:8080/odata/northwind/$metadata

SinceODataschemamodelisnotarelationalschemamodel,TeiidusesthefollowingsemanticstomapitsrelationalschemamodeltoODataschemamodel.

RelationalEntity MappedODataEntity

ModelName SchemaNamespace,EntityContainerName

Table/View EntityType,EntitySet

TableColumns EntityType’sProperties

PrimaryKey EntityType’sKeyProperties


186

ForeignKey NavigationPropertyonEntityType,Association,AssosiationSet

Procedure FunctionImport

Procedure’sTableReturn ComplexType

Teiidbydesigndoesnotdefineany"embedded"ComplexTypeintheEntityType.

TeiiddoesnotdefineanyoneEntityContainerthatresultedfromdifferentvdbmodelsasadefaultcontainer,soallentitiesmustbeaccessedusingfullpathtothem.

ODataVersion3.0TeiiddoesnotprovideacompleteODataVersion3.0implementation.SomeOData3.0featuresareprovidedwiththeODataVersion2.0support.


187

ODataVersion4.0SupportTeiidstrivestobecompliantwiththeODataspecification.TherestofthischapterhighlightsomespecificsofODataandTeiid’ssupport,butyoushouldalsoconsultthespecification.

HowtoAccessthedata?

Forexample,ifyouhaveavdbbynamenorthwinddeployedthathasacustomerstableinaNWmodel,thenyoucanaccessthattablewithanHTTPGETviatheURL:

http://localhost:8080/odata/northwind/NW/customers


SELECT*FROMNW.customers

Note Usecorrectcase(upperorlower)intheresourcepath.UnlikeSQL,thenamesusedintheURIascase-sensitive.

ThereturnedresultsfromODataquerycanbeinAtom/AtomPubXMLorJSONformat.JSONresultsarereturnedbydefault.

QueryBasicsUserscansubmitpredicateswithalongtheirquerytofiltertheresults:

http://localhost:8080/odata/northwind/NW/customers?$filter=name+eq+'bob'

thiswouldbesimilartomakingaJDBC/ODBCconnectionandissuingtheSQL

SELECT*FROMNW.customerswherename='bob'

Torequesttheresulttobeformattedinaspecificformat,addthequeryoption$format

http://localhost:8080/odata/northwind/NW/customers?$format=JSON

Queryoptionscanbecombinedasneeded.Forexampleformatwithafilter:

http://localhost:8080/odata/northwind/NW/customers?$filter=name+eq+'bob'&$format=xml

ODataallowsforqueryingnavigationsfromoneentitytoanother.Anavigationissimilartotheforeignkeyrelationshipsinrelationaldatabases.

Forexample,ifthecustomerstablehasanexportedkeytotheorderstableonthecustomersprimarykeycalledthecustomer_fk,thenanODataGETcouldbeissuedlike:

http://localhost:8080/odata/northwind/NW/customers(1234)/customer_fk?$filter=orderdate+gt+datetime'2012-12-31T2

1:23:38Z'



188

http://www.odata.org/documentation/

SELECTo.*FROMNW.ordersojoinNW.customerscono.customer_id=c.idwherec.id=1234ando.orderdate>{ts'

2012-12-3121:23:38'}

NoteMoreComprehensiveDocumentationaboutODATA-Fordetailedprotocolaccessyoucanreadthespecificationathttp://odata.org.YoucanalsoreadthisveryusefulwebresourceforanexampleofaccessinganODataserver.

Notseeingalltherows?

Seetheconfigurationsectionbelowformoredetails.Generallybatchingisbeingutilized,whichtoolingshouldunderstandautomatically,andadditionalquerieswitha$skiptokenqueryoptionspecifiedareneeded:

http://localhost:8080/odata/northwind/NW/customers?$skiptoken=xxx

"EntitySetNotFound"error?

Whenyouissuetheabovequeryareyouseeingamessagesimilartobelow?

{"error":{"code":null,"message":"CannotfindEntitySet,Singleton,ActionImportorFunctionImportwithname'xx

x'."}}

Then,itmeansthateitheryousuppliedthemodel-name/table-namecombinationwrong,checkthespellingandcase.

Itispossiblethattheentityisnotpartofthemetadata,suchaswhenatabledoesnothaveanyPRIMARYKEYorUNIQUEKEY(s).

Howtoupdateyourdata?

UsingtheODataprotocolitispossibletoperformCREATE/UPDATE/DELETEoperationsalongwithREADoperationsshownabove.TheseoperationsusedifferentHTTPmethods.

INSERT/CREATEisaccomplishedthroughanHTTPmethod"POST".

ExamplePOST

POST/service.svc/CustomersHTTP/1.1

Host:host

Content-Type:application/json

Accept:application/json

{

"CustomerID":"AS123X",

"CompanyName":"ContosoWidgets",

"Address":{

"Street":"58ContosoSt",

"City":"Seattle"

}

}

AnUPDATEisperformedwithanHTTP"PUT".

ExamplePUTUpdateofCustomer

PUT/service.svc/Customers('ALFKI')HTTP/1.1

Host:host

Content-Type:application/josn


{


189

http://odata.org

http://msdn.microsoft.com/en-us/library/ff478141.aspx

"CustomerID":"AS123X",

"CompanyName":"UpdatedCompanyName",

"Address":{

"Street":"UpdatedStreet"

}

}

TheDELETEoperationusestheHTTP"DELETE"method.

ExampleDelete

DELETE/service.svc/Customers('ALFKI')HTTP/1.1

Host:host

Content-Type:application/json


Security

BydefaultODataaccessissecuredusingHTTPBasicauthentication.TheuserwillbeauthenticatedagainstTeiid’sdefaultsecuritydomain"teiid-security".Usersareexpectedtohavetheodatarole.Besuretocreateuserwiththisrolewhenyouareusingadd-user.shscripttocreateanewuser.

However,ifyouwishtochangethesecuritydomainuseadeployment-overlaytooverridetheweb.xmlfileintheodata4fileinthe<modules>/org/jboss/teiid/main/deploymentsdirectory.

ODataWARcanalsosupportKerberos,SAMLandOAuth2authentications,forconfiguringthethesesecurityschemespleasesee../security/Security_Guide.adoc[SecurityGuide]

Configuration

TheODataWARfilecanbeconfiguredwithfollowingpropertiesintheweb.xmlfile.

PropertyName Description DefaultValue

batch-size Numberofrowstosendbackeachtime,-1returnsallrows 256

skiptoken-cache-timeTimeintervalbetweentheresultsbeingrecycled/expiredbetween$skiptokenrequests

300000

invalid-xml10-character-replacement XML1.0replacementcharacterfornonUTF-8characters.

local-transport-name TeiidLocaltransportnameforconnection odata

invalid-xml10-character-replacement

ReplacementstringifaninvalidXML1.0characterappearsinthedata-notethatthisreplacementwilloccurevenifJSONisrequested.Novalue(thedefault)meansthatanexceptionwillbethrownwithXMLresultsifsuchacharacterisencountered.

proxy-base-uri Definestheproxyserver’sURItobeusedinODataresponses. n/a


190

connection.XXX

SetsXXXasanexecutionpropertyonthelocalconnection.Canbeusedforexampletoenableresultsetcachemode.

n/a

Note

"BehindProxyorInCloudEnvironments?"-IftheTeiidserverisconfiguredbehindaproxyserverordeployedincloudenvironment,orusingaload-balancerthentheURIoftheserverwhichishandlingtheODatarequestisdifferentfromURIofproxy.TogeneratevalidlinksintheODataresponsesconfigure"proxy-base-uri"propertyintheweb.xml.Ifthisvalueisavailableassystempropertythendefinethepropertyvaluelikebelow

<init-param>

<param-name>proxy-base-uri</param-name>

<param-value>${system-property-name}</param-value>

</init-param>

Tomodifytheweb.xml,createadeployment-overlayusingthecliwiththemodifiedcontents:

deployment-overlayadd--name=myOverlay--content=/WEB-INF/web.xml=/modified/web.xml--deployments=teiid-odata-

odata4.war--redeploy-affected

TeiidODataserver,implementscursoringlogicwhentheresultrowsexceedtheconfiguredbatchsize.Oneveryrequest,onlybatch-sizenumberofrowsarereturned.Eachsuchrequestisconsideredanactivecursor,withaspecifiedamountofidletimespecifiedbyskip-token-cache-time.Afterthecursoristimedout,thecursorwillbeclosedandremainingresultswillbecleanedup,andwillnolongerbeavailableforfurtherqueries.Sincethereisnosessionbasedtrackingofthesecursors,iftherequestforskiptokencomesaftertheexpiredtime,theoriginalquerywillbeexecutedagainandtriestorepositionthecursortorelativeabsolutepotion,howevertheresultsarenotguaranteedtobesameastheunderlyingsourcesmayhavebeenupdatedwithnewinformationmeanwhile.

Limitations

Thefollowingfeaturelimitationscurrentlyapply.

deltaprocessingisnotsupported

data-aggregationextensiontospecificationisnotsupported.

$expandisminimallysupported,whereonlyonenavigationcanbeexpanded.

ClientToolsforAccessODataaccessisreallywheretheusercomesin,dependinguponyourprogrammingmodelandneedstherearevariouswaysyouwriteyouraccesslayerintoOData.Thefollowingaresomesuggestions:

YourBrowser:TheODataExplorerisanonlinetoolforbrowsinganODatadataservice.

Olingo:IsaJavaframeworkthatsupportsODataV4,hasbothconsumerandproducerframework.

Microsofthasvarious.Netbasedlibraries,seehttp://odata.github.io/

WindowsDesktop:LINQPadisawonderfultoolforbuildingODataqueriesinteractively.Seehttps://www.linqpad.net/

ShellScripts:useCURLtool

Forlatestinformationotherframeworksandtoolsavailablepleaseseehttp://www.odata.org/ecosystem/


191


http://odata.github.io/

https://www.linqpad.net/

http://www.odata.org/ecosystem/

ODataMetadata(HowTeiidinterpretstherelationalschemaintoOData’s$metadata)

ODatadefinesitsschemausingConceptualSchemaDefinitionLanguage(CSDL).EveryVDB,thatisdeployedinanACTIVEstateinTeiidserverexposesitsmetadatainCSDLformat.Forexampleifyouwantretrievemetadataforyourvdbnorthwind,youneedtoissueaquerylike

http://localhost:8080/odata/northwind/NW/$metadata

SinceODataschemamodelisnotarelationalschemamodel,TeiidusesthefollowingsemanticstomapitsrelationalschemamodeltoODataschemamodel.

RelationalEntity MappedODataEntity

ModelName SchemaNamespace,EntityContainerName

Table/View EntityType,EntitySet

TableColumns EntityType’sProperties

PrimaryKey EntityType’sKeyProperties

ForeignKey NavigationPropertyonEntityType

Procedure FunctionImport,ActionImport

Procedure’sTableReturn ComplexType

Teiidbydesigndoesnotdefineany"embedded"ComplexTypeintheEntityType.

SinceODataaccessismorekeybased,itis*MANDATORY*thateverytableTeiidexposesthroughODatamusthaveaPKoratleastoneUNIQUEkey.Atablewhichdoesnoteitherofthesewillbedropeedoutofthe$metadata


192


Configuration

Forthemostpart,interactingwithTeiidVDBs(VirtualDatabases)throughHibernateisnodifferentfromworkingwithanyothertypeofdatasource.First,dependingonwhereyourHibernateapplicationwillreside,eitherinthesameVMastheTeiidRuntimeoronaseparateVM,willdeterminewhichjar’sareused.

RunninginsameVMintheWildFlyserver,thentheteiid-client-{version}.jarandteiid-hibernate-dialect-{version}.jaralreadyresidein<jboss-install>/modules/org/jboss/teiid/client

RunningseparateVM’s,youneedtheTeiidJDBCDriverJARandTeiid’sHibernateDialectJARintheHibernate’sclasspath.TheHibernateJARcanbefoundin<jboss-install>/modules/org/jboss/teiid/client,teiid-hibernate-dialect-{version}.jarandtheTeiidJDBCDriverJARneedstobedownloaded.

TheseJARfileshavetheorg.teiid.dialect.TeiidDialectandorg.teiid.jdbc.TeiidDriverandorg.teiid.jdbc.TeiidDataSourceclasses.

YouconfigureHibernate(viahibernate.cfg.xml)asfollows:

SpecifytheTeiiddriverclassintheconnection.driver_classproperty:

<propertyname="connection.driver_class">

org.teiid.jdbc.TeiidDriver

</property>

SpecifytheURLfortheVDBintheconnection.urlproperty(replacingtermsinanglebracketswiththeappropriatevalues):

<propertyname="connection.url">

jdbc:teiid:<vdb-name>@mm://<host>:<port>;user=<user-name>;password=<password>

</property>

Tip BesuretouseaLocalJDBCConnectionifHibernateisinthesameVMastheapplicationserver.

SpecifytheTeiiddialectclassinthedialectproperty:

<propertyname="dialect">

org.teiid.dialect.TeiidDialect

</property>

Alternatively,ifyouputyourconnectionpropertiesinhibernate.propertiesinsteadofhibernate.cfg.xml,theywouldlooklikethis:

hibernate.connection.driver_class=org.teiid.jdbc.TeiidDriver

hibernate.connection.url=jdbc:teiid:<vdb-name>@mm://<host>:<port>

hibernate.connection.username=<user-name>

hibernate.connection.password=<password>

hibernate.dialect=org.teiid.dialect.TeiidDialect

NotealsothatsinceyourVDBswilllikelycontainmultiplesourceandviewmodelswithidenticaltablenames,youwillneedtofullyqualifytablenamesspecifiedinHibernatemappingfiles:


193


<classname="<Classname>"table="<Source/viewmodelname>.[<schemaname>.]<Tablename>">

...

</class>

ExampleMapping

<classname="org.teiid.example.Publisher"table="BOOKS.BOOKS.PUBLISHERS">

...

</class>

IdentifierGenerationIdentifiergenerationbasedupontablevalues,suchasthehilogenerator,requirethattheidentifiertable(s)beexposedthroughTeiid.

GUIDandIdentity(usinggeneratedkeyretrieval)identifiergenerationstrategyaredirectlysupported.

Limitations

ManyHibernateusecasesassumeadatasourcehastheability(withproperuserpermissions)toprocessDataDefinitionLanguage(DDL)statementslikeCREATETABLEandDROPTABLEaswellasDataManipulationLanguage(DML)statementslikeSELECT,UPDATE,INSERTandDELETE.TeiidcanhandleabroadrangeofDML,butdoesnotdirectlysupportDDLagainstaparticularsource.

Sequencegenerationisnotdirectlysupported.


194


Overview

WecanuseTeiidwithHibernate,wealsohaveaquickstartshowhowHibernateontopofTeiid.BothHibernateandEclipselinkarefullysupportJSR-317(JPA2.0),primarypurposeofthisdocumentisdemonstratehowuseTeiidwithEclipseLink.

Configuration

Forthemostpart,interactingwithTeiidVDBs(VirtualDatabases)throughEclipselinkisnodifferentfromworkingwithanyothertypeofdatasource.First,dependingonwhereyourEclipselinkapplicationwillreside,eitherinthesameVMastheTeiidRuntimeoronaseparateVM,willdeterminewhichjar’sareused.

RunninginsameVMintheWildFlyserver,theteiid-client-{version}.jarandteiid-eclipselink-platform-{version}.jarareneeded

RunningseparateVM’s,youneedtheTeiidJDBCDriverJAR(DownloadTeiidJDBCDriverJAR)andTeiid’sEclipselinkPlatformJAR(teiid-eclipselink-platform{version}.jar)intheEclipselink’sclasspath.

TheseJARfileshavetheorg.teiid.eclipselin.platform.TeiidPlatformandorg.teiid.jdbc.TeiidDriverclasses.

YouconfigureEclipseLink(viapersistence.xml)asfollows:

SpecifytheTeiiddriverclass,connectionurl

<propertyname="javax.persistence.jdbc.driver"value="org.teiid.jdbc.TeiidDriver"/>

<propertyname="javax.persistence.jdbc.url"value="jdbc:teiid:<vdb-name>@mm://<host>:<port>"/>

<propertyname="javax.persistence.jdbc.user"value="<username>"/>

<propertyname="javax.persistence.jdbc.password"value="<password>"/>

SpecifytheTeiidplatformclass

<propertyname="eclipselink.target-database"value="org.teiid.eclipselink.platform.TeiidPlatform"/>

Limitations

ManyEclipselinkusecasesassumeadatasourcehastheability(withproperuserpermissions)toprocessDataDefinitionLanguage(DDL)statementslikeCREATETABLEandDROPTABLEaswellasDataManipulationLanguage(DML)statementslikeSELECT,UPDATE,INSERTandDELETE.TeiidcanhandleabroadrangeofDML,butdoesnotdirectlysupportDDLagainstaparticularsource.

Sequencegenerationisnotdirectlysupported.


195

https://docs.jboss.org/author/display/teiid88final/Using+Teiid+with+Hibernate

https://docs.jboss.org/author/display/teiidexamples/Using+Hibernate+on+top+of+Teiid


Developer’sGuideThisguidecontainsinformationfordeveloperscreatingcustomsolutionswithTeiid.ItcoverscreatingJEEJCAconnectorswiththeTeiidframework,TeiidTranslators,TeiidUserDefinedFunctions(UDFs)aswellasrelatedtopics.

IntegratingdatafromaEnterpriseInformationSystem(EIS)intoTeiid,isseparatedintotwoparts.

1. ATranslator,whichisrequired.

2. AnoptionalResourceAdapter,whichwilltypicallybeaJCAResourceAdapter(alsocalledaJEEConnector)

ATranslatorisusedto:

TranslateaTeiid-specificcommandintoanativecommand

Executethecommand

ReturnbatchesofresultstranslatedtoexpectedTeiidtypes.

AResourceAdapterisusedto:

Handlesallcommunicationswithindividualenterpriseinformationsystem(EIS),whichcanincludedatabases,datafeeds,flatfiles,etc.

CanbeaJCAConnectororanyothercustomconnectionprovider.ThereasonTeiidrecommendsandusesJCAisthisspecificationdefineshowonecanwrite,package,andconfigureaccesstoEISsysteminconsistentmanner.Therearealsovariouscommercial/opensourcesoftwarevendorsalreadyprovidingJCAConnectorstoaccessavarietyofback-endsystems.Refertohttp://java.sun.com/j2ee/connector/.

AbstractsTranslatorsfrommanycommonconcerns,suchasconnectioninformation,resourcepooling,orauthentication.+GivenacombinationofaTranslator+ResourceAdapter,onecanconnectanyEISsystemtoTeiidfortheirdataintegrationneeds.

DoYouNeedaNewTranslator?

Teiidprovidesseveraltranslatorsforcommonenterpriseinformationsystemtypes.Ifyoucanuseoneoftheseenterpriseinformationsystems,youdonotneedtodevelopacustomone.

Teiidoffersnumerousbuilt-intranslators,including:

JDBCTranslator-Workswithmanyrelationaldatabases.TheJDBCtranslatorisvalidatedagainstthefollowingdatabasesystems:Oracle,MicrosoftSQLServer,IBMDB2,MySQL,Postgres,Derby,Sybase,H2,andHSQL.Inaddition,theJDBCTranslatorcanoftenbeusedwithother3rd-partydriversandprovidesawiderangeofextensibilityoptionstospecializebehavioragainstthosedrivers.

FileTranslator-Providesaproceduralwaytoaccessthefilesystemtohandletextfiles.

WSTranslator-ProvidesproceduralaccesstoXMLcontentusingWebServices.

LDAPTranslator-AccessestoLDAPdirectoryservices.

SalesforceTranslator-WorkswithSalesforceinterfaces.

Toseeafulllistofavailabletranslators,seeTranslators

Developer’sGuide

196

http://java.sun.com/j2ee/connector/

Ifthere’snotanavailabletranslatorthatmeetsyourneed,Teiidprovidestheframeworkfordevelopingyourowncustomtranslator.SeetheTranslatorDevelopmentsection,asitwilldescribehowtodevelop,packageanddeployacustomdevelopedtranslator.

DoYouNeedaNewResourceAdapter?

Asmentionedabove,foreveryTranslatorthatneedstogatherdatafromexternalsourcesystems,itrequiresaresourceadapter.

ThefollowingaresomeofresourceadaptersthatareavailabletoTeiid:

DataSource:ThisisprovidedbytheWildFlycontainer.ThisisusedbytheJDBCTranslator.

File:ProvidesaJEEJCAbasedConnectortoaccessdefineddirectoryonthefilesystem.ThisisusedbytheFileTranslator

WS:ProvidesJEEJCAConnectortoinvokeWebServicesusingWildFlyWebservicesstack.ThisisusedbytheWSTranslator

LDAP:ProvidesJEEJCAconnectortoaccessLDAP;UsedbytheLDAPTranslator.

Salesforce:ProvidesJEEJCAconnectortoaccessSalesforcebyinvokingtheirWebServiceinterface.UsedbytheSalesForceTranslator.

Toseeafulllist,seeDeployingVDBDependencies

Ifthere’snotanavailableresource-adapterthatmeetsyourneed,TeiidprovidestheframeworkfordevelopingyourownJEEJCAConnector.SeetheDevelopingJEEConnectorssection,asitwilldescribehowtodevelop,packageanddeployaresourceadapter.

OtherTeiidDevelopment

Teiidishighlyextensibleinotherways:

YoumayaddUserDefinedFunctions.RefertoUserDefinedFunctions.

Youmayadaptloggingtoyourneeds,whichisespeciallyusefulforcustomauditorcommandlogging.RefertoCustomLogging.

Youmaychangethesubsystemforcustomauthenticationandauthorization.RefertoCustomLoginModules.

Developer’sGuide

197


Developing(Custom)JEEConnectors(ResourceAdapters)

ThischapterexamineshowtousefacilitiesprovidedbytheTeiidAPItodevelopaJEEJCAConnector.PleasenotethatthesearestandardJEEJCAconnectors,nothingspecialneedstobedoneforTeiid.AsanaidtoourTranslatordevelopers,weprovidedabaseimplementationframework.IfyoualreadyhaveaJCAConnectororsomeothermechanismtogetdatafromyoursourcesystem,youcanskipthischapter.

IfyouarenotfamiliarwithJCAAPI,pleasereadtheJCA1.5Specificationathttp://java.sun.com/j2ee/connector/.TherearelotofonlinetutorialsonhowtodesignandbuildaJCAConnector.Thebelowarehigh-levelstepsforcreatingaverysimpleconnector,howeverbuildingactualconnectorthatsupportstransactions,securitycangetmuchmorecomplex.

1. UnderstandtheJEEConnectorspecificationtohavebasicideaaboutwhatJCAconnectorsarehowtheyaredevelopedandpackaged.Refertohttp://java.sun.com/j2ee/connector/.

2. GatherallnecessaryinformationaboutyourEnterpriseInformationSystem(EIS).Youwillneedtoknow:

APIforaccessingthesystem

Configurationandconnectioninformationforthesystem

Expectationforincomingqueries/metadata

Theprocessingconstructs,orcapabilities,supportedbyinformationsystem.

Requiredpropertiesfortheconnection,suchasURL,username,etc.

3. BaseclassesforalloftherequiredsupportingJCASPIclassesareprovidedbytheTeiidAPI.TheJCACCIsupportisnotprovidedfromTeiid,sinceTeiidusestheTranslatorAPIasit’scommonclientinterface.Youwillwanttoextend:

BasicConnectionFactory–DefinestheConnectionFactory

BasicConnection–representsaconnectiontothesource.

BasicResourceAdapter–Specifiestheresourceadapterclass

4. Packageyourresourceadapter.RefertoPackagingtheAdapter.

5. Deployyourresourceadapter.RefertoPackagingtheAdapter.

ForsampleresourceadaptercoderefertotheTeiidSourcecodeathttps://github.com/teiid/teiid/tree/master/connectors/.

RefertotheJBossApplicationServerConnectorsdocumentationathttp://docs.jboss.org/jbossas/jboss4guide/r4/html/ch7.chapt.html.


198



https://github.com/teiid/teiid/tree/master/connectors/

http://docs.jboss.org/jbossas/jboss4guide/r4/html/ch7.chapt.html

ConnectorEnvironmentSetupTosetuptheenvironmentfordevelopingacustomconnector,youhave2options:

1. Manuallysetuptheenvironment-structure,frameworkclasses,andresources.

2. usetheTeiidConnectorArchetypetemplatetogeneratetheinitialproject.


199

BuildEnvironmentForEclipseusers(withoutmavenintegration),createajavaprojectandadddependenciestoteiid-common-core,teiid-apiandJEEconnector-apijars.

Formavenusersaddthefollowingasyourdependencies:


<projectxsi:schemaLocation="http://maven.apache.org/POM/4.0.0http://maven.apache.org/maven-v4_0_0.xsd"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

<modelVersion>4.0.0</modelVersion>

<artifactId>connector-{name}</artifactId>

<groupId>org.company.project</groupId>

<name>NameConnector</name>

<packaging>rar</packaging>

<description>Thisconnectorisasample</description>

<dependencies>

<dependency>


<artifactId>teiid-api</artifactId>

<scope>provided</scope>

</dependency>

<dependency>


<artifactId>teiid-common-core</artifactId>


</dependency>

<dependency>

<groupId>javax.resource</groupId>

<artifactId>connector-api</artifactId>


</dependency>

</dependencies>

</project>

Wherethe${teiid-version}propertyshouldbesettotheexpectedversion,suchas9.0.0.Final.YoucanfindTeiidartifactsintheJBossmavenrepository.The$\{version.connector.api}versionlastusedwas1.5.


200

http://community.jboss.org/docs/DOC-15169

ArchetypeTemplateConnectorProjectOnewaytostartdevelopingacustomconnector(resource-adapter)istocreateaprojectusingtheTeiidarchetypetemplate.Whentheprojectiscreatedfromthetemplate,itwillcontaintheessentialclassesandresourcesforyoutobeginaddingyourcustomlogic.Additionally,themavendependenciesaredefinedinthepom.xmlsothatyoucanbegincompilingtheclasses.

Note Theprojectwillbecreatedasanindependentprojectandhasnoparentmavendependencies.It’sdesignedtobebuiltindependentofbuildingTeiid.

Youhave2optionsforcreatingaconnectorproject;inEclipsebycreatinganewmavenprojectfromthearchetypeorbyusingthecommandlinetogeneratetheproject.

CreateProjectinEclipseTocreateaJavaprojectinEclipsefromanarchetype,performthefollowing:

OpentheJAVAperspective

FromthemenuselectFile–>New—>Other

Inthetree,expandMavenandselectMavenProject,pressNext

Onthe"SelectprojectnameandLocation"window,youcanacceptthedefaults,pressNext

Onthe"SelectanArchetype"window,selectConfigurebutton

Addtheremotecatalog:https://repository.jboss.org/nexus/content/repositories/releases/thenclickOKtoreturn

Enter"teiid"inthefiltertoseetheTeiidarchetypes.

Selecttheconnector-archetypev8.7.1,thenpressNext

Enteralltheinformation(i.e.,GroupID,ArtifactID,etc.)neededtogeneratetheproject,thenclickFinish

Theprojectwillbecreatedandnameaccordingtothe*ArtifactID*.

CreateProjectusingCommandLine

Tocreateacustomconnectorprojectfromthecommandline,youcanusethefollowingtemplatecommand:

mvnarchetype:generate-DarchethypeRepository=https://repository.jboss.org/nexus/content/repositories/release

s/\

-DarchetypeGroupId=org.jboss.teiid.arche-types\

-DarchetypeArtifactId=connector-archetype\

-DarchetypeVersion=8.7.1\

-DgroupId=${groupId}\

-DartifactId=connector-${connector-name}\

-Dpackage=org.teiid.resource.adapter.${connector-name}\

-Dversion=${teiid.version}\

-Dconnector-name=${connector-name}\

-Dvendor-name=${vendor-name}\

-Dteiid-version=${teiid-version}

where:

-DarchetypeGroupId-isthegroupIDforthearchetypetousetogenerate


201

https://repository.jboss.org/nexus/content/repositories/releases/

-DarchetypeArtifactId-istheartifactIDforthearchetypetousetogenerate

-DarchetypeVersion-istheversionofthearchetypetousetogenerate

-DgroupId-(userdefined)groupIDforthenewconnectorprojectpom.xml

-DartifactId-(userdefined)artifactIDforthenewconnectorprojectpom.xml

-Dpackage-(userdefined)thepackagestructurewherethejavaandresourcefileswillbecreated

-Dversion-(userdefined)theversionthatthenewconnectorprojectpom.xmlwillbe

-Dconnector-name-(userdefined)thename(type)ofthenewconnectorproject,usedtocreatethejavacla

ssnamesandrar

-Dvendor-name-nameoftheVendorforthedatasource,updatestherar

-Dteiid-version-theTeiidversiontheconnectorwilldependupon

Thefollowingisanexample:

mvnarchetype:generate-DarchethypeRepository=https://repository.jboss.org/nexus/content/repositories/release

s/\


-DarchetypeArtifactId=connector-archetype\


-DgroupId=org.jboss.teiid.connectors\

-Dpackage=org.teiid.resource.adapter.myType\

-DartifactId=connector-myType\

-Dversion=0.0.1-SNAPSHOT\

-Dconnector-name=myType\

-Dvendor-name=MyVendor\

-Dteiid-version=8.7.0.Final

Whenexecuted,youwillbeaskedtoconfirmtheproperties

Confirmpropertiesconfiguration:

groupId:org.jboss.teiid.connectors

artifactId:connector-myType

version:0.0.1-SNAPSHOT

package:org.teiid.resource.adapter.myType

connector-name:myType

vendor-name:MyVendor

teiid-version:8.7.0.Final

Y::

typeY(yes)andpressenter,andthecreationoftheconnectorprojectwillbedone

Uponcreation,adirectorybasedonthe*artifactId*willbecreated,thatwillcontaintheproject.Note:Theprojectwillnotcompilebecausethe${connector-name}ConnectioninterfaceintheConnectionImplhasnotbeenaddedasadependencyinthepom.xml.Thiswillneedtobedone.

Nowyouarereadytostartaddingyourcustomcode.


202

ImplementingtheTeiidFrameworkIfyouaregoingtousetheTeiidframeworkfordevelopingaJCAconnector,followthesesteps.Therequiredclassesareinorg.teiid.resource.apipackage.PleasenotethatTeiidframeworkdoesnotmakeuseJCA’sCCIframework,onlytheJCA’sSPIinterfaces.

DefineManagedConnectionFactory

DefinetheConnectionFactoryclass

DefinetheConnectionclass

Definetheconfigurationpropertiesina"ra.xml"file

DefineManagedConnectionFactoryExtendtheBasicManagedConnectionFactory,andprovideaimplementationforthe"createConnectionFactory()"method.Thismethoddefinesafactorymethodthatcancreateconnections.

Thisclassalsodefinesconfigurationvariables,likeuser,password,URLetctoconnecttotheEISsystem.Defineanattributeforeachconfigurationvariable,andthenprovideboth"getter"and"setter"methodsforthem.Notetouseonly"java.lang"objectsastheattributes,DONOTuseJavaprimitivesfordefiningandaccessingtheproperties.Seethefollowingcodeforanexample.

publicclassMyManagedConnectionFactoryextendsBasicManagedConnectionFactory

{

@Override

publicObjectcreateConnectionFactory()throwsResourceException

{

returnnewMyConnectionFactory();

}

//configpropertyname(metadataforthesearedefinedinsidethera.xml)

StringuserName;

publicStringgetUserName(){returnthis.userName;}

publicvoidsetUserName(Stringname){this.userName=name;}

//configpropertycount(metadataforthesearedefinedinsidethera.xml)

Integercount;

publicIntegergetCount(){returnthis.count;}

publicvoidsetCount(Integervalue){this.count=value;}

}

DefinetheConnectionFactoryclass

ExtendtheBasicConnectionFactoryclass,andprovideaimplementationforthe"getConnection()"method.

publicclassMyConnectionFactoryextendsBasicConnectionFactory

{

@Override

publicMyConnectiongetConnection()throwsResourceException

{

returnnewMyConnection();

}

}


203

SincetheManagedconnectionobjectcreatedthe"ConnectionFactory"classithasaccesstoalltheconfigurationparameters,if"getConnection"methodneedstodopassanyofcredentialstotheunderlyingEISsystem.TheConnectionFactoryclasscanalsogetreferencetothecallinguser’sjavax.security.auth.Subjectduring"getConnection"methodbycalling

Subjectsubject=ConnectionContext.getSubject();

This"Subject"objectcangiveaccesstologged-inuser’scredentialsandrolesthataredefined.Notethatthismaybenull.

Notethatyoucandefine"security-domain"forthisresourceadapter,thatisseparatefromtheTeiiddefined"security-domain"forvalidatingtheJDBCenduser.However,itisusersresponsibilitytomakethenecessaryloginsbeforetheContainer’sthreadaccessesthisresourceadapter,andthiscangetoverlycomplex.

DefinetheConnectionclass

ExtendtheBasicConnectionclass,andprovideaimplementationbasedonyouraccessoftheConnectionobjectintheTranslator.Ifyourconnectionisstateful,thenoverride"isAlive()"and"cleanup()"methodsandprovideproperimplementations.ThesearecalledtocheckifaConnectionisstaleorneedtoflushthemfromtheconnectionpooletc.bytheContainer.

publicclassMyConnectionextendsBasicConnection

{

publicvoiddoSomeOperation(command)

{

//dosomeoperationwithEISsystem..

//ThisismethodyouuseintheTranslator,youshouldknow

//whatneedtobedonehereforyoursource..

}

@Override

publicbooleanisAlive()

{

returntrue;

}

@Override

publicvoidcleanUp()

{

}

}

XATransactions

IfyourEISsourcecanparticipateinXAtransactions,thenonyourConnectionobject,overridethe"getXAResource()"methodandprovidethe"XAResource"objectfortheEISsystem.RefertoDefinetheConnectionclass.Also,Youneedtoextendthe"BasicResourceAdapter"classandprovideimplementationformethod"publicXAResource[]getXAResources(ActivationSpec[]specs)"toparticipateincrashrecovery.

Notethat,onlywhentheresourceadaptersareXAcapable,thenTeiidcanmakethemparticipateinadistributedtransactions.IftheyarenotXAcapable,thensourcecanparticipateindistributedquerybutwillnotparticipateinthetransaction.Transactionsemanticsaredefinedbyhowyouyouconfigured"connection-factory"ina"resource-adapter".i.e.jta=true/false.

Definetheconfigurationpropertiesina"ra.xml"fileDefinea"ra.xml"filein"META-INF"directoryofyourRARfile.Anexamplefileisprovidedinra.xmlfileTemplate.


204

ForeveryattributedefinedinsidetheyourManagedConnectionFactoryclass,definethefollowingXMLconfigurationforthatattributeinsidethe"ra.xml"file.ThesepropertiesareusedbyusertoconfigureinstanceofthisConnectorinsideaContainer.Also,duringthestartuptheContainerreadsthesepropertiesfromthisfileandknowshowtoinjectprovidedvaluesinthe"-ds.xml"fileintoainstanceof"ManagedConnectionFactory"tocreatetheConnection.RefertoDevelopingJEEConnectors#DefineManagedConnectionFactory.

<config-property>

<description>

{$display:"${display-name}",$description:"${description}",$allowed="${allowed}",

$required="${true|false}",$defaultValue="${default-value}"}

</description>

<config-property-name>${property-name}</config-property-name>

<config-property-type>${property-type}</config-property-type>

<config-property-value>${optioal-property-value}</config-property-value>

</config-property>

Theformatandcontentsof"<description>"elementmaybeusedasextendedmetadatafortooling.Thespecialformatmustbeginandendwithcurlybracese.g.\{…}.Thisuseofthespecialformatandallpropertiesisoptional.Propertynamesbeginwith'$'andareseparatedfromthevaluewith':'.Doublequotesidentifiesasinglevalue.Apairofsquarebrackets,e.g.[…],containingcommaseparateddoublequotedentriesdenotesalistvalue.

Extendedmetadataproperties

$display:Displaynameoftheproperty

$description:Descriptionabouttheproperty

$required:Thepropertyisarequiredproperty;oroptionalandadefaultissupplied

$allowed:Ifpropertyvaluemustbeincertainsetoflegalvalues,thisdefinesalltheallowedvalues

$masked:Thetoolsneedtomasktheproperty;Donotshowinplaintext;usedforpasswords

$advanced:NotesthisasAdvancedproperty

$editable:Propertycanbemodified;orread-only

Notethatalltheseareoptionalproperties;howeverintheabsenceofthismetadata,Teiidtoolingmaynotworkasexpected.


205

ra.xmlfileTemplateThisappendixcontainsanexampleofthera.xmlfilethatcanbeusedasatemplatewhencreatinganewConnector.


<connectorxmlns="http://java.sun.com/xml/ns/j2ee"


xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee

http://java.sun.com/xml/ns/j2ee/connector_1_5.xsd"version="1.5">

<vendor-name>${comapany-name}</vendor-name>

<eis-type>${type-of-connector}</eis-type>

<resourceadapter-version>1.0</resourceadapter-version>

<license>

<description>${licensetext}</description>

<license-required>true</license-required>

</license>

<resourceadapter>

<resourceadapter-class>org.teiid.resource.spi.BasicResourceAdapter</resourceadapter-class>

<outbound-resourceadapter>

<connection-definition>

<managedconnectionfactory-class>${connection-factory}</managedconnectionfactory-class>



<config-property>

<description>

{$display:"${short-name}",$description:"${description}",$allowed:[${value-list}],

$required:"${required-boolean}",$defaultValue:"${default-value}"}

</description>

<config-property-name>${property-name}</config-property-name>

<config-property-type>${property-type}</config-property-type>

<config-property-value>${optional-property-value}</config-property-value>

</config-property>



<connectionfactory-interface>

javax.resource.cci.ConnectionFactory

</connectionfactory-interface>

<connectionfactory-impl-class>

org.teiid.resource.spi.WrappedConnectionFactory

</connectionfactory-impl-class>

<connection-interface>

javax.resource.cci.Connection

</connection-interface>

<connection-impl-class>

org.teiid.resource.spi.WrappedConnection

</connection-impl-class>



<authentication-mechanism>

<authentication-mechanism-type>BasicPassword</authentication-mechanism-type>

<credential-interface>

javax.resource.spi.security.PasswordCredential

</credential-interface>

</authentication-mechanism>

<reauthentication-support>false</reauthentication-support>

</outbound-resourceadapter>


206

</resourceadapter>

</connector>

$\{…}indicatesavaluetobesuppliedbythedeveloper.


207

PackagingtheAdapterOncealltherequiredcodeisdeveloped,itistimetopackagethemintoaRARartifact,thatcanbedeployedintoaContainer.ARARartifactissimilartoaWAR.ToputtogetheraRARfileitreallydependsuponthebuildsystemyouareusing.

Eclipse:YoucanstartoutwithbuildingJavaConnectorproject,itwillproducetheRARfile

Ant:Ifyouareusing"ant"buildtool,thereis"rar"buildtaskavailable

Maven:Ifyouareusingmaven,use<packaging>elementvalueas"rar".Teiidusesmaven,youcanlookatanyofthe"connector"projectsforsample"pom.xml"file.SeeBuildEnvironmentforanexampleofapom.xmlfile.

MakesurethattheRARfile,underits"META-INF"directoryhasthe"ra.xml"file.Ifyouareusingmavenrefertohttp://maven.apache.org/plugins/maven-rar-plugin/.IntherootoftheRARfile,youcanembedtheJARfilecontainingyourconnectorcodeandanydependentlibraryJARfiles.

PackagingtheAdapter

208

http://maven.apache.org/plugins/maven-rar-plugin/

AddingDependentLibrariesAddMANIFEST.MFfileintheMETA-INFdirectory,andthefollowinglinetoaddthecoreTeiidAPIdependenciesforresourceadapter.

Dependencies:org.jboss.teiid.common-core,org.jboss.teiid.api,javax.api

Ifyourresourceadapterdependsuponanyotherthirdpartyjarfiles,.dllor.sofilestheycanbeplacedattherootoftherarfile.IfanyoftheselibrariesarealreadyavailableasmodulesinWildFly,thenyoucanaddthemodulenametotheaboveMANIFEST.MFfiletodefineasdependency.

PackagingtheAdapter

209

DeployingtheAdapterOncetheRARfileisbuilt,deployitbycopyingtheRARfileinto"deploy"directoryofWildFly’schosenprofile.TypicallytheserverdoesnotneedtoberestartedwhenanewRARfileisbeingadded.Alternatively,youcanalsouse"admin-console",awebbasedmonitoringandconfigurationtool,todeploythisfileintothecontainer.

OncetheConnector’sRARfileisdeployedintotheWildFlycontainer,nowyoucancreateaninstanceofthisconnectortobeusedwithyourTranslator.CreatinganinstanceofthisConnectorisnodifferentthancreatinga"ConnectionFactory"inWildFly.Again,youhavetwowaystocreatea""ConnectionFactory".

Editstandalone.xmlordomain.xmlfile,andaddfollowingXMLinthe"resource-adapters"subystem.



<subsystemxmlns="urn:jboss:domain:resource-adapters:1.0">

<resource-adapters>

<resource-adapter>

<archive>teiid-connector-sample.rar</archive>



<connection-definitionclass-name="org.teiid.resource.adapter.MyManagedConnectionFactory"jndi

-name="${jndi-name}"

enabled="true"

use-java-context="true"

pool-name="sample-ds">

<config-propertyname="UserName">jdoe</config-property>

<config-propertyname="Count">12</config-property>



</resource-adapter>

</resource-adapters>

</subsystem>

Therearelotmorepropertiesthatyoucandefineforpooling,transactions,security,etc.,inthisfile.ChecktheWildFlydocumentationforalltheavailableproperties.

Alternatively,youcanusethewebbased""admin-console"configurationandmonitoringprogram,tocreateanewConnectionFactory.HaveyourRARfilenameandneededconfigurationpropertieshandyandfilloutwebformtocreatetheConnectionFactory.

DeployingtheAdapter

210

Translator(Custom)DevelopmentBelowarethehigh-levelstepsforcreatingcustomTranslators,whichisdescribedinthissection.Thissectionwillcoverhowtodoeachofthefollowingstepsindetail.Italsoprovidesadditionalinformationforadvancedtopics,suchasstreaminglargeobjects.

ForsampleTranslatorcode,refertotheTeiidsourcecodeathttps://github.com/teiid/teiid/tree/master/connectors/.

1. CreateaneworreuseanexistingResourceAdapterfortheEISsystem,tobeusedwiththisTranslator.RefertoCustomResourceAdapters.

2. DecidewhethertousetheTeiidarchetypetemplatetocreateyourinitialcustomtranslatorprojectandclassesormanuallycreateyourenvironment.RefertoEnvironmentSetup.

3. ImplementtherequiredclassesdefinedbytheTranslatorAPI.RefertoImplementingtheFramework.1)CreateanExecutionFactory–Extendtheorg.teiid.translator.ExecutionFactoryclass2)CreaterelevantExecutions(andsub-interfaces)–specifieshowtoexecuteeachtypeofcommand

4. Definethetemplateforexposingconfigurationproperties.RefertoPackaging.

5. DeployyourTranslator.RefertoDeployment.

6. DeployaVirtualDatabase(VDB)thatusesyourTranslator.

7. ExecutequeriesviaTeiid.

TranslatorDevelopment

211

https://github.com/teiid/teiid/tree/master/connectors/

EnvironmentSetupTosetuptheenvironmentfordevelopingacustomtranslator,youhave2options;1)manuallysetupthebuildenvironment,structureandframeworkclassesandresourcesor2)usetheTeiidTranslatorArchetypetemplatetogeneratetheinitialproject.

EnvironmentSetup

212

SettingupthebuildenvironmentForEclipseusers(withoutmavenintegration),createajavaprojectandadddependenciesto"teiid-common-core","teiid-api"andJEE"connector-api"jars.

Formavenusersaddthefollowingasyourdependencies:

<dependencies>

<dependency>



<version>${teiid-version}</version>


</dependency>

<dependency>



<version>${teiid-version}</version>


</dependency>

<dependency>

<groupId>javax.resource</groupId>

<artifactId>connector-api</artifactId>

<version>${version.connector.api}</version>


</dependency>

</dependencies>

Wherethe${teiid-version}propertyshouldbesettotheexpectedversion,suchas9.0.0.Final.YoucanfindTeiidartifactsintheJBossmavenrepository.The$\{version.connector.api}versionlastusedwas1.5.

EnvironmentSetup

213


ArchetypeTemplateTranslatorProjectOnewaytostartdevelopingacustomtranslatoristocreateaprojectusingtheTeiidarchetypetemplate.Whentheprojectiscreatedfromthetemplate,itwillcontaintheessentialclasses(i.e.,ExecutionFactory)andresourcesforyoutobeginaddingyourcustomlogic.Additionally,themavendependenciesaredefinedinthepom.xmlsothatyoucanbegincompilingtheclasses.

Note Theprojectwillbecreatedasanindependentprojectandhasnoparentmavendependencies.It’sdesignedtobebuiltindependentofbuildingTeiid.

Youhave2optionsforcreatingatranslatorproject;inEclipsebycreatinganewmavenprojectfromthearchetypeorbyusingthecommandlinetogeneratetheproject.

CreateProjectinEclipseTocreateaJavaprojectinEclipsefromanarchetype,performthefollowing:

OpentheJAVAperspective

FromthemenuselectFile–>New—>Other

Inthetree,expandMavenandselectMavenProject,pressNext

Onthe"SelectprojectnameandLocation"window,youcanacceptthedefaults,pressNext

Onthe"SelectanArchetype"window,selectConfigurebutton

Addtheremotecatalog:https://repository.jboss.org/nexus/content/repositories/releases/thenclickOKtoreturn

Enter"teiid"inthefiltertoseetheTeiidarchetypes.

Selectthetranslator-archetypev8.7.1,thenpressNext

Enteralltheinformation(i.e.,GroupID,ArtifactID,etc.)neededtogeneratetheproject,thenclickFinish

Theprojectwillbecreatedandnameaccordingtothe*ArtifactID*.

CreateProjectusingCommandLine

Tocreateacustomtranslatorprojectfromthecommandline,youcanusethefollowingtemplatecommand:

mvnarchetype:generate\

-DarchethypeRepository=https://repository.jboss.org/nexus/content/repositories/releases/\


-DarchetypeArtifactId=translator-archetype\


-DgroupId=${groupId}\

-DartifactId=translator-${translator-name}\

-Dpackage=org.teiid.translator.${translator-name}\

-Dversion=${version}\

-Dtranslator-name=${translator-name}\

-Dteiid-version=${teiid-version}

where:

-DarchetypeGroupId-isthegroupIDforthearchetypetousetogenerate

-DarchetypeArtifactId-istheartifactIDforthearchetypetousetogenerate

EnvironmentSetup

214

https://repository.jboss.org/nexus/content/repositories/releases/

-DarchetypeVersion-istheversionforthearchetypetousetogenerate

-DgroupId-(userdefined)groupIDforthenewtranslatorprojectpom.xml

-DartifactId-(userdefined)artifactIDforthenewtranslatorprojectpom.xml

-Dpackage-(userdefined)thepackagestructurewherethejavaandresourcefileswillbecreated

-Dversion-(userdefined)theversionthatthenewconnectorprojectpom.xmlwillbe

-Dtranslator-name-(userdefined)thename(type)ofthenewtranslatorproject,usedtocreatethejavacl

assnames

-Dteiid-version-theTeiidversiontheconnectorwilldependupon

Thefollowingisanexampletoexecute:

mvnarchetype:generate\

-DarchethypeRepository=https://repository.jboss.org/nexus/content/repositories/releases/\


-DarchetypeArtifactId=translator-archetype\


-DgroupId=org.jboss.teiid.connector\

-DartifactId=translator-myType\

-Dpackage=org.teiid.translator.myType\

-Dversion=0.0.1-SNAPSHOT\

-Dtranslator-name=MyType\

-Dteiid-version=8.7.0.Final

Whenexecuted,youwillbeaskedtoconfirmtheproperties

Confirmpropertiesconfiguration:

groupId:org.jboss.teiid.connector

artifactId:translator-myType

version:0.0.1-SNAPSHOT

package:org.teiid.translator.myType

teiid-version:8.7.0.Final

translator-name:MyType

Y::

typeY(yes)andpressenter,andthecreationofthetranslatorprojectwillbedone

Uponcreation,adirectorybasedonthe*artifactId*willbecreated,thatwillcontaintheproject.'cd'intothatdirectoryandexecuteatestbuildtoconfirmtheprojectwascreatedcorrectly:

mvncleaninstall

Thisshouldbuildsuccessfully,andnowyouarereadytostartaddingyourcustomcode.

EnvironmentSetup

215



216

CachingAPITranslatorsmaycontributecacheentriestotheresultsetcachebytheuseoftheCacheDirectiveobject.TranslatorswishingtoparticipateincachingshouldreturnaCacheDirectivefromtheExecutionFactory.getCacheDirectivemethod,whichiscalledpriortoexecution.ThecommandpassedtogetCacheDirectivewillalreadyhavebeenvettedtoensurethattheresultsareeligibleforcaching.Forexampleupdatecommandsorcommandswithpusheddependentsetswillnotbeeligibleforcaching.

IfthetranslatorreturnsnullfortheCacheDirective,whichisthedefaultimplementation,theenginewillnotcachethetranslatorresultsbeyondthecurrentcommand.Itisuptoyourcustomtranslatororcustomdelegatingtranslatortoimplementyourdesiredcachingpolicy.

Note Inspecialcircumstanceswherethetranslatorhasperformedit’sowncaching,itcanindicatetotheenginethattheresultsshouldnotbecachedorreusedbysettingtheScopetoScope.NONE.

ThereturnedCacheDirectivewillbesetontheExecutionContextandisavailableviatheExecutionContext.getCacheDirective()method.HavingExeuctionFactory.getCacheDirectivecalledpriortoexecutionallowsthetranslatortopotentiallybeselectiveaboutwhichresultstoevenattempttocache.Sincethereisaresourceoverheadwithcreatingandstoringthecachedresultsitmaynotbedesirabletoattempttocacheallresultsifit’spossibletoreturnlargeresultsthathavealowusagefactor.IfyouareunsureaboutwhethertocacheaparticularcommandresultyoumayreturnaninitialCacheDirectivethenchangetheScopetoScope.NONEatanytimepriortothefinalcacheentrybeingcreatedandtheenginewillgiveupcreatingtheentryandreleaseit’sresources.

IfyouplanonmodifyingtheCacheDirectiveduringexecution,justmakesuretoreturnanewinstancefromtheExecutionFactory.getCacheDirectivecall,ratherthanreturningasharedinstance.

TheCacheDirectivereadAllBooleanfieldisusedtocontrolwhethertheentireresultshouldbereadifnotalloftheresultswereconsumedbytheengine.IfreadAllisfalsethenanypartialusageoftheresultwillnotresultinitbeingaddedasacacheentry.Partialuseisdeterminedafteranyimplicitorexplicitlimithasbeenapplied.TheotherfieldsontheCacheDirectiveobjectmaptothecachehintoptions.Seethetablebelowforthedefaultvaluesforalloptions.

option default

scope Session

ttl rscachettl

readAll true

updatable true

prefersMemory false


217

CommandLanguage

Language

TeiidsendscommandstoyourTranslatorinobjectform.Theseclassesarealldefinedinthe"org.teiid.language"package.TheseobjectscanbecombinedtorepresentanypossiblecommandthatTeiidmaysendtotheTranslator.However,itispossibletonotifyTeiidthatyourTranslatorcanonlyacceptcertainkindsofconstructsviathecapabilitiesdefinedonthe"ExecutionFactory"class.RefertoTranslatorCapabilitiesformoreinformation.

ThelanguageobjectsallextendfromtheLanguageObjectinterface.Languageobjectsshouldbethoughtofasatreewhereeachnodeisalanguageobjectthathaszeroormorechildlanguageobjectsoftypesthataredependentonthecurrentnode.

AllcommandssenttoyourTranslatorareintheformoftheselanguagetrees,wheretherootofthetreeisasubclassofCommand.Commandhasseveralsub-interfaces,namely:

QueryExpression

Insert

Update

Delete

BatchedUpdates

Call

Importantcomponentsofthesecommandsareexpressions,criteria,andjoins,whichareexaminedincloserdetailbelow.Formoreontheclassesandinterfacesdescribedhere,refertotheTeiidJavaDocshttp://docs.jboss.org/teiid/7.6/apidocs.

ExpressionsAnexpressionrepresentsasinglevalueincontext,althoughinsomecasesthatvaluemaychangeasthequeryisevaluated.Forexample,aliteralvalue,suchas5representsanintegervalue.Ancolumnreferencesuchas"table.EmployeeName"representsacolumninadatasourceandmaytakeonmanyvalueswhilethecommandisbeingevaluated.

Expression–baseexpressioninterface

ColumnReference–representsancolumninthedatasource

Literal–representsaliteralscalarvalue.

Parameter–representsaparameterwithmultiplevalues.ThecommandshouldbeaninstanceofBatchedCommand,whichprovidesallvaluesviagetParameterValues.

Function–representsascalarfunctionwithparametersthatarealsoExpressions

AggregateFunction–representsanaggregatefunctionwhichcanholdasingleexpression

WindowFunction–representsanwindowfunctionwhichholdsanAggregateFunction(whichisalsousedtorepresentanalyticalfunctions)andaWindowSpecification

ScalarSubquery–representsasubquerythatreturnsasinglevalue

SearchedCase,SearchedWhenClause–representsasearchedCASEexpression.ThesearchedCASEexpressionevaluatesthecriteriainWHENclausestilloneevaluatestoTRUE,thenevaluatestheassociatedTHENclause.


218

http://docs.jboss.org/teiid/7.6/apidocs

Array–representsanarrayofexpressions,currentlyonlyusedbytheengineinmulti-attributedependentjoins-seethesupportsArrayTypecapability.

Condition

Acriteriaisacombinationofexpressionsandoperatorsthatevaluatestotrue,false,orunknown.CriteriaaremostcommonlyusedintheWHEREorHAVINGclauses.

Condition–thebasecriteriainterface

Not–usedtoNOTanothercriteria

AndOr–usedtocombineothercriteriaviaANDorOR

SubuqeryComparison–representsacomparisoncriteriawithasubqueryincludingaquantifiersuchasSOMEorALL

Comparison–representsacomparisoncriteriawith=,>,<,etc.

BaseInCondition–baseclassforanINcriteria

In–representsanINcriteriathathasasetofexpressionsforvalues

SubqueryIn–representsanINcriteriathatusesasubquerytoproducethevalueset

IsNull–representsanISNULLcriteria

Exists–representsanEXISTScriteriathatdetermineswhetherasubquerywillreturnanyvalues

Like–representsaLIKE/SIMILARTO/LIKE_REGEXcriteriathatcomparesstringvalues

TheFROMClause

TheFROMclausecontainsalistofTableReference’s.

NamedTable–representsasingleTable

Join–hasaleftandrightTableReferenceandinformationonthejoinbetweentheitems

DerivedTable–representsatabledefinedbyaninlineQueryExpression

AlistofTableReferenceareusedbydefault,inthepushdownquerywhennoouterjoinsareused.Ifanouterjoinisusedanywhereinthejointree,therewillbeatreeofJoinswithasingleroot.ThislatterformistheANSIpreferredstyle.IfyouwishallpushdownqueriescontainingjoinstobeinANSIstylehavethecapability"useAnsiJoin"returntrue.RefertoCommandFormformoreinformation.

QueryExpressionStructure

QueryExpressionisthebaseforbothSELECTqueriesandsetqueries.ItmayoptionallytakeanOrderBy(representingaSQLORDERBYclause),aLimit(representaSQLLIMITclause),oraWith(representsaSQLWITHclause).

SelectStructure

EachQueryExpressioncanbeaSelectdescribingtheexpressions(typicallyelements)beingselectedandanTableReferencespecifyingthetableortablesbeingselectedfrom,alongwithanyjoininformation.TheSelectmayoptionallyalsosupplyanCondition(representingaSQLWHEREclause),aGroupBy(representingaSQLGROUPBY


219

clause),ananCondition(representingaSQLHAVINGclause).

SetQueryStructure

AQueryExpressioncanalsobeaSetQuerythatrepresentsonoftheSQLsetoperations(UNION,INTERSECT,EXCEPT)ontwoQueryExpression.TheallflagmaybesettoindicateUNIONALL(currentlyINTERSECTandEXCEPTALLarenotallowedinTeiid)

WithStructure

AWithclausecontainsnamedQueryExpressionsheldbyWithItemsthatcanbereferencedastablesinthemainQueryExpression.

InsertStructure

EachInsertwillhaveasingleNamedTablespecifyingthetablebeinginsertedinto.ItwillalsohasalistofColumnReferencespecifyingthecolumnsoftheNamedTablethatarebeinginsertedinto.ItalsohasInsertValueSource,whichwillbealistofExpressions(ExpressionValueSource)oraQueryExpression

UpdateStructure

EachUpdatewillhaveasingleNamedTablespecifyingthetablebeingupdatedandlistofSetClauseentriesthatspecifyColumnReferenceandExpressionpairsfortheupdate.TheUpdatemayoptionallyprovideacriteriaConditionspecifyingwhichrowsshouldbeupdated.

DeleteStructure

EachDeletewillhaveasingleNamedTablespecifyingthetablebeingdeletedfrom.Itmayalsooptionallyhaveacriteriaspecifyingwhichrowsshouldbedeleted.

CallStructure

EachCallhaszeroormoreArgumentobjects.TheArgumentobjectsdescribetheinputparameters,theoutputresultset,andtheoutputparameters.

BatchedUpdatesStructure

EachBatchedUpdateshasalistofCommandobjects(whichmustbeeitherInsert,UpdateorDelete)thatcomposethebatch.

LanguageUtilities

Thissectioncoversutilitiesavailablewhenusing,creating,andmanipulatingthelanguageinterfaces.


220

DataTypes

TheTranslatorAPIcontainsaninterfaceTypeFacilitythatdefinesdatatypesandprovidesvaluetranslationfacilities.Thisinterfacecanbeobtainedfromcalling"getTypeFacility()"methodonthe"ExecutionFactory"class.

TheTypeFacitlityinterfacehasmethodsthatsupportdatatypetransformationanddetectionofappropriateruntimeorJDBCtypes.TheTypeFacility.RUNTIME_TYPESandTypeFacility.RUNTIME_NAMESinterfacesdefinesconstantsforallTeiidruntimedatatypes.AllExpressioninstancesdefineadatatypebasedonthissetoftypes.Theseconstantsareoftenneededinunderstandingorcreatinglanguageinterfaces.

LanguageManipulationInTranslatorsthatsupportafullersetofcapabilities(thosethatgenerallyaretranslatingtoalanguageofcomparabletoSQL),thereisoftenaneedtomanipulateorcreatelanguageinterfacestomoveclosertothesyntaxofchoice.Someutilitiesareprovidedforthispurpose:

SimilartotheTypeFacility,youcancall"getLanguageFactory()"methodonthe"ExecutionFactory"togetareferencetotheLanguageFactoryinstanceforyourtranslator.Thisinterfaceisafactorythatcanbeusedtocreatenewinstancesofalltheconcretelanguageinterfaceobjects.

SomehelpfulutilitiesforworkingwithConditionobjectsareprovidedintheLanguageUtilclass.ThisclasshasmethodstocombineConditionwithANDortobreakanConditionapartbasedonANDoperators.Theseutilitiesarehelpfulforbreakingapartacriteriaintoindividualfiltersthatyourtranslatorcanimplement.

RuntimeMetadataTeiidusesalibraryofmetadata,knownas"runtimemetadata"foreachvirtualdatabasethatisdeployedinTeiid.TheruntimemetadataisasubsetofmetadataasdefinedbymodelsintheTeiidmodelsthatcomposethevirtualdatabase.WhilebuilingyourVDBintheDesigner,youcandefinewhatcalled"ExtensionModel",thatdefinesanynumberofarbitarypropertiesonamodelanditsobjects.Atruntime,usingthisruntimemetadatainterface,yougetaccesstothosesetpropertiesdefinedduringthedesigntime,todefine/hintanyexecutionbehavior.

TranslatorgetsaccesstotheRuntimeMetadatainterfaceatthetimeofExcecutioncreation.Translatorscanaccessruntimemetadatabyusingtheinterfacesdefinedinorg.teiid.metadatapackage.ThispackagedefinesAPIrepresentingaSchema,Table,ColumnsandProcedures,andwaystonavigatetheseobjects.

MetadataObjects

AllthelanguageobjectsextendAbstractMetadataRecordclass

Column-returnsColumnmetadatarecord

Table-returnsaTablemetadatarecord

Procedure-returnsaProceduremetadatarecord

ProcedureParameter-returnsaProcedureParametermetadatarecord

Onceametadatarecordhasbeenobtained,itispossibletouseitsmetadataaboutthatobjectortofindotherrelatedmetadata.

AccesstoRuntimeMetadata


221

TheRuntimeMetadatainterfaceispassedinforthecreationofan"Execution".See"createExecution"methodonthe"ExecutionFactory"class.ItprovidestheabilitytolookupmetadatarecordsbasedontheirfullyqualifiednamesintheVDB.

TheprocessofgettingaTable’spropertiesissometimesneededfortranslatordevelopment.Forexampletogetthe"NameInSource"propertyorallextensionproperties:

ObtainingMetadataProperties

//gettingtheTablemetadatafromanTableisstraight-forward

Tabletable=runtimeMetadata.getTable("table-name");

StringcontextName=table.getNameInSource();

//Thepropswillcontainextensionproperties

Map<String,String>props=table.getProperties();

LanguageVisitors

Framework

TheAPIprovidesalanguagevisitorframeworkintheorg.teiid.language.visitorpackage.Theframeworkprovidesutilitiesusefulinnavigatingandextractinginformationfromtreesoflanguageobjects.

ThevisitorframeworkisavariantoftheVisitordesignpattern,whichisdocumentedinseveralpopulardesignpatternreferences.Thevisitorpatternencompassestwoprimaryoperations:traversingthenodesofagraph(alsoknownasiteration)andperformingsomeactionateachnodeofthegraph.Inthiscase,thenodesarelanguageinterfaceobjectsandthegraphisreallyatreerootedatsomenode.Theprovidedframeworkallowsforcustomizationofbothaspectsofvisiting.

ThebaseAbstractLanguageVisitorclassdefinesthevisitmethodsforallleaflanguageinterfacesthatcanexistinthetree.TheLanguageObjectinterfacedefinesanacceptVisitor()method–thismethodwillcallbackonthevisitmethodofthevisitortocompletethecontract.AbaseclasswithemptyvisitmethodsisprovidedasAbstractLanguageVisitor.TheAbstractLanguageVisitorisjustavisitorshell–itperformsnoactionswhenvisitingnodesanddoesnotprovideanyiteration.

TheHierarchyVisitorprovidesthebasiccodeforwalkingalanguageobjecttree.TheHierarchyVisitorperformsnoactionasitwalksthetree–itjustencapsulatestheknowledgeofhowtowalkit.Ifyourtranslatorwantstoprovideacustomiterationthatwalkstheobjectsinaspecialorder(toexcludenodes,includenodesmultipletimes,conditionallyincludenodes,etc)thenyoumusteitherextendHierarchyVisitororbuildyourowniterationvisitor.Ingeneral,thatisnotnecessary.

TheDelegatingHierarchyVisitorisaspecialsubclassoftheHierarchyVisitorthatprovidestheabilitytoperformadifferentvisitor’sprocessingbeforeandafteriteration.Thisallowsusersofthisclasstoimplementeitherpre-orpost-orderprocessingbasedontheHierarchyVisitor.TwohelpermethodsareprovidedonDelegatingHierarchyVisitortoaidinexecutingpre-andpost-ordervisitors.

ProvidedVisitorsTheSQLStringVisitorisaspecialvisitorthatcantraverseatreeoflanguageinterfacesandoutputtheequivalentTeiidSQL.Thisvisitorcanbeusedtoprintlanguageobjectsfordebuggingandlogging.TheSQLStringVisitordoesnotusetheHierarchyVisitordescribedinthelastsection;itprovidesbothiterationandprocessingtypefunctionalityinasinglecustomvisitor.

TheCollectorVisitorisahandyutilitytocollectalllanguageobjectsofacertaintypeinatree.Someadditionalhelpermethodsexisttodocommontaskssuchasretrievingallelementsinatree,retrievingallgroupsinatree,andsoon.

WritingaVisitor


222

Writingyourownvisitorcanbequiteeasyifyouusetheprovidedfacilities.Ifthenormalmethodofiteratingthelanguagetreeissufficient,thenjustfollowthesesteps:

CreateasubclassofAbstractLanguageVisitor.Overrideanyvisitmethodsneededforyourprocessing.Forinstance,ifyouwantedtocountthenumberofelementsinthetree,youneedonlyoverridethevisit(ColumnReference)method.Collectanystateinlocalvariablesandprovideaccessormethodsforthatstate.

Decidewhethertousepre-orderorpost-orderiteration.NotethatvisitationorderisbaseduponsyntaxorderingofSQLclauses-notprocessingorder.

WritecodetoexecuteyourvisitorusingtheutilitymethodsonDelegatingHierarchyVisitor:

//Getobjecttree

LanguageObjectobjectTree=…

//Createyourvisitorinitializeasnecessary

MyVisitorvisitor=newMyVisitor();

//Callthevisitorusingpre-ordervisitation

DelegatingHierarchyVisitor.preOrderVisit(visitor,objectTree);

//Retrievestatecollectedwhilevisiting

intcount=visitor.getCount();


223

ConnectionstoSource

Obtainingconnections

Theextended"ExecutionFactory"mustimplementthegetConnection()methodtoallowtheConnectorManagertoobtainaconnection.

ReleasingConnections

OncetheConnectorManagerhasobtainedaconnection,itwillusethatconnectiononlyforthelifetimeoftherequest.Whentherequesthascompleted,thecloseConnection()methodcalledonthe"ExecutionFactory".Youmustalsooverridethismethodtoproperlyclosetheconnection.

Incases(suchaswhenaconnectionisstatefulandexpensivetocreate),connectionsshouldbepooled.IftheresourceadapterisJEEJCAconnectorbased,thenpoolingisautomaticallyprovidedbytheWildFlycontainer.IfyourresourceadapterdoesnotimplementtheJEEJCA,thenconnectionpoolingsemanticsarelefttotheusertodefineontheirown.


224

DependentJoinPushdownDependentjoinsareatechniqueusedinfederationtoreducethecostofcrosssourcejoins.Joinvaluesfromonesideofajoinaremadeavailabletotheothersidewhichreducesthenumberoftuplesneededtopreformthejoin.TranslatorsmayindicatesupportfordependentjoinpushdownviathesupportsDependentJoinandsupportsFullDependentJoincapabilities.Thehandlingofpushdowndependentjoinqueriescanbecomplicated.

Note SeetheJDBCTranslatorforthereferenceimplementationofdependentjoinpushdownhandlingbasedupthecreationtemporarytables.

KeyPushdown

Themoresimplisticmodeofdependentjoinpushdownistopushonlythekey(equi-join)valuestoeffectivelyevaluateasemi-join-thefulljoinwillstillbeprocessedbytheengineaftertheretrieval.Theordering(ifpresent)andallofthenon-dependentcriteriaconstructsonthepushdowncommandmustbehonored.Thedependentcriteria,whichwillbeaComparisonwithaParameter(possiblyinArrayform),maybeignoredinpartorintotaltoretrieveasupersetofthetuplesrequested.

PushdownkeydependentjoinquerieswillbeinstancesofSelectwiththerelevantdependentvaluesavailableviaSelect.getDependentValues().AdependentvaluetuplelistisassociatedtoParametersbyidviatheParameter.getDepenentValueId()identifier.Thedependenttuplelistproviderowsthatarereferencedbythecolumnpositions(availableviaParameter.getValueIndex()).Careshouldbetakenwiththetuplevaluesastheymayguaranteedtobeordered,butwillbeuniquewithrespecttoalloftheParameterreferencesagainstthegivendependentvaluetuplelist.

FullPushdownInsomescenarios,typicallywithsmallindependentdatasetsorextensiveprocessingabovethejointhatcanbepushedtothesource,itisadvantageousforthesourcetohandlethedependentjoinpushdown.ThisfeatureismarkedassupportedbythesupportsFullDependentJoincapability.Herethesourceisexpectedtoprocessthecommandexactlyasspecified-thedependentjoinisnotoptional

FullpushdowndependentjoinquerieswillbeinstancesofQueryExpressionwiththerelevantdependentvaluesavailableviaspecialcommontabledefinitionsusingQueryExpression.getWith().TheindependentsideofafullpushdownjoinwillappearasacommontableWithItemwithadependentvaluetuplelistavailableviaWithItem.getDependentValues().ThedependentvaluetupleswillpositionallymatchthecolumnsdefinedbyWithItem.getColumns().Thedependentvaluetuplelistisnotguaranteedtobeinanyparticularorder.


225

ExecutingCommands

ExecutionModes

TheTeiidqueryengineusesthe"ExecutionFactory"classtoobtainthe"Execution"interfaceforthecommanditisexecuting.Theactualqueriesthemselvesaresenttotranslatorsintheformofasetofobjects,whicharefurtherdescribedinCommandLanguage.RefertoCommandLanguage.Translatorsareallowedtosupportanysubsetoftheavailableexecutionmodes.

ExecutionInterface Commandinterface(s) Description

ResultSetExecution QueryExpressionAquerycorrespondingtoaSQLSELECTorsetquerystatement.

UpdateExecutionInsert,Update,Delete,

BatchedUpdates

Aninsert,update,ordelete,correspondingtoaSQLINSERT,UPDATE,orDELETEcommand

ProcedureExecution Call

Aprocedureexecutionthatmayreturnaresultsetand/oroutputvalues.

TypesofExecutionModes

AlloftheexecutioninterfacesextendthebaseExecutioninterfacethatdefineshowexecutionsarecancelledandclosed.ProcedureExecutionalsoextendsResultSetExecution,sinceproceduresmayalsoreturnresultsets.

ExecutionContext

Theorg.teiid.translator.ExecutionContextprovidesaconsiderableamountofinformationrelatedtothecurrentexecution.AnExecutionContextinstanceismadeavailabletoeachExecution.Specificusageishighlightedinthisguidewhereapplicable,butyoumayuseanyinformationalgettermethodasdesired.ExampleusagewouldincludecallingExecutionContext.getRequestId(),ExecutionContext.getSession(),etc.forloggingpurposes.

CommandContext

Aorg.teiid.CommandContextisavailableviatheExecutionContext.getCommandContext()method.TheCommandContextcontainsinformationaboutthecurrentuserquery,includingtheVDB,theabilitytoaddclientwarnings-addWarning,orhandlegeneratedkeys-isReturnAutoGeneratedKeys,returnGeneratedKeys,andgetGeneratedKeys.

GeneratedKeys

Toseeiftheuserqueryexpectsgeneratedkeystobereturned,consulttheCommandContext.isReturnAutoGeneratedKeys()method.Ifyouwishtoreturngeneratedkeys,youmustfirstcreateaGeneratedKeysinstancetoholdthekeyswiththereturnGeneratedKeysmethodpassingthecolumnnamesandtypesofthekeycolumns.OnlyoneGeneratedKeysmaybeassociatedwiththeCommandContextatanygiventime.

SourceHints


226

TheTeiidsourcemeta-hintisusedtoprovidehintsdirectlytosourceexecutionsviauserortransformationqueries.Seethereferenceformoreonsourcehints.Ifspecifiedandapplicable,thegeneralandsourcespecifichintwillbesuppliedviatheExecutionContextmethodsgetGeneralHintandgetSourceHint.SeethesourcefortheOracleExecutionFactoryforanexampleofhowthissourcehintinformationcanbeutilized.

ResultSetExecution

TypicallymostcommandsexecutedagainsttranslatorsareQueryExpression.Whilethecommandisbeingexecuted,thetranslatorprovidesresultsviatheResultSetExecution’s"next"method.The"next"methodshouldreturnnulltoindicatetheendofresults.Note:theexpectedbatchsizecanbeobtainedfromtheExecutionContext.getBatchSize()methodandusedasahintinfetchingresultsfromtheEIS.

UpdateExecution

Eachexecutionreturnstheupdatecount(s)expectedbytheupdatecommand.IfpossibleBatchedUpdatesshouldbeexecutedatomically.TheExecutionContext.isTransactional()methodcanbeusedtodetermineiftheexecutionisalreadyunderatransaction.

ProcedureExecution

Procedurecommandscorrespondtotheexecutionofastoredprocedureorsomeotherfunctionalconstruct.Aproceduretakeszeroormoreinputvaluesandcanreturnaresultsetandzeroormoreoutputvalues.Examplesofprocedureexecutionwouldbeastoredprocedureinarelationaldatabaseoracalltoawebservice.

Ifaresultsetisexpectedwhenaprocedureisexecuted,allrowsfromitwillberetrievedviatheResultSetExecutioninterfacefirst.Then,ifanyoutputvaluesareexpected,theywillberetrievedviathegetOutputParameterValues()method.

AsynchronousExecutions

Insomescenarios,atranslatorneedstoexecuteasynchronouslyandallowtheexecutingthreadtoperformotherwork.Toallowasynchronousexecution,youshouldthrowaDataNotAvailableExecptionduringaretrievalmethod,ratherthanexplicitlywaitingorsleepingfortheresults.TheDataNotAvailableExceptionmaytakeadelayparameteroraDateinitsconstructortoindicatewhentopollnextforresults.Anynon-negativedelayvalueindicatesthetimeinmillisecondsuntilthenextpollingshouldbeperformed.TheDataNotAvailableException.NO_POLLINGexception(oranyDataNotAvailableExceptionwithanegativedelay)canbethrowntoindicatethattheexecutionwillcallExecutionContext.dataAvailable()toindicateprocessingshouldresume.

Note ADataNotAvailableExceptionshouldnotbethrownbytheexecutemethod,asthatcanresultintheexecutemethodbeingcalledmultipletimes.

Note Sincetheexecutionandtheassociatedconnectionarenotcloseduntiltheworkhascompleted,careshouldbetakenifusingasynchronousexecutionsthatholdalotofstate.

Apositiveretrydelayisnotaguaranteeofwhenthetranslatorwillbepollednext.IftheDataNotAvailableExceptionisconsumedwhiletheenginethinksmoreworkcanbeperformedorthereareothershorterdelaysissuedfromothertranslators,thentheplanmaybere-queuedearlierthanexpected.YoushouldsimplyrethrowaDataNotAvailableExceptionifyourexecutionisnotyetready.AlternativelytheDataNotAvailableExceptionmaybemarkedasstrict,whichdoesprovideaguaranteethattheExecutionwillnotbecalleduntilthedelayhasexpiredorthegivenDatehasbeenreached.UsingtheDateconstructor


227

makestheDataNotAvailableExceptionautomaticallystrict.Duetoenginethreadpoolcontention,platformtimeresolution,etc.astrictDataNotAvailableExceptionisnotareal-timeguaranteeofwhenthenextpollforresultswilloccur,onlythatitwillnot

occurbeforethen.

NoteIfyourExecutionFactoryreturnsonlyasynchexecutionsthatperformminimalwork,thenconsiderhavingExecutionFactory.isForkablereturnfalsesothattheengineknowsnottospawnaseparatethreadforaccessingyourExecution.

ReusableExecutions

AtranslatormayreturninstancesofReusableExecutionsfortheexpectedExecutionobjects.TherecanbeoneReusableExecutionperqueryexecutingnodeintheprocessingplan.ThelifecycleofaReusableExecutionisdifferentthatanormalExecution.Afteranormalcreation/execute/closecycletheReusableExecution.resetiscalledforthenextexecutioncycle.Thismayoccurindefinitelydependingonhowmanytimesaprocessingnodeexecutesitsquery.ThebehavioroftheclosemethodisnodifferentthanaregularExecution,itmaynotbecalleduntiltheendofthestatementiflobsaredetectedandanyconnectionassociatedwiththeExecutionwillalsobeclosed.Whentheusercommandisfinished,theReusableExecution.dispose()methodwillbecalled.

IngeneralReusableExecutionsaremostusefulforcontinuousqueryexecutionandwillalsomakeuseoftheExecutionCotext.dataAvailable()methodforAsynchronousExecutions.SeetheClientDeveloper’sGuideforexecutingcontinuousstatements.Incontinuousmodetheuserquerywillbecontinuouslyre-executed.AReusableExecutionallowsthesameExecutionobjecttobeassociatedwiththeprocessingplanforagivenprocessingnodeforthelifetimeoftheuserquery.Thiscansimplifyasynchresourcemanagement,suchasestablishingqueuelisteners.Returninganullresultfromthenext()methodReusableExecutionjustaswithnormalExecutionsindicatesthatthecurrentpushdowncommandresultshaveended.Oncethereset()methodhasbeencalled,thenextsetofresultsshouldbereturnedagainterminatedwithanullresult.

BulkExecutionNonbatchedInsert,Update,Deletecommandsmayhavemulti-valuedParameterobjectsifthecapabilitiesshowssupportforBulkUpdate.Commandswithmulti-valued\{{Parameters}}srepresentmultipleexecutionsofthesamecommandwithdifferentvalues.AswithBatchedUpdates,bulkoperationsshouldbeexecutedatomicallyifpossible.

CommandCompletionAllnormalcommandexecutionsendwiththecallingofclose()ontheExecutionobject.Yourimplementationofthismethodshoulddotheappropriateclean-upworkforallstatecreatedintheExecutionobject.

CommandCancellationCommandssubmittedtoTeiidmaybeabortedinseveralscenarios:

ClientcancellationviatheJDBCAPI(orotherclientAPIs)

Administrativecancellation

Clean-upduringsessiontermination

Clean-upifaqueryfailsduringprocessingUnliketheotherexecutionmethods,whicharehandledinasingle-threadedmanner,callstocancelhappenasynchronouslywithrespecttotheexecutionthread.


228

Yourconnectorimplementationmaychoosetodonothinginresponsetothiscancellationmessage.Inthisinstance,Teiidwillcallclose()ontheexecutionobjectaftercurrentprocessinghascompleted.Implementingthecancel()methodallowsforfasterterminationofqueriesbeingprocessedandmayallowtheunderlyingdatasourcetoterminateitsoperationsfasteraswell.


229

ExtendingtheExecutionFactoryClassThemainclassinthetranslatorimplementationisExecutionFactory.AbaseclassisprovidedintheTeiidAPI,soacustomtranslatormustextendorg.teiid.translator.ExecutionFactorytoconnectandqueryanenterprisedatasource.Thisextendedclassmustprovideano-argconstructorthatcanbeconstructedusingJavareflectionlibraries.ThisExecutionFactoryneedstodefine/overridethefollowingelements.

packageorg.teiid.translator.custom;

@Translator(name="custom",description="ConnecttoMyEIS")

publicclassCustomExecutionFactoryextendsExecutionFactory<MyConnectionFactory,MyConnection>{

publicCustomExecutionFactory(){

}

}

Definetheannotation@Translatoronextended"ExecutionFactory"class.Thisannotationdefinesthename,whichisusedastheidentifierduringdeployment,andthedescriptionofyourtranslator.ThisnameiswhatyouwillbeusingintheVDBandelsewhereintheconfigurationtorefertothistranslator.

ConnectionFactoryDefinesthe"ConnectionFactory"interfacethatisdefinedinresourceadapter.Thisisdefinedaspartofclassdefinitionofextended"ExecutionFactory"class.Referto"MyConnectionFactory"sampleintheDevelopingJEEConnectorschapter.

ConnectionDefinesthe"Connection"interfacethatisdefinedintheresourceadapter.Thisisdefinedaspartofclassdefinitionofextended"ExecutionFactory"class.Referto"MyConnection"classsampleinvtheDevelopingJEEConnectorschapter.

ConfigurationPropertiesIfthetranslatorrequiresexternalconfiguration,thatdefineswaysfortheusertoalterthebehaviorofaprogram,thendefineanattributevariableintheclassanddefine"get"and"set"methodsforthatattribute.Also,annotateeach"get"methodwith@TranslatorPropertyannotationandprovidethemetadataabouttheproperty.

Forexample,ifyouneedapropertycalled"foo",byprovidingtheannotationontheseproperties,theTeiidtoolingcanautomaticallyinterrogateandprovideagraphicalwaytoconfigureyourTranslatorwhiledesigningyourVDB.

privateStringfoo="blah";

@TranslatorProperty(display="Fooproperty",description="descriptionaboutFoo")

publicStringgetFoo()

{

returnfoo;

}

publicvoidsetFoo(Stringvalue)

{

returnthis.foo=value;

}


230

The@TranslatorPropertydefinesthefollowingmetadatathatyoucandefineaboutyourproperty

display:Displaynameoftheproperty

description:Descriptionabouttheproperty

required:Thepropertyisarequiredproperty

advanced:Thisisadvancedproperty;Adefaultvaluemustbeprovided.Apropertycannotbe"advanced"and"required"atsametime.

masked:Thetoolsneedtomasktheproperty;Donotshowinplaintext;usedforpasswords

Onlyjavaprimitive(int,boolean),primitiveobjectwrapper(java.lang.Integer),orEnumtypesaresupportedasTranslatorproperties.Complexobjectsarenotsupported.Thedefaultvaluewillbederivedfromcallingthegettermethod,ifavailable,onanewlyconstructedinstance.Allpropertiesshouldhaveadefaultvalue.Ifthereisnoapplicabledefault,thenthepropertyshouldbemarkedintheannotationasrequired.Initializationwillfailifarequiredpropertyvalueisnotprovided.

InitializingtheTranslator

Overrideandimplementthestartmethod(besuretocall"super.start()")ifyourtranslatorneedstodoanyinitializingbeforeitisusedbytheTeiidengine.ThismethodwillbecalledbyTeiid,onceafteralltheconfigurationpropertiessetaboveareinjectedintotheclass.

ExtendedTranslatorCapabilities

Thesearevariousmethodsthattypicallybeginwithmethodsignature"supports"onthe"ExecutionFactory"class.ThesemethodsneedtobeoverriddentodescribetheexecutioncapabilitiesoftheTranslator.RefertoTranslatorCapabilitiesformoreonthesemethods.

Execution(andsub-interfaces)

Basedontypesofexecutionsyouaresupporting,thefollowingmethodsneedtobeoverriddentoprovideimplementationsfortheirrespectivereturninterfaces.

createResultSetExecution-Overrideifyouaredoingreadbasedoperationthatisreturningarowsofresults.Forex:select

createUpdateExecution-Overrideifyouaredoingwritebasedoperations.Forex:insert,update,delete

createProcedureExecution-Overideifyouaredoingprocedurebasedoperations.Forex;storedprocedures.Thisworkswellfornon-relationalsources.Youcanchoosetoimplementalltheexecutionmodesorjustwhatyouneed.Seemoredetailsonthisbelow.

MetadataOverrideandimplementthemethodgetMetadataProcessor(),ifyouwanttoexposethemetadataaboutthesourceforuseinVDBs.Thisdefinesthetables,columnnames,procedures,parameters,etc.foruseinthequeryengine.ThismethodisusedbyDesignertoolingwhentheTeiidConnectionimporterisused.AsampleMetadataProcessormaylooklike

publicclassMyMetadataProcessorimplementsMetadataProcessor<Connection>{

publicvoidprocess(MetadataFactorymf,Connectionconn){

Objectsomedata=connection.getSomeMetadata();


231

Tabletable=mf.addTable(tableName);

Columncol1=mf.addColumn("col1",TypeFacility.RUNTIME_NAMES.STRING,table);

columncol2=mf.addColumn("col2",TypeFacility.RUNTIME_NAMES.STRING,table);

//addapushdownfunctionthatcanalsobeevaluatedintheengine

Methodmethod=...

Functionf=mf.addFunction("func",method);

//addapushdownaggregatefunctionthatcanalsobeevaluatedintheengine

MethodaggMethod=...

Functionaf=mf.addFunction("agg",aggMethod);

af.setAggregateAttributes(newAggregateAttributes());

...

}

}

IfyourMetadataProcessorneedsexternalpropertiesthatareneededduringtheimportprocess,youcandefinethemonMetadataProcessor.Forexample,todefineaimportpropertycalled"ColumnNamePattern",whichcanbeusedtofilterwhichcolumnsaredefinedonthetable,canbedefinedinthecodelikethefollowing

@TranslatorProperty(display="ColumnNamePattern",category=PropertyType.IMPORT,description="Patterntode

rivecolumnnames")

publicStringgetColumnNamePattern(){

returncolumnNamePattern;

}

publicvoidsetColumnNamePattern(StringcolumnNamePattern){

this.columnNamePattern=columnNamePattern;

}

Notethecategorytype.Theconfigurationpropertydefinedintheprevioussectionisdifferentfromthisone.Configurationpropertiesdefinetheruntimebehavioroftranslator,whereas"IMPORT"propertiesdefinethemetadataimportbehavior,andaidincontrollingwhatmetadataisexposedbyyourtranslator.

Thesepropertiescanbeautomaticallyinjectedthrough"import"propertiessetthroughDesignerwhenusingthe"TeiidConnection"importerorthepropertiescanbedefinedunderthe<model>constructinthevdb.xmlfile,like

<vdbname="myvdb"version="1">

<modelname="legacydata"type="PHYSICAL">

<propertyname="importer.ColumnNamePattern"value="col*"/>

....

<sourcename=.../>

</model>

</vdb>

ExtensionMetadataPropertiesTheremaybetimeswhenimplementingacustomtranslator,thebuiltinmetadataaboutyourschemaisnotenoughtoprocesstheincomingqueryduetovarianceofsemanticswithyoursourcequery.Toaidthisissue,Teiidprovidesamechanismcalled"ExtensionMetadata",whichisamechanismtodefinecustompropertiesandthenaddthosepropertiesonmetadataobject(table,procedure,function,column,indexetc.).Forexample,inmycustomtranslatoratablerepresentsafileondisk.Icoulddefineaextensionmetadatapropertyas

publicclassMyMetadataProcessorimplementsMetadataProcessor<Connection>{

publicstaticfinalStringNAMESPACE="{http://my.company.corp}";

@ExtensionMetadataProperty(applicable={Table.class},datatype=String.class,display="Filename",descript

ion="FileName",required=true)

publicstaticfinalStringFILE_PROP=NAMESAPCE+"FILE";


232

publicvoidprocess(MetadataFactorymf,Connectionconn){

Objectsomedata=connection.getSomeMetadata();

Tabletable=mf.addTable(tableName);

table.setProperty(FILE_PROP,somedata.getFileName());

Columncol1=mf.addColumn("col1",TypeFacility.RUNTIME_NAMES.STRING,table);

columncol2=mf.addColumn("col2",TypeFacility.RUNTIME_NAMES.STRING,table);

}

}

The@ExtensionMetadataPropertydefinesthefollowingmetadatathatyoucandefineaboutyourproperty

applicable:Metadataobjectthisisapplicableon.ThisisarrayofmetadataclasseslikeTable.class,Column.class.

datatype:Thejavaclassindicatingthedatatype

display:Displaynameoftheproperty

description:Descriptionabouttheproperty

required:Indicatesifthepropertyisarequiredproperty

Howthisisused?

Whenyoudefineanextensionmetadatapropertylikeabove,duringtheruntimeyoucanobtainthevalueofthatproperty.Ifyougetthequeryobjectwhichcontains`SELECT*FROMMyTable',MyTablewillberepresentedbyanobjectcalled"NamedTable".Soyoucandothefollowing

for(TableReferencetr:query.getFrom()){

NamedTablet=(NameTable)tr;

Tabletable=t.getMetadataObject();

Stringfile=table.getProperty(FILE_PROP);

..

}

NowyouhaveaccessedthefilenameyousetduringtheconstructionoftheTableschemaobject,andyoucanusethisvaluehoweveryouseemfeasibletoexecuteyourquery.Withthecombinationofbuiltinmetadatapropertiesandextensionmetadatapropertiesyoucandesignandexecutequeriesforavarietyofsources.

Logging

Teiidprovidesorg.teiid.logging.LogManagerclassforloggingpurposes.CreatealoggingcontextandusetheLogManagertologyourmessages.ThesewillbeautomaticallysenttothemainTeiidlogs.Youcaneditthe"jboss-log4j.xml"inside"conf"directoryoftheWildFly’sprofiletoaddthecustomcontext.TeiidusesLog4Jasitsunderlyingloggingsystem.

Exceptions

Ifyouneedtobubbleupanyexceptionuseorg.teiid.translator.TranslatorExceptionclass.


233


234

LargeObjectsThissectionexamineshowtousefacilitiesprovidedbytheTeiidAPItouselargeobjectssuchasblobs,clobs,andxmlinyourTranslator.

DataTypes

Teiidsupportsthreelargeobjectruntimedatatypes:blob,clob,andxml.Ablobisa"binarylargeobject",aclobisa"characterlargobject",and"xml"isa"xmldocument".Columnsmodeledasablob,clob,orxmlaretreatedsimilarlybythetranslatorframeworktosupportmemory-safestreaming.

WhyUseLargeObjectSupport?

TeiidallowsaTranslatortoreturnalargeobjectthroughtheTeiidtranslatorAPIbyjustreturningareferencetotheactuallargeobject.AccesstothatLOBwillbestreamedasappropriateratherthanretrievedallatonce.Thisisusefulforseveralreasons:

1. Reducesmemoryusagewhenreturningtheresultsettotheuser.

2. Improvesperformancebypassinglessdataintheresultset.

3. Allowsaccesstolargeobjectswhenneededratherthanassumingthatuserswillalwaysusethelargeobjectdata.

4. Allowsthepassingofarbitrarilylargedatavalues.However,thesebenefitscanonlytrulybegainediftheTranslatoritselfdoesnotmaterializeanentirelargeobjectallatonce.Forexample,theJavaJDBCAPIsupportsastreaminginterfaceforblobandclobdata.

HandlingLargeObjectsTheTranslatorAPIautomaticallyhandleslargeobjects(Blob/Clob/SQLXML)throughthecreationofspecialpurposewrapperobjectswhenitretrievesresults.

Oncethewrappedobjectisreturned,thestreamingofLOBisautomaticallysupported.TheseLOBobjectsthencanforexampleappearinclientresults,inuserdefinedfunctions,orsenttoothertranslators.

AExecutionisusuallyclosedandtheunderlyingconnectioniseitherclosed/releasedassoonasallrowsforthatexecutionhavebeenretrieved.However,LOBobjectsmayneedtobereadaftertheirinitialretrievalofresults.WhenLOBsaredetectedthedefaultclosingbehaviorispreventedbysettingaflagviatheExecutionContext.keepAlivemethod.

Whenthe"keepAlive"aliveflagisset,thentheexecutionobjectisonlyclosedwhenuser’sStatementisclosed.

executionContext.keepExecutionAlive(true);

InsertingorUpdatingLargeObjects

LOBswillbepassedtotheTranslatorinthelanguageobjectsasLiteralcontainingajava.sql.Blob,java.sql.Clob,orjava.sql.SQLXML.Youcanusetheseinterfacestoretrievethedatainthelargeobjectanduseitforinsertorupdate.


235


236

TranslatorCapabilitiesTheExecutionFactoryclassdefinesallthemethodsthatdescribethecapabilitiesofaTranslator.TheseareusedbytheConnectorManagertodeterminewhatkindsofcommandsthetranslatoriscapableofexecuting.AbaseExecutionFactoryclassimplementsallthebasiccapabilitiesmethods,whichsaysyourtranslatordoesnotsupportanycapabilities.YourextendedExecutionFactoryclassmustoverridethethenecessarymethodstospecifywhichcapabilitiesyourtranslatorsupports.Youshouldconsultthedebuglogofqueryplanning(setshowplandebug)toseeifdesiredpushdownrequiresadditionalcapabilities.

CapabilityScope

Notecapabilitiesaredeterminedandcachedforthelifetimeofthetranslator.Capabilitiesbasedonconnection/userarenotsupported.

Capabilities

ThefollowingtableliststhecapabilitiesthatcanbespecifiedintheExecutionFactoryclass.

Table1.AvailableCapabilities

Capability Requires Description

SelectDistinct TranslatorcansupportSELECTDISTINCTinqueries.

SelectExpression TranslatorcansupportSELECTofmorethanjustcolumnreferences.

SelectWithoutFrom TranslatorcansupportaSELECTofscalarvalueswithoutaFROMclause

AliasedTable TranslatorcansupportTablesintheFROMclausethathaveanalias.

InnerJoins Translatorcansupportinnerandcrossjoins

SelfJoins AliasedGroupsandatleastoneofthejointypesupports.

TranslatorcansupportaselfjoinbetweentwoaliasedversionsofthesameTable.

OuterJoins TranslatorcansupportLEFTandRIGHTOUTERJOIN.

FullOuterJoins TranslatorcansupportFULLOUTERJOIN.

DependentJoins Basejoinandcriteriasupport

Translatorsupportskeysetdependentjoinpushdown.SeeDependentJoinPushdown.WhensettheMaxDependentInPredicatesandMaxInCriteriaSizevaluesarenotusedbytheengine,ratherallindependentvaluesaremadeavailabletothepushdowncommand.

FullDependentJoins Basejoinandcriteriasupport

Translatorsupportsfulldependentjoinpushdown.SeeDependentJoinPushdown.WhensettheMaxDependentInPredicatesand


237

MaxInCriteriaSizevaluesarenotusedbytheengine,rathertheentireindependentdatasetismadeavailabletothepushdowncommand.

LateralJoin Translatorsupportslateraljoinpushdownwithsidewayscorrelation.

LateralJoinCondition LateralJoin Translatorsupportslateraljoinpushdownwithajoincondition.

SubqueryInOnJoinandbasesubquerysupport,suchasExistsCriteria

TranslatorcansupportsubqueriesintheONclause.Defaultstotrue.

InlineViews AliasedTable TranslatorcansupportanamedsubqueryintheFROMclause.

ProcedureTable TranslatorcansupportatablethatreturnsatableintheFROMclause.

BetweenCriteria Notcurrentlyused-betweencriteriaisrewritenascompoundcomparisions.

CompareCriteriaEquals Translatorcansupportcomparisoncriteriawiththeoperator=.

CompareCriteriaOrdered Translatorcansupportcomparisoncriteriawiththeoperator⇒or⇐.

CompareCriteriaOrderedExclusiveTranslatorcansupportcomparisoncriteriawiththeoperator>or<.DefaultstoCompareCriteriaOrdered

LikeCriteria TranslatorcansupportLIKEcriteria.

LikeCriteriaEscapeCharacter LikeCriteria TranslatorcansupportLIKEcriteriawithanESCAPEcharacterclause.

SimilarTo TranslatorcansupportSIMILARTOcriteria.

LikeRegexCriteria TranslatorcansupportLIKE_REGEXcriteria.

InCriteria MaxInCriteria TranslatorcansupportINpredicatecriteria.

InCriteriaSubquery TranslatorcansupportINpredicatecriteriawherevaluesaresuppliedbyasubquery.

IsNullCriteria TranslatorcansupportISNULLpredicatecriteria.

OrCriteria TranslatorcansupporttheORlogicalcriteria.

NotCriteria

TranslatorcansupporttheNOTlogicalcriteria.IMPORTANT:Thiscapabilityalsoappliestonegationofpredicates,suchasspecifyingISNOTNULL,<(not⇒),>(not⇐),etc.


238

ExistsCriteria TranslatorcansupportEXISTSpredicatecriteria.

QuantifiedCompareCriteriaAll TranslatorcansupportaquantifiedcomparisoncriteriausingtheALLquantifier.

QuantifiedCompareCriteriaSome TranslatorcansupportaquantifiedcomparisoncriteriausingtheSOMEorANYquantifier.

OnlyLiteralComparisonTranslatorifonlyLiteralcomparisons(equality,ordered,like,etc.)aresupportedfornon-joinconditions.

Convert(intfromType,inttoType)

Usedforfinegrainedcontrolofconvert/castpushdown.TheExecutionFactory.getSupportedFunctions()

shouldcontainSourceSystemFunctions.CONVERT.Thismethodcanthenreturnfalsetoindicatealackofspecificsupport.SeeTypeFacility.RUNTIME_CODESforthepossibletypecodes.TheenginewilldoesnotcareaboutanunnecessaryconversionwherefromType==toType.Bydefaultlobconversionisdisabled.

OrderBy TranslatorcansupporttheORDERBYclauseinqueries.

OrderByUnrelated OrderBy TranslatorcansupportORDERBYitemsthatarenotdirectlyspecifiedintheselectclause.

OrderByNullOrdering OrderBy TranslatorcansupportORDERBYitemswithNULLSFIRST/LAST.

OrderByWithExtendedGrouping OrderByTranslatorcansupportORDERBYdirectlyoveraGROUPBYwithanextendedgroupingelementsuchasaROLLUP.

GroupBy TranslatorcansupportanexplicitGROUPBYclause.

GroupByRollup GroupBy TranslatorcansupportGROUPBY(currentlyasingle)ROLLUP.

Having GroupBy TranslatorcansupporttheHAVINGclause.

AggregatesAvg TranslatorcansupporttheAVGaggregatefunction.

AggregatesCount TranslatorcansupporttheCOUNTaggregatefunction.

AggregatesCountStar TranslatorcansupporttheCOUNT(*)aggregatefunction.

AggregatesDistinct Atleastoneoftheaggregatefunctions.

TranslatorcansupportthekeywordDISTINCTinsideanaggregatefunction.Thiskeywordindicatesthatduplicatevalueswithin


239

agroupofrowswillbeignored.

AggregatesMax TranslatorcansupporttheMAXaggregatefunction.

AggregatesMin TranslatorcansupporttheMINaggregatefunction.

AggregatesSum TranslatorcansupporttheSUMaggregatefunction.

AggregatesEnhancedNumericTranslatorcansupporttheVAR_SAMP,VAR_POP,STDDEV_SAMP,STDDEV_POPaggregatefunctions.

ScalarSubqueriesTranslatorcansupporttheuseofasubqueryinascalarcontext(whereveranexpressionisvalid).

ScalarSubqueryProjection ScalarSubqueries Translatorcansupporttheuseofaprojectedscalarsubquery.

CorrelatedSubqueries Atleastoneofthesubquerypushdowncapabilities.

Translatorcansupportacorrelatedsubquerythatreferstoanelementintheouterquery.

CorrelatedSubqueryLimit CorrelatedSubqueriesDefaultstoCorrelatedSubqueriessupport.Translatorcansupportacorrelatedsubquerywithalimitclause.

CaseExpressions Notcurrentlyused-simplecaseisrewritenassearchedcase.

SearchedCaseExpressionsTranslatorcansupportsearchedCASEexpressionsanywherethatexpressionsareaccepted.

Unions TranslatorsupportUNIONandUNIONALL

Intersect TranslatorsupportsINTERSECT

Except TranslatorsupportsExcept

SetQueryOrderBy Unions,Intersect,orExcept TranslatorsupportssetquerieswithanORDERBY

RowLimit Translatorcansupportthelimitportionofthelimitclause

RowOffset Translatorcansupporttheoffsetportionofthelimitclause

FunctionsInGroupBy GroupBy Translatorcansupportnon-columnreferencegroupingexpressions.

InsertWithQueryExpression TranslatorsupportsINSERTstatementswithvaluesspecifiedbyanQueryExpression.


240

BatchedUpdatesTranslatorsupportsabatchofINSERT,UPDATEandDELETEcommandstobeexecutedtogether.

BulkUpdate Translatorsupportsupdateswithmultiplevaluesets

CommonTableExpressions TranslatorsupportstheWITHclause.

SubqueryCommonTableExpressions CommonTableExpressions TranslatorsupportsaWITHclauseinsubqueries.

ElementaryOlapOperationsTranslatorsupportswindowfunctionsandanalyticfunctionsRANK,DENSE_RANK,andROW_NUMBER.

WindowOrderByWithAggregates ElementaryOlapOperations Translatorsupportswindowedaggregateswithawindoworderbyclause.

WindowDistinctAggregates ElementaryOlapOperations,AggregatesDistinct

Translatorsupportswindoweddistinctaggregates.

AdvancedOlapOperations ElementaryOlapOperations Translatorsupportsaggregateconditions.

OnlyFormatLiterals

functionsupportforaparse/formatfunctionandanimplementationofthesupportsFormatLiteralmethod.

TranslatorsupportsonlyliteralformatpatternsthatmustbevalidatedbythesupportsFormatLiteralmethod.

FormatLiteral(Stringliteral,Formattype) OnlyFormatLiterals Translatorsupportsthegivenliteralformat

string.

ArrayType Translatorsupportsthepushdownofarrayvalues.

OnlyCorrelatedSubqueries CorrelatedSubqueries

TranslatorONLYsupportscorrelatedsubqueries.Uncorrelatedscalarandexistssubquerieswillbepre-evaluatedpriortopush-down.

SelectWithoutFrom SelectExpressions TranslatorsupportsselectingvalueswithoutaFROMclause,e.g.SELECT1.

NotethatanypushdownsubquerymustitselfbecompliantwiththeTranslatorcapabilities.

CommandFormThemethodExecutionFactory.useAnsiJoin()shouldreturntrueiftheTranslatorpreferstheuseofANSIstylejoinstructureforjointreesthatcontainonlyINNERandCROSSjoins.

ThemethodExecutionFactory.requiresCriteria()shouldreturntrueiftheTranslatorrequirescriteriaforanyQuery,Update,orDelete.ThisisareplacementforthemodelsupportpropertyWhereAll.

ScalarFunctions


241

ThemethodExecutionFactory.getSupportedFunctions()canbeusedtospecifywhichsystem/userdefinedscalaranduserdefinedaggregatefunctionstheTranslatorsupports.Theconstantsinterfaceorg.teiid.translator.SourceSystemFunctionscontainsthestringnamesofallpossiblebuilt-inpushdownfunctions,whichincludesthefourstandardmathoperators:+,-,*,and/.

NotallsystemfunctionsappearinSourceSystemFunctions,sincesomesystemfunctionswillalwaysbeevaluatedinTeiid,aresimplealiasestootherfunctions,orarerewrittentoamorestandardexpression.

ThisdocumentationforsystemfunctionscanbefoundatScalarFunctions.IftheTranslatorstatesthatitsupportsafunction,itmustsupportalltypecombinationsandoverloadedformsofthatfunction.

Atranslatormayalsoindicatesupportforscalarfunctionsthatareintendedforpushdownevaluationbythattranslator,butarenotregisteredasuserdefinedfunctionsviaamodel/schema.ThesepushdownfunctionsarereportedtotheengineviatheExecutionFactory.getPushDownFunctions()listasFunctionMethodmetadataobjects.TheFuncitonMethodrepresentationallowthetranslatortocontrolallofthemetadatarelatedtothefunction,includingtypesignature,determinism,varargs,etc.ThesimplestwaytoaddapushdownfunctioniswithacalltoExecutionFactory.addPushDownFunction:

FunctionMethodaddPushDownFunction(Stringqualifier,Stringname,StringreturnType,String...paramTypes)

Thisresultingfunctionwillbeknownassys.qualifier.name,butcanbecalledwithjustnameaslongasthefunctionnameisunique.ThereturnedFunctionMethodobjectmaybefurthermanipulateddependingupontheneedsofthesource.AnexampleofaddingacustomconcatvarargfunctioninanExecutionFactorysubclass:

publicvoidstart()throwsTranslatorException{

super.start();

FunctionMethodfunc=addPushDownFunction("oracle","concat","string","string","string");

func.setVarArgs(true);

...

}

PhysicalLimitsThemethodExecutionFactory.getMaxInCriteriaSize()canbeusedtospecifythemaximumnumberofvaluesthatcanbepassedinanINcriteria.ThisisanimportantconstraintasanINcriteriaisfrequentlyusedtopasscriteriabetweenonesourceandanotherusingadependentjoin.

ThemethodExecutionFactory.getMaxDependentInPredicates()isusedtospecifythemaximumnumberofINpredicates(ofatmostMaxInCriteriaSize)thatcanbepassedaspartofadependentjoin.Forexampleifthereare10000valuestopassaspartofthedependentjoinandaMaxInCriteriaSizeof1000andaMaxDependentInPredicatessettingof5,thenthedependentjoinlogicwillformtwosourcequerieseachwith5INpredicatesof1000valueseachcombinedbyOR.

ThemethodExecutionFactory.getMaxFromGroups()canbeusedtospecifythemaximumnumberofFROMClausegroupsthatcanusedinajoin.-1indicatesthereisnolimit.

UpdateExecutionModesThemethodExecutionFactory.supportsBatchedUpdates()canbeusedtoindicatethattheTranslatorsupportsexecutingtheBatchedUpdatescommand.

ThemethodExecutionFactory.supportsBulkUpdate()canbeusedtoindicatethattheTranslatoracceptsupdatecommandscontaingmultivaluedLiterals.

Notethatifthetranslatordoesnotsupporteitheroftheseupdatemodes,thequeryenginewillcompensatebyissuingtheupdatesindividually.


242

DefaultBehavior

ThemethodExecutionFactory.getDefaultNullOrder()specifiesthedefaultnullorder.CanbeoneofUNKNOWN,LOW,HIGH,FIRST,LAST.ThisisonlyusedifORDERBYissupported,butnullorderingisnot.

ThemethodExecutionFactory.getCollation()specifiesthedefaultcollation.Ifsettoavaluethatdoesnotmatchthecollationlocaledefinedbyorg.teiid.collationLocale,thensomeorderingmaynotbepusheddown.

ThemethodExecutionFactory.getRequiredLikeEscape()specifiestherequiredlikeescapecharacter.Usedonlywhenasourcesupportsaspecificescape.

UseofConnections

Method Description Default

is/setSourceRequiredTrueindicatesasourceconnectionisrequiredforfetchingthemetadataofthesourceorexecutingqueries.

true

is/setSourceRequiredForMetadataTrueindicatesasourceconnectionisrequiredforfetchingthemetadataofthesource.

SourceRequired

TransactionBehavior

ExecutionFactory.get/setTransactionSupportspecifiesthehighestleveloftransactionsupportedbyconnectionstothesource.ThisisusedasahinttotheenginefordecidingwhentostartatransactionintheautoCommitTxn=DETECTmode.DefaultstoXA.


243

TranslatorPropertiesDuringtranslatordevelopment,atranslatordevelopercandefinethree(3)differenttypesofpropertysetsthatcanhelpcustomizethebehaviorofthetranslator.Thesectionsbelowdescribeseachone.

TranslatorOverrideProperties

Onthe"ExecutionFactory"classatranslatordevelopercandefineanynumberof"getter/setter"[email protected](alsoreferredtoaexecutionproperties)canbeusedforextendingthecapabilitiesofthetranslator.Itisimportanttodefinedefaultvaluesforalltheseproperties,asthesepropertiesarebeingdefinedtochangethedefaultbehaviorofthetranslator.Ifneeded,thevaluesforthesepropertiesaresuppliedin"vdb.xml"fileduringthedeploytimewhenthetranslatorisusedtorepresentvdb’smodel.Asampleexampleisgivenbelow:

@TranslatorProperty(display="CopyLOBs",description="Iftrue,returnedLOBswillbecopied,ratherthanstreame

dfromthesource",advanced=true)

publicbooleanisCopyLobs(){

returncopyLobs;

}

publicvoidsetCopyLobs(booleancopyLobs){

this.copyLobs=copyLobs;

atruntimethesepropertiescanbedefinedinvdb.xmlas


<vdbname="vdb"version="1">

<modelname="PM1">

<sourcename="connector"translator-name="my-translator-override"/>

</model>

<translatorname="my-translator-override"type="my-translator">

<propertyname="CopyLobs"value="true"/>

</translator>

</vdb>

MetadataImportPropertiesIfatranslatorisdefiningschemainformationbasedonthephysicalsource(i.e.implementinggetMetadatamethodonExecutionFactory)itisconnectedto,thenimportpropertiesprovideawaytocustomizethebehavioroftheimportprocess.Forexample,intheJDBCtranslatoruserscanexcludecertaintablesthatmatcharegularexpressionetc.Todefineaimportproperty,the@TranslatorProperyannotationisusedonanygetter/settermethodonthe"ExecutionFactory"classoranyclassthatimplementsthe"MetadataProcessor"interface,withcategorypropertydefinedas"PropertyType.IMPORT".Forexample.

@Translator(name="my-translator",description="MyTranslator")

publicclassMyExecutionFactoryextendsExecutionFactory<ConnectionFactory,MyConnection>{

...

publicMetadataProcessor<C>getMetadataProcessor(){

returnMyMetadataProcessor();

}

}

publicMyMetadataProcessorimplementsMetadataProcessor<MyConnection>{

publicvoidprocess(MetadataFactorymetadataFactory,MyConnectionconnection)throwsTranslatorException{

//schemagenerationcodehere


244

}

@TranslatorProperty(display="HeaderRowNumber",category=PropertyType.IMPORT,description="Rownumberthat

containstheheaderinformation")

publicintgetHeaderRowNumber(){

returnheaderRowNumber;

}

publicvoidsetHeaderRowNumber(intheaderRowNumber){

this.headerRowNumber=headerRowNumber;

}

}

Belowisanexampleshowinghowtouseimportpropertieswithavdb.xmlfile



<modelname="PM1">

<propertyname="importer.HeaderRowNumber"value="12"/>

<sourcename="connector"translator-name="my-translator"/>

</model>

</vdb>

Note"DesignerIntegration"-Whenpropertiesaredefinedusingtheannotationmechanismandwhenusingthe"TeiidConnection"importerintheDesigner,thesepropertieswillautomaticallyshowupinappropriatewizardforinput.

ExtensionMetadataProperties

Duringtheexecutionofthecommandintranslator,atranslatorisresponsibletoconvertTeiidsuppliedSQLcommandintodatasourcespecificquery.Mostoftimesthisconversionisnotatrivialtaskcanbeconvertedfromoneformtoanother.Therearemanycasesbuilt-inmetadataisnotsufficientandadditionalmetadataaboutsourceisusefultoformarequesttotheunderlyingphysicalsourcesystem.ExtensionMetadataPropertiesonesuchmechanismtofillthegapinthemetadata.Thesecanbedefinedspecificforagiventranslator.

Atranslatorisaplugin,thatiscommunicatingwithTeiidengineaboutit’ssourcewithit’smetadata.MetadatainthiscontextisdefinitionsofTables,Columns,Procedures,Keysetc.ThismetadatacanbedecoratedwithadditionalcustommetadataandfedtoTeiidqueryengine.Teiidqueryenginekeepsthisextendedmetadataintactalongwithitsschemaobjects,andwhenauserqueryissubmittedtothethetranslatorforexecution,thisextendedmetadatacanberetrievedformakingdecisionsinthetranslatorcode.

Extendedpropertiesaredefinedusingannotationclasscalled@ExtensionMetadataPropertyonthefieldsinyour"MetadataProcessor"or"ExcutionFactory"classes.

Forexample,saytranslatorrequiresa"encoding"propertyonTable,todothecorrectun-marshalingofdata,thispropertycanbedefinedas

publicclassMyMetadataProcessorimplementsMetadataProcessor<MyConnection>{

publicstaticfinalStringURI="{http://www.teiid.org/translator/mytranslator/2014}";

@ExtensionMetadataProperty(applicable=Table.class,datatype=String.class,display="Encoding",description="

Encoding",required=true)

publicstaticfinalStringENCODING=URI+"encode";

publicvoidprocess(MetadataFactorymf,FileConnectionconn)throwsTranslatorException{

..

Tablet=mf.addTable(tableName);

t.setProperty(ENCODING,"UTF-16");

//addcolumnsetc.


245

..

}

}

Nowduringtheexecution,ontheCOMMANDobjectsuppliedtothe"Execution"class,usercan

Selectselect=(Select)command;

NamedTabletableReferece=select.getFrom().get(0);

Tablet=tableReference.getMetadataObject();

Stringencoding=t.getProperty(MyMetadataProcessor.ENCODING,false);

//usetheencodingvalueasneededtomarshalorunmarshaldata

Note

"DesignerIntegration"-Whenextendedpropertiesaredefinedusingtheannotationmechanism,whenusing"TeiidConnection"importerintheDesigner,youdonotneedtodefinethe"MetadataExtensionDefn"indesignerandregistertotousewithyourmodel,therequireddefinitionsareautomaticallydownloadedandconfiguredtouse.(ThisfeatureisnotavailableincurrentDesignerversion)


246

ExtendingTheJDBCTranslatorTheJDBCTranslatorcanbeextendedtohandlenewJDBCdriversanddatabaseversions.ThisisoneofthemostcommonneedsofcustomTranslatordevelopment.ThischapteroutlinestheprocessbywhichausercanmodifythebehavioroftheJDBCTranslatorforanewsource,ratherthanstartingfromscratch.

TodesignaJDBCTranslatorforanyRDMSthatisnotalreadyprovidedbytheTeiid,extendtheorg.teiid.translator.jdbc.JDBCExecutionFactoryclassinthe"translator-jdbc"module.TherearethreetypesofmethodsthatyoucanoverridefromthebaseclasstodefinethebehavioroftheTranslator.

Extension Purpose

Capabilities SpecifytheSQLsyntaxandfunctionsthesourcesupports.

SQLTranslation CustomizewhatSQLsyntaxisused,howsource-specificfunctionsaresupported,howproceduresareexecuted.

ResultsTranslation CustomizehowresultsareretrievedfromJDBCandtranslated.

CapabilitiesExtensionThisextensionmustoverridethemethodsthatbeginwith"supports"thatdescribetranslatorcapabilities.RefertoCommandLanguage#TranslatorCapabilitiesforalltheavailabletranslatorcapabilities.

Themostcommonexampleisaddingsupportforascalarfunction–thisrequiresbothdeclaringthatthetranslatorhasthecapabilitytoexecutethefunctionandoftenmodifyingtheSQLTranslatortotranslatethefunctionappropriatelyforthesource.

AnothercommonexampleisturningoffunsupportedSQLcapabilities(suchasouterjoinsorsubqueries)forlesssophisticatedJDBCsources.

SQLTranslationExtensionTheJDBCExcecutionFactoryprovidesseveralmethodstomodifythecommandandthestringformoftheresultingsyntaxbeforeitissenttotheJDBCdriver,including:

ChangebasicSQLsyntaxoptions.SeetheuseXXXmethods,e.g.useSelectLimitreturnstrueforSQLServertoindicatethatlimitsareappliedintheSELECTclause.

RegisteroneormoreFunctionModifiersthatdefinehowascalarfunctionshouldbemodifiedortransformed.

ModifyaLanguageObject.-seethetranslate,translateXXX,andFunctionModifiers.translatemethods.Modifythepassedinobjectandreturnnulltoindicatethatthestandardsyntaxoutputshouldbeused.

ChangethewaySQLstringsareformedforaLanguageObject.--seethetranslate,translateXXX,andFunctionModifiers.translatemethods.Returnalistofparts,whichcancontainstringsandLanguageObjects,thatwillbeappendedinordertotheSQLstring.IftheincomingLanguageObjectappearsinthereturnedlistitwillnotbetranslatedagain.RefertoUsingFunctionModifiers.

ResultsTranslationExtension


247

TheJDBCExecutionFactoryprovidesseveralmethodstomodifythejava.sql.Statementandjava.sql.ResultSetinteractions,including:

1. OverridingthecreateXXXExecutiontosubclassthecorrespondingJDBCXXXExecution.TheJDBCBaseExecutionhasprotectedmethodstogettheappropriatestatement(getStatement,getPreparedStatement,getCallableStatement)andtobindpreparedstatementvaluesbindPreparedStatementValues.

2. RetrievevaluesfromtheJDBCResultSetorCallableStatement-seetheretrieveValuemethods.

AddingFunctionSupportRefertoUserDefinedFunctionsforaddingnewfunctionstoTeiid.Thisexamplewillshowyouhowtodeclaresupportforthefunctionandmodifyhowthefunctionispassedtothedatasource.

Followingisasummaryofallcodingstepsinsupportinganewscalarfunction:

1. Overridethecapabilitiesmethodtodeclaresupportforthefunction(REQUIRED)

2. ImplementaFunctionModifiertochangehowafunctionistranslatedandregisteritforuse(OPTIONAL)ThereisacapabilitiesmethodgetSupportedFunctions()thatdeclaresallsupportedscalarfunctions.

Anexampleofanextendedcapabilitiesclasstoaddsupportforthe"abs"absolutevaluefunction:

packagemy.connector;

importjava.util.ArrayList;

importjava.util.List;

publicclassExtendedJDBCExecutionFactoryextendsJDBCExecutionFactory

{

@Override

publicListgetSupportedFunctions()

{

ListsupportedFunctions=newArrayList();

supportedFunctions.addAll(super.getSupportedFunctions());

supportedFunctions.add("ABS");

returnsupportedFunctions;

}

}

Ingeneral,itisagoodideatocallsuper.getSupportedFunctions()toensurethatyouretainanyfunctionsupportprovidedbythetranslatoryouareextending.

ThismaybeallthatisneededtosupportaTeiidfunctioniftheJDBCdatasourcesupportsthesamesyntaxasTeiid.Thebuilt-inSQLtranslationwilltranslatemostfunctionsas:"function(arg1,arg2,…)".

UsingFunctionModifiersInsomecasesyoumayneedtotranslatethefunctiondifferentlyoreveninsertadditionalfunctioncallsaboveorbelowthefunctionbeingtranslated.TheJDBCtranslatorprovidesanabstractclassFunctionModifierforthispurpose.

DuringthestartmethodamodifierinstancecanberegisteredagainstagivenfunctionnameviaacalltoJDBCExecutionFactory.registerFunctionModifier.

TheFunctionModifierhasamethodcalledtranslate.Usethetranslatemethodtochangethewaythefunctionisrepresented.


248

AnexampleofoverridingthetranslatemethodtochangetheMOD(a,b)functionintoaninfixoperatorforSybase(a%b).Thetranslatemethodreturnsalistofstringsandlanguageobjectsthatwillbeassembledbythetranslatorintoafinalstring.Thestringswillbeusedasisandthelanguageobjectswillbefurtherprocessedbythetranslator.

publicclassModFunctionModifierextendsFunctionModifier

{

publicListtranslate(Functionfunction)

{

Listparts=newArrayList();

parts.add("(");

Expression[]args=function.getParameters();

parts.add(args[0]);

parts.add("%");

parts.add(args[1]);

parts.add(")");

returnparts;

}

}

InadditiontobuildingyourownFunctionModifiers,thereareanumberofpre-builtgenericfunctionmodifiersthatareprovidedwiththetranslator.

Modifier Description

AliasModifier Handlessimplyrenamingafunction("ucase"to"upper"forexample)

EscapeSyntaxModifier WrapsafunctioninthestandardJDBCescapesyntaxforfunctions:\{fnxxxx()}

Toregisterthefunctionmodifiersforyoursupportedfunctions,youmustcalltheExecutionFactory.registerFunctionModifier(Stringname,FunctionModifiermodifier)method.

publicclassExtendedJDBCExecutionFactoryextendsJDBCExecutionFactory

{

@Override

publicvoidstart()

{

super.start();

//registerfunctions.

registerFunctionModifier("abs",newMyAbsModifier());

registerFunctionModifier("concat",newAliasModifier("concat2"));

}

}

Supportforthetwofunctionsbeingregistered("abs"and"concat")mustbedeclaredinthecapabilitiesaswell.Functionsthatdonothavemodifiersregisteredwillbetranslatedasusual.

InstallingExtensions

OnceyouhavedevelopedanextensiontotheJDBCtranslator,youmustinstallitintotheTeiidServer.TheprocessofpackagingordeployingtheextendedJDBCtranslatorsisexactlyasanyotherothertranslator.SincetheRDMSisaccessiblealreadythroughitsJDBCdriver,thereisnoneedtodeveloparesourceadapterforthissourceasWildFlyprovidesawrapperJCAconnector(DataSource)foranyJDBCdriver.

RefertoPackagingandDeploymentformoredetails.


249


250

DelegatingTranslatorInsomeinstancesyoumaywishtoextendseveraldifferntkindsoftranslatorswiththesamefunctionality.Ratherthancreateseparatesubclassesforeachextension,youcanusethedelegatingtranslatorframeworkwhichprovidesyouwithaproxyingmechanismtooverridetranslatorbehavior.Itimplementadelegatingtranslator,yourcommontranslatorlogicshouldbeaddedtoasubclassofBaseDelegatingExecutionFactorywhereyoucanoverrideanyofthedelegationmethodstoperformwhateverlogicyouwant.

ExampleBaseDelegatingExecutionFactorySubclass

@Translator(name="custom-delegator")

publicclassMyTranslatorextendsBaseDelegatingExecutionFactory<Object,Object>{

@Override

publicExecutioncreateExecution(Commandcommand,

ExecutionContextexecutionContext,RuntimeMetadatametadata,

Objectconnection)throwsTranslatorException{

if(commandinstanceofSelect){

//modifythecommandorreturnadifferentexecution

...

}

//thesupercallwillbetothedelegateinstance

returnsuper.createExecution(command,executionContext,metadata,connection);

}

...

}

Youwillbundleanddeployyourcustomdelegatingtranslatorisjustlikeanyothercustomtranslatordevelopment.Toyouuseyourdelegatingtranslatorinavdb,youdefineatranslatoroverridethatwiresinthedelegate.

ExampleTranslatorOverride

<translatortype="custom-delegator"name="my-translator">

<propertyvalue="delegateName"name="nameofthedelegateinstance"/>



</translator>

Fromthepreviousexamplethetranslatortypeiscustom-delegator.Nowmy-translatorcanbeusedasatranslator-nameonasourceandwillproxyallcallstowhateverdelegateinstanceyouassign.

Note Notethatthedelegateinstancecanbeanytranslatorinstance,whetherconfiguredbyit’sowntranslatorentryorjustthenameofastandardtranslatortype.

DelegatingTranslator

251

PackagingOncethe"ExecutionFactory"classisimplemented,packageitinaJARfile.Thenaddthefollowingnamedfilein"META-INF/services/org.teiid.translator.ExecutionFactory"withcontentsspecifyingthenameofyourmainTranslatorfile.Notethat,thenamemustexactlymatchtoabove.Thisisjava’sstandardserviceloaderpattern.ThiswillregistertheTranslatorfordeploymentwhenthejarisdeployedintoWildFly.

org.teiid.translator.custom.CustomExecutionFactory

Packaging

252

AddingDependentModulesAddaMANIFEST.MFfileintheMETA-INFdirectory,andthecoreTeiidAPIdependenciesforresourceadapterwiththefollowingline.

Dependencies:org.jboss.teiid.common-core,org.jboss.teiid.api,javax.api

Ifyourtranslatordependsuponanyotherthirdpartyjarfiles,ensureamoduleexistsandaddthemodulenametotheaboveMANIFEST.MFfile.

Packaging

253

DeploymentAtranslatorJARfilecanbedeployedintoTeiidServerintwodifferentways

AsWildFlymodule

Createamoduleunder"jboss-as/modules"directoryanddefinethetranslatornameandmodulenameintheteiidsubsysteminstandalone-teiid.xmlfileordomain-teiid.xmlfileandrestarttheserver.ThedependentTeiidoranyotherjavaclasslibrariesmustbedefinedinmodule.xmlfileofthemodule.Forproductionprofilesthisisrecommended.

AsJARdeployment

FordevelopmenttimeorquickdeploymentyoucandeploythetranslatorJARusingtheCLIorAdminShelloradminconsoleprograms.WhenyoudeployinJARformthedependenciestoTeiidjavalibrariesandanyotherthirdpartylibrariesmustbedefinedunderMETA-INF/MANIFEST.MFfile.

Deployment

254

UserDefinedFunctionsIfyouneedtoextendTeiid’sscalaroraggregatefunctionlibrary,thenTeiidprovidesameanstodefinecustomorUserDefinedFunctions(UDF).

ThefollowingareusedtodefineaUDF.

FunctionNameWhenyoucreatethefunctionname,keeptheserequirementsinmind:

YoucannotoverloadexistingTeiidSystemfunctions.

Thefunctionnamemustbeuniqueamonguser-definedfunctionsinitsmodelforthenumberofarguments.Youcanusethesamefunctionnamefordifferentnumbersoftypesofarguments.Hence,youcanoverloadyouruser-definedfunctions.

Thefunctionnamecannotcontainthe`.'character.

Thefunctionnamecannotexceed255characters.

InputParameters-definesatypespecificsignaturelist.Allargumentsareconsideredrequired.

ReturnType-theexpectedtypeofthereturnedscalarvalue.

Pushdown-canbeoneofREQUIRED,NEVER,ALLOWED.Indicatestheexpectedpushdownbehavior.IfNEVERorALLOWEDarespecifiedthenaJavaimplementationofthefunctionshouldbesupplied.IfREQUIREDisused,thenusermustextendtheTranslatorforthesourceandaddthisfunctiontoitspushdownfunctionlibrary.

invocationClass/invocationMethod-optionalpropertiesindicatingthemethodtoinvokewhentheUDFisnotpusheddown.

Deterministic-ifthemethodwillalwaysreturnthesameresultforthesameinputparameters.Defaultstofalse.Itisimportanttomarkthefunctionasdeterministicifitreturnsthesamevalueforthesameinputsasthiswillleadtobetterperformance.SeealsotheRelationalextensionbooleanmetadataproperty"deterministic"andtheDDLOPTIONproperty"determinism".Defaultstofalse.Itisimportanttomarkthefunctionasdeterministicifitreturnsthesamevalueforthesameinputsasthiswillleadtobetterperformance.SeealsotheRelationalextensionbooleanmetadataproperty"deterministic"andtheDDLOPTIONproperty"determinism".

EvenPushdownrequiredfunctionsneedtobeaddedasaUDFtoallowTeiidtoproperlyparseandresolvethefunction.Pushdownscalarfunctionsdifferfromnormaluser-definedfunctionsinthatnocodeisprovidedforevaluationintheengine.Anexceptionwillberaisedifapushdownrequiredfunctioncannotbeevaluatedbytheappropriatesource.

UserDefinedFunctions

255

SourceSupportedFunctionsWhileTeiidprovidesanextensivescalarfunctionlibrary,itcontainsonlythosefunctionsthatcanbeevaluatedwithinthequeryengine.Inmanycircumstances,especiallyforperformance,asourcefunctionallowsforcallingasourcespecificfunction.ThesemanticsofdefiningthesourcefunctionassimilarorsametooneofdefiningtheUDF.

Forexample,supposeyouwanttousetheOracle-specificfunctionsscoreandcontainslike:

SELECTscore(1),ID,FREEDATAFROMDocsWHEREcontains(freedata,'nick',1)>0

Thescoreandcontainsfunctionsarenotpartofbuilt-inscalarfunctionlibrary.Whileyoucouldwriteyourowncustomscalarfunctiontomimictheirbehavior,it’smorelikelythatyouwouldwanttousetheactualOraclefunctionsthatareprovidedbyOraclewhenusingtheOracleFreeTextfunctionality.

InordertoconfigureTeiidtopushtheabovefunctionevaluationtoOracle,Teiidprovidesafewdifferentwaysonecanconfiguretheirinstance.

ExtendingtheTranslator

TheExecutionFactory.getPushdownFunctionsmethodcanbeusedtodescribefunctionsthatarevalidagainstallinstancesofagiventranslatortype.Thefunctionnamesareexpectedtobeprefixedbythetranslatortype,orsomeotherlogicalgrouping,e.g.salesforce.includes.ThefullnameofthefunctiononceimportedintothesystemwillqualifiedbytheSYSschema,e.g.SYS.salesforce.includes.

AnyfuncitonsaddedviathesemechanismsdonotneedtobedeclaredinExecutionFactory.getSupportedFunctions.Anyoftheadditionalhandling,suchasaddingaFunctionModifier,coveredaboveisalsoapplicablehere.Allpushdownfunctionswillhavefunctionnamesettoonlythesimplename.Schemaorotherqualificationwillberemoved.Handling,suchasfunctionmodifiers,cancheckthefunctionmetadataifthereisthepotentialforanambiguity.

Forexample,toextendtheOracleConnector

Required-extendtheOracleExecutionFactoryandaddSCOREandCONTAINSassupportedpushdownfunctionsbyeitheroverridingoraddingadditionalfunctionsin"getPushDownFunctions"method.Forthisexample,we’llcalltheclassMyOracleExecutionFactory.Addtheorg.teiid.translator.Translatorannotationtotheclass,e.g.@Translator(name="myoracle")

OptionallyregisternewFunctionModifiersonthestartoftheExecutionFactorytohandletranslationofthesefunctions.Giventhatthesyntaxofthesefunctionsissameasothertypicalfunctions,thisprobablyisn’tneeded-thedefaulttranslationshouldwork.

CreateanewtranslatorJARcontainingyourcustomExecutionFactory.RefertoPackagingandDeploymentforinstructionsonusingtheJARfile.OncethisisextendedtranslatorisdeployedintheTeiidServer,use"myoracle"astranslatornameinsteadofthe"oracle"inyourVDB’sOraclesourceconfiguration.

Ifyousourcehandingofthefunctioncanbedescribedbysimpleparametersubstitutionintoastring,thenyoumaynotneedtoextendthetranslatorforasourcespecificfunction.Youcanusetheextensionpropertyteiid_rel:native-querytodefinethesyntaxhandling-seealsoDDLMetadataforfunctions.

WhenUsingDesigner


256

IfyouaredesigningyourVDBusingtheDesigner,youcandefineafunctiononany"source"model,andthatfunctionisautomaticallyaddedaspushdownfunctionwhentheVDBisdeployed.ThereisnoadditionalneedforaddingJavacode.

WithoutDesigner

IfyouarenotusingDesigner,seedefiningthemetadatausingDDL,youcandefineyoursourcefunctionintheVDBas

<vdbname="{vdb-name}"version="1">

<modelname="{model-name}"type="PHYSICAL">

<sourcename="AccountsDB"translator-name="oracle"connection-jndi-name="java:/oracleDS"/>


CREATEFOREIGNFUNCTIONSCORE(valinteger)RETURNSinteger;

....(othertables,proceduresetc)

]]>

</metadata>

</model>

</vdb>

Bydefaultwhenasourcecanprovidemetadata,theSourcemodel’smetadataisautomaticallyretrievedfromthesourceiftheywereJDBC,File,WebService.TheFileandWebServicesourcesarestatic,soonecannotaddadditionalmetadataonthem.HoweverontheJDBCsourcesyoucanretrievethemetadatafromsourceandthenusercanappendadditionalmetadataontopofthem.Forexample




<metadatatype="NATIVE,DDL"><![CDATA[

CREATEFOREIGNFUNCTIONSCORE(valinteger)RETURNSinteger;

]]>

</metadata>

</model>

</vdb>

TheaboveexampleusesNATIVEmetadatatype(NATIVEisthedefaultforsource/physicalmodels)firsttoretrieveschemainformationfromsource,thenusesDDLmetadatatypetoaddadditionalmetadata.OnlymetadatanotavailableviatheNATIVEtranslatorlogicwouldneedtobespecifiedviaDDL.

Alternatively,ifyouareusingcustomMetadataRepositorywithyourVDB,thenprovidethe"function"metadatadirectlyfromyourimplementation.ex.




<metadatatype="{metadata-repo-module}"></metadata>

</model>

</vdb>

Intheaboveexample,usercanimplementMetadataRepositoryinterfaceandpackagetheimplementationclassalongwithitsdependenciesinaWildFlymoduleandsupplythemodulenameintheaboveXML.FormoreinformationonhowtowriteaMetadataRepositoryrefertoCustomMetadataRepository.


257

SupportforUser-DefinedFunctions(Non-Pushdown)Todefineanon-pushdownfunction,aJavafunctionmustbeprovidedthatmatchestheVDBdefinedmetadata.UserDefinedFunction(orUDF)andUserDefinedAggregateFunction(orUDAF)maybecalledatruntimejustlikeanyotherfunctionoraggregatefunctionrespectively.

MetadatainDesigner

AuserdefinedfunctioncreatedonanyVDBonviewmodelbycreatingaFunctionjustasabasetable.YouwouldrequirealltheinformationdefinedonUserDefinedFunctionstocreateaUDF.MakesureyouprovidetheJAVAcodeimplementationdetailsinthepropertiesdialogfortheUDF.

MetadatawithoutDesigner

WhendefiningthemetadatawithoutDesigner,youcandefineaUDForUDAF(UserDefinedAggregateFunction)asshownbelow.


<modelname="{model-name}"type="VIRTUAL">


CREATEVIRTUALFUNCTIONcelsiusToFahrenheit(celsiusdecimal)RETURNSdecimalOPTIONS(JAVA_CLASS'

org.something.TempConv',JAVA_METHOD'celsiusToFahrenheit');

CREATEVIRTUALFUNCTIONsumAll(arginteger)RETURNSintegerOPTIONS(JAVA_CLASS'org.something.Sum

All',JAVA_METHOD'addInput',AGGREGATE'true',VARARGS'true',"NULL-ON-NULL"'true');]]></metadata>

</model>

</vdb>

YoumustcreateaJavamethodthatcontainsthefunction’slogic.ThisJavamethodshouldacceptthenecessaryarguments,whichtheTeiidSystemwillpasstoitatruntime,andfunctionshouldreturnthecalculatedoralteredvalue.

SeeDDLMetadataforallpossibleoptionsrelatedtofunctionsdefinedviaDDL.

WritingtheJavaCoderequiredbytheUDF

ThenumberofinputargumentsandtypesmustmatchthefunctionmetadatadefinedintheVDBmetadata.

CodeRequirementsForUDFs

Thejavaclasscontainingthefunctionmethodmustbedefinedpublic.

Note OneimplementationclasscancontainmorethanoneUDFimplementationmethods.

Thefunctionmethodmustbepublicandstatic.

CodeRequirementsForUDAFs

Thejavaclasscontainingthefunctionmethodmustbedefinedpublicandextendorg.teiid.UserDefinedAggregate

Thefunctionmethodmustbepublic.

OtherConsiderations

Anyexceptioncanbethrown,butTeiidwillrethrowtheexceptionasaFunctionExecutionException.


258

Youmayoptionallyaddanadditionalorg.teiid.CommandContextargumentasthefirstparameter.TheCommandContextinterfaceprovidesaccesstoinformationaboutthecurrentcommand,suchastheexecutinguser,Subject,thevdb,thesessionid,etc.ThisCommandContextparametershouldnotbedeclaredinthefunctionmetadata.

SampleUDFcode

packageorg.something;

publicclassTempConv

{

/**

*ConvertsthegivenCelsiustemperaturetoFahrenheit,andreturnsthe

*value.

*@paramdoubleCelsiusTemp

*@returnFahrenheit

*/

publicstaticDoublecelsiusToFahrenheit(DoubledoubleCelsiusTemp)

{

if(doubleCelsiusTemp==null)

{

returnnull;

}

return(doubleCelsiusTemp)*9/5+32;

}

}

SampleUDAFcode


publicstaticclassSumAllimplementsUserDefinedAggregate<Integer>{

privatebooleanisNull=true;

privateintresult;

publicvoidaddInput(Integer...vals){

isNull=false;

for(inti:vals){

result+=i;

}

}

@Override

publicIntegergetResult(org.teiid.CommandContextcommandContext){

if(isNull){

returnnull;

}

returnresult;

}

@Override

publicvoidreset(){

isNull=true;

result=0;

}

}

SampleCommandContextUsage


publicclassSessionInfo

{

/**

*@paramcontext


259

*@returnthecreatedTimestamp

*/

publicstaticTimestampsessionCreated(CommandContextcontext)

{

returnnewTimestamp(context.getSession().getCreatedTime());

}

}

ThecorrespondingUDFwouldbedeclaredasTimestampsessionCreated().

PostCodeActivities

AftercodingthefunctionsyoushouldcompiletheJavacodeintoaJavaArchive(JAR)file.

ZipDeployment

TheJARfilemaybeplacedinyourVDBunderthe"/lib"directory.ItwillautomaticallybeusedfortheVDBclassloaderclasspathwhendeployed.

ASModule

CreateaWildFlymodulewiththeJARfileunder<jboss-as>/modulesdirectoryanddefinethemoduleonthe-vdb.xmlfileasshownbelowexample


<propertyname="lib"value="{module-name}"></property>

...

</vdb>

Thelibpropertyvaluemaycontainaspacedelimitedlistofmodulenamesifmorethanonedependencyisneeded.


260

AdminAPIInmostcircumstancestheadminoperationswillbeperformedthroughtheadminconsoleorAdminShelltooling,butitisalsopossibletoinvokeadminfunctionalitydirectlyinJavathroughtheAdminAPI.

AllclassesfortheAdminAPIareintheclientjarundertheorg.teiid.adminapipackage.

Connecting

AnAdminAPIconnection,whichisrepresentedbytheorg.teiid.adminapi.Admininterface,isobtainedthroughtheorg.teiid.adminapi.AdminFactory.createAdminmethods.AdminFactoryisasingletonintheteiid-jboss-adminjar,seeAdminFactory.getInstance().TheAdmininstanceautomaticallytestsitsconnectionandreconnectstoaserverintheeventofafailure.Theclosemethodshouldbecalledtoterminatetheconnection.

SeeyourJBossinstallationfortheappropriateadminport-thedefaultportis9999.

AdminMethodsAdminmethodsexistformonitoring,serveradministration,andconfigurationpurposes.Notethattheobjectsreturnedbythemonitoringmethods,suchasgetRequests,areread-onlyandcannotbeusedtochangeserverstate.SeetheJavaDocsforallofthedetails

AdminAPI

261

CustomLoggingTheTeiidsystemprovidesawealthofinformationusinglogging.Tocontrollogginglevel,contexts,andloglocations,youshouldbefamiliarwithcontainer’sstandalone.xmlordomain.xmlconfigurationfileandcheckout"logging"subsystem.RefertotheAdministrator’sGuideformoredetailsaboutdifferentTeiidcontextsavailable.

Ifyouwantacustomloghandler,followthedirectionstowriteacustomjava.util.logging.Handler.IfyoudevelopacustomloggingHandler,theimplementationclassalongshouldbeplacedasajarin"org.jboss.teiid"moduleanddefineitsnameinthemodule.xmlfileaspartofthemodulealongwithanydependenciesitmayneed.Seebelow.

CommandLoggingAPI

Ifyouwanttobuildacustomhandlerforcommandloggingthatwillhaveaccesstojava.util.loggingLogRecordstothe"COMMAND_LOG"context,thehandlerwillreceiveainstanceofLogRecordmessage,thisobjectwillcontainaparameteroftypeorg.teiid.logging.CommandLogMessage.TherelevantTeiidclassesaredefinedintheteiid-api-9.0.0.Final.jar.TheCommmdLogMessageincludesinformationaboutvdb,session,commandsql,etc.CommandLogMessagesareloggedattheINFO(userqueries),DEBUG(sourcequeries),andTRACE(queryplan)levels.

SampleCommandLogMessageUsage


importjava.util.logging.Handler;

importjava.util.logging.LogRecord;

publicclassCommandHandlerextendsHandler{

@Override

publicvoidpublish(LogRecordrecord){

CommandLogMessagemsg=(CommandLogMessage)record.getParameters()[0];

//logtoadatabase,triggeranemail,etc.

}

@Override

publicvoidflush(){

}

@Override

publicvoidclose()throwsSecurityException{

}

}

AuditLoggingAPI

Ifyouwanttobuildacustomhandlerforcommandloggingthatwillhaveaccesstojava.util.loggingLogRecordstothe"AUDIT_LOG"context,thehandlerwillreceiveainstanceofLogRecordmessage,thisobjectwillcontainaparameteroftypeorg.teiid.logging.AuditMessage.TheAuditMessageincludesinformationaboutuser,theaction,andthetarget(s)oftheaction.TherelevantTeiidclassesaredefinedintheteiid-api-9.0.0.Final.jar.AuditMessagesareloggedattheDEBUGlevel.AuditMessagesareusedforbothdatarolevalidationandforlogon/logoffevents.OnlylogoneventswillcontainLogonInfo.

SampleAuditMessageUsage


importjava.util.logging.Handler;

importjava.util.logging.LogRecord;

publicclassAuditHandlerextendsHandler{

@Override

CustomLogging

262

http://docs.oracle.com/javase/6/docs/api/java/util/logging/Handler.html

http://docs.oracle.com/javase/6/docs/api/java/util/logging/LogRecord.html

http://docs.oracle.com/javase/6/docs/api/java/util/logging/LogRecord.html

publicvoidpublish(LogRecordrecord){

AuditMessagemsg=(AuditMessage)record.getParameters()[0];

//logtoadatabase,triggeranemail,etc.

}

@Override

publicvoidflush(){

}

@Override

publicvoidclose()throwsSecurityException{

}

}

ConfigurationNowthatyouhavedevelopedacustomhandlerclass,nowpackageimplementationinJarfile,thencopythisJarfileinto<jboss-as7>/modules/org/jboss/teiid/mainfolder,andeditmodule.xmlfileinthesamedirectoryandadd

<resource-rootpath="{your-jar-name}.jar"/>

thenusetheclitoupdatetheloggingconfiguration,suchasshownwiththeauditcommandscriptsinthebin/scriptsdirectoryoreditstandalone-teiid.xmlordomain.xmlfilebylocatingthe"logging"subsystemandaddthefollowingentries:

<custom-handlername="COMMAND"class="org.teiid.logging.CommandHandler"

module="org.jboss.teiid">

</custom-handler>

..otherentries



<handlers>

<handlername="COMMAND"/>

</handlers>

</logger>

ChangetheaboveconfigurationaccordinglyforAuditHandler,ifyouareworkingwithAuditMessages.

CustomLogging

263

RuntimeUpdatesTeiidsupportsseveralmechanismsforupdatingtheruntimesystem.

DataUpdates

DatachangeeventsareusedbyTeiidtoinvalidateresultsetcacheentries.Resultsetcacheentriesaretrackedbythetablesthatcontributedtotheirresults.BydefaultTeiidwillcaptureinternaldataeventsagainstphysicalsourcesanddistributethemacrossthecluster.Thisapproachhasseverallimitations.FirstupdatesarescopedonlytotheiroriginatingVDB/version.SecondupdatesmadeoutsideofTeiidarenotcaptured.ToincreasedataconsistencyexternalchangedatacapturetoolscanbeusedtosendeventstoTeiid.FromwithinaTeiidclustertheorg.teiid.events.EventDistributorFactoryandorg.teiid.events.EventDistributorcanbeusedtodistributechangeevents.TheEventDistributorFactorycanbelookedupbyitsname"teiid/event-distributor-factory".SeeProgrammaticControlforadataModificationexample.

Whenexternallycapturingallupdateevents,"detect-change-events"propertyintheteiidsubsystemincanbesettofalse,tonotduplicatechangeevents.Bydefault,thispropertyissettotrue.

Note Usingtheorg.teiid.events.EventDistributorinterfaceyoucanalsoupdateruntimemetadata.PleasechecktheAPI.

TheuseoftheotherEventDistributormethodstomanuallydistributeothereventsisnotalwaysnecessary.ChecktheSystemProceduresforSQLbasedupdates.

RuntimeMetadataUpdates

RuntimeupdatesviasystemproceduresandDDLstatementsarebydefaultephemeral.Theyareeffectiveacrosstheclusteronlyforthecurrentlyrunningvdbs.Withthenextvdbstartthevalueswillreverttowhateverisstoredinthevdb.Updatesmaybemadepersistentthoughbyconfiguringaorg.teiid.metadata.MetadataRepository.AninstanceofaMetadataRepositorycanbeinstalledviaVDBfile.InDesignerbasedVDB,youcaneditthevdb.xmlfileintheMETA-INFdirectoryoruseVDBfileasbelow.


<modelname="{model-name}"type="VIRTUAL">

<metadatatype="{jboss-as-module-name}"></metadata>

</model>

</vdb>

Intheabovecodefragment,replacethe{jboss-as-module-name}withaWildFlymodulenamethathaslibrarythatimplementstheorg.teiid.metadata.MetadataRepositoryinterfaceanddefinesfile"META-INF/services/org.teiid.metadata.MetadataRepository"withnameoftheimplementationfile.

TheMetadataRepositoryrepositoryinstancemayfullyimplementasmanyofthemethodsasneededandreturnnullfromanyunneededgetter.

Itisnotrecommendedtodirectlymanipulateorg.teiid.metadata.AbstractMetadataRecordinstances.SystemproceduresandDDLstatementsshouldbeusedinsteadsincetheeffectswillbedistributedthroughtheclusterandwillnotintroduceinconsistencies.

org.teiid.metadata.AbstractMetadataRecordobjectspassedtotheMetadataRepositoryhavenotyetbeenmodified.IftheMetadataRepositorycannotpersisttheupdate,thenaRuntimeExceptionshouldbethrowntopreventtheupdatefrombeingappliedbytheruntimeengine.

RuntimeUpdates

264

TheMetadataRepositorycanbeaccessedbymultiplethreadsbothduringloadoratruntimewiththroughDDLstatements.Yourimplementationshouldhandleanyneededsynchronization.

CostingUpdates

SeetheReferenceforthesystemproceduresSYSADMIN.setColumnStatsandSYSADMIN.setTableStats.TomakecostingupdatespersistentMetadataRepositoryimplementationsshouldbeprovidedfor:

TableStatsgetTableStats(StringvdbName,StringvdbVersion,Tabletable);

voidsetTableStats(StringvdbName,StringvdbVersion,Tabletable,TableStatstableStats);

ColumnStatsgetColumnStats(StringvdbName,StringvdbVersion,Columncolumn);

voidsetColumnStats(StringvdbName,StringvdbVersion,Columncolumn,ColumnStatscolumnStats);

SchemaUpdates

SeetheReferenceforsupportedDDLstatements.Tomakeschemaupdatespersistentimplementationsshouldbeprovidedfor:

StringgetViewDefinition(StringvdbName,StringvdbVersion,Tabletable);

voidsetViewDefinition(StringvdbName,StringvdbVersion,Tabletable,StringviewDefinition);

StringgetInsteadOfTriggerDefinition(StringvdbName,StringvdbVersion,Tabletable,Table.TriggerEventtrigger

Operation);

voidsetInsteadOfTriggerDefinition(StringvdbName,StringvdbVersion,Tabletable,Table.TriggerEventtriggerOp

eration,StringtriggerDefinition);

booleanisInsteadOfTriggerEnabled(StringvdbName,StringvdbVersion,Tabletable,Table.TriggerEventtriggerOpe

ration);

voidsetInsteadOfTriggerEnabled(StringvdbName,StringvdbVersion,Tabletable,Table.TriggerEventtriggerOpera

tion,booleanenabled);

StringgetProcedureDefinition(StringvdbName,StringvdbVersion,Procedureprocedure);

voidsetProcedureDefinition(StringvdbName,StringvdbVersion,Procedureprocedure,StringprocedureDefinition)

;

LinkedHashMap<String,String>getProperties(StringvdbName,StringvdbVersion,AbstractMetadataRecordrecord);

voidsetProperty(StringvdbName,StringvdbVersion,AbstractMetadataRecordrecord,Stringname,Stringvalue);

RuntimeUpdates

265

CustomMetadataRepositoryIfaboveprovidedmetadatafacilitiesarenotsufficientthenadevelopercanextendtheMetadataRepositoryclassprovidedintheorg.teiid.apijartoplug-intheirownmetadatafacilitiesintotheTeiidengine.Forexample,ausercanwriteametadatafacilitythatisbasedonreadingdatafromadatabaseoraJCRrepository.SeeSettingupthebuildenvironmenttostartdevelopment.ForExample:

SampleJavaCode

importorg.teiid.metadata.MetadataRepository;

...

packagecom.something;

publicclassCustomMetadataRepositoryextendsMetadataRepository{

@Override

publicvoidloadMetadata(MetadataFactoryfactory,ExecutionFactoryexecutionFactory,ObjectconnectionFacto

ry)

throwsTranslatorException{

/*Provideimplementationandfillthedetailsinfactory*/

...

}

}

ThenbuildaJARarchivewithaboveimplementationclassandcreatefileanamedorg.teiid.metadata.MetadataRepositoryintheMETA-INF/servicesdirectorywithcontents:

com.something.CustomMetadataRepository

OncetheJARfilehasbeenbuilt,itneedstobedeployedintheWildFlyasamoduleunder<jboss-as>/modulesdirectory.Followthebelowstepstocreateamodule.

Createadirectory<jboss-as>/modules/com/something/main

Underthisdirectorycreatea"module.xml"filethatlookslike

Samplemodule.xmlfile


<modulexmlns="urn:jboss:module:1.0"name="com.something">

<resources>

<resource-rootpath="something.jar"/>

</resources>

<dependencies>


<modulename="javax.resource.api"/>

<modulename="org.jboss.teiid.common-core"/>

<modulename="org.jboss.teiid.teiid-api"/>

</dependencies>

</module>

Copythejarfileunderthissamedirectory.Makesureyouaddanyadditionaldependenciesifrequiredbyyourimplementationclassunderdependencies.

Restarttheserver

ThebelowXMLfragmentshowshowtoconfiguretheVDBwiththecustommetadatarepositorycreated

Samplevdb.xmlfile


266




<metadatatype="{metadata-repo-module}"></metadata>

</model>

</vdb>

NowwhenthisVDBgetsdeployed,itwillcalltheCustomMetadataRepositoryinstanceformetadataofthemodel.UsingthisyoucandefinemetadataforsinglemodelorforthewholeVDBpragmatically.Becarefulaboutholdingstateandsynchronizationinyourrepositoryinstance.

DevelopmentConsiderations

MetadataRepositoryinstancesarecreatedonapervdbbasisandmaybecalledconcurrentlyfortheloadofmultiplemodels.

SeetheMetadataFactoryandtheorg.teiid.metadatapackagejavadocsformetadataconstructionmethodsandobjects.ForexampleifyouuseyourownDDL,thencalltheMetadataFactory.parse(Reader)method.IfyouneedaccesstofilesinaVDBzipdeployment,thenusetheMetadataFactory.getVDBResourcesmethod.

UsetheMetadataFactory.addPermissionandaddMetadataFactory.addColumnPermissionmethodtograntpermissionsonthegivenmetadataobjectstothenamedroles.Therolesshouldbedeclaredinyourvdb.xml,whichisalsowheretheyaretypicallytiedtocontainerroles.


267

PreParserIfitisdesirabletomanipulateincomingqueriespriortobeinghandledbyTeiidlogic,thenacustompre-parsercanbeinstalled.UsethePreParserinterfaceprovidedintheorg.teiid.apijartoplug-inapre-parserfortheTeiidengine.SeeSettingupthebuildenvironmenttostartdevelopment.ForExample:

SampleJavaCode

importorg.teiid.PreParser;

...

packagecom.something;

publicclassCustomPreParserimplementsPreParser{

@Override

publicStringpreParse(Stringcommand,CommandContextcontext){

//manipulatethecommand

}

}

ThenbuildaJARarchivewithaboveimplementationclassandcreateafilenamedorg.teiid.PreParserinMETA-INF/servicesdirectorywithcontents:

com.something.CustomPreParser

Thethejarhasbeenbuilt,thisneedstobedeployedintheWildFlyasamoduleunder<jboss-as>/modulesdirectory.Followthebelowstepstocreateamodule.

Createadirectory<jboss-as>/modules/com/something/main

Underthisdirectorycreateamodule.xmlfilethatlookslike

Samplemodule.xmlfile


<modulexmlns="urn:jboss:module:1.0"name="com.something">

<resources>

<resource-rootpath="something.jar"/>

</resources>

<dependencies>


<modulename="javax.resource.api"/>


<modulename="org.jboss.teiid.teiid-api"/>

</dependencies>

</module>

Copythejarfileunderthissamedirectory.Makesureyouaddanyadditionaldependenciesifrequiredbyyourimplementationclassunderdependencies.

Usethecliormodifytheconfigurationtosetthepreparser-moduleintheTeiidsubsystemconfigurationtotheappropriatemodulename.

Restarttheserver

DevelopmentConsiderations

PreParser

268

Changingtheincomingquerytoadifferenttypeofstatementisnotrecommendedasareanymodificationstothenumberortypesofprojectedsymbols.

PreParser

269

EmbeddedGuideEmbeddedisalight-weightversionofTeiidforuseinanyJava7+JRE.WildFlynoranyapplicationserverisnotrequired.Thisfeature/kitarestillevolving.PleaseconsultthesourceexamplesandevenunittestsutilizingtheEmbeddedServerforamorecompleteguideastoitsuse.

TableofContentsConfigurationTheClasspath

EmbeddedkitOSGIMavenVulnerableLibraries

VDBDeploymentAccessfromclientapplicationsSecurity

ExampleTransactionsAdminApiLoggingOtherDifferencesBetweenTeiidEmbeddedandanASDeployment

Configuration

TheprimarywaytoconfigureTeiidEmbeddediswiththeEmbeddedConfigurationclass.ItisprovidedtotheEmbeddedServeratstart-upanddictatesmuchofthebehavioroftheembeddedinstance.FromtheretherunningserverinstancemayhavetranslatorsandVDBsdeployedasneeded.AdditionalmodificationstotheEmbeddedConfigurationaftertheserverisstartedwillnothaveaneffect.

InmanycasesanEmbeddedConfigurationinstancecanjustbeinstantiatedandpassedtotheEmbeddedServerwithouttheneedtosetadditionalproperties.Manyproperties,includingthoseusedtoconfiguretheBufferManager,willbegivenasimilarnametotheirserversidecounterpart-forexamplesetProcessorBatchSize.

ImportantMostofthedefaultconfigurationvaluesformemoryandthreadsassumethatthereisonlyoneTeiidinstanceinthevm.IfyouareusingmultipleTeiidEmbeddedinstancesinthesamevm,thenmemoryandthreadresourcesshouldbeconfiguredmanually.

TheClasspath

Embeddedkit

YourapplicationisresponsibleforhavingtheappropriateclasspathtoutilizeTeiidembedded.Typicallyyouwillwanttoincludeallofthejarsfromtheembeddedkit’slibdirectory.Asneededbyyourdeploymentyoushouldincludejarsfromtheoptionalfolderalongwithanyjarsneededtoprovidesourceaccess.Hibernatecore4.1.6orcompatibleisneeded,butnotincludedinthekit,ifyouwishtoutilizetheJDBCtranslatorsupportfordependentjoinsusingtemptables.

OSGI

EmbeddedGuide

270

AllTeiidjarscanalsobedeployedasbundlesinaOSGIcontainerlikeKaraf.IfyouareworkingwithKaraf,afeature.xmlfileisavailableinmavenrepoforyourconvenience.Usagepatternisbelow

features:addurlmvn:org.jboss.teiid/teiid/8.6.0.Final/xml/karaf-features

features:install-vteiid

Maven

IfyouaretryingrunTeiddEmbeddedwithMavenbasedprojectandusingmaventopullartifacts,theruntime,admin,connector,translatordependenciesarenecessaryasbelow

<dependency>


<artifactId>teiid-runtime</artifactId>

</dependency>

<dependency>


<artifactId>teiid-admin</artifactId>

</dependency>

<dependency>

<groupId>org.jboss.teiid.connectors</groupId>

<artifactId>translator-SOURCE</artifactId>

</dependency>

<dependency>

<groupId>org.jboss.teiid.connectors</groupId>

<artifactId>connector-SOURCE</artifactId>

</dependency>

VulnerableLibraries

PriortoTeiid8.13/8.12.2whenusingtheremoteJDBCtransport,Teiidembeddedcouldbesusceptibletodeserializationexploitsifitalsoincludedmostversionsofcommon-collections,olderversionofgroovy,orspringintheclasspath-seealsothispostingformoredetailsontheaffectedlibraries.

VDBDeployment

VDBsmaybedeployedinseveralwaysinEmbedded.

VDBMetadataAPI

VDBdeploymentcanbedonedirectlythroughVDBmetadataobjectsthataretheunderpinningofvdb.xmldeployment.Models(schemas)aredeployedasasettoformanamedvdb-seetheEmbeddedServer.deployVDBmethod.

XMLDeployment

Similartoaserverbased-vdb.xmldeploymentanInputStreammaybegiventoavdb.xmlfile-seetheEmbeddedServer.deployVDB(InputStream)method.

ZipDeployment

Similartoaserverbased.vdbdeploymentaURLmaybegiventoazipfile-seetheEmbeddedServer.deployVDBZipmethod.TheuseoftheziplibfordependencyloadingisnotenabledinEmbedded.SeeVDBsWithoutToolingandMetadataRepositoriesformoreonatypicalvdbzipstructure.TeiidDesigner7andlaterVDBsarealsosupportedviathismethod,butaresubjecttoallofthelimitations/differenceshighlightedinthisguide.

EmbeddedGuide

271

http://www.infoq.com/news/2015/11/commons-exploit

Translators

TranslatorsinstancescanbescopedtoaVDBinASusingdeclarationsinavdb.xmlfile,howevernamedinstancesinembeddedarescopedtotheentireEmbeddedServerandmustberegisteredviatheEmbeddedServer.addTranslatormethods.NotethattherearetwoaddTranslatormethods:

addTranslator(Class<?extendsExecutionFactory>clazz)-AddsadefaultinstanceoftheExecutionFactory,usingthedefaultnameeitherfromtheTranslatorannotationortheclassname.

addTranslator(Stringname,ExecutionFactory<?,?>ef)-Addsapre-initialized(ExecutionFactory.start()musthavealreadybeencalled)instanceoftheExecutionFactory,usingthegiventranslatorname,thisisfunctionallyequivalenttousingavdb.xmltranslatoroverride.

Anewserverinstancedoesnotassumeanytranslatorsaredeployedanddoesnotperformanysortoflibraryscanningtofindtranslators.

Sources

TheEmbeddedServerwillstillattempttolookupthegivenJNDIconnectionfactorynamesviaJNDI.Inmostnon-containerenvironmentsitislikelythatnosuchbindingsexist.InthiscasetheEmbeddedServerinstancemusthaveConnectionFactoryProviderinstancesmanuallyregistered,eitherusingtheEmbeddedServer.addConnectionFactorymethod,ortheEmbeddedServer.addConnectionFactoryProvidermethodtoimplementConnectionFactoryProviderregistering.NotethattheEmbeddedServerdoesnothavebuilt-inpoolinglogic,sotomakebetteruseofastandardjava.sql.DataSourceortoenableproperuseofjavax.sql.XADataSourceyoumustfirstconfiguretheinstanceviaathird-partyconnectionpool.

Example-Deployment

EmbeddedServeres=newEmbeddedServer();

EmbeddedConfigurationec=newEmbeddedConfiguration();

//setanyconfigurationproperties

ec.setUseDisk(false);

es.start(ec);

//exampleofaddingatranslatorbypre-initializedExecutionFactoryandgiventranslatorname

H2ExecutionFactoryef=newH2ExecutionFactory()

ef.setSupportsDirectQueryProcedure(true);

ef.start();

es.addTranslator("translator-h2",ef);

//addaConnectionFactorywithathird-partyconnectionpool

DataSourceds=EmbeddedHelper.newDataSource("org.h2.Driver","jdbc:h2:mem://localhost/~/account","sa","sa");

es.addConnectionFactory("java:/accounts-ds",ds);

//addavdb

//physicalmodel

ModelMetaDatammd=newModelMetaData();

mmd.setName("my-schema");

mmd.addSourceMapping("my-schema","translator-h2","java:/accounts-ds");

//virtualmodel

ModelMetaDatammd1=newModelMetaData();

mmd1.setName("virt");

mmd1.setModelType(Type.VIRTUAL);

mmd1.setSchemaSourceType("ddl");

mmd1.setSchemaText("createview\"my-view\"OPTIONS(UPDATABLE'true')asselect*from\"my-table\"");

es.deployVDB("test",mmd,mmd1);

SecuredDataSources

IfSourcerelatedsecurityauthentication,forexample,ifyouwantconnect/federate/integrateTwittersuppliedrestsource,asecurityauthenticationisanecessary,thefollowingstepscanusetoexecutesecurityauthentication:

EmbeddedGuide

272

1. refertoSecureEmbeddedwithPicketBoxstartsectiontodevelopaSubjectFactory,

2. initializeaConnectionManagerwithironjacamarlibaries,setSubjectFactorytoConnectionManager

3. usethefollowingmethodtocreateConnectionFactory

Example-SecuredDataSources

WSManagedConnectionFactorymcf=newWSManagedConnectionFactory();

NoTxConnectionManagerImplcm=newNoTxConnectionManagerImpl();

cm.setSecurityDomain(securityDomain);

cm.setSubjectFactory(newEmbeddedSecuritySubjectFactory(authConf))

ObjectconnectionFactory=mcf.createConnectionFactory(cm);

server.addConnectionFactory("java:/twitterDS",connectionFactory);

twitter-as-a-datasourceisacompletedexample.

Accessfromclientapplications

TypicallywhenTeiidisdeployedasEmbeddedServer,andifyourenduserapplicationisalsodeployedinthesamevirtualmachineastheTeiidEmbedded,youcanuseLocalJDBCConnection,toaccesstoyourvirtualdatabase.Forexample:

Example-LocalJDBCConnection

EmbeddedServeres=...

Driverdriver=es.getDriver();

Connectionconn=driver.connect("jdbc:teiid:<vdb-name>",null);

//doworkwithconn;createstatementandexecuteit

conn.close();

Thisisthemostefficientmethodasitdoesnotimposeanyserializationofobjects.

IfyourclientapplicationisdeployedinremoteVM,oryourclientapplicationisnotaJAVAbasedapplicationthenaccessestotheTeiidEmbeddedisnotpossiblethroughabovemechanism.Inthosesituations,youneedtoopenasocketbasedconnectionfromremoteclientapplicationtotheEmbeddedTeiidServer.Bydefault,whenyoustarttheEmbeddedTeiidSeveritdoesnotaddanycapabilitiestoacceptremoteJDBC/ODBCbasedconnections.IfyouwouldliketoexposethefunctionalitytoacceptremoteJDBC/ODBCconnectionrequests,thenconfigurenecessarytransportsduringtheinitializationoftheTeiidEmbeddedServer.TheexamplebelowshowsasamplecodetoenableaODBCtransport

Example-RemoteODBCtransport

EmbeddedServeres=newEmbeddedServer()

SocketConfigurations=newSocketConfiguration();

s.setBindAddress("<host-name>");

s.setPortNumber(35432);

s.setProtocol(WireProtocol.pg);


config.addTransport(s);

es.start(config);

Example-SSLtransport

EmbeddedServerserver=newEmbeddedServer();

...


SocketConfigurationsocketConfiguration=newSocketConfiguration();

SSLConfigurationsslConfiguration=newSSLConfiguration();

//Settingsshownwiththeirdefaultvalues

//sslConfiguration.setMode(SSLConfiguration.ENABLED);

EmbeddedGuide

273

http://ironjacamar.org/

https://github.com/teiid/teiid-embedded-examples/tree/master/socialmedia-integration/twitter-as-a-datasource

//sslConfiguration.setAuthenticationMode(SSLConfiguration.ONEWAY);

//sslConfiguration.setSslProtocol(SocketUtil.DEFAULT_PROTOCOL);

//sslConfiguration.setKeymanagementAlgorithm(KeyManagerFactory.getDefaultAlgorithm());

//optionallyrestricttheciphersuites

//sslConfiguration.setEnabledCipherSuites("SSL_RSA_WITH_RC4_128_MD5,SSL_RSA_WITH_RC4_128_SHA");

//fortheserverkey

sslConfiguration.setKeystoreFilename("ssl-example.keystore");

sslConfiguration.setKeystorePassword("redhat");

sslConfiguration.setKeystoreType("JKS");

sslConfiguration.setKeystoreKeyAlias("teiid");

sslConfiguration.setKeystoreKeyPassword("redhat");

//fortwowaysslsetatruststoreforclientcerts

//sslConfiguration.setTruststoreFilename("ssl-example.truststore");

//sslConfiguration.setTruststorePassword("redhat");

socketConfiguration.setSSLConfiguration(sslConfiguration);

config.addTransport(socketConfiguration);


ifyouwanttoaddaJDBCtransport,followtheinstructionsabove,howeversettheprotocoltoWireProtocol.teiidandchooseadifferentportnumber.Oncetheaboveserverisrunning,youcanusesameinstructionsasTeiidServertoaccessEmbeddedTeiidServerfromremoteclientapplication.NotethatyoucanaddmultipletransportstosingleEmbeddedServerinstance,toexposedifferenttransports.

Security

TheprimaryinterfaceforTeiidembedded’ssecurityistheorg.teiid.security.SecurityHelperintheenginejar.TheSecurityHelperinstanceisassociatedwithwiththeEmbeddedServerviaEmbeddedConfiguration.setSecurityHelper.IfnoSecurityHelperisset,thennoauthenticationwillbeperformed.ASecurityHelpercontrolsauthenticationandassociatesasecuritycontextwithathread.Howasecuritycontextisobtainedcandependuponthesecuritydomainname.Thedefaultsecuritydomainnameisteiid-securityandcanbechangedviaEmbeddedConfiguration.setSecurityDomain.TheeffectivesecuritydomainmayalsobeconfiguredviaatransportoftheVDB.

SeetheJBossSecurityHelpersourceforanexampleofexpectedmechanics.

YoucanjustreturnnullfromnegotiateGssLoginunlessyouwanttoallGSSauthenticationsfromJDBC/ODBC.

Example

embedded-portfolio-securitydemonstrateshowtoimplementsecurityauthenticationinTeiidEmbedded:

EmbeddedSecurityHelperistheimplementationoforg.teiid.security.SecurityHelper

users.propertiesandroles.propertiesinclasspathusertopredefineusersandroles

application-policy’snameinauthentication.confshouldmatchtosecuritydomain(EmbeddedConfiguration.setSecurityDomain)

Transactions

TransactionprocessingrequiressettingtheTransactionManagerintheEmbeddedConfigurationusedtostarttheEmbeddedServer.Aclientfacingjavax.sql.DataSourceisnotprovidedforembedded.Howevertheusageofprovidedjava.sql.Drivershouldbesufficientastheembeddedserverisbydefaultabletodetectthreadboundtransactionsand

EmbeddedGuide

274

https://github.com/teiid/teiid/blob/master/jboss-integration/src/main/java/org/teiid/jboss/JBossSecurityHelper.java

https://github.com/teiid/teiid-embedded-examples/tree/master/embedded-portfolio-security

https://github.com/teiid/teiid-embedded-examples/blob/master/common/src/main/java/org/teiid/example/EmbeddedSecurityHelper.java

https://raw.githubusercontent.com/teiid/teiid-embedded-examples/master/embedded-portfolio-security/src/main/resources/users.properties

https://raw.githubusercontent.com/teiid/teiid-embedded-examples/master/embedded-portfolio-security/src/main/resources/roles.properties

https://raw.githubusercontent.com/teiid/teiid-embedded-examples/master/common/src/main/resources/picketbox/authentication.conf

appropriatelypropagatethetransactiontothreadslaunchedaspartofrequestprocessing.Theusageoflocalconnectionsisalso

permitted.

AdminApi

EmbeddedprovidesatheAdmininterfaceviatheEmbeddedServer.getAdminmethod.Notallmethodsareimplementedforembedded-forexamplethosethatdealwithdatasources.AlsothedeploymethodmayonlydeployVDBxmlartifacts.

Logging

TeiidbydefaultuseJBossLogging,whichwillutilizeJUL(JavaUtilLogging)orothercommonloggingframeworksdependingupontheirpresenceintheclasspath.RefertoLogginginTeiidEmbeddedfordetails.

TheinternalinterfaceforTeiidembedded’sloggingisorg.teiid.logging.Loggerinteiid-apijar.TheLoggerinstanceisassociatedwiththeorg.teiid.logging.LogManagerviastaticmethodLogManager.setLogListener().YoumayalternativelychoosetodirectlysetaLoggerofyourchoice.

OtherDifferencesBetweenTeiidEmbeddedandanASDeployment

ThereisnodefaultJDBC/ODBCsockettransportinembedded.YouareexpectedtoobtainaDriverconnectionviatheEmbeddedServer.getDrivermethod.IfyouwantremoteJDBC/ODBCtransportseeaboveonhowtoaddatransport.

AMetadataRepositoryisscopedtoaVDBinAS,butisscopedtotheentireEmbeddedServerinstanceandmustberegisteredviatheEmbeddedServer.addMetadataRepositorymethod.

MDCloggingvaluesarenotavailableasJavalogginglackstheconceptofamappeddiagnosticcontext.

Translatoroverridesinvdb.xmlfilesisnotsupported.

Thelegacyfunctionmodelisnotsupported.

EmbeddedGuide

275

LogginginTeiidEmbeddedTeiid’sLogManagerisaninterfacetoasingleloggingframeworkthatiseasilyaccessiblebyanycomponent.UsingtheLogManager,acomponentcanquicklysubmitalogmessage,andcanrelyupontheLogManagertodetermine

whetherthatmessageistoberecordedordiscarded

wheretosendanyrecordedmessages

JBossLoggingJBossLoggingisusedbydefault.TheJBossLoggingjarisalreadyinthekitandyoujustneedtoensurethejboss-logginglibraryisinyourclasspath.IfyouuseMaven,addthedependencyasshownbelow:

<dependency>

<groupId>org.jboss.logging</groupId>

<artifactId>jboss-loggging</artifactId>

</dependency>

BridgingwithJBossLoggingJBossLogManagerisareplacementfortheJDKloggingsystemLogManagerthatfixesorworksaroundmanyseriousproblemsinthedefaultimplementation.TouseJBossLogManagerwithJBossLogging,theonlyneedtodoisaddjboss-logmanagerlibrarytoclasspath.IfuseMaventopulldependencies,addthedependencyasshownbelow:

<dependency>

<groupId>org.jboss.logging</groupId>

<artifactId>jboss-logmanager</artifactId>

</dependency>

TeiidEmbeddedLoggingisaexampleforLoggingwithJBossLogManager.

Asamplelogging.propertiesforTeiidEmbedded:

loggers=sun.rmi,com.arjuna

logger.level=TRACE

logger.handlers=FILE,CONSOLE

logger.sun.rmi.level=WARN

logger.sun.rmi.useParentHandlers=true

logger.com.arjuna.level=WARN

logger.com.arjuna.useParentHandlers=true

handler.CONSOLE=org.jboss.logmanager.handlers.ConsoleHandler

handler.CONSOLE.level=INFO

handler.CONSOLE.formatter=COLOR-PATTERN

handler.CONSOLE.properties=autoFlush,target,enabled

handler.CONSOLE.autoFlush=true


276

https://raw.githubusercontent.com/teiid/teiid-embedded-examples/master/embedded-logging/src/main/java/org/teiid/example/TeiidEmbeddedLogging.java

handler.CONSOLE.target=SYSTEM_OUT

handler.CONSOLE.enabled=true

handler.FILE=org.jboss.logmanager.handlers.PeriodicRotatingFileHandler

handler.FILE.formatter=PATTERN

handler.FILE.properties=append,autoFlush,enabled,suffix,fileName

handler.FILE.constructorProperties=fileName,append

handler.FILE.append=true

handler.FILE.autoFlush=true

handler.FILE.enabled=true

handler.FILE.suffix=.yyyy-MM-dd

handler.FILE.fileName=target/teiid-embedded.log

formatter.PATTERN=org.jboss.logmanager.formatters.PatternFormatter

formatter.PATTERN.properties=pattern

formatter.PATTERN.pattern=%d{yyyy-MM-ddHH\:mm\:ss,SSS}%-5p\[%c\](%t)%s%e%n

formatter.COLOR-PATTERN=org.jboss.logmanager.formatters.PatternFormatter

formatter.COLOR-PATTERN.properties=pattern

formatter.COLOR-PATTERN.pattern=%K{level}%d{HH\:mm\:ss,SSS}%-5p\[%c\](%t)%s%e%n

BridgingwithLog4jTobridgeJBossLoggingwithLog4j,theonlyneedtodoishavea1.xlog4jjarinyourclasspath.

IfyoursystemuseLog4jasloggingframework,withaboveJBossLogManagerbridgeLog4jfunctionalityandstepsinBridgingwithJBossLogging,it’seasytosetuploggingframeworkconsistentbetweenTeiidEmbeddedandyoursystem.


277

SecureEmbeddedwithPicketBoxSecureEmbeddedwithPicketBox.

TableofContentsStepsofimplementaJAASauthenticationHowtodevelopaSecurityHelperEmbeddedSecuritywithUsersRolesLoginModuleEmbeddedSecuritywithLdapExtLoginModule

StepsofimplementaJAASauthentication

PicketBoxisaJavaSecurityFrameworkthatbuildontopofJAAS.PicketBoxisconfiguredviaaschemaformattedSecurityConfigurationFile(security-config_5_0.xsd)andprovidesvariousLoginModuleImplementations(UsersRolesLoginModule,LdapExtLoginModule,DatabaseServerLoginModule,etc).Thefollowingare5keystepstoexecuteaauthentication:

//1.establishtheJAASConfigurationwithpicketboxauthenticationxmlfile

SecurityFactory.prepare();

//2.loadpicketboxauthenticationxmlfile

PicketBoxConfigurationconfig=newPicketBoxConfiguration();

config.load(SampleMain.class.getClassLoader().getResourceAsStream("picketbox/authentication.conf"));

//3.getAuthenticationManager

AuthenticationManagerauthManager=SecurityFactory.getAuthenticationManager(securityDomain);

//4.executeauthentication

authManager.isValid(userPrincipal,credString,subject);

//5.releaseresource

SecurityFactory.release();

TeiidEmbeddedexposes2methodsforsecurityauthentication:

EmbeddedConfiguration.setSecurityHelper()-associatedwithaorg.teiid.security.SecurityHelperintheenginejar.IfnoSecurityHelperisset,thennoauthenticationwillbeperformed.

EmbeddedConfiguration.setSecurityDomain()-associatedwithaapplication-policy’snameinSecurityConfigurationfile.IfnoSecurityDomainisset,thenadefaultteiid-securitywillbeused.

EmbeddedSecurityHelperisasampleimplementationofSecurityHelper,authentication.confisasampleSecurityConfigurationfile.

HowtodevelopaSecurityHelper

Add’teiid-engine-VERSION.jar’toclasspathisnecessary.Ifyouareusingthemaventopullartifacts,theenginedependencycanaddedasbelow,

<dependency>


<artifactId>teiid-engine</artifactId>

</dependency>


278

https://raw.githubusercontent.com/picketbox/picketbox/master/security-jboss-sx/jbosssx/src/main/resources/schema/security-config_5_0.xsd

https://raw.githubusercontent.com/teiid/teiid-embedded/master/src/main/java/org/teiid/embedded/security/EmbeddedSecurityHelper.java

https://raw.githubusercontent.com/teiid/teiid-embedded/master/src/main/resources/picketbox/authentication.conf

ThekeytodevelopaSecurityHelperisimplementtheauthenticate()method.PicketBox’s5keystepstoexecuteanauthenticationwhichdepictedinStepsofimplementaJAASauthenticationisshownintheexamplebelow:

@Override

publicSecurityContextauthenticate(StringsecurityDomain,StringbaseUserName,Credentialscredentials,String

applicationName)throwsLoginException{

SecurityFactory.prepare();

try{

PicketBoxConfigurationconfig=newPicketBoxConfiguration();

config.load(this.getClass().getClassLoader().getResourceAsStream("picketbox/authentication.conf"));

AuthenticationManagerauthManager=SecurityFactory.getAuthenticationManager(securityDomain);

if(authManager!=null){

finalPrincipaluserPrincipal=newSimplePrincipal(baseUserName);

finalSubjectsubject=newSubject();

finalStringcredString=credentials==null?null:newString(credentials.getCredentialsAsCharArray()

);

finalStringdomain=securityDomain;

booleanisValid=authManager.isValid(userPrincipal,credString,subject);

if(isValid){

SecurityContextsecurityContext=AccessController.doPrivileged(newPrivilegedAction<SecurityCo

ntext>(){

@Override

publicSecurityContextrun(){

SecurityContextsc;

try{

sc=SecurityContextFactory.createSecurityContext(userPrincipal,credString,subjec

t,domain);

}catch(Exceptione){

thrownewRuntimeException(e);

}

returnsc;

}});

returnsecurityContext;

}

}

}finally{

SecurityFactory.release();

}

thrownewLoginException("Theusername"+baseUserName+"and/orpasswordcouldnotbeauthenticatedby

securitydomain"+securityDomain+".");

}

YoucanjustreturnnullfromnegotiateGssLoginunlessyouwanttoallGSSauthenticationsfromJDBC/ODBC.

EmbeddedSecuritywithUsersRolesLoginModuleAddthefollowingcontenttoPicketBoxSecurityConfigurationfile:

<application-policyname="teiid-security">

<authentication>

<login-modulecode="org.jboss.security.auth.spi.UsersRolesLoginModule"flag="required"></login-modu

le>

</authentication>

</application-policy>

Toprepareusers/rolesbyaddusers.propertiesandroles.propertiestoclasspath.Asampleofusers.properties

testUser=password


279

Asampleofroles.properties

testUser=user

TostartEmbeddedServerwithUsersRolesLoginModulebasedsecurityauthenticationvia:

EmbeddedServerserver=

...


config.setSecurityDomain("teiid-security-file");

config.setSecurityHelper(newEmbeddedSecurityHelper());


EmbeddedSecuritywithLdapExtLoginModuleAddthefollowingcontenttothePicketBoxSecurityConfigurationFile:

<application-policyname="teiid-security-ldap">

<authentication>

<login-modulecode="org.jboss.security.auth.spi.LdapExtLoginModule"flag="required">

<module-optionname="java.naming.factory.initial">com.sun.jndi.ldap.LdapCtxFactory</module-option>

<module-optionname="java.naming.provider.url">ldap://HOST:389</module-option>

<module-optionname="java.naming.security.authentication">simple</module-option>

<module-optionname="bindDN">cn=Manager,dc=example,dc=com</module-option>

<module-optionname="bindCredential">redhat</module-option>

<module-optionname="baseCtxDN">ou=Customers,dc=example,dc=com</module-option>

<module-optionname="baseFilter">(uid={0})</module-option>

<module-optionname="rolesCtxDN">ou=Roles,dc=example,dc=com</module-option>

<module-optionname="roleFilter">(uniqueMember={1})</module-option>

<module-optionname="roleAttributeID">cn</module-option>

</login-module>

</authentication>

</application-policy>

Todefinesecurityusers/rolesrefertoyourLDAPVendorsdocumentation.Forexample,ifyouuseOpenLDAP,thenwiththeldiffilecustomer-security.ldif,execute

ldapadd-x-D"cn=Manager,dc=example,dc=com"-wredhat-fcustomer-security.ldif

tosetupusers/roles.

Tip module-optionssettinglikeurl,bindDN,bindCredential,baseCtxDN,rolesCtxDNshouldmatchtoyourLDAPserversetting.

TostartEmbeddedServerwithLdapExtLoginModulebasedsecurityauthenticationvia:

EmbeddedServerserver=

...


config.setSecurityDomain("teiid-security-ldap");

config.setSecurityHelper(newEmbeddedSecurityHelper());



280

https://raw.githubusercontent.com/teiid/teiid-embedded-examples/master/embedded-portfolio-security/src/main/resources/customer-security.ldif


281

ReferenceGuideTeiidoffersahighlyscalableandhighperformancesolutiontoinformationintegration.ByallowingintegratedandenricheddatatobeconsumedrelationallyorasXMLovermultipleprotocols,Teiidsimplifiesdataaccessfordevelopersandconsumingapplications.

Commercialdevelopmentsupport,productionsupport,andtrainingforTeiidisavailablethroughJBossInc.TeiidisaProfessionalOpenSourceprojectandacriticalcomponentoftheJBossEnterpriseDataServicesPlatform.

BeforeonecandelveintoTeiiditisveryimportanttolearnfewbasicconstructsofTeiid,likewhatisVDB?whatisModel?etc.Forthatpleasereadtheshortintroductionherehttp://teiid.jboss.org/basics/

ReferenceGuide

282


DataSourcesTeiidprovidesthemeans(i.e.,TranslatorsandJEEconnectors)toaccessavarietyoftypesofdatasources.Thetypesofdatasourcesthatarecurrentlyaccessibleare:

1. Databases

Oracle

PostgreSQL

MySQL/MariaDB

DB2

MicrosoftSQLServer

Sybase

SybaseIQ

MicrosoftAccess

Derby

H2

HSQL

Ingres

Informix

MetaMatrix

Teradata

Vertica

GenericANSISQL-fortypicalJDBC/ODBCsources

SimpleSQL-foranyJDBC/ODBCsource

2. WebServices

SOAP

REST

ArbitraryHTTP(S)

3. OData

4. BigData/NoSQL/SearchEngines/JCRandOtherSources

ActianVector

AmazonSimpleDB

ApacheAccumulo

ApacheCassandraDB

DataSources

283

ApacheSOLR

ApacheSpark

Greenplum

Hive/Hadoop/AmazonElasticMapReduce

Impala/Hadoop/AmazonElasticMapReduce

ModeShapeJCRRepository

MongoDB

MondrianOLAP

Netezzadatawarehouseappliance

Phoenix/HBase

PrestoDB

Redshift

5. EnterpriseSystems

OSISoftPI

SalesForce

SAPGateway

SAPHana

Teiid

6. ObjectSources

JDG/InfinispanLibraryMode

JDG/InfinispanHotRodMode

IntersystemsCacheObjectDatabase

JPAsources

7. LDAP

RedHatDirectoryServer

ActiveDirectory

8. Files

Delimited/Fixedwidth

XML

9. Spreadsheets

Excel

GoogleSpreadsheet

DataSources

284

Thisrepresentsdatasourcesthathavebeenvalidatedtoworkusingtheavailabletranslatorsandconnectors.However,thisdoesnotprecludeanewdatasourcefromworking.Itcanbeaseasyasextendinganexistingtranslator,tocreatinganewtranslatorusingtheTranslatorDevelopmentextensions.

TakealookatthelistofTranslatorsthatareusedasthebridgebetweenTeiidandtheexternalsystem.

DataSources

285

SQLSupportTeiidprovidesnearlyallofthefunctionalityofSQL-92DML.SQL-99andlaterfeaturesareconstantlybeingaddedbaseduponcommunityneed.ThefollowingdoesnotattempttocoverSQLexhaustively,butratherhighlightsSQL’susagewithinTeiid.SeetheBNFforSQLGrammarfortheexactformofSQLacceptedbyTeiid.

SQLSupport

286

IdentifiersSQLcommandscontainreferencestotablesandcolumns.Thesereferencesareintheformofidentifiers,whichuniquelyidentifythetablesandcolumnsinthecontextofthecommand.Allqueriesareprocessedinthecontextofavirtualdatabase,orVDB.Becauseinformationcanbefederatedacrossmultiplesources,tablesandcolumnsmustbescopedinsomemannertoavoidconflicts.Thisscopingisprovidedbyschemas,whichcontaintheinformationforeachdatasourceorsetofviews.

Fully-qualifiedtableandcolumnnamesareofthefollowingform,wheretheseparate`parts'oftheidentifieraredelimitedbyperiods.

TABLE:<schema_name>.<table_spec>

COLUMN:<schema_name>.<table_spec>.<column_name>

SyntaxRules:

Identifierscanconsistofalphanumericcharacters,ortheunderscore(_)character,andmustbeginwithanalphabeticcharacter.AnyUnicodecharactermaybeusedinanidentifier.

Identifiersindoublequotescanhaveanycontents.Thedoublequotecharactercanit’sbeescapedwithanadditionaldoublequote.e.g."some","id"

Becausedifferentdatasourcesorganizetablesindifferentways,someprependingcatalogorschemaoruserinformation,Teiidallowstablespecificationtobeadot-delimitedconstruct.

NoteWhenatablespecificationcontainsadotresolvingwillallowforthematchofapartialnameagainstanynumberoftheendsegmentsinthename.e.g.atablewiththefully-qualifiednamevdbname."sourcescema.sourcetable"wouldmatchthepartialnamesourcetable.

Columns,schemas,andaliasesidentifierscannotcontainadot.

Identifiers,evenwhenquoted,arenotcase-sensitiveinTeiid.

Someexamplesofvalidfully-qualifiedtableidentifiersare:

MySchema.Portfolios

"MySchema.Portfolios"

MySchema.MyCatalog.dbo.Authors

Someexamplesofvalidfully-qualifiedcolumnidentifiersare:

MySchema.Portfolios.portfolioID

"MySchema.Portfolios"."portfolioID"

MySchema.MyCatalog.dbo.Authors.lastName

Fully-qualifiedidentifierscanalwaysbeusedinSQLcommands.Partially-orunqualifiedformscanalsobeused,aslongastheresultingnamesareunambiguousinthecontextofthecommand.Differentformsofqualificationcanbemixedinthesamequery.

ReservedWordsTeiid’sreservedwordsincludethestandardSQL2003Foundation,SQL/MED,andSQL/XMLreservedwords,aswellasTeiidspecificwordssuchasBIGINTEGER,BIGDECIMAL,orMAKEDEP.SeetheBNFforSQLGrammarReservedKeywordsandReservedKeywordsForFutureUsesectionsforallreservedwords.

Identifiers

287

Identifiers

288

ExpressionsIdentifiers,literals,andfunctionscanbecombinedintoexpressions.Expressionscanbeusedalmostanywhereinaquery–SELECT,FROM(ifspecifyingjoincriteria),WHERE,GROUPBY,HAVING,orORDERBY.

Teiidsupportsthefollowingtypesofexpressions:

ColumnIdentifiers

Literals

ScalarFunctions

AggregateFunctions

WindowFunctions

CaseandSearchedCase

ScalarSubqueries

ParameterReferences

Criteria

Arrays

ColumnIdentifiers

ColumnidentifiersareusedtospecifytheoutputcolumnsinSELECTstatements,thecolumnsandtheirvaluesforINSERTandUPDATEstatements,andcriteriausedinWHEREandFROMclauses.TheyarealsousedinGROUPBY,HAVING,andORDERBYclauses.ThesyntaxforcolumnidentifierswasdefinedintheIdentifierssectionabove.

LiteralsLiteralvaluesrepresentfixedvalues.Thesecananyofthe'standard'datatypes.

SyntaxRules:

Integervalueswillbeassignedanintegraldatatypebigenoughtoholdthevalue(integer,long,orbiginteger).

Floatingpointvalueswillalwaysbeparsedasadouble.

Thekeyword'null'isusedtorepresentanabsentorunknownvalueandisinherentlyuntyped.Inmanycases,anullliteralvaluewillbeassignedanimpliedtypebasedoncontext.Forexample,inthefunction'5+null',thenullvaluewillbeassignedthetype'integer'tomatchthetypeofthevalue'5'.AnullliteralusedintheSELECTclauseofaquerywithnoimpliedcontextwillbeassignedtotype'string'.

Someexamplesofsimpleliteralvaluesare:

'abc'

escapedsingletick

'isn"ttrue'

Expressions

289

5

scientificnotation

-37.75e01

exactnumerictypeBigDecimal

100.0

true

false

unicodecharacter

'\u0027'

binary

X'0F0A'

Date/TimeLiteralscanuseeitherJDBCEscapedLiteralSyntax:

DateLiteral

{d'...'}

TimeLiteral

{t'...'}

TimestampLiteral

{ts'...'}

OrtheANSIkeywordsyntax:

DateLiteral

DATE'...'

TimeLiteral

TIME'...'

TimestampLiteral

TIMESTAMP'...'

Eitherwaythestringliteralvalueportionoftheexpressionisexpectedtofollowthedefinedformat-"yyyy-MM-dd"fordate,"hh:mm:ss"fortime,and"yyyy-MM-dd[hh:mm:ss[.fff…]]"fortimestamp.

Expressions

290

AggregateFunctions

AggregatefunctionstakesetsofvaluesfromagroupproducedbyanexplicitorimplicitGROUPBYandreturnasinglescalarvaluecomputedfromthegroup.

Teiidsupportsthefollowingaggregatefunctions:

COUNT(*)–countthenumberofvalues(includingnullsandduplicates)inagroup.Returnsaninteger-anexceptionwillbethrownifalargercountiscomputed.

COUNT(x)–countthenumberofvalues(excludingnulls)inagroup.Returnsaninteger-anexceptionwillbethrownifalargercountiscomputed.

SUM(x)–sumofthevalues(excludingnulls)inagroup

AVG(x)–averageofthevalues(excludingnulls)inagroup

MIN(x)–minimumvalueinagroup(excludingnull)

MAX(x)–maximumvalueinagroup(excludingnull)

ANY(x)/SOME(x)–returnsTRUEifanyvalueinthegroupisTRUE(excludingnull)

EVERY(x)–returnsTRUEifeveryvalueinthegroupisTRUE(excludingnull)

VAR_POP(x)–biasedvariance(excludingnull)logicallyequals(sum(x^2)-sum(x)^2/count(x))/count(x);returnsadouble;nullifcount=0

VAR_SAMP(x)–samplevariance(excludingnull)logicallyequals(sum(x^2)-sum(x)^2/count(x))/(count(x)-1);returnsadouble;nullifcount<2

STDDEV_POP(x)–standarddeviation(excludingnull)logicallyequalsSQRT(VAR_POP(x))

STDDEV_SAMP(x)–samplestandarddeviation(excludingnull)logicallyequalsSQRT(VAR_SAMP(x))

TEXTAGG(expression[asname],…[DELIMITERchar][QUOTEchar][HEADER][ENCODINGid][ORDERBY…])–CSVtextaggregationofallexpressionsineachrowofagroup.WhenDELIMITERisnotspecified,bydefaultcomma(,)isusedasdelimiter.Doublequotes(")isthedefaultquotecharacter.UseQUOTEtospecifyadifferentvalue.Allnon-nullvalueswillbequoted.IfHEADERisspecified,theresultcontainstheheaderrowasthefirstline-theheaderlinewillbepresenteveniftherearenorowsinagroup.Thisaggregationreturnsablob.

TEXTAGG(col1,col2asnameDELIMITER'|'HEADERORDERBYcol1)

XMLAGG(xml_expr[ORDERBY…])–xmlconcatenationofallxmlexpressionsinagroup(excludingnull).TheORDERBYclausecannotreferencealiasnamesorusepositionalordering.

JSONARRAY_AGG(x[ORDERBY…])–createsaJSONarrayresultasaClobincludingnullvalue.TheORDERBYclausecannotreferencealiasnamesorusepositionalordering.SeealsotheJSONArrayfunction.

integervalueexample

jsonArray_Agg(col1orderbycol1nullsfirst)

couldreturn

[null,null,1,2,3]

Expressions

291

STRING_AGG(x,delim)–createsalobresultsfromtheconcatenationofxusingthedelimiterdelim.Ifeitherargumentisnull,novalueisconcatenated.Bothargumentsareexpectedtobecharacter(string/clob)orbinary(varbinary,blob)andtheresultwillbecloborblobrespectively.DISTINCTandORDERBYareallowedinSTRING_AGG.

stringaggexample

string_agg(col1,','ORDERBYcol1ASC)

couldreturn

'a,b,c'

ARRAY_AGG(x[ORDERBY…])–createsanarraywithabasetypematchingtheexpressionx.TheORDERBYclausecannotreferencealiasnamesorusepositionalordering.

agg([DISTINCT|ALL]arg…[ORDERBY…])–auserdefinedaggregatefunction

SyntaxRules:

Someaggregatefunctionsmaycontainakeyword'DISTINCT'beforetheexpression,indicatingthatduplicateexpressionvaluesshouldbeignored.DISTINCTisnotallowedinCOUNT(*)andisnotmeaningfulinMINorMAX(resultwouldbeunchanged),soitcanbeusedinCOUNT,SUM,andAVG.

AggregatefunctionscannotbeusedinFROM,GROUPBY,orWHEREclauseswithoutaninterveningqueryexpression.

Aggregatefunctionscannotbenestedwithinanotheraggregatefunctionwithoutaninterveningqueryexpression.

Aggregatefunctionsmaybenestedinsideotherfunctions.

AnyaggregatefunctionmaytakeanoptionalFILTERclauseoftheform

FILTER(WHEREcondition)

Theconditionmaybeanybooleanvalueexpressionthatdoesnotcontainasubqueryoracorrelatedvariable.Thefilterwilllogicallybeevaluatedforeachrowpriortothegroupingoperation.Iffalsetheaggregatefunctionwillnotaccumulateavalueforthegivenrow.

Formoreinformationonaggregates,seethesectionsonGROUPBYorHAVING.

WindowFunctionsTeiidsupportsANSISQL2003windowfunctions.Awindowfunctionallowsanaggregatefunctiontobeappliedtoasubsetoftheresultset,withouttheneedforaGROUPBYclause.Awindowfunctionissimilartoanaggregatefunction,butrequirestheuseofanOVERclauseorwindowspecification.

Usage:

aggregate|rankingOVER([PARTITIONBY...]][ORDERBY...])

aggregatecanbeanyAggregateFunctions.RankingcanbeoneofROW_NUMBER(),RANK(),DENSE_RANK().

SyntaxRules:

WindowfunctionscanonlyappearintheSELECTandORDERBYclausesofaqueryexpression.

Windowfunctionscannotbenestedinoneanother.

Expressions

292

Partitioningandorderbyexpressionscannotcontainsubqueriesorouterreferences.

Theranking(ROW_NUMBER,RANK,DENSE_RANK)functionsrequiretheuseofthewindowspecificationORDERBYclause.

AnXMLAGGorJSONARRAY_AGGORDERBYclausecannotbeusedwhenwindowed.

ThewindowspecificationORDERBYclausecannotreferencealiasnamesorusepositionalordering.

WindowedaggregatesmaynotuseDISTINCTifthewindowspecificationisordered.

AnalyticalFunctionDefinitionsROW_NUMBER()–functionalthesameasCOUNT(*)withthesamewindowspecification.Assignsanumbertoeachrowinapartitionstartingat1.

RANK()–Assignsanumbertoeachuniqueorderingvaluewithineachpartitionstartingat1,suchthatthenextrankisequaltothecountofpriorrows.

DENSE_RANK()–Assignsanumbertoeachuniqueorderingvaluewithineachpartitionstartingat1,suchthatthenextrankissequential.

Allvaluesareintegers-anexceptionwillbethrownifalargervalueisneeded.

ProcessingWindowfunctionsarelogicallyprocessedjustbeforecreatingtheoutputfromtheSELECTclause.WindowfunctionscanusenestedaggregatesifaGROUPBYclauseispresent.Theisnoguaranteedaffectontheoutputorderingfromthepresenceofwindowfunctions.TheSELECTstatementmusthaveanORDERBYclausetohaveapredictableordering.

Teiidwillprocessallwindowfunctionswiththesamewindowspecificationtogether.IngeneralafullpassovertherowvaluescomingintotheSELECTclausewillberequiredforeachuniquewindowspecification.ForeachwindowspecificationthevalueswillbegroupedaccordingtothePARTITIONBYclause.IfnoPARTITIONBYclauseisspecified,thentheentireinputistreatedasasinglepartition.Theoutputvalueisdeterminedbaseduponthecurrentrowvalue,it’speers(thatisrowsthatarethesamewithrespecttotheirordering),andallpriorrowvaluesbaseduponorderinginthepartition.TheROW_NUMBERfunctionwillassignauniquevaluetoeveryrowregardlessofthenumberofpeers.

ExampleWindowedResults

SELECTname,salary,max(salary)over(partitionbyname)asmax_sal,

rank()over(orderbysalary)asrank,dense_rank()over(orderbysalary)asdense_rank,

row_number()over(orderbysalary)asrow_numFROMemployees

name salary max_sal rank dense_rank row_num

John 100000 100000 2 2 2

Henry 50000 50000 5 4 5

John 60000 100000 3 3 3

Suzie 60000 150000 3 3 4

Suzie 150000 150000 1 1 1

Expressions

293

CaseandSearchedCase

TeiidsupportstwoformsoftheCASEexpressionwhichallowsconditionallogicinascalarexpression.

Supportedforms:

CASE<expr>(WHEN<expr>THEN<expr>)+[ELSEexpr]END

CASE(WHEN<criteria>THEN<expr>)+[ELSEexpr]END

Eachformallowsforanoutputbasedonconditionallogic.ThefirstformstartswithaninitialexpressionandevaluatesWHENexpressionsuntilthevaluesmatch,andoutputstheTHENexpression.IfnoWHENismatched,theELSEexpressionisoutput.IfnoWHENismatchedandnoELSEisspecified,anullliteralvalueisoutput.Thesecondform(thesearchedcaseexpression)searchestheWHENclauses,whichspecifyanarbitrarycriteriatoevaluate.Ifanycriteriaevaluatestotrue,theTHENexpressionisevaluatedandoutput.IfnoWHENistrue,theELSEisevaluatedorNULLisoutputifnoneexists.

ScalarSubqueries

SubqueriescanbeusedtoproduceasinglescalarvalueintheSELECT,WHERE,orHAVINGclausesonly.AscalarsubquerymusthaveasinglecolumnintheSELECTclauseandshouldreturneither0or1row.Ifnorowsarereturned,nullwillbereturnedasthescalarsubqueryvalue.Forothertypesofsubqueries,seetheSubqueriessection.

ParameterReferences

Parametersarespecifiedusinga'?'symbol.ParametersmayonlybeusedwithPreparedStatementorCallableStatementsinJDBC.Eachparameterislinkedtoavaluespecifiedby1-basedindexintheJDBCAPI.

Arrays

Arrayvaluesmaybeconstructedusingparenthesisaroundanexpressionlistwithanoptionaltrailingcomma.

emptyarrays

()(,)

singleelementarray

(expr,)

Note Atrailingcommaisrequiredfortheparsertorecognizeasingleelementexpressionasanarray,ratherthanasimplenestedexpression.

generalarraysyntax

(expr,expr...[,])

Ifalloftheelementsinthearrayhavethesametype,thearraywillhaveamatchingbasetype.Iftheelementtypesdifferthearraybasetypewillbeobject.

Anarrayelementreferencetakestheformof:

array_expr[index_expr]

Expressions

294

index_exprmustresolvetoanintegervalue.Thissyntaxiseffectivelythesameasthearray_getsystemfunctionandexpects1-basedindexing.

OperatorPrecedence

Teiidparsesandevaluatesoperatorswithhigherprecedencebeforethosewithlowerprecedence.Operatorwithequalprecedenceareleftassociative.Operatorprecedencelistedfromhightolow:

Operator Description

[] arrayelementreference

+,- positive/negativevalueexpression

*,/ multiplication/division

+,- addition/subtraction

||\ concat

criteria seeCriteria

Expressions

295

CriteriaCriteriamaybe:

Predicatesthatevaluatetotrueorfalse

Logicalcriteriathatcombinescriteria(AND,OR,NOT)

Avalueexpressionwithtypeboolean

Usage:

criteriaAND|ORcriteria

NOTcriteria

(criteria)

expression(=|<>|!=|<|>|<=|>=)(expression|((ANY|ALL|SOME)subquery|(array_expression)))

expression[NOT]ISNULL

expression[NOT]IN(expression[,expression]*)|subquery

expression[NOT]LIKEpattern[ESCAPEchar]

Matchesthestringexpressionagainstthegivenstringpattern.Thepatternmaycontain%tomatchanynumberofcharactersand_tomatchanysinglecharacter.Theescapecharactercanbeusedtoescapethematchcharacters%and_.

expression[NOT]SIMILARTOpattern[ESCAPEchar]

SIMILARTOisacrossbetweenLIKEandstandardregularexpressionsyntax.%and_arestillused,ratherthan.*and.respectively.

Note

TeiiddoesnotexhaustivelyvalidateSIMILARTOpatternvalues.Ratherthepatternisconvertedtoanequivalentregularexpression.CareshouldbetakennottorelyongeneralregularexpressionfeatureswhenusingSIMILARTO.Ifadditionalfeaturesareneeded,thenLIKE_REGEXshouldbeused.Usageofanon-literalpatternisdiscouragedaspushdownsupportislimited.

expression[NOT]LIKE_REGEXpattern

LIKE_REGEXallowsforstandardregularexpressionsyntaxtobeusedformatching.ThisdiffersfromSIMILARTOandLIKEinthattheescapecharacterisnolongerused(\isalreadythestandardescapemechanisminregularexpressionsand%and_havenospecialmeaning.TheruntimeengineusestheJREimplementationofregularexpressions-seethejava.util.regex.Patternclassfordetails.

Note

TeiiddoesnotexhaustivelyvalidateLIKE_REGEXpatternvalues.ItispossibletouseJREonlyregularexpressionfeaturesthatarenotspecifiedbytheSQLspecification.Additionalnotallsourcessupportthesameregularexpressionflavororextensions.Careshouldbetakeninpushdownsituationstoensurethatthepattern

Criteria

296

http://download.oracle.com/javase/6/docs/api/java/util/regex/Pattern.html

usedwillhavesamemeaninginTeiidandacrossallapplicablesources.

EXISTS(subquery)

expression[NOT]BETWEENminExpressionANDmaxExpression

TeiidconvertsBETWEENintotheequivalentformexpression>=minExpressionANDexpression⇐maxExpression

expression

Whereexpressionhastypeboolean.

SyntaxRules:

Theprecedenceorderingfromlowesttohighestiscomparison,NOT,AND,OR

Criterianestedbyparenthesiswillbelogicallyevaluatedpriortoevaluatingtheparentcriteria.

Someexamplesofvalidcriteriaare:

(balance>2500.0)

100*(50-x)/(25-y)>z

concat(areaCode,concat(’-`,phone))LIKE’314%1'

ComparingnullValues

Tip Nullvaluesrepresentanunknownvalue.Comparisonwithanullvaluewillevaluateto`unknown',whichcanneverbetrueevenif`not'isused.

CriteriaPrecedence

Teiidparsesandevaluatesconditionswithhigherprecedencebeforethosewithlowerprecedence.Conditionswithequalprecedenceareleftassociative.Conditionprecedencelistedfromhightolow:

Condition Description

sqloperators SeeExpressions

EXISTS,LIKE,SIMILARTO,LIKE_REGEX,BETWEEN,IN,ISNULL,<,⇐,>,>=,=,<> comparison

NOT negation

AND conjunction

OR disjunction

Notehoweverthattopreventlookaheadstheparserdoesnotacceptallpossiblecriteriasequences.Forexample"a=bisnull"isnotaccepted,sincebytheleftassociativeparsingwefirstrecognize"a=",thenlookforacommonvalueexpression."bisnull"isnotavalidcommonvalueexpression.Thusnestingmustbeused,forexample"(a=b)isnull".SeeBNFforSQLGrammarforallparsingrules.

Criteria

297

Criteria

298

ScalarFunctionsTeiidprovidesanextensivesetofbuilt-inscalarfunctions.SeealsoSQLSupportandDatatypes.Inaddition,TeiidprovidesthecapabilityforuserdefinedfunctionsorUDFs.SeetheDevelopersGuideforaddingUDFs.OnceaddedUDFsmaybecalledjustlikeanyotherfunction.

ScalarFunctions

299

NumericFunctionsNumericfunctionsreturnnumericvalues(integer,long,float,double,biginteger,bigdecimal).Theygenerallytakenumericvaluesasinputs,thoughsometakestrings.

Function Definition DatatypeConstraint

+-*/ Standardnumericoperatorsxin\{integer,long,float,double,biginteger,bigdecimal},returntypeissameasx[a]

ABS(x) Absolutevalueofx Seestandardnumericoperatorsabove

ACOS(x) Arccosineofx xin\{double,bigdecimal},returntypeisdouble

ASIN(x) Arcsineofx xin\{double,bigdecimal},returntypeisdouble

ATAN(x) Arctangentofx xin\{double,bigdecimal},returntypeisdouble

ATAN2(x,y) Arctangentofxandy x,yin\{double,bigdecimal},returntypeisdouble

CEILING(x) Ceilingofx xin\{double,float},returntypeisdouble

COS(x) Cosineofx xin\{double,bigdecimal},returntypeisdouble

COT(x) Cotangentofx xin\{double,bigdecimal},returntypeisdouble

DEGREES(x) Convertxdegreestoradians xin\{double,bigdecimal},returntypeisdouble

EXP(x) e^x xin\{double,float},returntypeisdouble

FLOOR(x) Floorofx xin\{double,float},returntypeisdouble

FORMATBIGDECIMAL(x,y) Formatsxusingformaty xisbigdecimal,yisstring,returnsstring

FORMATBIGINTEGER(x,y) Formatsxusingformaty xisbiginteger,yisstring,returnsstring

FORMATDOUBLE(x,y) Formatsxusingformaty xisdouble,yisstring,returnsstring

FORMATFLOAT(x,y) Formatsxusingformaty xisfloat,yisstring,returnsstring

ScalarFunctions

300

FORMATINTEGER(x,y) Formatsxusingformaty xisinteger,yisstring,returnsstring

FORMATLONG(x,y) Formatsxusingformaty xislong,yisstring,returnsstring

LOG(x) Naturallogofx(basee) xin\{double,float},returntypeisdouble

LOG10(x) Logofx(base10) xin\{double,float},returntypeisdouble

MOD(x,y) Modulus(remainderofx/y)xin\{integer,long,float,double,biginteger,bigdecimal},returntypeissameasx

PARSEBIGDECIMAL(x,y) Parsesxusingformaty x,yarestrings,returnsbigdecimal

PARSEBIGINTEGER(x,y) Parsesxusingformaty x,yarestrings,returnsbiginteger

PARSEDOUBLE(x,y) Parsesxusingformaty x,yarestrings,returnsdouble

PARSEFLOAT(x,y) Parsesxusingformaty x,yarestrings,returnsfloat

PARSEINTEGER(x,y) Parsesxusingformaty x,yarestrings,returnsinteger

PARSELONG(x,y) Parsesxusingformaty x,yarestrings,returnslong

PI() ValueofPi returnisdouble

POWER(x,y) xtotheypowerxin\{double,bigdecimal,biginteger},returnisthesametypeasx

RADIANS(x) Convertxradianstodegrees xin\{double,bigdecimal},returntypeisdouble

RAND()

Returnsarandomnumber,usinggeneratorestablishedsofarinthequeryorinitializingwithsystemclockifnecessary.

Returnsdouble.

RAND(x) Returnsarandomnumber,usingnewgeneratorseededwithx. xisinteger,returnsdouble.

ROUND(x,y)Roundxtoyplaces;negativevaluesofyindicateplacestotheleftofthedecimalpoint

xin\{integer,float,double,bigdecimal}yisinteger,returnissametypeasx

SIGN(x) 1ifx>0,0ifx=0,-1ifx<0xin\{integer,long,float,double,biginteger,bigdecimal},returntypeisinteger

SIN(x) Sinevalueofx xin\{double,bigdecimal},returntypeisdouble

SQRT(x) Squarerootofx xin\{long,double,bigdecimal},returntypeisdouble

ScalarFunctions

301

TAN(x) Tangentofx xin\{double,bigdecimal},returntypeisdouble

BITAND(x,y) BitwiseANDofxandy x,yin{integer},returntypeisinteger

BITOR(x,y) BitwiseORofxandy x,yin{integer},returntypeisinteger

BITXOR(x,y) BitwiseXORofxandy x,yin{integer},returntypeisinteger

BITNOT(x) BitwiseNOTofx xin{integer},returntypeisinteger

[a]Theprecisionandscaleofnon-bigdecimalarithmeticfunctionfunctionsresultsmatchesthatofJava.TheresultsofbigdecimaloperationsmatchJava,exceptfordivision,whichusesapreferredscaleofmax(16,dividend.scale+divisor.precision+1),whichthenhastrailingzerosremovedbysettingthescaletomax(dividend.scale,normalizedscale)

ParsingNumericDatatypesfromStringsTeiidoffersasetoffunctionsyoucanusetoparsenumbersfromstrings.Foreachstring,youneedtoprovidetheformattingofthestring.Thesefunctionsusetheconventionestablishedbythejava.text.DecimalFormatclasstodefinetheformatsyoucanusewiththesefunctions.YoucanlearnmoreabouthowthisclassdefinesnumericstringformatsbyvisitingtheSunJavaWebsiteatthefollowingURLforSunJava.

Forexample,youcouldusethesefunctioncalls,withtheformattingstringthatadherestothejava.text.DecimalFormatconvention,toparsestringsandreturnthedatatypeyouneed:

InputString FunctionCalltoFormatString OutputValue OutputDatatype

'$25.30' parseDouble(cost,'$,0.00;($,0.00)') 25.3 double

'25%' parseFloat(percent,',#0%') 25 float

'2,534.1' parseFloat(total,',0.;-,0.') 2534.1 float

'1.234E3' parseLong(amt,'0.###E0') 1234 long

'1,234,567' parseInteger(total,',0;-,0') 1234567 integer

FormattingNumericDatatypesasStringsTeiidoffersasetoffunctionsyoucanusetoconvertnumericdatatypesintostrings.Foreachstring,youneedtoprovidetheformatting.Thesefunctionsusetheconventionestablishedwithinthejava.text.DecimalFormatclasstodefinetheformatsyoucanusewiththesefunctions.YoucanlearnmoreabouthowthisclassdefinesnumericstringformatsbyvisitingtheSunJavaWebsiteatthefollowingURLforSunJava.

Forexample,youcouldusethesefunctioncalls,withtheformattingstringthatadherestothejava.text.DecimalFormatconvention,toformatthenumericdatatypesintostrings:

ScalarFunctions

302

https://docs.oracle.com/javase/7/docs/api/java/text/DecimalFormat.html

https://docs.oracle.com/javase/7/docs/api/java/text/DecimalFormat.html

InputValue InputDatatype FunctionCalltoFormatString

OutputString

25.3 double formatDouble(cost,'$,0.00;($,0.00)') '$25.30'

25 float formatFloat(percent,',#0%') '25%'

2534.1 float formatFloat(total,',0.;-,0.') '2,534.1'

1234 long formatLong(amt,'0.###E0') '1.234E3'

1234567 integer formatInteger(total,',0;-,0') '1,234,567'

ScalarFunctions

303

StringFunctionsStringfunctionsgenerallytakestringsasinputsandreturnstringsasoutputs.

Unlessspecified,alloftheargumentsandreturntypesinthefollowingtablearestringsandallindexesare1-based.The0indexisconsideredtobebeforethestartofthestring.


x||y Concatenationoperator x,yin{string},returntypeisstring

ASCII(x)ProvideASCIIvalueoftheleftmostcharacterinx.Theemptystringwillasinputwillreturnnull.

returntypeisinteger

CHR(x)CHAR(x) ProvidethecharacterforASCIIvaluex[a] xin{integer}

CONCAT(x,y)ConcatenatesxandywithANSIsemantics.Ifxand/oryisnull,returnsnull.

x,yin{string}

CONCAT2(x,y)

Concatenatesxandywithnon-ANSInullsemantics.Ifxandyisnull,returnsnull.Ifonlyxoryisnull,returnstheothervalue.

x,yin{string}

ENDSWITH(x,y) Checksifyendswithx.Ifxoryisnull,returnsnull. x,yin{string},returnsboolean

INITCAP(x)Makefirstletterofeachwordinstringxcapitalandallotherslowercase

xin{string}

INSERT(str1,start,length,str2) Insertstring2intostring1 str1in{string},startin{integer},lengthin{integer},str2in{string}

LCASE(x) Lowercaseofx xin{string}

LEFT(x,y) Getleftycharactersofx xin{string},yin{integer},returnstring

LENGTH(x) Lengthofx returntypeisinteger

LOCATE(x,y) Findpositionofxinystartingatbeginningofy

xin{string},yin{string},returninteger

LOCATE(x,y,z) Findpositionofxinystartingatz xin{string},yin{string},zin{integer},returninteger

LPAD(x,y) Padinputstringxwithspacesonthelefttothelengthofy

xin{string},yin{integer},returnstring

LPAD(x,y,z) Padinputstringxonthelefttothelengthofyusingcharacterz

xin{string},yin{string},zin{character},returnstring

ScalarFunctions

304

LTRIM(x) Lefttrimxofblankchars xin{string},returnstring

QUERYSTRING(path[,expr[ASname]…])

Returnsaproperlyencodedquerystringappendedtothegivenpath.Nullvaluedexpressionsareomitted,andanullpathistreatedas".Namesareoptionalforcolumnreferenceexpressions.e.g.QUERYSTRING('path','value'as

"&x",'&'asy,nullasz)

returns'path?

%26x=value&y=%20%26%20'

path,exprin{string}.nameisanidentifier

REPEAT(str1,instances) Repeatstring1aspecifiednumberoftimes

str1in{string},instancesin{integer}returnstring

RIGHT(x,y) Getrightycharactersofx xin{string},yin{integer},returnstring

RPAD(inputstringx,padlengthy) Padinputstringxwithspacesontherighttothelengthofy

xin{string},yin{integer},returnstring

RPAD(x,y,z) Padinputstringxontherighttothelengthofyusingcharacterz

xin{string},yin{string},zin{character},returnstring

RTRIM(x) Righttrimxofblankchars xisstring,returnstring

SPACE(x) Repeatthespacecharacterxnumberoftimes xisinteger,returnstring

SUBSTRING(x,y)SUBSTRING(xFROMy)

[b]Getsubstringfromx,frompositionytotheendofx yin{integer}

SUBSTRING(x,y,z)SUBSTRING(xFROMyFORz)

[b]Getsubstringfromxfrompositionywithlengthz y,zin{integer}

TRANSLATE(x,y,z)Translatestringxbyreplacingeachcharacterinywiththecharacterinzatthesameposition

xin{string}

TRIM([[LEADING|TRAILING|BOTH][x]FROM]y)

Trimtheleading,trailing,orbothendsofastringyofcharacterx.IfLEADING/TRAILING/BOTHisnotspecified,BOTHisused.Ifnotrimcharacterxisspecficedthentheblankspace’isused.

xin{character},yin{string}

UCASE(x) Uppercaseofx xin{string}

UNESCAPE(x)

Unescapedversionofx.Possibleescapesequencesare\b-backspace,\t-tab,\n-linefeed,\f-formfeed,\r-carriagereturn.\uXXXX,whereXisahexvalue,canbeusedtospecifyanyunicodecharacter.\XXX,whereXisanoctaldigit,canbeusedtospecifyanoctalbytevalue.Ifanyothercharacterappearsafteranescapecharacter,that

xin{string}

ScalarFunctions

305

characterwillappearintheoutputandtheescapecharacterwillbeignored.

[a]Non-ASCIIrangecharactersorintegersusedinthesefunctionsmayproducedifferentresultsorexceptionsdependingonwherethefunctionisevaluated(Teiidvs.source).Teiid’susesJavadefaultinttocharandchartointconversions,whichoperatesoverUTF16values.

[b]Thesubstringfunctiondependinguponthesourcedoesnothaveconsistentbehaviorwithrespecttonegativefrom/lengthargumentsnoroutofboundsfrom/lengtharguments.ThedefaultTeiidbehavioris:

returnanullvaluewhenthefromvalueisoutofboundsorthelengthislessthan0

azerofromindexiseffectivethesameas1.

anegativefromindexisfirstcountedfromtheendofthestring.

Somesourceshowevercanreturnanemptystringinsteadofnullandsomesourcesdonotsupportnegativeindexing.Ifanyoftheseinconsistenciesimpactyou,thenpleaseloganissue.

EncodingFunctions

TO_CHARS

Returnaclobfromtheblobwiththegivenencoding.

TO_CHARS(x,encoding[,wellformed])

BASE64,HEX,andthebuilt-inJavaCharsetnamesarevalidvaluesfortheencoding[b].xisablob,encodingisastring,wellformedisaboolean,andreturnsaclob.Thetwoargumentformdefaultstowellformed=true.Ifwellformedisfalse,theconversionfunctionwillimmediatelyvalidatetheresultsuchthatanunmappablecharacterormalformedinputwillraiseanexception.

TO_BYTES

Returnablobfromtheclobwiththegivenencoding.

TO_BYTES(x,encoding[,wellformed])

BASE64,HEX,andthebuiltinJavaCharsetnamesarevalidvaluesfortheencoding[b].xinaclob,encodingisastring,wellformedisabooleanandreturnsablob.Thetwoargumentformdefaultstowellformed=true.Ifwellformedisfalse,theconversionfunctionwillimmediatelyvalidatetheresultsuchthatanunmappablecharacterormalformedinputwillraiseanexception.Ifwellformedistrue,thenunmappablecharacterswillbereplacedbythedefaultreplacementcharacterforthecharacterset.Binaryformats,suchasBASE64andHEX,willbecheckedforcorrectnessregardlessofthewellformedparameter.

[b]SeetheCharsetJavaDocformoreonsupportedCharsetnames.

ReplacementFunctions

REPLACE

Replacealloccurrencesofagivenstringwithanother.

ScalarFunctions

306

http://java.sun.com/j2se/1.5.0/docs/api/java/nio/charset/Charset.html

REPLACE(x,y,z)

Replacealloccurrencesofywithzinx.x,y,zarestringsandthereturnvalueisastring.

REGEXP_REPLACE

Replaceoneoralloccurrencesofagivenpatternwithanotherstring.

REGEXP_REPLACE(str,pattern,sub[,flags])

Replaceoneormoreoccurrencesofpatternwithsubinstr.Allargumentsarestringsandthereturnvalueisastring.

ThepatternparameterisexpectedtobeavalidJavaRegularExpression

Theflagsargumentcanbeanyconcatenationofanyofthevalidflagswiththefollowingmeanings:

flag name meaning

g global Replacealloccurrences,notjustthefirst

m multiline Matchovermultiplelines

i caseinsensitive Matchwithoutcasesensitivity

Usage:

Thefollowingwillreturn"xxbyeWxx"usingtheglobalandcaseinsensitiveoptions.

Exampleregexp_replace

regexp_replace('GoodbyeWorld','[g-o].','x','gi')

ScalarFunctions

307

http://docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html

Date_TimeFunctionsDateandtimefunctionsreturnoroperateondates,times,ortimestamps.

ParseandformatDate/Timefunctionsusetheconventionestablishedwithinthejava.text.SimpleDateFormatclasstodefinetheformatsyoucanusewiththesefunctions.YoucanlearnmoreabouthowthisclassdefinesformatsbyvisitingtheJavadocsforSimpleDateFormat.


CURDATE() Returncurrentdate returnsdate

CURTIME() Returncurrenttime returnstime

NOW() Returncurrenttimestamp(dateandtime) returnstimestamp

DAYNAME(x) Returnnameofdayinthedefaultlocale

xin\{date,timestamp},returnsstring

DAYOFMONTH(x) Returndayofmonthxin\{date,timestamp},returnsinteger

DAYOFWEEK(x) Returndayofweek(Sunday=1,Saturday=7)

xin\{date,timestamp},returnsinteger

DAYOFYEAR(x) Returndaynumberinyearxin\{date,timestamp},returnsinteger

EXTRACT(YEAR|MONTH|DAY|HOUR|MINUTE|SECONDFROMx)

Returnthegivenfieldvaluefromthedatevaluex.ProducesthesameresultastheassoceatedYEAR,MONTH,DAYOFMONTH,HOUR,MINUTE,SECONDfunctions.TheSQLspecificationalsoallowsforTIMEZONE_HOURandTIMEZONE_MINUTEasextractiontargets.InTeiidalldatevaluesareinthetimezoneoftheserver.

xin\{date,time,timestamp},returnsinteger

FORMATDATE(x,y) Formatdatexusingformaty xisdate,yisstring,returnsstring

FORMATTIME(x,y) Formattimexusingformaty xistime,yisstring,returnsstring

FORMATTIMESTAMP(x,y) Formattimestampxusingformaty

xistimestamp,yisstring,returnsstring

ScalarFunctions

308

http://docs.oracle.com/javase/6/docs/api/java/text/SimpleDateFormat.html

FROM_UNIXTIME(unix_timestamp)ReturntheUnixtimestamp(inseconds)asaTimestampvalue

Unixtimestamp(inseconds)

HOUR(x) Returnhour(inmilitary24-hourformat)

xin\{time,timestamp},returnsinteger

MINUTE(x) Returnminutexin\{time,timestamp},returnsinteger

MODIFYTIMEZONE(timestamp,startTimeZone,endTimeZone)

Returnsatimestampbasedupontheincomingtimestampadjustedforthedifferentialbetweenthestartandendtimezones.i.e.iftheserverisinGMT-6,thenmodifytimezone(\{ts'2006-01-1004:00:00.0'},'GMT-7','GMT-8')willreturnthetimestamp\{ts'2006-01-1005:00:00.0'}asreadinGMT-6.Thevaluehasbeenadjusted1houraheadtocompensateforthedifferencebetweenGMT-7andGMT-8.

startTimeZoneandendTimeZonearestrings,returnsatimestamp

MODIFYTIMEZONE(timestamp,endTimeZone)

Returnatimestampinthesamemannerasmodifytimezone(timestamp,startTimeZone,endTimeZone),butwillassumethatthestartTimeZoneisthesameastheserverprocess.

Timestampisatimestamp;endTimeZoneisastring,returnsatimestamp

MONTH(x) Returnmonthxin\{date,timestamp},returnsinteger

MONTHNAME(x) Returnnameofmonthinthedefaultlocale

xin\{date,timestamp},returnsstring

PARSEDATE(x,y) Parsedatefromxusingformaty

x,yin{string},returnsdate

PARSETIME(x,y) Parsetimefromxusingformaty

x,yin{string},returnstime

PARSETIMESTAMP(x,y) Parsetimestampfromxusingformaty

x,yin{string},returnstimestamp

QUARTER(x) Returnquarterxin\{date,timestamp},returnsinteger

SECOND(x) Returnsecondsxin\{time,timestamp},returnsinteger

ScalarFunctions

309

TIMESTAMPCREATE(date,time) Createatimestampfromadateandtime

datein{date},timein{time},returnstimestamp

WEEK(x)Returnweekinyear1-53,seealsoSystemPropertiesforcustomization

xin\{date,timestamp},returnsinteger

YEAR(x) Returnfour-digityearxin\{date,timestamp},returnsinteger

Timestampadd/Timestampdiff

Timestampadd

Addaspecifiedintervalamounttothetimestamp.

TIMESTAMPADD(interval,count,timestamp)

countisanintegerandthereturnvalueisatimestamp.Intervalscanbeoneofthefollowingkeywords:#SQL_TSI_FRAC_SECOND-fractionalseconds(billionthsofasecond)

1. SQL_TSI_SECOND-seconds

2. SQL_TSI_MINUTE-minutes

3. SQL_TSI_HOUR-hours

4. SQL_TSI_DAY-days

5. SQL_TSI_WEEK-weeksusingSundayasthefirstday

6. SQL_TSI_MONTH-months

7. SQL_TSI_QUARTER-quarters(3months)wherethefirstquarterismonths1-3,etc.

8. SQL_TSI_YEAR-years

Thefullintervalamountbaseduponcalendarfieldswillbeadded.Forexampleadding1QUARTERwillmovethetimestampupbythreefullmonthsandnotjusttothestartofthenextcalendarquarter.

Timestampdiff

Calculatesthenumberofdatepartintervalscrossedbetweenthetwotimestamps.

TIMESTAMPDIFF(interval,startTime,endTime)

Intervalcanbeoneofthesamekeywordsasusedbytimestampadd;startTime,endTimearetimestampsandthereturnvalueisalong.

If(endTime>startTime),anon-negativenumberwillbereturned.If(endTime<startTime),anon-positivenumberwillbereturned.Thedatepartdifferencedifferenceiscountedregardlessofhowclosethetimestampsare.Forexample,'2000-01-0200:00:00.0'isstillconsidered1houraheadof`2000-01-0123:59:59.999999'.

CompatibilityIssues

ScalarFunctions

310

Timestampdifftypicallyreturnsaninteger,howeverTeiid’sversionreturnsalong.Youmayreceiveanexceptionifyouexpectavalueoutoftheintegerrangefromapusheddowntimestampdiff.

Teiid’simplementationoftimestampdiffin8.2andpriorversionsreturnedvaluesbaseduponthenumberofwholecanonicalintervalapproximations(365daysinayear,91daysinaquarter,30daysinamonth,etc.)crossed.Forexamplethedifferenceinmonthsbetween2013-03-24and2013-04-01was0,butbaseduponthedatepartscrossedis1.SeeSystemPropertiesforbackwardscompatibility.

ParsingDateDatatypesfromStrings

Teiiddoesnotimplicitlyconvertstringsthatcontaindatespresentedindifferentformats,suchas'19970101'and'31/1/1996'todate-relateddatatypes.Youcan,however,usetheparseDate,parseTime,andparseTimestampfunctions,describedinthenextsection,toexplicitlyconvertstringswithadifferentformattotheappropriatedatatype.Thesefunctionsusetheconventionestablishedwithinthejava.text.SimpleDateFormatclasstodefinetheformatsyoucanusewiththesefunctions.YoucanlearnmoreabouthowthisclassdefinesdateandtimestringformatsbyvisitingtheJavadocsforSimpleDateFormat.NotethattheformatstringswillbelocalespecifictoyourJavadefaultlocale.

Forexample,youcouldusethesefunctioncalls,withtheformattingstringthatadherestothejava.text.SimpleDateFormatconvention,toparsestringsandreturnthedatatypeyouneed:

String FunctionCallToParseString

'1997010' parseDate(myDateString,'yyyyMMdd')

'31/1/1996' parseDate(myDateString,'dd''/''MM''/''yyyy')

'22:08:56CST' parseTime(myTime,'HH:mm:ssz')

'03.24.2003at06:14:32' parseTimestamp(myTimestamp,'MM.dd.yyyy''at''hh:mm:ss')

SpecifyingTimeZones

Timezonescanbespecifiedinseveralformats.CommonabbreviationssuchasESTfor"EasternStandardTime"areallowedbutdiscouraged,astheycanbeambiguous.Unambiguoustimezonesaredefinedintheformcontinentorocean/largestcity.Forexample,America/New_York,America/Buenos_Aires,orEurope/London.Additionally,youcanspecifyacustomtimezonebyGMToffset:GMT[+/-]HH:MM.

Forexample:GMT-05:00

ScalarFunctions

311

http://docs.oracle.com/javase/6/docs/api/java/text/SimpleDateFormat.html

TypeConversionFunctionsWithinyourqueries,youcanconvertbetweendatatypesusingtheCONVERTorCASTkeyword.SeealsoTypeConversions

Function Definition

CONVERT(x,type) Convertxtotype,wheretypeisaTeiidBaseType

CAST(xAStype) Convertxtotype,wheretypeisaTeiidBaseType

Thesefunctionsareidenticalotherthansyntax;CASTisthestandardSQLsyntax,CONVERTisthestandardJDBC/ODBCsyntax.

Important Optionsthatarespecifiedonthetype,suchaslength,precision,scale,etc.,areeffectivelyignored-theruntimeissimplyconvertingfromoneobjecttypetoanother.

ScalarFunctions

312

ChoiceFunctionsChoicefunctionsprovideawaytoselectfromtwovaluesbasedonsomecharacteristicofoneofthevalues.


COALESCE(x,y+) Returnsthefirstnon-nullparameter xandally’scanbeanycompatibletypes

IFNULL(x,y) Ifxisnull,returny;elsereturnx x,y,andthereturntypemustbethesametypebutcanbeanytype

NVL(x,y) Ifxisnull,returny;elsereturnx x,y,andthereturntypemustbethesametypebutcanbeanytype

NULLIF(param1,param2) Equivalenttocasewhen(param1=param2)thennullelseparam1

param1andparam2mustbecompatablecomparabletypes

IFNULLandNVLarealiasesofeachother.Theyarethesamefunction.

ScalarFunctions

313

DecodeFunctionsDecodefunctionsallowyoutohavetheTeiidServerexaminethecontentsofacolumninaresultsetandalter,ordecode,thevaluesothatyourapplicationcanbetterusetheresults.


DECODESTRING(x,y[,z])

Decodecolumnxusingstringofvaluepairsywithoptionaldelimiterzandreturnthedecodedcolumnasastring.Ifadelimiterisnotspecified,isused.yhastheformateSearchDelimResultDelimSearchDelimResult[DelimDefault]ReturnsDefaultifspecifiedorxiftherearenomatches.Deprecated.UseaCASEexpressioninstead.

allstring

DECODEINTEGER(x,y[,z])

Decodecolumnxusingstringofvaluepairsywithoptionaldelimiterzandreturnthedecodedcolumnasaninteger.Ifadelimiterisnotspecified,isused.yhastheformateSearchDelimResultDelimSearchDelimResult[DelimDefault]ReturnsDefaultifspecifiedorxiftherearenomatches.Deprecated.UseaCASEexpressioninstead.

allstringparameters,returninteger

Withineachfunctioncall,youincludethefollowingarguments:

1. xistheinputvalueforthedecodeoperation.Thiswillgenerallybeacolumnname.

2. yistheliteralstringthatcontainsadelimitedsetofinputvaluesandoutputvalues.

3. zisanoptionalparameteronthesemethodsthatallowsyoutospecifywhatdelimiterthestringspecifiedinyuses.

Forexample,yourapplicationmightqueryatablecalledPARTSthatcontainsacolumncalledIS_IN_STOCKwhichcontainsaBooleanvaluethatyouneedtochangeintoanintegerforyourapplicationtoprocess.Inthiscase,youcanusetheDECODEINTEGERfunctiontochangetheBooleanvaluestointegers:

SELECTDECODEINTEGER(IS_IN_STOCK,'false,0,true,1')FROMPartsSupplier.PARTS;

WhentheTeiidSystemencountersthevaluefalseintheresultset,itreplacesthevaluewith0.

If,insteadofusingintegers,yourapplicationrequiresstringvalues,youcanusetheDECODESTRINGfunctiontoreturnthestringvaluesyouneed:

SELECTDECODESTRING(IS_IN_STOCK,'false,no,true,yes,null')FROMPartsSupplier.PARTS;

Inadditiontotwoinput/outputvaluepairs,thissamplequeryprovidesavaluetouseifthecolumndoesnotcontainanyoftheprecedinginputvalues.IftherowintheIS_IN_STOCKcolumndoesnotcontaintrueorfalse,theTeiidServerinsertsanullintotheresultset.

WhenyouusetheseDECODEfunctions,youcanprovideasmanyinput/outputvaluepairsifyouwantwithinthestring.Bydefault,theTeiidSystemexpectsacommadelimiter,butyoucanaddathirdparametertothefunctioncalltospecifyadifferentdelimiter:

SELECTDECODESTRING(IS_IN_STOCK,'false:no:true:yes:null',':')FROMPartsSupplier.PARTS;

YoucanusekeywordnullintheDECODEstringaseitheraninputvalueoranoutputvaluetorepresentanullvalue.However,ifyouneedtousetheliteralstringnullasaninputoroutputvalue(whichmeansthewordnullappearsinthecolumnandnotanullvalue)youcanputthewordinquotes:"null".

ScalarFunctions

314

SELECTDECODESTRING(IS_IN_STOCK,'null,no,"null",no,nil,no,false,no,true,yes')FROMPartsSupplier.PARTS;

IftheDECODEfunctiondoesnotfindamatchingoutputvalueinthecolumnandyouhavenotspecifiedadefaultvalue,theDECODEfunctionwillreturntheoriginalvaluetheTeiidServerfoundinthatcolumn.

ScalarFunctions

315

LookupFunctionTheLookupfunctionprovidesawaytospeedupaccesstovaluesfromareferencetable.TheLookupfunctionautomaticallycachesallkeyandreturncolumnpairsdeclaredinthefunctionforthereferencedtable.Subsequentlookupsagainstthesametableusingthesamekeyandreturncolumnswillusethecachedvalues.Thiscachingacceleratesresponsetimetoqueriesthatuselookuptables,alsoknowninbusinessterminologyascodeorreferencetables.

LOOKUP(codeTable,returnColumn,keyColumn,keyValue)

InthelookuptablecodeTable,findtherowwherekeyColumnhasthevaluekeyValueandreturntheassociatedreturnColumnvalueornull,ifnomatchingkeyValueisfound.codeTablemustbeastringliteralthatisthefully-qualifiednameofthetargettable.returnColumnandkeyColumnmustalsobestringliteralsandmatchcorrespondingcolumnnamesinthecodeTable.ThekeyValuecanbeanyexpressionthatmustmatchthedatatypeofthekeyColumn.ThereturndatatypematchesthatofreturnColumn.

CountryCodeLookup

lookup('ISOCountryCodes','CountryCode','CountryName','UnitedStates')

AnISOCountryCodestableisusedtotranslateacountrynametoanISOcountrycode.Onecolumn,CountryName,representsthekeyColumn.Asecondcolumn,CountryCode,representsthereturnColumn,containingtheISOcodeofthecountry.Hence,theusageofthelookupfunctionherewillprovideaCountryName,shownaboveas`UnitedStates',andexpectaCountryCodevalueinresponse.

WhenyoucallthisfunctionforanycombinationofcodeTable,returnColumn,andkeyColumnforthefirsttime,theTeiidSystemcachestheresult.TheTeiidSystemusesthiscacheforallqueries,inallsessions,thatlateraccessthislookuptable.Youshouldgenerallynotusethelookupfunctionfordatathatissubjecttoupdatesormaybesession/userspecific-includingrowbasedsecurityandcolumnmaskingeffects.SeetheCachingGuideformoreonthecachingaspectsoftheLookupfunction.

ThekeyColumnisexpectedtocontainuniquevaluesforitscorrespondingcodeTable.IfthekeyColumncontainsduplicatevalues,anexceptionwillbethrown.

ScalarFunctions

316

SystemFunctionsSystemfunctionsprovideaccesstoinformationintheTeiidsystemfromwithinaquery.

TableofContentsCOMMANDPAYLOADENVNODE_IDSESSION_IDUSERCURRENT_DATABASETEIID_SESSION_GETTEIID_SESSION_SET

COMMANDPAYLOAD

Retrieveastringfromthecommandpayloadornullifnocommandpayloadwasspecified.ThecommandpayloadissetbytheTeiidStatement.setPayloadmethodontheTeiidJDBCAPIextensionsonaper-querybasis.

COMMANDPAYLOAD([key])

Ifthekeyparameterisprovided,thecommandpayloadobjectiscasttoajava.util.Propertiesobjectandthecorrespondingpropertyvalueforthekeyisreturned.IfthekeyisnotspecifiedthereturnvalueisthecommandpayloadobjecttoStringvalue.

key,returnvaluearestrings

ENVRetrieveasystemenvironmentproperty.

ENV(key)

Topreventuntrustedaccesstosystemproperties,thisfunctionisnotenabledbydefault.TheENVfunctionmaybeenabledviatheallowEnvFunctionpropertyinthefile.

key,returnvaluearestrings

NODE_IDRetrievethenodeid-typicallytheSystempropertyvaluefor"jboss.node.name"whichwillnotbesetforTeiidembedded.

NODE_ID()

returnvalueisstring.

SESSION_IDRetrievethestringformofthecurrentsessionid.

SESSION_ID()

ScalarFunctions

317


USER

Retrievethenameoftheuserexecutingthequery.

USER()


CURRENT_DATABASERetrievethecatalognameofthedatabase.TheVDBnameisalwaysthecatalogname.

CURRENT_DATABASE()


TEIID_SESSION_GETRetrievethesessionvariable.

TEIID_SESSION_GET(name)

nameisastringandthereturnvalueisanobject.

Anullnamewillreturnanullvalue.TypicallyyouwillusetheagetwrappedinaCASTtoconverttothedesiredtype.

TEIID_SESSION_SETSetthesessionvariable.

TEIID_SESSION_SET(name,value)

nameisastring,valueisanobject,andthereturnvalueisanobject.

Thepreviousvalueforthekeyornullwillbereturned.Asethasnoeffectonthecurrenttransactionandisnotaffectedbycommit/rollback.

ScalarFunctions

318

XMLFunctionsXMLfunctionsprovidefunctionalityforworkingwithXMLdata.SeealsotheJSONTOXMLfunction.

TableofContentsSampleDataForExamplesXMLCASTXMLCOMMENTXMLCONCATXMLELEMENTXMLFORESTXMLAGGXMLPARSEXMLPIXMLQUERYXMLEXISTSXMLSERIALIZEXMLTEXTXSLTRANSFORMXPATHVALUEExamples

GeneratinghierarchicalXMLfromflatdatastructure

SampleDataForExamples

ExamplesprovidedwithXMLfunctionsusethefollowingtablestructure

TABLECustomer(

CustomerIdintegerPRIMARYKEY,

CustomerNamevarchar(25),

ContactNamevarchar(25)

Addressvarchar(50),

Cityvarchar(25),

PostalCodevarchar(25),

Countryvarchar(25),

);

withData

CustomerID CustomerName ContactName Address City PostalCode Country

87 WartianHerkku PirkkoKoskitalo

Torikatu38 Oulu 90110 Finland

88 WellingtonImportadora PaulaParente

RuadoMercado,12

Resende 08737-363 Brazil

89 WhiteCloverMarkets KarlJablonski

305-14thAve.S.Suite3B

Seattle 98128 USA

ScalarFunctions

319

XMLCAST

CasttoorfromXML.

XMLCAST(expressionAStype)

ExpressionortypemustbeXML.Thereturnvaluewillbetypedastype.ThisisthesamefunctionalityasXMLTABLEusestoconvertvaluestothedesiredruntimetype-withtheexceptionthatarraytypetargetsarenotsupportedwithXMLCAST.

XMLCOMMENT

Returnsanxmlcomment.

XMLCOMMENT(comment)

Commentisastring.Returnvalueisxml.

XMLCONCATReturnsanXMLwiththeconcatenationofthegivenxmltypes.

XMLCONCAT(content[,content]*)

Contentisxml.Returnvalueisxml.

Ifavalueisnull,itwillbeignored.Ifallvaluesarenull,nullisreturned.

ConcatenatetwoormoreXMLfragments

SELECTXMLCONCAT(

XMLELEMENT("name",CustomerName),

XMLPARSE(CONTENT'<a>b</a>'WELLFORMED)

)

FROMCustomerc

WHEREc.CustomerID=87;

==========================================================

<name>WartianHerkku</name><a>b</a>

XMLELEMENTReturnsanXMLelementwiththegivennameandcontent.

XMLELEMENT([NAME]name[,<NSP>][,<ATTR>][,content]*)

ATTR:=XMLATTRIBUTES(exp[ASname][,exp[ASname]]*)

NSP:=XMLNAMESPACES((uriASprefix|DEFAULTuri|NODEFAULT))+

Ifthecontentvalueisofatypeotherthanxml,itwillbeescapedwhenaddedtotheparentelement.Nullcontentvaluesareignored.WhitespaceinXMLorthestringvaluesofthecontentispreserved,butnowhitespaceisaddedbetweencontentvalues.

ScalarFunctions

320

XMLNAMESPACESisusedprovidenamespaceinformation.NODEFAULTisequivalenttodefiningthedefaultnamespacetothenulluri-xmlns="".OnlyoneDEFAULTorNODEFAULTnamespaceitemmaybespecified.Thenamespaceprefixesxmlnsandxmlarereserved.

Ifaattributenameisnotsupplied,theexpressionmustbeacolumnreference,inwhichcasetheattributenamewillbethecolumnname.Nullattributevaluesareignored.

Name,prefixareidentifiers.uriisastringliteral.contentcanbeanytype.Returnvalueisxml.Thereturnvalueisvalidforuseinplaceswhereadocumentisexpected.

SimpleExample

SELECTXMLELEMENT("name",CustomerName)

FROMCustomerc


==========================================================

<name>WartianHerkku</name>

MultipleColumns

SELECTXMLELEMENT("customer",

XMLELEMENT("name",c.CustomerName),

XMLELEMENT("contact",c.ContactName))

FROMCustomerc


==========================================================

<customer><name>WartianHerkku</name><contact>PirkkoKoskitalo</contact></customer>

ColumnsasAttributes


XMLELEMENT("name",c.CustomerName,

XMLATTRIBUTES(

"contact"asc.ContactName,

"id"asc.CustomerID

)

)

)

FROMCustomerc


==========================================================

<customer><namecontact="PirkkoKoskitalo"id="87">WartianHerkku</name></customer>

XMLFOREST

ReturnsanconcatenationofXMLelementsforeachcontentitem.

XMLFOREST(content[ASname][,<NSP>][,content[ASname]]*)

SeeXMLELEMENTforthedefinitionofNSP-XMLNAMESPACES

Nameisanidentifier.Contentcanbeanytype.Returnvalueisxml.

Ifanameisnotsuppliedforacontentitem,theexpressionmustbeacolumnreference,inwhichcasetheelementnamewillbeapartiallyescapedversionofthecolumnname.

ScalarFunctions

321

YoucanuseXMLFORRESTtosimplifythedeclarationofmultipleXMLELEMENTS,XMLFORESTfunctionallowsyoutoprocessmultiplecolumnsatonce

Example


XMLFOREST(

c.CustomerNameAS"name",

c.ContactNameAS"contact"

))

FROMCustomerc


==========================================================


XMLAGG

XMLAGGisanaggregatefunction,thattakesacollectionofXMLelementsandreturnsanaggregatedXMLdocument.

XMLAGG(xml)

FromaboveexampleinXMLElement,eachrowintheCustomertabletablewillgeneraterowofXMLiftherearemultiplerowsmatchingthecriteria.ThatwillgenerateavalidXML,butitwillnotbewellformed,becauseitlackstherootelement.XMLAGGcanusedtocorrectthat

Example

SELECTXMLELEMENT("customers",

XMLAGG(

XMLELEMENT("customer",

XMLFOREST(

c.CustomerNameAS"name",

c.ContactNameAS"contact"

)))

FROMCustomerc

==========================================================

<customers>


<customer><name>WellingtonImportadora</name><contact>PaulaParente</contact></customer>

<customer><name>WhiteCloverMarkets</name><contact>KarlJablonski</contact></customer>

</customers>

XMLPARSEReturnsanXMLtyperepresentationofthestringvalueexpression.

XMLPARSE((DOCUMENT|CONTENT)expr[WELLFORMED])

exprin\{string,clob,blob,varbinary}.Returnvalueisxml.

IfDOCUMENTisspecifiedthentheexpressionmusthaveasinglerootelementandmayormaynotcontainanXMLdeclaration.

IfWELLFORMEDisspecifiedthenvalidationisskipped;thisisespeciallyusefulforCLOBandBLOBknowntoalreadybevalid.

ScalarFunctions

322

SELECTXMLPARSE(CONTENT'<customer><name>WartianHerkku</name><contact>PirkkoKoskitalo</contact></customer>'W

ELLFORMED);

WillreturnaSQLXMLwithcontents

===============================================================


XMLPIReturnsanxmlprocessinginstruction.

XMLPI([NAME]name[,content])

Nameisanidentifier.Contentisastring.Returnvalueisxml.

XMLQUERY

ReturnstheXMLresultfromevaluatingthegivenxquery.

XMLQUERY([<NSP>]xquery[<PASSING>][(NULL|EMPTY)ONEMPTY]]

PASSING:=PASSINGexp[ASname][,exp[ASname]]*


Namespacesmayalsobedirectlydeclaredinthexqueryprolog.

TheoptionalPASSINGclauseisusedtoprovidethecontextitem,whichdoesnothaveaname,andnamedglobalvariablevalues.Ifthexqueryusesacontextitemandnoneisprovided,thenanexceptionwillberaised.OnlyonecontextitemmaybespecifiedandshouldbeanXMLtype.Allnon-contextnon-XMLpassingvalueswillbeconvertedtoanappropriateXMLtype.Nullwillbereturnedifthecontextitemevaluatestonull.

TheONEMPTYclauseisusedtospecifytheresultwhentheevalutedsequenceisempty.EMPTYONEMPTY,thedefault,returnsanemptyXMLresult.NULLONEMPTYreturnsanullresult.

xqueryinstring.Returnvalueisxml.

XMLQUERYispartoftheSQL/XML2006specification.

SeealsoFROMClause#XMLTABLE

Note SeealsoXQueryOptimization

XMLEXISTSReturnstrueifanon-emptysequencewouldbereturnedbyevaluatingthegivenxquery.

XMLEXISTS([<NSP>]xquery[<PASSING>]]

PASSING:=PASSINGexp[ASname][,exp[ASname]]*


ScalarFunctions

323

Namespacesmayalsobedirectlydeclaredinthexqueryprolog.

TheoptionalPASSINGclauseisusedtoprovidethecontextitem,whichdoesnothaveaname,andnamedglobalvariablevalues.Ifthexqueryusesacontextitemandnoneisprovided,thenanexceptionwillberaised.OnlyonecontextitemmaybespecifiedandshouldbeanXMLtype.Allnon-contextnon-XMLpassingvalueswillbeconvertedtoanappropriateXMLtype.Null/Unknownwillbereturnedifthecontextitemevaluatestonull.

xqueryinstring.Returnvalueisboolean.

XMLEXISTSispartoftheSQL/XML2006specification.


XMLSERIALIZEReturnsacharactertyperepresentationofthexmlexpression.

XMLSERIALIZE([(DOCUMENT|CONTENT)]xml[ASdatatype][ENCODINGenc][VERSIONver][(INCLUDING|EXCLUDING)XMLDECL

ARATION])

Returnvaluematchesdatatype.Ifnodatatypeisspecified,thenclobwillbeassumed.

Thetypemaybecharacter(string,varchar,clob)orbinary(blob,varbinar).CONTENTisthedefault.IfDOCUMENTisspecifiedandthexmlisnotavaliddocumentorfragment,thenanexceptionisraised.

Theencodingencisspecifiedasanidentifier.Acharacterserializationmaynotspecifyanencoding.Theversionverisspecifiedasastringliteral.IfaparticularXMLDECLARATIONisnotspecified,thentheresultwillhaveadeclarationonlyifperforminganonUTF-8/UTF-16ornonversion1.0documentserializationortheunderlyingxmlhasandeclaration.IfCONTENTisbeingserialized,thenthedeclarationwillbeomittedifthevalueisnotadocumentorelement.

SeethefollowingexamplethatproducesaBLOBofXMLinUTF-16includingtheappropriatebyteordermarkofFEFFandXMLdeclaration.

SampleBinarySerialization

XMLSERIALIZE(DOCUMENTvalueASBLOBENCODING"UTF-16"INCLUDINGXMLDECLARATION)

XMLTEXTReturnsxmltext.

XMLTEXT(text)

textisastring.Returnvalueisxml.

XSLTRANSFORM

AppliesanXSLstylesheettothegivendocument.

XSLTRANSFORM(doc,xsl)

Doc,xslin\{string,clob,xml}.Returnvalueisaclob.

ScalarFunctions

324

Ifeitherargumentisnull,theresultisnull.

XPATHVALUE

AppliestheXPATHexpressiontothedocumentandreturnsastringvalueforthefirstmatchingresult.FormorecontrolovertheresultsandXQuery,usetheXMLQUERYfunction.

XPATHVALUE(doc,xpath)

Docin\{string,clob,blob,xml}.xpathisstring.Returnvalueisastring.

Matchinganon-textnodewillstillproduceastringresult,whichincludesalldescendanttextnodes.Ifasingleelementismatchedthatismarkedwithxsi:nil,thennullwillbereturned.

Whentheinputdocumentutilizesnamespaces,itissometimesnecessarytospecifyXPATHthatignoresnamespaces:

SampleXMLforxpathValueIgnoringNamespaces

<?xmlversion="1.0"?>

<ns1:returnxmlns:ns1="http://com.test.ws/exampleWebService">Hello<x>World</x></return>

Function:

SamplexpathValueIgnoringNamespaces

xpathValue(value,'/*[local-name()="return"]')

ResultsinHelloWorld

Examples

GeneratinghierarchicalXMLfromflatdatastructure

Withfollowingtableanditscontents

Table{

xstring,

yinteger

}

datalike['a',1],['a',2],['b',3],['b',4],ifyouwantgenerateaXMLthatlookslike

<root>

<x>

a

<y>1</y>

<y>2</y>

</x>

<x>

b

<y>3</y>

<y>4</y>

</x>

</root>

usetheSQLstatementinTeiidasbelow

ScalarFunctions

325

selectxmlelement(name"root",xmlagg(p))

from(selectxmlelement(name"x",x,xmlagg(xmlelement(name"y",y))aspfromtblgroupbyx))asv

anotherusefullinkofexamplescanbefoundhere

ScalarFunctions

326

http://oracle-base.com/articles/misc/sqlxml-sqlx-generating-xml-content-using-sql.php

JSONFunctionsJSONfunctionsprovidefunctionalityforworkingwithJSON(JavaScriptObjectNotation)data.

TableofContentsJSONTOXMLJSONARRAYJSONOBJECTJSONPARSEConversiontoJSON

JSONTOXML

ReturnsanxmldocumentfromJSON.

JSONTOXML(rootElementName,json)

rootElementNameisastring,jsonisin\{clob,blob}.Returnvalueisxml.

TheappropriateUTFencoding(8,16LE.16BE,32LE,32BE)willbedetectedforJSONblobs.Ifanotherencodingisused,seetheto_charsfunction.

Theresultisalwaysawell-formedXMLdocument.

ThemappingtoXMLusesthefollowingrules:

ThecurrentelementnameisinitiallytherootElementName,andbecomestheobjectvaluenameastheJSONstructureistraversed.

Allelementnamesmustbevalidxml1.1names.InvalidnamesarefullyescapedaccordingtotheSQLXMLspecification.

Eachobjectorprimitivevaluewillbeenclosedinanelementwiththecurrentname.

Unlessanarrayvalueistheroot,itwillnotbeenclosedinanadditionalelement.

Nullvalueswillberepresentedbyanemptyelementwiththeattributexsi:nil="true"

Booleanandnumericalvalueelementswillhavetheattributexsi:typesettobooleananddecimalrespectively.

JSON:

SampleJSONtoXMLforjsonToXml(’person’,x)

{"firstName":"John","children":["Randy","Judy"]}

XML:

SampleJSONtoXMLforjsonToXml(’person’,x)


<person>

<firstName>John</firstName>

<children>Randy</children>

<children>Judy<children>

</person>

ScalarFunctions

327

http://www.json.org/

JSON:

SampleJSONtoXMLforjsonToXml('person',x)witharootarray

[{"firstName":"George"},{"firstName":"Jerry"}]

XML(Noticethereisanextra"person"wrappingelementtokeeptheXMLwell-formed):

SampleJSONtoXMLforjsonToXml(’person’,x)witharootarray


<person>

<person>

<firstName>George</firstName>

</person>

<person>

<firstName>Jerry</firstName>

</person>

</person>

JSON:

SampleJSONtoXMLforjsonToXml(’root’,x)withaninvalidname

{"/invalid":"abc"}

XML:

SampleJSONtoXMLforjsonToXml(’root’,x)withaninvalidname


<root>

<_u002F_invalid>abc</_u002F_invalid>

</root>

JSONARRAY

ReturnsaJSONarray.

JSONARRAY(value...)

valueisanyobjectconvertabletoaJSONvalue.ReturnvalueisaclobmarkedasbeingvalidJSON.

Nullvalueswillbeincludedintheresultasnullliterals.

mixedvalueexample

jsonArray('a"b',1,null,false,{d'2010-11-21'})

Wouldreturn

["a\"b",1,null,false,"2010-11-21"]

JSONOBJECT

ReturnsaJSONobject.

ScalarFunctions

328

JSONARRAY(value[asname]...)

valueisanyobjectconvertabletoaJSONvalue.ReturnvalueisaclobmarkedasbeingvalidJSON.

Nullvalueswillbeincludedintheresultasnullliterals.

Ifanameisnotsuppliedandtheexpressionisacolumnreference,thecolumnnamewillbeusedotherwiseexprNwillbeusedwhereNisthe1-basedindexofthevalueintheJSONARRAYexpression.

mixedvalueexample

jsonObject('a"b'asval,1,nullas"null")

Wouldreturn

{"val":"a\"b","expr2":1,"null":null}

JSONPARSEValidatesandreturnsaJSONresult.

JSONPARSE(value,wellformed)

valueisblobwithanappropriateJSONbinaryencoding(UTF-8,UTF-16,orUTF-32)oraclob.wellformedisabooleanindicatingthatvalidationshouldbeskipped.ReturnvalueisaclobmarkedasbeingvalidJSON.

Anullforeitherinputwillreturnnull.

jsonparseofasimpleliteralvalue

jsonParse('"a"',true)

ConversiontoJSON

Astraight-forwardspecificationcompliantconversionisusedforconvertingvaluesintotheirappropriateJSONdocumentform.

nullvaluesareincludedasthenullliteral.

valuesparsedasJSONorreturnedfromaJSONconstructionfunction(JSONPARSE,JSONARRAY,JSONARRAY_AGG)willbedirectlyappendedintoaJSONresult.

booleanvaluesareincludedastrue/falseliterals

numericvaluesareincludedastheirdefaultstringconversion-insomecircumstancesifnotanumberor+-infinityresultsareallowed,invalidjsonmaybeobtained.

stringvaluesareincludedintheirescaped/quotedform.

binaryvaluesarenotimplicitlyconvertabletoJSONvaluesandrequireaspecificpriortoinclusioninJSON.

allothervalueswillbeincludedastheirstringconversionintheappropriateescaped/quotedform.

ScalarFunctions

329

ScalarFunctions

330

SecurityFunctionsSecurityfunctionsprovidetheabilitytointeractwiththesecuritysystem.

HASROLE

WhetherthecurrentcallerhastheTeiiddataroleroleName.

hasRole([roleType,]roleName)

roleNamemustbeastring,thereturntypeisboolean.

Thetwoargumentformisprovidedforbackwardscompatibility.roleTypeisastringandmustbe`data'.

Rolenamesarecase-sensitiveandonlymatchTeiidDataRoles.JAASroles/groupsnamesarenotvalidforthisfunction-unlessthereiscorrespondingdatarolewiththesamename.

ScalarFunctions

331

SpatialFunctionsSpatialfunctionsprovidefunctionalityforworkingwithgeospatialdata.TeiidreliesontheJTSTopologySuitetoprovidepartialsupportfortheOpenGISSimpleFeaturesSpecificationForSQLRevision1.1.PleaserefertothespecificationortoPostGISformoredetailsaboutparticularfunctions.

MostGeometrysupportislimitedtotwodimensionsduetotheWKBandWKTformats.

Note Geometrysupportisstillevolving.TheremaybeminordifferencesbetweenTeiidandpushdownresultsthatwillneedtobefurtherrefined.

TableofContentsConversionFunctions

ST_GeomFromTextST_GeomFromWKB/ST_GeomFromBinaryST_GeomFromEWKBST_GeomFromTextST_GeomFromGeoJSONST_GeomFromGMLST_AsTextST_AsBinaryST_AsEWKBST_AsGeoJSONST_AsGMLST_AsEWKTST_AsKML

Operators&&

RelationshipFunctionsST_CONTAINSST_CROSSESST_DISJOINTST_DISTANCEST_DWITHINST_EQUALSST_INTERSECTSST_OVERLAPSST_TOUCHESST_WITHIN

Misc.FunctionsST_FORCE_2DST_ENVELOPEST_HASARCST_SRIDST_SetSRIDST_SIMPLIFYST_TRANSFORM

AggregateFunctionsST_EXTENT

ScalarFunctions

332

http://www.opengeospatial.org/

http://www.vividsolutions.com/jts/JTSHome.htm

https://portal.opengeospatial.org/files/?artifact_id=829

http://postgis.net/docs/manual-2.0/

ConversionFunctions

ST_GeomFromText

ReturnsageometryfromaClobinWKTformat.

ST_GeomFromText(text[,srid])

textisaclob,sridisanoptionalinteger.Returnvalueisageometry.

ST_GeomFromWKB/ST_GeomFromBinary

ReturnsageometryfromablobinWKBformat.

ST_GeomFromWKB(bin[,srid])

binisablob,sridisanoptionalinteger.Returnvalueisageometry.

ST_GeomFromEWKB

ReturnsageometryfromablobinEWKBformat.

ST_GeomFromEWKB(bin)

binisablob.Returnvalueisageometry.Only2dimensionsaresupported.

ST_GeomFromText

ReturnsageometryfromaClobinEWKTformat.

ST_GeomFromEWKT(text)

textisaclob.Returnvalueisageometry.Only2dimensionsaresupported.

ST_GeomFromGeoJSON

ReturnsageometryfromaClobinGeoJSONformat.

ST_GeomFromGeoJson(text[,srid])


ST_GeomFromGML

ReturnsageometryfromaClobinGML2format.

ST_GeomFromGML(text[,srid])


ST_AsText

ScalarFunctions

333

ST_AsText(geom)

geomisageometry.ReturnvalueisclobinWKTformat.

ST_AsBinary

ST_AsBinary(geom)

geomisageometry.ReturnvalueisablobinWKBformat.

ST_AsEWKB

ST_AsEWKB(geom)

geomisageometry.ReturnvalueisblobinEWKBformat.

ST_AsGeoJSON

ST_AsGeoJSON(geom)

geomisageometry.ReturnvalueisaclobwiththeGeoJSONvalue.

ST_AsGML

ST_AsGML(geom)

geomisageometry.ReturnvalueisaclobwiththeGML2value.

ST_AsEWKT

ST_AsEWKT(geom)

geomisageometry.ReturnvalueisaclobwiththeEWKTvalue.TheEWKTvalueistheWKTvaluewiththeSRIDprefix.

ST_AsKML

ST_AsKML(geom)

geomisageometry.ReturnvalueisaclobwiththeKMLvalue.TheKMLvalueiseffectivelyasimplifiedGMLvalueandprojectedintoSRID4326.

Operators

&&

Returnstrueiftheboundingboxesofgeom1andgeom2intersect.

ScalarFunctions

334

geom1&&geom2

geom1,geom2aregeometries.Returnvalueisaboolean.

RelationshipFunctions

ST_CONTAINS

Returnstrueifgeom1containsgeom2containsanother.

ST_CONTAINS(geom1,geom2)


ST_CROSSES

Returnstrueifthegeometriescross.

ST_CROSSES(geom1,geom2)


ST_DISJOINT

Returnstrueifthegeometriesaredisjoint.

ST_DISJOINT(geom1,geom2)


ST_DISTANCE

Returnsthedistancebetweentwogeometries.

ST_DISTANCE(geom1,geom2)

geom1,geom2aregeometries.Returnvalueisadouble.

ST_DWITHIN

Returnstrueifthegeometriesarewithinagivendistanceofoneanother.

ST_DWITHIN(geom1,geom2,dist)

geom1,geom2aregeometries.distisadouble.Returnvalueisaboolean.

ST_EQUALS

Returnstrueifthetwogeometriesarespatiallyequal-thepointsandordermaydiffer,butneithergeometryliesoutsideoftheother.

ScalarFunctions

335

ST_EQUALS(geom1,geom2)


ST_INTERSECTS

Returnstrueifthegeometriesintersect.

ST_INTERSECT(geom1,geom2)


ST_OVERLAPS

Returnstrueifthegeometriesoverlap.

ST_OVERLAPS(geom1,geom2)


ST_TOUCHES

Returnstrueifthegeometriestouch.

ST_TOUCHES(geom1,geom2)


ST_WITHIN

Returnstrueifgeom1iscompletelyinsidegeom2.

ST_WITHIN(geom1,geom2)


Misc.Functions

ST_FORCE_2D

Removesthezcoordinatevalueifpresent.

ST_FORCE_2D(geom)

geomisageometry.Returnvalueisageometry.

ST_ENVELOPE

Computesthe2Dboundingboxofthegivengeometry.

ScalarFunctions

336

ST_ENVELOPE(geom)


ST_HASARC

Testifthegeometryhasacircularstring.

ST_HASARC(geom)

geomisageometry.Returnvalueisageometry.Willcurrentlyonlyreportfalseascurvedgeometrytypesarenotsupported.

ST_SRID

ReturnstheSRIDforthegeometry.

ST_SRID(geom)

geomisageometry.Returnvalueisaninteger.A0valueratherthannullwillbereturnedforanunknownSRIDonanon-nullgeometry.

ST_SetSRID

SettheSRIDforthegivengeometry.

ST_SetSRID(geom,srid)

geomisageometry.sridisaninteger.Returnvalueisageometry.OnlytheSRIDmetadataofthegeometryismodified.

ST_SIMPLIFY

SimplifiesaGeometryusingtheDouglas-Peuckeralgorithm.

ST_SIMPLIFY(geom,distanceTolerance)

geomisageometry.distanceToleranceisadouble.Returnvalueisageometry.

ST_TRANSFORM

Transformsthegeometryvaluefromonecoordinatesystemtoanother.

ST_TRANSFORM(geom,srid)

geomisageometry.sridisaninteger.Returnvalueisageometry.ThesridvalueandthesridofthegeometryvaluemustexistintheSPATIAL_REF_SYSview.

AggregateFunctions

ST_EXTENT

ScalarFunctions

337

Computesthe2Dboundingboxaroundallofthegeometryvalues.Allvaluesshouldhavethesamesrid.

ST_EXTENT(geom)


ScalarFunctions

338

MiscellaneousFunctionsOtherfunctions.

array_get

Retunstheobjectvalueatagivenarrayindex.

array_get(array,index)

arrayistheobjecttype,indexmustbeaninteger,andthereturntypeisobject.

1-basedindexingisused.Theactualarrayvalueshouldbeajava.sql.Arrayorjavaarraytype.Anullwillbereturnedifeitherargumentisnulloriftheindexisoutofbounds.

array_length

Returnsthelengthforagivenarray

array_length(array)

arrayistheobjecttype,andthereturntypeisinteger.

Theactualarrayvalueshouldbeajava.sql.Arrayorjavaarraytype.Anexceptionwillbethrownifthearrayvalueisthewrongtype.

uuid

Retunsauniversallyuniqueidentifier.

uuid()

thereturntypeisstring.

Generatesatype4(pseudorandomlygenerated)UUIDusingacryptographicallystrongrandomnumbergenerator.TheformatisXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXXwhereeachXisahexdigit.

ScalarFunctions

339

NondeterministicFunctionHandlingTeiidcategorizesfunctionsbyvaryingdegreesofdeterminism.Whenafunctionisevaluatedandtowhatextenttheresultcanbecachedarebaseduponitsdeterminismlevel.

1. Deterministic-thefunctionwillalwaysreturnthesameresultforthegiveninputs.Deterministicfunctionsareevaluatedbytheengineassoonasallinputvaluesareknown,whichmayoccurassoonastherewritephase.Somefunctions,suchasthelookupfunction,arenottrulydeterministic,butistreatedassuchforperformance.Allfunctionsnotcategorizedbelowareconsidereddeterministic.

2. UserDeterministic-thefunctionwillreturnthesameresultforthegiveninputsforthesameuser.ThisincludesthehasRoleanduserfunctions.Userdeterministicfunctionsareevaluatedbytheengineassoonasallinputvaluesareknown,whichmayoccurassoonastherewritephase.Ifauserdeterministicfunctionisevaluatedduringthecreationofapreparedprocessingplan,thentheresultingplanwillbecachedonlyfortheuser.

3. SessionDeterministic-thefunctionwillreturnthesameresultforthegiveninputsunderthesameusersession.Thiscategoryincludestheenvfunction.Sessiondeterministicfunctionsareevaluatedbytheengineassoonasallinputvaluesareknown,whichmayoccurassoonastherewritephase.Ifasessiondeterministicfunctionisevaluatedduringthecreationofapreparedprocessingplan,thentheresultingplanwillbecachedonlyfortheuser’ssession.

4. CommandDeterministic-theresultoffunctionevaluationisonlydeterministicwithinthescopeoftheusercommand.Thiscategoryincludethecurdate,curtime,now,andcommandpayloadfunctions.Commanddeterministicfunctionsaredelayedinevaluationuntilprocessingtoensurethatevenpreparedplansutilizingthesefunctionswillbeexecutedwithrelevantvalues.Commanddeterministicfunctionevaluationwilloccurpriortopushdown-howevermultipleoccurrencesofthesamecommanddeterministictimefunctionarenotguaranteedtoevaluatetothesamevalue.

5. Nondeterministic-theresultoffunctionevaluationisfullynondeterministic.ThiscategoryincludestherandfunctionandUDFsmarkedasnondeterministic.Nondeterministicfunctionsaredelayedinevaluationuntilprocessingwithapreferenceforpushdown.Ifthefunctionisnotpusheddown,thenitmaybeevaluatedforeveryrowinit’sexecutioncontext(forexampleifthefunctionisusedintheselectclause).

ScalarFunctions

340

DMLCommandsTeiidsupportsSQLforissuingqueriesandfordefiningviewtransformations;seealsoProcedureLanguageforhowSQLisusedinvirtualproceduresandupdateprocedures.NearlyallthesefeaturesfollowstandardSQLsyntaxandfunctionality,soanySQLreferencecanbeusedformoreinformation.

Thereare4basiccommandsformanipulatingdatainSQL,correspondingtotheCRUDcreate,read,update,anddeleteoperations:INSERT,SELECT,UPDATE,andDELETE.AMERGEstatementactsasacombinationofINSERTandUPDATE.

Inaddition,procedurescanbeexecutedusingtheEXECUTEcommand,throughaProceduralRelationalCommand,oranAnonymousProcedureBlock.

SELECTCommandTheSELECTcommandisusedtoretrieverecordsanynumberofrelations.

ASELECTcommandhasanumberofclauses:

WITH…

SELECT…

[FROM…]

[WHERE…]

[GROUPBY…]

[HAVING…]

[ORDERBY…]

[(LIMIT…)|([OFFSET…][FETCH…])]

[OPTION…]

AlloftheseclausesotherthanOPTIONaredefinedbytheSQLspecification.Thespecificationalsospecifiestheorderthattheseclauseswillbelogicallyprocessed.Belowistheprocessingorderwhereeachstagepassesasetofrowstothefollowingstage.Notethatthisprocessingmodelislogicalanddoesnotrepresentthewayanyactualdatabaseengineperformstheprocessing,althoughitisausefulmodelforunderstandingquestionsaboutSQL.

WITHstage-gathersallrowsfromallwithitemsintheorderlisted.Subsequentwithitemsandthemainquerycanreferencetheawithitemasifitisatable.

FROMstage-gathersallrowsfromalltablesinvolvedinthequeryandlogicallyjoinsthemwithaCartesianproduct,producingasinglelargetablewithallcolumnsfromalltables.Joinsandjoincriteriaarethenappliedtofilterrowsthatdonotmatchthejoinstructure.

WHEREstage-appliesacriteriatoeveryoutputrowfromtheFROMstage,furtherreducingthenumberofrows.

GROUPBYstage-groupssetsofrowswithmatchingvaluesinthegroupbycolumns.

HAVINGstage-appliescriteriatoeachgroupofrows.Criteriacanonlybeappliedtocolumnsthatwillhaveconstantvalueswithinagroup(thoseinthegroupingcolumnsoraggregatefunctionsappliedacrossthegroup).

DMLCommands

341

SELECTstage-specifiesthecolumnexpressionsthatshouldbereturnedfromthequery.Expressionsareevaluated,includingaggregatefunctionsbasedonthegroupsofrows,whichwillnolongerexistafterthispoint.Theoutputcolumnsarenamedusingeithercolumnaliasesoranimplicitnamedeterminedbytheengine.IfSELECTDISTINCTisspecified,duplicateremovalwillbeperformedontherowsbeingreturnedfromtheSELECTstage.

ORDERBYstage-sortstherowsreturnedfromtheSELECTstageasdesired.Supportssortingonmultiplecolumnsinspecifiedorder,ascendingordescending.TheoutputcolumnswillbeidenticaltothosecolumnsreturnedfromtheSELECTstageandwillhavethesamename.

LIMITstage-returnsonlythespecifiedrows(withskipandlimitvalues).

ThismodelcanbeusedtounderstandmanyquestionsaboutSQL.Forexample,columnsaliasedintheSELECTclausecanonlybereferencedbyaliasintheORDERBYclause.Withoutknowledgeoftheprocessingmodel,thiscanbesomewhatconfusing.Seeninlightofthemodel,itisclearthattheORDERBYstageistheonlystageoccurringaftertheSELECTstage,whichiswherethecolumnsarenamed.BecausetheWHEREclauseisprocessedbeforetheSELECT,thecolumnshavenotyetbeennamedandthealiasesarenotyetknown.

Tip TheexplicittablesyntaxTABLExmaybeusedasashortcutforSELECT*FROMx.

VALUESCommandTheVALUEScommandisusedtoconstructasimpletable.

ExampleSyntax

VALUES(value,...)

VALUES(value,...),(valueX,...)...

AVALUEScommandwithasinglevaluesetisequivalentto"SELECTvalue,….".AVALUEScommandwithmultiplevaluessetsisequivalenttoaUNIONALLofsimpleSELECTs-"SELECTvalue,….UNIONALLSELECTvalueX,…".

UpdateCommands

Updatecommandscanreportintegerupdatecounts.Ifalargernumberorrowsisupdated,thenthemaxintegervaluewillbereported(2^31-1).

INSERTCommand

TheINSERTcommandisusedtoaddarecordtoatable.

ExampleSyntax

INSERTINTOtable(column,...)VALUES(value,...)

INSERTINTOtable(column,...)query

UPDATECommand

DMLCommands

342

TheUPDATEcommandisusedtomodifyrecordsinatable.Theoperationmayresultin1ormorerecordsbeingupdated,orinnorecordsbeingupdatedifnonematchthecriteria.

ExampleSyntax

UPDATEtableSET(column=value,...)[WHEREcriteria]

DELETECommand

TheDELETEcommandisusedtoremoverecordsfromatable.Theoperationmayresultin1ormorerecordsbeingdeleted,orinnorecordsbeingdeletedifnonematchthecriteria.

ExampleSyntax

DELETEFROMtable[WHEREcriteria]

MERGECommandTheMERGEcommand,alsoknownasUPSERT,isusedtoaddand/orupdaterecords.TheTeiidspecific(non-ANSI)MERGEissimplyamodifiedINSERTstatementthatrequiresthetargettabletohaveaprimarykeyandforthetargetcolumnstocovertheprimarykey.TheMERGEoperationwillthenchecktheexistenceofeachrowpriortoINSERTandinsteadperformanUPDATEiftherowalreadyexists.

ExampleSyntax

MERGEINTOtable(column,...)VALUES(value,...)

MERGEINTOtable(column,...)query

Note MergePushdown-TheMERGEstatementisnotcurrentlypushedtosources,butratherwillbebrokendownintotherespectiveinsert/updateoperations.

EXECUTECommand

TheEXECUTEcommandisusedtoexecuteaprocedure,suchasavirtualprocedureorastoredprocedure.Proceduresmayhavezeroormorescalarinputparameters.Thereturnvaluefromaprocedureisaresultsetorthesetofinout/out/returnscalars.NotethatEXECorCALLcanbeusedasashortformofthiscommand.

ExampleSyntax

EXECUTEproc()

CALLproc(value,...)

NamedParameterSyntax

EXECUTEproc(name1=>value1,name4=>param4,...)

DMLCommands

343

SyntaxRules:

Thedefaultorderofparameterspecificationisthesameashowtheyaredefinedintheproceduredefinition.

Youcanspecifytheparametersinanyorderbyname.Parametersthatarehavedefaultvaluesand/orarenullableinthemetadata,canbeomittedfromthenamedparametercallandwillhavetheappropriatevaluepassedatruntime.

Positionalparametersthatarehavedefaultvaluesand/orarenullableinthemetadata,canbeomittedfromtheendoftheparameterlistandwillhavetheappropriatevaluepassedatruntime.

Iftheproceduredoesnotreturnaresultset,thevaluesfromtheRETURN,OUT,andIN_OUTparameterswillbereturnedasasinglerowwhenusedasaninlineviewquery.

AVARIADICparametermayberepeated0ormoretimesasthelastpositionalargument.

ProceduralRelationalCommand

ProceduralrelationalcommandsusethesyntaxofaSELECTtoemulateanEXEC.InaproceduralrelationalcommandaproceduregroupnamesisusedinaFROMclauseinplaceofatable.Thatprocedurewillbeexecutedinplaceofanormaltableaccessifallofthenecessaryinputvaluescanbefoundincriteriaagainsttheprocedure.Eachcombinationofinputvaluesfoundinthecriteriaresultsinanexecutionoftheprocedure.

ExampleSyntax

select*fromproc

selectoutput_param1,output_param2fromprocwhereinput_param1='x'

selectoutput_param1,output_param2fromproc,tablewhereinput_param1=table.col1andinput_param2=table.c

ol2

SyntaxRules:

Theprocedureasatableprojectsthesamecolumnsasanexecwiththeadditionoftheinputparameters.Forproceduresthatdonotreturnaresultset,IN_OUTcolumnswillbeprojectedastwocolumns,onethatrepresentstheoutputvalueandonenamed\{columnname}_INthatrepresentstheinputoftheparameter.

Inputvaluesarepassedviacriteria.Valuescanbepassedby'=','isnull',or'in'predicates.Disjunctsarenotallowed.Itisalsonotpossibletopassthevalueofanon-comparablecolumnthroughanequalitypredicate.

TheprocedureviewautomaticallyhasanaccesspatternonitsINandIN_OUTparameterswhichallowsittobeplannedcorrectlyasadependentjoinwhennecessaryorfailwhensufficientcriteriacannotbefound.

Procedurescontainingduplicatenamesbetweentheparameters(IN,IN_OUT,OUT,RETURN)andresultsetcolumnscannotbeusedinaproceduralrelationalcommand.

DefaultvaluesforIN,IN_OUTparametersarenotusedifthereisnocriteriapresentforagiveninput.Defaultvaluesareonlyvalidfornamedproceduresyntax.

MultipleExecution

Theusageof'in'orjoincriteriacanresultintheprocedurebeingexecutedmultipletimes.

AlternativeSyntax

Noneofissueslistedinthesyntaxrulesaboveexistifanestedtablereferenceisused.

DMLCommands

344

AnonymousProcedureBlock

AProcedureLanguageblockmaybeexecutedasausercommand.Thisisadvantageousinsituationswhenavirtualproceduredoesn’texists,butasetofprocessingcanbecaredoutontheserversidetogether.

ExampleSyntax

begininsertintopm1.g1(e1,e2)select?,?;selectrowcount;end;

SyntaxRules:

Inparametersaresupportedwithprepared/callablestatementparametersasshownabovewitha?parameter.

outparametersarenotyetsupported-considerusingsessionvariablesasaworkaroundasneeded.

areturnparameterisnotsupported.

asingleresultwillbereturnedifanyofthestatementsreturnsaresultset.Allreturnableresultsetsmusthaveamatchingnumberofcolumnsandtypes.UsetheWITHOUTRETURNclausetoindicatethatastatementisnotintendedtoaresultsetasneeded.

DMLCommands

345

SetOperationsTeiidsupportstheUNION,UNIONALL,INTERSECT,EXCEPTsetoperationasawayofcombiningtheresultsofqueryexpressions.

Usage:

queryExpression(UNION|INTERSECT|EXCEPT)[ALL]queryExpression[ORDERBY...]

SyntaxRules:

Theoutputcolumnswillbenamedbytheoutputcolumnsofthefirstsetoperationbranch.

EachSELECTmusthavethesamenumberofoutputcolumnsandcompatibledatatypesforeachrelativecolumn.Datatypeconversionwillbeperformedifdatatypesareinconsistentandimplicitconversionsexist.

IfUNION,INTERSECT,orEXCEPTisspecifiedwithoutall,thentheoutputcolumnsmustbecomparabletypes.

INTERSECTALL,andEXCEPTALLarecurrentlynotsupported.

DMLCommands

346

SubqueriesAsubqueryisaSQLqueryembeddedwithinanotherSQLquery.Thequerycontainingthesubqueryistheouterquery.

Supportedsubquerytypes:

Scalarsubquery-asubquerythatreturnsonlyasinglecolumnwithasinglevalue.Scalarsubqueriesareatypeofexpressionandcanbeusedwheresinglevaluedexpressionsareexpected.

Correlatedsubquery-asubquerythatcontainsacolumnreferencetofromtheouterquery.

Uncorrelatedsubquery-asubquerythatcontainsnoreferencestotheoutersub-query.

InlineviewsSubqueriesintheFROMclauseoftheouterquery(alsoknownas"inlineviews")canreturnanynumberofrowsandcolumns.Thistypeofsubquerymustalwaysbegivenanalias.Aninlineviewisnearlyidenticaltoatraditionalview.SeealsoWITHClause.

ExampleSubqueryinFROMClause(InlineView)

SELECTaFROM(SELECTY.b,Y.cFROMYWHEREY.d='3')ASXWHEREa=X.cANDb=X.b

Subqueriescanappearanywherewhereanexpressionorcriteriaisexpected.Subqueriesaresupportedinquantifiedcriteria,theEXISTSpredicate,theINpredicate,andasScalarSubqueries.

ExampleSubqueryinWHEREUsingEXISTS

SELECTaFROMXWHEREEXISTS(SELECT1FROMYWHEREc=X.a)

ExampleQuantifiedComparisonSubqueries

SELECTaFROMXWHEREa>=ANY(SELECTbFROMYWHEREc=3)

SELECTaFROMXWHEREa<SOME(SELECTbFROMYWHEREc=4)

SELECTaFROMXWHEREa=ALL(SELECTbFROMYWHEREc=2)

ExampleINSubquery

SELECTaFROMXWHEREaIN(SELECTbFROMYWHEREc=3)

SeealsoSubqueryOptimization.

DMLCommands

347

WITHClauseTeiidsupportsnon-recursivecommontableexpressionsviatheWITHclause.WITHclauseitemsmaybereferencedastablesinsubsequentwithclauseitemsandinthemainquery.TheWITHclausecanbethoughtofasprovidingqueryscopedtemporarytables.

Usage:

WITHname[(column,...)]AS[/*+no_inline*/](queryexpression)...

SyntaxRules:

Alloftheprojectedcolumnnamesmustbeunique.Iftheyarenotunique,thenthecolumnnamelistmustbeprovided.

IfthecolumnsoftheWITHclauseitemaredeclared,thentheymustmatchthenumberofcolumnsprojectedbythequeryexpression.

Eachwithclauseitemmusthaveauniquename.

Theoptionalno_inlinehintindicatestotheoptimizerthatthequeryexpressionshouldnotbesubstitutedinlinewherereferenced.

Note TheWITHclauseisalsosubjecttooptimizationandit’sentriesmaynotbeprocessediftheyarenotneededinthesubsequentquery.

Examples:

WITHn(x)AS(selectcolfromtbl)selectxfromn,nasn1

WITHn(x)AS/*+no_inline*/(selectcolfromtbl)selectxfromn,nasn1

RecursiveCommonTableExpressionsArecursivecommontableexpressionisaspecialformofacommontableexpressionthatisallowedtorefertoitselftobuildthefullcommontableresultinarecursiveoriterativefashion.

Usage:

WITHname[(column,...)]AS(anchorqueryexpressionUNION[ALL]recursivequeryexpression)...

Therecursivequeryexpressionisallowedtorefertothecommontablebyname.ProcessingflowswithTheanchorqueryexpressionexecutedfirst.Theresultswillbeaddedtothecommontableandwillbereferencedfortheexecutionoftherecursivequeryexpression.Theprocesswillberepeatedagainstthenewresultsuntiltherearenomoreintermediateresults.

Note Anonterminatingrecursivecommontableexpressioncanleadtoexcessiveprocessing.

Topreventrunawayprocessingofarecursivecommontableexpression,processingisbydefaultlimitedto10000iterations.Recursivecommontableexpressionsthatarepusheddownarenotsubjecttothislimit,butmaybesubjecttoothersourcespecificlimits.Thelimitcanbemodifiedbysettingthesessionvariableteiid.maxRecusiontoalargerintegervalue.Oncethemaxhasbeenexceededanexceptionwillbethrown.

Example:

DMLCommands

348

SELECTteiid_session_set('teiid.maxRecursion',25);

WITHn(x)AS(values('a')UNIONselectchr(ascii(x)+1)fromnwherex<'z')select*fromn

Thiswillfailtoprocessastherecursionlimitwillbereachedbeforeprocessingcompletes.

DMLCommands

349

SELECTClauseSQLqueriesthatstartwiththeSELECTkeywordandareoftenreferredtoas"SELECTstatements".TeiidsupportsmostofthestandardSQLqueryconstructs.

Usage:

SELECT[DISTINCT|ALL]((expression[[AS]name])|(groupidentifier.STAR))*|STAR...

SyntaxRules:

AliasedexpressionsareonlyusedastheoutputcolumnnamesandintheORDERBYclause.Theycannotbeusedinotherclausesofthequery.

DISTINCTmayonlybespecifiediftheSELECTsymbolsarecomparable.

DMLCommands

350

FROMClausTheFROMclausespecifiesthetargettable(s)forSELECT,UPDATE,andDELETEstatements.

ExampleSyntax:

FROMtable[[AS]alias]

FROMtable1[INNER|LEFTOUTER|RIGHTOUTER|FULLOUTER]JOINtable2ONjoin-criteria

FROMtable1CROSSJOINtable2

FROM(subquery)[AS]alias

FROMTABLE(subquery)[AS]alias

FROMtable1JOIN/*+MAKEDEP*/table2ONjoin-criteria

FROMtable1JOIN/*+MAKENOTDEP*/table2ONjoin-criteria

FROM/*+MAKEIND*/table1JOINtable2ONjoin-criteria

FROM/*+NO_UNNEST*/vw1JOINtable2ONjoin-criteria

FROMtable1leftouterjoin/*+optional*/table2ONjoin-criteria

FROMTEXTTABLE…

FROMXMLTABLE…

FROMARRAYTABLE…

FROMOBJECTTABLE…

FROM(SELECT…

FromClauseHintsFromclausehintsaretypicallyspecifiedinacommentblockprecedingtheaffectedclause.MAKEDEPandMAKENOTDEPmayalsoappearafterinnon-commentformaftertheaffectedclause.Ifmultiplehintsapplytothatclause,thehintsshouldbeplacedinthesamecommentblock.

ExampleHint

FROM/*+MAKEDEPPRESERVE*/(tbl1innerjointbl2innerjointbl3ontbl2.col1=tbl3.col1ontbl1.col1=tbl2

.col1),tbl3WHEREtbl1.col1=tbl2.col1

DependentJoins

MAKEIND,MAKEDEP,andMAKENOTDEParehintsusedtocontroldependentjoinbehavior.Theyshouldonlybeusedinsituationswheretheoptimizerdoesnotchoosethemostoptimalplanbaseduponquerystructure,metadata,andcostinginformation.Thehintsmayappearinacommentthatproceedsthefromclause.Thehintscanbespecifiedagainstanyfromclause,notjustanamedtable.

MAKEIND-treatthisclauseastheindependent(feeder)sideofadependentjoinifpossible.

MAKEDEP-treatthisclauseasthedependent(filtered)sideofadependentjoinifpossible.

DMLCommands

351

MAKENOTDEP-donottreatthisclauseasthedependent(filtered)sideofajoin.

MAKEDEPandMAKEINDsupportoptionalmaxandjoinarguments:

MAKEDEP(JOIN)meansthattheentirejoinshouldbepushed

MAKEDEP(NOJOIN)meansthattheentirejoinshouldnotbepushed

MAKEDEP(MAX:val)meaningthatthedependentjoinshouldonlybeperformediftherearelessthanthemaxnumberofvaluesfromtheindependentside.

OtherHints

NO_UNNESTcanbespecifiedagainstasubqueryfromclauseorviewtoinstructtheplannertonotmergethenestedSQLinthesurroundingquery-alsoknownasviewflattening.ThishintonlyappliestoTeiidplanningandisnotpassedtosourcequeries.NO_UNNESTmayappearinacommentthatproceedsthefromclause.

ThePRESERVEhintcanbeusedagainstanANSIjointreetopreservethestructureofthejoinratherthanallowingtheTeiidoptimizertoreorderthejoin.ThisissimilarinfunctiontotheOracleORDEREDorMySQLSTRAIGHT_JOINhints.

ExamplePRESERVEHint

FROM/*+PRESERVE*/(tbl1innerjointbl2innerjointbl3ontbl2.col1=tbl3.col1ontbl1.col1=tbl2.col1)

NestedTableReference

NestedtablesmayappearintheFROMclausewiththeTABLEkeyword.Theyareanalternativetousingaviewwithnormaljoinsemantics.ThecolumnsprojectedfromthecommandcontainedinthenestedtablemaybeusedjustasanyoftheotherFROMclauseprojectedcolumnsinjoincriteria,thewhereclause,etc.

AnestedtablemayhavecorrelatedreferencestoprecedingFROMclausecolumnreferencesaslongasINNERandLEFTOUTERjoinsareused.Thisisespeciallyusefulincaseswherethennestedexpressionisaprocedureorfunctioncall.

Validexample:

select*fromt1,TABLE(callproc(t1.x))t2

Invalidexample,sincet1appearsafterthenestedtableinthefromclause:

select*fromTABLE(callproc(t1.x))t2,t1

Note MultipleExecution-Theusageofacorrelatednestedtablemayresultinmultipleexecutionsofthetableexpression-onceforeachcorrelatedrow.

DMLCommands

352

XMLTABLETheXMLTABLEfunctionusesXQuerytoproducetabularoutput.TheXMLTABLEfunctionisimplicitlyanestedtableandmaybecorrelatedtoprecedingFROMclauseentries.XMLTABLEispartoftheSQL/XML2006specification.

Usage:

XMLTABLE([<NSP>,]xquery-expression[<PASSING>][COLUMNS<COLUMN>,...)]ASname

COLUMN:=name(FORORDINALITY|(datatype[DEFAULTexpression][PATHstring]))

SeeXMLELEMENTforthedefinitionofNSP-XMLNAMESPACES.

SeeXMLQUERYforthedefinitionofPASSING.

SeealsoXMLQUERY


Parameters

TheoptionalXMLNAMESPACESclausespecifiesthenamepacesforuseintheXQueryandCOLUMNpathexpressions.

Thexquery-expressionshouldbeavalidXQuery.EachsequenceitemreturnedbythexquerywillbeusedtocreatearowofvaluesasdefinedbytheCOLUMNSclause.

IfCOLUMNSisnotspecified,thenthatisthesameashavingtheCOLUMNSclause:"COLUMNSOBJECT_VALUEXMLPATH'."',whichreturnstheentireitemasanXMLvalue.

AFORORDINALITYcolumnistypedasintegerandwillreturnthe1-baseditemnumberasitsvalue.

Eachnon-ordinalitycolumnspecifiesatypeandoptionallyaPATHandaDEFAULTexpression.

IfPATHisnotspecified,thenthepathwillbethesameasthecolumnname.

SyntaxRules:

Only1FORORDINALITYcolumnmaybespecified.

Thecolumnsnamesmustnotcontainduplicates.

Theblobdatatypeissupported,butthereisonlybuilt-insupportforxs:hexBinaryvalues.Forxs:base64Binary,useaworkaroundofaPATHthatusestheexplicitvalueconstructor"xs:base64Binary(<path>)".

Thecolumnexpressionmustevaluatetoasinglevalueifanon-arraytypeisexpected.

Ifanarraytypeisspecifiedthenanarraywillbereturnedunlesstherearenoelementsinthesequence,inwhichcaseanullvalueisreturned.

Anemptyelementisnotavalidnullvalueasitiseffectivelytheemptystring.Thexsi:nilattributeshouldbeusedtodefineconveyanullvaluedelement.

Examples

Useofpassing,returns1row[1]:

select*fromxmltable('/a'PASSINGxmlparse(document'<aid="1"/>')COLUMNSidintegerPATH'@id')x

DMLCommands

353

Asanestedtable:

selectx.*fromt,xmltable('/x/y'PASSINGt.docCOLUMNSfirststring,secondFORORDINALITY)x

Invalidmulti-value:

select*fromxmltable('/a'PASSINGxmlparse(document'<a><bid="1"/><bid="2"/></a>')COLUMNSidintegerPATH

'b/@id')x

Arraymulti-value:

select*fromxmltable('/a'PASSINGxmlparse(document'<a><bid="1"/><bid="2"/></a>')COLUMNSidinteger[]PATH

'b/@id')x

Nilelement.Withoutthenilattributeanexceptionwouldbethrownconvertingbtoanintegervalue.

select*fromxmltable('/a'PASSINGxmlparse(document'<axmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

><bxsi:nil="true"/></a>')COLUMNSidintegerPATH'b')x

DMLCommands

354

ARRAYTABLETheARRAYTABLEfunctionprocessesanarrayinputtoproducetabularoutput.Thefunctionitselfdefineswhatcolumnsitprojects.TheARRAYTABLEfunctionisimplicitlyanestedtableandmaybecorrelatedtoprecedingFROMclauseentries.

Usage:

ARRAYTABLE(expressionCOLUMNS<COLUMN>,...)ASname

COLUMN:=namedatatype

Parameters

expression-thearraytoprocess,whichshouldbeajava.sql.Arrayorjavaarrayvalue.

SyntaxRules:

Thecolumnsnamesmustbenotcontainduplicates.

Examples

Asanestedtable:

selectx.*from(callsource.invokeMDX('somequery'))r,arraytable(r.tupleCOLUMNSfirststring,secondbigdec

imal)x

ARRAYTABLEiseffectivelyashortcutforusingtheMiscellaneousFunctions#array_getfunctioninanestedtable.Forexample

ARRAYTABLE(valCOLUMNScol1string,col2integer)ASX

isthesameas

TABLE(SELECTcast(array_get(val,1)ASstring)AScol1,cast(array_get(val,2)ASinteger)AScol2)ASX

*Prev*FROMClause

Topofpage

Frontpage

*Next*OBJECTTABLE

DMLCommands

355

OBJECTTABLETheOBJECTTABLEfunctionprocessesanobjectinputtoproducetabularoutput.Thefunctionitselfdefineswhatcolumnsitprojects.TheOBJECTTABLEfunctionisimplicitlyanestedtableandmaybecorrelatedtoprecedingFROMclauseentries.

Usage:

OBJECTTABLE([LANGUAGElang]rowScript[PASSINGvalASname...]COLUMNScolNamecolTypecolScript[DEFAULTdefa

ultExpr]...)ASid

Parameters

lang-anoptionalstringliteralthatisthecasesensitivelanguagenameofthescriptstobeprocessed.ThescriptenginemustbeavailableviaaJSR-223ScriptEngineManagerlookup.Insomeinstancesthismaymeanmakingadditionalmodulesavailabletoyourvdb,whichcanbedoneviathesameprocessasaddingmodules/librariesforUDFs.IfaLANGUAGEisnotspecified,thedefaultof'teiid_script'(seebelow)willbeused.

name-anidentifierthatwillbindthevalexpressionvalueintothescriptcontext.

rowScriptisastringliteralspecifyingthescripttocreatetherowvalues.foreachnon-nullitemtheIteratorproducesthecolumnswillbeevaluated.

colName/colTypearetheid/datatypeofthecolumn,whichcanoptionallybedefaultedwiththeDEFAULTclauseexpressiondefaultExpr.

colScriptisastringliteralspecifyingthescriptthatevaluatestothecolumnvalue.

SyntaxRules:

Thecolumnsnamesmustbenotcontainduplicates.

Teiidwillplaceseveralspecialvariablesinthescriptexecutioncontext.TheCommandContextisavailableasteiid_context.AdditionallythecolScriptsmayaccessteiid_rowandteiid_row_number.teiid_rowisthecurrentrowobjectproducedbytherowscript.teiid_row_numberisthecurrent1-basedrownumber.

rowScriptisevaluatedtoanIterator.IftheresultsisalreadyanIterator,itisuseddirectly.IftheevaluationresultisanIteratable,thenanIteratorwillbeobtained.AnyotherObjectwillbetreatedasanIteratorofasingleitem).Inallcasesnullrowvalueswillbeskipped.

Note WhilethereisnorestrictionwhatcanbeusedasaPASSINGvariablenamesyoushouldchoosenamesthatcanbereferencedasidentifiersinthetargetlanguage.

Examples

Accessingspecialvariables:

SELECTx.*FROMOBJECTTABLE('teiid_context'COLUMNS"user"string'teiid_row.userName',row_numberinteger'tei

id_row_number')ASx

Theresultwouldbearowwithtwocolumnscontainingtheusernameand1respectively.

Note

DuetotheirmostlyunrestrictedaccesstoJavafunctionality,usageoflanguagesotherthanteiid_scriptisrestrictedbydefault.AVDBmustdeclareallallowablelanguagesbynameintheallowed-languagesVDBpropertyusingacommaseparatedlist.Thenamesarecasesensitivenamesandshouldbeseparatedwithoutwhitespace.WithoutthispropertyitisnotpossibletouseOBJECTTABLEevenfromwithinviewdefinitionsthatarenotsubjecttonormalpermissionchecks.

DMLCommands

356

DatarolesarealsosecuredwithDataRolesusingthelanguagepermission.

teiid_script

teiid_scriptisasimplescriptingexpressionlanguagethatallowsaccesstopassingandspecialvariablesaswellasanynon-void0-argumentmethodsonobjectsandindexedvaluesonarrays/lists.Ateiid_scriptexpressionbeginsbyreferencingthepassingorspecialvariable.Thenanynumberof.'accessorsmaybechainedtoevaluatetheexpressiontoadifferentvalue.Methodsmaybeaccessedbytheirpropertynames,forexamplefooratherthangetFoo.Iftheobjectbotha`getFoo()

andfoo()method,thentheaccessorfooreferencesfo()andgetFooshouldbeusedtocallthegetter.Anarrayorlistindexmaybeaccessedusinga1-basedpositiveintegralvalue-usingthesame'.'accessorsyntax.Thesamelogicasthesystemfunctionarray_getisusedmeaningthatnullwillbereturnedratherthanexceptioniftheindexisoutofbounds.

teiid_scriptiseffectivelydynamicallytypedastypingisperformedatruntime.Ifaaccessordoesnotexistontheobjectorifthemethodisnotaccessible,thenanexceptionwillberaised.Ifatanypointintheaccessorchainevaluatestoanullvalue,thennullwillbereturned.

Examples

TogettheVDBdescriptionstring:

teiid_context.session.vdb.description

TogetthefirstcharacteroftheVDBdescriptionstring:

teiid_context.session.vdb.description.toCharArray.1

DMLCommands

357

TEXTTABLETheTEXTTABLEfunctionprocessescharacterinputtoproducetabularoutput.Itsupportsbothfixedanddelimitedfileformatparsing.Thefunctionitselfdefineswhatcolumnsitprojects.TheTEXTTABLEfunctionisimplicitlyanestedtableandmaybecorrelatedtoprecedingFROMclauseentries.

Usage:

TEXTTABLE(expression[SELECTORstring]COLUMNS<COLUMN>,...[NOROWDELIMITER|ROWDELIMITERchar][DELIMITER

char][(QUOTE|ESCAPE)char][HEADER[integer]][SKIPinteger][NOTRIM])ASname

Where<COLUMN>

COLUMN:=name(FORORDINALITY|([HEADERstring]datatype[WIDTHinteger[NOTRIM]][SELECTORstringinteger]))

Parameters

expression-thetextcontenttoprocess,whichshouldbeconvertibletoCLOB.

SELECTORisusedwithfilescontainingmultipletypesofrows(example:orderheader,detail,summary).ATEXTTABLESELECTORspecifieswhichlinestoincludeintheoutput.Matchinglinesmustbeginwiththeselectorstring.Theselectorincolumndelimitedfilesmustbefollowedbythecolumndelimiter.

IfaTEXTTABLESELECTORisspecified,aSELECTORmayalsobespecifiedforcolumnvalues.AcolumnSELECTORargumentwillselectthenearestprecedingtextlinewiththegivenSELECTORprefixandselectthevalueatthegiven1-basedintegerposition(whichincludestheselectoritself).Ifnosuchtextlineorpositionwithagivenlineexists,anullvaluewillbeproduced.AcolumnSELECTORisnotvalidwithfixedwidthparsing.

NOROWDELIMITERindicatesthatfixedparsingshouldnotassumethepresenceofnewlinerowdelimiters.

ROWDELIMITERsetstherowdelimiter/newlinetoanalternatecharacter.Defaultstothenewlinecharacter-withbuiltinhandlingfortreatingcarriagereturnnewlineasasinglecharacter.IfROWDELIMITERisspecified,carriagereturnwillbegivennospecialtreatment.

DELIMITERsetsthefielddelimitercharactertouse.Defaultsto','.

QUOTEsetsthequote,orqualifier,characterusedtowrapfieldvalues.Defaultsto'"'.

ESCAPEsetstheescapecharactertouseifnoquotingcharacterisinuse.Thisisusedinsituationswherethedelimiterornewlinecharactersareescapedwithaprecedingcharacter,e.g.\,

HEADERspecifiesthetextlinenumber(countingeverynewline)onwhichthecolumnnamesoccur.IftheHEADERoptionforacolumnisspecified,thenthatwillbeusedastheexpectedheadername.Alllinespriortotheheaderwillbeskipped.IfHEADERisspecified,thentheheaderlinewillbeusedtodeterminetheTEXTTABLEcolumnpositionbycase-insensitivenamematching.Thisisespeciallyusefulinsituationswhereonlyasubsetofthecolumnsareneeded.IftheHEADERvalueisnotspecified,itdefaultsto1.IfHEADERisnotspecified,thencolumnsareexpectedtomatchpositionallywiththetextcontents.

SKIPspecifiesthenumberoftextlines(countingeverynewline)toskipbeforeparsingthecontents.HEADERmaystillbespecifiedwithSKIP.

AFORORDINALITYcolumnistypedasintegerandwillreturnthe1-baseditemnumberasitsvalue.

DMLCommands

358

WIDTHindicatesthefixed-widthlengthofacolumnincharacters-notbytes.WiththedefaultROWDELIMITER,aCRNLsequencecountsasasinglecharacter.

NOTRIMspecifiedontheTEXTTABLE,itwillaffectallcolumnandheadervalues.IfNOTRIMisspecifiedonacolumn,thenthefixedorunqualifiedtextvaluenotbetrimmedofleadingandtrailingwhitespace.

SyntaxRules:

Ifwidthisspecifiedforonecolumnitmustbespecifiedforallcolumnsandbeanon-negativeinteger.

Ifwidthisspecified,thenfixedwidthparsingisusedESCAPE,QUOTE,columnSELECTOR,norHEADERshouldnotbespecified.

Ifwidthisnotspecified,thenNOROWDELIMITERcannotbeused.

Thecolumnsnamesmustnotcontainduplicates.

TheQUOTE,DELIMITER,andROWDELIMITERmustallbedifferentcharacters.

Examples

UseoftheHEADERparameter,returns1row['b']:

SELECT*FROMTEXTTABLE(UNESCAPE('col1,col2,col3\na,b,c')COLUMNScol2stringHEADER)x

Useoffixedwidth,returns2rows['a','b','c'],['d','e','f']:

SELECT*FROMTEXTTABLE(UNESCAPE('abc\ndef')COLUMNScol1stringwidth1,col2stringwidth1,col3stringwidt

h1)x

Useoffixedwidthwithoutarowdelimiter,returns3rows['a'],['b'],['c']:

SELECT*FROMTEXTTABLE('abc'COLUMNScol1stringwidth1NOROWDELIMITER)x

UseofESCAPEparameter,returns1row['a,','b']:

SELECT*FROMTEXTTABLE('a:,,b'COLUMNScol1string,col2stringESCAPE':')x

Asanestedtable:

SELECTx.*FROMt,TEXTTABLE(t.clobcolumnCOLUMNSfirststring,seconddateSKIP1)x

UseofSELECTORs,returns2rows['c','d','b'],['c','f','b']:

SELECT*FROMTEXTTABLE('a,b\nc,d\nc,f'SELECTOR'c'COLUMNScol1string,col2stringcol3stringSELECTOR'a'2

)x

DMLCommands

359

WHEREClauseTheWHEREclausedefinesthecriteriatolimittherecordsaffectedbySELECT,UPDATE,andDELETEstatements.

ThegeneralformoftheWHEREis:

WHERECriteria

DMLCommands

360

GROUPBYClauseTheGROUPBYclausedenotesthatrowsshouldbegroupedaccordingtothespecifiedexpressionvalues.Onerowwillbereturnedforeachgroup,afteroptionallyfilteringthoseaggregaterowsbasedonaHAVINGclause.

ThegeneralformoftheGROUPBYis:

GROUPBYexpression[,expression]*

GROUPBYROLLUP(expression[,expression]*)

SyntaxRules:

ColumnreferencesinthegroupbycannotbemadetoaliasnamesintheSELECTclause.

Expressionsusedinthegroupbymustappearintheselectclause.

ColumnreferencesandexpressionsintheSELECT/HAVING/ORDERBYclausesthatarenotusedinthegroupbyclausemustappearinaggregatefunctions.

IfanaggregatefunctionisusedintheSELECTclauseandnoGROUPBYisspecified,animplicitGROUPBYwillbeperformedwiththeentireresultsetasasinglegroup.Inthiscase,everycolumnintheSELECTmustbeanaggregatefunctionasnoothercolumnvaluewillbefixedacrosstheentiregroup.

Thegroupbycolumnsmustbeofacomparabletype.

Rollups

Justlikenormalgrouping,rollupprocessinglogicallyoccursbeforetheHAVINGclauseisprocessed.AROLLUPofexpressionswillproducethesameoutputasaregulargroupingwiththeadditionofaggregatevaluescomputedathigheraggregationlevels.ForNexpressionsintheROLLUP,aggregateswillbeprovidedover(),(expr1),(expr1,expr2),etc.upto(expr1,…exprN-1)withtheothergroupingexpressionsintheoutputasnullvalues.Forexamplewiththenormalaggregationquery

SELECTcountry,city,sum(amount)fromsalesgroupbycountry,city

returning:

country city sum(amount)

US St.Louis 10000

US Raleigh 150000

US Denver 20000

UK Birmingham 50000

UK London 75000

Therollupquery

DMLCommands

361

SELECTcountry,city,sum(amount)fromsalesgroupbyrollup(country,city)

wouldreturn:

country city sum(amount)

US St.Louis 10000

US Raleigh 150000

US Denver 20000

US <null> 180000

UK Birmingham 50000

UK London 75000

UK <null> 125000

<null> <null> 305000

Note NotallsourcessupportROLLUPsandsomeoptimizationscomparedtonormalaggregateprocessingmaybeinhibitedbytheuseofaROLLUP.

Teiid’ssupportforROLLUPismorelimitedthantheSQLspecification.InfuturereleasessupportforCUBE,groupingsets,andmorethanasingleextendedgroupingelementmaybesupported.

DMLCommands

362

HAVINGClauseTheHAVINGclauseoperatesexactlyasaWHEREclausealthoughitoperatesontheoutputofaGROUPBY.ItsupportsthesamesyntaxastheWHEREclause.

SyntaxRules:

Expressionsusedinthegroupbyclausemusteithercontainanaggregatefunction:COUNT,AVG,SUM,MIN,MAX.orbeoneofthegroupingexpressions.

DMLCommands

363

ORDERBYClauseTheORDERBYclausespecifieshowrecordsshouldbesorted.TheoptionsareASC(ascending)andDESC(descending).

Usage:

ORDERBYexpression[ASC|DESC][NULLS(FIRST|LAST)],...

SyntaxRules:

Sortcolumnsmaybespecifiedpositionallybya1-basedpositionalinteger,bySELECTclausealiasname,bySELECTclauseexpression,orbyanunrelatedexpression.

ColumnreferencesmayappearintheSELECTclauseastheexpressionforanaliasedcolumnormayreferencecolumnsfromtablesintheFROMclause.IfthecolumnreferenceisnotintheSELECTclausethequerymustnotbeasetoperation,specifySELECTDISTINCT,orcontainaGROUPBYclause.

Unrelatedexpressions,expressionsnotappearingasanaliasedexpressionintheselectclause,areallowedintheorderbyclauseofanon-setQUERY.Thecolumnsreferencedintheexpressionmustcomefromthefromclausetablereferences.Thecolumnreferencescannotbetoaliasnamesorpositional.

TheORDERBYcolumnsmustbeofacomparabletype.

IfanORDERBYisusedinaninlinevieworviewdefinitionwithoutalimitclause,itwillberemovedbytheTeiidoptimizer.

IfNULLSFIRST/LASTisspecified,thennullsareguaranteedtobesortedeitherfirstorlast.Ifthenullorderingisnotspecified,thenresultswilltypicallybesortedwithnullsaslowvalues,whichisTeiid’sinternaldefaultsortingbehavior.Howevernotallsourcesreturnresultswithnulsssortedaslowvaluesbydefault,andTeiidmayreturnresultswithdifferentnullorderings.

Warning TheuseofpositionalorderingisnolongersupportedbytheANSISQLstandardandisadeprecatedfeatureinTeiid.Itispreferabletousealiasnamesintheorderbyclause.

DMLCommands

364

LIMITClauseTheLIMITclausespecifiesalimitonthenumberofrecordsreturnedfromtheSELECTcommand.Anoptionaloffset(thenumberofrowstoskip)canbespecified.TheLIMITclausecanalsobespecifiedusingtheSQL2008OFFSET/FETCHFIRSTclauses.IfanORDERBYisalsospecified,itwillbeappliedbeforetheOFFSET/LIMITareapplied.IfanORDERBYisnotspecifiedthereisgenerallynoguaranteewhatsubsetofrowswillbereturned.

Usage:

LIMIT[offset,]limit

[OFFSEToffsetROW|ROWS][FETCHFIRST|NEXT[limit]ROW|ROWSONLY]

SyntaxRules:

Thelimit/offsetexpressionsmustbeanon-negativeintegeroraparameterreference(?).Anoffsetof0isignored.Alimitof0willreturnnorows.

ThetermsFIRST/NEXTareinterchangeableaswellasROW/ROWS.

ThelimitclausemaytakeanoptionalprecedingNON_STRICThinttoindicatethatpushoperationsshouldnotbeinhibitedeveniftheresultswillnotbeconsistentwiththelogicalapplicationofthelimit.Thehintisonlyneededonunorderedlimits,e.g."SELECT*FROMVW/*+NON_STRICT*/LIMIT2".

Examples:

LIMIT100-returnsthefirst100records(rows1-100)

LIMIT500,100-skips500recordsandreturnsthenext100records(rows501-600)

OFFSET500ROWS-skips500records

OFFSET500ROWSFETCHNEXT100ROWSONLY-skips500recordsandreturnsthenext100records(rows501-600)

FETCHFIRSTROWONLY-returnsonlythefirstrecord

DMLCommands

365

INTOClause

Warning UsageoftheINTOClauseforinsertingintoatablehasbeenbeendeprecated.AnINSERTwithaquerycommandshouldbeusedinstead.

WhentheintoclauseisspecifiedwithaSELECT,theresultsofthequeryareinsertedintothespecifiedtable.Thisisoftenusedtoinsertrecordsintoatemporarytable.TheINTOclauseimmediatelyprecedestheFROMclause.

Usage:

INTOtableFROM...

SyntaxRules:

TheINTOclauseislogicallyappliedlastinprocessing,aftertheORDERBYandLIMITclauses.

Teiid’ssupportforSELECTINTOissimilartoMSSQLServer.ThetargetoftheINTOclauseisatablewheretheresultoftherestselectcommandwillbeinserted.SELECTINTOshouldnotbeusedUNIONquery.

DMLCommands

366

OPTIONClauseTheOPTIONkeyworddenotesoptionstheusercanpassinwiththecommand.TheseoptionsareTeiidspecificandnotcoveredbyanySQLspecification.

Usage:

OPTIONoption(,option)*

Supportedoptions:

MAKEDEPtable(,table)*-specifiessourcetablesthatshouldbemadedependentinthejoin

MAKEINDtable(,table)*-specifiessourcetablesthatshouldbemadedependentinthejoin

MAKENOTDEPtable(,table)*-preventsadependentjoinfrombeingused

NOCACHE[table(,table)*]-preventscachefrombeingusedforalltablesorforthegiventables

Examples:

OPTIONMAKEDEPtable1

OPTIONNOCACHE

AlltablesspecifiedintheOPTIONclauseshouldbefullyqualified,howeverthenamemaymatcheitheranaliasnameorthefullyqualifiedname.

Themakedepandmakeindhintscantakeoptionalargumentstocontrolthedependentjoin.Theextendedhintformis:

MAKEDEPtbl([max:val][[no]join])

tbl(JOIN)meansthattheentirejoinshouldbepushed

tbl(NOJOIN)meansthattheentirejoinshouldnotbepushed

tbl(MAX:val)meaningthatthedependentjoinshouldonlybeperformediftherearelessthanthemaxnumberofvaluesfromtheindependentside.

Tip PreviousversionsofTeiidacceptedthePLANONLY,DEBUG,andSHOWPLANoptionarguments.ThesearenolongeracceptedintheOPTIONclause.PleaseseetheClientDevelopersGuideforreplacementstothoseoptions.

NoteMAKEDEPandMAKENOTDEPhintsmaytaketablenamesintheformof@view1.view2…table.Forexamplewithaninlineview"select*from(select*fromtbl1,tbl2wheretbl1.c1=tbl2.c2)[email protected]"thehintwillnowbeunderstoodasapplyingunderthev1view.

DMLCommands

367

DDLCommandsTeiidsupportsasubsetofDDLatruntimetocreate/droptemporarytablesandtomanipulateprocedureandviewdefinitions.Itisnotcurrentlypossibletoarbitrarilydrop/createnon-temporarymetadataentries.SeeDDLMetadataforDDLusedwithinaVDBtodefineschemas.

Note AMetadataRepositorymustbeconfiguredtomakeanon-temporarymetadataupdatepersistent.SeetheDevelopersGuideRuntimeMetadataUpdatessectionformore.

DDLCommands

368

TempTablesTeiidsupportscreatingtemporary,or"temp",tables.Temptablesaredynamicallycreated,butaretreatedasanyotherphysicaltable.

LocalTemporaryTables

LocaltemporarytablescanbedefinedimplicitlybyreferencingtheminaINSERTstatementorexplicitlywithaCREATETABLEstatement.Implicitlycreatedtemptablesmusthaveanamethatstartswith`#'.

Creationsyntax:

Explicit:

CREATELOCALTEMPORARYTABLEname(columntype[NOTNULL],...[PRIMARYKEY(column,...)])[ONCOMMITPRESERVE

ROWS]

UsetheSERIALdatatypetospecifyaNOTNULLandauto-incrementingINTEGERcolumn.ThestartingvalueofaSERIALcolumnis1.

Implicit:

INSERTINTO#name(column,...)VALUES(value,...)

If#xdoesn’texist,itwillbedefinedusingthegivencolumnnamesandtypesfromthevalueexpressions.

Implicit:

INSERTINTO#name[(column,...)]selectc1,c2fromt

If#xdoesn’texist,itwillbedefinedusingthetargetcolumnnames(innotsupplied,thecolumnnameswillmatchthederivedcolumnnamesfromthequery),andthetypesfromthequeryderivedcolumns.

Note

Teiid’sinterpretationoflocalisdifferentthantheSQLspecificationandotherdatabasevendors.Localmeansthatthescopeoftemptablewillbeeithertothesessionortheblockofavirtualprocedurethatcreatesit.Uponexitingtheblockortheterminationofthesessionthetableisdropped.Sessionandanyothertemporarytablescreatedincallingproceduresarenotvisibletocalledprocedures.Ifatemporarytableofthesamenameiscreatedinacalledprocedureanewinstanceiscreated.

Dropsyntax:

DROPTABLEname

Thefollowingexampleisaseriesofstatementsthatloadsatemporarytablewithdatafrom2sources,andwithamanuallyinsertedrecord,andthenusesthattemptableinasubsequentquery.

...

CREATELOCALTEMPORARYTABLETEMP(ainteger,binteger,cinteger);

SELECT*INTOtempFROMSrc1;SELECT*INTOtempFROMSrc2;

INSERTINTOtempVALUES(1,2,3);

SELECTa,b,cFROMSrc3,tempWHERESrc3.a=temp.b;

...

DDLCommands

369

SeeVirtualProceduresformoreonlocaltemporarytableusage.

GlobalTemporaryTables

GlobaltemporarytablesarecreatedinTeiidDesignerorviathemetadatasuppliedtoTeiidatdeploytime.Unlikelocaltemporarytables,theycannotbecreatedatruntime.Aglobaltemporarytablesshareacommondefinitionviaaschemaentry,buteachsessionhasanewinstanceofthetemporarytablecreateduponit’sfirstuse.Thetableisthendroppedwhenthesessionends.Thereisnoexplicitdropsupport.Acommonuseforaglobaltemporarytableistopassresultsintoandoutofprocedures.

Creationsyntax:

CREATEGLOBALTEMPORARYTABLEname(columntype[NOTNULL],...[PRIMARYKEY(column,...)])OPTIONS(UPDATABLE

'true')

IftheSERIALdatatypeisused,theneachsession’sinstanceoftheglobaltemporarytablewilluseit’sownsequence.

SeetheCREATETABLEDDLstatementforallsyntaxoptions.

CurrentlyUPDATABLEmustbeexplicitlyspecifiedforthetemporarytabletobeupdated.

GlobalandLocalTemporaryTableFeaturesPrimaryKeySupport:

Allkeycolumnsmustbecomparable.

Useofaprimarykeycreatesaclusteredindexthatsupportssearchimprovementsforcomparison,in,like,andorderby.

Nullisanallowableprimarykeyvalue,buttheremustbeonly1rowthathasanallnullkey.

TransactionSupport:

TemptablessupportaREAD_UNCOMMITEDtransactionisolationlevel.Therearenolockingmechanismsavailabletosupporthigherisolationlevelsandtheresultofarollbackmaybeinconsistentacrossmultipletransactions.Ifconcurrenttransactionsarenotassociatedwiththesamelocaltemporarytableorsession,thenthetransactionisolationleveliseffectivelySERIALIZABLE.Ifyouwantfullconsistencywithlocaltemporarytables,thenonlyuseaconnectionwith1transactionatatime.Thismodeofoperationisensuredbyconnectionpoolingthattracksconnectionsbytransaction.

Limitations:

WiththeCREATETABLEsyntaxonlybasictabledefinition(columnname,type,andnullableinformation)andanoptionalprimarykeyaresupported.Forglobaltemporarytablesadditionalmetadatainthecreatestatementiseffectivelyignoredwhencreatingthetemporarytableinstance-butmaystillbeutilizedbyplanningsimilartoanyothertableentry.

SimilartoPostgreSQL,TeiiddefaultstoONCOMMITPRESERVEROWS.NootherONCOMMITactionissupportedatthistime.

The"dropbehavior"optionisnotsupportedinthedropstatement.

Temptablesarenotfail-oversafe.

Non-inlinedlobvalues(xml,clob,blob)aretrackedbyreferenceratherthanbyvalueinatemporarytable.Lobvaluesfromexternalsourcesthatareinsertedinatemporarytablemaybecomeunreadablewhentheassociatedstatementorconnectionisclosed.

DDLCommands

370

ForeignTemporaryTables

UnlikeTeiidlocalorglobaltemporarytables,aforeigntemporarytableisareferencetoasourcetablethatiscreatedatruntimeratherthanduringthemetadataload.

Aforeigntemporarytablerequiresexplicitcreationsyntax:

CREATEFOREIGNTEMPORARYTABLEname...ONschema

WherethetablecreationbodysyntaxisthesameasastandardCREATEFOREIGNTABLEDDLstatement.Ingeneral,usageofDDLOPTIONclausesmayberequiredtoproperlyaccessthesourcetable,includingsettingthenameinsource,updatability,nativetypes,etc.

Theschemanamemustspecifyanexistingschema/modelintheVDB.Thetablewillbeaccessedasifitisonthatsource,howeverwithinTeiidthetemporarytablewillstillbescopedthesameasanon-foreigntemporarytable.ThismeansthattheforeigntemporarytablewillnotbelongtoaTeiidschemaandwillbescopedtothesessionorprocedureblockwherecreated.

TheDROPsyntaxforaforeigntemporarytableisthesameasforanon-foreigntemporarytable.

Note NeitheraCREATEnoracorrespondingDROPofaforeigntemporarytableissueapushdowncommand,ratherthismechanismsimplyexposesasourcetableforusewithinTeiidonatemporarybasis.

TherearetwousagescenariosforaFOREIGNTEMPORARYTABLE.Thefirstistodynamicallyaccessadditionaltablesonthesource.TheotheristoreplacetheusageofaTeiidlocaltemporarytableforperformancereasons.Theusagepatternforthelattercasewouldlooklike:

//-createthesourcetable

source.native("CREATEGLOBALTEMPORARYTABLEnameIFNOTEXISTS...ONCOMMITDELETEROWS");

//-bringthetableintoTeiid

CREATEFOREIGNTEMPORARYTABLEname...OPTIONS(UPDATABLEtrue)

//-usethetable

...

//-forgetthetable

DROPTABLEname

NotetheusageofthenativeproceduretopasssourcespecificCREATEddltothesource.TeiiddoesnotcurrentlyattempttopushdownasourcecreationofatemporarytablebasedupontheCREATEstatement.Someothermechanism,suchasthenativeprocedureshownabove,mustbeusedtofirstcreatethetable.Alsonotethetableisexplicitlymarkedasupdatable,sinceDDLdefinedtablesarenotupdatablebydefault.

Thesource’shandlingoftemporarytablesmustalsobeunderstoodtomakethisworkasintended.SourcesthatusethesameGLOBALtabledefinitionforallsessionswhilescopingthedatatobesessionspecific(suchasOracle)orsourcesthatsupportsessionscopedtemporarytables(suchasPostgreSQL)willworkifaccessedunderatransaction.Atransactionisnecessarybecause:

thesourceoncommitbehavior(mostlikelyDELETEROWSorDROP)willensureclean-up.KeepinmindthataTeiiddropdoesnotissueasourcecommandandisnotguaranteedtooccur(insomeexceptioncases,lossofdbconnectivity,hardshutdown,etc.).

thesourcepoolwhenusingtrackconnectionsbytransactionwillensurethatmultipleusesofthatsourcebyTeiidwillusethesameconnection/sessionandthusthesametemporarytableanddata.

Tip SinceTeiiddoesnotyetsupporttheONCOMMITclauseit’simportanttoconsiderthatthesourcetableONCOMMITbehaviorwilllikelybedifferentthatthedefault,PRESERVEROWS,forTeiidlocaltemporarytables.

DDLCommands

371

DDLCommands

372

AlterViewUsage:

ALTERVIEWnameASqueryExpression

SyntaxRules:

Thealterqueryexpressionmaybeprefixedwithacachehintformaterializedviewdefinitions.Thehintwilltakeeffectthenexttimethematerializedviewtableisloaded.

DDLCommands

373

AlterProcedureUsage:

ALTERPROCEDUREnameASblock

SyntaxRules:

ThealterblockshouldnotincludeCREATEVIRTUALPROCEDURE

Thealterblockmaybeprefixedwithacachehintforcachedprocedures.

DDLCommands

374

AlterTriggerUsage:

ALTERTRIGGERONnameINSTEADOFINSERT|UPDATE|DELETE(ASFOREACHROWblock)|(ENABLED|DISABLED)

SyntaxRules:

Thetarget,name,mustbeanupdatableview.

Triggersarenotyettrueschemaobjects.Theyarescopedonlytotheirviewandhavenoname.

AnUpdateProcedures(Triggers)mustalreadyexistforthegiventriggerevent.

Note IfthedefaultinherentupdateischoseninTeiidDesigner,anySQLassociatedwithupdate(showninagreyedouttextbox)isnotpartoftheVDBandcannotbeenabledwithanaltertriggerstatement.

DDLCommands

375

XMLSELECTCommandComplexXMLdocumentscanbedynamicallyconstructedbyTeiidusingXMLDocumentModels.Adocumentmodelisgenerallycreatedfromaschema.ThedocumentmodelisboundtorelevantSQLstatementsthroughmappingclasses.SeetheDesignerguideformoreoncreatingdocumentmodels.

XMLdocumentsmayalsocreatedviaXQuerywiththeXMLQueryfunctionorwithvariousotherSQL/XMLfunctions.

QueryingXMLdocumentsissimilartoqueryingrelationaltables.AnidiomaticSQLvariantwithspecialscalarfunctionsgivescontroloverwhichpartsofagivendocumenttoreturn.

XMLSELECTCommand

376

QueryStructureAvalidXMLSELECTCommandagainstadocumentmodelisoftheformSELECT…FROM…WHERE…ORDERBY….TheuseofanyotherSELECTcommandclauseisnotallowed.

ThefullyqualifiednameforanXMLelementis:

"model"."documentname".[pathtoelement]."elementname"

.

Thefullyqualifiednameforanattributeis:

"model"."documentname".[pathtoelement]."elementname".[@]"attributename"

Partiallyqualifiednamesforelementsandattributescanbeusedaslongasthepartialnameisunique.

FROMClause

Specifiesthedocumenttogenerate.Documentnamesresembleothervirtualgroups-"model"."documentname".

SyntaxRules:

Thefrommayonlycontainoneunaryclausespecifyingthedesireddocument.

SELECTClause

TheselectclausedetermineswhichpartsoftheXMLdocumentaregeneratedforoutput.

ExampleSyntax:

select*frommodel.doc

selectmodel.doc.root.parent.element.*frommodel.doc

selectelement,[email protected]

SyntaxRules:

SELECT*andSELECT"xml"areequivalentandspecifythateveryelementandattributeofthedocumentshouldbeoutput.

TheSELECTclauseofanXMLQuerymayonlycontain*,"xml",orelementandattributereferencesfromthespecifieddocument.Anyotherexpressionsarenotallowed.

IftheSELECTclausecontainsanelementorattributereference(otherthan*or"xml")thenonlythespecifiedelements,attributes,andtheirancestorelementswillbeinthegenerateddocument.

element.*specifiesthattheelement,it’sattribute,andallchildcontentshouldbeoutput.

WHEREClause

XMLSELECTCommand

377

Thewhereclausespecifieshowtofiltercontentfromthegenerateddocumentbaseduponvaluescontainedintheunderlyingmappingclasses.MostpredicatesarevalidinanXMLSELECTCommand,howevercombiningvaluereferencesfromdifferentpartsofthedocumentmaynotalwaysbeallowed.

Criteriaislogicallyappliedtoacontextwhichisdirectlyrelatedtoamappingclass.Startingwiththerootmappingclass,thereisarootcontextthatdescribesallofthetoplevelrepeatedelementsthatwillbeintheoutputdocument.Criteriaappliedtotherootoranyothercontextwillchangetherelatedmappingclassquerytoapplytheaffectsofthecriteria,whichcanincludecheckingvaluesfromanyofthedescendantmappingclasses.

ExampleSyntax:

selectelement,[email protected].@attribute=1

selectelement,[email protected](element1,element1.@attribute)=1

SyntaxRules:

Eachcriteriaconjunctmustrefertoasinglecontextandcanbecriteriathatappliestoamappingclass,containarowlimitfunction,orcontainrowlimitexceptionfunction.

Criteriathatappliestoamappingclassisassociatedtothatmappingclassviathecontextfunction.Theabsenceofacontextfunctionimpliesthecriteriaappliestotherootcontext.

Atagivencontextthecriteriacanspanmultiplemappingclassesprovidedthatallmappingclassesinvolvedareeitherparentsofthecontext,thecontextitself,oradescendantofthecontext.

NoteSiblingRootMappingClasses-Impliedrootcontextusercriteriaagainstadocumentmodelwithsiblingrootmappingclassesisnotgenerallysemanticallycorrect.Itisappliedasifeachoftheconjunctsisappliedtoonlyasinglerootmappingclass.Thisbehavioristhesameaspriorreleasesbutmaybefixedinafuturerelease.

XMLSELECTCommandSpecificFunctions

XMLSELECTCommandfunctionsareresemblescalarfunctions,butactashintsintheWHEREclause.ThesefunctionsareonlyvalidinanXMLSELECTCommand.

ContextFunction

CONTEXT(arg1,arg2)

Selectthecontextforthecontainingconjunct.

SyntaxRules:

Contextfunctionsapplytothewholeconjunct.

Thefirstargumentmustbeanelementorattributereferencefromthemappingclasswhosecontextthecriteriaconjunctwillapplyto.

Thesecondparameteristhereturnvalueforthefunction.

RowlimitFunction

ROWLIMIT(arg)

XMLSELECTCommand

378

Limitstherowsprocessedforthegivencontext.

SyntaxRules:

Thefirstargumentmustbeanelementorattributereferencefromthemappingclasswhosecontexttherowlimitapplies.

Therowlimitfunctionmustbeusedinequalitycomparisoncriteriawiththerighthandexpressionequaltoanpositiveintegernumberorrowstolimit.

Onlyonerowlimitorrowlimitexceptionmayapplytoagivencontext.

RowlimitexceptionFunction

Limitstherowsprocessedforthegivencontextandthrowsanexceptionifthegivennumberofrowsisexceeded.

ROWLIMITEXCEPTION(arg)

SyntaxRules:

Thefirstargumentmustbeanelementorattributereferencefromthemappingclasswhosecontexttherowlimitexceptionapplies.

Therowlimitexceptionfunctionmustbeusedinequalitycomparisoncriteriawiththerighthandexpressionequaltoanpositiveintegernumberorrowstolimit.

Onlyonerowlimitorrowlimitexceptionmayapplytoagivencontext.

ORDERBYClauseTheXMLSELECTCommandORDERBYClausespecifiesorderingforthereferencedmappingclassqueries.

SyntaxRules:

Eachorderbyitemmustbeanelementorattributereferencetiedaoutputvaluefromamappingclass.

Theorderortheorderbyitemsistherelativeordertheywillbeappliedtotheirrespectivemappingclasses.

XMLSELECTCommand

379

DocumentGenerationDocumentgenerationstartswiththerootmappingclassandproceedsiterativelyandhierarchicallyoverallofthechildmappingclasses.Thiscanresultinalargenumberofqueryexecutions.Forexampleifadocumenthasarootmappingclasswith3childmappingclasses.Thenforeachrowselectedbytherootmappingclassaftertheapplicationoftherootcontextcriteria,eachofthechildmappingclassesquerieswillalsobeexecuted.

Note

DocumentCorrectness-BydefaultXMLgeneratedbyXMLdocumentsarenotcheckedforcorrectnessvs.therelevantschema.Itispossiblethatthemappingclassqueries,theusageofspecificSELECTorWHEREclausevalueswillgeneratedadocumentthatisnotvalidwithrespecttotheschema.SeeDocumentValidationonhowtoensurecorrectness.

Siblingorcousinelementsdefinedbythesamemappingclassthatdonothaveacommonparentinthatmappingclasswillbetreatedasindependentmappingclassesduringplanningandexecution.Thisallowsforamoredocumentcentricapproachtoapplyingcriteriaandorderbystomappingclasses.

DocumentValidationTheexecutionpropertyXMLValidationshouldbesetto'true'toindicatethatgenerateddocumentsshouldbecheckedforcorrectness.Correctnesscheckingwillnotpreventinvaliddocumentsfrombeinggenerated,sincecorrectnessischeckedaftergenerationandnotduring.

XMLSELECTCommand

380

Procedures

Procedures

381

ProcedureLanguageTeiidsupportsaprocedurallanguagefordefiningVirtualProcedures.Thesearesimilartostoredproceduresinrelationaldatabasemanagementsystems.YoucanusethislanguagetodefinethetransformationlogicfordecomposingINSERT,UPDATE,andDELETEcommandsagainstviews;theseareknownasUpdateProcedures(Triggers).

TableofContentsCommandStatementDynamicSQLCommandDeclarationStatementAssignmentStatementSpecialVariablesCompoundStatement

ExceptionHandlingIfStatementLoopStatementWhileStatementContinueStatementBreakStatementLeaveStatementReturnStatementErrorStatementRaiseStatementExceptionExpression

CommandStatement

AcommandstatementexecutesaDMLCommand,suchasSELECT,INSERT,UPDATE,DELETE,EXECUTE,oraDDLstatement,dynamicSQL,etc.

Usage:

command[(WITH|WITHOUT)RETURN];

ExampleCommandStatements

SELECT*FROMMySchema.MyTableWHEREColA>100WITHOUTRETURN;

INSERTINTOMySchema.MyTable(ColA,ColB)VALUES(50,'hi');

SyntaxRules:

EXECUTEcommandstatementsmayaccessIN/OUT,OUT,andRETURNparameters.Toaccessthereturnvaluethestatementwillhavetheformvar=EXECproc….ToaccessOUTorIN/OUTvaluesnamedparametersyntaxmustbeused.Forexample,EXECproc(in_param⇒'1',out_param⇒var)willassignthevalueoftheoutparametertothevariablevar.Itisexpectedthatthedatatypeofparameterwillbeimplicitlyconvertabletothedatatypeofthevariable.

TheRETURNclausedeterminesiftheresultofthecommandisreturnablefromtheprocedure.WITHRETURNisthedefault.Ifthecommanddoesnotreturnaresultsetortheproceduredoesnotreturnaresultset,theRETURNclauseisignored.IfWITHRETURNisspecified,theresultsetofthecommandmustmatchtheexpectedresultsetoftheprocedure.OnlythelastsuccessfullyexecutedstatementexecutedWITHRETURNwillbereturnedastheprocedureresultset.Iftherearenoreturnableresultsetsandtheproceduredeclaresthataresultsetwillbereturned,thenanemptyresultsetisreturned.

Procedures

382

DynamicSQLCommand

DynamicSQLallowsfortheexecutionofanarbitrarySQLcommandinavirtualprocedure.DynamicSQLisusefulinsituationswheretheexactcommandformisnotknownpriortoexecution.

Usage:

EXECUTEIMMEDIATE<expression>AS<variable><type>[,<variable><type>]*[INTO<variable>][USING<variable>=

<expression>[,<variable>=<expression>]*][UPDATE<literal>]

SyntaxRules:

The"AS"clauseisusedtodefinetheprojectedsymbolsnamesandtypesreturnedbytheexecutedSQLstring.The"AS"clausesymbolswillbematchedpositionallywiththesymbolsreturnedbytheexecutedSQLstring.Non-convertibletypesortoofewcolumnsreturnedbytheexecutedSQLstringwillresultinanerror.

The"INTO"clausewillprojectthedynamicSQLintothespecifiedtemptable.Withthe"INTO"clausespecified,thedynamiccommandwillactuallyexecuteastatementthatbehaveslikeanINSERTwithaQUERYEXPRESSION.IfthedynamicSQLcommandcreatesatemporarytablewiththe"INTO"clause,thenthe"AS"clauseisrequiredtodefinethetable’smetadata.

The"USING"clauseallowsthedynamicSQLstringtocontainvariablereferencesthatareboundatruntimetospecifiedvalues.ThisallowsforsomeindependenceoftheSQLstringfromthesurroundingprocedurevariablenamesandinputnames.Inthedynamiccommand"USING"clause,eachvariableisspecifiedbyshortnameonly.HoweverinthedynamicSQLthe"USING"variablemustbefullyqualifiedto"DVAR.".The"USING"clauseisonlyforvaluesthatwillbeusedinthedynamicSQLaslegalexpressions.Itisnotpossibletousethe"USING"clausetoreplacetablenames,keywords,etc.Thismakesusingsymbolsequivalentinpowertonormalbind(?)expressionsinpreparedstatements.The"USING"clausehelpsreducetheamountofstringmanipulationneeded.IfareferenceismadetoaUSINGsymbolintheSQLstringthatisnotboundtoavalueinthe"USING"clause,anexceptionwilloccur.

The"UPDATE"clauseisusedtospecifytheUpdatingModelCount.Acceptedvaluesare(0,1,*).0isthedefaultvalueiftheclauseisnotspecified.

ExampleDynamicSQL

...

/*Typicallycomplexcriteriawouldbeformedbaseduponinputstotheprocedure.

Inthissimpleexamplethecriteriaisreferencestheusingclausetoisolate

theSQLstringfromreferencingavaluefromtheproceduredirectly*/

DECLAREstringcriteria='Customer.Accounts.Last=DVARS.LastName';

/*NowwecreatethedesiredSQLstring*/

DECLAREstringsql_string='SELECTID,First||""||LastASName,BirthdateFROMCustomer.AccountsWHERE'

||criteria;

/*TheexecutionoftheSQLstringwillcreatethe#temptablewiththecolumns(ID,Name,Birthdate).

NotethatwealsohavetheUSINGclausetobindavaluetoLastName,whichisreferencedinthecriteria.*/

EXECUTEIMMEDIATEsql_stringASIDinteger,Namestring,BirthdatedateINTO#tempUSINGLastName='somename';

/*ThetemptablecannowbeusedwiththevaluesfromtheDynamicSQL*/

loopon(SELCTIDfrom#temp)asmyCursor

...

HereisanexampleshowingamorecomplexapproachtobuildingcriteriaforthedynamicSQLstring.Inshort,thevirtualprocedureAccountAccess.GetAccountshasinputsID,LastName,andbday.IfavalueisspecifiedforIDitwillbetheonlyvalueusedinthedynamicSQLcriteria.OtherwiseifavalueisspecifiedforLastNametheprocedurewilldetectifthevalueisasearchstring.IfbdayisspecifiedinadditiontoLastName,itwillbeusedtoformcompoundcriteriawithLastName.

Procedures

383

ExampleDynamicSQLwithUSINGclauseanddynamicallybuiltcriteriastring

...

DECLAREstringcrit=null;

IF(AccountAccess.GetAccounts.IDISNOTNULL)

crit='(Customer.Accounts.ID=DVARS.ID)';

ELSEIF(AccountAccess.GetAccounts.LastNameISNOTNULL)

BEGIN

IF(AccountAccess.GetAccounts.LastName=='%')

ERROR"Lastnamecannotbe%";

ELSEIF(LOCATE('%',AccountAccess.GetAccounts.LastName)<0)

crit='(Customer.Accounts.Last=DVARS.LastName)';

ELSE

crit='(Customer.Accounts.LastLIKEDVARS.LastName)';

IF(AccountAccess.GetAccounts.bdayISNOTNULL)

crit='('||crit||'and(Customer.Accounts.Birthdate=DVARS.BirthDay))';

END

ELSE

ERROR"IDorLastNamemustbespecified.";

EXECUTEIMMEDIATE'SELECTID,First||""||LastASName,BirthdateFROMCustomer.AccountsWHERE'||critUS

INGID=AccountAccess.GetAccounts.ID,LastName=AccountAccess.GetAccounts.LastName,BirthDay=AccountAccess.GetAcc

ounts.Bday;

...

KnownLimitationsandWork-Arounds

TheuseofdynamicSQLcommandresultsinanassignmentstatementrequirestheuseofatemptable.

ExampleAssignment

EXECUTEIMMEDIATE<expression>ASxstringINTO#temp;

DECLAREstringVARIABLES.RESULT=(SELECTxFROM#temp);

Theconstructionofappropriatecriteriawillbecumbersomeifpartsofthecriteriaarenotpresent.Forexampleif"criteria"werealreadyNULL,thenthefollowingexampleresultsin"criteria"remainingNULL.

ExampleDangerousNULLhandling

...

criteria='('||criteria||'and(Customer.Accounts.Birthdate=DVARS.BirthDay))';

ThepreferredapproachisfortheusertoensurethecriteriaisnotNULLprioritsusage.Ifthisisnotpossible,agoodapproachistospecifyadefaultasshowninthefollowingexample.

ExampleNULLhandling

...

criteria='('||nvl(criteria,'(1=1)')||'and(Customer.Accounts.Birthdate=DVARS.BirthDay))';

IfthedynamicSQLisanUPDATE,DELETE,orINSERTcommand,therowcountofthestatementcanbeobtainedfromtherowcountvariable.

ExamplewithASandINTOclauses

/*Executeanupdate*/

EXECUTEIMMEDIATE<expression>;

Unlessusedinotherpartsoftheprocedure,tablesinthedynamiccommandwillnotbeseenassourcesintheDesigner.

Whenusingthe"AS"clauseonlythetypeinformationwillbeavailabletotheDesigner.ResultSetcolumnsgeneratedfromthe"AS"clausethenwillhaveadefaultsetofpropertiesforlength,precision,etc.

Procedures

384

DeclarationStatement

Adeclarationstatementdeclaresavariableanditstype.Afteryoudeclareavariable,youcanuseitinthatblockwithintheprocedureandanysub-blocks.Avariableisinitializedtonullbydefault,butcanalsobeassignedthevalueofanexpressionaspartofthedeclarationstatement.

Usage:

DECLARE<type>[VARIABLES.]<name>[=<expression>];

ExampleSyntax

declareintegerx;

declarestringVARIABLES.myvar='value';

SyntaxRules:

Youcannotredeclareavariablewithaduplicatenameinasub-block

TheVARIABLESgroupisalwaysimpliedevenifitisnotspecified.

TheassignmentvaluefollowsthesamerulesasforanAssignmentStatement.

Inadditiontothestandardtypes,youmayspecifyEXCEPTIONifdeclaringanexceptionvariable.

AssignmentStatement

Anassignmentstatementassignsavaluetoavariablebyevaluatinganexpression.

Usage:

<variablereference>=<expression>;

ExampleSyntax

myString='Thankyou';

VARIABLES.x=(SELECTColumn1FROMMySchema.MyTable);

Validvariablesforassignmentincludeanyinscopevariablethathasbeendeclaredwithadeclarationstatement,ortheprocedurein_outandoutparameters.In_outandoutparameterscanbeaccessedastheirfullyqualifiedname.

ExampleOutParameter

CREATEVIRTUALPROCEDUREproc(OUTSTRINGx,INOUTSTRINGy)AS

BEGIN

proc.x='somevalue'||proc.y;

y='somenewvalue';

END

SpecialVariables

VARIABLES.ROWCOUNTintegervariablewillcontainthenumbersofrowsaffectedbythelastinsert/update/deletecommandstatementexecuted.InsertsthatareprocessedbydynamicsqlwithanintoclausewillalsoupdatetheROWCOUNT.

Procedures

385

Usage:

SampleUsage

...

UPDATEFOOSETX=1WHEREY=2;

DECLAREINTEGERUPDATED=VARIABLES.ROWCOUNT;

...

Non-updatecommandstatements(WITHorWITHOUTRETURN)willresettheROWCOUNTto0.

Note ToensureyouaregettingtheappropriateROWCOUNTvalue,savetheROWCOUNTtoavariableimmediatelyafterthecommandstatement.

CompoundStatement

Acompoundstatementorblocklogicallygroupsaseriesofstatements.Temporarytablesandvariablescreatedinacompoundstatementarelocalonlytothatblockaredestroyedwhenexitingtheblock.

Usage:

[label:]BEGIN[[NOT]ATOMIC]

statement*

[EXCEPTIONex

statement*

]

END

Note WhenablockisexpectedbyaIF,LOOP,WHILE,etc.asinglestatementisalsoacceptedbytheparser.EventhoughtheblockBEGIN/ENDarenotexpected,thestatementwillexecuteasifwrappedinaBEGIN/ENDpair.

SyntaxRules

IFNOTATOMICornoATOMICclauseisspecified,theblockwillbeexecutednon-atomically.

IFATOMICtheblockmustexecuteatomically.Ifatransactionisalreadyassociatedwiththethread,noadditionalactionwillbetaken-savepointsand/orsub-transactionsarenotcurrentlyused.Ifthehigherleveltransactionisusedandtheblockdoesnotcomplete-regardlessofthepresenceofexceptionhandlingthetransactionwillbemarkedasrollbackonly.Otherwiseatransactionwillbeassociatedwiththeexecutionoftheblock.Uponsuccessfulcompletionoftheblockthetransactionwillbecommitted.

Thelabelmustnotbethesameasanyotherlabelusedinstatementscontainingthisone.

Variableassignmentsandtheimplicitresultcursorareunaffectedbyrollbacks.Ifablockdoesnotcompletesuccessfullyitsassignmentswillstilltakeaffect.

ExceptionHandling

IftheEXCEPTIONclauseisusedwithinacompoundstatement,anyprocessingexceptionemittedfromstatementswillbecaughtwiththeflowofexecutiontransferringtoEXCEPTIONstatements.Anyblockleveltransactionstartedbythisblockwillcommitiftheexceptionhandlersuccessfullycompletes.Ifanotherexceptionortheoriginalexceptionisemittedfromtheexceptionhandlerthetransactionwillrollback.AnytemporarytablesorvariablesspecifictotheBLOCKwillnotbeavailabletotheexceptionhandlerstatements.

Note Onlyprocessingexceptions,whicharetypicallycausedbyerrorsoriginatingatthesourcesorwithfunctionexecution,arecaught.Alow-levelinternalTeiiderrororJavaRuntimeExceptionwillnotbecaught.

Procedures

386

ToaidintheprocessingofacaughtexceptiontheEXCEPTIONclausespecifiesagroupnamethatexposesthesignificantfieldsoftheexception.Theexceptiongroupwillcontain:

Variable Type Description

STATE string TheSQLState

ERRORCODE integer

Theerrororvendorcode.InthecaseofTeiidinternalexceptionsthiswillbetheintegersuffixoftheTEIIDxxxxcode

TEIIDCODE string ThefullTeiideventcode.TypicallyTEIIDxxxx.

EXCEPTION object Theexceptionbeingcaught,willbeaninstanceofTeiidSQLException

CHAIN object Thechainedexceptionorcauseofthecurrentexception

Note TeiiddoesnotyetfullycomplywiththeANSISQLspecificationonSQLStateusage.ForTeiiderrorswithoutanunderlyingSQLExceptioncause,itisbesttousetheTeiidcode.

Theexceptiongroupnamemaynotbethesameasanyhigherlevelexceptiongrouporloopcursorname.

ExampleExceptionGroupHandling

BEGIN

DECLAREEXCEPTIONe=SQLEXCEPTION'thisisbad'SQLSTATE'xxxxx';

RAISEvariables.e;

EXCEPTIONe

IF(e.state='xxxxx')

//inthistrivialexample,we'llalwayshitthisbranchandjustlogtheexception

RAISESQLWARNINGe.exception;

ELSE

RAISEe.exception;

END

IfStatement

AnIFstatementevaluatesaconditionandexecuteseitheroneoftwostatementsdependingontheresult.YoucannestIFstatementstocreatecomplexbranchinglogic.AdependentELSEstatementwillexecuteitsstatementonlyiftheIFstatementevaluatestofalse.

Usage:

IF(criteria)

block

[ELSE

block]

END

ExampleIfStatement

IF(var1='NorthAmerica')

BEGIN

...statement...

ENDELSE

Procedures

387

BEGIN

...statement...

END

ThecriteriamaybeanyvalidbooleanexpressionoranISDISTINCTFROMpredicate.ISDISTINCTFROMusesthesyntax:

rowValIS[NOT]DISTINCTFROMrowValOther

WhererowValandrowValOtherarereferencestorowvaluegroup.Thiswouldtypicallybeusedininsteadofupdatetriggersonviewstoquicklydetermineiftherowvaluesarechanging:

ExampleISDISTINCTFROMIfStatement

IF("new"ISDISTINCTFROM"old")

BEGIN

...statement...

END

ISDISTINCTFROMconsidersnullvaluesequivalentandneverproducesanUNKNOWNvalue.

Tip NULLvaluesshouldbeconsideredinthecriteriaofanIFstatement.ISNULLcriteriacanbeusedtodetectthepresenceofaNULLvalue.

LoopStatement

ALOOPstatementisaniterativecontrolconstructthatisusedtocursorthrougharesultset.

Usage:

[label:]LOOPON<selectstatement>AS<cursorname>

statement

SyntaxRules


WhileStatementAWHILEstatementisaniterativecontrolconstructthatisusedtoexecuteastatementrepeatedlywheneveraspecifiedconditionismet.

Usage:

[label:]WHILE<criteria>

statement

SyntaxRules


ContinueStatement

Procedures

388

ACONTINUEstatementisusedinsideaLOOPorWHILEconstructtocontinuewiththenextloopbyskippingovertherestofthestatementsintheloop.ItmustbeusedinsideaLOOPorWHILEstatement.

Usage:

CONTINUE[label];

SyntaxRules

Ifthelabelisspecified,itmustexistonacontainingLOOPorWHILEstatement.

Ifnolabelisspecified,thestatementwillaffecttheclosestcontainingLOOPorWHILEstatement.

BreakStatementABREAKstatementisusedinsideaLOOPorWHILEconstructtobreakfromtheloop.ItmustbeusedinsideaLOOPorWHILEstatement.

Usage:

BREAK[label];

SyntaxRules

Ifthelabelisspecified,itmustexistonacontainingLOOPorWHILEstatement.

Ifnolabelisspecified,thestatementwillaffecttheclosestcontainingLOOPorWHILEstatement.

LeaveStatementALEAVEstatementisusedinsideacompound,LOOP,orWHILEconstructtoleavetothespecifiedlevel.

Usage:

LEAVElabel;

SyntaxRules

Thelabelmustexistonacontainingcompoundstatement,LOOP,orWHILEstatement.

ReturnStatement

AReturnstatementgracefullyexitstheprocedureandoptionallyreturnsavalue.

Usage:

RETURN[expression];

SyntaxRules

Ifanexpressionisspecified,theproceduremusthaveareturnparameterandthevaluemustbeimplicitlyconvertabletotheexpectedtype.

Eveniftheprocedurehasareturnvalue,itisnotrequiredtospecifyareturnvalueinaRETURNstatement.

Procedures

389

ErrorStatement

AnERRORstatementdeclaresthattheprocedurehasenteredanerrorstateandshouldabort.Thisstatementwillalsorollbackthecurrenttransaction,ifoneexists.AnyvalidexpressioncanbespecifiedaftertheERRORkeyword.

Usage:

ERRORmessage;

ExampleErrorStatement

ERROR'Invalidinputvalue:'||nvl(Acct.GetBalance.AcctID,'null');

AnERRORstatementisequivalentto:

RAISESQLEXCEPTIONmessage;

RaiseStatementARAISEstatementisusedtoraiseanexceptionorwarning.Whenraisinganexception,thisstatementwillalsorollbackthecurrenttransaction,ifoneexists.

Usage:

RAISE[SQLWARNING]exception;

Whereexceptionmaybeavariablereferencetoanexceptionoranexceptionexpression.

SyntaxRules

IfSQLWARNINGisspecified,theexceptionwillbesenttotheclientasawarningandtheprocedurewillcontinuetoexecute.

Anullwarningwillbeignored.Anullnon-warningexceptionwillstillcauseanexceptiontoberaised.

ExampleRaiseStatement

RAISESQLWARNINGSQLEXCEPTION'invalid'SQLSTATE'05000';

ExceptionExpression

Anexceptionexpressioncreatesanexceptionthatcanberaisedorusedasawarning.

Usage:

SQLEXCEPTIONmessage[SQLSTATEstate[,code]]CHAINexception

SyntaxRules

Anyofthevaluesmaybenull;

messageandstatearestringexpressionsspecifyingtheexceptionmessageandSQLstaterespectively.TeiiddoesnotyetfullycomplywiththeANSISQLspecificationonSQLstateusage,butyouareallowedtosetanySQLstateyouchoose.

Procedures

390

codeisanintegerexpressionspecifyingthevendorcode

exceptionmustbeavariablereferencetoanexceptionoranexceptionexpressionandwillbechainedtotheresultingexceptionasitsparent.

Procedures

391

VirtualProceduresVirtualproceduresaredefinedusingtheTeiidprocedurallanguage.Avirtualprocedurehaszeroormoreinput/inout/outparameters,anoptionalreturnparameter,andanoptionalresultset.VirtualproceduressupporttheabilitytoexecutequeriesandotherSQLcommands,definetemporarytables,adddatatotemporarytables,walkthroughresultsets,useloops,anduseconditionallogic.

TableofContentsVirtualProcedureDefinitionProcedureParameters

ExampleVirtualProceduresExecutingVirtualProceduresLimitations

VirtualProcedureDefinition

InDesigner:

[CREATEVIRTUALPROCEDURE]statement

InDDL:DDLMetadata#CreateProcedure/Function

Withinthebodyoftheprocedure,anyvalidstatementmaybeused.

Thereisnoexplicitcursoringorvaluereturningstatement,ratherthelastunnamedcommandstatementexecutedintheprocedurethatreturnsaresultsetwillbereturnedastheresult.Theoutputofthatstatementmustmatchtheexpectedresultsetandparametersoftheprocedure.

ProcedureParametersVirtualprocedurescantakezeroormoreIN/INOUTparametersandmayalsohaveanynumberofOUTparametersandanoptionalRETURNparameter.Eachinputhasthefollowinginformationthatisusedduringruntimeprocessing:

Name-Thenameoftheinputparameter

Datatype-Thedesign-timetypeoftheinputparameter

Defaultvalue-Thedefaultvalueiftheinputparameterisnotspecified

Nullable-NO_NULLS,NULLABLE,NULLABLE_UNKNOWN;parameterisoptionalifnullable,andisnotrequiredtobelistedwhenusingnamedparametersyntax

Youreferenceaparameterinavirtualprocedurebyusingthefully-qualifiednameoftheparam(orlessifunambiguous).Forexample,MySchema.MyProc.Param1.

ExampleofReferencinganInputParameterandAssigninganOutParameterforGetBalanceProcedure

BEGIN

MySchema.GetBalance.RetVal=UPPER(MySchema.GetBalance.AcctID);

SELECTBalanceFROMMySchema.AcctsWHEREMySchema.Accts.AccountID=MySchema.GetBalance.AcctID;

END

Procedures

392

IfanINOUTparameterisnotassignedanyvalueinaprocedureitwillremainthevalueitwasassignedforinput.AnyOUT/RETURNparameternotassignedavaluewillremaintheasthedefaultNULLvalue.TheINOUT/OUT/RETURNoutputvaluesarevalidatedagainsttheNOTNULLmetadataoftheparameter.

ExampleVirtualProcedures

ThisexampleisaLOOPthatwalksthroughacursoredtableandusesCONTINUEandBREAK.

VirtualProcedureUsingLOOP,CONTINUE,BREAK

BEGIN

DECLAREdoubletotal;

DECLAREintegertransactions;

LOOPON(SELECTamt,typeFROMCashTxnTable)AStxncursor

BEGIN

IF(txncursor.type<>'Sale')

BEGIN

CONTINUE;

ENDELSE

BEGIN

total=(total+txncursor.amt);

transactions=(transactions+1);

IF(transactions=100)

BEGIN

BREAK;

END

END

END

SELECTtotal,(total/transactions)ASavg_transaction;

END

ThisexampleisusesconditionallogictodeterminewhichoftwoSELECTstatementstoexecute.

VirtualProcedurewithConditionalSELECT

BEGIN

DECLAREstringVARIABLES.SORTDIRECTION;

VARIABLES.SORTDIRECTION=PartsVirtual.OrderedQtyProc.SORTMODE;

IF(ucase(VARIABLES.SORTDIRECTION)='ASC')

BEGIN

SELECT*FROMPartsVirtual.SupplierInfoWHEREQUANTITY>PartsVirtual.OrderedQtyProc.QTYINORDERBYPartsVi

rtual.SupplierInfo.PART_ID;

ENDELSE

BEGIN

SELECT*FROMPartsVirtual.SupplierInfoWHEREQUANTITY>PartsVirtual.OrderedQtyProc.QTYINORDERBYPartsVi

rtual.SupplierInfo.PART_IDDESC;

END

END

ExecutingVirtualProceduresYouexecuteproceduresusingtheSQLEXECUTEcommand.Iftheprocedurehasdefinedinputs,youspecifythoseinasequentiallist,orusing"name=value"syntax.Youmustusethenameoftheinputparameter,scopedbythefullprocedurenameiftheparameternameisambiguousinthecontextofothercolumnsorvariablesintheprocedure.

AvirtualprocedurecallwillreturnaresultsetjustlikeanySELECT,soyoucanusethisinmanyplacesyoucanuseaSELECT.Typicallyyou’llusethefollowingsyntax:

SELECT*FROM(EXEC...)ASx

Procedures

393

Limitations

Teiidvirtualproceduresmayonlyreturn1resultset.Ifyouneedtopassinaresultsetorpassoutmultipleresultset,thenconsiderusingglobaltemporarytables.

Procedures

394

UpdateProcedures(Triggers)Viewsareabstractionsabovephysicalsources.Theytypicallyunionorjoininformationfrommultipletables,oftenfrommultipledatasourcesorotherviews.Teiidcanperformupdateoperationsagainstviews.Updatecommands-INSERT,UPDATE,orDELETE-againstaviewrequirelogictodefinehowthetablesandviewsintegratedbytheviewareaffectedbyeachtypeofcommand.Thistransformationlogic,alsoreferredtoasatrigger,isinvokedwhenanupdatecommandisissuedagainstaview.Updateproceduresdefinethelogicforhowauser’supdatecommandagainstaviewshouldbedecomposedintotheindividualcommandstobeexecutedagainsttheunderlyingphysicalsources.SimilartoVirtualProcedures,updateprocedureshavetheabilitytoexecutequeriesorothercommands,definetemporarytables,adddatatotemporarytables,walkthroughresultsets,useloops,anduseconditionallogic.

TableofContentsUpdateProcedureProcessingForEachRowDefinitionSpecialVariables

NEWVariablesOLDVariablesCHANGINGVariables

Examples

UpdateProcedureProcessing

1. TheuserapplicationsubmitstheSQLcommandthroughoneofSOAP,JDBC,orODBC.

2. TheviewthisSQLcommandisexecutedagainstisdetected.

3. ThecorrectprocedureischosendependinguponwhetherthecommandisanINSERT,UPDATE,orDELETE.

4. Theprocedureisexecuted.TheprocedureitselfcancontainSQLcommandsofitsownwhichcanbeofdifferenttypesthanthecommandsubmittedbytheuserapplicationthatinvokedtheprocedure.

5. Commands,asdescribedintheprocedure,areissuedtotheindividualphysicaldatasourcesorotherviews.

6. Avaluerepresentingthenumberofrowschangedisreturnedtothecallingapplication.

ForEachRow

AFOREACHROWprocedurewillevaluateitsblockforeachrowoftheviewaffectedbytheupdatestatement.ForUPDATEandDELETEstatementsthiswillbeeveryrowthatpassestheWHEREcondition.ForINSERTstatementstherewillbe1newrowforeachsetofvaluesfromtheVALUESorqueryexpression.Therowsupdatedisreportedasthisnumberregardlessoftheaffectoftheunderlyingprocedurelogic.

TeiidFOREACHROWupdateproceduresfunctionlikeINSTEADOFtriggersintraditionaldatabases.Theremayonlybe1FOREACHROWprocedureforeachINSERT,UPDATE,orDELETEoperationagainstaview.FOREACHROWupdateprocedurescanalsobeusedtoemulateBEFORE/AFTEReachrowtriggerswhilestillretainingtheabilitytoperformaninherentupdate.ThisBEFORE/AFTERtriggerbehaviorwithaninherentupdatecanbeachievedbycreatinganadditionalupdatableviewoverthetargetviewwithupdateproceduresoftheform:

FOREACHROW

BEGINATOMIC

Procedures

395

--beforerowlogic

--defaultinsert/update/deleteagainstthetargetview

INSERTINTOVW(c1,c2,c3)VALUES(NEW.c1,NEW.c2,NEW.c3);

--afterrowlogic

END

DefinitionUsage:

FOREACHROW

BEGINATOMIC

...

END

TheBEGINandENDkeywordsareusedtodenoteblockboundaries.Withinthebodyoftheprocedure,anyvalidstatementmaybeused.

Tip Theuseoftheatomickeywordiscurrentlyoptionalforbackwardcompatibility,butunlikeanormalblock,thedefaultforinsteadoftriggersisatomic.

SpecialVariablesYoucanuseanumberofspecialvariableswhendefiningyourupdateprocedure.

NEWVariables

EveryattributeintheviewwhoseUPDATEandINSERTtransformationsyouaredefininghasanequivalentvariablenamedNEW.<column_name>

WhenanINSERToranUPDATEcommandisexecutedagainsttheview,thesevariablesareinitializedtothevaluesintheINSERTVALUESclauseortheUPDATESETclauserespectively.

InanUPDATEprocedure,thedefaultvalueofthesevariables,iftheyarenotsetbythecommand,istheoldvalue.InanINSERTprocedure,thedefaultvalueofthesevariablesisthedefaultvalueofthevirtualtableattributes.SeeCHANGINGVariablesfordistinguishingdefaultsfrompassedvalues.

OLDVariables

EveryattributeintheviewwhoseUPDATEandDELETEtransformationsyouaredefininghasanequivalentvariablenamedOLD.<column_name>

WhenaDELETEorUPDATEcommandisexecutedagainsttheview,thesevariablesareinitializedtothecurrentvaluesoftherowbeingdeletedorupdatedrespectively.

CHANGINGVariables

EveryattributeintheviewwhoseUPDATEandINSERTtransformationsyouaredefininghasanequivalentvariablenamedCHANGING.<column_name>

Procedures

396

WhenanINSERToranUPDATEcommandisexecutedagainsttheview,thesevariablesareinitializedtotrueorfalsedependingonwhethertheINPUTvariablewassetbythecommand.ACHANGINGvariableiscommonlyusedtodifferentiatebetweenadefaultinsertvalueandonespecifiedintheuserquery.

Forexample,foraviewwithcolumnsA,B,C:

IfUserExecutes… Then…

INSERTINTOVT(A,B)VALUES(0,1)CHANGING.A=true,CHANGING.B=true,CHANGING.C=false

UPDATEVTSETC=2CHANGING.A=false,CHANGING.B=false,CHANGING.C=true

ExamplesForexample,foraviewwithcolumnsA,B,C:

SampleDELETEProcedure

FOREACHROW

BEGIN

DELETEFROMXWHEREY=OLD.A;

DELETEFROMZWHEREY=OLD.A;//cascadethedelete

END

SampleUPDATEProcedure

FOREACHROW

BEGIN

IF(CHANGING.B)

BEGIN

UPDATEZSETY=NEW.BWHEREY=OLD.B;

END

END

Procedures

397

CommentsTeiidsupportsmulti-linecommentsenclosedwith/**/:

/*comment

comment

comment...*/

Andsinglelinecomments:

SELECT...--comment

Commentnestingissupported.

Comments

398

Datatypes

Datatypes

399

SupportedTypesTeiidsupportsacoresetofruntimetypes.Runtimetypescanbedifferentthansemantictypesdefinedintypefieldsatdesigntime.Theruntimetypecanalsobespecifiedatdesigntimeoritwillbeautomaticallychosenastheclosestbasetypetothesemantictype.

Table1.TeiidRuntimeTypes

Type Description JavaRuntimeClass JDBCType ODBCType

stringorvarchar

variablelengthcharacterstringwithamaximumlengthof4000.

java.lang.String VARCHAR VARCHAR

varbinary

variablelengthbinarystringwithanominalmaximumlengthof8192.

byte[][1] VARBINARY VARBINARY

char asingleUnicodecharacter java.lang.Character CHAR CHAR

boolean

asinglebit,orBoolean,thatcanbetrue,false,ornull(unknown)

java.lang.Boolean BIT SMALLINT

byteortinyint numeric,integraltype,signed8-bit java.lang.Byte TINYINT SMALLINT

shortorsmallint numeric,integraltype,signed16-bit java.lang.Short SMALLINT SMALLINT

integerorserial

numeric,integraltype,signed32-bit.Theserialtypealsoimpliesnotnullandhasanauto-incrementingvaluethatstartsat1.serialtypesarenotautomaticallyUNIQUE.

java.lang.Integer INTEGER INTEGER

longorbigint numeric,integraltype,signed64-bit java.lang.Long BIGINT NUMERIC

biginteger

numeric,integraltype,arbitraryprecisionofupto1000digits

java.math.BigInteger NUMERIC NUMERIC

floatorreal

numeric,floatingpointtype,32-bitIEEE754floating-pointnumbers

java.lang.Float REAL FLOAT

SupportedTypes

400

doublenumeric,floatingpointtype,64-bitIEEE754floating-pointnumbers

java.lang.Double DOUBLE DOUBLE

bigdecimalordecimal

numeric,floatingpointtype,arbitraryprecisionofupto1000digits.

java.math.BigDecimal NUMERIC NUMERIC

date

datetime,representingasingleday(year,month,day)

java.sql.Date DATE DATE

time

datetime,representingasingletime(hours,minutes,seconds,milliseconds)

java.sql.Time TIME TIME

timestamp

datetime,representingasingledateandtime(year,month,day,hours,minutes,seconds,milliseconds,nanoseconds)

java.sql.Timestamp TIMESTAMP TIMESTAMP

object

anyarbitraryJavaobject,mustimplementjava.lang.Serializable

Any JAVA_OBJECT VARCHAR

blobbinarylargeobject,representingastreamofbytes

java.sql.Blob[2] BLOB VARCHAR

clobcharacterlargeobject,representingastreamofcharacters

java.sql.Clob[3] CLOB VARCHAR

xml XMLdocument java.sql.SQLXML[4] JAVA_OBJECT VARCHAR

geometry GeospatialObject java.sql.Blob[5] BLOB BLOB

Note Evenifatypeisdeclaredwithalength,precision,orscaleargument,thoserestrictionsareeffectivelyignoredbytheruntimesystem.

ReferenceLink

1. Theruntimetypeisorg.teiid.core.types.BinaryType.TranslatorswillneedtoexplicitlyhandleBinaryTypevalues.UDFswillinsteadhaveabyte[]valuepassed.

2. Theconcretetypeisexpectedtobeorg.teiid.core.types.BlobType

3. Theconcretetypeisexpectedtobeorg.teiid.core.types.ClobType

4. Theconcretetypeisexpectedtobeorg.teiid.core.types.XMLType

5. Theconcretetypeisexpectedtobeorg.teiid.core.types.GeometryType

SupportedTypes

401

Arrays

Warning Teiid’ssupportforarraysisanewfeatureasofthe8.5release.Supportwillberefinedandenhancedinsubsequentreleases.

Anarrayofanytypeisdesignatedbyadding[]foreacharraydimensiontothetypedeclaration.

Examplearraytypes:

string[]

integer[][]

Note Teiidarrayhandlingistypicallyinmemory.Itisnotadvisabletorelyontheusageoflargearrayvalues.Alsoarraysoflobsarenotwellsupportedandwilltypicallynotbehandledcorrectlywhenserialized.

SupportedTypes

402

TypeConversionsDatatypesmaybeconvertedfromoneformtoanothereitherexplicitlyorimplicitly.Implicitconversionsautomaticallyoccurincriteriaandexpressionstoeasedevelopment.ExplicitdatatypeconversionsrequiretheuseoftheCONVERTfunctionorCASTkeyword.

TypeConversionConsiderations:

AnytypemaybeimplicitlyconvertedtotheOBJECTtype.

TheOBJECTtypemaybeexplicitlyconvertedtoanyothertype.

TheNULLvaluemaybeconvertedtoanytype.

Anyvalidimplicitconversionisalsoavalidexplicitconversion.

Situationsinvolvingliteralvaluesthatwouldnormallyrequireexplicitconversionsmayhavetheexplicitconversionappliedimplicitlyifnolossofinformationoccurs.

IfwidenComparisonToStringisfalse(thedefault),whenTeiiddetectsthatanexplicitconversioncannotbeappliedimplicitlyincriteria,thenanexceptionwillberaised.IfwidenComparisonToStringistrue,thendependinguponthecomparisonawideningconversionwillbeappliedorthecriteriawillbetreatedasfalse.

Forexample:

SELECT*FROMmy.tableWHEREcreated_by='notadate'

WithwidenComparisonToStringasfalseandcreated_byistypedasdate,ratherthanconvertingnotadatetoadatevalue,anexceptionwillberaised.

Arrayconversionsarecurrentlyonlyvalidtoandfromcompatibleobjectarrays.Itisnotyetpossibleforexampletocastfrominteger[]tolong[].

Explicitconversionsthatarenotallowedbetweentwotypeswillresultinanexceptionbeforeexecution.Allowedexplicitconversionsmaystillfailduringprocessingiftheruntimevaluesarenotactuallyconvertable.

Warning

TheTeiidconversionsoffloat/double/bigdecimal/timestamptostringrelyontheJDBC/Javadefinedoutputformats.Pushdownbehaviorattemptstomimictheseresults,butmayvarydependingupontheactualsourcetypeandconversionlogic.Careshouldbetakentonotassumethestringformincriteriaorotherplaceswhereavariationmaycausedifferentresults.

Table1.TypeConversions

SourceType ValidImplicitTargetTypes ValidExplicitTargetTypes

string clobchar,boolean,byte,short,integer,long,biginteger,float,double,bigdecimal,xml[1]

char string

boolean string,byte,short,integer,long,biginteger,float,double,bigdecimal

byte string,short,integer,long,biginteger,float,double,bigdecimal boolean

short string,integer,long,biginteger,float, boolean,byte

TypeConversions

403

short string,integer,long,biginteger,float,double,bigdecimal

boolean,byte

integer string,long,biginteger,double,bigdecimal boolean,byte,short,float

long string,biginteger,bigdecimal boolean,byte,short,integer,float,double

biginteger string,bigdecimal boolean,byte,short,integer,long,float,double

bigdecimal string boolean,byte,short,integer,long,biginteger,float,double

float string,bigdecimal,double boolean,byte,short,integer,long,biginteger

double string,bigdecimal boolean,byte,short,integer,long,biginteger,float

date string,timestamp

time string,timestamp

timestamp string date,time

clob string

xml string[2]

ReferenceLink

1. stringtoxmlisequivalenttoXMLPARSE(DOCUMENTexp)-SeealsoXMLFunctions#XMLPARSE

2. xmltostringisequivalenttoXMLSERIALIZE(expASSTRING)-seealsoXMLFunctions#XMLSERIALIZE

TypeConversions

404


ConversionofStringLiterals

TeiidautomaticallyconvertsstringliteralswithinaSQLstatementtotheirimpliedtypes.Thistypicallyoccursinacriteriacomparisonwhereanexpressionwithadifferentdatatypeiscomparedtoaliteralstring:

SELECT*FROMmy.tableWHEREcreated_by='2016-01-02'

Hereifthecreated_bycolumnhasthedatatypeofdate,Teiidautomaticallyconvertsthestringliteraltoadatedatatypeaswell.

ConvertingtoBooleanTeiidcanautomaticallyconvertliteralstringsandnumerictypevaluestoBooleanvaluesasfollows:

Type LiteralValue BooleanValue

String 'false' false

'unknown' null

other true

Numeric 0 false

other true

Date/Time/TimestampTypeConversions

Teiidcanimplicitlyconvertproperlyformattedliteralstringstotheirassociateddate-relateddatatypesasfollows:

StringLiteralFormat PossibleImplicitConversionType

yyyy-mm-dd DATE

hh:mm:ss TIME

yyyy-mm-dd[hh:mm:ss.[fff…]] TIMESTAMP

TheformatsabovearethoseexpectedbytheJDBCdatetypes.TouseotherformatsseethefunctionsPARSEDATE,PARSETIME,PARSETIMESTAMP.


405

EscapedLiteralSyntaxRatherthanrelyingonimplicitconversion,datatypevaluesmaybeexpresseddirectlyinSQLusingescapesyntaxtodefinethetype.Notethatthesuppliedstringvaluemustmatchtheexpectedformatexactlyoranexceptionwilloccur.

Datatype EscapedSyntax

DATE \{d'yyyy-mm-dd'}

TIME \{t'hh-mm-ss'}

TIMESTAMP \{ts'yyyy-mm-dd[hh:mm:ss.[fff…]]'}

EscapedLiteralSyntax

406

UpdatableViewsAnyviewmaybemarkedasupdatable.InmanycircumstancestheviewdefinitionmayallowtheviewtobeinherentlyupdatablewithouttheneedtomanuallydefineatriggertohandleINSERT/UPDATE/DELETEoperations.

Aninherentlyupdatableviewcannotbedefinedwithaquerythathas:

Asetoperation(INTERSECT,EXCEPT,UNION).

SELECTDISTINCT

Aggregation(aggregatefunctions,GROUPBY,HAVING)

ALIMITclause

AUNIONALLcandefineaninherentlyupdatableviewonlyifeachoftheUNIONbranchesisitselfinherentlyupdatable.AviewdefinedbyaUNIONALLcansupportinherentINSERTsifitisaFederatedOptimizations#PartitionedUnionandtheINSERTspecifiesvaluesthatbelongtoasinglepartition.

AnyviewcolumnthatisnotmappeddirectlytoacolumnisnotupdatableandcannotbetargetedbyanUPDATEsetclauseorbeanINSERTcolumn.

IfaviewisdefinedbyajoinqueryorhasaWITHclauseitmaystillbeinherentlyupdatable.Howeverinthesesituationstherearefurtherrestrictionsandtheresultingqueryplanmayexecutemultiplestatements.Foranon-simplequerytobeupdatable,itisrequired:

AnINSERT/UPDATEcanonlymodifyasingleKey-preservedTable.

ToallowDELETEoperationstheremustbeonlyasingleKey-preservedTable.

IfthedefaulthandlingisnotavailableoryouwishtohaveanalternativeimplementationofanINSERT/UPDATE/DELETE,thenyoumayuseUpdateProcedures(Triggers)todefineprocedurestohandletherespectiveoperations.

UpdatableViews

407

preservedTableAkey-preservedtablehasaprimaryoruniquekeythatwouldremainuniqueifitwereprojectedintotheresultofthequery.NotethatitisnotactuallyrequiredforaviewtoreferencethekeycolumnsintheSELECTclause.Thequeryenginecandetectakeypreservedtablebyanalyzingthejoinstructure.Theenginewillensurethatajoinofakey-preservedtablemustbeagainstoneofitsforeignkeys.

preservedTable

408

TransactionSupportTeiidutilizesXAtransactionsforparticipatinginglobaltransactionsandfordemarcatingitslocalandcommandscopedtransactions.JBossTransactionsisusedbyTeiidasitstransactionmanager.SeethisdocumentationfortheadvancedfeaturesprovidedbyJBossTransactions.

Table1.TeiidTransactionScopes

Scope Description

Command

Treatstheusercommandasifallsourcecommandsareexecutedwithinthescopeofthesametransaction.TheAutoCommitTxnexecutionpropertycontrolsthebehaviorofcommandleveltransactions.

Local Thetransactionboundaryislocaldefinedbyasingleclientsession.

Global TeiidparticipatesinaglobaltransactionasanXAResource.

ThedefaulttransactionisolationlevelforTeiidisREAD_COMMITTED.

TransactionSupport

409

http://www.jboss.org/jbosstm/

http://www.jboss.org/jbosstm/docs/index.html

AutoCommitTxnExecutionPropertySinceuserlevelcommandsmayexecutemultiplesourcecommands,userscanspecifytheAutoCommitTxnexecutionpropertytocontrolthetransactionalbehaviorofausercommandwhennotinalocalorglobaltransaction.

Table1.AutoCommitTxnSettings

Setting Description

OFFDonotwrapeachcommandinatransaction.Individualsourcecommandsmaycommitorrollbackregardlessofthesuccessorfailureoftheoverallcommand.

ON Wrapeachcommandinatransaction.Thismodeisthesafest,butmayintroduceperformanceoverhead.

DETECTThisisthedefaultsetting.Willautomaticallywrapcommandsinatransaction,butonlyifthecommandseemstobetransactionallyunsafe.

TheconceptofcommandsafetywithrespecttoatransactionisdeterminedbyTeiidbaseduponcommandtype,thetransactionisolationlevel,andavailablemetadata.Awrappingtransactionisnotneededif:

Ifausercommandisfullypushedtothesource.

IftheusercommandisaSELECT(includingXML)andthetransactionisolationisnotREPEATABLE_READnorSERIALIABLE.

IftheusercommandisastoredprocedureandthetransactionisolationisnotREPEATABLE_READnorSERIALIABLEandtheUpdatingModelCountiszero.

Theupdatecountmaybesetonallproceduresaspartoftheproceduremetadatainthemodel.

AutoCommitTxnExecutionProperty

410

UpdatingModelCountTheterm"updatingmodelcount"referstothenumberoftimesanymodelisupdatedduringtheexecutionofacommand.Itisusedtodeterminewhetheratransaction,ofanyscope,isrequiredtosafelyexecutethecommand.

Table1.UpdatingModelCountSettings

Count Description

0 Noupdatesareperformedbythiscommand.

1

Indicatesthatonlyonemodelisupdatedbythiscommand(anditssubcommands).Alsothesuccessorfailureofthatupdatecorrespondstothesuccessoffailureofthecommand.Itshouldnotbepossiblefortheupdatetosucceedwhilethecommandfails.Executionisnotconsideredtransactionallyunsafe.

*Anynumbergreaterthan1indicatesthatexecutionistransactionallyunsafeandanXAtransactionwillberequired.

UpdatingModelCount

411

JDBCandTransactions

JDBCAPIFunctionality

ThetransactionscopesabovemaptotheseJDBCmodes:

Command-ConnectionautoCommitpropertysettotrue.

Local-ConnectionautoCommitpropertysettofalse.ThetransactioniscommittedbysettingautoCommittotrueorcallingjava.sql.Connection.commit.Thetransactioncanberolledbackbyacalltojava.sql.Connection.rollback

Global-theXAResourceinterfaceprovidedbyanXAConnectionisusedtocontrolthetransaction.NotethatXAConnectionsareavailableonlyifTeiidisconsumedthroughitsXADataSource,org.teiid.jdbc.TeiidDataSource.JEEcontainersordataaccessAPIstypicallycontrolXAtransactionsonbehalfofapplicationcode.

J2EEUsageModels

J2EEprovidesthreewaystomanagetransactionsforbeans:

Client-controlled–theclientofabeanbeginsandendsatransactionexplicitly.

Bean-managed–thebeanitselfbeginsandendsatransactionexplicitly.

Container-managed–theappservercontainerbeginsandendsatransactionautomatically.

Inanyofthesecases,transactionsmaybeeitherlocalorXAtransactions,dependingonhowthecodeanddescriptorsarewritten.Somekindsofbeans(statefulsessionbeansandentitybeans)arenotrequiredbythespectosupportnon-transactionalsources,althoughthespecdoesallowanappservertooptionallysupportthiswiththecautionthatthisisnotportableorpredictable.Generallyspeaking,tosupportmosttypicalEJBactivitiesinaportablefashionrequiressomekindoftransactionsupport.

JDBCandTransactions

412

TransactionalBehaviorwithWildFlyDataSourceTypesWildFlyallowscreationofdifferenttypesofdatasources,basedontheirtransactionalcapabilities.ThetypeofdatasourceyoucreateforyourVDB’ssourcesalsodictatesifthatdatasourcewillbeparticipatingthedistributedtransactionornot,irrespectiveofthetransactionscopeyouselectedfromabove.Herearedifferenttypesofdatasources

xa-datasource:CapableofparticipatinginthedistributedtransactionusingXA.ThisisrecommendedtypebeusedwithanyTeiidsources.

local-datasource:DoesnotparticipateinXA,unlessthisistheonlysourcethatislocal-datasourcethatisparticipatingamongotherxa-datasourcesinthecurrentdistributedtransaction.Thistechniqueiscalledlastcommitoptimization.However,ifyouhavemorethenonelocal-datasourcesparticipatinginatransaction,thenthetransactionmanagerwillendupwith"Couldnotenlistintransactiononenteringmeta-awareobject!;"exception.

no-tx-datasource:Doesnotparticipateindistributedtransactionatall.InthescopeofTeiidcommandovermultiplesources,youcanincludethistypeofdatasourceinthesamedistributedtransactioncontext,howeverthissourcewillbeitwillnotbesubjecttoanytransactionalparticipation.Anychangesdoneonthissourceaspartofthetransactionscope,cannotberolledback.IfyouhavethreedifferentsourcesA,B,CandtheyarebeingusedinTeiid.Herearesomevariationsonhowtheybehavewithdifferenttypesofdatasources.Thesuffixes"xa","local","no-tx"definedifferenttypeofsourcesused.

A-xaB-xa,C-xa:Canparticipateinalltransactionalscopes.Norestrictions.

A-xa,B-xa,c-local:Canparticipateinalltransactionalscopes.Notethatthereisonlyonesinglesourceis"local".ItisassumedthatintheGlobalscope,thethirdpartydatasource,otherthanTeiidDatasourceisalsoXA.

A-xa,B-xa,C-no-tx:Canparticipateinalltransactionalscopes.Note"C"isnotareallyboundbyanytransactionalcontract.AandBaretheonlyparticipentsinXAtransaction.

A-xa,B-local,C-no-tx:Canparticipateinalltransactionalscopes.Note"C"isnotareallyboundbyanytransactionalcontract,andthereisonlysingle"local"source.

Ifanytwoormoresourcesare"local":TheycanonlyparticipateinCommandmodewith"autoCommitTxn=OFF".Otherwisewillendwithexceptionas"Couldnotenlistintransactiononenteringmeta-awareobject!;"exception,asitisnotpossibletodoaXAtransactionwith"local"datasources.

A-no-tx,B-no-tx,C-no-tx:Canparticipateinalltransactionscopes,butnoneofthesourceswillbeboundbytransactionalterms.ThisisequivalenttonotusingtransactionsorsettingCommandmodewith"autoCommitTxn=OFF".

Note

TeiidDesignercreates"local"datasourcebydefaultwhichisnotoptimalfortheXAtransactions.TeiidwouldlikethistobecreatingaXAdatasources,howeverwithcurrentlimitationswithDTPthatfeatureiscurrentlynotavailable.TocreateXAdatasource,lookintheWildFly"doc"directoryforexampletemplates,orusethe"admin-console"tocreatetheXAdatasources.

IfyourdatasourceisnotXA,andnottheonlylocalsourceandcannotuse"no-tx",thenyoucanlookintoextendingthesourcetoimplementthecompensatingXAimplementation.i.e.defineyourownresourcemanagerforyoursourceandmanagethetransactionthewayyouwantittobehave.NotethatthiscouldbecomplicatedifnotimpossibleifyoursourcenativelydoesnotsupportdistributedXAprotocol.Insummay

UseXAdatasourceifpossible

Useno-txdatasourceifapplicable

UseautoCommitTxn=OFF,andletgodistributedtransactions,thoughnotrecommended

WriteacompensatingXAbasedimplementation.

Table1.TeiidTransactionParticipation


413

Teiid-Tx-Scope XAsource LocalSource No-TxSource

Local(Auto-commit=false) always OnlyIfSingleSource never

Global always OnlyIfSingleSource never

Auto-commit=true,AutoCommitTxn=ON,orDETECTandtxnstarted

always OnlyIfSingleSource never

Auto-commit=true,AutoCommitTxn=OFF never never never


414

LimitationsandWorkaroundsTheclientsettingoftransactionisolationlevelisnotpropogatedtotheconnectors.ThetransactionisolationlevelcanbesetoneachXAconnector,howeverthisisolationlevelisfixedandcannotbechangedatruntimeforspecificconnections/commands.

LimitationsandWorkarounds

415

DataRolesDataroles,alsocalledentitlements,aresetsofpermissionsdefinedperVDBthatdictatedataaccess(create,read,update,delete).Datarolesuseafine-grainedpermissionsystemthatTeiidwillenforceatruntimeandprovideauditlogentriesforaccessviolations-seeLoggingandCustomLoggingformore.

Priortoapplyingdataroles,youshouldconsiderrestrictingsourcesystemaccessthroughthefundamentaldesignofyourVDB.Foremost,Teiidcanonlyaccesssourceentriesthatarerepresentedinimportedmetadata.YoushouldnarrowimportedmetadatatoonlywhatisnecessaryforusebyyourVDB.WhenusingTeiidDesigner,youmaythengofurtherandmodifytheimportedmetadataatagranularleveltoremovespecificcolumns,marktablesasnon-updatable,etc.

IfdatarolevalidationisenabledanddatarolesaredefinedinaVDB,thenaccesspermissionswillbeenforcedbytheTeiidServer.Theuseofdatarolesmaybedisabledsystemwidebyremovingthesettingfortheteiidsubsystempolicy-decider-module.Datarolesalsohavebuilt-insystemfunctionsthatcanbeusedforrow-basedandotherauthorizationchecks.

Tip

UnlikepreviousversionsofTeiiddataroleswillonlybecheckedifpresentinaVDB.AVDBdeployedwithoutdatarolesisopenforusebyanyauthenticateduser.Ifyouwanttoensuresomeattempthasbeenmadeatsecuringaccess,thensetthedata-roles-requiredconfigurationelementtotrueviatheCLIorinthestandalone.xmlontheteiidsubsystem.

DataRoles

416

Permissions

UserQueryPermissions

CREATE,READ,UPDATE,DELETE(CRUD)permissionscanbesetforanyresourcepathinaVDB.Aresourcepathcanbeasspecificasthefullyqualifiednameofacolumnorasgeneralatoplevelmodel(schema)name.Permissionsgrantedtoaparticularpathapplytoitandanyresourcepathsthatsharethesamepartialname.Forexample,grantingreadto"model"willalsograntreadto"model.table","model.table.column",etc.Allowingordenyingaparticularactionisdeterminedbysearchingforpermissionsfromthemosttoleastspecificresourcepaths.Thefirstpermissionfoundwithaspecificallowordenywillbeused.Thusitispossibletosetverygeneralpermissionsathigh-levelresourcepathnamesandtooverrideonlyasnecessaryatmorespecificresourcepaths.

Permissiongrantsareonlyneededforresourcesthataroleneedsaccessto.Permissionsarealsoonlyappliedtothecolumns/tables/proceduresintheuserquery-nottoeveryresourceaccessedtransitivelythroughviewandproceduredefinitions.Itisimportantthereforetoensurethatpermissiongrantsareappliedconsistentlyacrossmodelsthataccessthesameresources.

NoteUnlikepreviousversionsofTeiid,non-visiblemodelsareaccessiblebyuserqueries.Torestrictuseraccessatamodellevel,atleastonedataroleshouldbecreatedtoenabledatarolechecking.Inturnthatrolecanbemappedtoanyauthenticateduserandshouldnotgrantpermissionstomodelsthatshouldbeinaccessible.

PermissionsarenotapplicabletotheSYSandpg_catalogschemas.Thesemetadatareportingschemasarealwaysaccessibleregardlessoftheuser.TheSYSADMINschemahowevermayneedpermissionsasapplicable.

ToprocessaSELECTstatementorastoredprocedureexecution,theuseraccountrequiresthefollowingaccessrights:

READ-ontheTable(s)beingaccessedortheprocedurebeingcalled.

READ-oneverycolumnreferenced.

ToprocessanINSERTstatement,theuseraccountrequiresthefollowingaccessrights:

CREATE-ontheTablebeinginsertedinto.

CREATE-oneverycolumnbeinginsertedonthatTable.

ToprocessanUPDATEstatement,theuseraccountrequiresthefollowingaccessrights:

UPDATE-ontheTablebeingupdated.

UPDATE-oneverycolumnbeingupdatedonthatTable.

READ-oneverycolumnreferencedinthecriteria.

ToprocessaDELETEstatement,theuseraccountrequiresthefollowingaccessrights:

DELETE-ontheTablebeingdeleted.

READ-oneverycolumnreferencedinthecriteria.

ToprocessaEXEC/CALLstatement,theuseraccountrequiresthefollowingaccessrights:

EXECUTE(orREAD)-ontheProcedurebeingexecuted.

Toprocessanyfunction,theuseraccountrequiresthefollowingaccessrights:

EXECUTE(orREAD)-ontheFunctionbeingcalled.

ToprocessanyALTERorCREATETRIGGERstatement,theuseraccountrequiresthefollowingaccessrights:

Permissions

417

ALTER-onthevieworprocedurethatiseffected.INSTEADOFTriggers(updateprocedures)arenotyettreatedasfullschemaobjectsandareinsteadtreatedasattributesoftheview.

ToprocessanyOBJECTTABLEfunction,theuseraccountrequiresthefollowingaccessrights:

LANGUAGE-specifyingthelanguagenamethatisallowed.

ToprocessanystatementagainstaTeiidtemporarytablerequiresthefollowingaccessrights:

allow-create-temporary-tablesattributeonanyapplicablerole

CREATE,READ,UPDATE,DELETE-againstthetargetmodel/schemaasneededforoperationsagainstaFOREIGNtemporarytable.

RowandColumnBasedSecurity

AlthoughspecifiedinasimilarwaytouserqueryCRUDpermissions,row-basedandcolumn-basedpermissionsmaybeusedtogetherorseparatelytocontrolatamoregranularandconsistentlevelthedatareturnedtousers.SeealsoXMLDefinitionforexamplesofspecifyingdataroleswithrowandcolumnbasedsecurity.

Row-BasedSecurity

Apermissionagainstafullyqualifiedtable/view/proceduremayalsospecifyacondition.UnliketheallowCRUDactionsdefinedabove,aconditionisalwaysapplied-notjustattheuserquerylevel.TheconditioncanbeanyvalidSQLreferencingthecolumnsofthetable/view/procedure.Procedureresultsetcolumnsmaybereferencedasproc.col.Theconditionwillactasarow-basedfilterandasacheckedconstraintforinsert/updateoperations.

HowRow-BasedConditionsAreApplied

Aconditionisappliedconjunctivelytoupdate/delete/selectwhereclausesagainsttheaffectedresource.Thosequerieswillthereforeonlyeverbeeffectiveagainstthesubsetofrowsthatpassthecondition,i.e."SELECT*FROMTBLWHEREblahANDcondition".Theconditionwillbepresentregardlessofhowthetable/viewisusedinthequery,whetherviaaunion,join,etc.

Insertsandupdatesagainstphysicaltablesaffectedbyaconditionarefurthervalidatedsothattheinsert/changevaluesmustpassthecondition(evaluatetotrue)fortheinsert/updatetosucceed-thisiseffectivelythesameaSQLconstraint.Thiswillhappenforallstylesofinsert/update-insertwithqueryexpression,bulkinsert/update,etc.Inserts/updatesagainstviewsarenotcheckedwithregardstotheconstraint.Youmaydisabletheinsert/updateconstraintcheckbysettingtheconditionconstraintflagtofalse.Thisistypicallyonlyneededincircumstanceswhentheconditioncannotalwaysbeevaluated.Howeverdisablingtheconditionasaconstraintsimplydropstheconditionfromconsiderationwhenlogicallyevaluatingtheconstraint.Anyotherconditionconstraintswillstillbeevaluated.

Acrossmultipleapplicablerolesifmorethanoneconditionappliestothesameresource,theconditionswillbeaccumulateddisjunctivelyviaOR,i.e."(condition1)OR(condition2)…".Thereforegrantingapermissionwiththecondition"true"willallowusersinthatroletoseeallrowsofthegivenresource.

ConsiderationsWhenUsingConditions

Non-pushdownconditionsmayadverselyimpactperformance,sincetheirevaluationmayinhibitpushdownofqueryconstructsontopoftheaffectedresource.Multipleconditionsagainstthesameresourceshouldgenerallybeavoidedasanynon-pushdownconditionwillcausetheentireORofconditionstonotbepusheddown.Insomecircumstancestheinsertionofpermissionconditionsmayrequirethattheplanbealteredwiththeadditionofaninlineview,whichcanresultinadverseperformanceagainstsourcesthatdonotsupportinlineviews.

Permissions

418

Pushdownofmulti-rowinsert/updateoperationswillbeinhibitedsincetheconditionmustbecheckedforeachrow.

Inadditiontomanagingpermissionconditionsonaper-rolebasis,anotherapproachistoaddconditionpermissionswouldinananyauthenticatedrolesuchthattheconditionsaregeneralizedforallusers/rolesusingthehasRole,user,andothersuchsecurityfunctions.Theadvantageofthelatterapproachisthatthereiseffectivelyastaticrow-basedpolicyineffectsuchthatallqueryplanscanstillbesharedbetweenusers.

HandlingofnullvaluesisuptotheimplementerofthedataroleandmayrequireISNULLcheckstoensurethatnullvaluesareallowedwhenacolumnisnullable.

Limitations

Conditionsonsourcetablesthatactascheckconstraintsmustcurrentlynotcontaincorrelatedsubqueries.

Conditionsmaynotcontainaggregateorwindowedfunctions.

Tablesandproceduresreferencedviasubquerieswillstillhaverow-basedfiltersandcolumnmaskingappliedtothem.

Note Row-basedfilterconditionsareenforcedevenformaterializedviewloads.

Youshouldensurethattablesconsumedtoproducematerializedviewsdonothaverow-basedfilterconditionsonthemthatcouldaffectthematerializedviewresults.

ColumnMasking

Apermissionagainstafullyqualifiedtable/view/procedurecolumnmayalsospecifyamaskandoptionallyacondition.Whenthequeryissubmittedtherolesareconsultedandtherelevantmask/conditioninformationarecombinedtoformasearchedcaseexpressiontomaskthevaluesthatwouldhavebeenreturnedbytheaccess.UnliketheCRUDallowactionsdefinedabove,theresultingmaskingeffectisalwaysapplied-notjustattheuserquerylevel.TheconditionandexpressioncanbeanyvalidSQLreferencingthecolumnsofthetable/view/procedure.Procedureresultsetcolumnsmaybereferencedasproc.col.

HowColumnMasksAreApplied

ColumnmaskingisappliedonlyagainstSELECTs.Columnmaskingisappliedlogicallyaftertheaffectofrowbasedsecurity.Howeversincebothviewsandsourcetablesmayhaverowandcolumnbasedsecurity,theactualviewlevelmaskingmaytakeplaceontopofsourcelevelmasking.Iftheconditionisspecifiedalongwiththemask,thentheeffectivemaskexpressioneffectsonlyasubsetoftherows:"CASEWHENconditionTHENmaskELSEcolumn".OtherwisetheconditionisassumedtobeTRUE,meaningthatthemaskappliestoallrows.

Ifmultiplerolesspecifyamaskagainstacolumn,themaskorderargumentwilldeterminetheirprecedencefromhighesttolowestaspartofalargersearchedcaseexpression.Forexampleamaskwiththedefaultorderof0andamaskwithanorderof1wouldbecombinedas"CASEWHENcondition1THENmask1WHENcondition0THENmask0ELSEcolumn".

ConsiderationsWhenUsingMasking

Non-pushdownmaskingconditions/expressionsmayadverselyimpactperformance,sincetheirevaluationmayinhibitpushdownofqueryconstructsontopoftheaffectedresource.Insomecircumstancestheinsertionofmaskingmayrequirethattheplanbealteredwiththeadditionofaninlineview,whichcanresultinadverseperformanceagainstsourcesthatdonotsupportinlineviews.

Inadditiontomanagingmaskingonaper-rolebasiswiththeuseoftheordervalue,anotherapproachistospecifymaskinginasingleanyauthenticatedrolesuchthattheconditions/expressionsaregeneralizedforallusers/rolesusingthehasRole,user,andothersuchsecurityfunctions.Theadvantageofthelatterapproachisthatthereiseffectivelyastaticmaskingpolicyineffectsuchthatallqueryplanscanstillbesharedbetweenusers.

Permissions

419

Limitations

Intheeventthattwomaskshavethesameordervalue,itisnotwelldefinedwhatordertheyareappliedin.

Masksortheirconditionsmaynotcontainaggregateorwindowedfunctions.

Tablesandproceduresreferencedviasubquerieswillstillhaverow-basedfiltersandcolumnmaskingappliedtothem.

Note Maskingisenforcedevenformaterializedviewloads.

Youshouldensurethattablesconsumedtoproducematerializedviewsdonothavemaskingonthemthatcouldaffectthematerializedviewresults.

Permissions

420

RoleMappingEachTeiiddatarolecanbemappedtoanynumberofcontainerrolesoranyauthenticateduser.YoumaycontrolrolemembershipthroughwhateversystemtheTeiidsecuritydomainloginmodulesareassociatedwith.ThekitincludesexamplefilesforusewiththeUsersRolesLoginModule-seeteiid-security-roles.properties.

IfyouhavemorethanonesecuritydomainforthetransportorsimplyhaveanalternativesecuritydomainthataVDBshoulduse,thensettheVDBpropertysecurity-domaintotherelevantsecuritydomain.

Itispossibleforausertohaveanynumberofcontainerroles,whichinturnimplyasubsetofTeiiddataroles.EachapplicableTeiiddatarolecontributescumulativelytothepermissionsoftheuser.Noonerolesupersedesornegatesthepermissionsoftheotherdataroles.

RoleMapping

421

XMLDefinitionDatarolesaredefinedinsidethevdb.xmlfile(insidethe.vdbZiparchiveunderMETA-INF/vdb.xml)ifyouusedDesigner.The"vdb.xml"fileischeckedagainsttheschemafilevdb-deployer.xsd,whichcanbefoundinthekitunderdocs/teiid/schema.Thisexamplewillshowasample"vdb.xml"filewithfewsimpledataroles.

Forexample,ifaVDBdefinesatable"TableA"inschema"modelName"withcolumns(column1,column2)-notethatthecolumntypesdonotmatter.Andwewishtodefinethreeroles"RoleA","RoleB",and"admin"withfollowingpermissions:

1. RoleAhaspermissionstoread,writeaccesstoTableA,butcannotdelete.

2. RoleBhaspermissionsthatonlyallowreadaccesstoTableA.column1

3. adminhasallpermissions

vdb.xmldefiningRoleA,RoleB,andAdmin


<vdbname="sample"version="1">

<modelname="modelName">

<sourcename="source-name"translator-name="oracle"connection-jndi-name="java:myDS"/>

</model>

<data-rolename="RoleA">

<description>Allowall,exceptDelete</description>

<permission>

<resource-name>modelName.TableA</resource-name>

<allow-create>true</allow-create>

<allow-read>true</allow-read>

<allow-update>true</allow-update>

</permission>

<mapped-role-name>role1</mapped-role-name>

</data-role>

<data-rolename="RoleB">

<description>Allowreadonly</description>

<permission>

<resource-name>modelName.TableA</resource-name>


</permission>

<permission>

<resource-name>modelName.TableA.colum2</resource-name>

<allow-read>false</allow-read>

</permission>


</data-role>

<data-rolename="admin"grant-all="true">

<description>Adminrole</description>

<mapped-role-name>admin-group</mapped-role-name>

</data-role>

</vdb>

XMLDefinition

422

TheaboveXMLdefinedthreedataroles,"RoleA"whichallowseverythingexceptdeleteonthetable,"RoleB"thatallowsonlyreadoperationonthetable,andthe"admin"rolewithallpermissions.SinceTeiidusesdenybydefault,thereisnoexplicitdata-roleentryneededfor"RoleB".NotethatexplicitcolumnpermissionsarenotneededforRoleA,sincetheparentresourcepath,modelName.TableA,permissionsstillapply.RoleBhowevermustexplicitlydisallowreadtocolumn2.

The"mapped-role-name"definesthecontainerJAASrolesthatareassignedthedatarole.ForassigningrolestoyourusersintheWildFly,checkouttheinstructionsfortheselectedLoginModule.Checkthe"AdminGuide"forconfiguringLoginModules.

AdditionalRoleAttributes

Youmayalsochoosetoallowanyauthenticatedusertohaveadatarolebysettingtheany-authenticatedattributevaluetotrueondata-roleelement.

The"allow-create-temporary-tables"data-rolebooleanattributeisusedtoexplicitlyenableordisabletemporarytableusagefortherole.Ifitisleftunspecified,thenthevaluewillbedefaultedtofalse.

TempTableRoleforAnyAuthenticated

<data-rolename="role"any-authenticated="true"allow-create-temporary-tables="true">

<description>TempTableRoleforAnyAuthenticated</description>

<permission>

...

</permission>

</data-role>

LanguageAccess

Thefollowingshowsavdbxmlthatallowstheuseofthejavascriptlanguage.Theallowed-languagespropertyenablesthelanguagesuseforanypurposeinthevdb,whiletheallow-languagepermissionallowsthelanguagetobeusedbyuserswithRoleA.

vdb.xmlallowingJavaScriptaccess



<propertyname="allowed-languages"value="javascript"/>



</model>


<description>Readandjavascriptaccess.</description>

<permission>

<resource-name>modelName</resource-name>


</permission>

<permission>

<resource-name>javascript</resource-name>

<allow-language>true</allow-language>

</permission>


</data-role>

</vdb>

Row-BasedSecurity

XMLDefinition

423

Thefollowingshowsavdbxmlutilizingaconditiontorestrictaccess.Theconditionactsasbothafilterandconstraint.EventhoughRoleAopensupread/insertaccesstomodelName.tblName,thebase-roleconditionwillensurethatonlyvaluesofcolumn1matchingthecurrentusercanbereadorinserted.Notethatheretheconstraintenforcementhasbeendisabled.

vdb.xmlallowingconditionalaccess





</model>

<data-rolename="base-role"any-authenticated="true">

<description>Conditionalaccess</description>

<permission>

<resource-name>modelName.tblName</resource-name>

<conditionconstraint="false">column1=user()</condition>

</permission>

</data-role>


<description>Read/Insertaccess.</description>

<permission>




</permission>


</data-role>

</vdb>

ColumnMasking

Thefollowingshowsavdbxmlutilizingcolumnmasking.HeretheRoleAcolumn1masktakesprecedenceoverthebase-rolemask,butonlyforasubsetoftherowsasspecifiedbythecondition.ForuserswithoutRoleA,accesstocolumn1willeffectivelybereplacedwith"CASEWHENcolumn1=user()THENcolumn1END",whileforuserswithRoleA,accesstocolumn1willeffectivelybereplacedwith"CASEWHENcolumn2=’x’THENcolumn1WHENTRUETHENCASEWHENcolumn1=user()THENcolumn1ENDEND".

vdb.xmlwithcolumnmasking





</model>

<data-rolename="base-role"any-authenticated="true">

<description>Masking</description>

<permission>

<resource-name>modelName.tblName.column1</resource-name>

<mask>CASEWHENcolumn1=user()THENcolumn1END</mask>

</permission>

</data-role>


XMLDefinition

424

<description>Read/Insertaccess.</description>

<permission>




</permission>

<permission>

<resource-name>modelName.tblName.column1</resource-name>

<condition>column2='x'</condition>

<maskorder="1">column1</mask>

</permission>


</data-role>

</vdb>

XMLDefinition

425

CustomizingSeetheDeveloper’sGuidechaptersonCustomAuthorizationValidatorsand[Teiid:LoginModules]fordetailsonusinganalternativeauthorizationscheme.

Customizing

426

SystemSchemaThebuilt-inSYSandSYSADMINschemasprovidemetadatatablesandproceduresagainstthecurrentVDB.

BydefaultasystemschemaforODBCmetadatapg_catalogisalsoexposed-howeverthatshouldbeconsideredforgeneraluse.

MetadataVisibility

TheSYSsystemschematablesandproceduresarealwaysvisible/accessible.

UnlikeTeiid8.xandpriorreleaseswhenDataRolesareinusetable/viewsandproceduremetadataentrieswillnotbevisibleiftheuserisnotentitledtousetheobject.Tables/views/columnsrequiretheREADpermissionandproceduresrequiretheEXECUTEpermission.Allcolumnsofakeymustbeaccessiblefortheentrytobevisible.

Note Ifthereisanycachingofsystemmetadatawhendatarolesareinuse,thenvisibilityneedstobeconsidered.

SystemSchema

427

SYSSchemaSystemschemaforpublicinformationandactions.

TableofContentsTables/Views

SYS.ColumnsSYS.DataTypesSYS.KeyColumnsSYS.KeysSYS.ProcedureParamsSYS.ProceduresSYS.FunctionParamsSYS.FunctionsSYS.PropertiesSYS.ReferenceKeyColumnsSYS.SchemasSYS.TablesSYS.VirtualDatabasesSYS.spatial_sys_refSYS.GEOMETRY_COLUMNS

ProceduresSYS.getXMLSchemasSYS.ArrayIterate

Tables/Views

SYS.Columns

Thistablesuppliesinformationaboutalltheelements(columns,tags,attributes,etc)inthevirtualdatabase.

ColumnName Type Description

VDBName string VDBname

SchemaName string SchemaName

TableName string Tablename

Name string Elementname(notqualified)

Position integer Positioningroup(1-based)

NameInSource string Nameofelementinsource

DataType string Teiidruntimedatatypename

Scale integer Numberofdigitsafterthedecimalpoint

SYS

428

ElementLength integer Elementlength(mostlyusedforstrings)

sLengthFixed boolean Whetherthelengthisfixedorvariable

SupportsSelect boolean ElementcanbeusedinSELECT

SupportsUpdates boolean Valuescanbeinsertedorupdatedintheelement

IsCaseSensitive boolean Elementiscase-sensitive

IsSigned boolean Elementissignednumericvalue

IsCurrency boolean Elementrepresentsmonetaryvalue

IsAutoIncremented boolean Elementisauto-incrementedinthesource

NullType string Nullability:"Nullable","NoNulls","Unknown"

MinRange string Minimumvalue

MaxRange string Maximumvalue

DistinctCount integer Distinctvaluecount,-1canindicateunknown

NullCount integer Nullvaluecount,-1canindicateunknown

SearchType stringSearchability:"Searchable","AllExceptLike","LikeOnly",Unsearchable"

Format string Formatofstringvalue

DefaultValue string Defaultvalue

JavaClass string Javaclassthatwillbereturned

Precision integer Numberofdigitsinnumericvalue

CharOctetLength integer Measureofreturnvaluesize

Radix integer Radixfornumericvalues

GroupUpperName string Upper-casefullgroupname

UpperName string Upper-caseelementname

UID string ElementuniqueID

SYS

429

Description string Description

TableUID string ParentTableuniqueID

SYS.DataTypes

Thistablesuppliesinformationondatatypes.


Name string Teiiddesign-timetypename

IsStandard boolean Alwaysfalse

IsPhysical boolean Alwaysfalse

TypeName string Design-timetypename(sameasName)

JavaClass string Javaclassreturnedforthistype

Scale integer Maxscaleofthistype

TypeLength integer Maxlengthofthistype


IsSigned boolean Issignednumeric?

IsAutoIncremented boolean Isauto-incremented?

IsCaseSensitive boolean Iscase-sensitive?

Precision integer Maxprecisionofthistype

Radix integer Radixofthistype

SearchType stringSearchability:"Searchable","AllExceptLike","LikeOnly","Unsearchable"

UID string DatatypeuniqueID

RuntimeType string Teiidruntimedatatypename

BaseType string Basetype

Description string Descriptionoftype

SYS.KeyColumns

SYS

430

Thistablesuppliesinformationaboutthecolumnsreferencedbyakey.





Name string Elementname

KeyName string Keyname

KeyType string Keytype:"Primary","Foreign","Unique",etc

RefKeyUID string ReferencedkeyUID

UID string KeyUID

Position integer Positioninkey

TableUID string ParentTableuniqueID

SYS.Keys

Thistablesuppliesinformationaboutprimary,foreign,anduniquekeys.





Name string Keyname


NameInSource string Nameofkeyinsourcesystem

Type string Typeofkey:"Primary","Foreign","Unique",etc

IsIndexed boolean Trueifkeyisindexed

RefKeyUID string ReferencedkeyUID(ifforeignkey)

UID string KeyuniqueID

SYS

431

SYS.ProcedureParams

Thissuppliesinformationonprocedureparameters.




ProcedureName string Procedurename

Name string Parametername


Position integer Positioninprocedureargs

Type string Parameterdirection:"In","Out","InOut","ResultSet","ReturnValue"

Optional boolean Parameterisoptional

Precision integer Precisionofparameter

TypeLength integer Lengthofparametervalue

Scale integer Scaleofparameter

Radix integer Radixofparameter


Description string Descriptionofparameter

SYS.Procedures

Thistablesuppliesinformationabouttheproceduresinthevirtualdatabase.




Name string Procedurename

NameInSource string Procedurenameinsourcesystem

ReturnsResults boolean Returnsaresultset

UID string ProcedureUID

SYS

432


SchemaUID string ParentSchemauniqueID

SYS.FunctionParams

Thissuppliesinformationonfunctionparameters.




FunctionName string Functionname

FunctionUID string FunctionUID

Name string Parametername


Position integer Positioninprocedureargs

Type string Parameterdirection:"In","Out","InOut","ResultSet","ReturnValue"

Precision integer Precisionofparameter

TypeLength integer Lengthofparametervalue

Scale integer Scaleofparameter

Radix integer Radixofparameter


Description string Descriptionofparameter

SYS.Functions

Thistablesuppliesinformationaboutthefunctionsinthevirtualdatabase.




Name string Functionname

NameInSource string

SYS

433

NameInSource string

UID string FunctionUID


IsVarArgs boolean Doesthefunctionacceptvariablearguments

SYS.Properties

Thistablesuppliesuser-definedpropertiesonallobjectsbasedonmetamodelextensions.Normally,thistableisemptyifnometamodelextensionsarebeingused.


Name string Extensionpropertyname

Value string Extensionpropertyvalue

UID string KeyuniqueID

ClobValue clob ClobValue

SYS.ReferenceKeyColumns

Thistablesuppliesinformatonaboutcolumn’skeyreference.


PKTABLE_CAT string VDBName

PKTABLE_SCHEM string SchemaName

PKTABLE_NAME string Table/ViewName

PKCOLUMN_NAME string ColumnName

FKTABLE_CAT string VDBName

FKTABLE_SCHEM string SchemaName

FKTABLE_NAME string Table/ViewName

FKCOLUMN_NAME string ColumnName

KEY_SEQ short KeySequence

UPDATE_RULE integer UpdateRule

DELETE_RULE integer DeleteRule

SYS

434

FK_NAME string FKName

PK_NAME string PKNmae

DEFERRABILITY integer

SYS.Schemas

Thistablesuppliesinformationaboutalltheschemasinthevirtualdatabase,includingthesystemschemaitself(System).



Name string Schemaname

IsPhysical boolean Trueifthisrepresentsasource

UID string UniqueID


PrimaryMetamodelURI stringURIfortheprimarymetamodeldescribingthemodelusedforthisschema

SYS.Tables

Thistablesuppliesinformationaboutallthegroups(tables,views,documents,etc)inthevirtualdatabase.




Name string Shortgroupname

Type string Tabletype(Table,View,Document,…)

NameInSource string Nameofthisgroupinthesource

IsPhysical boolean Trueifthisisasourcetable

SupportsUpdates boolean Trueifgroupcanbeupdated

UID string GroupuniqueID

Cardinality integer Approximatenumberofrowsinthegroup


SYS

435

IsSystem boolean Trueifinsystemtable

SchemaUID string ParentSchemauniqueID

SYS.VirtualDatabases

Thistablesuppliesinformationaboutthecurrentlyconnectedvirtualdatabase,ofwhichthereisalwaysexactlyone(inthecontextofaconnection).


Name string ThenameoftheVDB

Version string TheversionoftheVDB

SYS.spatial_sys_ref

SeealsothePostGISDocumentation


srid integer SpatialReferenceIdentifier

auth_name string Nameofthestandardorstandardsbody

auth_srid integer SRIDfortheauth_nameauthority

srtext string Well-KnownTextrepresentation

proj4text string ForusewiththeProj4library

SYS.GEOMETRY_COLUMNS

SeealsothePostGISDocumentation


F_TABLE_CATALOG string catalogname

F_TABLE_SCHEMA string schemaname

F_TABLE_NAME string tablename

F_GEOMETRY_COLUMN string columnname

COORD_DIMENSION integer Numberofcoordinatedimensions

SRID integer SpatialReferenceIdentifier

TYPE string Geometrytypename

SYS

436

http://postgis.net/docs/using_postgis_dbmanagement.html#spatial_ref_sys

http://postgis.net/docs/using_postgis_dbmanagement.html#geometry_columns

Procedures

SYS.getXMLSchemas

Returnsaresultsetwithasinglecolumn,schema,containingtheschemasasxml.

SYS.getXMLSchemas(INdocumentstringNOTNULL)RETURNSTABLE(schemaxml)

SYS.ArrayIterate

Returnsaresultsetwithasinglecolumnwitharowforeachvalueinthearray.

SYS.ArrayIterate(INvalobject[])RETURNSTABLE(colobject)

ExampleArrayIterate

selectarray_get(cast(x.colasstring[]),2)from(execarrayiterate((('a','b'),('c','d'))))x

Thiswillproducetworows-'b',and'd'.

SYS

437

SYSADMINSchemaSystemschemaforadministrativeinformationandactions.

TableofContentsTables/Views

SYSADMIN.UsageSYSADMIN.MatViewsSYSADMIN.VDBResourcesSYSADMIN.TriggersSYSADMIN.ViewsSYSADMIN.StoredProcedures

ProceduresSYSADMIN.isLoggableSYSADMIN.logMsgSYSADMIN.refreshMatViewSYSADMIN.refreshMatViewRowSYSADMIN.refreshMatViewRowsSYSADMIN.setColumnStatsSYSADMIN.setPropertySYSADMIN.setTableStatsSYSADMIN.matViewStatusSYSADMIN.loadMatViewSYSADMIN.updateMatView

Tables/Views

SYSADMIN.Usage

Thistablesuppliesinformationabouthowviews/proceduresaredefined.



UID string ObjectUID

object_type string Typeofobject(StoredProcedure,View,etc.)

Name string ObjectNameorparentnameifElementNameisnotnull

ElementName string Nameofcolumnorparameter

Uses_UID string UsedobjectUID

Uses_object_type string Usedobjecttype

Uses_SchemaName string Usedobjectschema

SYSADMIN

438

Uses_Name string UsedobjectnameorparentnameifUses_ElementNameisnotnull

Uses_ElementName string Usedcolumnorparametername

ExampleSYSADMIN.Usage

SELECT*FROMSYSADMIN.Usage

SYSADMIN.MatViews

Thistablesuppliesinformationaboutallthematerailizedviewsinthevirtualdatabase.




Name string Shortgroupname

TargetSchemaName stringNameofthematerializedtableschema.Willbenullforinternalmaterialization.

TargetName string Nameofthematerializedtable

Valid booleanTrueifmaterializedtableiscurrentlyvalid.Willbenullforexternalmaterialization.

LoadState boolean

Theloadstate,canbeoneofNEEDS_LOADING,LOADING,LOADED,FAILED_LOAD.Willbenullforexternalmaterialization.

Updated timestampThetimestampofthelastfullrefresh.Willbenullforexternalmaterialization.

Cardinality integerThenumberofrowsinthematerializedviewtable.Willbenullforexternalmaterialization.

Valid,LoadState,Updated,andCardinalitymaybecheckedforexternalmaterializedviewswiththeSYSADMIN.matViewStatusprocedure.

ExampleSYSADMIN.MatViews

SELECT*FROMSYSADMIN.MatViews

SYSADMIN.VDBResources

ThistableprovidesthecurrentVDBcontents.


SYSADMIN

439

resourcePath string Thepathtothecontents.

contents blob Thecontentsasablob.

ExampleSYSADMIN.VDBResources

SELECT*FROMSYSADMIN.VDBResources

SYSADMIN.Triggers

ThistableprovidestheTriggersinthevirtualdatabase.





Name string Triggername

TriggerType string TriggerType

TriggerEvent string TriggeringEvent

Status string IsEnabled

Body clob TriggerAction(FOREACHROW…)

TableUID string TableUniqueID

ExampleSYSADMIN.Triggers

SELECT*FROMSYSADMIN.Triggers

SYSADMIN.Views

ThistableprovidestheViewsinthevirtualdatabase.




Name string Viewname

Body clob ViewDefinitionBody(SELECT…)

UID string TableUniqueID

SYSADMIN

440

ExampleSYSADMIN.Views

SELECT*FROMSYSADMIN.Views

SYSADMIN.StoredProcedures

ThistableprovidestheStoredProceduresinthevirtualdatabase.




Name string Procedurename

Body clob ProcedureDefinitionBody(BEGIN…)

UID string UniqueID

ExampleSYSADMIN.StoredProcedures

SELECT*FROMSYSADMIN.StoredProcedures

Procedures

SYSADMIN.isLoggable

Testsifloggingisenabledatthegivenlevelandcontext.

SYSADMIN.isLoggable(OUTloggablebooleanNOTNULLRESULT,INlevelstringNOTNULLDEFAULT'DEBUG',INcontext

stringNOTNULLDEFAULT'org.teiid.PROCESSOR')

Returnstrueifloggingisenabled.levelcanbeoneofthelog4jlevels:OFF,FATAL,ERROR,WARN,INFO,DEBUG,TRACE.leveldefaultsto'DEBUG'andcontextdefaultsto'org.teiid.PROCESSOR'

ExampleisLoggable

IF((CALLSYSADMIN.isLoggable(context=>'org.something'))

BEGIN

DECLARESTRINGmsg;

//logictobuildthemessage...

CALLSYSADMIN.logMsg(msg=>msg,context=>'org.something')

END

SYSADMIN.logMsg

Logamessagetotheunderlyingloggingsystem.

SYSADMIN.logMsg(OUTloggedbooleanNOTNULLRESULT,INlevelstringNOTNULLDEFAULT'DEBUG',INcontextstring

NOTNULLDEFAULT'org.teiid.PROCESSOR',INmsgobjectNOTNULL)

SYSADMIN

441

Returnstrueifthemessagewaslogged.levelcanbeoneofthelog4jlevels:OFF,FATAL,ERROR,WARN,INFO,DEBUG,TRACE.leveldefaultsto'DEBUG'andcontextdefaultsto'org.teiid.PROCESSOR'

ExamplelogMsg

CALLSYSADMIN.logMsg(msg=>'somedebug',context=>'org.something')

Thiswilllogthemessage'somedebug'atthedefaultlevelDEBUGtothecontextorg.something.

SYSADMIN.refreshMatView

Fullrefresh/loadofaninternalmaterializedview.ReturnsintegerRowsUpdated.-1indicatesaloadisinprogress,otherwisethecardinalityofthetableisreturned.SeetheCachingGuideformore.

SeealsoSYSADMIN.loadMatView

SYSADMIN.refreshMatView(OUTRowsUpdatedintegerNOTNULLRESULT,INViewNamestringNOTNULL,INInvalidateboo

leanNOTNULLDEFAULT'false')

SYSADMIN.refreshMatViewRow

Refreshesarowinaninternalmaterializedview.

ReturnsintegerRowsUpdated.-1indicatesthematerializedtableiscurrentlyinvalid.0indicatesthatthespecifiedrowdidnotexistinthelivedataqueryorinthematerializedtable.SeetheCachingGuideformore.

SYSADMIN.CREATEFOREIGNPROCEDURErefreshMatViewRow(OUTRowsUpdatedintegerNOTNULLRESULT,INViewNamestring

NOTNULL,INKeyobjectNOTNULL,VARIADICKeyOtherobject)

ExampleofSYSADMIN.refreshMatViewRow

ThematerializedviewSAMPLEMATVIEWhas3rowsundertheTestMatModelasbelow:

Assumingtheprimarykeyonlycontainsonecolumn,id,updatethesecondrow:

EXECSYSADMIN.refreshMatViewRow('TestMat.SAMPLEMATVIEW','101')

Assumingtheprimarykeycontainsmorecolumns,aandb,updatethesecondrow:

EXECSYSADMIN.refreshMatViewRow('TestMat.SAMPLEMATVIEW','101','a1','b1')

SYSADMIN.refreshMatViewRows

Refreshesrowsinaninternalmaterializedview.

SYSADMIN

442

ReturnsintegerRowsUpdated.-1indicatesthematerializedtableiscurrentlyinvalid.AnyrowthatdoesnotexistinthelivedataqueryorinthematerializedtablewillnotcounttowardtheRowsUpdated.SeetheCachingGuideformore.

SYSADMIN.refreshMatViewRows(OUTRowsUpdatedintegerNOTNULLRESULT,INViewNamestringNOTNULL,VARIADICKey

object[]NOTNULL)

ExampleofSYSADMIN.refreshMatViewRows

ContinuingusetheSAMPLEMATVIEWinExampleofSYSADMIN.refreshMatViewRow.Assumingtheprimarykeyonlycontainsonecolumn,id,updateallrows:

EXECSYSADMIN.refreshMatViewRows('TestMat.SAMPLEMATVIEW',('100',),('101',),('102',))

Assumingtheprimarykeycomtainmorecolumns,id,aandbcomposeoftheprimarykey,updateallrows:

EXECSYSADMIN.refreshMatViewRows('TestMat.SAMPLEMATVIEW',('100','a0','b0'),('101','a1','b1'),('102','a2

','b2'))

SYSADMIN.setColumnStats

Setstatisticsforthegivencolumn.

SYSADMIN.setColumnStats(INtableNamestringNOTNULL,INcolumnNamestringNOTNULL,INdistinctCountlong,IN

nullCountlong,INmaxstring,INminstring)

Allstatvaluesarenullable.Passinganullstatvaluewillleavecorrespondingmetadatavalueunchanged.

SYSADMIN.setProperty

Setanextensionmetadatapropertyforthegivenrecord.ExtensionmetadataistypicallyusedbyTranslators.

SYSADMIN.setProperty(OUTOldValueclobNOTNULLRESULT,INUIDstringNOTNULL,INNamestringNOTNULL,IN"Va

lue"clob)

Settingavaluetonullwillremovetheproperty.

ExamplePropertySet

CALLSYSADMIN.setProperty(uid=>(SELECTuidFROMTABLESWHEREname='tab'),name=>'somename',value=>'somevalue'

)

Thiswillsettheproperty'somename'='somevalue'ontabletab.

Note Theuseofthisprocedurewillnottriggerreplanningofassociatedpreparedplans.

Propertiesfrombuilt-inteiid_*namespacescanbesetusingthetheshortform-namespace:keyform.

SYSADMIN.setTableStats

Setstatisticsforthegiventable.

SYSADMIN.setTableStats(INtableNamestringNOTNULL,INcardinalitylongNOTNULL)

SYSADMIN

443

NoteSYSADMIN.setColumnStats,SYSADMIN.setProperty,SYSADMIN.setTableStatsareMetadataProcedures.AMetadataRepositorymustbeconfiguredtomakeanon-temporarymetadataupdatepersistent.SeetheDeveloper’sGuideRuntimeMetadataUpdatessectionformore.

SYSADMIN.matViewStatus

matViewStatusisusedtoretrieveMaterializedviews'statusviaschemaNameandviewName.

ReturnstableswhichcontainsTargetSchemaName,TargetName,Valid,LoadState,Updated,Cardinality,LoadNumber,OnErrorAction.

SYSADMIN.matViewStatus(INschemaNamestringNOTNULL,INviewNamestringNOTNULL)RETURNSTABLE(TargetSchemaN

amevarchar(50),TargetNamevarchar(50),Validboolean,LoadStatevarchar(25),Updatedtimestamp,Cardinalityl

ong,LoadNumberlong,OnErrorActionvarchar(25))

SYSADMIN.loadMatView

loadMatViewisusedtoperformacompleterefreshofaninternalorexternalmaterializedtable.

ReturnsintegerRowsInserted.-1indicatesthematerializedtableiscurrentlyinvalid.And-3indicatestherewasanexceptionwhenperformingtheload.SeetheCachingGuideformore.

SYSADMIN.loadMatView(INschemaNamestringNOTNULL,INviewNamestringNOTNULL,INinvalidatebooleanNOTNULL

DEFAULT'false')RETURNSinteger

SYSADMIN.updateMatView

TheupdateMatViewprocedureisusedtoupdateasubsetofaninternalorexternalmaterializedtablebasedontherefreshcriteria.

ReturnsintegerRowsUpdated.-1indicatesthematerializedtableiscurrentlyinvalid.And-3indicatestherewasanexceptionwhenperformingtheupdate.SeetheCachingGuideformore.

SYSADMIN.updateMatView(INschemaNamestringNOTNULL,INviewNamestringNOTNULL,INrefreshCriteriastring)R

ETURNSinteger

SYSADMIN.updateMatView

ContinuingusetheSAMPLEMATVIEWinExampleofSYSADMIN.refreshMatViewRow.Updateviewrows:

EXECSYSADMIN.updateMatView('TestMat','SAMPLEMATVIEW','id=''101''ANDa=''a1''')

SYSADMIN

444

VDBsAVirtualDatabaseorVDBisthecoreabstractionlayerforTeiid.AVDBdefineshowtointegrateandexposeasetofsources.

VDBs

445

VDBDefinitionAVDBorvirtualdatabasedefinitioniscontainedinanXMLfile.For.vdbarchivefilescreatedinthedesigntool,thisfileisembeddedinthearchiveandmostfieldscanbeupdatedthroughtooling.TheXMLschemaforthisfilecanbefoundinthedocs/teiid/schemadirectory.

ExampleVDBXML

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



<description>...</description>



<connection-type>...</connection-type>



<propertyname="${property-name}"value="${property-value}"/>



<propertyname="lib"value="{module-name}"></property>

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



<modelvisible="true"name="${model-name}"type="${model-type}">

<propertyname="..."value="..."/>

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

i-name}">

<metadatatype="${repository-type}">rawtext</metadata>



</model>



<modelname="${model-name}"path="/Test/Customers.xmi">

<propertyname="multisource"value="true"/>

...

<sourcename="${source-name}"

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

<source.../>

<source.../>

</model>



<data-rolename="${role-name}">

<description>${role-description}</description>

….

</data-role>



<translatorname="${translator-name}"type="${translator-type}"/>

<propertyname="..."value="..."/>

</translator>

</vdb>

VDBDefinition

446

NotePropertySubstitution-Ifa-vdb.xmlfilehasdefinedpropertyvalueslike$\{my.property.name.value},thesecanbereplacedbyactualvaluesthataredefinedthroughJAVAsystemproperties.TodefinesystempropertiesonaWildFlyserver,pleaseconsultWildFlydocumentation.

WarningYoumaychoosetolocallynamevdbartifactsasyouwish,buttheruntimenamesofdeployedVDBartifactsmusteitherbe*.vdbforazipfileor*-vdb.xmlforanxmlfile.FailuretonamethedeploymentproperlywillresultinadeploymentfailureastheTeiidsubsystemwillnotknowhowtoproperlyhandletheartifact.

VDBElement

Attributes

name

ThenameoftheVDB.TheVDBnamereferencedthroughthedriverordatasourceduringtheconnectiontime.

version

TheversionoftheVDB.ProvidesanexplicitversioningmechanismtotheVDBname-seeVDBVersioning.

DescriptionElement

OptionaltextelementtodescribetheVDB.

ConnectionTypeElement

DetermineshowclientscanconnecttotheVDB.CanbeoneofBY_VERSION,ANY,orNONE.DefaultstoBY_VERSION.SeeVDBVersioning.

PropertyElements

cache-metadata

Canbe"true"or"false".defaultsto"false"for-vdb.xmldeploymentsotherwise"true".If"false",Teiidwillobtainmetadataonceforeverylaunchofthevdb."true"willsaveafilecontainingthemetadataintothePROFILE/data/teiiddirectory

query-timeout

SetsthedefaultquerytimeoutinmillisecondsforqueriesexecutedagainstthisVDB.0indicatesthattheserverdefaultquerytimeoutshouldbeused.Defaultsto0.Willhavenoeffectiftheserverdefaultquerytimeoutissettoalesservalue.Notethatclientscanstillsettheirowntimeoutsthatwillbemanagedontheclientside.

lib

Settoalistofmodulesforthevdbclasspathforuserdefinedfunctionloading.SeealsoSupportforUser-DefinedFunctions(Non-Pushdown).

security-domain

SettothesecuritydomaintouseifaspecificsecuritydomainisapplicabletotheVDB.Otherwisethesecuritydomainlistfromthetransportwillbeused.

<propertyname="security-domain"value="custom-security"/>

Note Anadminneedstoconfigureamatching"custom-security"loginmoduleinstandalone-teiid.xmlconfigurationfilebeforetheVDBisdeployed.

connection.XXX

VDBDefinition

447

ForusebytheODBCtransportandODatatosetdefaultconnection/executionproperties.SeeDriverConnectionforallproperties.Notethesearesetontheconnectionafterithasbeenestablished.

<propertyname="connection.partialResultsMode"value="true"/>

authentication-type

Authenticationtypeofconfiguredsecuritydomain.Allowedvaluescurrentlyare(GSS,USERPASSWORD).Thedefaultissetonthetransport(typicallyUSERPASSWORD).

password-pattern

Regularexpressionmatchedagainsttheconnectinguser’snamethatdeterminesifUSERPASSWORDauthenticationisused.password-patternTakesprecedenceofoverauthentication-type.Thedefaultisauthentication-type.

gss-pattern

Regularexpressionmatchedagainsttheconnectinguser’snamethatdeterminesifGSSauthenticationisused.gss-patternTakesprecedenceofoverpassword-pattern.Thedefaultispassword-pattern.

model.visible

Usedtooverridethevisibilityofimportedvdbmodels,wheremodelisthenameoftheimportedmodel.

include-pg-metadata

Bydefault,PGmetadataisalwaysaddedtoVDBunlessSystemPropertiessetpropertyorg.teiid.addPGMetadatatofalse.ThispropertyenablesaddingPGmetadataperVDB.PleasenotethatifyouareusingODBCtoaccessyourVDB,theVDBmustincludePGmetadata.

lazy-invalidate

BydefaultTTLexpirationwillbeinvalidating-seeInternalMaterialization.Settinglazy-invalidatetotruewillmakettlrefreshesnon-invalidating.

deployment-name

Effectivelyreserved.Willbesetatdeploytimebytheservertothenameoftheserverdeployment.

import-vdbElement

Attributes

name

ThenameoftheVDBtobeimported.

version

TheversionoftheVDBtobeimported(shouldbeanpositiveinteger).

import-data-policies

Optionalattributetoindicatewhetherthedatapoliciesshouldbeimportedaswell.Defaultsto"true".

ModelElement

Attributes

VDBDefinition

448

name

Thenameofthemodelisusedasatoplevelschemanameforallofthemetadataimportedfromtheconnector.ThenameshouldbeuniqueamongallModelsintheVDBandshouldnotcontainthe'.'character.

visible

Bydefaultthisvalueissetto"true",whenthevalueissetto"false",thismodelwillnotbevisibletowhenJDBCmetadataqueries.Usuallyitisusedtohideamodelfromclientapplicationsthatshouldnotdirectlyissuequeriesagainstit.However,thisdoesnotprohibiteitherclientapplicationorotherviewmodelsusingthismodel,iftheyknewtheschemaforthismodel.

PropertyElements

AllpropertiesareavailableasextensionmetadataonthecorrespondingSchemaobjectthatisaccessibleviathemetadataAPI.

cache-metadata

Canbe"true"or"false".defaultsto"false"for-vdb.xmldeploymentsotherwise"true".If"false",Teiidwillobtainmetadataonceforeverylaunchofthevdb."true"willsaveafilecontainingthemetadataintothePROFILE/data/teiiddirectoryCanbeusedtooverridethevdblevelcache-metadataproperty.

teiid_rel:DETERMINISM

Canbeoneof:DETERMINISMNONDETERMINISTICCOMMAND_DETERMINISTICSESSION_DETERMINISTICUSER_DETERMINISTICVDB_DETERMINISTICDETERMINISTIC

Willinfluencethecachescopeforresultsetcacheentriesformedfromaccessingthismodel.AlternativelythescopemaybeinfluencedthroughtheTranslatorAPIorviatable/procedureextensionmetadata.

SourceElement

Asourceisanamedbindingofatranslatorandconnectionsourcetoamodel.

name

Thenameofthesourcetouseforthismodel.Thiscanbeanynameyoulike,butwilltypicallybethesameasthemodelname.Havinganamedifferentthanthemodelnameisonlyusefulinmulti-sourcescenarios.Inmulti-source,thesourcenamesunderagivenmodelmustbeunique.Ifyouhavethesamesourceboundtomultiplemodelsitmayhavethesamenameforeach.Anexceptionwillberaisedifthesamesourcenameisusedfordifferentsources.

translator-name

ThenameortypeoftheTeiidTranslatortouse.Possiblevaluesincludethebuilt-intypes(ws,file,ldap,oracle,sqlserver,db2,derby,etc.)andtranslatorsdefinedinthetranslatorssection.

connection-jndi-name

TheJNDInameofthissource’sconnectionfactory.Thereshouldbeacorresponding"-ds.xml"filethatdefinestheconnectionfactoryintheJBossAS.CheckoutthedeployingVDBdependenciessectionforinfo.YoualsoneedtodeploytheseconnectionfactoriesbeforeyoucandeploytheVDB.

PropertyElements

importer.<propertyname>

Propertytobeusedbytheconnectorimporterforthemodelforpurposesimportingmetadata.Seepossiblepropertyname/valuesintheTranslatorspecificsection.Notethatusingthesepropertiesyoucannarroworwidenthedataelementsavailableforintegration.

MetadataElement

VDBDefinition

449

Theoptionalmetadataelementdefinesthemetadatarepositorytypeandoptionalrawmetadatatobeconsumedbythemetadatarepository.

type

Themetadatarepositorytype.DefaultstoINDEXforDesignerVDBsandNATIVEfornon-DesignerVDBsourcemodels.Forallotherdeployments/modelsavaluemustbespecified.Built-intypesincludeDDL,NATIVE,INDEX,andDDL-FILE.Theusageoftherawtextvarieswiththebytype.NATIVEandINDEX(onlyforDesignerVDBs)metadatarepositoriesdonotusetherawtext.TherawtextforDDLisexpectedtobebeaseriesofDDLstatementsthatdefinetheschema-seealsoDDLMetadata.DDL-FILE(usedonlywithzipdeployments)issimilartoDDL,exceptthattherawtextspecifiesanabsolutepathrelativetothevdbrootofthelocationofafilecontainingtheDDL.SeealsoCustomMetadataRepository.Usemorethan1metadataelementtodefinemultiplesourcesofmetadata.

TranslatorElementAttributes

name

ThenameofthetheTranslator.Referencedbythesourceelement.

type

ThebasetypeoftheTranslator.Canbeoneofthebuilt-intypes(ws,file,ldap,oracle,sqlserver,db2,derby,etc.).

PropertyElements

Setavaluethatoverridesatranslatordefaultproperty.Seepossiblepropertyname/valuesintheTranslatorspecificsection.

VDBDefinition

450

VDBsWithoutToolingTeiidintegrationisavailableviaaVDBwithouttheneedforTeiidDesignertooling.

VDBstaketwoforms-asimplexmldeploymentandafullzipfile.

XMLDeployment

YoucansimplycreateaSOME-NAME-vdb.xmlfile.TheXMLfilecapturesinformationabouttheVDB,thesourcesitintegrate,andpreferencesforimportingmetadata.

Note TheVDBnamepatternmustadhereto"-vdb.xml"fortheTeiidVDBdeployertorecognizethisfile.

Thevdb-deployer.xmlschemaforthisfileisavailableintheschemafolderunderthedocswiththeTeiiddistribution.

VDBZipDeployment

Formorecomplicatedscenariosyouarenotlimitedtojustanxmlfiledeployment.AfullzipfilesimilartoaDesignerVDBmayalsobedeployed.Inavdbzipdeployment:

Thedeploymentmustendwiththeextension.vdb

Thevdbxmlfilemustbenamevdb.xmlandplacedinthezipunder/META-INF/vdb.xml

Ifa/libfolderexistsanyjarsfoundunderneathwillautomaticallybeaddedtothevdbclasspath.

ForbackwardscompatabilitywithDesignerVDBs,ffany.INDEXfileexiststhedefaultmetadatarepositorywillbeassumedtobeINDEX.

FileswithintheVDBzipareaccessiblebyaCustomMetadataRepositoryusingtheMetadataFactory.getVDBResources()method,whichreturnsamapofallVDBResourcesintheVDBkeyedbyabsolutepathrelativetothevdbroot.

Thebuilt-inDDL-FILEmetadatarepositorytypemaybeusedtodefineDDL-basedmetadatainfilesoutsideofthevdb.xml.Thisimprovesthememoryfootprintofthevdbmetadataandthemaintainabilityofvdb.xml.

ExampleVDBZipStructure

/META-INF

vdb.xml

/ddl

schema1.ddl

/lib

some-udf.jar

Intheaboveexamplethevdb.xmlcoulduseaDDL-FILEmetadatatypeforschema1:

<modelname="schema1"...

<metadatatype="DDL-FILE">/ddl/schema1.ddl</metadata>

</model>

VDBsWithoutTooling

451

VDBsWithoutTooling

452

MultisourceModelsMultisourcemodelscanbeusedtoquicklyaccessdatainmultiplesourceswithhomogeneousmetadata.Whenyouhavemultipleinstancesusingidenticalschema(horizontalsharding),Teiidcanhelpyougatherdataacrossalltheinstances,using"multisource"models.Inthisscenario,insteadofcreating/importingamodelforeverydatasource,onesourcemodelisdefinedtorepresentstheschemaandisconfiguredwithmultipledata"sources"underneathit.Duringruntimewhenaqueryissuedagainstthismodel,thequeryengineanalyzestheinformationandgatherstherequireddatafromallsourcesconfiguredandgatherstheresultsandprovidesinasingleresult.Sinceallsourcesutilizethesamephysicalmetadata,thisfeatureismostappropriateforaccessingthesamesourcetypewithmultipleinstances.

Configuration

Tomarkamodelasmultisource,themodelpropertymultisourcecanbesettotrueormorethanonesourcecanbelistedforthemodelinthe"vdb.xml"file.Hereisacodeexampleshowingavdbwithsinglemodelwithmultiplesourcesdefined.

<vdbname="vdbname"version="1">

<modelvisible="true"type="PHYSICAL"name="Customers"path="/Test/Customers.xmi">

<propertyname="multisource"value="true"/>



<sourcename="chicago"

translator-name="oracle"connection-jndi-name="chicago-customers"/>

<sourcename="newyork"

translator-name="oracle"connection-jndi-name="newyork-customers"/>

<sourcename="la"

translator-name="oracle"connection-jndi-name="la-customers"/>

</model>

</vdb>

NOTECurrentlythetoolingsupportformanagingthemultisourcefeatureislimited,soifyouneedtousethisfeaturebuildtheVDBasusualintheTeiidDesignerandtheneditthe"vdb.xml"fileintheVDBarchiveusingaTexteditortoaddtheadditionalsourcesasdefinedabove.Youmustdeployaseparatedatasourceforeachsourcedefinedinthexmlfile.

Intheaboveexample,theVDBhasasinglemodelcalledCustomers,thathasmultiplesources(chicago,newyork,andla)thatdefinedifferentinstancesofdata.

TheMultisourceColumn

Whenamodelismarkedasmultisource,theenginewilladdoruseanexistingcolumnoneachtabletorepresentthesourcenamevalues.Intheabovevdb.xmlthecolumnwouldreturnchicago,la,newyorkforeachoftherespectivesources.ThenameofthecolumndefaultstoSOURCE_NAME,butisconfigurablebysettingthemodelpropertymultisource.columnName.Ifacolumnalreadyexistsonthetable(oranINprocedureparameter)withthesamename,theenginewillassumethatitshouldrepresentthemultisourcecolumnanditwillnotbeusedtoretrievephysicaldata.Ifthemultisourcecolumnisnotpresent,thegeneratedcolumnwillbetreatedasapseudocolumnwhichisnotselectableviawildcards(*nortbl.*).

Thisallowsquerieslikethefollowing:

select*fromtablewhereSOURCE_NAME='newyork'

updatetablecolumn=valuewhereSOURCE_NAME='chicago'

deletefromtablewherecolumn=xandSOURCE_NAME='la'

insertintotable(column,SOURCE_NAME)VALUES('value','newyork')

MultisourceModels

453

TheMulti-SourceColumninSystemMetadata

Thepseudocolumnisbydefaultnotpresentinyouractualmetadata;itisnotaddedonsourcetables/procedureswhenyouimportthemetadata.Ifyouwouldliketousethemultisourcecolumninyourtransformationstocontrolwhichsourcesareaccessedorupdatedand/orwantthecolumnreportedviametadatafacilities,thereareseveraloptions:

IfdirectlyusingDDL,thepseduo-columnwillalreadybeavailabletotransformations,butwillnotbepresentinyourSystemmetadatabydefault.IfusingDDLandwanttobeselective(ratherthanusingthemultisource.addColumnproperty),youcanmanuallyaddthecolumnviaDDL.

WitheitherVDBtypetomakethemultisourcecolumnpresentinthesystemmetadata,youmaysetthemodelpropertymultisource.addColumntotrueonamultisourcemodel.Ifthetablehasacolumnortheprocedurehasaparameteralreadywithamatchingname,thenanadditionalcolumnwillnotbeadded.Avariadicprocedurecanstillhaveasourceparameteradded,butitcanonlybespecifiedwhenusingnamedparameters.CareshouldbetakenthoughwhenusingthispropertyinDesignerasanytransformationlogic(views/procedures)thatyouhavedefinedwillnothavebeenawareofthemultisourcecolumnandmayfailvalidationuponserverdeployment.

IfusingDesigner,youcanmanuallyaddthemultisourcecolumn.

PlanningandExecutionTheplannerlogicallytreatsamultisourcetableasifitwereaviewcontainingtheunionalloftherespectivesourcetables.Morecomplexpartitioningscenarios,suchasheterogeneoussourcesorlistpartitioningwillrequiretheuseofaFederatedOptimizations#PartitionedUnion.

Mostofthefederatedoptimizationsavailableoverunionsarestillapplicableinmultisourcemode.Thisincludesaggregationpushdown/decomposition,limitpushdown,joinpartitioning,etc.

Youcanadd/removesourcesfrommultisourcemodelsatruntimewiththeadminaddSourceandremoveSourceoptions.Theprocessingofamultisourceplanwilldeterminethesetofmultisourcetargetswhentheaccessnodeisopened.Iftheplanisreusedandthesourceschangesincethelastexecution,themultisourceaccesswillberegenerated.Ifasourceisaddedafterarelevantmultisourcequerystarts,itwillnotbeintheresults.Ifasourceisremovedafterarelevantmultisourcequerystarts,itwillbetreatedasanullsourcewhichshouldinmostsituationsallowthequerytocompletenormally.

ThattheSHOWPLANoutputwillvaryuponwhenitisobtained.IfyougettheSHOWPLANoutputpriortoexecution,themultisourceaccesswillappearasasingleaccessnode.AfterexecutiontheSHOWPLANoutputwillshowthesetofsourcesaccessedasindividualnodes.

SELECTs,UPDATEs,DELETEs

AmultisourcequeryagainstaSELECT/UPDATE/DELETEmayaffectanysubsetofthesourcesbasedupontheevaluationoftheWHEREclause.

Themultisourcecolumnmaynotbetargetedinanupdatechangeset.

ThesumoftheupdatecountsforUPDATEs/DELETEswillbereturnedastheresultantupdatecount.

Whenrunningunderatransactioninamodethatdetectstheneedforatransactionandmultipleupdatesmayperformedoratransactionalreadisrequiredandmultiplesourcesmaybereadfrom,atransactionwillbestartedtoenlisteachsource.

INSERTs

AmultisourceINSERTmustusethesource_namecolumnasaninsertcolumntospecifywhichsourceshouldbetargetedbytheINSERT.OnlyanINSERTusingtheVALUESclauseissupported.

MultisourceModels

454

StoredProcedures

Aphysicalstoredproceduresrequirestheadditionofastringinparametermatchingthemultisourcecolumnnametospecifywhichsourcetheprocedureisexecutedon.Iftheparameterisnotpresentanddefaultstoanullvalue,thentheprocedurewillbeexecutedoneachsource.ItisnotpossibletoexecuteproceduresthatarerequiredtoreturnIN/OUT,OUT,orRETURNparametersvaluesonmorethan1source.

ExampleDDL

CREATEFOREIGNPROCEDUREPROC(arg1INSTRINGNOTNULL,arg2INSTRING,SOURCE_NAMEINSTRING)

ExampleCallsAgainstASingleSource

CALLPROC(arg1=>'x',SOURCE_NAME=>'sourceA')

EXECPROC('x','y','sourceB')

ExampleCallsAgainstAllSources

CALLPROC(arg1=>'x')

EXECPROC('x','y')

MultisourceModels

455

DDLMetadataDDLMetadatacanbeusedinsteadoforinadditiontometadatadefinedbyTeiidDesigner.

TableofContentsDDLMetadatainVDBModelsBNFnotationfortheMetadataCreateFOREIGNTableCreateView

CONSTRAINTSINSTEADOFTRIGGERS

CreateProcedure/FunctionOptionsALTERStatement

ALTERCOLUMNALTEROPTION

DataTypesNamespacesforExtensionMetadata

Built-inNamespacePrefixesFullExampleshowingaboveDDLbasedmetadata

DDLMetadatainVDBModels

StartingwithTeiid8.0,aVDBcandefinemodels/schemasusingDDL.HereissmallexampleofhowonecandefineaViewinsidethe"-vdb.xml"file.Seethe<metadata>elementunder<model>.

Exampletoshowviewdefinition

<modelvisible="true"type="VIRTUAL"name="customers">


CREATEVIEWPARTS(

PART_IDintegerPRIMARYKEY,

PART_NAMEvarchar(255),

PART_COLORvarchar(30),

PART_WEIGHTvarchar(255)

)AS

selecta.idasPART_ID,a.nameasPART_NAME,b.colorasPART_COLOR,b.weightasPART_WEIGHTf

rommodelA.parta,modelB.partbwherea.id=b.id

]]>

</metadata>

</model>

AnothercompleteDDLbasedexampleisattheendofthissection.

Note

MetadataRepositories-ThedeclarationofmetadatausingDDL,NATIVE,orDDL-FILEissupportedoutofthebox,howevertheMetadataRepositoryinterfaceallowsuserstoplug-intheirownmetadatafacilities.Forexample,youcanwriteaHibernatebasedstorethatcanfeedthenecessarymetadata.SeeCustomMetadataRepositoryformoreinformation.

Note MetadataforSourceModels-TheDDLbasedschemaisnotconstrainedtobedefinedonlyfortheviewmodels.

BNFnotationfortheMetadata

DDLMetadata

456

Note GrammarReference-ThefullgrammarforDDLcanbefoundintheBNFforSQLGrammar.

CreateFOREIGNTable

AFOREIGNtableistablethatisdefinedonPHYSICALmodelthatrepresentsarealrelationaltableinsourcedatabaseslikeOracle,SQLServeretc.Forrelationaldatabases,TeiidhascapabilitytoautomaticallyretrievethedatabaseschemainformationuponthedeploymentoftheVDB,ifoneliketoautoimporttheexistingschema.However,usercanusebelowFOREIGNtablesemantics,whentheywouldliketoexplicitlydefinetablesonPHYSICALmodelsorrepresentnon-relationaldataasrelationalincustomtranslators.

Example:CreateForeignTable(CreatedonPHYSICALmodel)

CREATEFOREIGNTABLECustomer(idintegerPRIMARYKEY,firstnamevarchar(25),lastnamevarchar(25),dobtimest

amp);

CREATEFOREIGNTABLEOrder(idintegerPRIMARYKEY,customeridinteger,saledatedate,amountdecimal(25,4),CO

NSTRAINTCUSTOMER_FKFOREGINKEY(customerid)REFERENCESCustomer(id));

CreateViewAviewisavirtualtable.Aviewcontainsrowsandcolumns,likearealtable.Thefieldsinaviewarefieldsfromoneormorerealtablesfromthesourceorotherviewmodels.Theycanalsobeexpressionsmadeupmultiplecolumns,oraggregatedcolumns.Whencolumndefinitionsarenotdefinedontheviewtable,theywillbederivedfromtheprojectedcolumnsoftheview’sselecttransformationthatisdefinedaftertheASkeyword.

Youcanaddfunctions,JOINstatementsandWHEREclausestoaviewdataasifthedatawerecomingfromonesingletable.

TABLE/VIEWOPTIONS:(thebelowarewellknownoptions,anyotherspropertiesdefinedwillbeconsideredasextensionmetadata)

Property DataTypeorAllowedValues Description

UUID string UniqueidentifierforView

MATERIALIZED 'TRUE'|'FALSE' Definesifatableismaterialized

MATERIALIZED_TABLE 'table.name'

Ifthisviewisbeingmaterializedtoaexternaldatabase,thisdefinesthenameofthetablethatisbeingmaterializedto

DDLMetadata

457

CARDINALITY intCostinginformation.Numberofrowsinthetable.Usedforplanningpurposes

UPDATABLE 'TRUE'|'FALSE' Definesiftheviewisallowedtoupdateornot

ANNOTATION string Descriptionoftheview

DETERMINISM

NONDETERMINISTIC,COMMAND_DETERMINISTIC,SESSION_DETERMINISTIC,USER_DETERMINISTIC,VDB_DETERMINISTIC,DETERMINISTIC

Onlycheckedonsourcetables

Example:CreateViewTable(CreatedonVIRTUALmodel)

CREATEVIEWCustomerOrders(namevarchar(50),saledatedate,amountdecimal)OPTIONS(CARDINALITY100,ANNOTAT

ION'Example')

AS

SELECTconcat(c.firstname,c.lastname)asname,o.saledateassaledate,o.amountasamountFROMCustomerCJO

INOrderoONc.id=o.customerid;

COLUMNOPTIONS:(thebelowarewellknownoptions,anyotherspropertiesdefinedwillbeconsideredasextensionmetadata)


UUID stringAuniqueidentifierforthecolumn

NAMEINSOURCE string

IfthisisacolumnnameontheFOREIGNtable,thisvaluerepresentsnameofthecolumninsourcedatabase,ifomittedthecolumnnameisused

DDLMetadata

458

whenqueryingfordataagainstthesource

CASE_SENSITIVE 'TRUE'|'FALSE'

SELECTABLE 'TRUE'|'FALSE'

TRUEwhenthiscolumnisavailableforselectionfromtheuserquery

UPDATABLE 'TRUE'|'FALSE'

Definesifthecolumnisupdatable.Defaultstotrueiftheview/tableisupdatable.

SIGNED 'TRUE'|'FALSE'

CURRENCY 'TRUE'|'FALSE'

FIXED_LENGTH 'TRUE'|'FALSE'

SEARCHABLE 'SEARCHABLE'|'UNSEARCHABLE'|'LIKE_ONLY'|'ALL_EXCEPT_LIKE'

columnsearchability,usuallydictatedbythedatatype

MIN_VALUE

MAX_VALUE

CHAR_OCTET_LENGTH integer

ANNOTATION string

NATIVE_TYPE string

RADIX integer

NULL_VALUE_COUNT long

costinginformation.NumberofNULLSinthiscolumn

DISTINCT_VALUES long

costinginformation.Numberofdistinctvaluesinthiscolumn

DDLMetadata

459

ColumnsmayalsobemarkedasNOTNULL,auto_increment,andwithaDEFAULTvalue.Currentlyonlystringvaluesaresupportedasthedefaultvalue.Tohavethestringinterpretedasanexpressionusetheextensionpropertyteiid_rel:default_handlingsettoexpression.

CONSTRAINTS

Constraintscanbedefinedontable/viewtodefineindexesandrelationshipstoothertables/views.ThisinformationisusedbytheTeiidoptimizertoplanqueriesorusetheindexesinmaterializationtablestooptimizetheaccesstothedata.

CONSTRAINTSaresameasonecandefineonRDBMS.

ExampleofCONSTRAINTs

CREATEVIEWCustomerOrders(namevarchar(50),saledatedate,amountdecimal,

CONSTRAINTEXAMPLE_INDEXINDEX(name,amount),

ACCESSPATTERN(name),

PRIMARYKEY...

INSTEADOFTRIGGERS

AviewcomprisingmultiplebasetablesmustuseanINSTEADOFtriggertosupportinserts,updatesanddeletesthatreferencedatainthetables.Basedontheselecttransformation’scomplexitysometimesINSTEADOFTRIGGERSareautomaticallyprovidedfortheuserwhen"UPDATABLE"OPTIONontheviewissetto"TRUE".However,usingtheCREATETRIGGERmechanismusercanprovide/overridethedefaultbehavior.

Example:DefineinsteadoftriggeronView

CREATETRIGGERONCustomerOrdersINSTEADOFINSERTAS

FOREACHROW

BEGINATOMIC

INSERTINTOCustomer(...)VALUES(NEW.value...);

END

DDLMetadata

460

CreateProcedure/Function

Usingthebelowsyntax,usercandefinea

SourceProcedure("CREATEFOREIGNPROCEDURE")-astoredprocedureinsource

SourceFunction("CREATEFOREIGNFUNCTION")-Afunctionthatissupportedbythesource,whereTeiidwillpushdowntosourceinsteadofevaluatinginTeiidengine

VirtualProcedure("CREATEVIRTUALPROCEDURE")-Similartostoredprocedure,howeverthisisdefinedusingtheTeiid’sProcedurelanguageandevaluatedintheTeiid’sengine.

Function/UDF("CREATEVIRTUALFUNCTION")-Auserdefinedfunction,thatcanbedefinedusingtheTeiidprocedurelanguageorcanhavetheimplementationdefinedusingaJAVAClass.

Seethefullgrammarforcreatefunction/procedureintheBNFforSQLGrammar.

VariableArgumentSupport

InsteadofusingjustanINparameter,thelastnonoptionalparametercanbedeclaredVARIADICtoindicatethatitcanberepeated0ormoretimeswhentheprocedureiscalled

Example:Varargprocedure

CREATEFOREIGNPROCEDUREproc(xinteger,VARIADICzinteger)returns(xstring);

FUNCTIONOPTIONS:(thebelowarewellknownoptions,anyotherspropertiesdefinedwillbeconsideredasextensionmetadata)


UUID string uniqueIdentifier

NAMEINSOURCE

Ifthisissourcefunction/procedurethenameinthephysicalsource,ifdifferentfromthelogicalnamegivenabove

DDLMetadata

461

ANNOTATION string Descriptionofthefunction/procedure

CATEGORY string FunctionCategory

DETERMINISM

NONDETERMINISTIC,COMMAND_DETERMINISTIC,SESSION_DETERMINISTIC,USER_DETERMINISTIC,VDB_DETERMINISTIC,DETERMINISTIC

Notusedonvirtualprocedures

NULL-ON-NULL 'TRUE'|'FALSE'

JAVA_CLASS string JavaClassthatdefinesthemethodincaseofUDF

JAVA_METHOD stringTheJavamethodnameontheabovedefinedjavaclassfortheUDFimplementation

VARARGS 'TRUE'|'FALSE'

Indicatesthatthelastargumentofthefunctioncanberepeated0toanynumberoftimes.defaultfalse.ItismorepropertouseaVARIADICparameter.

AGGREGATE 'TRUE'|'FALSE'

Indicatesthefunctionisauserdefinedaggregatefunction.Propertiesspecifictoaggregatesarelistedbelow.

NotethatNULL-ON-NULL,VARARGS,andalloftheAGGREGATEpropertiesarealsovalidrelationalextensionmetadatapropertiesthatcanbeusedonsourceproceduresmarkedasfunctions.SeealsoSourceSupportedFunctionsforcreatingFOREIGNfunctionsthataresupportedbyasource.

AGGREGATEFUNCTIONOPTIONS:


ANALYTIC 'TRUE'|'FALSE' indicatestheaggregatefunctionmustbewindowed.defaultfalse.

ALLOWS-ORDERBY 'TRUE'|'FALSE'indicatestheaggregatefunctionsupportsanORDERBYclause.defaultfalse

ALLOWS-DISTINCT 'TRUE'|'FALSE'indicatestheaggregatefunctionsupportstheDISTINCTkeyword.defaultfalse

DECOMPOSABLE 'TRUE'|'FALSE'

indicatesthesingleargumentaggregatefunctioncanbedecomposedasagg(agg(x))oversubsetsofdata.defaultfalse

USES-DISTINCT-ROWS 'TRUE'|'FALSE'indicatestheaggregatefunctioneffectivelyusesdistinctrowsratherthanallrows.defaultfalse

DDLMetadata

462

NotethatvirtualfunctionsdefinedusingtheTeiidprocedurelanguagecannotbeaggregatefunctions.

NoteProvidingtheJARlibraries-IfyouhavedefinedaUDF(virtual)functionwithoutaTeiidproceduredeinition,thenitmustbeaccompaniedbyitsimplementationinJava.ToconfiguretheJavalibraryasdependencytotheVDB,seeSupportforUser-DefinedFunctions

PROCEDUREOPTIONS:(thebelowarewellknownoptions,anyotherspropertiesdefinedwillbeconsideredasextensionmetadata)


UUID string UniqueIdentifier

NAMEINSOURCE string Inthecaseofsource

ANNOTATION string Descriptionoftheprocedure

UPDATECOUNT int

ifthisprocedureupdatestheunderlyingsources,whatistheupdatecount,whenupdatecountis>1theXAprotocolforexecutionisenforced

Example:DefineProcedure

CREATEVIRTUALPROCEDURECustomerActivity(customeridinteger)RETURNS(namevarchar(25),activitydatedate,amo

untdecimal)AS

BEGIN

...

END

Example:DefineVirtualFunction

CREATEVIRTUALFUNCTIONCustomerRank(customeridinteger)RETURNSintegerAS

BEGIN

...

END

ProcedurecolumnsmayalsobemarkedasNOTNULL,orwithaDEFAULTvalue.Currentlyonlystringvaluesaresupportedasthedefaultvalue.Tohavethestringinterpretedasanexpressionusetheextensionpropertyteiid_rel:default_handlingsettoexpression.OnasourceprocedureifyouwanttheparametertobedefaultableinthesourceprocedureandnotsupplyadefaultvalueinTeiid,thentheparametermustbenullableandusetheextensionpropertyteiid_rel:default_handlingsettoomit.

TherecanonlybeasingleRESULTparameteranditmustbeanoutparameter.ARESULTparameteristhesameashavingasinglenon-tableRETURNStype.Ifbotharedeclaredtheyareexpectedtomatchotherwiseanexceptionisthrown.Oneisnomorecorrectthantheother."RETURNStype"isshorterhandsyntaxespeciallyforfunctions,whiletheparameterformisusefulforadditionalmetadata(explicitname,extensionmetadata,alsodefiningareturnstable,etc.)

RelationalExtensionOPTIONS:


native-query ParameterizedString

Appliestobothfunctionsandprocedures.Thereplacementforthefunctionsyntaxratherthanthestandardprefixformwithparens.SeealsoTranslators#native

DDLMetadata

463

non-prepared boolean AppliestoJDBCproceduresusingthenative-queryoption.IftrueaPreparedStatementwillnotbeusedtoexecutethenativequery.

Example:NativeQuery

CREATEFOREIGNFUNCTIONfunc(xinteger,yinteger)returnsintegerOPTIONS("teiid_rel:native-query"'$1<<$2'

);

Example:SequenceNativeQuery

CREATEFOREIGNFUNCTIONseq_nextval()returnsintegerOPTIONS("teiid_rel:native-query"'seq.nextval');

Tip UntilTeiidprovideshigher-levelmetadatasupportforsequences,asourcefunctionrepresentationisthebestfittoexposesequencefunctionality.

Options

NoteAnyoptionnameoftheformprefix:keywillattempttoberesolvedagainstthecurrentsetofnamespaces.Failuretoresolvewillresultintheoptionnamebeingleftasis.Aresolvednamewillbereplacedwith{uri}key.SeealsoNamespacesforExtensionMetadata.

OptionscanalsobeaddedusingtheALTERstatement.SeeALTERstmt.

ALTERStatement

ALTERstatementscurrentlyprimarilysupportsaddingOPTIONSpropertiestoTables,ViewsandProcedures.UsingaALTERstatement,youcaneitheradd,modifyorremoveaproperty.

ALTERCOLUMN

DDLMetadata

464

ALTEROPTION

ExampleALTER

ALTERFOREIGNTABLE"customer"OPTIONS(ADDCARDINALITY10000);

ALTERFOREIGNTABLE"customer"ALTERCOLUMN"name"OPTIONS(SETUPDATABLEFALSE)

ALTERstatementsareespeciallyuseful,whenuserwouldliketomodify/enhancethemetadatathathasbeenimportedfromaNATIVEdatasource.Forexample,ifyouhaveadatabasecalled"northwind",andyouimportedthatmetadataandwouldliketoaddCARDINALITYtoits"customer"table,youcanuseALTERstatement,alongwith"chainable"metadatarepositoriesfeaturetoaddthispropertytothedesiredtable.Thebelowshowsanexample-vdb.xmlfile,thatillustratestheusage.

ExampleVDB


<vdbname="northwind"version="1">

<modelname="nw">

<propertyname="importer.importKeys"value="true"/>

<propertyname="importer.importProcedures"value="true"/>

<sourcename="northwind-connector"translator-name="mysql"connection-jndi-name="java:/nw-ds"/>

<metadatatype="NATIVE,DDL"><![CDATA[

ALTERFOREIGNTABLE"customer"OPTIONS(ADDCARDINALITY10000);

ALTERFOREIGNTABLE"customer"ALTERCOLUMN"name"OPTIONS(SETUPDATABLEFALSE);

]]>

</metadata>

</model>

</vdb>

DataTypesThefollowingarethesupporteddatatypesintheTeiid.

DDLMetadata

465

DDLMetadata

466

NamespacesforExtensionMetadata

WhendefiningtheextensionmetadatainthecaseofCustomTranslators,thepropertiesontables/views/procedures/columnscandefinenamespaceforthepropertiessuchthattheywillnotcollidewiththeTeiidspecificproperties.ThepropertyshouldbeprefixedwithaliasoftheNamespace.Prefixesstartingwithteiid_arereservedforusebyTeiid.

ExampleofNamespace

SETNAMESPACE'http://custom.uri'ASfoo

CREATEVIEWMyView(...)OPTIONS("foo:mycustom-prop"'anyvalue')

Built-inNamespacePrefixes

Prefix URI Description

teiid_rel http://www.teiid.org/ext/relational/2012Relationalextensions.Usesincludefunctionandnativequerymetadata

teiid_sf http://www.teiid.org/translator/salesforce/2012 Salesforceextensions.

FullExampleshowingaboveDDLbasedmetadata

FullExampleVDBwithViewDefinition


<vdbname="twitter"version="1">

<description>ShowshowtocallWebServices</description>

<modelname="twitter">

<sourcename="twitter"translator-name="rest"connection-jndi-name="java:/twitterDS"/>

</model>

<modelname="twitterview"type="VIRTUAL">


CREATEVIRTUALPROCEDUREgetTweets(queryvarchar)RETURNS(created_onvarchar(25),from_uservarch

ar(25),to_uservarchar(25),

profile_image_urlvarchar(25),sourcevarchar(25),textvarchar(140))AS

selecttweet.*from

(calltwitter.invokeHTTP(action=>'GET',endpoint=>querystring(",queryas"q")))w,

XMLTABLE('results'passingJSONTOXML('myxml',w.result)columns

created_onstringPATH'created_at',

from_userstringPATH'from_user',

to_userstringPATH'to_user',

profile_image_urlstringPATH'profile_image_url',

sourcestringPATH'source',

textstringPATH'text')tweet;

CREATEVIEWTweetASselect*FROMtwitterview.getTweets;

]]></metadata>

</model>

DDLMetadata

467

http://www.teiid.org/ext/relational/2012

http://www.teiid.org/translator/salesforce/2012

<translatorname="rest"type="ws">

<propertyname="DefaultBinding"value="HTTP"/>

<propertyname="DefaultServiceMode"value="MESSAGE"/>

</translator>

</vdb>

DDLMetadata

468

VDBReuseVDBsmayreuseotherVDBsdeployedinthesameserverinstancebyusingan"import-vdb"declarationinthevdb.xmlfile.AnimportedVDBcanhaveit’stablesandproceduresreferencedbyviewsandproceduresintheimportingVDBasiftheyarepartoftheVDB.ImportedVDBsarerequiredtoexistbeforeanimportingVDBmaystart.IfanimportedVDBisundeployed,thenanyimportingVDBwillbestopped.

AnimportedVDBincludesallofitsmodelsandmaynotconflictwithanymodel,datapolicy,orsourcealreadydefinedintheimportingVDB.OnceaVDBisimporteditismostlyoperationallyindependentfromthebaseVDB.OnlycostrelatedmetadatamaybeupdatedforanobjectfromanimportedVDBinthescopeoftheimportingVDB.AllotherupdatesmustbemadethroughtheoriginalVDB,buttheywillbevisibleinallimportedVDBs.EvenmaterializedviewsareseparatelymaintainedforanimportedVDBinthescopeofeachimportingVDB.

ExamplereuseVDBXML

<vdbname="reuse"version="1">

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

<modelvisible="true"type="VIRTUAL"name="new-model">


CREATEVIEWx(

yvarchar

)AS

select*fromold-model.tbl;

]]>

</metadata>

</model>

</vdb>

IntheaboveexamplethereuseVDBwillhaveaccesstoallofthemodelsdefinedinthecommonVDBandaddsinthe"new-model".

VDBReuse

469

RESTServiceThroughVDBWithhelpofDDLMetadatavarietyofmetadatacanbedefinedonVDBschemamodels.Thismetadataisnotlimitedtojustdefiningthetables,proceduresandfunctions.ThecapabilitiesofsourcesystemsoranyextensionstometadatacanalsobedefinedontheschemaobjectsusingtheOPTIONSclause.OnesuchextensionpropertiesthatTeiiddefinesistoexposeTeiidproceduresasRESTbasedservices.

ExposeTeiidProcedureasRestService

OnecandefinebelowRESTbasedpropertiesonaTeiidvirtualprocedure,andwhentheVDBisdeployedtheTeiidVDBdeployerwillanalysethemetadataanddeployaRESTserviceautomatically.WhentheVDBun-deployedtheRESTservicealsodeployed.

PropertyName Description IsRequired AllowedValues

METHOD HTTPMethodtouse Yes GET|POST|PUT|DELETE

URI URIofprocedure Yes ex:/procedure

PRODUCES Typeofcontentproducedbytheservice no xml|json|plain|anytext

CHARSET

WhenprocedurereturnsBlob,andcontenttypetextbased,thischaractersettousedtoconvertthedata

no US-ASCII|UTF-8

TheabovepropertiesmustbedefinedwithNAMESPACE`http://teiid.org/rest'onthemetadata.HereisanexampleVDBthatdefinestheRESTbasedservice.

ExampleVDBwithRESTbasedmetadataproperties



<propertyname="{http://teiid.org/rest}auto-generate"value="true"/>

<modelname="PM1">

<sourcename="text-connector"translator-name="loopback"/>


CREATEFOREIGNTABLEG1(e1string,e2integer);

CREATEFOREIGNTABLEG2(e1string,e2integer);

]]></metadata>

</model>

<modelname="View"type="VIRTUAL">


SETNAMESPACE'http://teiid.org/rest'ASREST;

CREATEVIRTUALPROCEDUREg1Table(INp1integer)RETURNSTABLE(xml_outxml)OPTIONS(UPDATECOUNT0,

"REST:METHOD"'GET',"REST:URI"'g1/{p1}')

AS

BEGIN

SELECTXMLELEMENT(NAME"rows",XMLATTRIBUTES(g1Table.p1asp1),XMLAGG(XMLELEMENT(NAME"row",

XMLFOREST(e1,e2))))ASxml_outFROMPM1.G1;

END

]]></metadata>

</model>

</vdb>


470

Note

<propertyname="\{http://teiid.org/rest[http://teiid.org/rest]}auto-generate"value="true"/>,canbeusedtocontrolthegenerationoftheRESTbasedWARbasedontheVDB.ThispropertyalongwithatleastoneprocedurewithRESTbasedextensionmetadataisrequiredtogenerateaRESTWARfile.Also,theprocedureneedstoreturnresultsetwithsinglecolumnofeitherXML,Clob,BloborString.WhenPRODUCESpropertyisnotdefined,thispropertyisderivedfromtheresultcolumnthatisprojectedout.

whentheaboveVDBisdeployedintheWildFly+Teiidserver,andiftheVDBisvalidandafterthemetadataisloadedthenaRESTwargeneratedautomaticallyanddeployedintothelocalWildFlyserver.TheRESTVDBisdeployedwith"{vdb-name}_{vdb-version}"context.Themodelnameisprependedtourioftheservicecall.Forexampletheprocedureinaboveexamplecanbeaccessedas

http://{host}:8080/sample_1/view/g1/123

where"sample_1"iscontext,"view"ismodelname,"g1"isURI,and123isparameter{p1}fromURI.IfyoudefinedaprocedurethatreturnsaXMLcontent,thenRESTservicecallshouldbecalledwith"accepts"HTTPheaderof"application/xml".Also,ifyoudefinedaprocedurethatreturnsaJSONcontentandPRODUCESpropertyisdefined"json"thenHTTPclientcallshouldincludethe"accepts"headerof"application/json".Inthesituationswhere"accepts"headerismissing,andonlyoneprocedureisdefinedwithuniquepath,thatprocedurewillbeinvoked.IftherearemultipleprocedureswithsameURIpath,forexampleonegeneratingXMLandanothergeneratingJSONcontentthen"accepts"headerdirectstheRESTengineastowhichprocedureshouldbeinvokedtogettheresults.Awrong"accepts"headerwillresultinerror.

"GETMethods"

WhendesigningtheproceduresthatwillbeinvokedthroughGETbasedcall,theinputparametersforprocedurescanbedefinedinthePATHoftheURI,asthe{p1}exampleabove,ortheycanalsobedefinedasqueryparameter,orcombinationofboth.Forexample

http://{host}:8080/sample_1/view/g1?p1=123

http://{host}:8080/sample_1/view/g1/123?p2=foo

MakesurethatthenumberofparametersdefinedontheURIandquerymatchtotheparametersdefinedonproceduredefinition.Ifyoudefinedadefaultvalueforaparameterontheprocedure,andthatparametergoingtobepassedinqueryparameteronURLthenyouhavechoicetoomitthatqueryparameter,ifyoudefinedasPATHyoumustsupplyavalueforit.

"POSTmethods"

'POST'methodsMUSTnotbedefinedwithURIwithPATHSforparametersasinGEToperations,theprocedureparametersareautomaticallyaddedas@FormParamannotationsonthegeneratedprocedure.AclientinvokingthisservicemustuseFORMtopostthevaluesfortheparameters.TheFORMfieldnamesMUSTmatchthenamesoftheprocedureparametersnames.

IfanyoneoftheprocedureparametersareBLOB,CLOBorXMLtype,thenPOSToperationcanbeonlyinvokedusing"multipart/form-data"RFC-2388protocol.ThisallowsusertouploadlargebinaryorXMLfilesefficientlytoTeiidusingstreaming".

"VARBINARYtype"

IfaparametertotheprocedureisVARBINARYtypethenthevalueoftheparametermustbeproperlyBASE64encoded,irrespectiveoftheHTTPmethodusedtoexecutetheprocedure.IfthisVARBINARYhaslargecontent,thenconsiderusingBLOB.

SecurityonGeneratedServices


471

http://teiid.org/rest

https://www.ietf.org/rfc/rfc2388.txt

BydefaultallthegeneratedRestbasedservicesaresecuredusing"HTTPBasic"withsecuritydomain"teiid-security"andwithsecurityrole"rest".However,thesepropertiescanbecustomizedbydefiningthetheninvdb.xmlfile.

Examplevdb.xmlfilesecurityspecification


<propertyname="{http://teiid.org/rest}auto-generate"value="true"/>

<propertyname="{http://teiid.org/rest}security-type"value="HttpBasic"/>

<propertyname="{http://teiid.org/rest}security-domain"value="teiid-security"/>

<propertyname="{http://teiid.org/rest}security-role"value="example-role"/>

...

</vdb>

_auto-generate-willautomaticallygeneratetheWARfileforthedeployedVDB

security-type-definesthesecuritytype.allowedvaluesare"HttpBasic"or"none".Ifomittedwilldefaultto"HttpBasic"

security-domain-definesJAASsecuritydomaintobeusedwithHttpBasic.Ifomittedwilldefaultto"teiid-security"

security-role-securityrolethatHttpBasicwillusetoauthorizetheusers.Ifomittedthevaluewilldefaultto"rest"

Note rest-security-itisourintentiontoprovideothertypesofsecuritieslikeKerberosandOAuth2infuturereleases.

SpecialAd-HocRestServices

Apartfromtheexplicitlydefinedprocedurebasedrestservices,thegeneratedjax-rswarfilewillalsoimplicitlyincludeaspecialrestbasedserviceunderURI"/query"thatcantakeanyXMLorJSONproducingSQLasparameterandexposetheresultsofthatqueryasresultoftheservice.Thisserviceisdefinedwith"POST",acceptingaFormParameternamed"sql".Forexample,afteryoudeploytheVDBdefinedinaboveexample,youcanissueaHTTPPOSTcallas

http://localhost:8080/sample_1/view/query

sql=SELECTXMLELEMENT(NAME"rows",XMLAGG(XMLELEMENT(NAME"row",XMLFOREST(e1,e2))))ASxml_outFROMPM1.G1

AsampleHTTPRequestfromJavacanbemadelikebelow

publicstaticStringhttpCall(Stringurl,Stringmethod,Stringparams)throwsException{

StringBufferbuff=newStringBuffer();

HttpURLConnectionconnection=(HttpURLConnection)newURL(url).openConnection();

connection.setRequestMethod(method);

connection.setDoOutput(true);

if(method.equalsIgnoreCase("post")){

OutputStreamWriterwr=newOutputStreamWriter(connection.getOutputStream());

wr.write(params);

wr.flush();

}

BufferedReaderserverResponse=newBufferedReader(newInputStreamReader(connection.getInputStream()));

Stringline;

while((line=serverResponse.readLine())!=null){

buff.append(line);

}

returnbuff.toString();

}

publicstaticvoidmain(String[]args)throwsException{

Stringparams=URLEncoder.encode("sql","UTF-8")+"="+URLEncoder.encode("SELECTXMLELEMENT(NAME"ro

ws",XMLAGG(XMLELEMENT(NAME"row",XMLFOREST(e1,e2))))ASxml_outFROMPM1.G1","UTF-8");

httpCall("http://localhost:8080/sample_1/view/query","POST",params);

}


472


473

MetadataRepositoriesTraditionallythemetadataforaVirtualDatabaseisbuiltbyTeiidDesignerandsuppliedtoTeiidenginethroughaVDBarchivefile.ThisVDBfilecontains.INDEXmetadatafiles.BydefaulttheyareloadedbyaMetadataRepositorywiththenameINDEX.Otherbuilt-inmetadatarepositoriesincludethefollowing:

NATIVE

Thisisonlyapplicableonsourcemodels(andisalsothedefault),whenusedthemetadataforthemodelisretrievedfromthesourcedatabaseitself.

Samplevdb.xmlfile




<metadatatype="NATIVE"></metadata>

</model>

</vdb>

DDL

Samplevdb.xmlfile




<metadatatype="DDL">

**DDLHere**

</metadata>

</model>

</vdb>

Thisisapplicabletobothsourceandviewmodels.SeeDDLMetadataformoreinformationonhowtousethisfeature.

FILE

Samplevdb.xmlfile




<metadatatype="DDL-FILE">/accounts.ddl</metadata>

</model>

</vdb>

DDLisapplicabletobothsourceandviewmodelsinzipVDBdeployments.SeeDDLMetadataformoreinformationonhowtousethisfeature.

ChainingRepositories


474

Whendefiningthemetadatatypeforamodel,multiplemetadataelementscanbeused.Alltherepositoryinstancesdefinedareconsultedintheorderconfiguredtogatherthemetadataforthegivenmodel.Forexample:

Samplevdb.xmlfile




<metadatatype="NATIVE"/>

<metadatatype="DDL">

**DDLHere**

</metadata>

</model>

</vdb>

Note Fortheabovemodel,NATIVEimporterisfirstused,thenDDLimporterusedtoaddadditionalmetadatatoNATIVEimportedmetadata.

Custom

SeeCustomMetadataRepository


475

TranslatorsTheTeiidConnectorArchitecture(TCA)providesTeiidwitharobustmechanismforintegratingwithexternalsystems.TheTCAdefinesacommonclientinterfacebetweenTeiidandanexternalsystemthatincludesmetadataastowhatSQLconstructsaresupportedforpushdownandtheabilitytoimportmetadatafromtheexternalsystem.

ATranslatoristheheartoftheTCAandactsasthebridgelogicbetweenTeiidandanexternalsystem,whichismostcommonlyaccessedthroughaJCAresourceadapter.RefertotheTeiidDevelopersGuidefordetailsondevelopingcustomTranslatorsandJCAresourceadaptersforusewithTeiid.

Tip TheTCAisnotthesameastheJCA,theJavaEEConnectorArchitecture,althoughtheTCAisdesignedforusewithJCAresourceadapters.

Tip TheimportcapabilitiesofTeiidTranslatorscanbeutilizedinTeiidDesignerviatheTeiidConnectionImporter.

ATranslatoristypicallypairedwithaparticularJCAresourceadapter.Ininstanceswherepooling,environmentdependentconfigurationmanagement,advancedsecurityhandling,etc.arenotneeded,thenaJCAresourceadapterisnotneeded.TheconfigurationofJCAConnectionFactoriesforneededresourceadaptersisnotpartofthisguide,pleaseseetheTeiidAdministratorGuideandthekitexamplesforconfiguringresourceadaptersforuseinJBossAS.

Translatorscanhaveanumberofconfigurableproperties.Thesearebrokendownintoexecutionproperties,whichdetermineaspectsofhowdataisretrieved,andimportsettings,whichdeterminewhatmetadataisreadforimport.

Theexecutionpropertiesforatranslatortypicallyhavereasonabledefaults.Forspecifictranslatortypes,e.g.theDerbytranslator,baseexecutionpropertiesarealreadytunedtomatchthesource.Inmostcasestheuserwillnotneedtoadjusttheirvalues.

Table1.BaseExecutionProperties-sharedbyalltranslators

Name Description Default

Immutable Settotruetoindicatethatthesourceneverchanges. false

RequiresCriteriaSettotruetoindicatethatsourceSELECT/UPDATE/DELETEqueriesrequireawhereclause.

false

SupportsOrderBy SettotruetoindicatethattheORDERBYclauseissupported. false

SupportsOuterJoins SettotruetoindicatethatOUTERJOINsaresupported. false

SupportsFullOuterJoinsIfouterjoinsaresupported,trueindicatesthatFULLOUTERJOINsaresupported.

false

SupportsInnerJoins SettotruetoindicatethatINNERJOINsaresupported. false

SupportedJoinCriteria

Ifjoinsaresupported,defineswhatcriteriamaybeusedasthejoincriteria.Maybeoneof(ANY,THETA,EQUI,orKEY).

ANY

Translators

476

MaxInCriteriaSize Ifincriteriaaresupported,defineswhatthemaximumnumberofinentriesareperpredicate.-1indicatesnolimit.

-1

MaxDependentInPredicates

Ifincriteriaaresupported,defineswhatthemaximumnumberofpredicatesthatcanbeusedforadependentjoin.Valueslessthan1indicatetouseonlyoneinpredicateperdependentvaluepushed(whichmatchesthepre-7.4behavior).

-1

DirectQueryProcedureName

ifthedirectqueryprocedureissupportedonthetranslator,thispropertyindicatesthenameoftheprocedure.

native

SupportsDirectQueryProcedureSettotruetoindicatethetranslatorsupportsthedirectexecutionofcommands

false

ThreadBoundSettotruetoindicatethetranslator’sExecutionsshouldbeprocessedbyonlyasinglethread

false

CopyLobs

Iftrue,thenreturnedlobs(clob,blob,sql/xml)willbecopiedbytheengineinamemorysafemanner.Usethisoptionifthesourcedoesnotsupportmemorysafelobsoryouwanttodisconnectlobsfromthesourceconnection.

false

TransactionSupport

Thehighestleveloftransactionsupport.UsedbytheengineasahinttodetermineifatransactionisneededforautoCommitTxn=DETECTmode.CanbeoneofXA,NONE,orLOCAL.IfXA,thenaccessunderatransactionwillbeserialized.

XA

Note Onlyasubsetofthesupportsmetadatacanbesetthroughexecutionproperties.Ifmorecontrolisneeded,pleaseconsulttheDeveloper’sGuide.

Therearenobaseimportersettings.

OverrideExecutionPropertiesForallthetranslatorstooverrideExecutionPropertiescanbeconfiguredinthevdb.xmlfile.

ExampleOverridingofTranslatorProperty

<modelname="ora">

<sourcename="ora"translator-name="oracle-override"connection-jndi-name="java:/oracle"/>

</model>

<translatorname="oracle-override"type="oracle">

<propertyname="RequiresCriteria"value="true"/>

Translators

477

</translator>

TheaboveXMLfragmentisoverridingtheoracletranslatorandalteringthebehaviorofRequiresCriteriapropertytotrue.NotethatthemodifiedtranslatorisonlyavailableinthescopeofthisVDB.

SeealsoVDBDefinition.

ParameterizableNativeQueriesInsomesituationstheteiid_rel:native-querypropertyandnativeproceduresacceptparameterizablestringsthatcanpositionallyreferenceINparameters.Aparameterreferencehastheform$integer,i.e.$1Notethat1basedindexingisusedandthatonlyINparametersmaybereferenced.Dollar-signintegeristhereforereserved,butmaybeescapedwithanother$,i.e.$$1.Thevaluewillbeboundasapreparedvalueoraliteralisasourcespecificmanner.Thenativequerymustreturnaresultsetthatmatchestheexpectationofthecallingprocedure.

Forexamplethenative-queryselectcfromgwherec1=$1andc2='$$1'resultsinaJDBCsourcequeryofselectcfromgwherec1=?andc2='$1',where?willbereplacedwiththeactualvalueboundtoparameter1.

Translators

478

AmazonSimpleDBTranslatorTheAmazonSimpleDBTranslator,knownbythetypenamesimpledb,exposesqueryingfunctionalitytoAmazonSimpleDBDataSources.

Note

"AmazonSimpleDB"-AmazonSimpleDBisawebserviceforrunningqueriesonstructureddatainrealtime.ThisserviceworksincloseconjunctionwithAmazonSimpleStorageService(AmazonS3)andAmazonElasticComputeCloud(AmazonEC2),collectivelyprovidingtheabilitytostore,processandquerydatasetsinthecloud.Theseservicesaredesignedtomakeweb-scalecomputingeasierandmorecost-effectivefordevelopers.Readmoreaboutitathttp://aws.amazon.com/simpledb/

ThistranslatorprovidesaneasywayconnecttoAmazonSimpleDBandprovidesrelationalwayusingSQLtoaddrecordsfromdirectlyfromuserorfromothersourcesthatareintegratedwithTeiid.Italsogivesabilitytoread/update/deleteexistingrecordsfromSimpleDBstore.

UsageAmazonSimpleDBishostedkey/valuestorewhereasinglekeycancontainhostmultipleattributename/valuepairswherewherevaluecanalsobeamulti-value.Thedatastructurecanberepresentedby

Basedonabovedatastructure,whenyouimportthemetadatafromSimpleDBintoTeiid,theconstructsarealignedasbelow

SimpleDBName SQL(Teiid)

Domain Table

ItemName Column(ItemName)PrimaryKey

attribute-singlevalue Column-StringDatatype

attribute-multivalue Column-StringArrayDatatype

Sinceallattributesarebydefaultareconsideredasstringdatatypes,columnsaredefinedwithstringdatatype.However,duringmodelingoftheschemainDesigner,onecanusevariousotherdatatypessupportedthroughTeiidtodefineadatatypeofcolumn,thatuserwishestoexposeas.

NoteIfyoudidmodifydatatypebeotherthanstringbased,becautionedanddonotusethosecolumnsincomparisonqueries,asSimpleDBdoesonlylexicographicalmatching.Toavoidit,setthe"SearchType"onthatcolumnto"UnSearchable".

AnExampleVDBthatshowsSimpleDBtranslatorcanbedefinedas


479

http://aws.amazon.com/simpledb/


<modelname="simpledb">

<sourcename="node"translator-name="simpledb"connection-jndi-name="java:/simpledbDS"/>

</model>

<vdb>

ThetranslatordoesNOTprovideaconnectiontotheSimpleDB.Forthatpurpose,TeiidhasaJCAadapterthatprovidesaconnectiontoSimpleDBusingAmazonSDKJavalibraries.Todefinesuchconnector,seeAmazonSimpleDBDataSourcesorseeanexamplein"<jboss-as>/docs/teiid/datasources/simpledb"

IfyouareusingDesignerTooling,tocreateVDB

Create/useaTeiidDesignerModelproject

Use"TeiidConnection>>SourceModel"importer,createSimpleDBDataSourceusingdatasourcecreationwizardandusesimpledbastranslatorintheimporter.Thetable(s)iscreatedinasourcemodelbythetimeyoufinishwiththisimporter,ifthedataisalreadydefinedonAmazonSimpleDB.

CreateaVDBanddeployintoTeiidServeranduseeitherjdbc,odbc,odataetctoquery.

PropertiesTheAmazonSimpleDBTranslatorcurrentlyhasnoimportorexecutionproperties.

CapabilitiesTheAmazonSimpleDBTranslatorsupportsSELECTstatementswitharestrictivesetofcapabilitiesincluding:comparisonpredicates,INpredicates,LIMITandORDERBY.Insert,update,deletearealsosupported.

QueriesonAttributeswithMultipleValues

Attributeswithmultiplevalueswilldefinedasstringarraytype.SothiscolumnistreatedSQLArraytype.ThebelowtableshowsSimpleDBwayofqueryingtoTeiidwaytoquery.Thequeriesarebasedonhttp://docs.aws.amazon.com/AmazonSimpleDB/latest/DeveloperGuide/RangeValueQueriesSelect.html

SimpleDBQuery TeiidQuery

select*frommydomainwhereRating='4stars'orRating='**' select*frommydomainwhereRating=('4stars','**')

select*frommydomainwhereKeyword='Book'andKeyword='Hardcover'

select*frommydomainwhereintersection(Keyword,'Book','Hardcover')

select*frommydomainwhereevery(Rating)='**' select*frommydomainwhereevery(Rating)='**'

WithInsert/Update/DeleteyouwritepreparestatementsoryoucanwriteSQLlike

INSERTINTOmydomain(ItemName,title,author,year,pages,keyword,rating)values('0385333498','TheSirens

ofTitan','KurtVonnegut',('1959'),('Book',Paperback'),('*****','5stars','Excellent'))

DirectQuerySupport

Thisfeatureisturnedoffbydefaultbecauseofthesecurityriskthisexposestoexecuteanycommandagainstthe


480

http://docs.aws.amazon.com/AmazonSimpleDB/latest/DeveloperGuide/RangeValueQueriesSelect.html

source.Toenablethisfeature,overridetheexecutionpropertycalledSupportsDirectQueryProceduretotrue.

Tip Bydefaultthenameoftheprocedurethatexecutesthequeriesdirectlyiscallednative.OverridetheexecutionpropertyDirectQueryProcedureNametochangeittoanothername.

TheSimpleDBtranslatorprovidesaproceduretoexecuteanyad-hocsimpledbquerydirectlyagainstthesourcewithoutTeiidparsingorresolving.Sincethemetadataofthisprocedure’sresultsarenotknowntoTeiid,theyarereturnedasanobjectarray.ARRAYTABLEcanbeusedconstructtabularoutputforconsumptionbyclientapplications.Directquerysupportedfor"select"basedcalls.

SELECTX.*

FROMsimpledb_source.native('SELECTfirstname,lastnameFROMusers')n,ARRAYTABLE(n.tupleCOLUMNSfirstname

string,lastnamestring)ASX

JCAResourceAdapter

TheTeiidspecificAmazonSimpleDBResourceAdaptershouldbeusedwiththistranslator.SeeAmazonSimpleDBDataSourcesforconnectingtoSimpleDB.


481

ApacheAccumuloTranslatorTheApacheAccumuloTranslator,knownbythetypenameaccumulo,exposesqueryingfunctionalitytoAccumuloDataSources.ApacheAccumuloisasorted,distributedkeyvaluestorewithrobust,scalable,highperformancedatastorageandretrievalsystem.ThistranslatorprovidesaneasywayconnecttoAccumulosystemandprovidesrelationalwayusingSQLtoaddrecordsfromdirectlyfromuserorfromothersourcesthatareintegratedwithTeiid.Italsogivesabilitytoread/update/deleteexistingrecordsfromAccumulostore.Teiidhascapabilitytopass-inloggedinuser’srolesasvisibilitypropertiestorestrictthedataaccess.

Tip "versions"-ThedevelopmentwasdoneusingAccumulo1.5.0,Hadoop2.2.0andZookeeper3.4.5

Note ThisdocumentassumesthatuserisfamiliarwithAccumulosourceandhasbasicunderstandingofhowTeiidworks.ThisdocumentonlycontainsdetailsaboutAccumulotranslator.

IntendedUsecasesTheusageAccumulotranslatorcanbehighlydependentonuser’susecase(s).Herearesomecommonscenarios.

AccumulosourcecanbeusedinTeiid,tocontinuallyadd/updatethedocumentsintheAccumulosystemfromothersourcesautomatically.

AccessAccumulothroughSQLinterface.

Makeuseofcelllevelsecuritythroughenterpriseroles.

AccumulotranslatorcanbeusedasanindexingsystemtogatherdatafromotherenterprisesourcessuchasRDBMS,WebService,SalesForceetc,allinsingleclientcalltransparentlywithoutanycoding.

Usage

ApacheAccumuloisdistributedkeyvaluestorewithuniquedatamodel.Itallowstogroupitskey-valuepairsinacollectioncalled"table".Thekeystructureisdefinedas

Basedonaboveinformation,onecandefineaschemarepresentingAccumulotablestructuresinTeiidusingDDLorusingTeiidDesignerwithhelpofmetadataextensionpropertiesdefinedbelow.Sincenodatatypeinformationisdefinedonthecolumns,bydefaultallcolumnsareconsideredasstringdatatypes.However,duringmodelingoftheschema,onecanusevariousotherdatatypessupportedthroughTeiidtodefineadatatypeofcolumn,thatuserwishestoexposeas.

OncethisschemaisdefinedandexposedthroughVDBinaTeiiddatabase,andAccumuloDataSourcesiscreated,theusercanissue"INSERT/UPDATE/DELETE"basedSQLcallstoinsert/update/deleterecordsintotheAccumulo,andissue"SELECT"basedcallstoretrieverecordsfromAccumulo.YoucanusefullrangeofSQLwithTeiidsystemintegratingothersourcesalongwithAccumulosource.


482

https://accumulo.apache.org/

Bydefault,Accumulotablestructureisflatcannotdefinerelationshipsamongtables.So,aSQLJOINisperformedinTeiidlayerratherthanpushedtosourceevenifbothtablesoneithersideoftheJOINresideintheAccumulo.CurrentlyanycriteriabasedonEQUALITYand/orCOMPARISONusingcomplexAND/ORclausesarehandledbyAccumulotranslatorandwillbeproperlyexecutedatsource.

AnExampleVDBthatshowsAccumulotranslatorcanbedefinedas


<modelname="accumulo">

<sourcename="node-one"translator-name="accumulo"connection-jndi-name="java:/accumuloDS"/>

</model>

<vdb>

ThetranslatordoesNOTprovideaconnectiontotheAccumulo.Forthatpurpose,TeiidhasaJCAadapterthatprovidesaconnectiontoAccumulousingAccumuloJavalibraries.Todefinesuchconnector,seeAccumuloDataSourcesorseeanexamplein"<jboss-as>/docs/teiid/datasources/accumulo"

IfyouareusingDesignerTooling,tocreateVDB


Use"TeiidConnection>>SourceModel"importer,createAccumuloDataSourceusingdatasourcecreationwizardanduseaccumuloastranslatorintheimporter.Thetableiscreatedinasourcemodelbythetimeyoufinishwiththisimporter.


PropertiesAccumulotranslatoriscapableoftraversingthroughAccumulotablestructuresandbuildametadatastructureforTeiidtranslator.TheschemaimportercanunderstandsimpletablesbytraversingasingleROWIDofdata,thenlooksforalltheuniquekeys,basedonititcomesupwithatabularstructureforAccumulobasedtable.Usingthefollowingimportproperties,youcanfurtherrefinetheimportbehavior.

ImportProperties


ColumnNamePattern Howthecolumnnameshouldbeformed false {CF}_{CQ}

ValueInWherethevalueforcolumnisdefinedCQorVALUE

false {VALUE}

Note{CQ},{CF},{ROWID}areexpressionsthatyoucanusetodefineabovepropertiesinanypattern,andrespectivevaluesofColumnQualifer,ColumnFamiliyorROWIDwillbereplacedatimporttime.ROWIDoftheAccumulotable,isautomaticallycreatedasROWIDcolumn,andwillbedefinedasPrimaryKeyonthetable.

YoucanalsodefinethemetadatafortheAccumulobasedmodel,usingDDLorusingtheTeiidDesigner.Whendoingsuchexercise,theAccumuloTranslatorcurrentlydefinesfollowingextendedmetadatapropertiestobedefinedonitsTeiidschemamodeltoguidethetranslatortomakeproperdecisions.ThefollowingpropertiesaredescribedunderNAMESPACE"http://www.teiid.org/translator/accumulo/2013",foruserconveniencethisnamespacehasaliasnameteiid_accumulodefindinTeiid.Todefineaextensionpropertyuseexpressionlike"teiid_accumulo:{property-name}value".AllthepropertiesbelowareintendedtobeusedasOPTIONpropertiesonCOLUMNS.SeeDDLMetadataformoreinformationondefiningDDLbasedmetadata.


483

ExtensionMetadataProperties


CF ColumnFamily true none

CQ ColumnQualifier false empty

VALUE-INValueofcolumndefinedin.Possiblevalues(VALUE,CQ)

false VALUE

HowtouseaboveProperties

Sayforexampleyouhaveatablecalled"User"inyourAccumuloinstance,anddoingascanreturnedfollowingdata

root@teiid>tableUser

root@teiidUser>scan

1name:age[]43

1name:firstname[]John

1name:lastname[]Does

2name:age[]10

2name:firstname[]Jane

2name:lastname[]Smith

3name:age[]13

3name:firstname[]Mike

3name:lastname[]Davis

IfyouusedthedefaultimporterfromtheAccumulotranslator(liketheVDBdefinedabove),thetablegeneratedwillbelikebelow

CREATEFOREIGNTABLE"User"(

rowidstringOPTIONS(UPDATABLEFALSE,SEARCHABLE'All_Except_Like'),

name_agestringOPTIONS(SEARCHABLE'All_Except_Like',"teiid_accumulo:CF"'name',"teiid_accumulo:CQ"'age'

,"teiid_accumulo:VALUE-IN"'{VALUE}'),

name_firstnamestringOPTIONS(SEARCHABLE'All_Except_Like',"teiid_accumulo:CF"'name',"teiid_accumulo:CQ"

'firstname',"teiid_accumulo:VALUE-IN"'{VALUE}'),

name_lastnamestringOPTIONS(SEARCHABLE'All_Except_Like',"teiid_accumulo:CF"'name',"teiid_accumulo:CQ"

'lastname',"teiid_accumulo:VALUE-IN"'{VALUE}'),

CONSTRAINTPK0PRIMARYKEY(rowid)

)OPTIONS(UPDATABLETRUE);

Youcanuse"ImportProperty"as"ColumnNamePattern"as"{CQ}"willgeneratethefollowing(notethenamesofthecolumn)

CREATEFOREIGNTABLE"User"(

rowidstringOPTIONS(UPDATABLEFALSE,SEARCHABLE'All_Except_Like'),

agestringOPTIONS(SEARCHABLE'All_Except_Like',"teiid_accumulo:CF"'name',"teiid_accumulo:CQ"'age',"t

eiid_accumulo:VALUE-IN"'{VALUE}'),

firstnamestringOPTIONS(SEARCHABLE'All_Except_Like',"teiid_accumulo:CF"'name',"teiid_accumulo:CQ"'fi

rstname',"teiid_accumulo:VALUE-IN"'{VALUE}'),

lastnamestringOPTIONS(SEARCHABLE'All_Except_Like',"teiid_accumulo:CF"'name',"teiid_accumulo:CQ"'las

tname',"teiid_accumulo:VALUE-IN"'{VALUE}'),

CONSTRAINTPK0PRIMARYKEY(rowid)

)OPTIONS(UPDATABLETRUE);


484

respectivelyifthecolumnnameisdefinedbyColumnFamily,youcanuse"ColumnNamePattern"as"{CF}",andifthevalueforthatcolumnexistsintheColumnQualifierthenyoucanuse"ValueIn"as"{CQ}".Usingimportpropertiesyoucandictatehowthetableshouldbemodeled.

Ifyoudidnotusebuiltinimport,andwouldliketomanuallydesignthetableinDesignerlikebelow

ThenyoumustmakesureyousupplytheExtensionMetadataPropertiesdefinedaboveontheUsertable’scolumnsfromAccumuloextendedmetadata(InDesigner,rightclickonModel,andselect"ModelExtensionDefinitions"andselectAccumulo.ForexampleonFirstNamecolumn,youwouldsupply

teiid_accumulo:CFname

teiid_accumulo:CQfirstname

teiid_accumulo:VALUE-INVALUE

andrepeatforeachandeverycolumn,sothatTeiidknowshowtocommunicatecorrectlywithAccumulo.

JCAResourceAdapterTheTeiidspecificAccumuloResourceAdaptershouldbeusedwiththistranslator.SeeAccumuloDataSourcesforconnectingtoaAccumuloSource.

NativeQueriesCurrentlythisfeatureisnotapplicable.BasedonuserdemandTeiidcouldexposeawayforusertosubmitaMAP-REDUCEjob.

DirectQueryProcedureThisfeatureisnotapplicableforthistranslator.


485

ApacheSOLRTranslatorTheApacheSOLRTranslator,knownbythetypenamesolr,exposesqueryingfunctionalitytoSolrDataSources.ApacheSolrisasearchenginebuiltontopofApacheLuceneforindexingandsearching.ThistranslatorprovidesaneasywayconnecttoexistingoranewSolrsearchsystem,andprovideswaytoadddocuments/recordsfromdirectlyfromuserorfromothersourcesthatareintegratedwithTeiid.Italsogivesabilitytoread/update/deleteexistingdocumentsfromSolrSearchsystem.

Properties

TheSolrTranslatorcurrentlyhasnoimportorexecutionproperties.Itdoesnotdefineanyextensionmetadata.

IntendedUsecases

TheusageSolrtranslatorcanbehighlydependentonuser’susecase(s).Herearesomecommonscenarios.

SolrsourcecanbeusedinTeiid,tocontinuallyadd/updatethedocumentsinthesearchsystemfromothersourcesautomatically.

IfthesearchfieldsarestoredinSolrsystem,thiscanbeusedasverylowlatencydataretrievalforservinghightrafficapplications.

Solrtranslatorcanbeusedasafastfulltextsearch.TheSolrdocumentcancontainonlytheindexinformation,thentheresultsasaninvertedindextogathertargetfulldocumentsfromtheotherenterprisesourcessuchasRDBMS,WebService,SalesForceetc,allinsingleclientcalltransparentlywithoutanycoding.

Usage

Solrsearchsystemprovidessearchesbasedonindexedsearchfields.EachSolrinstanceistypicallyconfiguredwithasinglecorethatdefinesmultiplefieldswithdifferenttypeinformation.Teiidmetadataqueryingmechanismisequippedwith"Luke"basedqueries,thatatdeploytimeoftheVDBusethismechanismtoretrieveallthestored/indexedfields.CurrentlyTeiiddoesNOTsupportdynamicfieldsandnon-storedfields.Basedonretrievedfields,Solrtranslatorexposesasingletablethatcontainsallthefields.Ifafieldismulti-valuebased,it’stypeisrepresentedasArraytype.

OncethistableisexposedthroughVDBinaTeiiddatabase,andSolrDataSourcesiscreated,theusercanissue"INSERT/UPDATE/DELETE"basedSQLcallstoinsert/update/deletedocumentsintotheSolr,andissue"SELECT"basedcallstoretrievedocumentsfromSolr.YoucanusefullrangeofSQLwithTeiidsystemintegratingothersourcesalongwithSolrsource.

TheSolrTranslatorsupportsSELECTstatementswitharestrictivesetofcapabilitiesincluding:comparisonpredicates,INpredicates,LIMITandOrderBy.

AnExampleVDBthatshowsSolrtranslatorcanbedefinedas

<vdbname="search"version="1">

<modelname="solr">

<sourcename="node-one"translator-name="solr"connection-jndi-name="java:/solrDS"/>

</model>

<vdb>


486

ThetranslatordoesNOTprovideaconnectiontotheSolr.Forthatpurpose,TeiidhasaJCAadapterthatprovidesaconnectiontoSolrusingtheSolrJJavalibrary.Todefinesuchconnector,seeSolrDataSourcesorseeanexamplein"<jboss-as>/docs/teiid/datasources/solr"

IfyouareusingDesignerTooling,tocreateVDBthen


Use"TeiidConnection>>SourceModel"importer,createSolrDataSourceusingdatasourcecreationwizardandusesolrastranslatorintheimporter.Thesearchtableiscreatedinasourcemodelbythetimeyoufinishwiththisimporter.


JCAResourceAdapterTheTeiidspecificSolrResourceAdaptershouldbeusedwiththistranslator.SeeSolrDataSourcesforconnectingtoaSolrSearchEngine.

NativeQueries

ThisfeatureisnotapplicableforSolrtranslator.

DirectQueryProcedure

ThisfeatureisnotavailableforSolrtranslatorcurrently.


487

CassandraTranslatorTheCassandraTranslator,knownbythetypenamecassandra,exposesqueryingfunctionalitytoCassandraDataSources.ThetranslatortranslatesTeiidpushdowncommandsintoCassandraCQL.

Properties

TheCassandraTranslatorcurrentlyhasnoimportorexecutionproperties.

Usage

TheCassandraTranslatorsupportsINSERT/UPDATE/DELETE/SELECTstatementswitharestrictivesetofcapabilitiesincluding:count(*),comparisonpredicates,INpredicates,andLIMIT.Onlyindexedcolumnsaresearchable.Consideracustomextensionorcreateanenhancementrequestshouldyourusagerequireadditionalcapabilities.

IfyouareusingDesignerTooling,tocreateVDBthen:


Use"TeiidConnection>>SourceModel"importer,createanewJBossDataSourceconnectionprofile,specifyingtheJNDInameforresourceadapterconfiguredhttps://docs.jboss.org/author/display/TEIIDCassandra+Data+Sources[datasource]andusecassandraastranslatortype.Thesourcemodelwillbecreatedwhenyoufinishwiththisimporter.


Cassandraupdatesalwaysreturnanupdatecountof1perupdateregardlessofthenumberofrowsaffected.

Cassandrainsertsarefunctionallyupserts,thatisifagivenrowexistsitwillbeupdatedratherthancausinganexception.

JCAResourceAdapter

TheTeiidspecificCassandraResourceAdaptershouldbeusedwiththistranslator.SeeCassandraDataSourcesforconnectingtoaCassandracluster.

NativeQueries

Cassandrasourceproceduresmaybecreatedusingtheteiid_rel:native-queryextension-seeParameterizableNativeQueries.Theprocedurewillinvokethenative-querysimilartoadirectprocedurecallwiththebenefitsthatthequeryispredeterminedandthatresultcolumntypesareknown,ratherthanrequiringtheuseofARRAYTABLEorsimilarfunctionality.


Thisfeatureisturnedoffbydefaultbecauseofthesecurityriskthisexposestoexecuteanycommandagainstthesource.Toenablethisfeature,overridetheexecutionpropertycalled_SupportsDirectQueryProceduretotrue.

Bydefaultthenameoftheprocedurethatexecutesthequeriesdirectlyiscallednative.Overridetheexecutionproperty_DirectQueryProcedureNametochangeittoanothername.

TheCassandratranslatorprovidesaproceduretoexecuteanyad-hocCQLquerydirectlyagainstthesourcewithoutTeiidparsingorresolving.Sincethemetadataofthisprocedure’sresultsarenotknowntoTeiid,theyarereturnedasanobjectarray.ARRAYTABLEcanbeusedconstructtabularoutputforconsumptionbyclientapplications.

ExampleCQLDirectQuery

SELECTX.*

FROMcassandra_source.native('SELECTfirstname,lastnameFROMusersWHEREbirth_year=$1ANDcountry=$2AL

CassandraTranslator

488

http://cassandra.apache.org/doc/cql/CQL.html

https://docs.jboss.org/author/display/TEIID

LOWFILTERING',1981,'US')n,

ARRAYTABLE(n.tupleCOLUMNSfirstnamestring,lastnamestring)ASX

CassandraTranslator

489

CoherenceCacheTranslatorTheCoherenceCachetranslator,knownbythenameofcoherence,isabridgeforreadingandwritingjavaobjectsto/fromanCoherenceCache.ThistranslatorextendstheObjectTranslatorandusesitforthecoreprocessingofreadingandwritingobjects.TheCoherenceCacheTranslatoriswrittensothatitcancontrolhowthecacheissearchedandanycapabilitiesthatareneededtocontrolthatbehavior.

SearchingCapabilities

CurrentsearchingcapabilitiesthatisperformedbythecacheisKeysearching.Futureenhancementsarebeingtargetedtoworkoutthedetailsforhowtheindexingcanbeconfiguredsothatsearchingonanyindexedcolumnispossible.

Installation

ThecoherencetranslatorisnotbuiltaspartofcoreTeiidbuild.Itsbeingstoredinaseparateteiid-coherencegithubrepositoryduetothecoherencejardependencyisnotavailableinapublicmavenrepo.SeetheREADME.mdforfulldetailsonbuildingandinstallation.

ExecutionProperties

Noneapplicableatthistime.

SupportedCapabilities

ThefollowingaretheconnectorcapabilitieswhenKeySearchingisused:

SELECTcommand

CompareCriteria-onlyEQ

InCriteria

Insert,Update,Delete

UsageRetrieveobjectsfromacacheandtransformintorowsandcolumns.

Performwritestothecache

Metadata

SeetheObjectTranslator#Metadatafordetailsondefiningthemetadata.

JCAResourceAdapter

SeetheCoherenceDatasourcesresourceadapterforthistranslator.


490

https://github.com/teiid/teiid-coherence/tree/master/translator-coherence

https://github.com/teiid/teiid-coherence/blob/master/README.md


491

DelegatingTranslatorsYoumaycreateadelegatingtranslatorbyextendingtheorg.teiid.translator.BaseDelegatingExecutionFactory.Onceyourclassesarethenpackagedasacustomtranslator,youwillbeabletowireanothertranslatorinstanceintoyourdelegatingtranslatoratruntimeinordertointerceptallofthecallstothedelegate.Thisbaseclassdoesnotprovideanyfunctionalityonitsown,otherthandelegation.

ExecutionProperties


Letssayyouarecurrentlyusing"oracle"translatorinyourVDB,youwanttointerceptthecallsgoingthroughthistranslator,thenyoufirstwriteacustomdelegatingtranslatorlike

@Translator(name="interceptor",description="interceptor")

publicclassInterceptorExecutionFactoryextendsorg.teiid.translator.BaseDelegatingExecutionFactory{

@Override

publicvoidgetMetadata(MetadataFactorymetadataFactory,Cconn)throwsTranslatorException{

//dointerceptingcodehere..

//Ifyouwantcalltheoriginaldelegate,donotcallifdonotneedto.

//butifyoudidnotcallthedelegatefullfillthemethodcontract

super.getMetadata(metadataFactory,conn);

//domoreinterceptingcodehere..

}

}

NowdeploythistranslatorinTeiidengine.Theninyour-vdb.xmlor.vdbfiledefinelikebelow.



<modelname="mymodel">

<sourcename="source"translator-name="oracle-interceptor"connection-jndi-name="java:oracle-ds"/>

</model>



<translatorname="orcle-interceptor"type="interceptor"/>

<propertyname="delegateName"value="oracle"/>

</translator>

</vdb>

Wehavedefineda"translator"overridecalled"oracle-interceptor",whichisbasedonthecustomtranslator"interceptor"fromabove,andsuppliedthetranslatoritneedstodelegateto"oracle"asitsdelegateName.Then,weusedthisoverridetranslator"oracle-interceptor"inyourVDB.NowanycallsgoingintothisVDBmodel’stranslatorwillbeinterceptedbyYOURcodetodowhateveryouwanttodo.

DelegatingTranslators

492

FileTranslatorThefiletranslator,knownbythetypenamefile,exposesstoredprocedurestoleveragefilesystemresourcesexposedbythefileresourceadapter.ItwillcommonlybeusedwiththeTEXTTABLEorXMLTABLEtablefunctionstouseCSVorXMLformatteddata.

ExecutionProperties


EncodingTheencodingthatshouldbeusedforCLOBsreturnedbythegetTextFilesprocedure

Thesystemdefaultencoding

ExceptionIfFileNotFoundThrowanexceptioningetFilesorgetTextFilesifthespecifiedfile/directorydoesnotexist.

true(falsepriorto8.2)

UsageRetrieveallfilesasBLOBswithanoptionalextensionatthegivenpath.

callgetFiles('path/*.ext')

Iftheextensionpathisspecified,thenitwillfilterallofthefileinthedirectoryreferencedbythebasepath.Iftheextensionpatternisnotspecifiedandthepathisadirectory,thenallfilesinthedirectorywillbereturned.Otherwisethesinglefilereferencedwillbereturned.Ifthepathdoesn’texist,thennoresultswillbereturnedifExceptionIfFileNotFoundisfalse,otherwiseanexceptionwillberaised.

RetrieveallfilesasCLOB(s)withtheanoptionalextensionatthegivenpath.

callgetTextFiles('path/*.ext')

AllthesamefilesagetFileswillberetrieved,theonlydifferenceisthattheresultswillbeCLOBvaluesusingtheencodingexecutionpropertyasthecharacterset.

SavetheCLOB,BLOB,orXMLvaluetogivenpath

callsaveFile('path',value)

Thepathshouldreferenceanewfilelocationoranexistingfiletooverwritecompletely.

NOTE Nativequeries-NativeordirectqueryexecutionisnotsupportedontheFileTranslator.

JCAResourceAdapter

Theresourceadapterforthistranslatorprovidedthrough"FileDataSource",RefertoAdminGuideforconfigurationinformation.

FileTranslator

493

FileTranslator

494

GoogleSpreadsheetTranslatorThegoogle-spreadsheettranslatorisusedtoconnecttoaGoogleSpreadsheet.TousetheGoogleSpreadsheetTranslatoryouneedtoconfigureanddeploytheGoogleJCAconnector-seetheAdminGuide.

Thequeryapproachexpectsthedataintheworksheettobeinaspecificformat.Namely:

Anycolumnthathasdataisqueryable.

Anynon-stringcolumnwithanemptycellhasthevalueretrievedasnull,otherwiseitistheemptystring.

Ifthefirstrowispresentandcontainsstringvalues,thenitwillbeassumedtorepresentthecolumnlabels.

Ifyouareusingthedefaultnativemetadataimport,themetadataforyourGoogleaccount(worksheetsandinformationaboutcolumnsinworksheets)areloadedupontranslatorstartup.Ifyoumakeanychangesindatatypes,itisadvisabletorestartyourvdb.

Thetranslatorsupportsqueriesagainstasinglesheet.Itsupportsordering,aggregation,basicpredicates,andmostofthefunctionssupportedbythespreadsheetquerylanguage.

Therearenogoogle-spreadsheetimportersettings,butitcanprovidemetadataforVDBs.

JCAResourceAdapterTheTeiidspecificGoogleSpreadsheetDataSourcesResourceAdaptershouldbeusedwiththistranslator.

NativeQueries

Googlespreadsheetsourceproceduresmaybecreatedusingtheteiid_rel:native-queryextension-seeParameterizableNativeQueries.Theprocedurewillinvokethenative-querysimilartoannativeprocedurecallwiththebenefitsthatthequeryispredeterminedandthatresultcolumntypesareknown,ratherthanrequiringtheuseofARRAYTABLEorsimilarfunctionality.SeetheSelectformatbelow.


Note Thisfeatureisturnedoffbydefaultbecauseofthesecurityriskthisexposestoexecuteanycommandagainstthesource.Toenablethisfeature,overridetheexecutionpropertycalled_SupportsDirectQueryProceduretotrue.

Tip Bydefaultthenameoftheprocedurethatexecutesthequeriesdirectlyiscallednative.Overridetheexecutionproperty_DirectQueryProcedureNametochangeittoanothername.

TheGooglespreadsheettranslatorprovidesaproceduretoexecuteanyad-hocquerydirectlyagainstthesourcewithoutanyTeiidparsingorresolving.Sincethemetadataofthisprocedure’sexecutionresultsarenotknowntoTeiid,theyarereturnedasanobjectarray.ARRAYTABLEcanbeusedconstructtabularoutputforconsumptionbyclientapplications.Teiidexposesthisprocedurewithasimplequerystructureasbelow:

Select

SelectExample

SELECTx.*FROM(callgoogle_source.native('worksheet=People;query=SELECTA,B,C'))w,

ARRAYTABLE(w.tupleCOLUMNS"id"string,"type"string,"name"String)ASx


495

thefirstargumenttakessemi-colon(;)separatednamevaluepairsoffollowingpropertiestoexecutetheprocedure:

Property Description Required

worksheet Googlespreadsheetname yes

query spreadsheetquery yes

limit numberrowstofetch no

offset offsetofrowstofetchfromlimitorbeginning no


496

InfinispanHotRodTranslatorTheInfinispanHotRodTranslator,knownbythetypeispn-hotrod,canreadthejavaobjectsfromaremoteInfinispanCacheviatheHotRodclientusingtheGoogleProtobufforserialization.ThiswillenableTeiidtoquerytheremotecacheusingJDGDSL.IfyouareusingJDGinlibrarymode,seethe[InfinispanLibraryModeTranslator]forthistypeofconfiguration.

Usage

Retrieveobjectsfromacacheandtransformintorowsandcolumns.

Supportsperformingwritestothecache

Useforexternalmaterializationtoimprovequeryperformance


Thefollowingaretheconnectorcapabilities:

CompareCriteria-EQ

CompareCriteriaOrdered-LT,GT,LE,GE-ifthesupportsCompareCriteriaOrderedtranslatoroverrideissettotrue.ItdefaultstofalseduetoanissuewithJDG.

And/OrCriteria

InCriteria

LikeCriteria

OrderBy

INSERT,UPDATE,DELETE(non-transactional)

ThefollowingwillnotbepusheddowntoJDGforprocessing,butwillbedonewithinTeiid:

Not(NE,<>)

IsNull

Limitations:

supportfor'Not'hasbeendisabled,becauseJDGconsiders<columnwhennull><>1tobetrueandSQLdoesnot.

booleandatatype:JDGwillthrowanexceptionifnovalueisspecifiedontheinsertorwhennodefaultvalueisdefinedintheprotobufdefinitionfile.

chardatatype:isnotasupportedtypeintheProtobufdatatypes(https://developers.google.com/protocol-buffers/docs/proto#scalar).WouldeitherhavetohandleconversionintheprotobufmarshallerorcreateaTeiidviewwiththedatatypeaschar.

1-to-Many,currentlyonlysupportsCollectionorArray,notMap’s'

WritetransactionsnotsupportedbyJDGwhenusingHotRodclient

Tobedone:

supportdeletingcontainingclass(s)(i.e.,person-→phones,deleteaphone)


497

https://issues.jboss.org/browse/TEIID-3627

https://developers.google.com/protocol-buffers/docs/proto#scalar

supportupdatingcontainingclass(s)

Installation

Theispn-hotrodtranslatorisnotconfigured,out-of-the-box,inthestandalone-teiid.xmlconfiguration.Toconfigurethetranslator,runtheadd-infinispan-hotrod-translator.cliscript.Thisscriptcanalsobefoundintheteiid-jboss-dist.zipkit,underdocs/teiid/datasources/infinispan.Seethejdg-remote-cachequickstartforanexample.Note,thisassumesyouwillbeinstallingaseparateJDGserver,whichwillbeaccessedviatheHotRodClientinstalledintotheTeiidserver.

ConfiguringPojoclass


Totakeadvantageofthecachebeingindexedenabled,shouldannotatetheclass.SeeJDGIndexingWithProtobufAnnotationsathttps://access.redhat.com/documentation/en-US/Red_Hat_JBoss_Data_Grid/6.6/html-single/Infinispan_Query_Guide/index.html#Custom_Fields_Indexing_with_Protobuf


Exampleclass:

publicclassPerson{

@ProtoField(number=2,required=true)

publicStringname;

@ProtoField(number=1,required=true)

publicintid;

@ProtoField(number=3)

publicStringemail;

privateList<PhoneNumber>phones;

publicStringgetName(){

returnname;

}

publicvoidsetName(Stringname){

this.name=name;

}

publicintgetId(){

returnid;

}

publicvoidsetId(intid){

this.id=id;

}

publicStringgetEmail(){

returnemail;

}

publicvoidsetEmail(Stringemail){

this.email=email;

}

publicList<PhoneNumber>getPhones(){

returnphones;

}

publicvoidsetPhones(List<PhoneNumber>phones){

this.phones=phones;

}

}


498

https://github.com/teiid/teiid/blob/master/build/kits/jboss-as7/docs/teiid/datasources/infinispan/add-infinispan-hotrod-translator.cli

https://docs.jboss.org/author/display/teiidexamples/JBoss+Data+Grid+Remote+Cache+as+a+Data+Source

https://access.redhat.com/documentation/en-US/Red_Hat_JBoss_Data_Grid/6.6/html-single/Infinispan_Query_Guide/index.html#Custom_Fields_Indexing_with_Protobuf




Metadata

OptionsforDefining

Thereareseveraloptionstodefiningthemetadatarepresentingyourobjectinthecache.

"Recommended"UsetheTeiidConnectionImporterinTeiidDesignertocreatethephysicalsourcemodelbasedonyourobjectcache.

UseTeiidDesignertomanuallycreatethephysicalsourcemodelbasedonyourobjectcacheusingthebelowDefinitionRequirements.

AsimpleVDBthatonlydefinesthedatasourcetouse.Example:

<modelname="People"type="Physical">

<propertyname="importer.useFullSchemaName"value="false"/>

<sourcename="infinispan-hotrod-connector"translator-name="ispn-hotrod"connection-jndi-name="java:/in

finispanRemoteDSL"/>

</model>

Themetadatawillberesolvedbyreverseengineeringthedefinedobjectinthecache.ThiscanbeusefulwhenusingtheTeiidDesignerTeiidConnectionImporterforbuildingthephysicalsourcemodel(s).

YoucanalsodefinethemetadatausingDDL.

Note,thisalsoshowsacontainerclass,PhoneNumber,asanexampleoftheforeignkeythat’sdefinestherelationship.

<vdbname="PeopleVDB"version="1">

<modelname="People"visible="true">


<sourcename="infinispan-cache-dsl-connector"translator-name="ispn-hotrod"connection-jndi-name="java:

/infinispanRemote"/>


CREATEFOREIGNTABLEPerson(

PersonObjectobjectOPTIONS(NAMEINSOURCE'this',UPDATABLEFALSE,SEARCHABLE'Unsearchable',NATIVE_TY

PE'java.lang.Object'),

idintegerNOTNULLOPTIONS(SEARCHABLE'Searchable',NATIVE_TYPE'int'),

namestringOPTIONS(SEARCHABLE'Searchable',NATIVE_TYPE'java.lang.String'),

emailstringOPTIONS(SEARCHABLE'Searchable',NATIVE_TYPE'java.lang.String'),

CONSTRAINTPK_IDPRIMARYKEY(id)

)OPTIONS(NAMEINSOURCE'PersonsCache',UPDATABLETRUE);

CREATEFOREIGNTABLEPhoneNumber(

numberstringOPTIONS(NAMEINSOURCE'phone.number',SEARCHABLE'Searchable',NATIVE_TYPE'java.lang.Str

ing'),

typestringOPTIONS(NAMEINSOURCE'phone.type',SEARCHABLE'Searchable',NATIVE_TYPE'java.lang.String'

),

idintegerNOTNULLOPTIONS(SELECTABLEFALSE,UPDATABLEFALSE,SEARCHABLE'Searchable',NATIVE_TYPE'i


499

nt'),

CONSTRAINTFK_PERSONFOREIGNKEY(id)REFERENCESPerson(id)OPTIONS(NAMEINSOURCE'phones')

)OPTIONS(NAMEINSOURCE'PersonsCache',UPDATABLETRUE);

]]></metadata>

</model>

</vdb>

DefinitionRequirements

Eachgoogleregisteredclassinthecachewillhaveacorrespondingtablecreated.

Thetablefortherootclass,musthaveaprimarykeydefined,whichmustmaptoanattributeintheclass.

Note ThedatatypefortheattributeintheclassmustmatchtheJDGcachekeydatatype.

Thetable"nameinsource"(NIS)willbethenameoftheJDGcachethistable/classisstored

Thetablecolumnswillbecreatedfromthegoogleprotobufdefinition,thatcorrespondstoaregisteredclass.

ColumnswillbeidentifiedasSEARCHABLEifeithertheprotobufdefinitionforacolumnindicatesitsindexedorthepojoclasshastheattribute/methodannotated.

Attributesdefinedasrepeatable(i.e.,collections,arrays,etc.)oracontainerclass,willbesupportedas1-to-*relationships,andwillhavecorrespondingregisteredclass(iftheyaretobesearched).

A1-to-*relationshipclassmusthaveaforeignkeytomaptotherootclass/table,wherethenameinsourcefortheforeignkeyisthenameoftherootclassmethodtoaccessthosechildobjects.Note,thisistheclassmethod,notareferenceinthegoogleprotobufdefinition.

Acontainer/childclasswillhaveattributeswheretheNIScontainaperiod.Example:phone.number.ThisisbecausethismapstotogoogleprotobufdefinitionandwhatisexpectedtobeusedintheDSLquery.


Thistranslatorsupportsusingthecacheforexternalmaterialization.However,therearespecificconfigurationchangesthatarerequiredatthe[Infinispan-HotRodresource-adapter]andatthetranslator.

NativeQueries

ExternalmaterializationisenabledbytheuseofnativequeriesintheBEFORE_LOAD_SCRIPTandAFTER_LOAD_SCRIPT.Atranslatoroverridewillneedtobesettoenablenativequeries:SupportsNativeQueries=true

Thefollowingmaterializationpropertiesmustbedefined:

Script Nativequery Description

teiid_rel:MATVIEW_BEFORE_LOAD_SCRIPT truncatecache Totruncatethecacheidentifiedasthestagingcache

teiid_rel:MATVIEW_AFTER_LOAD_SCRIPT swapcachenames

Toswapthealiasesforthecaches,sothattheprimarycachepointstotherecentlyloadedcache

ThefollowingisanexampleoffordefiningtheloadscriptsinDDL:


500

..

"teiid_rel:MATVIEW_BEFORE_LOAD_SCRIPT"'executeStockMatCache.native(''truncatecache'');',

"teiid_rel:MATVIEW_LOAD_SCRIPT"'insertintoStockMatCache.Stock(productId,symbol,price,companyName)SELECT

A.ID,S.symbol,S.price,A.COMPANY_NAMEFROMStocks.StockPricesASS,Accounts.PRODUCTASAWHERES.symbol=

A.SYMBOL',

"teiid_rel:MATVIEW_AFTER_LOAD_SCRIPT"'executeStockMatCache.native(''swapcachenames'');',

NativequeriesareusedtosimulatehowitsdoneusingRDBMSandrenamingtables,becauseInfinispandoesn’tcurrentlysupportrenamingacache.Sothenativequerieswilltriggertheclearingofthe"staging"cache,andtheswappingofthecachealiases.


Additionally,theexecutionofnativequeriesisdonethruthesupportofdirectqueryprocedures.Theproceduretobeexecutediscallednative.

{warning}Thisfeatureisturnedoffbydefaultbecauseofthesecurityriskthisexposestoexecuteanycommandagainstthesource.Toenablethisfeature,overridetheexecutionproperty[OverrideExecutionProperties]calledSupportsDirectQueryProceduretotrue.{warning}

JCAResourceAdapter

SeetheInfinispan-HotRodresourceadapterforthistranslator.ItcanbeconfiguredtolookupthecachecontainerviaJNDI,serverlist,orhotrodproperties.


501

InfinispanLibraryModeTranslatorTheInfinispanLibraryModetranslator,knownbythenameofispn-lib-mode,isabridgeforreadingandwritingjavaobjectsto/fromanInfinispan/JDGCache.ThistranslatorextendstheObjectTranslatorandusesitforthecoreprocessingofreadingandwritingobjects.TheInfinispanLibraryModeTranslatoriswrittensothatitcancontrolhowthecacheissearchedandanycapabilitiesthatareneededtocontrolthatbehavior.

ItisassumedthatyouwillbeinstallingtheJDGLibraryModeEAPModulesKit,whichcanbeobtainedontheRedHat’sCustomerPortalathttps://access.redhat.com/jbossnetwork/restricted/listSoftware.html.

IfyouareusingJDGtoaccessaremotecache,seetheInfinispanHotRodTranslatorforthistypeofconfiguration.



Useforexternalmaterializationtoimprovequeryperformance

SearchingOptions

Supportsthefollowingoptionsforsearching:

DSLsearching(JDG6.3+)

Hibernate/Lucenesearching(nowdeprecated)

Keysearching(whennoindexingisused).

Seethejdg-local-cachequickstartforanexample.



SELECTcommand


InCriteria

ThefollowingaretheconnectorcapabilitieswhenDSLSearchingisenabled:

SELECTcommand

CompareCriteria-EQ,NE

CompareCriteria-GT,LT,GE,andLEcanbeenabled,seeExecutionProperties

And/OrCriteria

InCriteria

LikeCriteria

OrCriteria


502

https://access.redhat.com/jbossnetwork/restricted/listSoftware.html

https://docs.jboss.org/author/display/teiidexamples/JBoss+Data+Grid+%28JDG%29+running+in+Library+Mode+as+a+Data+Source+Example

IsNullcheck-seeExecutionProperties

Not(negation)-example:NotIn,NotLike

INSERT,UPDATE,DELETE

InstallationTheispn-lib-modetranslatorisnotconfigured,out-of-the-box,inthestandalone-teiid.xmlconfiguration.Toconfigurethetranslator,runtheadd-infinispan-libmode-translator.cliscript.Thisscriptcanalsobefoundintheteiid-jboss-dist.zipkit,underdocs/teiid/datasources/infinispan.

ExecutionProperties

Name Description Required Default

SupportsLuceneSearching(Deprecated)

SettingtotrueassumesyourobjectsareannotatedandHibernate/Lucenewillbeusedtosearchthecache

No false

SupportsDSLSearchingSettingtotrueassumesyourareusingJDGv6.3orbetterandyourcachehasindexingenabled

No true

SupportsIsNullCriteriaSettingtotrueassumeshttps://issues.jboss.org/browse/TEIID-3539hasbeenresolved

No false

SupportsCompareCriteriaOrderedSettingtotrueassumeshttps://issues.jboss.org/browse/TEIID-3627hasbeenresolved

No false

SupportsNotCriteriaSettingtotrueassumeshttps://issues.jboss.org/browse/TEIID-3573hasbeenresolved

No false

SupportsNotCriteriadefaultstofalsebecausethetestingofcolum----n<>1returnstruewhenthecolumnisnull,whichisn’tcorrectbySQLstandards-seehttps://issues.jboss.org/browse/TEIID-3573.Thereisanenhancementcomingthatwillenableadding"columnISNOTNULL"whencolumn<>1typecriteriaisdetected.

SupportsIsNullCriteriadefaultstofalsebecauseInfinispan/JDGhasanissuewithissuingaISNULLcheckonanumerictypeattribute-seehttps://issues.jboss.org/browse/TEIID-3539.Setthistotrueifyouneedthischeckandcancontrolwhichnon-numericcolumnsthatthiswillbeissuedagainst.

SupportsCompareCriteriaOrdereddefaultstofalsebecausetheInfinispan/JDGhasanissuewithstringcomparisons-seehttps://issues.jboss.org/browse/TEIID-3627.

ConfiguringPojoclass


Totakeadvantageofthecachebeingindexedenabled,shouldannotatetheclass.SeeJDGdocumentationathttps://access.redhat.com/documentation/en-US/Red_Hat_JBoss_Data_Grid/6.6/html-single/Infinispan_Query_Guide/index.html#chap-Annotating_Objects_and_Querying



503

https://github.com/teiid/teiid/blob/master/build/kits/jboss-as7/docs/teiid/datasources/infinispan/add-infinispan-libmode-translator.cli







https://access.redhat.com/documentation/en-US/Red_Hat_JBoss_Data_Grid/6.6/html-single/Infinispan_Query_Guide/index.html#chap-Annotating_Objects_and_Querying

Exampleclass

@Indexed

publicclassStock{

@NumericField@Field(index=Index.YES,store=Store.YES,analyze=Analyze.NO)

publicintproductId;

@Field(index=Index.YES,store=Store.YES,analyze=Analyze.NO)

publicBigDecimalprice;


publicStringsymbol;


publicStringcompanyName;

publicintgetProductId(){

returnthis.productId;

}

publicvoidsetProductId(intid){

this.productId=id;

}

publicBigDecimalgetPrice(){

returnthis.price;

}

publicvoidsetPrice(BigDecimalprice){

this.price=price;

}

publicvoidsetPrice(doubleprice){

this.price=newBigDecimal(price);

}

publicStringgetSymbol(){

returnthis.symbol;

}

publicvoidsetSymbol(Stringsymbol){

this.symbol=symbol;

}

publicStringgetCompanyName(){

returncompanyName;

}

publicvoidsetCompanyName(Stringname){

this.companyName=name;

}

}




TheJDGcommonsmodule,org.infinispan.commons,slot="jdg-6.6"orslotforversioninstalled,needstohavethepojodependencyadded:

<modulename="{pojo_module_name}"export="true"/>


504

Metadata

OptionsforDefining

Therearecoupleoptionstodefiningthemetadatarepresentingyourobjectinthecache.

UsetheTeiidConnectionImporterinTeiidDesignertocreatethephysicalsourcemodelbasedonyourobjectcache.

DirectlydefinetheVDB

ThefollowingisaVDBexamplesimilartoquickstart(seegithubathttps://github.com/teiid/teiid-quickstarts/tree/master/jdg-local-cache).ItdefinesthephysicalsourceandwillusethetranslatornativeimporterlogictohavethemetadatareverseengineeredfromtheStockclass,seeabove,tobeexposedasthesourcetable.


<vdbname="Stocks"version="1">

<description>ShowshowtocallanInfinispanlocalcache</description>

<propertyname="UseConnectorMetadata"value="cached"/>

<propertyname="lib"value="com.client.quickstart.pojos"></property>

<modelname="StockCache"type="Physical">


<sourcename="StockSource"translator-name="infinispan1"connection-jndi-name="java:/infinispanLocal"/>

</model>

<translatorname="infinispan1"type="ispn-lib-mode">

<propertyname="SupportsDSLSearching"value="true"/>

</translator>

</vdb>



Thetable"nameinsource"(NIS)willbethenameofthecachethistable/classisstored

Theprimaryobjectthatrepresentsthecachedobjectshouldhaveanameinsourceof'this'.Allothercolumnswillhavetheirnameinsource(whichdefaultstothecolumnname)interpretedasthepathtothecolumnvaluefromtheprimaryobject.

AllcolumnsthatarenottheprimarykeynorcoveredbyaluceneindexshouldbemarkedasSEARCHABLE'Unsearchable'.



VDBsusingnativemetadataimportwillautomaticallybuildthephysicaltablefortherootobjectandwillhaveeachtoplevelmemberrepresentedasacolumn.

ExternalMaterializationThistranslatorsupportsusingthecacheforexternalmaterialization.However,therearespecificconfigurationchangesthatarerequiredattheInfinispanDataSourcesresource-adapterandatthetranslator.Foranexample,seethejdglocalquickstart.


505

https://github.com/teiid/teiid-quickstarts/tree/master/jdg-local-cache

https://github.com/teiid/teiid-quickstarts/tree/master/jdg-local-cache-materialization

NativeQueries

ExternalmaterializationisenabledbytheuseofnativequeriesintheBEFORE_LOAD_SCRIPTandAFTER_LOAD_SCRIPT.Atranslatoroverridewillneedtobesettoenablenativequeries:SupportsNativeQueries=true

Thefollowingmaterializationpropertiesmustbedefined:

Script Nativequery Description

teiid_rel:MATVIEW_BEFORE_LOAD_SCRIPT truncatecache Totruncatethecacheidentifiedasthestagingcache

teiid_rel:MATVIEW_AFTER_LOAD_SCRIPT swapcachenames

Toswapthealiasesforthecaches,sothattheprimarycachepointstotherecentlyloadedcache

ThefollowingisanexampleofdefiningthematerializationloadscriptsinDDL:

..

"teiid_rel:MATVIEW_BEFORE_LOAD_SCRIPT"'executeStockMatCache.native(''truncatecache'');',

"teiid_rel:MATVIEW_LOAD_SCRIPT"'insertintoStockMatCache.Stock(productId,symbol,price,companyName)SELECT

A.ID,S.symbol,S.price,A.COMPANY_NAMEFROMStocks.StockPricesASS,Accounts.PRODUCTASAWHERES.symbol=

A.SYMBOL',

"teiid_rel:MATVIEW_AFTER_LOAD_SCRIPT"'executeStockMatCache.native(''swapcachenames'');',

NativequeriesareusedtosimulatehowitsdoneusingRDBMSandrenamingtables,becauseInfinispandoesn’tcurrentlysupportrenamingacache.Sothenativequerieswilltriggertheclearingofthe"staging"cache,andtheswappingofthecachealiases.


Additionally,theexecutionofnativequeriesisdonethruthesupportofdirectqueryprocedures.Theproceduretobeexecutediscallednative.

WarningThisfeatureisturnedoffbydefaultbecauseofthesecurityriskthisexposestoexecuteanycommandagainstthesource.Toenablethisfeature,[overridetheexecutionproperty|Translators#OverrideExecutionProperties]calledSupportsDirectQueryProceduretotrue.

JCAResourceAdapterSeetheInfinispanDatasourcesresourceadapterforthistranslator.ItcanbeconfiguredtolookupthecachecontainerviaJNDIorcreated(i.e.,ConfigurationFileName).


506

JDBCTranslatorsTheJDBCtranslatorsbridgebetweenSQLsemanticanddatatypedifferencesbetweenTeiidandatargetRDBMS.Teiidhasarangeofspecifictranslatorsthattargetthemostpopularopensourceandproprietarydatabases.

Usage

UsageofaJDBCsourceisstraight-forward.UsingTeiidSQL,thesourcemaybequeriedasifthetablesandprocedureswerelocaltotheTeiidsystem.

Ifyouareusingarelationaldatasource,oradatasourcethathasaJDBCdriver,andyoudonotfindaspecifictranslatoravailableforthatdatasourcetype,thenstartwiththeJDBCANSITranslator.TheJDBCANSITranslatorshouldenableyoutoperformtheSQLbasics.Iftherespecificdatasourcecapabilitiesthatarenotavailable,thenconsiderusingtheTranslatorDevelopmenttocreatewhatyouneed.OrlogaTeiidJirawithyourrequirements.

ExecutionProperties-sharedbyallJDBCTranslators


DatabaseTimeZoneThetimezoneofthedatabase.Usedwhenfetchingsdate,time,ortimestampvalues.

Thesystemdefaulttimezone

DatabaseVersionThespecificdatabaseversion.Usedtofurthertunepushdownsupport.

ThebasesupportedversionorderivedfromtheDatabaseMetadata.getDatabaseProductVersionstring.AutomaticdetectionrequiresaConnection.Iftherearecircumstanceswhereyouaregettinganexceptionfromcapabilitiesbeingunavailable(mostlikelyduetoanissueobtainingaConnection),thensetDatabaseVersionproperty.UsetheJDBCExecutionFactory.usesDatabaseVersion()methodtocontrolwhetheryourtranslatorrequiresaconnectiontodeterminecapabilities.

TrimStrings

truetotrimtrailingwhitespacefromfixedlengthcharacterstrings.NotethatTeiidonlyhasastring,orvarchar,typethattreatstrailingwhitespaceasmeaningful.

false

UseBindVariables

truetoindicatethatPreparedStatementsshouldbeusedandthatliteralvaluesinthesourcequeryshouldbereplacewithbindvariables.IffalseonlyLOBvalueswilltriggertheuseofPreparedStatements.

true

UseCommentsInSourceQuery

Thiswillembedaleadingcommentwithsession/requestidinthesourceSQLfor

false

JDBCTranslators

507

https://jira.jboss.org/jira/browse/Teiid

informationalpurposes.CanbecustomizedwiththeCommentFormatproperty.

CommentFormat

MessageFormatstringtobeusedifUseCommentsInSourceQueryisenabled.Availableproperties:0-sessionidstring,1-parentrequestidstring,2-requestpartidstring,3-executioncountidstring,4-usernamestring,5-vdbnamestring,6-vdbversioninteger,7-istransactionalboolean

/teiidsessionid:{0},requestid:{1}.{2}/

MaxPreparedInsertBatchSize Themaxsizeofapreparedinsertbatch. 2048

StructRetrieval

StructretrievalmodecanbeoneofOBJECT-getObjectvaluereturned,COPY-returnedasaSerialStruct,ARRAY-returnedasanArray)

OBJECT

EnableDependentJoins

Forsourcesthatsupporttemporarytables(DB2,Derby,H2,HSQL2.0+,MySQL5.0+,Oracle,PostgreSQL,SQLServer,Sybase)allowdependentjoinpushdown

false

ImporterProperties-sharedbyallJDBCTranslators

Whenspecifyingtheimporterproperty,itmustbeprefixedwith"importer.".Example:importer.tableTypes


catalog SeeDatabaseMetaData.getTables[1] null

schemaPattern SeeDatabaseMetaData.getTables[1] null

tableNamePattern SeeDatabaseMetaData.getTables[1] null

procedureNamePattern SeeDatabaseMetaData.getProcedures[1] null

tableTypesCommaseparatedlist-withoutspaces-ofimportedtabletypes.SeeDatabaseMetaData.getTables[1]

null

excludeTables

Acase-insensitiveregularexpressionthatwhenmatchedagainstafullyqualifiedtablename[2]willexcludeitfromimport.Appliedaftertablenamesareretrieved.Useanegativelook-ahead(?!<inclusionpattern>).*toactasaninclusionfilter.

null

JDBCTranslators

508

http://docs.oracle.com/javase/7/docs/api/java/text/MessageFormat.html

excludeProcedures

Acase-insensitiveregularexpressionthatwhenmatchedagainstafullyqualifiedprocedurename[2]willexcludeitfromimport.Appliedafterprocedurenamesareretrieved.Useanegativelook-ahead(?!<inclusionpattern>).*toactasaninclusionfilter.

null

useFullSchemaName

Whenfalse,directstheimportertodropthesourcecatalog/schemafromtheTeiidobjectname,sothattheTeiidfullyqualifiednamewillbeintheformof<modelname>.<tablename>-Note:whenfalsethismayleadtoobjectswithduplicatenameswhenimportingfrommultipleschemas,whichresultsinanexception.Thisoptiondoesnotaffectthenameinsourceproperty.

true

importKeystruetoimportprimaryandforeignkeys-NOTEforeignkeystotablesthatarenotimportedwillbeignored

true

autoCreateUniqueConstraints truetocreateauniqueconstraintifoneisnotfoundforaforeignkeys true

importIndexes truetoimportindex/uniquekey/cardinalityinformation false

importApproximateIndexestruetoimportapproximateindexinformation.SeeDatabaseMetaData.getIndexInfo[1]

true

importProcedures

truetoimportproceduresandprocedurecolumns-Notethatitisnotalwayspossibletoimportprocedureresultsetcolumnsduetodatabaselimitations.Itisalsonotcurrentlypossibletoimportoverloadedprocedures.

false

widenUnsignedTypes

truetoconvertunsignedtypestothenextwidesttype.ForexampleSQLServerreportstinyintasanunsignedtype.Withthisoptionenabled,tinyintwouldbeimportedasashortinsteadofabyte.

true

quoteNameInSourcefalsewilloverridethedefaultanddirectTeiidtocreatesourcequeriesusingunquotedidentifiers.

true

useProcedureSpecificName

truewillallowtheimportofoverloadedprocedures(whichwillnormallyresultinaduplicateprocedureerror)byusingtheuniqueprocedurspecificnameastheTeiidname.ThisoptionwillonlyworkwithJDBC4.0compatibledriversthatreportspecificnames.

false

JDBCTranslators

509

useCatalogName

truewilluseanynon-null/non-emptycatalognameaspartofthenameinsource,e.g."catalog"."schema"."table"."column",andintheTeiidruntimenameifuseFullSchemaNameisalsotrue.falsewillnotusethecatalognameineitherthenameinsourceortheTeiidruntimename.Shouldbesettofalseforsourcesthatdonotfullysupportacatalogconcept,butreturnanon-nullcatalognameintheirmetadata-suchasHSQL.

true

useQualifiedName

truewillusenamequalificationforboththeTeiidnameandnameinsourceasdictatedbytheuseCatalogNameanduseFullSchemaNameproperties.SettofalsetodisableallqualificationforboththeTeiidnameandthenameinsource,whicheffectivelyignorestheuseCatalogNameanduseFullSchemaNameproperties.Note:whenfalsethismayleadtoobjectswithduplicatenameswhenimportingfrommultipleschemas,whichresultsinanexception.

true

useAnyIndexCardinality

truewillusethemaximumcardinalityreturnedfromDatabaseMetaData.getIndexInfo.importKeysorimportIndexesneedstobeenabledforthissettingtohaveaneffect.Thisallowsforbetterstatsgatheringfromsourcesthatdon’tsupportreturningastatisticalindex.

false

importStatistics

truewillusedatabasedependentlogictodeterminethecardinalityifnoneisdetermined.Notyetsupportedbyalldatabasetypes-currentlyonlysupportedbyOracleandMySQL.

false

importRowIdAsBinary truewillimportRowIdcolumnsasvarbinaryvalues. false

[1]JavaDocforDatabaseMetaData[2]Thefullyqualifiednameforexclusionisbaseduponthesettingsofthetranslatorandtheparticularsofthedatabase.Alloftheapplicablenamepartsusedbythetranslatorsettings(seeuseQualifiedNameanduseCatalogName)includingcatalog,schema,tablewillbecombinedascatalogName.schemaName.tableNamewithnoquoting.ForexampleOracledoesnotreportacatalog,sothenameusedwithdefaultsettingsforcomparisonwouldbejustschemaName.tableName.

WarningThedefaultimportsettingswillcrawlallavailablemetadata.Thisimportprocessistimeconsumingandfullmetadataimportisnotneededinmostsituations.Mostcommonlyyou’llwanttolimittheimportbyatleastschemaPatternandtableTypes.

Exampleimportersettingstoonlyimporttablesandviewsfrommy-schema.SeealsoVDBDefinition

<model...

JDBCTranslators

510

https://docs.oracle.com/javase/7/docs/api/java/sql/DatabaseMetaData.html

<propertyname="importer.tableTypes"value="TABLE,VIEW"/>

<propertyname="importer.schemaPattern"value="my-schema"/>

...

</model>

NativeQueries

Physicaltables,functions,andproceduresmayoptionallyhavenativequeriesassociatedwiththem.Novalidationofthenativequeryisperformed,itissimplyusedinastraight-forwardmannertogeneratethesourceSQL.Foraphysicaltablesettingtheteiid_rel:native-queryextensionmetadatawillexecutethenativequeryasaninlineviewinthesourcequery.Thisfeatureshouldonlybeusedagainstsourcesthatsupportinlineviews.Thenativequeryisusedasisandisnottreatedasaparameterizedstring.ForexampleonaphysicaltableywithnameInSource="x"andteiid_rel:native-query="selectcfromg",theTeiidsourcequery"SELECTcFROMy"wouldgeneratetheSQLquery"SELECTcFROM(selectcfromg)asx".NotethatthecolumnnamesinthenativequerymustmatchthenameInSourceofthephysicaltablecolumnsfortheresultingSQLtobevalid.

Forphysicalproceduresyoumayalsosettheteiid_rel:native-queryextensionmetadatatoadesiredquerystringwiththeaddedabilitytopositionallyreferenceINparameters-seeParameterizableNativeQueries.Theteiid_rel:non-preparedextensionmetadatapropertymaybesettofalsetoturnoffparameterbinding.NotethisoptionshouldbeusedwithcautionasinboundmayallowforSQLinjectionattacksifnotproperlyvalidated.Thenativequerydoesnotneedtocallastoredprocedure.AnySQLthatreturnsaresultsetpositionallymatchingtheresultsetexpectedbythephysicalstoredproceduremetadatawillwork.Forexampleonastoredprocedurexwithteiid_rel:native-query="selectcfromgwherec1=$1andc2=`$$1"',theTeiidsourcequery"CALLx(?)"wouldgeneratetheSQLquery"selectcfromgwherec1=?andc2=`$1"'.Notethat?inthisexamplewillbereplacedwiththeactualvalueboundtoparameter1.



Bydefaultthenameoftheprocedurethatexecutesthequeriesdirectlyisnative.Overridetheexecutionproperty_DirectQueryProcedureNametochangeittoanothername.

TheJDBCtranslatorprovidesaproceduretoexecuteanyad-hocSQLquerydirectlyagainstthesourcewithoutTeiidparsingorresolving.Sincethemetadataofthisprocedure’sresultsarenotknowntoTeiid,theyarereturnedasanobjectarray.ARRAYTABLEcanbeusedconstructtabularoutputforconsumptionbyclientapplications.

SelectExample

SELECTx.*FROM(calljdbc_source.native('select*fromg1'))w,

ARRAYTABLE(w.tupleCOLUMNS"e1"integer,"e2"string)ASx

InsertExample

SELECTx.*FROM(calljdbc_source.native('insertintog1(e1,e2)values(?,?)',112,'foo'))w,

ARRAYTABLE(w.tupleCOLUMNS"update_count"integer)ASx

UpdateExample

SELECTx.*FROM(calljdbc_source.native('updateg1sete2=?wheree1=?','blah',112))w,


DeleteExample

SELECTx.*FROM(calljdbc_source.native('deletefromg1wheree1=?',112))w,


JDBCTranslators

511

JCAResourceAdapter

TheresourceadapterforthistranslatorprovidedthroughdatasourceinWildFly,SeetoAdminGuidesectionWildFlyDataSourcesforconfiguration.

JDBCTranslators

512

ActianVectorTranslator(actian-vector)AlsoseecommonJDBCTranslatorInformation

TheActianVectorTranslator,knownbythetypenameactian-vector,isforuseActianVectorinHadoop.

DownloadtheJDBCdriverathttp://esd.actian.com/platform.NotetheportnumberinconnectionURLis"AH7"whichmapsto16967.

JDBCTranslators

513

http://esd.actian.com/Express/readme_HSE_2.0.html

http://esd.actian.com/platform

ApacheHBaseTranslator(hbase)AlsoseecommonJDBCTranslatorInformation

TheApacheHBaseTranslator,knownbythetypenamehbase,exposesqueryingfunctionalitytoHBaseTables.ApachePhoenixisaJDBCSQLinterfaceforHBase-seePhoenixDataSourcesthatisrequiredforthistranslatorasitpushesdowncommandsintoPhoenixSQL.

TheDatabaseTimezonepropertyshouldnotbeusedwiththistranslator.

TheHBaseTranslatordoesn’tsupportJoins.PhoenixusestheHBaseTableRowIDasthePrimaryKey,whichmapto.ThisTranslatorisdevelopedwithPhoenix4.3+forHBase0.98.1+.

NoteThetranslatorimplementsINSERT/UPDATEthroughthePhoenixUPSERToperation.ThismeansyoucanseedifferentbehaviorthanwithstandardINSERT/UPDATE-suchasrepeatedinsertswillnotthrowaduplicatekeyexception,butwillinsteadupdatetherowinquestion.

Note DuetoPhoenixdriverlimitationstheimporterwillnotlookforuniqueconstraintsanddefaultstonotimportingforeignkeys.

WarningThePhoenixdriverdoesnothaverobusthandlingoftimevalues.Ifyourtimevaluesarenormalizedtouseadatecomponentof1970-01-01,thenthedefaulthandlingwillworkcorrectly.Ifnot,thenthetimecolumnshouldbemodeledastimestampinstead.

JDBCTranslators

514

http://hbase.apache.org/

http://phoenix.apache.org/

http://phoenix.apache.org/language/index.html

ClouderaImpalaTranslator(impala)AlsoseecommonJDBCTranslatorInformation

TheCouderaImpalaTranslator,knownbythetypenameimpala,isforusewithClouderaImpala1.2.1orlater.

Impalahaslimitedsupportfordatatypes.Itisdoesnothavenativesupportfortime/date/xmlorLOBs.Theselimitationsarereflectedinthetranslatorcapabilities.ATeiidviewcanusethesetypes,howeverthetransformationwouldneedtospecifythenecessaryconversions.Notethatinthosesituations,theevaluationswillbedoneintheTeiidengine.

TheDatabaseTimeZonetranslatorpropertyshouldnotbeused.

ImpalaonlysupportsEQUIjoin,sousinganyotherjoinstypesonitssourcetableswillresultininefficientqueries.

Towritecriteriabasedonpartitionedcolumns,modeledthemonsourcetable,butdonotincludetheminselectioncolumns.

Note ImpalaHiveimporterdoesnothaveconceptofcatalogorsourceschema,nordoesitimportkeys,procedures,indexes,etc.

Impalaspecificimporterproperties:

useDatabaseMetaData-Settotruetousethenormalimportlogicwiththeoptiontoimportindexinformationdisabled.Defaultstofalse.

Note IfuseDatabaseMetaDataisfalsethetypicalJDBCDatabaseMetaDatacallsarenotusedsonotallofthecommonJDBCimporterpropertiesareapplicabletoImpala.YoumaystilluseexcludeTablesregardless.

Note

SomeversionsofImpalarequirestheuseofaLIMITwhenperforminganORDERBY.IfnodefaultisconfiguredinImpala,thenanexceptioncanoccurwhenaTeiidquerywithanORDERBYbutnoLIMITisissued.YoushouldsetanImpalawidedefault,orconfiguretheconnectionpooltouseanewconnectionsqlstringtoissueaSETDEFAULT_ORDER_BY_LIMITstatement.SeetheClouderadocsformoreonlimitoptions-suchascontrollingwhathappenswhenthelimitisexceeded.

JDBCTranslators

515

http://www.cloudera.com/content/cloudera-content/cloudera-docs/Impala/latest/Installing-and-Using-Impala/ciiu_langref_sql.html?scroll=limit_unique_1

DB2Translator(db2)AlsoseecommonJDBCTranslatorInformation

TheDB2Translator,knownbythetypenamedb2,ifforusewithDB28orlaterandDB2fori5.4orlater.

DB2specificexecutionproperties:

DB2ForI-indicatesthatthetheDB2instanceisDB2fori.Defaultstofalse.

supportsCommonTableExpressions-indicatesthattheDB2instancesupportsCommonTableExpressions.Defaultstotrue.Someolderversions,orinstancesrunninginaconversionmode,ofDB2lackfullcommontableexpressionsupportandmayneedsupportdisabled.

JDBCTranslators

516

DerbyTranslator(derby)AlsoseecommonJDBCTranslatorInformation

TheDerbyTranslator,knownbythetypenamederby,isforusewithDerby10.1orlater.

JDBCTranslators

517

GreenplumTranslator(greenplum)AlsoseecommonJDBCTranslatorInformation

TheGreenplumTranslator,knownbythetypenamegreenplum,isforusewiththeGreenplumdatabase.ThistranslatorisanextensionofthePostgreSQLTranslatorandinheritsitsoptions.

JDBCTranslators

518

H2Translator(h2)AlsoseecommonJDBCTranslatorInformation

TheH2Translator,knownbythetypenameh2,isforusewithH2version1.1orlater.

JDBCTranslators

519

HiveTranslator(hive)AlsoseecommonJDBCTranslatorInformation

TheHiveTranslator,knownbythetypenamehive,isforusewithHivev.10andSparkSQLv1.0andlater.

Capabilities

Hivehaslimitedsupportfordatatypes.Itdoesnothavenativesupportfortime/xmlorLOBs.Theselimitationsarereflectedinthetranslatorcapabilities.ATeiidviewcanusethesetypes,howeverthetransformationwouldneedtospecifythenecessaryconversions.Notethatinthosesituations,theevaluationswillbedoneinTeiidengine.

TheDatabaseTimeZonetranslatorpropertyshouldnotbeused.

HiveonlysupportsEQUIjoin,sousinganyotherjoinstypesonitssourcetableswillresultininefficientqueries.

Towritecriteriabasedonpartitionedcolumns,modeledthemonsourcetable,butdonotincludetheminselectioncolumns.

Note TheHiveimporterdoesnothaveconceptofcatalogorsourceschema,nordoesitimportkeys,procedures,indexes,etc.

ImportProperties

trimColumnNames-ForHive0.11.0andlaterthetheDESCRIBEcommandmetadataisinappropriatelyreturnedwithpadding,settotruetostriptrimwhitespacefromcolumnnames.Defaultstofalse.

useDatabaseMetaData-ForHive0.13.0andlaterthenormalJDBCDatabaseMetaDatafacilitiesaresufficienttoperformanimport.Settotruetousethenormalimportlogicwiththeoptiontoimportindexinformationdisabled.Defaultstofalse.Whentrue,trimColumnNameshasnoeffect.

Note IffalsethetypicalJDBCDatabaseMetaDatacallsarenotusedsonotallofthecommonJDBCimporterpropertiesareapplicabletoHive.YoumaystilluseexcludeTablesregardless.

"DatabaseName"

WhenthedatabasenameusedintheHiveisdifferentthan"default",themetadataretrievalandexecutionofqueriesdoesnotworkasexpectedinTeiid,asHiveJDBCdriverseemstobeimplicitlyconnecting(testedwith<0.12)to"default"database,thusignoringthedatabasenamementionedonconnectionURL.ThiscanworkaroundintheTeiidinWildFlyenvironmentbysettingthefollowingindatasourceconfiguration.

<new-connection-sql>use{database-name}</new-connection-sql>

Thisisfixedin>0.13versionHiveDriver.Seehttps://issues.apache.org/jira/browse/HIVE-4256

JDBCTranslators

520


https://issues.apache.org/jira/browse/HIVE-4256

HSQLTranslator(hsql)AlsoseecommonJDBCTranslatorInformation

TheHSQLTranslator,knownbythetypenamehsql,isforusewithHSQLDB1.7orlater.

JDBCTranslators

521

InformixTranslator(informix)AlsoseecommonJDBCTranslatorInformation

TheInformixTranslator,knownbythetypenameinformix,isforusewithanyInformixversion.

KnownIssues

TEIID-3808-TheInformixdriverhandlingoftimezoneinformationisinconsistent-evenifthedatabaseTimezonetranslatorpropertyisset.ConsiderensuringthattheInformixserverandtheapplicationserverareinthesametimezone.

JDBCTranslators

522


IngresTranslators(ingres/ingres93)AlsoseecommonJDBCTranslatorInformation

TheIngrestranslationissupportedby2translators.

ingres

TheIngresTranslator,knownbythetypenameingres,isforusewithIngres2006orlater.

ingres93

TheIngres93Translator,knownbythetypenameingres93,isforusewithIngres9.3orlater.

JDBCTranslators

523

IntersystemsCacheTranslator(intersystems-cache)AlsoseecommonJDBCTranslatorInformation

TheIntersystemCacheTranslator,knownbythetypenameintersystems-cache,isforusewithIntersystemsCacheObjectdatabase(onlyrelationalaspectofit).

JDBCTranslators

524

JDBCANSITranslator(jdbc-ansi)AlsoseecommonJDBCTranslatorInformation

TheJDBCANSItranslator,knownbythetypenamejdbc-ansi,declaressupportformostSQLconstructssupportedbyTeiid,exceptforrowlimit/offsetandEXCEPT/INTERSECT.TranslatessourceSQLintoANSIcompliantsyntax.Thistranslatorshouldbeusedwhenanothermorespecifictypeisnotavailable.IfsourceexceptionsarisefromunsupportedSQL,thenconsiderusingtheJDBCSimpleTranslatortofurtherrestrictcapabilities,orcreateaCustomTranslator/createanenhancementrequest.

JDBCTranslators

525

JDBCSimpleTranslator(jdbc-simple)AlsoseecommonJDBCTranslatorInformation

TheJDBCSimpletranslator,knownbythetypenamejdbc-simple,isthesameasjdbc-ansi,exceptdisablessupportfornearlyallpushdownconstructsformaximumcompatibility.

JDBCTranslators

526

MetaMatrixTranslator(metamatrix)AlsoseecommonJDBCTranslatorInformation

TheMetaMatrixTranslator,knownbythetypenamemetamatrix,isforusewithMetaMatrix5.5.0orlater.

JDBCTranslators

527

MicrosoftAccessTranslatorsAlsoseecommonJDBCTranslatorInformation

access

TheMicrosoftAccessTranslatorknownbythetypenameaccessisforusewithMicrosoftAccess2003orlaterviatheJDBC-ODBCbridge.

IfyouareusingthedefaultnativemetadataimportortheTeiidconnectionimportertheimporterdefaultstoimportKeys=falseandexcludeTables=.[.]MSys.toavoidissueswiththemetadataprovidedbytheJDBCODBCbridge.YoumayneedtoadjustthesevaluesifyouuseadifferentJDBCdriver.

ucanaccess

TheMicrosoftAccessTranslatorknownbythetypenameucanaccessisforusewithMicrosoftAccess2003orlaterviathefortheUCanAccessdriver.

JDBCTranslators

528

http://ucanaccess.sourceforge.net/site.html

MicrosoftExcel-ODBCTranslator(excel-odbc)AlsoseecommonJDBCTranslatorInformation

TheExcel-ODBCTranslator,knownbythetypenameexcel_odbc,isforusewithExcel2003orlaterviatheJDBC-ODBCbridge.

ThistranslatorisdeprecatedastheJDBC-ODBCbridgehasbeenremovedfromJava1.8.

JDBCTranslators

529

MicrosoftSQLServerTranslator(sqlserver)AlsoseecommonJDBCTranslatorInformation

TheMicrosoftSQLServerTranslator,knownbythetypenamesqlserver,isforusewithSQLServer2000orlater.ASQLServerJDBCdriverversion2.0orlater(orcompatiblee.g.JTDS1.2orlater)shouldbeused.TheSQLServerDatabaseVersionpropertymaybesetto2000,2005,2008,or2012,butotherwiseexpectsastandardversionnumber-e.g."10.0".

ExecutionProperties

SQLServerspecificexecutionproperties:

JtdsDriver-indicatesthattheopensourceJTDSdriverisbeingused.Defaultstofalse.

JDBCTranslators

530

ModeShapeTranslator(modeshape)AlsoseecommonJDBCTranslatorInformation

TheModeShapeTranslator,knownbythetypenamemodeshape,isforusewithModeshape2.2.1orlater.

Usage

ThePATH,NAME,LOCALNODENAME,DEPTH,andSCOREfunctionsshouldbeaccessedaspseudo-columns,e.g."nt:base"."jcr:path".

TeiidUFDs(prefixedbyJCR_)areavailableforCONTIANS,ISCHILDNODE,ISDESCENDENT,ISSAMENODE,REFERENCE-seetheJCRFunctions.xmi.IfaselectornameisneededinaJCRfunction,youshouldusethepseudo-column"jcr:path",e.g.JCR_ISCHILDNODE(foo.jcr_path,'x/y')wouldbecomeISCHILDNODE(foo,`x/y')intheModeShapequery.

Anadditionalpseudo-column"mode:properties"shouldbeimportedbysettingtheModeShapeJDBCconnectionpropertyteiidsupport=true.Thecolumn"mode:properties"shouldbeusedbytheJCR_REFERENCEandotherfunctionsthatexpecta.*selectorname,e.g.JCR_REFERENCE(nt_base.jcr_properties)wouldbecomeREFERENCE("nt:base".*)intheModeShapequery.

JDBCTranslators

531

MySQLTranslator(mysql/mysql5)AlsoseecommonJDBCTranslatorInformation

MySQL/MariaDBtranslationissupportedby2translators.

mysql

TheMysqltranslator,knownbythetypenamemysql,isforusewithMySQLversion4.x.

mysql5

TheMysql5translator,knownbythetypenamemysql5,isforusewithMySQLversion5orlater.

AlsosupportscompatibleMySQLderivativesincludingMariaDB.

UsageTheMySQLTranslatorsexpectthedatabaseorsessiontobeusingANSImode.IfthedatabaseisnotusingANSImode,aninitializationqueryshouldbeusedonthepooltosetANSImode:

setSESSIONsql_mode='ANSI'

Ifyoumaydealwithnulltimestampvalues,thensettheconnectionpropertyzeroDateTimeBehavior=convertToNull.Otherwiseyou’llgetconversionerrorsinTeiidthat`0000-00-0000:00:00'cannotbeconvertedtoatimestamp.

JDBCTranslators

532

NetezzaTranslator(netezza)AlsoseecommonJDBCTranslatorInformation

TheNetezzaTranslator,knownbythetypenamenetezza,isforusewithanyNetezzaversion.

Usage

ThecurrentNetezzavendorsuppliedJDBCdriverperformspoorlywithsingletransactionalupdates.Asisgenerallythecasewhenpossibleusebatchedupdates.

ExecutionProperties

Netezzaspecificexecutionproperties:

SqlExtensionsInstalled-indicatesthatSQLExtensions,includingsupportforREGEXP_LIKE,areinstalled.AllotherREGEXPfunctionsarethenavailableaspushdownfunctions.Defaultstofalse.

JDBCTranslators

533

OracleTranslator(oracle)AlsoseecommonJDBCTranslatorInformation

TheOracleTranslator,knownbythetypenameoracle,isforusewithOracle9iorlater.

SequencesmaybeusedwiththeOracletranslator.AsequencemaybemodeledasatablewithanameinsourceofDUALandcolumnswiththenameinsourcesetto\{\{<sequencename>.[nextval|currval].}}

Teiid8.4andPriorOracleSequenceDDL

CREATEFOREIGNTABLEseq(nextvalintegerOPTIONS(NAMEINSOURCE'seq.nextval'),currvalintegeroptions(NAMEIN

SOURCE'seq.currval'))OPTIONS(NAMEINSOURCE'DUAL')

WithTeiid8.5it’snolongernecessarytorelyonatablerepresentationandOraclespecifichandlingforsequences.SeeDDLMetadataforrepresentingcurrvalandnextvalassourcefunctions.

Youcanalsouseasequenceasthedefaultvalueforinsertcolumnsbysettingthecolumntoautoincrementandthenameinsourceto<elementname>:SEQUENCE=<sequencename>.<sequencevalue>.

ArownumcolumncanalsoaddedtoanyOraclephysicaltabletosupporttherownumpseudo-column.Arownumcolumnshouldhaveanameinsourceofrownum.TheserownumcolumnsdonothavethesamesemanticsastheOraclerownumconstructsocaremustbetakenintheirusage.

Outparametersforproceduresmayalsobeusedtoreturnaresultset,ifthisisnotrepresentedcorrectlybytheautomaticimportyouneedtomanuallycreatearesultsetandrepresenttheoutputparameterwithnativetype"REFCURSOR".

DDLforoutparameterresultset

createforeignprocedureproc(inxinteger,outyobjectoptions(native_type'REFCURSOR'))

returnstable(ainteger,bstring)

Oraclespecificimporterproperties:

useGeometryType-UsetheTeiidGeometytypewhenimportingcolumnswithasourcetypeofSDO_GEOMETRY.Defaultstofalse.

useIntegralTypes-Useintegraltypesratherthandecimalwhenthescaleis0.Defaultstofalse.

Oraclespecificexecutionproperties:

OracleSuppliedDriver-indicatesthattheOraclesupplieddriver(typicallyprefixedbyojdbc)isbeingused.Defaultstotrue.SettofalsewhenusingDataDirectorotherOracleJDBCdrivers.

GeoSpatialfunctionsupport

Oracletranslatorsupportsgeospatialfunctions.Thesupportedfunctionsare:

Relate=sdo_relate

CREATEFOREIGNFUNCTIONsdo_relate(arg1string,arg2string,arg3string)RETURNSstring;

CREATEFOREIGNFUNCTIONsdo_relate(arg1Object,arg2Object,arg3string)RETURNSstring;

CREATEFOREIGNFUNCTIONsdo_relate(arg1string,arg2Object,arg3string)RETURNSstring;

CREATEFOREIGNFUNCTIONsdo_relate(arg1Object,arg2string,arg3string)RETURNSstring;

Nearest_Neighbor=sdo_nn

JDBCTranslators

534

CREATEFOREIGNFUNCTIONsdo_nn(arg1string,arg2Object,arg3string,arg4integer)RETURNSstring;

CREATEFOREIGNFUNCTIONsdo_nn(arg1Object,arg2Object,arg3string,arg4integer)RETURNSstring;

CREATEFOREIGNFUNCTIONsdo_nn(arg1Object,arg2string,arg3string,arg4integer)RETURNSstring;

Within_Distance=sdo_within_distance

CREATEFOREIGNFUNCTIONsdo_within_distance(arg1Object,arg2Object,arg3string)RETURNSstring;

CREATEFOREIGNFUNCTIONsdo_within_distance(arg1string,arg2Object,arg3string)RETURNSstring;

CREATEFOREIGNFUNCTIONsdo_within_distance(arg1Object,arg2string,arg3string)RETURNSstring;

Nearest_Neigher_Distance=sdo_nn_distance

CREATEFOREIGNFUNCTIONsdo_nn_distance(arginteger)RETURNSinteger;

Filter=sdo_filter

CREATEFOREIGNFUNCTIONsdo_filter(arg1Object,arg2string,arg3string)RETURNSstring;

CREATEFOREIGNFUNCTIONsdo_filter(arg1Object,arg2Object,arg3string)RETURNSstring;

CREATEFOREIGNFUNCTIONsdo_filter(arg1string,arg2object,arg3string)RETURNSstring;

JDBCTranslators

535

OSISoftPITranslator(osisoft-pi)AlsoseecommonJDBCTranslatorInformation

TheOSISoftTranslator,knownbythetypenameosisoft-pi,isforusewithOSIsoftPI.

JDBCTranslators

536

PostgreSQLTranslator(postgresql)AlsoseecommonJDBCTranslatorInformation

ThePostgreSQLTranslator,knownbythetypenamepostgresql,isforusewith8.0orlaterclientsand7.1orlaterserver.

ExecutionProperties

PostgreSQLspecificexecutionproperties:

PostGisVersion-indicatethePostGISversioninuse.Defaultsto0meaningPostGISisnotinstalled.Willbesetautomaticallyifthedatabaseversionisnotset.

ProjSupported-booleanindicatingifProjissupportforPostGis.Willbesetautomaticallyifthedatabaseversionisnotset.

JDBCTranslators

537

PrestoDBTranslator(prestodb)AlsoseecommonJDBCTranslatorInformation

ThePrestoDBtranslator,knownbythetypenameprestodb,exposesqueryingfunctionalitytoPrestoDBDataSources.Indataintegrationrespect,PrestoDBhasverysimilarcapabilitiesofTeiid,howeveritgoesbeyondintermsofdistributedqueryexecutionwithmultipleworkernodes.Teiid’sexecutionmodelislimitedtosingleexecutionnodeandfocusesmoreonpushingthequerydowntosources.CurrentlyTeiidhasmuchmorecompletequerysupportandmanyenterprisefeatures.

Capabilities

ThePrestoDBtranslatorsupportsonlySELECTstatementswitharestrictivesetofcapabilities.Thistranslatorisdevelopedwith0.85versionofPrestoDBandcapabilitiesaredesignedforthisversion.WithnewversionsofPrestoDBTeiidwilladjustthecapabilitiesofthistranslator.SincePrestoDBexposesarelationalmodel,theusageofthisisnodifferentthananyRDBMSsourcelikeOracle,DB2etc.ForconfiguringthePrestoDBconsultthePrestoDBdocumentation.

JDBCTranslators

538

RedshiftTranslator(redshift)AlsoseecommonJDBCTranslatorInformation

TheRedshiftTranslator,knownbythetypenameredshift,isforusewiththeRedshiftdatabase.ThistranslatorisanextensionofthePostgreSQLTranslatorandinheritsitsoptions.

JDBCTranslators

539

SAPHanaTranslator(hana)AlsoseecommonJDBCTranslatorInformation

TheSAPHanaTranslator,knownbythenameofhana,isforusewithSAPHana.

KnownIssues

TEIID-3805-ThepushdownofthesubstringfunctionisinconsistentwiththeTeiidsubstringfunctionwhenthefromindexexceedsthelengthofthestring.SAPHanawillreturnanemptystring,whileTeiidproducesanullvalue.

JDBCTranslators

540


SybaseIQTranslator(sybaseiq)AlsoseecommonJDBCTranslatorInformation

TheSybaseIQTranslator,knownbythetypenamesybaseiq,isforusewithSybaseIQversion15.1orlater.

JDBCTranslators

541

SybaseTranslator(sybase)TheSybaseTranslator,knownbythetypenamesybase,isforusewithSybaseversion12.5orlater.

Ifusingthethedefaultnativeimportandnoimportpropertiesarespecified(notrecommended,seeimportpropertiesbelow),thenexceptionscanbethrownretrievingsystemtableinformation.YoushouldspecifyaschemaPatternoruseexcludeTablestoexcludesystemtablesifthisoccurs.

Ifthenameinsourcemetadatacontainsquotedidentifiers(suchasrequiredbyreservedwordsorwordscontainingcharactersthatwouldnototherwisebeallowed)andyouareusingajconnectSybasedriver,youmustfirstconfiguretheconnectionpooltoenablequoted_identifier:

DriverURLwithSQLINITSTRING

jdbc:sybase:Tds:host.at.some.domain:5000/db_name?SQLINITSTRING=setquoted_identifieron

IfyouareajconnectSybasedriverandwilltargetthesourcefordependentjoins,youshouldallowthetranslatortosendmorevaluesbysettingtheJCONNECT_VERSION.Otherwiseyouwillgetexceptionswithstatementsthathavemorethan481bindvalues:

DriverURLwithJCONNECT_VERSION

jdbc:sybase:Tds:host.at.some.domain:5000/db_name?SQLINITSTRING=setquoted_identifieron&JCONNECT_VERSION=6

Sybasespecificexecutionproperties:

JtdsDriver-indicatesthattheopensourceJTDSdriverisbeingused.Defaultstofalse.

JDBCTranslators

542

TeiidTranslator(teiid)AlsoseecommonJDBCTranslatorInformation

TheTeiidTranslator,knownbythetypenameteiid,isforusewithTeiid6.0orlater.

JDBCTranslators

543

TeradataTranslator(teradata)AlsoseecommonJDBCTranslatorInformation

TheTeradataTranslator,knownbythetypenameteradata,isforusewithTeradataV2R5.1orlater.

WithTeradatadriverversion15date,time,andtimestampvaluesbydefaultwillbeadjustedfortheTeiidservertimezone.Toremovethisadjustment,setthetranslatorDatabaseTimezonepropertytoGMTorwhatevertheTeradataserverdefaultsto.

JDBCTranslators

544

VerticaTranslator(vertica)AlsoseecommonJDBCTranslatorInformation

TheVerticaTranslator,knownbythetypenamevertica,isforusewithVertica6orlater.

JDBCTranslators

545

JPATranslatorTheJPAtranslator,knownbythetypenamejpa2,canreverseaJPAobjectmodelintoarelationalmodel,whichcanthenbeintegratedwithotherrelationalornon-relationalsources.ForinformationonJPApersistenceinaWildFly,seeJPAReferenceGuide.

Properties

TheJPATranslatorcurrentlyhasnoimportorexecutionproperties.

NativeQueriesJPAsourceproceduresmaybecreatedusingtheteiid_rel:native-queryextension-seeParameterizableNativeQueries.Theprocedurewillinvokethenative-querysimilartoannativeprocedurecallwiththebenefitsthatthequeryispredeterminedandthatresultcolumntypesareknown,ratherthanrequiringtheuseofARRAYTABLEorsimilarfunctionality.Seethequerysyntaxbelow.



Tip Bydefaultthenameoftheprocedurethatexecutesthequeriesdirectlyisnative.Overridetheexecutionproperty_DirectQueryProcedureNametochangeittoanothername.

TheJPAtranslatorprovidesaproceduretoexecuteanyad-hocJPA-QLquerydirectlyagainstthesourcewithoutTeiidparsingorresolving.Sincethemetadataofthisprocedure’sresultsarenotknowntoTeiid,theyarereturnedasobjectarray.UsercanuseARRAYTABLEcanbeusedconstructtabularoutputforconsumptionbyclientapplications.Teiidexposesthisprocedurewithasimplequerystructureasbelow

Select

SelectExample

SELECTx.*FROM(calljpa_source.native('search;FROMAccount'))w,


fromtheabovecode,the"search"keywordfollowedbyaquerystatement-seeParameterizableNativeQueriestosubstituteparametervalues.

Delete

DeleteExample

SELECTx.*FROM(calljpa_source.native('delete;<jpa-ql>'))w,

ARRAYTABLE(w.tupleCOLUMNS"updatecount"integer)ASx

formtheabovecode,the"delete"keywordfollowedbyJPA-QLfordeleteoperation.

Update

JPATranslator

546

https://docs.jboss.org/author/display/WFLY9/JPA+Reference+Guide

CreateExample

SELECTx.*FROM

(calljpa_source.native('update;<jpa-ql>'))w,


formtheabovecode,the"update"keywordmustbefollowedbyJPA-QLfortheupdatestatement.

Create

UpdateExample

SELECTx.*FROM

(calljpa_source.native('create;',<entity>))w,


Createoperationneedstosend"create"wordasmarkerandsendtheentityasathefirstparameter.

JPATranslator

547

LDAPTranslatorTheLDAPtranslatorisimplementedbytheorg.teiid.translator.ldap.LDAPExecutionFactoryclassandknownbythetranslatortypenameldap.TheLDAPtranslatorexposesanLDAPdirectorytreerelationallywithpushdownsupportforfilteringviacriteria.ThisistypicallycoupledwiththeLDAPresourceadapter.

Note TheresourceadapterforthistranslatorisprovidedbyconfiguringtheldapdatasourceintheJBossEAPinstance.

ExecutionProperties


SearchDerfaultBaseDN DefaultBaseDNforLDAPSearches null

SearchDefaultScope

DefaultScopeforLDAPSearches.CanbeoneofSUBTREE_SCOPE,OBJECT_SCOPE,ONELEVEL_SCOPE.

ONELEVEL_SCOPE

RestrictToObjectClass RestrictSearchestoobjectClassnamedintheNamefieldforatable false

UsePaginationUseaPagedResultsControltopagethroughlargeresults.Thisisnotsupportedbyalldirectoryservers.

false

ExceptionOnSizeLimitExceeded

SettotruetothrowanexceptionwhenaSizeLimitExceededExceptionisreceivedandaLIMITisnotproperlyenforced.

false

Therearenoimportsettingsfortheldaptranslator;italsodoesnotprovidemetadata.

MetadataOptions

SEARCHABLE'equality_only'

Foropenldap,apacheds,andotherldapserversdnattributeshavesearchrestrictions,suchthatonlyequalitypredicatesaresupported.UseSEARCHABLEequality_onlytoindicatesthatonlyequalitypredicatesshouldbepusheddown.Anyotherpredicatewouldneedevaluatedintheengine.Forexample

colstringOPTIONS(SEARCHABLE'equality_only',...)

teiid_ldap:rdn_type

Usedonacolumnwithadnvaluetoindicatetherdntoextract.Iftheentrysuffixdoesnotmatchthisrdntype,thennorowwillbeproduced.Forexample

colstringOPTIONS("teiid_ldap:rdn_type"'cn',...)

teiid_ldap:dn_prefix

LDAPTranslator

548

Usedonacolumnifrdn_typeisspecifiedtoindicatesthatthevaluesshouldmatchthisprefix,norowwillbeproducedforanon-matchingentry.Forexample

colstringOPTIONS("teiid_ldap:rdn_type"'cn',"teiid_ldap:dn_prefix"'ou=groups,dc=example,dc=com',...)

MultivaluedAttributeSupport

Ifoneofthemethodsbelowisnotusedandtheattributeismappedtoanon-arraytype,thenanyvaluemaybereturnedonareadoperation.Alsoinsert/update/deletesupportwillnotbemulti-valueaware.

Concatenation

Stringcolumnswithadefaultvalueof"multivalued-concat"willconcatenateallattributevaluestogetherinalphabeticalorderusinga?delimiter.Insert/updatewillfunctionasexpectedifallapplicablevaluesaresuppliedintheconcatenatedformat.

Arraysupport

Multipleattributevaluesmayalsosupportedasanarraytype.Thearraytypemappingalsoallowsforinsert/updateoperations.

ForexamplehereisddlwithobjectClassanduniqueMemberasarrays:

createforeigntableldap_groups(objectClassstring[],DNstring,namestringoptions(nameinsource'cn'),uni

queMemberstring[])options(nameinsource'ou=groups,dc=teiid,dc=org',updatabletrue)

ThearrayvaluescanberetrievedwithaSELECT.Anexampleinsertwitharrayvaluescouldlooklike:

insertintoldap_groups(objectClass,DN,name,uniqueMember)values(('top','groupOfUniqueNames'),'cn=a,ou=g

roups,dc=teiid,dc=org','a',('cn=SamSmith,ou=people,dc=teiid,dc=org',))

Unwrap

Whenamultivaluedattributerepresentsanassociationbetweenentities,it’spossibletouseextensionmetadatapropertiestorepresentitasa1-to-manyormany-to-manyrelationship.

Examplemany-to-manyDDL:

CREATEforeigntableusers(usernamestringprimarykeyoptions(nameinsource'cn'),surnamestringoptions(na

meinsource'sn'),...)options(nameinsource'ou=users,dc=example,dc=com');

CREATEforeigntablegroups(groupnamestringprimarykeyoptions(nameinsource'cn'),descriptionstring,...)

options(nameinsource'ou=groups,dc=example,dc=com');

CREATEforeigntablemembership(usernamestringoptions(nameinsource'cn'),groupnameoptions(nameinsource'

memberOf',SEARCHABLE'equality_only',"teiid_rel:partial_filter"true,"teiid_ldap:unwrap"true,"teiid_ldap:d

n_prefix"'ou=groups,dc=example,dc=com',"teiid_ldap:rdn_type"'cn'),foreignkey(username)referencesusers(

username),foreignkey(groupname)referencesgroups(groupname))options(nameinsource'ou=users,dc=example,dc

=com');

Theresultfrom"select*frommembership"willthenproduce1rowforeachmemberOfandthekeyvaluewillbebaseduponthecnrdnvalueratherthanthefulldn.Alsoqueriesthatjoinbetweenusersandmembershipwillbepushedasasinglequery.

Iftheunwrapattributeismissingortherearenovalues,thenasinglerowwithanullvaluewillbeproduced.

NativeQueries

LDAPTranslator

549

LDAPproceduresmayoptionallyhavenativequeriesassociatedwiththem-seeParameterizableNativeQueries.Theoperationprefix(select;,insert;,update;,delete;-seebelowformore)mustbepresentinthenative-query,butitwillnotbeissuedaspartofthequerytothe

ExampleDDLforanLDAPnativeprocedure

CREATEFOREIGNPROCEDUREproc(arg1integer,arg2string)OPTIONS("teiid_rel:native-query"'search;context-nam

e=corporate;filter=(&(objectCategory=person)(objectClass=user)(!cn=$2));count-limit=5;timeout=$1;search-scope=O

NELEVEL_SCOPE;attributes=uid,cn')returns(col1string,col2string);

Parametervalueswillhavereservedcharactersescaped,butareotherwisedirectlysubstitutedintothequery.




TheLDAPtranslatorprovidesaproceduretoexecuteanyad-hocLDAPquerydirectlyagainstthesourcewithoutTeiidparsingorresolving.Sincethemetadataofthisprocedure’sresultsarenotknowntoTeiid,theyarereturnedasanobjectarray.ARRAYTABLEcanbeusedconstructtabularoutputforconsumptionbyclientapplications.

Search

SearchExample

SELECTx.*FROM(callpm1.native('search;context-name=corporate;filter=(objectClass=*);count-limit=5;timeout=6;

search-scope=ONELEVEL_SCOPE;attributes=uid,cn'))w,

ARRAYTABLE(w.tupleCOLUMNS"uid"string,"cn"string)ASx

fromtheabovecode,the"search"keywordfollowedbybelowproperties.Eachpropertymustbedelimitedbysemi-colon(;)Ifapropertycontainsasemi-colon(;),itshouldbeescapedbyanothersemi-colon-seealsoParameterizableNativeQueriesandthenative-queryprocedureexampleabove.

Name Description Required

context-name LDAPContextname Yes

filter querytofiltertherecordsinthecontext No

count-limit limitthenumberofresults.sameasusingLIMIT No

timeout Timeoutthequeryifnotfinishedingivenmilliseconds No

search-scope

LDAPsearchscope,oneofSUBTREE_SCOPE,OBJECT_SCOPE,ONELEVEL_SCOPE

No

attributes attributestoretrieve Yes

LDAPTranslator

550

Delete

DeleteExample

SELECTx.*FROM(callpm1.native('delete;uid=doe,ou=people,o=teiid.org'))w,


formtheabovecode,the"delete"keywordfollowedthe"DN"string.Allthestringcontentsafterthe"delete;"usedasDN.

CreateorUpdate

CreateExample

SELECTx.*FROM

(callpm1.native('create;uid=doe,ou=people,o=teiid.org;attributes=one,two,three','one',2,3.0))w,


formtheabovecode,the"create"keywordfollowedthe"DN"string.Allthestringcontentsafterthe"create;"isusedasDN.Italsotakesonepropertycalled"attributes"whichiscommaseparatedlistofattributes.Thevaluesforeachattributeisspecifiedasseparateargumenttothe"native"procedure.

Updateissimilarto"create".

UpdateExample

SELECTx.*FROM

(callpm1.native('update;uid=doe,ou=people,o=teiid.org;attributes=one,two,three','one',2,3.0))w,


LDAPConnectorCapabilitiesSupport

LDAPdoesnotprovidethesamesetoffunctionalityasarelationaldatabase.TheLDAPConnectorsupportsmanystandardSQLconstructs,andperformsthejoboftranslatingthoseconstructsintoanequivalentLDAPsearchstatement.Forexample,theSQLstatement:

SELECTfirstname,lastname,guid

FROMpublic_views.people

WHERE

(lastname='Jones'andfirstnameIN('Michael','John'))

OR

guid>600000

usesanumberofSQLconstructs,including:

SELECTclausesupport

selectindividualelementsupport(firstname,lastname,guid)

FROMsupport

WHEREclausecriteriasupport

nestedcriteriasupport

AND,ORsupport

Comparecriteria(Greater-than)support

INsupport

LDAPTranslator

551

TheLDAPConnectorexecutesLDAPsearchesbypushingdowntheequivalentLDAPsearchfilterwheneverpossible,basedonthesupportedcapabilities.TeiidautomaticallyprovidesadditionaldatabasefunctionalitywhentheLDAPConnectordoesnotexplicitlyprovidesupportforagivenSQLconstruct.Inthesecases,theSQLconstructcannotbepusheddowntothedatasource,soitwillbeevaluatedinTeiid,inordertoensurethattheoperationisperformed.IncaseswherecertainSQLcapabilitiescannotbepusheddowntoLDAP,Teiidpushesdownthecapabilitiesthataresupported,andfetchesasetofdatafromLDAP.Teiidthenevaluatestheadditionalcapabilities,creatingasubsetoftheoriginaldataset.Finally,Teiidwillpasstheresulttotheclient.Itisusefultobeawareofunsupportedcapabilities,inordertoavoidfetchinglargedatasetsfromLDAPwhenpossible.

LDAPConnectorCapabilitiesSupportList

ThefollowingcapabilitiesaresupportedintheLDAPConnector,andwillbeevaluatedbyLDAP:

SELECTqueries

SELECTelementpushdown(forexample,individualattributeselection)

ANDcriteria

Comparecriteria(e.g.<,⇐,>,>=,=,!=)

INcriteria

LIKEcriteria.

ORcriteria

INSERT,UPDATE,DELETEstatements(mustmeetModelingrequirements)

DuetothenatureoftheLDAPsource,thefollowingcapabilityisnotsupported:

SELECTqueries

ThefollowingcapabilitiesarenotsupportedintheLDAPConnector,andwillbeevaluatedbyTeiidafterdataisfetchedbytheconnector:

Functions

Aggregates

BETWEENCriteria

CaseExpressions

AliasedGroups

CorrelatedSubqueries

EXISTSCriteria

Joins

Inlineviews

ISNULLcriteria

NOTcriteria

ORDERBY

Quantifiedcomparecriteria

RowOffset

SearchedCaseExpressions

LDAPTranslator

552

SelectDistinct

SelectLiterals

UNION

XATransactions

Usage

ldap-as-a-datasourcequickstartdemonstratesusingtheldapTranslatortoaccessdatainOpenLDAPServer.Thenameofthetranslatortouseinvdb.xmlis"translator-ldap",forexample:


<vdbname="ldapVDB"version="1">

<modelname="HRModel">

<sourcename="local"translator-name="translator-ldap"

connection-jndi-name="java:/ldapDS"/>

</model>

</vdb>

ThetranslatordoesnotprovideaconnectiontotheOpenLDAP.Forthatpurpose,TeiidhasaJCAadapterthatprovidesaconnectiontoOpenLDAPusingtheJavaNamingAPI.Todefinesuchconnector,usethefollowingXMLfragmentinstandalone-teiid.xml.Seeaexamplein"<jboss-as>/docs/teiid/datasources/ldap"

<resource-adapterid="ldapQS">

<moduleslot="main"id="org.jboss.teiid.resource-adapter.ldap"/>


<connection-definition

class-name="org.teiid.resource.adapter.ldap.LDAPManagedConnectionFactory"

jndi-name="java:/ldapDS"enabled="true"use-java-context="true"

pool-name="ldapDS">

<config-propertyname="LdapAdminUserPassword">

redhat

</config-property>

<config-propertyname="LdapAdminUserDN">

cn=Manager,dc=example,dc=com

</config-property>

<config-propertyname="LdapUrl">

ldap://localhost:389

</config-property>



</resource-adapter>

Theabovedefinesthetranslatorandconnector.FormorewaystocreatetheconnectorseeLDAPDataSources,LDAPtranslatorcanderivethemetadatabasedonexistingUsers/GroupsinLDAPServer,userneedtodefinethemetadata.Forexample,youcandefineaschemausingDDL:


<vdbname="ldapVDB"version="1">

<modelname="HRModel">


CREATEFOREIGNTABLEHR_Group(

DNstringoptions(nameinsource`dn'),

SNstringoptions(nameinsource`sn'),

UIDstringoptions(nameinsource`uid'),

MAILstringoptions(nameinsource`mail'),

NAMEstringoptions(nameinsource`cn')

)OPTIONS(nameinsource`ou=HR,dc=example,dc=com',updatabletrue);

]]>

LDAPTranslator

553

https://github.com/teiid/teiid-quickstarts/tree/master/ldap-as-a-datasource

</metadata>

</model>

</vdb>

whenSELECToperationbelowexecutedagainsttableusingTeiidwillretrieveUsers/GroupsinLDAPServer:

SELECT*FROMHR_Group

LDAPAttributeDatatypeSupport

LDAPproviderscurrentlyreturnattributevaluetypesofjava.lang.Stringandbyte[],anddonotsupporttheabilitytoreturnanyotherattributevaluetype.TheLDAPConnectorcurrentlysupportsattributevaluetypesofjava.lang.Stringonly.Therefore,allattributesaremodeledusingtheStringdatatypeinTeiidDesigner.ConversionfunctionsthatareavailableinTeiidallowyoutousemodelsthatconvertaStringvaluefromLDAPintoadifferentdatatype.Someconversionsmaybeappliedimplicitly,anddonotrequiretheuseofanyconversionfunctions.Otherconversionsmustbeappliedexplicitly,viatheuseofCONVERTfunctions.SincetheCONVERTfunctionsarenotsupportedbytheunderlyingLDAPsystem,theywillbeevaluatedinTeiid.Therefore,ifanycriteriaisevaluatedagainstaconverteddatatype,thatevaluationcannotbepushedtothedatasource,sincethenativetypeisString.

WhenconvertingfromStringtoothertypes,beawarethatcriteriaagainstthatnewdatatypewillnotbepusheddowntotheLDAPdatasource.Thismaydecreaseperformanceforcertainqueries.

Asanalternative,thedatatypecanremainastringandtheclientapplicationcanmaketheconversion,ortheclientapplicationcancircumventanyLDAPsupports⇐and>=,buthasnoequivalentfor<or>.Inordertosupport<or>pushdowntothesource,theLDAPConnectorwilltranslate<to⇐,anditwilltranslate>to>=.WhenusingtheLDAPConnector,beawarethatstrictly-less-thanandstrictly-greater-thancomparisonswillbehavedifferentlythanexpected.Itisadvisabletouse⇐and>=forqueriesagainstanLDAPbaseddatasource,sincethishasadirectmappingtocomparisonoperatorsinLDAP.

LDAP:TestingYourConnector

YoumustdefineLDAPConnectorpropertiesaccuratelyortheTeiidserverwillreturnunexpectedresults,ornoneatall.AsyoudeploytheconnectorinConsole,improperconfigurationcanleadtoproblemswhenyouattempttostartyourconnector.YoucantestyourLDAPConnectorinTeiidDesignerpriortoConsoledeploymentbysubmittingqueriesatmodelingtimeforverification.

LDAP:ConsoleDeploymentIssues

TheConsoleshowsanExceptionThatSaysErrorSynchronizingtheServer,IfyoureceiveanexceptionwhenyousynchronizetheserverandyourLDAPConnectoristheonlyservicethatdoesnotstart,itmeansthattherewasaproblemstartingtheconnector.Verifywhetheryouhavecorrectlytypedinyourconnectorpropertiestoresolvethisissue.

JCAResourceAdapter

Theresourceadapterforthistranslatorprovidedthrough"LDAPDataSource",RefertoAdminGuideforconfiguration.

LDAPTranslator

554

LoopbackTranslatorTheLoopbacktranslator,knownbythetypenameloopback,providesaquicktestingsolution.ItsupportsallSQLconstructsandreturnsdefaultresults,withsomeconfigurablebehavior.

ExecutionProperties


ThrowError truetoalwaysthrowanerror false

RowCount Rowsreturnedfornon-updatequeries. 1

WaitTime Waitrandomlyuptothisnumberofmillisecondswitheachsourcequery. 0

PollIntervalInMilli

ifpositiveresultswillbeasynchronouslyreturned-thatisaDataNotAvailableExceptionwillbethrowninitiallyandtheenginewillwaitthepollintervalbeforepollingfortheresults.

-1

DelegateName settothenameofthetranslatortomimicthecapabilitiesof

YoucanalsousetheLoopbacktranslatortomimichowarealsourcequerywouldbeformedforagiventranslator(althoughloopbackwillstillreturndummydatathatmaynotbeusefulforyoursituation).Toenablethisbehavior,settheDelegateNamepropertytothenameofthetranslatoryouwishtomimic.Forexampletodisableallcapabilities,settheDelegateNamepropertyto"jdbc-simple".

JCAResourceAdapter

Asourceconnectionisnotrequiredforthistranslator.

LoopbackTranslator

555

MicrosoftExcelTranslatorTheMicrosoftExcelTranslator,knownbythetypenameexcel,exposesqueryingfunctionalitytoExceldocumentsusingFileDataSources.MicrosoftExcelisapopularspreadsheetsoftwarethatisusedbyalltheorganizationsacrosstheglobeforsimplereportingpurposes.ThistranslatorprovidesaneasywayreadaExcelspreadsheetandprovidecontentsofthespreadsheetinthetabularformthatcanbeintegratedwithothersourcesinTeiid.

Note "DoesitonlyworkonWindows?"-No,itworksonallplatforms,includingWindowsandLinux.ThistranslatorusesApachePOIlibrariestoaccesstheExceldocumentswhichareplatformindependent.

Usage

ThebelowtabledescribeshowExceltranslatorinterpretsthedatainExceldocumentintorelationalterms.

ExcelTerm RelationalTerm

Workbook schema

Sheet Table

Row Rowofdata

Cell ColumnDefinitionorDataofacolumn

Exceltranslatorsupports"sourcemetadata"feature,wheregivenExcelworkbook,itcanintrospectandbuildtheschemabasedontheSheetsdefinedinsideit.Thereareoptionsavailableforyouguide,tobeabletodetectheadercolumnsanddatacolumnsinaworksheettodefinethecorrectmetadataofatable.

VDBExample

ThebelowshowsanexampleofaVDB,thatshowsaexposingaExcelDocument.


<vdbname="excelvdb"version="1">

<modelname="excel">

<propertyname="importer.headerRowNumber"value="1"/>

<propertyname="importer.ExcelFileName"value="names.xls"/>

<sourcename="connector"translator-name="excel"connection-jndi-name="java:/fileDS"/>

</model>

</vdb>

"connection-jndi-name"inaboverepresentsconnectiontoExceldocument.TheExceltranslatordoesNOTprovideaconnectiontotheExcelDocument.Forthatpurpose,TeiidusesFileJCAadapterthatprovidesaconnectiontoExcel.Todefinesuchconnector,seeFileDataSourcesorseeanexamplein"<jboss-as>/docs/teiid/datasources/file".Onceyouconfigurebothoftheabove,youcandeploythemtoTeiidServerandaccesstheExcelDocumentusingJDBC/ODBC/ODataprotocol.

DesignerVDB

IfyouareusingDesignerTooling,tocreateExcelbasedVDB


556


Use"TeiidConnection>>SourceModel"importer,createFileDataSourceusingdatasourcecreationwizardanduseexcelastranslatorintheimporter.BasedontheExceldocumentrelevantrelationaltableswillbecreated.

CreateaVDBanddeployintoTeiidServerandandaccesstheExcelDocumentusingJDBC/ODBC/ODataprotocol.

Note"HeadersinDocument?"-IfyouhaveheadersintheExceldocument,youcanguidetheimportprocesstoselectthecellheadersasthecolumnnamesinthetablecreationprocess.See"ImportProperties"sectionbelowondefiningthe"import"properties.

ImportProperties

ImportpropertiesguidetheschemagenerationpartduringthedeploymentoftheVDB.Thiscanbeusedinanativeimportorwhileusing"TeiidConnection>>SourceModel"inTeiidDesigner.

PropertyName Description Default

importer.excelFileName

DefinesthenameoftheExcelDocumenttoimportmetadata.Thiscanbedefinedasafilepattern(*.xls),howeverwhendefinedaspatternallfilesmustbeofsameformatandthetranslatorwillchooseanarbitraryfiletoimportmetadatafrom.UsefilepatterntoreaddatafrommultipleExceldocumentsinthesamedirectory,insinglefilecasechoosetheabsolutename.

required

importer.headerRowNumber Definesthecellheaderinformationtobeusedascolumnnames

optional,defaultisfirstdatarowofsheet

importer.dataRowNumber Definestherownumberwherethedatarowsstart

optional,defaultisfirstdatarowofsheet

Itishighlyrecommendedthatyoudefinealltheaboveimporterproperties,suchthatinformationinsidetheExcelDocumentiscorrectlyinterpreted.

Note

Purelynumericalcellsinacolumncontaincontainingmixedtypeswillhaveastringformmatchingtheirdecimalrepresentation,thusintegralvalueswillhave.0appended.Ifyouneedtheexacttextrepresentation,thencellmustbeastringvaluewhichcanbeforcedbyputtingasinglequote'infrontofthenumerictextofthecell,orbyputtingasinglespaceinfrontofthenumerictext.

TranslatorExtensionProperties

CurrentlytherearenoTranslatorExtensionpropertiesdefinedforthistranslator.

MetadataExtensionProperties

MetadataExtensionPropertiesarethepropertiesthataredefinedontheschemaartifactslikeTable,Column,Procedureetc,todescribehowthetranslatorneedstointeractorinterpretwithsourcesystems.Allthepropertiesaredefinedwithnamespace'http://www.teiid.org/translator/excel/2014[http://www.teiid.org/translator/excel/2014\]',whichalsohasarecognizedalias'teiid_excel'.

PropertyName SchemaItemPropertyBelongsTo Description Mandatory


557

http://www.teiid.org/translator/excel/2014\

FILE Table

DefinesExcelDocumentnameornamepattern(*.xls).Filepatterncanbeusedtoreaddatafrommultiplefiles.

Yes

FIRST_DATA_ROW_NUMBER Table

Definestherownumberwhererecordsstartinthesheet(appliestoeverysheet)

optional

CELL_NUMBER ColumnofTableDefinescellnumbertouseforreadingdataofparticularcolumn

Yes

ThebelowshowsanexampletablethatisdefinedusingtheExtensionMetadataProperties.


<vdbname="excelvdb"version="1">

<modelname="excel">

<sourcename="connector"translator-name="excel"connection-jndi-name="java:/fileDS"/>


CREATEFOREIGNTABLEPerson(

ROW_IDintegerOPTIONS(SEARCHABLE'All_Except_Like',"teiid_excel:CELL_NUMBER"'ROW_ID'),

FirstNamestringOPTIONS(SEARCHABLE'Unsearchable',"teiid_excel:CELL_NUMBER"'1'),

LastNamestringOPTIONS(SEARCHABLE'Unsearchable',"teiid_excel:CELL_NUMBER"'2'),

AgeintegerOPTIONS(SEARCHABLE'Unsearchable',"teiid_excel:CELL_NUMBER"'3'),

CONSTRAINTPK0PRIMARYKEY(ROW_ID)

)OPTIONS("NAMEINSOURCE"'Sheet1',"teiid_excel:FILE"'names.xlsx',"teiid_excel:FIRST_DATA_ROW_NU

MBER"'2')

]]></metadata>

</model>

</vdb>

Note

"ExtendedcapabilitiesusingROW_IDcolumn"-Ifyoudefinecolumn,thathasextensionmetadataproperty"CELL_NUMBER"withvalue"ROW_ID",thenthatcolumnvaluecontainstherowinformationfromExceldocument.YoucanmarkthiscolumnasPrimaryKey.YoucanusethiscolumninSELECTstatementswitharestrictivesetofcapabilitiesincluding:comparisonpredicates,INpredicatesandLIMIT.Allothercolumnscannotbeusedaspredicatesinaquery.

Tip

Userdoesnothavetodependupon"sourcemetadata"import,orDesignertoolimporttocreatetheschemarepresentedbyExceldocument,theycanmanuallycreateasourcetableandaddtheappropriateextensionpropertiestomakeafullyfunctionalmodel.Ifyouintrospecttheschemamodelcreatedbytheimport,itwouldlooklikeabove.

TIP:CurrentlyExceltranslatordoesnotsupportupdates.

JCAResourceAdapterTheTeiidspecificExcelResourceAdapterdoesnotexist,usershoulduseFileJCAadapterwiththistranslator.SeeFileDataSourcesforopeningaFilebasedconnection.

NativeQueries

Note ThisfeatureisnotapplicableforExceltranslator.



558

Note ThisfeatureisnotapplicableforExceltranslator.


559

MongoDBTranslatorTheMongoDBtranslator,knownbythetypenamemongodb,providesarelationalviewofdatathatresidesinaMongoDBdatabase.ThistranslatoriscapableofconvertingTeiidSQLqueriesintoMongoDBbasedqueries.ItsupportsafullrangeofSELECT,INSERT,UPDATEandDELETEcalls.

MongoDBisadocumentbased"schema-less"databasewithitownquerylanguage-itdoesnotmapperfectlywithrelationalconceptsortheSQLquerylanguage.MoreandmoresystemsareusingaMongoDBkindofNOSQLstoreforscalabilityandperformance.Forexample,applicationslikestoringauditlogsormanagingwebsitedatafitswellwithMongoDB,anddoesnotrequireusingastructuraldatabaselikeOracle,Postgresetc.MongoDBusesJSONdocumentsasitsprimarystorageunit,andthosedocumentscanhaveadditionalembeddeddocumentsinsidetheparentdocument.Byusingembeddeddocumentsitco-locatestherelatedinformationtoachievede-normalizationthattypicallyrequireseitherduplicationofdataorjoinstoachievequeryinginarelationaldatabase.

TomakeMongoDBworkwithTeiidthechallengefortheMongoDBtranslatoris"HowtodesignaMongoDBstorethatcanachievethebalancebetweenrelationalanddocumentbasedstorage?"Inouropiniontheadvantagesof"schema-less"designaregreatatdevelopmenttime,notmuchatruntimeexceptinfewspecialsituations."Schema-less"canalsobeaproblemwithmigrationofapplicationversionsandtheabilitytoqueryandmakeuseofreturnedinformationeffectively.

SinceitishardandmaybeimpossibleincertainsituationstoderiveaschemabasedonexistingtheMongoDBcollection(s),Teiidapproachestheprobleminreversecomparedtoothertranslators.WhenworkingwithMongoDB,TeiidrequirestheusertodefinetheMongoDBschemaupfrontusingTeiidmetadata.SinceTeiidonlyallowsrelationalschemaasitsmetadata,theuserneedstodefinetheirMongoDBschemainrelationaltermsusingtables,procedures,andfunctions.ForthepurposesofMongoDB,theTeiidmetadatahasbeenextendedtosupportextensionpropertiesthatcanbedefinedonthetabletoconvertitintoaMongoDBbaseddocument.Theseextensionpropertiesletusersdefine,howaMongoDBdocumentisstructuredandstored.Basedontherelationships(primary-key,foreign-key)definedonatable,andthecardinality(ONE-to-ONE,ONE-to-MANY,MANY-to-ONE)relationsbetweentablesaremappedsuchthatrelatedinformationcanbeembeddedalongwiththeparentdocumentforco-location(seethede-normalizationcommentabove).Thusarelationalschemabaseddesign,butdocumentbasedstorageinMongoDB.CurrentlydirectmappingofMANY-to-MANYisnotsupported.

Whoistheprimaryaudienceforthistranslator?

Theabovemaynotsatisfyeveryuser’sneeds.ThedocumentstructureinMongoDBcanbemorecomplexthanwhatTeiidcancurrentlydefine.WehopethiswilleventuallycatchupinfutureversionsofTeiid.Thisiscurrentlydesignedfor:

1. Usersthatareusingrelationaldatabasesandwouldliketomove/migratetheirdatatoMongoDBtotakeadvantagesscalingandperformancewithoutmodifyingtheenduserapplicationscurrentlyrunning.

2. UsersthatarestartingoutwithMongoDBanddonothaveexperiencewithMongoDB,butareseasonedSQLdevelopers.ThisprovidesalowbarrierofentrycomparedtousingMongoDBdirectlyasanapplicationdeveloper.

3. IntegrateotherenterprisedatasourceswithMongoDBbaseddata.

Usage

Thenameofthetranslatortouseinvdb.xmlis"mongodb".Forexample:

<vdbname="nothwind"version="1">

<modelname="northwind">

<sourcename="local"translator-name="mongodb"connection-jndi-name="java:/mongoDS"/>

</model>

MongoDBTranslator

560

<vdb>

ThetranslatordoesnotprovideaconnectiontotheMongoDB.Forthatpurpose,TeiidhasaJCAadapterthatprovidesaconnectiontoMongoDBusingtheMongoDBJavaDriver.Todefinesuchconnector,usethefollowingXMLfragmentinstandalone-teiid.xml.Seeaexamplein"<jboss-as>/docs/teiid/datasources/mongodb"

<resource-adapters>

<resource-adapterid="mongodb">

<moduleslot="main"id="org.jboss.teiid.resource-adapter.mongodb"/>



<connection-definitionclass-name="org.teiid.resource.adapter.mongodb.MongoDBManagedConnectionF

actory"

jndi-name="java:/mongoDS"

enabled="true"


pool-name="teiid-mongodb-ds">



<config-propertyname="RemoteServerList">localhost:27017</config-property>



<config-propertyname="Database">test</config-property>





</resource-adapter>

</resource-adapters>

Theabovedefinesthetranslatorandconnector.FormorewaystocreatetheconnectorseeMongoDBDataSources.MongoDBtranslatorcanderivethemetadatabasedonexistingdocumentcollectionsinsomescenarios,howeverwhenworkingwithcomplexdocumentstheinterpretationofmetadatamaybeinaccurate,inthosesituationstheuserMUSTdefinethemetadata.Forexample,youcandefineaschemausingDDL:

<vdbname="nothwind"version="1">

<modelname="northwind">

<sourcename="local"translator-name="mongodb"connection-jndi-name="java:/mongoDS"/>



customer_idinteger,

FirstNamevarchar(25),

LastNamevarchar(25)

)OPTIONS(UPDATABLE'TRUE');

]]></metadata>

</model>

<vdb>

whenINSERToperationbelowexecutedagainsttableusingTeiid,

INSERTINTOCustomer(customer_id,FirstName,LastName)VALUES(1,'John','Doe');

MongoDBtranslatorwillcreateabelowdocumentintheMongoDB

{

_id:ObjectID("509a8fb2f3f4948bd2f983a0"),

customer_id:1,

FirstName:"John",

LastName:"Doe"

MongoDBTranslator

561

}

IfaPRIMARYKEYisdefinedonthetableas


customer_idintegerPRIMARYKEY,


LastNamevarchar(25)


thenthatcolumnnameisautomaticallyusedas"_id"fieldintheMongoDBcollection,thendocumentstructureisstoredintheMongoDBas

{

_id:1,

FirstName:"John",

LastName:"Doe"

}

IfyoudefinedthecompositePRIMARYKEYonCustomertableas


customer_idinteger,


LastNamevarchar(25),

PRIMARYKEY(FirstName,LastName)


thedocumentstructurewillbe

{

_id:{

FirstName:"John",

LastName:"Doe"

},

customer_id:1,

}

DataTypes

MongoDBtranslatorsupportsautomaticmappingofTeiiddatatypesintoMongoDBdatatypes,includingthesupportforBlobs,ClobsandXML.TheLOBsupportisbasedonGridFSinMongoDB.Arraysareintheformof

{

_id:1,

FirstName:"John",

LastName:"Doe"

Score:[89,"ninety",91.0]

}

aresupported.Usercangetindividualitemsinthearrayusingfunctionarray_get,orcantransformthearrayintotabularstructureusingARRATTABLE.

Note Notethateventhoughembeddeddocumentscanalsobeinarrays,thehandlingofembeddeddocumentsisdifferentfromarraywithscalarvalues.

MongoDBTranslator

562

RegularExpressions,MongoDB::Code,MongoDB::MinKey,MongoDB::MaxKey,MongoDB::OIDisnotcurrentlysupported.

ExtensionMetadataPropertiesToBuildComplexDocuments

UsingtheaboveDDLoranyothermetadatafacility,ausercanmapatableinarelationalstoreintoadocumentinMongoDB,howevertomakeeffectiveuseofMongoDB,youneedtobeabletobuildcomplexdocuments,thatcanco-locaterelatedinformation,sothatdatacanqueriedinasingleMongoDBquery.Otherwise,sinceMongoDBdoesnotsupportjoinrelationshipslikerelationaldatabase,youneedtoissuemultiplequeriestoretrieveandjoindatamanually.ThepowerofMongoDBcomesfromits"embedded"documentsanditssupportofcomplexdatatypeslikearraysanduseoftheaggregationframeworktobeabletoquerythem.Thistranslatorprovideswaytoachievethatgoals.

WhenyoudonotdefinethecomplexembeddeddocumentsinMongoDB,Teiidcanstepinforjoinprocessingandprovidethatfunctionality,howeverifyouwanttomakeuseofthepowerofMongoDBitselfinqueryingthedataandavoidbringingtheunnecessarydataandimproveperformance,youneedtolookintobuildingthesecomplexdocuments.

MongoDBtranslatordefinestwoadditionalmetadatapropertiesalongwithotherTeiidmetadatapropertiestoaidinbuildingthecomplex"embedded"documents.YoucanusethefollowingmetadatapropertiesinyourDDL.

teiid_mongo:EMBEDDABLE-Meansthatdatadefinedinthistableisallowedtobeincludedasan"embeddable"documentinanyparentdocument.Theparentdocumentisreferencedbytheforeignkeyrelationships.Inthisscenario,TeiidmaintainsmorethanonecopyofthedatainMongoDBstore,oneinitsowncollectionandalsoacopyineachoftheparenttablesthathaverelationshiptothistable.Youcanevennestembeddabletableinsideanotherembeddabletablewithsomelimitations.Usethispropertyontable,wheretablecanexist,encompassallitsrelationsonitsown.Forexample,a"Category"tablethatdefinesa"Product"’scategoryisindependentofProduct,whichcanbeembeddablein"Products"table.

teiid_mongo:MERGE-Meansthatdataofthistableismergedwiththedefinedparenttable.Thereisonlyasinglecopyofthedatathatisembeddedintheparentdocument.Parentdocumentisdefinedusingtheforeignkeyrelationships.

UsingtheabovepropertiesandFOREIGNKEYrelationships,wewillillustratehowtobuildcomplexdocumentsinMongoDB.

NoteUsage-Pleasenoteagiventablecancontaineitherthe"teiid_mongo:EMBEDDABLE"propertyorthe"teiid_mongo:MERGE"propertydefiningthetypeofnestinginMongoDB.Atableisnotallowedtohavebothproperties.

2-ONEMapping

IfyourcurrentDDLstructurerepresentingONE-2-ONErelationshipislike




LastNamevarchar(25)


CREATEFOREIGNTABLEAddress(

CustomerIdinteger,

Streetvarchar(50),

Cityvarchar(25),

Statevarchar(25),

Zipcodevarchar(6),

FOREIGNKEY(CustomerId)REFERENCESCustomer(CustomerId)


bydefault,thiswillproducetwodifferentcollectionsinMongoDB,likewithsampledataitwilllooklike

Customer

{

MongoDBTranslator

563

_id:1,

FirstName:"John",

LastName:"Doe"

}

Address

{

_id:ObjectID("..."),

CustomerId:1,

Street:"123Lane"

City:"NewYork",

State:"NY"

Zipcode:"12345"

}

YoucanenhancethestorageinMongoDBtoasinglecollectionbyusing"teiid_mongo:MERGE’extensionpropertyonthetable’sOPTIONSclause




LastNamevarchar(25)


CREATEFOREIGNTABLEAddress(


Streetvarchar(50),

Cityvarchar(25),

Statevarchar(25),

Zipcodevarchar(6),


)OPTIONS(UPDATABLE'TRUE',"teiid_mongo:MERGE"'Customer');

thiswillproducesinglecollectioninMongoDB,like

Customer

{

_id:1,

FirstName:"John",

LastName:"Doe",

Address:

{

Street:"123Lane",

City:"NewYork",

State:"NY",

Zipcode:"12345"

}

}

WiththeabovebothtablesaremergedintoasinglecollectionthatcanbequeriedtogetherusingtheJOINclauseintheSQLcommand.Sincetheexistenceofchild/additionalrecordhasnomeaningwithoutparenttableusingthe"teiid_mongo:MERGE"extensionpropertyisrightchoiceinthissituation.

Note NotethattheForeignKeydefinedonchildtable,mustrefertoPrimaryKeysonbothparentandchildtablestoformaOne-2-Onerelationship.

2-MANYMapping.

Typicallytherecanbemorethantwo(2)tablesinvolvedinthisrelationship.IfMANYsideisonlyassociatedsingletable,thenuse"teiid_mongo:MERGE"propertyonMANYsideoftableanddefineONEastheparent.Ifassociatedwithmorethansingletablethenuse"teiid_mongo:EMBEDDABLE".

MongoDBTranslator

564

ForexampleifyouhaveDDLlike




LastNamevarchar(25)


CREATEFOREIGNTABLEOrder(

OrderIDintegerPRIMARYKEY,

CustomerIdinteger,

OrderDatedate,

Statusinteger,



intheaboveaSingleCustomercanhaveMANYOrders.TherearetwooptionstodefinethehowwestoretheMongoDBdocument.Ifinyourschema,theCustomertable’sCustomerIdisonlyreferencedinOrdertable(i.e.CustomerinformationusedforonlyOrderpurposes),youcanuse




LastNamevarchar(25)




CustomerIdinteger,

OrderDatedate,

Statusinteger,


)OPTIONS(UPDATABLE'TRUE',"teiid_mongo:MERGE"'Customer');

thatwillproduceasingledocumentforCustomertablelike

{

_id:1,

FirstName:"John",

LastName:"Doe",

Order:

[

{

_id:100,

OrderDate:ISODate("2000-01-01T06:00:00Z")

Status:2

},

{

_id:101,


Status:5

}

...

]

}

IfCustomertableisreferencedinmoretablesotherthanOrdertable,thenuse"teiid_mongo:EMBEDDABLE"property




LastNamevarchar(25)

)OPTIONS(UPDATABLE'TRUE',"teiid_mongo:EMBEDDABLE"'TRUE');

MongoDBTranslator

565



CustomerIdinteger,

OrderDatedate,

Statusinteger,



CREATEFOREIGNTABLEComments(

CommentIDintegerPRIMARYKEY,

CustomerIdinteger,

Commentvarchar(140),



ThiscreatesthreedifferentcollectionsinMongoDB.

Customer

{

_id:1,

FirstName:"John",

LastName:"Doe"

}

Order

{

_id:100,

CustomerId:1,


Status:2

Customer:

{

FirstName:"John",

LastName:"Doe"

}

}

Comment

{

_id:12,

CustomerId:1,

Comment:"Thisworks!!!"

Customer:

{

FirstName:"John",

LastName:"Doe"

}

}

HereasyoucanseetheCustomertablecontentsareembeddedalongwithothertable’sdatawheretheywerereferenced.ThiscreatesduplicateddatawheremultipleoftheseembeddeddocumentsaremanagedautomaticallyintheMongoDBtranslator.

Note

AlltheSELECT,INSERT,DELETEoperationsthataregeneratedagainstthetableswith"teiid_mongo:EMBEDDABLE"propertyareatomic,exceptforUPDATES,astherecanbemultipleoperationsinvolvedtoupdateallthecopies.SincetherearenotransactionsinMongoDB,TeiidplanstoprovideautomaticcompensatingtransactionframeworkaroundthisinfuturereleasesTEIID-2957.

MANY-2-ONEMapping.

ThisissameasONE-2-MANY,seeabovetodefinerelationships.

Note Aparenttablecanhavemultiple"embedded"andaswellas"merge"documentsinsideit,itnotlimitedsoeitheroneorother.However,pleasenotethatMongoDBimposesdocumentsizeislimitedcannotexceed16MB.

MongoDBTranslator

566


MANY-2-MANYMapping.

Thiscanalsomappedwithcombinationof"teiid_mongo:MERGE"and"teiid_mongo:EMBEDDABLE"properties(partially).ForexampleifDDLlookslike



OrderDatedate,

Statusinteger


CREATEFOREIGNTABLEOrderDetail(

OrderIDinteger,

ProductIDinteger,

PRIMARYKEY(OrderID,ProductID),

FOREIGNKEY(OrderID)REFERENCESOrder(OrderID),

FOREIGNKEY(ProductID)REFERENCESProduct(ProductID)


CREATEFOREIGNTABLEProducts(

ProductIDintegerPRIMARYKEY,

ProductNamevarchar(40)


youmodifytheDDLlikebelow,tohave



OrderDatedate,

Statusinteger


CREATEFOREIGNTABLEOrderDetail(

OrderIDinteger,

ProductIDinteger,

PRIMARYKEY(OrderID,ProductID),

FOREIGNKEY(OrderID)REFERENCESOrder(OrderID),

FOREIGNKEY(ProductID)REFERENCESProduct(ProductID)

)OPTIONS(UPDATABLE'TRUE',"teiid_mongo:MERGE"'Order');

CREATEFOREIGNTABLEProducts(

ProductIDintegerPRIMARYKEY,

ProductNamevarchar(40)

)OPTIONS(UPDATABLE'TRUE',"teiid_mongo:EMBEDDABLE"'TRUE');

Thatwillproduceadocumentlike

{

_id:10248,

OrderDate:ISODate("1996-07-04T05:00:00Z"),

Status:5

OrderDetails:[

{

_id:{

OrderID:10248,

ProductID:11

Products:{

ProductID:11

ProductName:"Hammer"

}

}

},

{

MongoDBTranslator

567

_id:{

OrderID:10248,

ProductID:14

Products:{

ProductID:14

ProductName:"ScrewDriver"

}

}

}

]

}

Products

{

{

ProductID:11

ProductName:"Hammer"

}

{

ProductID:14

ProductName:"ScrewDriver"

}

}

Limitations

CurrentlynestedembeddingofdocumentshaslimitedsupportduetocapabilitiesofhandlingnestedarraysislimitedintheMongoDB.Nestingof"EMBEDDALBLE"propertywithmultiplelevelsisOK,howevermorethantwolevelswithMERGEisnotrecommended.Also,youneedtobecautionaboutnotexceedingthedocumentsizeof16MBforsinglerow,sodeepnestingisnotrecommended.

JOINSbetweenrelatedtables,MUSThaveusedeitherof"EMBEDDABLE"or"MERGE"property,otherwisethequerywillresultinerror.InorderforTeiidtocorrectlyplanandsupporttheJOINS,inthecasethatanytwotablesareNOTembeddedineachother,useallow-joins=falsepropertyontheForeignKeythatrepresentstherelation.Forexample:




LastNamevarchar(25)




CustomerIdinteger,

OrderDatedate,

Statusinteger,

FOREIGNKEY(CustomerId)REFERENCESCustomer(CustomerId)OPTIONS(allow-join'FALSE')


withtheexampleabove,Teiidwillcreatetwocollections,howeverwhenuserissuesquerysuchas

SELECTOrderID,LastNameFROMOrderJOINCustomerONOrder.CustomerId=Customer.CustomerId;

insteadofresultinginerror,theJOINprocessingwillhappenintheTeiidengine,withouttheabovepropertyitwillresultinanerror.

WhenyouuseabovepropertiesandcarefullydesigntheMongoDBdocumentstructure,Teiidtranslatorcanintelligentlycollatedatabasedontheirco-locationandtakeadvantageofitwhilequerying.

GeoSpatialfunctionsupport

MongoDBTranslator

568

MongoDBtranslatorsupportsgeospatialqueryoperatorsinthe"WHERE"clause,whenthedataisstoredintheGeoJSonformatintheMongoDBDocument.Thesupportedfunctionsare

CREATEFOREIGNFUNCTIONgeoIntersects(columnRefstring,typestring,coordinatesdouble[][])RETURNSboolean;

CREATEFOREIGNFUNCTIONgeoWithin(ccolumnRefstring,typestring,coordinatesdouble[][])RETURNSboolean;

CREATEFOREIGNFUNCTIONnear(ccolumnRefstring,coordinatesdouble[],maxdistanceinteger)RETURNSboolean;

CREATEFOREIGNFUNCTIONnearSphere(ccolumnRefstring,coordinatesdouble[],maxdistanceinteger)RETURNSboole

an;

CREATEFOREIGNFUNCTIONgeoPolygonIntersects(refstring,northdouble,eastdouble,westdouble,southdouble)

RETURNSboolean;

CREATEFOREIGNFUNCTIONgeoPolygonWithin(refstring,northdouble,eastdouble,westdouble,southdouble)RET

URNSboolean;

asamplequerylookslike

SELECTlocFROMmapswheremongo.geoWithin(loc,'LineString',((cast(1.0asdouble),cast(2.0asdouble)),(cast

(1.0asdouble),cast(2.0asdouble))))

CapabilitiesMongoDBtranslatordesignedontopoftheMongoDBaggregationframework,useofMongoDBversionthatsupportsthisframeworkismandatory.ApartfromSELECTqueries,thistranslatoralsosupportsINSERT,UPDATEandDELETEqueries.

Thistranslatorsupports

grouping

matching

sorting

filtering

limit

supportforLOBsusingGridFS

Compositeprimaryandforeignkeys.

Note example-Forafullexampleseehttps://github.com/teiid/teiid/blob/master/connectors/translator-mongodb/src/test/resources/northwind.ddl

NativeQueries

MongoDBsourceproceduresmaybecreatedusingtheteiid_rel:native-queryextension-seeParameterizableNativeQueries.Theprocedurewillinvokethenative-querysimilartoadirectprocedurecallwiththebenefitsthatthequeryispredeterminedandthatresultcolumntypesareknown,ratherthanrequiringtheuseofARRAYTABLEorsimilarfunctionality.



Bydefaultthenameoftheprocedurethatexecutesthequeriesdirectlyiscallednative.Overridetheexecutionproperty_DirectQueryProcedureNametochangeittoanothername.

MongoDBTranslator

569

https://github.com/teiid/teiid/blob/master/connectors/translator-mongodb/src/test/resources/northwind.ddl

TheMongoDBtranslatorprovidesaproceduretoexecuteanyad-hocaggregatequerydirectlyagainstthesourcewithoutTeiidparsingorresolving.Sincethemetadataofthisprocedure’sresultsarenotknowntoTeiid,theyarereturnedasanobjectarraycontainingsingleblobatarraylocationone(1).ThisblobcontainstheJSONdocument.XMLTABLEcanbeusedconstructtabularoutputforconsumptionbyclientapplications.

ExampleMongoDBDirectQuery

selectx.*fromTABLE(callnative('city;{$match:{"city":"FREEDOM"}}'))t,

xmltable('/city'PASSINGJSONTOXML('city',cast(array_get(t.tuple,1)asBLOB))COLUMNScitystring,

statestring)x

Intheaboveexample,acollectioncalled"city"islookedupwithfilterthatmatchesthe"city"namewith"FREEDOM",using"native"procedureandthenusingthenestedtablesfeaturetheoutputispassedtoaXMLTABLEconstruct,wheretheoutputfromtheprocedureissenttoaJSONTOXMLfunctiontoconstructaXMLthentheresultsofthatareexposedintabularform.

ThedirectqueryMUSTbeintheformat

"collectionName;{$pipelineinstr}+"

FromTeiid8.10,MongoDBtranslatoralsoallowstoexecuteShelltypejavascriptcommandslikeremove,drop,createIndex.Forthisthecommandneedstobeinformat

"$ShellCmd;collectionName;operationName;{$instr}+"

andexamplelookslike

"$ShellCmd;MyTable;remove;{qty:{$gt:20}}"

MongoDBTranslator

570

ObjectTranslatorTheObjecttranslator,knownbythenameofmap-cache,isabridgeforreadingandwritingjavaobjectsfromexternalsources(i.e.,Mapcache)anddeliveringthemtotheengineforprocessing.Andtoassistinprovidingthatbridge,theOBJECTTABLEfunctioncanbeusedtotransformcomplexjavaobjectsintorowsandcolumns.

SearchCapabilities

SupportsalocalcachethatisoftypeMapandituseskeysearchingonthemaptofindobjects.



SELECTcommand


InCriteria

Insert,UpdateandDelete



Metadata



Thetable"nameinsource"(NIS)willbethenameofthecachethistable/classisstored

Theprimaryobjectthatrepresentsthecachedobjectshouldhaveanameinsourceof'this'.Allothercolumnswillhavetheirnameinsource(whichdefaultstothecolumnname)interpretedasthepathtothecolumnvaluefromtheprimaryobject.

AllcolumnsthatarenottheprimarykeynorcoveredbyaluceneindexshouldbemarkedasSEARCHABLE'Unsearchable'.



Usingnativemetadataimportwillautomaticallydetermineaphsyicaltableforeachrootobjectandwillhaveeachtoplevelmemberrepresentedasacolumn.

OptionsforDefining

ObjectTranslator

571

Thefollowingisanexampleofakeysearchandaviewthatassociatedplayernameswiththeirteam.ThevdbdefinesthephysicalsourceandviewsusingDDL.ItusesaTeamObjectclass,shownbelow,withateamNamefieldthatisusedasitscachekeyandaStringlistofplayers.

publicclassTeamObject{

privateStringteamName;

privateList<String>players=newArrayList<String>();

publicStringgetTeamName(){

returnteamName;

}

publicvoidsetTeamName(StringteamName){

this.teamName=teamName;

}

publicList<String>getPlayers(){

returnplayers;

}

}

ThenativeimportlogicwillprovideyouwithaTeamObjectphysicaltablethatcanbequeried.AnequivalentTeamtableisshownherefordemonstrationpurposes.

<vdbname="team"version="1">

<modelname="Team"visible="false">

<sourcename="objsource"translator-name="map-cache"connection-jndi-name="java:cache-jndi"/>


CREATEFOREIGNTABLETeam(

TeamObjectObjectOPTIONS(NAMEINSOURCE'this',SEARCHABLE'Unsearchable'),

teamNamevarchar(255)PRIMARYKEY)

OPTIONS(NAMEINSOURCE'teams');

]]></metadata>

</model>

<modelname="TeamView"type="VIRTUAL">


CREATEVIEWPlayers(

TeamNamevarchar(255)PRIMARYKEY,

PlayerNamevarchar(255)

)

AS

SELECTt.TeamName,y.NameFROMTeamasT,

OBJECTTABLE('m.players'PASSINGT.TeamObjectasmCOLUMNSNamestring'teiid_row')asy;

]]></metadata>

</model>

</vdb>

Noticetheuseofthe[OBJECTABLE]functiontoparsetheobjectfromTeamandtransformintorowsandcolumn.Thisisonlyfordemonstrationpurposes,andisnotrequiredinordertoparsetheobjectintorowsandcolumns.

ThismetadatacouldalsobedefinedbyusingtheTeiidDesignerTeiidConnectionImporter.

JCAResourceAdapter

ObjectTranslator

572

ObjectTranslator

573

ODataTranslatorTheODatatranslator,knownbythetypename"odata"exposestheODataV2andV3datasourcesandusestheTeiidWSresourceadapterformakingwebservicecalls.ThistranslatorisextensionofWebServicesTranslator.

Note

WhatisOdata-TheOpenDataProtocol(OData)Webprotocolisforqueryingandupdatingdatathatprovidesawaytounlockyourdataandfreeitfromsilosthatexistinapplicationstoday.ODatadoesthisbyapplyingandbuildinguponWebtechnologiessuchasHTTP,AtomPublishingProtocol(AtomPub)andJSONtoprovideaccesstoinformationfromavarietyofapplications,services,andstores.ODataisbeingusedtoexposeandaccessinformationfromavarietyofsourcesincluding,butnotlimitedto,relationaldatabases,filesystems,contentmanagementsystemsandtraditionalWebsites.

UsingthisspecificationfromOASISgroup,withthehelpfromtheOData4Jframework,TeiidmapsODataentitiesintorelationalschema.TeiidsupportsreadingofCSDL(ConceptualSchemaDefinitionLanguage)fromtheODataendpointprovidedandconvertstheODataschemaintorelationalschema.ThebelowtableshowsthemappingselectionsinODataTranslatorfromCSDLdocument

OData MappedtoRelationalEntity

EntitySet Table

FunctionImport Procedure

AssosiationSet ForeignKeysontheTable*

ComplexType ignored**

AManytoManyassociationwillresultinalinktablethatcannotbeselectedfrom,butcanbeusedforjoinpurposes.

WhenusedinFunctions,animplicittableisexposed.Whenusedtodefineaembeddedtable,allthecolumnswillbein-lined

AllCRUDoperationswillbeappropriatelymappedtotheresultingentitybasedontheSQLsubmittedtotheODatatranslator.

Usage

UsageofaODatasourceissimilaraJDBCtranslator.Themetadataimportissupportedthroughthetranslator,oncethemetadataisimportedfromsourcesystemandexposedinrelationalterms,thenthissourcecanbequeriedasiftheEntitySetsandFunctionImportswerelocaltotheTeiidsystem.

ExecutionProperties


DatabaseTimeZoneThetimezoneofthedatabase.Usedwhenfetchingsdate,time,ortimestampvalues


SupportsOdataCount Supports$count true

SupportsOdataFilter Supports$filter true

SupportsOdataOrderBy Supports$orderby true

ODataTranslator

574

http://www.odata.org

http://code.google.com/p/odata4j/

SupportsOdataSkip Supports$skip true

SupportsOdataTop Supports$top true

ImporterProperties


schemaNamespace Namespaceoftheschematoimport null

entityContainer EntityContainerNametoimport defaultcontainer

ExampleimportersettingstoonlyimporttablesandviewsfromNetflixCatalog.

<propertyname="importer.schemaNamespace"value="System.Data.Objects"/>

<propertyname="importer.schemaPattern"value="NetflixCatalog"/>

Note

ODataServerisnotfullycompatible-Sometimesit’spossiblethattheodataserveryouarequeryingdoesnotfullyimplementallODataspecificationfeatures.IfyourODataimplementationdoesnotsupportacertainfeature,thenturnoffthecorrespondingcapabilityusing"executionProperties",sothatTeiidwillnotpushdowninvalidqueriestothetranslator.Forexample,toturnoff$filteryouaddfollowingtoyourvdb.xml

<translatorname="odata-override"type="odata">

<propertyname="SupportsOdataFilter"value="false"/>

</translator>

thenuse"odata-override"asthetranslatornameonyoursourcemodel.

TipNativeQueries-NativeordirectqueryexecutionisnotsupportedthroughODatatranslator.However,usercanuseWebServicesTranslator’sinvokehttpmethoddirectlytoissueaRestbasedcallandparseresultsusingSQLXML.

Tip WanttouseasServer?-TeiidcannotonlyconsumeODatabaseddatasources,butitcanexposeanydatasourceasanOdatabasedwebservice.FormoreinformationseeODataSupport.

JCAResourceAdapterTheresourceadapterforthistranslatorisaWebServiceDataSource.

ODataTranslator

575

ODataV4TranslatorTheODataV4translator,knownbythetypename"odata4"exposestheODataVersion4datasourcesandusestheTeiidWSresourceadapterformakingwebservicecalls.ThistranslatorisextensionofWebServicesTranslator.

Note

WhatisOdata-TheOpenDataProtocol(OData)Webprotocolisforqueryingandupdatingdatathatprovidesawaytounlockyourdataandfreeitfromsilosthatexistinapplicationstoday.ODatadoesthisbyapplyingandbuildinguponWebtechnologiessuchasHTTP,AtomPublishingProtocol(AtomPub)andJSONtoprovideaccesstoinformationfromavarietyofapplications,services,andstores.ODataisbeingusedtoexposeandaccessinformationfromavarietyofsourcesincluding,butnotlimitedto,relationaldatabases,filesystems,contentmanagementsystemsandtraditionalWebsites.

UsingthisspecificationfromOASISgroup,withthehelpfromtheOlingoframework,TeiidmapsODataV4CSDL(ConceptualSchemaDefinitionLanguage)documentfromtheODataendpointprovidedandconvertstheODatametadataintoTeiid’srelationalschema.ThebelowtableshowsthemappingselectionsinODataV4TranslatorfromCSDLdocument

OData MappedtoRelationalEntity

EntitySet Table

EntityType Tablesee[1]

ComplexType Tablesee[2]

FunctionImport Procedure[3]

ActionImport Procedure[3]

NavigationProperties Table[4]

[1]OnlyiftheEntityTypeisexposedastheEntitySetintheEntityContainer[2]OnlyifthecomplextypeisusedaspropertyintheexposedEntitySet.Thistablewillbedesignedaschildtablewithforeignkey[1to1]or[1tomany]relationshiptotheparent[3]IfthereturntypeisEntityTypeorComplexType,theprocedureisdesignedtoreturnatable[4]Navigationpropertiesareexposedastables.Thetablewillbecreatedwithforeignkeyrelationshiptotheparent.

AllCRUDoperationswillbeappropriatelymappedtotheresultingentitybasedontheSQLsubmittedtotheODatatranslator.

Usage

UsageofaODatasourceissimilaraJDBCtranslator.Themetadataimportissupportedthroughthetranslator,oncethemetadataisimportedfromsourcesystemandexposedinrelationalterms,thenthissourcecanbequeriedasiftheEntitySets,FunctionImportsandActionImportswerelocaltotheTeiidsystem.

ThebelowissampleVDBthatcanreadmetadataservicefromTripPinserviceonhttp://odata.orgsite.

<vdbname="trippin"version="1">

<modelname="trippin">

<sourcename="odata4"translator-name="odata4"connection-jndi-name="java:/tripDS"/>

</model>

</vdb>

Therequiredresource-adapterconfigurationwilllooklike

ODataV4Translator

576

http://www.odata.org

http://olingo.apache.org/

http://odata.org

<resource-adapterid="trippin">





"java:/tripDS"enabled="true"use-java-context="true"pool-name="teiid-trip-ds">

<config-propertyname="EndPoint">

http://services.odata.org/V4/(S(va3tkzikqbtgu1ist44bbft5))/TripPinServiceRW

</config-property>



</resource-adapter>

Onceyouconfigureaboveresource-adapteranddeploytheVDBsuccessfully,thenyoucanconnecttotheVDBdeployedusingTeiidJDBCdriverandissueSQLstatementslike

SELECT*FROMtrippin.People;

SELECT*FROMtrippin.PeopleWHEREUserName='russelwhyte';

SELECT*FROMtrippin.PeoplepINNERJOINtrippin.People_FriendspfONp.UserName=pf.People_UserName;(notet

hatPeople_UserNameisimplicitlyaddedbyTeiidmetadata)

EXECGetNearestAirport(lat,lon);

ConfigurationofTranslator

ExecutionProperties

Executionpropertiesextend/limitthefunctionalityofthetranslatorbasedonthephysicalsourcecapabilities.Sometimesdefaultpropertiesneedtoadjustedforproperexecutionofthetranslator.

ExecutionProperties







SupportsUpdates SupportsINSERT/UPDATE/DELETE true

Sometimesit’spossiblethattheodataserveryouarequeryingdoesnotfullyimplementallODataspecificationfeatures.IfyourODataimplementationdoesnotsupportacertainfeature,thenturnoffthecorrespondingcapabilityusing"executionProperties",sothatTeiidwillnotpushdowninvalidqueriestothetranslator.Forexample,toturnoff$filteryouaddfollowingtoyourvdb.xml

<translatorname="odata-override"type="odata">

<propertyname="SupportsOdataFilter"value="false"/>

</translator>

thenuse"odata-override"asthetranslatornameonyoursourcemodel.

ODataV4Translator

577

ImporterProperties

Importerpropertiesdefinethebehaviorofthetranslatorduringthemetadataimportfromthephysicalsource.

ImporterProperties


schemaNamespace Namespaceoftheschematoimport null

ExampleimportersettingstoonlyimporttablesandviewsfromTrippinserviceexposedonodata.org

<propertyname="importer.schemaNamespace"value="Microsoft.OData.SampleService.Models.TripPin"/>

Youcanleavethispropertyundefined,asifitdoesnotfindoneconfiguredthetranslatorwillselectthedefaultnameoftheEntityContainer.

JCAResourceAdapter

TheresourceadapterforthistranslatorisaWebServiceDataSource.

NoteNativeQueries-NativeordirectqueryexecutionisnotsupportedthroughODatatranslator.However,usercanuseWebServicesTranslator’sinvokehttpmethoddirectlytoissueaRestbasedcallandparseresultsusingSQLXML.

Note WanttouseasODataServer?-TeiidcannotonlyconsumeODatabaseddatasources,butitcanexposeanydatasourceasanODatabasedwebservice.FormoreinformationseeODataSupport.

ODataV4Translator

578

http://services.odata.org/V4/(S(nivess3y23eyhit4jbppgtdj))/TripPinServiceRW/$metadata

SwaggerTranslatorTheSwaggertranslator,knownbythetypename"swagger"exposestheSwaggerdatasourcesinrealationalconceptsandusestheTeiidWSresourceadapterformakingwebservicecalls.

Note

WhatisSwagger-http://swagger.io/[OpenAPISpecification(Swagger)]SwaggerisasimpleyetpowerfulrepresentationofyourRESTfulAPI.WiththelargestecosystemofAPItoolingontheplanet,thousandsofdevelopersaresupportingSwaggerinalmosteverymodernprogramminglanguageanddeploymentenvironment.WithaSwagger-enabledAPI,yougetinteractivedocumentation,clientSDKgenerationanddiscoverability.

StartingJanuary1st2016theSwaggerSpecificationhasbeendonatedtotheOpenAPIInitiative(OAI)andhasbeenrenamedtotheOpenAPISpecification.

UsageUsageofaSwaggersourceissimilaranyothertranslatorinTeiid.Themetadataimportissupportedthroughthetranslator,themetadataisimportedfromsourcesystem’sswagger.jsonfileandthenAPIfromthisfileisexposedasstoredproceduresinTeiid,thensourcesystemcanbequeriedbyexecutingthesestoredproceduresinTeiidsystem.

ThebelowissampleVDBthatcanreadmetadatafromPetstorereferenceserviceonhttp://petstore.swagger.io/site.

<vdbname="petstore"version="1">

<modelvisible="true"name="m">

<sourcename="s"translator-name="swagger"connection-jndi-name="java:/swagger"/>

</model>

</vdb>

Therequiredresource-adapterconfigurationwilllooklike

<resource-adapterid="swagger">





"java:/swagger"enabled="true"use-java-context="true"pool-name="teiid-swagger-ds">


http://petstore.swagger.io/v2

</config-property>



</resource-adapter>

Onceyouconfigureaboveresource-adapteranddeploytheVDBsuccessfully,thenyoucanconnecttotheVDBdeployedusingTeiidJDBCdriverandissueSQLstatementslike

EXECfindPetsByStatus(('sold',))

EXECgetPetById(1461159803)

EXECdeletePet('',1461159803)

ConfigurationofTranslator

ExecutionProperties

SwaggerTranslator

579

http://swagger.io/

http://petstore.swagger.io/

Executionpropertiesextend/limitthefunctionalityofthetranslatorbasedonthephysicalsourcecapabilities.Sometimesdefaultpropertiesneedtoadjustedforproperexecutionofthetranslator.

ExecutionProperties

none

ImporterProperties

Importerpropertiesdefinethebehaviorofthetranslatorduringthemetadataimportfromthephysicalsource.

ImporterProperties


useDefaultHost

UsedefaulthostspecifiedintheSwaggerfile;Defaultstotrue,whenfalseusestheendpointintheresource-adapter

true

preferredSchemePreferredSchemetousewhenSwaggerfilesupportsmultipleinvocationschemeslikehttp,https

null

preferredProducesPreferredAcceptMIMEtypeheader,thisshouldbeoneoftheSwagger'produces'types;

application/json

preferredConsumesPreferredContent-TypeMIMEtypeheader,thisshouldbeoneoftheSwagger'consumer'types;

application/json

Exampleimportersettingstoavoidcallinghostdefinedontheswagger.jsonfile

<propertyname="importer.useDefaultHost"value="false"/>

JCAResourceAdapter


NoteNativeQueries-NativeordirectqueryexecutionisnotsupportedthroughSwaggertranslator.However,usercanuseWebServicesTranslator’sinvokehttpmethoddirectlytoissueaRestbasedcallandparseresultsusingSQLXML.

Limitations

"application/xml"mimetypeinboth"Accept"and"Content-Type"iscurrentlynotsupported

File,Mapproeprtiesarecurrentlynotsupported,thusanymulti-partpayloadsarenotsupported

Securitymetadataiscurrentlynotsupported

Custompropertiesthatstartwith"x-"arenotsupported.

Schemawith"allof","multipleof","items"fromJSONschemaarenotsupported

SwaggerTranslator

580

SwaggerTranslator

581

OLAPTranslatorTheOLAPServicestranslator,knownbythetypenameolap,exposesstoredproceduresforcallinganalysissevicesbackedbyaOLAPserverusingMDXquerylanguage.Thistranslatorexposesastoredprocedure,invokeMDX,thatreturnsaresultsetcontainingtuplearrayvaluesforagivenMDXquery.invokeMDXwillcommonlybeusedwiththeARRAYTABLEtablefunctiontoextracttheresults.

SincetheCubemetadataexposedbytheOLAPserversandrelationaldatabasemetadataaresodifferent,thereisnosinglewaytomapthemetadatafromonetoother.ItisbesttoqueryOLAPsystemusingitsownnativeMDXlanguagethrough.MDXqueriesmybedefinedstaticallyorbuiltdynamicallyinTeiid’sabstractionlayers.

Usage

Theolaptranslatorexposesonelowlevelprocedureforaccessingolapservices.

InvokeMDXProcedure

invokeMdxreturnsaresultsetofthetuplesasarrayvalues.

ProcedureinvokeMdx(mdxinSTRING,paramsVARIADICOBJECT)returnstable(tupleobject)

ThemdxparameterisaMDXquerytobeexecutedontheOLAPserver.

Theresultsofthequerywillbereturnedsuchthateachrowontherowaxiswillbepackedintoanarrayvaluethatwillfirstcontaineachhierarchymembernameontherowaxistheneachmeasurevaluefromthecolumnaxis.

TheuseofDataRolesshouldbeconsideredtopreventarbitraryMDXfrombeingsubmittedtotheinvokeMDXprocedure.

NativeQueries

OLAPsourceproceduresmaybecreatedusingtheteiid_rel:native-queryextension-seeParameterizableNativeQueries.

Theparametervaluesubstitutiondirectlyinsertsboolean,andnumbervalues,andtreatsallothervaluesasstringliterals.

Theprocedurewillinvokethenative-querysimilartoaninvokeMdxcallwiththebenefitsthatthequeryispredeterminedandthatresultcolumntypesareknown,ratherthanrequiringtheuseofARRAYTABLEorsimilarfunctionality.

DirectQueryProcedureTheinvokeMdxprocedureisthedirectqueryprocedurefortheOLAPtranslator.Itmaybedisabledorhaveit’snamechangedviathecommondirectquerytranslatorpropertiesjustlikeanyothersource.Acalltothedirectqueryprocedurewithoutanyparameterswillnotattempttoparsethemdxqueryforparameterization.Ifparametersareused,thevaluesubstitutiondirectlyinsertsboolean,andnumbervalues,andtreatsallothervaluesasstringliterals.

JCAResourceAdapter

OLAPTranslator

582

TheresourceadapterforthistranslatorprovidedthroughdatasourceinWildFly,RefertoAdminGuidefor"JDBCDataSources"configurationsection.Twosample-ds.xmlfilesprovidedforaccessingOLAPserversinteiid-examplessection.OneisMondrianspecific,whenMondrianserverisdeployedinthesameWildFlyasTeiid(mondrian-ds.xml).ToaccessanyotherOLAPserversusingXMLAinterface,thedatasourceforthemcanbecreatedusingthemexampletemplateolap-xmla-ds.xml

OLAPTranslator

583

SalesforceTranslatorsTheSalesforcetranslatorsupportstheSELECT,DELETE,INSERTandUPDATEoperationsagainstaSalesforce.comaccount.ItisdesignedforusewiththeTeiidSalesforceresourceadapter.

SalesforceAPIVersionSupport

salesforce

Thetranslator,knownbythetypenamesalesforce,providesSalesforceAPI22.0support.ThetranslatormustbeusedwiththecorrespondingSalesforceresourceadapterofthesameAPIversion.SalesforceAPIversion22.0supporthasbeendeprecated.

salesforce-34

Thetranslator,knownbythetypenameofsalesforce-34,providesSalesforceAPI34.0support.ThetranslatormustbeusedwiththecorrespondingSalesforceresourceadapterofthesameAPIversion.

OtherAPIVersions

IfyouneedconnectivitytoanAPIversionotherthanwhatisbuiltin,pleaseutilizetheprojecthttps://github.com/teiid/salesforcetogeneratenewresourceadapter/translatorpair.

ExecutionProperties


ModelAuditFeilds AuditModelFields false

MaxBulkInsertBatchSize BatchSizetousetoinsertbulkinserts 2048

SupportsGroupBy

SupportsGroupByPushdown.SettofalsetohaveTeiidprocessgroupbyaggregations,suchasthosereturningmorethan2000rowswhicherrorinSOQL.

true

TheSalesforcetranslatorcanimportmetadata.

ImportProperties


NormalizeNames

Iftheimportershouldattempttomodifytheobject/fieldnamessothattheycanbeusedunquoted.

false true


584


excludeTables

Acase-insensitiveregularexpressionthatwhenmatchedagainstatablenamewillexcludeitfromimport.Appliedaftertablenamesareretrieved.Useanegativelook-ahead(?!<inclusionpattern>).*toactasaninclusionfilter.

false n/a

includeTables

Acase-insensitiveregularexpressionthatwhenmatchedagainstatablenamewillbeincludedduringimport.Appliedaftertablenamesareretrievedfromsource.

false n/a

importStatstics

RetrievescardinalitiesduringimportusingtheRESTAPIexplainplanfeature.

false false

NOTEWhenboth includeTablesandexcludeTablespatternsarepresentduringtheimport,the_includeTablespatternmatchedfirst,thentheexcludePatternswillbeapplied.

TIPTeiidtranslatorusesSalesforcePartnerAPIlibrariestoaccesstheSalesforcesystem.BydefaultTeiidusesPartnerAPIversion"22".MetadataretrievalusingthetranslatorandexecutionofqueriesagainstSalesforceusingthismetadataarestronglydependentupontheAPIversionthathasbeenused.ItisrequiredthatyouusesameAPIversionsforbothMetadataretrievalandqueryexecution.ForthisreasonifyouhaveolderVDBSthenyoueitherneedtore-importthemetadataorkeepusingthedefaultversion.ForanyreasonyouneedtouseadifferentversionofAPIthan"22",thenyoucanprovidethenewtranslatorandresource-adaptercombinationforthatAPI.Foryourconvenienceweprovidedatemplateprojecthttps://github.com/teiid/salesforcethatyoucanbuildanddeployintoTeiidsystemforthenewversionoftheAPI.IfyouareusingTeiidEmbedded,thenyoucouldsimplychoosetoreplacethekittedsalesforcejarswithalaterversion.Uptoversionv34isknowntobecompatible.

SQLProcessing

Salesforcedoesnotprovidethesamesetoffunctionalityasarelationaldatabase.Forexample,Salesforcedoesnotsupportarbitraryjoinsbetweentables.However,workingincombinationwiththeTeiidQueryPlanner,theSalesforceconnectorsupportsnearlyalloftheSQLsyntaxsupportedbytheTeiid.

TheSalesforceConnectorexecutesSQLcommandsby"pushingdown"thecommandtoSalesforcewheneverpossible,basedonthesupportedcapabilities.TeiidwillautomaticallyprovideadditionaldatabasefunctionalitywhentheSalesforceConnectordoesnotexplicitlyprovidesupportforagivenSQLconstruct.IncaseswherecertainSQLcapabilitiescannotbepusheddowntoSalesforce,Teiidwillpushdownthecapabilitiesthataresupported,andfetchasetofdatafromSalesforce.Then,Teiidwillevaluatetheadditionalcapabilities,creatingasubsetoftheoriginaldataset.Finally,Teiidwillpasstheresulttotheclient.

IfyouareissuingquerieswithagroupbyclauseandreceiveanerrorforsalesforcerelatedtoqueryMorenotbeingsupported,youmayeitheraddlimitsorsettheexecutionpropertySupportsGroupBytofalse.

SELECTsum(Reports)FROMSupervisorwhereDivision='customersupport';

NeitherSalesforcenortheSalesforceConnectorsupportthesum()scalarfunction,buttheydosupportCompareCriteriaEquals,sothequerythatispassedtoSalesforcebytheconnectorwillbetransformedtothisquery.

SELECTReportsFROMSupervisorwhereDivision='customersupport';


585


Thesum()scalarfunctionwillbeappliedbytheTeiidQueryEnginetotheresultsetreturnedbytheconnector.

InsomecasesmultiplecallstotheSalesforceapplicationwillbemadetosupporttheSQLpassedtotheconnector.

DELETEFromCaseWHEREStatus='Closed';

TheAPIinSalesforcetodeleteobjectsonlysupportsdeletingbyID.InordertoaccomplishthistheSalesforceconnectorwillfirstexecuteaquerytogettheIDsofthecorrectobjects,andthendeletethoseobjects.SotheaboveDELETEcommandwillresultinthefollowingtwocommands.

SELECTIDFromCaseWHEREStatus='Closed';

DELETEFromCasewhereIDIN(<resultofquery>);

NOTETheSalesforceAPIDELETEcallisnotexpressedinSQL,buttheaboveisanequivalentSQLexpression.

It’susefultobeawareofunsupportedcapabilities,inordertoavoidfetchinglargedatasetsfromSalesforceandmakingyouqueriesasperformantaspossible.SeeallSupportedCapabilities.

SelectingfromMulti-SelectPicklists

Amulti-selectpicklistisafieldtypeinSalesforcethatcancontainmultiplevaluesinasinglefield.QuerycriteriaoperatorsforfieldsofthistypeinSOQLarelimitedtoEQ,NE,includesandexcludes.ThefullSalesforcedocumentationforselectingfrommullti-selectpicklistscanbefoundatthefollowinglinkQueryingMulit-selectPicklists

TeiidSQLdoesnotsupporttheincludesorexcludesoperators,buttheSalesforceconnectorprovidesuserdefinedfunctiondefinitionsfortheseoperatorsthatprovidedequivalentfunctionalityforfieldsoftypemulti-select.Thedefinitionforthefunctionsis:

booleanincludes(Columncolumn,Stringparam)

booleanexcludes(Columncolumn,Stringparam)

Forexample,takeasinglemulti-selectpicklistcolumncalledStatusthatcontainsallofthesevalues.

current

working

critical

Forthatcolumn,allofthebelowarevalidqueries:

SELECT*FROMIssueWHEREtrue=includes(Status,'current,working');

SELECT*FROMIssueWHEREtrue=excludes(Status,'current,working');

SELECT*FROMIssueWHEREtrue=includes(Status,'current;working,critical');

EQandNEcriteriawillpasstoSalesforceassupplied.Forexample,thesequerieswillnotbemodifiedbytheconnector.

SELECT*FROMIssueWHEREStatus='current';

SELECT*FROMIssueWHEREStatus='current;critical';

SELECT*FROMIssueWHEREStatus!='current;working';

SelectingAllObjects


586

http://www.salesforce.com/us/developer/docs/soql_sosl/Content/sforce_api_calls_soql_querying_multiselect_picklists.htm

TheSalesforceconnectorsupportsthecallingthequeryAlloperationfromtheSalesforceAPI.ThequeryAlloperationisequivalenttothequeryoperationwiththeexceptionthatitreturnsdataaboutallcurrentanddeletedobjectsinthesystem.

TheconnectordeterminesifitwillcallthequeryorqueryAlloperationviareferencetotheisDeletedpropertypresentoneachSalesforceobject,andmodeledasacolumnoneachtablegeneratedbytheimporter.BydefaultthisvalueissettoFalsewhenthemodelisgeneratedandthustheconnectorcallsquery.UsersarefreetochangethevalueinthemodeltoTrue,changingthedefaultbehaviouroftheconnectortobequeryAll.

ThebehaviorisdifferentifisDeletedisusedasaparameterinthequery.IftheisDeletedcolumnisusedasaparameterinthequery,andthevalueis'true'theconnectorwillcallqueryAll.

select*fromContactwhereisDeleted=true;

IftheisDeletedcolumnisusedasaparameterinthequery,andthevalueis'false'theconnectorperformthedefaultbehaviorwillcallquery.

select*fromContactwhereisDeleted=false;

SelectingUpdatedObjects

IftheoptionisselectedwhenimportingmetadatafromSalesforce,aGetUpdatedprocedureisgeneratedinthemodelwiththefollowingstructure:

GetUpdated(ObjectNameINstring,

StartDateINdatetime,

EndDateINdatetime,

LatestDateCoveredOUTdatetime)

returns

IDstring

SeethedescriptionoftheGetUpdatedoperationintheSalesforcedocumentationforusagedetails.

SelectingDeletedObjects

IftheoptionisselectedwhenimportingmetadatafromSalesforce,aGetDeletedprocedureisgeneratedinthemodelwiththefollowingstructure:

GetDeleted(ObjectNameINstring,

StartDateINdatetime,

EndDateINdatetime,

EarliestDateAvailableOUTdatetime,

LatestDateCoveredOUTdatetime)

returns

IDstring,

DeletedDatedatetime

SeethedescriptionoftheGetDeletedoperationintheSalesforcedocumentationforusagedetails.

RelationshipQueries


587

http://www.salesforce.com/us/developer/docs/api/Content/sforce_api_calls_getupdated.htm

http://www.salesforce.com/us/developer/docs/api/Content/sforce_api_calls_getdeleted.htm

Salesforcedoesnotsupportjoinslikearelationaldatabase,butitdoeshavesupportforqueriesthatincludeparent-to-childorchild-to-parentrelationshipsbetweenobjects.ThesearetermedRelationshipQueries.TheSalesForceconnectorsupportsRelationshipQueriesthroughOuterJoinsyntax.

SELECTAccount.name,Contact.NamefromContactLEFTOUTERJOINAccount

onContact.Accountid=Account.id

ThisqueryshowsthecorrectsyntaxtoqueryaSalesForcemodelwithtoproducearelationshipqueryfromchildtoparent.ItresolvestothefollowingquerytoSalesForce.

SELECTContact.Account.Name,Contact.NameFROMContact

selectContact.Name,Account.NamefromAccountLeftouterJoinContact

onContact.Accountid=Account.id

ThisqueryshowsthecorrectsyntaxtoqueryaSalesForcemodelwithtoproducearelationshipqueryfromparenttochild.ItresolvestothefollowingquerytoSalesForce.

SELECTAccount.Name,(SELECTContact.NameFROM

Account.Contacts)FROMAccount

SeethedescriptionoftheRelationshipQueriesoperationintheSalesForcedocumentationforlimitations.

BulkInsertQueries

SalesForcetranslatoralsosupportsbulkinsertstatementsusingJDBCbatchsemanticsorSELECTINTOsemantics.ThebatchsizeisdeterminedbytheexecutionpropertyMaxBulkInsertBatchSize,whichcanbeoverriddeninthevdb.xmlfile.Thedefaultvalueofthebatchis2048.ThebulkinsertfeatureusestheasyncRESTbasedAPIexposedbySalesforceforexecutionforbetterperformance.


ThefollowingarethetheconnectorcapabilitiessupportedbytheSalesforceConnector.TheseSQLconstructswillbepusheddowntoSalesforce.

SELECTcommand

INSERTCommand

UPDATECommand

DELETECommand

CompareCriteriaEquals

InCriteria

LikeCriteria-SupportedforStringfieldsonly.

RowLimit

AggregatesCountStar

NotCriteria


588

http://www.salesforce.com/us/developer/docs/api/index_Left.htm#StartTopic=Content/sforce_api_calls_soql_relationships.htm

OrCriteria

CompareCriteriaOrdered

OuterJoinswithjoincriteriaKEY

NativeQueriesSalesforceproceduresmayoptionallyhavenativequeriesassociatedwiththem-seeParameterizableNativeQueries.Theoperationprefix(select;,insert;,update;,delete;-seebelowformore)mustbepresentinthenative-query,butitwillnotbeissuedaspartofthequerytothesource.

ExampleDDLforaSFnativeprocedure

CREATEFOREIGNPROCEDUREproc(arg1integer,arg2string)OPTIONS("teiid_rel:native-query"'search;SELECT...

complexSOQL...WHEREcol1=$1andcol2=$2')returns(col1string,col2string,col3timestamp);




TheSalesforcetranslatorprovidesaproceduretoexecuteanyad-hocSOQLquerydirectlyagainstthesourcewithoutTeiidparsingorresolving.Sincethemetadataofthisprocedure’sresultsarenotknowntoTeiid,theyarereturnedasanobjectarray.ARRAYTABLEcanbeusedconstructtabularoutputforconsumptionbyclientapplications.Teiidexposesthisprocedurewithasimplequerystructureasfollows:

Select

SelectExample

SELECTx.*FROM(callsf_source.native('search;SELECTAccount.Id,Account.Type,Account.NameFROMAccount'))w,


fromtheabovecode,the"search"keywordfollowedbyaquerystatement.

Note TheSOQListreatedasaparameterizednativequerysothatparametervaluesmaybeinsertedinthequerystringproperly-seeParameterizableNativeQueries

TheresultsreturnedbysearchmaycontaintheobjectIdasthefirstcolumnvalueregardlessofwhetheritwasselected.Alsoqueriesthatselectcolumnsfrommultipleobjecttypeswillnotbecorrect.

Delete

DeleteExample

SELECTx.*FROM(callsf_source.native('delete;','id1','id2'))w,


formtheabovecode,the"delete;"keywordfollowedbytheidstodeleteasvarargs.

CreateorUpdate


589

CreateExample

SELECTx.*FROM

(callsf_source.native('create;type=table;attributes=one,two,three','one',2,3.0))w,


formtheabovecode,the"create"or"update"keywordmustbefollowedbythefollowingproperties.Attributesmustbematchedpositionallybytheprocedurevariables-thusintheexampleattributetwowillbesetto2.

PropertyName Description Required

type TableName Yes

attributes commaseparatedlistofnamesofthecolumns no

Thevaluesforeachattributeisspecifiedasseparateargumenttothe"native"procedure.

Updateissimilartocreate,withonemoreextrapropertycalled"id",whichdefinesidentifierfortherecord.

UpdateExample

SELECTx.*FROM

(callsf_source.native('update;id=pk;type=table;attributes=one,two,three','one',2,3.0))w,


Tip Bydefaultthenameoftheprocedurethatexecutesthequeriesdirectlyiscallednative,howeverusercan+setoverrideexecutionpropertyvdb.xmlfiletochangeit.

JCAResourceAdapter

TheresourceadapterforthistranslatorisprovidedthroughSalesforceDataSources.RefertoAdminGuideforconfiguration.


590

SAPGatewayTranslatorTheSAPGatewayTranslator,knownbythetypenamesap-gateway,providesatranslatorforaccessingtheSAPGatewayusingtheODataprotocol.ThistranslatorisextensionofODataTranslatorandusesTeiidWSresourceadapterformakingwebservicecalls.ThistranslatorunderstandsthemostoftheSAPspecificODataextensionstothemetadatadefinedinthedocumentSAPAnnotationsforODataVersion2.0

WhenthemetadataisimportedfromSAPGateway,theTeiidmodelsarecreatedtoaccordinglyforSAPspecificEntitySetandPropertyannotationsdefinedindocumentabove.

Thefollowing"executionproperties"aresupportedinthistranslator

ExecutionProperties


DatabaseTimeZoneThetimezoneofthedatabase.Usedwhenfetchingsdate,time,ortimestampvalues







BasedonhowyouimplementedyourSAPGatewayservice,ifcanchoosetoturnoffsomeofthefeaturesabove.

Note

Usingpagable,topablemetadataextensions?-Ifmetadataonyourservicedefined"pagable"and/or"topable"as"false"onanytable,youmustturnoff"SupportsOdataTop"and"SupportsOdataSkip"execution-propertiesinyourtranslator,sothatyouwillnotendupwithwrongresults.SAPmetadatahascapabilitytocontroltheseinafinegrainedfashionanyonEnitySet,howeverTeiidcanonlycontroltheseattranslatorlevel.

Note

SAPExamples-Sampleexamplesdefinedathttp://scn.sap.com/docs/DOC-31221,wefoundtobelackinginfullmetadataincertainexamples.Forexample,"filterable"clauseneverdefinedonsomeproperties,butifyousendarequest$filteritwillsilentlyignoreit.YoucanverifythisbehaviorbydirectlyexecutingtheRESTserviceusingawebbrowserwithrespectivequery.So,Makesureyouhaveimplementedyourservicecorrectly,oryoucanturnoffcertainfeaturesinthistranslatorbyusing"executionproperties"override.SeeanexampleinODataTranslator

SAPGatewayTranslator

591

http://scn.sap.com/docs/DOC-44986

http://scn.sap.com/docs/DOC-31221

WebServicesTranslatorTheWebServicestranslator,knownbythetypenamews,exposesstoredproceduresforcallingwebservicesbackedbyaTeiidWSresourceadapter.TheWSresourceadaptermayoptionallybeconfiguredtopointataspecificWSDL.ResultsfromthistranslatorwillcommonlybeusedwiththeTEXTTABLEorXMLTABLEtablefunctionstouseCSVorXMLformateddata.

ExecutionProperties

Name Description WhenUsed Default

DefaultBinding

Thebindingthatshouldbeusedifoneisnotspecified.CanbeoneofHTTP,SOAP11,orSOAP12

invoke* SOAP12

DefaultServiceMode

Thedefaultservicemode.ForSOAP,MESSAGEmodeindicatesthattherequestwillcontaintheentireSOAPenvelopeandnotjustthecontentsoftheSOAPbody.CanbeoneofMESSAGEorPAYLOAD

invoke*orWSDLcall PAYLOAD

XMLParamName

UsedwiththeHTTPbinding(typicallywiththeGETmethod)toindicatethattherequestdocumentshouldbepartofthequerystring.

invoke* null-unused

NoteSettingtheproperbindingvalueonthetranslatorisrecommendedasitremovestheneedforcallerstopassanexplicitvalue.IfyourserviceisactuallyusesSOAP11,butthebindingusedSOAP12youwillreceiveexecutionfailures.

Therearenowsimportersettings,butitcanprovidemetadataforVDBs.IftheconnectionisconfiguredtopointataspecificWSDL,thetranslatorwillimportallSOAPoperationsunderthespecifiedserviceandportasprocedures.

ImporterPropertiesWhenspecifyingtheimporterproperty,itmustbeprefixedwith"importer.".Example:importer.tableTypes


importWSDL ImportthemetadatafromtheWSDLURLconfiguredinresource-adapter true

Usage

TheWStranslatorexposeslowlevelproceduresforaccessingwebservices.Seealsothetwitterexampleinthekit.

InvokeProcedure


592

Invokeallowsformultiplebinding,orprotocolmodes,includingHTTP,SOAP11,andSOAP12.

Procedureinvoke(bindinginSTRING,actioninSTRING,requestinXML,endpointinSTRING,streaminBOOLEAN)re

turnsXML

Thebindingmaybeoneofnull(tousethedefault)HTTP,SOAP11,orSOAP12.ActionwithaSOAPbindingindicatestheSOAPActionvalue.ActionwithaHTTPbindingindicatestheHTTPmethod(GET,POST,etc.),whichdefaultstoPOST.

Anullvalueforthebindingorendpointwillusethedefaultvalue.ThedefaultendpointisspecifiedintheWSresourceadapterconfiguration.TheendpointURLmaybeabsoluteorrelative.Ifit’srelativethenitwillbecombinedwiththedefaultendpoint.

Sincemultipleparametersarenotrequiredtohavevalues,itisoftenmorecleartocalltheinvokeprocedurewithnamedparametersyntax.

callinvoke(binding=>'HTTP',action=>'GET')

TherequestXMLshouldbeavalidXMLdocumentorrootelement.

InvokeHTTPProcedure

invokeHttpcanreturnthebytecontentsofanHTTP(S)call.

ProcedureinvokeHttp(actioninSTRING,requestinOBJECT,endpointinSTRING,streaminBOOLEAN,contentTypeou

tSTRING,headersinCLOB)returnsBLOB

ActionindicatestheHTTPmethod(GET,POST,etc.),whichdefaultstoPOST.

Anullvalueforendpointwillusethedefaultvalue.ThedefaultendpointisspecifiedintheWSresourceadapterconfiguration.TheendpointURLmaybeabsoluteorrelative.Ifit’srelativethenitwillbecombinedwiththedefaultendpoint.

Sincemultipleparametersarenotrequiredtohavevalues,itisoftenmorecleartocalltheinvokeprocedurewithnamedparametersyntax.

callinvokeHttp(action=>'GET')

TherequestcanbeoneofSQLXML,STRING,BLOB,orCLOB.TherequestwillbesentasthePOSTpayloadinbyteform.ForSTRING/CLOBvaluesthiswilldefaulttotheUTF-8encoding.Tocontrolthebyteencoding,seetheto_bytesfunction.

TheoptionalheadersparametercanbeusedtospecifytherequestheadervaluesasaJSONvalue.TheJSONvalueshouldbeaJSONobjectwithprimitiveorlistofprimitivevalues.

callinvokeHttp(...headers=>jsonObject('application/json'as"Content-Type",jsonArray('gzip','deflate')as"

Accept-Encoding"))

Recommendationsforsettingheadersparameter:

Content-TypemaybenecessaryifHTTPPOST/PUTmethodisinvoked

AcceptisnecessaryifyouwanttocontrolreturnMediaType

WSDLbasedProcedures


593

Theproceduresabovegiveyouanonymouswaytoexecuteanywebservicemethodsbysupplyinganendpoint,withthismechanismyoucanaltertheendpointdefinedinWSDLwithadifferentendpoint.However,ifyouhaveaccesstotheWSDL,thenyoucanconfiguretheWSDLURLintheweb-serviceresource-adapter’sconnectionconfiguration,WebServicetranslatorcanparsetheWSDLandprovidethemethodsunderconfiguredportaspre-builtproceduresasitsmetadata.Ifyouareusingthedefaultnativemetadataimport,youwillseetheproceduresinyourwebservice’ssourcemodel.

Note Nativequeries-NativequeriesoradirectqueryexecutionprocedureisnotsupportedontheWebServicesTranslator.

StreamingConsiderations

Ifthestreamparameterissettotrue,thentheresultinglobvaluemayonlybeusedasingletime.Ifstreamisnullorfalse,thentheenginemayneedtosaveacopyoftheresultforrepeateduse.Caremustbeusedassomeoperations,suchascastingorXMLPARSEmayperformvalidationwhichresultsinthestreambeingconsumed.

JCAResourceAdapter


Note WS-Security-CurrentlyyoucanonlyuseWSDLbasedProceduresparticipateinWS-Security,whenresource-adapterisconfiguredwithcorrectCXFconfiguration.


594

FederatedPlanningTeiidatitscoreisafederatedrelationalqueryengine.ThisqueryengineallowsyoutotreatallofyourdatasourcesasonevirtualdatabaseandaccesstheminasingleSQLquery.Thisallowsyoutofocusonbuildingyourapplication,notonhand-codingjoins,andotherrelationaloperations,betweendatasources.

ChildPages

PlanningOverview

QueryPlanner

QueryPlans



XQueryOptimization


ConformedTables

FederatedPlanning

595

PlanningOverviewWhenthequeryenginereceivesanincomingSQLqueryitperformsthefollowingoperations:

1. Parsing-validatesyntaxandconverttointernalform

2. Resolving-linkallidentifierstometadataandfunctionstothefunctionlibrary

3. Validating-validateSQLsemanticsbasedonmetadatareferencesandtypesignatures

4. Rewriting-rewriteSQLtosimplifyexpressionsandcriteria

5. Logicalplanoptimization-therewrittencanonicalSQLisconvertedintoalogicalplanforin-depthoptimization.TheTeiidoptimizerispredominantlyrule-based.Baseduponthequerystructureandhintsacertainrulesetwillbeapplied.Theserulesmaytriggerinturntriggertheexecutionofmorerules.Withinseveralrules,Teiidalsotakesadvantageofcostinginformation.ThelogicalplanoptimizationstepscanbeseenbyusingSETSHOWPLANDEBUGclause,asamplestepsaredescribedinQueryPlanner#ReadingaDebugPlan.Moredetailsaboutlogicalplan’snodesandrule-basedoptimizationrefertoQueryPlanner.

6. Processingplanconversion-thelogicplanisconvertedintoanexecutableformwherethenodesarerepresentativeofbasicprocessingoperations.ThefinalprocessingplanisdisplayedastheQueryPlans.

Thelogicalqueryplanisatreeofoperationsusedtotransformdatainsourcetablestotheexpectedresultset.Inthetree,dataflowsfromthebottom(tables)tothetop(output).Theprimarylogicaloperationsareselect(selectorfilterrowsbasedonacriteria),project(projectorcomputecolumnvalues),join,source(retrievedatafromatable),sort(ORDERBY),duplicateremoval(SELECTDISTINCT),group(GROUPBY),andunion(UNION).

Forexample,considerthefollowingquerythatretrievesallengineeringemployeesbornsince1970.

Examplequery

SELECTe.title,e.lastnameFROMEmployeesASeJOINDepartmentsASdONe.dept_id=d.dept_idWHEREyear(e.birt

hday)>=1970ANDd.dept_name='Engineering'

Logically,thedatafromtheEmployeesandDepartmentstablesareretrieved,thenjoined,thenfilteredasspecified,andfinallytheoutputcolumnsareprojected.Thecanonicalqueryplanthuslookslikethis:

PlanningOverview

596

Dataflowsfromthetablesatthebottomupwardsthroughthejoin,throughtheselect,andfinallythroughtheprojecttoproducethefinalresults.Thedatapassedbetweeneachnodeislogicallyaresultsetwithcolumnsandrows.

Ofcourse,thisiswhathappenslogically,nothowtheplanisactuallyexecuted.Startingfromthisinitialplan,thequeryplannerperformstransformationsonthequeryplantreetoproduceanequivalentplanthatretrievesthesameresultsfaster.Bothafederatedqueryplannerandarelationaldatabaseplannerdealwiththesameconceptsandmanyofthesameplantransformations.Inthisexample,thecriteriaontheDepartmentsandEmployeestableswillbepusheddownthetreetofiltertheresultsasearlyaspossible.

Inbothcases,thegoalistoretrievethequeryresultsinthefastestpossibletime.However,therelationaldatabaseplannerdoesthisprimarilybyoptimizingtheaccesspathsinpullingdatafromstorage.

Incontrast,afederatedqueryplannerislessconcernedaboutstorageaccessbecauseitistypicallypushingthatburdentothedatasource.Themostimportantconsiderationforafederatedqueryplannerisminimizingdatatransfer.

PlanningOverview

597

QueryPlannerCanonicalPlanandAllNodes

NodeProperties

AccessProperties

SetoperationProperties

JoinProperties

ProjectProperties

SelectProperties

SortProperties

SourceProperties

GroupProperties

TupleLimitProperties

GeneralandCostingProperties

Rules

Foreachsub-commandintheusercommandanappropriatekindofsub-plannerisused(relational,XML,procedure,etc).

Eachplannerhasthreeprimaryphases:

1. Generatecanonicalplan

2. Optimization

3. Plantoprocessconverter-convertsplandatastructureintoaprocessingform

RelationalPlanner

Arelationalprocessingplaniscreatedbytheoptimizerafterthelogicalplanismanipulatedbyaseriesofrules.Theapplicationofrulesisdeterminedbothbythequerystructureandbytherulesthemselves.Thenodestructureofthedebugplanresemblesthatoftheprocessingplan,butthenodetypesmorelogicallyrepresentSQLoperations.

CanonicalPlanandAllNodes

AsPlanningOverview,auserSQLstatementafterParsing,Resolving,Validating,Rewriting,itbeconvertedintoacanonicalplanform.ThecanonicalplanformmostcloselyresemblestheinitialSQLstructure.ASQLselectqueryhasthefollowingpossibleclauses(allbutSELECTareoptional):WITH,SELECT,FROM,WHERE,GROUPBY,HAVING,ORDERBY,LIMIT.Theseclausesarelogicallyexecutedinthefollowingorder:

1. WITH(createcommontableexpressions)-handledbyaspecializedPROJECTNODE

2. FROM(readandjoinalldatafromtables)-SOURCEnodeforeachfromclauseitem,Joinnode(if>1table)

3. WHERE(filterrows)-SELECTnode

4. GROUPBY(grouprowsintocollapsedrows)-GROUPnode

QueryPlanner

598

5. HAVING(filtergroupedrows)-SELECTnode

6. SELECT(evaluateexpressionsandreturnonlyrequestedrows)-PROJECTnodeandDUP_REMOVEnode(forSELECTDISTINCT)

7. INTO-specializedPROJECTwithaSOURCEchild

8. ORDERBY(sortrows)-SORTnode

9. LIMIT(limitresultsettoacertainrangeofresults)-LIMITnode

Forexample,aSQLstatementsuchasSELECTmax(pm1.g1.e1)FROMpm1.g1WHEREe2=1createsalogicalplan:

Project(groups=[anon_grp0],props={PROJECT_COLS=[anon_grp0.agg0ASexpr1]})

Group(groups=[anon_grp0],props={SYMBOL_MAP={anon_grp0.agg0=MAX(pm1.G1.E1)}})

Select(groups=[pm1.G1],props={SELECT_CRITERIA=pm1.G1.E2=1})

Source(groups=[pm1.G1])

HeretheSourcecorrespondstotheFROMclause,theSelectcorrespondstotheWHEREclause,theGroupcorrespondstotheimpliedgroupingtocreatethemaxaggregate,andtheProjectcorrespondstotheSELECTclause.

Note Theaffectofgroupinggenerateswhatiseffectivelyaninlineview,anon_grp0,tohandletheprojectionofvaluescreatedbythegrouping.

Table1.NodeTypes

TypeName Description

ACCESS asourceaccessorplanexecution.

DUP_REMOVE removesduplicaterows

JOIN ajoin(LEFTOUTER,FULLOUTER,INNER,CROSS,SEMI,etc.)

QueryPlanner

599

PROJECT aprojectionoftuplevalues

SELECT afilteringoftuples

SORT anorderingoperation,whichmaybeinsertedtoprocessotheroperationssuchasjoins

SOURCE anylogicalsourceoftuplesincludinganinlineview,asourceaccess,XMLTABLE,etc.

GROUP agroupingoperation

SET_OP asetoperation(UNION/INTERSECT/EXCEPT)

NULL asourceofnotuples

TUPLE_LIMIT rowoffset/limit

NodeProperties

Eachnodehasasetofapplicablepropertiesthataretypicallyshownonthenode.

AccessProperties

Table2.AccessProperties

PropertyName Description

ATOMIC_REQUEST Thefinalformofasourcerequest

MODEL_ID Themetadataobjectforthetargetmodel/schema

PROCEDURE_CRITERIA/PROCEDURE_INPUTS/PROCEDURE_DEFAULTS Usedinplanningprocedurealrelationalqueries

IS_MULTI_SOURCE settotruewhenthenoderepresentsamulti-sourceaccess

SOURCE_NAME usedtotrackthemulti-sourcesourcename

CONFORMED_SOURCEStracksthesetofconformedsourceswhentheconformedextensionmetadataisused

SUB_PLAN/SUB_PLANS usedinmulti-sourceplanning

SetoperationProperties

Table3.SetoperationProperties


SET_OPERATION/USE_ALL definesthesetoperation(UNION/INTERSECT/EXCEPT)andifallrowsordistinctrowsareused.

QueryPlanner

600

JoinProperties

Table4.JoinProperties


JOIN_CRITERIA alljoinpredicates

JOIN_TYPE typeofjoin(INNER,LEFTOUTER,etc.)

JOIN_STRATEGY thealgorithmtouse(nestedloop,merge,etc.)

LEFT_EXPRESSIONS theexpressionsinequi-joinpredicatesthatoriginatefromtheleftsideofthejoin

RIGHT_EXPRESSIONS theexpressionsinequi-joinpredicatesthatoriginatefromtherightsideofthejoin

DEPENDENT_VALUE_SOURCE setifadependentjoinisused

NON_EQUI_JOIN_CRITERIA non-equijoinpredicates

SORT_LEFT iftheleftsideneedssortedforjoinprocessing

SORT_RIGHT iftherightsideneedssortedforjoinprocessing

IS_OPTIONAL ifthejoinisoptional

IS_LEFT_DISTINCT iftheleftsideisdistinctwithrespecttotheequijoinpredicates

IS_RIGHT_DISTINCT iftherightsideisdistinctwithrespecttotheequijoinpredicates

IS_SEMI_DEP ifthedependentjoinrepresentsasemi-join

PRESERVE ifthepreservehintispreservingthejoinorder

ProjectProperties

Table5.ProjectProperties


PROJECT_COLS theexpressionsprojected

INTO_GROUP thegrouptargetedifthisisaselectintoorinsertwithaqueryexpression

HAS_WINDOW_FUNCTIONS trueifwindowfunctionsareused

CONSTRAINT theconstraintthatmustbemetifthevaluesarebeingprojectedintoagroup

QueryPlanner

601

SelectProperties

Table6.SelectProperties


SELECT_CRITERIA thefilter

IS_HAVING ifthefilterisappliedaftergrouping

IS_PHANTOM trueifthenodeismarkedforremoval,buttemporarilyleftintheplan.

IS_TEMPORARY inferredcriteriathatmaynotbeusedinthefinalplan

IS_COPIED ifthecriteriahasalreadybeenprocessedbyrulecopycriteria

IS_PUSHED ifthecriteriaispushedasfaraspossible

IS_DEPENDENT_SET ifthecriteriaisthefilterofadependentjoin

SortProperties

Table7.SortProperties


SORT_ORDER theorderbythatdefinesthesort

UNRELATED_SORT iftheorderingincludesavaluethatisnotbeingprojected

IS_DUP_REMOVAL ifthesortshouldalsoperformduplicateremovalovertheentireprojection

SourceProperties

Table8.SourceProperties


SYMBOL_MAP themappingfromthecolumnsabovethesourcetotheprojectedexpressions.AlsopresentonGroupnodes

PARTITION_INFO thepartitioningoftheunionbranches

VIRTUAL_COMMAND ifthesourcerepresentsanvieworinlineview,thequerythatdefinedtheview

MAKE_DEP hintinformation

PROCESSOR_PLAN theprocessorplanofanon-relationalsource(typicallyfromtheNESTED_COMMAND)

NESTED_COMMAND thenon-relationalcommand

QueryPlanner

602

TABLE_FUNCTION thetablefunction(XMLTABLE,OBJECTTABLE,etc.)definingthesource

CORRELATED_REFERENCES thecorrelatedreferencesforthenodesbelowthesource

MAKE_NOT_DEP ifmakenotdepisset

INLINE_VIEW Ifthesourcenoderepresentsaninlineview

NO_UNNEST iftheno_unnesthintisset

MAKE_IND ifthemakeindhintisset

SOURCE_HINT thesourcehint.SeeFederatedOptimizations.

ACCESS_PATTERNS accesspatternsyettobesatisfied

ACCESS_PATTERN_USED satisfiedaccesspatterns

REQUIRED_ACCESS_PATTERN_GROUPS groupsneededtosatisfytheaccesspatterns.Usedinjoinplanning.

Note Manysourcepropertiesalsobecomepresentonassociatedaccessnodes.

GroupProperties

Table9.GroupProperties


GROUP_COLS thegroupingcolumns

ROLLUP ifthegroupingincludesarollup

TupleLimitProperties

Table10.TupleLimitProperties


MAX_TUPLE_LIMIT expressionthatevaluatestothemaxnumberoftuplesgenerated

OFFSET_TUPLE_COUNT Expressionthatevaluatestothetupleoffsetofthestartingtuple

IS_IMPLICIT_LIMIT ifthelimitiscreatedbytherewriteraspartofasubqueryoptimization

IS_NON_STRICT iftheunorderedlimitshouldnotbeenforcedstrictly

GeneralandCostingProperties

Table11.GeneralandCostingProperties

QueryPlanner

603


OUTPUT_COLS theoutputcolumnsforthenode.Istypicallysetafterruleassignoutputelements.

EST_SET_SIZErepresentstheestimatedsetsizethisnodewouldproduceforasiblingnodeastheindependentnodeinadependentjoinscenario

EST_DEP_CARDINALITYvaluethatrepresentstheestimatedcardinality(amountofrows)producedbythisnodeasthedependentnodeinadependentjoinscenario

EST_DEP_JOIN_COST valuethatrepresentstheestimatedcostofadependentjoin(thejoinstrategyforthiscouldbeNestedLooporMerge)

EST_JOIN_COST valuethatrepresentstheestimatedcostofamergejoin(thejoinstrategyforthiscouldbeNestedLooporMerge)

EST_CARDINALITY representstheestimatedcardinality(amountofrows)producedbythisnode

EST_COL_STATS columnstatisticsincludingnumberofnullvalues,distinctvaluecount,etc.

EST_SELECTIVITY representstheselectivityofacriterianode

Rules

Relationaloptimizationisbaseduponruleexecutionthatevolvestheinitialplanintotheexecutionplan.Thereareasetofpre-definedrulesthataredynamicallyassembledintoarulestackforeveryquery.Therulestackisassembledbasedonthecontentsoftheuser’squeryandtheviews/proceduresaccessed.Forexample,iftherearenoviewlayers,thenruleMergeVirtual,whichmergesviewlayerstogether,isnotneededandwillnotbeaddedtothestack.Thisallowstherulestacktoreflectthecomplexityofthequery.

Logicallytheplannodedatastructurerepresentsatreeofnodeswherethesourcedatacomesupfromtheleafnodes(typicallyAccessnodesinthefinalplan),flowsupthroughthetreeandproducestheuser’sresultsoutthetop.Thenodesintheplanstructurecanhavebidirectionallinks,dynamicproperties,andallowanynumberofchildnodes.Processingplansincontrasttypicallyhavefixedproperties.

Planrulemanipulatetheplantree,fireotherrules,anddrivetheoptimizationprocess.Eachruleisdesignedtoperformanarrowsetoftasks.Somerulescanberunmultipletimes.Somerulesrequireaspecificsetofprecursorstorunproperly.

AccessPatternValidation-ensuresthatallaccesspatternshavebeensatisfied

ApplySecurity-appliesrowandcolumnlevelsecurity

AssignOutputSymbol-thisrulewalkstopdownthrougheverynodeandcalculatestheoutputcolumnsforeachnode.Columnsthatarenotneededaredroppedateverynode,whichisknownasprojectionminimization.Thisisdonebykeepingtrackofboththecolumnsneededtofeedtheparentnodeandalsokeepingtrackofcolumnsthatare"created"atacertainnode.

CalculateCost-addscostinginformationtotheplan

ChooseDependent-thisrulelooksateachjoinnodeanddetermineswhetherthejoinshouldbemadedependentandinwhichdirection.Cardinality,thenumberofdistinctvalues,andprimarykeyinformationareusedinseveralformulastodeterminewhetheradependentjoinislikelytobeworthwhile.Thedependentjoindiffersinperformanceideallybecausea

QueryPlanner

604

fewernumberofvalueswillbereturnedfromthedependentside.Also,wemustconsiderthenumberofvaluespassedfromindependenttodependentside.IfthatsetislargerthanthemaxnumberofvaluesinanINcriteriaonthedependentside,thenwemustbreakthequeryintoasetofqueriesandcombinetheirresults.Executingeachqueryintheconnectorhassomeoverheadandthatistakenintoaccount.Withoutcostinginformationalotofcommoncaseswheretheonlycriteriaspecifiedisonanon-unique(butstronglylimiting)fieldaremissed.Ajoiniseligibletobedependentif:

thereisatleastoneequi-joincriterion,i.e.tablea.col=tableb.col

thejoinisnotafullouterjoinandthedependentsideofthejoinisontheinnersideofthejoin

Thejoinwillbemadedependentifoneofthefollowingconditions,listedinprecedenceorder,holds:

Thereisanunsatisfiedaccesspatternthatcanbesatisfiedwiththedependentjoincriteria

Thepotentialdependentsideofthejoinismarkedwithanoptionmakedep

(4.3.2)ifcostingwasenabled,theestimatedcostforthedependentjoin(5.0+possiblyineachdirectioninthecaseofinnerjoins)iscomputedandcomparedtonotperformingthedependentjoin.Ifthecostswerealldetermined(whichrequiresallrelevanttablecardinality,columnndv,andpossiblynnvvaluestobepopulated)thelowestischosen.

Ifkeymetadatainformationindicatesthatthepotentialdependentsideisnot"small"andtheothersideis"notsmall"or(5.0.1)thepotentialdependentsideistheinnersideofaleftouterjoin.

Dependentjoinisthekeyoptimizationweusetoefficientlyprocessmulti-sourcejoins.InsteadofreadingallofsourceAandallofsourceBandjoiningthemonA.x=B.x,wereadallofAthenbuildasetofA.xthatarepassedasacriteriawhenqueryingB.IncaseswhereAissmallandBislarge,thiscandrasticallyreducethedataretrievedfromB,thusgreatlyspeedingtheoverallquery.

ChooseJoinStrategy-choosethejoinstrategybaseduponthecostandattributesofthejoin.

CleanCriteria-removesphantomcriteria

CollapseSource-takesallofthenodesbelowanaccessnodeandcreatesaSQLqueryrepresentation

CopyCriteria-thisrulecopiescriteriaoveranequalitycriteriathatispresentinthecriteriaofajoin.Sincetheequalitydefinesanequivalence,thisisavalidwaytocreateanewcriteriathatmaylimitresultsontheothersideofthejoin(especiallyinthecaseofamulti-sourcejoin).

DecomposeJoin-thisruleperfomrsapartition-wisejoinoptimizationonjoinsofFederatedOptimizations#PartitionedUnion.Thedecisiontodecomposeisbasedupondetectingthateachsideofthejoinisapartitionedunion(notethatnon-ansijoinsofmorethan2tablesmaycausetheoptimizationtonotdetecttheappropriatejoin).Therulecurrentlyonlylooksforsituationswhereatmost1partitionmatchesfromeachside.

ImplementJoinStrategy-addsnecessarysortandothernodestoprocessthechosenjoinstrategy

MergeCriteria-combinesselectnodesandcanconvertsubqueriestosemi-joins

MergeVirtual-removesviewandinlineviewlayers

PlaceAccess-placesaccessnodesundersourcenodes.Anaccessnoderepresentsthepointatwhicheverythingbelowtheaccessnodegetspushedtothesourceorisaplaninvocation.Laterrulesfocusoneitherpushingundertheaccessorpullingtheaccessnodeupthetreetomovemoreworkdowntothesources.ThisruleisalsoresponsibleforplacingFederatedOptimizations#AccessPatterns.

PlanJoins-thisruleattemptstofindanoptimalorderingofthejoinsperformedintheplan,whileensuringthatFederatedOptimizations#AccessPatternsdependenciesaremet.Thisrulehasthreemainsteps.Firstitmustdetermineanorderingofjoinsthatsatisfytheaccesspatternspresent.Seconditwillheuristicallycreatejoinsthatcanbepushedtothesource(ifasetofjoinsarepushedtothesource,wewillnotattempttocreateanoptimalorderingwithinthatset.Morethanlikelyitwillbe

QueryPlanner

605

senttothesourceinthenon-ANSImulti-joinsyntaxandwillbeoptimizedbythedatabase).Thirditwillusecostinginformationtodeterminethebestleft-linearorderingofjoinsperformedintheprocessingengine.Thisthirdstepwilldoanexhaustivesearchfor7orlessjoinsourcesandisheuristicallydrivenbyjoinselectivityfor8ormoresources.

PlanOuterJoins-reordersouterjoinsaspermittedtoimprovepushdown.

PlanProcedures-plansproceduresthatappearinproceduralrelationalqueries

PlanSorts-optimizationsaroundsorting,suchascombiningsortoperationsormovingprojection

PlanUnions-reordersunionchildrenformorepushdown

PlanAggregates-performsaggregatedecompositionoverajoinorunion

PushLimit-pushestheaffectofalimitnodefurtherintotheplan

PushNon-JoinCriteria-thisrulewillpushpredicatesoutofanonclauseifitisnotnecessaryforthecorrectnessofthejoin.

PushSelectCriteria-pushedselectnodesasfaraspossiblethroughunions,joins,andviewslayerstowardtheaccessnodes.Inmostcasesmovementdownthetreeisgoodasthiswillfilterrowsearlierintheplan.WecurrentlydonotundothedecisionsmadebyPushSelectCriteria.Howeverinsituationswherecriteriacannotbeevaluatedbythesource,thiscanleadtosuboptimalplans.

Oneofthemostimportantoptimizationrelatedtopushingcriteria,ishowthecriteriawillbepushedthroughjoin.Considerthefollowingplantreethatrepresentsasubtreeoftheplanforthequeryselect*fromAinnerjoinbon(A.x=B.x)whereB.y=3

SELECT(B.y=3)

|

JOIN-InnerJoinon(A.x=B.x)

/\

SRC(A)SRC(B)

Note SELECTnodesrepresentcriteria,andSRCstandsforSOURCE.

Itisalwaysvalidforinnerjoinandcrossjoinstopush(singlesource)criteriathatareabovethejoin,belowthejoin.Thisallowsforcriteriaoriginatingintheuserquerytoeventuallybepresentinsourcequeriesbelowthejoins.Thisresultcanberepresentedvisuallyas:


/\

/SELECT(B.y=3)

||

SRC(A)SRC(B)

Thesameoptimizationisvalidforcriteriaspecifiedagainsttheoutersideofanouterjoin.Forexample:

SELECT(B.y=3)

|

JOIN-RightOuterJoinon(A.x=B.x)

/\

SRC(A)SRC(B)

Becomes

JOIN-RightOuterJoinon(A.x=B.x)

/\

/SELECT(B.y=3)

||

SRC(A)SRC(B)

QueryPlanner

606

Howevercriteriaspecifiedagainsttheinnersideofanouterjoinneedsspecialconsideration.Theabovescenariowithaleftorfullouterjoinisnotthesame.Forexample:

SELECT(B.y=3)

|

JOIN-LeftOuterJoinon(A.x=B.x)

/\

SRC(A)SRC(B)

Canbecome(availableonlyafter5.0.2):


/\

/SELECT(B.y=3)

||

SRC(A)SRC(B)

Sincethecriterionisnotdependentuponthenullvaluesthatmaybepopulatedfromtheinnersideofthejoin,thecriterioniseligibletobepushedbelowthejoin–butonlyifthejointypeisalsochangedtoaninnerjoin.Ontheotherhand,criteriathataredependentuponthepresenceofnullvaluesCANNOTbemoved.Forexample:

SELECT(B.yisnull)

|

JOIN-LeftOuterJoinon(A.x=B.x)

/\

SRC(A)SRC(B)

Thisplantreemusthavethecriteriaremainabovethejoin,sincetheouterjoinmaybeintroducingnullvaluesitself.

RaiseAccess-thisruleattemptstoraisetheAccessnodesasfaruptheplanaspossible.Thisismostlydonebylookingatthesource’scapabilitiesanddeterminingwhethertheoperationscanbeachievedinthesourceornot.

RaiseNull-raisesnullnodes.Raisinganullnoderemovestheneedtoconsideranypartoftheoldplanthatwasbelowthenullnode.

RemoveOptionalJoins-removesjoinsthataremarkedasordeterminedtobeoptional

SubstituteExpressions-usedonlywhenafunctionbasedindexispresent

ValidateWhereAll-ensurescriteriaisusedwhenrequiredbythesource

CostCalculations

Thecostofnodeoperationsisprimarilydeterminedbyanestimateofthenumberofrows(alsoreferredtoascardinality)thatwillbeprocessedbyit.Theoptimizerwilltypicallycomputecardinalitiesfromthebottomupoftheplan(orsubplan)atseveralpointsintimewithplanning-oncegenerallywithrulecalculatecost,andthenspecificallyforjoinplanningandotherdecisions.Thecostcalculationismainlydirectedbythestatisticssetonphysicaltables(cardinality,NNV,NDV,etc.)andisalsoinfluencedbythepresenceofconstraints(unique,primarykey,index,etc.).Ifthereisasituationthatseemslikeasub-optimalplanisbeingchosen,youshouldfirstensurethatatleastrepresentativetablecardinalitiesaresetonthephysicaltablesinvolved.

ReadingaDebugPlan

Aseachrelationalsubplanisoptimized,theplanwillshowwhatisbeingoptimizedandit’scanonicalform:

OPTIMIZE:

SELECTe1FROM(SELECTe1FROMpm1.g1)ASx

QueryPlanner

607

----------------------------------------------------------------------------

GENERATECANONICAL:

SELECTe1FROM(SELECTe1FROMpm1.g1)ASx

CANONICALPLAN:

Project(groups=[x],props={PROJECT_COLS=[e1]})

Source(groups=[x],props={NESTED_COMMAND=SELECTe1FROMpm1.g1,SYMBOL_MAP={x.e1=e1}})

Project(groups=[pm1.g1],props={PROJECT_COLS=[e1]})

Source(groups=[pm1.g1])

Withmorecomplicateduserqueries,suchasaprocedureinvocationoronecontainingsubqueries,thesubplansmaybenestedwithintheoverallplan.Eachplanendsbyshowingthefinalprocessingplan:

----------------------------------------------------------------------------

OPTIMIZATIONCOMPLETE:

PROCESSORPLAN:

AccessNode(0)output=[e1]SELECTg_0.e1FROMpm1.g1ASg_0

Theaffectofrulescanbeseenbythestateoftheplantreebeforeandaftertherulefires.Forexample,thedebuglogbelowshowstheapplicationofrulemergevirtual,whichwillremovethe"x"inlineviewlayer:

EXECUTINGAssignOutputElements

AFTER:

Project(groups=[x],props={PROJECT_COLS=[e1],OUTPUT_COLS=[e1]})

Source(groups=[x],props={NESTED_COMMAND=SELECTe1FROMpm1.g1,SYMBOL_MAP={x.e1=e1},OUTPUT_COLS=[e1]})

Project(groups=[pm1.g1],props={PROJECT_COLS=[e1],OUTPUT_COLS=[e1]})

Access(groups=[pm1.g1],props={SOURCE_HINT=null,MODEL_ID=Schemaname=pm1,nameInSource=null,uuid=3335,

OUTPUT_COLS=[e1]})

Source(groups=[pm1.g1],props={OUTPUT_COLS=[e1]})

============================================================================

EXECUTINGMergeVirtual

AFTER:

Project(groups=[pm1.g1],props={PROJECT_COLS=[e1],OUTPUT_COLS=[e1]})

Access(groups=[pm1.g1],props={SOURCE_HINT=null,MODEL_ID=Schemaname=pm1,nameInSource=null,uuid=3335,OUTP

UT_COLS=[e1]})


Someimportantplanningdecisionsareshownintheplanastheyoccurasanannotation.Forexamplethesnippetbelowshowsthattheaccessnodecouldnotberaisedastheparentselectnodecontainedanunsupportedsubquery.

Project(groups=[pm1.g1],props={PROJECT_COLS=[e1],OUTPUT_COLS=null})

Select(groups=[pm1.g1],props={SELECT_CRITERIA=e1IN/*+NO_UNNEST*/(SELECTe1FROMpm2.g1),OUTPUT_COLS=nu

ll})

Access(groups=[pm1.g1],props={SOURCE_HINT=null,MODEL_ID=Schemaname=pm1,nameInSource=null,uuid=3341,OU

TPUT_COLS=null})

Source(groups=[pm1.g1],props={OUTPUT_COLS=null})

============================================================================

EXECUTINGRaiseAccess

LOWRelationalPlannerSubqueryInisnotsupportedbysourcepm1-e1IN/*+NO_UNNEST*/(SELECTe1FROMpm2.g

1)wasnotpushed

AFTER:

Project(groups=[pm1.g1])

Select(groups=[pm1.g1],props={SELECT_CRITERIA=e1IN/*+NO_UNNEST*/(SELECTe1FROMpm2.g1),OUTPUT_COLS=nu

ll})

Access(groups=[pm1.g1],props={SOURCE_HINT=null,MODEL_ID=Schemaname=pm1,nameInSource=null,uuid=3341,OU

QueryPlanner

608

TPUT_COLS=null})


ProcedurePlanner

Theprocedureplannerisfairlysimple.Itconvertsthestatementsintheprocedureintoinstructionsinaprogramthatwillberunduringprocessing.Thisismostlya1-to-1mappingandverylittleoptimizationisperformed.

XMLPlanner

TheXMLPlannercreatesanXMLplanthatisrelativelyclosetotheendresultoftheProcedurePlanner–aprogramwithinstructions.Manyoftheinstructionsareevensimilar(whileloop,executeSQL,etc).Additionalinstructionsdealwithproducingtheoutputresultdocument(addingelementsandattributes).

TheXMLplannerdoesseveraltypesofplanning(notnecessarilyinthisorder):

Documentselection-determinewhichtagsofthevirtualdocumentshouldbeexcludedfromtheoutputdocument.Thisisdonebasedonacombinationofthemodel(whichmarkspartsofthedocumentexcluded)andthequery(whichmayspecifyasubsetofcolumnstoincludeintheSELECTclause).

Criteriaevaluation-breaksaparttheuser’scriteria,determinewhichresultsetthecriteriashouldbeappliedto,andaddthatcriteriatothatresultsetquery.

Resultsetordering-thequery’sORDERBYclauseisbrokenupandtheORDERBYisappliedtoeachresultsetasnecessary

Resultsetplanning-ultimately,eachresultsetisplannedusingtherelationalplannerandtakingintoaccountalltheimpactsfromtheuser’squery.Theplannerwillalsolooktoautomaticallycreatestagingtablesanddependentjoinsbaseduponthemappingclasshierarchy.

Programgeneration-asetofinstructionstoproducethedesiredoutputdocumentisproduced,takingintoaccountthefinalresultsetqueriesandtheexcludedpartsofthedocument.Generally,thisinvolveswalkingthroughthevirtualdocumentindocumentorder,executingqueriesasnecessaryandemittingelementsandattributes.

XMLprogramscanalsoberecursive,whichinvolvesusingthesamedocumentfragmentforboththeinitialfragmentandasetofrepeatedfragments(eachanewquery)untilsometerminationcriteriaorlimitismet.

XQuery

XQueryiseligibleforspecificoptimizations.Documentprojectionisthemostcommonoptimization.Itwillbeshowninthedebugplanasanannotation.Forexamplewiththeuserquerycontaining"xmltable('/a/b'passingdoccolumnsxstringpath'@x',valstringpath'/.')",thedebugplanwouldshowatreeofthedocumentthatwilleffectivelybeusedbythecontextandpathXQuerys:

MEDIUMXQueryPlanningProjectionconditionsmetfor/a/b-Documentprojectionwillbeused

childelement(Q{}a)

childelement(Q{}b)

attributeattribute(Q{}x)

childtext()

childtext()

QueryPlanner

609

QueryPlansWhenintegratinginformationusingafederatedqueryplanneritisusefultoviewthequeryplanstobetterunderstandhowinformationisbeingaccessedandprocessed,andtotroubleshootproblems.

Aqueryplan(alsoknownasanexecutionorprocessingplan)isasetofinstructionscreatedbyaqueryengineforexecutingacommandsubmittedbyauserorapplication.Thepurposeofthequeryplanistoexecutetheuser’squeryinasefficientawayaspossible.

GettingaQueryPlan

Youcangetaqueryplananytimeyouexecuteacommand.TheSQLoptionsavailableareasfollows:

SETSHOWPLAN[ON|DEBUG]-ReturnstheprocessingplanortheplanandthefullplannerDebugLog.SeealsotheSETStatement.

Withtheaboveoptions,thequeryplanisavailablefromtheStatementobjectbycastingtotheorg.teiid.jdbc.TeiidStatementinterfaceorbyusingtheSHOWPLANstatement.

RetrievingaQueryPlanUsingTeiidExtensions

statement.execute("setshowplanon");

ResultSetrs=statement.executeQuery("select...");

TeiidStatementtstatement=statement.unwrap(TeiidStatement.class);

PlanNodequeryPlan=tstatement.getPlanDescription();

System.out.println(queryPlan);

RetrievingaQueryPlanUsingStatements

statement.execute("setshowplanon");

ResultSetrs=statement.executeQuery("select...");

...

ResultSetplanRs=statement.executeQuery("showplan");

planRs.next();

System.out.println(planRs.getString("PLAN_XML"));

ThequeryplanismadeavailableautomaticallyinseveralofTeiid’stools.

AnalyzingaQueryPlan

Onceaqueryplanhasbeenobtainedyouwillmostcommonlybelookingfor:

Sourcepushdown–whatpartsofthequerythatgotpushedtoeachsource

Ensurethatanypredicatesespeciallyagainstindexesarepushed

Joins-asfederatedjoinscanbequiteexpensive

Joinordering-typicallyinfluencedbycosting

Joincriteriatypemismatches.

Joinalgorithmused-merge,enhancedmerge,nestedloop,etc.

Presenceoffederatedoptimizations,suchasdependentjoins.

QueryPlans

610

Ensurehintshavethedesiredaffects-seeHintsandOptions,hintsintheFROMClause,SubqueryOptimization,andFederatedOptimizations.

Alloftheaboveinformationcanbedeterminedfromtheprocessingplan.Youwilltypicallybeinterestedinanalyzingthetextualformofthefinalprocessingplan.Tounderstandwhyparticulardecisionsaremadefordebuggingorsupportyouwillwanttoobtainthefulldebuglogwhichwillcontaintheintermediateplanningstepsaswellasannotationsastowhyspecificpushdowndecisionsaremade.

Aqueryplanconsistsofasetofnodesorganizedinatreestructure.IfyouareexecutingaprocedureorgeneratinganXMLdocumentfromanXMLDocumentModel,theoverallqueryplanwillcontainadditionalinformationrelatedthesurroundingproceduralexecution.

Inaproceduralcontexttheorderingofchildnodesimpliestheorderofexecution.Inmostothersituation,childnodesmaybeexecutedinanyordereveninparallel.Onlyinspecificoptimizations,suchasdependentjoin,willthechildrenofajoinexecuteserially.

RelationalQueryPlans

Relationalplansrepresenttheprocessingplanthatiscomposedofnodesrepresentingbuildingblocksoflogicalrelationaloperations.Relationalprocessingplansdifferfromlogicaldebugrelationalplansinthattheywillcontainadditionaloperationsandexecutionspecificsthatwerechosenbytheoptimizer.

Thenodesforarelationalqueryplanare:

Access-Accessasource.Asourcequeryissenttotheconnectionfactoryassociatedwiththesource.(Foradependentjoin,thisnodeiscalledDependentAccess.)

DependentProcedureAccess-Accessastoredprocedureonasourceusingmultiplesetsofinputvalues.

BatchedUpdate-Processesasetofupdatesasabatch.

Project-Definesthecolumnsreturnedfromthenode.Thisdoesnotalterthenumberofrecordsreturned.

ProjectInto-Likeanormalproject,butoutputsrowsintoatargettable.

InsertPlanExecution-Similartoaprojectinto,butexecutesaplanratherthanasourcequery.Typicallycreatedwhenexecutinganinsertintoviewwithaqueryexpression.

WindowFunctionProject-Likeanormalproject,butincludeswindowfunctions.

Select-Selectisacriteriaevaluationfilternode(WHERE/HAVING).

Join-Definesthejointype,joincriteria,andjoinstrategy(mergeornestedloop).

UnionAll-Therearenopropertiesforthisnode,itjustpassesrowsthroughfromit’schildren.Dependinguponotherfactors,suchasifthereisatransactionorthesourcequeryconcurrencyallowed,notalloftheunionchildrenwillexecuteinparallel.

Sort-Definesthecolumnstosorton,thesortdirectionforeachcolumn,andwhethertoremoveduplicatesornot.

DupRemove-Removesduplicaterows.TheprocessingusesatreestructuretodetectduplicatessothatresultswilleffectivelystreamatthecostofIOoperations.

Grouping-Groupssetsofrowsintogroupsandevaluatesaggregatefunctions.

Null-Anodethatproducesnorows.UsuallyreplacesaSelectnodewherethecriteriaisalwaysfalse(andwhatevertreeisunderneath).Therearenopropertiesforthisnode.

PlanExecution-Executesanothersubplan.Typicallythesubplanwillbeanon-relationalplan.

QueryPlans

611

DependentProcedureExecution-Executesasubplanusingmultiplesetsofinputvalues.

Limit-Returnsaspecifiednumberofrows,thenstopsprocessing.Alsoprocessesanoffsetifpresent.

XMLTable-EvaluatesXMLTABLE.ThedebugplanwillcontainmoreinformationabouttheXQuery/XPathwithregardstotheiroptimization-seetheXQuerysectionbeloworXQueryOptimization.

TextTable-EvaluatesTEXTTABLE

ArrayTable-EvaluatesARRAYTABLE

ObjectTable-EvaluatesOBJECTTABLE

NodeStatistics

Everynodehasasetofstatisticsthatareoutput.Thesecanbeusedtodeterminetheamountofdataflowingthroughthenode.Beforeexecutionaprocessorplanwillnotcontainnodestatistics.Alsothestatisticsareupdatedastheplanisprocessed,sotypicallyyou’llwantthefinalstatisticsafterallrowshavebeenprocessedbytheclient.

Statistic Description Units

NodeOutputRows Numberofrecordsoutputfromthenode count

NodeNextBatchProcessTime Timeprocessinginthisnodeonly millisec

NodeCumulativeNextBatchProcessTime

Timeprocessinginthisnode+childnodes millisec

NodeCumulativeProcessTime Elapsedtimefrombeginningofprocessingtoend millisec

NodeNextBatchCalls Numberoftimesanodewascalledforprocessing count

NodeBlocks Numberoftimesablockedexceptionwasthrownbythisnodeorachild count

Inadditiontonodestatistics,somenodesdisplaycostestimatescomputedatthenode.

CostEstimates Description Units

EstimatedNodeCardinalityEstimatednumberofrecordsthatwillbeoutputfromthenode;-1ifunknown

count

Therootnodewilldisplayadditionalinformation.

ToplevelStatistics Description Units

DataBytesSent Thesizeoftheserializeddataresult(rowandlobvalues)senttotheclient bytes

ReadingaProcessorPlan

QueryPlans

612

Thequeryprocessorplancanbeobtainedinaplaintextorxmlformat.Theplantextformatistypicallyeasiertoread,whilethexmlformatiseasiertoprocessbytooling.Whenpossibletoolingshouldbeusedtoexaminetheplansasthetreestructurescanbedeeplynested.

Dataflowsfromtheleafsofthetreetotheroot.Subplansforprocedureexecutioncanbeshowninline,andaredifferentiatedbydifferentindentation.GivenauserqueryofSELECTpm1.g1.e1,pm1.g2.e2,pm1.g3.e3frompm1.g1innerjoin(pm1.g2leftouterjoinpm1.g3onpm1.g2.e1=pm1.g3.e1)onpm1.g1.e1=pm1.g3.e1,thetextforaprocessorplanthatdoesnotpushdownthejoinswouldlooklike:

ProjectNode

+OutputColumns:

0:e1(string)

1:e2(integer)

2:e3(boolean)


+Child0:

JoinNode

+OutputColumns:

0:e1(string)

1:e2(integer)

2:e3(boolean)


+Child0:

JoinNode

+OutputColumns:

0:e1(string)

1:e1(string)

2:e3(boolean)


+Child0:

AccessNode

+OutputColumns:e1(string)


+Query:SELECTg_0.e1ASc_0FROMpm1.g1ASg_0ORDERBYc_0

+ModelName:pm1

+Child1:

AccessNode

+OutputColumns:

0:e1(string)

1:e3(boolean)


+Query:SELECTg_0.e1ASc_0,g_0.e3ASc_1FROMpm1.g3ASg_0ORDERBYc_0

+ModelName:pm1

+JoinStrategy:MERGEJOIN(ALREADY_SORTED/ALREADY_SORTED)

+JoinType:INNERJOIN

+JoinCriteria:pm1.g1.e1=pm1.g3.e1

+Child1:

AccessNode

+OutputColumns:

0:e1(string)

1:e2(integer)


+Query:SELECTg_0.e1ASc_0,g_0.e2ASc_1FROMpm1.g2ASg_0ORDERBYc_0

+ModelName:pm1

+JoinStrategy:ENHANCEDSORTJOIN(SORT/ALREADY_SORTED)

+JoinType:INNERJOIN

+JoinCriteria:pm1.g3.e1=pm1.g2.e1

+SelectColumns:

0:pm1.g1.e1

1:pm1.g2.e2

2:pm1.g3.e3

QueryPlans

613

Notethatthenestedjoinnodeisusingamergejoinandexpectsthesourcequeriesfromeachsidetoproducetheexpectedorderingforthejoin.Theparentjoinisanenhancedsortjoinwhichcandelaythedecisiontoperformsortingbasedupontheincomingrows.Notethattheouterjoinfromtheuserqueryhasbeenmodifiedtoaninnerjoinsincenoneofthenullinnervaluescanbepresentinthequeryresult.

Thesameplaninxmlformlookslike:


<nodename="ProjectNode">

<propertyname="OutputColumns">

<value>e1(string)</value>

<value>e2(integer)</value>

<value>e3(boolean)</value>

</property>

<propertyname="CostEstimates">

<value>EstimatedNodeCardinality:-1.0</value>

</property>

<propertyname="Child0">

<nodename="JoinNode">





</property>



</property>


<nodename="JoinNode">





</property>



</property>


<nodename="AccessNode">



</property>



</property>

<propertyname="Query">

<value>SELECTg_0.e1ASc_0FROMpm1.g1ASg_0ORDERBYc_0</value>

</property>

<propertyname="ModelName">

<value>pm1</value>

</property>

</node>

</property>






</property>



</property>


<value>SELECTg_0.e1ASc_0,g_0.e3ASc_1FROMpm1.g3ASg_0

ORDERBYc_0</value>

</property>


QueryPlans

614

<value>pm1</value>

</property>

</node>

</property>

<propertyname="JoinStrategy">

<value>MERGEJOIN(ALREADY_SORTED/ALREADY_SORTED)</value>

</property>

<propertyname="JoinType">

<value>INNERJOIN</value>

</property>

<propertyname="JoinCriteria">

<value>pm1.g1.e1=pm1.g3.e1</value>

</property>

</node>

</property>






</property>



</property>


<value>SELECTg_0.e1ASc_0,g_0.e2ASc_1FROMpm1.g2ASg_0

ORDERBYc_0</value>

</property>


<value>pm1</value>

</property>

</node>

</property>

<propertyname="JoinStrategy">

<value>ENHANCEDSORTJOIN(SORT/ALREADY_SORTED)</value>

</property>

<propertyname="JoinType">

<value>INNERJOIN</value>

</property>

<propertyname="JoinCriteria">

<value>pm1.g3.e1=pm1.g2.e1</value>

</property>

</node>

</property>

<propertyname="SelectColumns">

<value>pm1.g1.e1</value>



</property>

</node>

Notethatthesameinformationappearsineachoftheplanforms.Insomecasesitcanactuallybeeasiertofollowthesimplifiedformatofthedebugplanfinalprocessorplan.FromtheDebugLogthesameplanasabovewouldappearas:

OPTIMIZATIONCOMPLETE:

PROCESSORPLAN:

ProjectNode(0)output=[pm1.g1.e1,pm1.g2.e2,pm1.g3.e3][pm1.g1.e1,pm1.g2.e2,pm1.g3.e3]

JoinNode(1)[ENHANCEDSORTJOIN(SORT/ALREADY_SORTED)][INNERJOIN]criteria=[pm1.g3.e1=pm1.g2.e1]output=[pm

1.g1.e1,pm1.g2.e2,pm1.g3.e3]

JoinNode(2)[MERGEJOIN(ALREADY_SORTED/ALREADY_SORTED)][INNERJOIN]criteria=[pm1.g1.e1=pm1.g3.e1]output

=[pm1.g3.e1,pm1.g1.e1,pm1.g3.e3]

AccessNode(3)output=[pm1.g1.e1]SELECTg_0.e1ASc_0FROMpm1.g1ASg_0ORDERBYc_0

AccessNode(4)output=[pm1.g3.e1,pm1.g3.e3]SELECTg_0.e1ASc_0,g_0.e3ASc_1FROMpm1.g3ASg_0ORDER

BYc_0

AccessNode(5)output=[pm1.g2.e1,pm1.g2.e2]SELECTg_0.e1ASc_0,g_0.e2ASc_1FROMpm1.g2ASg_0ORDERBY

c_0

QueryPlans

615

NodeProperties

Common

OutputColumns-whatcolumnsmakeupthetuplesreturnedbythisnode

DataBytesSent-howmanydatabyte,notincludingmessagingoverhead,weresentbythisquery

PlanningTime-theamountoftimeinmillisecondsspentplanningthequery

Relational

RelationalNodeID-matchesthenodeidsseeninthedebuglogNode(id)

Criteria-thebooleanexpressionusedforfiltering

SelectColumns-thecolumnsthatdefinetheprojection

GroupingColumns-thecolumnsusedforgrouping

GroupingMapping-showsthemappingofaggregateandgroupingcolumninternalnamestotheirexpressionform

Query-thesourcequery

ModelName-themodelname

SharingID-nodessharingthesamesourceresultswillhavethesamesharingid

DependentJoin-ifadependentjoinisbeingused

JoinStrategy-thejoinstrategy(NestedLoop,SortMerge,EnhancedSort,etc.)

JoinType-thejointype(LeftOuterJoin,InnerJoin,CrossJoin)

JoinCriteria-thejoinpredicates

ExecutionPlan-thenestedexecutionplan

IntoTarget-theinsertiontarget

SortColumns-thecolumnsforsorting

SortMode-ifthesortperformsanotherfunctionaswell,suchasdistinctremoval

Rollup-ifthegroupbyhastherollupoption

Statistics-theprocessingstatistics

CostEstimates-thecost/cardinalityestimatesincludingdependentjoincostestimates

RowOffset-therowoffsetexpression

RowLimit-therowlimitexpression

With-thewithclause

WindowFunctions-thewindowfunctionsbeingcomputed

TableFunction-thetablefunction(XMLTABLE,OBJECTTABLE,TEXTTABLE,etc.)

XML

Message

QueryPlans

616

Tag

Namespace

DataColumn

NamespaceDeclarations

OptionalFlag

DefaultValue

RecursionDirection

Bindings

IsStagingFlag

SourceInMemoryFlag

Condition

DefaultProgram

Encoding

FormattedFlag

Procedure

Expression

ResultSet

Program

Variable

Then

Else

OtherPlans

XMLdocumentmodelqueriesandprocedureexecution(includinginsteadoftriggers)useintermediateandfinalplanformsthatincluderelationalplans.Generallythestructureofthexml/procedureplanswillcloselymatchtheirlogicalforms.It’sthenestedrelationalplansthatwillbeofinterestwhenanalyzingperformanceissues.

QueryPlans

617


AccessPatterns

Accesspatternsareusedonbothphysicaltablesandviewstospecifytheneedforcriteriaagainstasetofcolumns.Failuretosupplythecriteriawillresultinaplanningerror,ratherthanarun-awaysourcequery.Accesspatternscanbeappliedinasetsuchthatonlyoneoftheaccesspatternsisrequiredtobesatisfied.

Currentlyanyformofcriteriareferencinganaffectedcolumnmaysatisfyanaccesspattern.

PushdownInfederateddatabasesystemspushdownreferstodecomposingtheuserlevelqueryintosourcequeriesthatperformasmuchworkaspossibleontheirrespectivesourcesystem.Pushdownanalysisrequiresknowledgeofsourcesystemcapabilities,whichisprovidedtoTeiidthoughtheConnectorAPI.AnyworknotperformedatthesourceisthenprocessedinFederate’srelationalengine.

Baseduponcapabilities,Teiidwillmanipulatethequeryplantoensurethateachsourceperformsasmuchjoining,filtering,grouping,etc.aspossible.Inmaycases,suchaswithjoinordering,planningisacombinationofStandardRelationalTechniquesand,costbasedandheuristicsforpushdownoptimization.

Criteriaandjoinpushdownaretypicallythemostimportantaspectsofthequerytopushdownwhenperformanceisaconcern.SeeQueryPlansonhowtoreadaplantoensurethatsourcequeriesareasefficientaspossible.

DependentJoins

Aspecialoptimizationcalledadependentjoinisusedtoreducetherowsreturnedfromoneofthetworelationsinvolvedinamulti-sourcejoin.Inadependentjoin,queriesareissuedtoeachsourcesequentiallyratherthaninparallel,withtheresultsobtainedfromthefirstsourceusedtorestricttherecordsreturnedfromthesecond.Dependentjoinscanperformsomejoinsmuchfasterbydrasticallyreducingtheamountofdataretrievedfromthesecondsourceandthenumberofjoincomparisonsthatmustbeperformed.

TheconditionswhenadependentjoinisusedaredeterminedbythequeryplannerbasedonAccessPatterns,hints,andcostinginformation.TherearethreedifferentkindsofdependentjoinsthatTeiidsupports

Joinbasedonin/equalitysupport-wheretheenginewilldeterminehowtobreakofthequeries

KeyPushdown-wherethetranslatorhasaccesstothefullsetofkeyvaluesanddetermineswhatqueriestosend

FullPushdown-wheretranslatorshipsthealldatafromtheindependentsidetothetranslator.Canbeusedautomaticallybycostingorcanbespecifiedasanoptioninthehint.

Teiidsupportshintstocontroldependentjoinbehavior:

MAKEIND-indicatesthattheclauseshouldbetheindependentsideofadependentjoin.

MAKEDEP-indicatesthattheclauseshouldbethedependentsideofajoin.MAKEDEPasanon-commenthintsupportsoptionalmaxandjoinarguments-MAKEDEP(JOIN)meaningthattheentirejoinshouldbepushed,andMAKEDEP(MAX:5000)meaningthatthedependentjoinshouldonlybeperformediftherearelessthanthemaxnumberofvaluesfromtheindependentside.

MAKENOTDEP-preventstheclausefrombeingthedependentsideofajoin.


618

ThesescanbeplacedineithertheOPTIONClauseordirectlyintheFROMClause.AslongasallAccessPatternscanbemet,theMAKEIND,MAKEDEP,andMAKENOTDEPhintsoverrideanyuseofcostinginformation.MAKENOTDEPsupersedestheotherhints.

TipTheMAKEDEP/MAKEINDhintshouldonlybeusediftheproperqueryplanisnotchosenbydefault.Youshouldensurethatyourcostinginformationisrepresentativeoftheactualsourcecardinality.AninappropriateMAKEDEP/MAKEINDhintcanforceaninefficientjoinstructureandmayresultinmanysourcequeries.

TheenginewillforINclausestofilterthevaluescomingfromthedependentside.IfthenumberofvaluesfromtheindependentsideexceedsthetranslatorsMaxInCriteriaSize,thevalueswillbesplitintomultipleINpredicatesuptoMaxDependentPredicates.WhenthenumberofindependentvaluesexceedsMaxInCriteriaSize*MaxDependentPredicates,thenmultipledependentquerieswillbeissuedinparallel.

TipWhilethesehintscanbeappliedtoviews,theoptimizerwillbydefaultremoveviewswhenpossible.Thiscanresultinthehintplacementbeingsignificantlydifferentthantheoriginalintention.YoushouldconsiderusingtheNO_UNNESThinttopreventtheoptimizerfromremovingtheviewinthesecases.

Note

FullPushdown-AFullPushdown,sometimesalsocalledasdata-shippushdown,iswhereallthedatafromindependentsideofthejoinissenttodependentside.CurrentlythisisonlysupportedintheJDBCtranslators.Toenableit,providetranslatoroverrideproperty"enableDependentJoins"to"true".ThetheJDBCsourcemustsupportcreationtemptables(thisisdeterminedbyusingHibernatedialectcapabilitiesforthesource).OncethesepropertiesareenabledandMAKEDEPhintisused,thetranslatorwillshipthedataastemptablecontentsandpushthedependentjointothesourceforfullrocessing.IfyouareworkingwithcustomtranslatorsseeDependentJoinPushdownastohowtosupportit.

CopyCriteriaCopycriteriaisanoptimizationthatcreatesadditionalpredicatesbaseduponcombiningjoinandwhereclausecriteria.Forexample,equi-joinpredicates(source1.table.column=source2.table.column)areusedtocreatenewpredicatesbysubstitutingsource1.table.columnforsource2.table.columnandviceversa.Inacrosssourcescenario,thisallowsforwherecriteriaappliedtoasinglesideofthejointobeappliedtobothsourcequeries

ProjectionMinimizationTeiidensuresthateachpushdownqueryonlyprojectsthesymbolsrequiredforprocessingtheuserquery.Thisisespeciallyhelpfulwhenqueryingthroughlargeintermediateviewlayers.

PartialAggregatePushdownPartialaggregatepushdownallowsforgroupingoperationsabovemulti-sourcejoinsandunionstobedecomposedsothatsomeofthegroupingandaggregatefunctionsmaybepusheddowntothesources.

OptionalJoinTheoptionaljoinhintindicatestotheoptimizerthatajoinedtableshouldbeomittedifnoneofitscolumnsareusedbytheoutputoftheuserqueryorinameaningfulwaytoconstructtheresultsoftheuserquery.Thishintistypicallyonlyusedinviewlayerscontainingmulti-sourcejoins.

Theoptionaljoinhintisappliedasacommentonajoinclause.ItcanbeappliedinbothANSIandnon-ANSIjoins.Withnon-ANSIjoinsanentirejoinedtablemaybemarkedasoptional.

ExampleOptionalJoinHint


619

selecta.column1,b.column2froma,/*+optional*/bWHEREa.key=b.key

SupposethisexampledefinesaviewlayerX.IfXisqueriedinsuchawayastonotneedb.column2,thentheoptionaljoinhintwillcausebtobeomittedfromthequeryplan.TheresultwouldbethesameasifXweredefinedas:

ExampleOptionalJoinHint

selecta.column1froma

ExampleANSIOptionalJoinHint

selecta.column1,b.column2,c.column3from/*+optional*/(ainnerjoinbONa.key=b.key)INNERJOINcONa.

key=c.key

InthisexampletheANSIjoinsyntaxallowsforthejoinofaandbtobemarkedasoptional.SupposethisexampledefinesaviewlayerX.Onlyifbothcolumna.column1andb.column2arenotneeded,e.g."SELECTcolumn3FROMX"willthejoinberemoved.

Theoptionaljoinhintwillnotremoveabridgingtablethatisstillrequired.

ExampleBridgingTable

selecta.column1,b.column2,c.column3from/*+optional*/a,b,cWHEREONa.key=b.keyANDa.key=c.key

SupposethisexampledefinesaviewlayerX.Ifb.column2orc.column3aresolelyrequiredbyaquerytoX,thenthejoinonaberemoved.Howeverifa.column1orbothb.column2andc.column3areneeded,thentheoptionaljoinhintwillnottakeeffect.

Whenajoinclauseisomittedviatheoptionaljoinhint,therelevantcriteriaisnotapplied.Thusitispossiblethatthequeryresultsmaynothavethesamecardinalityoreventhesamerowvaluesaswhenthejoinisfullyapplied.

Left/rightouterjoinswheretheinnersidevaluesarenotusedandwhoserowsundergoadistinctoperationwillautomaticallybetreatedasanoptionaljoinanddonotrequireahint.

ExampleUnnecessaryOptionalJoinHint

selectdistincta.column1fromaLEFTOUTERJOIN/*+optional*/bONa.key=b.key

Note Asimple"SELECTCOUNT(*)FROMVIEW"againstaviewwherealljointablesaremarkedasoptionalwillnotreturnameaningfulresult.

SourceHintsTeiiduserandtransformationqueriescancontainametasourcehintthatcanprovideadditionalinformationtosourcequeries.Thesourcehinthastheform:

/*+sh[[KEEPALIASES]:'arg']source-name[KEEPALIASES]:'arg1'...*/

Thesourcehintisexpectedtoappearafterthequery(SELECT,INSERT,UPDATE,DELETE)keyword.

Sourcehintsmayappearinanysubqueryorinviews.Allhintsapplicabletoagivensourcequerywillbecollectedandpusheddowntogetherasalist.Theorderofthehintsisnotguaranteed.


620

TheshargisoptionalandispassedtoallsourcequeriesviatheExecutionContext.getGeneralHintsmethod.Theadditionalargsshouldhaveasource-namethatmatchesthesourcenameassignedtothetranslatorintheVDB.Ifthesource-namematches,thehintvalueswillbesuppliedviatheExecutionContext.getSourceHintsmethod.SeetheDeveloper’sGuideformoreonusinganExecutionContext.

Eachoftheargvalueshastheformofastringliteral-itmustbesurroundedinsinglequotesandasinglequotecanbeescapedwithanothersinglequote.OnlytheOracletranslatordoesanythingwithsourcehintsbydefault.TheOracletranslatorwilluseboththesourcehintandthegeneralhint(inthatorder)ifavailabletoformanOraclehintenclosedin/*+…*/.

IftheKEEPALIASESoptionisusedeitherforthegeneralhintorontheapplicablesourcespecifichint,thenthetable/viewaliasesfromtheuserqueryandanynestedviewswillbepreservedinthepush-downquery.Thisisusefulinsituationswherethesourcehintmayneedtoreferencealiasesandtheuserdoesnotwishtorelyonthegeneratedaliases(whichcanbeseeninthequeryplanintherelevantsourcequeries-seeabove).Howeverinsomesituationsthismayresultinaninvalidsourcequeryifthepreservedaliasnamesarenotvalidforthesourceorresultinanamecollision.IftheusageofKEEPALIASESresultsinanerror,thequerycouldbemodifiedbypreventingviewremovalwiththeNO_UNNESThint,thealiasesmodified,ortheKEEPALIASESoptioncouldberemovedandthequeryplanusedtodeterminethegeneratedaliasnames.

SampleSourceHints

SELECT/*+sh:'generalhint'*/...

SELECT/*+shKEEPALIASES:'generalhint'my-oracle:'oraclehint'*/...

PartitionedUnionUnionpartitioningisinferredfromthetransformation/inlineview.Ifone(ormore)oftheUNIONcolumnsisdefinedbyconstantsand/orhasWHEREclauseINpredicatescontainingonlyconstantsthatmakeeachbranchmutuallyexclusive,thentheUNIONisconsideredpartitioned.UNIONALLmustbeusedandtheUNIONcannothaveaLIMIT,WITH,orORDERBYclause(althoughindividualbranchesmayuseLIMIT,WITH,orORDERBY).Partitioningvaluesshouldnotbenull.Forexampletheviewdefinition"select1asx,yfromfoounionallselectz,afromfoo1wherezin(2,3)"wouldbeconsideredpartitionedoncolumnx,sincethefirstbranchcanonlybethevalue1andthesecondbranchcanonlybethevalues2or3.Notethatmoreadvancedorexplicitpartitioncouldbeconsideredinthefuture.Theconceptofapartitionedunionisusedforperformingpartition-wisejoins,inUpdatableViews,andPartialAggregatePushdown.

StandardRelationalTechniquesTeiidalsoincorporatesmanystandardrelationaltechniquestoensureefficientqueryplans.

Rewriteanalysisforfunctionsimplificationandevaluation.

Booleanoptimizationsforbasiccriteriasimplification.

Removalofunnecessaryviewlayers.

Removalofunnecessarysortoperations.

Advancedsearchtechniquesthroughtheleft-linearspaceofjointrees.

Parallelizingofsourceaccessduringexecution.


JoinCompensation


621

Somesourcesystemsonlyallow"relationship"querieslogicallyproducingleftouterjoinresultsevenwhenqueriedwithaninnerjoinTeiidwillattempttoformanappropriateleftouterjoin.Thesesourcesarerestrictedtoonlysupportingkeyjoins.Insomecircumstancesforeignkeyrelationshipsonthesamesourceshouldnotbetraversedatallorwiththereferencedtableontheoutersideofjoin.Theextensionpropertyteiid_rel:allow-joincanbeusedontheforeignkeytofurtherrestrictthepushdownbehavior.Withavalueof"false"nojoinpushdownwillbeallowed,andwithavalueof"inner"thereferencedtablemustbeontheinnersideofthejoin.Ifthejoinpushdownisprevented,thejoinwillbeprocessedasafederatedjoin.


622

SubqueryOptimizationEXISTSsubqueriesaretypicallyrewriteto"SELECT1FROM…"topreventunnecessaryevaluationofSELECTexpressions.

QuantifiedcompareSOMEsubqueriesarealwaysturnedintoanequivalentINpredicateorcomparisonagainstanaggregatevalue.e.g.col>SOME(selectcol1fromtable)wouldbecomecol>(selectmin(col1)fromtable)

UncorrelatedEXISTsandscalarsubquerythatarenotpushedtothesourcecanbepre-evaluatedpriortosourcecommandformation.

CorrelatedsubqueriesusedinDETELEsorUPDATEsthatarenotpushedaspartofthecorrespondingDELETE/UPDATEwillcauseTeiidtoperformrow-by-rowcompensatingprocessing.Thiswillonlyhappeniftheaffectedtablehasaprimarykey.Ifitdoesnot,thenanexceptionwillbethrown.

WHEREorHAVINGclauseIN,QuantifiedComparison,ScalarSubqueryCompare,andEXISTspredicatescantaketheMJ(mergejoin),DJ(dependentjoin),orNO_UNNEST(nounnest)hintsappearingjustbeforethesubquery.TheMJhintdirectstheoptimizertouseatraditional,semijoin,orantisemijoinmergejoinifpossible.TheDJisthesameastheMJhint,butadditionallydirectstheoptimizertousethesubqueryastheindependentsideofadependentjoinifpossible.TheNO_UNNESThint,whichsupercedestheotherhints,willdirecttheoptimizertoleavethesubqueryinplace.

MergeJoinHintUsage

SELECTcol1fromtblwherecol2IN/*+MJ*/(SELECTcol1FROMtbl2)

DependentJoinHintUsage

SELECTcol1fromtblwherecol2IN/*+DJ*/(SELECTcol1FROMtbl2)

NoUnnestHintUsage

SELECTcol1fromtblwherecol2IN/*+NO_UNNEST*/(SELECTcol1FROMtbl2)

Thesystempropertyorg.teiid.subqueryUnnestDefaultcontrolswhethertheoptimizerwillbydefaultunnestsubqueriesduringrewrite.Iftrue,thenmostnon-negatedWHEREorHAVINGclauseEXISTSorINsubquerypredicatescanbeconvertedtoatraditionaljoin.

Theplannerwillalwaysconverttoantijoinorsemijoinvariantsifcostingisfavorable.Useahinttooverridethisbehaviorneeded.

EXISTsandscalarsubqueriesthatarenotpusheddown,andnotconvertedtomergejoins,areimplicitlylimitedto1and2resultrowsrespectively.

Conversionofsubquerypredicatestonestedloopjoinsisnotyetavailable.


623

XQueryOptimizationAtechniqueknownasdocumentprojectionisusedtoreducethememoryfootprintofthecontextitemdocument.DocumentprojectionloadsonlythepartsofthedocumentneededbytherelevantXQueryandpathexpressions.Sincedocumentprojectionanalysisusesallrelevantpathexpressions,even1expressionthatcouldpotentiallyusemanynodes,e.g.//xratherthan/a/b/xwillcausealargermemoryfootprint.Withtherelevantcontentremovedtheentiredocumentwillstillbeloadedintomemoryforprocessing.Documentprojectionwillonlybeusedwhenthereisacontextitem(unnamedPASSINGclauseitem)passedtoXMLTABLE/XMLQUERY.Anamedvariablewillnothavedocumentprojectionperformed.Insomecasestheexpressionsusedmaybetoocomplexfortheoptimizertousedocumentprojection.YoushouldchecktheSHOWPLANDEBUGfullplanoutputtoseeiftheappropriateoptimizationhasbeenperformed.

Withadditionalrestrictions,simplecontextpathexpressionsallowtheprocessortoevaluatedocumentsubtreesindependently-withoutloadingthefulldocumentinmemory.Asimplecontextpathexpressioncanbeoftheform"[/][ns:]root/[ns1:]elem/…",whereanamespaceprefixorelementnamecanalsobethe*wildcard.AswithnormalXQueryprocessingifnamespaceprefixesareusedintheXQueryexpression,theyshouldbedeclaredusingtheXMLNAMESPACESclause.

StreamingEligibleXMLQUERY

XMLQUERY('/*:root/*:child'PASSINGdoc)

Ratherthanloadingtheentiredocin-memoryasaDOMtree,eachchildelementwillbeindependentlyaddedtotheresult.

StreamingIneligibleXMLQUERY

XMLQUERY('//child'PASSINGdoc)

Theuseofthedescendantaxispreventsthestreamingoptimization,butdocumentprojectioncanstillbeperformed.

WhenusingXMLTABLE,theCOLUMNPATHexpressionshaveadditionalrestrictions.Theyareallowedtoreferenceanypartoftheelementsubtreeformedbythecontextexpressionandtheymayuseanyattributevaluefromtheirdirectparentage.Anypathexpressionwhereitispossibletoreferenceanon-directancestororsiblingofthecurrentcontextitempreventstreamingfrombeingused.

StreamingEligibleXMLTABLE

XMLTABLE('/*:root/*:child'PASSINGdocCOLUMNSfullchildXMLPATH'.',parent_attrstringPATH'../@attr',chil

d_valinteger)

ThecontextXQueryandthecolumnpathexpressionallowthestreamingoptimization,ratherthanloadingtheentiredocin-memoryasaDOMtree,eachchildelementwillbeindependentlyaddedtotheresult.

StreamingIneligibleXMLTABLE

XMLTABLE('/*:root/*:child'PASSINGdocCOLUMNSsibling_attrstringPATH'../other_child/@attr')

Thereferenceofanelementoutsideofthechildsubtreeinthesibling_attrpathpreventsthestreamingoptimizationfrombeingused,butdocumentprojectioncanstillbeperformed.

Note Columnpathsshouldbeastargetedaspossibletoavoidperformanceissues.Ageneralpathsuchas`..//child'willcausetheentiresubtreeofthecontextitemtobesearchedoneachoutputrow.

XQueryOptimization

624

XQueryOptimization

625

PartialResultsTeiidprovidesthecapabilitytoobtain"partialresults"intheeventofdatasourceunavailabilityorfailure.Thisisespeciallyusefulwhenunioninginformationfrommultiplesources,orwhendoingaleftouterjoin,whereyouare`appending'columnstoamasterrecordbutstillwanttherecordiftheextrainformationisnotavailable.

Asourceisconsideredtobe`unavailable'iftheconnectionfactoryassociatedwiththesourceissuesanexceptioninresponsetoaquery.Theexceptionwillbepropagatedtothequeryprocessor,whereitwillbecomeawarningonthestatement.SeetheClientGuideformoreonPartialResultsModeandSQLWarnings.


626

ConformedTablesAconformedtableisasourcetablethatisthesameinseveralphysicalsources.UnlikeMultisourceModelswhichassumeapartitioningparadigm,theplannerassumesanyconformedtablemaybesubstitutedforanothertoimproveperformance.Typicallythiswouldbeusedwhenreferencedataexistsinmultiplesources,butonlyasinglemetadataentryisdesiredtorepresentthetable.

Conformedtablesaredefinedbyaddingthe

{http://www.teiid.org/ext/relational/2012}conformed-sources

extensionmetadatapropertytotheappropriatesourcetables.ExtensionpropertiescanbesetatdesigntimeinDesigner,inthevdb.xmlwhenusingfullDDLMetadataoralterstatements,oratruntimeusingthesetPropertysystemprocedure.Thepropertyisexpectedtobeacommaseparatedlistofphysicalmodel/schemanames.

DDLAlterExample

ALTERFOREIGNTABLE"reference_data"OPTIONS(ADD"teiid_rel:conformed-sources"'source2,source3');

Thereisnoexpectationthatametadataentryexistsontheotherschemas.Justaswiththemulti-sourcefeature,thereisthennosourcespecificmetadataentrytotheconformedsources.Alsojustaswithmulti-sourceplanning,thecapabilitiesareassumedtobethesameacrossconformedsources.

Theenginewilltakethelistofconformedsourcesandassociateasetofmodelmetadataidstothecorrespondingaccessnode.Thelogicconsideringjoinsandsubquerieswillalsoconsidertheconformedsetswhenmakingpushdowndecisions.Thesubqueryhandlingwillonlycheckforconformedsourcesforthesubquery-notintheparent.Sohavingaconformedtableinthesubquerywillpushdownasexpected,butnotviceversa.

ConformedTables

627

TeiidComponents

DesignerPlugin-EclipsePluginbasedTeiiddesignenvironment,usedtoconnect/federate/transformdatasourcestoproducea.vdbfile.

JVM-TeiidisapureJavaDataVirtualizationPlatform.

WildFly-TeiiduseaplugableinstallationwhichneedaWildFlyServerinstalled,alternatively,afullinstalledWildFlykitbedistributed.

Subsystem-DuetoWildFly’sModularandPluggableArchitecture(aseriesofManagementcommandscomposeofasubsystem,aseriesofsubsystemscomposeofthewholeserver),TeiidimplementWildFly’sController/ManagementAPIdevelopedateiidsubsystemandreuselotsofothersubsystemslikeresource-adapter,infinispan,security,logging,datasource.

odata.war-TeiidsupportODataviaodata.war,moredetailsrefertoODataSupport

dashboard.war-Awebbaseddashboardgenerator.

teiid-console-AwebbasedadministrativeandmonitoringtoolforTeiid,moredetailsrefertoTeiidConsole

JDBCDriver-JDBCDrivertoconnecttoTeiidServer.

adminshell-AscriptingbasedMonitor/ManagementTool,moredetailsrefertoAdminShell

quickstarts-AmavenquickstartshowinghowtoutilizeTeiid.

TeiidArchitecture

Architecture

628

Client-ClientDevelopGuide

Transport-ATransportmanagementsclientconnections-securityauthentication,encryption,etc.

QueryEngine-TheQueryEnginehasseverallayers/components.Requestprocessingatahighlevel:

1. SQLisconvertedtoaProcessorPlan.TheenginereceivesanincomingSQLquery.Itisparsedtoainternalcommand.Thenthecommandisconvertedalogicalplanviaresolving,validating,andrewriting.Lastlyruleandcost-basedoptimizationconvertthelogicalplantoafinalProcessorPlan.MoredetailsrefertoFederatedPlanning.

2. BatchProcessing.Thesourceandotheraspectsofqueryprocessingmayreturnresultsasynchronouslytotheprocessingthread.Assoonaspossiblebatchesofresultsaremadeavailabletotheclient.

3. BufferManagementControlsthebulkoftheonandoffheapmemorythatTeiidisusing.Itpreventsconsumingtoomuchmemorythatotherwisemightexceedthevmsize.

4. TransactionManagementdetermineswhentransactionsareneededandinteractswiththeTransactionManagersubsystemtocoordinateXAtransactions.

SourcequeriesarehandledbytheDataTierlayerwhichinterfaceswiththeQueryEngineandtheConnectorLayerwhichutilizesaTranslator/ResourceAdapterpairtointeractdirectlywithasource.Connectivityisprovidedforheterogeneousdatastores,likeDatabases/Datawarehouse,NoSQL,Hadoop,DataGrid/Cache,File,SaaS,etc.-seeDataSources.

Translator-TeiidhasdevelopedaseriesofTranslators,formoredetailsrefertoTranslators.

ResourceAdapter-Providescontainermanagedaccesstoasource,formoredetailsrefertoDevelopingJEEConnectors.

Architecture

629

TerminologyVMorProcess–aJBossASinstancerunningTeiid.

Host–amachinethatis"hosting"oneormoreVMs.

Service–asubsystemrunninginaVM(ofteninmanyVMs)andprovidingarelatedsetoffunctionality.Inadditiontothesemaincomponents,theserviceplatformprovidesacoresetofservicesavailabletoapplicationsbuiltontopoftheserviceplatform.Theseservicesare:

Session–theSessionservicemanagesactivesessioninformation.

BufferManager–theBufferManagerserviceprovidesaccesstodatamanagementforintermediateresults.

Transaction–theTransactionservicemanagesglobal,local,andrequestscopedtransactions.SeealsothedocumentationonTransactionSupport.

Terminology

630

DataManagement

CursoringandBatching

Teiidcursorsallresults,regardlessofwhethertheyarefromonesourceormanysources,andregardlessofwhattypeofprocessing(joins,unions,etc.)havebeenperformedontheresults.

Teiidprocessesresultsinbatches.Abatchissimplyasetofrecords.Thenumberofrowsinabatchisdeterminedbythebuffersystempropertyprocessor-batch-sizeandisscaledupontheestimatedmemoryfootprintofthebatch.

Clientapplicationshavenodirectknowledgeofbatchesorbatchsizes,butratherspecifyfetchsize.Howeverthefirstbatch,regardlessoffetchsizeisalwaysproactivelyreturnedtosynchronousclients.Subsequentbatchesarereturnedbasedonclientdemandforthedata.Pre-fetchingisutilizedatboththeclientandconnectorlevels.

BufferManagement

Thebuffermanagermanagesmemoryforallresultsetsusedinthequeryengine.Thatincludesresultsetsreadfromaconnectionfactory,resultsetsusedtemporarilyduringprocessing,andresultsetspreparedforauser.Eachresultsetisreferredtointhebuffermanagerasatuplesource.

Whenretrievingbatchesfromthebuffermanager,thesizeofabatchinbytesisestimatedandthenallocatedagainstthemaxlimit.

MemoryManagement

Thebuffermanagerhastwostoragemanagers-amemorymanagerandadiskmanager.Thebuffermanagermaintainsthestateofallthebatches,anddetermineswhenbatchesmustbemovedfrommemorytodisk.

DiskManagement

Eachtuplesourcehasadedicatedfile(namedbytheID)ondisk.Thisfilewillbecreatedonlyifatleastonebatchforthetuplesourcehadtobeswappedtodisk.Thefileisrandomaccess.Theprocessorbatchsizepropertydefineshowmanyrowsshouldnominallyexistinabatchassuming2048bitsworthofdatainarow.Iftherowislargerorsmallerthanthattarget,theenginewilladjustthebatchsizeforthosetuplesaccordingly.Batchesarealwaysreadandwrittenfromthestoragemanagerwhole.

Thediskstoragemanagerhasacaponthemaximumnumberofopenfilestopreventrunningoutoffilehandles.Incaseswithheavybuffering,thiscancausewaittimeswhilewaitingforafilehandletobecomeavailable(thedefaultmaxopenfilesis64).

CleanupWhenatuplesourceisnolongerneeded,itisremovedfromthebuffermanager.Thebuffermanagerwillremoveitfromboththememorystoragemanagerandthediskstoragemanager.Thediskstoragemanagerwilldeletethefile.Inaddition,everytuplesourceistaggedwitha"groupname"whichistypicallythesessionIDoftheclient.Whentheclient’ssessionisterminated(byclosingtheconnection,serverdetectingclientshutdown,oradministrativetermination),acallissenttothebuffermanagertoremovealltuplesourcesforthesession.

Inaddition,whenthequeryengineisshutdown,thebuffermanagerisshutdown,whichwillremoveallstatefromthediskstoragemanagerandcauseallfilestobeclosed.Whenthequeryengineisstopped,itissafetodeleteanyfilesinthebufferdirectoryastheyarenotusedacrossqueryenginerestartsandmustbeduetoasystemcrashwherebufferfileswerenotcleaned

DataManagement

631

up.

DataManagement

632

QueryTermination

CancelingQueries

Whenaqueryiscanceled,processingwillbestoppedinthequeryengineandinallconnectorsinvolvedinthequery.Thesemanticsofwhataconnectordoesinresponsetoacancellationcommandisdependentontheconnectorimplementation.Forexample,JDBCconnectorswillasynchronouslycallcancelontheunderlyingJDBCdriver,whichmayormaynotactuallysupportthismethod.

UserQueryTimeouts

UserquerytimeoutsinTeiidcanbemanagedontheclient-sideortheserver-side.Timeoutsareonlyrelevantforthefirstrecordreturned.Ifthefirstrecordhasnotbeenreceivedbytheclientwithinthespecifiedtimeoutperiod,a`cancel'commandisissuedtotheserverfortherequestandnoresultsarereturnedtotheclient.Thecancelcommandisissuedasynchronouslywithouttheclient’sintervention.

TheJDBCAPIusesthequerytimeoutsetbythejava.sql.Statement.setQueryTimeoutmethod.Youmayalsosetadefaultstatementtimeoutviatheconnectionproperty"QUERYTIMEOUT".ODBCclientsmayalsoutilizeQUERYTIMEOUTasanexecutionpropertyviaasetstatementtocontrolthedefaulttimeoutsetting.SeetheClientDevelopersGuideformoreonconnection/executionpropertiesandsetstatements.

Server-sidetimeoutsstartwhenthequeryisreceivedbytheengine.TheremaybeaskewfromthewhentheclientissuedthequeryduetonetworklatencyorserverloadthatmayslowtheprocessingofIOwork.Thetimeoutwillbecancelledifthefirstresultissentbackbeforethetimeouthasended.SeetheVDBssectionformoreonsettingthequery-timeoutVDBproperty.SeetheAdminGuideformoreonmodifyingthefiletosetdefaultquerytimeoutforallqueries.

QueryTermination

633

Processing

JoinAlgorithms

Nestedloopdoesthemostobviousprocessing–foreveryrowintheoutersource,itcompareswitheveryrowintheinnersource.Nestedloopisonlyusedwhenthejoincriteriahasnoequi-joinpredicates.

Mergejoinfirstsortstheinputsourcesonthejoinedcolumns.Youcanthenwalkthrougheachsideinparallel(effectivelyonepassthrougheachsortedsource)andwhenyouhaveamatch,emitarow.Ingeneral,mergejoinisontheorderofn+mratherthann*minnestedloop.Mergejoinisthedefaultalgorithm.

Usingcostinginformationtheenginemayalsodelaythedecisiontoperformafullsortmergejoin.Basedupontheactualrowcountsinvolved,theenginecanchoosetobuildanindexofthesmallerside(whichwillperformsimilarlytoahashjoin)ortoonlypartiallysortthelargersideoftherelation.

Joinsinvolvingequi-joinpredicatesarealsoeligibletobemadeintodependentjoins.

SortBasedAlgorithms

SortingisusedasthebasisoftheSort(ORDERBY),Grouping(GROUPBY),andDupRemoval(SELECTDISTINCT)operations.Thesortalgorithmisamulti-passmerge-sortthatdoesnotrequirealloftheresultsettoeverbeinmemoryyetusesthemaximalamountofmemoryallowedbythebuffermanager.

Itconsistsoftwophases.Thefirstphase("sort")willtakeanunsortedinputstreamandproduceoneormoresortedinputstreams.Eachpassreadsasmuchoftheunsortedstreamaspossible,sortsit,andwritesitbackoutasanewstream.Sincethestreammaybemorethancanfitinmemory,thismayresultinmanysortedstreams.

Thesecondphase("merge")consistsofasetofphasesthatgrabthenextbatchfromasmanysortedinputstreamsaswillfitinmemory.Itthenrepeatedlygrabsthenexttupleinsortedorderfromeachstreamandoutputsmergedsortedbatchestoanewsortedstream.Atcompletionofthepass,allinputstreamsaredropped.Inthisway,eachpassreducesthenumberofsortedstreams.Whenonlyonestreamremains,itisthefinaloutput.

Processing

634

BNFforSQLGrammarMainEntryPoints

callablestatement

ddlstatement

procedurebodydefinition

directlyexecutablestatement

ReservedKeywords

Non-ReservedKeywords

ReservedKeywordsForFutureUse

Tokens

ProductionCross-Reference

Productions

ReservedKeywords

Keyword Usage

ADD addsetoption

ALLstandardaggregatefunction,function,queryexpressionbody,queryterm,selectclause,quantifiedcomparisonpredicate

ALTER alter,altercolumnoptions,alteroptions

AND betweenpredicate,booleanterm

ANY standardaggregatefunction,quantifiedcomparisonpredicate

ARRAY_AGG orderedaggregatefunction

AS

alter,arraytable,createprocedure,optionnamespace,createtable,createtrigger,derivedcolumn,dynamicdatastatement,function,loopstatement,xmlnamespaceelement,objecttable,selectderivedcolumn,tablesubquery,texttable,tablename,unescapedFunction,withlistelement,xmlserialize,xmltable

ASC sortspecification

ATOMIC compoundstatement,foreachrowtriggeraction

BEGIN compoundstatement,foreachrowtriggeraction

BNFforSQLGrammar

635

BETWEEN betweenpredicate

BIGDECIMAL simpledatatype

BIGINT simpledatatype

BIGINTEGER simpledatatype

BLOB simpledatatype,xmlserialize

BOOLEAN simpledatatype

BOTH function

BREAK branchingstatement

BY groupbyclause,orderbyclause,windowspecification

BYTE simpledatatype

CALL callablestatement,callstatement

CASE caseexpression,searchedcaseexpression

CAST function

CHAR function,simpledatatype

CLOB simpledatatype,xmlserialize

COLUMN altercolumnoptions

COMMIT createtemporarytable

CONSTRAINT createtablebody

CONTINUE branchingstatement

CONVERT function

CREATEcreateprocedure,createforeigntemptable,createtable,createtemporarytable,createtrigger,procedurebodydefinition

CROSS crossjoin

DATE nonnumericliteral,simpledatatype

DAY function

DECIMAL simpledatatype

DECLARE declarestatement

BNFforSQLGrammar

636

DEFAULT tableelement,xmlnamespaceelement,objecttablecolumn,procedureparameter,xmltablecolumn

DELETE alter,createtrigger,deletestatement

DESC sortspecification

DISTINCT standardaggregatefunction,function,ifstatement,queryexpressionbody,queryterm,selectclause

DOUBLE simpledatatype

DROP dropoption,droptable

EACH foreachrowtriggeraction

ELSE caseexpression,ifstatement,searchedcaseexpression

END caseexpression,compoundstatement,foreachrowtriggeraction,searchedcaseexpression

ERROR raiseerrorstatement

ESCAPE matchpredicate,texttable

EXCEPT queryexpressionbody

EXEC dynamicdatastatement,callstatement

EXECUTE dynamicdatastatement,callstatement

EXISTS existspredicate

FALSE nonnumericliteral

FETCH fetchclause

FILTER filterclause

FLOAT simpledatatype

FOR foreachrowtriggeraction,function,textaggreatefunction,texttablecolumn,xmltablecolumn

FOREIGN alteroptions,createprocedure,createforeigntemptable,createtable,foreignkey

FROM deletestatement,fromclause,function,ifstatement

FULL qualifiedtable

FUNCTION createprocedure

BNFforSQLGrammar

637

GEOMETRY simpledatatype

GLOBAL createtable

GROUP groupbyclause

HAVING havingclause

HOUR function

IF ifstatement

IMMEDIATE dynamicdatastatement

IN procedureparameter,inpredicate

INNER qualifiedtable

INOUT procedureparameter

INSERT alter,createtrigger,function,insertstatement

INTEGER simpledatatype

INTERSECT queryterm

INTO dynamicdatastatement,insertstatement,intoclause

IS ifstatement,isnullpredicate

JOIN crossjoin,makedepoptions,qualifiedtable

LANGUAGE objecttable

LATERAL tablesubquery

LEADING function

LEAVE branchingstatement

LEFT function,qualifiedtable

LIKE matchpredicate

LIKE_REGEX likeregexpredicate

LIMIT limitclause

LOCAL createforeigntemptable,createtemporarytable

LONG simpledatatype

BNFforSQLGrammar

638

LOOP loopstatement

MAKEDEP optionclause,tableprimary

MAKEIND optionclause,tableprimary

MAKENOTDEP optionclause,tableprimary

MERGE insertstatement

MINUTE function

MONTH function

NO makedepoptions,xmlnamespaceelement,texttablecolumn,texttable

NOCACHE optionclause

NOT

betweenpredicate,compoundstatement,tableelement,ifstatement,isnullpredicate,matchpredicate,booleanfactor,procedureparameter,procedureresultcolumn,likeregexpredicate,inpredicate,temporarytableelement

NULLtableelement,isnullpredicate,nonnumericliteral,procedureparameter,procedureresultcolumn,temporarytableelement,xmlquery

OBJECT simpledatatype

OF alter,createtrigger

OFFSET limitclause

ON alter,createforeigntemptable,createtemporarytable,createtrigger,loopstatement,qualifiedtable,xmlquery

ONLY fetchclause

OPTION optionclause

OPTIONS alteroptionslist,optionsclause

OR booleanvalueexpression

ORDER orderbyclause

OUT procedureparameter

OUTER qualifiedtable

OVER windowspecification

PARAMETER altercolumnoptions

BNFforSQLGrammar

639

PARTITION windowspecification

PRIMARY tableelement,createtemporarytable,primarykey

PROCEDURE alter,alteroptions,createprocedure,procedurebodydefinition

REAL simpledatatype

REFERENCES foreignkey

RETURN assignmentstatement,returnstatement,datastatement

RETURNS createprocedure

RIGHT function,qualifiedtable

ROLLUP groupbyclause

ROW fetchclause,foreachrowtriggeraction,limitclause,texttable

ROWS createtemporarytable,fetchclause,limitclause

SECOND function

SELECT selectclause

SET addsetoption,optionnamespace,updatestatement

SHORT simpledatatype

SIMILAR matchpredicate

SMALLINT simpledatatype

SOME standardaggregatefunction,quantifiedcomparisonpredicate

SQLEXCEPTION sqlexception

SQLSTATE sqlexception

SQLWARNING raisestatement

STRING dynamicdatastatement,simpledatatype,xmlserialize

TABLEalteroptions,createprocedure,createforeigntemptable,createtable,createtemporarytable,droptable,queryprimary,tablesubquery

TEMPORARY createforeigntemptable,createtable,createtemporarytable

BNFforSQLGrammar

640

THEN caseexpression,searchedcaseexpression

TIME nonnumericliteral,simpledatatype

TIMESTAMP nonnumericliteral,simpledatatype

TINYINT simpledatatype

TO matchpredicate

TRAILING function

TRANSLATE function

TRIGGER alter,createtrigger

TRUE nonnumericliteral

UNION crossjoin,queryexpressionbody

UNIQUE otherconstraints,tableelement

UNKNOWN nonnumericliteral

UPDATE alter,createtrigger,dynamicdatastatement,updatestatement

USER function

USING dynamicdatastatement

VALUES queryprimary

VARBINARY simpledatatype,xmlserialize

VARCHAR simpledatatype,xmlserialize

VIRTUAL alteroptions,createprocedure,createtable,procedurebodydefinition

WHEN caseexpression,searchedcaseexpression

WHERE filterclause,whereclause

WHILE whilestatement

WITH assignmentstatement,queryexpression,datastatement

WITHOUT assignmentstatement,datastatement

XML simpledatatype

BNFforSQLGrammar

641

XMLAGG orderedaggregatefunction

XMLATTRIBUTES xmlattributes

XMLCAST unescapedFunction

XMLCOMMENT function

XMLCONCAT function

XMLELEMENT xmlelement

XMLEXISTS xmlquery

XMLFOREST xmlforest

XMLNAMESPACES xmlnamespaces

XMLPARSE xmlparse

XMLPI function

XMLQUERY xmlquery

XMLSERIALIZE xmlserialize

XMLTABLE xmltable

XMLTEXT function

YEAR function

Non-ReservedKeywords

Name Usage

ACCESSPATTERN otherconstraints,non-reservedidentifier

ARRAYTABLE arraytable,non-reservedidentifier

AUTO_INCREMENT tableelement,non-reservedidentifier

AVG standardaggregatefunction,non-reservedidentifier

CHAIN sqlexception,non-reservedidentifier

COLUMNS arraytable,non-reservedidentifier,objecttable,texttable,xmltable

CONTENT non-reservedidentifier,xmlparse,xmlserialize

BNFforSQLGrammar

642

COUNT standardaggregatefunction,non-reservedidentifier

DELIMITER non-reservedidentifier,textaggreatefunction,texttable

DENSE_RANK analyticaggregatefunction,non-reservedidentifier

DISABLED alter,non-reservedidentifier

DOCUMENT non-reservedidentifier,xmlparse,xmlserialize

EMPTY non-reservedidentifier,xmlquery

ENABLED alter,non-reservedidentifier

ENCODING non-reservedidentifier,textaggreatefunction,xmlserialize

EVERY standardaggregatefunction,non-reservedidentifier

EXCEPTION compoundstatement,declarestatement,non-reservedidentifier

EXCLUDING non-reservedidentifier,xmlserialize

EXTRACT function,non-reservedidentifier

FIRST fetchclause,non-reservedidentifier,sortspecification

HEADER non-reservedidentifier,textaggreatefunction,texttablecolumn,texttable

INCLUDING non-reservedidentifier,xmlserialize

INDEX otherconstraints,tableelement,non-reservedidentifier

INSTEAD alter,createtrigger,non-reservedidentifier

JSONARRAY_AGG non-reservedidentifier,orderedaggregatefunction

JSONOBJECT jsonobject,non-reservedidentifier

KEY tableelement,createtemporarytable,foreignkey,non-reservedidentifier,primarykey

LAST non-reservedidentifier,sortspecification

MAX standardaggregatefunction,makedepoptions,non-reservedidentifier

MIN standardaggregatefunction,non-reservedidentifier

NAME function,non-reservedidentifier,xmlelement

BNFforSQLGrammar

643

NAMESPACE optionnamespace,non-reservedidentifier

NEXT fetchclause,non-reservedidentifier

NULLS non-reservedidentifier,sortspecification

OBJECTTABLE non-reservedidentifier,objecttable

ORDINALITY non-reservedidentifier,texttablecolumn,xmltablecolumn

PASSING non-reservedidentifier,objecttable,xmlquery,xmlquery,xmltable

PATH non-reservedidentifier,xmltablecolumn

PRESERVE createtemporarytable,non-reservedidentifier

QUERYSTRING non-reservedidentifier,querystringfunction

QUOTE non-reservedidentifier,textaggreatefunction,texttable

RAISE non-reservedidentifier,raisestatement

RANK analyticaggregatefunction,non-reservedidentifier

RESULT non-reservedidentifier,procedureparameter

ROW_NUMBER analyticaggregatefunction,non-reservedidentifier

SELECTOR non-reservedidentifier,texttablecolumn,texttable

SERIAL tableelement,non-reservedidentifier,temporarytableelement

SKIP non-reservedidentifier,texttable

SQL_TSI_DAY timeinterval,non-reservedidentifier

SQL_TSI_FRAC_SECOND timeinterval,non-reservedidentifier

SQL_TSI_HOUR timeinterval,non-reservedidentifier

SQL_TSI_MINUTE timeinterval,non-reservedidentifier

SQL_TSI_MONTH timeinterval,non-reservedidentifier

SQL_TSI_QUARTER timeinterval,non-reservedidentifier

SQL_TSI_SECOND timeinterval,non-reservedidentifier

SQL_TSI_WEEK timeinterval,non-reservedidentifier

BNFforSQLGrammar

644

SQL_TSI_YEAR timeinterval,non-reservedidentifier

STDDEV_POP standardaggregatefunction,non-reservedidentifier

STDDEV_SAMP standardaggregatefunction,non-reservedidentifier

SUBSTRING function,non-reservedidentifier

SUM standardaggregatefunction,non-reservedidentifier

TEXTAGG non-reservedidentifier,textaggreatefunction

TEXTTABLE non-reservedidentifier,texttable

TIMESTAMPADD function,non-reservedidentifier

TIMESTAMPDIFF function,non-reservedidentifier

TO_BYTES function,non-reservedidentifier

TO_CHARS function,non-reservedidentifier

TRIM function,non-reservedidentifier,texttablecolumn,texttable

VARIADIC non-reservedidentifier,procedureparameter

VAR_POP standardaggregatefunction,non-reservedidentifier

VAR_SAMP standardaggregatefunction,non-reservedidentifier

VERSION non-reservedidentifier,xmlserialize

VIEW alter,alteroptions,createtable,non-reservedidentifier

WELLFORMED non-reservedidentifier,xmlparse

WIDTH non-reservedidentifier,texttablecolumn

XMLDECLARATION non-reservedidentifier,xmlserialize

ReservedKeywordsForFutureUse

ALLOCATE ARE ARRAY

ASENSITIVE ASYMETRIC AUTHORIZATION

BINARY CALLED CASCADED

CHARACTER CHECK CLOSE

BNFforSQLGrammar

645

COLLATE CONNECT CORRESPONDING

CRITERIA CURRENT_DATE CURRENT_TIME

CURRENT_TIMESTAMP CURRENT_USER CURSOR

CYCLE DATALINK DEALLOCATE

DEC DEREF DESCRIBE

DETERMINISTIC DISCONNECT DLNEWCOPY

DLPREVIOUSCOPY DLURLCOMPLETE DLURLCOMPLETEONLY

DLURLCOMPLETEWRITE DLURLPATH DLURLPATHONLY

DLURLPATHWRITE DLURLSCHEME DLURLSERVER

DLVALUE DYNAMIC ELEMENT

EXTERNAL FREE GET

GRANT HAS HOLD

IDENTITY IMPORT INDICATOR

INPUT INSENSITIVE INT

INTERVAL ISOLATION LARGE

LOCALTIME LOCALTIMESTAMP MATCH

MEMBER METHOD MODIFIES

MODULE MULTISET NATIONAL

NATURAL NCHAR NCLOB

NEW NONE NUMERIC

OLD OPEN OUTPUT

OVERLAPS PRECISION PREPARE

RANGE READS RECURSIVE

REFERENCING RELEASE REVOKE

ROLLBACK SAVEPOINT SCROLL

SEARCH SENSITIVE SESSION_USER

BNFforSQLGrammar

646

SPECIFIC SPECIFICTYPE SQL

START STATIC SUBMULTILIST

SYMETRIC SYSTEM SYSTEM_USER

TIMEZONE_HOUR TIMEZONE_MINUTE TRANSLATION

TREAT VALUE VARYING

WHENEVER WINDOW WITHIN

XMLBINARY XMLDOCUMENT XMLITERATE

Tokens

Name Definition Usage

allingroupidentifier <identifier><period><star> allingroup

binarystringliteral "X"|"x""\'"(<hexit><hexit>)+"\'" nonnumericliteral

colon ":" makedepoptions,statement

comma ","

alteroptionslist,columnlist,createprocedure,typedelementlist,createtablebody,createtemporarytable,derivedcolumnlist,sqlexception,namedparameterlist,expressionlist,fromclause,function,limitclause,nestedexpression,objecttable,optionclause,optionsclause,orderbyclause,simpledatatype,queryexpression,queryprimary,querystringfunction,selectclause,setclauselist,inpredicate,textaggreatefunction,texttable,xmlattributes,xmlelement,xmlquery,xmlforest,xmlnamespaces,xmlquery,xmltable

concat_op "||" commonvalueexpression

decimalnumericliteral (<digit>)*<period><unsignedintegerliteral> unsignednumericliteral

digit \["0"\-"9"\]

dollar "$" parameterreference

double_amp_op "&&" commonvalueexpression

eq "="

assignmentstatement,callablestatement,declarestatement,namedparameterlist,comparisonoperator,setclauselist

BNFforSQLGrammar

647

escapedfunction "{""fn" unsignedvalueexpressionprimary

escapedjoin "{""oj" tablereference

escapedtype "{"("d"|"t"|"ts"|"b") nonnumericliteral

approximatenumericliteral<digit><period><unsignedintegerliteral>\["e","E"\](<plus>|<minus>)?<unsignedintegerliteral>

unsignednumericliteral

ge ">=" comparisonoperator

gt ">" namedparameterlist,comparisonoperator

hexit \["a"\-"f","A"\-"F"\]|<digit>

identifier <quoted_id>(<period><quoted_id>)*

identifier,unsignedvalueexpressionprimary

id_part ("@"|"#"|<letter>)(<letter>|"_"|<digit>)*

lbrace "{" callablestatement,matchpredicate

le "⇐" comparisonoperator

letter \["a"\-"z","A"\-"Z"\]|\["\u0153"\-"\ufffd"\]

lparen "("

standardaggregatefunction,alteroptionslist,analyticaggregatefunction,arraytable,callablestatement,columnlist,otherconstraints,createprocedure,createtablebody,createtemporarytable,filterclause,function,groupbyclause,ifstatement,jsonobject,loopstatement,makedepoptions,nestedexpression,objecttable,optionsclause,orderedaggregatefunction,simpledatatype,queryprimary,querystringfunction,inpredicate,callstatement,subquery,quantifiedcomparisonpredicate,tablesubquery,tableprimary,textaggreatefunction,texttable,unescapedFunction,whilestatement,windowspecification,withlistelement,xmlattributes,xmlelement,xmlquery,xmlforest,xmlnamespaces,xmlparse,xmlquery,xmlserialize,xmltable

lsbrace "[" datatype,valueexpressionprimary

lt "<" comparisonoperator

BNFforSQLGrammar

648

minus "-" plusorminus

ne "<>" comparisonoperator

ne2 "!=" comparisonoperator

period "."

plus "+" plusorminus

qmark "?" callablestatement,parameterreference

quoted_id <id_part>|"\""("\"\""|~\["\""\])+"\""

rbrace "}"callablestatement,matchpredicate,nonnumericliteral,tablereference,unsignedvalueexpressionprimary

rparen ")"

standardaggregatefunction,alteroptionslist,analyticaggregatefunction,arraytable,callablestatement,columnlist,otherconstraints,createprocedure,createtablebody,createtemporarytable,filterclause,function,groupbyclause,ifstatement,jsonobject,loopstatement,makedepoptions,nestedexpression,objecttable,optionsclause,orderedaggregatefunction,simpledatatype,queryprimary,querystringfunction,inpredicate,callstatement,subquery,quantifiedcomparisonpredicate,tablesubquery,tableprimary,textaggreatefunction,texttable,unescapedFunction,whilestatement,windowspecification,withlistelement,xmlattributes,xmlelement,xmlquery,xmlforest,xmlnamespaces,xmlparse,xmlquery,xmlserialize,xmltable

rsbrace "]" datatype,valueexpressionprimary

semicolon ";" ddlstatement,delimitedstatement

slash "/" starorslash

star "*"standardaggregatefunction,dynamicdatastatement,selectclause,starorslash

stringliteral ("N"|"E")?"\'"("\'\'"|~\["\'"\])*"\'" string

unsignedintegerliteral (<digit>)+ unsignedinteger,unsignednumericliteral

BNFforSQLGrammar

649

ProductionCross-Reference

Name Usage

addsetoption alteroptionslist

standardaggregatefunction unescapedFunction

allingroup selectsublist

alter directlyexecutablestatement

altercolumnoptions alteroptions

alteroptionslist altercolumnoptions,alteroptions

alteroptions ddlstatement

analyticaggregatefunction unescapedFunction

arraytable tableprimary

assignmentstatement delimitedstatement

assignmentstatementoperand assignmentstatement,declarestatement

betweenpredicate booleanprimary

booleanprimary filterclause,booleanfactor

branchingstatement delimitedstatement

caseexpression unsignedvalueexpressionprimary

character matchpredicate,textaggreatefunction,texttable

columnlist otherconstraints,createtemporarytable,foreignkey,insertstatement,primarykey,withlistelement

commonvalueexpressionbetweenpredicate,booleanprimary,comparisonpredicate,sqlexception,matchpredicate,likeregexpredicate,inpredicate,texttable

comparisonpredicate booleanprimary

booleanterm booleanvalueexpression

booleanvalueexpression condition

compoundstatement statement,directlyexecutablestatement

otherconstraints createtablebody

BNFforSQLGrammar

650

tableelement createtablebody

createprocedure ddlstatement

typedelementlist arraytable,dynamicdatastatement

createforeigntemptable directlyexecutablestatement

optionnamespace ddlstatement

createtable ddlstatement

createtablebody createforeigntemptable,createtable

createtemporarytable directlyexecutablestatement

createtrigger ddlstatement,directlyexecutablestatement

condition expression,havingclause,ifstatement,qualifiedtable,searchedcaseexpression,whereclause,whilestatement

crossjoin joinedtable

declarestatement delimitedstatement

deletestatement assignmentstatementoperand,directlyexecutablestatement

delimitedstatement statement

derivedcolumnderivedcolumnlist,objecttable,querystringfunction,textaggreatefunction,xmlattributes,xmlquery,xmlquery,xmltable

derivedcolumnlist jsonobject,xmlforest

dropoption alteroptionslist

droptable directlyexecutablestatement

dynamicdatastatement datastatement

raiseerrorstatement delimitedstatement

sqlexception assignmentstatementoperand,exceptionreference

exceptionreference sqlexception,raisestatement

namedparameterlist callablestatement,callstatement

existspredicate booleanprimary

BNFforSQLGrammar

651

expression

standardaggregatefunction,assignmentstatementoperand,caseexpression,tableelement,derivedcolumn,dynamicdatastatement,raiseerrorstatement,namedparameterlist,expressionlist,function,nestedexpression,objecttablecolumn,orderedaggregatefunction,procedureparameter,querystringfunction,returnstatement,searchedcaseexpression,selectderivedcolumn,setclauselist,sortkey,quantifiedcomparisonpredicate,unescapedFunction,xmltablecolumn,xmlelement,xmlparse,xmlserialize

expressionlist callablestatement,otherconstraints,function,groupbyclause,queryprimary,callstatement,windowspecification

fetchclause limitclause

filterclause function,unescapedFunction

foreachrowtriggeraction alter,createtrigger

foreignkey createtablebody

fromclause query

function unescapedFunction,unsignedvalueexpressionprimary

groupbyclause query

havingclause query

identifier

alter,altercolumnoptions,alteroptions,arraytable,assignmentstatement,branchingstatement,callablestatement,columnlist,compoundstatement,tableelement,createprocedure,typedelementlist,createforeigntemptable,optionnamespace,createtable,createtablebody,createtemporarytable,createtrigger,declarestatement,deletestatement,derivedcolumn,dropoption,droptable,dynamicdatastatement,exceptionreference,namedparameterlist,foreignkey,function,ifstatement,insertstatement,intoclause,loopstatement,xmlnamespaceelement,objecttablecolumn,objecttable,optionclause,optionpair,procedureparameter,procedureresultcolumn,queryprimary,selectderivedcolumn,setclauselist,statement,callstatement,tablesubquery,temporarytableelement,textaggreatefunction,texttablecolumn,texttable,tablename,updatestatement,withlistelement,xmltablecolumn,xmlelement,xmlserialize,xmltable

ifstatement statement

insertstatement assignmentstatementoperand,directlyexecutablestatement

integerparameter fetchclause,limitclause

unsignedintegerdynamicdatastatement,integerparameter,makedepoptions,parameterreference,simpledatatype,texttablecolumn,texttable

timeinterval function

BNFforSQLGrammar

652

intoclause query

isnullpredicate booleanprimary

joinedtable tableprimary,tablereference

jsonobject function

limitclause queryexpressionbody

loopstatement statement

makedepoptions optionclause,tableprimary

matchpredicate booleanprimary

xmlnamespaceelement xmlnamespaces

nestedexpression unsignedvalueexpressionprimary

nonnumericliteral optionpair,valueexpressionprimary

non-reservedidentifier identifier,unsignedvalueexpressionprimary

booleanfactor booleanterm

objecttablecolumn objecttable

objecttable tableprimary

comparisonoperator comparisonpredicate,quantifiedcomparisonpredicate

optionclause callablestatement,deletestatement,insertstatement,queryexpressionbody,callstatement,updatestatement

optionpair addsetoption,optionsclause

optionsclause tableelement,createprocedure,createtable,createtablebody,procedureparameter,procedureresultcolumn

orderbyclause function,orderedaggregatefunction,queryexpressionbody,textaggreatefunction,windowspecification

orderedaggregatefunction unescapedFunction

parameterreference unsignedvalueexpressionprimary

datatype

tableelement,createprocedure,typedelementlist,declarestatement,function,objecttablecolumn,procedureparameter,procedureresultcolumn,temporarytableelement,texttablecolumn,unescapedFunction,xmltablecolumn

BNFforSQLGrammar

653

simpledatatype datatype

numericvalueexpression commonvalueexpression,valueexpressionprimary

plusorminus optionpair,numericvalueexpression,valueexpressionprimary

primarykey createtablebody

procedureparameter createprocedure

procedureresultcolumn createprocedure

qualifiedtable joinedtable

query queryprimary

queryexpressionalter,assignmentstatementoperand,createtable,insertstatement,loopstatement,subquery,tablesubquery,directlyexecutablestatement,withlistelement

queryexpressionbody queryexpression,queryprimary

queryprimary queryterm

querystringfunction function

queryterm queryexpressionbody

raisestatement delimitedstatement

likeregexpredicate booleanprimary

returnstatement delimitedstatement

searchedcaseexpression unsignedvalueexpressionprimary

selectclause query

selectderivedcolumn selectsublist

selectsublist selectclause

setclauselist dynamicdatastatement,updatestatement

inpredicate booleanprimary

sortkey sortspecification

sortspecification orderbyclause

datastatement delimitedstatement

BNFforSQLGrammar

654

statementalter,compoundstatement,createprocedure,foreachrowtriggeraction,ifstatement,loopstatement,procedurebodydefinition,whilestatement

callstatement assignmentstatement,subquery,tablesubquery,directlyexecutablestatement

string

character,optionnamespace,function,xmlnamespaceelement,nonnumericliteral,objecttablecolumn,objecttable,texttablecolumn,texttable,xmltablecolumn,xmlquery,xmlquery,xmlserialize,xmltable

subquery existspredicate,inpredicate,quantifiedcomparisonpredicate,unsignedvalueexpressionprimary

quantifiedcomparisonpredicate booleanprimary

tablesubquery tableprimary

temporarytableelement createtemporarytable

tableprimary crossjoin,joinedtable

tablereference fromclause,qualifiedtable

textaggreatefunction unescapedFunction

texttablecolumn texttable

texttable tableprimary

term numericvalueexpression

starorslash term

tablename tableprimary

unescapedFunction unsignedvalueexpressionprimary

unsignednumericliteral optionpair,valueexpressionprimary

unsignedvalueexpressionprimary integerparameter,valueexpressionprimary

updatestatement assignmentstatementoperand,directlyexecutablestatement

directlyexecutablestatement datastatement

valueexpressionprimary arraytable,term

whereclause deletestatement,query,updatestatement

whilestatement statement

BNFforSQLGrammar

655

windowspecification unescapedFunction

withlistelement queryexpression

xmlattributes xmlelement

xmltablecolumn xmltable

xmlelement function

xmlquery booleanprimary

xmlforest function

xmlnamespaces xmlelement,xmlquery,xmlforest,xmlquery,xmltable

xmlparse function

xmlquery function

xmlserialize function

xmltable tableprimary

Productions

string::=

<stringliteral>

Astringliteralvalue.Use''toescape'inthestring.

Example:

'astring'

'it''sastring'

non-reservedidentifier::=

INSTEAD

VIEW

ENABLED

DISABLED

KEY

SERIAL

BNFforSQLGrammar

656

TEXTAGG

COUNT

ROW_NUMBER

RANK

DENSE_RANK

SUM

AVG

MIN

MAX

EVERY

STDDEV_POP

STDDEV_SAMP

VAR_SAMP

VAR_POP

DOCUMENT

CONTENT

TRIM

EMPTY

ORDINALITY

PATH

FIRST

LAST

NEXT

SUBSTRING

EXTRACT

TO_CHARS

TO_BYTES

TIMESTAMPADD

TIMESTAMPDIFF

QUERYSTRING

NAMESPACE

RESULT

INDEX

ACCESSPATTERN

BNFforSQLGrammar

657

AUTO_INCREMENT

WELLFORMED

SQL_TSI_FRAC_SECOND

SQL_TSI_SECOND

SQL_TSI_MINUTE

SQL_TSI_HOUR

SQL_TSI_DAY

SQL_TSI_WEEK

SQL_TSI_MONTH

SQL_TSI_QUARTER

SQL_TSI_YEAR

TEXTTABLE

ARRAYTABLE

SELECTOR

SKIP

WIDTH

PASSING

NAME

ENCODING

COLUMNS

DELIMITER

QUOTE

HEADER

NULLS

OBJECTTABLE

VERSION

INCLUDING

EXCLUDING

XMLDECLARATION

VARIADIC

RAISE

EXCEPTION

CHAIN

JSONARRAY_AGG

BNFforSQLGrammar

658

JSONOBJECT

PRESERVE

Allowsnon-reservedkeywordstobeparsedasidentifiers

Example:SELECTCOUNTFROM…

identifier::=

<identifier>

<non-reservedidentifier>

Partialorfullnameofasingleentity.

Example:

tbl.col

"tbl"."col"

createtrigger::=

CREATETRIGGERON<identifier>INSTEADOF(INSERT|UPDATE|DELETE)AS<foreachrowtriggeraction>

Createsatriggeractiononthegiventarget.

Example:

CREATETRIGGERONvwINSTEADOFINSERTASFOREACHROWBEGINATOMIC...END

alter::=

ALTER((VIEW<identifier>AS<queryexpression>)|(PROCEDURE<identifier>AS<statement>)|(TRIGGERON<identifier>INSTEADOF(INSERT|UPDATE|DELETE)((AS<foreachrowtriggeraction>)|ENABLED|DISABLED)))

Alterthegiventarget.

Example:

ALTERVIEWvwASSELECTcolFROMtbl

foreachrowtriggeraction::=

FOREACHROW((BEGIN(ATOMIC)?(<statement>)*END)|<statement>)

Definesanactiontoperformoneachrow.

Example:

BNFforSQLGrammar

659

FOREACHROWBEGINATOMIC...END

directlyexecutablestatement::=

<queryexpression>

<callstatement>

<insertstatement>

<updatestatement>

<deletestatement>

<droptable>

<createtemporarytable>

<createforeigntemptable>

<alter>

<createtrigger>

<compoundstatement>

Astatementthatcanbeexecutedatruntime.

Example:

SELECT*FROMtbl

droptable::=

DROPTABLE<identifier>

Createsatriggeractiononthegiventarget.

Example:

CREATETRIGGERONvwINSTEADOFINSERTASFOREACHROWBEGINATOMIC...END

createtemporarytable::=

CREATE(LOCAL)?TEMPORARYTABLE<identifier><lparen><temporarytableelement>(<comma><temporarytableelement>)*(<comma>PRIMARYKEY<columnlist>)?<rparen>(ONCOMMITPRESERVEROWS)?

Createsatemporarytable.

Example:

CREATELOCALTEMPORARYTABLEtmp(colinteger)

BNFforSQLGrammar

660

temporarytableelement::=

<identifier>(<datatype>|SERIAL)(NOTNULL)?

Definesatemporarytablecolumn.

Example:

colstringNOTNULL

raiseerrorstatement::=

ERROR<expression>

Raisesanerrorwiththegivenmessage.

Example:

ERROR'somethingwentwrong'

raisestatement::=

RAISE(SQLWARNING)?<exceptionreference>

Raisesanerrororwarningwiththegivenmessage.

Example:

RAISESQLEXCEPTION'somethingwentwrong'

exceptionreference::=

<identifier>

<sqlexception>

areferencetoanexception

Example:

SQLEXCEPTION'somethingwentwrong'SQLSTATE'00X',2

sqlexception::=

SQLEXCEPTION<commonvalueexpression>(SQLSTATE<commonvalueexpression>(<comma><commonvalueexpression>)?)?(CHAIN<exceptionreference>)?

createsasqlexceptionorwarningwiththespecifiedmessage,state,andcode

Example:

BNFforSQLGrammar

661

SQLEXCEPTION'somethingwentwrong'SQLSTATE'00X',2

statement::=

((<identifier><colon>)?(<loopstatement>|<whilestatement>|<compoundstatement>))

<ifstatement>|<delimitedstatement>

Aprocedurestatement.

Example:

IF(x=5)BEGIN...END

delimitedstatement::=

(<assignmentstatement>|<datastatement>|<raiseerrorstatement>|<raisestatement>|<declarestatement>|<branchingstatement>|<returnstatement>)<semicolon>

Aprocedurestatementterminatedby;.

Example:

SELECT*FROMtbl;

compoundstatement::=

BEGIN((NOT)?ATOMIC)?(<statement>)*(EXCEPTION<identifier>(<statement>)*)?END

AprocedurestatementblockcontainedinBEGINEND.

Example:

BEGINNOTATOMIC...END

branchingstatement::=

((BREAK|CONTINUE)(<identifier>)?)

(LEAVE<identifier>)

Aprocedurebranchingcontrolstatement,whichtypicallyspecifiesalabeltoreturncontrolto.

Example:

BREAKx

returnstatement::=

BNFforSQLGrammar

662

RETURN(<expression>)?

Areturnstatement.

Example:

RETURN1

whilestatement::=

WHILE<lparen><condition><rparen><statement>

Aprocedurewhilestatementthatexecutesuntilitsconditionisfalse.

Example:

WHILE(var)BEGIN...END

loopstatement::=

LOOPON<lparen><queryexpression><rparen>AS<identifier><statement>

Aprocedureloopstatementthatexecutesoverthegivencursor.

Example:

LOOPON(SELECT*FROMtbl)ASxBEGIN...END

ifstatement::=

IF<lparen>((<identifier>IS(NOT)?DISTINCTFROM<identifier>)|<condition>)<rparen><statement>(ELSE<statement>)?

Aprocedureloopstatementthatexecutesoverthegivencursor.

Example:

IF(boolVal)BEGINvariables.x=1ENDELSEBEGINvariables.x=2END

declarestatement::=

DECLARE(<datatype>|EXCEPTION)<identifier>(<eq><assignmentstatementoperand>)?

Aproceduredeclarationstatementthatcreatesavariableandoptionallyassignsavalue.

Example:

DECLARESTRINGx='a'

BNFforSQLGrammar

663

assignmentstatement::=

<identifier><eq>(<assignmentstatementoperand>|(<callstatement>((WITH|WITHOUT)RETURN)?))

Assignsavariableavalueinaprocedure.

Example:

x='b'

assignmentstatementoperand::=

<insertstatement>

<updatestatement>

<deletestatement>

<expression>

<queryexpression>

<sqlexception>

Avalueorcommandthatcanbeusedinanassignment.{note}Allassigmentsexceptforexpressionaredeprecated.{note}

datastatement::=

(<directlyexecutablestatement>|<dynamicdatastatement>)((WITH|WITHOUT)RETURN)?

AprocedurestatementthatexecutesaSQLstatement.AnupdatestatementcanhaveitsupdatecountaccessedviatheROWCOUNTvariable.

procedurebodydefinition::=

(CREATE(VIRTUAL)?PROCEDURE)?<statement>

DefinesaprocedurebodyonaProceduremetadataobject.

Example:

BEGIN...END

dynamicdatastatement::=

(EXECUTE|EXEC)(STRING|IMMEDIATE)?<expression>(AS<typedelementlist>(INTO<identifier>)?)?(USING<setclauselist>)?(UPDATE(<unsignedinteger>|<star>))?

Aprocedurestatementthatcanexecutearbitrarysql.

Example:

EXECUTEIMMEDIATE'SELECT*FROMtbl'ASxSTRINGINTO#temp

BNFforSQLGrammar

664

setclauselist::=

<identifier><eq><expression>(<comma><identifier><eq><expression>)*

Alistofvalueassignments.

Example:

col1='x',col2='y'...

typedelementlist::=

<identifier><datatype>(<comma><identifier><datatype>)*

Alistoftypedelements.

Example:

col1string,col2integer...

callablestatement::=

<lbrace>(<qmark><eq>)?CALL<identifier>(<lparen>(<namedparameterlist>|(<expressionlist>)?)<rparen>)?<rbrace>(<optionclause>)?

AcallablestatementdefinedusingJDBCescapesyntax.

Example:

{?=CALLproc}

callstatement::=

((EXEC|EXECUTE|CALL)<identifier><lparen>(<namedparameterlist>|(<expressionlist>)?)<rparen>)(<optionclause>)?

Executestheprocedurewiththegivenparameters.

Example:

CALLproc('a',1)

namedparameterlist::=

(<identifier><eq>(<gt>)?<expression>(<comma><identifier><eq>(<gt>)?<expression>)*)

Alistofnamedparameters.

BNFforSQLGrammar

665

Example:

param1=>'x',param2=>1

insertstatement::=

(INSERT|MERGE)INTO<identifier>(<columnlist>)?<queryexpression>(<optionclause>)?

Insertsvaluesintothegiventarget.

Example:

INSERTINTOtbl(col1,col2)VALUES('a',1)

expressionlist::=

<expression>(<comma><expression>)*

Alistofexpressions.

Example:

col1,'a',...

updatestatement::=

UPDATE<identifier>SET<setclauselist>(<whereclause>)?(<optionclause>)?

Updatevaluesinthegiventarget.

Example:

UPDATEtblSET(col1='a')WHEREcol2=1

deletestatement::=

DELETEFROM<identifier>(<whereclause>)?(<optionclause>)?

Deleterowsfromthegiventarget.

Example:

DELETEFROMtblWHEREcol2=1

queryexpression::=

(WITH<withlistelement>(<comma><withlistelement>)*)?<queryexpressionbody>

BNFforSQLGrammar

666

Adeclarativequeryfordata.

Example:

SELECT*FROMtblWHEREcol2=1

withlistelement::=

<identifier>(<columnlist>)?AS<lparen><queryexpression><rparen>

Aqueryexpressionforuseintheenclosingquery.

Example:

X(Y,Z)AS(SELECT1,2)

queryexpressionbody::=

<queryterm>((UNION|EXCEPT)(ALL|DISTINCT)?<queryterm>)*(<orderbyclause>)?(<limitclause>)?(<optionclause>)?

Thebodyofaqueryexpression,whichcanoptionallybeorderedandlimited.

Example:

SELECT*FROMtblORDERBYcol1LIMIT1

queryterm::=

<queryprimary>(INTERSECT(ALL|DISTINCT)?<queryprimary>)*

UsedtoestablishINTERSECTprecedence.

Example:

SELECT*FROMtbl

SELECT*FROMtbl1INTERSECTSELECT*FROMtbl2

queryprimary::=

<query>

(VALUES<lparen><expressionlist><rparen>(<comma><lparen><expressionlist><rparen>)*)

(TABLE<identifier>)

(<lparen><queryexpressionbody><rparen>)

Adeclarativesourceofrows.

BNFforSQLGrammar

667

Example:

TABLEtbl

SELECT*FROMtbl1

query::=

<selectclause>(<intoclause>)?(<fromclause>(<whereclause>)?(<groupbyclause>)?(<havingclause>)?)?

ASELECTquery.

Example:

SELECTcol1,max(col2)FROMtblGROUPBYcol1

intoclause::=

INTO<identifier>

Usedtodirectthequeryintoatable.{note}Thisisdeprecated.UseINSERTINTOwithaqueryexpressioninstead.{note}

Example:

INTOtbl

selectclause::=

SELECT(ALL|DISTINCT)?(<star>|(<selectsublist>(<comma><selectsublist>)*))

Thecolumnsreturnedbyaquery.Canoptionallybedistinct.

Example:

SELECT*

SELECTDISTINCTa,b,c

selectsublist::=

<selectderivedcolumn>

<allingroup>

Anelementintheselectclause

Example:

tbl.*

BNFforSQLGrammar

668

tbl.colASx

selectderivedcolumn::=

(<expression>((AS)?<identifier>)?)

Aselectclauseitemthatselectsasinglecolumn.{note}ThisisslightlydifferentthanaderivedcolumninthattheASkeywordisoptional.{note}

Example:

tbl.colASx

derivedcolumn::=

(<expression>(AS<identifier>)?)

Anoptionallynamedexpression.

Example:

tbl.colASx

allingroup::=

<allingroupidentifier>

Aselectsublistthatcanselectallcolumnsfromthegivengroup.

Example:

tbl.*

orderedaggregatefunction::=

(XMLAGG|ARRAY_AGG|JSONARRAY_AGG)<lparen><expression>(<orderbyclause>)?<rparen>

Anaggregatefunctionthatcanoptionallybeordered.

Example:

XMLAGG(col1)ORDERBYcol2

ARRAY_AGG(col1)

BNFforSQLGrammar

669

textaggreatefunction::=

TEXTAGG<lparen>(FOR)?<derivedcolumn>(<comma><derivedcolumn>)*(DELIMITER<character>)?(QUOTE<character>)?(HEADER)?(ENCODING<identifier>)?(<orderbyclause>)?<rparen>

Anaggregatefunctionforcreatingseparatedvalueclobs.

Example:

TEXTAGG(col1ast1,col2ast2DELIMITER','HEADER)

standardaggregatefunction::=

(COUNT<lparen><star><rparen>)

((COUNT|SUM|AVG|MIN|MAX|EVERY|STDDEV_POP|STDDEV_SAMP|VAR_SAMP|VAR_POP|SOME|ANY)<lparen>(DISTINCT|ALL)?<expression><rparen>)

Astandardaggregatefunction.

Example:

COUNT(*)

analyticaggregatefunction::=

(ROW_NUMBER|RANK|DENSE_RANK)<lparen><rparen>

Ananalyticaggregatefunction.

Example:

ROW_NUMBER()

filterclause::=

FILTER<lparen>WHERE<booleanprimary><rparen>

Anaggregatefilterclauseappliedpriortoaccumulatingthevalue.

Example:

FILTER(WHEREcol1='a')

fromclause::=

FROM(<tablereference>(<comma><tablereference>)*)

Aqueryfromclausecontainingalistoftablereferences.

Example:

BNFforSQLGrammar

670

FROMa,b

FROMarightouterjoinb,c,djoine".</p>

tablereference::=

(<escapedjoin><joinedtable><rbrace>)

<joinedtable>

Anoptionallyescapedjoinedtable.

Example:

a

ainnerjoinb

joinedtable::=

<tableprimary>(<crossjoin>|<qualifiedtable>)*

Atableorjoin.

Example:

a

ainnerjoinb

crossjoin::=

((CROSS|UNION)JOIN<tableprimary>)

Acrossjoin.

Example:

aCROSSJOINb

qualifiedtable::=

(((RIGHT(OUTER)?)|(LEFT(OUTER)?)|(FULL(OUTER)?)|INNER)?JOIN<tablereference>ON<condition>)

AnINNERorOUTERjoin.

BNFforSQLGrammar

671

Example:

ainnerjoinb

tableprimary::=

(<texttable>|<arraytable>|<xmltable>|<objecttable>|<tablename>|<tablesubquery>|(<lparen><joinedtable><rparen>))((MAKEDEP<makedepoptions>)|MAKENOTDEP)?((MAKEIND<makedepoptions>))?

Asinglesourceofrows.

Example:

a

makedepoptions::=

(<lparen>(MAX<colon><unsignedinteger>)?((NO)?JOIN)?<rparen>)?

optionsforthemakedephint

Example:

(min:10000)

xmlserialize::=

XMLSERIALIZE<lparen>(DOCUMENT|CONTENT)?<expression>(AS(STRING|VARCHAR|CLOB|VARBINARY|BLOB))?(ENCODING<identifier>)?(VERSION<string>)?((INCLUDING|EXCLUDING)XMLDECLARATION)?<rparen>

SerializesanXMLvalue.

Example:

XMLSERIALIZE(col1ASCLOB)

arraytable::=

ARRAYTABLE<lparen><valueexpressionprimary>COLUMNS<typedelementlist><rparen>(AS)?<identifier>

TheARRAYTABLEtablefunctioncreatestabularresultsfromarrays.Itcanbeusedasanestedtablereference.

Example:

ARRAYTABLE(col1COLUMNSxSTRING)ASy

BNFforSQLGrammar

672

texttable::=

TEXTTABLE<lparen><commonvalueexpression>(SELECTOR<string>)?COLUMNS<texttablecolumn>(<comma><texttablecolumn>)*((NOROWDELIMITER)|(ROWDELIMITER<character>))?(DELIMITER<character>)?((ESCAPE<character>)|(QUOTE<character>))?(HEADER(<unsignedinteger>)?)?(SKIP<unsignedinteger>)?(NOTRIM)?<rparen>(AS)?<identifier>

TheTEXTTABLEtablefunctioncreatestabularresultsfromtext.Itcanbeusedasanestedtablereference.

Example:

TEXTTABLE(fileCOLUMNSxSTRING)ASy

texttablecolumn::=

<identifier>((FORORDINALITY)|((HEADER<string>)?<datatype>(WIDTH<unsignedinteger>(NOTRIM)?)?(SELECTOR<string><unsignedinteger>)?))

Atexttablecolumn.

Example:

xINTEGERWIDTH6

xmlquery::=

XMLEXISTS<lparen>(<xmlnamespaces><comma>)?<string>(PASSING<derivedcolumn>(<comma><derivedcolumn>)*)?<rparen>

ExecutesanXQuerytoreturnanXMLresult.

Example:

XMLQUERY('<a>...</a>'PASSINGdoc)

xmlquery::=

XMLQUERY<lparen>(<xmlnamespaces><comma>)?<string>(PASSING<derivedcolumn>(<comma><derivedcolumn>)*)?((NULL|EMPTY)ONEMPTY)?<rparen>

ExecutesanXQuerytoreturnanXMLresult.

Example:

XMLQUERY('<a>...</a>'PASSINGdoc)

objecttable::=

BNFforSQLGrammar

673

OBJECTTABLE<lparen>(LANGUAGE<string>)?<string>(PASSING<derivedcolumn>(<comma><derivedcolumn>)*)?COLUMNS<objecttablecolumn>(<comma><objecttablecolumn>)*<rparen>(AS)?<identifier>

Returnstableresultsbyprocessingascript.

Example:

OBJECTTABLE('z'PASSINGvalASzCOLUMNScolOBJECT'teiid_row')ASX

objecttablecolumn::=

<identifier><datatype><string>(DEFAULT<expression>)?

objecttablecolumn.

Example:

yinteger'teiid_row_number'

xmltable::=

XMLTABLE<lparen>(<xmlnamespaces><comma>)?<string>(PASSING<derivedcolumn>(<comma><derivedcolumn>)*)?(COLUMNS<xmltablecolumn>(<comma><xmltablecolumn>)*)?<rparen>(AS)?<identifier>

ReturnstableresultsbyprocessinganXQuery.

Example:

XMLTABLE('/a/b'PASSINGdocCOLUMNScolXMLPATH'.')ASX

xmltablecolumn::=

<identifier>((FORORDINALITY)|(<datatype>(DEFAULT<expression>)?(PATH<string>)?))

XMLtablecolumn.

Example:

yFORORDINALITY

unsignedinteger::=

<unsignedintegerliteral>

Anunsignedintergervalue.

Example:

12345

BNFforSQLGrammar

674

tablesubquery::=

(TABLE|LATERAL)?<lparen>(<queryexpression>|<callstatement>)<rparen>(AS)?<identifier>

Atabledefinedbyasubquery.

Example:

(SELECT*FROMtbl)ASx

tablename::=

(<identifier>((AS)?<identifier>)?)

AtablenamedintheFROMclause.

Example:

tblASx

whereclause::=

WHERE<condition>

Specifiesasearchcondition

Example:

WHEREx='a'

condition::=

<booleanvalueexpression>

Abooleanexpression.

booleanvalueexpression::=

<booleanterm>(OR<booleanterm>)*

AnoptionallyORedbooleanexpression.

booleanterm::=

<booleanfactor>(AND<booleanfactor>)*

AnoptionalANDedbooleanfactor.

BNFforSQLGrammar

675

booleanfactor::=

(NOT)?<booleanprimary>

Abooleanfactor.

Example:

NOTx='a'

booleanprimary::=

(<commonvalueexpression>(<betweenpredicate>|<matchpredicate>|<likeregexpredicate>|<inpredicate>|<isnullpredicate>|<quantifiedcomparisonpredicate>|<comparisonpredicate>)?)

<existspredicate>

<xmlquery>

Abooleanpredicateorsimpleexpression.

Example:

colLIKE'a%'

comparisonoperator::=

<eq>

<ne>

<ne2>

<lt>

<le>

<gt>

<ge>

Acomparisonoperator.

Example:

=

comparisonpredicate::=

<comparisonoperator><commonvalueexpression>

Avaluecomparison.

Example:

BNFforSQLGrammar

676

='a'

subquery::=

<lparen>(<queryexpression>|<callstatement>)<rparen>

Asubquery.

Example:

(SELECT*FROMtbl)

quantifiedcomparisonpredicate::=

<comparisonoperator>(ANY|SOME|ALL)(<subquery>|(<lparen><expression><rparen>))

Asubquerycomparison.

Example:

=ANY(SELECTcolFROMtbl)

matchpredicate::=

(NOT)?(LIKE|(SIMILARTO))<commonvalueexpression>(ESCAPE<character>|(<lbrace>ESCAPE<character><rbrace>))?

Matchesbaseduponapattern.

Example:

LIKE'a_'

likeregexpredicate::=

(NOT)?LIKE_REGEX<commonvalueexpression>

Aregularexpressionmatch.

Example:

LIKE_REGEX'a.*b'

character::=

<string>

Asinglecharacter.

BNFforSQLGrammar

677

Example:

'a'

betweenpredicate::=

(NOT)?BETWEEN<commonvalueexpression>AND<commonvalueexpression>

Acomparisonbetweentwovalues.

Example:

BETWEEN1AND5

isnullpredicate::=

IS(NOT)?NULL

Anulltest.

Example:

ISNOTNULL

inpredicate::=

(NOT)?IN(<subquery>|(<lparen><commonvalueexpression>(<comma><commonvalueexpression>)*<rparen>))

Acomparisonwithmultiplevalues.

Example:

IN(1,5)

existspredicate::=

EXISTS<subquery>

Atestifrowsexist.

Example:

EXISTS(SELECTcolFROMtbl)

groupbyclause::=

GROUPBY(ROLLUP<lparen><expressionlist><rparen>|<expressionlist>)

BNFforSQLGrammar

678

Definesthegroupingcolumns

Example:

GROUPBYcol1,col2

havingclause::=

HAVING<condition>

Searchconditionappliedaftergrouping.

Example:

HAVINGmax(col1)=5

orderbyclause::=

ORDERBY<sortspecification>(<comma><sortspecification>)*

Specificesrowordering.

Example:

ORDERBYx,yDESC

sortspecification::=

<sortkey>(ASC|DESC)?(NULLS(FIRST|LAST))?

Defineshowtosortonaparticularexpression

Example:

col1NULLSFIRST

sortkey::=

<expression>

Asortexpression.

Example:

col1

integerparameter::=

BNFforSQLGrammar

679

<unsignedinteger>

<unsignedvalueexpressionprimary>

Aliteralintegerorparameterreferencetoaninteger.

Example:

?

limitclause::=

(LIMIT<integerparameter>(<comma><integerparameter>)?)

(OFFSET<integerparameter>(ROW|ROWS)(<fetchclause>)?)

<fetchclause>

Limitsand/oroffsetstheresultantrows.

Example:

LIMIT2

fetchclause::=

FETCH(FIRST|NEXT)(<integerparameter>)?(ROW|ROWS)ONLY

ANSIlimit.

Example:

FETCHFIRST1ROWSONLY

optionclause::=

OPTION(MAKEDEP<identifier><makedepoptions>(<comma><identifier><makedepoptions>)*|MAKEIND<identifier><makedepoptions>(<comma><identifier><makedepoptions>)*|MAKENOTDEP<identifier>(<comma><identifier>)*|NOCACHE(<identifier>(<comma><identifier>)*)?)*

Specifiesqueryoptions.

Example:

OPTIONMAKEDEPtbl

expression::=

<condition>

Avalue.

BNFforSQLGrammar

680

Example:

col1

commonvalueexpression::=

(<numericvalueexpression>((<double_amp_op>|<concat_op>)<numericvalueexpression>)*)

Establishestheprecedenceofconcat.

Example:

'a'||'b'

numericvalueexpression::=

(<term>(<plusorminus><term>)*)

Example:

1+2

plusorminus::=

<plus>

<minus>

The+or-operator.

Example:

+

term::=

(<valueexpressionprimary>(<starorslash><valueexpressionprimary>)*)

Anumericterm

Example:

1*2

starorslash::=

<star>

BNFforSQLGrammar

681

<slash>

The*or/operator.

Example:

/

valueexpressionprimary::=

<nonnumericliteral>

(<plusorminus>)?(<unsignednumericliteral>|(<unsignedvalueexpressionprimary>(<lsbrace><numericvalueexpression><rsbrace>)*))

Asimplevalueexpression.

Example:

+col1

parameterreference::=

<qmark>

(<dollar><unsignedinteger>)

Aparameterreferencetobeboundlater.

Example:

?

unescapedFunction::=

((<textaggreatefunction>|<standardaggregatefunction>|<orderedaggregatefunction>)(<filterclause>)?(<windowspecification>)?)|(<analyticaggregatefunction>(<filterclause>)?<windowspecification>)|(<function>(<windowspecification>)?)

(XMLCAST<lparen><expression>AS<datatype><rparen>)

nestedexpression::=

(<lparen>(<expression>(<comma><expression>)*)?(<comma>)?<rparen>)

Anexpressionnestedinparens

Example:

(1)

BNFforSQLGrammar

682

unsignedvalueexpressionprimary::=

<parameterreference>

(<escapedfunction><function><rbrace>)

<unescapedFunction>

<identifier>|<non-reservedidentifier>

<subquery>

<nestedexpression>

<searchedcaseexpression>

<caseexpression>

Anunsignedsimplevalueexpression.

Example:

col1

windowspecification::=

OVER<lparen>(PARTITIONBY<expressionlist>)?(<orderbyclause>)?<rparen>

Thewindowspecificationforananalyticalorwindowedaggregatefunction.

Example:

OVER(PARTIONBYcol1)

caseexpression::=

CASE<expression>(WHEN<expression>THEN<expression>)+(ELSE<expression>)?END

If/then/elsechainusingacommonsearchpredicand.

Example:

CASEcol1WHEN'a'THEN1ELSE2

searchedcaseexpression::=

CASE(WHEN<condition>THEN<expression>)+(ELSE<expression>)?END

If/then/elsechainusingmultiplesearchconditions.

Example:

CASEWHENx='a'THEN1WHENy='b'THEN2

BNFforSQLGrammar

683

function::=

(CONVERT<lparen><expression><comma><datatype><rparen>)

(CAST<lparen><expression>AS<datatype><rparen>)

(SUBSTRING<lparen><expression>((FROM<expression>(FOR<expression>)?)|(<comma><expressionlist>))<rparen>)

(EXTRACT<lparen>(YEAR|MONTH|DAY|HOUR|MINUTE|SECOND)FROM<expression><rparen>)

(TRIM<lparen>((((LEADING|TRAILING|BOTH)(<expression>)?)|<expression>)FROM)?<expression><rparen>)

((TO_CHARS|TO_BYTES)<lparen><expression><comma><string>(<comma><expression>)?<rparen>)

((TIMESTAMPADD|TIMESTAMPDIFF)<lparen><timeinterval><comma><expression><comma><expression><rparen>)

<querystringfunction>

((LEFT|RIGHT|CHAR|USER|YEAR|MONTH|HOUR|MINUTE|SECOND|XMLCONCAT|XMLCOMMENT|XMLTEXT)<lparen>(<expressionlist>)?<rparen>)

((TRANSLATE|INSERT)<lparen>(<expressionlist>)?<rparen>)

<xmlparse>

<xmlelement>

(XMLPI<lparen>((NAME)?<identifier>)(<comma><expression>)?<rparen>)

<xmlforest>

<jsonobject>

<xmlserialize>

<xmlquery>

(<identifier><lparen>(ALL|DISTINCT)?(<expressionlist>)?(<orderbyclause>)?<rparen>(<filterclause>)?)

Callsascalarfunction.

Example:

func('1',col1)

xmlparse::=

XMLPARSE<lparen>(DOCUMENT|CONTENT)<expression>(WELLFORMED)?<rparen>

ParsesthegivenvalueasXML.

Example:

XMLPARSE(DOCUMENTdocWELLFORMED)

BNFforSQLGrammar

684

querystringfunction::=

QUERYSTRING<lparen><expression>(<comma><derivedcolumn>)*<rparen>

ProducesaURLquerystringfromthegivenarguments.

Example:

QUERYSTRING('path',col1ASopt,col2ASval)

xmlelement::=

XMLELEMENT<lparen>((NAME)?<identifier>)(<comma><xmlnamespaces>)?(<comma><xmlattributes>)?(<comma><expression>)*<rparen>

CreatesanXMLelement.

Example:

XMLELEMENT(NAME"root",child)

xmlattributes::=

XMLATTRIBUTES<lparen><derivedcolumn>(<comma><derivedcolumn>)*<rparen>

Createsattributesforthecontainingelement.

Example:

XMLATTRIBUTES(col1ASattr1,col2ASattr2)

jsonobject::=

JSONOBJECT<lparen><derivedcolumnlist><rparen>

ProducesaJSONobjectcontainingnamevaluepairs.

Example:

JSONOBJECT(col1ASval1,col2ASval2)

derivedcolumnlist::=

<derivedcolumn>(<comma><derivedcolumn>)*

alistofnamevaluepairs

Example:

col1ASval1,col2ASval2

BNFforSQLGrammar

685

xmlforest::=

XMLFOREST<lparen>(<xmlnamespaces><comma>)?<derivedcolumnlist><rparen>

Producesanelementforeachderivedcolumn.

Example:

XMLFOREST(col1ASELEM1,col2ASELEM2)

xmlnamespaces::=

XMLNAMESPACES<lparen><xmlnamespaceelement>(<comma><xmlnamespaceelement>)*<rparen>

DefinesXMLnamespaceURI/prefixcombinations

Example:

XMLNAMESPACES('http://foo'ASfoo)

xmlnamespaceelement::=

(<string>AS<identifier>)

(NODEFAULT)

(DEFAULT<string>)

Anxmlnamespace

Example:

NODEFAULT

simpledatatype::=

(STRING(<lparen><unsignedinteger><rparen>)?)

(VARCHAR(<lparen><unsignedinteger><rparen>)?)

BOOLEAN

BYTE

TINYINT

SHORT

SMALLINT

(CHAR(<lparen><unsignedinteger><rparen>)?)

INTEGER

BNFforSQLGrammar

686

LONG

BIGINT

(BIGINTEGER(<lparen><unsignedinteger><rparen>)?)

FLOAT

REAL

DOUBLE

(BIGDECIMAL(<lparen><unsignedinteger>(<comma><unsignedinteger>)?<rparen>)?)

(DECIMAL(<lparen><unsignedinteger>(<comma><unsignedinteger>)?<rparen>)?)

DATE

TIME

TIMESTAMP

(OBJECT(<lparen><unsignedinteger><rparen>)?)

(BLOB(<lparen><unsignedinteger><rparen>)?)

(CLOB(<lparen><unsignedinteger><rparen>)?)

(VARBINARY(<lparen><unsignedinteger><rparen>)?)

GEOMETRY

XML

Anon-collectiondatatype.

Example:

STRING

datatype::=

<simpledatatype>(<lsbrace><rsbrace>)*

Adatatype.

Example:

STRING[]

timeinterval::=

SQL_TSI_FRAC_SECOND

SQL_TSI_SECOND

SQL_TSI_MINUTE

SQL_TSI_HOUR

BNFforSQLGrammar

687

SQL_TSI_DAY

SQL_TSI_WEEK

SQL_TSI_MONTH

SQL_TSI_QUARTER

SQL_TSI_YEAR

Atimeintervalkeyword.

Example:

SQL_TSI_HOUR

nonnumericliteral::=

<string>

<binarystringliteral>

FALSE

TRUE

UNKNOWN

NULL

(<escapedtype><string><rbrace>)

((DATE|TIME|TIMESTAMP)<string>)

Anescapedorsimplenonnumericliteral.

Example:

'a'

unsignednumericliteral::=

<unsignedintegerliteral>

<approximatenumericliteral>

<decimalnumericliteral>

Anunsignednumericliteralvalue.

Example:

1.234

ddlstatement::=

BNFforSQLGrammar

688

(<createtable>|<createprocedure>|<optionnamespace>|<alteroptions>|<createtrigger>)(<semicolon>)?

Adatadefinitionstatement.

Example:

CREATEFOREIGNTABLEX(YSTRING)

optionnamespace::=

SETNAMESPACE<string>AS<identifier>

Anamespaceusedtoshortenthefullnameofanoptionkey.

Example:

SETNAMESPACE'http://foo'ASfoo

createprocedure::=

CREATE(VIRTUAL|FOREIGN)?(PROCEDURE|FUNCTION)(<identifier><lparen>(<procedureparameter>(<comma><procedureparameter>)*)?<rparen>(RETURNS(<optionsclause>)?(((TABLE)?<lparen><procedureresultcolumn>(<comma><procedureresultcolumn>)*<rparen>)|<datatype>))?(<optionsclause>)?(AS<statement>)?)

Definesaprocedureorfunctioninvocation.

Example:

CREATEFOREIGNPROCEDUREproc(paramSTRING)RETURNSSTRING

procedureparameter::=

(IN|OUT|INOUT|VARIADIC)?<identifier><datatype>(NOTNULL)?(RESULT)?(DEFAULT<expression>)?(<optionsclause>)?

Aprocedureorfunctionparameter

Example:

OUTxINTEGER

procedureresultcolumn::=

<identifier><datatype>(NOTNULL)?(<optionsclause>)?

Aprocedureresultcolumn.

Example:

BNFforSQLGrammar

689

xINTEGER

createtable::=

CREATE((FOREIGNTABLE)|((VIRTUAL)?VIEW)|(GLOBALTEMPORARYTABLE))<identifier>(<createtablebody>|(<optionsclause>)?)(AS<queryexpression>)?

Definesatableorview.

Example:

CREATEVIEWvwASSELECT1

createforeigntemptable::=

CREATE(LOCAL)?FOREIGNTEMPORARYTABLE<identifier><createtablebody>ON<identifier>

Definesaforeigntemptable

Example:

CREATEFOREIGNTEMPORARYTABLEt(xstring)ONz

createtablebody::=

<lparen><tableelement>(<comma><tableelement>)*(<comma>(CONSTRAINT<identifier>)?(<primarykey>|<otherconstraints>|<foreignkey>)(<optionsclause>)?)*<rparen>(<optionsclause>)?

Definesatable.

Example:

(xstring)OPTIONS(CARDINALITY100)

foreignkey::=

FOREIGNKEY<columnlist>REFERENCES<identifier>(<columnlist>)?

Definestheforeignkeyreferentialconstraint.

Example:

FOREIGNKEY(a,b)REFERENCEStbl(x,y)

primarykey::=

PRIMARYKEY<columnlist>

BNFforSQLGrammar

690

Definestheprimarykey.

Example:

PRIMARYKEY(a,b)

otherconstraints::=

((UNIQUE|ACCESSPATTERN)<columnlist>)

(INDEX<lparen><expressionlist><rparen>)

DefinesACCESSPATTERNandUNIQUEconstraintsandINDEXes.

Example:

UNIQUE(a)

columnlist::=

<lparen><identifier>(<comma><identifier>)*<rparen>

Alistofcolumnnames.

Example:

(a,b)

tableelement::=

<identifier>(SERIAL|(<datatype>(NOTNULL)?(AUTO_INCREMENT)?))((PRIMARYKEY)|((UNIQUE)?(INDEX)?))(DEFAULT<expression>)?(<optionsclause>)?

Definesatablecolumn.

Example:

xINTEGERNOTNULL

optionsclause::=

OPTIONS<lparen><optionpair>(<comma><optionpair>)*<rparen>

Alistofstatementoptions.

Example:

OPTIONS('x''y','a''b')

BNFforSQLGrammar

691

optionpair::=

<identifier>(<nonnumericliteral>|(<plusorminus>)?<unsignednumericliteral>)

Anoptionkey/valuepair.

Example:

'key''value'

alteroptions::=

ALTER(VIRTUAL|FOREIGN)?(TABLE|VIEW|PROCEDURE)<identifier>(<alteroptionslist>|<altercolumnoptions>)

altersoptionsoftables/procedure

Example:

ALTERFOREIGNTABLEfooOPTIONS(ADDcardinality100)

alteroptionslist::=

OPTIONS<lparen>(<addsetoption>|<dropoption>)(<comma>(<addsetoption>|<dropoption>))*<rparen>

alistofalterationstooptions

Example:

OPTIONS(ADDupdatabletrue)

dropoption::=

DROP<identifier>

dropoption

Example:

DROPupdatable

addsetoption::=

(ADD|SET)<optionpair>

addorsetanoptionpair

Example:

ADDupdatabletrue

BNFforSQLGrammar

692

altercolumnoptions::=

ALTER(COLUMN|PARAMETER)?<identifier><alteroptionslist>

altersasetofcolumnoptions

Example:

ALTERCOLUMNbarOPTIONS(ADDupdatabletrue)

BNFforSQLGrammar

693

SecurityGuideTheTeiidsystemprovidesarangeofbuilt-inandextensiblesecurityfeaturestoenablesecuredataaccess.Thisintroductionprovidesahigh-levelguidetosecurityconcerns.Therestoftheguideprovidesspecificsonconfiguringclients,theTeiidserver,andtheapplicationserver.

Authentication

ClientAuthentication

JDBC/ODBC/WebServiceclientsmayusesimplepasswordstoauthenticateauser.

Typicallyausernameisrequired,howeverusernamesmaybeconsideredoptionaliftheidentityoftheusercanbediscernedbythepasswordcredentialalone.Inanycaseitisuptotheconfiguredsecuritydomaintodeterminewhetherausercanbeauthenticated.Ifyouneedauthentication,theadministratormustconfigureLoginModulesforTeiid.

CautionBydefault,accesstoTeiidisNOTsecure.ThedefaultLoginModulesareonlybackedbyfilebasedauthentication,whichhasawellknownusernameandpassword.WeDONOTrecommendleavingthedefaultsecurityprofileasdefinedwhenyouareexposingsensitivedata.

TeiidJDBC/ODBCalsosupportsKerberosauthenticationwithadditionalconfiguration.

Auto-generatedwebservices,suchasOData,forconsumingTeiidtypicallysupportHTTPBasicauthentication,whichinturnshouldutilizePass-throughAuthentication.

SourceAuthentication

SourceauthenticationisgenerallydeterminedbythecapabilitiesofJCAresourceadaptersusedtoconnecttoexternalresources.ConsulttheASJCAdocumentationforthecapabilitiesofsourcepoolingandsuppliedresourceadaptersformoreinformation.Typicallyasingleusername/passwordcredentialissupported,suchaswhencreatingJDBCDataSources.Inmoreadvancedusagescenariosthesourceand/ortranslatormaybeconfiguredorcustomizedtouseanexecutionpayload,theTeiidsubject,oreventhecallingapplicationsubjectviaPass-throughAuthentication.SeealsoDevelopingJEEConnectorsandTranslatorDevelopment

Pass-throughAuthentication

Ifyourclientapplication(webapplicationorWebservice)residesinthesameWildFlyinstanceasTeiidandtheclientapplicationusesasecuritydomain,thenyoucanconfigureTeiidtousethesamesecuritydomainandnotforcetheusertore-authenticate.Inpass-throughmodeTeiidlooksforanauthenticatedsubjectinthecallingthreadcontextandusesitforsessioningandauthorization.ToconfigureTeiidforpass-throughauthentication,changetheTeiidsecurity-domainnametothesamenameasyourapplication’ssecuritydomainname.ThischangecanbemadeviatheCLIorinthestandalone-teiid.xmlfileifrunninginstandalonemode.ThesecuritydomainmustbeaJAASbasedLoginModuleandyourclientapplicationMUSTobtainitsTeiidconnectionusingaLocalConnectionwiththe_PassthroughAuthentication=trueconnectionflagset.Youmayalsosetthesecurity-domainontheVDB.

Authorization

Authorizationcoversbothadministrativeactivitiesanddataroles.Adataroleisacollectionofpermissions(alsoreferredtoasentitlements)andacollectionofentitledprincipalsorgroups.WiththedeploymentofaVDBthedeployercanchoosewhichprincipalsandgroupshavewhichdataroles.CheckoutReferenceGuideDataRoleschapterformoreinformation.Anysourcelevelauthorizationdecisionsareuptothesourcesystemsbeingintegrated.

SecurityGuide

694

VDBswithoutdatarolesdefinedareaccessiblebyanyauthenticateduser.Ifyouwanttoensuresomeattempthasbeenmadeatsecuringaccess,thensetthedata-roles-requiredconfigurationelementtotrueviatheCLIorinthestandalone.xmlontheteiidsubsystem.

Encryption

TeiidTransports

Teiidprovidesbuilt-insupportforJDBC/ODBCoverSSL.JDBCdefaultstojustsensitivemessageencryption(loginmode),whileODBC(thepgtransport)defaultstojustcleartextpasswordsifusingsimpleusername/passwordauthentication.

TheASinstancemustbeconfiguredforSSLaswellsothatAnywebservicesconsumingTeiidmayuseSSL.

Configuration

Passwordsinconfigurationfilesarebydefaultstoredinplaintext.Ifyouneedthesevaluestobeencrypted,pleaseseeencryptingpasswordsforinstructionsonencryptionfacilitiesprovidedbythecontainer.

SourceAccess

Encryptingremotesourceaccessistheresponsibilityfortheresourceadapterandlibrary/driverusedtoaccessthesourcesystem.

TemporaryData

TeiidtemporarydatawhichcanbestoredonthefilesystemasconfiguredbytheBufferManagermayoptionallybeencrypted.Setthebuffer-service-encrypt-filespropertytotrueontheTeiidsubsystemtouse128-bitAEStoencryptanyfileswrittenbytheBufferManager.AnewsymmetrickeywillbegeneratedforeachstartoftheTeiidsystemoneachserver.Aperformancehitwillbeseenforprocessingthatismemoryintensivesuchthatdatatypicallyspillstodisk.ThissettingdoesnotaffecthowVDBs(eithertheartifactoranexplodedform)orlogfilesarewrittentodisk.

SecurityGuide

695

http://community.jboss.org/wiki/maskingpasswordsinjbossasxmlconfiguration

LoginModules

LoginModulesareanessentialpartoftheJAASsecurityframeworkandprovideTeiidcustomizableuserauthenticationandtheabilitytoreuseexistingLoginModulesdefinedforWildFly.RefertotheWildFlysecuritydocumentationforinformationaboutconfiguringsecurityinWildFly,http://docs.jboss.org/jbossas/admindevel326/html/ch8.chapter.html.

TeiidcanbeconfiguredwithmultiplenamedapplicationpoliciesthatgrouptogetherrelevantLoginModules.Thesesecurity-domainnamescanbereferencedonapervdb.

Thesecurity-domainattributeundertheauthenticationelementinteiidsubsysteminthe<jboss-install>/standalone/configuration/standalone-teiid.xmlfileisusedsetthesecurity-domainname.Forexample,indefaultconfigurationunderteiidsubsystemyouwillfind


<transportname="jdbc"protocol="teiid"socket-binding="teiid-jdbc">

<sslmode="login"/>

</transport>

Ifnodomaincanauthenticatetheuser,theloginattemptwillfail.Detailsofthefailedattemptincludinginvalidusers,whichdomainswereconsulted,etc.willbeintheserverlogwithappropriatelevelsofseverity.

security-domaininVDB

StartingfromTeiid8.7version,aVDBcanbeconfiguredtouseaseparatesecurity-domainthansecurity-domaindefinedonthetransportthatitisbeingaccessedon.Thisconfigurationisdefinedinthevdb.xmlfile,seeVDBDefinitionformoreinformation.Thesecurity-domaindefinedontransportconfigurationwillbeusedasdefaultsecurity-domain,ifasecurity-domainisnotconfiguredforaspecificVDB.


<propertyname="security-domain"value="custom-security"/>

...

</vdb>

TipInexistinginstallationsanappropriatesecuritydomainmayalreadybeconfiguredforusebyadministrativeclients(typicallyforadmin-console).Iftheadminconnections(CLIandadminshell)arenotsecured,itisrecommendedthatyousecurethatinterfacebyexecutingadd-user.shscriptinthebin/scriptsdirectory.

Built-inLoginModules

JBossASprovidesseveralLoginModulesforcommonauthenticationneeds,suchasauthenticatingfromaTextBasedLoginModuleoraLDAPBasedLoginModule.

Youcaninstallmultipleloginmodulesaspartofsinglesecuritydomainconfigurationandconfigurethemtobepartoftheloginprocess.Forexample,forteiid-securitydomain,youcanconfigureafilebasedandalsoLDAPbasedloginmodules,andhaveyouruserauthenticatedwitheitherorbothloginmodules.Ifyouwanttowriteyourowncustomloginmodule,refertotheDeveloper’sGuideforinstructions.

Foralltheavailableloginmodulesrefertohttp://community.jboss.org/docs/DOC-11287.

RealmBasedLoginModule

LoginModules

696

http://docs.jboss.org/jbossas/admindevel326/html/ch8.chapter.html


TheRealmDirectLoginModuleutilizesaseparatelyconfiguredsecurityrealm,bydefaultApplicationRealm,toperformauthentication.ThebelowXMLfragmentunder`security'subsystemshowsarealmbasedloginmodule.


<subsystemxmlns="urn:jboss:domain:security:1.1">

<security-domains>

<security-domainname="teiid-security"cache-type="default">

<authentication>

<login-modulecode="RealmDirect"flag="required">

<module-optionname="password-stacking"value="useFirstPass"/>

</login-module>

</authentication>

</security-domain>

</security-domains>

</subsystem>

TextBasedLoginModule

Refertohttp://community.jboss.org/docs/DOC-12510.TheUsersRolesLoginModuleutilizessimpletextfilestoauthenticateusersandtodefinetheirgroups.ThebelowXMLfragmentunder`security'subsystemshowsaTextbasedloginmodule.



<security-domains>

<security-domainname="teiid-security"cache-type="default">

<authentication>

<login-modulecode="UsersRoles"flag="required">

<module-optionname="usersProperties"value="$(jboss.server.config.dir)/teiid-security-user

s.properties"/>

<module-optionname="rolesProperties"value="$(jboss.server.config.dir)/teiid-security-role

s.properties"/>

</login-module>

</authentication>

</security-domain>

</security-domains>

</subsystem>

Warning TheUsersRolesLoginModuleisnotrecommendedforproductionuseandisstronglyrecommendedthatyoureplacethisloginmodule.

Usernamesandpasswordsarestoredinthe<jboss-as>/standalone/configuration/teiid-security-users.propertiesfile.

Exampleuser.propertiesfile

#Ausers.propertiesfileforusewiththeUsersRolesLoginModule

#username=password

fred=password

george=password

...

JAASroleassignmentsarestoredinthe<jboss-as>/standalone/configuration/teiid-security-roles.propertiesfile.

Exampleuser.propertiesfile

#Aroles.propertiesfileforusewiththeUsersRolesLoginModule

LoginModules

697


#username=role1,role2,...

data_role_1=fred,sally

data_role_2=george

Userandrolenamesareentirelyuptotheneedsofthegivendeployment.ForexampleeachapplicationteamcansettheirownsecurityconstraintsfortheirVDBs,bymappingtheirVDBdatarolestoapplicationspecificJAASroles,e.g.app_role_1=user1,user2,user3.

Note TeiiddatarolesnamesareindependentofJAASroles.VDBcreatorscanchoosewhatevernametheywantfortheirdataroles,whicharethenmappedatdeploymenttimetoJAASroles.

LDAPBasedLoginModuleSeeLDAPLoginModuleconfigurationfortheAScommunityguide.Thefollowingarestreamlinedinstallationinstructions.

ConfigureLDAPauthenticationbyeditingstandalone-teiid.xmlundersecurity'subsystem.Oncethesecurity-domainisdefined,theneditthesecurity-domainattributeforTeiid’stransportforwhichyouwantusethisLDAPlogin.



<security-domains>

<security-domainname="ldap_security_domain">

<authentication>

<login-modulecode="LdapExtended"flag="required">

<module-optionname="java.naming.factory.initial"value="com.sun.jndi.ldap.LdapCtxFactory"

/>

<module-optionname="java.naming.provider.url"value="ldap://mydomain.org:389"/>

<module-optionname="java.naming.security.authentication"value="simple"/>

<module-optionname="bindDN"value="myuser"/>

<module-optionname="bindCredential"value="mypasswd"/>

<module-optionname="baseCtxDN"value="ou=People,dc=XXXX,dc=ca"/>

<module-optionname="baseFilter"value="(cn={0})"/>

<module-optionname="rolesCtxDN"value="ou=Webapp-Roles,ou=Groups,dc=XXXX,dc=ca"/>

<module-optionname="roleFilter"value="(member={1})"/>

<module-optionname="uidAttributeID"value="member"/>

<module-optionname="roleAttributeID"value="cn"/>

<module-optionname="roleAttributeIsDN"value="true"/>

<module-optionname="roleNameAttributeID"value="cn"/>

<module-optionname="roleRecursion"value="-1"/>

<module-optionname="searchScope"value="ONELEVEL_SCOPE"/>

<module-optionname="allowEmptyPasswords"value="false"/>

<module-optionname="throwValidateError"value="true"/>

</login-module>

</authentication>

</security-domain>

</security-domains>

</subsystem>

Note IfusingSSLtotheLDAPserver,ensurethattheCorporateCACertificateisaddedtotheJREtruststore.

DatabaseLoginModuleLoginmodulethatusesDatabase-basedauthentication.Refertohttp://community.jboss.org/docs/DOC-9511.

CertLoginModule

LoginModules

698



LoginmodulethatusesX509certificatebasedauthentication.Seehttp://community.jboss.org/docs/DOC-9160.

RoleMappingLoginModule

IftheLoginModuleyouareusingexposesrolenamesthatyouwishtomaptomoreapplicationspecificnames,thenyoucanusetheRoleMappingLoginModule.Thisusesapropertiesfiletoinjectadditionalrolenames,andoptionallyreplacetheexistingrole,onauthenticatedsubjects.



<security-domains>

<security-domainname="ldap_security_domain">

<authentication>

...

<login-modulecode="org.jboss.security.auth.spi.RoleMappingLoginModule"flag="optional">

<module-optionname="rolesProperties"value="${jboss-install}/standalone/configuration/role

s.properties"/>

<module-optionname="replaceRole"value="false"/>

</login-module>

...

</authentication>

</security-domain>

</security-domains>

</subsystem>

CustomLoginModules

IfyourauthenticationneedsgobeyondtheprovidedLoginModules,pleaserefertotheJAASdevelopmentguideathttp://java.sun.com/j2se/1.5.0/docs/guide/security/jaas/JAASLMDevGuide.html.Therearealsonumerousguidesavailable.

Ifyouareextendingoneofthebuilt-inLoginModules,refertohttp://community.jboss.org/docs/DOC-9466.

LoginModules

699


http://java.sun.com/j2se/1.5.0/docs/guide/security/jaas/JAASLMDevGuide.html


TeiidServerTransportSecurityTherearetwotypesofremotetransports,eachwithit’sownencryptionconfiguration:

"teiid"-Defaultstoonlyencryptlogintraffic,inwhichnoneoftheotherconfigurationpropertiesareused.

"pg"-DefaultstonoSSL

Note ThepgtransportforODBCaccessdefaultstocleartextusernamepasswordauthentication.

SSLconfigurationispartofthetransportconfigurationintheTeiidsubsystem.

EncryptionModesTeiidsupportsacoupledifferentencryptionmodesbasedonthemodeattributeonsslelement.

logIn-Thisisthedefaultsettingforthetransports.

JDBC(non-databydefault)messagesbetweenclientandserverareencryptedusing128bitAESwithaDiffie-Hellmankeythatisnegotiatedperconnection.Whenpossiblea2048bitkeyexchangewillbeusedotherwise1024bitwillbeused.Oracle/Sun1.7JREsareknownnottosupportkeylengthsover1024bits.TheconnectionpropertyencryptRequestcanbeusedtoencryptrequestsandresultsusingthesame128AESscheme.

Forthepgtransportauthenticationisexpectedtobesecure-whichcurrentlyisonlyGSSlogins.

enabled-ModetoenableSSL.ClientsarerequiredtoconnectusingSSL.

disabled-turnsoffanykindofencryption.Thisisthedefaultforthepgtransport.

SSLAuthenticationModesanonymous–Nocertificatesarerequired,butallcommunicationsarestillencryptedusingtheTLS_DH_anon_WITH_AES_128_CBC_SHASSLciphersuite.Inmostsecureintranetenvironments,anonymousissuitabletojustbulkencrypttrafficwithouttheneedtosetupSSLcertificates.Nocertificatesareexchanged,andsettingsarenotneededforthekeystoreandtruststoreproperties.JDBCClientsmusthave'org.teiid.ssl.allowAnon'settotrue(thedefault)toconnecttoananonymousserver.

Note

ODBCclientsandsomeVMs,suchasIBM,maynothavetheTLS_DH_anon_WITH_AES_128_CBC_SHAciphersuiteavailable.Whentheclientorserverlacktheanonymousciphersuite,considerusing1-waywithaself-signedcertificate.ODBCclientstypicallydonotrequireservercertificatevalidation.TeiidJDBCclientsbydefaultvalidatetheservercertificate,butcanusetheorg.teiid.ssl.trustAllpropertytoacceptanyservercertificate.

1-way–Thedefault.Onlyauthenticatestheservertotheclient.Requiresaprivatekeykeystoretobecreatedfortheserver.Iftheclientisconfiguredtovalidatetheservercertificate,theclientwillneedanappropriatetruststoreconfigured.

2-way–Mutualclientandserverauthentication.Theserverandclientapplicationseachhaveakeystorefortheirprivatekeysandeachhasatruststorethatauthenticatestheother.Theserverwillpresentacertificate,whichisobtainedfromthekeystorerelatedproperties.Theclientshouldhaveatruststoreconfiguredtoaccepttheservercertificate.Theclientisalsoexpectedtopresentacertificate,whichisobtainedfromitskeystore.Theclientcertificateshouldbeacceptedbythetruststoreconfiguredbythetruststorerelatedproperties.

Fornon-anonymousSSL,thesuiteisnegotiated-seeenabled-cipher-suitesbelowbelow.


700

http://en.wikipedia.org/wiki/Diffie-Hellman_key_exchange

DependingupontheSSLmode,followtheguidelinesofyourorganizationaroundcreating/obtainingprivatekeys.Ifyouhavenoorganizationalrequirements,thenfollowthisguidetocreateself-signedcertificateswiththeirrespectivekeystoresandtruststores.ThefollowingkeystoreandtruststorecombinationsarerequiredfordifferentSSLmodes.Thenamesofthefilescanbechosenbytheuser.Thefollowingfilesareshownforexamplepurposesonly.

1-way

1. server.keystore-hasserver’sprivatekey

2. server.truststore-hasserver’spublickey

2-way

1. server.keystore-hasserver’sprivatekey

2. server.truststore-hasserver’spublickey

3. client.keystore-client’sprivatekey

4. client.truststore-hasclient’spublickey

FullConfigurationOptions

ExampleXMLConfiguration

<sslmode="enabled"authentication-mode="1-way"ssl-protocol="TSLv1"keymanagement-algorithm="algo"

enabled-cipher-suites="SSL_RSA_WITH_RC4_128_MD5,SSL_RSA_WITH_RC4_128_SHA">

<keystorename="cert.keystore"password="passwd"type="JKS"key-alias="alias"key-password="passwd1"

/>

<truststorename="cert.truststore"password="passwd"/>

</ssl>

Properties

mode-diabled|login|enableddisabled=notransportormessagelevelsecuritywillbeused.login=onlythelogintrafficwillbeencryptedatamessagelevelusing128bitAESwithanephemeralDHkeyexchange.Onlyappliestotheteiidtransportandnootherconfigvaluesareneededinthismode.enabled=trafficwillbesecuredwithSSLusingtheotherconfigurationproperties.teiidtransportclientsmustconnectusingSSLwiththemmsprotocol.ODBC"pg"transportclientsmayoptionallyuseSSL.

ssl-protocol-TypeofSSLprotocoltobeused.Optional-bydefaultTLSv1.

Caution SSLv3isnotrecommendedduetothePOODLEsecurityvulnerability.

keystore/type-Keystoretypecreatedbythekeytool.Optional-bydefault"JKS"isused.

authentication-mode-anonymous|1-way|2-way,TypeofSSLAuthenticationMode.

keymanagement-algorithm-Typeofkeyalgorithmused.Optional-bydefaultisbasedupontheVM,e.g."SunX509"

keystore/name-Thefilenameofthekeystore,whichcontainstheprivatekeyoftheServer.ThefilenamecanberelativeresourcepathavailabletotheTeiiddeployerclassloaderoranabsolutefilesystempath.AtypicalinstallationwouldplacethekeystorefileintheconfdirectoryoftheprofilewhereTeiidisdeployedwithafilenamerelativetotheconfpath.Typicallyrequiredif1-wayor2-wayauthenticationisused.

keystore/password-passwordforthekeystore.Requiredifthekeystorehasapassword.

keystore/key-alias-Aliasnamefortheprivatekeytouse.Optional-onlyneedediftherearemultipleprivatekeysinthekeystoreandyouneedtochoosewhichonetouse.


701

keystore/key-password-Aliasnamefortheprivatekeytouse.Optional-onlyneededifthekeypasswordisdifferentthanthekeystorepassword.

truststore/name-Thisisthetruststorecontainingthepubliccertificate(s)forclientkeys.Dependinguponhowyoucreatedthekeystoreandtruststores,thismaybesamefileasdefinedunder"keystore/name"property.Requiredif"authenticationMode"is"2-way".

truststore/password-passwordforthetruststore.Requiredifthetruststorehasapassword.

truststore/check-expired-Whethertocheckforexpiredclientcertificates.Defaultfalse.

enabled-cipher-suites-Acommaseparatedlistofciphersuitesallowedforencryptionbetweenserverandclient.ThevaluesmustbevalidsupportedciphersuitesotherwiseSSLconnectionswillfail.Optional-defaultstoallsupportedciphersuitesforthevm.

Alternatively,youcanusetheCLItoaddormodifythetransportconfiguration

/subsystem=teiid/transport=jdbc:write-attribute(name=ssl-mode,value=enabled)

/subsystem=teiid/transport=jdbc:write-attribute(name=ssl-authentication-

mode,value=1-way)

/subsystem=teiid/transport=jdbc:write-attribute(name=ssl-ssl-protocol,value=TLSv1)

/subsystem=teiid/transport=jdbc:write-attribute(name=ssl-keymanagement-

algorithm,value=SunX509)

/subsystem=teiid/transport=jdbc:write-attribute(name=ssl-enabled-cipher-

suites,value="SSL_RSA_WITH_RC4_128_MD5,SSL_RSA_WITH_RC4_128_SHA")

/subsystem=teiid/transport=jdbc:write-attribute(name=keystore-name,value=ssl-

example.keystore)

/subsystem=teiid/transport=jdbc:write-attribute(name=keystore-

password,value=redhat)

/subsystem=teiid/transport=jdbc:write-attribute(name=keystore-type,value=JKS)

/subsystem=teiid/transport=jdbc:write-attribute(name=keystore-key-

alias,value=teiid)

/subsystem=teiid/transport=jdbc:write-attribute(name=keystore-key-


/subsystem=teiid/transport=jdbc:write-attribute(name=truststore-name,value=ssl-

example.truststore)

/subsystem=teiid/transport=jdbc:write-attribute(name=truststore-


NoteIfyoudonotliketoleavecleartextpasswordsintheconfigurationfile,thenyoucanuseWildFlyvaultmechanismforstoringthekeystoreandtruststorepasswords.Usethedirectionsdefinedherehttps://community.jboss.org/docs/DOC-17248

EncryptionStrengthBothanonymousSSLandloginonly(JDBCspecific)encryptionareconfiguredtouse128bitAESencryptionbydefault.Bydefault1-wayand2-waySSLallowforciphersuitenegotiationbaseduponthedefaultciphersuitessupportedbytherespectiveJavaplatformsoftheclientandserver.Userscanrestricttheciphersuitesusedbyspecifyingtheenabled-cipher-suitespropertyaboveintheSSLconfiguration.

Examples


702

https://community.jboss.org/docs/DOC-17248

1-waysslauthenticationmode


703

https://developer.jboss.org/docs/DOC-55352

JDBC/ODBCSSLconnectionusingself-signedSSLcertificatesWhenyouareoperatinginasecureenvironment,youneedtothinkaboutmutualauthenticationwiththeserveryouconnectingtoandalsoencryptallthemessagesgoingbackandforthbetweentheclientandserver.InTeiid,bothJDBCandODBCprotocolssupportSSLbasedconnections.TypicallyfordevelopmentpurposesyouwillnothaveCAsignedcertificates,andyouneedtovalidatewithself-signedcertificates.Inarticle,Iwillshowthestepstogenerateaself-signedcertificateandthenconfiguringtheminTeiid.ThenconfiguringtheJDBCandODBCclientswiththedefinedSSLcertificatestocommunicatewiththeTeiidserver.

Creatingself-signedcertificates

Ifyoudonotalreadyhaveit,downloadthe"openssl"librariesforyourenvironment.Followthebelowscriptforcreatingthecertificate(s).

CreaterootCACertificate

Tobeginwith,youneedtogeneratetherootCAkey(thisiswhatsignsallissuedcerts),makesureyougiveastrongpassphrase.

opensslgenrsa-des3-passoutpass:changeme-outrootCA.key2048

opensslrsa-passinpass:changeme-inrootCA.key-outrootCA.key

Generatetheself-signed(withthekeypreviouslygenerated)rootCAcertificate:

opensslreq-new-keyrootCA.key-outrootCA.csr

opensslreq-x509-inrootCA.csr-keyrootCA.key-days365-outrootCA.crt

YoucaninstallthisonTeiidServermachinethatwillbecommunicatingwithservicesusingSSLcertificatesgeneratedbythisrootcertificate.Typically,you’llwanttoinstallthisonalloftheserversonyourinternalnetwork.

ToworkwithTeiidserver,youneedtoimportthiscertificateintokeystore.Followthebelowsteps

opensslpkcs12-export-inrootCA.crt-inkeyrootCA.key-outrootCA.p12-noiter-

nomaciter-nameroot

keytool-importkeystore-destkeystorerootCA.keystore-srckeystorerootCA.p12-

srcstoretypepkcs12-aliasroot

GeneratingclientsidecertificatesOnceyouhavetherootCAcertificategenerated,youcanusethattogenerateadditionalSSLcertificatesforotherJDBCorODBCandforotherservices.

1-WAYSSL

For1-WAYSSL,wewouldneedtoextractrootCA’strustcertificate(publickey)andcreateakeystorewithit.


704

opensslx509-trustout-inrootCA.crt>rootCA_trust.crt

keytool-importcert-v-trustcacerts-aliasrootCA-filerootCA_trust.crt-keystore

teiid.keystore

opensslx509-inrootCA_trust.crt-outrootCA_trust.cer-outformder

Herewecreatedkeystore(teiid.keystore)thatcanbeusedwithjavabasedapplicationslikeJDBCdriver,andalsocreatedcertificate(rootCA_trust.cer)thatcanbeusedinWindowsplatform.

2-WAYSSL

for2-WAYSSL,youwouldneedananothercertificateonclientside.TocreateanSSLcertificateyoucanuseforoneofyourservices,thefirststepistocreateacertificatesigningrequest(CSR).Todothat,youneedakey(separatefromtherootCAkeyyougeneratedearlier).ThengenerateaCSR

opensslgenrsa-outteiid.key2048

opensslrsa-passinpass:changeme-inteiid.key-outteiid.key

Generatetheself-signedcertificate,andgeneratesignedcertificateusingtherootCAcertificateandkeyyougeneratedpreviously.MakesuretheCommonName(CN)issettotheFQDN,hostnameorIPaddressofthemachineyou’regoingtoputthison.

opensslreq-new-keyteiid.key-outteiid.csr

opensslx509-req-inteiid.csr-CArootCA.crt-CAkeyrootCA.key-CAcreateserial-

outteiid.crt-days365

NowyouhaveanSSLcertificate(inPEMformat)calledteiid.crtThisisthecertificateyouwantyourJDBCorODBCtouse.Importthiscertificateintoaexistingkeystoreorcreateanewoneusing

opensslpkcs12-export-inteiid.crt-inkeyteiid.key-outteiid.p12-noiter-

nomaciter-nameteiid

keytool-importkeystore-destkeystoreteiid.keystore-srckeystoreteiid.p12-

srcstoretypepkcs12-aliasteiid

keytool-importcert-filerootCA_trust.crt-keystoreteiid.keystore

Also,importtheclientcertificate’spublickeyintorootCAkeystore

opensslx509-trustout-inteiid.crt>teiid_trust.crt

keytool-importcert-fileteiid_trust.crt-keystorerootCA.keystore

Ialsofoundagreatreferencehere[1]&[2]forcertificategeneration.Noteinabovethat,IhadissueswithrecognizingthePKCS12formattedkeystoreinJavaVM,IhadtoconvertintoaJKSformat.

ConfiguringtheTeiidServerwithCertificates

InstallTeiidserverifyoudonotalreadyhaveone.

Editthestandalone-teiid.xmlfile,andfind"teiid"subsystemandinsidefindJDBCandODBCtransportsandaddasfollowing.

<transportname="jdbc"socket-binding="teiid-jdbc"protocol="teiid">


705

<sslmode="enabled"authentication-mode="1-way">

<keystorename="/path/to/rootCA.keystore"password="changeme"type="JKS"/>



</ssl>

</transport>

<transportname="odbc"socket-binding="teiid-odbc"protocol="pg">


<sslmode="enabled"authentication-mode="1-way">

<keystorename="/path/to/rootCA.keystore"password="changeme"type="JKS"/>



</ssl>

</transport>

ThenrestarttheservertostartacceptingtheconnectionsusingSSL.Nowserversetupiscomplete.

ConfiguringJDBCclienttouseSSL

WhenusingaJDBCclienttousetheSSL,copytheserver.truststorefiletothetargetmachine.OneofthemainchangeisdifferenceinJDBCconnectionURLyouneedtouse.ForexampleifyourJDBCconnectionstringis

jdbc:teiid:<vdb>:mm://<host>:31000

thenchangeitto

jdbc:teiid:<vdb>:mms://<host>:31000

note"mm[s]"torepresent[s]forsecure.Youalsoneedtoaddthefollowingsystempropertiestoyourclientfor====1-WAYSSL

-Djavax.net.ssl.trustStore=/path/to/teiid.keystore

-Djavax.net.ssl.trustStorePassword=changeme

-Djavax.net.ssl.keyStoreType=JKS

2-WAYSSL

-Djavax.net.ssl.keyStore=/path/to/teiid.keystore

-Djavax.net.ssl.keyStorePassword=changeme

-Djavax.net.ssl.trustStore=/path/to/teiid.keystore

-Djavax.net.ssl.trustStorePassword=changeme

-Djavax.net.ssl.keyStoreType=JKS

Thestartyourclientapplicationnormally,thatshouldmakesuretheSSLcertificatesusedforencryption.

ConfiguringODBCclienttouseSSL(Windows)


706

InstallthePostgresqlODBCdriverinyourWindowsmachine.Youcandownloadthedriverfromhttp://www.postgresql.org/ftp/odbc/versions/====1-WAYSSL

Copythe"rootCA.crt"and"rootCA_trust.cer"filesintoyourWindowsmachineintodirectoryc:\Users\<yourname>\AppData\Roaming\postgresql.Notethisdirectorymaybehiddenornonexistent,ifnon-existentcreateanewfolder.NotethatifyouaredealingwithCAsignedcertificate,youdonothavetoshareyourprivatecertificate"rootCA.crt".Howeversinceweareusingselfsignedthiswillbecometherootcertificate.

Rename"rootCA.crt"to"root.crt"

Rename"rootCA_trust.cer"to"postgresql.cer"

Nowopenthe"ODBCDataManager"application,createDSNfortheconnectionyouarereadytomakeusingpreviouslyinstalledPostgresODBCdriver.Providethecorrecthostnameandport(35432),anduseVDBnameasDatabasename,andselectthe"ssl-model"propertyto"verify-ca"or"verify-full"andsavetheconfiguration.

2-WAYSSL

Copythe"rootCA.crt","teiid.crt","teiid.key"filesintoyourWindowsmachineintodirectoryc:\Users\<yourname>\AppData\Roaming\postgresql.Notethisdirectorymaybehiddenornonexistent,ifnon-existentcreateanewfolder.NotethatifyouaredealingwithCAsignedcertificate,youdonothavetoshareyourprivatecertificate"rootCA.crt".Howeversinceweareusingselfsignedthiswillbecometherootcertificate.

Rename"rootCA.crt"to"root.crt"

Rename"teiid.crt"to"postgresql.crt"

Rename"teiid.key"to"postgresql.key"

Nowopenthe"ODBCDataManager"application,createDSNfortheconnectionyouarereadytomakeusingpreviouslyinstalledPostgresODBCdriver.Providethecorrecthostnameandport(35432),anduseVDBnameasDatabasename,andselectthe"ssl-model"propertyto"verify-ca"or"verify-full"andsavetheconfiguration.

NowuseanyODBCclientapplication/toollike(QTODBC)andmakeODBCconnectionusingtheDSNcreatedandstartissuingtheSQLqueries.


707

http://www.postgresql.org/ftp/odbc/versions/

SecurityattheDataSourceLevel

Insomeusecases,theusermightneedtopass-indifferentcredentialstotheirdatasourcesbasedontheloggedinuserratherthanusingthesharedcredentialsforalltheloggedusers.Tosupportthisfeature,WildFlyandTeiidprovidemultipledifferentloginmodulestobeusedinconjunctionwithTeiid’smainsecuritydomain.Seethisdocumentfordetailsonconfiguration.Notethatthebelowdirectionsneedtobeusedinconjunctionwiththisdocument.

CallerIdentity

Ifclientwantstopassinsimpletextpasswordoracertificateoracustomserializedobjectastokencredentialtothedatasource,usercanconfigure"CallerIdentity"loginmodule.Usingthisloginmodule,usercanpass-insamecredentialthatuserloggedintoTeiidsecuritydomaintothedatasource.Hereisasampleconfiguration:



<security-domains>

<security-domainname="my-security-domain">

<authentication>

<login-modulecode="RealmDirect"flag="required">


</login-module>

<login-modulecode="org.picketbox.datasource.security.CallerIdentityLoginModule"flag="required"

>


</login-module>

</authentication>

</security-domain>

</security-domains>

</subsystem>

Note

"applicability"-CallerIdentityLoginmoduleisonlyapplicablewhenloggedinsubjectcontainsthetextbasedcredentials,wherethisloginmoduleretrievesandusestheusernameandpasswordforthedatasourceauthenticationpurposes.WhenworkingwithnoncharacterbasedpasswordsusePassthoughIdentitydefinedbelow.

Inthedatasourceconfiguration,insteadofsupplyingtheuserid/paswordyouneedtoaddthefollowingelement

InJDBCDatasource

<datasourcejndi-name="java:/mysql-ds"pool-name="mysql-ds"enabled="true">

<connection-url>jdbc:mysql://localhost:3306/txns</connection-url>

<driver>mysql</driver>

<pool><allow-multiple-users/></pool>

<security>

<security-domain>my-security-domain</security-domain>

</security>

</datasource>

Note Thissecuritydomainonlyshouldbeusedasdatasourcesecuritydomains,notasgenericpurposesecuritydomain.

Inaconnectionfactoryex:ldap

<resource-adapter>

DataSourceSecurity

708


<archive>teiid-connector-ldap.rar</archive>



<connection-definitionclass-name="org.teiid.resource.adapter.ldap.LDAPManagedConnectionFactory"

jndi-name="java:/ldapDS"

enabled="true"


pool-name="ldap-ds">

<config-propertyname="LdapUrl">ldap://ldapServer:389</config-property>

<config-propertyname="LdapAdminUserDN">cn=???,ou=???,dc=???</config-property>

<config-propertyname="LdapAdminUserPassword">pass</config-property>

<config-propertyname="LdapTxnTimeoutInMillis">-1</config-property>

<security>

<security-domain>my-security-domain</security-domain>

</security>



</resource-adapter>

Intheaboveconfigurationexample,intheprimaryloginmodule“UsersRoles”issetuptoholdthepasswordsinthefile,andwhenuserlogsinwithpassword,thesameuseridandpasswordwillbealsosetontheloggedinSubjectafterauthentication.ThesecredentialscanbeextractedbythedatasourcebyaskingforSubject’sprivatecredentials.

PleasenotethatencodinganddecodingofthisobjectisstrictlyuptotheuserasWildFlyandTeiidwillonlyactasacarrieroftheinformationfromloginmoduletoconnectionfactory.UsingthisCallerIdentitymodule,theconnectionpoolfordatasourceissegmentedbySubject.

PassThroughIdentityThisoneissimilartoCallerIdentityloginmodule,wherethecallinguser’scredentialsandrolesarepassedasis.Thisisespeciallyusefulwhendealingwithnon-textbasedcredentialswhereyouwanttopassdownthepayloadasis.TheexampleiswhenkerberosloginisusedtheloggedinsubjectcontainsGSSCredentialobjectthatcontainstheGSStoken.



<security-domains>

<security-domainname="passthrough-security">

<authentication>

<login-modulecode="org.teiid.jboss.PassthroughIdentityLoginModule"flag="required"module="org

.jboss.teiid">

<module-optionname="username"value="guest"/>

<module-optionname="password"value="guest"/>

</login-module>

</authentication>

</security-domain>

</security-domains>

</subsystem>

Inthedatasourceconfiguration,insteadofsupplyingtheuserid/paswordyouneedtoaddthefollowingelement

InJDBCDatasource

<datasourcejndi-name="java:/mysql-ds"pool-name="mysql-ds"enabled="true">

<connection-url>jdbc:mysql://localhost:3306/txns</connection-url>

<driver>mysql</driver>

<pool><allow-multiple-users/></pool>

<security>

DataSourceSecurity

709

<security-domain>passthrough-security</security-domain>

</security>

</datasource>

Note Thissecuritydomainonlyshouldbeusedasdatasourcesecuritydomainsinpass-throughscenarios,notasgenericpurposesecuritydomain.

Tip

WhenworkingwithKerberos/GSSsecuritytoken(GssCredential),someJDBCdrivers(MS-SQLServer)uponcloseoftheconnectiontheyinvalidatetheGssCredentialsecuritytoken,toavoidaccidentalinvalidation,addanoptiontoabovesecurity-domain’slogin-moduleconfigurationtowrapthepassedinsecuritytokenbyaddingbelowconfiguration

<module-optionname="wrapGSSCredential"value="true"/>

TranslatorCustomizationTeiid’sextensibleTranslatorframeworkalsoprovideshooksforsecuringaccessattheDataSourcelevel.TheExecutionFactory.getConnectionmaybeoverriddentoinitializethesourceconnectioninanynumberofways,suchasre-authentication,basedupontheTeiidSubject,executionpayload,sessionvariables,andanyoftheotherrelevantinformationaccessibleviatheExecutionContextandtheCommandContext.YoumayevenalsomodifythegeneratedsourceSQLinanywaythatisseenfitintherelevantExecution.

DataSourceSecurity

710

TeiidsupportskerberosauthenticationusingGSSAPIforsinglesign-onapplications.ThisserviceticketnegotiationbasedauthenticationissupportedthroughremoteJDBC/ODBCdriversandLocalConnections.Clientconfigurationisdifferentforeachclienttype.

LocalConnection

SettheJDBCURLpropertyPassthroughAuthenticationastrueanduseJBossNegotiationforauthenticationofyourweb-applicationwithkerberos.Whenthewebapplicationauthenticateswiththeprovidedkerberostoken,thesamesubjectauthenticatedwillbeusedinTeiid.Fordetailsaboutconfiguration,checktheconfiguringtheSSOwithKerberosinEAP

ServerconfigurationforRemoteJDBC/ODBCConnections

TosupportkerberosSSOonremoteJDBCandODBCconnections,bothclientsideandserversideconfigurationsneedtobemodified.Ontheserverside,EAPneedstobeconfiguredwithtwodifferentloginmodules.ThebelowCLIscriptshowsexamplesofit.Makenecessarychangesrelatedtoyourconfigurationintermsofkeytablocations,serviceprincipaletc.

Configuresecuritydomaintorepresenttheidentityoftheserver.

Thefirstsecuritydomainauthenticatesthecontaineritselftothedirectoryservice.Itneedstousealoginmodulewhichacceptssometypeofstaticloginmechanism,becausearealuserisnotinvolved.Thisexampleusesastaticprincipalandreferencesakeytabfilewhichcontainsthecredential.

/subsystem=security/security-domain=host:add(cache-type=default)

/subsystem=security/security-domain=host/authentication=classic:add

/subsystem=security/security-domain=host/authentication=classic/login-module=Kerberos:add(code=Kerberos,flag=r

equired,

module-options=[storeKey=true,refreshKrb5Config=true,useKeyTab=true,

principal=host/testserver@MY_REALM,keyTab=/path/to/service.keytab,doNotPrompt=true,debug=false])

reload

TheabovecommandwillgenerateresultingXMLinthestandalone.xmlfileordomain.xmlfile.


<security-domainname="host">

<authentication>




<module-optionname="principal"value="host/testserver@MY_REALM"/>

<module-optionname="keyTab"value="/path/to/service.keytab"/>


<module-optionname="debug"value="false"/>

<module-optionname="refreshKrb5Config"value="true"/>

</login-module>

</authentication>

</security-domain>

ConfiguresecuritydomaintosecuretheTeiidapplication.


711

https://access.redhat.com/documentation/en/red-hat-jboss-enterprise-application-platform/7.0/how-to-set-up-sso-with-kerberos/how-to-set-up-sso-with-kerberos

ThesecondsecuritydomainisusedtoauthenticatetheindividualusertotheKerberosserver.Youneedatleastoneloginmoduletoauthenticatetheuser,andanothertosearchfortherolestoapplytotheuser.ThefollowingXMLcodeshowsanexampleSPNEGOsecuritydomain.Itincludesanauthorizationmoduletomaprolestoindividualusers.Youcanalsouseamodulewhichsearchesfortherolesontheauthenticationserveritself.Notethenameofsecurity-domainMUSTmatchrealm.ThefollowingCLIscriptshowsexampleofcreatingtheloginmodule

/subsystem=security/security-domain=MY_REALM:add(cache-type=default)

/subsystem=security/security-domain=MY_REALM/authentication=classic:add

/subsystem=security/security-domain=MY_REALM/authentication=classic/login-module=SPNEGO:add(code=SPNEGO,flag=r

equisite,

module-options=[serverSecurityDomain=host,password-stacking=useFirstPass])

/subsystem=security/security-domain=MY_REALM/authentication=classic/login-module=UserRoles:add(code=SPNEGO,fla

g=requisite,

module-options=[usersProperties=spnego-users.properties,rolesProperties=spnego-roles.properties])

reload

TheaboveCLIwillresultinfollowingresultXMLinstandalone.xmlordomain.xmldependinguponconfiguration


<security-domainname="MY_REALM">

<authentication>



<login-modulecode="SPNEGO"flag="requisite">


<module-optionname="serverSecurityDomain"value="host"/>

</login-module>



<login-modulecode="UserRoles"flag="requisite">


<module-optionname="usersProperties"value="spnego-users.properties"/>

<module-optionname="rolesProperties"value="spnego-roles.properties"/>

</login-module>

</authentication>

</security-domain>

Note

"UserRoles/Groupsassociations"Kerberosdoesnotassignanyuserrolestotheauthenticatedsubject,thatisreasonyouneedtoconfigureaseparaterolemappingmoduletoassignroles.Asanexampleintheabove,"UserRoles"login-moduleisadded.Userneedtoedit"spnego-roles.properties"fileandaddgroupsintheformatof`user@MY_REALM=my-group.CheckJBossEAPdocumentation,astoalltheavailablemappingmodulesthatareavailable.

SPENGOsecurity-domaindelegatesthecallsrelatingtoKerberostoKerberosserverbasedon"serverSecurityDomain"property.IfyouwouldlikeconfigurethechoiceofauthenticatingusingKerberosorsomeotheradditionalsecuritydomainonthesameJDBC/ODBCtransport,thenyouneedtosupplyanadditionalmoduleoption(thiscanalsobeviewedasfallbackauthenticationmodel)

<module-optionname="usernamePasswordDomain"value="{user-name-based-auth}"/>

theresultingxmlwilllooklikebelowwhere{user-name-based-auth}replacedwithaJAASbasedsimpleusername/passwordloginmodule"app-fallback"


<security-domainname="MY_REALM">

<authentication>



<login-modulecode="SPNEGO"flag="requisite">


<module-optionname="serverSecurityDomain"value="host"/>

<module-optionname="usernamePasswordDomain"value="app-fallback"/>


712

</login-module>



<login-modulecode="UserRoles"flag="requisite">


<module-optionname="usersProperties"value="spnego-users.properties"/>

<module-optionname="rolesProperties"value="spnego-roles.properties"/>

</login-module>

</authentication>

</security-domain>

<security-domainname="app-fallback"cache-type="default">

<authentication>

<login-modulecode="UsersRoles"flag="required">

<module-optionname="usersProperties"value="file:${jboss.server.config.dir}/fallback-u

sers.properties"/>

<module-optionname="rolesProperties"value="file:${jboss.server.config.dir}/fallback-r

oles.properties"/>

</login-module>

</authentication>

</security-domain>

ServerTransportConfiguration

Theaboveconfigurationdefinedsecurity-domains,beforeyoucanusethesedomainsforloginintoTeiid,theyneedtobeassociatedwithTeiid’stransportconfigurationorVDBconfiguration.Paragraphsbelowofferbothsolutions.

Defininga"default"authenticationbasedonTeiidTransport

Usercandefinea"default"authenticationpertransportasbelowthatcanbeusedforalltheVDBssystemwide.

ForJDBC:

UsebelowCLIcommandstoedittheconfiguration

----

/subsystem=teiid/transport=jdbc:write-attribute(name=authentication-security-domain,value=MY_REALM)

/subsystem=teiid/transport=jdbc:write-attribute(name=authentication-type,value=GSS)

----

Willresultinfollowingchanges(oryoucaneditthestandalone-teiid.xmlfiledirectly)

<transportname="jdbc"protocol="teiid"socket-binding="teiid-jdbc"/>

<authenticationsecurity-domain="MY_REALM"type="GSS"/>

</transport>

ForODBC:

UsebelowCLIcommandstoedittheconfiguration

----

/subsystem=teiid/transport=odbc:write-attribute(name=authentication-security-domain,value=MY_REALM)

/subsystem=teiid/transport=odbc:write-attribute(name=authentication-type,value=GSS)

----

<transportname="odbc"protocol="pg"socket-binding="teiid-odbc"/>

<authenticationsecurity-domain="MY_REALM"type="GSS"/>

</transport>

"WhatisthevalueofType"


713

The"type"attributeabovedefinesthetypeofauthenticationthatneedstobeenforcedonthetransport/vdb.Theallowedvaluesfortypeare

USERPASSWORD-onlyallowusername/passwordbasedauthentications

GSS-onlyallowGSSAPIbasedauthentication(Kerberos5).

DefiningVDBbasedauthentication

YoucanaddfollowingcombinationVDBpropertiesinthevdb.xmlfiletoselectorforcethesecurity-domainandauthenticationtype.

<propertyname="security-domain"value="MY_REALM"/>

<propertyname="gss-pattern"value="{regex}"/>

<propertyname="password-pattern"value="{regex}"/>

<propertyname="authentication-type"value="GSSorUSERPASSWORD"/>

AllthepropertiesaboveareoptionalonaVDB.IfyouwanttodefineVDBbasedsecurityconfiguration"security-domain"propertyisrequired.Ifyouwanttoenforcesingleauthenticationtypeuse"authentication-type"propertyisrequired.IfyoursecuritydomaincansupportbothGSSandUSERPASSWORD,thenyoucandefine"gss-pattern"and"password-pattern"properties,anddefinearegularexpressionasthevalue.Duringtheconnection,theseregularexpressionsarematchedagainsttheconnectinguser’snameprovidedtoselectwhichauthenticationmethoduserprefers.Forexample,iftheconfigurationisdefinedasbelow


<propertyname="gss-pattern"value="logasgss"/>

andifyoupassedthe"user=logasgss"intheconnectionstring,thenGSSauthenticationisselectedasloginauthenticationmechanism.Iftheusernamedoesnotmatch,thendefaulttransport’sauthenticationmethodisselected.Alternatively,ifyouwantchooseUSERPASSWORD


<propertyname="password-pattern"value="*-simple"/>

andiftheusernameislike"mike-simple",thenthatuserwillbesubjectedtoauthenticateagainstUSERPASSWORDbasedauthenticationdomain.Youcanconfiguredifferentsecurity-domainsfordifferentVDBS.VDBauthenticationwillnolongerbedependentuponunderlyingtransport.Ifyoulikeforce"GSS"allthetimethenuseconfigurationlikebelow


<propertyname="authentication-type"value="GSS"/>

RequiredSystemPropertiesonServer

JBossEAPofferstheabilitytoconfiguresystempropertiesrelatedtoconnectingtoKerberosservers.DependingontheKDC,KerberosDomain,andnetworkconfiguration,thebelowsystempropertiesmayormaynotberequired.

Editthe"standalone.conf"ordomain.conffileinthe"${jboss-as}/bin"directoryandaddthefollowingJVMoptions\(changingtherealmandKDCsettingsaccordingtoyourenvironment)

JAVA_OPTS="$JAVA_OPTS-Djava.security.krb5.realm=EXAMPLE.COM-

Djava.security.krb5.kdc=kerberos.example.com-

Djavax.security.auth.useSubjectCredsOnly=false"


714

or

JAVA_OPTS="$JAVA_OPTS-Djava.security.krb5.conf=/path/to/krb5.conf-

Djava.security.krb5.debug=false-Djavax.security.auth.useSubjectCredsOnly=false"

oryoucanalsoaddthesepropertiesinsidestandalone-teiid.xmlfile,rightafter\{<extensions>}segmentas

<system-properties>

<propertyname="java.security.krb5.conf"value="/pth/to/krb5.conf"/>

<propertyname="java.security.krb5.debug"value="false"/>

<propertyname="javax.security.auth.useSubjectCredsOnly"value="false"/>

</system-properties>

Thisfinishestheconfigurationontheserverside,restarttheserverandmakesuretherearenoerrorsduringstartup.

JDBCClientConfiguration

YourworkstationwheretheJDBCClientexistsmusthavebeenauthenticatedusingGSSAPIagainstActiveDirectoryorEnterprisedirectoryserver.Seethiswebsitehttp://spnego.sourceforge.netoninstructionsastohowtoverifyyoursystemisauthenticatedintoenterprisedirectoryserver.Contactyourcompany’soperationsteamifyouhaveanyquestions.

InyourclientVMtheJAASconfigurationforKerberosauthenticationneedstobewritten.Asampleconfigurationfile(client.conf)isshowbelow

"client.conf"

Teiid{

com.sun.security.auth.module.Krb5LoginModulerequired

useTicketCache=true

storeKey=true

useKeyTab=true

keyTab="/path/to/krb5.keytab"

doNotPrompt=true

debug=false

principal="[email protected]";

};

Makesureyouhaveconfiguredthe"keytab"properly,youcancheckthiswebsiteforutilitiesandinstructionstocheckyouraccesstoKDCserverandtocreatekeytabespeciallyonwindowsenvironmentshttp://spnego.sourceforge.net.ForRedhatLinuxseehttps://access.redhat.com/site/solutions/208173

AddthefollowingJVMoptionstoyourclient’sstartupscript-changeRealmandKDCsettingsaccordingtoyourenvironment

"Basedonkrb5.conffile"

-Djava.security.krb5.conf=/path/to/krb5.conf(defaultonLinux/etc/krb5.conf)

-Djava.security.auth.login.config=/path/to/client.conf

-Djavax.security.auth.useSubjectCredsOnly=false

-Dsun.security.krb5.debug=false

or

"BasedonKDCandRealmfile"

-Djava.security.krb5.realm=EXAMPLE.COM


715

http://spnego.sourceforge.net


https://access.redhat.com/site/solutions/208173

-Djava.security.krb5.kdc=kerberos.example.com

-Djavax.security.auth.useSubjectCredsOnly=false

-Dsun.security.krb5.debug=false

-Djava.security.auth.login.config=/path/to/client.conf

AddthefollowingadditionalURLconnectionpropertiestoTeiidJDBCconnectionstringalongwithURLproperty.NotethatwhenconfiguredwithKerberos,inordertoparticipateinKerberosbasedauthenticationyouneedtoconfigure"user"propertyasrequiredby"gss-pattern"ordefinethe"authentication-type"propertyontheVDBortransport.However,aftersuccessfulloginintosecurity-domain,theusernamefromGSSlogincontextwillbeusedforrepresentingthesessionintheTeiid.

jaasName=Teiid;user={pattern};kerberosServicePrincipleName=host/testserver@MY_REALM

jassNamedefinestheJAASconfigurationnameinlogin.configfile.Thispropertyisoptional,ifomittedthe"Teiid"isusedasthedefaultconfigurationname.

kerberosServicePrincipleNamedefinesserviceprinciplethatneedstoberequestedonbehalfoftheservicethatisbeingconnectedtousingtheKerberosprincipleconfigured.Ifthispropertyisomittedthedefaultserviceprinciplewouldbe"TEIID/hostname"andhostnameisderivedfromtheJDBCconnectionURL.

Note

InordertoavoidaddingtheserviceprinciplenametoallyourJDBCandODBCclients,Teiidcanusethedefaultserviceprinciplenameas"TEIID/hostname".CreatethisserviceticketinKDC.ThisalsohelpsifyoumoveyourTeiidserveronehosttoanotherbysimplycreatinganewprincipleinKDCwithnewhostname.ThenyouwouldonlyrequiredtoupdatehostnameintheURL.

ODBCClientConfiguration

CreateaDSNfortheVDBontheclientmachinetotheVDBthatyouwouldliketoconnectusingPostgreSQLODBCdriver.InordertoparticipateinKerberosbasedauthenticationyouneedtoconfigure"user"propertyasrequiredby"gss-pattern"ordefinethe"authentication-type"propertyontheVDBortransport.

Noadditionalconfigurationisneededaspartofthis,exceptthatyourworkstationwheretheODBCDSNexistsmusthavebeenauthenticatedusingGSSAPIagainstActiveDirectoryorotherEnterprisedirectoryserver.Seethiswebsitehttp://spnego.sourceforge.netoninstructionsastohowtoverifyyoursystemisauthenticatedintoenterprisedirectoryserver.Contactyourcompany’soperationsteamifyouhaveanyquestions.

ODataClient

ThedefaultODataclientisconfiguredwithHTTPBasicauthentication,toconvertthisauthenticationmethodintokerberos,cloneorcopythemavenprojectfromhttps://github.com/teiid/teiid-web-securityandthenedittheweb.xmlandjboss-web.xmlfilesandthenreplaceMY_RELAMpropertywiththepropertyofsecuritydomaincreatedabove.Oncethepropertiesareupdated,createaWARfilebyrunning

mvncleaninstall

ThiswillgenerateanewWARfilein"odata-kerberos/target"directory.Followthebelowdeploymentdirectionbasedonyourserver

CommunityTeiidServerbasedonWildFly

Replacethe<wildfly>/modules/system/layers/dv/org/jboss/teiid/main/deployments/teiid-olingo-odata4.war"filewithnewWARfile,byexecutingacommandsimilarto


716


https://github.com/teiid/teiid-web-security

{code}cpteiid-web-security/odata-kerberos/target/teiid-odata-kerberos-{version}.war<wildfly>/modules/system/layers/dv/org/jboss/teiid/main/deployments/teiid-olingo-odata4.war{code}

JDVServer

IfyouareworkingwithJDV6.3serverorgreater,thenrunthefollowingCLIscript,youmayhavechangethebelowscripttoadopttothecorrectversionoftheWARanddirectorynameswherethecontentislocated.

undeployteiid-olingo-odata4.war

deployteiid-web-security/odata-kerberos/target/teiid-odata-kerberos-{version}.war

oroverlaythenewoneusingCLIscriptlike

deployment-overlayadd--name=myOverlay--content=/WEB-INF/web.xml=teiid-web-

security/odata-kerberos/src/main/webapp/WEB-INF/web.xml,/WEB-INF/jboss-

web.xml=teiid-web-security/odata-kerberos/src/main/webapp/WEB-INF/jboss-

web.xml,/META-INF/MANIFEST.MF=teiid-web-security/odata-

kerberos/src/main/webapp/META-INF/MANIFEST.MF--deployments=teiid-olingo-odata4.war

--redeploy-affected


717

CustomAuthorizationValidatorInsituationswhereTeiid’sbuilt-inDataRolesmechanismisnotsufficient,acustomorg.teiid.PolicyDecidercanbeinstalledviaaJBossmodule.NotethataPolicyDecideronlymakeshigh-levelauthorizationdecisionsbasedupontheaccesscontext(INSERT,UPDATE,DELETE,etc.),thecaller,andtheresource(column,table/view,procedure,function,etc.).Data-levelcolumnmaskingandrowbasedsecuritypolicyinformationduetoitsinteractionwiththeTeiidplannercannotbeinjectedviaacustomorg.teiid.PolicyDecider.Youmayaddcolumnmaskingandrowbasedsecuritypermissionsviatheorg.teiid.MetadataFactoryincustomaorg.teiid.MetadataRepositoryorcustomtranslator.

Toprovideacustomauthorizationvalidator,youmustextendtheorg.teiid.PolicyDeciderinterfaceandbuildacustomjavaclass.Ifyouareusingmavenasyourbuildprocess,youcanusefollowingdependencies:

<dependencies>

<dependency>




</dependency>

<dependency>




</dependency>

</dependencies>

ThePoilcyDeciderinterfaceisloadedbytheTeiidusingtheJava’sstandardserviceloadermechanism.Forthistowork,addthefollowingnamedfileMETA-INF/services/org.teiid.PolicyDeciderwithfullnameofyourPolicyDeciderimplementationclassasitscontents.forexample:

META-INF/services/org.teiid.PolicyDecider

org.jboss.teiid.auth.MyCustomPolicyDecider

NowpackageallthesefilesintoaJARarchivefileandbuildJBossmoduleinjboss-as/modulesdirectory.IfyourPolicyDeciderhasanythirdpartydependenciesthosejarfilescanalsobeaddedasdependenciestothesamemodule.Makesureyoulistallthefilesinthemodule.xmlfile.Belowissamplemodule.xmlfilealongwithTeiidspecificdependencies

module.xml


<modulexmlns="urn:jboss:module:1.0"name="org.jboss.teiid.auth">

<resources>

<resource-rootpath="my_custom_policy.jar"/>



</resources>

<dependencies>


<modulename="org.jboss.teiid.api"/>


</dependencies>

</module>

createfolderinthe"<jboss-as>/modules/org/jboss/teiid/auth/main",copytheabovemodule.xmlfilealongwithallthejarfiles.Thisdirectorycanbedifferentifyouchoose,justmakesurethenameofthemoduleandthedirectorynamematch.


718

Afterthemodulehasbeenadded,changetheconfiguration.Editeitherthestandalone-teiid.xmlortedomain-teiid.xmlfile,andinthe"teiid"subsystemxmlfragmentaddthefollowingxmlwiththemodulenamecreated.

<policy-decider-module>name</policy-decider-module>

thenrestartthesystem.APolicyDecidermaybeconsultedmanytimesforasingleusercommand,butitisonlycalledtomakedecisionsbaseduponresourcesthatappearinuserqueries.Anyfurtheraccessofresourcesthroughviewsorstoredprocedures,justaswithdataroles,isnotcheckedagainstaPolicyDecider.


719

SAMLBasedSecurityForODataBydefaulttheODataaccesstoaVirtualDatabase(VDB)inWildFlyisrestrictedtoauthenticationusingtheHTTPBasic.However,itpossiblewithbelowinstructionsonecanconfigureODataaccesstoparticipateinaSingle-Sign-On(SSO)basedsecurityusingSAML2.ThebelowinstructionsarebasedonJBossEAPplatformusingPicketlinksecurityframework.

InSAMLbasedauthenticationthereareIdentityProviders(IDP)whoprovideauthenticationservicesandServiceProviders(SP),aenduserservicelikeodataanduser(you).ItisexpectedthatyoualreadyhaveIDP,configuredandworkingwithsecuritydomainofyourchoicelikeLDAPorKerberoesetc.TheSPinthiscaseistheODataWARfilethatissuppliedwithTeiiddistributionalongwithPicketlinkbasedframework.PicketlinkframeworkdoesnotexplicitlymentiontheinteroperabilitywithotherthirdpartyexternalvendorssuppliedIDP,butTeiidteamhastestedsuccessfullywith

Shibboleth

PicketlinkIDP

SalesforceIDP(thisisdocumentedonPicketlink,notverified)

SocialLoginswithPicketlinkIDP(like,google,facebooketc.ThishasbeenmentionedinPicketlinkdocumentationbutnotverified)

Note SinceSAML2isstandard,webelieveanystandardscomplaintIDPvendorwillworkwithPicketlinkSP.

requisites

CollectthecertificateforauthenticationthatisusedbyIDPtosigntheSAMLmessages.

GathertheSSOPOSTbasedURLforyourIDP,thatyourSPcanusetoredirectforauthenticationcall.

Note "DNSNames"-DonottrytouseIPaddressorlocalhostexceptforthetestingscenarios.ConfigureproperDNSnamesforbothIDPandSPserversandmakesurebothcanaccesseachotherusingtheURLsconfigured.

ConfigureforSAMLbasedauthenticationtheOData

Insecurity-domainsaddfollowingloginmoduleusingthefollowingCLI

/subsystem=security/security-domain=teiid-security/authentication=classic/login-

module=RealmDirect:write-attribute(name=flag,value=sufficient)


module=saml2:add(code=org.picketlink.identity.federation.bindings.jboss.auth.SAML2L

oginModule,flag=sufficient)

reload

theabovecommandswillresultinXMLinstandalone.xmlordomain.xmlfilesimilarto:

"Security-DomainforSAMLAuthentication"

<security-domainname="teiid-security">

<authentication>

<login-modulecode="org.picketlink.identity.federation.bindings.jboss.auth.SAML2LoginModule"flag="

sufficient"/>

<login-modulecode="RealmDirect"flag="sufficient">



720

</login-module>

</authentication>

</security-domain>

ModifytheODataWARFiletouseSAMLbasedauthenticationExtractthe"teiid-olingo-odata4.war"filefrom"modules/system/base/dv/org/jboss/teiid/main/deployments"toanotherlocation.TheWARfileissimpleZIPfilesoyoucan"jar-xteiid-olingo-odata4.war/modified"

Edit"WEB-INF/jboss-web.xml"file,anditshouldlooklike

"jboss-web.xml"


<jboss-web>

<context-root>odata4</context-root>

<security-domain>teiid-security</security-domain>

<valve>

<class-name>org.picketlink.identity.federation.bindings.tomcat.sp.ServiceProviderAuthenticator</class-na

me>

<param>

<param-name>configProvider</param-name>

<param-value>org.picketlink.identity.federation.web.config.SPPostMetadataConfigurationProvider</param-val

ue>

</param>

</valve>

</jboss-web>

Edit"web.xml"fileandremovethesectionbelow

"web.xml"

<login-config>

<auth-method>BASIC</auth-method>

<realm-name>yourdomain.com</realm-name>

</login-config>

AddthecertificatekeystorefromyourIDPtotheclassesdirectory.Thisis{KEYSTORE-FILE}inbelowconfiguration.oryoucanaddtoaexistingkeystoreusingfollowingcommand

keytool-import-fileidp_cert.cer-keystore\{KEYSTORE-FILE\}-alias\

{CERTIFICATE-ALIAS\}

Add"picketlink.xml"filetoWEB-INFdirectorywithfollowingcontent

"picketlink.xml"

<PicketLinkxmlns="urn:picketlink:identity-federation:config:2.1">

<PicketLinkSPxmlns="urn:picketlink:identity-federation:config:2.1"

ServerEnvironment="tomcat"BindingType="POST"SupportsSignatures="true">

<KeyProvider

ClassName="org.picketlink.identity.federation.core.impl.KeyStoreKeyManager">

<AuthKey="KeyStoreURL"Value="\{KEYSTORE-FILE\}"/>

<AuthKey="KeyStorePass"Value="\{KEYSTORE-PASSWORD\}"/>

<AuthKey="SigningKeyAlias"Value="\{CERTIFICATE-ALIAS\}"/>

<AuthKey="SigningKeyPass"Value="\{CERTIFICATE-PASSWORD\}"/>

<ValidatingAliasKey="localhost"Value="\{CERTIFICATE-ALIAS\}"/>

<ValidatingAliasKey="127.0.0.1"Value="\{CERTIFICATE-ALIAS\}"/>

</KeyProvider>

</PicketLinkSP>

<Handlersxmlns="urn:picketlink:identity-federation:handler:config:2.1">


721

<Handlerclass="org.picketlink.identity.federation.web.handlers.saml2.SAML2LogOutHandler"/>

<Handlerclass="org.picketlink.identity.federation.web.handlers.saml2.SAML2AuthenticationHandler"/>

<Handlerclass="org.picketlink.identity.federation.web.handlers.saml2.RolesGenerationHandler"/>

<Handlerclass="org.picketlink.identity.federation.web.handlers.saml2.SAML2SignatureGenerationHandler"

/>

<Handlerclass="org.picketlink.identity.federation.web.handlers.saml2.SAML2SignatureValidationHandler"

/>

</Handlers>

</PicketLink>

Note {CERTIFICATE-ALIAS}istypicallysomethinglike"idp.example.com"forwhichthecertificateiscreatedfor

AddthecertificatereceivedfromIDPvendorto"WEB-INF/classes"directory.Notethismustbesamenameas{CERTIFICATE-FILE-NAME}usedin"ConfiguringthePicketlinkSubsystem"

Add"sp-metadata.xml"totheclassesdirectory.Notethatyour"sp-metadata.xml"contentswillentirelydependentuponyourIdentityProvidersettings.ThebelowsampleONLYprovidedasanexample

"sp-metadata.xml"


<EntitiesDescriptorName="urn:mace:shibboleth:testshib:two"

xmlns:shibmd="urn:mace:shibboleth:metadata:1.0"xmlns="urn:oasis:names:tc:SAML:2.0:metadata"

xmlns:ds="http://www.w3.org/2000/09/xmldsig#"xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

<EntityDescriptorentityID="http://localhost:8080/idp-metadata/">

<IDPSSODescriptor

protocolSupportEnumeration="urn:oasis:names:tc:SAML:1.1:protocolurn:oasis:names:tc:SAML:2.0:protoc

ol">

<NameIDFormat>urn:oasis:names:tc:SAML:2.0:nameid-format:transient

</NameIDFormat>

<SingleSignOnServiceBinding="urn:mace:shibboleth:1.0:profiles:AuthnRequest"

Location="http://localhost:8080/idp-metadata/"/>

<SingleSignOnServiceBinding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"


<SingleSignOnService

Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect"


<SingleLogoutService

Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"

Location="http://localhost:8080/idp-metadata/?GLO=true"/>

<SingleLogoutService

Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect"

Location="http://localhost:8080/idp-metadata/SLO"/>

</IDPSSODescriptor>

<Organization>

<OrganizationNamexmlns="urn:oasis:names:tc:SAML:2.0:metadata"

xml:lang="en">JBoss</OrganizationName>

<OrganizationDisplayNamexmlns="urn:oasis:names:tc:SAML:2.0:metadata"

xml:lang="en">JBossbyRedHat</OrganizationDisplayName>

<OrganizationURLxmlns="urn:oasis:names:tc:SAML:2.0:metadata"

xml:lang="en">http://www.jboss.org</OrganizationURL>

</Organization>

<ContactPersoncontactType="technical">

<GivenName>The</GivenName>

<SurName>Admin</SurName>

<EmailAddress>[email protected]</EmailAddress>

</ContactPerson>

</EntityDescriptor>

<EntityDescriptorentityID="http://localhost:8080/odata4/">

<SPSSODescriptor

protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocolurn:oasis:names:tc:SAML:1.1:protoc

olhttp://schemas.xmlsoap.org/ws/2003/07/secext">

<NameIDFormat>urn:oasis:names:tc:SAML:2.0:nameid-format:transient

</NameIDFormat>

<AssertionConsumerService

Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"Location="http://localhost:8080/odata4

/"


722

index="1"isDefault="true"/>

</SPSSODescriptor>

<Organization>

<OrganizationNamexmlns="urn:oasis:names:tc:SAML:2.0:metadata"

xml:lang="en">JBoss</OrganizationName>

<OrganizationDisplayNamexmlns="urn:oasis:names:tc:SAML:2.0:metadata"

xml:lang="en">JBossbyRedHat</OrganizationDisplayName>

<OrganizationURLxmlns="urn:oasis:names:tc:SAML:2.0:metadata"

xml:lang="en">http://localhost:8080/odata4/</OrganizationURL>

</Organization>

<ContactPersoncontactType="technical">

<GivenName>The</GivenName>

<SurName>Admin</SurName>

<EmailAddress>[email protected]</EmailAddress>

</ContactPerson>

</EntityDescriptor>

</EntitiesDescriptor>

Createadeployment-overlayusingthecliwiththemodifiedcontents:

deployment-overlayadd--name=myOverlay--content=/WEB-INF/web.xml=/modified/web.xml,/WEB-INF/jboss-web.xml=/mo

dified/jboss-web.xml--deployments=teiid-odata-odata4.war--redeploy-affected


723


ThisdocumentwillprovidedetailedinstructionstoenableOAuthV2authenticationonTeiid’sODatainterfaceusingtheKeycloakasauthenticationserver(IDP).PleasenotethatuseadifferentIDPserverwillnotworkwiththisimplementaionasOAuthimplementionsarenotinteroperable.ToworkwithseparateIDPthanKeycloakconsulttheirdocumentation,replacetheweblayersemantics,likethe"login-config"inweb.xmlfileetc.ProvidingthedetailsofotherIDPisbeyondthescopeofthisdocument.

Thisexampleswillshowcaseanexample,whereTeiid’sODatarestinterfaceissecuredusingOAuthusingKeycloakasIDP.TheVDBaccessedbytheODatainterfacealsodependsonanotherwebservicewhichisusedasadatasource,thatisalsosecuredwithOAuthusingthesameKeycloakIDP.Thecentralideabehindthisexampleistopassthesame"access-token"usedatODatainterfacelayertopassthroughtheTeiidlayertobottomdatasourcelayerandgainaccesstothesource.

DownloadandinstallKeycloakasaseparatewebserver.

Loginusingthedefault"admin/admin"credentialsintotheKeycloak"master"realm.

Addanewrealmcalled"oauth-demo"

Addanewusercalled"user"andaddcredentials.

Addtworoles"odata"and"user".Theseareenterpriseroles,thatwillbeusedbythewebservicestogranttheaccesstouser.Alsotheserolesareusedas"scopes"intheOAuthprotocol.


724

Addanewclientcalled"odata4-oauth",thisclientrepresentstheTeiid’sODataclientthatwearegoingtocreate

andchoosescopes"odata"and"user"forthisclient.NotethattheredirectURIneedstobewheretheactualserviceisgoingtobeavailable.

Note

Theclientweb-servicetypicallydefineswhatrolesthatloggedinusermusthaveinorderfortogranttheaccess.IntheKeycloakOAuthimplementation,theserolesareusedas"scopes".Notethatthe"odata4-oauth"clientMUSThaveALLthescopesthatitisgoingtodelegatetheaccess-tokenforgainingaccesstobottomdataservices.InthisexampleTeiid’sODatawebservicesrequires"odata"role,thebottomweb-servicerequiresthe"user"role.SincetheODataaccessesthebottomweb-serviceitrequiresboththeroles.


725

Addanotherclientcalled"database-service"andchoosescope"user".Choosetypeas"Bearer".

InstallandconfigureTeiidserver

DownloadandinstallTeiidserver

DownloadKeycloakadapterfortheEAP,andunzipovertheTeiidserverinstallation

DownloadKeycloakSAMLadapterforEAP,andunzipovertheTeiidserverinstallation.(optionalbutneedforanotherexercise)

Editthestandalone-teiid.xml,addthefollowingsections

RunthefollowingCLItoaddKeycloakspecificmodulestotheserver


726

/extension=org.keycloak.keycloak-saml-adapter-subsystem:add(module=org.keycloak.keycloak-saml-adapter-subsystem

)

/extension=org.keycloak.keycloak-adapter-subsystem:add(module=org.keycloak.keycloak-adapter-subsystem)

abovecommandswillresultinXMLinstandalone.xmlordomain.xmlfilelike

<extensionmodule="org.keycloak.keycloak-saml-adapter-subsystem"/>

<extensionmodule="org.keycloak.keycloak-adapter-subsystem"/>

Addthesetwosubsystemsanywhereinthefile,usethefollowingtheCLIscript

/subsystem=keycloak:add

/subsystem=keycloak-saml:add


<subsystemxmlns="urn:jboss:domain:keycloak-saml:1.1"/>

<subsystemxmlns="urn:jboss:domain:keycloak:1.1"/>

Insecurity-domainsaddfollowingsecuritydomainsusingthefollowingCLI

/subsystem=security/security-domain=oauth:add(cache-type=default)

/subsystem=security/security-domain=oauth/authentication=classic:add

/subsystem=security/security-domain=oauth/authentication=classic/login-

module=oauth:add(code=org.teiid.jboss.PassthroughIdentityLoginModule,

flag=required,module=org.jboss.teiid)

/subsystem=security/security-domain=keycloak:add(cache-type=default)

/subsystem=security/security-domain=keycloak/authentication=classic:add

/subsystem=security/security-domain=keycloak/authentication=classic/login-

module=keycloak:add(code=org.keycloak.adapters.jboss.KeycloakLoginModule,

flag=required)

reload

abovecommandswillresultinXMLinstandalone.xmlordomain.xmlfilelike(youcanalsoeditstandalone.xmldirectly)

<security-domainname="oauth">

<authentication>

<login-modulecode="org.teiid.jboss.PassthroughIdentityLoginModule"flag="required"module="org.jbo

ss.teiid"/>

</authentication>

</security-domain>

<security-domainname="keycloak">

<authentication>

<login-modulecode="org.keycloak.adapters.jboss.KeycloakLoginModule"flag="required"/>

</authentication>

</security-domain>

UnderTeiidsubsystem,changethe"security-domain"ofthe"odata"transport,to

/subsystem=teiid/transport=odata:write-attribute(name=authentication-security-domain,value=oauth)


727

resultsinXML

<transportname="odata">

<authenticationsecurity-domain="oauth"/>

</transport>

ThisfinishesalltheserversidechangesthatarerequiredtomakeOAuthauthenticationusingKeycloak.

ODataApplicationWARInordertouseOAuthauthentication,theODataWARneedstobeupdatedtomakeuseoftheOAuthbasedsecuritydomain.BydefaultTeiidinstallationcomeswithODatawebserviceWARfileconfiguredwith"HTTPBasic"authentication.ThisWARneedstoeitherreplacedorupdated.

BuildthenewODataWARfilethatsupportsOAuth.

TobuildOAuthbasedODataWARfile,Teiidprovidesatemplatemavenproject,eitherdownloadorclonetheprojectfromhttps://github.com/teiid/teiid-web-security

TheabovelinkprovidestemplatesforcreatingtwoWARfiles,oneWARfileistocreateTeiid’sODataservicewithOAuth,thenextisasample"database-service"forthisdemo.Pleasenotethat"database-service"istomimicthedatabaseservice,thatwillbedifferentinarealuse-case,howeverthestepsdefinedfortheaccesswillbesame.

Replacethe"teiid-web-security/teiid-odata-oauth-keycloak/src/main/webapp/WEB-INF/keyclock.json"filecontentswith"installation"scriptin"keycloak.json"formatfromKeycloakadminconsole’s"odata4-client"clientapplication.

Similarlyreplacethe"teiid-web-security/examples/database-service/src/main/webapp/WEB-INF/keyclock.json"filecontentswith"installation"scriptin"keycloak.json"formatfromKeycloakadminconsole’s"database-client"clientapplication.

tobuildtheWARfilesrunningthemavencommand

mvncleanpackage

TheabovecommandwillgenerateanewWARfilefordeployment.FollowthebelowdirectionstodeploythisnewWARfile.

TeiidServeronWildFly


{code}cpteiid-web-security/odata-oauth-keycloak/target/teiid-odata-oauth-keycloak-{version}.war<wildfly>/modules/system/layers/dv/org/jboss/teiid/main/deployments/teiid-olingo-odata4.war{code}

JDVServer



deployteiid-web-security/odata-oauth-keycloak/target/teiid-odata-oauth-keycloak-

{version}.war



728



security/odata-oauth-keycloak/src/main/webapp/WEB-INF/web.xml,/WEB-INF/jboss-

web.xml=teiid-web-security/odata-oauth-keycloak/src/main/webapp/WEB-INF/jboss-

web.xml,/META-INF/MANIFEST.MF=teiid-web-security/odata-oauth-

keycloak/src/main/webapp/META-INF/MANIFEST.MF,/WEB-INF/keycloak.json=teiid-web-

security/odata-oauth-keycloak/src/main/webapp/WEB-INF/keycloak.json/WEB-

INF/lib/teiid-odata-oauth-keycloak-{version}.jar=teiid-web-security/odata-oauth-

keycloak/src/main/webapp/WEB-INF/lib/teiid-odata-oauth-keycloak-{version}.jar--

deployments=teiid-olingo-odata4.war--redeploy-affected

WorkingwithexampleVDB

Editthestandalone-teiid.xmlandunderresource-adapterssubsystem,addthefollowingtoaddaccesstoadatabase-servicefromtheTeiidqueryengine.

<resource-adapterid="database">




<connection-definitionclass-name="org.teiid.resource.adapter.ws.WSManagedConnectionFactory"

jndi-name="java:/database"enabled="true"use-java-context="true"

pool-name="teiid-database-ds">

<config-propertyname="SecurityType">

OAuth

</config-property>


http://localhost:8180/database/

</config-property>

<security>

<security-domain>oauth</security-domain>

</security>



</resource-adapter>

AddaVDBwithfollowingcontents(oauthdemo-vdb.xml)

<vdbname="oauthdemo"version="1">

<modelvisible="true"name="PM1">

<sourcename="array"translator-name="loopback"/>


CREATEFOREIGNTABLEG1(e1integerPRIMARYKEY,e2varchar(25),e3double);

]]>

</metadata>

</model>

<modelname="view"type="VIRTUAL">


createviewmessage(msgtostringprimarykey,msgfromstring,headingstring,bodystring)

as

SELECTA.msgto,A.msgfrom,A.heading,A.body

FROM

(EXECrestsvc.invokeHttp(action=>'GET',endpoint=>'sample',stream=>'TRUE'))ASf,

XMLTABLE('/note'PASSINGXMLPARSE(DOCUMENTf.result)COLUMNS

msgtostringPATH'to',

msgfromstringPATH'from',

headingstringPATH'heading',

bodystringPATH'body')ASA;

]]>

</metadata>

</model>


729

<modelname="restsvc"type="PHYSICAL"visible="true">

<propertyname="importer.importWSDL"value="false"/>

<sourcename="restsvc"translator-name="ws"connection-jndi-name="java:/database"/>

</model>

</vdb>

StartbothKeycloakandTeiidServers.Ifbothoftheseserversareinthesamemachine,thenweneedtooffsettheportsofTeiidserversuchthattheywillnotconflictwiththatoftheKeycloakserver.Forthisexample,IstartedtheTeiidserveras

./standalone.sh-cstandalone-teiid.xml-Djboss.socket.binding.port-offset=100

whereallportsareoffsetby100.Sothemanagementportis10090anddefaultJDBCportwillbe31100.TheKeycloakserverisstartedondefaultports.

Testingtheexample

Therearetwodifferentmechanismsfortestingthisexample.Oneispurelyfortestingtheusingthebrowser,thenotherisprogramatically.TypicallyusingthebrowserisNOTcorrectforaccessingtheTeiid’sODataservice,butitisshownbelowfortestingpurposes.

UsingtheWebBrowser

Usingthebrowserissueaquery(theuseofbrowserisneededbecause,thisprocessdoesfewredirectsonlybrowserscanautomaticallyfollow)

http://localhost:8180/odata4/kerberos/auth

thenyoushouldseeamessagelike"Congratulations!!!Loginsuccessful..".Whatthisprocessisdoingisnegotiatinga"access-token"fromtheKeycloakauthenticationserverandplacesthisintheclient’sweb-session,suchthatsubsequentcallstotheserviceusethistokenforaccess.

Nowtofetchthedatafromthe"database-service"usingthenegotiated"access-token"issueaquery

http://localhost:8180/odata4/oauthdemo/view/message

Ifalltheconfigurationissetupcorrectly,thenyouwillseetheresponselikebelow.

<?xmlversion='1.0'encoding='UTF-8'?>

<a:feedxmlns:a="http://www.w3.org/2005/Atom"xmlns:m="http://docs.oasis-open.org/odata/ns/metadata"

xmlns:d="http://docs.oasis-open.org/odata/ns/data"m:context="$metadata#mesage">

<a:id>http://localhost:8180/odata4/saml.1/RestViewModel/mesage</a:id>

<a:entry>

<a:id>mesage('Tove')</a:id>

<a:title/>

<a:summary/>

<a:updated>2016-01-18T20:10:48Z</a:updated>

<a:author>

<a:name/>

</a:author>

<a:linkrel="edit"href="mesage('Tove')"/>

<a:categoryscheme="http://docs.oasis-open.org/odata/ns/scheme"

term="#saml.1.RestViewModel.mesage"/>

<a:contenttype="application/xml">

<m:properties>

<d:msgto>Tove</d:msgto>

<d:msgfrom>Jani</d:msgfrom>


730

<d:heading>Reminder</d:heading>

<d:body>Don'tforgetmethisweekend!</d:body>

</m:properties>

</a:content>

</a:entry>

</a:feed>

Warning Whenabovemethodisusedtocaptureaccesstoken,itispossiblethattheaccesstokengetsexpiredafteritslifespan,inthatsituationanewaccesstokenneedstobenegotiated.

Callingprogramatically

Thisprocessofcallingdoesnotneedtoinvolveaweb-browser,thisistypicalofscenariowhereanotherweb-applicationormobileapplicationiscallingtheTeiid’sODataweb-servicetoretrievethedata.Howeverinthisprocess,theprocessofnegotiatingthe"access-token"isexternalizedandisdefinedbytheIDP,whichinthiscaseisKeycloak.

FordemonstrationpurposeswecanuseCURLtonegotiatethistokenasshownbelow(client_secretcanfoundtheKeycloakadminconsoleunderclientcredentialstab)

curl-vPOSThttp://localhost:8080/auth/realms/oauth-demo/protocol/openid-connect/token-H"Content-Type:appl

ication/x-www-form-urlencoded"-d'username=user'-d'password=user'-d'grant_type=password'-d'client_id=oda

ta4-oauth'-d'client_secret=36fdc2b9-d2d3-48df-8eea-99c0e729f525'

thisshouldreturnaJSONpayloadsimilarto

{"access_token":"eyJhbGciOiJSUzI1NiJ9.eyJqdGkiOiI0YjI4NDMzYS1..",

"expires_in":300,

"refresh_expires_in":1800,

"refresh_token":"eyJhbGciOiJSUzI1NiJ9.eyJqdGkiOiJmY2JmNjY2ZC0xNzIwLTQwODQtOTBiMi0wMjg4ODdhNDkyZWYiLCJl..",

"token_type":"bearer",

"id_token":"eyJhbGciOiJSUzI1NiJ9.eyJqdGkiOiIwZjYyNDQ1MS1iNTE0LTQ5YjUtODZlNy1jNTI5MDU2OTI3ZDIiLCJleH..",

"not-before-policy":0,

"session-state":"6c8884e8-c5aa-4f7a-a3fe-9a7f6c32658c"

}

fromtheaboveyoucantakethe"access_token"andissuethequerytofetchresultslike

curl-k-H"Authorization:BearereyJhbGciOiJSUzI1NiJ9.eyJqdGkiOiI0YjI4NDMzYS1.."http://localhost:8180/odata4/

oauthdemo/view/message

YoushouldseesameXMLresponseasabove.Pleasenotethattoprogramaticallyachievetheaccess_tokeninyourownprogram(notusingcurl)youcanseesomesuggestionsinthisdocument[http://keycloak.github.io/docs/userguide/keycloak-server/html/direct-access-grants.html]


731

http://keycloak.github.io/docs/userguide/keycloak-server/html/direct-access-grants.html

ThisdocumentwillprovidedetailedinstructionstoenableSAMLauthenticationonTeiid’sODatainterfaceusingtheKeycloakasauthenticationserver(IDP).SAMLisstandard,sothemodifiedODataWARshouldworkfinewithanyothercompatibleSAMLAuthorizationserver,howevertheconfigurationmaybelittledifferent.PleaseconsulttheirdocumentationforanysuchspecificsofdifferentauthorizationserverotherthenKeyCloak.

Thisexampleswillshowcaseanexample,whereTeiid’sODatarestinterfaceissecuredusingSAMLusingKeycloakasIDP.TheVDBaccessedbytheODatainterface,thepass-throughofSAMLAssertionforOAuthtoken(SAMLBearer)isnotyetavailableinKeyCloak,whenthefeatureisavailablethenTeiidwillsupportit.However,ifyouareworkingwithaIDPthatsupportstheSAMLBearer,Teiiddoessupportthemechanismwhereonecanpassthe"access-token"fromweblayertothedatasourcelayer.SeetheOAuthexampleastemplateandpossibleconfigurationneeded.(noteitisnotexactlysame,butverysimilar)

DownloadandinstallKeycloakasaseparatewebserver.

Loginusingthedefault"admin/admin"credentialsintotheKeycloak"master"realm.

Addanewrealmcalled"oauth-demo"

Addanewusercalled"user"andaddcredentials.

Addtworoles"odata"and"user".Theseareenterpriseroles,thatwillbeusedbythewebservicestogranttheaccesstouser.Alsotheserolesareusedas"scopes"intheOAuthprotocol.


732

Addanewclientcalled"odata4-saml",thisclientrepresentstheTeiid’sSAMLclientthatwearegoingtocreate

ClickonSAMLKeys,eitherimportyourcertificateorgenerateanewone.Thenclickexport,andkeeptheexportedcertificateforlateruse.


733

InstallandconfigureTeiidserver

DownloadandinstallTeiidserver

DownloadKeycloakadapterfortheEAP,andunzipovertheTeiidserverinstallation

DownloadKeycloakSAMLadapterforEAP,andunzipovertheTeiidserverinstallation.(optionalbutneedforanotherexercise)

Editthestandalone-teiid.xml,addthefollowingsections

RunthefollowingCLItoaddKeycloakspecificmodulestotheserver

/extension=org.keycloak.keycloak-saml-adapter-

subsystem:add(module=org.keycloak.keycloak-saml-adapter-subsystem)

/extension=org.keycloak.keycloak-adapter-

subsystem:add(module=org.keycloak.keycloak-adapter-subsystem)


<extensionmodule="org.keycloak.keycloak-saml-adapter-subsystem"/>

<extensionmodule="org.keycloak.keycloak-adapter-subsystem"/>

Addthesetwosubsystemsanywhereinthefile,usethefollowingtheCLIscript

/subsystem=keycloak:add

/subsystem=keycloak-saml:add


<subsystemxmlns="urn:jboss:domain:keycloak-saml:1.1"/>

<subsystemxmlns="urn:jboss:domain:keycloak:1.1"/>


734

Insecurity-domainsaddfollowingloginmoduleusingthefollowingCLI

subsystem=security/security-domain=teiid-security/authentication=classic/login-

module=RealmDirect:write-attribute(name=flag,value=sufficient)


module=keycloak:add(code=org.keycloak.adapters.jboss.KeycloakLoginModule,

flag=sufficient)

reload

theabovecommandswillresultinXMLinstandalone.xmlordomain.xmlfilelikesimilarto:

<security-domainname="teiid-security">

<authentication>

<login-modulecode="org.keycloak.adapters.jboss.KeycloakLoginModule"flag="sufficient"/>

<login-modulecode="RealmDirect"flag="sufficient">


</login-module>

</authentication>

</security-domain>

ThisfinishesalltheserversidechangesthatarerequiredtomakeOAuthauthenticationusingKeycloak.

ODataApplicationWAR

InordertouseOAuthauthentication,theODataWARneedstobeupdatedtomakeuseoftheOAuthbasedsecuritydomain.BydefaultTeiidinstallationcomeswithODatawebserviceWARfileconfiguredwith"HTTPBasic"authentication.ThisWARneedstoeitherreplacedorupdated.

BuildthenewODataWARfilethatsupportsSAML.

TobuildSAMLbasedODataWARfile,Teiidprovidesatemplatemavenproject,eitherdownloadorclonetheprojectfromhttps://github.com/teiid/teiid-web-security

TheabovelinkprovidestemplatesforcreatingtwoWARfiles,oneWARfileistocreateTeiid’sODataservicewithOAuth,thenextisforSAML.ChoosetheSAMLone.

Replacethe"teiid-web-security/teiid-odata-saml-keycloak/src/main/webapp/WEB-INF/keyclock.json"filecontentswith"installation"scriptin"keycloak.json"formatfromKeycloakadminconsole’s"odata4-saml"clientapplication.

Similarlyreplacethe"teiid-web-security/teiid-odata-saml-keycloak/src/main/webapp/WEB-INF/keystore.jks"filewiththeexportedkeystorefromearliersteps.

buildthe"keycloak-saml.xml"file,andaddallthesectionsof"metadata"specifictoyourservice.ThisiswhereserviceknowswhereIDPlocatedandwhichservicethisrepresentsetc.

ThebuildtheWARfilesrunningthemavencommand

mvncleanpackage

TheabovecommandwillgenerateanewWARfilefordeployment.FollowthebelowdirectionstodeploythisnewWARfiletotheserver


735


CommunityTeiidServeronWildfly


cpteiid-web-security/teiid-odata-saml-keycloak/target/teiid-odata-saml-keycloak-

{version}.war

<wildfly>/modules/system/layers/dv/org/jboss/teiid/main/deployments/teiid-olingo-

odata4.war

JDVServer



deployteiid-web-security/teiid-odata-saml-keycloak/target/teiid-odata-saml-

keycloak-{version}.war



security/teiid-odata-saml-keycloak/src/main/webapp/WEB-INF/web.xml,/WEB-INF/jboss-

web.xml=teiid-web-security/teiid-odata-saml-keycloak/src/main/webapp/WEB-INF/jboss-

web.xml,/META-INF/MANIFEST.MF=teiid-web-security/teiid-odata-saml-

keycloak/src/main/webapp/META-INF/MANIFEST.MF,/WEB-INF/keycloak-saml.xml=teiid-web-

security/teiid-odata-saml-keycloak/src/main/webapp/WEB-INF/keycloak-saml.xml,/WEB-

INF/keycloak.jks=teiid-web-security/teiid-odata-saml-keycloak/src/main/webapp/WEB-

INF/keycloak.jks--deployments=teiid-olingo-odata4.war--redeploy-affected

TestingtheexampleusingWebBrowser

TotestanySAMLbasedapplicationyoumustuseaWebbrowser.UsingabrowserissueanyODataspecificquery,andyouwillberedirectedtodoSAMLauthentication.

http://localhost:8180/odata4/<vdb>.<version>/<model>/<view>


736