Field Formatting

Overview

All scalar fields in the Finale GraphQL API support the formatter argument, which controls how field values are returned. This allows you to choose between HTML-formatted output (with links and formatting), raw values, abbreviated versions, or other formatting options.

Universal Support

Important: The formatter argument is available on all scalar fields, regardless of their type or default formatting behavior. This is a universal feature of the API.

Formatter Options

Every scalar field accepts these formatter values:

`"html"`

Returns HTML-formatted content with links and escaped text. This is useful for display in web interfaces.

Example:

query {
  productViewConnection(first: 5) {
    edges {
      node {
        productId(formatter: "html")
        sku(formatter: "html")
      }
    }
  }
}

Use when:

Displaying data in a web UI that can render HTML
You want clickable links for IDs
You need properly escaped content for security

`"none"`

Returns the raw, unformatted value exactly as stored in the database.

Example:

query {
  productViewConnection(first: 5) {
    edges {
      node {
        productId(formatter: "none")
        price(formatter: "none")
      }
    }
  }
}

Use when:

Processing data programmatically
You need the exact stored value
Building integrations or exports
You want to avoid HTML markup

`"abbreviated"`

Returns an abbreviated or shortened version of the formatted value.

Example:

query {
  productViewConnection(first: 5) {
    edges {
      node {
        description(formatter: "abbreviated")
        notes(formatter: "abbreviated")
      }
    }
  }
}

Use when:

Displaying data in space-constrained UIs (tables, lists)
You need a summary or preview
Performance is critical and full formatting is expensive

`"blank-zero"`

Returns an empty string if the value is zero, otherwise returns the formatted value.

Example:

query {
  productViewConnection(first: 5) {
    edges {
      node {
        quantityOnHand(formatter: "blank-zero")
        price(formatter: "blank-zero")
      }
    }
  }
}

Use when:

Displaying numeric fields where zero should appear empty
Creating cleaner reports and tables
Following business rules that treat zero as "not applicable"

Default Formatter

When no formatter argument is specified, the API uses the field's default formatting behavior:

Fields with HTML formatting capabilities typically default to standard formatting (not HTML)
Some fields (like IDs, names, links) may have "html" as their default formatter
Most fields use standard formatting by default

You can check each field's default formatter in its documentation under "Default Formatter" in the reference pages.

Usage Patterns

Field-Level Formatting

Apply formatting to individual fields:

query {
  orderViewConnection(first: 10) {
    edges {
      node {
        orderId(formatter: "html")      # HTML formatted
        orderDate(formatter: "none")     # Raw value
        total(formatter: "blank-zero")   # Empty if zero
        description                      # Default formatting
      }
    }
  }
}

Node-Level Formatting

Apply the same formatter to all fields in a node:

query {
  productViewConnection(first: 10) {
    edges {
      node(formatter: "html") {
        productId    # All fields use HTML formatting
        sku
        name
        description
      }
    }
  }
}

Note: Field-level formatters override node-level formatters.

Mixing Formatters

Combine node-level and field-level formatters for fine-grained control:

query {
  orderViewConnection(first: 10) {
    edges {
      node(formatter: "html") {
        orderId                    # Uses node-level "html"
        orderDate(formatter: "none")  # Overrides to "none"
        customerId                 # Uses node-level "html"
        total(formatter: "blank-zero")  # Overrides to "blank-zero"
      }
    }
  }
}

Default Formatter Behavior

Some fields have a default formatter defined (usually "html"). When a field has a default formatter:

If you don't specify formatter, the field uses its default formatter
To get raw value, explicitly use formatter: "none"
To use a different format, specify the formatter you want

Example with field that defaults to HTML:

query {
  productViewConnection(first: 5) {
    edges {
      node {
        productId                    # Uses default (html)
        productId(formatter: "none")  # Gets raw value
        sku                          # Uses default (standard)
      }
    }
  }
}

Best Practices

Use "none" for integrations: When building integrations or exports, use formatter: "none" to get exact values without formatting
Use "html" for web display: When displaying data in a web UI, use formatter: "html" for properly formatted and linked content
Check default formatters: Review field documentation to understand default formatting behavior
Be explicit in production: Always specify formatters explicitly in production code to avoid surprises if defaults change
Consider performance: The "none" formatter is typically fastest since it skips formatting logic

Common Use Cases

Data Export

query {
  productViewConnection(first: 1000) {
    edges {
      node(formatter: "none") {
        productId
        sku
        name
        price
        quantityOnHand
      }
    }
  }
}

Web UI Display

query {
  orderViewConnection(first: 50) {
    edges {
      node(formatter: "html") {
        orderId
        orderDate
        customerName
        total
        status
      }
    }
  }
}

Report Generation

query {
  productViewConnection(first: 100) {
    edges {
      node {
        productId(formatter: "html")
        sku(formatter: "none")
        quantityOnHand(formatter: "blank-zero")
        description(formatter: "abbreviated")
      }
    }
  }
}

Technical Details

Implementation

The formatter argument is:

Available on all scalar fields (String, Int, Float, Boolean, Date, etc.)
Not available on relation fields or connection fields
Processed on the server side before returning data
Applies formatting based on the field's dimension definition

Performance Considerations

Fastest: "none" - skips all formatting logic
Standard: default formatter - applies basic formatting
Slowest: "html" - applies HTML escaping, link generation, and formatting

For large queries, consider using "none" and applying formatting client-side if needed.

Next Steps

Browse API Reference to see default formatters for each field
Learn about Pagination to efficiently fetch large datasets
Explore Filtering to narrow down results