This article explains what the Expression Builder is, why you would use it for custom exports, common terminology, and a step‑by‑step walkthrough with an example. Features and terms reflect the current implementation of the Expression Builder and its underlying query model.
What is the Expression Builder?
The Expression Builder lets you shape data for custom exports without writing code. You can:
Filter lists down to just the items you want
Aggregate values such as sum, count, min, or max
Format dates, date/times, and numbers for your target system
Preview results as you configure
🧰 Admins can optionally switch to a raw expression mode for advanced use cases.
Why use it?
Flexibility: Create tailored CSV or spreadsheet outputs for partners, BI tools, or finance systems.
Consistency: Save and reuse export mappings across teams.
Precision: Filter and aggregate directly at export time so downstream spreadsheets stay simple.
Terminology
Term | Definition |
Path | A pointer to the data you want to extract. For example, trip > charges points to the list of charges on a trip. |
Filter | A condition that narrows a list to only matching items. Example: charge_type = "Transport". |
Operator | The comparison used in a filter, such as EQ, NEQ, GT, GTE, LT, LTE, IN, NONE_IN. |
Aggregation | A way to reduce a list into a single value. Options include SUM, COUNT, DISTINCT, MIN, MAX, EXISTS, NOT_EXISTS. |
Formatting | Output presentation controls for dates, date/times, and numbers, and an optional cast to string for CSV safety. |
Expression mode (Advanced) | A raw expression editor available to admins for complex transformations. |
Preview | A live rendering that shows the result of your configuration before you export. |
Notes and current limitations
Enum values are not yet translated.
Filtering inside certain nested lists may require workarounds if a typed path is not available.
Unit conversions and “combine multiple fields into one column” are tracked separately.
Walkthrough: Configure and use the Expression Builder
Below is a common scenario—exporting a trip’s transport charges total and a formatted pickup date/time—built as two export columns.
Before you start:
Make sure you have a custom export mapping open or create a new one.
Identify the entity you’re exporting from, such as orders.
Column A: Total Transport Charges
Add a new column
Name: Total Transport Charge
Choose a path
Path: orders > charges
This points to the list of all charges on the trip.
Add a filter
Filter path: charge_type
Operator: EQ
Value: Transport
Result: Only charges with type Transport will be considered.
Set an aggregation
Aggregation: SUM
Field summed: amount
Result: Sums the amount across the filtered charges.
Formatting
Numeric format: #,###.00
Cast to string: On, to ensure CSV cells are never blank and are treated as text if required.
Preview
Use Preview to confirm the resulting number matches expectations.
What this does
Starts from the charges list
Filters to charge_type = Transport
Sums the amount
Outputs a formatted string fit for CSV importing in accounting tools.
📚 Where an expression is included, details are shown in brackets.
Column B: Pickup Datetime (US format)
Add a new column
Name: Pickup Date/time (US)
Choose a path
Path: trip > pickup_datetime
Formatting
Datetime format: yyyy-MM-dd HH:mm:ss
Example: 2025-12-31 16:45:00
Cast to string: On, to keep CSV output consistent.
Preview
Confirm date and time appear in the requested format.
What this does
Reads the trip’s pickup date/time and outputs it in a clear, consistent format for downstream tools.
Export
Save the mapping and run the export. Your CSV will include both columns using the transformation rules you configured.
Charge-Type Filter Options
You can now apply filters to expressions that reference charges, giving you full control over which charges are included in your calculation.
1. Surcharges – Now Fully Supported
Previously, the Data Feed only exposed index surcharges (fuel surcharges), which meant UI and export logic were not aligned.
The Expression Builder now supports two configuration options:
Surcharges (all types)
Includes all surcharge types used in the UI:General surcharges
Index surcharges (FSC)
Any future surcharge types
Other surcharges (excluding FSC)
Designed for cases like Mulgrews, where FSC should not be mixed into the surcharge bucket.
This gives teams flexibility to choose the behaviour that matches their reporting model.
2. Extras Revenue (New Category)
You can now select Extras as a dedicated category.
Extras include:
All charges where
addon_type≠ surchargeAny ad-hoc charges
This makes it easy to calculate “All revenue except transport/fuel” or to report on miscellaneous charge items.
3. Consistent Filtering Across UI and Export
The Expression Builder now uses the same charge-filtering logic as Qargo’s pricing UI, including:
Filtering out approved DONT_INVOICE charges
Correct handling of transport charges
Full alignment with existing frontend behaviour
This ensures that what users see in the UI matches what they get in exports and automated calculations — no surprises.
Tips
Start with a path and a single filter, then add aggregation and formatting once your preview looks right.
Use COUNT or EXISTS when you need a yes/no or a simple quantity of matches.
Use DISTINCT to de‑duplicate values when exporting lists into a single cell.
Advanced: Expression mode
Workspace admins can switch to a raw expression mode to author complex logic directly. This is useful for edge cases where the form-based builder is too limited. Keep in mind that saved expressions should be documented for maintainability.
Troubleshooting
Empty cells: Turn on Cast to string to avoid blank values being misread by spreadsheet tools.
Unexpected totals: Check your filter operator and value spelling. Verify the path points to the list you intend.
Date formatting: Confirm the date/time format string and whether the source field contains a date or a date‑time.