menu SweetData.io
close Home What is SweetData.io? Sign Up Login

What is candy-visualization.json

The `candy-visualization.json` file is a JSON file that describes charts and graphs associated with a candy (dataset) on SweetData.io. The file is a JSON array for which each element represents a chart (JSON objects). ## Chart object The chart object contains several properties: - **title**: *[string]* Title of the chart. - **chartType**: *[string]* Type of the chart (line, pie, donut, bar, area, scatter, barStacked, barStackedFull, areaStacked, areaStackedFull or geo). - **xAxisTitle**: *[string]* Label for the data in the X axis. - **yAxisTitle**: *[string]* Label for the data in the Y axis. - **nColumns**: *[number.integer]* Number of columns the chart should span. (max: 6, min: depends on chart type) - **nRows**: *[number.integer]* Number of rows the chart should span. (min: depends on chart type) - **data**: *[array]* An array of ChartData objects. More info in the *ChartData object* section. ## ChartData object The `ChartData` object described how should the data for the chart be aggregated. In other words, it describes how should the data for this particular chart be gathered from the candy. It has the following properties: - **query**: *[object]* A Query object that describes the request that should be made to the API to retrieve the data to fill the chart. More info in the *Query object* section. - **dataset**: *[string]* The handle of the dataset from which the data should be gathered. This handle is the same as the one defined in the candy.json file. *(Note: this is not the handle of the candy itself, it is the handle of the dataset in the candy.)* - **xField**: *[string]* The name of the field in the API query results that should be used as the X value for the data series. Depending on the chart type, this field can hold numbers, dates or even categories (strings). - **yField**: *[string]* The name of the field in the API query results that should be used as the Y value for the data series. This field usually holds numbers. - **xValuesFormat**: *[string]* The formatting that should be used to display the values of the X axis. (possible values: number.money, number.percentage, number.integer, number.float, date.year, date.timestamp, date.timestampMs) - **yValuesFormat**: *[string]* The formatting that should be used to display the values of the Y axis. (possible values: number.money, number.percentage, number.integer, number.float, date.year, date.timestamp, date.timestampMs) - **title**: *[string]* The title of this data series. - **nPages**: *[string]* (optional, default=1) API Requests have a limit on the number of results they can return. Pagination is used to go retrieve more results. This parameter describes how many pages of results to go through to fill the chart. (max: 5) ## Query object The `Query` object describes a request to SweetData.io API allowing to retrieve data from specific datasets. It allows filtering the data, sorting, limiting the number of results, aggregation (grouping) and it has a pagination system. The following properties allow DB operations: ### filters An array of strings each allowing to filter the DB request. The strings must be formatted as `FIELD_NAME-OPERATION-VALUE` with no spaces. Below are example of operations currently available: - `["A=1"]`: field A equal to 1 - `["A=Hello everyone"]`: field A equal to "Hello everyone" - `["A!=1"]`: field A not equal to 1 - `["A<=1"]`: field A smaller or equal to 1 - `["A>=1"]`: field A greater or equal to 1 - `["A<1"]`: field A smaller than 1 - `["A>1"]`: field A greater than 1 The filters property can also be defined as an Array of Array of strings to form OR operations. E.g. `[["a=1", "b=2"], ["c=3", "d=4"]]` is equivalent to: `(a==1 && b==2) || (c==3 && d==4)` ### sort The sort property allows you to sort the final output of the request. It must be formatted as the name of the field to use for the sort operation. If you want to sort in descending order, prefix the field name with a `-`. E.g. `{"sort":"-amount"}`. ### limit An integer value indication how many results to return. If you use pagination (nPages>1), you should set this value to its maximum: 100. ### fields An array of field names that should be returned by the request. In order to improve performance and network usage, set this field to only return the fields you need for your operation. ### group The group object property allows you to aggregate results by specifying a group field. This is similar to the SQL `GROUP BY` statement. In addition, you can also apply operations on the aggregates such as counting how many entries each group has, adding up values for a particular field, doing averages and more. Below is an example of a query with the group property: ``` { "group": { "by": [ "country" ], "operations": [ { "operation": "avg", "field": "value", "as": "total" } ] } } ``` In this example, entries from a dataset will be grouped by "country" (i.e. one entry per country). In addition, an operation will be applied on each aggregate: The average of the "value" field will be calculated for each country and returned as in a field called "total". Currently supported operations are: - *sum*: Summation - *avg*: Average - *max*: Maximum value - *min*: Minimum value - *count*: Number of entries in aggregate ### joins When data is spread across multiple datasets in a candy, you can use `joins` to retrieve data from other datasets by specified the local and foreign fields. The joins property is an Array of objects each specifying a join operation. A join object is represented as: ``` { "localField" : "countryCode", "joinDataset" : "countries", "joinField" : "countryCode", "as" : "countries" } ``` *Note: the `as` property is optional. By default it takes the value of the `joinField` field.* The join will merge results from a *foreign* dataset (`joinDataset`) into the results of the current query by looking for matching entries for which the `joinField` field have equal values to the `countryCode` field in the query results. The joined dataset join will become a property (`as`) in the query results. ## Grid system for charts When the device screen is large enough, charts are displayed on a grid. The grid has six columns and a varying number of rows. The `nColumns` and `nRows` properties of the Chart object allow you to fill the grid layout with your charts. Charts are inserted in the grid while trying to fill the wholes that are created by other charts. For better looking layouts, it is recommended to span the charts in order to fill all the available space. ## Example Below is an example of two charts used for the [World Development Index](https://sweetdata.io/candy/wdi) candy. The left chart is a map on which the GDP per capital is represented and on the right chart, it is ... ``` [ { "title": "GDP (current US$)", "chartType": "geo", "data": [ { "dataset": "country-indicators", "xField": "countryCode", "yField": "value", "xValuesFormat": "string", "yValuesFormat": "number.money", "title": "GDP per capita by country", "nPages": 3, "query": { "filters": [ "indicatorCode=NY.GDP.PCAP.CD", "year=2018" ], "sort": "-value", "limit": 100, "fields": [ "countryCode", "country.shortName", "value" ] } } ], "xAxisTitle": "Year", "yAxisTitle": "GDP (trillion of US $)", "nColumns": 2, "nRows": 2 }, { "title": "GDP (current US$)", "chartType": "areaStackedFull", "data": [ { "dataset": "country-indicators", "xField": "year", "yField": "total", "xValuesFormat": "date.year", "yValuesFormat": "number.money", "title": "GDP (current US$)", "query": { "filters": [ "indicatorCode=NY.GDP.MKTP.CD" ], "group": { "by": [ "year" ], "operations": [ { "operation": "sum", "field": "value", "as": "total" } ] }, "limit": 100 } }, { "dataset": "country-indicators", "xField": "year", "yField": "total", "xValuesFormat": "date.year", "yValuesFormat": "number.money", "title": "GDP (constant 2010 US$)", "query": { "filters": [ "indicatorCode=NY.GDP.MKTP.KD" ], "group": { "by": [ "year" ], "operations": [ { "operation": "sum", "field": "value", "as": "total" } ] }, "limit": 100 } } ], "xAxisTitle": "Year", "yAxisTitle": "GDP (trillion of US $)", "nColumns": 4, "nRows": 2 } ] ```

Login

OR Create an Account