8.8.0

Export Catalog

GoodData.UI visual components render data stored in your GoodData platform or GoodData.CN workspaces. Your application specifies what data to render by referencing the Logical Data Model (LDM) objects: attributes, display forms (also known as labels), facts, and measures.

To simplify this task, GoodData.UI offers the @gooddata/catalog-export tool. @gooddata/catalog-export exports a list of catalog items and date datasets from a GoodData workspace into JavaScript or TypeScript code. The generated code contains exported constant-per-LDM-object.

Using this generated code, you can create charts and execution definitions in a very efficient and natural way.

Built-in integration in Accelerator Toolkit applications

The @gooddata/catalog-export tool is installed and integrated into all applications bootstrapped using the @gooddata/create-gooddata-react-app tool. A bootstrapped application's package.json contains the refresh-md script that you can call to start the @gooddata/catalog-export tool with arguments derived from your application configuration.

If you created your application using @gooddata/create-gooddata-react-app, you may be interested in additional configuration options described further in this document.

Installing @gooddata/catalog-export

Include @gooddata/catalog-export as a devDependency of your application. Launching it through npx is not supported. If you start the tool using npx and try to export the catalog into a JavaScript file, you will encounter errors.

To install the stable version, run one of the following commands depending on your package manager:

yarn

yarn add @gooddata/catalog-export --dev

npm

$ npm install @gooddata/catalog-export --save-dev

Using @gooddata/catalog-export

@gooddata/catalog-export is a command-line program that loads metadata from a workspace and transforms it into TypeScript, JavaScript, or a JSON representation. The program can run in interactive, silent, or hybrid modes.

NOTE: The JSON representation is deprecated. We will remove it in a future major version.

This is how it works:

  1. The program searches the current directory for the .gdcatalogrc config file. If found, the program reads input parameters from this file.

    The configuration file must be in the JSON format. It can contain any or all parameters that you would normally provide on the command line:

    {
    "hostname": "your.gooddata.hostname.com",
    "projectId": "your_gooddata_workspaceid",
    "username": "email",
    "password": "password",
    "output": "desired_file_name.ts|js|json"
}

    NOTE: TypeScript, JavaScript or JSON output files are generated based on the filename extension specified in the output parameter.

  2. The program reads input parameters from the command line. To learn more about the available parameters, run the following command:

    npx @gooddata/catalog-export --help

    Parameters provided via the command line take precedence over the corresponding parameters in the config file.

  3. If all required parameters are entered, the program runs and exports the metadata from the workspace. If any parameter is missing, the program will prompt you to enter it.

    IMPORTANT! The program does not accept passwords via the command line. You can either put the password into .gdcatalogrc or enter it interactively. Do NOT save .gdcatalogrc in a version control system.

NOTE: We are planning to rename the projectId parameter to workspaceId. This will apply to both the configuration file and command line arguments. You can already use the workspaceId instead of projectId, and the end result will be the same. If you specify both, workspaceId takes preference.

Using @gooddata/catalog-export with GoodData.CN

The @gooddata/catalog-export tool can work on top of either the GoodData platform or GoodData.CN. By default, the tool assumes it is connecting to the GoodData platform. To switch to GoodData.CN, use either the backend argument on the command line or the backend parameter in the .gdcatalogrc configuration file:

  • Command line:

    --backend tiger

  • .gdcatalogrc:

    {
    "hostname": "your.own.gooddata.com",
    "workspaceId": "your_workspace_id",
    "output": "desired_file_name.ts|js|json",
    "backend": "tiger"
}

The tool uses Bearer token authentication when communicating with your GoodData.CN installation. For more information about how to obtain API tokens, see the GoodData.CN documentation.

Once you have a valid API token, set it into an exported TIGER_API_TOKEN variable:

export TIGER_API_TOKEN="<your_api_token>"

Or if you are using Microsoft Windows:

SET TIGER_API_TOKEN='<your_api_token>'

Subsequent catalog exports

TypeScript and JavaScript representations

The catalog export will overwrite the generated files. If you need to modify the generated constants or add new LDM objects, do so through a layer of indirection: in a different file adjacent to the generated code.

JSON representation

A catalog export maintains keys used in an existing catalog export JSON file. You can rename keys inside the following properties:

  • Visualizations
  • Measures
  • Attributes
  • dateDataSets
  • displayForms

At the next run, @gooddata/catalog-export tries to resolve the new items from the server against the existing items, and does the following:

  • Preserves the existing keys by matching their identifier attributes
  • Removes the keys that do not exist on the server
  • Adds the new keys from the server equal to their title property

In addition, the existing catalog file is renamed to catalogue.json.bak, and the last backup gets rewritten.

Recommendations

  • Include @gooddata/catalog-export as a devDependency of your application and define an NPM script refresh-md to run the program.

  • Do not import the constants directly. Instead, wrap the constants into a namespace as follows:

    import * as Md from "./md/generatedFile";
export { Md };

  • Never modify the generated files.

  • If you need to modify the generated constants or add new LDM objects, do so through a layer of indirection: in a different file adjacent to the generated code. For examples, look at our reference-workspace LDM and package.

Limitations

@gooddata/catalog-export exports only data from a workspace (production data).

If you uploaded data to your workspace from a file, the data from the file is added as a separate dataset (non-production data), and @gooddata/catalog-export cannot retrieve it. This also includes any measures that were created using the data from that separate dataset.

Example

Attributes with multiple display forms (labels) are generated into a constant such as this:

export const City = {
    /**
     * Display Form Title: city
     * Display Form ID: label.uscities.city
     */
    Default: newAttribute("label.uscities.city"),
    /**
     * Display Form Title: location
     * Display Form ID: label.uscities.city.location
     */ Location: newAttribute("label.uscities.city.location"),
};

Attributes with a single display form (label) are generated into a constant such as this:

/**
 * Attribute Title: Location Resort
 * Display Form ID: attr.restaurantlocation.locationresort
 */
export const LocationResort = newAttribute("label.restaurantlocation.locationresort");

MAQL metrics are generated into a constant such as this:

/**
 * Metric Title: $ Total Sales
 * Metric ID: aa7ulGyKhIE5
 * Metric Type: MAQL Metric
 */
export const $TotalSales = newMeasure("aa7ulGyKhIE5");
/**
 * Metric Title: $ Franchise Fees
 * Metric ID: aaEGaXAEgB7U
 * Metric Type: MAQL Metric
 */
export const $FranchiseFees = newMeasure("aaEGaXAEgB7U");
/**
 * Metric Title: $ Franchise Fees (Ad Royalty)
 * Metric ID: aabHeqImaK0d
 * Metric Type: MAQL Metric
 */
export const $FranchiseFeesAdRoyalty = newMeasure("aabHeqImaK0d");
/**
 * Metric Title: $ Franchise Fees (Ongoing Royalty)
 * Metric ID: aaWGcgnsfxIg
 * Metric Type: MAQL Metric
 */
export const $FranchiseFeesOngoingRoyalty = newMeasure("aaWGcgnsfxIg");

For facts, @gooddata/catalog-export generates an object with keys for each supported aggregation:

/**
 * Fact Title: Cost
 * Fact ID: fact.restaurantcostsfact.cost
 */
export const Cost = {
    /**
     * Fact Title: Cost
     * Fact ID: fact.restaurantcostsfact.cost
     * Fact Aggregation: sum
     */
    Sum: newMeasure("fact.restaurantcostsfact.cost", (m) => m.aggregation("sum")),
    /**
     * Fact Title: Cost
     * Fact ID: fact.restaurantcostsfact.cost
     * Fact Aggregation: count
     */ Count: newMeasure("fact.restaurantcostsfact.cost", (m) => m.aggregation("count")),
    /**
     * Fact Title: Cost
     * Fact ID: fact.restaurantcostsfact.cost
     * Fact Aggregation: avg
     */ Avg: newMeasure("fact.restaurantcostsfact.cost", (m) => m.aggregation("avg")),
    /**
     * Fact Title: Cost
     * Fact ID: fact.restaurantcostsfact.cost
     * Fact Aggregation: min
     */ Min: newMeasure("fact.restaurantcostsfact.cost", (m) => m.aggregation("min")),
    /**
     * Fact Title: Cost
     * Fact ID: fact.restaurantcostsfact.cost
     * Fact Aggregation: max
     */ Max: newMeasure("fact.restaurantcostsfact.cost", (m) => m.aggregation("max")),
    /**
     * Fact Title: Cost
     * Fact ID: fact.restaurantcostsfact.cost
     * Fact Aggregation: median
     */ Median: newMeasure("fact.restaurantcostsfact.cost", (m) => m.aggregation("median")),
    /**
     * Fact Title: Cost
     * Fact ID: fact.restaurantcostsfact.cost
     * Fact Aggregation: runsum
     */ Runsum: newMeasure("fact.restaurantcostsfact.cost", (m) => m.aggregation("runsum")),
};

For date datasets, @gooddata/catalog-export includes one constant per attribute. The date dimension name is the prefix of the constant name. Attributes with multiple display forms are generated as follows:

export const TimelineMonth = {
    /**
     * Display Form Title: Short (Jan) (Timeline)
     * Display Form ID: timeline.abm81lMifn6q
     */
    Short: newAttribute("timeline.abm81lMifn6q"),
    /**
     * Display Form Title: Long (January) (Timeline)
     * Display Form ID: timeline.abs81lMifn6q
     */ Long: newAttribute("timeline.abs81lMifn6q"),
    /**
     * Display Form Title: Number (M1) (Timeline)
     * Display Form ID: timeline.abq81lMifn6q
     */ Number: newAttribute("timeline.abq81lMifn6q"),
    /**
     * Display Form Title: M/Q (M1/Q1) (Timeline)
     * Display Form ID: timeline.abo81lMifn6q
     */ MQ: newAttribute("timeline.abo81lMifn6q"),
};

Date dataset attributes that do not have multiple display forms are generated as follows:

export const TimelineQuarterYear = newAttribute("timeline.aci81lMifn6q");
← Understand the Execution ModelGoodData Platform Introduction →