1. Home
  2. Latest Release Docs
  3. Guides
  4. Concepts
    1. Aggregate filter
    2. Alias
    3. Apache Avro™
    4. Apache Kafka™
    5. Applied filter
    6. Base table
    7. Bookmark
    8. Business schema
    9. Business schema view
    10. Business schema view column
    11. Business schema view formula column
    12. Column
    13. Connector
    14. Dashboard filter
    15. Dashboard folder
    16. Dashboard runtime filter
    17. Data agent
    18. Data alert
    19. Data destination
    20. Data purge
    21. Data retention
    22. Date system variable
    23. Distinct filter
    24. Dynamic field
    25. Expression
    26. External data source
    27. External session variable
    28. Filter expression
    29. Filter expression session variable
    30. Filter option
    31. Formula column
    32. Formula expression
    33. Full load
    34. Global variable
    35. Incorta Analyzer Table
    36. Incorta Analyzer Table column
    37. Incorta Analyzer Table formula column
    38. Incorta Analyzer View
    39. Incorta Analyzer View formula column
    40. Incorta Spark SQL View
    41. Incorta SQL Table
    42. Individual filter
    43. Insight filter
    44. Internal query expression
    45. Internal session variable
    46. Join
    47. Join condition
    48. Join condition column
    49. Join filter
    50. Join filter column
    51. Level-based measure
    52. Load filter
    53. Local data file
    54. Local data folder
    55. Materialized View
    56. Materialized View column
    57. Materialized View formula column
    58. Measure filter
    59. Miscellaneous system variable
    60. Multi-source table
    61. Physical schema
    62. Physical schema table
    63. Physical schema table column
    64. Physical schema table formula column
    65. Physical schema table runtime security filter
    66. PostgreSQL (Incorta SQL) View
    67. Presentation variable
    68. Prompt
    69. Query system variable
    70. Runtime business view
    71. Runtime business view formula column
    72. Runtime security filter
    73. Schema evolution
    74. Session variable
    75. Shared Storage
    76. Upgrade Readiness
    77. Variable
    78. Visualization
  5. Tools
  6. References
  7. Integrations
  8. Data applications
  9. Release Notes
  10. Incorta Premium

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.

Querying with limits

In 2024.1.6, Incorta has introduced two query functions designed for efficient data retrieval when working with internal session variables and global variables. These functions enable you to specify a limit on the number of records returned, allowing more targeted querying based on defined conditions.

  • queryWithLimit: Returns a specified number of records from a given column, with the option to apply additional filters to further narrow down the results.
  • queryDistinctWithLimit: Returns a limited set of unique (distinct) values from a specified column, with the ability to apply filters to refine the selection of distinct values.
Note

When you use a variable that returns a date or a date value, make sure that the value is in the following format yyyy-MM-dd.

Internal query expression context

The context for an internal query expression is an internal session variable or an In Query 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:

  • Physical_Schema.Table.Column
  • Physical_Schema.Table.Formula_Column
  • Physical_Schema.Incorta_Table.Column
  • Physical_Schema.Incorta_Table.Formula_Column
  • Physical_Schema.Incorta_Analyzer_Table.Column
  • Physical_Schema.Incorta_Analyzer_Table.Formula_Column
  • Physical_Schema.Incorta_SQL_Table.Column
  • Business_Schema.View.Column
  • Business_Schema.View.Formula_Column
  • Business_Schema.Incorta_View.Column
  • Business_Schema.Incorta_View.Formula_Column

Supported built-in functions

The following are the types of valid built-in functions for an internal query expression:

Function TypeDescriptionExample
BooleanFunctions that evaluate to True or Falseand, between, contains, endsWith, in, inList, isNan, isNull, like, not, or, startsWith
Conditional StatementStatements that return a value based on the evaluation of a parametercase, decode, and if
ConversionFunctions 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
MiscellaneousFunctions with assorted usesdescendantOf, lookup, rowNumber, and schemaRefreshTime
ArithmeticFunctions that take one or more values and return a single value.abs, ceil, exp, floor, max, min, mod, rnd, round, sqrt, and trunc
DateFunctions that manipulate Timestamp and Date values.addDays, date, month, removeTime, weekday, and year
StringFunctions that return string values or return values based on string parameters.bin, concat, find, ifNull, repeat, rTrim, and upper
QueryFunctions that act as the base query function or query filtering functions.query and queryDistinct
Note

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 TypeInternal Session VariableInQuery
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.COUNTRIES.COUNTRY_NAME
)

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
)
Note

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 a referenceable system variable:

queryDistinct(
    SALES.SALES.PROD_ID,
    SALES.SALES.TIME_ID = $currentDate
)

Examples with Boolean functions:

Example 1:

query(
    if(
        or(
            SALES.SALES.AMOUNT_SOLD > 3600,
            SALES.SALES.COST_OF_GOODS <= 2000
        ),
        "Green",
        "Red"
    ),
    trim(
        upper(
            SALES.COUNTRIES.COUNTRY_NAME
        )
    ) = trim(
        upper(
            $country
        )
    ),
    SALES.SALES.TIME_ID = date(
        "2007-12-31"
    )
)

Example 2:

query(
    SALES.SALES.AMOUNT_SOLD,
    and(
        SALES.COUNTRIES.COUNTRY_NAME = "Italy",
        SALES.SALES.AMOUNT_SOLD > 6950
    )
)

Following is an example internal query expression using a conditional statement in the query:

queryDistinct(
    if(
        SALES.SALES.AMOUNT_SOLD >= int(
            $evar_threshold
        ),
        "True",
        "False"
    )
)
Important

Because the result of a session variable is always a string or an array of strings, you must cast the session variable result value when you compare it to a non-string value.