Skip to content

Commit 10ca22f

Browse files
jaceksanjaceksan
authored
Merge pull request #1510 from gooddata/jacek/working
docs: add AAC YAML support documentation
2 parents 49ea0d5 + 971282f commit 10ca22f

6 files changed

Lines changed: 189 additions & 17 deletions

File tree

‎.aida/rules/packages/gooddata-sdk.mdc‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,8 @@ alwaysApply: false
1515
- Compute services (execution, caching, export)
1616
- Visualization services (insights, dashboards)
1717
- Declarative API support (layout export/import)
18+
- Analytics-as-Code (AAC) YAML support via `gooddata-code-convertors`
19+
- `gdc` CLI for deploying/cloning AAC and declarative layouts
1820
- Model management (LDM, PDM operations)
1921

2022
## Does NOT Own
@@ -31,7 +33,11 @@ alwaysApply: false
3133

3234
**Service-based**: `catalog_*`, `compute_*`, `insights_*`, `tables_*`
3335

34-
**Depends on**: `gooddata-api-client` (generated OpenAPI client)
36+
**Depends on**: `gooddata-api-client` (generated OpenAPI client), `gooddata-code-convertors` (AAC↔declarative conversion via WASM)
37+
38+
**AAC module**: `catalog/workspace/aac.py` — conversion functions and workspace-level load/store
39+
40+
**CLI**: `cli/` — `gdc` command for deploy/clone with AAC YAML support, reads `gooddata.yaml`
3541

3642
## SDK Usage
3743

‎.claude/CLAUDE.md‎

Lines changed: 0 additions & 16 deletions
This file was deleted.

‎docs/content/en/latest/getting-started.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -55,6 +55,21 @@ Start integrating GoodData into your Python application right now.
5555

5656
The `token` field should reference an environment variable that holds your personal access token. The `access` field can include references to environment variables with data source secrets, or it can be left empty if not needed.
5757

58+
If you use the GoodData VSCode extension, the SDK can read its `gooddata.yaml` config file directly:
59+
60+
```yaml
61+
profiles:
62+
default:
63+
host: "https://www.example.com"
64+
token: "$GOODDATA_API_TOKEN"
65+
workspace_id: "my-workspace" # used by gdc CLI
66+
data_source: "my-datasource" # used by gdc CLI
67+
default_profile: "default"
68+
source_dir: "analytics" # used by gdc CLI
69+
```
70+
71+
The `workspace_id`, `data_source`, and `source_dir` fields are used by the `gdc` CLI for [Analytics-as-Code workflows](../workspace/workspaces/#analytics-as-code-aac-methods) and are ignored by the SDK API client.
72+
5873
1. Start using Python SDK! For example, get a list of all workspaces:
5974

6075
```python

‎docs/content/en/latest/workspace/workspaces/_index.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,11 @@ Manage workspaces. Entity and Declarative methods are supported.
3030
* [get_declarative_automations](./get_declarative_automations/)
3131
* [put_declarative_automations](./put_declarative_automations/)
3232

33+
### Analytics-as-Code (AAC) Methods
34+
35+
* [load_and_put_aac_workspace](./load_and_put_aac_workspace/)
36+
* [get_and_store_aac_workspace](./get_and_store_aac_workspace/)
37+
3338

3439
## Example
3540

‎docs/content/en/latest/workspace/workspaces/get_and_store_aac_workspace.md‎

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
---
2+
title: "get_and_store_aac_workspace"
3+
linkTitle: "get_and_store_aac_workspace"
4+
weight: 136
5+
superheading: "catalog_workspace."
6+
api_ref: "CatalogWorkspaceService.get_and_store_aac_workspace"
7+
---
8+
9+
<!-- AUTO-GENERATED FROM DOCSTRING — do not edit above this line -->
10+
11+
<div class="python-ref">
12+
<p><code>get_and_store_aac_workspace(workspace_id: str, source_dir: Path)</code></p>
13+
<div class="python-ref-description">
14+
<p>Get declarative workspace from server, convert to AAC YAML files, and write to disk.</p>
15+
</div>
16+
<h4>Parameters</h4>
17+
<table class="gd-docs-parameters-block">
18+
<thead>
19+
<tr>
20+
<th>name</th>
21+
<th>type</th>
22+
<th>description</th>
23+
</tr>
24+
</thead>
25+
<tbody>
26+
<tr>
27+
<th padding="0px">workspace_id
28+
<th padding="0px">str
29+
<th>
30+
Workspace identification string e.g. "demo"
31+
</tr>
32+
<tr>
33+
<th padding="0px">source_dir
34+
<th padding="0px">Path
35+
<th>
36+
Path to the directory where AAC YAML files will be written.
37+
</tr>
38+
</tbody>
39+
</table>
40+
<h4>Returns</h4>
41+
<i>None</i>
42+
</div>
43+
44+
## Example
45+
46+
Clone a workspace layout as AAC YAML files:
47+
48+
```python
49+
from pathlib import Path
50+
from gooddata_sdk import GoodDataSdk
51+
52+
host = "https://www.example.com"
53+
token = "some_user_token"
54+
sdk = GoodDataSdk.create(host, token)
55+
56+
# Clone workspace to AAC YAML files
57+
sdk.catalog_workspace.get_and_store_aac_workspace(
58+
workspace_id="demo",
59+
source_dir=Path("analytics")
60+
)
61+
```
62+
63+
This creates typed subdirectories under the target path:
64+
65+
```
66+
analytics/
67+
datasets/
68+
campaigns.yaml
69+
orders.yaml
70+
metrics/
71+
revenue.yaml
72+
visualisations/
73+
revenue_chart.yaml
74+
dashboards/
75+
overview.yaml
76+
```

‎docs/content/en/latest/workspace/workspaces/load_and_put_aac_workspace.md‎

Lines changed: 86 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
---
2+
title: "load_and_put_aac_workspace"
3+
linkTitle: "load_and_put_aac_workspace"
4+
weight: 135
5+
superheading: "catalog_workspace."
6+
api_ref: "CatalogWorkspaceService.load_and_put_aac_workspace"
7+
---
8+
9+
<!-- AUTO-GENERATED FROM DOCSTRING — do not edit above this line -->
10+
11+
<div class="python-ref">
12+
<p><code>load_and_put_aac_workspace(workspace_id: str, source_dir: Path)</code></p>
13+
<div class="python-ref-description">
14+
<p>Load AAC YAML files from source_dir, convert to declarative, and deploy to workspace.</p>
15+
</div>
16+
<h4>Parameters</h4>
17+
<table class="gd-docs-parameters-block">
18+
<thead>
19+
<tr>
20+
<th>name</th>
21+
<th>type</th>
22+
<th>description</th>
23+
</tr>
24+
</thead>
25+
<tbody>
26+
<tr>
27+
<th padding="0px">workspace_id
28+
<th padding="0px">str
29+
<th>
30+
Workspace identification string e.g. "demo"
31+
</tr>
32+
<tr>
33+
<th padding="0px">source_dir
34+
<th padding="0px">Path
35+
<th>
36+
Path to the directory containing AAC YAML files.
37+
</tr>
38+
</tbody>
39+
</table>
40+
<h4>Returns</h4>
41+
<i>None</i>
42+
</div>
43+
44+
## Example
45+
46+
Deploy AAC YAML files from a local directory to a workspace:
47+
48+
```python
49+
from pathlib import Path
50+
from gooddata_sdk import GoodDataSdk
51+
52+
host = "https://www.example.com"
53+
token = "some_user_token"
54+
sdk = GoodDataSdk.create(host, token)
55+
56+
# Deploy AAC YAML files to workspace
57+
sdk.catalog_workspace.load_and_put_aac_workspace(
58+
workspace_id="demo",
59+
source_dir=Path("analytics")
60+
)
61+
```
62+
63+
The AAC YAML directory can contain typed subdirectories:
64+
65+
```
66+
analytics/
67+
datasets/
68+
campaigns.yaml
69+
orders.yaml
70+
metrics/
71+
revenue.yaml
72+
visualisations/
73+
revenue_chart.yaml
74+
dashboards/
75+
overview.yaml
76+
```
77+
78+
Each YAML file has a `type` field that determines its kind:
79+
80+
```yaml
81+
type: metric
82+
id: revenue
83+
title: Revenue
84+
maql: SELECT SUM({fact/amount})
85+
format: "#,##0"
86+
```

0 commit comments

Comments
 (0)