Object Structures
One of the most important things to understand when working with the VS Code extension is the structure of the objects.
There several types of objects:
All objects are declared in .yaml files. A single file may contain a single object or several objects,
defined as separate YAML documents and delimited by ---.
type: dataset
id: customers
# ...
---
type: metric
id: revenue_pre_customer
# ...
This makes it easy to organize larger analytical projects by domain instead of being object type. For example, you can have all customer-related objects in one file and all revenue-related objects in another, etc.
You can also use any folder structure you like, as long as the files are in the source_dir folder
(defined in gooddata.yaml) or its subfolder.
gooddata.yaml
gooddata.yaml is a configuration file that contains settings for the project and must be located in the project root. It is also used to define the profiles.
The profile is a set of settings that determine which workspace you connect to and which data source should be used to connect data.
The easiest way to create a profile file is through the CLI with gd init command.
The structure is as follows:
profiles:
[name]: # Name of the profile
host: # Base URL
token: # API token variable [DO NOT HARDCODE]
workspace_id: #ID of the workspace
data_source_id: #ID of the data source
source_dir: # Folder where to store/load the metrics and datasets
default_profile: # The profile to use when none is provided
experimental_features: # Optional, a list of experimental features
[feature_name]: # A boolean flag to enable/disable the feature
You can add as many profiles as you need. The default_profile is the profile that will be used when none is provided when running a CLI command.
The host is the base URL of the GoodData platform. It is the same for all workspaces and is usually in the form of https://<your_domain>.gooddata.com/.
The token refers to the name of the environment variable, which stores the API token. We recommend defining the token variable in the .env file and ensuring it’s added to .gitignore to avoid sharing it publicly.
The workspace_id is an ID of the actual workspace, which you will be cloning and deploying to. You can find it in the URL of your GoodData web interface when you are in the workspace.
The data_source_id is an ID of the data source used in the workspace. You can find it in the list of data sources in your UI.
Example
profiles:
local:
host: https://localhost:3000/
token: $GOODDATA_API_TOKEN_LOCAL
workspace_id: gdc_demo_730b50f8-8a93-4723-a872-64dca815a616
data_source_id: gdc_demo_c2066bb5-bb14-419a-8172-239a380ffb49
dev:
host: https://mamma_mia.trial.cloud.gooddata.com/
token: $GOODDATA_API_TOKEN_DEV
workspace_id: gdc_demo_730b50f8-8a93-4723-a872-64dca815a616
data_source_id: gdc_demo_c2066bb5-bb14-419a-8172-239a380ffb49
prod:
host: https://my-company.gooddata.com/
token: $GOODDATA_API_TOKEN_PROD
workspace_id: gdc_demo_730b50f8-8a93-4723-a872-64dca815a616
data_source_id: gdc_demo_c2066bb5-bb14-419a-8172-239a380ffb49
source_dir: analytics
default_profile: dev
Dataset
The dataset is a logical entity representing facts, attributes, and attribute labels. To learn more about the datasets, see the Dataset section.
The structure of the .yaml dataset file is as follows:
type: dataset
id: # The Dataset ID. This ID is further used to refer to this instance of the dataset.
title: # An optional human-readable title for the dataset. Derived from id, when not provided explicitly.
description: # An optional description of the dataset
tags: # An optional list of tags
# Define the source of the data either as table path or SQL statement
table_path: # A table path in the data source delimited by the `/` character
sql: # An optional SQL statement to define the dataset
primary_key: # Either a single field id or a list of field ids in case of a composite primary key.
fields:
[field_name]:
type: # The type of the field, one of fact, attribute
title: # An optional human-readable title for the dataset. Derived from file name, when not provided explicitly.
description: # An optional description of the field
tags: # An optional list of tags
source_column: # An optional source column for the field, defaults to the field name
data_type: # A datatype of the source column, one of "INT", "STRING", "DATE", "NUMERIC", "TIMESTAMP", "TIMESTAMP_TZ", "BOOLEAN"
sort_column: # A column name in the source table to do sorting by
sort_direction: # A direction of the sorting, one of "ASC", "DESC"
default_view: # Default label to use in the case of attribute type of field with multiple labels.
labels: # Optional list of attribute labels in the case of attribute type of field
[label_name]:
title: # An optional human-readable title for the dataset. Derived from label name, when not provided explicitly.
description: # An optional description of the label
tags: # An optional list of tags
source_column: # An optional source column for the label, defaults to the label name
data_type: # A datatype of the source column
value_type: # A type of the label, one of "TEXT", "HYPERLINK", "GEO", "GEO_LONGITUDE", "GEO_LATITUDE"
references: # A list of references to other datasets
- dataset: # An ID of the referenced dataset
sources: # A list of source fields to connect by
- target: # A primary key field in the referenced dataset we are connecting by
source_column: # A database column we are connecting by, in this dataset
data_type: # A data type of the source column
multi_directional: # Defines if dataset connection can work in both directions. Optional, defaults to false.
Example
type: dataset
id: customers
table_path: SCHEMA/customers
title: Customers
tags:
- customer
- ecommerce
- retail
description: A dataset containing information about customers.
primary_key: customer
fields:
customer:
type: attribute
title: Customer id
data_type: STRING
default_view: customer_name
labels:
customer_id:
data_type: STRING
value_type: TEXT
customer_name:
data_type: STRING
value_type: TEXT
customer_age:
type: fact
data_type: INT
region:
type: attribute
data_type: STRING
state:
type: attribute
data_type: STRING
labels:
geo__state__location:
title: State - Geolocation
description: Location of the state
data_type: GEO
Date Dataset
A date dataset is a dataset in the logical data model (LDM) representing the DATE / TIMESTAMP columns in your database. The date dataset helps you manage time-based data and enables aggregation at the day, week, month, quarter, and year levels.
To learn more and see the list of possible granularities, refer to the Dataset section.
The structure is as follows:
type: date
id: # ID of a date dataset. It has to be unique.
title: # An optional human-readable title for the dataset. Derived from id, when not provided explicitly.
description: # An optional description of the dataset
tags: # An optional list of tags
granularities:
# A list of granularities supported by the date dataset. The list can contain any of the following values:
# MINUTE, HOUR, DAY, WEEK, MONTH, QUARTER, YEAR, MINUTE_OF_HOUR, HOUR_OF_DAY,
# DAY_OF_WEEK, DAY_OF_MONTH, DAY_OF_YEAR, WEEK_OF_YEAR, MONTH_OF_YEAR, QUARTER_OF_YEAR
title_base: # A base title to be used in the title pattern, if omitted, the dataset title is used
title_pattern: # A pattern for the title formatting, e.g. "%titleBase - %granularityTitle"
Example
type: date
id: purchase_date
title: Purchase Date
description: A date dimension representing the purchase date
tags: ["Date"]
granularities:
- MINUTE
- HOUR
- DAY
- WEEK
- MONTH
- QUARTER
- YEAR
- MINUTE_OF_HOUR
- HOUR_OF_DAY
- DAY_OF_WEEK
- DAY_OF_MONTH
- DAY_OF_YEAR
- WEEK_OF_YEAR
- MONTH_OF_YEAR
- QUARTER_OF_YEAR
title_base: ""
title_pattern: "%titleBase - %granularityTitle"
Metric
A metric is a computational expression of numerical data (facts or other metrics). For example, you can have metrics representing the average invoice sum or the number of sold items per country.
They are built using MAQL and follow a formatting convention.
The structure of the metric representation in .yaml is as follows:
type: metric
id: # ID of a metric. It has to be unique
title: # An optional human-readable title for the dataset. Derived from id, when not provided explicitly.
description: # An optional description of the metric
tags: # An optional list of tags
maql: # The actual maql statement. e.g : SELECT AVG(SELECT {metric/net_sales} BY {label/customer_id})
format: # Formatting of the result. e.g : 123.4k$ vs. 123456.78
Example
type: metric
id: percent_revenue
title: "% Revenue"
description: Percent of Total Revenue
maql: SELECT {metric/revenue} / {metric/total_revenue}
format: "#,##0.0%"
Visualization
A visualization is a representation of data in a graphical form.
The structure of the visualization representation in .yaml is as follows:
type: # A type of specific visualization, one of:
# table, bar_chart, column_chart, line_chart, area_chart, scatter_chart,
# bubble_chart, pie_chart, donut_chart, treemap_chart, pyramid_chart, funnel_chart,
# heatmap_chart, bullet_chart, waterfall_chart, dependency_wheel_chart,
# sankey_chart, headline_chart, combo_chart, geo_chart
id: # ID of a visualization. It has to be unique
title: # An optional human-readable title for the visualization. Derived from id, when not provided explicitly.
description: # An optional description of the visualization
tags: # An optional list of tags
query: # Defines the data used in this visualization
fields:
[field_name]: # A field definition. The definition varies significantly on type of field, described below
filter_by:
- # An array of filters, described below
sort_by:
- # An array of sorting, described below
# ... visualization data buckets
"[bucket_name]":
- # A single string id of the field defined in query, or...
- field: # field id from the query
format: # A format of the numeric field, e.g. "#,##0.0"
axes: # Axis to use for this bucket. Only applicable for "combo" charts. One of "primary", "secondary"
totals: # An optional list of totals, mainly for the table visualization
- type: # Aggregation type, one of "SUM", "AVG", "MAX", "MIN", "MED", "NAT"
title: # A total title
using: # A field id from the query to use for the total
config: # Visualization configuration
Specific set of buckets and configuration options differ depending on visualization type. This defines which metrics will be shown at which axes, or how exactly the data will be sliced, colored and rendered.
Refer to the Visualization section for more information.
Query Fields
Each field in the query can be defined as a simple id referring to specific attribute, label, fact or metric, or as a more complex object with additional properties.
# for attribute field
title: # An optional human-readable title for the visualization. Will be derived from id if not provided explicitly.
using: # Defines which attribute to be used for this field
show_all_values: # A boolean flag to show all values, including NULL and empty values
---
# for metric
title: # An optional human-readable title for the visualization. Will be derived from id if not provided explicitly.
using: # Defines which metric to be used for this field
compute_ratio: # A boolean flag to compute a ratio of this metric
filter_by:
- # An optional list of filter to apply to this metric, same format as Query Filters described below
---
# for calculated metric
title: # An optional human-readable title for the visualization. Will be derived from id if not provided explicitly.
using: # Defines which fact, attribute or label to be used for this field
aggregation: # An aggregation type, one of SUM, COUNT, APPROXIMATE_COUNT, AVG, MIN, MAX, MEDIAN, RUNSUM
compute_ratio: # A boolean flag to compute a ratio of this metric
filter_by:
- # An optional list of filter to apply to this metric, same format as Query Filters described below
---
# for inline metric
title: # A field title
maql: # A maql statement
---
# for arithmetic metric
title: # A field title
operator: # An operator, one of "SUM", "DIFFERENCE", "MULTIPLICATION", "RATIO", "CHANGE"
using: # An array of exactly two fields to use for the operation
---
# for period over period / previous period metric
title: # A field title
type: PREVIOUS_YEAR | PREVIOUS_PERIOD
using: # Defines which metric to be used for this field
date_filter: # Relative date filter to use for the period over period comparison
period: # In case of PREVIOUS_PERIOD, defines how many periods to go back
Query Filters
# absolute date filter
type: date_filter
using: # A date dataset id to use for the filter
from: # A string with specific date, e.g. "2020-01-01"
to: # A string with specific date, e.g. "2020-01-01"
---
# relative date filter
type: date_filter
using: # A date dataset id to use for the filter
granularity: # A granularity to use for the filter, one of MINUTE, HOUR, DAY, WEEK, MONTH, QUARTER, YEAR,
# MINUTE_OF_HOUR, HOUR_OF_DAY, DAY_OF_WEEK, DAY_OF_MONTH, DAY_OF_YEAR, WEEK_OF_YEAR,
# MONTH_OF_YEAR, QUARTER_OF_YEAR
from: # A number specifying how many periods to start from, e.g. -1 for previous period
to: # A number specifying how many periods to end with, e.g. -2 for two periods ago
---
# attribute filter
type: attribute_filter
using: # An attribute or attribute label id to use for the filter
state: # the default state of the filter, should contain either include or exclude
include: # An array of attribute values to include
exclude: # An array of attribute values to exclude
---
# metric value comparison filter
type: metric_value_filter
using: # A metric id to use for the filter
condition: # A condition to use for the filter, one of GREATER_THAN, GREATER_THAN_OR_EQUAL_TO, LESS_THAN,
# LESS_THAN_OR_EQUAL_TO, EQUAL_TO, NOT_EQUAL_TO
value: # A value to compare the metric with
null_values_as_zero: # A boolean flag to treat NULL values as zero
---
# metric range filter
type: metric_value_filter
using: # A metric id to use for the filter
condition: # A condition to use for the filter, one of BETWEEN, NOT_BETWEEN
from: # A value to start the range from
to: # A value to end the range with
null_values_as_zero: # A boolean flag to treat NULL values as zero
---
# ranking filter
type: ranking_filter
using: # A metric id to use for the filter
attribute: # An attribute id to use for the filter
bottom: # A number of bottom values to include
# ...or...
top: # A number of top values to include
Query Sorting
# attribute sort
type: attribute_sort
by: # An attribute id to use for the sorting
aggregation: # An aggregation type, only SUM at the moment
direction: # A direction of the sorting, one of ASC, DESC
---
# metric sort
type: metric_sort
metrics: # An array of metric ids to use for the sorting
- # A metric id
- by: # A metric id
element: # An attribute id to use for the sorting
function: # An aggregation type, one of SUM, AVG, MIN, MAX, MED, NAT
direction: # A direction of the sorting, one of ASC, DESC
Field Buckets
Depending on the type of visualization, the fields are divided into different buckets. The buckets are used to define how the data will be sliced or grouped.
| Visualization type | Buckets |
|---|---|
| Headline chart | metrics |
| Pie chart | metrics, view_by |
| Donut chart | metrics, view_by |
| Pyramid chart | metrics, view_by |
| Funnel chart | metrics, view_by |
| Bullet chart | metrics, view_by |
| Waterfall chart | metrics, view_by |
| Combo chart | metrics, view_by |
| Scatter chart | metrics, view_by (alias attributes) |
| Dependency wheel | metrics, view_by (alias from, to) |
| Sankey chart | metrics, view_by (alias from, to) |
| Treemap chart | metrics, view_by, segment_by |
| Geo chart | metrics, view_by, segment_by |
| Table | metrics, view_by (alias rows), segment_by (alias columns) |
| Heatmap chart | metrics, view_by (alias rows), segment_by (alias columns) |
| Bar chart | metrics, view_by, segment_by (alias stack_by) |
| Column chart | metrics, view_by, segment_by (alias stack_by) |
| Area chart | metrics, view_by, segment_by (alias stack_by) |
| Line chart | metrics, view_by (alias trend_by), segment_by |
| Bubble chart | metrics, view_by, segment_by (alias size_by) |
Configuration options
For visualization config options, refer to GoodData.UI Reference.
Dashboard
A dashboard is a graphical summary of information that presents various aspects of your data.
The structure of the dashboard representation in .yaml is as follows:
type: dashboard
id: # A unique identifier of the dashboard
title: # An optional human-readable title for the visualization. Derived from id, when not provided explicitly.
description: # An optional description of the visualization
tags: # An optional list of tags
filters: # An optional map of filters to apply to the dashboard
[filter_name]: # Absolute date filter
type: date_filter
title: # An optional human-readable title for the filter
mode: # A mode the filter is working in, one of "readonly", "hidden", "active"
date: # A date dataset id to use for the filter (omitted for the first date filter)
from: # A string with specific date, e.g. "2020-01-01"
to: # A string with specific date, e.g. "2020-01-01"
[filter_name]: # Relative date filter
type: date_filter
title: # An optional human-readable title for the filter
mode: # A mode the filter is working in, one of "readonly", "hidden", "active"
date: # A date dataset id to use for the filter (omitted for the first date filter)
granularity: # A granularity to use for the filter, one of MINUTE, HOUR, DAY, WEEK, MONTH, QUARTER, YEAR,
# MINUTE_OF_HOUR, HOUR_OF_DAY, DAY_OF_WEEK, DAY_OF_MONTH, DAY_OF_YEAR, WEEK_OF_YEAR,
# MONTH_OF_YEAR, QUARTER_OF_YEAR
from: # A number specifying how many periods to start from, e.g. -1 for previous period
to: # A number specifying how many periods to end with, e.g. -2 for two periods ago
[filter_name]: # Attribute filter
type: attribute_filter
title: # An optional human-readable title for the filter
mode: # A mode the filter is working in, one of "readonly", "hidden", "active"
using: # An attribute or attribute label id to use for the filter
multiselect: # A boolean flag to enable multiselect
parents: # An optional list of parent attribute filter names to limit the available options in the filter
state: # the default state of the filter, should contain either include or exclude.
# In case of multiselect set to false, should contain a single array of values
include: # An array of attribute values to include
exclude: # An array of attribute values to exclude
cross_filtering: # A boolean flag to enable cross-filtering between the widgets
sections: # A list of sections in the dashboard
- title: # Optional section title
description: # Optional section description
widgets: # An array of widgets in the section
- visualization: # A visualization id to be rendered in this widget
title: # An optional title override for the widget. When omitted, the visualization title is used
# Disable title for a widget by setting it to false
description: # An optional description override for the widget. When omitted, the visualization description is used
# Disable description for a widget by setting it to false
columns: # A number of columns that widget should occupy on the dashboard layout [1..12]
rows: # A number of rows that widget should occupy on the dashboard layout, each row is 20px high
date: # An id of the date dataset to use for the widget when filtering dashboard by date
ignored_filters: # An optional list of filters to ignore for this widget
- # A filter name to ignore
zoom_data: # An optional boolean flag to enable zooming in the widget
interactions: # A list of interaction user can do with the widget
- # drill to plain URL
click_on: # A field name that triggers the interaction
open_url: # A string with a URL to open
- # drill to URL from attribute
click_on: # A field name that triggers the interaction
open_url: # A reference to attribute or label that holds the URL
href: # An attribute or label id to use for the URL
label: # An attribute or label id to use for the URL label
- # drill to dashboard
click_on: # A field name that triggers the interaction
open_dashboard: # A dashboard id to open
- # drill to visualization
click_on: # A field name that triggers the interaction
open_visualization: # A visualization id to open
plugins: # A list of plugins to use in the dashboard
- # A string with the plugin id, or a plugin definition
- id: # A plugin id
parameters: # A plugin parameters as a string or serializable structure
Example
type: dashboard
id: my_dashboard
title: My Dashboard
description: A dashboard with some visualizations
tags:
- dashboard
- retail
filters:
order_date:
type: date_filter
from: 2024-01-01
to: 2024-12-31
return_date:
type: date_filter
title: Return Date
date: return_date_dataset
granularity: MONTH
from: -3
to: 0
country_filter:
type: attribute_filter
title: Country of Ordering
using: country
multiselect: true
state:
include:
- USA
- Canada
cross_filtering: true
sections:
- title: My First Section
description: A section with some visualizations
widgets:
- visualization: revenue_by_country
date: order_date
interactions:
- click_on: country
open_dashboard: country_dashboard
plugins:
- id: my_plugin
parameters:
my: plugin
params: here
Dashboard plugin
A dashboard plugin lets you customize the dashboard even further with a little bit of code.
The structure of the dashboard plugin representation in .yaml is as follows:
type: plugin
id: # A unique identifier of the plugin
title: # An optional human-readable title for the plugin. Derived from id, when not provided explicitly.
description: # An optional description of the plugin
tags: # An optional list of tags
url: # A URL to the plugin source code entry point
Example
type: plugin
id: my_plugin
title: My Plugin
description: A plugin to customize the dashboard
tags:
- plugin
- custom
url: https://my-company.com/my-plugin.js