diff --git a/.aida/rules/packages/gooddata-sdk.mdc b/.aida/rules/packages/gooddata-sdk.mdc index f1b4f5045..a73f8c76f 100644 --- a/.aida/rules/packages/gooddata-sdk.mdc +++ b/.aida/rules/packages/gooddata-sdk.mdc @@ -15,6 +15,8 @@ alwaysApply: false - Compute services (execution, caching, export) - Visualization services (insights, dashboards) - Declarative API support (layout export/import) +- Analytics-as-Code (AAC) YAML support via `gooddata-code-convertors` +- `gdc` CLI for deploying/cloning AAC and declarative layouts - Model management (LDM, PDM operations) ## Does NOT Own @@ -31,7 +33,11 @@ alwaysApply: false **Service-based**: `catalog_*`, `compute_*`, `insights_*`, `tables_*` -**Depends on**: `gooddata-api-client` (generated OpenAPI client) +**Depends on**: `gooddata-api-client` (generated OpenAPI client), `gooddata-code-convertors` (AAC↔declarative conversion via WASM) + +**AAC module**: `catalog/workspace/aac.py` — conversion functions and workspace-level load/store + +**CLI**: `cli/` — `gdc` command for deploy/clone with AAC YAML support, reads `gooddata.yaml` ## SDK Usage diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md deleted file mode 100644 index bd6eb9e11..000000000 --- a/.claude/CLAUDE.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -apply: always ---- - -# You must follow this guidance only if AIDA MCP tools are available. -Call AIDA MCP `get_rules` at every task start and after every scope change; the `query` must match the current requested task. -Reuse one stable `session_id` for the whole conversation when calling `get_rules`. -When a `get_rules` response returns `delta.cursor`, pass it as `delta_cursor` on the next `get_rules` call in the same conversation. -You must always follow instructions returned by the `get_rules` MCP tool. -Do not perform Git or GitHub management unless the user explicitly asks for it. -If the user asks for code or docs changes only, stop before commit, push, or PR actions. -For commit and push workflow, do not call `get_rules`. -When the user explicitly asks for a commit, call the AIDA MCP `commit_command` tool. -The tool executes the commit server-side. If it returns `ok=true`, the commit is done — do not run any git commit commands. -If it returns `status=needs_more_input`, infer the missing policy-controlled values from the current changes and retry instead of asking the user. -Do not handcraft `git commit` arguments. diff --git a/docs/content/en/latest/getting-started.md b/docs/content/en/latest/getting-started.md index f312fad64..d9cb0293f 100644 --- a/docs/content/en/latest/getting-started.md +++ b/docs/content/en/latest/getting-started.md @@ -55,6 +55,21 @@ Start integrating GoodData into your Python application right now. 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. + If you use the GoodData VSCode extension, the SDK can read its `gooddata.yaml` config file directly: + + ```yaml + profiles: + default: + host: "https://www.example.com" + token: "$GOODDATA_API_TOKEN" + workspace_id: "my-workspace" # used by gdc CLI + data_source: "my-datasource" # used by gdc CLI + default_profile: "default" + source_dir: "analytics" # used by gdc CLI + ``` + + 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. + 1. Start using Python SDK! For example, get a list of all workspaces: ```python diff --git a/docs/content/en/latest/workspace/workspaces/_index.md b/docs/content/en/latest/workspace/workspaces/_index.md index 01e1ce242..cc06080b3 100644 --- a/docs/content/en/latest/workspace/workspaces/_index.md +++ b/docs/content/en/latest/workspace/workspaces/_index.md @@ -30,6 +30,11 @@ Manage workspaces. Entity and Declarative methods are supported. * [get_declarative_automations](./get_declarative_automations/) * [put_declarative_automations](./put_declarative_automations/) +### Analytics-as-Code (AAC) Methods + +* [load_and_put_aac_workspace](./load_and_put_aac_workspace/) +* [get_and_store_aac_workspace](./get_and_store_aac_workspace/) + ## Example diff --git a/docs/content/en/latest/workspace/workspaces/get_and_store_aac_workspace.md b/docs/content/en/latest/workspace/workspaces/get_and_store_aac_workspace.md new file mode 100644 index 000000000..6c4957bd0 --- /dev/null +++ b/docs/content/en/latest/workspace/workspaces/get_and_store_aac_workspace.md @@ -0,0 +1,76 @@ +--- +title: "get_and_store_aac_workspace" +linkTitle: "get_and_store_aac_workspace" +weight: 136 +superheading: "catalog_workspace." +api_ref: "CatalogWorkspaceService.get_and_store_aac_workspace" +--- + + + +
+

get_and_store_aac_workspace(workspace_id: str, source_dir: Path)

+
+

Get declarative workspace from server, convert to AAC YAML files, and write to disk.

+
+

Parameters

+ + + + + + + + + + + + + + +
nametypedescription
workspace_id +str + +Workspace identification string e.g. "demo" +
source_dir +Path + +Path to the directory where AAC YAML files will be written. +
+

Returns

+None +
+ +## Example + +Clone a workspace layout as AAC YAML files: + +```python +from pathlib import Path +from gooddata_sdk import GoodDataSdk + +host = "https://www.example.com" +token = "some_user_token" +sdk = GoodDataSdk.create(host, token) + +# Clone workspace to AAC YAML files +sdk.catalog_workspace.get_and_store_aac_workspace( + workspace_id="demo", + source_dir=Path("analytics") +) +``` + +This creates typed subdirectories under the target path: + +``` +analytics/ + datasets/ + campaigns.yaml + orders.yaml + metrics/ + revenue.yaml + visualisations/ + revenue_chart.yaml + dashboards/ + overview.yaml +``` diff --git a/docs/content/en/latest/workspace/workspaces/load_and_put_aac_workspace.md b/docs/content/en/latest/workspace/workspaces/load_and_put_aac_workspace.md new file mode 100644 index 000000000..ed07dd5db --- /dev/null +++ b/docs/content/en/latest/workspace/workspaces/load_and_put_aac_workspace.md @@ -0,0 +1,86 @@ +--- +title: "load_and_put_aac_workspace" +linkTitle: "load_and_put_aac_workspace" +weight: 135 +superheading: "catalog_workspace." +api_ref: "CatalogWorkspaceService.load_and_put_aac_workspace" +--- + + + +
+

load_and_put_aac_workspace(workspace_id: str, source_dir: Path)

+
+

Load AAC YAML files from source_dir, convert to declarative, and deploy to workspace.

+
+

Parameters

+ + + + + + + + + + + + + + +
nametypedescription
workspace_id +str + +Workspace identification string e.g. "demo" +
source_dir +Path + +Path to the directory containing AAC YAML files. +
+

Returns

+None +
+ +## Example + +Deploy AAC YAML files from a local directory to a workspace: + +```python +from pathlib import Path +from gooddata_sdk import GoodDataSdk + +host = "https://www.example.com" +token = "some_user_token" +sdk = GoodDataSdk.create(host, token) + +# Deploy AAC YAML files to workspace +sdk.catalog_workspace.load_and_put_aac_workspace( + workspace_id="demo", + source_dir=Path("analytics") +) +``` + +The AAC YAML directory can contain typed subdirectories: + +``` +analytics/ + datasets/ + campaigns.yaml + orders.yaml + metrics/ + revenue.yaml + visualisations/ + revenue_chart.yaml + dashboards/ + overview.yaml +``` + +Each YAML file has a `type` field that determines its kind: + +```yaml +type: metric +id: revenue +title: Revenue +maql: SELECT SUM({fact/amount}) +format: "#,##0" +```