Red Hat Training

A Red Hat training course is available for Red Hat JBoss Data Virtualization

3.4. Scalar Functions

3.4.1. Scalar Functions

JBoss Data Virtualization provides an extensive set of built-in scalar functions. See Section 3.1, “SQL Support” and Section 4.1, “Supported Types”.
In addition, JBoss Data Virtualization provides the capability for user defined functions or UDFs. See Red Hat JBoss Development Guide: Server Development for adding UDFs. Once added, UDFs may be called like any other function.

3.4.2. Numeric Functions

Numeric functions return numeric values (integer, long, float, double, biginteger, bigdecimal). They generally take numeric values as inputs, though some take strings.

Table 3.1. Numeric Functions

Function
Definition
Data Type Constraint
+ - * /
Standard numeric operators
x in {integer, long, float, double, biginteger, bigdecimal}, return type is same as x

Note

The precision and scale of non-bigdecimal arithmetic function functions results matches that of Java. The results of bigdecimal operations match Java, except for division, which uses a preferred scale of max(16, dividend.scale + divisor.precision + 1), which then has trailing zeros removed by setting the scale to max(dividend.scale, normalized scale).
ABS(x)
Absolute value of x
See standard numeric operators above
ACOS(x)
Arc cosine of x
x in {double, bigdecimal}, return type is double
ASIN(x)
Arc sine of x
x in {double, bigdecimal}, return type is double
ATAN(x)
Arc tangent of x
x in {double, bigdecimal}, return type is double
ATAN2(x,y)
Arc tangent of x and y
x, y in {double, bigdecimal}, return type is double
CEILING(x)
Ceiling of x
x in {double, float}, return type is double
COS(x)
Cosine of x
x in {double, bigdecimal}, return type is double
COT(x)
Cotangent of x
x in {double, bigdecimal}, return type is double
DEGREES(x)
Convert x degrees to radians
x in {double, bigdecimal}, return type is double
EXP(x)
e^x
x in {double, float}, return type is double
FLOOR(x)
Floor of x
x in {double, float}, return type is double
FORMATBIGDECIMAL(x, y)
Formats x using format y
x is bigdecimal, y is string, returns string
FORMATBIGINTEGER(x, y)
Formats x using format y
x is biginteger, y is string, returns string
FORMATDOUBLE(x, y)
Formats x using format y
x is double, y is string, returns string
FORMATFLOAT(x, y)
Formats x using format y
x is float, y is string, returns string
FORMATINTEGER(x, y)
Formats x using format y
x is integer, y is string, returns string
FORMATLONG(x, y)
Formats x using format y
x is long, y is string, returns string
LOG(x)
Natural log of x (base e)
x in {double, float}, return type is double
LOG10(x)
Log of x (base 10)
x in {double, float}, return type is double
MOD(x, y)
Modulus (remainder of x / y)
x in {integer, long, float, double, biginteger, bigdecimal}, return type is same as x
PARSEBIGDECIMAL(x, y)
Parses x using format y
x, y are strings, returns bigdecimal
PARSEBIGINTEGER(x, y)
Parses x using format y
x, y are strings, returns biginteger
PARSEDOUBLE(x, y)
Parses x using format y
x, y are strings, returns double
PARSEFLOAT(x, y)
Parses x using format y
x, y are strings, returns float
PARSEINTEGER(x, y)
Parses x using format y
x, y are strings, returns integer
PARSELONG(x, y)
Parses x using format y
x, y are strings, returns long
PI()
Value of Pi
return is double
POWER(x,y)
x to the y power
x in {double, bigdecimal, biginteger}, return is the same type as x
RADIANS(x)
Convert x radians to degrees
x in {double, bigdecimal}, return type is double
RAND()
Returns a random number, using generator established so far in the query or initializing with system clock if necessary.
Returns double.
RAND(x)
Returns a random number, using new generator seeded with x.
x is integer, returns double.
ROUND(x,y)
Round x to y places; negative values of y indicate places to the left of the decimal point
x in {integer, float, double, bigdecimal} y is integer, return is same type as x
SIGN(x)
1 if x > 0, 0 if x = 0, -1 if x < 0
x in {integer, long, float, double, biginteger, bigdecimal}, return type is integer
SIN(x)
Sine value of x
x in {double, bigdecimal}, return type is double
SQRT(x)
Square root of x
x in {long, double, bigdecimal}, return type is double
TAN(x)
Tangent of x
x in {double, bigdecimal}, return type is double
BITAND(x, y)
Bitwise AND of x and y
x, y in {integer}, return type is integer
BITOR(x, y)
Bitwise OR of x and y
x, y in {integer}, return type is integer
BITXOR(x, y)
Bitwise XOR of x and y
x, y in {integer}, return type is integer
BITNOT(x)
Bitwise NOT of x
x in {integer}, return type is integer

3.4.3. Parsing Numeric Data Types from Strings

JBoss Data Virtualization provides a set of functions to parse formatted strings as various numeric data types:
  • parseDouble - parses a string as a double
  • parseFloat - parses a string as a float
  • parseLong - parses a string as a long
  • parseInteger - parses a string as an integer
For each function, you have to provide the formatting of the string. The formatting follows the convention established by the java.text.DecimalFormat class. See examples below.
Input String
Function Call to Format String
Output Value
Output Data Type
'$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

3.4.4. Formatting Numeric Data Types as Strings

JBoss Data Virtualization provides a set of functions to convert numeric data types into formatted strings:
  • formatDouble - formats a double as a string
  • formatFloat - formats a float as a string
  • formatLong - formats a long as a string
  • formatInteger - formats an integer as a string
For each function, you have to provide the formatting of the string. The formatting follows the convention established by the java.text.DecimalFormat class. See examples below.
Input Value
Input Data Type
Function Call to Format String
Output String
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'

3.4.5. String Functions

String functions generally take strings as inputs and return strings as outputs.
Unless specified, all of the arguments and return types in the following table are strings and all indexes are one-based. The zero index is considered to be before the start of the string.

Important

Non-ASCII range characters or integers used by ASCII(x), CHR(x), and CHAR(x) may produce different results or exceptions depending on where the function is evaluated (JBoss Data Virtualization vs. source). JBoss Data Virtualization uses Java default int to char and char to int conversions, which operates over UTF16 values.

Table 3.2. String Functions

Function
Definition
DataType Constraint
x || y
Concatenation operator
x,y in {string}, return type is string
ASCII(x)
Provide ASCII value of the left most character in x. The empty string will return null.
return type is integer
CHR(x) CHAR(x)
Provide the character for ASCII value x
x in {integer}
CONCAT(x, y)
Concatenates x and y with ANSI semantics. If x and/or y is null, returns null.
x, y in {string}
CONCAT2(x, y)
Concatenates x and y with non-ANSI null semantics. If x and y is null, returns null. If only x or y is null, returns the other value.
x, y in {string}
ENDSWITH(x, y)
Checks if y ends with x. If only x or y is null, returns null.
x, y in {string}, returns boolean
INITCAP(x)
Make first letter of each word in string x capital and all others lowercase
x in {string}
INSERT(str1, start, length, str2)
Insert string2 into string1
str1 in {string}, start in {integer}, length in {integer}, str2 in {string}
LCASE(x)
Lowercase of x
x in {string}
LEFT(x, y)
Get left y characters of x
x in {string}, y in {integer}, return string
LENGTH(x)
Length of x
return type is integer
LOCATE(x, y)
Find position of x in y starting at beginning of y
x in {string}, y in {string}, return integer
LOCATE(x, y, z)
Find position of x in y starting at z
x in {string}, y in {string}, z in {integer}, return integer
LPAD(x, y)
Pad input string x with spaces on the left to the length of y
x in {string}, y in {integer}, return string
LPAD(x, y, z)
Pad input string x on the left to the length of y using character z
x in {string}, y in {string}, z in {character}, return string
LTRIM(x)
Left trim x of blank characters
x in {string}, return string
QUERYSTRING(path [, expr [AS name] ...])
Returns a properly encoded query string appended to the given path. Null valued expressions are omitted, and a null path is treated as ''.
Names are optional for column reference expressions.
e.g. QUERYSTRING('path', 'value' as "&x", ' & ' as y, null as z) returns 'path?%26x=value&y=%20%26%20'
path, expr in {string}. name is an identifier
REPEAT(str1,instances)
Repeat string1 a specified number of times
str1 in {string}, instances in {integer} return string
REPLACE(x, y, z)
Replace all y in x with z
x,y,z in {string}, return string
RIGHT(x, y)
Get right y characters of x
x in {string}, y in {integer}, return string
RPAD(input string x, pad length y)
Pad input string x with spaces on the right to the length of y
x in {string}, y in {integer}, return string
RPAD(x, y, z)
Pad input string x on the right to the length of y using character z
x in {string}, y in {string}, z in {character}, return string
RTRIM(x)
Right trim x of blank characters
x is string, return string
SPACE(x)
Repeats space x times
x in {integer}
SUBSTRING(x, y)
SUBSTRING(x FROM y)
Get substring from x, from position y to the end of x
y in {integer}
SUBSTRING(x, y, z)
SUBSTRING(x FROM y FOR z)
Get substring from x from position y with length z
y, z in {integer}
TO_CHARS(x, encoding)
Return a CLOB from the BLOB with the given encoding. BASE64, HEX, and the built-in Java Charset names are valid values for the encoding.

Note

For charsets, unmappable chars will be replaced with the charset default character. Binary formats, such as BASE64, will error in their conversion to bytes if an unrecognizable character is encountered.
x is a BLOB, encoding is a string, and returns a CLOB
TO_BYTES(x, encoding)
Return a BLOB from the CLOB with the given encoding. BASE64, HEX, and the builtin Java Charset names are valid values for the encoding.
x in a CLOB, encoding is a string, and returns a BLOB
TRANSLATE(x, y, z)
Translate string x by replacing each character in y with the character in z at the same position.
Note that the second arg (y) and the third arg (z) must be the same length. If they are not equal, Red Hat JBoss data Virtualization throws this exception: 'TEIID30404 Source and destination character lists must be the same length.'
x in {string}
TRIM([[LEADING|TRAILING|BOTH] [x] FROM] y)
Trim character x from the leading, trailing, or both ends of string y. If LEADING/TRAILING/BOTH is not specified, BOTH is used by default. If no trim character x is specified, a blank space ' ' is used for x by default.
x in {character}, y in {string}
UCASE(x)
Uppercase of x
x in {string}
UNESCAPE(x)
Unescaped version of x. Possible escape sequences are \b - backspace, \t - tab, \n - line feed, \f - form feed, \r - carriage return. \uXXXX, where X is a hex value, can be used to specify any unicode character. \XXX, where X is an octal digit, can be used to specify an octal byte value. If any other character appears after an escape character, that character will appear in the output and the escape character will be ignored.
x in {string}

3.4.6. Date/Time Functions

Date and time functions return or operate on dates, times, or timestamps.
Parse and format Date/Time functions use the convention established within the java.text.SimpleDateFormat class to define the formats you can use with these functions.

Table 3.3. Date and Time Functions

Function
Definition
Datatype Constraint
CURDATE()
Return current date
returns date
CURTIME()
Return current time
returns time
NOW()
Return current timestamp (date and time)
returns timestamp
DAYNAME(x)
Return name of day in the default locale
x in {date, timestamp}, returns string
DAYOFMONTH(x)
Return day of month
x in {date, timestamp}, returns integer
DAYOFWEEK(x)
Return day of week (Sunday=1, Saturday=7)
x in {date, timestamp}, returns integer
DAYOFYEAR(x)
Return day number
x in {date, timestamp}, returns integer
EXTRACT(YEAR|MONTH|DAY|HOUR|MINUTE|SECOND FROM x)
Return the given field value from the date value x. Produces the same result as the associated YEAR, MONTH, DAYOFMONTH, HOUR, MINUTE, SECOND functions.
The SQL specification also allows for TIMEZONE_HOUR and TIMEZONE_MINUTE as extraction targets. In JBoss Data Virtualization, all date values are in the timezone of the server.
x in {date, time, timestamp}, returns integer
FORMATDATE(x, y)
Format date x using format y
x is date, y is string, returns string
FORMATTIME(x, y)
Format time x using format y
x is time, y is string, returns string
FORMATTIMESTAMP(x, y)
Format timestamp x using format y
x is timestamp, y is string, returns string
FROM_UNIXTIME (unix_timestamp)
Return the Unix timestamp (in seconds) as a Timestamp value
Unix timestamp (in seconds)
HOUR(x)
Return hour (in military 24-hour format)
x in {time, timestamp}, returns integer
MINUTE(x)
Return minute
x in {time, timestamp}, returns integer
MODIFYTIMEZONE (timestamp, startTimeZone, endTimeZone)
Returns a timestamp based upon the incoming timestamp adjusted for the differential between the start and end time zones.  i.e. if the server is in GMT-6, then modifytimezone({ts '2006-01-10 04:00:00.0'},'GMT-7', 'GMT-8') will return the timestamp {ts '2006-01-10 05:00:00.0'} as read in GMT-6.  The value has been adjusted 1 hour ahead to compensate for the difference between GMT-7 and GMT-8.
startTimeZone and endTimeZone are strings, returns a timestamp
MODIFYTIMEZONE (timestamp, endTimeZone)
Return a timestamp in the same manner as modifytimezone(timestamp, startTimeZone, endTimeZone), but will assume that the startTimeZone is the same as the server process.
Timestamp is a timestamp; endTimeZone is a string, returns a timestamp
MONTH(x)
Return month
x in {date, timestamp}, returns integer
MONTHNAME(x)
Return name of month in the default locale
x in {date, timestamp}, returns string
PARSEDATE(x, y)
Parse date from x using format y
x, y in {string}, returns date
PARSETIME(x, y)
Parse time from x using format y
x, y in {string}, returns time
PARSETIMESTAMP(x,y)
Parse timestamp from x using format y
x, y in {string}, returns timestamp
QUARTER(x)
Return quarter
x in {date, timestamp}, returns integer
SECOND(x)
Return seconds
x in {time, timestamp}, returns integer
TIMESTAMPCREATE(date, time)
Create a timestamp from a date and time
date in {date}, time in {time}, returns timestamp
TIMESTAMPADD(interval, count, timestamp)
Add a specified interval (hour, day of week, month) to the timestamp, where intervals can be:
  1. SQL_TSI_FRAC_SECOND - fractional seconds (billionths of a second)
  2. SQL_TSI_SECOND - seconds
  3. SQL_TSI_MINUTE - minutes
  4. SQL_TSI_HOUR - hours
  5. SQL_TSI_DAY - days
  6. SQL_TSI_WEEK - weeks where Sunday is the first day
  7. SQL_TSI_MONTH - months
  8. SQL_TSI_QUARTER - quarters (3 months), where the first quarter is months 1-3
  9. SQL_TSI_YEAR - years

Note

The full interval amount based upon calendar fields will be added. For example adding 1 QUARTER will move the timestamp up by three full months and not just to the start of the next calendar quarter.
The interval constant may be specified either as a string literal or a constant value. Interval in {string}, count in {integer}, timestamp in {date, time, timestamp}
TIMESTAMPDIFF(interval, startTime, endTime)
Calculates the date part intervals crossed between the two timestamps. interval is one of the same keywords as those used for TIMESTAMPADD.
If (endTime > startTime), a positive number will be returned. If (endTime < startTime), a negative number will be returned. The date part difference is counted regardless of how close the timestamps are. For example, '2000-01-02 00:00:00.0' is still considered 1 hour ahead of '2000-01-01 23:59:59.999999'.

Note

TIMESTAMPDIFF typically returns an integer, however JBoss Data Virtualization returns a long. You will encounter an exception if you expect a value out of the integer range from a pushed down TIMESTAMPDIFF.

Note

The implementation of TIMESTAMPDIFF in previous versions returned values based upon the number of whole canonical interval approximations (365 days in a year, 91 days in a quarter, 30 days in a month, etc.) crossed. For example the difference in months between 2013-03-24 and 2013-04-01 was 0, but based upon the date parts crossed is 1. See the System Properties section in Red Hat JBoss Data Virtualization Administration and Configuration Guide for backwards compatibility.
Interval in {string}; startTime, endTime in {timestamp}, returns a long.
WEEK(x)
Return week in year (1-53). see also System Properties for customization.
x in {date, timestamp}, returns integer
YEAR(x)
Return four-digit year
x in {date, timestamp}, returns integer

3.4.7. Parsing Date Data Types from Strings

JBoss Data Virtualization does not implicitly convert strings that contain dates presented in different formats, such as '19970101' and '31/1/1996' to date-related data types. You can, however, use the following functions to explicitly convert strings with a different format to the appropriate data type:
  • parseDate
  • parseTime
  • parseTimestamp
For each function, you have to provide the formatting of the string. The formatting follows the convention established by the java.text.SimpleDateFormat class. See examples below.

Table 3.4. Functions to Parse Dates

String
Function Call To Parse String
'19970101'
parseDate(myDateString, 'yyyyMMdd')
'31/1/1996'
parseDate(myDateString, 'dd''/''MM''/''yyyy')
'22:08:56 CST'
parseTime (myTime, 'HH:mm:ss z')
'03.24.2003 at 06:14:32'
parseTimestamp(myTimestamp, 'MM.dd.yyyy ''at'' hh:mm:ss')

Note

Formatted strings will be based on your default Java locale.

3.4.8. Specifying Time Zones

Time zones can be specified in several formats. Common abbreviations such as EST for "Eastern Standard Time" are allowed but discouraged, as they can be ambiguous. Unambiguous time zones are defined in the form continent or ocean/largest city. For example, America/New_York, America/Buenos_Aires, or Europe/London. Additionally, you can specify a custom time zone by GMT offset: GMT[+/-]HH:MM.
For example: GMT-05:00

3.4.9. Type Conversion Functions

Within your queries, you can convert between data types using the CONVERT or CAST keyword. Also see Section 4.2, “Type Conversions”.

Table 3.5. Type Conversion Functions

Function
Definition
CONVERT(x, type)
Convert x to type, where type is a JBoss Data Virtualization Base Type
CAST(x AS type)
Convert x to type, where type is a JBoss Data Virtualization Base Type
These functions are identical other than syntax; CAST is the standard SQL syntax, CONVERT is the standard JDBC/ODBC syntax.

3.4.10. Choice Functions

Choice functions provide a way to select from two values based on some characteristic of one of the values.

Table 3.6. Type Conversion Functions

Function
Definition
Data Type Constraint
COALESCE(x,y+)
Returns the first non-null parameter
x and all y's can be any compatible types
IFNULL(x,y)
If x is null, return y; else return x
x, y, and the return type must be the same type but can be any type
NVL(x,y)
If x is null, return y; else return x
x, y, and the return type must be the same type but can be any type
NULLIF(param1, param2)
Equivalent to case when (param1 = param2) then null else param1
param1 and param2 must be compatible comparable types

Note

IFNULL and NVL are aliases of each other. They are the same function.

3.4.11. Decode Functions

Decode functions allow you to have JBoss Data Virtualization examine the contents of a column in a result set and alter, or decode, the value so that your application can better use the results.

Table 3.7. Decode Functions

Function
Definition
Data Type Constraint
DECODESTRING(x, y [, z])
Decode column x using value pairs in y (with optional delimiter, z) and return the decoded column as a set of strings.

Warning

Deprecated. Use a CASE expression instead.
All string
DECODEINTEGER(x, y [, z])
Decode column x using value pairs in y (with optional delimiter z) and return the decoded column as a set of integers.

Warning

Deprecated. Use a CASE expression instead.
All string parameters, return integer
Within each function call, you include the following arguments:
  1. x is the input value for the decode operation. This will generally be a column name.
  2. y is the literal string that contains a delimited set of input values and output values.
  3. z is an optional parameter on these methods that allows you to specify what delimiter the string specified in y uses.
For example, your application might query a table called PARTS that contains a column called IS_IN_STOCK which contains a Boolean value that you need to change into an integer for your application to process. In this case, you can use the DECODEINTEGER function to change the Boolean values to integers:
SELECT DECODEINTEGER(IS_IN_STOCK, 'false, 0, true, 1') FROM PartsSupplier.PARTS;
When JBoss Data Virtualization encounters the value false in the result set, it replaces the value with 0.
If, instead of using integers, your application requires string values, you can use the DECODESTRING function to return the string values you need:
SELECT DECODESTRING(IS_IN_STOCK, 'false, no, true, yes, null') FROM PartsSupplier.PARTS;
In addition to two input/output value pairs, this sample query provides a value to use if the column does not contain any of the preceding input values. If the row in the IS_IN_STOCK column does not contain true or false, JBoss Data Virtualization inserts a null into the result set.
When you use these DECODE functions, you can provide as many input/output value pairs as you would like within the string. By default, JBoss Data Virtualization expects a comma delimiter, but you can add a third parameter to the function call to specify a different delimiter:
SELECT DECODESTRING(IS_IN_STOCK, 'false:no:true:yes:null',':') FROM PartsSupplier.PARTS;
You can use keyword null in the DECODE string as either an input value or an output value to represent a null value. However, if you need to use the literal string null as an input or output value (which means the word null appears in the column and not a null value) you can put the word in quotes: "null".
SELECT DECODESTRING( IS_IN_STOCK, 'null,no,"null",no,nil,no,false,no,true,yes' ) FROM PartsSupplier.PARTS;
If the DECODE function does not find a matching output value in the column and you have not specified a default value, the DECODE function will return the original value JBoss Data Virtualization found in that column.

3.4.12. Lookup Function

The Lookup function provides a way to speed up access to values in a lookup table (also known as a code table or reference table). The Lookup function caches all key and return column pairs specified in the function for the given table. Subsequent lookups against the same table using the same key and return columns will use the cached values. This caching accelerates response time to queries that use the lookup tables.
In the following example, based on the lookup table, codeTable, the following function will find the row where keyColumn has the value, keyValue, and return the associated returnColumn value (or null if no matching key is found).
LOOKUP(codeTable, returnColumn, keyColumn, keyValue)
codeTable must be a string literal that is the fully qualified name of the target table. returnColumn and keyColumn must also be string literals and match corresponding column names in codeTable. keyValue can be any expression that must match the datatype of the keyColumn. The return data type matches that of returnColumn.
Consider the following example in which the ISOCountryCodes table is used to translate country names to ISO codes:
lookup('ISOCountryCodes', 'CountryCode', 'CountryName', 'UnitedStates')
CountryName represents a key column and CountryCode represents the ISO code of the country. A query to this lookup table would provide a CountryName, in this case 'UnitedStates', and expect a CountryCode in response.

Note

JBoss Data Virtualization unloads these cached lookup tables when you stop and restart JBoss Data Virtualization. Thus, it is best not to use this function for data that is subject to updates or specific to a session or user (including row based security and column masking effects). It is best used for data that does not change over time. See the Red Hat JBoss Data Virtualization Administration and Configuration Guide for more on the caching aspects of the lookup function.

Important

  • The key column must contain unique values. If the column contains duplicate values, an exception will be thrown.

3.4.13. System Functions

System functions provide access to information in JBoss Data Virtualization from within a query.
Function
Definition
Data Type Constraint
COMMANDPAYLOAD([key])
If the key parameter is provided, the command payload object is cast to a java.util.Properties object and the corresponding property value for the key is returned. If the key is not specified, the return value is the command payload toString value.
The command payload is set by the TeiidStatement.setPayload method on the Data Virtualization JDBC API extensions on a per-query basis.
key in {string}, return value is string
ENV(key)
Retrieve a system environment property.

Note

The only key specific to the current session is 'sessionid'. The preferred mechanism for getting the session id is with the session_id() function.

Note

To prevent untrusted access to system properties, this function is not enabled by default. The ENV function may be enabled via the allowEnvFunction property.
key in {string}, return value is string
SESSION_ID()
Retrieve the string form of the current session id.
return value is string
USER()
Retrieve the name of the user executing the query.
return value is string
CURRENT_DATABASE()
Retrieve the catalog name of the database which, for the VDB, is the VDB name.
return value is string
TEIID_SESSION_GET(name)
Retrieve the session variable.
A null name will return a null value. Typically you will use the a get wrapped in a CAST to convert to the desired type.
name in {string}, return value is object
TEIID_SESSION_SET(name, value)
Set the session variable.
The previous value for the key or null will be returned. A set has no effect on the current transaction and is not affected by commit/rollback.
name in {string}, value in {object}, return value is object

3.4.14. XML Functions

XML functions provide functionality for working with XML data.
	TABLE  Customer (
    CustomerId integer PRIMARY KEY,
    CustomerName varchar(25),
    ContactName varchar(25)
    Address varchar(50),
    City varchar(25),
    PostalCode varchar(25),
    Country varchar(25),                
);
use this data
CustomerID 	CustomerName 	ContactName 	Address 	City 	PostalCode 	Country
87 	Wartian Herkku 	Pirkko Koskitalo 	Torikatu 38 	Oulu 	90110 	Finland
88 	Wellington Importadora 	Paula Parente 	Rua do Mercado, 12 	Resende 	08737-363 	Brazil
89 	White Clover Markets 	Karl Jablonski 	305 - 14th Ave. S. Suite 3B 	Seattle 	98128 	USA

XMLCAST
Cast to or from XML:
XMLCAST(expression AS type)
Expression or type must be XML. The return value will be typed as type. This is the same functionality as XMLTABLE uses to convert values to the desired runtime type - with the exception that array type targets are not supported with XMLCAST.
XMLCOMMENT
XMLCOMMENT(comment)
Returns an XML comment.
comment is a string. Return value is XML.
XMLCONCAT
XMLCONCAT(content [, content]*)
Returns XML with the concatenation of the given XML types. If a value is null, it will be ignored. If all values are null, null is returned. This is how you concatenate two or more XML fragments:
					SELECT XMLCONCAT( XMLELEMENT("name", CustomerName), XMLPARSE(CONTENT '
					<a>
						b
					</a>' WELLFORMED) ) FROM Customer c WHERE c.CustomerID = 87; ========================================================== 
					<name>
						Wartian Herkku
					</name>
					<a>
						b
					</a>
				
content is XML. Return value is XML.
XMLELEMENT
XMLELEMENT([NAME] name [, <NSP>] [, <ATTR>][, content]*)
ATTR:=XMLATTRIBUTES(exp [AS name] [, exp [AS name]]*)
NSP:=XMLNAMESPACES((uri AS prefix | DEFAULT uri | NO DEFAULT))+
Returns an XML element with the given name and content. If the content value is of a type other than XML, it will be escaped when added to the parent element. Null content values are ignored. Whitespace in XML or the string values of the content is preserved, but no whitespace is added between content values.
XMLNAMESPACES is used to provide namespace information. NO DEFAULT is equivalent to defining the default namespace to the null URI - xmlns="". Only one DEFAULT or NO DEFAULT namespace item may be specified. The namespace prefixes xmlns and xml are reserved.
If an attribute name is not supplied, the expression must be a column reference, in which case the attribute name will be the column name. Null attribute values are ignored.
For example, with an xml_value of <doc/>,
XMLELEMENT(NAME "elem", 1, '<2/>', xml_value)
returns
<elem>1&lt;2/&gt;<doc/><elem/>
name and prefix are identifiers. uri is a string literal. content can be any type. Return value is XML. The return value is valid for use in places where a document is expected.
				SELECT XMLELEMENT("name", CustomerName)
FROM   Customer c
WHERE  c.CustomerID = 87;
 
==========================================================
<name>Wartian Herkku</name>
"Multiple Columns"
SELECT XMLELEMENT("customer", 
          XMLELEMENT("name", c.CustomerName),
          XMLELEMENT("contact", c.ContactName))
FROM   Customer c
WHERE  c.CustomerID = 87;
 
==========================================================
<customer><name>Wartian Herkku</name><contact>Pirkko Koskitalo</contact></customer>
"Columns as Attributes"
SELECT XMLELEMENT("customer", 
          XMLELEMENT("name", c.CustomerName,
            XMLATTRIBUTES(
                  "contact" as c.ContactName,
                  "id" as c.CustomerID
            )
          )
       )
FROM   Customer c
WHERE  c.CustomerID = 87;
 
==========================================================
<customer><name contact="Pirkko Koskitalo" id="87">Wartian Herkku</name></customer>
XMLFOREST
XMLFOREST(content [AS name] [, <NSP>] [, content [AS name]]*)
Returns an concatenation of XML elements for each content item. See XMLELEMENT for the definition of NSP. If a name is not supplied for a content item, the expression must be a column reference, in which case the element name will be a partially escaped version of the column name.
name is an identifier. content can be any type. Return value is XML.
You can use XMLFORREST to simplify the declaration of multiple XMLELEMENTS, XMLFOREST function allows you to process multiple columns at once:
SELECT XMLELEMENT("customer", 
          XMLFOREST(
             c.CustomerName AS "name",
             c.ContactName AS "contact"
          ))
FROM   Customer c
WHERE  c.CustomerID = 87;
 
==========================================================
<customer><name>Wartian Herkku</name><contact>Pirkko Koskitalo</contact></customer>
XMLAGG

XMLAGG is an aggregate function, that takes a collection of XML elements and returns an aggregated XML document.
XMLAGG(xml)

From above example in XMLElement, each row in the Customer table table will generate row of XML if there are multiple rows matching the criteria. That will generate a valid XML, but it will not be well formed, because it lacks the root element. XMLAGG can used to correct that
"Example"
SELECT XMLELEMENT("customers",
         XMLAGG(
           XMLELEMENT("customer", 
             XMLFOREST(
               c.CustomerName AS "name",
               c.ContactName AS "contact"
             )))
FROM   Customer c
 
 
==========================================================
<customers>
<customer><name>Wartian Herkku</name><contact>Pirkko Koskitalo</contact></customer>
<customer><name>Wellington Importadora</name><contact>Paula Parente</contact></customer>
<customer><name>White Clover Markets</name><contact>Karl Jablonski</contact></customer>
</customers>
XMLPARSE
XMLPARSE((DOCUMENT|CONTENT) expr [WELLFORMED])
Returns an XML type representation of the string value expression. If DOCUMENT is specified, then the expression must have a single root element and may or may not contain an XML declaration. If WELLFORMED is specified then validation is skipped; this is especially useful for CLOB and BLOB known to already be valid.
expr in {string, clob, blob and varbinary}. Return value is XML.
If DOCUMENT is specified then the expression must have a single root element and may or may not contain an XML declaration. If WELLFORMED is specified then validation is skipped; this is especially useful for CLOB and BLOB known to already be valid.
SELECT XMLPARSE(CONTENT '<customer><name>Wartian Herkku</name><contact>Pirkko Koskitalo</contact></customer>' WELLFORMED);
 
Will return a SQLXML with contents:
<customer><name>Wartian Herkku</name><contact>Pirkko Koskitalo</contact></customer>
 
XMLPI
XMLPI([NAME] name [, content])
Returns an XML processing instruction.
name is an identifier. content is a string. Return value is XML.
XMLQUERY
XMLQUERY([<NSP>] xquery [<PASSING>] [(NULL|EMPTY) ON EMPTY]]
PASSING:=PASSING exp [AS name] [, exp [AS name]]*
Returns the XML result from evaluating the given xquery. See XMLELEMENT for the definition of NSP. Namespaces may also be directly declared in the XQuery prolog.
The optional PASSING clause is used to provide the context item, which does not have a name, and named global variable values. If the XQuery uses a context item and none is provided, then an exception will be raised. Only one context item may be specified and should be an XML type. All non-context non-XML passing values will be converted to an appropriate XML type.
The ON EMPTY clause is used to specify the result when the evaluated sequence is empty. EMPTY ON EMPTY, the default, returns an empty XML result. NULL ON EMPTY returns a null result.
xquery in string. Return value is XML.

Note

XMLQUERY is part of the SQL/XML 2006 specification.
See also XMLTABLE.
XMLEXISTS
Returns true if a non-empty sequence would be returned by evaluating the given xquery.
XMLEXISTS([<NSP>] xquery [<PASSING>]]
 
PASSING:=PASSING exp [AS name] [, exp [AS name]]*
Namespaces may also be directly declared in the xquery prolog.
The optional PASSING clause is used to provide the context item, which does not have a name, and named global variable values. If the xquery uses a context item and none is provided, then an exception will be raised. Only one context item may be specified and should be an XML type. All non-context non-XML passing values will be converted to an appropriate XML type. Null/Unknown will be returned if the context item evaluates to null.
xquery in string. Return value is boolean.
XMLEXISTS is part of the SQL/XML 2006 specification.
XMLSERIALIZE
XMLSERIALIZE([(DOCUMENT|CONTENT)] xml [AS datatype] [ENCODING enc] [VERSION ver] [(INCLUDING|EXCLUDING) XMLDECLARATION])
Returns a character type representation of the XML expression.
datatype may be character (string, varchar, clob) or binary (blob, varbinary). CONTENT is the default. If DOCUMENT is specified and the XML is not a valid document or fragment, then an exception is raised.
Return value matches data type. If no data type is specified, then CLOB will be assumed.
The encoding enc is specified as an identifier. A character serialization may not specify an encoding. The version ver is specified as a string literal. If a particular XMLDECLARATION is not specified, then the result will have a declaration only if performing a non UTF-8/UTF-16 or non version 1.0 document serialization or the underlying XML has an declaration. If CONTENT is being serialized, then the declaration will be omitted if the value is not a document or element.
The following example produces a BLOB of XML in UTF-16 including the appropriate byte order mark of FE FF and XML declaration:
XMLSERIALIZE(DOCUMENT value AS BLOB ENCODING "UTF-16" INCLUDING XMLDECLARATION)
XSLTRANSFORM
XSLTRANSFORM(doc, xsl)
Applies an XSL stylesheet to the given document.
doc and xsl in {string, clob, xml}. Return value is a CLOB. If either argument is null, the result is null.
XPATHVALUE
XPATHVALUE(doc, xpath)
Applies the XPATH expression to the document and returns a string value for the first matching result. For more control over the results and XQuery, use the XMLQUERY function.
Matching a non-text node will still produce a string result, which includes all descendant text nodes.
doc and xpath in {string, clob, xml}. Return value is a string.
When the input document utilizes namespaces, it is sometimes necessary to specify XPATH that ignores namespaces. For example, given the following XML,
<?xml version="1.0" ?>
  <ns1:return xmlns:ns1="http://com.test.ws/exampleWebService">Hello<x> World</x></return>
the following function results in 'Hello World'.
xpathValue(value, '/*[local-name()="return"])

3.4.15. JSON Functions

JSON functions provide functionality for working with JSON (JavaScript Object Notation) data.
JSONTOXML
JSONTOXML(rootElementName, json)
Returns an XML document from JSON. The appropriate UTF encoding (8, 16LE. 16BE, 32LE, 32BE) will be detected for JSON BLOBS. If another encoding is used, see the TO_CHARS function (see Section 3.4.5, “String Functions”).
rootElementName is a string, json is in {clob, blob}. Return value is XML. The result is always a well-formed XML document.
The mapping to XML uses the following rules:
  • The current element name is initially the rootElementName, and becomes the object value name as the JSON structure is traversed.
  • All element names must be valid XML 1.1 names. Invalid names are fully escaped according to the SQLXML specification.
  • Each object or primitive value will be enclosed in an element with the current name.
  • Unless an array value is the root, it will not be enclosed in an additional element.
  • Null values will be represented by an empty element with the attribute xsi:nil="true"
  • Boolean and numerical value elements will have the attribute xsi:type set to boolean and decimal respectively.

Example 3.1. Sample JSON to XML for jsonToXml('person', x)

JSON:
{ "firstName" : "John" , "children" : [ "Randy", "Judy" ] }
XML:
<?xml version="1.0" ?><person><firstName>John</firstName><children>Randy</children><children>Judy</children></person>

Example 3.2. Sample JSON to XML for jsonToXml('person', x) with a root array.

JSON:
[{ "firstName" : "George" }, { "firstName" : "Jerry" }]
XML (Notice there is an extra "person" wrapping element to keep the XML well-formed):
<?xml version="1.0" ?><person><person><firstName>George</firstName></person><person><firstName>Jerry</firstName></person></person>
JSON:

Example 3.3. Sample JSON to XML for jsonToXml('root', x) with an invalid name.

{"/invalid" : "abc" }
XML:

Example 3.4. Sample JSON to XML for jsonToXml('root', x) with an invalid name.

<?xml version="1.0" ?>
<root>
  <_u002F_invalid>abc</_u002F_invalid>
</root>
JSONARRAY
JSONARRAY(value...)
Returns a JSON array.
value is any object convertable to a JSON value (see Section 3.4.16, “Conversion to JSON”). Return value is a CLOB marked as being valid JSON. Null values will be included in the result as null literals.
For example:
jsonArray('a"b', 1, null, false, {d'2010-11-21'})
returns
["a\"b",1,null,false,"2010-11-21"]
JSONOBJECT
JSONARRAY(value [as name] ...)
Returns a JSON object.
value is any object convertable to a JSON value (see Section 3.4.16, “Conversion to JSON”). Return value is a clob marked as being valid JSON.
Null values will be included in the result as null literals.
If a name is not supplied and the expression is a column reference, the column name will be used otherwise exprN will be used where N is the 1-based index of the value in the JSONARRAY expression.
For example:
jsonObject('a"b' as val, 1, null as "null")
returns
{"val":"a\"b","expr2":1,"null":null}
JSONPARSE
JSONPARSE(value, wellformed)
Validates and returns a JSON result.
value is blob with an appropriate JSON binary encoding (UTF-8, UTF-16, or UTF-32) or clob. wellformed is a boolean indicating that validation should be skipped. Return value is a CLOB marked as being valid JSON.
A null for either input will return null.
jsonParse('"a"')

3.4.16. Conversion to JSON

A straightforward specification compliant conversion is used for converting values into their appropriate JSON document form.
  • null values are included as the null literal.
  • values parsed as JSON or returned from a JSON construction function (JSONPARSE, JSONARRAY, JSONARRAY_AGG) will be directly appended into a JSON result.
  • boolean values are included as true/false literals
  • numeric values are included as their default string conversion - in some circumstances if not a number or +-infinity results are allowed, invalid JSON may be obtained.
  • string values are included in their escaped/quoted form.
  • binary values are not implicitly convertible to JSON values and require a specific prior to inclusion in JSON.
  • all other values will be included as their string conversion in the appropriate escaped/quoted form.

3.4.17. Security Functions

Security functions provide the ability to interact with the security system.
HASROLE
hasRole([roleType,] roleName)
Whether the current caller has the JBoss Data Virtualization data role roleName.
roleName must be a string, the return type is boolean.
The two argument form is provided for backwards compatibility. roleType is a string and must be 'data'.
Role names are case-sensitive and only match JBoss Data Virtualization data roles (see Section 7.1, “Data Roles”). JAAS roles/groups names are not valid for this function, unless there is corresponding data role with the same name.

3.4.18. Miscellaneous Functions

array_get
array_get(array, index)
Returns the object value at a given array index.
array is the object type, index must be an integer, and the return type is object.
One-based indexing is used. The actual array value must be a java.sql.Array or Java array type. An exception will be thrown if the array value is the wrong type of the index is out of bounds.
array_length
array_length(array)
Returns the length for a given array.
array is the object type, and the return type is integer.
The actual array value must be a java.sql.Array or Java array type. An exception will be thrown if the array value is the wrong type.
uuid
uuid()
Returns a universally unique identifier.
The return type is string.
Generates a type 4 (pseudo randomly generated) UUID using a cryptographically strong random number generator. The format is XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX where each X is a hex digit.

3.4.19. Nondeterministic Function Handling

JBoss Data Virtualization categorizes functions by varying degrees of determinism. When a function is evaluated and to what extent the result can be cached are based upon its determinism level.
  1. Deterministic - the function will always return the same result for the given inputs. Deterministic functions are evaluated by the engine as soon as all input values are known, which may occur as soon as the rewrite phase. Some functions, such as the lookup function, are not truly deterministic, but is treated as such for performance. All functions not categorized below are considered deterministic.
  2. User Deterministic - the function will return the same result for the given inputs for the same user. This includes the hasRole and user functions. User deterministic functions are evaluated by the engine as soon as all input values are known, which may occur as soon as the rewrite phase. If a user deterministic function is evaluated during the creation of a prepared processing plan, then the resulting plan will be cached only for the user.
  3. Session Deterministic - the function will return the same result for the given inputs under the same user session. This category includes the env function. Session deterministic functions are evaluated by the engine as soon as all input values are known, which may occur as soon as the rewrite phase. If a session deterministic function is evaluated during the creation of a prepared processing plan, then the resulting plan will be cached only for the user's session.
  4. Command Deterministic - the result of function evaluation is only deterministic within the scope of the user command. This category include the curdate, curtime, now, and commandpayload functions. Command deterministic functions are delayed in evaluation until processing to ensure that even prepared plans utilizing these functions will be executed with relevant values. Command deterministic function evaluation will occur prior to pushdown; however, multiple occurrences of the same command deterministic time function are not guaranteed to evaluate to the same value.
  5. Nondeterministic - the result of function evaluation is fully nondeterministic. This category includes the rand function and UDFs marked as nondeterministic. Nondeterministic functions are delayed in evaluation until processing with a preference for pushdown. If the function is not pushed down, then it may be evaluated for every row in its execution context (for example, if the function is used in the select clause).