![Page 1: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/1.jpg)
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.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
1.3.8.2
TableofContentsIntroduction
LegalNotice
Administrator’sGuide
InstallationGuide
DeployingVDBs
DeployingVDBDependencies
AccumuloDataSources
AmazonSimpleDBDataSources
CassandraDataSources
FileDataSources
GoogleSpreadsheetDataSources
InfinispanLibraryModeDataSources
InfinispanHotRodDataSources
JDBCDataSources
LDAPDataSources
MongoDBDataSources
PhoenixDataSources
SalesforceDataSources
SolrDataSources
WebServiceDataSources
KerberoswithRESTbasedServices
OAuthAuthenticationWithRESTBasedServices
VDBVersioning
Logging
ClusteringinTeiid
Monitoring
PerformanceTuning
MemoryManagement
Threading
CacheTuning
SocketTransports
LOBs
OtherConsiderations
TeiidConsole
AdminShell
GettingStarted
Executingascriptfile
1
![Page 2: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/2.jpg)
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.1.1
1.5.1.1.1
1.5.1.1.2
1.5.1.1.3
1.5.1.1.4
1.5.1.1.5
1.5.1.1.6
1.5.1.1.7
1.5.1.2
1.5.1.3
1.5.1.4
1.5.1.4.1
1.5.1.4.2
1.5.1.4.3
1.5.1.4.4
1.5.1.4.5
1.5.1.5
1.5.1.5.1
1.5.1.5.2
1.5.2
LogFileandRecordedScriptfile
DefaultConnectionProperties
HandlingMultipleConnections
InteractiveShellNuances
OtherScriptingEnvironments
SystemProperties
TeiidManagementCLI
DiagnosingIssues
MigrationGuideFromTeiid8.x
CachingGuide
ResultsCaching
MaterializedViews
ExternalMaterialization
InternalMaterialization
CodeTableCaching
TranslatorResultsCaching
HintsandOptions
ProgrammaticControl
ClientDeveloper’sGuide
JDBCSupport
ConnectingtoaTeiidServer
DriverConnection
DataSourceConnection
StandaloneApplication
WildFlyDataSource
UsingMultipleHosts
SSLClientConnections
AdditionalSocketClientSettings
PreparedStatements
ResultSetLimitations
JDBCExtensions
StatementExtensions
PartialResultsMode
Non-blockingStatementExecution
ResultSetExtensions
ConnectionExtensions
UnsupportedJDBCMethods
UnsupportedClassesandMethodsin"java.sql"
UnsupportedClassesandMethodsin"javax.sql"
ODBCSupport
2
![Page 3: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/3.jpg)
1.5.2.1
1.5.2.2
1.5.2.3
1.5.2.4
1.5.3
1.5.3.1
1.5.4
1.5.5
1.5.6
1.5.7
1.5.8
1.5.8.1
1.5.9
1.5.10
1.5.11
1.5.11.1
1.5.11.2
1.5.11.3
1.5.11.4
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
1.6.2.2.6
InstallingtheODBCDriverClient
ConfiguringtheDataSourceName(DSN)
DSNLessConnection
ODBCConnectionProperties
ODataSupport
ODataVersion4.0Support
UsingTeiidwithHibernate
UsingTeiidwithEclipseLink
GeoServerIntegration
Reauthentication
ExecutionProperties
XMLextensions
SETStatement
SHOWStatement
Transactions
LocalTransactions
RequestLevelTransactions
UsingGlobalTransactions
Restrictions
Developer’sGuide
DevelopingJEEConnectors
ConnectorEnvironmentSetup
BuildEnvironment
ArchetypeTemplateConnectorProject
ImplementingtheTeiidFramework
ra.xmlfileTemplate
PackagingtheAdapter
AddingDependentLibraries
DeployingtheAdapter
TranslatorDevelopment
EnvironmentSetup
Settingupthebuildenvironment
ArchetypeTemplateTranslatorProject
ImplementingtheFramework
CachingAPI
CommandLanguage
ConnectionstoSource
DependentJoinPushdown
ExecutingCommands
ExtendingtheExecutionFactoryClass
3
![Page 4: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/4.jpg)
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.3.2.1
1.6.4
1.6.5
1.6.6
1.6.7
1.6.8
1.6.8.1
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
LargeObjects
TranslatorCapabilities
TranslatorProperties
ExtendingTheJDBCTranslator
DelegatingTranslator
Packaging
AddingDependentModules
Deployment
UserDefinedFunctions
SourceSupportedFunctions
SupportforUser-DefinedFunctions(Non-Pushdown)
ArchethypeTemplateUDFProject
AdminAPI
CustomLogging
RuntimeUpdates
CustomMetadataRepository
PreParser
ArchethypeTemplatePreParserProject
EmbeddedGuide
LogginginTeiidEmbedded
SecureEmbeddedwithPicketBox
ReferenceGuide
DataSources
SQLSupport
Identifiers
Expressions
Criteria
ScalarFunctions
NumericFunctions
StringFunctions
Date_TimeFunctions
TypeConversionFunctions
ChoiceFunctions
DecodeFunctions
LookupFunction
SystemFunctions
XMLFunctions
JSONFunctions
SecurityFunctions
SpatialFunctions
4
![Page 5: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/5.jpg)
1.8.2.4.13
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
MiscellaneousFunctions
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
5
![Page 6: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/6.jpg)
1.8.5.1
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.10.1
1.8.9.10.2
1.8.9.10.3
1.8.9.10.4
1.8.9.10.5
1.8.9.10.6
1.8.9.10.7
1.8.9.10.8
AutoCommitTxnExecutionProperty
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
DelegatingTranslators
FileTranslator
GoogleSpreadsheetTranslator
InfinispanHotRodTranslator
InfinispanLibraryModeTranslator
JDBCTranslators
ActianVectorTranslator
ApacheHBaseTranslator
ClouderaImpalaTranslator
DB2Translator
DerbyTranslator
GreenplumTranslator
H2Translator
HiveTranslator
6
![Page 7: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/7.jpg)
1.8.9.10.9
1.8.9.10.10
1.8.9.10.11
1.8.9.10.12
1.8.9.10.13
1.8.9.10.14
1.8.9.10.15
1.8.9.10.16
1.8.9.10.17
1.8.9.10.18
1.8.9.10.19
1.8.9.10.20
1.8.9.10.21
1.8.9.10.22
1.8.9.10.23
1.8.9.10.24
1.8.9.10.25
1.8.9.10.26
1.8.9.10.27
1.8.9.10.28
1.8.9.10.29
1.8.9.10.30
1.8.9.10.31
1.8.9.11
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.10
1.8.10.1
1.8.10.2
1.8.10.3
HSQLTranslator
InformixTranslator
IngresTranslators
IntersystemsCacheTranslator
JDBCANSITranslator
JDBCSimpleTranslator
MetaMatrixTranslator
MicrosoftAccessTranslators
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
QueryPlans
7
![Page 8: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/8.jpg)
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
FederatedOptimizations
SubqueryOptimization
XQueryOptimization
FederatedFailureModes
ConformedTables
Architecture
Terminology
DataManagement
QueryTermination
Processing
BNFforSQLGrammar
SecurityGuide
LoginModules
TeiidServerTransportSecurity
JDBC/ODBCSSLconnectionusingself-signedSSLcertificates
DataSourceSecurity
KerberossupportthroughGSSAPI
CustomAuthorizationValidator
SAMLBasedSecurityForOData
OAuth2BasedSecurityForODataUsingKeyCloak
SAMLBasedSecurityForODataUsingKeyCloak
8
![Page 9: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/9.jpg)
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
![Page 10: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/10.jpg)
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
![Page 11: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/11.jpg)
LegalNotice
1801VarsityDriveRaleigh,NC27606-2072USAPhone:+19197543700Phone:8887334281Fax:+19197543701POBox13588ResearchTrianglePark,NC27709USA
Copyright©2016byRedHat,Inc.Thiscopyrightedmaterialismadeavailabletoanyonewishingtouse,modify,copy,orredistributeitsubjecttothetermsandconditionsoftheGNULesserGeneralPublicLicense,aspublishedbytheFreeSoftwareFoundation.
RedHatandtheRedHat"ShadowMan"logoareregisteredtrademarksofRedHat,Inc.intheUnitedStatesandothercountries.
Allothertrademarksreferencedhereinarethepropertyoftheirrespectiveowners.
CA2086862BD69DFC65F6ECC4219180CDDB42A60E
LegalNotice
11
![Page 12: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/12.jpg)
Administrator’sGuideThisguideisintendedforanyuserwhoassumesroleofadeveloper/administratorofTeiidinstance.ThisguideguidesuserthroughinstallationofTeiidServer,configurationofdifferentservicesanddeploymentofTeiidartifactssuchasVDBs.BeforeonecandelveintoTeiiditisveryimportanttolearnfewbasicconstructsofTeiid,likewhatisVDB?whatisModel?etc.Forthatpleasereadtheshortintroductionherehttp://teiid.jboss.org/basics/
Administrator’sGuide
12
![Page 13: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/13.jpg)
InstallationGuideTeiidneedstobeinstalledintoanexistingWildFly10.0.0installation.
Note Teiidprovidesanembeddedkit,howeveritshouldbeconsideredatechpreviewasitsAPIswilllikelyevolveandthereissparsedocumentation.
StepstoinstallTeiid
DownloadtheWildFlyapplicationserver.Installtheserverbyunzippingintoaknownlocation.Ex:/apps/jboss-install
Note YoumayalsochoosetouseanexistingASinstallation.HoweverifapreviousversionofTeiidwasalreadyinstalled,youmustremovetheoldTeiiddistributionartifactsbeforeinstallingthenewversion.
DownloadTeiid.UnzipthedownloadedartifactinsidetheWildFlyinstallation.Teiid9.1directorystructurematchesWildFlydirectly-itisjustanoverlay.ThiswilladdnecessarymodulesandconfigurationfilestoinstallTeiidinWildFly10.0.0inbothStandaloneandDomainmodes.Teiidprovidesseparateconfigurationfilesforbothstandalonemodeanddomainmode.BasedonmodetypeyouselectedtorunWildFly10.0.0,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
thiswillinstallTeiidsubsystemintotherunningconfigurationoftheWildFly10.0.0instandalonemode.
DomainMode
Tostarttheserverin"Domain"mode,installWildFly10.0.0andTeiid9.1onalltheserversthataregoingtobepartofthecluster.Selectoneoftheserversasthe"master"domaincontroller,therestoftheserverswillbeslavesthatconnecttothe"master"domaincontrollerforalltheadministrativeoperations.PleaserefertoWildFly10.0.0provideddocumentationforfulldetails.
InstallationGuide
13
![Page 14: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/14.jpg)
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.1deployment.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
![Page 15: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/15.jpg)
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/* ThisdirectorycontainstheTeiidmodulesforWildFly10.0.0system
/modules/system/layers/base/org/jboss/teiid/client
ThisdirectorycontainsTeiidclientlibraries.IthastheTeiidJDBCdriverjar,"teiid-9.1.0.Final-jdbc.jar",andalsocontains"teiid-hibernate-dialect-9.1.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
![Page 16: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/16.jpg)
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
WildFly10.0.0providescommandlineinterface(CLI)fordoinganykindofadministrativetask.Execute
bin/jboss-cli.sh--connect
DeployingVDBs
16
![Page 17: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/17.jpg)
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
![Page 18: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/18.jpg)
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.
DeployingVDBDependencies
18
![Page 19: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/19.jpg)
ApacheAccumuloDataSourcesAccumulodatasourcesuseaTeiidspecificJCAconnectorthatisdeployedintoWildFly10.0.0duringinstallation.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-IfWildFly10.0.0isrunninginstandalonemode,youcanalsomanuallyeditthe"<jboss-install>/standalone/configuration/standalone-teiid.xml"fileandaddtheXMLconfigurationdefinedin"<jboss-install>/docs/teiid/datasources/accumulo"directoryunder"resource-adapters"subsystem.Shutdowntheserver
DeployingVDBDependencies
19
![Page 20: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/20.jpg)
beforeyoueditthisfile,andrestartafterthemodificationsaredone.
DeployingVDBDependencies
20
![Page 21: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/21.jpg)
AmazonSimpleDBDataSourcesSimpleDBdatasourcesuseaTeiidspecificJCAconnectorthatisdeployedintoWildFly10.0.0duringinstallation.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-IfWildFly10.0.0isrunninginstandalonemode,youcanalsomanuallyeditthe"<jboss-install>/standalone/configuration/standalone-teiid.xml"fileandaddtheXMLconfigurationdefinedin"<jboss-install>/docs/teiid/datasources/simpledb"directoryunder"resource-adapters"subsystem.Shutdowntheserverbeforeyoueditthisfile,andrestartafterthemodificationsaredone.
DeployingVDBDependencies
21
![Page 22: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/22.jpg)
CassandraDataSourcesCassandradatasourcesuseaTeiidspecificJCAconnectorthatisdeployedintoWildFly10.0.0duringinstallation.TherearemanywaystocreateaCassandradatasource,usingCLI,AdminShell,admin-console,etc.TheexampleshownbelowusestheCLItool,asthisworksinbothStandaloneandDomainmodes.
ExecutethefollowingcommandusingtheCLIonceyouconnectedtotheServer.MakesureyouprovidethecorrectURLandusercredentials.Addanyadditionalpropertiesrequiredbytheconnectorbyduplicatingthe"connection-definitions"commandbelow.EdittheJNDInametomatchtheJNDInameyouusedinVDB.
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-IfWildFly10.0.0isrunninginstandalonemode,youcanalsomanuallyeditthe"<jboss-install>/standalone/configuration/standalone-teiid.xml"fileandaddtheXMLconfigurationdefinedin"<jboss-install>/docs/teiid/datasources/cassandra"directoryunder"resource-adapters"subsystem.Shutdowntheserverbeforeyoueditthisfile,andrestartafterthemodificationsaredone.
DeployingVDBDependencies
22
![Page 23: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/23.jpg)
FileDataSourcesFiledatasourcesuseaTeiidspecificJCAconnectorthatisdeployedintoWildFly10.0.0duringinstallation.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-IfWildFly10.0.0isrunninginstandalonemode,youcanalsomanuallyeditthe"<jboss-install>/standalone/configuration/standalone-teiid.xml"fileandaddtheXMLconfigurationdefinedin"<jboss-install>/docs/teiid/datasources/file"directoryunder"resource-adapters"subsystem.Shutdowntheserverbeforeyoueditthisfile,andrestartafterthemodificationsaredone.
DeployingVDBDependencies
23
![Page 24: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/24.jpg)
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
DeployingVDBDependencies
24
![Page 25: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/25.jpg)
InfinispanLibraryModeDataSourcesInfinispanLibaryModedatasourcesuseaTeiidspecificJCAconnectorthatisdeployedintoWildFly10.0.0duringinstallation.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
DeployingVDBDependencies
25
![Page 26: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/26.jpg)
module N SpecifytheWildFlymodulethatcontainsthecacheclassesthatweredefinedinCacheTypeMap
CacheJndiName N JNDInametofinetheCacheContainer
ConfigurationFileNameForLocalCache N TheInfinispanConfigurationxmlfileforconfiguringalocalcache
UsingCacheforExternalMaterialization
ThefollowingaretheadditionalpropertiesthatneedtobeconfiguredifusingtheRemoteCacheforexternalmaterialization:
PropertyName Req. Description
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)
/subsystem=resource-adapters/resource-adapter=infinispan/connection-definitions=infinispanDS/config-properties=
Module:add(value=org.somewhere)
/subsystem=resource-adapters/resource-adapter=infinispan/connection-definitions=infinispanDS/config-properties=
CacheJndiName:add(value=java:/myCache)
runbatch
TofindoutallthepropertiesthataresupportedbythisInfinispanConnectorexecutethefollowingcommandintheCLI.
/subsystem=teiid:read-rar-description(rar-name=infinispan)
Tip
Developer’sTip-IfWildFly10.0.0isrunninginstandalonemode,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.
DeployingVDBDependencies
26
![Page 27: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/27.jpg)
DeployingVDBDependencies
27
![Page 28: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/28.jpg)
InfinispanHotRodDataSourcesInfinispancachesrunninginclient/servermodecanuseaTeiidspecificJCAconnectorforaccessingasadatasource,whichisdeployedintoWildFly10.0.0duringinstallation.ThisconnectorcanbeconfiguredtosupporttheaccessingofaremoteInfinispancacheusingthetheHotRodclient.
EachInfinispancachethathasareferencedpojoobjectbydoinga"get(key)"onthecache,forwhichyouwanttoaccess,willrequireadifferentconfiguredresource-adapter.
TherearetwooptionsforhowtheInfinispanschemacanbeconfiguredintheconnector;protobufannotationsorprotobuf(.proto)filewithmarshaller(s).Thefollowingaretherequirements.
Requirement(option1)Minimum,JDG6.2-thisrequiresyouprovideaprotobufdefinitionfileandpojomarshaller(s)forthepojotoconfiguretheJDGschema
(option2)Minimum,JDG6.6-thiscanbeusedwhenthepojohasdefinedprotobufannotationswhichareusedtoconfiguretheJDGschema.
SeeInfinispanHotRodTranslatorfordetailsonhowthethemetadatawillbeexposedorcanbemanuallyconfiguredbasedontheschemathat’sdefinedforthisdatasource.
ConfigurationThefollowingpropertyisrequiredasitprovidesthemappingtotheInfinispancacheandpojothatwillbeaccessed.
PropertyName PropertyTemplate Description
CacheTypeMap cacheName:className[;pkFieldName[:cacheKeyJavaType]]
FortheindicatedcacheName,maptherootJavaObject(pojo)classname.Optionally,butrequiredforupdates,identifywhichclassattributeistheprimarykeytothecache.Optionally,identifyprimarykeyjavatypewhendifferentthanclassattributetype
ProtobufDefinitionandMarshaller(s)
Thefollowingpropertiesarerequiredwhentheprotobufdefinitionfile(.proto)andthepojomarshaller(s)arebeingusedtoconfiguretheJDGschema:
PropertyName Req. PropertyTemplate Description
ProtobufDefinitionFile Y
PathtotheGoogleProtobuffilethat’spackagedinajar(ex:/quickstart/addressbook.proto)
DeployingVDBDependencies
28
![Page 29: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/29.jpg)
MessageMarshallers Y marshaller\[,marshaller,..\]
ContainsClassnamesmappeditsrespectivemessagemarshaller,(class:marshaller,\[class:marshaller,..\]),thataretoberegisteredforserialization
MessageDescriptor YMessagedescriptorclassnamefortherootobjectincache
PojoClass/Jar
Thepojoclassistheobjectthatisusedtostorethedatainthecache.Itshouldbebuiltaccordingly:
Ifthepojoistobeusedtodefinetheschema,thenshouldusetheprotobufannotations.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
Iftheprotobufdefinitionandmashaller(s)aretobeused,thentheseshouldalsobepackagedinthejar(oraseparatejarthatisincludedintheclasspath).
Theclassshouldbepackagedintoajarsothatitcanbedeployedasamodule.
SamplePojowithAnnotations
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){
DeployingVDBDependencies
29
![Page 30: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/30.jpg)
this.phones=phones;
}
}
Toconfiguretheresource-adaptertousethepojo,dothefollowing:
Deploythepojojarasamoduleinthejboss-asserver.
ReadingandWritingtotheCache
OneofthefollowingpropertiesisrequiredfordefininghowtheRemoteCacheManagerwillbecreated/accessed:
PropertyName Req. PropertyTemplate Description
CacheJndiName N JNDInametofindtheCacheContainer
RemoteServerList N host:port\[;host:port….\]
Specifythehostandportsthatwillbeclusteredtogethertoaccessthecaches
HotRodClientPropertiesFile N
TheHotRodpropertiesfileforconfiguringaconnectiontoaremotecache
Thefollowingpropertyshouldbedefinedwhenusingprotobufdefinitionfileandmarshallers:
PropertyName Req. PropertyTemplate Description
module N
SpecifytheWildFlymodulethatcontainsthecacheclassesthatneedtobeloaded
UsingRemoteCacheforExternalMaterialization
ThefollowingaretheadditionalpropertiesthatneedtobeconfiguredifusingtheRemoteCacheforexternalmaterialization:
PropertyName Req. Description
StagingCacheName Y Cachenameforthestagingcacheusedinmaterialization
AliasCacheName Y
Cachenameforthealiascacheusedintrackingaliasingofthecachesusedinmaterialization.Thiscachecanbesharedwithotherconfiguredmaterializations.
Examples
Therearemanywaystocreatethedatasource,usingCLI,AdminShell,admin-consoleetc.Thefirstexampleisanxmlsnippetofaresource-adapterthatisusedtoconnecttotheJDGremote-queryquickstart:me
SampleResourceAdapterdefiningProtobufDefinitionandMarshaller
<resource-adapterid="infinispanRemQS">
DeployingVDBDependencies
30
![Page 31: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/31.jpg)
<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="ProtobufDefinitionFile">
/quickstart/addressbook.proto
</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>
SampleResourceAdapterusingPojowithannotations
<resource-adapterid="infinispanRemQSDSL">
<moduleslot="main"id="org.jboss.teiid.resource-adapter.infinispan.dsl"/>
<connection-definitions>
<connection-definitionclass-name="org.teiid.resource.adapter.infinispan.dsl.Infinispan
ManagedConnectionFactory"jndi-name="java:/infinispanRemoteDSL"enabled="true"use-java-context="true"pool-name
="infinispanRemoteDSL">
<config-propertyname="RemoteServerList">
127.0.0.1:11322
</config-property>
<config-propertyname="CacheTypeMap">
addressbook_indexed:org.jboss.as.quickstarts.datagrid.hotrod.query.domain.Perso
n;id
</config-property>
</connection-definition>
</connection-definitions>
</resource-adapter>
SampleResourceAdapterforexternalmaterialization
<resource-adapterid="infinispanRemQSDSL">
<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:/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">
DeployingVDBDependencies
31
![Page 32: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/32.jpg)
aliasCache
</config-property>
<config-propertyname="Module">
com.client.quickstart.addressbook.pojos
</config-property>
<config-propertyname="RemoteServerList">
127.0.0.1:11322
</config-property>
</connection-definition>
</connection-definitions>
</resource-adapter>
DeployingVDBDependencies
32
![Page 33: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/33.jpg)
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-IfWildFly10.0.0isrunninginstandalonemode,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
DeployingVDBDependencies
33
![Page 34: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/34.jpg)
Thedriver-namewillmatchthenameofjarormodulethatyoudeployedforthedriver.
Tip
Developer’sTip-IfWildFly10.0.0isrunninginstandalonemode,youcanalsomanuallyeditthe"<jboss-install>/standalone/configuration/standalone-teiid.xml"fileandaddtheXMLconfigurationdefinedin*"<jboss-install>/docs/teiid/datasources/oracle"directoryunder"datasources"subsystem.Shutdowntheserverbeforeyoueditthisfile,andrestartafterthemodificationsaredone.
DeployingVDBDependencies
34
![Page 35: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/35.jpg)
LDAPDataSourcesLDAPdatasourcesuseaTeiidspecificJCAconnectorwhichisdeployedintoWildFly10.0.0duringinstallation.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)
/subsystem=resource-adapters/resource-adapter=ldap/connection-
definitions=ldapDS/config-properties=LdapUrl:add(value=ldap://ldapServer:389)
/subsystem=resource-adapters/resource-adapter=ldap/connection-
definitions=ldapDS/config-properties=LdapAdminUserDN:add(value=
{cn=???,ou=???,dc=???})
/subsystem=resource-adapters/resource-adapter=ldap/connection-
definitions=ldapDS/config-properties=LdapAdminUserPassword:add(value={pass})
/subsystem=resource-adapters/resource-adapter=ldap/connection-
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-IfWildFly10.0.0isrunninginstandalonemode,youcanalsomanuallyeditthe"<jboss-install>/standalone/configuration/standalone-teiid.xml"fileandaddtheXMLconfigurationdefinedin*"<jboss-install>/docs/teiid/datasources/ldap"directoryunder"resource-adapters"subsystem.Shutdowntheserverbeforeyoueditthisfile,andrestartafterthemodificationsaredone.
Note Touseananonymousbind,settheLdapAdminUserDNandLdapAdminUserPasswordtoemptyvalues.
Tip Ifyouexperiencestaleconnectionsinthepool,youshouldenableeitherthevalidate-on-matchorthebackground-validationpoolsettings.
DeployingVDBDependencies
35
![Page 36: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/36.jpg)
MongoDBDataSourcesMongoDBdatasourcesuseaTeiidspecificJCAconnectorthatisdeployedintoWildFly10.0.0duringinstallation.TherearemanywaystocreateaMongoDBdatasource,usingCLI,AdminShell,admin-console,etc.TheexampleshownbelowusestheCLItool,asthisworksinbothStandaloneandDomainmodes.
ExecutethefollowingcommandusingtheCLIonceyouconnectedtotheServer.MakesureyouprovidethecorrectURLandusercredentials.Addanyadditionalpropertiesrequiredbytheconnectorbyduplicatingthe"connection-definitions"commandbelow.EdittheJNDInametomatchtheJNDInameyouusedinVDB.
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
PropertyName Description Required Default
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-IfWildFly10.0.0isrunninginstandalonemode,youcanalsomanuallyeditthe"<jboss-install>/standalone/configuration/standalone-teiid.xml"fileandaddtheXMLconfigurationdefinedin"<jboss-install>/docs/teiid/datasources/mongodb"directoryunder"resource-adapters"subsystem.Shutdowntheserverbeforeyoueditthisfile,andrestartafterthemodificationsaredone.
DeployingVDBDependencies
36
![Page 37: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/37.jpg)
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.
DeployingVDBDependencies
37
![Page 38: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/38.jpg)
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.
DeployingVDBDependencies
38
![Page 39: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/39.jpg)
DeployingVDBDependencies
39
![Page 40: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/40.jpg)
SalesforceDataSourcesSalesforcedatasourcesuseaTeiidspecificJCAconnectorthatisdeployedintoWildFly10.0.0duringinstallation.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-IfWildFly10.0.0isrunninginstandalonemode,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"
DeployingVDBDependencies
40
![Page 41: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/41.jpg)
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
h==OAuthSecuritywith"RefreshToken"
ThebelowlayoutthedirectionstouseRefreshTokenbasedOAuthAuthenticationwithSalesforce.
1)createconnectedapp(mayneedtosetupcustomdomain)2)addprofileand/orpermissionssettotheconnectedapp3)grabthe"callbackurl"(oneneedtosetashttps://localhost:443/_callback"4)Runthroughtheteiid-oauth-util.shin"<eap>/bin"directory,useclient_id,client_pass,andcallbackfromconnectedapp5)use"https://login.salesforce.com/services/oauth2/authorize"authorizelink6)use"https://login.salesforce.com/services/oauth2/token"foraccesstokenurl7)theyougetarefreshtokenfromit8)createasecurity-domainbyexecutingCLI
/subsystem=security/security-domain=oauth2-security:add(cache-type=default)
/subsystem=security/security-domain=oauth2-security/authentication=classic:add
/subsystem=security/security-domain=oauth2-security/authentication=classic/login-
module=Kerberos:add(code=org.teiid.jboss.oauth.OAuth20LoginModule,flag=required,
module=org.jboss.teiid.security,
module-options=[client-id=xxxx,client-secret=xxxx,refresh-token=xxxx,
access-token-uri=https://login.salesforce.com/services/oauth2/token])
reload
thiswillgeneratefollowingXMLinthestandalone.xmlordomain.xml(thiscanalsobedirectlyaddedtothestandalone.xmlordomain.xmlfilesinsteadofexecutingtheCLI)
standalone.xml
<security-domainname="oauth2-security">
<authentication>
<login-modulecode="org.teiid.jboss.oauth.OAuth20LoginModule"flag="required"module="org.jboss.teiid.s
ecurity">
<module-optionname="client-id"value="xxxx"/>
<module-optionname="client-secret"value="xxxx"/>
<module-optionname="refresh-token"value="xxxx"/>
<module-optionname="access-token-uri"value="https://login.salesforce.com/services/oauth2/token"/>
</login-module>
</authentication>
</security-domain>
9)Thentousetheabovesecuritydomaininthesalesforcedatasourceconfiguration,add"<security-domain>oauth2-security</security-domain>"
DeployingVDBDependencies
41
![Page 42: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/42.jpg)
OAuthSecuritywith"JWTToken"basedSteps
ThebelowlayoutthedirectionstouseJWTtokenbasedOAuthAuthenticationwithSalesforce.
1)CreateaSelf-SignedcertificatelocallyoronSalesForce.(user→setup→security-controls→CertificateandKeyManagement)2)Downloadthecertificateandalsoputinkeystoreanddownloadkeystore.KeystoreisneededforTeiid,certificateforthesalesforcesetup3)CreateconnectedappandselectOAuth,andselectallthescopes(somepostssayrefresh-tokenofflineismust)4)createaprofileand/orpermissionsetassigntotheconnectedapp.Ibelievebeforeyoucancreateaconnectedappyouneedtosetupcustomdomain5)Whenyoucreatingconnectedappmakesureyouaddthecertificatein"DigitalCertificate"6)NowinTeiidcreatesecurity-domainbyexecutingCLI
/subsystem=security/security-domain=oauth2-jwt-security:add(cache-type=default)
/subsystem=security/security-domain=oauth2-jwt-security/authentication=classic:add
/subsystem=security/security-domain=oauth2-jwt-
security/authentication=classic/login-
module=oauth:add(code=org.teiid.jboss.oauth.OAuth20LoginModule,flag=required,
module=org.jboss.teiid.security,
module-options=[client-id=xxxx,client-secret=xxxx,access-token-
uri=https://login.salesforce.com/services/oauth2/token,jwt-
audience=https://login.salesforce.com,[email protected],
keystore-type=JKS,keystore-password=changeme,keystore-
url=${jboss.server.config.dir}/salesforce.jks,certificate-alias=teiidtest,
signature-algorithm-name=SHA256withRSA])
reload
thiswillgeneratefollowingXMLinthestandalone.xmlordomain.xml(thiscanalsobedirectlyaddedtothestandalone.xmlordomain.xmlfilesinsteadofexecutingtheCLI)
standalone.xml
<security-domainname="oauth2-jwt-security">
<authentication>
<login-modulecode="org.teiid.jboss.oauth.JWTBearerTokenLoginModule"flag="required"module="org.jboss.
teiid.security">
<module-optionname="client-id"value="xxxxx"/>
<module-optionname="client-secret"value="xxxx"/>
<module-optionname="access-token-uri"value="https://login.salesforce.com/services/oauth2/token"/>
<module-optionname="jwt-audience"value="https://login.salesforce.com"/>
<module-optionname="jwt-subject"value="[email protected]"/>
<module-optionname="keystore-type"value="JKS"/>
<module-optionname="keystore-password"value="changeme"/>
<module-optionname="keystore-url"value="${jboss.server.config.dir}/salesforce.jks"/>
<module-optionname="certificate-alias"value="teiidtest"/>
<module-optionname="signature-algorithm-name"value="SHA256withRSA"/>
</login-module>
</authentication>
</security-domain>
7)Thentousetheabovesecuritydomaininthesalesforcedatasourceconfiguration,add"<security-domain>oauth2-jwt-security</security-domain>"
Morehelpfullinks
https://developer.salesforce.com/blogs/developer-relations/2011/03/oauth-and-the-soap-api.htmlhttps://help.salesforce.com/apex/HTViewHelpDoc?id=remoteaccess_oauth_jwt_flow.htm&language=en_US#create_tokenhttp://salesforce.stackexchange.com/questions/31904/how-and-when-does-a-salesforce-saml-oauth2-user-give-permission-to-use-
DeployingVDBDependencies
42
![Page 43: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/43.jpg)
a-connehttp://salesforce.stackexchange.com/questions/30596/oauth-2-0-jwt-bearer-token-flowhttp://salesforce.stackexchange.com/questions/88396/invalid-assertion-error-in-jwt-bearer-token-flow
DeployingVDBDependencies
43
![Page 44: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/44.jpg)
SolrDataSourcesSolrdatasourcesuseaTeiidspecificJCAconnectorthatisdeployedintoWildFly10.0.0duringinstallation.TherearemanywaystocreateaSolrdatasource,usingCLI,AdminShell,admin-console,etc.TheexampleshownbelowusestheCLItool,asthisworksinbothStandaloneandDomainmodes.
ExecutethefollowingcommandusingtheCLIonceyouconnectedtotheServer.MakesureyouprovidethecorrectURLandusercredentials.Addanyadditionalpropertiesrequiredbytheconnectorbyduplicatingthe"connection-definitions"commandbelow.EdittheJNDInametomatchtheJNDInameyouusedinVDB.
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-IfWildFly10.0.0isrunninginstandalonemode,youcanalsomanuallyeditthe"<jboss-install>/standalone/configuration/standalone-teiid.xml"fileandaddtheXMLconfigurationdefinedin"<jboss-install>/docs/teiid/datasources/solr"directoryunder"resource-adapters"subsystem.Shutdowntheserverbeforeyoueditthisfile,andrestartafterthemodificationsaredone.
DeployingVDBDependencies
44
![Page 45: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/45.jpg)
WebServiceDataSourcesWebservicedatasourcesuseaTeiidspecificJCAconnectorthatisdeployedintoWildFly10.0.0duringinstallation.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-IfWildFly10.0.0isrunninginstandalonemode,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
DeployingVDBDependencies
45
![Page 46: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/46.jpg)
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
<beansxmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:http-conf="http://cxf.apache.org/transports/http/configuration"
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">
<http-conf:clientConnectionTimeout="120000"ReceiveTimeout="240000"/>
</http-conf: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
DeployingVDBDependencies
46
![Page 47: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/47.jpg)
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)
/subsystem=resource-adapters/resource-adapter=webservice:activate
runbatch
Thecorrespondingxxx-jbossws-cxf.xmlfilethataddsatimestamptotheSOAPheader
ExampleWS-Securityenableddatasource
<beansxmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
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
DeployingVDBDependencies
47
![Page 48: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/48.jpg)
<?xmlversion="1.0"encoding="UTF-8"?>
<beansxmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:http="http://cxf.apache.org/transports/http/configuration"
xmlns:jaxws="http://cxf.apache.org/jaxws"
xmlns:cxf="http://cxf.apache.org/core"
xmlns:p="http://cxf.apache.org/policy"
xmlns:sec="http://cxf.apache.org/configuration/security"
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-
DeployingVDBDependencies
48
![Page 49: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/49.jpg)
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=ConfigFile:add(value=${jboss.server.home.dir}/standalone/configuration/x
xx-jbossws-cxf.xml)
/subsystem=resource-adapters/resource-adapter=webservice/connection-
definitions=wsDS/config-properties=ConfigName:add(value=port_x)
/subsystem=resource-adapters/resource-adapter=webservice:activate
runbatch
Correspondingxxx-jbossws-cxf.xml
Exampleloggingdatasource
<beansxmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
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_y"
createdFromAPI="true">
<jaxws:features>
<beanclass="org.apache.cxf.feature.LoggingFeature"/>
</jaxws:features>
</jaxws:client>
</beans>
TransportSettings
TheCXFconfigpropertymayalsobeusedtocontrollowlevelaspectsoftheHTTPtransport.SeetheCXFdocumentationforallpossibleoptions.
ExampleDisablingHostnameVerification
<beansxmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:http-conf="http://cxf.apache.org/transports/http/configuration"
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">
<!--WARNING!disableCNcheck=trueshouldNOTbeusedinproduction-->
<http-conf:tlsClientParametersdisableCNcheck="true"/>
</http-conf:conduit>
</beans>
ConfiguringSSLSupport(Https)ForusingtheHTTPS,youcanconfigureCXFfileasbelow
DeployingVDBDependencies
49
![Page 50: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/50.jpg)
<beansxmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
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>
forallthehttp-conduitbasedconfigurationseehttp://cxf.apache.org/docs/client-http-transport-including-ssl-support.html.YoucanalsoconfigureforHTTPBasic,kerberos,etc.
DeployingVDBDependencies
50
![Page 51: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/51.jpg)
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>
<login-modulecode="Kerberos"flag="required">
<module-optionname="storeKey"value="true"/>
<module-optionname="useKeyTab"value="true"/>
<module-optionname="keyTab"value="/home/username/service.keytab"/>
<module-optionname="principal"value="host/testserver@MY_REALM"/>
<module-optionname="doNotPrompt"value="true"/>
<module-optionname="debug"value="false"/>
</login-module>
</authentication>
</security-domain>
andthejboss-cxf-xxx.xmlfileneedstobesetas
<beansxmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:sec="http://cxf.apache.org/configuration/security"
xmlns:http-conf="http://cxf.apache.org/transports/http/configuration"
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:conduitname="*.http-conduit">
<http-conf:authorization>
<sec:AuthorizationType>Negotiate</sec:AuthorizationType>
<sec:Authorization>MY_REALM</sec:Authorization>
</http-conf:authorization>
</http-conf:conduit>
</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.
DeployingVDBDependencies
51
![Page 52: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/52.jpg)
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.
DeployingVDBDependencies
52
![Page 53: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/53.jpg)
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===
DeployingVDBDependencies
53
![Page 54: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/54.jpg)
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-definitions>
<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>
DeployingVDBDependencies
54
![Page 55: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/55.jpg)
<security>
<security-domain>oauth2-security</security-domain>
</security>
</connection-definition>
</connection-definitions>
</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.
DeployingVDBDependencies
55
![Page 56: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/56.jpg)
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
56
![Page 57: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/57.jpg)
VDBVersioning
57
![Page 58: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/58.jpg)
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">
<levelname="DEBUG"/>
<queue-lengthvalue="1024"/>
<overflow-actionvalue="block"/>
<subhandlers>
<handlername="COMMAND_FILE"/>
</subhandlers>
</async-handler>
<loggercategory="org.teiid.COMMAND_LOG">
<levelname="DEBUG"/>
<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
58
![Page 59: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/59.jpg)
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
59
![Page 60: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/60.jpg)
Toenablecommandloggingtoanalternativefilelocation,configureaseparatefileappenderfortheDETAILloggingoftheorg.teiid.COMMAND_LOGcontext.Anexampleofthisisshownbelowandcanalsobefoundinthestandalone-teiid.xmldistributedwithTeiid.
<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>
<loggercategory="org.teiid.COMMAND_LOG">
<levelname="DEBUG"/>
<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
60
![Page 61: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/61.jpg)
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
61
![Page 62: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/62.jpg)
ClusteringinTeiidSinceTeiidisinstalledinWildFly,thereisnoadditionalconfigurationneededbeyondwhatwasperformedwhenTeiidissetupinDomainMode.SeetheDomainModesectionintheTeiidInstallationGuide.JustmakesurethatyouinstalledTeiidineveryWildFlynodeandstartedallWildFlyinstancesintheDomainmodethattobeapartofthecluster.
Typicallyuserscreateclusterstoimprovetheperformanceofthesystemthrough:
LoadBalancing:TakelookattheClientDeveloper’sGuideonhowtouseloadbalancingbetweenmultiplenodes.
FailOver:TakelookattheClientDeveloper’sGuideonhowtousefailoverbetweenmultiplenodes.
DistributedCaching:Thisisautomaticallydoneforyouonceyouconfigureitasspecifiedabove.
Eventdistribution:metadataanddatamodificationswillbedistributedtoallclustermembers.
IntheDomainmode,theonlywayausercandeployanyartifactsisusingeitherCLIorusingtheAdminAPIorAdminShell.CopyingVDBdirectlyintothe"deployments"directoryisnotsupported.
ClusteringinTeiid
62
![Page 63: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/63.jpg)
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(default10000)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
63
![Page 64: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/64.jpg)
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
64
![Page 65: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/65.jpg)
ResultSetCache#ofRequests
QUERY_SERVICE_RESULT_SET_CACHE.request-count
Totalnumberofrequestsmadeagainstcache.
ResultSetCacheHitRatio% QUERY_SERVICE_RESULT_SET_CACHE.hit-ratio Percentageofpositivecache
hits.
Monitoring
65
![Page 66: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/66.jpg)
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
66
![Page 67: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/67.jpg)
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
67
![Page 68: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/68.jpg)
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.Ifyouaredealingwithdatasetswithbillionsofrowsandyourunintomemoryissues,thenafterexaminingtherootcauseifyouseethatit’ssolelyrelatedtomemoryheldbyasignificantnumberofbatchreferences,thenconsiderincreasingtheprocessor-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’ssizewillbereducedslightlytoallowforeffectivelymore
MemoryManagement
68
![Page 69: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/69.jpg)
workingmemoryinthevm.
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.
MemoryManagement
69
![Page 70: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/70.jpg)
UsinginternalmaterializationisbasedontheBufferManager.BufferManagersettingsmayneedtobeupdatedbaseduponthedesiredamountofinternalmaterializationperformedbydeployedvdbs.
Ifanoutofmemoryerroroccursitisbesttofirstcaptureaheapdumptodeterminewherememoryisbeingheld-tweakingtheBufferManagersettingsmaynotbenecessarydependinguponthecause.
CommonConfigurationScenarios
Inadditiontoscenariosoutlinedabove,acommonscenariowouldbetominimizetheamountofonheapspaceconsumedbyTeiid.Thiscanbedonebymovingthememorybuffertooffheapwiththememory-buffer-off-heapsettingorbyrestrictingthemax-reserve-kbsetting.Reducingthemax-processing-kbsettingshouldgenerallynotbenecessary,unlessthereisaneedtoseverlyrestricttheheapusagebeyondthemax-reserve-kbsetting.
MemoryManagement
70
![Page 71: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/71.jpg)
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
71
![Page 72: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/72.jpg)
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
72
![Page 73: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/73.jpg)
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
73
![Page 74: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/74.jpg)
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
74
![Page 75: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/75.jpg)
OtherConsiderationsWhenusingTeiidinadevelopmentenvironment,youmayconsidersettingthemax-source-rows-allowedpropertytoreasonablysmalllevelvalue(e.g.10000)topreventlargeamountsofdatafrombeingpulledfromsources.Leavingtheexception-on-max-source-rowssetto"true"willalertthedeveloperthroughanexceptionthatanattemptwasmadetoretrievemorethanthespecifiednumberofrows.
OtherConsiderations
75
![Page 76: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/76.jpg)
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.
TeiidConsole
76
![Page 77: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/77.jpg)
UsingthisviewyoucanchangeanyconfigurationvalueofTeiid.Notethatvariousdifferentconfigurationpropertiesaresub-dividedintodifferenttabs.Youcanclick"NeedHelp"linkonthesepagestoseethedescriptionofeachfieldonthepage.
Note ServerRestart-Notethatsomepropertiesrequireyoutorestarttheserverbeforetheycantakeeffect.
RuntimeViewRuntimeviewshowsruntimeinformationaboutAS7andTeiidsubsystem.RuntimeinformationaboutTeiidcanbeviewedbyselecting"VirtualDatabases"onlefthandnavigationaltree.
TeiidConsole
77
![Page 78: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/78.jpg)
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.
TeiidConsole
78
![Page 79: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/79.jpg)
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
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
79
![Page 80: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/80.jpg)
TeiidConsole
80
![Page 81: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/81.jpg)
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
81
![Page 82: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/82.jpg)
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
82
![Page 83: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/83.jpg)
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
83
![Page 84: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/84.jpg)
//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
84
![Page 85: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/85.jpg)
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
85
![Page 86: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/86.jpg)
LogFileandRecordedScriptfile
Duringtheinteractivemode,inputisrecordedinahistoryfile.Thisfilecanbeaccessedviatheuparrowintheinteractiveshell.
Usercanalsocapturethecommandsenteredduringainteractivesessiontotheirownscriptfilebyusing"startRecording"and"stopRecording"commands.Forexample,
recordstartdirectory/filename.txt
<commandsandscript..>
recordstop
Allinputandoutputbetweenthestartandstoparecapturedinthe"directory/filename.txt"file.Thisgivestheuseranoptiontocaptureonlycertainportionsoftheinteractivesessionandtolaterrefineascriptoutofrecordedfile.
LogFileandRecordedScriptfile
86
![Page 87: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/87.jpg)
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
87
![Page 88: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/88.jpg)
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
88
![Page 89: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/89.jpg)
InteractiveShellNuancesTheinteractiveshellusesaspecialshellinterpretterandthereforehasdifferentbehaviorthanjustwrittingascriptinGroovy.SeetheGroovyShellDocumentationformoreonitsusage.Notabledifferences:
DefstatementsdonotdefineavariableinthecontextoftheShell,e.g.donotusedefx=1,usex=1
Shellcommands(asseenthroughhelp)usingthenon-functionalshellsyntaxareonlyavailableintheshell.
GroovyclassesusingannotationscannotbeparsedintheShell.
InteractiveShellNuances
89
![Page 90: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/90.jpg)
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
90
![Page 91: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/91.jpg)
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
91
![Page 92: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/92.jpg)
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.
org.teiid.assumeMatchingCollation-defaultstofalse.IffalseandatranslatordoesnotspecifyacollationLocale,thenasortinvolvingcharacterdataforasort/mergejoinwillnotbepushed.TeiiddefaultstotheJavaUCS-2collation,whichmaynotmatchthedefaultcollationforsources,particulartables,orcolumns.Youmaysetthesystempropertyorg.teiid.assumeMatchingCollationtotruetorestoretheolddefaultbehaviororselectivelyupdatethetranslatorstoreportacollationLocalematchingorg.teiid.collationLocale(UCS-2ifunset).
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'.
org.teiid.aggressiveJoinGrouping-defaultstotrue.Settofalsetonotaggressivelygroupjoins(typicallyallowedifthereexistsanexplicitrelationship)againstthesamesourceforpushdownandrelymoreuponacostbasedordering.
Security
org.teiid.allowCreateTemporaryTablesByDefault-defaultstofalse.Settotruetousethepre-8.0behaviorofallowinganyauthenticatedusertocreatetemptableswithoutanexplicitpermission.
SystemProperties
92
![Page 93: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/93.jpg)
org.teiid.allowFunctionCallsByDefault-defaultstofalse.Settotruetousethepre-8.0behaviorofallowinganyauthenticatedusertocallanynon-systemfunctionwithoutanexplicitpermission.
org.teiid.ignoreUnauthorizedAsterisk-defaultstofalse.Iftrueunauthorizedcolumns(asdeterminedbydatarolechecking)arenotpartofselectallorqualifiedselectallexpansion.Iffalse,theclientmaysetthesessionvariableignore_unauthorized_asterisktotruetoachievethesamebehavior.
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
93
![Page 94: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/94.jpg)
TeiidManagementCLITheWildFlyCLIisacommandlinebasedadministrativeandmonitoringtoolforTeiid.ManysnippetsofCLIscriptingareshownthroughouttheAdminGuide-especiallyaroundmanagingdatasources.AdminShellprovidesabindingintotheGroovyscriptinglanguageandhigherlevelmethodsthatareoftenneededwheninteractingwithTeiid.ItisstillusefultoknowtheunderlyingCLIcommandsinmanycircumstances.ThebelowisaseriesusefulCLIcommandsforadministeringaTeiidServer.PleasealsorefertotheASdocumentationformoreoninteractingwiththeCLI-includinghowtonavigate,listoperations,etc.
TableofContentsVDBOperationsAuthenticationOperationsSourceOperationsTranslatorOperationsRuntimeOperations
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=tes
t)
/subsystem=teiid:remove-data-role(vdb-name=AdminAPITestVDB,vdb-version=1,data-role=TestDataRole,mapped-role=
test)
AuthenticationOperations
/subsystem=teiid:read-attribute(name=authentication-security-domain)
/subsystem=teiid:write-attribute(name=authentication-security-domain,value=teiid-security)
/subsystem=teiid:read-attribute(name=authentication-max-sessions-allowed)
/subsystem=teiid:write-attribute(name=authentication-max-sessions-allowed,value=1000)
/subsystem=teiid:read-attribute(name=authentication-sessions-expiration-timelimit)
/subsystem=teiid:write-attribute(name=authentication-sessions-expiration-timelimit,value=0)
/subsystem=teiid:read-attribute(name=authentication-type)
/subsystem=teiid:write-attribute(name=authentication-type,value=USERPASSWORD)
/subsystem=teiid:read-attribute(name=authentication-trust-all-local)
/subsystem=teiid:write-attribute(name=authentication-trust-all-local,value=true)
SourceOperations
/subsystem=teiid:add-source(vdb-name=AdminAPITestVDB,vdb-version=1,source-name=text-connector-test,translato
r-name=file,model-name=TestModel,ds-name=java:/test-file)
TeiidManagementCLI
94
![Page 95: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/95.jpg)
/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,transl
ator-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)
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
95
![Page 96: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/96.jpg)
DiagnosingIssuesYoumayexperiencesituationswhereyouincurperformanceissuesorunexpectedresults/exceptions.Therestofthischapterwillfocusonqueryplanningandprocessingissues.Configurationoroperationalissuesrelatedtothecontaineraretypicallymoreisolatedandeasiertoresolve.
GeneralDiagnosticProcess
Whenthereisanissue,startbyisolatingaproblemqueryasmuchaspossible.IfaccessingthroughODBCorOData,doesasimilarissueoccurjustthroughJDBC.Inwhateverscenariotheissueoccurs,theparticularsmatter-whatsources,ifthereisatransaction,load,etc.
Don’tmaketoomanyassumptions
Forexamplememoryconsumptioncanbeheavilydependentupondrivers,andaresultingoutofmemoryissuemayonlybeindirectlyrelatedtoTeiid
Startwiththequeryplan-especiallywithperformanceissues
Theremaybesimplificationsorchangespossibletoviewsandproceduresutilizedbytheuserquery.
Ensurethatrelevantcostingmetadataissetand/orthathintsyouhaveprovidedarebeingappliedasexpected.
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
DiagnosingIssues
96
![Page 97: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/97.jpg)
Onceyouhavetheplan,youcan:
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,Teiiddoesnotbuildhistogramsorotherin-depthmodelsofthedata.Thesesvaluesaremeanttobeapproximationswithnominallydistributionassumptions.Thecostinginformationfromthemetadataonlymattersforphysicalentitiesaswe’llrecomputethehighervaluesinplanningaftermergevirtualandotherplanmodifications.Ifyouseethatjoinisbeingimplementedinefficiently,thenfirstmakesurereasonablecostingvaluesarebeingsetonthetablesinvolved.Statisticscanbegatheredforsomesourcesatdesigntimeordeploytime.Inenvironmentsthatfluctuaterapidly,youmayneedtoissueruntimecostingupdatesviasystemprocedures.
Note:ifyoucardinalityvaluesareunknown-shownas'NodeCardinality:-1.0'intheplan-andnohintsareused,thentheoptimizerwillnotassumethatdependentjoinplansshouldbeused.
PushdownInhibited
Oneofthemostcommonissuesthatcausesperformanceproblemsiswhennotenoughoftheplanispushedtoagivensourceleadingtotoomanyrowsbeingfetchedand/ortoomuchprocessinginTeiid.
DiagnosingIssues
97
![Page 98: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/98.jpg)
Pushdownproblemsfallintotwocategories:
Somethingthatcannotbepusheddown.Forexamplenotallsystemfunctionsaresupportedbyeachsource.Formattingfunctionsinparticulararenotbroadlysupported.
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'
OutofMemory
DiagnosingIssues
98
![Page 99: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/99.jpg)
Outofmemoryerrorscanbedifficulttotrackdown.Inalmostallcases,itisbesttodeterminetheactualmemoryconsumptionutilizingaheapdump-whichcanbeobtainedusingthevmHeapDumpOnOutOfMemoryErroroptionorviaatoolsuchasVisualVM.Youmayalsosimplyincreasethesizeoftheheap,butthatmaysimplydelaytheissuefromreappearing.
Logging
Thequeryplanalonedoesnotprovideafullaccountingofprocessing.Somedecisionsaredelayeduntilexecutionorcanonlybeseenintheserverlogs:
TheENAHANCEDSORTJOINnodemayexecutecanexecuteoneofthreedifferentjoinstrategiesdependingontheactuallyrowcountsfound,thiswillnotbeseenunlessthequeryplanisobtainedattheendofexecution.
Theeffectoftranslationisnotyetaccountedforastheplanshowstheengineformofthequery
Thefulltranslationcanbeseeninwithcommandloggingatatracelevelorwithdebug/traceloggingingeneral.
Thequeryplandoesn’tshowtheexecutionstatsofindividualthesourcequeries,whichisshowninthecommandlog
Theforfullpictureofexecutiondowntoallthebatchfetches,you’lljustneedthefullserverdebug/tracelog
PlanDebugLog
Thelogicalplanoptimizationisrepresentedbytheplanningdebuglogandismoreusefultounderstandwhyplanningdecisionsweremade.
SETSHOWPLANDEBUG
SELECT...
SHOWPLAN
Youwilltypicallynotneedtousethislevelofdetailtodiagnoseissues,butitisusefultoprovidetheplandebuglogtosupportwhenplanningissuesoccur.
DiagnosingIssues
99
![Page 100: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/100.jpg)
MigrationGuideFromTeiid8.xTeiidstrivestomaintainconsistencybetweenallversions,butwhennecessarybreakingconfigurationandVDB/sqlchangesaremade-andthentypicallyonlyformajorreleases.
Youshouldconsultthereleasenotesforcompatibilityandconfigurationchangesfromeachminorversionthatyouareupgradingover.Thisguideexpandsuponthereleasenotesincludedinthekittocoverchangessince8.x.
IfpossibleyoushouldmakeyourmigrationtoTeiid9byfirstusingTeiid8.13.8.13isanon-featuretransitionalreleasethatiseffectivelyTeiid8.12runningonWildFly9.0.2.Seealso8.13MigrationGuide
JRESupportTeiid9.1usesWildFly10.0.0.BoththeserverkitandusageofTeiidEmbeddedwillrequireJava1.8+.Theclientdrivermaystillusea1.6runtime.
Teiid9.0usesWildFly9.0.2.BoththeserverkitandusageofTeiidEmbeddedwillrequireJava1.7+.Theclientdrivermaystillusea1.6runtime.
ConfigurationChanges
YouwillneedtoapplyyourTeiidandotherconfigurationchangesstartingwithanewbaseconfigurationforWildFly,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">
<authenticationsecurity-domain="teiid-security"/>
</transport>
<transportname="odbc"protocol="pg"socket-binding="teiid-odbc">
<authenticationsecurity-domain="teiid-security"/>
<sslmode="disabled"/>
</transport>
Newstandalone.xmlConfiguration
<authenticationsecurity-domain="teiid-security"/>
<transportname="local"/>
<transportname="odata"/>
<transportname="jdbc"protocol="teiid"socket-binding="teiid-jdbc"/>
<transportname="odbc"protocol="pg"socket-binding="teiid-odbc">
<sslmode="disabled"/>
</transport>
MigrationGuideFromTeiid8.x
100
![Page 101: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/101.jpg)
Thedefaultmaximumnumberofsessionswasincreasedto10000toaccommodateforthischange.
Inadditionthereisanewpropertytrust-all-localthatdefaultstotrueandallowsunauthenticatedaccessbylocalpass-throughconnectionsovertheembeddedtransport-thiswaseffectivelythedefaultbehaviorof8.xandbeforewhennosecurity-domainwassetontheembeddedtransport.Youmaychoosetodisallowthattypeofaccessbysettingthepropertytofalseinstead.
Theauthentication-security-domainpropertywillonlyacceptasinglesecuritydomain,andwillnotinterpretthevalueasacommaseparatedlist.Thedefaultbehaviorhasalsochangedforusernames-theyarelongerallowedtobequalifiedbythesecuritydomain.Usetheauthentication-allow-security-domain-qualifierpropertytoallowtheoldbehaviorofacceptingusernamesthataresecuritydomainqualified.
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.
DefaultPrecision/Scale
Ifacolumnisspecifiedwithaprecisionof0orleftasthedefaultinDDLmetadataitwillbetreatedashavingthenominalinternalmaximumvalueof32767.Thismaycausetheprecisionandscaletobereporteddifferently,whichmayhavebeen2147483647insomeplacesor20inJDBCDatabaseMetaData.
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.
MigrationGuideFromTeiid8.x
101
![Page 102: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/102.jpg)
XMLDocumentModel
TheXMLDocumentModelhasbeendeprecated.PleaseconsidermigratingtoODataorutilizingSQL/XMLfunctionsforconstructingdocuments.
Kitting/BuildChanges
AdminJAR
For8.13theentrypointforcreatingremoteadminconnection,AdminFactory,wasmovedintotheteiid-jboss-adminjarratherthanbeinglocatedinteiid-admin.
APIChanges
TheAuthorizationValidatorandPolicyDeciderinterfaceshadminorchanges.AuthorizationValidatorhasanadditionalmethodtodeterminemetadatafiltering,andPolicyDeciderhadisTempAccessablecorrectedtoisTempAccessible.
SemanticversioningrequiredthechangeoftheVDBversionfieldfromanintegertoastring.Thisaffectedthefollowingpublicclasses:
VDBSessionEventListenerVDBImportExecutionContextMetadataRepository
Therearealsoduplicate/deprecatedmethodson:
EventDistributorAdmin
UsingtheTranslatorPropertyannotationwithoutasetternowrequiresthatreadOnly=truebesetontheannotation.
TheJDBCDatabaseMetaDataandCommandContextgetUserNamemethodswillnowreturnjustthebaseusernamewithoutthesecuritydomain.
EmbeddedKit
TheEmbeddedKithasbeenremoved.YoushouldfollowtheEmbeddedExamplestousemaventopullthedependenciesyouneedforyourproject.
Therewereextensivechangesindependencymanagementforhowtheprojectisbuilt.Thesechangesallowedustoremovetheneedforresourceadapterjarsbuiltwiththelibclassifier.Ifyouneedtoreferencetheseartifactsfrommaven,justomittheclassifier.
LegacyDrivers
ThedriversforJRE1.4/1.5systemshavebeendiscontinued.Ifyoustillneedaclientforthoseplatforms,youshouldusetheappropriate8.xdriver.
OData
TheODatav2warbaseduponodata4jhasbeenremoved.YoushouldutilizetheODatav4warserviceinstead.
Thenamesofthewarshavebeenchangedtostripversioninformation-thismakesiteasiertocaptureadeployment-overlayintheconfigurationsuchthatitwon’tbechangedfromoneTeiidversiontothenext.
teiid-odata-odata2.warhasbecometeiid-odata.warteiid-olingo-odata4.warhasbecometeiid-olingo-odata4.war
Tochangepropertiesinanweb.xmlfileoraddotherfilestothedefaultodatawar,youshoulduseadeploymentoverlayinstead.
MigrationGuideFromTeiid8.x
102
![Page 103: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/103.jpg)
Materialization
Thesemanticversioningchangerequiresthematerializationstatustablestochangetheirversioncolumnfromanintegertostring.Boththesourceandthesourcemodelwillneedtobeupdatedwiththecolumntypechange.
MigrationGuideFromTeiid8.x
103
![Page 104: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/104.jpg)
CachingGuideTeiidprovidesseveralcapabilitiesforcachingdataincluding:
1. Materializedviews
2. ResultSetcaching
3. Codetablecaching
Thesetechniquescanbeusedtosignificantlyimproveperformanceinmanysituations.
Withtheexceptionofexternalmaterializedviews,thecacheddataisaccessedthroughtheBufferManager.ForbetterperformancetheBufferManagersettingshouldbeadjustedtothememoryconstraintsofyourinstallation.SeetheCacheTuningformoreonparametertuning.
CachingGuide
104
![Page 105: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/105.jpg)
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
105
![Page 106: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/106.jpg)
/*+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
106
![Page 107: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/107.jpg)
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
107
![Page 108: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/108.jpg)
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
108
![Page 109: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/109.jpg)
Fullcontrolisneededofloadingandrefresh.Internalmaterializationdoesofferseveralsystemsupportedmethodsforrefreshing,butdoesnotgivefullaccesstothematerializedtable.
Controlisneededoverthematerializedtabledefinition.InternalmaterializationdoessupportIndexes,buttheycannotbedirectlycontrolled.Constraintsorotherdatabasefeaturescannotbeaddedtointernalmaterializationtables.
Thedatavolumeislarge.Internalmaterialization(andtemptablesingeneral)havememoryoverheadforeachpage.Aroughguidelineisthattherecanbe100millionrowsinallmaterializedtablesacrossallVDBsforeverygigabyteofheap.
Important
MaterializedviewtablesdefaulttotheVDBscope.Bydefaultifamaterializedviewdefinitiondirectlyortransitivelycontainsanon-deterministicfunctioncall,suchasrandomorhasRole,theresultingtablewillcontainonlytheinitiallyevaluatedvalues.Inmostinstancesyoushouldconsidernestingamaterializedviewwithoutthedeterministicresultsthatisjoinedwithrelevantnon-deterministicvaluesinaparentview.Youmayalsoscopethematerializedviewtobesessionspecific,butthatmaylimitthereuseoftheresultsinmanysituations.
MaterializedViews
109
![Page 110: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/110.jpg)
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.
ExternalMaterialization
110
![Page 111: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/111.jpg)
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
ExternalMaterialization
111
![Page 112: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/112.jpg)
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
ExternalMaterialization
112
![Page 113: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/113.jpg)
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.
ExternalMaterialization
113
![Page 114: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/114.jpg)
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.
Warning
Somedatabases,suchasMySQLwiththeInnoDBbackend,maynotallowalargeprimarykeysuchastheoneforthestatustable.Ifyouexperiencethis,youshouldconsidermakingthefieldsshorter(suchasthetablename),usingadifferentdatabasetoholdthestatus,orusingasmallerindex(forexamplejustovervdbnameandvdbversion).
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',
ExternalMaterialization
114
![Page 115: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/115.jpg)
Ifstagetableisnotdefined,youcandefinetruncatetargettableinbeforeloadscriptanddefineinserttargettableinloadscript:
"teiid_rel:MATVIEW_BEFORE_LOAD_SCRIPT"'executeaccounts.native(''truncatetablematTable'');',
"teiid_rel:MATVIEW_LOAD_SCRIPT"'insertintomatTableselect*frommatviewoptionnocachematview',
Note
Thathowevermaybetoosimplisticbecauseyourindexcreationmaybemoreperformantifdeferreduntilafterthetablehasbeencreated.Alsofullsnapshotrefreshesarebestdonetoastagingtablethenswappingitfortheexistingphysicaltabletoensurethattherefreshdoesnotimpactuserqueriesandtoensurethatthetableisvalidpriortouse.
Forsomesources,theeffectofaRENAMEoperationsmaynotbeperformedatomicallywiththeotherafterloadscriptoperations.Ifthisisthecase,itwillbepossibleforthematerializationtargettabletonotexistwhilebeingqueried.Possibleworkaroundsinclude:
It’spossibletosendasetofcommandstothesourceratherthanasindividualnativequeries.Forexample:'executeaccounts.native(''ALTERTABLEmatTableRENAMETOmatTable_temp;ALTERTABLEstageTableRENAMETOmatTable;ALTERTABLEmatTable_tempRENAMETOstageTable'')'
Useanalternativestrategybaseduponmaintainingjustasingletable,suchasupdatingbaseduponanUPSERT/MERGEandthenapurgeofentriesthatarenolongervalid.
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.
ExternalMaterialization
115
![Page 116: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/116.jpg)
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
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
ExternalMaterialization
116
![Page 117: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/117.jpg)
Appendix-1:DDLforcreatingMatViewStatusTable
h2
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)
);
MariaDB
CREATETABLEstatus
(
VDBNamevarchar(50)notnull,
VDBVersionintegernotnull,
SchemaNamevarchar(50)notnull,
Namevarchar(256)notnull,
TargetSchemaNamevarchar(50),
TargetNamevarchar(256)notnull,
Validbooleannotnull,
LoadStatevarchar(25)notnull,
Cardinalitybigint,
Updatedtimestampnotnull,
LoadNumberbigintnotnull,
PRIMARYKEY(VDBName,VDBVersion,SchemaName,Name)
);
ExternalMaterialization
117
![Page 118: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/118.jpg)
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.
InternalMaterialization
118
![Page 119: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/119.jpg)
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)
InternalMaterialization
119
![Page 120: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/120.jpg)
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.
InternalMaterialization
120
![Page 121: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/121.jpg)
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.
InternalMaterialization
121
![Page 122: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/122.jpg)
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
122
![Page 123: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/123.jpg)
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
123
![Page 124: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/124.jpg)
TranslatorResultsCachingTranslatorscancontributecacheentriesintotheresultsetcacheviatheuseoftheCacheDirectiveobject.Theresultingcacheentriesbehavejustasiftheywerecreatedbyauserquery.SeetheTranslatorCachingAPIformoreonthisfeature.
TranslatorResultsCaching
124
![Page 125: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/125.jpg)
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
125
![Page 126: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/126.jpg)
SELECT*fromvg1,vg2,vg3WHERE…OPTIONNOCACHE
Nocachedresultswillbeusedatall.
SpecificNOCACHE
SELECT*fromvg1,vg2,vg3WHERE…OPTIONNOCACHEvg1,vg3
Onlythevg1andvg3cacheswillbeskipped,vg2oranycachedresultsnestedundervg1andvg3willbeused.
OPTIONNOCACHEmaybespecifiedinprocedureorviewdefinitions.Inthatway,transformationscanspecifytoalwaysusereal-timedataobtaineddirectlyfromsources.
HintsandOptions
126
![Page 127: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/127.jpg)
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
127
![Page 128: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/128.jpg)
ClientDeveloper’sGuideThisguideintendedfordevelopersthataretryingtowrite3rdpartyapplicationsthatinteractwithTeiid.Thiswillguideyouthroughconnectionmechanisms,extensionstoJDBCAPI,ODBC,SSLetc.BeforeonecandelveintoTeiiditisveryimportanttolearnfewbasicconstructsofTeiid,likewhatisVDB?whatisModel?etc.Forthatpleasereadtheshortintroductionherehttp://teiid.jboss.org/basics/
ClientDeveloper’sGuide
128
![Page 129: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/129.jpg)
JDBCSupportTeiidprovidesarobustJDBCdriverthatimplementsmostoftheJDBCAPIaccordingtothelatestspecificationandsupportedJavaversion.MosttoolingdesignedtoworkwithJDBCshouldworkseamlesslywiththeTeiiddriver.Whenindoubt,seeUnsupportedJDBCMethodsforfunctionalitythathasyettobeimplemented.
Ifyou’reneedsgobeyondJDBC,TeiidhasalsoprovidedJDBCExtensionsforasynchhandling,federation,andotherfeatures.
GeneratedKeys
TeiidsupportsreturninggeneratedkeysforJDBCsourcesandfromTeiidtemptableswithSERIALprimarykeycolumns.Howeverthecurrentimplementationwillreturnonlythelastsetofkeysgeneratedandwillreturnthekeyresultsdirectlyfromthesource-noviewprojectionofotherintermediatehandlingisperformed.Formostscenarios(singlesourceinserts)thishandlingissufficient.AcustomsolutionmayneedtobedevelopedifyouareusingaFOREACHROWinsteadoftriggertoprocessyourinsertsandtargetmultipletablesthateachreturngeneratedkeys.ItispossibletodevelopaUDFthatalsomanipulatesthereturnedgeneratedkeys-seetheorg.teiid.CommandContextmethodsdealingwithgeneratedkeysformore.
JDBCSupport
129
![Page 130: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/130.jpg)
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.1.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.1.0.Final</version>
</dependency>
Against
MainclassesintheclientJAR:
org.teiid.jdbc.TeiidDriver-allowsJDBCconnectionsusingtheDriverManagerclass.
org.teiid.jdbc.TeiidDatasource-allowsJDBCconnectionsusingtheDataSourceXADataSourceclass.YoushouldusethisclasstocreatemanagedorXAconnections.
OnceyouhaveestablishedaconnectionwiththeTeiidServer,youcanusestandardJDBCAPIclassestointerrogatemetadataandexecutequeries.
ConnectingtoaTeiidServer
130
![Page 131: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/131.jpg)
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.)
Note hostandportmaybeacommaseparatedlisttospecifymultiplehosts.
LocalConnections
Tomakealocalin-VMconnection,omittheprotocolandhost/port.
URLConnectionProperties
ThefollowingtableshowsallthesupportedconnectionpropertiesthatcanusedwithTeiidJDBCDriverURLconnectionstring,orontheTeiidJDBCDataSourceclass.
Table1.ConnectionProperties
PropertyName Type Description
ApplicationName StringNameoftheclientapplication;allowstheadministratortoidentifytheconnections
FetchSize intSizeoftheresultset;Thedefaultsizeif500.⇐0indicatesthatthedefaultshouldbeused.
partialResultsMode booleanEnable/disablesupportpartialresultsmode.Defaultfalse.SeethePartialResultsModesection.
ConnectingtoaTeiidServer
131
![Page 132: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/132.jpg)
autoCommitTxn String
Onlyappliesonlywhen"autoCommit"issetto"true".ThisdetermineshowaexecutedcommandneedstobetransactionallywrappedinsidetheTeiidenginetomaintainthedataintegrity.
ON-Alwayswrapcommandindistributedtransaction
OFF-Neverwrapcommandindistributedtransaction
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,
ConnectingtoaTeiidServer
132
![Page 133: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/133.jpg)
itswitchestheidentityontheconnection,ifthenewuserisalsoeligibletologintoTeiidotherwiseconnectionfailstoexecute.
useCallingThread boolean
Onlyappliesto"local"connections.Whenthisoptionissetto"true"(thedefault),thenthecallingthreadwillbeusedtoprocessthequery.Iffalse,thenanenginethreadwillbeused.
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.0indicatesnospecifictimeout,butothertimeoutsmayapply.Ifaconnectioncannotbecreatedinapproximatelythethetimeoutvalueanexceptionwillbethrown.Adefaultof0doesnotmeanthattheloginwillwaitindefinitely.Typicallyisanactivevdbcannotbefoundtheloginwillfailatthattime.Localconnectionsthatspecifyavdbversionhowevercanwaitbydefaultforuptoorg.teiid.clientVdbLoadTimeoutMillis.
reportAsViews boolean
IfDatabaseMetaDatawillreportTeiidviewsasaVIEWtabletype.IffalsethenTeiidviewswillbereportedasaTABLE.Defaulttrue.
ConnectingtoaTeiidServer
133
![Page 134: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/134.jpg)
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.
ConnectingtoaTeiidServer
134
![Page 135: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/135.jpg)
NoteAdditionalProperties-AllthepropertiesfromURLConnectionPropertiescanbeusedonDataSourceusingtheAdditionalPropertiessettermethodifthecorrespondingsettermethodisnotalreadyavailable.Forexample,youcanadd"useCallingThread"propertyas<xa-datasource-propertyname="AdditionalProperties">useCallingThread=false</xa-datasource-property>
ConnectingtoaTeiidServer
135
![Page 136: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/136.jpg)
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();
}
}
ConnectingtoaTeiidServer
136
![Page 137: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/137.jpg)
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.api"/>
<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>
ConnectingtoaTeiidServer
137
![Page 138: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/138.jpg)
<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>
<driver>teiid</driver>
<pool>
<prefill>false</prefill>
<use-strict-min>false</use-strict-min>
<flush-strategy>FailingConnectionOnly</flush-strategy>
</pool>
<security>
<user-name>{user}</user-name>
<password>{password}</password>
</security>
</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>
LocalJDBCConnectionIfyouaredeployingyourclientapplicationonthesameWildFlyinstanceastheTeiidruntimeisinstalled,thenyouwillwanttoconfiguretheconnectiontoby-passmakingasocketbasedJDBCconnection.Byusingaslightlydifferentdatasourceconfigurationtomakea"local"connection,theJDBCAPIwilllookupalocalTeiidruntimeinthesameVM.
Warning
SinceDataSourcesstartbeforeTeiidVDBsaredeployed,leavetheminpoolsizeof0forlocalconnections.OtherwiseerrorsmayoccuronthestartupoftheTeiidDataSource.AlsonotethatlocalconnectionsspecifyingaVDBversionwillwaitfortheirVDBtobeloadedbeforeallowingaconnection.SeeloginTimeoutandtheorg.teiid.clientVdbLoadTimeoutMillissystemproperty.
WarningDonotincludeanyadditionalcopyofTeiidjarsintheapplicationclassloadthatisutilizingthelocalconnection.Eveniftheexactsameversionoftheclientjarisincludedinyourapplicationclassloader,youwillfailtoconnecttothelocalconnectionwithaclasscastexception.
ConnectingtoaTeiidServer
138
![Page 139: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/139.jpg)
NoteBydefaultlocalconnectionsusetheircallingthreadtoperformprocessingoperationsratherthanusinganenginethreadwhilethecallingthreadisblocked.TodisablethisbehaviorsettheconnectionpropertyuseCallingThreads=false.Thedefaultistrue,andisrecommendedintransactionalqueries.
Localdatasource
<datasources>
<datasourcejndi-name="java:/teiidDS"pool-name="teiidDS">
<connection-url>jdbc:teiid:{vdb}</connection-url>
<driver>teiid-local</driver>
<pool>
<prefill>false</prefill>
<use-strict-min>false</use-strict-min>
<flush-strategy>FailingConnectionOnly</flush-strategy>
</pool>
<security>
<user-name>{user}</user-name>
<password>{password}</password>
</security>
</datasource>
<drivers>
<drivername="teiid-local"module="org.jboss.teiid">
<driver-class>org.teiid.jdbc.TeiidDriver</driver-class>
<xa-datasource-class>org.teiid.jdbc.TeiidDataSource</xa-datasource-class>
</driver>
</drivers>
</datasources>
ThisisessentiallythesameastheXAconfiguration,but"ServerName"and"PortNumber"arenotspecified.LocalconnectionshaveadditionalfeaturessuchasusingPassthroughAuthentication
ConnectingtoaTeiidServer
139
![Page 140: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/140.jpg)
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>
<datasourcejndi-name="java:/teiidDS"pool-name="teiidDS">
<connection-url>jdbc:teiid:{vdb}@mm://{host}:31000</connection-url>
<driver>teiid</driver>
<pool>
<prefill>false</prefill>
<use-strict-min>false</use-strict-min>
<flush-strategy>FailingConnectionOnly</flush-strategy>
<check-valid-connection-sql>SETNEWINSTANCETRUE</check-valid-connection-sql>
</pool>
<security>
<user-name>{user}</user-name>
<password>{password}</password>
</security>
ConnectingtoaTeiidServer
140
![Page 141: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/141.jpg)
</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>
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.
ConnectingtoaTeiidServer
141
![Page 142: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/142.jpg)
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
ConnectingtoaTeiidServer
142
![Page 143: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/143.jpg)
#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
ConnectingtoaTeiidServer
143
![Page 144: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/144.jpg)
##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)
ConnectingtoaTeiidServer
144
![Page 145: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/145.jpg)
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)
ConnectingtoaTeiidServer
145
![Page 146: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/146.jpg)
#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.
ConnectingtoaTeiidServer
146
![Page 147: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/147.jpg)
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
147
![Page 148: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/148.jpg)
ResultSetLimitationsTYPE_SCROLL_SENSITIVEisnotsupported.
UPDATABLEResultSetsarenotsupported.
ReturningmultipleResultSetsfromProcedureexecutionisnotsupported.
ResultSetLimitations
148
![Page 149: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/149.jpg)
JDBCExtensionsThesearecustomextensionstoJDBCAPIfromTeiidtosupportvariousfeatures.
JDBCExtensions
149
![Page 150: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/150.jpg)
StatementExtensionsTheTeiidstatementextensioninterface,org.teiid.jdbc.TeiidStatement,providesfunctionalitybeyondtheJDBCstandard.Tousetheextensioninterface,simplycastorunwapthestatementreturnedbytheConnection.Thefollowingmethodsareprovidedontheextensioninterface:
Table1.ConnectionProperties
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
150
![Page 151: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/151.jpg)
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
151
![Page 152: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/152.jpg)
}
warning=warning.getNextWarning();
}
Warning
Insomeinstances,typicallyJDBCsources,thesourcenotbeinginitiallyavailablewillpreventTeiidfromautomaticallydeterminingtheappropriatesetofsourcecapabilities.Ifyougetanexceptionindicatingthatthecapabilitiesforanunavailablesourcearenotvalidinpartialresultsmode,thenitmaybenecessarytomanuallysetthedatabaseversionorsimilarpropertyonthetranslatortoensurethatthecapabilitiesareknownevenifthesourceisnotavailable.
JDBCExtensions
152
![Page 153: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/153.jpg)
Non-blockingStatementExecutionJDBCqueryexecutioncanindefinitelyblockthecallingthreadwhenastatementisexecutedoraresultsetisbeingiterated.Insomesituationsyoumaynotwishtohaveyourcallingthreadsheldintheseblockedstates.Whenusingembedded/localconnections,youmayoptionallyusetheorg.teiid.jdbc.TeiidStatementandorg.teiid.jdbc.TeiidPreparedStatementinterfacestoexecutequerieswithacallbackorg.teiid.jdbc.StatementCallbackthatwillbenotifiedofstatementevents,suchasanavailablerow,anexception,orcompletion.Yourcallingthreadwillbefreetoperformotherwork.Thecallbackwillbeexecutedbyanengineprocessingthreadasneeded.Ifyourresultsprocessingisitselfblockingandyouwantqueryprocessingtobeconcurrentwithresultsprocessing,thenyourcallbackshouldimplementonRowhandlinginamulti-threadedmannertoallowtheenginethreadtocontinue.
Non-blockingPreparedStatementExecution
PreparedStatementstmt=c.prepareStatemen(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
153
![Page 154: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/154.jpg)
Sinceresourceconsumptionisexpectedtobedifferentinacontinuousplan,itdoesnotcountagainsttheservermaxactiveplanlimit.Typicallycustomsourceswillbeusedtoprovidedatastreams.SeetheDeveloper’sGuide,inparticularthesectiononReusableExecutionsformore.
Whentheclientwishestoendthecontinuousquery,theStatement.close()orStatement.cancel()methodshouldbecalled.Typicallyyourcallbackwillclosewheneveritnolongneedstoprocessresults.
SeealsotheContinuousStatementCallbackforuseastheStatementCallbackforadditionalmethodsrelatedtocontinuousprocessing.
JDBCExtensions
154
![Page 155: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/155.jpg)
ResultSetExtensionsTheTeiidresultsetextensioninterface,org.teiid.jdbc.TeiidResultSet,providesfunctionalitybeyondtheJDBCstandard.Tousetheextensioninterface,simplycastorunwaparesultsetreturnedbyaTeiidstatement.Thefollowingmethodsareprovidedontheextensioninterface:
Table1.ConnectionProperties
MethodName Description
available
Returnsanestimateoftheminimumnumberofrowsthatcanberead(afterthecurrent)withoutblockingortheendoftheResultSetisreached.
JDBCExtensions
155
![Page 156: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/156.jpg)
ConnectionExtensionsTeiidconnections(definedbytheorg.teiid.jdbc.TeiidConnectioninterface)supportthechangeUsermethodtoreauthenticateagivenconnection.Ifthereauthenticationissuccessfulthecurrentconnectionmybeusedwiththegivenidentity.Existingstatements/resultsetsarestillavailableforuseundertheoldidentity.SeetheJBossASissueJBAS-1429formoreonusingreauthenticationsupportwithJCA.
JDBCExtensions
156
![Page 157: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/157.jpg)
UnsupportedJDBCMethodsBasedupontheJDBCinJDK1.6,thisappendixdetailsonlythoseJDBCmethodsthatTeiiddoesnotsupport.Unlessspecifiedbelow,TeiidsupportsallotherJDBCMethods.
ThosemethodslistedwithoutcommentsthrowaSQLExceptionstatingthatitisnotsupported.
Wherespecified,somelistedmethodsdonotthrowanexception,butpossiblyexhibitunexpectedbehavior.Ifnoargumentsarespecified,thenallrelated(overridden)methodsarenotsupported.Ifanargumentislistedthenonlythoseformsofthemethodspecifiedarenotsupported.
UnsupportedJDBCMethods
157
![Page 158: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/158.jpg)
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-
UnsupportedJDBCMethods
158
![Page 159: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/159.jpg)
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
UnsupportedJDBCMethods
159
![Page 160: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/160.jpg)
UnsupportedClassesandMethodsin"javax.sql"
Classname Methods
RowSet* NotSupported
UnsupportedJDBCMethods
160
![Page 161: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/161.jpg)
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.
Ifyoudonotwishtogloballyenableorg.teiid.backslashDefaultMatchEscape,thenhaveyourODBCclientissue"selectcast(teiid_session_set('backslashDefaultMatchEscape',true)asboolean)"toalterthedefaultbehaviorforjustthecurrentsession.
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.
InstallationBeforeanapplicationcanuseODBC,youmustfirstinstalltheODBCdriveronsamemachinethattheapplicationisrunningonandthencreateaDataSourceName(DSN)thatrepresentsaconnectionprofileforyourTeiidVDB.
Forawindowsclient,seetheWindowsInstallationGuide.
Configuration
Warning
BydefaultTeiidsupportsplaintextpasswordauthenticationforODBC.Iftheclient/serverarenotconfiguredtouseSSLorGSSauthentication,thepasswordwillbesentinplaintextoverthenetwork.IfyouneedsecurepasswordsintransitandarenotusingSSL,thenconsiderinstallingasecuritydomainthatwillacceptsafepasswordvaluesfromtheclient(forexampleencryptedorhashed).
SeetheSecurityGuidefordetailsonconfiguringSSLforandusingKerberoswiththepgtransport.
Forawindowsclient,seetheConfiguringtheDataSourceName.
SeealsoDSNLessConnection.
ODBCSupport
161
![Page 162: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/162.jpg)
ConnectionSettings
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"aredisabled
SSLmode SeeSecurityGuide
UseDeclare/Fetchcursors&FetchMaxCount Shouldbeusedtobettermanageresourceswhenlargeresultsetsareused
Logging/debugsettingscanbeutilizedasneeded.
Settingsthatmanipulatedatatypes,metadata,oroptimizationssuchas"ShowSystemTables","Trueis-1","Backendgeneticoptimizer","ByteaasLongVarBinary","BoolsasChar",etc.areignoredbytheTeiidserverandhavenoclientsideeffect.Ifthereisaneedfortheseoranyothersettingstohaveadefinedaffect,pleaseopenanissuewiththeproduct/project.
Anyothersettingthatdoeshaveaclientsideaffect,suchas"LF<→CR/LFconversion",maybeusedifdesiredbutthereiscurrentlynoserversideusageofthesetting.
TeiidConnectionSettings
MostTeiidspecificconnectionpropertiesdonotmaptoODBCclientconnectionsettings.IfyoufindyourselfinthissituationandcannotusepostconnectionSETstatements,thentheVDBitselfmaytakedefaultconnectionpropertiesforODBC.UseVDBpropertiesoftheformconnection.XXXtocontrolthingslikepartialresultsmode,resultsetcaching,etc.
ODBCSupport
162
![Page 163: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/163.jpg)
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.
InstallingtheODBCDriverClient
163
![Page 164: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/164.jpg)
Carefullyreadit,andcheckthe"IacceptthetermsintheLicenseAgreement",ifyouareagreeingtothelicensingterms.Thenclick"Next".6.Thenextstepofthewizarddisplays.
Ifyouwanttoinstallinadifferentdirectorythanthedefaultthatisalreadyselected,clickthe"Browse"buttonandselectadirectory.Click"Next"tostartinstallingintheselecteddirectory.7.Thenextstepofthewizarddisplays.
InstallingtheODBCDriverClient
164
![Page 165: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/165.jpg)
Thisstepsummarizesthechoicesyouhavemadeinthewizard.Reviewthisinformation.Ifyouneedtochangeanything,youcanusetheBackbuttontoreturntoprevioussteps.Click"Install"toproceed.8.1.Theinstallationwizardcopiesthenecessaryfilestothelocationyouspecified.Whenitfinishes,thefollowingscreendisplays.
Click"Finish"tocomplete.
Other*nixPlatformInstallations
InstallingtheODBCDriverClient
165
![Page 166: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/166.jpg)
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.
InstallingtheODBCDriverClient
166
![Page 167: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/167.jpg)
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.
ConfiguringtheDataSourceName(DSN)
167
![Page 168: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/168.jpg)
Clickon"page2"andmakesuretheoptionsareselectedasshown
1. Click"save"andyoucanoptionallyclick"test"tovalidateyourconnectioniftheTeiidisrunning.YouhaveconfiguredaTeiid’svirtualdatabaseasadatasourceforyourODBCapplications.NowyoucanuseapplicationssuchasExcel,AccesstoquerythedataintheVDB
ConfiguringtheDataSourceName(DSN)
168
![Page 169: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/169.jpg)
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.
ConfiguringtheDataSourceName(DSN)
169
![Page 170: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/170.jpg)
ConfiguringtheDataSourceName(DSN)
170
![Page 171: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/171.jpg)
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
171
![Page 172: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/172.jpg)
ConfiguringConnectionPropertieswithODBCWhenworkingwithODBCconnection,theusercansettheconnectionpropertiesDriverConnection#URLConnectionPropertiesthatareavailableinTeiidbyexecutingthecommandlikebelow.
SET<property-name>TO<property-value>
forexampletoturnontheresultsetcachingyoucanissue
SETresultSetCacheModeTO'true'
AnotheroptionistosetthisasVDBpropertyinvdb.xmlfileas
<vdbname="...">
<propertyname="connection.resultSetCacheMode"value="true"/>
...
</vdb>
ODBCConnectionProperties
172
![Page 173: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/173.jpg)
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.
TeiidprovidesODataVersion4.0support.LegacyODataVersion2.0supporthasbeenremoved,butcouldbemaintainedasit’sownproject-pleasecontactthecommunityifyoustillneedthisfeatureandwanttomaintainit.
ODataSupport
173
![Page 174: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/174.jpg)
ODataVersion4.0SupportTeiidstrivestobecompliantwiththeODataspecification.TherestofthischapterhighlightsomespecificsofODataandTeiid’ssupport,butyoushouldalsoconsultthespecification.
HowtoAccessthedata?
Forexample,ifyouhaveavdbbynamenorthwinddeployedthathasacustomerstableinaNWmodel,thenyoucanaccessthattablewithanHTTPGETviatheURL:
http://localhost:8080/odata/northwind/NW/customers
thiswouldbeakintomakingaJDBC/ODBCconnectionandissuingtheSQL:
SELECT*FROMNW.customers
Note Usecorrectcase(upperorlower)intheresourcepath.UnlikeSQL,thenamesusedintheURIascase-sensitive.
ThereturnedresultsfromODataquerycanbeinAtom/AtomPubXMLorJSONformat.JSONresultsarereturnedbydefault.
QueryBasicsUserscansubmitpredicateswithalongtheirquerytofiltertheresults:
http://localhost:8080/odata/northwind/NW/customers?$filter=nameeq'bob'
NoteSpacesaround'eq'areforreadabilityoftheexampleonly;inrealURLstheymustbepercent-encodedas%20.ODatamandatespercentencodingforallspacesinURLs.http://docs.oasis-open.org/odata/odata/v4.0/odata-v4.0-part2-url-conventions.html
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=nameeq'bob'&$format=xml
ODataallowsforqueryingnavigationsfromoneentitytoanother.Anavigationissimilartotheforeignkeyrelationshipsinrelationaldatabases.
Forexample,ifthecustomerstablehasanexportedkeytotheorderstableonthecustomersprimarykeycalledthecustomer_fk,thenanODataGETcouldbeissuedlike:
ODataVersion4.0Support
174
![Page 175: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/175.jpg)
http://localhost:8080/odata/northwind/NW/customers(1234)/customer_fk?$filter=orderdategtdatetime'2012-12-31T2
1:23:38Z'
thiswouldbeakintomakingaJDBC/ODBCconnectionandissuingtheSQL:
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".
ODataVersion4.0Support
175
![Page 176: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/176.jpg)
ExamplePUTUpdateofCustomer
PUT/service.svc/Customers('ALFKI')HTTP/1.1
Host:host
Content-Type:application/josn
Accept:application/json
{
"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
Accept:application/json
Security
BydefaultODataaccessissecuredusingHTTPBasicauthentication.TheuserwillbeauthenticatedagainstTeiid’sdefaultsecuritydomain"teiid-security".Usersareexpectedtohavetheodatarole.Besuretocreateuserwiththisrolewhenyouareusingadd-user.shscripttocreateanewuser.
However,ifyouwishtochangethesecuritydomainuseadeployment-overlaytooverridetheweb.xmlfileintheodata4fileinthe<modules>/org/jboss/teiid/main/deploymentsdirectory.
ODataWARcanalsosupportKerberos,SAMLandOAuth2authentications,forconfiguringthethesesecurityschemespleaseseeSecurityGuide
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.No
ODataVersion4.0Support
176
![Page 177: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/177.jpg)
invalid-xml10-character-replacement value(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
<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.
searchisnotsupported
deltaprocessingisnotsupported
data-aggregationextensiontospecificationisnotsupported.
$itusageislimitedtoonlyprimitivecollectionproperties
ClientToolsforAccessODataaccessisreallywheretheusercomesin,dependinguponyourprogrammingmodelandneedstherearevariouswaysyouwriteyouraccesslayerintoOData.Thefollowingaresomesuggestions:
YourBrowser:TheODataExplorerisanonlinetoolforbrowsinganODatadataservice.
ODataVersion4.0Support
177
![Page 178: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/178.jpg)
Olingo:IsaJavaframeworkthatsupportsODataV4,hasbothconsumerandproducerframework.
Microsofthasvarious.Netbasedlibraries,seehttp://odata.github.io/
WindowsDesktop:LINQPadisawonderfultoolforbuildingODataqueriesinteractively.Seehttps://www.linqpad.net/
ShellScripts:useCURLtool
Forlatestinformationotherframeworksandtoolsavailablepleaseseehttp://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
ODataVersion4.0Support
178
![Page 179: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/179.jpg)
UsingTeiidwithHibernate
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:
UsingTeiidwithHibernate
179
![Page 180: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/180.jpg)
<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.
UsingTeiidwithHibernate
180
![Page 181: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/181.jpg)
UsingTeiidwithEclipseLink
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.
UsingTeiidwithEclipseLink
181
![Page 182: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/182.jpg)
GeoServerIntegrationGeoServerisanopensourceserverforgeospatialdata.ItcanbeintegratedwithTeiidtoservegeospatialdatafromavarietyofsources.
Prerequisites
HaveGeoServerinstalled.BydefaultthiswillbeinadifferentcontainerthantheTeiidWildFlyinstance,butitshouldbepossibletodeployintothesameWildFlyinstance.
YourTeiidinstallationshouldalreadybesetupforODBCaccess.Thisallowsthebuilt-insupportofGeoServerforPostGIS/PostgreSQLtobeused.
HaveaVDBdeployedthatexposesoneormoretablescontaininganappropriateGeometrycolumn.
a. TheTeiidsystemtableGEOMETY_COLUMNSwillbeusedbyGeoServer.Pleaseensurethattherelevantgeometrycolumnshavetheappropriatesridandcoord_dimensions,whichmayrequiresettingthe{http://www.teiid.org/translator/spatial/2015}sridand{http://www.teiid.org/translator/spatial/2015}coord_dimensionextensionpropertyonthegeometrycolumn.
GeoServerConfiguration
ThisprocesswillneedtoberepeatedforeachVDBschemayouareexposingthatcontainsgeospatialdata.
1. UsingtheGeoServeradminwebapplication,selectStores→AddnewStore.UnderVectorDataSources,selectPostGIS.
2. Usingthenon-JNDIconnection,fillintheTeiidserverhost,ODBCport,database(VDBNamewithoptionalversion),user,andpassword,schema(schema/modelfromthetargetVDB).
i. IfyourVDBscontaintargetschemaortablenameswith%or_,Teiidmustbeconfiguredtousethesamedefaultlikeescapecharacter'\'asPostgreSQLtoproperlyrespondtometadataqueries.Eitherthesystempropertyorg.teiid.backslashDefaultMatchEscapemustbesettotrueortheTeiidsessionvariablebackslashDefaultMatchEscapemustbesettotrue-forexampleenter"selectcast(teiid_session_set('backslashDefaultMatchEscape',true)asboolean)"inthe"SessionstartupSQL"toconfigurejustthisGeoServerconnectionpool.
3. FollowthetypicalGeoServerinstructionsforcreatingaLayerbasedupontheTeiidstore.
i. NotethatthePostGISfunctionST_Estimated_ExtentisnotsupportedbyTeiidandtheexecutionwillbeshowninthelogsasanerrorwhenselectingtocomputetheboundingboxfromthedata.
AdditionalConsiderations
IfyouareintegratingaPostgreSQLsource,youmustnotre-exposethegeometry_columnstable.ThisisbecauseGeoServermakesunqualifiedqueriesthatreferencegeometry_columnsandthequeryshouldresolveagainsttheTeiidsystemtableinstead.
GeoServerIntegration
182
![Page 183: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/183.jpg)
ReauthenticationTeiidallowsforconnectionstobereauthenticatedsothattheidentityontheconnectioncanbechangedratherthancreatingawholenewconnection.IfusingJDBC,seethechangeUserConnectionextension.IfusingODBC,orsimplyneedastatementbasedmechanismforreauthentication,seealsotheSETStatementforSESSIONAUTHORIZATION.
Reauthentication
183
![Page 184: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/184.jpg)
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
184
![Page 185: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/185.jpg)
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
185
![Page 186: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/186.jpg)
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
186
![Page 187: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/187.jpg)
SETStatement
187
![Page 188: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/188.jpg)
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
188
![Page 189: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/189.jpg)
TransactionsTeiidsupportsthreetypesoftransactionsfromaclientperspective–global,local,andrequestlevel.AllareimplementedbytheTeiidServerasXAtransactions.SeetheJTAspecificationformoreonXATransactions.
Transactions
189
![Page 190: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/190.jpg)
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
190
![Page 191: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/191.jpg)
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
191
![Page 192: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/192.jpg)
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
192
![Page 193: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/193.jpg)
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>
}
UsingGlobalTransactions
193
![Page 194: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/194.jpg)
WiththeuseofglobaltransactionsmultipleTeiidXAConnectionsmayparticipateinthesametransaction.TheTeiidJDBCXAResource"isSameRM"methodreturns"true"onlyifconnectionsaremadetothesameserverinstanceinacluster.IftheTeiidconnectionsaretodifferentserverinstancesthentransactionalbehaviormaynotbethesameasiftheyweretothesameclustermember.Forexample,iftheclienttransactionmanagerusesthesameXIDforeachconnection(whichitshouldnotsinceisSameRMwillreturnfalse),duplicateXIDexceptionsmayarisefromthesamephysicalsourceaccessedthroughdifferentclustermembers.Morecommonlyiftheclienttransactionmanagerusesadifferentbranchidentifierforeachconnection,issuesmayarisewithsourcesthatlockorisolatechangesbaseduponbranchidentifiers.
UsingGlobalTransactions
194
![Page 195: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/195.jpg)
Restrictions
ApplicationRestrictions
Theuseofglobal,local,andrequestleveltransactionsareallmutuallyexclusive.Requestleveltransactionsonlyapplywhennotinaglobalorlocaltransaction.Anyattempttomixglobalandlocaltransactionsconcurrentlywillresultinanexception.
EnterpriseInformationSystem(EIS)Support
TheunderlyingresourceadaptorsthatrepresenttheEISsystemandtheEISsystemitselfmustsupportXAtransactionsiftheywanttoparticipateindistributedXAtransactionthroughTeiid.IfsourcesystemdoesnotsupporttheXA,thenitcannotparticipateinthedistributedtransaction.However,thesourceisstilleligibletoparticipateindataintegrationwithouttheXAsupport.
TheparticipationintheXAtransactionisautomaticallydeterminedbasedontheresourceadaptorsXAcapability.Itisuser’sresponsibilitytomakesurethattheyconfigureaXAresourcewhentheyrequirethemtoparticipateindistributedtransaction.
Restrictions
195
![Page 196: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/196.jpg)
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
![Page 197: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/197.jpg)
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
![Page 198: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/198.jpg)
DevelopingJEEConnectors
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.
DevelopingJEEConnectors
198
![Page 199: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/199.jpg)
ConnectorEnvironmentSetupTosetuptheenvironmentfordevelopingacustomconnector,youhave2options:
1. Manuallysetupthebuildenvironment-structure,frameworkclasses,andresources.
2. UsetheTeiidConnectorArchetypetemplatetogeneratetheinitialproject.
ConnectorEnvironmentSetup
199
![Page 200: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/200.jpg)
BuildEnvironmentForEclipseusers(withoutmavenintegration),createajavaprojectandadddependenciestoteiid-common-core,teiid-apiandJEEconnector-apijars.
Formavenusersaddthefollowingasyourdependencies:
<?xmlversion="1.0"encoding="UTF-8"?>
<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>
<groupId>org.jboss.teiid</groupId>
<artifactId>teiid-api</artifactId>
<scope>provided</scope>
</dependency>
<dependency>
<groupId>org.jboss.teiid</groupId>
<artifactId>teiid-common-core</artifactId>
<scope>provided</scope>
</dependency>
<dependency>
<groupId>javax.resource</groupId>
<artifactId>connector-api</artifactId>
<scope>provided</scope>
</dependency>
</dependencies>
</project>
Wherethe${teiid-version}propertyshouldbesettotheexpectedversion,suchas9.1.0.Final.YoucanfindTeiidartifactsintheJBossmavenrepository.The$\{version.connector.api}versionlastusedwas1.5.
ConnectorEnvironmentSetup
200
![Page 201: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/201.jpg)
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
ConnectorEnvironmentSetup
201
![Page 202: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/202.jpg)
-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/\
-DarchetypeGroupId=org.jboss.teiid.arche-types\
-DarchetypeArtifactId=connector-archetype\
-DarchetypeVersion=8.7.1\
-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.
ConnectorEnvironmentSetup
202
![Page 203: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/203.jpg)
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();
}
}
ImplementingtheTeiidFramework
203
![Page 204: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/204.jpg)
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.
ImplementingtheTeiidFramework
204
![Page 205: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/205.jpg)
ForeveryattributedefinedinsidetheyourManagedConnectionFactoryclass,definethefollowingXMLconfigurationforthatattributeinsidethe"ra.xml"file.ThesepropertiesareusedbyusertoconfigureinstanceofthisConnectorinsideaContainer.Also,duringthestartuptheContainerreadsthesepropertiesfromthisfileandknowshowtoinjectprovidedvaluesinthedatasourcedefinitionintoaninstanceof"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.
ImplementingtheTeiidFramework
205
![Page 206: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/206.jpg)
ra.xmlfileTemplateThisappendixcontainsanexampleofthera.xmlfilethatcanbeusedasatemplatewhencreatinganewConnector.
<?xmlversion="1.0"encoding="UTF-8"?>
<connectorxmlns="http://java.sun.com/xml/ns/j2ee"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
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>
<!--repeatforeveryconfigurationproperty-->
<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>
<!--usethebelowasisifyouusedtheConnectionFactoryinterface-->
<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>
</connection-definition>
<transaction-support>NoTransaction</transaction-support>
<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>
ImplementingtheTeiidFramework
206
![Page 207: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/207.jpg)
</resourceadapter>
</connector>
$\{…}indicatesavaluetobesuppliedbythedeveloper.
ImplementingtheTeiidFramework
207
![Page 208: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/208.jpg)
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
![Page 209: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/209.jpg)
AddingDependentLibrariesAddMANIFEST.MFfileintheMETA-INFdirectory,andthefollowinglinetoaddthecoreTeiidAPIdependenciesforresourceadapter.
Dependencies:org.jboss.teiid.common-core,org.jboss.teiid.api,javax.api
Ifyourresourceadapterdependsuponanyotherthirdpartyjarfiles,.dllor.sofilestheycanbeplacedattherootoftherarfile.IfanyoftheselibrariesarealreadyavailableasmodulesinWildFly,thenyoucanaddthemodulenametotheaboveMANIFEST.MFfiletodefineasdependency.
PackagingtheAdapter
209
![Page 210: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/210.jpg)
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.
<!--Ifsusbsytemisalreadydefined,onlycopythecontentsunderitandedittosuityourneeds-->
<subsystemxmlns="urn:jboss:domain:resource-adapters:1.0">
<resource-adapters>
<resource-adapter>
<archive>teiid-connector-sample.rar</archive>
<transaction-support>NoTransaction</transaction-support>
<connection-definitions>
<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>
</connection-definition>
</connection-definitions>
</resource-adapter>
</resource-adapters>
</subsystem>
Therearelotmorepropertiesthatyoucandefineforpooling,transactions,security,etc.,inthisfile.ChecktheWildFlydocumentationforalltheavailableproperties.
Alternatively,youcanusethewebbased""admin-console"configurationandmonitoringprogram,tocreateanewConnectionFactory.HaveyourRARfilenameandneededconfigurationpropertieshandyandfilloutwebformtocreatetheConnectionFactory.
DeployingtheAdapter
210
![Page 211: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/211.jpg)
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
![Page 212: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/212.jpg)
TranslatorEnvironmentSetupTosetuptheenvironmentfordevelopingacustomtranslator,youhave2options;
1. Manuallysetupthebuildenvironment-structure,frameworkclasses,andresources.
2. UsetheTeiidTranslatorArchetypetemplatetogeneratetheinitialproject.
EnvironmentSetup
212
![Page 213: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/213.jpg)
SettingupthebuildenvironmentForEclipseusers(withoutmavenintegration),createajavaprojectandadddependenciesto"teiid-common-core","teiid-api"andJEE"connector-api"jars.
Formavenusersaddthefollowingasyourdependencies:
<dependencies>
<dependency>
<groupId>org.jboss.teiid</groupId>
<artifactId>teiid-api</artifactId>
<version>${teiid-version}</version>
<scope>provided</scope>
</dependency>
<dependency>
<groupId>org.jboss.teiid</groupId>
<artifactId>teiid-common-core</artifactId>
<version>${teiid-version}</version>
<scope>provided</scope>
</dependency>
<dependency>
<groupId>javax.resource</groupId>
<artifactId>connector-api</artifactId>
<version>${version.connector.api}</version>
<scope>provided</scope>
</dependency>
</dependencies>
Wherethe${teiid-version}propertyshouldbesettotheexpectedversion,suchas9.1.0.Final.YoucanfindTeiidartifactsintheJBossmavenrepository.The$\{version.connector.api}versionlastusedwas1.5.
EnvironmentSetup
213
![Page 214: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/214.jpg)
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/\
-DarchetypeGroupId=org.jboss.teiid.arche-types\
-DarchetypeArtifactId=translator-archetype\
-DarchetypeVersion=8.7.1\
-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
![Page 215: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/215.jpg)
-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/\
-DarchetypeGroupId=org.jboss.teiid.arche-types\
-DarchetypeArtifactId=translator-archetype\
-DarchetypeVersion=8.7.1\
-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
![Page 216: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/216.jpg)
ImplementingtheFramework
ImplementingtheFramework
216
![Page 217: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/217.jpg)
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
ImplementingtheFramework
217
![Page 218: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/218.jpg)
CommandLanguage
Language
TeiidsendscommandstoyourTranslatorinobjectform.Theseclassesarealldefinedinthe"org.teiid.language"package.TheseobjectscanbecombinedtorepresentanypossiblecommandthatTeiidmaysendtotheTranslator.However,itispossibletonotifyTeiidthatyourTranslatorcanonlyacceptcertainkindsofconstructsviathecapabilitiesdefinedonthe"ExecutionFactory"class.RefertoTranslatorCapabilitiesformoreinformation.
ThelanguageobjectsallextendfromtheLanguageObjectinterface.Languageobjectsshouldbethoughtofasatreewhereeachnodeisalanguageobjectthathaszeroormorechildlanguageobjectsoftypesthataredependentonthecurrentnode.
AllcommandssenttoyourTranslatorareintheformoftheselanguagetrees,wheretherootofthetreeisasubclassofCommand.Commandhasseveralsub-classes,namely:
QueryExpression
Insert-alsorepresentsanupsert,seetheisUpsertflag.
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.
ImplementingtheFramework
218
![Page 219: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/219.jpg)
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
ImplementingtheFramework
219
![Page 220: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/220.jpg)
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.
ImplementingtheFramework
220
![Page 221: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/221.jpg)
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
ImplementingtheFramework
221
![Page 222: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/222.jpg)
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
ImplementingtheFramework
222
![Page 223: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/223.jpg)
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();
ImplementingtheFramework
223
![Page 224: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/224.jpg)
ConnectionstoSource
Obtainingconnections
Theextended"ExecutionFactory"mustimplementthegetConnection()methodtoallowtheConnectorManagertoobtainaconnection.
ReleasingConnections
OncetheConnectorManagerhasobtainedaconnection,itwillusethatconnectiononlyforthelifetimeoftherequest.Whentherequesthascompleted,thecloseConnection()methodcalledonthe"ExecutionFactory".Youmustalsooverridethismethodtoproperlyclosetheconnection.
Incases(suchaswhenaconnectionisstatefulandexpensivetocreate),connectionsshouldbepooled.IftheresourceadapterisJEEJCAconnectorbased,thenpoolingisautomaticallyprovidedbytheWildFlycontainer.IfyourresourceadapterdoesnotimplementtheJEEJCA,thenconnectionpoolingsemanticsarelefttotheusertodefineontheirown.
ImplementingtheFramework
224
![Page 225: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/225.jpg)
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.
ImplementingtheFramework
225
![Page 226: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/226.jpg)
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
ImplementingtheFramework
226
![Page 227: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/227.jpg)
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
ImplementingtheFramework
227
![Page 228: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/228.jpg)
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.
ImplementingtheFramework
228
![Page 229: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/229.jpg)
Yourconnectorimplementationmaychoosetodonothinginresponsetothiscancellationmessage.Inthisinstance,Teiidwillcallclose()ontheexecutionobjectaftercurrentprocessinghascompleted.Implementingthecancel()methodallowsforfasterterminationofqueriesbeingprocessedandmayallowtheunderlyingdatasourcetoterminateitsoperationsfasteraswell.
ImplementingtheFramework
229
![Page 230: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/230.jpg)
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;
}
ImplementingtheFramework
230
![Page 231: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/231.jpg)
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();
ImplementingtheFramework
231
![Page 232: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/232.jpg)
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";
ImplementingtheFramework
232
![Page 233: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/233.jpg)
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.
ImplementingtheFramework
233
![Page 234: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/234.jpg)
ImplementingtheFramework
234
![Page 235: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/235.jpg)
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.
ImplementingtheFramework
235
![Page 236: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/236.jpg)
ImplementingtheFramework
236
![Page 237: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/237.jpg)
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
SelfJoinsAliasedGroupsandatleastoneofthejointypesupports.
TranslatorcansupportaselfjoinbetweentwoaliasedversionsofthesameTable.
OuterJoins TranslatorcansupportLEFTandRIGHTOUTERJOIN.
FullOuterJoins TranslatorcansupportFULLOUTERJOIN.
DependentJoins Basejoinandcriteriasupport
Translatorsupportskeysetdependentjoinpushdown.SeeDependentJoinPushdown.WhensettheMaxDependentInPredicatesandMaxInCriteriaSizevaluesarenotusedbytheengine,ratherallindependentvaluesaremadeavailabletothepushdowncommand.
Translatorsupportsfulldependentjoinpushdown.SeeDependentJoinPushdown.WhensettheMaxDependentInPredicatesand
ImplementingtheFramework
237
![Page 238: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/238.jpg)
Basejoinandcriteriasupport
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.
ImplementingtheFramework
238
![Page 239: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/239.jpg)
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.
GroupByMultipleDistinctAggregates GroupByTranslatorcansupportGROUPBYtocreatemultipledistinctaggregates(SeeIMPALA-110).
Having GroupBy TranslatorcansupporttheHAVINGclause.
AggregatesAvg TranslatorcansupporttheAVGaggregatefunction.
AggregatesCount TranslatorcansupporttheCOUNTaggregatefunction.
ImplementingtheFramework
239
![Page 240: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/240.jpg)
AggregatesCountStarTranslatorcansupporttheCOUNT(*)aggregatefunction.
AggregatesDistinct Atleastoneoftheaggregatefunctions.
TranslatorcansupportthekeywordDISTINCTinsideanaggregatefunction.Thiskeywordindicatesthatduplicatevalueswithinagroupofrowswillbeignored.
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
ImplementingtheFramework
240
![Page 241: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/241.jpg)
FunctionsInGroupBy GroupBy Translatorcansupportnon-columnreferencegroupingexpressions.
InsertWithQueryExpression TranslatorsupportsINSERTstatementswithvaluesspecifiedbyanQueryExpression.
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.
Upsert Translatorsupportsanupsertstyleinsert.
NotethatanypushdownsubquerymustitselfbecompliantwiththeTranslatorcapabilities.
CommandForm
ImplementingtheFramework
241
![Page 242: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/242.jpg)
ThemethodExecutionFactory.useAnsiJoin()shouldreturntrueiftheTranslatorpreferstheuseofANSIstylejoinstructureforjointreesthatcontainonlyINNERandCROSSjoins.
ThemethodExecutionFactory.requiresCriteria()shouldreturntrueiftheTranslatorrequirescriteriaforanyQuery,Update,orDelete.ThisisareplacementforthemodelsupportpropertyWhereAll.
ScalarFunctions
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);
...
}
PhysicalLimits
ThemethodExecutionFactory.getMaxInCriteriaSize()canbeusedtospecifythemaximumnumberofvaluesthatcanbepassedinanINcriteria.ThisisanimportantconstraintasanINcriteriaisfrequentlyusedtopasscriteriabetweenonesourceandanotherusingadependentjoin.
ThemethodExecutionFactory.getMaxDependentInPredicates()isusedtospecifythemaximumnumberofINpredicates(ofatmostMaxInCriteriaSize)thatcanbepassedaspartofadependentjoin.Forexampleifthereare10000valuestopassaspartofthedependentjoinandaMaxInCriteriaSizeof1000andaMaxDependentInPredicatessettingof5,thenthedependentjoinlogicwillformtwosourcequerieseachwith5INpredicatesof1000valueseachcombinedbyOR.
ThemethodExecutionFactory.getMaxFromGroups()canbeusedtospecifythemaximumnumberofFROMClausegroupsthatcanusedinajoin.-1indicatesthereisnolimit.
ImplementingtheFramework
242
![Page 243: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/243.jpg)
UpdateExecutionModes
ThemethodExecutionFactory.supportsBatchedUpdates()canbeusedtoindicatethattheTranslatorsupportsexecutingtheBatchedUpdatescommand.
ThemethodExecutionFactory.supportsBulkUpdate()canbeusedtoindicatethattheTranslatoracceptsupdatecommandscontaingmultivaluedLiterals.
Notethatifthetranslatordoesnotsupporteitheroftheseupdatemodes,thequeryenginewillcompensatebyissuingtheupdatesindividually.
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.
ImplementingtheFramework
243
![Page 244: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/244.jpg)
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
<?xmlversion="1.0"encoding="UTF-8"standalone="yes"?>
<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
ImplementingtheFramework
244
![Page 245: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/245.jpg)
}
@TranslatorProperty(display="HeaderRowNumber",category=PropertyType.IMPORT,description="Rownumberthat
containstheheaderinformation")
publicintgetHeaderRowNumber(){
returnheaderRowNumber;
}
publicvoidsetHeaderRowNumber(intheaderRowNumber){
this.headerRowNumber=headerRowNumber;
}
}
Belowisanexampleshowinghowtouseimportpropertieswithavdb.xmlfile
<?xmlversion="1.0"encoding="UTF-8"standalone="yes"?>
<vdbname="vdb"version="1">
<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.
ImplementingtheFramework
245
![Page 246: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/246.jpg)
..
}
}
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)
ImplementingtheFramework
246
![Page 247: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/247.jpg)
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
ExtendingTheJDBCTranslator
247
![Page 248: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/248.jpg)
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.
ExtendingTheJDBCTranslator
248
![Page 249: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/249.jpg)
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.
ExtendingTheJDBCTranslator
249
![Page 250: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/250.jpg)
ExtendingTheJDBCTranslator
250
![Page 251: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/251.jpg)
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"/>
<!--anycustompropertiesyoumayhaveonyourcustomtranslator-->
</translator>
Fromthepreviousexamplethetranslatortypeiscustom-delegator.Nowmy-translatorcanbeusedasatranslator-nameonasourceandwillproxyallcallstowhateverdelegateinstanceyouassign.
Note Notethatthedelegateinstancecanbeanytranslatorinstance,whetherconfiguredbyit’sowntranslatorentryorjustthenameofastandardtranslatortype.
DelegatingTranslator
251
![Page 252: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/252.jpg)
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
![Page 253: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/253.jpg)
AddingDependentModulesAddaMANIFEST.MFfileintheMETA-INFdirectory,andthecoreTeiidAPIdependenciesforresourceadapterwiththefollowingline.
Dependencies:org.jboss.teiid.common-core,org.jboss.teiid.api,javax.api
Ifyourtranslatordependsuponanyotherthirdpartyjarfiles,ensureamoduleexistsandaddthemodulenametotheaboveMANIFEST.MFfile.
Packaging
253
![Page 254: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/254.jpg)
DeploymentAtranslatorJARfilecanbedeployedintoTeiidServerintwodifferentways
AsWildFlymodule
Createamoduleunder"jboss-as/modules"directoryanddefinethetranslatornameandmodulenameintheteiidsubsysteminstandalone-teiid.xmlfileordomain-teiid.xmlfileandrestarttheserver.ThedependentTeiidoranyotherjavaclasslibrariesmustbedefinedinmodule.xmlfileofthemodule.Forproductionprofilesthisisrecommended.
AsJARdeployment
FordevelopmenttimeorquickdeploymentyoucandeploythetranslatorJARusingtheCLIorAdminShelloradminconsoleprograms.WhenyoudeployinJARformthedependenciestoTeiidjavalibrariesandanyotherthirdpartylibrariesmustbedefinedunderMETA-INF/MANIFEST.MFfile.
Deployment
254
![Page 255: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/255.jpg)
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
![Page 256: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/256.jpg)
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
SourceSupportedFunctions
256
![Page 257: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/257.jpg)
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"/>
<metadatatype="DDL"><![CDATA[
CREATEFOREIGNFUNCTIONSCORE(valinteger)RETURNSinteger;
....(othertables,proceduresetc)
]]>
</metadata>
</model>
</vdb>
Bydefaultwhenasourcecanprovidemetadata,theSourcemodel’smetadataisautomaticallyretrievedfromthesourceiftheywereJDBC,File,WebService.TheFileandWebServicesourcesarestatic,soonecannotaddadditionalmetadataonthem.HoweverontheJDBCsourcesyoucanretrievethemetadatafromsourceandthenusercanappendadditionalmetadataontopofthem.Forexample
<vdbname="{vdb-name}"version="1">
<modelname="{model-name}"type="PHYSICAL">
<sourcename="AccountsDB"translator-name="oracle"connection-jndi-name="java:/oracleDS"/>
<metadatatype="NATIVE,DDL"><![CDATA[
CREATEFOREIGNFUNCTIONSCORE(valinteger)RETURNSinteger;
]]>
</metadata>
</model>
</vdb>
TheaboveexampleusesNATIVEmetadatatype(NATIVEisthedefaultforsource/physicalmodels)firsttoretrieveschemainformationfromsource,thenusesDDLmetadatatypetoaddadditionalmetadata.OnlymetadatanotavailableviatheNATIVEtranslatorlogicwouldneedtobespecifiedviaDDL.
Alternatively,ifyouareusingcustomMetadataRepositorywithyourVDB,thenprovidethe"function"metadatadirectlyfromyourimplementation.ex.
<vdbname="{vdb-name}"version="1">
<modelname="{model-name}"type="PHYSICAL">
<sourcename="AccountsDB"translator-name="oracle"connection-jndi-name="java:/oracleDS"/>
<metadatatype="{metadata-repo-module}"></metadata>
</model>
</vdb>
Intheaboveexample,usercanimplementMetadataRepositoryinterfaceandpackagetheimplementationclassalongwithitsdependenciesinaWildFlymoduleandsupplythemodulenameintheaboveXML.FormoreinformationonhowtowriteaMetadataRepositoryrefertoCustomMetadataRepository.
SourceSupportedFunctions
257
![Page 258: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/258.jpg)
SupportforUser-DefinedFunctions(Non-Pushdown)Todefineanon-pushdownfunction,aJavafunctionmustbeprovidedthatmatchestheVDBdefinedmetadata.UserDefinedFunction(orUDF)andUserDefinedAggregateFunction(orUDAF)maybecalledatruntimejustlikeanyotherfunctionoraggregatefunctionrespectively.
MetadatainDesigner
AuserdefinedfunctioncreatedonanyVDBonviewmodelbycreatingaFunctionjustasabasetable.YouwouldrequirealltheinformationdefinedonUserDefinedFunctionstocreateaUDF.MakesureyouprovidetheJAVAcodeimplementationdetailsinthepropertiesdialogfortheUDF.
MetadatawithoutDesigner
WhendefiningthemetadatawithoutDesigner,youcandefineaUDForUDAF(UserDefinedAggregateFunction)asshownbelow.
<vdbname="{vdb-name}"version="1">
<modelname="{model-name}"type="VIRTUAL">
<metadatatype="DDL"><![CDATA[
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.
SupportforUser-DefinedFunctions(Non-Pushdown)
258
![Page 259: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/259.jpg)
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
packageorg.something;
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
packageorg.something;
publicclassSessionInfo
{
/**
*@paramcontext
SupportforUser-DefinedFunctions(Non-Pushdown)
259
![Page 260: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/260.jpg)
*@returnthecreatedTimestamp
*/
publicstaticTimestampsessionCreated(CommandContextcontext)
{
returnnewTimestamp(context.getSession().getCreatedTime());
}
}
ThecorrespondingUDFwouldbedeclaredasTimestampsessionCreated().
PostCodeActivities
AftercodingthefunctionsyoushouldcompiletheJavacodeintoaJavaArchive(JAR)file.
ZipDeployment
TheJARfilemaybeplacedinyourVDBunderthe"/lib"directory.ItwillautomaticallybeusedfortheVDBclassloaderclasspathwhendeployed.
ASModule
CreateaWildFlymodulewiththeJARfileunder<jboss-as>/modulesdirectoryanddefinethemoduleonthe-vdb.xmlfileasshownbelowexample
<vdbname="{vdb-name}"version="1">
<propertyname="lib"value="{module-name}"></property>
...
</vdb>
Thelibpropertyvaluemaycontainaspacedelimitedlistofmodulenamesifmorethanonedependencyisneeded.
SupportforUser-DefinedFunctions(Non-Pushdown)
260
![Page 261: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/261.jpg)
ArchetypeTemplateUDFProjectOnewaytostartdevelopingacustomuserdefinedfunction(UDF)istocreateaprojectusingtheTeiidUDFarchetypetemplate.Whentheprojectiscreatedfromthetemplate,itwillcreateamavenprojectthatcontainsanexamplejavaclassandtheassemblyresourcesforpackagingasamoduleoraCLIscriptforconfiguringviajboss-cli.
Note Theprojectwillbecreatedasanindependentprojectandhasnoparentmavendependencies.It’sdesignedtobebuiltindependentofbuildingTeiid.
Youhave2optionsforcreatingaUDFproject;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.
Selecttheudf-archetypev9.0.0,thenpressNext
Enteralltheinformation(i.e.,GroupID,ArtifactID,method-name,method-args,return-typeetc.)neededtogeneratetheproject,thenclickFinish
Theprojectwillbecreatedandnameaccordingtothe*ArtifactID*.
CreateProjectusingCommandLine
Tocreateacustomtranslatorprojectfromthecommandline,youcanusethefollowingtemplatecommand:
mvnarchetype:generate-DarchethypeRepository=https://repository.jboss.org/nexus/content/repositories/rel
eases/\
-DarchetypeGroupId=org.jboss.teiid.arche-types\
-DarchetypeArtifactId=udf-archetype\
-DarchetypeVersion=9.0.0\
-DgroupId=${groupId} \
-DartifactId=${udf-artifact-id} \
-Dpackage=${packageName}\
-Dversion=0.0.1-SNAPSHOT\
-Dudf-name=${functionName}\
-Dmethod-name=${methodName}\
-Dmethod-args=${methodArguments}\
-Dreturn-type=${returnType}
where:
SupportforUser-DefinedFunctions(Non-Pushdown)
261
![Page 262: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/262.jpg)
-DarchetypeGroupId-isthegroupIDforthearchetypetousetogenerate
-DarchetypeArtifactId-istheartifactIDforthearchetypetousetogenerate
-DarchetypeVersion -istheversionforthearchetypetousetogenerate
-DgroupId -(userdefined)groupIDforthenewudfprojectpom.xml
-DartifactId -(userdefined)artifactIDforthenewudfprojectpom.xml
-Dpackage -(userdefined)thepackagestructurewherethejava,moduleandresourcefileswill
becreated
-Dversion -(userdefined)theversionthatthenewconnectorprojectpom.xmlwillbe
-Dudf-name -(userdefined)thenametogivethenewuserdefinedfunction,willbecometheClass
Name
-Dmethod-name-(userdefined)thenameofthemethodthatwillbeconfiguredinthemodelprocedure
-Dmethod-args-(userdefined)theargumentsthemethodwillaccept.'Typename[,Typename[,...]]
Example:'Stringarg0'or'Stringarg0,integerarg1'
-Dreturn-type-(userdefined)thedatatypeofthevaluereturnedbythemethod
Thefollowingisanexampletoexecute:
mvnarchetype:generate-DarchethypeRepository=https://repository.jboss.org/nexus/content/repositories/r
eleases/\\
-DarchetypeGroupId=org.jboss.teiid.arche-types\
-DarchetypeArtifactId=udf-archetype\
-DarchetypeVersion=9.0.0\
-DgroupId=org.teiid.udf\
-DartifactId=udf-myFunction\
-Dpackage=org.teiid.udf\
-Dversion=0.0.1-SNAPSHOT\
-Dudf-name=myFunction\
-Dmethod-name=myFunction\
-Dmethod-args='Stringarg1'\
-Dreturn-type=String
Whenexecuted,youwillbeaskedtoconfirmtheproperties
[INFO]Archetyperepositorynotdefined.Usingtheonefrom[org.jboss.teiid.arche-types:udf-archetype:9.0.0]f
oundincataloglocal
[INFO]Usingproperty:groupId=org.teiid.udf
[INFO]Usingproperty:artifactId=udf-myFunction
[INFO]Usingproperty:version=0.0.1-SNAPSHOT
[INFO]Usingproperty:package=org.teiid.udf
[INFO]Usingproperty:method-args=Stringarg1
[INFO]Usingproperty:method-name=myFunction
[INFO]Usingproperty:return-type=String
[INFO]Usingproperty:udf-name=myFunction
Confirmpropertiesconfiguration:
groupId:org.teiid.udf
artifactId:udf-myFunction
version:0.0.1-SNAPSHOT
package:org.teiid.udf
method-args:Stringarg1
method-name:myFunction
return-type:String
udf-name:myFunction
Y::y
typeY(yes)andpressenter,andthecreationofthetranslatorprojectwillbedone
Uponcreation,adirectorybasedonthe*artifactId*willbecreated,thatwillcontaintheproject.'cd'intothatdirectoryandexecuteatestbuildtoconfirmtheprojectwascreatedcorrectly:
mvncleaninstall
Thisshouldbuildsuccessfully,andnowyouarereadytostartaddingyourcustomcode.
SupportforUser-DefinedFunctions(Non-Pushdown)
262
![Page 263: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/263.jpg)
SupportforUser-DefinedFunctions(Non-Pushdown)
263
![Page 264: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/264.jpg)
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
264
![Page 265: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/265.jpg)
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.1.0.Final.jar.TheCommmdLogMessageincludesinformationaboutvdb,session,commandsql,etc.CommandLogMessagesareloggedattheINFO(userqueries),DEBUG(sourcequeries),andTRACE(queryplan)levels.
SampleCommandLogMessageUsage
packageorg.something;
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.1.0.Final.jar.AuditMessagesareloggedattheDEBUGlevel.AuditMessagesareusedforbothdatarolevalidationandforlogon/logoffevents.OnlylogoneventswillcontainLogonInfo.
SampleAuditMessageUsage
packageorg.something;
importjava.util.logging.Handler;
importjava.util.logging.LogRecord;
publicclassAuditHandlerextendsHandler{
@Override
CustomLogging
265
![Page 266: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/266.jpg)
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
<loggercategory="org.teiid.COMMAND_LOG">
<levelname="DEBUG"/>
<handlers>
<handlername="COMMAND"/>
</handlers>
</logger>
ChangetheaboveconfigurationaccordinglyforAuditHandler,ifyouareworkingwithAuditMessages.
CustomLogging
266
![Page 267: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/267.jpg)
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.
<vdbname="{vdb-name}"version="1">
<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
267
![Page 268: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/268.jpg)
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
268
![Page 269: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/269.jpg)
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
<?xmlversion="1.0"encoding="UTF-8"?>
<modulexmlns="urn:jboss:module:1.0"name="com.something">
<resources>
<resource-rootpath="something.jar"/>
</resources>
<dependencies>
<modulename="javax.api"/>
<modulename="javax.resource.api"/>
<modulename="org.jboss.teiid.common-core"/>
<modulename="org.jboss.teiid.teiid-api"/>
</dependencies>
</module>
Copythejarfileunderthissamedirectory.Makesureyouaddanyadditionaldependenciesifrequiredbyyourimplementationclassunderdependencies.
Restarttheserver
ThebelowXMLfragmentshowshowtoconfiguretheVDBwiththecustommetadatarepositorycreated
Samplevdb.xmlfile
CustomMetadataRepository
269
![Page 270: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/270.jpg)
<vdbname="{vdb-name}"version="1">
<modelname="{model-name}"type="PHYSICAL">
<sourcename="AccountsDB"translator-name="oracle"connection-jndi-name="java:/oracleDS"/>
<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.
CustomMetadataRepository
270
![Page 271: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/271.jpg)
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
<?xmlversion="1.0"encoding="UTF-8"?>
<modulexmlns="urn:jboss:module:1.0"name="com.something">
<resources>
<resource-rootpath="something.jar"/>
</resources>
<dependencies>
<modulename="javax.api"/>
<modulename="javax.resource.api"/>
<modulename="org.jboss.teiid.common-core"/>
<modulename="org.jboss.teiid.teiid-api"/>
</dependencies>
</module>
Copythejarfileunderthissamedirectory.Makesureyouaddanyadditionaldependenciesifrequiredbyyourimplementationclassunderdependencies.
Usethecliormodifytheconfigurationtosetthepreparser-moduleintheTeiidsubsystemconfigurationtotheappropriatemodulename.
Restarttheserver
DevelopmentConsiderations
PreParser
271
![Page 272: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/272.jpg)
Changingtheincomingquerytoadifferenttypeofstatementisnotrecommendedasareanymodificationstothenumberortypesofprojectedsymbols.
PreParser
272
![Page 273: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/273.jpg)
ArchetypeTemplatePreParserProjectOnewaytostartdevelopingacustompreparseristocreateaprojectusingtheTeiidarchetypetemplate.Whentheprojectiscreatedfromthetemplate,itwillcontainanexampleclassandresourcesforyoutobeginaddingyourcustomlogic.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.
Selectthepreparser-archetype,thenpressNext
Enteralltheinformation(i.e.,GroupID,ArtifactID,etc.)neededtogeneratetheproject,thenclickFinish
Theprojectwillbecreatedandnameaccordingtothe*ArtifactID*.
CreateProjectusingCommandLine
Tocreateacustompreparserprojectfromthecommandline,youcanusethefollowingtemplatecommand:
mvnarchetype:generate-DarchethypeRepository=https://repository.jboss.org/nexus/content/repositories/rel
eases/\
-DarchetypeGroupId=org.jboss.teiid.arche-types\
-DarchetypeArtifactId=preparser-archetype\
-DarchetypeVersion=9.0.0\
-DgroupId=${groupId} \
-DartifactId=${udf-artifact-id} \
-Dpackage=${packageName}\
-Dversion=0.0.1-SNAPSHOT\
-Dclass-name=${className}\
-Dteiid-version${teiidVersion}
where:
-DarchetypeGroupId-isthegroupIDforthearchetypetousetogenerate
-DarchetypeArtifactId-istheartifactIDforthearchetypetousetogenerate
ArchethypeTemplatePreParserProject
273
![Page 274: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/274.jpg)
-DarchetypeVersion -istheversionforthearchetypetousetogenerate
-DgroupId -(userdefined)groupIDforthenewpreparserprojectpom.xml
-DartifactId -(userdefined)artifactIDforthenewpreparserprojectpom.xml
-Dpackage -(userdefined)thepackagestructurewherethejava,moduleandresourcefileswill
becreated
-Dversion -(userdefined)theversionthatthenewpreparserprojectpom.xmlwillbe
-Dclass-name -(userdefined)theclassnametogivethenewuserpreparser,willbecometheClass
Name
-Dteiid-version-Optional,defaultsto9.0.0.Final
EXAMPLE
thisisanexampleofthetemplatethatcanberun:
mvnarchetype:generate-DarchethypeRepository=https://repository.jboss.org/nexus/content/repositories/rel
eases/\
-DarchetypeGroupId=org.jboss.teiid.arche-types\
-DarchetypeArtifactId=preparser-archetype\
-DarchetypeVersion=9.0.0\
-DgroupId=org.teiid.preparser\
-DartifactId=preparser-myParser\
-Dpackage=org.teiid.preparser\
-Dversion=0.0.1-SNAPSHOT\
-Dclass-name=myPreParser
Whenexecuted,youwillbeaskedtoconfirmthepackageproperty
[INFO]Usingproperty:groupId=org.teiid.preparser
[INFO]Usingproperty:artifactId=preparser-myParser
[INFO]Usingproperty:version=0.0.1-SNAPSHOT
[INFO]Usingproperty:package=org.teiid.preparser
[INFO]Usingproperty:class-name=myPreParser
[INFO]Usingproperty:teiid-version=9.0.0.Final
Confirmpropertiesconfiguration:
groupId:org.teiid.preparser
artifactId:preparser-myParser
version:0.0.1-SNAPSHOT
package:org.teiid.preparser
class-name:myPreParser
teiid-version:9.0.0.Final
Y::y
typeY(yes)andpressenter,andthecreationofthepreparserprojectwillbedone
Uponcreation,adirectorybasedonthe*artifactId*willbecreated,thatwillcontaintheproject.'cd'intothatdirectoryandexecuteatestbuildtoconfirmtheprojectwascreatedcorrectly:
mvncleaninstall
Thisshouldbuildsuccessfully,andnowyouarereadytostartaddingyourcustomcode.
ArchethypeTemplatePreParserProject
274
![Page 275: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/275.jpg)
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
275
![Page 276: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/276.jpg)
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>
<groupId>org.jboss.teiid</groupId>
<artifactId>teiid-runtime</artifactId>
</dependency>
<dependency>
<groupId>org.jboss.teiid</groupId>
<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
276
![Page 277: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/277.jpg)
Translators
TranslatorsinstancescanbescopedtoaVDBinASusingdeclarationsinavdb.xmlfile,howevernamedinstancesinembeddedarescopedtotheentireEmbeddedServerandmustberegisteredviatheEmbeddedServer.addTranslatormethods.NotethattherearethreeaddTranslatormethods:
addTranslator(Class<?extendsExecutionFactory>clazz)-AddsadefaultinstanceoftheExecutionFactory,usingthedefaultnameeitherfromtheTranslatorannotationortheclassname.
addTranslator(Stringname,ExecutionFactory<?,?>ef)-Addsapre-initialized(ExecutionFactory.start()musthavealreadybeencalled)instanceoftheExecutionFactory,usingthegiventranslatorname.Theinstancewillbesharedforallusage.
addTranslator(Stringname,Stringtype,Map<String,String>properties)-Addsadefinitionofanoverridetranslator-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
EmbeddedGuide
277
![Page 278: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/278.jpg)
IfSourcerelatedsecurityauthentication,forexample,ifyouwantconnect/federate/integrateTwittersuppliedrestsource,asecurityauthenticationisanecessary,thefollowingstepscanusetoexecutesecurityauthentication:
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.
AccessfromclientapplicationsTypicallywhenTeiidisdeployedasEmbeddedServer,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);
EmbeddedConfigurationconfig=newEmbeddedConfiguration();
config.addTransport(s);
es.start(config);
Example-SSLtransport
EmbeddedServerserver=newEmbeddedServer();
...
EmbeddedConfigurationconfig=newEmbeddedConfiguration();
SocketConfigurationsocketConfiguration=newSocketConfiguration();
SSLConfigurationsslConfiguration=newSSLConfiguration();
EmbeddedGuide
278
![Page 279: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/279.jpg)
//Settingsshownwiththeirdefaultvalues
//sslConfiguration.setMode(SSLConfiguration.ENABLED);
//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);
server.start(config);
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
EmbeddedGuide
279
![Page 280: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/280.jpg)
TransactionprocessingrequiressettingtheTransactionManagerintheEmbeddedConfigurationusedtostarttheEmbeddedServer.Aclientfacingjavax.sql.DataSourceisnotprovidedforembedded.Howevertheusageofprovidedjava.sql.Drivershouldbesufficientastheembeddedserverisbydefaultabletodetectthreadboundtransactionsandappropriatelypropagatethetransactiontothreadslaunchedaspartofrequestprocessing.Theusageoflocalconnectionsisalsopermitted.
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
280
![Page 281: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/281.jpg)
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
LogginginTeiidEmbedded
281
![Page 282: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/282.jpg)
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.
LogginginTeiidEmbedded
282
![Page 283: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/283.jpg)
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>
<groupId>org.jboss.teiid</groupId>
<artifactId>teiid-engine</artifactId>
</dependency>
SecureEmbeddedwithPicketBox
283
![Page 284: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/284.jpg)
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
SecureEmbeddedwithPicketBox
284
![Page 285: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/285.jpg)
Asampleofroles.properties
testUser=user
TostartEmbeddedServerwithUsersRolesLoginModulebasedsecurityauthenticationvia:
EmbeddedServerserver=
...
EmbeddedConfigurationconfig=newEmbeddedConfiguration();
config.setSecurityDomain("teiid-security-file");
config.setSecurityHelper(newEmbeddedSecurityHelper());
server.start(config);
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=
...
EmbeddedConfigurationconfig=newEmbeddedConfiguration();
config.setSecurityDomain("teiid-security-ldap");
config.setSecurityHelper(newEmbeddedSecurityHelper());
server.start(config);
SecureEmbeddedwithPicketBox
285
![Page 286: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/286.jpg)
SecureEmbeddedwithPicketBox
286
![Page 287: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/287.jpg)
ReferenceGuideTeiidoffersahighlyscalableandhighperformancesolutiontoinformationintegration.ByallowingintegratedandenricheddatatobeconsumedrelationallyorasXMLovermultipleprotocols,Teiidsimplifiesdataaccessfordevelopersandconsumingapplications.
Commercialdevelopmentsupport,productionsupport,andtrainingforTeiidisavailablethroughJBossInc.TeiidisaProfessionalOpenSourceprojectandacriticalcomponentoftheJBossEnterpriseDataServicesPlatform.
BeforeonecandelveintoTeiiditisveryimportanttolearnfewbasicconstructsofTeiid,likewhatisVDB?whatisModel?etc.Forthatpleasereadtheshortintroductionherehttp://teiid.jboss.org/basics/
ReferenceGuide
287
![Page 288: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/288.jpg)
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
288
![Page 289: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/289.jpg)
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
289
![Page 290: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/290.jpg)
Thisrepresentsdatasourcesthathavebeenvalidatedtoworkusingtheavailabletranslatorsandconnectors.However,thisdoesnotprecludeanewdatasourcefromworking.Itcanbeaseasyasextendinganexistingtranslator,tocreatinganewtranslatorusingtheTranslatorDevelopmentextensions.
TakealookatthelistofTranslatorsthatareusedasthebridgebetweenTeiidandtheexternalsystem.
DataSources
290
![Page 291: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/291.jpg)
SQLSupportTeiidprovidesnearlyallofthefunctionalityofSQL-92DML.SQL-99andlaterfeaturesareconstantlybeingaddedbaseduponcommunityneed.ThefollowingdoesnotattempttocoverSQLexhaustively,butratherhighlightsSQL’susagewithinTeiid.SeetheBNFforSQLGrammarfortheexactformofSQLacceptedbyTeiid.
SQLSupport
291
![Page 292: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/292.jpg)
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
292
![Page 293: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/293.jpg)
Identifiers
293
![Page 294: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/294.jpg)
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
294
![Page 295: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/295.jpg)
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
295
![Page 296: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/296.jpg)
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|NOQUOTE][HEADER][ENCODINGid][ORDERBY…])–CSVtextaggregationofallexpressionsineachrowofagroup.WhenDELIMITERisnotspecified,bydefaultcomma(,)isusedasdelimiter.Allnon-nullvalueswillbequoted.Doublequotes(")isthedefaultquotecharacter.UseQUOTEtospecifyadifferentvalue,orNOQUOTEfornovaluequoting.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
296
![Page 297: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/297.jpg)
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
297
![Page 298: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/298.jpg)
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
298
![Page 299: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/299.jpg)
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
299
![Page 300: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/300.jpg)
index_exprmustresolvetoanintegervalue.Thissyntaxiseffectivelythesameasthearray_getsystemfunctionandexpects1-basedindexing.
OperatorPrecedence
Teiidparsesandevaluatesoperatorswithhigherprecedencebeforethosewithlowerprecedence.Operatorwithequalprecedenceareleftassociative.Operatorprecedencelistedfromhightolow:
Operator Description
[] arrayelementreference
+,- positive/negativevalueexpression
*,/ multiplication/division
+,- addition/subtraction
||\ concat
criteria seeCriteria
Expressions
300
![Page 301: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/301.jpg)
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.
NoteTeiiddoesnotexhaustivelyvalidateLIKE_REGEXpatternvalues.ItispossibletouseJREonlyregularexpressionfeaturesthatarenotspecifiedbytheSQLspecification.Additionalnotallsourcessupportthesameregularexpressionflavororextensions.Careshouldbetakeninpushdownsituationstoensurethatthepattern
Criteria
301
![Page 302: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/302.jpg)
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
302
![Page 303: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/303.jpg)
Criteria
303
![Page 304: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/304.jpg)
ScalarFunctionsTeiidprovidesanextensivesetofbuilt-inscalarfunctions.SeealsoSQLSupportandDatatypes.Inaddition,TeiidprovidesthecapabilityforuserdefinedfunctionsorUDFs.SeetheDevelopersGuideforaddingUDFs.OnceaddedUDFsmaybecalledjustlikeanyotherfunction.
ScalarFunctions
304
![Page 305: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/305.jpg)
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) Formatsxusingformatyxisbiginteger,yisstring,returnsstring
FORMATDOUBLE(x,y) Formatsxusingformaty xisdouble,yisstring,returnsstring
FORMATFLOAT(x,y) Formatsxusingformaty xisfloat,yisstring,returnsstring
ScalarFunctions
305
![Page 306: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/306.jpg)
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
306
![Page 307: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/307.jpg)
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
307
![Page 308: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/308.jpg)
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
308
![Page 309: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/309.jpg)
StringFunctionsStringfunctionsgenerallytakestringsasinputsandreturnstringsasoutputs.
Unlessspecified,alloftheargumentsandreturntypesinthefollowingtablearestringsandallindexesare1-based.The0indexisconsideredtobebeforethestartofthestring.
Function Definition DatatypeConstraint
x||y Concatenationoperator x,yin\{string,clob},returntypeisstringorclob
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) Padinputstringxonthelefttothe xin{string},yin{string},zin
ScalarFunctions
309
![Page 310: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/310.jpg)
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
310
![Page 311: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/311.jpg)
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
311
![Page 312: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/312.jpg)
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
312
![Page 313: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/313.jpg)
Date_TimeFunctionsDateandtimefunctionsreturnoroperateondates,times,ortimestamps.
ParseandformatDate/Timefunctionsusetheconventionestablishedwithinthejava.text.SimpleDateFormatclasstodefinetheformatsyoucanusewiththesefunctions.YoucanlearnmoreabouthowthisclassdefinesformatsbyvisitingtheJavadocsforSimpleDateFormat.
Function Definition DatatypeConstraint
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
313
![Page 314: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/314.jpg)
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
314
![Page 315: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/315.jpg)
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
315
![Page 316: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/316.jpg)
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
316
![Page 317: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/317.jpg)
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
317
![Page 318: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/318.jpg)
ChoiceFunctionsChoicefunctionsprovideawaytoselectfromtwovaluesbasedonsomecharacteristicofoneofthevalues.
Function Definition DatatypeConstraint
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
318
![Page 319: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/319.jpg)
DecodeFunctionsDecodefunctionsallowyoutohavetheTeiidServerexaminethecontentsofacolumninaresultsetandalter,ordecode,thevaluesothatyourapplicationcanbetterusetheresults.
Function Definition DatatypeConstraint
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
319
![Page 320: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/320.jpg)
SELECTDECODESTRING(IS_IN_STOCK,'null,no,"null",no,nil,no,false,no,true,yes')FROMPartsSupplier.PARTS;
IftheDECODEfunctiondoesnotfindamatchingoutputvalueinthecolumnandyouhavenotspecifiedadefaultvalue,theDECODEfunctionwillreturntheoriginalvaluetheTeiidServerfoundinthatcolumn.
ScalarFunctions
320
![Page 321: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/321.jpg)
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
321
![Page 322: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/322.jpg)
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.TheENVfunctionneedstobeenabledviaCLI
/subsystem=teiid:write-attribute(name=allow-env-function,value=true)
oreditthestandalone-teiid.xmlfileandaddfollowingtothe"teiid"subsystem
<allow-env-function>true</allow-env-function>
thencallusingENV('KEY'),whichreturnsvalueasstring.Ex:ENV('PATH')
NODE_IDRetrievethenodeid-typicallytheSystempropertyvaluefor"jboss.node.name"whichwillnotbesetforTeiidembedded.
NODE_ID()
returnvalueisstring.
ScalarFunctions
322
![Page 323: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/323.jpg)
SESSION_ID
Retrievethestringformofthecurrentsessionid.
SESSION_ID()
returnvalueisstring.
USER
Retrievethenameoftheuserexecutingthequery.
USER([includeSecurityDomain])
includeSecurityDomainisaboolean.returnvalueisstring.
IfincludeSecurityDomainisomittedortrue,thentheusernamewillbereturnedwith@security-domainappended.
CURRENT_DATABASE
Retrievethecatalognameofthedatabase.TheVDBnameisalwaysthecatalogname.
CURRENT_DATABASE()
returnvalueisstring.
TEIID_SESSION_GET
Retrievethesessionvariable.
TEIID_SESSION_GET(name)
nameisastringandthereturnvalueisanobject.
Anullnamewillreturnanullvalue.TypicallyyouwillusetheagetwrappedinaCASTtoconverttothedesiredtype.
TEIID_SESSION_SETSetthesessionvariable.
TEIID_SESSION_SET(name,value)
nameisastring,valueisanobject,andthereturnvalueisanobject.
Thepreviousvalueforthekeyornullwillbereturned.Asethasnoeffectonthecurrenttransactionandisnotaffectedbycommit/rollback.
ScalarFunctions
323
![Page 324: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/324.jpg)
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
324
![Page 325: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/325.jpg)
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
325
![Page 326: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/326.jpg)
XMLNAMESPACESisusedprovidenamespaceinformation.NODEFAULTisequivalenttodefiningthedefaultnamespacetothenulluri-xmlns="".OnlyoneDEFAULTorNODEFAULTnamespaceitemmaybespecified.Thenamespaceprefixesxmlnsandxmlarereserved.
Ifaattributenameisnotsupplied,theexpressionmustbeacolumnreference,inwhichcasetheattributenamewillbethecolumnname.Nullattributevaluesareignored.
Name,prefixareidentifiers.uriisastringliteral.contentcanbeanytype.Returnvalueisxml.Thereturnvalueisvalidforuseinplaceswhereadocumentisexpected.
SimpleExample
SELECTXMLELEMENT("name",CustomerName)
FROMCustomerc
WHEREc.CustomerID=87;
==========================================================
<name>WartianHerkku</name>
MultipleColumns
SELECTXMLELEMENT("customer",
XMLELEMENT("name",c.CustomerName),
XMLELEMENT("contact",c.ContactName))
FROMCustomerc
WHEREc.CustomerID=87;
==========================================================
<customer><name>WartianHerkku</name><contact>PirkkoKoskitalo</contact></customer>
ColumnsasAttributes
SELECTXMLELEMENT("customer",
XMLELEMENT("name",c.CustomerName,
XMLATTRIBUTES(
"contact"asc.ContactName,
"id"asc.CustomerID
)
)
)
FROMCustomerc
WHEREc.CustomerID=87;
==========================================================
<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
326
![Page 327: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/327.jpg)
YoucanuseXMLFORRESTtosimplifythedeclarationofmultipleXMLELEMENTS,XMLFORESTfunctionallowsyoutoprocessmultiplecolumnsatonce
Example
SELECTXMLELEMENT("customer",
XMLFOREST(
c.CustomerNameAS"name",
c.ContactNameAS"contact"
))
FROMCustomerc
WHEREc.CustomerID=87;
==========================================================
<customer><name>WartianHerkku</name><contact>PirkkoKoskitalo</contact></customer>
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>WartianHerkku</name><contact>PirkkoKoskitalo</contact></customer>
<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
327
![Page 328: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/328.jpg)
SELECTXMLPARSE(CONTENT'<customer><name>WartianHerkku</name><contact>PirkkoKoskitalo</contact></customer>'W
ELLFORMED);
WillreturnaSQLXMLwithcontents
===============================================================
<customer><name>WartianHerkku</name><contact>PirkkoKoskitalo</contact></customer>
XMLPIReturnsanxmlprocessinginstruction.
XMLPI([NAME]name[,content])
Nameisanidentifier.Contentisastring.Returnvalueisxml.
XMLQUERY
ReturnstheXMLresultfromevaluatingthegivenxquery.
XMLQUERY([<NSP>]xquery[<PASSING>][(NULL|EMPTY)ONEMPTY]]
PASSING:=PASSINGexp[ASname][,exp[ASname]]*
SeeXMLELEMENTforthedefinitionofNSP-XMLNAMESPACES
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]]*
SeeXMLELEMENTforthedefinitionofNSP-XMLNAMESPACES
ScalarFunctions
328
![Page 329: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/329.jpg)
Namespacesmayalsobedirectlydeclaredinthexqueryprolog.
TheoptionalPASSINGclauseisusedtoprovidethecontextitem,whichdoesnothaveaname,andnamedglobalvariablevalues.Ifthexqueryusesacontextitemandnoneisprovided,thenanexceptionwillberaised.OnlyonecontextitemmaybespecifiedandshouldbeanXMLtype.Allnon-contextnon-XMLpassingvalueswillbeconvertedtoanappropriateXMLtype.Null/Unknownwillbereturnedifthecontextitemevaluatestonull.
xqueryinstring.Returnvalueisboolean.
XMLEXISTSispartoftheSQL/XML2006specification.
Note SeealsoXQueryOptimization
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
329
![Page 330: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/330.jpg)
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
330
![Page 331: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/331.jpg)
selectxmlelement(name"root",xmlagg(p))
from(selectxmlelement(name"x",x,xmlagg(xmlelement(name"y",y))aspfromtblgroupbyx))asv
anotherusefullinkofexamplescanbefoundhere
ScalarFunctions
331
![Page 332: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/332.jpg)
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)
<?xmlversion="1.0"?>
<person>
<firstName>John</firstName>
<children>Randy</children>
<children>Judy<children>
</person>
ScalarFunctions
332
![Page 333: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/333.jpg)
JSON:
SampleJSONtoXMLforjsonToXml('person',x)witharootarray
[{"firstName":"George"},{"firstName":"Jerry"}]
XML(Noticethereisanextra"person"wrappingelementtokeeptheXMLwell-formed):
SampleJSONtoXMLforjsonToXml(’person’,x)witharootarray
<?xmlversion="1.0"?>
<person>
<person>
<firstName>George</firstName>
</person>
<person>
<firstName>Jerry</firstName>
</person>
</person>
JSON:
SampleJSONtoXMLforjsonToXml(’root’,x)withaninvalidname
{"/invalid":"abc"}
XML:
SampleJSONtoXMLforjsonToXml(’root’,x)withaninvalidname
<?xmlversion="1.0"?>
<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
333
![Page 334: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/334.jpg)
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
334
![Page 335: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/335.jpg)
ScalarFunctions
335
![Page 336: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/336.jpg)
SecurityFunctionsSecurityfunctionsprovidetheabilitytointeractwiththesecuritysystem.
HASROLE
WhetherthecurrentcallerhastheTeiiddataroleroleName.
hasRole([roleType,]roleName)
roleNamemustbeastring,thereturntypeisboolean.
Thetwoargumentformisprovidedforbackwardscompatibility.roleTypeisastringandmustbe`data'.
Rolenamesarecase-sensitiveandonlymatchTeiidDataRoles.JAASroles/groupsnamesarenotvalidforthisfunction-unlessthereiscorrespondingdatarolewiththesamename.
ScalarFunctions
336
![Page 337: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/337.jpg)
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_OrderingEqualsST_OverlapsST_RelateST_TouchesST_Within
AttributesandTestsST_AreaST_CoordDimST_DimensionST_EndPointST_ExteriorRingST_GeometryNST_GeometryTypeST_HasArc
ScalarFunctions
337
![Page 338: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/338.jpg)
ST_InteriorRingNST_IsClosedST_IsEmptyST_IsRingST_IsSimpleST_IsValidST_LengthST_NumGeometriesST_NumInteriorRingsST_NunPointsST_PointOnSurfaceST_PerimeterST_PointNST_SRIDST_SetSRIDST_StartPointST_XST_YST_Z
Misc.FunctionsST_BoundaryST_BufferST_CentroidST_ConvexHullST_CurveToLineST_DifferenceST_EnvelopeST_Force_2DST_IntersectionST_SimplifyST_SymDifferenceST_TransformST_Union
AggregateFunctionsST_Extent
ConstructionFunctionsST_PointST_Polygon
ConversionFunctions
ST_GeomFromText
ReturnsageometryfromaClobinWKTformat.
ST_GeomFromText(text[,srid])
textisaclob,sridisanoptionalinteger.Returnvalueisageometry.
ST_GeomFromWKB/ST_GeomFromBinary
ScalarFunctions
338
![Page 339: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/339.jpg)
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])
textisaclob,sridisanoptionalinteger.Returnvalueisageometry.
ST_GeomFromGML
ReturnsageometryfromaClobinGML2format.
ST_GeomFromGML(text[,srid])
textisaclob,sridisanoptionalinteger.Returnvalueisageometry.
ST_AsText
ST_AsText(geom)
geomisageometry.ReturnvalueisclobinWKTformat.
ST_AsBinary
ST_AsBinary(geom)
geomisageometry.ReturnvalueisablobinWKBformat.
ScalarFunctions
339
![Page 340: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/340.jpg)
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.
geom1&&geom2
geom1,geom2aregeometries.Returnvalueisaboolean.
RelationshipFunctions
ST_Contains
Returnstrueifgeom1containsgeom2containsanother.
ST_Contains(geom1,geom2)
ScalarFunctions
340
![Page 341: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/341.jpg)
geom1,geom2aregeometries.Returnvalueisaboolean.
ST_Crosses
Returnstrueifthegeometriescross.
ST_Crosses(geom1,geom2)
geom1,geom2aregeometries.Returnvalueisaboolean.
ST_Disjoint
Returnstrueifthegeometriesaredisjoint.
ST_Disjoint(geom1,geom2)
geom1,geom2aregeometries.Returnvalueisaboolean.
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.
ST_Equals(geom1,geom2)
geom1,geom2aregeometries.Returnvalueisaboolean.
ST_Intersects
Returnstrueifthegeometriesintersect.
ST_Intersects(geom1,geom2)
geom1,geom2aregeometries.Returnvalueisaboolean.
ScalarFunctions
341
![Page 342: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/342.jpg)
ST_OrderingEquals
Returnstrueifgeom1andgeom2havethesamestructureandthesameorderingofpoints.
ST_OrderingEquals(geom1,geom2)
geom1,geom2aregeometries.Returnvalueisaboolean.
ST_Overlaps
Returnstrueifthegeometriesoverlap.
ST_Overlaps(geom1,geom2)
geom1,geom2aregeometries.Returnvalueisaboolean.
ST_Relate
Testorreturntheintersectionofgeom1andgeom2.
ST_Relate(geom1,geom2,pattern)
geom1,geom2aregeometries.patternisaninecharacterDE-9IMpatternstring.Returnvalueisaboolean.
ST_Relate(geom1,geom2)
geom1,geom2aregeometries.ReturnvalueistheninecharacterDE-9IMintersectionstring.
ST_Touches
Returnstrueifthegeometriestouch.
ST_Touches(geom1,geom2)
geom1,geom2aregeometries.Returnvalueisaboolean.
ST_Within
Returnstrueifgeom1iscompletelyinsidegeom2.
ST_Within(geom1,geom2)
geom1,geom2aregeometries.Returnvalueisaboolean.
AttributesandTests
ST_Area
Returnstheareaofgeom.
ST_Area(geom)
ScalarFunctions
342
![Page 343: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/343.jpg)
geomisageometry.Returnvalueisadouble.
ST_CoordDim
Returnsthecoordinatedimensionsofgeom.
ST_CoordDim(geom)
geomisageometry.Returnvalueisanintegerbetween0and3.
ST_Dimension
Returnsthedimensionofgeom.
ST_Dimension(geom)
geomisageometry.Returnvalueisanintegerbetween0and3.
ST_EndPoint
ReturnstheendPointoftheLineStringgeom.ReturnsnullifgeomisnotaLineString.
ST_EndPoint(geom)
geomisageometry.Returnvalueisageometry.
ST_ExteriorRing
ReturnstheexteriorringorshellLineStringofthePolygongeom.ReturnsnullifgeomisnotaPolygon.
ST_ExteriorRing(geom)
geomisageometry.Returnvalueisageometry.
ST_GeometryN
Returnsthenthgeometryatthegiven1-basedindexingeom.Returnsnullifageometryatthegivenindexdoesnotexist.Noncollectiontypesreturnthemselvesatthefirstindex.
ST_GeometryN(geom,index)
geomisageometry.indexisaninteger.Returnvalueisageometry.
ST_GeometryType
ReturnsthetypenameofgeomasST_name.WherenamewillbeLineString,Polygon,Pointetc.
ST_GeometryType(geom)
geomisageometry.Returnvalueisastring.
ScalarFunctions
343
![Page 344: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/344.jpg)
ST_HasArc
Testifthegeometryhasacircularstring.Willcurrentlyonlyreportfalseascurvedgeometrytypesarenotsupported.
ST_HasArc(geom)
geomisageometry.Returnvalueisageometry.
ST_InteriorRingN
ReturnsthenthinteriorringLinearStringgeometryatthegiven1-basedindexingeom.ReturnsnullifageometryatthegivenindexdoesnotexistorifgeomisnotaPolygon.
ST_InteriorRingN(geom,index)
geomisageometry.indexisaninteger.Returnvalueisageometry.
ST_IsClosed
ReturnstrueifLineStringgeomisclosed.ReturnsfalseifgeomisnotaLineString
ST_IsClosed(geom)
geomisageometry.Returnvalueisaboolean.
ST_IsEmpty
Returnstrueifthesetofpointsisempty.
ST_IsEmpty(geom)
geomisageometry.Returnvalueisaboolean.
ST_IsRing
ReturnstrueiftheLineStringgeomisaring.ReturnsfalseifgeomisnotaLineString.
ST_IsRing(geom)
geomisageometry.Returnvalueisaboolean.
ST_IsSimple
Returnstrueifthegeomissimple.
ST_IsSimple(geom)
geomisageometry.Returnvalueisaboolean.
ST_IsValid
ScalarFunctions
344
![Page 345: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/345.jpg)
Returnstrueifthegeomisvalid.
ST_IsValid(geom)
geomisageometry.Returnvalueisaboolean.
ST_Length
Returnsthelengthofa(Multi)LineStringotherwise0.
ST_Length(geom)
geomisageometry.Returnvalueisadouble.
ST_NumGeometries
Returnsthenumberofgeometriesingeom.Willreturn1ifnotageometrycollection.
ST_NumGeometries(geom)
geomisageometry.Returnvalueisaninteger.
ST_NumInteriorRings
ReturnsthenumberofinteriorringsinthePolygongeom.ReturnsnullifgeomisnotaPolygon.
ST_NumInteriorRings(geom)
geomisageometry.Returnvalueisaninteger.
ST_NunPoints
ReturnsthenumberofPointsingeom.
ST_NunPoints(geom)
geomisageometry.Returnvalueisaninteger.
ST_PointOnSurface
ReturnsaPointthatisguarenteedtobeonthesurfaceofgeom.
ST_PointOnSurface(geom)
geomisageometry.ReturnvalueisaPointgeometry.
ST_Perimeter
Returnstheperimeterofthe(Multi)Polygongeom.Willreturn0ifgeomisnota(Multi)Polygon
ST_Perimeter(geom)
ScalarFunctions
345
![Page 346: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/346.jpg)
geomisageometry.Returnvalueisadouble.
ST_PointN
ReturnsthenthPointatthegiven1-basedindexingeom.ReturnsnullifaPointatthegivenindexdoesnotexistorifgeomisnotaLineString.
ST_PointN(geom,index)
geomisageometry.indexisaninteger.Returnvalueisageometry.
ST_SRID
ReturnstheSRIDforthegeometry.
ST_SRID(geom)
geomisageometry.Returnvalueisaninteger.A0valueratherthannullwillbereturnedforanunknownSRIDonanon-nullgeometry.
ST_SetSRID
SettheSRIDforthegivengeometry.
ST_SetSRID(geom,srid)
geomisageometry.sridisaninteger.Returnvalueisageometry.OnlytheSRIDmetadataofthegeometryismodified.
ST_StartPoint
ReturnsthestartPointoftheLineStringgeom.ReturnsnullifgeomisnotaLineString.
ST_StartPoint(geom)
geomisageometry.Returnvalueisageometry.
ST_X
ReturnstheXordinatevalue,ornullifthePointisempty.ThrowsanexceptioniftheGeometryisnotaPoint.
ST_X(geom)
geomisageometry.Returnvalueisadouble.
ST_Y
ReturnstheYordinatevalue,ornullifthePointisempty.ThrowsanexceptioniftheGeometryisnotaPoint.
ST_Y(geom)
geomisageometry.Returnvalueisadouble.
ScalarFunctions
346
![Page 347: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/347.jpg)
ST_Z
ReturnstheZordinatevalue,ornullifthePointisempty.ThrowsanexceptioniftheGeometryisnotaPoint.Willtypicallyreturnnullas3dimensionsarenotfullysupported.
ST_Z(geom)
geomisageometry.Returnvalueisadouble.
Misc.Functions
ST_Boundary
Computestheboundaryofthegivengeometry.
ST_Boundary(geom)
geomisageometry.Returnvalueisageometry.
ST_Buffer
Computesthegeometrythathaspointswithinthegivendistanceofgeom.
ST_Buffer(geom,distance)
geomisageometry.distanceisadouble.Returnvalueisageometry.
ST_Centroid
ComputesthegeometriccenterPointofgeom.
ST_Centroid(geom)
geomisageometry.Returnvalueisageometry.
ST_ConvexHull
ReturnthesmallestconvexPolygonthatcontainsallofthepointsingeom.
ST_ConvexHull(geom)
geomisageometry.Returnvalueisageometry.
ST_CurveToLine
ConvertsaCircularString/CurvedPolygontoaLineString/Polygon.NotcurrentlyimplementedinTeiid.
ST_CurveToLine(geom)
geomisageometry.Returnvalueisageometry.
ScalarFunctions
347
![Page 348: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/348.jpg)
ST_Difference
Computestheclosureofthepointsetofthepointscontainedingeom1thatarenotingeom2
ST_Difference(geom1,geom2)
geom1,geom2aregeometry.Returnvalueisageometry.
ST_Envelope
Computesthe2Dboundingboxofthegivengeometry.
ST_Envelope(geom)
geomisageometry.Returnvalueisageometry.
ST_Force_2D
Removesthezcoordinatevalueifpresent.
ST_Force_2D(geom)
geomisageometry.Returnvalueisageometry.
ST_Intersection
Computesthepointsetintersectionofthepointscontainedingeom1andingeom2
ST_Intersection(geom1,geom2)
geom1,geom2aregeometry.Returnvalueisageometry.
ST_Simplify
SimplifiesaGeometryusingtheDouglas-Peuckeralgorithm.
ST_Simplify(geom,distanceTolerance)
geomisageometry.distanceToleranceisadouble.Returnvalueisageometry.
ST_SymDifference
Returnthepartofgeom1thatdoesnotintersectwithgeom2andviceversa.
ST_SymDifference(geom1,geom2)
geom1,geom2aregeometry.Returnvalueisageometry.
ST_Transform
Transformsthegeometryvaluefromonecoordinatesystemtoanother.
ScalarFunctions
348
![Page 349: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/349.jpg)
ST_Transform(geom,srid)
geomisageometry.sridisaninteger.Returnvalueisageometry.ThesridvalueandthesridofthegeometryvaluemustexistintheSPATIAL_REF_SYSview.
ST_Union
Returnageometrythatrepresentsthepointsetcontainingallofgeom1andgeom2.
ST_Union(geom1,geom2)
geom1,geom2aregeometry.Returnvalueisageometry.
AggregateFunctions
ST_Extent
Computesthe2Dboundingboxaroundallofthegeometryvalues.Allvaluesshouldhavethesamesrid.
ST_Extent(geom)
geomisageometry.Returnvalueisageometry.
ConstructionFunctions
ST_Point
RetunsthePointforthegivencooridinates.
ST_Point(x,y)
xandyaredoubles.ReturnvalueisaPointgeometry.
ST_Polygon
RetunsthePolygonwiththegivenshellandsrid.
ST_Polygon(geom,srid)
geomisalinearringgeometryandsridisaninteger.ReturnvalueisaPolygongeometry.
ScalarFunctions
349
![Page 350: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/350.jpg)
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
350
![Page 351: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/351.jpg)
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).
Note Uncorrelatedsubquerieswillbetreatedasdeterministicregardlessofthefunctionsusedwithinthem.
ScalarFunctions
351
![Page 352: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/352.jpg)
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
352
![Page 353: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/353.jpg)
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
353
![Page 354: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/354.jpg)
TheUPDATEcommandisusedtomodifyrecordsinatable.Theoperationmayresultin1ormorerecordsbeingupdated,orinnorecordsbeingupdatedifnonematchthecriteria.
ExampleSyntax
UPDATEtableSET(column=value,...)[WHEREcriteria]
DELETECommand
TheDELETEcommandisusedtoremoverecordsfromatable.Theoperationmayresultin1ormorerecordsbeingdeleted,orinnorecordsbeingdeletedifnonematchthecriteria.
ExampleSyntax
DELETEFROMtable[WHEREcriteria]
UPSERT/MERGECommandTheUPSERT(orMERGE)isusedtoaddand/orupdaterecords.TheTeiidspecific(non-ANSI)UPSERTissimplyamodifiedINSERTstatementthatrequiresthetargettabletohaveaprimarykeyandforthetargetcolumnstocovertheprimarykey.TheUPSERToperationwillthenchecktheexistenceofeachrowpriortoINSERTandinsteadperformanUPDATEiftherowalreadyexists.
ExampleSyntax
UPSERTINTOtable(column,...)VALUES(value,...)
UPSERTINTOtable(column,...)query
Note UPSERTPushdown-IfUPSERTstatementisnotpushedtothesource,itwillbebrokendownintotherespectiveinsert/updateoperations,whichrequiresXAsupportonthetargetsystemtoguaranteeatomicity.
EXECUTECommand
TheEXECUTEcommandisusedtoexecuteaprocedure,suchasavirtualprocedureorastoredprocedure.Proceduresmayhavezeroormorescalarinputparameters.Thereturnvaluefromaprocedureisaresultsetorthesetofinout/out/returnscalars.NotethatEXECorCALLcanbeusedasashortformofthiscommand.
ExampleSyntax
EXECUTEproc()
CALLproc(value,...)
NamedParameterSyntax
EXECUTEproc(name1=>value1,name4=>param4,...)
DMLCommands
354
![Page 355: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/355.jpg)
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
355
![Page 356: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/356.jpg)
AnonymousProcedureBlock
AProcedureLanguageblockmaybeexecutedasausercommand.Thisisadvantageousinsituationswhenavirtualproceduredoesn’texists,butasetofprocessingcanbecaredoutontheserversidetogether.
ExampleSyntax
begininsertintopm1.g1(e1,e2)select?,?;selectrowcount;end;
SyntaxRules:
Inparametersaresupportedwithprepared/callablestatementparametersasshownabovewitha?parameter.
outparametersarenotyetsupported-considerusingsessionvariablesasaworkaroundasneeded.
areturnparameterisnotsupported.
asingleresultwillbereturnedifanyofthestatementsreturnsaresultset.Allreturnableresultsetsmusthaveamatchingnumberofcolumnsandtypes.UsetheWITHOUTRETURNclausetoindicatethatastatementisnotintendedtoaresultsetasneeded.
DMLCommands
356
![Page 357: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/357.jpg)
SetOperationsTeiidsupportstheUNION,UNIONALL,INTERSECT,EXCEPTsetoperationasawayofcombiningtheresultsofqueryexpressions.
Usage:
queryExpression(UNION|INTERSECT|EXCEPT)[ALL]queryExpression[ORDERBY...]
SyntaxRules:
Theoutputcolumnswillbenamedbytheoutputcolumnsofthefirstsetoperationbranch.
EachSELECTmusthavethesamenumberofoutputcolumnsandcompatibledatatypesforeachrelativecolumn.Datatypeconversionwillbeperformedifdatatypesareinconsistentandimplicitconversionsexist.
IfUNION,INTERSECT,orEXCEPTisspecifiedwithoutall,thentheoutputcolumnsmustbecomparabletypes.
INTERSECTALL,andEXCEPTALLarecurrentlynotsupported.
DMLCommands
357
![Page 358: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/358.jpg)
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
358
![Page 359: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/359.jpg)
WITHClauseTeiidsupportsnon-recursivecommontableexpressionsviatheWITHclause.WITHclauseitemsmaybereferencedastablesinsubsequentwithclauseitemsandinthemainquery.TheWITHclausecanbethoughtofasprovidingqueryscopedtemporarytables.
Usage:
WITHname[(column,...)]AS[/*+no_inline|materialize*/](queryexpression)...
SyntaxRules:
Alloftheprojectedcolumnnamesmustbeunique.Iftheyarenotunique,thenthecolumnnamelistmustbeprovided.
IfthecolumnsoftheWITHclauseitemaredeclared,thentheymustmatchthenumberofcolumnsprojectedbythequeryexpression.
Eachwithclauseitemmusthaveauniquename.
Theoptionalno_inlinehintindicatestotheoptimizerthatthequeryexpressionshouldnotbesubstitutedasaninlineviewwherereferenced.Itispossiblewithno_inlineformultipleevaluationsofthecommontableasneededbysourcequeries.
TheoptionalmaterializehintrequiresthatthecommontablebecreatedasatemporarytableinTeiid.Thisforcesasingleevaluationofthecommontable.
Note TheWITHclauseisalsosubjecttooptimizationandit’sentriesmaynotbeprocessediftheyarenotneededinthesubsequentquery.
Examples:
WITHn(x)AS(selectcolfromtbl)selectxfromn,nasn1
WITHn(x)AS/*+no_inline*/(selectcolfromtbl)selectxfromn,nasn1
RecursiveCommonTableExpressions
Arecursivecommontableexpressionisaspecialformofacommontableexpressionthatisallowedtorefertoitselftobuildthefullcommontableresultinarecursiveoriterativefashion.
Usage:
WITHname[(column,...)]AS(anchorqueryexpressionUNION[ALL]recursivequeryexpression)...
Therecursivequeryexpressionisallowedtorefertothecommontablebyname.ProcessingflowswithTheanchorqueryexpressionexecutedfirst.Theresultswillbeaddedtothecommontableandwillbereferencedfortheexecutionoftherecursivequeryexpression.Theprocesswillberepeatedagainstthenewresultsuntiltherearenomoreintermediateresults.
Note Anonterminatingrecursivecommontableexpressioncanleadtoexcessiveprocessing.
Topreventrunawayprocessingofarecursivecommontableexpression,processingisbydefaultlimitedto10000iterations.Recursivecommontableexpressionsthatarepusheddownarenotsubjecttothislimit,butmaybesubjecttoothersourcespecificlimits.Thelimitcanbemodifiedbysettingthesessionvariableteiid.maxRecusiontoalargerintegervalue.Oncethemaxhas
DMLCommands
359
![Page 360: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/360.jpg)
beenexceededanexceptionwillbethrown.
Example:
SELECTteiid_session_set('teiid.maxRecursion',25);
WITHn(x)AS(values('a')UNIONselectchr(ascii(x)+1)fromnwherex<'z')select*fromn
Thiswillfailtoprocessastherecursionlimitwillbereachedbeforeprocessingcompletes.
DMLCommands
360
![Page 361: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/361.jpg)
SELECTClauseSQLqueriesthatstartwiththeSELECTkeywordandareoftenreferredtoas"SELECTstatements".TeiidsupportsmostofthestandardSQLqueryconstructs.
Usage:
SELECT[DISTINCT|ALL]((expression[[AS]name])|(groupidentifier.STAR))*|STAR...
SyntaxRules:
AliasedexpressionsareonlyusedastheoutputcolumnnamesandintheORDERBYclause.Theycannotbeusedinotherclausesofthequery.
DISTINCTmayonlybespecifiediftheSELECTsymbolsarecomparable.
DMLCommands
361
![Page 362: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/362.jpg)
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
362
![Page 363: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/363.jpg)
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
363
![Page 364: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/364.jpg)
XMLTABLETheXMLTABLEfunctionusesXQuerytoproducetabularoutput.TheXMLTABLEfunctionisimplicitlyanestedtableandmaybecorrelatedtoprecedingFROMclauseentries.XMLTABLEispartoftheSQL/XML2006specification.
Usage:
XMLTABLE([<NSP>,]xquery-expression[<PASSING>][COLUMNS<COLUMN>,...)]ASname
COLUMN:=name(FORORDINALITY|(datatype[DEFAULTexpression][PATHstring]))
SeeXMLELEMENTforthedefinitionofNSP-XMLNAMESPACES.
SeeXMLQUERYforthedefinitionofPASSING.
SeealsoXMLQUERY
Note SeealsoXQueryOptimization
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
364
![Page 365: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/365.jpg)
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
365
![Page 366: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/366.jpg)
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
366
![Page 367: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/367.jpg)
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
367
![Page 368: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/368.jpg)
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
368
![Page 369: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/369.jpg)
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
369
![Page 370: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/370.jpg)
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
370
![Page 371: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/371.jpg)
WHEREClauseTheWHEREclausedefinesthecriteriatolimittherecordsaffectedbySELECT,UPDATE,andDELETEstatements.
ThegeneralformoftheWHEREis:
WHERECriteria
DMLCommands
371
![Page 372: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/372.jpg)
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
372
![Page 373: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/373.jpg)
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
373
![Page 374: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/374.jpg)
HAVINGClauseTheHAVINGclauseoperatesexactlyasaWHEREclausealthoughitoperatesontheoutputofaGROUPBY.ItsupportsthesamesyntaxastheWHEREclause.
SyntaxRules:
Expressionsusedinthegroupbyclausemusteithercontainanaggregatefunction:COUNT,AVG,SUM,MIN,MAX.orbeoneofthegroupingexpressions.
DMLCommands
374
![Page 375: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/375.jpg)
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
375
![Page 376: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/376.jpg)
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
376
![Page 377: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/377.jpg)
INTOClause
Warning UsageoftheINTOClauseforinsertingintoatablehasbeenbeendeprecated.AnINSERTwithaquerycommandshouldbeusedinstead.
WhentheintoclauseisspecifiedwithaSELECT,theresultsofthequeryareinsertedintothespecifiedtable.Thisisoftenusedtoinsertrecordsintoatemporarytable.TheINTOclauseimmediatelyprecedestheFROMclause.
Usage:
INTOtableFROM...
SyntaxRules:
TheINTOclauseislogicallyappliedlastinprocessing,aftertheORDERBYandLIMITclauses.
Teiid’ssupportforSELECTINTOissimilartoMSSQLServer.ThetargetoftheINTOclauseisatablewheretheresultoftherestselectcommandwillbeinserted.SELECTINTOshouldnotbeusedUNIONquery.
DMLCommands
377
![Page 378: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/378.jpg)
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
378
![Page 379: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/379.jpg)
DDLCommandsTeiidsupportsasubsetofDDLatruntimetocreate/droptemporarytablesandtomanipulateprocedureandviewdefinitions.Itisnotcurrentlypossibletoarbitrarilydrop/createnon-temporarymetadataentries.SeeDDLMetadataforDDLusedwithinaVDBtodefineschemas.
Note AMetadataRepositorymustbeconfiguredtomakeanon-temporarymetadataupdatepersistent.SeetheDevelopersGuideRuntimeMetadataUpdatessectionformore.
DDLCommands
379
![Page 380: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/380.jpg)
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
380
![Page 381: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/381.jpg)
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
381
![Page 382: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/382.jpg)
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
382
![Page 383: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/383.jpg)
DDLCommands
383
![Page 384: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/384.jpg)
AlterViewUsage:
ALTERVIEWnameASqueryExpression
SyntaxRules:
Thealterqueryexpressionmaybeprefixedwithacachehintformaterializedviewdefinitions.Thehintwilltakeeffectthenexttimethematerializedviewtableisloaded.
DDLCommands
384
![Page 385: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/385.jpg)
AlterProcedureUsage:
ALTERPROCEDUREnameASblock
SyntaxRules:
ThealterblockshouldnotincludeCREATEVIRTUALPROCEDURE
Thealterblockmaybeprefixedwithacachehintforcachedprocedures.
DDLCommands
385
![Page 386: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/386.jpg)
AlterTriggerUsage:
ALTERTRIGGERONnameINSTEADOFINSERT|UPDATE|DELETE(ASFOREACHROWblock)|(ENABLED|DISABLED)
SyntaxRules:
Thetarget,name,mustbeanupdatableview.
Triggersarenotyettrueschemaobjects.Theyarescopedonlytotheirviewandhavenoname.
AnUpdateProcedures(Triggers)mustalreadyexistforthegiventriggerevent.
Note IfthedefaultinherentupdateischoseninTeiidDesigner,anySQLassociatedwithupdate(showninagreyedouttextbox)isnotpartoftheVDBandcannotbeenabledwithanaltertriggerstatement.
DDLCommands
386
![Page 387: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/387.jpg)
XMLSELECTCommandNOTE:XMLDocumentsModelsaredeprecated.YoushoulduseSQL/XMLfunctionsorODataaccesstoformcomplexdocumentsinstead.
ComplexXMLdocumentscanbedynamicallyconstructedbyTeiidusingXMLDocumentModels.Adocumentmodelisgenerallycreatedfromaschema.ThedocumentmodelisboundtorelevantSQLstatementsthroughmappingclasses.SeetheDesignerguideformoreoncreatingdocumentmodels.
XMLdocumentsmayalsocreatedviaXQuerywiththeXMLQueryfunctionorwithvariousotherSQL/XMLfunctions.
QueryingXMLdocumentsissimilartoqueryingrelationaltables.AnidiomaticSQLvariantwithspecialscalarfunctionsgivescontroloverwhichpartsofagivendocumenttoreturn.
XMLSELECTCommand
387
![Page 388: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/388.jpg)
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
388
![Page 389: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/389.jpg)
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
389
![Page 390: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/390.jpg)
Limitstherowsprocessedforthegivencontext.
SyntaxRules:
Thefirstargumentmustbeanelementorattributereferencefromthemappingclasswhosecontexttherowlimitapplies.
Therowlimitfunctionmustbeusedinequalitycomparisoncriteriawiththerighthandexpressionequaltoanpositiveintegernumberorrowstolimit.
Onlyonerowlimitorrowlimitexceptionmayapplytoagivencontext.
RowlimitexceptionFunction
Limitstherowsprocessedforthegivencontextandthrowsanexceptionifthegivennumberofrowsisexceeded.
ROWLIMITEXCEPTION(arg)
SyntaxRules:
Thefirstargumentmustbeanelementorattributereferencefromthemappingclasswhosecontexttherowlimitexceptionapplies.
Therowlimitexceptionfunctionmustbeusedinequalitycomparisoncriteriawiththerighthandexpressionequaltoanpositiveintegernumberorrowstolimit.
Onlyonerowlimitorrowlimitexceptionmayapplytoagivencontext.
ORDERBYClauseTheXMLSELECTCommandORDERBYClausespecifiesorderingforthereferencedmappingclassqueries.
SyntaxRules:
Eachorderbyitemmustbeanelementorattributereferencetiedaoutputvaluefromamappingclass.
Theorderortheorderbyitemsistherelativeordertheywillbeappliedtotheirrespectivemappingclasses.
XMLSELECTCommand
390
![Page 391: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/391.jpg)
DocumentGenerationDocumentgenerationstartswiththerootmappingclassandproceedsiterativelyandhierarchicallyoverallofthechildmappingclasses.Thiscanresultinalargenumberofqueryexecutions.Forexampleifadocumenthasarootmappingclasswith3childmappingclasses.Thenforeachrowselectedbytherootmappingclassaftertheapplicationoftherootcontextcriteria,eachofthechildmappingclassesquerieswillalsobeexecuted.
Note
DocumentCorrectness-BydefaultXMLgeneratedbyXMLdocumentsarenotcheckedforcorrectnessvs.therelevantschema.Itispossiblethatthemappingclassqueries,theusageofspecificSELECTorWHEREclausevalueswillgeneratedadocumentthatisnotvalidwithrespecttotheschema.SeeDocumentValidationonhowtoensurecorrectness.
Siblingorcousinelementsdefinedbythesamemappingclassthatdonothaveacommonparentinthatmappingclasswillbetreatedasindependentmappingclassesduringplanningandexecution.Thisallowsforamoredocumentcentricapproachtoapplyingcriteriaandorderbystomappingclasses.
DocumentValidationTheexecutionpropertyXMLValidationshouldbesetto'true'toindicatethatgenerateddocumentsshouldbecheckedforcorrectness.Correctnesscheckingwillnotpreventinvaliddocumentsfrombeinggenerated,sincecorrectnessischeckedaftergenerationandnotduring.
XMLSELECTCommand
391
![Page 392: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/392.jpg)
Procedures
Procedures
392
![Page 393: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/393.jpg)
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
393
![Page 394: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/394.jpg)
DynamicSQLCommand
DynamicSQLallowsfortheexecutionofanarbitrarySQLcommandinavirtualprocedure.DynamicSQLisusefulinsituationswheretheexactcommandformisnotknownpriortoexecution.
Usage:
EXECUTEIMMEDIATE<sqlexpression>AS<variable><type>[,<variable><type>]*[INTO<variable>][USING<variab
le>=<expression>[,<variable>=<expression>]*][UPDATE<literal>]
SyntaxRules:
Thesqlexpressionmustbeaclob/stringvaluelessthan262144characters.
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.OtherwiseifavalueisspecifiedforLastNametheprocedurewilldetectifthevalueisasearch
Procedures
394
![Page 395: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/395.jpg)
string.IfbdayisspecifiedinadditiontoLastName,itwillbeusedtoformcompoundcriteriawithLastName.
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.
Procedures
395
![Page 396: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/396.jpg)
Whenusingthe"AS"clauseonlythetypeinformationwillbeavailabletotheDesigner.ResultSetcolumnsgeneratedfromthe"AS"clausethenwillhaveadefaultsetofpropertiesforlength,precision,etc.
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
Procedures
396
![Page 397: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/397.jpg)
VARIABLES.ROWCOUNTintegervariablewillcontainthenumbersofrowsaffectedbythelastinsert/update/deletecommandstatementexecuted.InsertsthatareprocessedbydynamicsqlwithanintoclausewillalsoupdatetheROWCOUNT.
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.
Procedures
397
![Page 398: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/398.jpg)
Note Onlyprocessingexceptions,whicharetypicallycausedbyerrorsoriginatingatthesourcesorwithfunctionexecution,arecaught.Alow-levelinternalTeiiderrororJavaRuntimeExceptionwillnotbecaught.
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
IfStatementAnIFstatementevaluatesaconditionandexecuteseitheroneoftwostatementsdependingontheresult.YoucannestIFstatementstocreatecomplexbranchinglogic.AdependentELSEstatementwillexecuteitsstatementonlyiftheIFstatementevaluatestofalse.
Usage:
IF(criteria)
block
[ELSE
block]
END
ExampleIfStatement
Procedures
398
![Page 399: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/399.jpg)
IF(var1='NorthAmerica')
BEGIN
...statement...
ENDELSE
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
Thelabelmustnotbethesameasanyotherlabelusedinstatementscontainingthisone.
WhileStatement
AWHILEstatementisaniterativecontrolconstructthatisusedtoexecuteastatementrepeatedlywheneveraspecifiedconditionismet.
Usage:
[label:]WHILE<criteria>
statement
SyntaxRules
Thelabelmustnotbethesameasanyotherlabelusedinstatementscontainingthisone.
Procedures
399
![Page 400: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/400.jpg)
ContinueStatement
ACONTINUEstatementisusedinsideaLOOPorWHILEconstructtocontinuewiththenextloopbyskippingovertherestofthestatementsintheloop.ItmustbeusedinsideaLOOPorWHILEstatement.
Usage:
CONTINUE[label];
SyntaxRules
Ifthelabelisspecified,itmustexistonacontainingLOOPorWHILEstatement.
Ifnolabelisspecified,thestatementwillaffecttheclosestcontainingLOOPorWHILEstatement.
BreakStatement
ABREAKstatementisusedinsideaLOOPorWHILEconstructtobreakfromtheloop.ItmustbeusedinsideaLOOPorWHILEstatement.
Usage:
BREAK[label];
SyntaxRules
Ifthelabelisspecified,itmustexistonacontainingLOOPorWHILEstatement.
Ifnolabelisspecified,thestatementwillaffecttheclosestcontainingLOOPorWHILEstatement.
LeaveStatement
ALEAVEstatementisusedinsideacompound,LOOP,orWHILEconstructtoleavetothespecifiedlevel.
Usage:
LEAVElabel;
SyntaxRules
Thelabelmustexistonacontainingcompoundstatement,LOOP,orWHILEstatement.
ReturnStatementAReturnstatementgracefullyexitstheprocedureandoptionallyreturnsavalue.
Usage:
RETURN[expression];
SyntaxRules
Procedures
400
![Page 401: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/401.jpg)
Ifanexpressionisspecified,theproceduremusthaveareturnparameterandthevaluemustbeimplicitlyconvertabletotheexpectedtype.
Eveniftheprocedurehasareturnvalue,itisnotrequiredtospecifyareturnvalueinaRETURNstatement.
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
Procedures
401
![Page 402: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/402.jpg)
Anyofthevaluesmaybenull;
messageandstatearestringexpressionsspecifyingtheexceptionmessageandSQLstaterespectively.TeiiddoesnotyetfullycomplywiththeANSISQLspecificationonSQLstateusage,butyouareallowedtosetanySQLstateyouchoose.
codeisanintegerexpressionspecifyingthevendorcode
exceptionmustbeavariablereferencetoanexceptionoranexceptionexpressionandwillbechainedtotheresultingexceptionasitsparent.
Procedures
402
![Page 403: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/403.jpg)
VirtualProceduresVirtualproceduresaredefinedusingtheTeiidprocedurallanguage.Avirtualprocedurehaszeroormoreinput/inout/outparameters,anoptionalreturnparameter,andanoptionalresultset.VirtualproceduressupporttheabilitytoexecutequeriesandotherSQLcommands,definetemporarytables,adddatatotemporarytables,walkthroughresultsets,useloops,anduseconditionallogic.
TableofContentsVirtualProcedureDefinitionProcedureParametersExampleVirtualProceduresExecutingVirtualProceduresLimitations
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
403
![Page 404: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/404.jpg)
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
404
![Page 405: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/405.jpg)
Limitations
Teiidvirtualproceduresmayonlyreturn1resultset.Ifyouneedtopassinaresultsetorpassoutmultipleresultset,thenconsiderusingglobaltemporarytables.
Procedures
405
![Page 406: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/406.jpg)
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
406
![Page 407: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/407.jpg)
--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
407
![Page 408: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/408.jpg)
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
408
![Page 409: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/409.jpg)
CommentsTeiidsupportsmulti-linecommentsenclosedwith/**/:
/*comment
comment
comment...*/
Andsinglelinecomments:
SELECT...--comment
Commentnestingissupported.
Comments
409
![Page 410: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/410.jpg)
Datatypes
Datatypes
410
![Page 411: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/411.jpg)
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
411
![Page 412: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/412.jpg)
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,butmaybeenforced/reportedattheedgebyOData,ODBC,JDBC.
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
412
![Page 413: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/413.jpg)
Arrays
Warning Teiid’ssupportforarraysisanewfeatureasofthe8.5release.Supportwillberefinedandenhancedinsubsequentreleases.
Anarrayofanytypeisdesignatedbyadding[]foreacharraydimensiontothetypedeclaration.
Examplearraytypes:
string[]
integer[][]
Note Teiidarrayhandlingistypicallyinmemory.Itisnotadvisabletorelyontheusageoflargearrayvalues.Alsoarraysoflobsarenotwellsupportedandwilltypicallynotbehandledcorrectlywhenserialized.
SupportedTypes
413
![Page 414: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/414.jpg)
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
TypeConversions
414
![Page 415: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/415.jpg)
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
415
![Page 416: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/416.jpg)
SpecialConversionCases
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.
SpecialConversionCases
416
![Page 417: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/417.jpg)
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
417
![Page 418: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/418.jpg)
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
418
![Page 419: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/419.jpg)
preservedTableAkey-preservedtablehasaprimaryoruniquekeythatwouldremainuniqueifitwereprojectedintotheresultofthequery.NotethatitisnotactuallyrequiredforaviewtoreferencethekeycolumnsintheSELECTclause.Thequeryenginecandetectakeypreservedtablebyanalyzingthejoinstructure.Theenginewillensurethatajoinofakey-preservedtablemustbeagainstoneofitsforeignkeys.
preservedTable
419
![Page 420: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/420.jpg)
TransactionSupportTeiidutilizesXAtransactionsforparticipatinginglobaltransactionsandfordemarcatingitslocalandcommandscopedtransactions.JBossTransactionsisusedbyTeiidasitstransactionmanager.SeethisdocumentationfortheadvancedfeaturesprovidedbyJBossTransactions.
Table1.TeiidTransactionScopes
Scope Description
Command
Treatstheusercommandasifallsourcecommandsareexecutedwithinthescopeofthesametransaction.TheAutoCommitTxnexecutionpropertycontrolsthebehaviorofcommandleveltransactions.
Local Thetransactionboundaryislocaldefinedbyasingleclientsession.
Global TeiidparticipatesinaglobaltransactionasanXAResource.
ThedefaulttransactionisolationlevelforTeiidisREAD_COMMITTED.
TransactionSupport
420
![Page 421: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/421.jpg)
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
421
![Page 422: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/422.jpg)
UpdatingModelCountTheterm"updatingmodelcount"referstothenumberoftimesanymodelisupdatedduringtheexecutionofacommand.Itisusedtodeterminewhetheratransaction,ofanyscope,isrequiredtosafelyexecutethecommand.
Table1.UpdatingModelCountSettings
Count Description
0 Noupdatesareperformedbythiscommand.
1
Indicatesthatonlyonemodelisupdatedbythiscommand(anditssubcommands).Alsothesuccessorfailureofthatupdatecorrespondstothesuccessoffailureofthecommand.Itshouldnotbepossiblefortheupdatetosucceedwhilethecommandfails.Executionisnotconsideredtransactionallyunsafe.
*Anynumbergreaterthan1indicatesthatexecutionistransactionallyunsafeandanXAtransactionwillberequired.
UpdatingModelCount
422
![Page 423: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/423.jpg)
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
423
![Page 424: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/424.jpg)
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
TransactionalBehaviorwithJBossDataSourceTypes
424
![Page 425: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/425.jpg)
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
TransactionalBehaviorwithJBossDataSourceTypes
425
![Page 426: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/426.jpg)
LimitationsandWorkaroundsTheclientsettingoftransactionisolationlevelisnotpropogatedtotheconnectors.ThetransactionisolationlevelcanbesetoneachXAconnector,howeverthisisolationlevelisfixedandcannotbechangedatruntimeforspecificconnections/commands.
LimitationsandWorkarounds
426
![Page 427: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/427.jpg)
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
427
![Page 428: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/428.jpg)
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
428
![Page 429: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/429.jpg)
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
429
![Page 430: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/430.jpg)
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
430
![Page 431: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/431.jpg)
Limitations
Intheeventthattwomaskshavethesameordervalue,itisnotwelldefinedwhatordertheyareappliedin.
Masksortheirconditionsmaynotcontainaggregateorwindowedfunctions.
Tablesandproceduresreferencedviasubquerieswillstillhaverow-basedfiltersandcolumnmaskingappliedtothem.
Note Maskingisenforcedevenformaterializedviewloads.
Youshouldensurethattablesconsumedtoproducematerializedviewsdonothavemaskingonthemthatcouldaffectthematerializedviewresults.
Permissions
431
![Page 432: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/432.jpg)
RoleMappingEachTeiiddatarolecanbemappedtoanynumberofcontainerrolesoranyauthenticateduser.YoumaycontrolrolemembershipthroughwhateversystemtheTeiidsecuritydomainloginmodulesareassociatedwith.ThekitincludesexamplefilesforusewiththeUsersRolesLoginModule-seeteiid-security-roles.properties.
IfyouhavemorethanonesecuritydomainforthetransportorsimplyhaveanalternativesecuritydomainthataVDBshoulduse,thensettheVDBpropertysecurity-domaintotherelevantsecuritydomain.
Itispossibleforausertohaveanynumberofcontainerroles,whichinturnimplyasubsetofTeiiddataroles.EachapplicableTeiiddatarolecontributescumulativelytothepermissionsoftheuser.Noonerolesupersedesornegatesthepermissionsoftheotherdataroles.
RoleMapping
432
![Page 433: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/433.jpg)
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
<?xmlversion="1.0"encoding="UTF-8"?>
<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>
<allow-read>true</allow-read>
</permission>
<permission>
<resource-name>modelName.TableA.colum2</resource-name>
<allow-read>false</allow-read>
</permission>
<mapped-role-name>role2</mapped-role-name>
</data-role>
<data-rolename="admin"grant-all="true">
<description>Adminrole</description>
<mapped-role-name>admin-group</mapped-role-name>
</data-role>
</vdb>
XMLDefinition
433
![Page 434: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/434.jpg)
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
<?xmlversion="1.0"encoding="UTF-8"?>
<vdbname="sample"version="1">
<propertyname="allowed-languages"value="javascript"/>
<modelname="modelName">
<sourcename="source-name"translator-name="oracle"connection-jndi-name="java:myDS"/>
</model>
<data-rolename="RoleA">
<description>Readandjavascriptaccess.</description>
<permission>
<resource-name>modelName</resource-name>
<allow-read>true</allow-read>
</permission>
<permission>
<resource-name>javascript</resource-name>
<allow-language>true</allow-language>
</permission>
<mapped-role-name>role1</mapped-role-name>
</data-role>
</vdb>
Row-BasedSecurity
XMLDefinition
434
![Page 435: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/435.jpg)
Thefollowingshowsavdbxmlutilizingaconditiontorestrictaccess.Theconditionactsasbothafilterandconstraint.EventhoughRoleAopensupread/insertaccesstomodelName.tblName,thebase-roleconditionwillensurethatonlyvaluesofcolumn1matchingthecurrentusercanbereadorinserted.Notethatheretheconstraintenforcementhasbeendisabled.
vdb.xmlallowingconditionalaccess
<?xmlversion="1.0"encoding="UTF-8"?>
<vdbname="sample"version="1">
<modelname="modelName">
<sourcename="source-name"translator-name="oracle"connection-jndi-name="java:myDS"/>
</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>
<data-rolename="RoleA">
<description>Read/Insertaccess.</description>
<permission>
<resource-name>modelName.tblName</resource-name>
<allow-read>true</allow-read>
<allow-create>true</allow-create>
</permission>
<mapped-role-name>role1</mapped-role-name>
</data-role>
</vdb>
ColumnMasking
Thefollowingshowsavdbxmlutilizingcolumnmasking.HeretheRoleAcolumn1masktakesprecedenceoverthebase-rolemask,butonlyforasubsetoftherowsasspecifiedbythecondition.ForuserswithoutRoleA,accesstocolumn1willeffectivelybereplacedwith"CASEWHENcolumn1=user()THENcolumn1END",whileforuserswithRoleA,accesstocolumn1willeffectivelybereplacedwith"CASEWHENcolumn2=’x’THENcolumn1WHENTRUETHENCASEWHENcolumn1=user()THENcolumn1ENDEND".
vdb.xmlwithcolumnmasking
<?xmlversion="1.0"encoding="UTF-8"?>
<vdbname="sample"version="1">
<modelname="modelName">
<sourcename="source-name"translator-name="oracle"connection-jndi-name="java:myDS"/>
</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>
<data-rolename="RoleA">
XMLDefinition
435
![Page 436: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/436.jpg)
<description>Read/Insertaccess.</description>
<permission>
<resource-name>modelName.tblName</resource-name>
<allow-read>true</allow-read>
<allow-create>true</allow-create>
</permission>
<permission>
<resource-name>modelName.tblName.column1</resource-name>
<condition>column2='x'</condition>
<maskorder="1">column1</mask>
</permission>
<mapped-role-name>role1</mapped-role-name>
</data-role>
</vdb>
XMLDefinition
436
![Page 437: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/437.jpg)
CustomizingSeetheDeveloper’sGuidechaptersonCustomAuthorizationValidatorsand[Teiid:LoginModules]fordetailsonusinganalternativeauthorizationscheme.
Customizing
437
![Page 438: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/438.jpg)
SystemSchemaThebuilt-inSYSandSYSADMINschemasprovidemetadatatablesandproceduresagainstthecurrentVDB.
BydefaultasystemschemaforODBCmetadatapg_catalogisalsoexposed-howeverthatshouldbeconsideredforgeneraluse.
MetadataVisibility
TheSYSsystemschematablesandproceduresarealwaysvisible/accessible.
UnlikeTeiid8.xandpriorreleaseswhenDataRolesareinusetable/viewsandproceduremetadataentrieswillnotbevisibleiftheuserisnotentitledtousetheobject.Tables/views/columnsrequiretheREADpermissionandproceduresrequiretheEXECUTEpermission.Allcolumnsofakeymustbeaccessiblefortheentrytobevisible.
Note Ifthereisanycachingofsystemmetadatawhendatarolesareinuse,thenvisibilityneedstobeconsidered.
SystemSchema
438
![Page 439: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/439.jpg)
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 integerNumberofdigitsafterthedecimalpoint
SYS
439
![Page 440: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/440.jpg)
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
440
![Page 441: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/441.jpg)
Description string Description
TableUID string ParentTableuniqueID
SYS.DataTypes
Thistablesuppliesinformationondatatypes.
ColumnName Type Description
Name string Teiiddesign-timetypename
IsStandard boolean Alwaysfalse
IsPhysical boolean Alwaysfalse
TypeName string Design-timetypename(sameasName)
JavaClass string Javaclassreturnedforthistype
Scale integer Maxscaleofthistype
TypeLength integer Maxlengthofthistype
NullType string Nullability:"Nullable","NoNulls","Unknown"
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
441
![Page 442: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/442.jpg)
Thistablesuppliesinformationaboutthecolumnsreferencedbyakey.
ColumnName Type Description
VDBName string VDBname
SchemaName string SchemaName
TableName string Tablename
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.
ColumnName Type Description
VDBName string VDBname
SchemaName string SchemaName
TableName string Tablename
Name string Keyname
Description string Description
NameInSource string Nameofkeyinsourcesystem
Type string Typeofkey:"Primary","Foreign","Unique",etc
IsIndexed boolean Trueifkeyisindexed
RefKeyUID string ReferencedkeyUID(ifforeignkey)
UID string KeyuniqueID
SYS
442
![Page 443: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/443.jpg)
SYS.ProcedureParams
Thissuppliesinformationonprocedureparameters.
ColumnName Type Description
VDBName string VDBname
SchemaName string SchemaName
ProcedureName string Procedurename
Name string Parametername
DataType string Teiidruntimedatatypename
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
NullType string Nullability:"Nullable","NoNulls","Unknown"
Description string Descriptionofparameter
SYS.Procedures
Thistablesuppliesinformationabouttheproceduresinthevirtualdatabase.
ColumnName Type Description
VDBName string VDBname
SchemaName string SchemaName
Name string Procedurename
NameInSource string Procedurenameinsourcesystem
ReturnsResults boolean Returnsaresultset
UID string ProcedureUID
SYS
443
![Page 444: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/444.jpg)
Description string Description
SchemaUID string ParentSchemauniqueID
SYS.FunctionParams
Thissuppliesinformationonfunctionparameters.
ColumnName Type Description
VDBName string VDBname
SchemaName string SchemaName
FunctionName string Functionname
FunctionUID string FunctionUID
Name string Parametername
DataType string Teiidruntimedatatypename
Position integer Positioninprocedureargs
Type string Parameterdirection:"In","Out","InOut","ResultSet","ReturnValue"
Precision integer Precisionofparameter
TypeLength integer Lengthofparametervalue
Scale integer Scaleofparameter
Radix integer Radixofparameter
NullType string Nullability:"Nullable","NoNulls","Unknown"
Description string Descriptionofparameter
SYS.Functions
Thistablesuppliesinformationaboutthefunctionsinthevirtualdatabase.
ColumnName Type Description
VDBName string VDBname
SchemaName string SchemaName
Name string Functionname
Functionnameinsourcesystem
SYS
444
![Page 445: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/445.jpg)
Functionnameinsourcesystem
UID string FunctionUID
Description string Description
IsVarArgs boolean Doesthefunctionacceptvariablearguments
SYS.Properties
Thistablesuppliesuser-definedpropertiesonallobjectsbasedonmetamodelextensions.Normally,thistableisemptyifnometamodelextensionsarebeingused.
ColumnName Type Description
Name string Extensionpropertyname
Value string Extensionpropertyvalue
UID string KeyuniqueID
ClobValue clob ClobValue
SYS.ReferenceKeyColumns
Thistablesuppliesinformatonaboutcolumn’skeyreference.
ColumnName Type Description
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
445
![Page 446: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/446.jpg)
FK_NAME string FKName
PK_NAME string PKNmae
DEFERRABILITY integer
SYS.Schemas
Thistablesuppliesinformationaboutalltheschemasinthevirtualdatabase,includingthesystemschemaitself(System).
ColumnName Type Description
VDBName string VDBname
Name string Schemaname
IsPhysical boolean Trueifthisrepresentsasource
UID string UniqueID
Description string Description
PrimaryMetamodelURI stringURIfortheprimarymetamodeldescribingthemodelusedforthisschema
SYS.Tables
Thistablesuppliesinformationaboutallthegroups(tables,views,documents,etc)inthevirtualdatabase.
ColumnName Type Description
VDBName string VDBname
SchemaName string SchemaName
Name string Shortgroupname
Type string Tabletype(Table,View,Document,…)
NameInSource string Nameofthisgroupinthesource
IsPhysical boolean Trueifthisisasourcetable
SupportsUpdates boolean Trueifgroupcanbeupdated
UID string GroupuniqueID
Cardinality integer Approximatenumberofrowsinthegroup
Description string Description
SYS
446
![Page 447: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/447.jpg)
IsSystem boolean Trueifinsystemtable
SchemaUID string ParentSchemauniqueID
SYS.VirtualDatabases
Thistablesuppliesinformationaboutthecurrentlyconnectedvirtualdatabase,ofwhichthereisalwaysexactlyone(inthecontextofaconnection).
ColumnName Type Description
Name string ThenameoftheVDB
Version string TheversionoftheVDB
SYS.spatial_sys_ref
SeealsothePostGISDocumentation
ColumnName Type Description
srid integer SpatialReferenceIdentifier
auth_name string Nameofthestandardorstandardsbody
auth_srid integer SRIDfortheauth_nameauthority
srtext string Well-KnownTextrepresentation
proj4text string ForusewiththeProj4library
SYS.GEOMETRY_COLUMNS
SeealsothePostGISDocumentation
ColumnName Type Description
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
447
![Page 448: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/448.jpg)
Note:Thecoord_dimensionandsridpropertiesaredeterminedfromthe{http://www.teiid.org/translator/spatial/2015}coord_dimensionand{http://www.teiid.org/translator/spatial/2015}sridextensionpropertiesonthecolumn.Whenpossiblethesevalueswillbesetautomaticallybytherelevantimporter.Iftheyarenotset,theywillbereportedas2and0respectively.Ifclientlogicexpectsactualvalues,suchasintegrationwithGeoServer,thenyoumayneedtosetthesevaluesmanually.
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
448
![Page 449: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/449.jpg)
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.
ColumnName Type Description
VDBName string VDBname
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
449
![Page 450: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/450.jpg)
Uses_Name string UsedobjectnameorparentnameifUses_ElementNameisnotnull
Uses_ElementName string Usedcolumnorparametername
ExampleSYSADMIN.Usage
SELECT*FROMSYSADMIN.Usage
SYSADMIN.MatViews
Thistablesuppliesinformationaboutallthematerailizedviewsinthevirtualdatabase.
ColumnName Type Description
VDBName string VDBname
SchemaName string SchemaName
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.
ColumnName Type Description
SYSADMIN
450
![Page 451: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/451.jpg)
resourcePath string Thepathtothecontents.
contents blob Thecontentsasablob.
ExampleSYSADMIN.VDBResources
SELECT*FROMSYSADMIN.VDBResources
SYSADMIN.Triggers
ThistableprovidestheTriggersinthevirtualdatabase.
ColumnName Type Description
VDBName string VDBname
SchemaName string SchemaName
TableName string Tablename
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.
ColumnName Type Description
VDBName string VDBname
SchemaName string SchemaName
Name string Viewname
Body clob ViewDefinitionBody(SELECT…)
UID string TableUniqueID
SYSADMIN
451
![Page 452: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/452.jpg)
ExampleSYSADMIN.Views
SELECT*FROMSYSADMIN.Views
SYSADMIN.StoredProcedures
ThistableprovidestheStoredProceduresinthevirtualdatabase.
ColumnName Type Description
VDBName string VDBname
SchemaName string SchemaName
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
452
![Page 453: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/453.jpg)
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
453
![Page 454: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/454.jpg)
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
454
![Page 455: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/455.jpg)
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.-1indicatesthematerializedtableiscurrentlyloading.And-3indicatestherewasanexceptionwhenperformingtheload.SeetheCachingGuideformore.
SYSADMIN.loadMatView(INschemaNamestringNOTNULL,INviewNamestringNOTNULL,INinvalidatebooleanNOTNULL
DEFAULT'false')RETURNSinteger
ExampleloadMatView
execSYSADMIN.loadMatView(schemaName=>'TestMat',viewname=>'SAMPLEMATVIEW',invalidate=>'true')
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
455
![Page 456: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/456.jpg)
VDBsAVirtualDatabaseorVDBisthecoreabstractionlayerforTeiid.AVDBdefineshowtointegrateandexposeasetofsources.
VDBs
456
![Page 457: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/457.jpg)
VDBDefinitionAVDBorvirtualdatabasedefinitioniscontainedinanXMLfile.For.vdbarchivefilescreatedinthedesigntool,thisfileisembeddedinthearchiveandmostfieldscanbeupdatedthroughtooling.TheXMLschemaforthisfilecanbefoundinthedocs/teiid/schemadirectory.
ExampleVDBXML
<vdbname="${vdb-name}"version="${vdb-version}">
<!--Optionaldescription-->
<description>...</description>
<!--Optionalconnection-type-->
<connection-type>...</connection-type>
<!--VDBproperties-->
<propertyname="${property-name}"value="${property-value}"/>
<!--UDFdefinedinanASmodule,seeDevelopersGuide-->
<propertyname="lib"value="{module-name}"></property>
<import-vdbname="..."version="..."import-data-policies="true|false"/>
<!--defineamodelfragmentforeachdatasource-->
<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>
<!--additionalmetadata
<metadatatype="${repository-type}">rawtext</metadata>
-->
</model>
<!--defineamodelwithmultiplesources-seeMulti-SourceModels-->
<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>
<!--seeReferenceGuide-DataRoles-->
<data-rolename="${role-name}">
<description>${role-description}</description>
….
</data-role>
<!--createtranslatorinstancesthatoverridedefaultproperties-->
<translatorname="${translator-name}"type="${translator-type}"/>
<propertyname="..."value="..."/>
</translator>
</vdb>
VDBDefinition
457
![Page 458: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/458.jpg)
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
458
![Page 459: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/459.jpg)
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
459
![Page 460: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/460.jpg)
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.ThereshouldbeacorrespondingdatasourcethatdefinestheconnectionfactoryintheJBossAS.CheckoutthedeployingVDBdependenciessectionforinfo.YoualsoneedtodefinetheseconnectionfactoriesbeforeyoucandeploytheVDB.
PropertyElements
importer.<propertyname>
Propertytobeusedbytheconnectorimporterforthemodelforpurposesimportingmetadata.Seepossiblepropertyname/valuesintheTranslatorspecificsection.Notethatusingthesepropertiesyoucannarroworwidenthedataelementsavailableforintegration.
MetadataElement
VDBDefinition
460
![Page 461: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/461.jpg)
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
461
![Page 462: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/462.jpg)
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
462
![Page 463: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/463.jpg)
VDBsWithoutTooling
463
![Page 464: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/464.jpg)
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"/>
<!--optionalproperties
<propertyname="multisource.columnName"value="somename"/>
<propertyname="multisource.addColumn"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
464
![Page 465: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/465.jpg)
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
465
![Page 466: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/466.jpg)
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
466
![Page 467: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/467.jpg)
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">
<metadatatype="DDL"><![CDATA[
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
467
![Page 468: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/468.jpg)
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
468
![Page 469: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/469.jpg)
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)
Property DataTypeorAllowedValues Description
UUID stringAuniqueidentifierforthecolumn
NAMEINSOURCE string
IfthisisacolumnnameontheFOREIGNtable,thisvaluerepresentsnameofthecolumninsourcedatabase,ifomittedthecolumnnameisused
DDLMetadata
469
![Page 470: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/470.jpg)
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
470
![Page 471: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/471.jpg)
ColumnsmayalsobemarkedasNOTNULL,auto_increment,andwithaDEFAULTvalue.Currentlyonlystringvaluesaresupportedasthedefaultvalue.Tohavethestringinterpretedasanexpressionusetheextensionpropertyteiid_rel:default_handlingsettoexpression.
Acolumnoftypebigdecimal/decimal/numericcanbedeclaredwithoutaprecision/scalewhichwilldefaulttoaninternalmaximumforprecisionwithhalfscale,orwithaprecisionwhichwilldefaulttoascaleof0.
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
471
![Page 472: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/472.jpg)
CreateProcedure/FunctionUsingthebelowsyntax,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)
Property DataTypeorAllowedValues Description
UUID string uniqueIdentifier
NAMEINSOURCE
Ifthisissourcefunction/procedurethenameinthephysicalsource,ifdifferentfromthelogicalnamegivenabove
DDLMetadata
472
![Page 473: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/473.jpg)
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:
Property DataTypeorAllowedValues Description
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
473
![Page 474: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/474.jpg)
NotethatvirtualfunctionsdefinedusingtheTeiidprocedurelanguagecannotbeaggregatefunctions.
NoteProvidingtheJARlibraries-IfyouhavedefinedaUDF(virtual)functionwithoutaTeiidproceduredeinition,thenitmustbeaccompaniedbyitsimplementationinJava.ToconfiguretheJavalibraryasdependencytotheVDB,seeSupportforUser-DefinedFunctions
PROCEDUREOPTIONS:(thebelowarewellknownoptions,anyotherspropertiesdefinedwillbeconsideredasextensionmetadata)
Property DataTypeorAllowedValues Description
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:
Property DataTypeorAllowedValues Description
native-query ParameterizedString
Appliestobothfunctionsandprocedures.Thereplacementforthefunctionsyntaxratherthanthestandardprefixformwithparens.SeealsoTranslators#native
DDLMetadata
474
![Page 475: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/475.jpg)
non-prepared booleanAppliestoJDBCproceduresusingthenative-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.
ALTERStatementALTERstatementscurrentlyprimarilysupportsaddingOPTIONSpropertiestoTables,ViewsandProcedures.UsingaALTERstatement,youcaneitheradd,modifyorremoveaproperty.
ALTERCOLUMN
DDLMetadata
475
![Page 476: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/476.jpg)
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
<?xmlversion="1.0"encoding="UTF-8"standalone="yes"?>
<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
476
![Page 477: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/477.jpg)
DDLMetadata
477
![Page 478: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/478.jpg)
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
<?xmlversion="1.0"encoding="UTF-8"standalone="yes"?>
<vdbname="twitter"version="1">
<description>ShowshowtocallWebServices</description>
<modelname="twitter">
<sourcename="twitter"translator-name="rest"connection-jndi-name="java:/twitterDS"/>
</model>
<modelname="twitterview"type="VIRTUAL">
<metadatatype="DDL"><![CDATA[
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
478
![Page 479: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/479.jpg)
<translatorname="rest"type="ws">
<propertyname="DefaultBinding"value="HTTP"/>
<propertyname="DefaultServiceMode"value="MESSAGE"/>
</translator>
</vdb>
DDLMetadata
479
![Page 480: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/480.jpg)
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">
<metadatatype="DDL"><![CDATA[
CREATEVIEWx(
yvarchar
)AS
select*fromold-model.tbl;
]]>
</metadata>
</model>
</vdb>
IntheaboveexamplethereuseVDBwillhaveaccesstoallofthemodelsdefinedinthecommonVDBandaddsinthe"new-model".
VDBReuse
480
![Page 481: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/481.jpg)
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
<?xmlversion="1.0"encoding="UTF-8"standalone="yes"?>
<vdbname="sample"version="1">
<propertyname="{http://teiid.org/rest}auto-generate"value="true"/>
<modelname="PM1">
<sourcename="text-connector"translator-name="loopback"/>
<metadatatype="DDL"><![CDATA[
CREATEFOREIGNTABLEG1(e1string,e2integer);
CREATEFOREIGNTABLEG2(e1string,e2integer);
]]></metadata>
</model>
<modelname="View"type="VIRTUAL">
<metadatatype="DDL"><![CDATA[
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>
RESTServiceThroughVDB
481
![Page 482: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/482.jpg)
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
RESTServiceThroughVDB
482
![Page 483: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/483.jpg)
BydefaultallthegeneratedRestbasedservicesaresecuredusing"HTTPBasic"withsecuritydomain"teiid-security"andwithsecurityrole"rest".However,thesepropertiescanbecustomizedbydefiningthetheninvdb.xmlfile.
Examplevdb.xmlfilesecurityspecification
<vdbname="sample"version="1">
<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);
}
RESTServiceThroughVDB
483
![Page 484: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/484.jpg)
RESTServiceThroughVDB
484
![Page 485: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/485.jpg)
MetadataRepositoriesTraditionallythemetadataforaVirtualDatabaseisbuiltbyTeiidDesignerandsuppliedtoTeiidenginethroughaVDBarchivefile.ThisVDBfilecontains.INDEXmetadatafiles.BydefaulttheyareloadedbyaMetadataRepositorywiththenameINDEX.Otherbuilt-inmetadatarepositoriesincludethefollowing:
NATIVE
Thisisonlyapplicableonsourcemodels(andisalsothedefault),whenusedthemetadataforthemodelisretrievedfromthesourcedatabaseitself.
Samplevdb.xmlfile
<vdbname="{vdb-name}"version="1">
<modelname="{model-name}"type="PHYSICAL">
<sourcename="AccountsDB"translator-name="oracle"connection-jndi-name="java:/oracleDS"/>
<metadatatype="NATIVE"></metadata>
</model>
</vdb>
DDL
Samplevdb.xmlfile
<vdbname="{vdb-name}"version="1">
<modelname="{model-name}"type="PHYSICAL">
<sourcename="AccountsDB"translator-name="oracle"connection-jndi-name="java:/oracleDS"/>
<metadatatype="DDL">
**DDLHere**
</metadata>
</model>
</vdb>
Thisisapplicabletobothsourceandviewmodels.SeeDDLMetadataformoreinformationonhowtousethisfeature.
FILE
Samplevdb.xmlfile
<vdbname="{vdb-name}"version="1">
<modelname="{model-name}"type="PHYSICAL">
<sourcename="AccountsDB"translator-name="oracle"connection-jndi-name="java:/oracleDS"/>
<metadatatype="DDL-FILE">/accounts.ddl</metadata>
</model>
</vdb>
DDLisapplicabletobothsourceandviewmodelsinzipVDBdeployments.SeeDDLMetadataformoreinformationonhowtousethisfeature.
ChainingRepositories
MetadataRepositories
485
![Page 486: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/486.jpg)
Whendefiningthemetadatatypeforamodel,multiplemetadataelementscanbeused.Alltherepositoryinstancesdefinedareconsultedintheorderconfiguredtogatherthemetadataforthegivenmodel.Forexample:
Samplevdb.xmlfile
<vdbname="{vdb-name}"version="1">
<modelname="{model-name}"type="PHYSICAL">
<sourcename="AccountsDB"translator-name="oracle"connection-jndi-name="java:/oracleDS"/>
<metadatatype="NATIVE"/>
<metadatatype="DDL">
**DDLHere**
</metadata>
</model>
</vdb>
Note Fortheabovemodel,NATIVEimporterisfirstused,thenDDLimporterusedtoaddadditionalmetadatatoNATIVEimportedmetadata.
Custom
SeeCustomMetadataRepository
MetadataRepositories
486
![Page 487: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/487.jpg)
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
487
![Page 488: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/488.jpg)
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
488
![Page 489: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/489.jpg)
</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
489
![Page 490: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/490.jpg)
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
AmazonSimpleDBTranslator
490
![Page 491: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/491.jpg)
<vdbname="myvdb"version="1">
<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
Note Thisfeatureisturnedoffbydefaultbecauseofthesecurityriskthisexposestoexecuteanycommandagainstthe
AmazonSimpleDBTranslator
491
![Page 492: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/492.jpg)
Note 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.
AmazonSimpleDBTranslator
492
![Page 493: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/493.jpg)
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.
ApacheAccumuloTranslator
493
![Page 494: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/494.jpg)
Bydefault,Accumulotablestructureisflatcannotdefinerelationshipsamongtables.So,aSQLJOINisperformedinTeiidlayerratherthanpushedtosourceevenifbothtablesoneithersideoftheJOINresideintheAccumulo.CurrentlyanycriteriabasedonEQUALITYand/orCOMPARISONusingcomplexAND/ORclausesarehandledbyAccumulotranslatorandwillbeproperlyexecutedatsource.
AnExampleVDBthatshowsAccumulotranslatorcanbedefinedas
<vdbname="myvdb"version="1">
<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
Create/useaTeiidDesignerModelproject
Use"TeiidConnection>>SourceModel"importer,createAccumuloDataSourceusingdatasourcecreationwizardanduseaccumuloastranslatorintheimporter.Thetableiscreatedinasourcemodelbythetimeyoufinishwiththisimporter.
CreateaVDBanddeployintoTeiidServeranduseeitherjdbc,odbc,odataetctoquery.
PropertiesAccumulotranslatoriscapableoftraversingthroughAccumulotablestructuresandbuildametadatastructureforTeiidtranslator.TheschemaimportercanunderstandsimpletablesbytraversingasingleROWIDofdata,thenlooksforalltheuniquekeys,basedonititcomesupwithatabularstructureforAccumulobasedtable.Usingthefollowingimportproperties,youcanfurtherrefinetheimportbehavior.
ImportProperties
PropertyName Description Required Default
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.
ApacheAccumuloTranslator
494
![Page 495: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/495.jpg)
ExtensionMetadataProperties
PropertyName Description Required Default
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);
ApacheAccumuloTranslator
495
![Page 496: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/496.jpg)
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.
ApacheAccumuloTranslator
496
![Page 497: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/497.jpg)
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>
ApacheSOLRTranslator
497
![Page 498: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/498.jpg)
ThetranslatordoesNOTprovideaconnectiontotheSolr.Forthatpurpose,TeiidhasaJCAadapterthatprovidesaconnectiontoSolrusingtheSolrJJavalibrary.Todefinesuchconnector,seeSolrDataSourcesorseeanexamplein"<jboss-as>/docs/teiid/datasources/solr"
IfyouareusingDesignerTooling,tocreateVDBthen
Create/useaTeiidDesignerModelproject
Use"TeiidConnection>>SourceModel"importer,createSolrDataSourceusingdatasourcecreationwizardandusesolrastranslatorintheimporter.Thesearchtableiscreatedinasourcemodelbythetimeyoufinishwiththisimporter.
CreateaVDBanddeployintoTeiidServeranduseeitherjdbc,odbc,odataetctoquery.
JCAResourceAdapterTheTeiidspecificSolrResourceAdaptershouldbeusedwiththistranslator.SeeSolrDataSourcesforconnectingtoaSolrSearchEngine.
NativeQueries
ThisfeatureisnotapplicableforSolrtranslator.
DirectQueryProcedure
ThisfeatureisnotavailableforSolrtranslatorcurrently.
ApacheSOLRTranslator
498
![Page 499: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/499.jpg)
CassandraTranslatorTheCassandraTranslator,knownbythetypenamecassandra,exposesqueryingfunctionalitytoCassandraDataSources.ThetranslatortranslatesTeiidpushdowncommandsintoCassandraCQL.
Properties
TheCassandraTranslatorcurrentlyhasnoimportorexecutionproperties.
Usage
TheCassandraTranslatorsupportsINSERT/UPDATE/DELETE/SELECTstatementswitharestrictivesetofcapabilitiesincluding:count(*),comparisonpredicates,INpredicates,andLIMIT.Onlyindexedcolumnsaresearchable.Consideracustomextensionorcreateanenhancementrequestshouldyourusagerequireadditionalcapabilities.
IfyouareusingDesignerTooling,tocreateVDBthen:
Create/useaTeiidDesignerModelproject
Use"TeiidConnection>>SourceModel"importer,createanewJBossDataSourceconnectionprofile,specifyingtheJNDInameforresourceadapterconfiguredhttps://docs.jboss.org/author/display/TEIIDCassandra+Data+Sources[datasource]andusecassandraastranslatortype.Thesourcemodelwillbecreatedwhenyoufinishwiththisimporter.
CreateaVDBanddeployintoTeiidServeranduseeitherjdbc,odbc,odataetctoquery.
Cassandraupdatesalwaysreturnanupdatecountof1perupdateregardlessofthenumberofrowsaffected.
Cassandrainsertsarefunctionallyupserts,thatisifagivenrowexistsitwillbeupdatedratherthancausinganexception.
JCAResourceAdapter
TheTeiidspecificCassandraResourceAdaptershouldbeusedwiththistranslator.SeeCassandraDataSourcesforconnectingtoaCassandracluster.
NativeQueries
Cassandrasourceproceduresmaybecreatedusingtheteiid_rel:native-queryextension-seeParameterizableNativeQueries.Theprocedurewillinvokethenative-querysimilartoadirectprocedurecallwiththebenefitsthatthequeryispredeterminedandthatresultcolumntypesareknown,ratherthanrequiringtheuseofARRAYTABLEorsimilarfunctionality.
DirectQueryProcedure
Thisfeatureisturnedoffbydefaultbecauseofthesecurityriskthisexposestoexecuteanycommandagainstthesource.Toenablethisfeature,overridetheexecutionpropertycalled_SupportsDirectQueryProceduretotrue.
Bydefaultthenameoftheprocedurethatexecutesthequeriesdirectlyiscallednative.Overridetheexecutionproperty_DirectQueryProcedureNametochangeittoanothername.
TheCassandratranslatorprovidesaproceduretoexecuteanyad-hocCQLquerydirectlyagainstthesourcewithoutTeiidparsingorresolving.Sincethemetadataofthisprocedure’sresultsarenotknowntoTeiid,theyarereturnedasanobjectarray.ARRAYTABLEcanbeusedconstructtabularoutputforconsumptionbyclientapplications.
ExampleCQLDirectQuery
SELECTX.*
FROMcassandra_source.native('SELECTfirstname,lastnameFROMusersWHEREbirth_year=$1ANDcountry=$2AL
CassandraTranslator
499
![Page 500: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/500.jpg)
LOWFILTERING',1981,'US')n,
ARRAYTABLE(n.tupleCOLUMNSfirstnamestring,lastnamestring)ASX
CassandraTranslator
500
![Page 501: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/501.jpg)
DelegatingTranslators
Translator"delegator"
Atranslatorbyname"delegator"isavailableincoreTeiidinstallation,thatcanbeusedtomodifythecapabilitiesofaexistingtranslator.Oftentimesfordebuggingpurposesorinspecialsituations,onemayrequiretoeitherturnon/offcertaincapabilityoftranslator.Forexample,assumeHivedatabaseintheirlatestversionsupportingtheORDERBYconstruct,howeverTeiid’scurrentversionoftheHivetranslatordoesnothavethiscapability,youcanusethe"delegator"translatortoturnONthe"ORDERBY"supportwithoutactuallywritinganycode.Sometimesyoumaywanttodothereverse,youwantturnoffcertaincapabilitytoproduceabetterplan.Inthesesituations,youcanusethistranslator.
Tousethistranslator,youneedtodefinethistranslatorintheVDB,asashowninthebelowVDB.Thebelowexampleoverridingthe"hive"translatorandturningofftheORDERBYsupport.
<?xmlversion="1.0"encoding="UTF-8"standalone="yes"?>
<vdbname="myvdb"version="1">
<modelname="mymodel">
<sourcename="source"translator-name="hive-delegator"connection-jndi-name="java:hive-ds"/>
</model>
<!--thebelowitiscalledtranslatoroverriding,whereyoucansetdifferentproperties-->
<translatorname="hive-delegator"type="delegator"/>
<propertyname="delegateName"value="hive"/>
<propertyname="supportsOrderBy"value="false"/>
</translator>
</vdb>
Youcanoverrideany/allthetranslatorcapabilitiesdefinedhereTranslatorCapabilitiesasExecutionPropertiestooverride.Exampleof"supportsOrderBy"isshowninaboveexample.
Extendingthe"delegator"translator
Youmaycreateadelegatingtranslatorbyextendingtheorg.teiid.translator.BaseDelegatingExecutionFactory.Onceyourclassesarethenpackagedasacustomtranslator,youwillbeabletowireanothertranslatorinstanceintoyourdelegatingtranslatoratruntimeinordertointerceptallofthecallstothedelegate.Thisbaseclassdoesnotprovideanyfunctionalityonitsown,otherthandelegation.Thedifferenceherefromprevious"delegator"translatoris,youcanhardcodethecapabilitiesinsteadofdefiningasconfigurationinsidethe-vdb.xml,aswellasoverridemethodstoprovidealternatebehavior.
ExecutionProperties
Name Description Default
delegateName Translatorinstancenametodelegateto n/a
Letssayyouarecurrentlyusing"oracle"translatorinyourVDB,youwanttointerceptthecallsgoingthroughthistranslator,thenyoufirstwriteacustomdelegatingtranslatorlike
@Translator(name="interceptor",description="interceptor")
publicclassInterceptorExecutionFactoryextendsorg.teiid.translator.BaseDelegatingExecutionFactory{
@Override
publicvoidgetMetadata(MetadataFactorymetadataFactory,Cconn)throwsTranslatorException{
DelegatingTranslators
501
![Page 502: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/502.jpg)
//dointerceptingcodehere..
//Ifyouwantcalltheoriginaldelegate,donotcallifdonotneedto.
//butifyoudidnotcallthedelegatefullfillthemethodcontract
super.getMetadata(metadataFactory,conn);
//domoreinterceptingcodehere..
}
}
NowdeploythistranslatorinTeiidengine.Theninyour-vdb.xmlor.vdbfiledefinelikebelow.
<?xmlversion="1.0"encoding="UTF-8"standalone="yes"?>
<vdbname="myvdb"version="1">
<modelname="mymodel">
<sourcename="source"translator-name="oracle-interceptor"connection-jndi-name="java:oracle-ds"/>
</model>
<!--thebelowitiscalledtranslatoroverriding,whereyoucansetdifferentproperties-->
<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
502
![Page 503: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/503.jpg)
FileTranslatorThefiletranslator,knownbythetypenamefile,exposesstoredprocedurestoleveragefilesystemresourcesexposedbythefileresourceadapter.ItwillcommonlybeusedwiththeTEXTTABLEorXMLTABLEtablefunctionstouseCSVorXMLformatteddata.
ExecutionProperties
Name Description Default
EncodingTheencodingthatshouldbeusedforCLOBsreturnedbythegetTextFilesprocedure
Thesystemdefaultencoding
ExceptionIfFileNotFoundThrowanexceptioningetFilesorgetTextFilesifthespecifiedfile/directorydoesnotexist.
true(falsepriorto8.2)
Usage
getFiles
RetrieveallfilesasBLOBswithanoptionalextensionatthegivenpath.
callgetFiles('path/*.ext')
Ifthepathisadirectory,thenallfilesinthedirectorywillbereturned.Ifthepathmatchesasinglefile,itwillbereturned.
The'*'characterwillbetreatedasawildcardtomatchanynumberofcharactersinthepathname-0ormatchingfileswillbereturned.
If'*'isnotusedandthepathdoesn’texistandExceptionIfFileNotFoundistrue,thenanexceptionwillberaised.
getTextFiles
RetrieveallfilesasCLOB(s)withtheanoptionalextensionatthegivenpath.
callgetTextFiles('path/*.ext')
AllthesamefilesagetFileswillberetrieved,theonlydifferenceisthattheresultswillbeCLOBvaluesusingtheencodingexecutionpropertyasthecharacterset.
saveFile
SavetheCLOB,BLOB,orXMLvaluetogivenpath
callsaveFile('path',value)
deleteFile
Deletethefileatthegivenpath
FileTranslator
503
![Page 504: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/504.jpg)
calldeleteFile('path')
Thepathshouldreferenceanexistingfile.IfthefiledoesnotexistandExceptionIfFileNotFoundistrue,thenanexceptionwillbethrown.Orifthefilecannotbedeletedanexceptionwillbethrown.
NOTE Nativequeries-NativeordirectqueryexecutionisnotsupportedontheFileTranslator.
JCAResourceAdapterTheresourceadapterforthistranslatorprovidedthrough"FileDataSource",RefertoAdminGuideforconfigurationinformation.
FileTranslator
504
![Page 505: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/505.jpg)
GoogleSpreadsheetTranslatorThegoogle-spreadsheettranslatorisusedtoconnecttoaGoogleSpreadsheet.TousetheGoogleSpreadsheetTranslatoryouneedtoconfigureanddeploytheGoogleJCAconnector-seetheAdminGuide.
Thequeryapproachexpectsthedataintheworksheettobeinaspecificformat.Namely:
Anycolumnthathasdataisqueryable.
Anycolumnwithanemptycellhasthevalueretrievedasnull.
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.
DirectQueryProcedure
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
GoogleSpreadsheetTranslator
505
![Page 506: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/506.jpg)
thefirstargumenttakessemi-colon(;)separatednamevaluepairsoffollowingpropertiestoexecutetheprocedure:
Property Description Required
worksheet Googlespreadsheetname yes
query spreadsheetquery yes
limit numberrowstofetch no
offset offsetofrowstofetchfromlimitorbeginning no
GoogleSpreadsheetTranslator
506
![Page 507: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/507.jpg)
InfinispanHotRodTranslatorTheInfinispanHotRodTranslator,knownbythetypeispn-hotrod,canreadthejavaobjectsfromaremoteInfinispanCacheviatheHotRodclientusingtheGoogleProtobufforserialization.ThiswillenableTeiidtoquerytheremotecacheusingJDGDSL.ThistranslatorextendstheObjectTranslatorandusesitforthecoreprocessingofreadingandwritingobjects.
ItisassumedthatyouwillbeinstallingtheJDGHotrodClientEAPModulesKit,whichcanbeobtainedontheRedHat’sCustomerPortalathttps://access.redhat.com/jbossnetwork/restricted/listSoftware.html.
IfyouareusingJDGinlibrarymode,seetheInfinispanLibraryModeTranslatorforthistypeofconfiguration.
UsageRetrieveobjectsfromacacheandtransformintorowsandcolumns.
Supportsperformingwritestothecache
Useforexternalmaterializationtoimprovequeryperformance
SupportedCapabilities
Thefollowingaretheconnectorcapabilities:
CompareCriteria-EQ
CompareCriteriaOrdered-LT,GT,LE,GE-supportforSupportsComapareCriteriaOrderedwillbecontrolledbytheversionofJDGbeingaccessed.AnyJDGversion6.5andpriorwillhavethissettofalseduetoanissuewithJDG.
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
InfinispanHotRodTranslator
507
![Page 508: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/508.jpg)
Tobedone:
supportdeletingcontainingclass(s)(i.e.,person-→phones,deleteaphone)
supportupdatingcontainingclass(s)
InstallationTheispn-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.
Metadata
OptionsforDefining
Thereareseveraloptionstodefiningthemetadatarepresentingyourobjectinthecache.
"Recommended"UsetheTeiidConnectionImporterinTeiidDesignertocreatethephysicalsourcemodelbasedonyourobjectcache.Thetablecolumnswillbecreatedfromthegoogleprotobufdefinition,thatcorrespondstoaregisteredclass.
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.SeeObjectTranslatorforanexample.
DefinitionRequirements
seeObjectTranslatorMetadatasectionforbasedefinitionrequirements.
ColumnswillbeidentifiedasSEARCHABLEifeithertheprotobufdefinitionforacolumnindicatesitsindexedorthepojoclasshastheattribute/methodannotated.
A1-to-*relationshipclassmusthaveaforeignkeytomaptotherootclass/table,wherethenameinsourcefortheforeignkeyisthenameoftherootclassmethodtoaccessthosechildobjects.Note,thisistheclassmethod,notareferenceinthegoogleprotobufdefinition.
Acontainer/childclasswillhaveattributeswheretheNIScontainaperiod.Example:phone.number.ThisisbecausethismapstotogoogleprotobufdefinitionandwhatisexpectedtobeusedintheDSLquery.
ExternalMaterialization
InfinispanHotRodTranslator
508
![Page 509: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/509.jpg)
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:
..
"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.
DirectQueryProcedure
Additionally,theexecutionofnativequeriesisdonethruthesupportofdirectqueryprocedures.Theproceduretobeexecutediscallednative.
WarningThisfeatureisturnedoffbydefaultbecauseofthesecurityriskthisexposestoexecuteanycommandagainstthesource.Toenablethisfeature,overridetheexecutionproperty[OverrideExecutionProperties]calledSupportsDirectQueryProceduretotrue.
MetadataRequirements
IfyoumanuallymodelthecachetableinTeiidDesigner,thenyouwillneedtoaddthepropertyextensionfordefiningtheproperty"primary_table".ThefollowingisaDDLexample:
SETNAMESPACE'http://www.teiid.org/translator/object/2016'ASn0;
CREATEFOREIGNTABLETrade(
....
CONSTRAINTPK_TRADEIDPRIMARYKEY(tradeId)
)OPTIONS(UPDATABLETRUE);
CREATEFOREIGNTABLEST_Trade(
....
)OPTIONS(NAMEINSOURCE'Trade',UPDATABLETRUE,"n0:primary_table"'ObjectSchema.Trade');
InfinispanHotRodTranslator
509
![Page 510: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/510.jpg)
JCAResourceAdapter
SeeInfinispanHotRodDataSourcesresourceadapterforthistranslator.ItcanbeconfiguredtolookupthecachecontainerviaJNDI,serverlist,orhotrodproperties.
InfinispanHotRodTranslator
510
![Page 511: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/511.jpg)
InfinispanLibraryModeTranslatorTheInfinispanLibraryModetranslator,knownbythenameofispn-lib-mode,isabridgeforreadingandwritingjavaobjectsto/fromanInfinispan/JDGCacherunninginlibrarymode.ThistranslatorextendstheObjectTranslatorandusesitforthecoreprocessingofreadingandwritingobjects.TheInfinispanLibraryModeTranslatoriswrittensothatitcancontrolhowthecacheissearchedandanycapabilitiesthatareneededtocontrolthatbehavior.
ItisassumedthatyouwillbeinstallingtheJDGLibraryModeEAPModulesKit,whichcanbeobtainedontheRedHat’sCustomerPortalathttps://access.redhat.com/jbossnetwork/restricted/listSoftware.html.
IfyouareusingJDGtoaccessaremotecache,seetheInfinispanHotRodTranslatorforthistypeofconfiguration.
UsageRetrieveobjectsfromacacheandtransformintorowsandcolumns.
Performwritestothecache
Useforexternalmaterializationtoimprovequeryperformance
SearchingOptions
Supportsthefollowingoptionsforsearching:
DSLsearching(JDG6.3+)
Hibernate/Lucenesearching(nowdeprecated)
Keysearching(whennoindexingisused).
Seethejdg-local-cachequickstartforanexample.
SupportedCapabilities
ThefollowingaretheconnectorcapabilitieswhenKeySearchingisused:
SELECTcommand
CompareCriteria-onlyEQ
InCriteria
ThefollowingaretheconnectorcapabilitieswhenDSLSearchingisenabled:
SELECTcommand
CompareCriteria-EQ,NE
CompareCriteria-GT,LT,GE,andLEcanbeenabled,seeExecutionProperties
And/OrCriteria
InCriteria
LikeCriteria
OrCriteria
InfinispanLibraryModeTranslator
511
![Page 512: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/512.jpg)
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
Thepojoclassistheobjectthatwillbeusedtostorethedatainthecache.Itshouldbebuiltaccordingly:
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
Theclassshouldbepackagedintoajarsothatitcanbedeployedasamodule
InfinispanLibraryModeTranslator
512
![Page 513: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/513.jpg)
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;
@Field(index=Index.YES,store=Store.YES,analyze=Analyze.NO)
publicStringsymbol;
@Field(index=Index.YES,store=Store.YES,analyze=Analyze.NO)
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;
}
}
Toconfiguretheuseofthepojo,dothefollowing:
Deploythepojojarasamoduleinthejboss-asserver.Thendefinethe"lib"propertyinthe-vdb.xmlandassignthecorrectmodulename.Thiscanbedoneusingthefollowingtemplate:
<propertyname="lib"value="{pojo_module_name}"></property>
TheJDGcommonsmodule,org.infinispan.commons,slot="jdg-6.6"orslotforversioninstalled,needstohavethepojodependencyadded:
<modulename="{pojo_module_name}"export="true"/>
InfinispanLibraryModeTranslator
513
![Page 514: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/514.jpg)
Metadata
OptionsforDefining
Therearecoupleoptionstodefiningthemetadatarepresentingyourobjectinthecache.
"Recommended"UsetheTeiidConnectionImporterinTeiidDesignertocreatethephysicalsourcemodelbasedonyourobjectcache.Thetablecolumnswillbecreatedfromthegoogleprotobufdefinition,thatcorrespondstoaregisteredclass.
UseTeiidDesignertomanuallycreatethephysicalsourcemodelbasedonyourobjectcacheusingthebelowDefinitionRequirements.
ThefollowingisaVDBexamplesimilartoquickstart(seegithubathttps://github.com/teiid/teiid-quickstarts/tree/master/jdg-local-cache).ItdefinesthephysicalsourceandwillusethetranslatornativeimporterlogictohavethemetadatareverseengineeredfromtheStockclass,seeabove,tobeexposedasthesourcetable.
<?xmlversion="1.0"encoding="UTF-8"standalone="yes"?>
<vdbname="Stocks"version="1">
<description>ShowshowtocallanInfinispanlocalcache</description>
<propertyname="UseConnectorMetadata"value="cached"/>
<propertyname="lib"value="com.client.quickstart.pojos"></property>
<modelname="StockCache"type="Physical">
<propertyname="importer.useFullSchemaName"value="false"/>
<sourcename="StockSource"translator-name="infinispan1"connection-jndi-name="java:/infinispanLocal"/>
</model>
<translatorname="infinispan1"type="ispn-lib-mode">
<propertyname="SupportsDSLSearching"value="true"/>
</translator>
</vdb>
Themetadatawillberesolvedbyreverseengineeringthedefinedobjectinthecache.ThiscanbeusefulwhenusingtheTeiidDesignerTeiidConnectionImporterforbuildingthephysicalsourcemodel(s).
YoucanalsodefinethemetadatausingDDL.SeeObjectTranslatorforanexample.
DefinitionRequirements
seeObjectTranslatorMetadatasectionforbasedefinitionrequirements.
AllcolumnsthatarenottheprimarykeynorcoveredbyaluceneindexshouldbemarkedasSEARCHABLE'Unsearchable'.
ExternalMaterializationThistranslatorsupportsusingthecacheforexternalmaterialization.However,therearespecificconfigurationchangesthatarerequiredattheInfinispanDataSourcesresource-adapterandatthetranslator.Foranexample,seethejdglocalquickstart.
NativeQueries
ExternalmaterializationisenabledbytheuseofnativequeriesintheBEFORE_LOAD_SCRIPTandAFTER_LOAD_SCRIPT.Atranslatoroverridewillneedtobesettoenablenativequeries:SupportsNativeQueries=true
Thefollowingmaterializationpropertiesmustbedefined:
InfinispanLibraryModeTranslator
514
![Page 515: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/515.jpg)
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.
DirectQueryProcedure
Additionally,theexecutionofnativequeriesisdonethruthesupportofdirectqueryprocedures.Theproceduretobeexecutediscallednative.
WarningThisfeatureisturnedoffbydefaultbecauseofthesecurityriskthisexposestoexecuteanycommandagainstthesource.Toenablethisfeature,[overridetheexecutionproperty|Translators#OverrideExecutionProperties]calledSupportsDirectQueryProceduretotrue.
MetadataRequirements
IfyoumanuallymodelthecachetableinTeiidDesigner,thenyouwillneedtoaddthepropertyextensionfordefiningtheproperty"primary_table".ThefollowingisaDDLexample:
SETNAMESPACE'http://www.teiid.org/translator/object/2016'ASn0;
CREATEFOREIGNTABLETrade(
....
CONSTRAINTPK_TRADEIDPRIMARYKEY(tradeId)
)OPTIONS(UPDATABLETRUE);
CREATEFOREIGNTABLEST_Trade(
....
)OPTIONS(NAMEINSOURCE'Trade',UPDATABLETRUE,"n0:primary_table"'ObjectSchema.Trade');
JCAResourceAdapterSeeInfinispanLibraryModeDataSourcesresourceadapterforthistranslator.ItcanbeconfiguredtolookupthecachecontainerviaJNDIorcreated(i.e.,ConfigurationFileName).
InfinispanLibraryModeTranslator
515
![Page 516: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/516.jpg)
InfinispanLibraryModeTranslator
516
![Page 517: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/517.jpg)
JDBCTranslatorsTheJDBCtranslatorsbridgebetweenSQLsemanticanddatatypedifferencesbetweenTeiidandatargetRDBMS.Teiidhasarangeofspecifictranslatorsthattargetthemostpopularopensourceandproprietarydatabases.
Usage
UsageofaJDBCsourceisstraight-forward.UsingTeiidSQL,thesourcemaybequeriedasifthetablesandprocedureswerelocaltotheTeiidsystem.
Ifyouareusingarelationaldatasource,oradatasourcethathasaJDBCdriver,andyoudonotfindaspecifictranslatoravailableforthatdatasourcetype,thenstartwiththeJDBCANSITranslator.TheJDBCANSITranslatorshouldenableyoutoperformtheSQLbasics.Iftherespecificdatasourcecapabilitiesthatarenotavailable,thenconsiderusingtheTranslatorDevelopmenttocreatewhatyouneed.OrlogaTeiidJirawithyourrequirements.
ExecutionProperties-sharedbyallJDBCTranslators
Name Description Default
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
517
![Page 518: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/518.jpg)
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
Name Description Default
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
518
![Page 519: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/519.jpg)
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
519
![Page 520: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/520.jpg)
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
520
![Page 521: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/521.jpg)
<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.
DirectQueryProcedure
Thisfeatureisturnedoffbydefaultbecauseofthesecurityriskthisexposestoexecuteanycommandagainstthesource.Toenablethisfeature,overridetheexecutionpropertycalled_SupportsDirectQueryProceduretotrue.
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,
ARRAYTABLE(w.tupleCOLUMNS"update_count"integer)ASx
DeleteExample
SELECTx.*FROM(calljdbc_source.native('deletefromg1wheree1=?',112))w,
ARRAYTABLE(w.tupleCOLUMNS"update_count"integer)ASx
JDBCTranslators
521
![Page 522: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/522.jpg)
JCAResourceAdapter
TheresourceadapterforthistranslatorprovidedthroughdatasourceinWildFly,SeetoAdminGuidesectionWildFlyDataSourcesforconfiguration.
JDBCTranslators
522
![Page 523: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/523.jpg)
ActianVectorTranslator(actian-vector)AlsoseecommonJDBCTranslatorInformation
TheActianVectorTranslator,knownbythetypenameactian-vector,isforuseActianVectorinHadoop.
DownloadtheJDBCdriverathttp://esd.actian.com/platform.NotetheportnumberinconnectionURLis"AH7"whichmapsto16967.
JDBCTranslators
523
![Page 524: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/524.jpg)
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
524
![Page 525: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/525.jpg)
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
525
![Page 526: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/526.jpg)
DB2Translator(db2)AlsoseecommonJDBCTranslatorInformation
TheDB2Translator,knownbythetypenamedb2,ifforusewithDB28orlaterandDB2fori5.4orlater.
DB2specificexecutionproperties:
DB2ForI-indicatesthatthetheDB2instanceisDB2fori.Defaultstofalse.
supportsCommonTableExpressions-indicatesthattheDB2instancesupportsCommonTableExpressions.Defaultstotrue.Someolderversions,orinstancesrunninginaconversionmode,ofDB2lackfullcommontableexpressionsupportandmayneedsupportdisabled.
JDBCTranslators
526
![Page 527: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/527.jpg)
DerbyTranslator(derby)AlsoseecommonJDBCTranslatorInformation
TheDerbyTranslator,knownbythetypenamederby,isforusewithDerby10.1orlater.
JDBCTranslators
527
![Page 528: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/528.jpg)
GreenplumTranslator(greenplum)AlsoseecommonJDBCTranslatorInformation
TheGreenplumTranslator,knownbythetypenamegreenplum,isforusewiththeGreenplumdatabase.ThistranslatorisanextensionofthePostgreSQLTranslatorandinheritsitsoptions.
JDBCTranslators
528
![Page 529: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/529.jpg)
H2Translator(h2)AlsoseecommonJDBCTranslatorInformation
TheH2Translator,knownbythetypenameh2,isforusewithH2version1.1orlater.
JDBCTranslators
529
![Page 530: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/530.jpg)
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
530
![Page 531: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/531.jpg)
HSQLTranslator(hsql)AlsoseecommonJDBCTranslatorInformation
TheHSQLTranslator,knownbythetypenamehsql,isforusewithHSQLDB1.7orlater.
JDBCTranslators
531
![Page 532: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/532.jpg)
InformixTranslator(informix)AlsoseecommonJDBCTranslatorInformation
TheInformixTranslator,knownbythetypenameinformix,isforusewithanyInformixversion.
KnownIssues
TEIID-3808-TheInformixdriverhandlingoftimezoneinformationisinconsistent-evenifthedatabaseTimezonetranslatorpropertyisset.ConsiderensuringthattheInformixserverandtheapplicationserverareinthesametimezone.
JDBCTranslators
532
![Page 533: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/533.jpg)
IngresTranslators(ingres/ingres93)AlsoseecommonJDBCTranslatorInformation
TheIngrestranslationissupportedby2translators.
ingres
TheIngresTranslator,knownbythetypenameingres,isforusewithIngres2006orlater.
ingres93
TheIngres93Translator,knownbythetypenameingres93,isforusewithIngres9.3orlater.
JDBCTranslators
533
![Page 534: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/534.jpg)
IntersystemsCacheTranslator(intersystems-cache)AlsoseecommonJDBCTranslatorInformation
TheIntersystemCacheTranslator,knownbythetypenameintersystems-cache,isforusewithIntersystemsCacheObjectdatabase(onlyrelationalaspectofit).
JDBCTranslators
534
![Page 535: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/535.jpg)
JDBCANSITranslator(jdbc-ansi)AlsoseecommonJDBCTranslatorInformation
TheJDBCANSItranslator,knownbythetypenamejdbc-ansi,declaressupportformostSQLconstructssupportedbyTeiid,exceptforrowlimit/offsetandEXCEPT/INTERSECT.TranslatessourceSQLintoANSIcompliantsyntax.Thistranslatorshouldbeusedwhenanothermorespecifictypeisnotavailable.IfsourceexceptionsarisefromunsupportedSQL,thenconsiderusingtheJDBCSimpleTranslatortofurtherrestrictcapabilities,orcreateaCustomTranslator/createanenhancementrequest.
JDBCTranslators
535
![Page 536: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/536.jpg)
JDBCSimpleTranslator(jdbc-simple)AlsoseecommonJDBCTranslatorInformation
TheJDBCSimpletranslator,knownbythetypenamejdbc-simple,isthesameasjdbc-ansi,exceptdisablessupportfornearlyallpushdownconstructsformaximumcompatibility.
JDBCTranslators
536
![Page 537: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/537.jpg)
MetaMatrixTranslator(metamatrix)AlsoseecommonJDBCTranslatorInformation
TheMetaMatrixTranslator,knownbythetypenamemetamatrix,isforusewithMetaMatrix5.5.0orlater.
JDBCTranslators
537
![Page 538: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/538.jpg)
MicrosoftAccessTranslatorsAlsoseecommonJDBCTranslatorInformation
access
TheMicrosoftAccessTranslatorknownbythetypenameaccessisforusewithMicrosoftAccess2003orlaterviatheJDBC-ODBCbridge.
IfyouareusingthedefaultnativemetadataimportortheTeiidconnectionimportertheimporterdefaultstoimportKeys=falseandexcludeTables=.[.]MSys.toavoidissueswiththemetadataprovidedbytheJDBCODBCbridge.YoumayneedtoadjustthesevaluesifyouuseadifferentJDBCdriver.
ucanaccess
TheMicrosoftAccessTranslatorknownbythetypenameucanaccessisforusewithMicrosoftAccess2003orlaterviathefortheUCanAccessdriver.
JDBCTranslators
538
![Page 539: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/539.jpg)
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
539
![Page 540: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/540.jpg)
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
540
![Page 541: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/541.jpg)
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.
Warning Ifretrievinglargeresultsets,youshouldconsidersettingtheconnectionpropertyuseCursorFetch=true,otherwiseMySQLwillfullyfetchresultsetsintomemoryontheTeiidinstance.
JDBCTranslators
541
![Page 542: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/542.jpg)
NetezzaTranslator(netezza)AlsoseecommonJDBCTranslatorInformation
TheNetezzaTranslator,knownbythetypenamenetezza,isforusewithanyNetezzaversion.
Usage
ThecurrentNetezzavendorsuppliedJDBCdriverperformspoorlywithsingletransactionalupdates.Asisgenerallythecasewhenpossibleusebatchedupdates.
ExecutionProperties
Netezzaspecificexecutionproperties:
SqlExtensionsInstalled-indicatesthatSQLExtensions,includingsupportforREGEXP_LIKE,areinstalled.AllotherREGEXPfunctionsarethenavailableaspushdownfunctions.Defaultstofalse.
JDBCTranslators
542
![Page 543: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/543.jpg)
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
543
![Page 544: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/544.jpg)
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
544
![Page 545: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/545.jpg)
OSISoftPITranslator(osisoft-pi)AlsoseecommonJDBCTranslatorInformation
TheOSISoftTranslator,knownbythetypenameosisoft-pi,isforusewithOSIsoftPIOLEDBEnterprise.ThistranslatorusestheJDBCdriverprovidedbytheOSISoft.ThedriverisnotprovidedwithTeiidinstall,thisneedsbedownloadedfromOSISoftandinstalledcorrectlyonTeiidserveraccordingtoOSISoftdocumentationPI-JDBC-2016-Administrator-Guide.pdforlatestdocument.
InstallonLinux
MakesureyouhaveOpenSSLlibrariesinstalled,andyouhavefollowing"export"addedcorrectlyinyourshellenvironmentvariables.Otherwiseyoucanalsoaddin<WildFly>/bin/standalone.shfileor<WildFly>/bin/domain.shfile.
exportPI_RDSA_LIB=/<path>/pipc/jdbc/lib/libRdsaWrapper-1.5b.so
exportPI_RDSA_LIB64=/<path>/pipc/jdbc/lib/libRdsaWrapper64-1.5b.so
PleasealsonotetoexecutefromLinux,youalsoneedinstall'gSoap'library,asPIJDBCdriverusesSOAPoverHTTPStocommunicatewithPIserver.
InstallonWindows
FollowtheinstallationprogramprovidedbyOSISoftforinstallingtheJDBCdrivers.Makesureyouhavethefollowingenvironmentvariablesconfigured.
PI_RDSA_LIBC:\ProgramFiles(x86)\PIPC\JDBC\RDSAWrapper.dll
PI_RDSA_LIB64C:\ProgramFiles\PIPC\JDBC\RDSAWrapper64.dll
InstallingtheJDBCdriverforTeiid(sameforbothLinuxandWindows)
Thencopythemoduledirectoryfrom<WildFly>/teiid/datasources/osisoft-pi/modulesdirectoryinto_<WilfFly>/modulesdirectory.Thenfindthe"PIJDBCDriver.jar"filefromtheinstallationdirectory,andcopyitto_<WildFly>/module/system/layers/dv/com/osisoft/main"directory.Thenaddthedriverdefinitiontothestandalone.xmlfilebyeditingthefileandaddingsomethingsimilartobelow
<drivers>
<drivername="osisoft-pi"module="com.osisoft">
<driver-class>com.osisoft.jdbc.Driver</driver-class>
</driver>
</drivers>
ThatcompletestheconfigurationofthePIdriverintheTeiid.WestillhavenotcreatedaconnectiontothePIserver.youcanstarttheservernow.
CreatingaDataSourcetoPI
YoucanexecutefollowingsimilarCLIscripttocreateadatasource
JDBCTranslators
545
![Page 546: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/546.jpg)
/subsystem=datasources/data-source=pi-ds:add(jndi-name=java:/pi-ds,driver-
name=osisoft-pi,connection-url=jdbc:pioledbent://<DACServer>/DataSource=<AF
Server>;IntegratedSecurity=SSPI,user-name=user,password=mypass)
/subsystem=datasources/data-source=pi-ds:enable
thiswillcreatefollowingXMLinstandalone.xmlordomain.xml(youcanalsodirectlyeditthesefilesandaddmanually)
<datasourcejndi-name="java:/pi-ds"pool-name="pi-ds">
<connection-url>jdbc:pioledbent://<DACServer>/DataSource=<AFServer>;
IntegratedSecurity=SSPI</connection-url>
<driver>osisoft-pi</driver>
<pool>
<prefill>false</prefill>
<use-strict-min>false</use-strict-min>
<flush-strategy>FailingConnectionOnly</flush-strategy>
</pool>
<security>
<user-name>user</user-name>
<password>mypass</password>
</security>
</datasource>
NowyouhavefullyconfiguredtheTeiidwithPIdatabaseconnection.YoucancreateVDBthatcanusethisconnectiontoissuethequeries.
UsageYoucandevelopaVDBlikefollowstofetchmetadatafromPIandgiveyouaccesstoexecutingqueriesagainstPI.
pi-vdb.xml
<vdbname="pi"version="1">
<modelname="AF">
<propertyname="importer.importProcedures"value="true"/>
<sourceconnection-jndi-name="java:/pi-ds"name="pi-connector"translator-
name="osisoft-pi"/>
</model>
</vdb>
DeploythisfileintoTeiidusingCLIorusingmanagementconsole
deploypi-vdb.xml
OncethemetadataisloadedandVDBisactiveyoucanuseTeiidJDBC/ODBCdriverorODatatoconnecttotheVDBandissuequeries.
PITranslatorCapabilities
JDBCTranslators
546
![Page 547: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/547.jpg)
PItranslatorisextensionofjdbc-ansitranslator,soalltheSQLANSIqueriesaresupported.PItranslatoralsosupportsLATERALjoinwithTableValuedFunctions(TVF).AnexampleTeiidquerylookslike
{code}SELECTEH.Name,BT."Time",BT."NumberofComputers",BT."Temperature"FROMSample.Asset.ElementHierarchyEHLEFTJOINLATERAL(exec"TransposeArchive_BuildingTemplate"(EH.ElementID,TIMESTAMPADD(SQL_TSI_HOUR,-1,now()),now()))BTon1=1WHEREEH.ElementIDIN(SELECTElementIDFROMSample.Asset.ElementHierarchyWHEREPath='\DataCenter\'){code}
NoteANSISQLsemanticsrequireaONclause,butCROSSAPPLYorOUTERAPPLYdonohaveaONclause,soforthisreasonuserneedtopassinadummyONclauselikeON(1=1),whichwillbeignoredwhenconvertedtoAPPLYclausewhichwillbepusheddown.
Bydefaultthistranslatorturnsoffthe"importer.ImportKeys"tofalse.
NoteThePIdatatype,"GUID"willneedtobemodeledas"String"andmustdefinetheNATIVE_TYPEoncolumnas"guid",thenTeiidtranslatorwillappropriatelyconvertthedatabackforthwiththePIdatasource’snativeguidtypewithappropriatetypecastingfromstring.
JDBCTranslators
547
![Page 548: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/548.jpg)
PostgreSQLTranslator(postgresql)AlsoseecommonJDBCTranslatorInformation
ThePostgreSQLTranslator,knownbythetypenamepostgresql,isforusewith8.0orlaterclientsand7.1orlaterserver.
ExecutionProperties
PostgreSQLspecificexecutionproperties:
PostGisVersion-indicatethePostGISversioninuse.Defaultsto0meaningPostGISisnotinstalled.Willbesetautomaticallyifthedatabaseversionisnotset.
ProjSupported-booleanindicatingifProjissupportforPostGis.Willbesetautomaticallyifthedatabaseversionisnotset.
Note SomedriverversionsofPostgreSQLwillnotassociatecolumnsto"INDEX"typetablesandfailduringimportiftheimporter.tableTypepropertyisleftasthedefault.
JDBCTranslators
548
![Page 549: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/549.jpg)
PrestoDBTranslator(prestodb)AlsoseecommonJDBCTranslatorInformation
ThePrestoDBtranslator,knownbythetypenameprestodb,exposesqueryingfunctionalitytoPrestoDBDataSources.Indataintegrationrespect,PrestoDBhasverysimilarcapabilitiesofTeiid,howeveritgoesbeyondintermsofdistributedqueryexecutionwithmultipleworkernodes.Teiid’sexecutionmodelislimitedtosingleexecutionnodeandfocusesmoreonpushingthequerydowntosources.CurrentlyTeiidhasmuchmorecompletequerysupportandmanyenterprisefeatures.
Capabilities
ThePrestoDBtranslatorsupportsonlySELECTstatementswitharestrictivesetofcapabilities.Thistranslatorisdevelopedwith0.85versionofPrestoDBandcapabilitiesaredesignedforthisversion.WithnewversionsofPrestoDBTeiidwilladjustthecapabilitiesofthistranslator.SincePrestoDBexposesarelationalmodel,theusageofthisisnodifferentthananyRDBMSsourcelikeOracle,DB2etc.ForconfiguringthePrestoDBconsultthePrestoDBdocumentation.
JDBCTranslators
549
![Page 550: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/550.jpg)
RedshiftTranslator(redshift)AlsoseecommonJDBCTranslatorInformation
TheRedshiftTranslator,knownbythetypenameredshift,isforusewiththeRedshiftdatabase.ThistranslatorisanextensionofthePostgreSQLTranslatorandinheritsitsoptions.
JDBCTranslators
550
![Page 551: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/551.jpg)
SAPHanaTranslator(hana)AlsoseecommonJDBCTranslatorInformation
TheSAPHanaTranslator,knownbythenameofhana,isforusewithSAPHana.
KnownIssues
TEIID-3805-ThepushdownofthesubstringfunctionisinconsistentwiththeTeiidsubstringfunctionwhenthefromindexexceedsthelengthofthestring.SAPHanawillreturnanemptystring,whileTeiidproducesanullvalue.
JDBCTranslators
551
![Page 552: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/552.jpg)
SybaseIQTranslator(sybaseiq)AlsoseecommonJDBCTranslatorInformation
TheSybaseIQTranslator,knownbythetypenamesybaseiq,isforusewithSybaseIQversion15.1orlater.
JDBCTranslators
552
![Page 553: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/553.jpg)
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
553
![Page 554: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/554.jpg)
TeiidTranslator(teiid)AlsoseecommonJDBCTranslatorInformation
TheTeiidTranslator,knownbythetypenameteiid,isforusewithTeiid6.0orlater.
JDBCTranslators
554
![Page 555: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/555.jpg)
TeradataTranslator(teradata)AlsoseecommonJDBCTranslatorInformation
TheTeradataTranslator,knownbythetypenameteradata,isforusewithTeradataV2R5.1orlater.
WithTeradatadriverversion15date,time,andtimestampvaluesbydefaultwillbeadjustedfortheTeiidservertimezone.Toremovethisadjustment,setthetranslatorDatabaseTimezonepropertytoGMTorwhatevertheTeradataserverdefaultsto.
JDBCTranslators
555
![Page 556: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/556.jpg)
VerticaTranslator(vertica)AlsoseecommonJDBCTranslatorInformation
TheVerticaTranslator,knownbythetypenamevertica,isforusewithVertica6orlater.
JDBCTranslators
556
![Page 557: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/557.jpg)
JPATranslatorTheJPAtranslator,knownbythetypenamejpa2,canreverseaJPAobjectmodelintoarelationalmodel,whichcanthenbeintegratedwithotherrelationalornon-relationalsources.ForinformationonJPApersistenceinaWildFly,seeJPAReferenceGuide.
Properties
TheJPATranslatorcurrentlyhasnoimportorexecutionproperties.
NativeQueriesJPAsourceproceduresmaybecreatedusingtheteiid_rel:native-queryextension-seeParameterizableNativeQueries.Theprocedurewillinvokethenative-querysimilartoannativeprocedurecallwiththebenefitsthatthequeryispredeterminedandthatresultcolumntypesareknown,ratherthanrequiringtheuseofARRAYTABLEorsimilarfunctionality.Seethequerysyntaxbelow.
DirectQueryProcedure
Note Thisfeatureisturnedoffbydefaultbecauseofthesecurityriskthisexposestoexecuteanycommandagainstthesource.Toenablethisfeature,overridetheexecutionpropertycalled_SupportsDirectQueryProceduretotrue.
Tip Bydefaultthenameoftheprocedurethatexecutesthequeriesdirectlyisnative.Overridetheexecutionproperty_DirectQueryProcedureNametochangeittoanothername.
TheJPAtranslatorprovidesaproceduretoexecuteanyad-hocJPA-QLquerydirectlyagainstthesourcewithoutTeiidparsingorresolving.Sincethemetadataofthisprocedure’sresultsarenotknowntoTeiid,theyarereturnedasobjectarray.UsercanuseARRAYTABLEcanbeusedconstructtabularoutputforconsumptionbyclientapplications.Teiidexposesthisprocedurewithasimplequerystructureasbelow
Select
SelectExample
SELECTx.*FROM(calljpa_source.native('search;FROMAccount'))w,
ARRAYTABLE(w.tupleCOLUMNS"id"string,"type"string,"name"String)ASx
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
557
![Page 558: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/558.jpg)
CreateExample
SELECTx.*FROM
(calljpa_source.native('update;<jpa-ql>'))w,
ARRAYTABLE(w.tupleCOLUMNS"update_count"integer)ASx
formtheabovecode,the"update"keywordmustbefollowedbyJPA-QLfortheupdatestatement.
Create
UpdateExample
SELECTx.*FROM
(calljpa_source.native('create;',<entity>))w,
ARRAYTABLE(w.tupleCOLUMNS"update_count"integer)ASx
Createoperationneedstosend"create"wordasmarkerandsendtheentityasathefirstparameter.
JPATranslator
558
![Page 559: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/559.jpg)
LDAPTranslatorTheLDAPtranslatorisimplementedbytheorg.teiid.translator.ldap.LDAPExecutionFactoryclassandknownbythetranslatortypenameldap.TheLDAPtranslatorexposesanLDAPdirectorytreerelationallywithpushdownsupportforfilteringviacriteria.ThisistypicallycoupledwiththeLDAPresourceadapter.
Note TheresourceadapterforthistranslatorisprovidedbyconfiguringtheldapdatasourceintheJBossEAPinstance.
ExecutionProperties
Name Description Default
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
559
![Page 560: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/560.jpg)
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
560
![Page 561: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/561.jpg)
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.
DirectQueryProcedure
Note Thisfeatureisturnedoffbydefaultbecauseofthesecurityriskthisexposestoexecuteanycommandagainstthesource.Toenablethisfeature,overridetheexecutionpropertycalled_SupportsDirectQueryProceduretotrue.
Tip Bydefaultthenameoftheprocedurethatexecutesthequeriesdirectlyisnative.Overridetheexecutionproperty_DirectQueryProcedureNametochangeittoanothername.
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
561
![Page 562: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/562.jpg)
Delete
DeleteExample
SELECTx.*FROM(callpm1.native('delete;uid=doe,ou=people,o=teiid.org'))w,
ARRAYTABLE(w.tupleCOLUMNS"updatecount"integer)ASx
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,
ARRAYTABLE(w.tupleCOLUMNS"update_count"integer)ASx
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,
ARRAYTABLE(w.tupleCOLUMNS"update_count"integer)ASx
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
562
![Page 563: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/563.jpg)
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
563
![Page 564: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/564.jpg)
SelectDistinct
SelectLiterals
UNION
XATransactions
Usage
ldap-as-a-datasourcequickstartdemonstratesusingtheldapTranslatortoaccessdatainOpenLDAPServer.Thenameofthetranslatortouseinvdb.xmlis"translator-ldap",forexample:
<?xmlversion="1.0"encoding="UTF-8"standalone="yes"?>
<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-definitions>
<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>
</connection-definition>
</connection-definitions>
</resource-adapter>
Theabovedefinesthetranslatorandconnector.FormorewaystocreatetheconnectorseeLDAPDataSources,LDAPtranslatorcanderivethemetadatabasedonexistingUsers/GroupsinLDAPServer,userneedtodefinethemetadata.Forexample,youcandefineaschemausingDDL:
<?xmlversion="1.0"encoding="UTF-8"standalone="yes"?>
<vdbname="ldapVDB"version="1">
<modelname="HRModel">
<metadatatype="DDL"><![CDATA[
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
564
![Page 565: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/565.jpg)
</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
565
![Page 566: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/566.jpg)
LoopbackTranslatorTheLoopbacktranslator,knownbythetypenameloopback,providesaquicktestingsolution.ItsupportsallSQLconstructsandreturnsdefaultresults,withsomeconfigurablebehavior.
ExecutionProperties
Name Description Default
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
566
![Page 567: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/567.jpg)
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.
<?xmlversion="1.0"encoding="UTF-8"standalone="yes"?>
<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
MicrosoftExcelTranslator
567
![Page 568: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/568.jpg)
Create/useaTeiidDesignerModelproject
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
MicrosoftExcelTranslator
568
![Page 569: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/569.jpg)
FILE Table
DefinesExcelDocumentnameornamepattern(*.xls).Filepatterncanbeusedtoreaddatafrommultiplefiles.
Yes
FIRST_DATA_ROW_NUMBER Table
Definestherownumberwhererecordsstartinthesheet(appliestoeverysheet)
optional
CELL_NUMBER ColumnofTableDefinescellnumbertouseforreadingdataofparticularcolumn
Yes
ThebelowshowsanexampletablethatisdefinedusingtheExtensionMetadataProperties.
<?xmlversion="1.0"encoding="UTF-8"standalone="yes"?>
<vdbname="excelvdb"version="1">
<modelname="excel">
<sourcename="connector"translator-name="excel"connection-jndi-name="java:/fileDS"/>
<metadatatype="DDL"><![CDATA[
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.
DirectQueryProcedure
MicrosoftExcelTranslator
569
![Page 570: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/570.jpg)
Note ThisfeatureisnotapplicableforExceltranslator.
MicrosoftExcelTranslator
570
![Page 571: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/571.jpg)
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
571
![Page 572: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/572.jpg)
<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"/>
<transaction-support>NoTransaction</transaction-support>
<connection-definitions>
<connection-definitionclass-name="org.teiid.resource.adapter.mongodb.MongoDBManagedConnectionF
actory"
jndi-name="java:/mongoDS"
enabled="true"
use-java-context="true"
pool-name="teiid-mongodb-ds">
<!--MongoDBserverlist(host:port[;host:port...])-->
<config-propertyname="RemoteServerList">localhost:27017</config-property>
<!--DatabaseNameintheMongoDB-->
<config-propertyname="Database">test</config-property>
<!--
Uncommentthesepropertiestosupplyusernameandpassword
<config-propertyname="Username">user</config-property>
<config-propertyname="Password">user</config-property>
-->
</connection-definition>
</connection-definitions>
</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"/>
<metadatatype="DDL"><![CDATA[
CREATEFOREIGNTABLECustomer(
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
572
![Page 573: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/573.jpg)
}
IfaPRIMARYKEYisdefinedonthetableas
CREATEFOREIGNTABLECustomer(
customer_idintegerPRIMARYKEY,
FirstNamevarchar(25),
LastNamevarchar(25)
)OPTIONS(UPDATABLE'TRUE');
thenthatcolumnnameisautomaticallyusedas"_id"fieldintheMongoDBcollection,thendocumentstructureisstoredintheMongoDBas
{
_id:1,
FirstName:"John",
LastName:"Doe"
}
IfyoudefinedthecompositePRIMARYKEYonCustomertableas
CREATEFOREIGNTABLECustomer(
customer_idinteger,
FirstNamevarchar(25),
LastNamevarchar(25),
PRIMARYKEY(FirstName,LastName)
)OPTIONS(UPDATABLE'TRUE');
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
573
![Page 574: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/574.jpg)
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
CREATEFOREIGNTABLECustomer(
CustomerIdintegerPRIMARYKEY,
FirstNamevarchar(25),
LastNamevarchar(25)
)OPTIONS(UPDATABLE'TRUE');
CREATEFOREIGNTABLEAddress(
CustomerIdinteger,
Streetvarchar(50),
Cityvarchar(25),
Statevarchar(25),
Zipcodevarchar(6),
FOREIGNKEY(CustomerId)REFERENCESCustomer(CustomerId)
)OPTIONS(UPDATABLE'TRUE');
bydefault,thiswillproducetwodifferentcollectionsinMongoDB,likewithsampledataitwilllooklike
Customer
{
MongoDBTranslator
574
![Page 575: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/575.jpg)
_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
CREATEFOREIGNTABLECustomer(
CustomerIdintegerPRIMARYKEY,
FirstNamevarchar(25),
LastNamevarchar(25)
)OPTIONS(UPDATABLE'TRUE');
CREATEFOREIGNTABLEAddress(
CustomerIdintegerPRIMARYKEY,
Streetvarchar(50),
Cityvarchar(25),
Statevarchar(25),
Zipcodevarchar(6),
FOREIGNKEY(CustomerId)REFERENCESCustomer(CustomerId)
)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
575
![Page 576: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/576.jpg)
ForexampleifyouhaveDDLlike
CREATEFOREIGNTABLECustomer(
CustomerIdintegerPRIMARYKEY,
FirstNamevarchar(25),
LastNamevarchar(25)
)OPTIONS(UPDATABLE'TRUE');
CREATEFOREIGNTABLEOrder(
OrderIDintegerPRIMARYKEY,
CustomerIdinteger,
OrderDatedate,
Statusinteger,
FOREIGNKEY(CustomerId)REFERENCESCustomer(CustomerId)
)OPTIONS(UPDATABLE'TRUE');
intheaboveaSingleCustomercanhaveMANYOrders.TherearetwooptionstodefinethehowwestoretheMongoDBdocument.Ifinyourschema,theCustomertable’sCustomerIdisonlyreferencedinOrdertable(i.e.CustomerinformationusedforonlyOrderpurposes),youcanuse
CREATEFOREIGNTABLECustomer(
CustomerIdintegerPRIMARYKEY,
FirstNamevarchar(25),
LastNamevarchar(25)
)OPTIONS(UPDATABLE'TRUE');
CREATEFOREIGNTABLEOrder(
OrderIDintegerPRIMARYKEY,
CustomerIdinteger,
OrderDatedate,
Statusinteger,
FOREIGNKEY(CustomerId)REFERENCESCustomer(CustomerId)
)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,
OrderDate:ISODate("2001-03-06T06:00:00Z")
Status:5
}
...
]
}
IfCustomertableisreferencedinmoretablesotherthanOrdertable,thenuse"teiid_mongo:EMBEDDABLE"property
CREATEFOREIGNTABLECustomer(
CustomerIdintegerPRIMARYKEY,
FirstNamevarchar(25),
LastNamevarchar(25)
)OPTIONS(UPDATABLE'TRUE',"teiid_mongo:EMBEDDABLE"'TRUE');
MongoDBTranslator
576
![Page 577: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/577.jpg)
CREATEFOREIGNTABLEOrder(
OrderIDintegerPRIMARYKEY,
CustomerIdinteger,
OrderDatedate,
Statusinteger,
FOREIGNKEY(CustomerId)REFERENCESCustomer(CustomerId)
)OPTIONS(UPDATABLE'TRUE');
CREATEFOREIGNTABLEComments(
CommentIDintegerPRIMARYKEY,
CustomerIdinteger,
Commentvarchar(140),
FOREIGNKEY(CustomerId)REFERENCESCustomer(CustomerId)
)OPTIONS(UPDATABLE'TRUE');
ThiscreatesthreedifferentcollectionsinMongoDB.
Customer
{
_id:1,
FirstName:"John",
LastName:"Doe"
}
Order
{
_id:100,
CustomerId:1,
OrderDate:ISODate("2000-01-01T06:00:00Z")
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
577
![Page 578: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/578.jpg)
MANY-2-MANYMapping.
Thiscanalsomappedwithcombinationof"teiid_mongo:MERGE"and"teiid_mongo:EMBEDDABLE"properties(partially).ForexampleifDDLlookslike
CREATEFOREIGNTABLEOrder(
OrderIDintegerPRIMARYKEY,
OrderDatedate,
Statusinteger
)OPTIONS(UPDATABLE'TRUE');
CREATEFOREIGNTABLEOrderDetail(
OrderIDinteger,
ProductIDinteger,
PRIMARYKEY(OrderID,ProductID),
FOREIGNKEY(OrderID)REFERENCESOrder(OrderID),
FOREIGNKEY(ProductID)REFERENCESProduct(ProductID)
)OPTIONS(UPDATABLE'TRUE');
CREATEFOREIGNTABLEProducts(
ProductIDintegerPRIMARYKEY,
ProductNamevarchar(40)
)OPTIONS(UPDATABLE'TRUE');
youmodifytheDDLlikebelow,tohave
CREATEFOREIGNTABLEOrder(
OrderIDintegerPRIMARYKEY,
OrderDatedate,
Statusinteger
)OPTIONS(UPDATABLE'TRUE');
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
578
![Page 579: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/579.jpg)
_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:
CREATEFOREIGNTABLECustomer(
CustomerIdintegerPRIMARYKEY,
FirstNamevarchar(25),
LastNamevarchar(25)
)OPTIONS(UPDATABLE'TRUE');
CREATEFOREIGNTABLEOrder(
OrderIDintegerPRIMARYKEY,
CustomerIdinteger,
OrderDatedate,
Statusinteger,
FOREIGNKEY(CustomerId)REFERENCESCustomer(CustomerId)OPTIONS(allow-join'FALSE')
)OPTIONS(UPDATABLE'TRUE');
withtheexampleabove,Teiidwillcreatetwocollections,howeverwhenuserissuesquerysuchas
SELECTOrderID,LastNameFROMOrderJOINCustomerONOrder.CustomerId=Customer.CustomerId;
insteadofresultinginerror,theJOINprocessingwillhappenintheTeiidengine,withouttheabovepropertyitwillresultinanerror.
WhenyouuseabovepropertiesandcarefullydesigntheMongoDBdocumentstructure,Teiidtranslatorcanintelligentlycollatedatabasedontheirco-locationandtakeadvantageofitwhilequerying.
GeoSpatialfunctionsupport
MongoDBTranslator
579
![Page 580: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/580.jpg)
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))))
Samefunctionsusingbuilt-inGeometrytype(theabovefunctionswillbedeprecatedandremovedinfutureversions)
CREATEFOREIGNFUNCTIONgeoIntersects(columnRefstring,geogeometry)RETURNS
boolean;
CREATEFOREIGNFUNCTIONgeoWithin(ccolumnRefstring,geogeometry)RETURNS
boolean;
CREATEFOREIGNFUNCTIONnear(ccolumnRefstring,geogeometry,maxdistanceinteger)
RETURNSboolean;
CREATEFOREIGNFUNCTIONnearSphere(ccolumnRefstring,geogeometry,maxdistance
integer)RETURNSboolean;
CREATEFOREIGNFUNCTIONgeoPolygonIntersects(refstring,geogeometry)RETURNS
boolean;
CREATEFOREIGNFUNCTIONgeoPolygonWithin(refstring,geogeometry)RETURNS
boolean;
asamplequerylookslike
SELECTlocFROMmapswheremongo.geoWithin(loc,ST_GeomFromGeoJSON('{"coordinates":[[1,2],[3,4]],"type":"Polygo
n"}'))
Therearevarious"st_geom.."methodsareavailableintheGeoSpatialfunctionlibraryinTeiid.
CapabilitiesMongoDBtranslatordesignedontopoftheMongoDBaggregationframework,useofMongoDBversionthatsupportsthisframeworkismandatory.ApartfromSELECTqueries,thistranslatoralsosupportsINSERT,UPDATEandDELETEqueries.
Thistranslatorsupports
grouping
matching
sorting
MongoDBTranslator
580
![Page 581: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/581.jpg)
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.
DirectQueryProcedure
Thisfeatureisturnedoffbydefaultbecauseofthesecurityriskthisexposestoexecuteanycommandagainstthesource.Toenablethisfeature,overridetheexecutionpropertycalled_SupportsDirectQueryProceduretotrue.
Bydefaultthenameoftheprocedurethatexecutesthequeriesdirectlyiscallednative.Overridetheexecutionproperty_DirectQueryProcedureNametochangeittoanothername.
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
581
![Page 582: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/582.jpg)
MongoDBTranslator
582
![Page 583: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/583.jpg)
ObjectTranslatorTheObjecttranslator,knownbythenameofmap-cache,isabridgeforreadingandwritingjavaobjectsfromexternalsources(i.e.,Mapcache)anddeliveringthemtotheengineforprocessing.Andtoassistinprovidingthatbridge,theOBJECTTABLEfunctionisanalternaitivemeansfortransformingcomplexjavaobjectsintorowsandcolumns.
SearchCapabilities
SupportsalocalcachethatisoftypeMapandituseskeysearchingonthemaptofindobjects.
SupportedCapabilities
ThefollowingaretheconnectorcapabilitieswhenKeySearchingisused:
SELECTcommand
CompareCriteria-onlyEQ
InCriteria
Insert,UpdateandDelete
UsageRetrieveobjectsfromacacheandtransformintorowsandcolumns.
Performinserts,updatesanddeletestothecache
Properties
Objecttranslatoriscapableofreturningtotheclientapplicationthejavaobjectstoredinthecache.Toenablethetranslatortoautomaticallyincludetheobjectasacolumninthemetadata,usethefollowingImportProperties.
ImportProperties
PropertyName Description Required Default
ClassObjectColumn
Iftrue,andwhenthetranslatorprovidesthemetadata,acolumnofobjectdatatypewillbecreatedthatrepresentsthestoredobjectinthecache
false false
Metadata
RequirementsforDefiningTableforRootClass
Tablelevelrequirements
ObjectTranslator
583
![Page 584: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/584.jpg)
Thetablefortherootclass,musthaveaprimarykeydefined,whichmustmaptoanattributeintheclass.
Thetablename(orthenameinsource)mustmatchthenameofthePojoclassname.Thisishowthetableismatchedtotheregisteredclassinthecache.
Note Theprimarykeydatatypefortheattributeintheclassmustmatchthecachekeydatatype.
Columnlevelrequirements
Theclassobjectcolumnthatrepresentsthecachedobjectshouldhaveanameinsourceof'this'.Allothercolumnswillhavetheirnameinsource(whichdefaultstothecolumnname)interpretedasthepathtothecolumnvaluefromtheprimaryobject.
AllcolumnsthatarenottheprimarykeynorcoveredbyaluceneindexshouldbemarkedasSEARCHABLE'Unsearchable'.
Attributesdefinedasrepeatable(i.e.,collections,arrays,ormap)oracontainerclass,canbesupportedas1-to-*relationship,andwillhavecorrespondingregisteredclass(iftheyaretobesearched).
RequirementsforDefiningChildTableinaRelationship
Arelationshipneedstobedefinediftheprimaryclasscontainsacomplexobjecttypethatyouwanttoquery.
Supportedrelationships
1-to-1-musthavegetter/setterforasingleobject
1-to-many-musthavegetter/setterforaCollection,MaporArraytype.
Tablelevelrequirements
Thetablename(orthenameinsource)mustmatchthenameofthePojoclassstoringthechildinformation.Thisishowthetableismatchedtotheregisteredclass(s)inthecache.
Thechildtablemusthaveaforeignkeythatmapstotheparenttableprimarykey.
Thenameinsourcefortheforeignkeyisthenameoftheparentclassmethodtoaccessthechildobjects.
ExampleforDefiningMetadata
ThefollowingisanexampleofaPersonthatcanhavePhones.ThisdemonstrateshowtodefinetheprimaryclassandarelationshipusingDDL.
publicclassPerson{
publicStringname;
publicintid;
publicStringemail;
publicList<PhoneNumber>phones;
publicStringgetName(){
returnname;
}
publicvoidsetName(Stringname){
this.name=name;
}
publicintgetId(){
ObjectTranslator
584
![Page 585: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/585.jpg)
returnid;
}
publicvoidsetId(intid){
this.id=id;
}
publicStringgetEmail(){
returnemail;
}
publicvoidsetEmail(Stringemail){
this.email=email;
}
publicList<PhoneNumber>getPhones(){
returnphones;
}
publicvoidsetPhones(List<PhoneNumber>phones){
this.phones=phones;
}
}
publicclassPhoneNumber{
privateStringnumber;
privateStringtype;
publicStringgetNumber(){
returnnumber;
}
publicvoidsetNumber(Stringnumber){
this.number=number;
}
publicStringgetType(){
returntype;
}
publicvoidsetType(Stringtype){
this.type=type;
}
}
Note,thisalsoshowsacontainerclass,PhoneNumber,asanexampleoftheforeignkeythat’sdefinestherelationship.
<vdbname="PersonVDB"version="1">
<modelname="PersonModel"visible="false">
<sourcename="objsource"translator-name="map-cache"connection-jndi-name="java:cache-jndi"/>
<metadatatype="DDL"><![CDATA[
CREATEFOREIGNTABLEPerson(
PersonObjectobjectOPTIONS(NAMEINSOURCE'this',SELECTABLEFALSE,UPDATABLEFALSE,SE
ARCHABLE'Unsearchable',NATIVE_TYPE'org.jboss.as.quickstarts.datagrid.hotrod.query.domain.Person'),
idintegerNOTNULLOPTIONS(NAMEINSOURCE'id',SEARCHABLE'Searchable',NATIVE_TYPE'i
nt'),
namestringOPTIONS(NAMEINSOURCE'name',SEARCHABLE'Searchable',NATIVE_TYPE'java.la
ng.String'),
emailstringOPTIONS(NAMEINSOURCE'email',SEARCHABLE'Searchable',NATIVE_TYPE'java.
lang.String'),
CONSTRAINTPK_IDPRIMARYKEY(id)
)OPTIONS(UPDATABLETRUE);
CREATEFOREIGNTABLEPhoneNumber(
ObjectTranslator
585
![Page 586: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/586.jpg)
idintegerNOTNULLOPTIONS(NAMEINSOURCE'id',SELECTABLEFALSE,UPDATABLEFALSE,SEAR
CHABLE'Searchable',NATIVE_TYPE'int'),
numberstringOPTIONS(NAMEINSOURCE'phone.number',SEARCHABLE'Searchable',NATIVE_TYP
E'java.lang.String'),
typestringOPTIONS(NAMEINSOURCE'phone.type',SEARCHABLE'Unsearchable',NATIVE_TYPE
'java.lang.Enum'),
CONSTRAINTFK_PERSONFOREIGNKEY(id)REFERENCESPerson(id)OPTIONS(NAMEINSOURCE'phon
es')
)OPTIONS(UPDATABLETRUE);
]]></metadata>
</model>
</vdb>
ThismetadatacouldalsobedefinedbyusingtheTeiidDesigner.
JCAResourceAdapter
ObjectTranslator
586
![Page 587: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/587.jpg)
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
Name Description Default
DatabaseTimeZoneThetimezoneofthedatabase.Usedwhenfetchingsdate,time,ortimestampvalues
Thesystemdefaulttimezone
SupportsOdataCount Supports$count true
SupportsOdataFilter Supports$filter true
SupportsOdataOrderBy Supports$orderby true
ODataTranslator
587
![Page 588: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/588.jpg)
SupportsOdataSkip Supports$skip true
SupportsOdataTop Supports$top true
ImporterProperties
Name Description Default
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
588
![Page 589: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/589.jpg)
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
589
![Page 590: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/590.jpg)
<resource-adapterid="trippin">
<moduleslot="main"id="org.jboss.teiid.resource-adapter.webservice"/>
<transaction-support>NoTransaction</transaction-support>
<connection-definitions>
<connection-definitionclass-name="org.teiid.resource.adapter.ws.WSManagedConnectionFactory"jndi-name=
"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>
</connection-definition>
</connection-definitions>
</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
Name Description Default
SupportsOdataCount Supports$count true
SupportsOdataFilter Supports$filter true
SupportsOdataOrderBy Supports$orderby true
SupportsOdataSkip Supports$skip true
SupportsOdataTop Supports$top true
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
590
![Page 591: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/591.jpg)
ImporterProperties
Importerpropertiesdefinethebehaviorofthetranslatorduringthemetadataimportfromthephysicalsource.
ImporterProperties
Name Description Default
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
591
![Page 592: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/592.jpg)
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">
<moduleslot="main"id="org.jboss.teiid.resource-adapter.webservice"/>
<transaction-support>NoTransaction</transaction-support>
<connection-definitions>
<connection-definitionclass-name="org.teiid.resource.adapter.ws.WSManagedConnectionFactory"jndi-name=
"java:/swagger"enabled="true"use-java-context="true"pool-name="teiid-swagger-ds">
<config-propertyname="EndPoint">
http://petstore.swagger.io/v2
</config-property>
</connection-definition>
</connection-definitions>
</resource-adapter>
Onceyouconfigureaboveresource-adapteranddeploytheVDBsuccessfully,thenyoucanconnecttotheVDBdeployedusingTeiidJDBCdriverandissueSQLstatementslike
EXECfindPetsByStatus(('sold',))
EXECgetPetById(1461159803)
EXECdeletePet('',1461159803)
ConfigurationofTranslator
ExecutionProperties
SwaggerTranslator
592
![Page 593: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/593.jpg)
Executionpropertiesextend/limitthefunctionalityofthetranslatorbasedonthephysicalsourcecapabilities.Sometimesdefaultpropertiesneedtoadjustedforproperexecutionofthetranslator.
ExecutionProperties
none
ImporterProperties
Importerpropertiesdefinethebehaviorofthetranslatorduringthemetadataimportfromthephysicalsource.
ImporterProperties
Name Description Default
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
TheresourceadapterforthistranslatorisaWebServiceDataSource.
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
593
![Page 594: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/594.jpg)
SwaggerTranslator
594
![Page 595: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/595.jpg)
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
595
![Page 596: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/596.jpg)
TheresourceadapterforthistranslatorprovidedthroughdatasourceinWildFly,RefertoAdminGuidefor"JDBCDataSources"configurationsection.TwosamplexmlfilesareprovidedforaccessingOLAPserversintheteiid-examplessection.OneisMondrianspecific,whenMondrianserverisdeployedinthesameWildFlyasTeiid(mondrian-ds.xml).ToaccessanyotherOLAPserversusingXMLAinterface,thedatasourceforthemcanbecreatedusingthemexampletemplateolap-xmla-ds.xml
OLAPTranslator
596
![Page 597: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/597.jpg)
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
Name Description Default
ModelAuditFeilds AuditModelFields false
MaxBulkInsertBatchSize BatchSizetousetoinsertbulkinserts 2048
SupportsGroupBy
SupportsGroupByPushdown.SettofalsetohaveTeiidprocessgroupbyaggregations,suchasthosereturningmorethan2000rowswhicherrorinSOQL.
true
TheSalesforcetranslatorcanimportmetadata.
ImportProperties
PropertyName Description Required Default
NormalizeNames
Iftheimportershouldattempttomodifytheobject/fieldnamessothattheycanbeusedunquoted.
false true
Acase-insensitiveregularexpressionthatwhenmatchedagainstatablenamewillexcludeitfrom
SalesforceTranslators
597
![Page 598: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/598.jpg)
excludeTables import.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.
ExtensionMetadataProperties
Salesforceisnotrelationaldatabase,howeverTeiidprovideswaystomapSaleforcedataintorelationalconstructslikeTablesandProcedures.YoucandefineaforeignTableusingDDLinTeiidVDB,whichmapstoSalesforce’sSObject.Atruntime,tointerpretthistablebacktoaSObject,Teiiddecoratesortagsthistabledefinitionwithadditionalmetadata.Forexample,atableisdefinedas
CREATEFOREIGNTABLEPricebook2(
Idstring,
Namestring,
IsActiveboolean,
IsStandardboolean,
Descriptionstring,
IsDeletedboolean)
OPTIONS(
UPDATABLE'TRUE',
"teiid_sf:SupportsQuery"'TRUE');
IntheabovethepropertyinOPTIONSclausewithproperty"teiid_sf:SupportsQuery"annotatingthatthistablessupportsSELECTcommands.ThebelowarelistofmetadataextensionpropertiesthatcanbeusedonSalesforceschema.
PropertyName Description Required Default AppliesTo
SupportsQueryThetablesupportsSELECTcommands
false true Table
SalesforceTranslators
598
![Page 599: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/599.jpg)
SupportsRetrieve
ThetablesupportsretrievalofresultsasresultofSELECTcommands
false true Table
SQLProcessing
Salesforcedoesnotprovidethesamesetoffunctionalityasarelationaldatabase.Forexample,Salesforcedoesnotsupportarbitraryjoinsbetweentables.However,workingincombinationwiththeTeiidQueryPlanner,theSalesforceconnectorsupportsnearlyalloftheSQLsyntaxsupportedbytheTeiid.
TheSalesforceConnectorexecutesSQLcommandsby"pushingdown"thecommandtoSalesforcewheneverpossible,basedonthesupportedcapabilities.TeiidwillautomaticallyprovideadditionaldatabasefunctionalitywhentheSalesforceConnectordoesnotexplicitlyprovidesupportforagivenSQLconstruct.IncaseswherecertainSQLcapabilitiescannotbepusheddowntoSalesforce,Teiidwillpushdownthecapabilitiesthataresupported,andfetchasetofdatafromSalesforce.Then,Teiidwillevaluatetheadditionalcapabilities,creatingasubsetoftheoriginaldataset.Finally,Teiidwillpasstheresulttotheclient.
IfyouareissuingquerieswithagroupbyclauseandreceiveanerrorforsalesforcerelatedtoqueryMorenotbeingsupported,youmayeitheraddlimitsorsettheexecutionpropertySupportsGroupBytofalse.
SELECTarray_agg(Reports)FROMSupervisorwhereDivision='customersupport';
NeitherSalesforcenortheSalesforceConnectorsupportthearray_agg()scalar,buttheydosupportCompareCriteriaEquals,sothequerythatispassedtoSalesforcebytheconnectorwillbetransformedtothisquery.
SELECTReportsFROMSupervisorwhereDivision='customersupport';
Thearray_agg()functionwillbeappliedbytheTeiidQueryEnginetotheresultsetreturnedbytheconnector.
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
SalesforceTranslators
599
![Page 600: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/600.jpg)
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
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,
SalesforceTranslators
600
![Page 601: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/601.jpg)
LatestDateCoveredOUTdatetime)
returns
IDstring
SeethedescriptionoftheGetUpdatedoperationintheSalesforcedocumentationforusagedetails.
SelectingDeletedObjects
IftheoptionisselectedwhenimportingmetadatafromSalesforce,aGetDeletedprocedureisgeneratedinthemodelwiththefollowingstructure:
GetDeleted(ObjectNameINstring,
StartDateINdatetime,
EndDateINdatetime,
EarliestDateAvailableOUTdatetime,
LatestDateCoveredOUTdatetime)
returns
IDstring,
DeletedDatedatetime
SeethedescriptionoftheGetDeletedoperationintheSalesforcedocumentationforusagedetails.
RelationshipQueries
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.
SalesforceTranslators
601
![Page 602: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/602.jpg)
SupportedCapabilities
ThefollowingarethecapabilitiessupportedbytheSalesforceConnector.TheseSQLconstructswillbepusheddowntoSalesforce.
SELECTcommand
INSERTCommand
UPDATECommand
DELETECommand
NotCriteria
OrCriteria
CompareCriteriaEquals
CompareCriteriaOrdered
IsNullCritiera
InCriteria
LikeCriteria-SupportedforStringfieldsonly.
RowLimit
BasicAggregates
OuterJoinswithjoincriteriaKEY
NativeQueries
Salesforceproceduresmayoptionallyhavenativequeriesassociatedwiththem-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);
DirectQueryProcedure
Thisfeatureisturnedoffbydefaultbecauseofthesecurityriskthisexposestoexecuteanycommandagainstthesource.Toenablethisfeature,overridetheexecutionpropertycalled_SupportsDirectQueryProceduretotrue.
Tip Bydefaultthenameoftheprocedurethatexecutesthequeriesdirectlyisnative.Overridetheexecutionproperty_DirectQueryProcedureNametochangeittoanothername.
TheSalesforcetranslatorprovidesaproceduretoexecuteanyad-hocSOQLquerydirectlyagainstthesourcewithoutTeiidparsingorresolving.Sincethemetadataofthisprocedure’sresultsarenotknowntoTeiid,theyarereturnedasanobjectarray.ARRAYTABLEcanbeusedconstructtabularoutputforconsumptionbyclientapplications.Teiidexposesthisprocedurewithasimplequerystructureasfollows:
SalesforceTranslators
602
![Page 603: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/603.jpg)
Select
SelectExample
SELECTx.*FROM(callsf_source.native('search;SELECTAccount.Id,Account.Type,Account.NameFROMAccount'))w,
ARRAYTABLE(w.tupleCOLUMNS"id"string,"type"string,"name"String)ASx
fromtheabovecode,the"search"keywordfollowedbyaquerystatement.
Note TheSOQListreatedasaparameterizednativequerysothatparametervaluesmaybeinsertedinthequerystringproperly-seeParameterizableNativeQueries
TheresultsreturnedbysearchmaycontaintheobjectIdasthefirstcolumnvalueregardlessofwhetheritwasselected.Alsoqueriesthatselectcolumnsfrommultipleobjecttypeswillnotbecorrect.
Delete
DeleteExample
SELECTx.*FROM(callsf_source.native('delete;','id1','id2'))w,
ARRAYTABLE(w.tupleCOLUMNS"updatecount"integer)ASx
formtheabovecode,the"delete;"keywordfollowedbytheidstodeleteasvarargs.
CreateorUpdate
CreateExample
SELECTx.*FROM
(callsf_source.native('create;type=table;attributes=one,two,three','one',2,3.0))w,
ARRAYTABLE(w.tupleCOLUMNS"update_count"integer)ASx
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,
ARRAYTABLE(w.tupleCOLUMNS"update_count"integer)ASx
Tip Bydefaultthenameoftheprocedurethatexecutesthequeriesdirectlyiscallednative,howeverusercan+setoverrideexecutionpropertyvdb.xmlfiletochangeit.
JCAResourceAdapter
SalesforceTranslators
603
![Page 604: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/604.jpg)
TheresourceadapterforthistranslatorisprovidedthroughSalesforceDataSources.RefertoAdminGuideforconfiguration.
SalesforceTranslators
604
![Page 605: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/605.jpg)
SAPGatewayTranslatorTheSAPGatewayTranslator,knownbythetypenamesap-gateway,providesatranslatorforaccessingtheSAPGatewayusingtheODataprotocol.ThistranslatorisextensionofODataTranslatorandusesTeiidWSresourceadapterformakingwebservicecalls.ThistranslatorunderstandsthemostoftheSAPspecificODataextensionstothemetadatadefinedinthedocumentSAPAnnotationsforODataVersion2.0
WhenthemetadataisimportedfromSAPGateway,theTeiidmodelsarecreatedtoaccordinglyforSAPspecificEntitySetandPropertyannotationsdefinedindocumentabove.
Thefollowing"executionproperties"aresupportedinthistranslator
ExecutionProperties
Name Description Default
DatabaseTimeZoneThetimezoneofthedatabase.Usedwhenfetchingsdate,time,ortimestampvalues
Thesystemdefaulttimezone
SupportsOdataCount Supports$count true
SupportsOdataFilter Supports$filter true
SupportsOdataOrderBy Supports$orderby true
SupportsOdataSkip Supports$skip true
SupportsOdataTop Supports$top true
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
605
![Page 606: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/606.jpg)
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
Name Description Default
importWSDL ImportthemetadatafromtheWSDLURLconfiguredinresource-adapter true
Usage
TheWStranslatorexposeslowlevelproceduresforaccessingwebservices.Seealsothetwitterexampleinthekit.
InvokeProcedure
WebServicesTranslator
606
![Page 607: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/607.jpg)
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
WebServicesTranslator
607
![Page 608: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/608.jpg)
Theproceduresabovegiveyouanonymouswaytoexecuteanywebservicemethodsbysupplyinganendpoint,withthismechanismyoucanaltertheendpointdefinedinWSDLwithadifferentendpoint.However,ifyouhaveaccesstotheWSDL,thenyoucanconfiguretheWSDLURLintheweb-serviceresource-adapter’sconnectionconfiguration,WebServicetranslatorcanparsetheWSDLandprovidethemethodsunderconfiguredportaspre-builtproceduresasitsmetadata.Ifyouareusingthedefaultnativemetadataimport,youwillseetheproceduresinyourwebservice’ssourcemodel.
Note Nativequeries-NativequeriesoradirectqueryexecutionprocedureisnotsupportedontheWebServicesTranslator.
StreamingConsiderations
Ifthestreamparameterissettotrue,thentheresultinglobvaluemayonlybeusedasingletime.Ifstreamisnullorfalse,thentheenginemayneedtosaveacopyoftheresultforrepeateduse.Caremustbeusedassomeoperations,suchascastingorXMLPARSEmayperformvalidationwhichresultsinthestreambeingconsumed.
JCAResourceAdapter
TheresourceadapterforthistranslatorisaWebServiceDataSource.
Note WS-Security-CurrentlyyoucanonlyuseWSDLbasedProceduresparticipateinWS-Security,whenresource-adapterisconfiguredwithcorrectCXFconfiguration.
WebServicesTranslator
608
![Page 609: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/609.jpg)
FederatedPlanningTeiidatitscoreisafederatedrelationalqueryengine.ThisqueryengineallowsyoutotreatallofyourdatasourcesasonevirtualdatabaseandaccesstheminasingleSQLquery.Thisallowsyoutofocusonbuildingyourapplication,notonhand-codingjoins,andotherrelationaloperations,betweendatasources.
ChildPages
PlanningOverview
QueryPlanner
QueryPlans
FederatedOptimizations
SubqueryOptimization
XQueryOptimization
FederatedFailureModes
ConformedTables
FederatedPlanning
609
![Page 610: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/610.jpg)
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
610
![Page 611: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/611.jpg)
Dataflowsfromthetablesatthebottomupwardsthroughthejoin,throughtheselect,andfinallythroughtheprojecttoproducethefinalresults.Thedatapassedbetweeneachnodeislogicallyaresultsetwithcolumnsandrows.
Ofcourse,thisiswhathappenslogically,nothowtheplanisactuallyexecuted.Startingfromthisinitialplan,thequeryplannerperformstransformationsonthequeryplantreetoproduceanequivalentplanthatretrievesthesameresultsfaster.Bothafederatedqueryplannerandarelationaldatabaseplannerdealwiththesameconceptsandmanyofthesameplantransformations.Inthisexample,thecriteriaontheDepartmentsandEmployeestableswillbepusheddownthetreetofiltertheresultsasearlyaspossible.
Inbothcases,thegoalistoretrievethequeryresultsinthefastestpossibletime.However,therelationaldatabaseplannerdoesthisprimarilybyoptimizingtheaccesspathsinpullingdatafromstorage.
Incontrast,afederatedqueryplannerislessconcernedaboutstorageaccessbecauseitistypicallypushingthatburdentothedatasource.Themostimportantconsiderationforafederatedqueryplannerisminimizingdatatransfer.
PlanningOverview
611
![Page 612: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/612.jpg)
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
612
![Page 613: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/613.jpg)
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
613
![Page 614: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/614.jpg)
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
PropertyName Description
SET_OPERATION/USE_ALL definesthesetoperation(UNION/INTERSECT/EXCEPT)andifallrowsordistinctrowsareused.
QueryPlanner
614
![Page 615: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/615.jpg)
JoinProperties
Table4.JoinProperties
PropertyName Description
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
PropertyName Description
PROJECT_COLS theexpressionsprojected
INTO_GROUP thegrouptargetedifthisisaselectintoorinsertwithaqueryexpression
HAS_WINDOW_FUNCTIONS trueifwindowfunctionsareused
CONSTRAINT theconstraintthatmustbemetifthevaluesarebeingprojectedintoagroup
UPSERT Iftheinsertisanupsert
QueryPlanner
615
![Page 616: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/616.jpg)
SelectProperties
Table6.SelectProperties
PropertyName Description
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
PropertyName Description
SORT_ORDER theorderbythatdefinesthesort
UNRELATED_SORT iftheorderingincludesavaluethatisnotbeingprojected
IS_DUP_REMOVAL ifthesortshouldalsoperformduplicateremovalovertheentireprojection
SourceProperties
Table8.SourceProperties
PropertyName Description
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
616
![Page 617: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/617.jpg)
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
PropertyName Description
GROUP_COLS thegroupingcolumns
ROLLUP ifthegroupingincludesarollup
TupleLimitProperties
Table10.TupleLimitProperties
PropertyName Description
MAX_TUPLE_LIMIT expressionthatevaluatestothemaxnumberoftuplesgenerated
OFFSET_TUPLE_COUNT Expressionthatevaluatestothetupleoffsetofthestartingtuple
IS_IMPLICIT_LIMIT ifthelimitiscreatedbytherewriteraspartofasubqueryoptimization
IS_NON_STRICT iftheunorderedlimitshouldnotbeenforcedstrictly
GeneralandCostingProperties
Table11.GeneralandCostingProperties
QueryPlanner
617
![Page 618: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/618.jpg)
PropertyName Description
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
618
![Page 619: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/619.jpg)
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
619
![Page 620: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/620.jpg)
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:
JOIN-InnerJoinon(A.x=B.x)
/\
/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
620
![Page 621: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/621.jpg)
Howevercriteriaspecifiedagainsttheinnersideofanouterjoinneedsspecialconsideration.Theabovescenariowithaleftorfullouterjoinisnotthesame.Forexample:
SELECT(B.y=3)
|
JOIN-LeftOuterJoinon(A.x=B.x)
/\
SRC(A)SRC(B)
Canbecome(availableonlyafter5.0.2):
JOIN-InnerJoinon(A.x=B.x)
/\
/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
621
![Page 622: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/622.jpg)
----------------------------------------------------------------------------
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]})
Source(groups=[pm1.g1])
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
622
![Page 623: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/623.jpg)
TPUT_COLS=null})
Source(groups=[pm1.g1])
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
623
![Page 624: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/624.jpg)
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
624
![Page 625: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/625.jpg)
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
625
![Page 626: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/626.jpg)
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
626
![Page 627: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/627.jpg)
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)
+CostEstimates:EstimatedNodeCardinality:-1.0
+Child0:
JoinNode
+OutputColumns:
0:e1(string)
1:e2(integer)
2:e3(boolean)
+CostEstimates:EstimatedNodeCardinality:-1.0
+Child0:
JoinNode
+OutputColumns:
0:e1(string)
1:e1(string)
2:e3(boolean)
+CostEstimates:EstimatedNodeCardinality:-1.0
+Child0:
AccessNode
+OutputColumns:e1(string)
+CostEstimates:EstimatedNodeCardinality:-1.0
+Query:SELECTg_0.e1ASc_0FROMpm1.g1ASg_0ORDERBYc_0
+ModelName:pm1
+Child1:
AccessNode
+OutputColumns:
0:e1(string)
1:e3(boolean)
+CostEstimates:EstimatedNodeCardinality:-1.0
+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)
+CostEstimates:EstimatedNodeCardinality:-1.0
+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
627
![Page 628: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/628.jpg)
Notethatthenestedjoinnodeisusingamergejoinandexpectsthesourcequeriesfromeachsidetoproducetheexpectedorderingforthejoin.Theparentjoinisanenhancedsortjoinwhichcandelaythedecisiontoperformsortingbasedupontheincomingrows.Notethattheouterjoinfromtheuserqueryhasbeenmodifiedtoaninnerjoinsincenoneofthenullinnervaluescanbepresentinthequeryresult.
Thesameplaninxmlformlookslike:
<?xmlversion="1.0"encoding="UTF-8"?>
<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">
<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">
<propertyname="OutputColumns">
<value>e1(string)</value>
<value>e1(string)</value>
<value>e3(boolean)</value>
</property>
<propertyname="CostEstimates">
<value>EstimatedNodeCardinality:-1.0</value>
</property>
<propertyname="Child0">
<nodename="AccessNode">
<propertyname="OutputColumns">
<value>e1(string)</value>
</property>
<propertyname="CostEstimates">
<value>EstimatedNodeCardinality:-1.0</value>
</property>
<propertyname="Query">
<value>SELECTg_0.e1ASc_0FROMpm1.g1ASg_0ORDERBYc_0</value>
</property>
<propertyname="ModelName">
<value>pm1</value>
</property>
</node>
</property>
<propertyname="Child1">
<nodename="AccessNode">
<propertyname="OutputColumns">
<value>e1(string)</value>
<value>e3(boolean)</value>
</property>
<propertyname="CostEstimates">
<value>EstimatedNodeCardinality:-1.0</value>
</property>
<propertyname="Query">
<value>SELECTg_0.e1ASc_0,g_0.e3ASc_1FROMpm1.g3ASg_0
ORDERBYc_0</value>
</property>
<propertyname="ModelName">
QueryPlans
628
![Page 629: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/629.jpg)
<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>
<propertyname="Child1">
<nodename="AccessNode">
<propertyname="OutputColumns">
<value>e1(string)</value>
<value>e2(integer)</value>
</property>
<propertyname="CostEstimates">
<value>EstimatedNodeCardinality:-1.0</value>
</property>
<propertyname="Query">
<value>SELECTg_0.e1ASc_0,g_0.e2ASc_1FROMpm1.g2ASg_0
ORDERBYc_0</value>
</property>
<propertyname="ModelName">
<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>
<value>pm1.g2.e2</value>
<value>pm1.g3.e3</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
629
![Page 630: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/630.jpg)
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
Upsert-iftheinsertisanupsert
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
QueryPlans
630
![Page 631: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/631.jpg)
Message
Tag
Namespace
DataColumn
NamespaceDeclarations
OptionalFlag
DefaultValue
RecursionDirection
Bindings
IsStagingFlag
SourceInMemoryFlag
Condition
DefaultProgram
Encoding
FormattedFlag
Procedure
Expression
ResultSet
Program
Variable
Then
Else
OtherPlansXMLdocumentmodelqueriesandprocedureexecution(includinginsteadoftriggers)useintermediateandfinalplanformsthatincluderelationalplans.Generallythestructureofthexml/procedureplanswillcloselymatchtheirlogicalforms.It’sthenestedrelationalplansthatwillbeofinterestwhenanalyzingperformanceissues.
QueryPlans
631
![Page 632: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/632.jpg)
FederatedOptimizations
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.
FederatedOptimizations
632
![Page 633: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/633.jpg)
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
FederatedOptimizations
633
![Page 634: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/634.jpg)
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.
FederatedOptimizations
634
![Page 635: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/635.jpg)
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.
SubqueryOptimization
JoinCompensation
FederatedOptimizations
635
![Page 636: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/636.jpg)
Somesourcesystemsonlyallow"relationship"querieslogicallyproducingleftouterjoinresultsevenwhenqueriedwithaninnerjoinTeiidwillattempttoformanappropriateleftouterjoin.Thesesourcesarerestrictedtoonlysupportingkeyjoins.Insomecircumstancesforeignkeyrelationshipsonthesamesourceshouldnotbetraversedatallorwiththereferencedtableontheoutersideofjoin.Theextensionpropertyteiid_rel:allow-joincanbeusedontheforeignkeytofurtherrestrictthepushdownbehavior.Withavalueof"false"nojoinpushdownwillbeallowed,andwithavalueof"inner"thereferencedtablemustbeontheinnersideofthejoin.Ifthejoinpushdownisprevented,thejoinwillbeprocessedasafederatedjoin.
FederatedOptimizations
636
![Page 637: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/637.jpg)
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,whichsupersedestheotherhints,willdirecttheoptimizertoleavethesubqueryinplace.
SELECTscalarsubqueriescantaketheMJ(mergejoin)orNO_UNNEST(nounnest)hintsappearingjustbeforethesubquery.TheMJhintdirectstheoptimizertouseatraditionalorsemijoinmergejoinifpossible.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.
SubqueryOptimization
637
![Page 638: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/638.jpg)
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
638
![Page 639: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/639.jpg)
XQueryOptimization
639
![Page 640: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/640.jpg)
PartialResultsTeiidprovidesthecapabilitytoobtain"partialresults"intheeventofdatasourceunavailabilityorfailure.Thisisespeciallyusefulwhenunioninginformationfrommultiplesources,orwhendoingaleftouterjoin,whereyouare`appending'columnstoamasterrecordbutstillwanttherecordiftheextrainformationisnotavailable.
Asourceisconsideredtobe`unavailable'iftheconnectionfactoryassociatedwiththesourceissuesanexceptioninresponsetoaquery.Theexceptionwillbepropagatedtothequeryprocessor,whereitwillbecomeawarningonthestatement.SeetheClientGuideformoreonPartialResultsModeandSQLWarnings.
FederatedFailureModes
640
![Page 641: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/641.jpg)
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
641
![Page 642: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/642.jpg)
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
642
![Page 643: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/643.jpg)
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
643
![Page 644: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/644.jpg)
TerminologyVMorProcess–aJBossASinstancerunningTeiid.
Host–amachinethatis"hosting"oneormoreVMs.
Service–asubsystemrunninginaVM(ofteninmanyVMs)andprovidingarelatedsetoffunctionality.Inadditiontothesemaincomponents,theserviceplatformprovidesacoresetofservicesavailabletoapplicationsbuiltontopoftheserviceplatform.Theseservicesare:
Session–theSessionservicemanagesactivesessioninformation.
BufferManager–theBufferManagerserviceprovidesaccesstodatamanagementforintermediateresults.
Transaction–theTransactionservicemanagesglobal,local,andrequestscopedtransactions.SeealsothedocumentationonTransactionSupport.
Terminology
644
![Page 645: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/645.jpg)
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
645
![Page 646: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/646.jpg)
up.
DataManagement
646
![Page 647: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/647.jpg)
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
647
![Page 648: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/648.jpg)
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
648
![Page 649: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/649.jpg)
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
649
![Page 650: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/650.jpg)
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
650
![Page 651: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/651.jpg)
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
651
![Page 652: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/652.jpg)
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
652
![Page 653: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/653.jpg)
LOOP loopstatement
MAKEDEP optionclause,tableprimary
MAKEIND optionclause,tableprimary
MAKENOTDEP optionclause,tableprimary
MERGE insertstatement
MINUTE function
MONTH function
NO makedepoptions,xmlnamespaceelement,textaggreatefunction,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
653
![Page 654: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/654.jpg)
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
654
![Page 655: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/655.jpg)
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
655
![Page 656: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/656.jpg)
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
656
![Page 657: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/657.jpg)
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
657
![Page 658: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/658.jpg)
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
658
![Page 659: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/659.jpg)
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
UPSERT insertstatement,non-reservedidentifier
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
BNFforSQLGrammar
659
![Page 660: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/660.jpg)
CHARACTER CHECK CLOSE
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
BNFforSQLGrammar
660
![Page 661: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/661.jpg)
SEARCH SENSITIVE SESSION_USER
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
BNFforSQLGrammar
661
![Page 662: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/662.jpg)
eq "="assignmentstatement,callablestatement,declarestatement,namedparameterlist,comparisonoperator,setclauselist
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
BNFforSQLGrammar
662
![Page 663: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/663.jpg)
lt "<" comparisonoperator
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
BNFforSQLGrammar
663
![Page 664: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/664.jpg)
unsignedintegerliteral (<digit>)+ unsignedinteger,unsignednumericliteral
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
BNFforSQLGrammar
664
![Page 665: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/665.jpg)
compoundstatement statement,directlyexecutablestatement
otherconstraints createtablebody
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
BNFforSQLGrammar
665
![Page 666: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/666.jpg)
existspredicate booleanprimary
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
BNFforSQLGrammar
666
![Page 667: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/667.jpg)
timeinterval function
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,temporarytable
BNFforSQLGrammar
667
![Page 668: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/668.jpg)
element,texttablecolumn,unescapedFunction,xmltablecolumn
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
BNFforSQLGrammar
668
![Page 669: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/669.jpg)
datastatement delimitedstatement
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
BNFforSQLGrammar
669
![Page 670: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/670.jpg)
whilestatement statement
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
BNFforSQLGrammar
670
![Page 671: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/671.jpg)
SERIAL
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
BNFforSQLGrammar
671
![Page 672: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/672.jpg)
ACCESSPATTERN
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
BNFforSQLGrammar
672
![Page 673: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/673.jpg)
JSONARRAY_AGG
JSONOBJECT
PRESERVE
UPSERT
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>)
BNFforSQLGrammar
673
![Page 674: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/674.jpg)
Definesanactiontoperformoneachrow.
Example:
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:
BNFforSQLGrammar
674
![Page 675: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/675.jpg)
CREATELOCALTEMPORARYTABLEtmp(colinteger)
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>)?
BNFforSQLGrammar
675
![Page 676: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/676.jpg)
createsasqlexceptionorwarningwiththespecifiedmessage,state,andcode
Example:
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
BNFforSQLGrammar
676
![Page 677: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/677.jpg)
returnstatement::=
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:
BNFforSQLGrammar
677
![Page 678: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/678.jpg)
DECLARESTRINGx='a'
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>))?
BNFforSQLGrammar
678
![Page 679: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/679.jpg)
Aprocedurestatementthatcanexecutearbitrarysql.
Example:
EXECUTEIMMEDIATE'SELECT*FROMtbl'ASxSTRINGINTO#temp
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)
BNFforSQLGrammar
679
![Page 680: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/680.jpg)
namedparameterlist::=
(<identifier><eq>(<gt>)?<expression>(<comma><identifier><eq>(<gt>)?<expression>)*)
Alistofnamedparameters.
Example:
param1=>'x',param2=>1
insertstatement::=
(INSERT|MERGE|UPSERT)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
BNFforSQLGrammar
680
![Page 681: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/681.jpg)
queryexpression::=
(WITH<withlistelement>(<comma><withlistelement>)*)?<queryexpressionbody>
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>)
BNFforSQLGrammar
681
![Page 682: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/682.jpg)
(<lparen><queryexpressionbody><rparen>)
Adeclarativesourceofrows.
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
BNFforSQLGrammar
682
![Page 683: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/683.jpg)
Example:
tbl.*
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
683
![Page 684: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/684.jpg)
textaggreatefunction::=
TEXTAGG<lparen>(FOR)?<derivedcolumn>(<comma><derivedcolumn>)*(DELIMITER<character>)?((QUOTE<character>)|(NOQUOTE))?(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.
BNFforSQLGrammar
684
![Page 685: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/685.jpg)
Example:
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>)
BNFforSQLGrammar
685
![Page 686: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/686.jpg)
AnINNERorOUTERjoin.
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
686
![Page 687: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/687.jpg)
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
687
![Page 688: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/688.jpg)
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
688
![Page 689: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/689.jpg)
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
689
![Page 690: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/690.jpg)
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
690
![Page 691: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/691.jpg)
='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
691
![Page 692: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/692.jpg)
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
692
![Page 693: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/693.jpg)
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
693
![Page 694: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/694.jpg)
<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
694
![Page 695: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/695.jpg)
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
695
![Page 696: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/696.jpg)
<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
696
![Page 697: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/697.jpg)
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
697
![Page 698: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/698.jpg)
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
698
![Page 699: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/699.jpg)
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
699
![Page 700: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/700.jpg)
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
700
![Page 701: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/701.jpg)
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
701
![Page 702: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/702.jpg)
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
702
![Page 703: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/703.jpg)
(<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
703
![Page 704: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/704.jpg)
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
704
![Page 705: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/705.jpg)
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
705
![Page 706: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/706.jpg)
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
706
![Page 707: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/707.jpg)
altercolumnoptions::=
ALTER(COLUMN|PARAMETER)?<identifier><alteroptionslist>
altersasetofcolumnoptions
Example:
ALTERCOLUMNbarOPTIONS(ADDupdatabletrue)
BNFforSQLGrammar
707
![Page 708: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/708.jpg)
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
708
![Page 709: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/709.jpg)
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
709
![Page 710: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/710.jpg)
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
<authenticationsecurity-domain="teiid-security"/>
<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.
<vdbname="vdb"version="1">
<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
710
![Page 711: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/711.jpg)
TheRealmDirectLoginModuleutilizesacommonsecurityrealmacrossinstalledWildFly/EAPinstancedefinedbydefaultApplicationRealmtoperformauthenticationandauthorization.TousethissecurityrelamaddthefollowingXMLunder"security"subsysteminstandalone-teiid.xmlordomain.xml
standalone-teiid.xml
<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>
Whenusingthissecuritydomain,use<wildfly>/bin/add-user.shor<wildfly>/bin/add-user.batscriptstoadd/updateauserin"ApplicationRelam".Whenusingthisrelam,thepasswordasstoredinencryptedform.Thisisthedefaultsecuritymodulethatisused.
TextBasedLoginModuleTheUsersRolesLoginModuleutilizessimpletextfilestoauthenticateusersandtodefinetheirgroups.TousethisaddthefollowingXMLunder"security"subsysteminstandalone-teiid.xmlordomain.xml
standalone-teiid.xml
<subsystemxmlns="urn:jboss:domain:security:1.1">
<security-domains>
<security-domainname="teiid-security"cache-type="default">
<authentication>
<login-modulecode="UsersRoles"flag="required">
<module-optionname="usersProperties"value="$(jboss.server.config.dir)/users.properties"/>
<module-optionname="rolesProperties"value="$(jboss.server.config.dir)/roles.properties"/>
</login-module>
</authentication>
</security-domain>
</security-domains>
</subsystem>
Warning TheUsersRolesLoginModuleisnotrecommendedforproductionuseandisstronglyrecommendedthatyoureplacethisloginmodule.
Peraboveconfiguration,Usernamesandpasswordsarestoredinthe<wildfly>/standalone/configuration/users.propertiesfile,anexampleuser.propertiesfilelookslikebelow
users.properties
#Ausers.propertiesfileforusewiththeUsersRolesLoginModule
#username=password
fred=password
george=password
...
LoginModules
711
![Page 712: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/712.jpg)
Theroleassignmentsarestoredinthe<wildfly>/standalone/configuration/roles.propertiesfile,anexampleroles.propertiesfilelookslikebelow
roles.properties
#Aroles.propertiesfileforusewiththeUsersRolesLoginModule
#username=role1,role2,...
data_role_1=fred,sally
data_role_2=george
Userandrolenamesareentirelyuptotheneedsofthegivendeployment.ForexampleeachapplicationteamcansettheirownsecurityconstraintsfortheirVDBs,bymappingtheirVDBdatarolestoapplicationspecificJAASroles,e.g.app_role_1=user1,user2,user3.
Note Whenyouconfigurethissecuritydomain,youmustprovidetheemptyuser.propertiesandroles.propertiesfilesatthecorrectpathdefinedintheconfiguration,otherwisetheinitializationofsecuritydomainwillendupinfailure.
Note TeiiddatarolesnamesareindependentofJAASroles.VDBcreatorscanchoosewhatevernametheywantfortheirdataroles,whicharethenmappedatdeploymenttimetoJAASroles.
LDAPBasedLoginModuleFormorecompleteinformationtoconfigureaLDAPbasedloginmoduleconsultEAPdocumentation
ConfigureLDAPauthenticationbyeditingstandalone-teiid.xmlunder'security'subsystem.Oncethesecurity-domainisdefined,theneditthe'security-domain'attributeforTeiid’s'transport'forwhichyouwantusethisLDAPlogin.
standalone-teiid.xml
<subsystemxmlns="urn:jboss:domain:security:1.1">
<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>
LoginModules
712
![Page 713: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/713.jpg)
Note IfusingSSLtotheLDAPserver,ensurethattheCorporateCACertificateisaddedtotheJREtruststore.
Note SometimesroleinformationisDN,thenyouwillrequiretheproperty"parseRoleNameFromDN=true".
DatabaseLoginModule
ForinformationtoconfigureaDatabasebasedloginmoduleconsultEAPdocumentation
CertLoginModule
FormorecompleteinformationtoconfigureaCertificatebasedloginmoduleconsultEAPdocumentation
RoleMappingLoginModule
IftheLoginModuleyouareusingexposesrolenamesthatyouwishtomaptomoreapplicationspecificnames,thenyoucanusetheRoleMappingLoginModule.Thisusesapropertiesfiletoinjectadditionalrolenames,andoptionallyreplacetheexistingrole,onauthenticatedsubjects.
standalone-teiid.xml
<subsystemxmlns="urn:jboss:domain:security:1.1">
<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
713
![Page 714: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/714.jpg)
TeiidServerTransportSecurityTherearetwotypesofremotetransports,eachwithit’sownencryptionconfiguration:
"teiid"-Defaultstoonlyencryptlogintraffic,inwhichnoneoftheotherconfigurationpropertiesareused.
"pg"-DefaultstonoSSL
Warning ThepgtransportforODBCaccessdefaultstocleartextusernamepasswordauthentication.Youshouldconsiderusingasecuritydomainthatutilizesnon-plaintextpasswords,kerberos,orSSL.
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.
TeiidServerTransportSecurity
714
![Page 715: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/715.jpg)
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.
TeiidServerTransportSecurity
715
![Page 716: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/716.jpg)
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-
password,value=redhat)
/subsystem=teiid/transport=jdbc:write-attribute(name=truststore-name,value=ssl-
example.truststore)
/subsystem=teiid/transport=jdbc:write-attribute(name=truststore-
password,value=redhat)
NoteIfyoudonotliketoleavecleartextpasswordsintheconfigurationfile,thenyoucanuseWildFlyvaultmechanismforstoringthekeystoreandtruststorepasswords.Usethedirectionsdefinedherehttps://community.jboss.org/docs/DOC-17248
EncryptionStrengthBothanonymousSSLandloginonly(JDBCspecific)encryptionareconfiguredtouse128bitAESencryptionbydefault.Bydefault1-wayand2-waySSLallowforciphersuitenegotiationbaseduponthedefaultciphersuitessupportedbytherespectiveJavaplatformsoftheclientandserver.Userscanrestricttheciphersuitesusedbyspecifyingtheenabled-cipher-suitespropertyaboveintheSSLconfiguration.
Examples
TeiidServerTransportSecurity
716
![Page 717: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/717.jpg)
1-waysslauthenticationmode
TeiidServerTransportSecurity
717
![Page 718: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/718.jpg)
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.
JDBC/ODBCSSLconnectionusingself-signedSSLcertificates
718
![Page 719: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/719.jpg)
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">
JDBC/ODBCSSLconnectionusingself-signedSSLcertificates
719
![Page 720: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/720.jpg)
<sslmode="enabled"authentication-mode="1-way">
<keystorename="/path/to/rootCA.keystore"password="changeme"type="JKS"/>
<!--uncommentandconfigurefor2-wayauthentication
<truststorename="/path/to/rootCA.keystore"password="changeme"/>
-->
</ssl>
</transport>
<transportname="odbc"socket-binding="teiid-odbc"protocol="pg">
<authenticationsecurity-domain="teiid-security"/>
<sslmode="enabled"authentication-mode="1-way">
<keystorename="/path/to/rootCA.keystore"password="changeme"type="JKS"/>
<!--uncommentandconfigurefor2-wayauthentication
<truststorename="/path/to/rootCA.keystore"password="changeme"/>
-->
</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.
JDBC/ODBCSSLconnectionusingself-signedSSLcertificates
720
![Page 721: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/721.jpg)
ConfiguringODBCclienttouseSSL(Windows)
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.
JDBC/ODBCSSLconnectionusingself-signedSSLcertificates
721
![Page 722: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/722.jpg)
SecurityattheDataSourceLevel
Insomeusecases,theusermightneedtopass-indifferentcredentialstotheirdatasourcesbasedontheloggedinuserratherthanusingthesharedcredentialsforalltheloggedusers.Tosupportthisfeature,WildFlyandTeiidprovidemultipledifferentloginmodulestobeusedinconjunctionwithTeiid’smainsecuritydomain.Seethisdocumentfordetailsonconfiguration.Notethatthebelowdirectionsneedtobeusedinconjunctionwiththisdocument.
CallerIdentity
Ifclientwantstopassinsimpletextpasswordoracertificateoracustomserializedobjectastokencredentialtothedatasource,usercanconfigure"CallerIdentity"loginmodule.Usingthisloginmodule,usercanpass-insamecredentialthatuserloggedintoTeiidsecuritydomaintothedatasource.Hereisasampleconfiguration:
standalone-teiid.xml
<subsystemxmlns="urn:jboss:domain:security:1.1">
<security-domains>
<security-domainname="my-security-domain">
<authentication>
<login-modulecode="RealmDirect"flag="required">
<module-optionname="password-stacking"value="useFirstPass"/>
</login-module>
<login-modulecode="org.picketbox.datasource.security.CallerIdentityLoginModule"flag="required"
>
<module-optionname="password-stacking"value="useFirstPass"/>
</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
722
![Page 723: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/723.jpg)
<archive>teiid-connector-ldap.rar</archive>
<transaction-support>NoTransaction</transaction-support>
<connection-definitions>
<connection-definitionclass-name="org.teiid.resource.adapter.ldap.LDAPManagedConnectionFactory"
jndi-name="java:/ldapDS"
enabled="true"
use-java-context="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>
</connection-definition>
</connection-definitions>
</resource-adapter>
Intheaboveconfigurationexample,intheprimaryloginmodule“UsersRoles”issetuptoholdthepasswordsinthefile,andwhenuserlogsinwithpassword,thesameuseridandpasswordwillbealsosetontheloggedinSubjectafterauthentication.ThesecredentialscanbeextractedbythedatasourcebyaskingforSubject’sprivatecredentials.
PleasenotethatencodinganddecodingofthisobjectisstrictlyuptotheuserasWildFlyandTeiidwillonlyactasacarrieroftheinformationfromloginmoduletoconnectionfactory.UsingthisCallerIdentitymodule,theconnectionpoolfordatasourceissegmentedbySubject.
PassThroughIdentityThisoneissimilartoCallerIdentityloginmodule,wherethecallinguser’scredentialsandrolesarepassedasis.Thisisespeciallyusefulwhendealingwithnon-textbasedcredentialswhereyouwanttopassdownthepayloadasis.TheexampleiswhenkerberosloginisusedtheloggedinsubjectcontainsGSSCredentialobjectthatcontainstheGSStoken.
standalone-teiid.xml
<subsystemxmlns="urn:jboss:domain:security:1.1">
<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
723
![Page 724: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/724.jpg)
<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"/>
OAuthAuthenticationSecuredRestserviceswithOAuthauthenticationcanbeusedinTeiid,howeverthedatasourcesneedtobeconfiguredwithOAuthRefreshTokenorJsonWebToken(JWT)basedsecuritydomains.
RefreshToken
InordertouseOAuth,oneneedtocreateapplicationinvendorswebservice.AconnectedapplicationisdifferentfordifferentvendorslikeGoogle,LinkedIn,SalesForceetc.Fordetailsaboutcreatinganapplicationconsultvendor’sdocumentation.Onceyouhavecreatedconnectedapplication,thenrunteiid-oauth-util.shin"<eap>/bin"directory,useclient_id,client_pass,andcallbackfromsourcespecificconnectedapplication.Thisscriptwillprovidethenecessaryvaluestoplug-inbelowCLIscript.
createasecurity-domainbyexecutingCLI
/subsystem=security/security-domain=oauth2-security:add(cache-type=default)
/subsystem=security/security-domain=oauth2-security/authentication=classic:add
/subsystem=security/security-domain=oauth2-security/authentication=classic/login-module=oauth:add(code=org.teii
d.jboss.oauth.OAuth20LoginModule,flag=required,module=org.jboss.teiid.security,
module-options=[client-id=xxxx,client-secret=xxxx,refresh-token=xxxx,
access-token-uri=https://login.salesforce.com/services/oauth2/token])
reload
thiswillgeneratefollowingXMLinthestandalone.xmlordomain.xml(thiscanalsobedirectlyaddedtothestandalone.xmlordomain.xmlfilesinsteadofexecutingtheCLI)
standalone.xml
<security-domainname="oauth2-security">
<authentication>
<login-modulecode="org.teiid.jboss.oauth.OAuth20LoginModule"flag="required"module="org.jboss.teiid.s
ecurity">
<module-optionname="client-id"value="xxxx"/>
<module-optionname="client-secret"value="xxxx"/>
<module-optionname="refresh-token"value="xxxx"/>
<module-optionname="access-token-uri"value="https://login.salesforce.com/services/oauth2/token"/>
</login-module>
</authentication>
</security-domain>
JSONWebToken(JWT)
DataSourceSecurity
724
![Page 725: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/725.jpg)
InordertouseOAuth,oneneedtocreateapplicationinvendorswebservice.AconnectedapplicationisdifferentfordifferentvendorslikeGoogle,LinkedIn,SalesForceetc.Fordetailsaboutcreatinganapplicationconsultvendor’sdocumentation.OnceyouhavecreatedconnectedapplicationthatusestheJWT,gatherthebelowinformationclient-id,client-secret,access-token-uri,jwt-audience,jwt-subject,keystore-type,keystore-password,keystore-url,certificate-alias,signature-algorithm-nameandprovideinthebelowCLI.(onlytestedwithSalesForce)
/subsystem=security/security-domain=oauth2-jwt-security:add(cache-type=default)
/subsystem=security/security-domain=oauth2-jwt-security/authentication=classic:add
/subsystem=security/security-domain=oauth2-jwt-security/authentication=classic/login-module=oauth:add(code=org.
teiid.jboss.oauth.OAuth20LoginModule,flag=required,module=org.jboss.teiid.security,
module-options=[client-id=xxxx,client-secret=xxxx,access-token-uri=https://login.salesforce.com/services/o
auth2/token,jwt-audience=https://login.salesforce.com,[email protected],
keystore-type=JKS,keystore-password=changeme,keystore-url=${jboss.server.config.dir}/salesforce.jks,cert
ificate-alias=teiidtest,signature-algorithm-name=SHA256withRSA])
reload
thiswillgeneratefollowingXMLinthestandalone.xmlordomain.xml(thiscanalsobedirectlyaddedtothestandalone.xmlordomain.xmlfilesinsteadofexecutingtheCLI)
standalone.xml
<security-domainname="oauth2-jwt-security">
<authentication>
<login-modulecode="org.teiid.jboss.oauth.JWTBearerTokenLoginModule"flag="required"module="org.jboss.
teiid.security">
<module-optionname="client-id"value="xxxxx"/>
<module-optionname="client-secret"value="xxxx"/>
<module-optionname="access-token-uri"value="https://login.salesforce.com/services/oauth2/token"/>
<module-optionname="jwt-audience"value="https://login.salesforce.com"/>
<module-optionname="jwt-subject"value="[email protected]"/>
<module-optionname="keystore-type"value="JKS"/>
<module-optionname="keystore-password"value="changeme"/>
<module-optionname="keystore-url"value="${jboss.server.config.dir}/salesforce.jks"/>
<module-optionname="certificate-alias"value="teiidtest"/>
<module-optionname="signature-algorithm-name"value="SHA256withRSA"/>
</login-module>
</authentication>
</security-domain>
Kerberos
Kerberoscanalsousedasdatasourcesecurity.ThebelowconfigurationistoconfigureastaticKerberosticketatdatasource.PleasenotethatKerberoscanbeusedwithRDBMS,RESTwebservices.
/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.
standalone.xml
<security-domainname="host">
<authentication>
<login-modulecode="Kerberos"flag="required">
<module-optionname="storeKey"value="true"/>
<module-optionname="useKeyTab"value="true"/>
DataSourceSecurity
725
![Page 726: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/726.jpg)
<module-optionname="principal"value="host/testserver@MY_REALM"/>
<module-optionname="keyTab"value="/path/to/service.keytab"/>
<module-optionname="doNotPrompt"value="true"/>
<module-optionname="debug"value="false"/>
<module-optionname="refreshKrb5Config"value="true"/>
</login-module>
</authentication>
</security-domain>
Kerberospassthrough
ForusingthesamekerberostokenatTeiidandaswellasatthedatasourcelevel,thetokennegotiatedattheTeiidenginecanbepassedintodatasource.Datasourceexplicitlyneedstoprovidethissupport.MajordatabasevendorslikeOracle,MS-SQLServer,DB2,HIVE,Impalasupportkerberos.Somealsosupportpassthroughmode.ToMakepass-throughwork,followthedirectionsheretosetuptheKerberosatTeiidenginelevel[KerberossupportthroughGSSAPI]thenfordatasourcelevelcreatethe[#PassThroughIdentity]
TranslatorCustomizationTeiid’sextensibleTranslatorframeworkalsoprovideshooksforsecuringaccessattheDataSourcelevel.TheExecutionFactory.getConnectionmaybeoverriddentoinitializethesourceconnectioninanynumberofways,suchasre-authentication,basedupontheTeiidSubject,executionpayload,sessionvariables,andanyoftheotherrelevantinformationaccessibleviatheExecutionContextandtheCommandContext.YoumayevenalsomodifythegeneratedsourceSQLinanywaythatisseenfitintherelevantExecution.
DataSourceSecurity
726
![Page 727: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/727.jpg)
KerberossupportthroughGSSAPI
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.
standalone-teiid.xml
<security-domainname="host">
<authentication>
<login-modulecode="Kerberos"flag="required">
<module-optionname="storeKey"value="true"/>
<module-optionname="useKeyTab"value="true"/>
<module-optionname="principal"value="host/testserver@MY_REALM"/><!--serviceprincipal-->
<module-optionname="keyTab"value="/path/to/service.keytab"/>
<module-optionname="doNotPrompt"value="true"/>
<module-optionname="debug"value="false"/>
<module-optionname="refreshKrb5Config"value="true"/>
</login-module>
</authentication>
</security-domain>
ConfiguresecuritydomaintosecuretheTeiidapplication.
KerberossupportthroughGSSAPI
727
![Page 728: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/728.jpg)
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
standalone-teiid.xml
<security-domainname="MY_REALM">
<authentication>
<!--Checktheusernameandpassword-->
<login-modulecode="SPNEGO"flag="requisite">
<module-optionname="password-stacking"value="useFirstPass"/>
<module-optionname="serverSecurityDomain"value="host"/>
</login-module>
<!--Searchforroles-->
<login-modulecode="UserRoles"flag="requisite">
<module-optionname="password-stacking"value="useFirstPass"/>
<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"
standalone-teiid.xml
<security-domainname="MY_REALM">
<authentication>
<!--Checktheusernameandpassword-->
<login-modulecode="SPNEGO"flag="requisite">
<module-optionname="password-stacking"value="useFirstPass"/>
<module-optionname="serverSecurityDomain"value="host"/>
<module-optionname="usernamePasswordDomain"value="app-fallback"/>
KerberossupportthroughGSSAPI
728
![Page 729: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/729.jpg)
</login-module>
<!--Searchforroles-->
<login-modulecode="UserRoles"flag="requisite">
<module-optionname="password-stacking"value="useFirstPass"/>
<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"
KerberossupportthroughGSSAPI
729
![Page 730: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/730.jpg)
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="security-domain"value="MY_REALM"/>
<propertyname="gss-pattern"value="logasgss"/>
andifyoupassedthe"user=logasgss"intheconnectionstring,thenGSSauthenticationisselectedasloginauthenticationmechanism.Iftheusernamedoesnotmatch,thendefaulttransport’sauthenticationmethodisselected.Alternatively,ifyouwantchooseUSERPASSWORD
<propertyname="security-domain"value="MY_REALM"/>
<propertyname="password-pattern"value="*-simple"/>
andiftheusernameislike"mike-simple",thenthatuserwillbesubjectedtoauthenticateagainstUSERPASSWORDbasedauthenticationdomain.Youcanconfiguredifferentsecurity-domainsfordifferentVDBS.VDBauthenticationwillnolongerbedependentuponunderlyingtransport.Ifyoulikeforce"GSS"allthetimethenuseconfigurationlikebelow
<propertyname="security-domain"value="MY_REALM"/>
<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"
KerberossupportthroughGSSAPI
730
![Page 731: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/731.jpg)
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
KerberossupportthroughGSSAPI
731
![Page 732: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/732.jpg)
-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
KerberossupportthroughGSSAPI
732
![Page 733: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/733.jpg)
{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
KerberossupportthroughGSSAPI
733
![Page 734: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/734.jpg)
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>
<groupId>org.jboss.teiid</groupId>
<artifactId>teiid-api</artifactId>
<scope>provided</scope>
</dependency>
<dependency>
<groupId>org.jboss.teiid</groupId>
<artifactId>teiid-common-core</artifactId>
<scope>provided</scope>
</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
<?xmlversion="1.0"encoding="UTF-8"?>
<modulexmlns="urn:jboss:module:1.0"name="org.jboss.teiid.auth">
<resources>
<resource-rootpath="my_custom_policy.jar"/>
<!--addanyotherdependentjarshere,iftheyarenotdefinedasmodules-->
</resources>
<dependencies>
<modulename="org.jboss.teiid.common-core"/>
<modulename="org.jboss.teiid.api"/>
<modulename="javax.api"/>
</dependencies>
</module>
createfolderinthe"<jboss-as>/modules/org/jboss/teiid/auth/main",copytheabovemodule.xmlfilealongwithallthejarfiles.Thisdirectorycanbedifferentifyouchoose,justmakesurethenameofthemoduleandthedirectorynamematch.
CustomAuthorizationValidator
734
![Page 735: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/735.jpg)
Afterthemodulehasbeenadded,changetheconfiguration.Editeitherthestandalone-teiid.xmlortedomain-teiid.xmlfile,andinthe"teiid"subsystemxmlfragmentaddthefollowingxmlwiththemodulenamecreated.
<policy-decider-module>name</policy-decider-module>
thenrestartthesystem.APolicyDecidermaybeconsultedmanytimesforasingleusercommand,butitisonlycalledtomakedecisionsbaseduponresourcesthatappearinuserqueries.Anyfurtheraccessofresourcesthroughviewsorstoredprocedures,justaswithdataroles,isnotcheckedagainstaPolicyDecider.
CustomAuthorizationValidator
735
![Page 736: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/736.jpg)
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)
/subsystem=security/security-domain=teiid-security/authentication=classic/login-
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">
<module-optionname="password-stacking"value="useFirstPass"/>
SAMLBasedSecurityForOData
736
![Page 737: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/737.jpg)
</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"
<?xmlversion="1.0"encoding="UTF-8"?>
<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">
SAMLBasedSecurityForOData
737
![Page 738: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/738.jpg)
<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"
<?xmlversion="1.0"encoding="UTF-8"?>
<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"
Location="http://localhost:8080/idp-metadata/"/>
<SingleSignOnService
Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect"
Location="http://localhost:8080/idp-metadata/"/>
<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
/"
SAMLBasedSecurityForOData
738
![Page 739: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/739.jpg)
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
SAMLBasedSecurityForOData
739
![Page 740: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/740.jpg)
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.
OAuth2BasedSecurityForODataUsingKeyCloak
740
![Page 741: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/741.jpg)
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.
OAuth2BasedSecurityForODataUsingKeyCloak
741
![Page 742: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/742.jpg)
Addanotherclientcalled"database-service"andchoosescope"user".Choosetypeas"Bearer".
InstallandconfigureTeiidserver
DownloadandinstallTeiidserver
DownloadKeycloakadapterfortheEAP,andunzipovertheTeiidserverinstallation
DownloadKeycloakSAMLadapterforEAP,andunzipovertheTeiidserverinstallation.(optionalbutneedforanotherexercise)
Editthestandalone-teiid.xml,addthefollowingsections
RunthefollowingCLItoaddKeycloakspecificmodulestotheserver
OAuth2BasedSecurityForODataUsingKeyCloak
742
![Page 743: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/743.jpg)
/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
abovecommandswillresultinXMLinstandalone.xmlordomain.xmlfilelike
<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)
OAuth2BasedSecurityForODataUsingKeyCloak
743
![Page 744: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/744.jpg)
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
Replacethe<wildfly>/modules/system/layers/dv/org/jboss/teiid/main/deployments/teiid-olingo-odata4.war"filewithnewWARfile,byexecutingacommandsimilarto
{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
IfyouareworkingwithJDV6.3serverorgreater,thenrunthefollowingCLIscript,youmayhavechangethebelowscripttoadopttothecorrectversionoftheWARanddirectorynameswherethecontentislocated.
undeployteiid-olingo-odata4.war
deployteiid-web-security/odata-oauth-keycloak/target/teiid-odata-oauth-keycloak-
{version}.war
oroverlaythenewoneusingCLIscriptlike
OAuth2BasedSecurityForODataUsingKeyCloak
744
![Page 745: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/745.jpg)
deployment-overlayadd--name=myOverlay--content=/WEB-INF/web.xml=teiid-web-
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">
<moduleslot="main"id="org.jboss.teiid.resource-adapter.webservice"/>
<transaction-support>NoTransaction</transaction-support>
<connection-definitions>
<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>
<config-propertyname="EndPoint">
http://localhost:8180/database/
</config-property>
<security>
<security-domain>oauth</security-domain>
</security>
</connection-definition>
</connection-definitions>
</resource-adapter>
AddaVDBwithfollowingcontents(oauthdemo-vdb.xml)
<vdbname="oauthdemo"version="1">
<modelvisible="true"name="PM1">
<sourcename="array"translator-name="loopback"/>
<metadatatype="DDL"><![CDATA[
CREATEFOREIGNTABLEG1(e1integerPRIMARYKEY,e2varchar(25),e3double);
]]>
</metadata>
</model>
<modelname="view"type="VIRTUAL">
<metadatatype="DDL"><![CDATA[
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>
OAuth2BasedSecurityForODataUsingKeyCloak
745
![Page 746: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/746.jpg)
<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>
OAuth2BasedSecurityForODataUsingKeyCloak
746
![Page 747: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/747.jpg)
<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]
OAuth2BasedSecurityForODataUsingKeyCloak
747
![Page 748: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/748.jpg)
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.
SAMLBasedSecurityForODataUsingKeyCloak
748
![Page 749: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/749.jpg)
Addanewclientcalled"odata4-saml",thisclientrepresentstheTeiid’sSAMLclientthatwearegoingtocreate
ClickonSAMLKeys,eitherimportyourcertificateorgenerateanewone.Thenclickexport,andkeeptheexportedcertificateforlateruse.
SAMLBasedSecurityForODataUsingKeyCloak
749
![Page 750: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/750.jpg)
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)
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
abovecommandswillresultinXMLinstandalone.xmlordomain.xmlfilelike
<subsystemxmlns="urn:jboss:domain:keycloak-saml:1.1"/>
<subsystemxmlns="urn:jboss:domain:keycloak:1.1"/>
SAMLBasedSecurityForODataUsingKeyCloak
750
![Page 751: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/751.jpg)
Insecurity-domainsaddfollowingloginmoduleusingthefollowingCLI
subsystem=security/security-domain=teiid-security/authentication=classic/login-
module=RealmDirect:write-attribute(name=flag,value=sufficient)
/subsystem=security/security-domain=teiid-security/authentication=classic/login-
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">
<module-optionname="password-stacking"value="useFirstPass"/>
</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
SAMLBasedSecurityForODataUsingKeyCloak
751
![Page 752: Table of Contents - GitHub Pagesteiid.github.io/teiid-documents/9.1.x/teiid-documents.pdf · 2020-04-08 · JDBC Support Connecting to a Teiid Server Driver Connection DataSource](https://reader030.vdocument.in/reader030/viewer/2022041001/5ea1de7cf16d455ee014e4d9/html5/thumbnails/752.jpg)
CommunityTeiidServeronWildfly
Replacethe<wildfly>/modules/system/layers/dv/org/jboss/teiid/main/deployments/teiid-olingo-odata4.war"filewithnewWARfile,byexecutingacommandsimilarto
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
IfyouareworkingwithJDV6.3serverorgreater,thenrunthefollowingCLIscript,youmayhavechangethebelowscripttoadopttothecorrectversionoftheWARanddirectorynameswherethecontentislocated.
undeployteiid-olingo-odata4.war
deployteiid-web-security/teiid-odata-saml-keycloak/target/teiid-odata-saml-
keycloak-{version}.war
oroverlaythenewoneusingCLIscriptlike
deployment-overlayadd--name=myOverlay--content=/WEB-INF/web.xml=teiid-web-
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>
SAMLBasedSecurityForODataUsingKeyCloak
752