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

> Understand how Ossie expression language uses field expressions and calculated fields. Learn about SQL fragments, regex patterns, arithmetic operators, and aggregate functions.

- Repository: [The Apache Software Foundation/ossie](https://github.com/apache/ossie)
- Tags: how-to-guide
- Published: 2026-07-26

---

**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`](https://github.com/apache/ossie/blob/main/core-spec/expression_language.md), the canonical structure for a calculated field appears as:

```yaml
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`](https://github.com/apache/ossie/blob/main/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:

```java
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:

```java
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:

```java
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:

```java
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`](https://github.com/apache/ossie/blob/main/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:

```java
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`](https://github.com/apache/ossie/blob/main/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`](https://github.com/apache/ossie/blob/main/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`](https://github.com/apache/ossie/blob/main/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`](https://github.com/apache/ossie/blob/main/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`](https://github.com/apache/ossie/blob/main/core-spec/expression_language.md).