Cube Variables

Cube Variables are named values that can be substituted into a Point of View (POV) when a query is executed.

They allow query definitions to remain dynamic rather than hardcoding values that change over time.

For example, instead of storing:

{
  "YEARS": ["FY26"]
}

a POV can reference:

{
  "YEARS": ["&CurrentYear"]
}

If CurrentYear currently contains:

FY26

the query is evaluated using:

{
  "YEARS": ["FY26"]
}

Updating the variable changes the value used by every query that references it without requiring those query definitions to be edited.

Variable Syntax

Use an ampersand followed by the variable name:

&VariableName

For example:

&CurrentYear

&CurrentPeriod

&CurrentScenario

For variable names containing spaces, use brackets:

&[Variable With Spaces]

For example:

&[Current Year]

Both forms are supported.

Using a Variable in a POV

A variable can be used anywhere its resolved value produces valid POV syntax.

For example:

{
  "MEASURES": ["Units"],
  "TIME": ["Qtr1"],
  "YEARS": ["&CurrentYear"]
}

If:

CurrentYear = Curr Year

the effective POV becomes:

{
  "MEASURES": ["Units"],
  "TIME": ["Qtr1"],
  "YEARS": ["Curr Year"]
}

The query engine then processes the resolved POV normally.

Conceptually:

POV
 │
 │ "YEARS": ["&CurrentYear"]
 ▼
Resolve Cube Variable
 │
 │ CurrentYear = Curr Year
 ▼
Resolved POV
 │
 │ "YEARS": ["Curr Year"]
 ▼
Execute Query

Variables Are Text Substitutions

A Cube Variable is not limited to a particular business concept such as Year, Period, Scenario, or Version.

The variable value is substituted into the POV at query time.

What matters is that the POV is syntactically valid after the substitution occurs.

For example, a variable could represent:

Curr Year

Actual

Jan

or another value appropriate to the location in which the variable is referenced.

The variable name itself does not determine what kind of value it can contain.

The rule is:

Original POV
     │
     ▼
Variable Substitution
     │
     ▼
Final POV must be valid
Casabase Cube POV syntax

This makes Cube Variables a general-purpose substitution mechanism rather than a feature limited specifically to time members.

Example: Current Year

Define:

CurrentYear = Curr Year

and use:

{
  "MEASURES": ["Units"],
  "TIME": [{"children": "Qtr1"}],
  "YEARS": ["&CurrentYear"]
}

The same POV can continue to be used when the reporting year changes.

For example, changing:

CurrentYear = Curr Year

to another valid member value changes subsequent executions without modifying the query itself.

Example: Current Scenario

A variable can represent a Scenario member:

CurrentScenario = Actual

The POV can then use:

{
  "MEASURES": ["Units"],
  "SCENARIO": ["&CurrentScenario"],
  "YEARS": ["Curr Year"]
}

Changing:

CurrentScenario = Forecast

causes subsequent executions to resolve the same POV to:

{
  "MEASURES": ["Units"],
  "SCENARIO": ["Forecast"],
  "YEARS": ["Curr Year"]
}

Using Multiple Variables

A POV can reference more than one Cube Variable.

For example:

{
  "MEASURES": ["Units"],
  "TIME": ["&CurrentPeriod"],
  "YEARS": ["&CurrentYear"],
  "SCENARIO": ["&CurrentScenario"]
}

Each variable is resolved when the query executes.

Conceptually:

&CurrentPeriod   ──► Qtr1
&CurrentYear     ──► Curr Year
&CurrentScenario ──► Actual

resulting in:

{
  "MEASURES": ["Units"],
  "TIME": ["Qtr1"],
  "YEARS": ["Curr Year"],
  "SCENARIO": ["Actual"]
}

Cube Variables and Saved Queries

Cube Variables are particularly useful with Saved Queries.

A Saved Query stores its POV, so a variable allows the query definition to remain unchanged while selected values move over time.

For example:

{
  "MEASURES": ["Units", "Transactions"],
  "TIME": ["&CurrentPeriod"],
  "YEARS": ["&CurrentYear"]
}

can remain stored as the Saved Query definition.

When the variables change:

CurrentPeriod = Qtr2
CurrentYear   = Curr Year

the next execution automatically uses those values.

This separates:

Query Structure
      │
      │ remains stable
      ▼
Saved POV

Variable Values
      │
      │ change as needed
      ▼
Execution Context

The query does not need to be recreated simply because the current reporting period changes.

Cube Variables and Scheduled Queries

The same behavior applies when a Saved Query is scheduled for materialization.

For example:

Saved Query
     │
     ├── &CurrentPeriod
     └── &CurrentYear
             │
             ▼
      Scheduled Execution
             │
             ▼
       Resolve Variables
             │
             ▼
         Execute POV
             │
             ▼
      Materialized Result

The variables are resolved when the query executes, so updating a variable can change the next scheduled result without changing the Saved Query or its schedule.

See Saved Queries for scheduling and materialization behavior.

Managing Cube Variables with SQL

Cube Variables can be managed programmatically with:

CUBE.MANAGE_CUBE_VAR

The procedure signature is:

CALL CUBE.MANAGE_CUBE_VAR(
    cube_name,
    action,
    var_name,
    var_value,
    active,
    ids
);

The procedure uses the following parameters:

Parameter	Description
cube_name	Cube containing the variable.
action	Variable-management action.
var_name	Variable name.
var_value	Current variable value.
active	Whether the variable is active.
ids	Array of variable IDs used for applicable batch operations.

Supported management actions include:

create
update
delete
list

Creating a Variable

For example:

CALL CUBE.MANAGE_CUBE_VAR(
    'ASOSAMP',
    'create',
    'CurrentYear',
    'Curr Year',
    TRUE,
    NULL
);

This creates:

CurrentYear = Curr Year

which can then be referenced in a POV as:

&CurrentYear

Updating a Variable

To change the value used by queries, update the variable rather than modifying every POV that references it.

Conceptually:

Before

CurrentYear
    │
    ▼
Curr Year


Update Variable
    │
    ▼

CurrentYear
    │
    ▼
Next Year

Every subsequent query using:

&CurrentYear

resolves using the new value.

Listing Cube Variables

Use:

CALL CUBE.GET_CUBE_VARS('ASOSAMP');

to retrieve the variables defined for a cube.

The result includes:

VAR_NAME
VAR_VALUE
ACTIVE

This is useful for inspecting the current values before executing or troubleshooting a dynamic POV.

Active Variables

Cube Variables include an ACTIVE setting.

An active variable is available for normal use in supported query and formula contexts.

When troubleshooting a variable reference, verify:

• The variable exists for the intended cube.
• The variable name is spelled correctly.
• The variable is active.
• The current variable value is what the query expects.
• The POV remains syntactically valid after substitution.

Variable Names with Spaces

For a variable named:

Current Fiscal Year

use:

&[Current Fiscal Year]

For example:

{
  "YEARS": ["&[Current Fiscal Year]"]
}

The bracketed syntax disambiguates the full variable name.

Variables without spaces normally use the simpler form:

&CurrentYear

Variables and POV Arrays

Cube Variables do not change the structural rules of a POV.

Every dimension value must still be a JSON array.

Correct:

{
  "YEARS": ["&CurrentYear"]
}

Incorrect:

{
  "YEARS": "&CurrentYear"
}

Variable substitution occurs within the POV, but the resulting POV must continue to satisfy all normal POV requirements.

See Point of View (POV) for those rules.

Variables and Member Names

When a variable is used in a location that expects a member, its resolved value must identify a valid underlying member name.

Aliases do not become valid POV member references merely because they are stored in a Cube Variable.

For example, if:

Member Name = 100-10
Alias       = Cash

a variable intended to resolve that Account member should ultimately produce:

100-10

rather than the alias:

Cash

POV resolution continues to use underlying member names.

Variables and Default Members

Cube Variables and default members perform different functions.

A Cube Variable explicitly substitutes a dynamic value into a POV.

A default member controls how a dimension is resolved when the POV does not explicitly provide a selection, and can also affect plain references to the dimension’s top member.

For example:

{
  "YEARS": ["&CurrentYear"]
}

explicitly includes YEARS in the POV.

YEARS is therefore being controlled by the variable rather than relying on omission and default-member behavior.

When the intended reporting context matters, using a Cube Variable can make that selection explicit while still allowing it to change centrally.

See Point of View (POV) for default-member behavior.

When to Use Cube Variables

Cube Variables are useful when the structure of the query should remain stable but part of its execution context changes.

Common examples include:

• Current reporting period
• Current year
• Current scenario
• Current forecast cycle
• Current version
• Another centrally maintained query selection

For example:

Without Variable

Saved Query FY26
Saved Query FY27
Saved Query FY28

can often become:

Saved Query
    │
    ▼
&CurrentYear

with the current value maintained separately.

Cube Variables are not required for values that are intentionally fixed as part of a query’s business definition.

For example, a query specifically designed to compare against Actual should continue to reference Actual directly if that selection should never move with configuration.

Recommended Usage

Use Cube Variables when:

• The same value appears in multiple query definitions.
• A selection changes periodically.
• A Saved Query should remain stable across reporting cycles.
• Scheduled materialization should automatically follow a changing reporting context.
• A centrally maintained value should control multiple consumers.

Keep fixed business selections explicit when they are fundamental to what the query represents.

For example:

{
  "SCENARIO": ["Actual"],
  "YEARS": ["&CurrentYear"]
}

makes the distinction clear:

Actual
  │
  └── fixed business selection

CurrentYear
  │
  └── dynamic execution context

Troubleshooting

If a query containing a Cube Variable does not behave as expected, check the following.

Verify the Variable Exists

CALL CUBE.GET_CUBE_VARS('ASOSAMP');

Confirm the expected variable name is present.

Verify the Current Value

Check VAR_VALUE to make sure it contains the intended replacement text.

Verify the Variable Is Active

Check:

ACTIVE = TRUE

Verify the Reference Syntax

For a simple name:

&CurrentYear

For a name containing spaces:

&[Current Year]

Verify the Resolved POV

Consider what the POV becomes after substitution.

For example:

{
  "YEARS": ["&CurrentYear"]
}

with:

CurrentYear = Curr Year

must result in the equivalent of:

{
  "YEARS": ["Curr Year"]
}

If the resulting POV would not be valid, correct either the variable value or the location in which it is referenced.

Key Principle

The most important rule for Cube Variables is:

A Cube Variable can represent any value appropriate to its use, provided that substituting the value produces syntactically valid Casabase Cube POV content.

Cube Variables do not define a separate query language. They dynamically supply values to the existing POV language.

Related Topics

• Point of View (POV)
• Query Builder
• Querying with SQL
• Saved Queries