Object Structures
One of the most important things to understand when working with the VS Code extension is the structure of the objects.
There are two main concepts:
Both are declared in .yaml, as it is easy to read, version, and powerful enough to represent all the different possibilities.
The gooddata.yaml structure is vital for the extension to know where to send requests.
Datasets
Datasets are split into two categories:
- Datasets
- Date Dataset
A date dataset is virtual and does not exist in your database. It helps you add granularity to your dates.
Dataset
Dataset is a representation of a database table with its primary key and foreign key. It is a logical object/entity representing facts and attributes. To learn more about 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.
table_name: # Name of a table mapped to this dataset.
tags: # List of tags
primary_key: ...
fields:
[field_name]:
type: ...
title: ...
description: ...
tags: []
labels:
[label_name]:
title: ...
description: ...
tags: []
Example
type: dataset
id: customers
table_name: customers
tags:
- Customers
primary_key: customer_id
fields:
customer_id:
type: attribute
title: Customer id
description: Customer id
tags:
- Customers
customer_name:
type: attribute
title: Customer name
description: Customer name
tags:
- Customers
region:
type: attribute
description: Region
tags:
- Customers
state:
type: attribute
description: State
tags:
- Customers
labels:
geo__state__location:
title: State - Geolocation
description: Location
tags:
- Customers
Date Dataset
A Date dataset is a dataset in the logical data model (LDM) that represents 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.
tags: []
granularities:
# List of granularities
title_base: # A title for the title formatting
title_pattern: # A pattern for the title formatting
Example
type: date
id: 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"
Metrics
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 # This always needs to be set to metric
id: # ID of a metric. It has to be unique, e.g., revenue_per_customer
title: ...
description: ...
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
tags: []
maql: SELECT {metric/revenue} / {metric/total_revenue}
format: "#,##0.0%"
Profiles
Profile is a set of settings, that determine to which exact workspace you connect and which source folder is used as the source/target.
You can have multiple profiles, and they are saved in the gooddata.yaml file, which is in the root of the folder hierarchy.
The easiest way to create a profile file is through the CLI. This will however allow you to have only one profile, as CLI currently does not support multiple profile creation. In such a case, you should create such a file manually.
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 upon which to work on
data_source_id: #ID of the data source
source_dir: # Folder where to store/load the metrics and datasets
default_profile: # Which profile to use when none is provided
The token refers to the name of the environment variable, which stores the API token.
The workspace_id is an ID of the actual workspace, which you will be cloning and deploying to. This id is set up in the gd init flow. You can find it in the URL.
The data_source_id is an ID of the data source used in the workspace, This id is set up in the gd init flow. You can find it in the list of data sources in your UI.
If you create the gooddata.yaml through CLI, .env is created automatically and the token is correctly set. In case you created it manually, be sure to propagate the correct variable from the .env.
Example
profiles:
dev:
host: https://mamma_mia.trial.cloud.gooddata.com/
token: $GOODDATA_API_TOKEN
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