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-ldm
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:
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.
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.
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 scriptrefresh-ldm
to run the program.Do not import the constants directly. Instead, wrap the constants into a namespace as follows:
import * as Ldm from "./ldm/generatedFile"; export { Ldm };
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");