Skip to content
amCharts 4

DataSource

Type class

Represents a single data source - external file with all of its settings, such as format, data parsing, etc.

chart.dataSource.url = "http://www.myweb.com/data.json";
chart.dataSource.parser = am4core.JSONParser;

chart.dataSource.url = "http://www.myweb.com/data.json";
chart.dataSource.parser = am4core.JSONParser;

{
  // ...
  "dataSource": {
    "url": "http://www.myweb.com/data.json",
    "parser": "JSONParser"
  },
  // ...
}

More info: IDataSourceEvents for a list of available events

More info: IDataSourceAdapters for a list of available Adapters

Sources

DataSource can be used (imported) via one of the following packages.

/**
 * Import from: "core.ts"
 * Use like: am4core.DataSource
 */
import * as am4core from "@amcharts/amcharts4/core";

Inheritance

DataSource extends BaseObjectEvents.

DataSource is not extended by any other symbol.

Properties

adapter

Type Adapter <DataSource, IDataSourceAdapters>Default new Adapter<DataSource, IDataSourceAdapters>(this)

Adapter.

component

Type Component

A Component recipient of the data.

data

Type any

Loaded and parsed data.

dateFormatter

Type DateFormatter

A DateFormatter to use when parsing dates from string formats.

Will inherit and use chart's DateFormatter if not ser.

disableCache

Type boolean

If set to true it will timestamp all requested URLs to work around browser cache.

incremental

Type booleanDefault false

Should subsequent reloads be treated as incremental?

Incremental loads will assume that they contain only new data items since the last load.

If incremental = false the loader will replace all of the target's data with each load.

This setting does not have any effect trhe first time data is loaded.

NOTE: this setting works only with element's data property. It won't work with any other externally-loadable data property.

incrementalParams

Type object

An object consisting of key/value pairs to apply to an URL when data source is making an incremental request.

keepCount

Type booleanDefault false

This setting is used only when incremental = true. If set to true, it will try to retain the same number of data items across each load.

E.g. if incremental load yeilded 5 new records, then 5 items from the beginning of data will be removed so that we end up with the same number of data items.

language

Type Language

Language instance to use.

Will inherit and use chart's language, if not set.

lastLoad

Type Date

Holds the date of the last load.

parser

Type DataParserDefault JSONParser

A parser to be used to parse data.

chart.dataSource.url = "http://www.myweb.com/data.json";
chart.dataSource.parser = am4core.JSONParser;

chart.dataSource.url = "http://www.myweb.com/data.json";
chart.dataSource.parser = am4core.JSONParser;

{
  // ...
  "dataSource": {
    "url": "http://www.myweb.com/data.json",
    "parser": {
      "type": "JSONParser"
    }
  },
  // ...
}
reloadFrequency

Type number

Data source reload frequency.

If set, it will reload the same URL every X milliseconds.

requestOptions

Type INetRequestOptions

Custom options for HTTP(S) request.

At this moment the only option supported is: requestHeaders, which holds an array of objects for custom request headers, e.g.:

chart.dataSource.requestOptions.requestHeaders = [{
  "key": "x-access-token",
  "value": "123456789"
}];

chart.dataSource.requestOptions.requestHeaders = [{
  "key": "x-access-token",
  "value": "123456789"
}];

{
  // ...
  "dataSource": {
    // ...
    "requestOptions": {
      "requestHeaders": [{
        "key": "x-access-token",
        "value": "123456789"
      }]
    }
  }
}

NOTE: setting this options on an-already loaded DataSource will not trigger a reload.

showPreloader

Type booleanDefault true

Will show loading indicator when loading files.

updateCurrentData

Type booleanDefault falseSince 2.5.5

If set to true, each subsequent load will be treated as an update to currently loaded data, meaning that it will try to update values on existing data items, not overwrite the whole data.

This will work faster than complete update, and also will animate the values to their new positions.

Data sources across loads must contain the same number of data items.

Loader will not truncate the data set if loaded data has fewer data items, and if it is longer, the excess data items will be ignored.

NOTE: this setting is ignored if incremental = true.

url

Type string

URL of the data source.

5 inherited items
clonedFrom

Type $type.Optional <this>Inherited from BaseObject

Reference to the original object this object was cloned from. We need to keep this so we can disassociate it from source object when this object is disposed.

config

Type objectInherited from BaseObject

Use this property to set JSON-based config. When set, triggers processing routine, which will go through all properties, and try to apply values, create instances, etc.

Use this with caution, as it is a time-consuming process. It's used for initialchart setup only, not routine operations.

events

Type EventDispatcher <AMEvent <this, IBaseObjectEvents>>Inherited from BaseObjectEvents

An EventDispatcher instance

id

Type $type.Optional <string>Inherited from BaseObject

Sets the user-defined id of the element.

uid

Type stringInherited from BaseObject

Returns object's internal unique ID.

Methods

addUrlParams(url: string,
params: object)

Returns string

Adds parameters to url as query strings. Will take care of proper separators.

constructor(url?: string,
parser?: string | DataParser)

Returns DataSource

Constructor

dispose()

Returns void

Disposes of this object.

load()

Returns void

Initiate the load.

All loading in JavaScript is asynchronous. This function will trigger the load and will exit immediately.

Use DataSource's events to watch for loaded data and errors.

timestampUrl(url: string)

Returns string

Adds current timestamp to the URL.

6 inherited items
clone(cloneId?: string)

Returns thisInherited from BaseObject

Makes a copy of this object and returns the clone. Try to avoid cloning complex objects like chart, create new instances if you need them.

copyFrom(source: this)

Returns voidInherited from BaseObjectEvents

Copies all parameters from another Sprite.

dispatch(eventType: Key,
data?: any)

Returns voidInherited from BaseObjectEvents

Dispatches an event using own event dispatcher. Will automatically populate event data object with event type and target (this element).

It also checks if there are any handlers registered for this sepecific event.

dispatchImmediately(eventType: Key,
data?: any)

Returns voidInherited from BaseObjectEvents

Works like dispatch, except event is triggered immediately, without waiting for the next frame cycle.

getCurrentThemes()

Returns ITheme[]Inherited from BaseObject

Returns a list of themes that should be applied to this element. It could either be a list of themes set explicitly on this element, or system-wide.

isDisposed()

Returns booleanInherited from BaseObject

Returns if this object has been already been disposed.

Events

done

Param { type: "done", target: DataSource, data: any }

Invoked when data source was successfully loaded and parsed.

ended

Param { type: "ended", target: DataSource }

Invoked when loading and parsing finishes.

error

Param { type: "error", target: DataSource, code: number, message: string }

Invoked when data source encounters a loading error.

loadended

Param { type: "loadended", target: DataSource }

Invoked when the loading of the data finishes.

loadstarted

Param { type: "loadstarted", target: DataSource }

Invoked when loading of the data starts.

parseended

Param { type: "parseended", target: DataSource }

Invoked when parsing of the loaded data finishes.

parseerror

Param { type: "parseerror", target: DataSource, message: string }

Invoked when data source encounters a parsing error.

parsestarted

Param { type: "parsestarted", target: DataSource }

Invoked when parsing of the loaded data starts.

started

Param { type: "started", target: DataSource }

Invoked when loading of the data starts.

Adapters

dateFields

Param string[]

Applied to the array that lists fields in data that hold date-based values.

incremental

Param boolean

Applied to incremental setting.

incrementalParams

Param object

Applied to incrementalParams setting.

keepCount

Param boolean

Applied to keepCount setting.

numberFields

Param string[]

Applied to the array that lists fields in data that hold numeric values.

parsedData

Param any

Applied to the loaded data after it was parsed by a parser.

parser

Param DataParser

Applied to a parser type, before parsing starts.

Can be used to supply different parser than the one set/determined by Data Loader.

parserOptions

Param any

Applied to parser options.

reloadTimeout

Param number

Applied to the timeout setting.

requestOptions

Param INetRequestOptions

Applied to the custom request options object.

unparsedData

Param string

Applied to the loaded data before it is passed to parser.

updateCurrentData

Param boolean

Applied to updateCurrentData setting.

url

Param string

Applied to a data source URL before it is loaded.