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:

Datasets
Metrics

Both are declared in .yaml, as it is easy to read, version, and powerful enough to represent all the different possibilities.

The profile .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.

SQL Dataset

We plan to incorporate support for SQL datasets in the near future.

Dataset

A dataset is a logical object representing related facts, attributes, and attribute labels. 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%"

Profile

The easiest way to create the profile file is through the CLI. You can also create such a file manually.

Profiles are saved in the gooddata.yaml file, which is in the root of the directory hierarchy.

API token setup

To ensure you do not leak the token, gooddata.yaml does not accept a hardcoded token. It only accepts a name of an environmental variable, such as $GOODDATA_API_TOKEN or $GD_API_TOKEN.

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: # Directory 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. Ideally, this should be located in the .env`` file. An example is $GOODDATA_API_TOKEN. You can create your API token.

The workspace_id`` can be retrieved from the URL. To find it, navigate to the workspace. The URL format should resemble: http:///dashboards/#/workspace/<workspace_id>`.

For instance, for the URL:

https://mamma_mia.trial.cloud.gooddata.com/dashboards/#/workspace/6739444cbf8b4cae88c8b4f1ad4500e9

the workspace_id is 6739444cbf8b4cae88c8b4f1ad4500e9.

You can find the data_source_id in the list of data sources.

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

Get Started

Command-line Interface