Concepts → Internal Query Expression
About an Internal Query Expression
An internal query expression queries a physical schema table or runtime business view. In this regard, the adjective “internal” references physical schemas and business schemas within a given tenant. The objective of an internal query expression is to return a single scalar value or an array of scalar values.
You use the Formula Builder to create the internal query expression. The internal query expression requires either the query() or queryDistinct() built-in function. Both functions require a fully qualified name for a single column in a physical schema table or a runtime business view. An internal query expression can also contain one or more predicates for filtering query results.
Internal query expression context
The context for an internal query expression is an internal session variable or an InQuery filter operator and formula expression. The internal query expression context determines the validation rules for the expression itself and the limitations of the expression.
For example, an internal query expression can reference in a predicate another internal query expression or another internal session variable.
Valid references in an internal query expression
Here are the valid references in an internal query expression:
- Referenceable columns
- Supported built-in functions
- Referenceable variables
View Access Rights
In order to reference a column or variable in an internal query expression, you must have View access rights to the grandparent object (schema or business schema) or the variable.
Referenceable columns
A referenceable column has a fully qualified name. A referenceable column exists in a physical schema or runtime business view. Here are the possible types of referenceable columns in an internal query expression:
- Physcial_Schema.Table.Column
- PhyscialSchema.Table.FormulaColumn
- PhyscialSchema.IncortaTable.Column
- PhyscialSchema.IncortaTable.Formula_Column
- Business_Schema.View.Column
- BusinessSchema.View.FormulaColumn
- BusinessSchema.IncortaView.Column
- BusinessSchema.IncortaView.Formula_Column
Supported built-in functions
The following are the types of valid built-in functions for an internal query expression:
| Function Type | Description | Example |
|---|---|---|
| Boolean | Functions that evaluate to True or False | and, between, contains, endsWith, in, inList, isNan, isNull, like, not, or, startsWith |
| Conditional Statement | Statements that return a value based on the evaluation of a parameter | case, decode, and if |
| Conversion | Functions that convert the Incorta Data Type of a parameter. In addition, functions that manipulate Timestamp and Date values for different return values. | day, double, monthName, parseDouble, string, toChar, and year |
| Miscellaneous | Functions with assorted uses | descendantOf, lookup, rowNumber, and schemaRefreshTime |
| Arithmetic | Functions that take one or more values and return a single value. | abs, ceil, exp, floor, max, min, mod, rnd, round, sqrt, and trunc |
| Date | Functions that manipulate Timestamp and Date values. | addDays, date, month, removeTime, weekday, and year |
| String | Functions that return string values or return values based on string parameters. | bin, concat, find, ifNull, repeat, rTrim, and upper |
| Query | Functions that act as the base query function or query filtering functions. | and, query, queryDistinct, and where |
Internal query expressions are incompatible with built-in aggregation or analytics functions. They will not be listed in the Formula Builder when building an expression.
Referenceable variables and functions
The following are the types of variables and functions that are referenceable in an internal query expression:
| Variable Type | Internal Session Variable | InQuery |
|---|---|---|
| Built-in function | ✔ | ✔ |
| Date system variable | ✔ | ✔ |
| External session variable | ✔ | ✔ |
| Filter expression session variable | ||
| Internal session variable | ✔ | ✔ |
| Global session variable | ✔ | ✔ |
| Miscellaneous system variable | ✔ | ✔ |
| Presentation variable | ✔ |
Internal query expression examples
The following are several examples of internal query expressions:
Example with fully qualified column name:
query(
SALES.SALES.AMOUNT_SOLD
)Example with referenceable internal or external session variable:
queryDistinct(
sch_IncortaMetadata.GROUP.ID,
sch_IncortaMetadata.GROUP.NAME = "grp_Admin",
sch_IncortaMetadata.GROUP.TENANTID = $ivar_getTenantID
)Both Internal and external session variables are referenced in an internal query expression using the same syntax, using a $ before the variable name.
Example with referenceable system variable and where() predicate:
queryDistinct(
SALES.SALES.PROD_ID,
where(
SALES.SALES.TIME_ID,
= ,
$currentDate
)Example with or() predicate:
query(
if(
or(
$ivar_getCurrentDayName = 'Saturday',
$ivar_getCurrentDayName = 'Friday'
),
formatDate(
addDays(
date(
$ivar_getCurrentWeekStartDate
),
5
),
"yyyy-MM-dd"
),
formatDate(
addDays(
date(
$ivar_getCurrentWeekStartDate
),
-2
),
"yyyy-MM-dd"
)
)
)Example with and() predicate:
queryDistinct(
SALES.SALES.PROD_ID,
where(
SALES.SALES.TIME_ID,
= ,
$currentDate
)and(
SALES.CUSTOMERS.CUST_ID,
,
SALES.SALES.CUSTOMER_ID
)
)Example of nested query expression:
queryDistinct(
SALES.PRODUCTS.PROD_ID,
inList(
SALES.PRODUCTS.PROD_CATEGORY_ID,
queryDistinct(
SALES.PRODUCTS.PROD_CATEGORY_ID
)
)
)Following is an example internal query expression using a conditional statement in the query:
query(
if(
SALES.SALES.AMOUNT_SOLD >= $evar_threshold,
"True",
"False"
)
)