@gooddata/code-cli 0.28.0 → 0.30.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +13 -1
- package/esm/fixtures/mcp.json +7 -0
- package/esm/fixtures/rules/dashboards.mdc +101 -0
- package/esm/fixtures/rules/datasets.mdc +102 -0
- package/esm/fixtures/rules/gooddata.mdc +39 -0
- package/esm/fixtures/rules/metrics.mdc +56 -0
- package/esm/fixtures/rules/visualizations.mdc +110 -0
- package/esm/index.js +183805 -0
- package/package.json +1 -2
package/CHANGELOG.md
CHANGED
|
@@ -1,6 +1,18 @@
|
|
|
1
1
|
# Change Log - @gooddata/code-cli
|
|
2
2
|
|
|
3
|
-
This log was last generated on
|
|
3
|
+
This log was last generated on Wed, 20 May 2026 09:24:58 GMT and should not be manually modified.
|
|
4
|
+
|
|
5
|
+
## 0.30.0
|
|
6
|
+
|
|
7
|
+
Wed, 20 May 2026 09:24:58 GMT
|
|
8
|
+
|
|
9
|
+
_Version update only_
|
|
10
|
+
|
|
11
|
+
## 0.29.0
|
|
12
|
+
|
|
13
|
+
Wed, 20 May 2026 09:05:03 GMT
|
|
14
|
+
|
|
15
|
+
_Version update only_
|
|
4
16
|
|
|
5
17
|
## 0.28.0
|
|
6
18
|
|
|
@@ -0,0 +1,101 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: Detailed information about GoodData dashboards definition.
|
|
3
|
+
alwaysApply: false
|
|
4
|
+
---
|
|
5
|
+
# Fields
|
|
6
|
+
|
|
7
|
+
On top of generic fields like `id`, `type` (always "dashboard"), `title`, `description` and `tags`,
|
|
8
|
+
dashboards support:
|
|
9
|
+
|
|
10
|
+
- `sections`: (array, required) List of dashboard sections. Each section can have an optional `title`, `description`, and a list of `widgets`.
|
|
11
|
+
- `widgets`: (array, required in each section) List of widgets (visualizations or containers) to display. Each widget can have:
|
|
12
|
+
- `id`: (string, required) Unique widget identifier.
|
|
13
|
+
- `visualization`: (string, required for visualization widgets) ID of the visualization to display.
|
|
14
|
+
- `title`: (string, optional) Widget title.
|
|
15
|
+
- `description`: (string, optional) Widget description.
|
|
16
|
+
- `columns`: (integer, required) Number of columns the widget spans.
|
|
17
|
+
- `rows`: (integer, required) Number of rows the widget spans.
|
|
18
|
+
- `date`: (string, optional) Date dataset reference for filtering.
|
|
19
|
+
- `zoom_data`: (boolean, optional) Enable zooming for chart data.
|
|
20
|
+
- `interactions`: (array, optional) List of interactions (e.g., click actions) for the widget. Each interaction can define:
|
|
21
|
+
- `click_on`: (string) ID of the element to interact with.
|
|
22
|
+
- `open_visualization`: (string) Visualization ID to open.
|
|
23
|
+
- `open_dashboard`: (string) Dashboard ID to open.
|
|
24
|
+
- `open_url`: (string) URL to open.
|
|
25
|
+
- `container`: (string, optional) ID of a container widget (for nested layouts).
|
|
26
|
+
- `layout_direction`: (string, optional) Layout direction for container widgets (e.g., `row`, `column`).
|
|
27
|
+
- `enable_section_headers`: (boolean, optional) Show/hide section headers in containers.
|
|
28
|
+
- `sections`: (array, optional) Nested sections for container widgets.
|
|
29
|
+
|
|
30
|
+
- `filters`: (object, optional) Dashboard-level filters. Each filter can be a `date_filter` or `attribute_filter` with fields like `type`, `granularity`, `from`, `to`, and `using`.
|
|
31
|
+
- `permissions`: (object, optional) Dashboard-level permissions. Common keys are `VIEW` and `EDIT`, with user or group assignments.
|
|
32
|
+
|
|
33
|
+
# Best Practices
|
|
34
|
+
- Use clear, descriptive titles and IDs for dashboards, sections, and widgets.
|
|
35
|
+
- Organize widgets into logical sections for better readability.
|
|
36
|
+
- Use container widgets for flexible, nested layouts.
|
|
37
|
+
- Document the purpose of the dashboard and each section in the `description` fields.
|
|
38
|
+
- Use filters to enable interactive, user-driven analysis.
|
|
39
|
+
- Do not assign permissions unless explicitly requested.
|
|
40
|
+
|
|
41
|
+
# Example Dashboard YAML
|
|
42
|
+
|
|
43
|
+
```yaml
|
|
44
|
+
type: dashboard
|
|
45
|
+
id: example_dashboard
|
|
46
|
+
|
|
47
|
+
title: Example Dashboard
|
|
48
|
+
|
|
49
|
+
description: Overview of key business metrics and trends.
|
|
50
|
+
|
|
51
|
+
sections:
|
|
52
|
+
- title: Sales Overview
|
|
53
|
+
description: How is your company performing?
|
|
54
|
+
widgets:
|
|
55
|
+
- id: sales_trend
|
|
56
|
+
visualization: sales_trend_chart
|
|
57
|
+
title: Sales Trend
|
|
58
|
+
description: Monthly sales trend.
|
|
59
|
+
columns: 8
|
|
60
|
+
rows: 22
|
|
61
|
+
date: date
|
|
62
|
+
zoom_data: true
|
|
63
|
+
interactions:
|
|
64
|
+
- click_on: sales_point
|
|
65
|
+
open_visualization: sales_detail_chart
|
|
66
|
+
- id: sales_breakdown
|
|
67
|
+
visualization: sales_breakdown_chart
|
|
68
|
+
title: Sales Breakdown
|
|
69
|
+
columns: 4
|
|
70
|
+
rows: 22
|
|
71
|
+
date: customer_created_date
|
|
72
|
+
- title: Customers Overview
|
|
73
|
+
description: Where are your customers coming from?
|
|
74
|
+
widgets:
|
|
75
|
+
- id: customer_map
|
|
76
|
+
visualization: customer_geo_chart
|
|
77
|
+
title: Customers by Location
|
|
78
|
+
columns: 6
|
|
79
|
+
rows: 32
|
|
80
|
+
date: customer_created_date
|
|
81
|
+
interactions:
|
|
82
|
+
- click_on: city_point
|
|
83
|
+
open_visualization: customer_detail_chart
|
|
84
|
+
|
|
85
|
+
filters:
|
|
86
|
+
date_month:
|
|
87
|
+
type: date_filter
|
|
88
|
+
granularity: MONTH
|
|
89
|
+
from: -1
|
|
90
|
+
to: -1
|
|
91
|
+
customer_country_filter:
|
|
92
|
+
type: attribute_filter
|
|
93
|
+
using: label/customer_country
|
|
94
|
+
|
|
95
|
+
permissions:
|
|
96
|
+
VIEW:
|
|
97
|
+
all: true
|
|
98
|
+
EDIT:
|
|
99
|
+
users:
|
|
100
|
+
- user@example.com
|
|
101
|
+
```
|
|
@@ -0,0 +1,102 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: Detailed information about GoodData datasets and date instances. Covers facts, attributes, labels and dates definition.
|
|
3
|
+
alwaysApply: false
|
|
4
|
+
---
|
|
5
|
+
# Types of Datasets
|
|
6
|
+
|
|
7
|
+
- **dataset**: Standard dataset is an abstraction on top of existing database table or view. Has type `dataset`.
|
|
8
|
+
- **SQL dataset**: Special dataset built on top of an SQL query result. Has type `dataset`.
|
|
9
|
+
- **date instance**: Special dataset for date dimensions, with granularities. Has type `date`.
|
|
10
|
+
|
|
11
|
+
# Fields
|
|
12
|
+
|
|
13
|
+
All types of datasets have generic fields like `id`, `type`, `title`, `description` and `tags`.
|
|
14
|
+
|
|
15
|
+
Datasets and SQL datasets contain the following fields:
|
|
16
|
+
- `table_path` (string, required for standard datasets): Path to the table in the data source.
|
|
17
|
+
- `sql` (string, required for SQL datasets): SQL statement representing the dataset.
|
|
18
|
+
- `primary_key` (string or array, recommended): Primary key column(s) for the dataset.
|
|
19
|
+
- `fields` (object, required): Map of fields (attributes and facts) in the dataset.
|
|
20
|
+
- `references` (array): Relationships to other datasets.
|
|
21
|
+
- `workspace_data_filters` (array): Workspace-level filters.
|
|
22
|
+
- `data_source` (string): Data source ID.
|
|
23
|
+
|
|
24
|
+
Date instances special fields are:
|
|
25
|
+
- `granularities` (array, required): List of supported granularities (e.g., DAY, MONTH, YEAR).
|
|
26
|
+
- `title_base` and `title_pattern`: Define the formatting for the date.
|
|
27
|
+
|
|
28
|
+
# Best Practices
|
|
29
|
+
- Use one file per dataset object.
|
|
30
|
+
- Use clear, unique IDs for datasets and fields.
|
|
31
|
+
- Prefer `table_path` for simple tables, `sql` for complex logic.
|
|
32
|
+
- Always specify `primary_key` for joinability.
|
|
33
|
+
- Use `references` to define relationships between datasets.
|
|
34
|
+
- For date datasets, include all granularities needed for reporting.
|
|
35
|
+
|
|
36
|
+
# Real-World Examples
|
|
37
|
+
|
|
38
|
+
## Example: Standard Dataset
|
|
39
|
+
```yaml
|
|
40
|
+
id: customers
|
|
41
|
+
type: dataset
|
|
42
|
+
title: Customers
|
|
43
|
+
table_path: public/customers
|
|
44
|
+
primary_key: customer_id
|
|
45
|
+
fields:
|
|
46
|
+
customer_id:
|
|
47
|
+
type: attribute
|
|
48
|
+
data_type: STRING
|
|
49
|
+
labels:
|
|
50
|
+
customer_name:
|
|
51
|
+
source_column: customer_name
|
|
52
|
+
data_type: STRING
|
|
53
|
+
revenue:
|
|
54
|
+
type: fact
|
|
55
|
+
data_type: NUMERIC
|
|
56
|
+
|
|
57
|
+
references:
|
|
58
|
+
- dataset: customer_created_date
|
|
59
|
+
sources:
|
|
60
|
+
- source_column: customer_created_date
|
|
61
|
+
data_type: DATE
|
|
62
|
+
target: customer_created_date
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
## Example: SQL Dataset
|
|
66
|
+
```yaml
|
|
67
|
+
id: orders
|
|
68
|
+
type: dataset
|
|
69
|
+
title: Orders
|
|
70
|
+
sql: SELECT * from orders;
|
|
71
|
+
primary_key: order_id
|
|
72
|
+
fields:
|
|
73
|
+
order_id:
|
|
74
|
+
type: attribute
|
|
75
|
+
data_type: STRING
|
|
76
|
+
// ... the rest is same as for standard dataset
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
## Example: Date Dataset
|
|
80
|
+
```yaml
|
|
81
|
+
id: order_date
|
|
82
|
+
type: date
|
|
83
|
+
title: Order Date
|
|
84
|
+
- MINUTE
|
|
85
|
+
- HOUR
|
|
86
|
+
- DAY
|
|
87
|
+
- WEEK
|
|
88
|
+
- MONTH
|
|
89
|
+
- QUARTER
|
|
90
|
+
- YEAR
|
|
91
|
+
- MINUTE_OF_HOUR
|
|
92
|
+
- HOUR_OF_DAY
|
|
93
|
+
- DAY_OF_WEEK
|
|
94
|
+
- DAY_OF_MONTH
|
|
95
|
+
- DAY_OF_YEAR
|
|
96
|
+
- WEEK_OF_YEAR
|
|
97
|
+
- MONTH_OF_YEAR
|
|
98
|
+
- QUARTER_OF_YEAR
|
|
99
|
+
|
|
100
|
+
title_base: ""
|
|
101
|
+
title_pattern: "%titleBase - %granularityTitle"
|
|
102
|
+
```
|
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: General information about GoodData Analytics as Code, glossary
|
|
3
|
+
alwaysApply: false
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
GoodData Analytics as Code allows you to represent metadata for analytical workspace in a simple declarative syntax as code.
|
|
7
|
+
|
|
8
|
+
# Glossary
|
|
9
|
+
|
|
10
|
+
- **LDM (Logical Data Model)** is a collection of related datasets and date instances. It is an abstraction on top of a physical database schema (or several in case of data federation). LDM does not have to be a 1-to-1 representation of the database schema and may include some last mile ETL transformations.
|
|
11
|
+
- **Dataset** is an abstraction on a single table or view in a database. It consists of facts, attributes and attribute labels.
|
|
12
|
+
- **SQL Dataset** is a special form of dataset where facts, attributes and attribute labels are mapped to the SQL query result instead of an actual column in a table or a view. This is useful when you need to do a last mile ETL.
|
|
13
|
+
- **Fact** is a numeric column in a dataset.
|
|
14
|
+
- **Attribute** is a collection of attribute labels and represents a non-numeric column (a.k.a. dimension) in a dataset. Attributes may have a single default label or multiple labels in case we need to represent different aspects of the same dimension. For example, "User" attribute may have name and id, or "City" may have title and geographic coordinates. The correct label for representing an attribute is selected based on the usage context.
|
|
15
|
+
- **Attribute label** is a non-numeric field in a dataset. It is always linked to an attribute.
|
|
16
|
+
- **Date instance** (Date Dataset) is a representation of a date dimension.
|
|
17
|
+
- **Metric** is an aggregation on top of facts and attribute labels. A single number that can be sliced ad-hoc when building a visualization.
|
|
18
|
+
- **Multidimensional Analytical Query Language (MAQL)** a proprietary language used by GoodData for metrics definition.
|
|
19
|
+
- **Semantic Layer** is LDM and Metrics combined.
|
|
20
|
+
- **Visualization** - a data visualization built on top of Semantic Layer. I.e. a chart, graph or a table.
|
|
21
|
+
- **Dashboard** - a collection of visualizations.
|
|
22
|
+
- **Analytical Layer** - all visualizations and dashboards combined.
|
|
23
|
+
|
|
24
|
+
# General rules
|
|
25
|
+
|
|
26
|
+
- Every metadata object should be stored in a separate file YAML.
|
|
27
|
+
- All metadata objects must always have `type` and `id` string fields.
|
|
28
|
+
- All metadata objects may optionally have `title`, `description` string fields and `tags` - an array of strings.
|
|
29
|
+
- Other fields are dependant on the object type.
|
|
30
|
+
|
|
31
|
+
# Folder structure
|
|
32
|
+
|
|
33
|
+
A typical folder structure for GoodData analytics project looks like this:
|
|
34
|
+
|
|
35
|
+
- `{{ANALYTICS}}` - the root folder for the project
|
|
36
|
+
- `{{ANALYTICS}}/datasets` - a folder with all datasets and date instances
|
|
37
|
+
- `{{ANALYTICS}}/metrics` - a folder with all metrics
|
|
38
|
+
- `{{ANALYTICS}}/visualisations` - a folder with all visualizations
|
|
39
|
+
- `{{ANALYTICS}}/dashboards` - a folder with all dashboards
|
|
@@ -0,0 +1,56 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: Detailed information about GoodData metrics definition.
|
|
3
|
+
alwaysApply: false
|
|
4
|
+
---
|
|
5
|
+
# Fields
|
|
6
|
+
|
|
7
|
+
On top of generic fields like `id`, `type` (always "metric"), `title`, `description` and `tags`,
|
|
8
|
+
metrics support:
|
|
9
|
+
- `maql`: (string, required) a MAQL statement for this metric.
|
|
10
|
+
- `format`: (string) an Excel-like string formatting pattern.
|
|
11
|
+
|
|
12
|
+
# MAQL
|
|
13
|
+
|
|
14
|
+
MAQL is a query language for metric definition. Unlike SQL, it always returns a single number,
|
|
15
|
+
assuming the slicing will be done later based on the metric application.
|
|
16
|
+
|
|
17
|
+
MAQL syntax is different from SQL. Do not try generating MAQL expressions based on SQL knowledge. Instead, point user to
|
|
18
|
+
GoodData documentation: https://www.gooddata.com/docs/cloud/create-metrics/maql/
|
|
19
|
+
|
|
20
|
+
# Format
|
|
21
|
+
|
|
22
|
+
Here are few examples:
|
|
23
|
+
|
|
24
|
+
`#,##0` and 1,234.5678 gives "1,235"
|
|
25
|
+
`#,##0.0` and -1,234.5678 gives "-1,234.6"
|
|
26
|
+
`#,##0.00` and 1,234.5678 gives "1,234.57"
|
|
27
|
+
`#,##0%` and -1,234.5678 gives "-123,457%"
|
|
28
|
+
`$#,##0.00` and -1,234.5678 gives "$-1,234.57"
|
|
29
|
+
|
|
30
|
+
Conditional formatting with colors:
|
|
31
|
+
```
|
|
32
|
+
[>=1000000000000][green]#,,,,.0 T;
|
|
33
|
+
[>=1000000000][green]#,,,.0 B;
|
|
34
|
+
[>=1000000][green]#,,.0 M;
|
|
35
|
+
[>=1000][black]#,.0 K;
|
|
36
|
+
[>=0][black]#,##0;
|
|
37
|
+
[<=-1000000000000][red]-#,,,,.0 T;
|
|
38
|
+
[<=-1000000000][red]-#,,,.0 B;
|
|
39
|
+
[<=-1000000][red]-#,,.0 M;
|
|
40
|
+
[<=-1000][red]-#,.0 K;
|
|
41
|
+
[<0][black]-#,##0
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
Conditional formatting for trends:
|
|
45
|
+
```
|
|
46
|
+
[<0][green]▲ #,##0.0%;
|
|
47
|
+
[=0][black]#,##0.0%;
|
|
48
|
+
[>0][red]▼ #,##0.0%
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
Replace empty values with zero:
|
|
52
|
+
```
|
|
53
|
+
[=null]0.00;
|
|
54
|
+
[>=0]#,#0.00;
|
|
55
|
+
[<0]-#,#0.00
|
|
56
|
+
```
|
|
@@ -0,0 +1,110 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: Detailed information about GoodData visualizations definition.
|
|
3
|
+
alwaysApply: false
|
|
4
|
+
---
|
|
5
|
+
# Fields
|
|
6
|
+
|
|
7
|
+
On top of generic fields like `id`, `type`, `title`, `description` and `tags`,
|
|
8
|
+
visualizations support:
|
|
9
|
+
|
|
10
|
+
- `query`: Defines fields (metrics/attributes) and optional filters for the chart.
|
|
11
|
+
- `metrics`: A bucket with metrics from the query.
|
|
12
|
+
- `view_by`: A bucket of dimensions to slice by.
|
|
13
|
+
- `config`: Chart-specific configuration (e.g., legend position, data).
|
|
14
|
+
|
|
15
|
+
## Query Structure
|
|
16
|
+
|
|
17
|
+
- `fields`: Map of field IDs to either a string reference (e.g., `metric/gross_profit_margin`) or an object with additional options (e.g., `compute_ratio`, `using`, `type`).
|
|
18
|
+
- `filter_by`: (optional) Map of filters, such as date filters, with type, granularity, and range.
|
|
19
|
+
|
|
20
|
+
### Example:
|
|
21
|
+
```yaml
|
|
22
|
+
query:
|
|
23
|
+
fields:
|
|
24
|
+
gross_profit_margin: metric/gross_profit_margin
|
|
25
|
+
|
|
26
|
+
filter_by:
|
|
27
|
+
date_month:
|
|
28
|
+
type: date_filter
|
|
29
|
+
granularity: MONTH
|
|
30
|
+
from: 0
|
|
31
|
+
to: 0
|
|
32
|
+
using: date
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
## Referencing Metrics and Attributes
|
|
36
|
+
|
|
37
|
+
- Metrics and attributes are referenced by their field IDs, which should correspond to those defined in the datasets and metrics YAMLs.
|
|
38
|
+
- Use the format `metric/<metric_id>` or `label/<attribute_id>` as needed.
|
|
39
|
+
|
|
40
|
+
## Chart Configuration (`config`)
|
|
41
|
+
|
|
42
|
+
- Optional, but recommended for customizing appearance.
|
|
43
|
+
- Common options: `data_labels`, `legend_position`, etc.
|
|
44
|
+
|
|
45
|
+
### Example:
|
|
46
|
+
```yaml
|
|
47
|
+
config:
|
|
48
|
+
data_labels: auto
|
|
49
|
+
legend_position: right
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
## Best Practices
|
|
53
|
+
|
|
54
|
+
- Use clear, descriptive titles and IDs.
|
|
55
|
+
- Keep queries concise; only include necessary fields and filters.
|
|
56
|
+
- Use human readable IDs.
|
|
57
|
+
- Document the purpose of the visualization in the description.
|
|
58
|
+
|
|
59
|
+
## Example Visualization YAML
|
|
60
|
+
|
|
61
|
+
```yaml
|
|
62
|
+
type: donut_chart
|
|
63
|
+
id: net_sales_by_prod_cat
|
|
64
|
+
title: Net Sales by Product Category
|
|
65
|
+
|
|
66
|
+
query:
|
|
67
|
+
fields:
|
|
68
|
+
net_sales:
|
|
69
|
+
compute_ratio: true
|
|
70
|
+
using: metric/net_sales
|
|
71
|
+
product_category: label/product_category
|
|
72
|
+
|
|
73
|
+
metrics:
|
|
74
|
+
- field: net_sales
|
|
75
|
+
format: "#,##0.00%"
|
|
76
|
+
|
|
77
|
+
view_by:
|
|
78
|
+
- product_category
|
|
79
|
+
|
|
80
|
+
config:
|
|
81
|
+
data_labels: auto
|
|
82
|
+
legend_position: right
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
# Supported types
|
|
86
|
+
|
|
87
|
+
The `type` field of the object must correspond to the chart type used for this visualization.
|
|
88
|
+
|
|
89
|
+
List of supported chart types:
|
|
90
|
+
- `table`
|
|
91
|
+
- `bar_chart`
|
|
92
|
+
- `column_chart`
|
|
93
|
+
- `line_chart`
|
|
94
|
+
- `area_chart`
|
|
95
|
+
- `scatter_chart`
|
|
96
|
+
- `bubble_chart`
|
|
97
|
+
- `pie_chart`
|
|
98
|
+
- `donut_chart`
|
|
99
|
+
- `treemap_chart`
|
|
100
|
+
- `pyramid_chart`
|
|
101
|
+
- `funnel_chart`
|
|
102
|
+
- `heatmap_chart`
|
|
103
|
+
- `bullet_chart`
|
|
104
|
+
- `waterfall_chart`
|
|
105
|
+
- `dependency_wheel_chart`
|
|
106
|
+
- `sankey_chart`
|
|
107
|
+
- `headline_chart`
|
|
108
|
+
- `combo_chart`
|
|
109
|
+
- `geo_chart`
|
|
110
|
+
- `repeater_chart`
|