Mapping

The mapping defines how fields from the data source are treated and presented within the component. 

The mapping is described by the MappingObject, where each key is the field’s unique name, and a value is the FieldMappingObject. The FieldMappingObject contains properties that will be applied to the field.

To see different examples of using the mapping, visit our Examples page.

Usage

You can define the mapping for all data sources but with some differences:

• For JSON, CSV, Flexmonster Data Server, MongoDB, and the custom data source API, you can define field data types and captions, group fields under separate dimensions, create multilevel hierarchies, and more.
  Note If you use Flexmonster Data Server, it is also possible to define field data types on the server.
• For SSAS, you can set captions and manage the visibility of fields and measures.
• For Elasticsearch, you can customize hierarchy captions, formats, time zones, control field visibility, and more. Read more about configuring the mapping in Elasticsearch.

Mapping properties

See the full list of available MappingObject properties.

How to define the mapping

You can define the mapping in the following ways:

1. As an inline MappingObject.
2. As a URL to a JSON file with the mapping.

As an inline MappingObject

The mapping can be defined as an inline MappingObject in the following way:

report: {
  dataSource: {
    filename: "data.csv",
    mapping: {
      "Month": {
        type: "month"
      },
      "Company Name": {
        type: "string"
      },
      "Region": {
        type: "string",
        hierarchy: "Geography"
      },
      // ...
    }
  }
}

Live example

As a URL to a file

To define the mapping as a URL to a file, do the following:

Step 1. Create a new JSON file with the mapping (e.g., mapping.json). Your code should look similar to the following example:

{
  "Month": {
    "type": "month"
  },
  "Company Name": {
    "type": "string"
  },
  "Region": {
    "type": "string",
    "hierarchy": "Geography"
  },
  // ...
}

Step 2. Put your mapping file where Flexmonster can access it.

Step 3. In the report, define the mapping as a URL to your file:

report: {
  dataSource: {
    filename: "data.csv",
    mapping: "<URL_to_your_mapping_file>"
  }
}

Live example

Use cases

Specify a caption for a field

By default, a caption is a field’s uniqueName. To specify the field’s custom caption, use the [field_name].caption property:

report: {
  dataSource: {
    filename: "data.csv",
    mapping: {
      "item_price": {
        caption: "Price"
      },
      // Other fields
    }
  }
}

Live example

Define the type of a field

By default, Flexmonster autodetects the field types. You can manually specify the type of a field when working with JSON, CSV, Flexmonster Data Server, MongoDB, or the custom data source API.

To specify the field type, use the [field_name].type property:

report: {
  dataSource: {
    filename: "data.csv",
    mapping: {
      "Month": {
        type: "month",
      }
    }
  }
}

Live example

Watch the video that demonstrates how a type is set for a field: Mapping in Flexmonster Pivot.

Hide a field in the component

To hide a field in the component, set the [field_name].visible property to false:

report: {
  dataSource: {
    filename: "data.csv",
    mapping: {
      "Country": {
        visible: false,
      }
    }
  }
}

As a result, the "Country" field will be hidden on the grid, charts, and in the Field List Live example.

Group several fields in a folder

To group several fields in the Field List, use the [field_name].folder property:

report: {
  dataSource: {
    filename: "data.csv",
    mapping: {
      "Country": {
        folder: "Place",
      },
      "State": {
        folder: "Place",
      },
      "City": {
        folder: "Place",
      }
    }
  }
}

Live example

This feature is supported for JSON, CSV, Flexmonster Data Server, MongoDB, and the custom data source API.

Note If a root folder contains only one field, this field will be shown without the folder in the Field List.

Format a date field

You can format date fields when working with JSON, CSV, Flexmonster Data Server, MongoDB, the custom data source API, or Elasticsearch.

To format a specific date field, use the [field_name].format property:

report: {
  dataSource: {
    data: [
      // ...
    ],
    mapping: {
      "OrderDate": {
        type: "date string",
        format: "MM/dd/yyyy"
      }
    }
  }
}

Live example

Learn more about date and time formatting.

Define available aggregations for a field

Each field has a list of available aggregations based on the field’s type. You can limit the list to aggregations you need by specifying them in the <uniqueName>.aggregations property:

report: {
  dataSource: {
    filename: "data/data.csv",
    mapping: {
      "Price": {
        aggregations: ["max", "min"]
      }
    }
  }
}

Live example

Limit which fields can be used as measures

By default, any field can be used as a measure. When working with the JSON data source, you can limit which fields are available as measures:

Step 1. Set the isMeasure mapping property to true for fields that should be used as measures:

mapping: {
  "Price": {
    type: "number",
    isMeasure: true
  },
  "Quantity": {
    type: "number",
    isMeasure: true
  }
}

Step 2. Set the report.options.strictDataTypes property to true:

report: {
  options: {
    strictDataTypes: true
  },
  // Other configs
}

As a result, only fields marked with isMeasure: true are available as measures. All other fields can be used only for rows, columns, or report filters Live example.

Configure multilevel hierarchies

In Flexmonster, you can group related fields into a multilevel hierarchy (e.g., Date: Year > Month > Day). Compared to folders or multiple fields in rows or columns, hierarchies provide greater control over data structure and display:

• Fields in a hierarchy are organized in a parent-child structure.
• The hierarchy can be displayed in the pivot table starting from any level.
• Filters respect the hierarchy's parent-child relationships (e.g., filtering a parent cascades to its children).

This feature is supported for JSON, CSV, Flexmonster Data Server, MongoDB, and the custom data source API. Note that in the custom data source API, multilevel hierarchies must be supported on the server side.

To configure multilevel hierarchies, specify the [field_name].hierarchy and [field_name].parent properties in the mapping. Here is an example of creating the "Geography" hierarchy from the "Country", "State", and "City" fields:

report: {
  dataSource: {
    filename: "data.json",
    mapping: {
      "Country": {
        hierarchy: "Geography",
      },
      "State": {
        hierarchy: "Geography",
        parent: "Country"
      },
      "City": {
        hierarchy: "Geography",
        parent: "State"
      }
    }
  }
}

Live example

Watch the video that shows how to create a multilevel hierarchy: Mapping in Flexmonster Pivot.

Creating several fields from one field

Starting from version 2.9, you can create multiple fields from one field and use them separately in the slice. This feature is available for JSON and CSV data sources.

To create several fields from one field, specify the mapping as follows:

dataSource: {
  mapping: {
    "Date": [
      {
        type: "date",
        uniqueName: "DateHierarchical",
        caption: "Date (hierarchical)"
      },
      {
        type: "date string",
        uniqueName: "DateString",
        caption: "Date (string)"
      }
    ],
    // ...
  }
}

Notice that we use an array of FieldMappingObjects as a mapping value for the "Date" field. Each FieldMappingObject describes a separate field that will be created in the component.

Each created field should have a unique value for the uniqueName property. Specify other mapping properties as usual.

After you have defined the necessary fields, include them in the slice as ordinary fields:

report: {
  slice: {
    rows: [
      {
        uniqueName: "DateString"
      }
    ],
    // ...
  } 
}

Live example

Defining available aggregations for fields of a certain type

report: {
  dataSource: {
    filename: "data.json",
    mapping: {
      aggregations: {
        number: [ "sum", "average" ],
        date: [ "max", "min" ],
        string: [ "count", "distinctcount" ]
      }
    }
  }
}

See also

• Mapping examples
• Choose fields for the grid
• Number formatting
• Date and time formatting
• Managing Flexmonster’s functionality