Get Started with GoodData for VS Code

This article will get you started with the VS Code extension and the CLI tool.

Prerequisites

Before getting started, ensure that you have the following:

• VS Code 😉
• Node.js version 16.17 or newer installed
• A running instance of GoodData.

Install VS Code Extension

Install the GoodData Visual Studio Code Extension (VS Code Extension). It provides tools for developer effectiveness, such as IntelliSense, syntax highlighting, and validation.

Steps:

1. Open the extensions tab in your VS Code.
2. In the search bar, look for “GoodData”.
3. Select the GoodData extension and install it.

The extension may require you to reload your VS Code.

Install CLI

To install the GoodData Command-line Interface (CLI), run:

npm i -g @gooddata/code-cli`

Now that you have a new CLI command available, try running

`gd -v`

This should return something along the lines of 0.1.0.

How to Use

Initialize Project

Projects are initialized using the CLI.

Steps:

1. In your terminal, navigate to a folder where you want to build and store your analytics.

2. Run the following command to initialize your project:

   gd init
   

   Follow the instructions to create a gooddata.yaml definition file.

   If you are unsure about some of the steps, see the Profile Structure.

   The result should look like this:

   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
   

3. Add an environmental variable that stores your API access token. For example:

   GOODDATA_API_TOKEN="<your_API_access_token>"
   

   For the easiest workflow, add the variable to your .env file.

   Be sure to add the .env to the .gitignore, so you don’t expose your API key.

4. Run the following command to clone your GoodData analytical environment to your local machine:

   gd clone
   

   You should now have an analytics folder that contains your datasets and metrics.

   The resulting folder structure should look like this:

    root_directory
            └── analytics
            │       ├── datasets
            │       │       ├── dataset1.yaml
            │       │       ├── dataset2.yaml
            │       │       └── ...
            │       └── metrics
            │       │       ├── metric1.yaml
            │       │       ├── metric2.yaml
            │       │       └── ...
            └── gooddata.yaml
   

Create and Preview Metrics

Once you set up your project, you can create new Analytical Objects using code.

Steps:

1. Create a new yaml file in your metrics folder to represent your new metric. For example, revenue_per_customer.yaml.

2. Define a metric:

   type: metric
   id: pending_revenue
   
   title: Pending revenue
   description: The sum of orders in carts
   
   maql: select SUM({fact/order_unit_price}) WHERE {label/order_status}= “In Cart”
   

   Notice the Run button.

   
   

3. Click Run to run your metric.

   You will be prompted whether you want to deploy your local environment.

   Click Deploy only if you are sure you will not break anything.

   
   

   Running metrics deploys local environment

   When you run the metric, it automatically deploys your local environment to the server. This is because we assume your directory to be the source of truth. To avoid breaking your production, create a new development workspace.

   Result:

   
   

4. Save the file.

Deploy Your Changes

To deploy your project to a GoodData server, ensure all your changes are saved and run the following command:

gd deploy

Your changes will be deployed to the hostname and workspace you defined in the gooddata.yaml definition file.