How Field Expressions and Calculated Fields Work in the Ossie Expression Language

Field expressions in the Apache Ossie project are portable SQL fragments stored as dialect-specific maps, where calculated fields are detected by the FieldMappingHandler using regex patterns to identify arithmetic operators and SQL aggregate functions.

The Ossie expression language provides a vendor-agnostic way to define reusable SQL logic within semantic models. Understanding how field expressions and calculated fields function is essential for developers implementing converters that translate between Ossie's internal representation and platform-specific formats like Salesforce.

The Dialect-Based Storage Model

Ossie treats a field expression as a portable representation of a SQL fragment that can be evaluated by any compliant implementation. The expression is stored in the model as a map with a top-level key expression that contains a list of dialects. Each dialect entry holds a dialect name (e.g., TABLEAU, ANSI_SQL) and the raw SQL string for that dialect.

YAML Structure for Field Definitions

In core-spec/expression_language.md, the canonical structure for a calculated field appears as:

field_name:
  expression:
    dialects:
      - dialect: TABLEAU
        expression: "quantity * unit_price"

When no dialect is specified, implementations treat the first entry as the default Ossie dialect. Vendors can provide multiple dialects for the same logical expression, allowing converters to select deterministic SQL syntax for target databases.

The ExpressionInfo Record

According to the source code in converters/salesforce/src/main/java/org/apache/ossie/converter/FieldMappingHandler.java, the internal representation uses a private record to transport extracted expression data between methods:

private record ExpressionInfo(String expression, String dialect)

This immutable record holds the raw SQL string and its associated dialect type for downstream processing.

Converting Between Ossie and Vendor Formats

The Salesforce converter demonstrates the bidirectional translation logic that wraps raw SQL strings into Ossie's dialect structure and unwraps them during import.

The Wrap/Unwrap Cycle

When converting Ossie → Salesforce, the FieldMappingHandler extracts the raw expression string and builds a dialect list with a single entry using the wrapExpression method:

private Map<String, Object> wrapExpression(String expressionValue) {
    Map<String, Object> dialect = new LinkedHashMap<>();
    dialect.put(DIALECT, DIALECT_TABLEAU);
    dialect.put(EXPRESSION, expressionValue);

    List<Map<String, Object>> dialects = List.of(dialect);
    Map<String, Object> expression = new LinkedHashMap<>();
    expression.put(DIALECTS, dialects);
    return expression;
}

When converting Salesforce → Ossie, the handler reads the expression map, selects the first dialect entry via unwrapExpression, and pulls out the raw string for processing.

Detecting Calculated Fields vs Direct Column References

Ossie distinguishes between direct column references (simple identifiers like customer_id) and calculated fields (expressions containing operators or functions like quantity * unit_price or SUM(amount)).

The isCalculatedExpression Heuristic

The FieldMappingHandler determines field type using pattern matching against normalized SQL strings:

private boolean isCalculatedExpression(String expression) {
    if (expression == null || expression.isEmpty()) return false;
    String normalized = expression.trim().toUpperCase();

    return normalized.matches(".*[+\\-*/%].*")
        || normalized.matches(".*\\b(SUM|AVG|COUNT|MAX|MIN|CASE)\\b.*");
}

This heuristic scans for arithmetic operators (+, -, *, /, %) and SQL aggregate keywords to identify calculations.

Semantic Calculated Dimensions

If the dialect is TABLEAU and isCalculatedExpression returns true, the converter marks the field as a calculated field and creates a semanticCalculatedDimension for the Salesforce target:

ExpressionInfo expressionInfo = unwrapExpression(osiField);
String expression = expressionInfo.expression();
String dialect = expressionInfo.dialect();

boolean isCalculated = DIALECT_TABLEAU.equals(dialect) && isCalculatedExpression(expression);
if (isCalculated) {
    Map<String, Object> calcDim = createSemanticCalculatedDimension(osiField, expression);
}

The same logic applies to metrics via MetricMappingHandler.java, demonstrating that the expression container structure is reused across different semantic element types.

Runtime SQL Generation

Downstream components read the expression.dialects[0].expression value and embed it verbatim into generated SQL, trusting that the dialect matches the target database:

String sql = "SELECT " + expressionInfo.expression() + " AS total_price FROM orders";

Because the expression is pre-validated and dialect-specific, the SQL generator injects it directly without additional translation.

Summary

• Ossie stores field expressions as maps containing a dialects list, where each entry specifies a SQL dialect and its corresponding expression string.
• The FieldMappingHandler class in the Salesforce converter implements wrapExpression and unwrapExpression methods to manage bidirectional translation.
• Calculated fields are detected using the isCalculatedExpression method, which identifies arithmetic operators and SQL functions via regex pattern matching.
• The ExpressionInfo record provides a type-safe container for expression strings and their dialect metadata during conversion.
• MetricMappingHandler.java mirrors field-level logic for metric objects, confirming the expression structure is consistent across semantic model elements.

Frequently Asked Questions

What is the structure of an Ossie field expression?

An Ossie field expression is stored as a YAML or JSON map with a top-level expression key containing a dialects list. Each list entry is an object with two fields: dialect (a string identifier like TABLEAU or ANSI_SQL) and expression (the raw SQL string). This structure allows the same logical field to carry different SQL syntaxes optimized for specific database engines.

How does Ossie determine if a field is calculated?

Ossie determines if a field is calculated by calling the isCalculatedExpression method in FieldMappingHandler.java. This method normalizes the input to uppercase and applies regex patterns to detect arithmetic operators (+, -, *, /, %) or SQL keywords including SUM, AVG, COUNT, MAX, MIN, and CASE. A field is only marked as calculated if this method returns true and the dialect is TABLEAU.

Can an Ossie field expression support multiple SQL dialects?

Yes. The dialects list can contain multiple entries, each providing a SQL variant for a specific vendor. When converting models, the handler typically selects the first dialect entry or uses a deterministic selection strategy based on the target platform requirements, as implemented in the unwrapExpression logic.

Where is the expression handling logic implemented in the codebase?

The core conversion logic resides in converters/salesforce/src/main/java/org/apache/ossie/converter/FieldMappingHandler.java, which contains the wrapExpression, unwrapExpression, and isCalculatedExpression methods. Analogous logic for metrics appears in converters/salesforce/src/main/java/org/apache/ossie/converter/MetricMappingHandler.java. The formal specification of supported SQL constructs is documented in core-spec/expression_language.md.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}