Mapping is the process of defining how fields contained in the data source are treated and presented within the component. For mapping in Flexmonster, you can use the MappingObject, which is a property of the DataSourceObject.
The MappingObject is available for all data sources but with some differences.
For JSON, CSV, and the custom data source API, it’s possible to define field data types and captions, group fields under separate dimensions, create multilevel hierarchies, and more. For SSAS, it’s possible to set captions for dimensions and measures. For data from Elasticsearch, it’s possible to customize hierarchy captions, formats, time zones, control field visibility, and more.
This guide contains the following sections:
The MappingObject has the following properties:
(uniqueName)
— Object | Array of objects. Allows setting the mapping for a specific field from the dataset. (uniqueName)
is the field’s unique name."json"
and "csv"
data source types, it is possible to create several fields from a certain field. It can be done by specifying the mapping as an array of objects, where each object is a new field. Learn more in our guide.caption
optional — String. The hierarchy’s caption. type
optional — String. The field’s data type. Only for "json"
, "csv"
, and "api"
data source types. type
can be:"string"
— The field stores string data."number"
— The field stores numerical data. It can be aggregated with all available aggregations."month"
— The field stores months. Note that if the field stores month names only (in either short or full form), the field will be recognized by Flexmonster as a field of the "month"
type automatically. If the field contains custom month names, specify its type as "month"
explicitly."weekday"
— The field stores days of the week."date"
— The field stores a date. Fields of this type are split into 3 different fields: Year, Month, Day. Only for "json"
and "csv"
data source types."year/month/day"
— The field stores a date. It’s displayed as a multilevel hierarchy with the following levels: Year > Month > Day. Only for "json"
and "csv"
data source types."year/quarter/month/day"
— The field is a date. It’s displayed as a multilevel hierarchy with the following levels: Year > Quarter > Month > Day. Only for "json"
and "csv"
data source types."date string"
— The field stores a date. Fields of this type are represented as strings and can be used in rows, columns, or report filters. The component sorts members of such a field as dates."date string"
fields are rounded down with the "1d"
interval (i.e., "04/25/2021T21:30:05"
is rounded down to "04/25/2021T00:00:00"
). If needed, you can set a custom interval for a field. Learn more about intervals."date string"
type can be formatted using the datePattern option (the default pattern is "dd/MM/yyyy"
)."datetime"
— The field stores a date. You can select fields of this type for values."datetime"
type can be formatted using the dateTimePattern option (the default pattern is "dd/MM/yyyy HH:mm:ss"
)."time"
— The field stores time. The "time"
type is used for fields that store a time interval (e.g., duration or elapsed time), which is not related to a specific date."HH:mm:ss"
)."id"
— The field is an id. This field is not shown in the Field List. Fields of this type can be used for editing data."property"
— The field for setting member properties. This field is not shown in the Field List. For example, it can be used to associate a productID
with a product
. See an example here.hierarchy
optional — String. The hierarchy’s name. When configuring hierarchies, specify this property to mark the field as a level of a hierarchy or as a member property of a hierarchy (in this case, the type
parameter should be set to "property"
). Only for "json"
, "csv"
, and "api"
data source types.parent
optional — String. The unique name of the parent level. This property is necessary if the field is a level of a hierarchy and has a parent level. Only for "json"
, "csv"
, and "api"
data source types.folder
optional — String. The field’s folder. Folders are used to group several fields in the Field List. folder
supports nesting via /
(e.g., "Folder/Subfolder/"
). Only for "json"
, "csv"
, and "api"
data source types.aggregations
optional — Array of strings. This property represents the list of aggregation functions that can be applied to the current measure."csv"
and "json"
data source types, you can also define available aggregations for all fields of a certain type.filters
optional — Boolean. This property allows enabling and disabling the UI filters for a specific hierarchy. When set to false
, the UI filters are disabled. Default value: true
.visible
optional — Boolean. When set to false
, hides the field from the Field List. Only for "elasticsearch"
, "json"
, "csv"
, and "api"
data source types. interval
optional — String. Allows rounding down dates by the given interval. For example, if the interval
is "1d"
, 2021-05-25T21:30:00
will be rounded to 2021-05-25T00:00:00
. See an example on JSFiddle.interval
property can be used in the following ways: "date string"
and "datetime"
field types. Supported date intervals are the following:"y"
for one year (e.g., "y"
)."q"
for one quarter (e.g., "q"
)."M"
for one month (e.g., "M"
)."w"
for one week (e.g., "w"
)."d"
for days (e.g., "1d"
). Note that rounding by days starts from 1 January 1970. "h"
for hours (e.g., "7h"
)."m"
for minutes (e.g., "20m"
)."s"
for seconds (e.g., "30s"
)."y"
, "q"
, "M"
, and "w"
intervals should be used without numbers. Only for "csv"
and "json"
data source types.interval
was deprecated in Elasticsearch version 7.2 and removed in version 8. If your Elasticsearch version is higher than 7.2, use either calendar_interval or fixed_interval properties instead of the interval
."elasticsearch"
data source type.calendar_interval
optional — String. Sets the Elasticsearch’s calendar_interval parameter for the date histogram. This parameter allows rounding down dates by the given interval. For example, if the calendar_interval
is "day"
, 2021-05-25T19:30:00
will be rounded to 2021-05-25T00:00:00
. See an example on JSFiddle."day"
.
fixed_interval
optional — String. Sets the Elasticsearch’s fixed_interval parameter for the date histogram. This parameter allows rounding down dates by the given interval. For example, if the fixed_interval
is "3h"
, 2021-05-25T19:30:00
will be rounded to 2021-05-25T18:00:00
. See an example on JSFiddle.isMeasure
optional — Boolean. When set to true
, the field can be selected only as a measure. The isMeasure
property should be used only with the strictDataTypes option (see an example on JSFiddle). Only for the "json"
data source type. Default value: false
.time_zone
optional — String. Used for the date histogram. You can specify time zones as either an ISO 8601 UTC offset (e.g., +01:00
or -08:00
) or as a time zone ID as specified in the IANA time zone database, such as America/Los_Angeles
. Only for the "elasticsearch"
data source type. Check out an example here.format
optional — String. Used to format different types of date fields. format
can be used in the following ways:format
will override its value for the field."elasticsearch"
data source type."date string"
type, it allows overriding the datePattern set in the OptionsObject. The pattern string for the format
is the same as in the datePattern
option (i.e., "dd/MM/yyyy"
). Only for "json"
, "csv"
, and "api"
data source types. Learn more about date and time formatting."datetime"
type, it allows overriding the dateTimePattern set in the OptionsObject. The pattern string for the format
is the same as in the dateTimePattern
option (i.e., "dd/MM/yyyy HH:mm:ss"
). Only for "json"
, "csv"
, and "api"
data source types. Learn more about date and time formatting."time"
type, it allows overriding the timePattern set in the OptionsObject. The pattern string for the format
is the same as in the timePattern
option (i.e., "HH:mm:ss"
). Only for "json"
, "csv"
, and "api"
data source types. Learn more about date and time formatting.min_doc_count
optional — Number. Only for the "elasticsearch"
data source type. Used for the date histogram. Can be used to show intervals with empty values (min_doc_count: 0
). Default value: 1
(empty intervals are hidden).aggregations
optional — Object. Available aggregation functions for all fields of a certain type. See an example on JSFiddle. Only for "json"
and "csv"
data source types.aggregations
object can have the following properties:date
optional — Array of strings. Available aggregation functions for the "date string"
field type.number
optional — Array of strings. Available aggregation functions for the "number"
field type.string
optional — Array of strings. Available aggregation functions for the "string"
field type.time
optional — Array of strings. Available aggregation functions for the "time"
field type.In Flexmonster, there are two ways to define the mapping:
The inline mapping can be defined as follows:
report: { dataSource: { filename: "data.csv", mapping: { "Month": { "type": "month" }, "Company Name": { "type": "string" }, "Region": { "type": "string", "hierarchy": "Geography" }, "State": { "type": "string", "parent": "region", "hierarchy": "Geography" }, "Price": { "type": "number", "caption": "Unit Price" } } } }
See the full code on JSFiddle.
To define the mapping as a URL to a file, complete the steps below.
Step 1. Create a new JSON file with the mapping (e.g., mapping.json
). Its contents should look similar to the following:
{
"Month": {
"type": "month"
},
"Company Name": {
"type": "string"
},
"Region": {
"type": "string",
"hierarchy": "Geography"
},
"State": {
"type": "string",
"parent": "region",
"hierarchy": "Geography"
},
"Price": {
"type": "number",
"caption": "Unit Price"
}
}
Step 2. Put your mapping file where Flexmonster can access it.
Step 3. In Flexmonster, define the mapping as a URL to your file:
report: { dataSource: { filename: "data.csv", mapping: "<URL_to_your_mapping_file>" } }
See a live sample on JSFiddle.
Using the mapping, you can create multilevel hierarchies from non-hierarchical data. This feature is supported for JSON, CSV, Flexmonster Data Server, MongoDB, and custom data source API.
Note In the custom data source API, multilevel hierarchies should be supported on the server side as well. Learn more in this guide: Supporting multilevel hierarchies.
To configure multilevel hierarchies in the component, specify the hierarchy and parent properties in the mapping.
The example below illustrates how to configure multilevel hierarchies. We create the "Geography"
hierarchy with the "Country"
field as a first level, "State"
field as a second level, and "City"
field as a third level:
report: { dataSource: { filename: "data.json", mapping: { "Country": { hierarchy: "Geography", }, "State": { hierarchy: "Geography", parent: "Country" }, "City": { hierarchy: "Geography", parent: "State" } } } }
See a live example on JSFiddle.
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, 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 instead of an object, we used an array of objects as a mapping value. Each object describes a separate field that will be created.
Every new field should have its own uniqueName
property. As for other mapping properties, you can use any property available for your data source.
After you have defined the needed fields, you can include them in the slice as ordinary fields:
report: { slice: { rows: [ { uniqueName: "DateString" } ], ... } }
See a live sample on JSFiddle.
Starting from version 2.8.33, you can define available aggregations for fields of a "number"
, "string"
, "date"
, or "time"
type.
To define aggregations for a certain field type, specify an array with them in the aggregations.[field_type] property. For example:
mapping: { aggregations: { "number": [ "sum", "average" ], "date": [ "max", "min" ], "string": [ "count", "distinctcount" ] } }
See the full code on JSFiddle. As a result, the following aggregations will be available:
"sum"
and "average"
."max"
and "min"
."count"
and "distinctcount"
.It’s not necessary to define aggregations for all field types. If a type is not listed in the aggregations
property, a field of this type will have aggregations available by default.
When using the custom data source API, you can define supported aggregations for all fields of a certain type in the aggregations property of the /fields request.
Learn more about aggregations in the custom data source API here: Supporting more aggregation functions.
1) Creating multilevel hierarchies in JSON:
mapping: {
"Color": {
type: "string"
},
"Country": {
type: "string",
hierarchy: "Geography"
},
"State": {
type: "string",
hierarchy: "Geography",
parent: "Country"
},
"City": {
type: "string",
hierarchy: "Geography",
parent: "State"
},
"Price": {
type: "number"
}
}
Try the live demo on JSFiddle.
2) Setting custom captions and field data types as well as creating multilevel hierarchies in a CSV data source:
mapping: { "Order ID": { type: "string" }, "Month": { type: "month" }, "Company Name": { type: "string" }, "Customer": { type: "string" }, "region": { caption: "Region", type: "string", hierarchy: "Geography" }, "State": { type: "string", parent: "region", hierarchy: "Geography" }, "City": { type: "string", parent: "State", hierarchy: "Geography" }, "Salesperson": { type: "string" }, "Payment Method": { type: "string" }, "Category": { type: "string" }, "Name": { type: "string", caption: "Product Name" }, "price": { type: "number", caption: "Unit Price" }, "Quantity": { type: "number" }, "Revenue": { type: "number" }, "Shipping Cost": { type: "number" } }
Try it on JSFiddle.
3) Setting custom captions and grouping fields in separate folders in a JSON data source:
mapping: {
"Color": {
caption: "color"
},
"Country": {
caption: "MyCountry",
folder: "Place"
},
"State": {
caption: "MyState",
folder: "Place"
},
"City": {
caption: "MyCity",
folder: "Place"
},
"Price": {
type: "number",
caption: "MyPrice"
},
"Quantity": {
type: "number",
caption: "MyQuantity"
}
}
See the live demo on JSFiddle.
4) Specifying custom captions for hierarchies and measures for SSAS:
mapping: {
"[Geography].[Geography]": {
caption: "My Geography"
},
"[Product].[Category]": {
caption: "My Category"
}
}
See the live demo on JSFiddle.