GoodData Python SDK Documentation

GoodData Python SDK provides a clean and convenient Python API to interact with GoodData.CN and GoodData Cloud.

At the moment the SDK provides services to inspect and interact with the semantic layer and to consume analytics.

Installation

Requirements

Python 3.7 or newer
GoodData.CN or GoodData Cloud

Installation

Run the following command to install the gooddata-sdk package on your system:

pip install gooddata-sdk

Troubleshooting

On MacOS, I am getting an error containig following message:

(Caused by SSLError(SSLCertVerificationError(1, '[SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: unable to get local issuer certificate (_ssl.c:1129)'))).

This likely caused by Python and it occurs if you have installed Python installed directly from python.org. To mitigate this problem, please install your SSL certificates in Macintosh HD -> Applications -> Python -> Install Certificates.command*.

Services

All services are accessible by class gooddata_sdk.GoodDataSdk. The class forms an entry-point to the SDK.

To create an instance of GoodDataSdk:

from gooddata_sdk import GoodDataSdk

# GoodData.CN host in the form of uri eg. "http://localhost:3000"
host = "http://localhost:3000"
# GoodData.CN user token
token = "some_user_token"
sdk = GoodDataSdk.create(host, token)

# Now you can start calling services.
# For example, get a list of all workspaces from my GoodData.CN project
workspaces = sdk.catalog_workspace.list_workspaces()

Catalog Workspace Service

The gooddata_sdk.catalog_workspace service enables you to perform the following actions on workspaces:

Get and list existing workspaces
Update or delete existing workspaces
Create new workspaces
Store and restore workspaces from directory layout structure

The service supports two types of methods:

Entity methods let you work with workspaces on a high level using simplified CatalogWorkspace entities.
Declarative methods allow you to work with workspaces on a more granular level by fetching entire workspace layouts, including all of their nested objects.

Entity methods

The gooddata_sdk.catalog_workspace supports the following entity API calls:

create_or_update(workspace: CatalogWorkspace)

Create a new workspace or overwrite an existing workspace with the same id.
get_workspace(workspace_id: str)

Returns CatalogWorkspace.

Get an individual workspace.
delete_workspace(workspace_id: str)

Delete a workspace with all its content - logical model and analytics model.
list_workspaces()

Returns List[CatalogWorkspace].

Get a list of all existing workspaces.

Example Usage

from gooddata_sdk import GoodDataSdk, CatalogWorkspace

# GoodData.CN host in the form of uri eg. "http://localhost:3000"
host = "http://localhost:3000"
# GoodData.CN user token
token = "some_user_token"
sdk = GoodDataSdk.create(host, token)

# List workspaces
workspaces = sdk.catalog_workspace.list_workspaces()

print(workspaces)
# [
#   CatalogWorkspace(id=demo, name=Demo),
#   CatalogWorkspace(id=demo_west, name=Demo West),
#   CatalogWorkspace(id=demo_west_california, name=Demo West California)
# ]

# Create new workspace entity locally
my_workspace_object = CatalogWorkspace(workspace_id="test_demo",
                                       name="Test demo",
                                       parent_id="demo")

# Create workspace
sdk.catalog_workspace.create_or_update(workspace=my_workspace_object)

# Edit local workspace entity
my_workspace_object.name = "Test"

# Update workspace
sdk.catalog_workspace.create_or_update(workspace=my_workspace_object)

# Get workspace
workspace = sdk.catalog_workspace.get_workspace(workspace_id="test_demo")

print(workspace)
# CatalogWorkspace(id=test_demo, name=Test)

# Delete workspace
sdk.catalog_workspace.delete_workspace(workspace_id="test_demo")

Declarative methods

The gooddata_sdk.catalog_workspace supports the following declarative API calls:

Workspaces

get_declarative_workspaces()

Returns CatalogDeclarativeWorkspaces.

Retrieve layout of all workspaces and their hierarchy.
put_declarative_workspaces(workspace: CatalogDeclarativeWorkspaces)

Set layout of all workspaces and their hierarchy.

store_declarative_workspaces(layout_root_path: Path = Path.cwd())

Store workspaces layouts in directory hierarchy.

gooddata_layouts
└── organization_id
        ├── workspaces
        │       ├── workspace_a
        │       │       ├── analytics_model
        │       │       │   ├── analytical_dashboards
        │       │       │   │       └── analytical_dashboard.yaml
        │       │       │   ├── dashboard_plugins
        │       │       │   │       └── dashboard_plugin.yaml
        │       │       │   ├── filter_contexts
        │       │       │   │       └── filter_context.yaml
        │       │       │   ├── metrics
        │       │       │   │       └── metric.yaml
        │       │       │   └── visualization_objects
        │       │       │           └── visualization_object.yaml
        │       │       ├── ldm
        │       │       │   ├── datasets
        │       │       │   │       └── dataset.yaml
        │       │       │   └── date_instances
        │       │       │           └── date_instance.yaml
        │       │       └── workspace_a.yaml
        │       └── workspace_b
        │               └── ...
        │
        └── workspaces_data_filters
                ├── filter_1.yaml
                └── filter_2.yaml

load_declarative_workspaces(layout_root_path: Path = Path.cwd())

Returns CatalogDeclarativeWorkspaces.

Load declarative workspaces layout, which was stored using store_declarative_workspaces.
load_and_put_declarative_workspaces(layout_root_path: Path = Path.cwd())

This method combines load_declarative_workspaces and put_declarative_workspaces methods to load and set layouts stored using store_declarative_workspaces.

Workspace

get_declarative_workspace(workspace_id: str)

Returns CatalogDeclarativeWorkspaceModel.

Retrieve a workspace layout.
put_declarative_workspace(workspace_id: str)

Set a workspace layout.

store_declarative_workspace(workspace_id: str, layout_root_path: Path = Path.cwd())``

Store workspace layout in directory hierarchy.

gooddata_layouts
└── organization_id
        └── workspaces
                └── workspace_a
                        ├── analytics_model
                        │   ├── analytical_dashboards
                        │   │       └── analytical_dashboard.yaml
                        │   ├── dashboard_plugins
                        │   │       └── dashboard_plugin.yaml
                        │   ├── filter_contexts
                        │   │       └── filter_context.yaml
                        │   ├── metrics
                        │   │       └── metric.yaml
                        │   └── visualization_objects
                        │           └── visualization_object.yaml
                        └── ldm
                            ├── datasets
                            │       └── dataset.yaml
                            └── date_instances
                                    └── date_instance.yaml

load_declarative_workspace(workspace_id: str, layout_root_path: Path = Path.cwd())

Returns CatalogDeclarativeWorkspaceModel.

Load declarative workspaces layout, which was stored using store_declarative_workspace.
load_and_put_declarative_workspace(workspace_id: str, layout_root_path: Path = Path.cwd())

This method combines load_declarative_workspace and put_declarative_workspace methods to load and set layouts stored using store_declarative_workspace.

Workspace data filters

get_declarative_workspace_data_filters()

Returns CatalogDeclarativeWorkspaceDataFilters.

Retrieve a workspace data filter layout.
put_declarative_workspace_data_filters(workspace_data_filters: CatalogDeclarativeWorkspaceDataFilters)

Set a workspace data filter layout.

store_declarative_workspace_data_filters(layout_root_path: Path = Path.cwd())

Store workspace data filters in directory hierarchy.

gooddata_layouts
└── organization_id
        └── workspaces_data_filters
                ├── filter_1.yaml
                └── filter_2.yaml

load_declarative_workspace_data_filters(layout_root_path: Path = Path.cwd())

Returns CatalogDeclarativeWorkspaceDataFilters.

Load declarative workspaces layout, which was stored using store_declarative_workspace_data_filters.
load_and_put_declarative_workspace_data_filters(layout_root_path: Path = Path.cwd())

This method combines load_declarative_workspace_data_filters and put_declarative_workspace_data_filters methods to load and set layouts stored using store_declarative_workspace_data_filters.

Example Usage

from gooddata_sdk import GoodDataSdk
from pathlib import Path

# GoodData.CN host in the form of uri eg. "http://localhost:3000"
host = "http://localhost:3000"
# GoodData.CN user token
token = "some_user_token"
sdk = GoodDataSdk.create(host, token)

backup_path = Path("workspace_hierarchy_backup")

# First create a backup of all workspace layout
sdk.catalog_workspace.store_declarative_workspaces(layout_root_path=backup_path)

# Get workspace layout
workspace_layout = sdk.catalog_workspace.get_declarative_workspace(workspace_id="demo")

# Modify workspace layout
workspace_layout.ldm.datasets[0].description = "This is test"

# Update the workspace layout on the server with your changes
sdk.catalog_workspace.put_declarative_workspace(workspace_id="demo",
                                                workspace=workspace_layout)

# If something goes wrong, use your backup to restore your workspaces from backup
sdk.catalog_workspace.load_and_put_declarative_workspaces(layout_root_path=backup_path)

Catalog Workspace Content Service

The gooddata_sdk.catalog_workspace_content service enables you to list catalog all objects from a workspace. These objects include:

Datasets
Metrics
Facts
Attributes

The service enables read, put, load and store of declarative layout for LDM (logical data model) and analytics model.

The service supports two types of methods:

Entity methods let you work with workspace content on a high level using simplified entities.
Declarative methods allow you to work with workspace content on a more granular level by fetching entire workspace content layouts, including all of their nested objects.

Entity methods

The gooddata_sdk.catalog_workspace_content supports the following entity API calls:

get_full_catalog(workspace_id: str)

Returns CatalogWorkspaceContent.

Retrieve all datasets with attributes, facts, and metrics for a workspace.
get_attributes_catalog(workspace_id: str)

Returns list[CatalogAttribute]

Retrieve all attributes for a workspace.
get_labels_catalog(workspace_id: str)

Returns list[CatalogLabel]

Retrieve all labels for a workspace.
get_metrics_catalog(workspace_id: str)

Returns list[CatalogMetric]

Retrieve all metrics for a workspace.
get_facts_catalog(workspace_id: str)

Returns list[CatalogFact]

Retrieve all facts for a workspace.
get_dependent_entities_graph(workspace_id: str)

Returns CatalogDependentEntitiesResponse

There are dependencies among all catalog objects, the chain is the following:

fact/attribute/label -> dataset -> metric -> insight -> dashboard

Some steps can be skipped, e.g. fact -> insight

We do not support table -> dataset dependency yet.
get_dependent_entities_graph_from_entry_points(workspace_id: str, dependent_entities_request: CatalogDependentEntitiesRequest)

Returns CatalogDependentEntitiesResponse

Extends get_dependent_entities_graph with the entry point from which the graph is created.

Example Usage

from gooddata_sdk import GoodDataSdk

# GoodData.CN host in the form of uri eg. "http://localhost:3000"
host = "http://localhost:3000"
# GoodData.CN user token
token = "some_user_token"
sdk = GoodDataSdk.create(host, token)

workspace_id = "demo"

# Read catalog for demo workspace
catalog = sdk.catalog_workspace_content.get_full_catalog(workspace_id)

# Print all dataset in the workspace
for dataset in catalog.datasets:
    print(str(dataset))

# Print all metrics in the workspace
for metric in catalog.metrics:
    print(str(metric))

# Read list of attributes for demo workspace
attributes = sdk.catalog_workspace_content.get_attributes_catalog(workspace_id)

# Read list of facts for demo workspace
facts = sdk.catalog_workspace_content.get_facts_catalog(workspace_id)

Declarative methods

The gooddata_sdk.catalog_workspace_content supports the following declarative API calls:

Logical data model (LDM)

get_declarative_ldm(workspace_id: str)

Returns CatalogDeclarativeModel.

Retrieve a logical model layout. On CatalogDeclarativeModel user can call modify_mapped_data_source(data_source_mapping: dict) method, which substitutes data source id in datasets.
put_declarative_ldm(workspace_id: str, ldm: CatalogDeclarativeModel, validator: Optional[DataSourceValidator])

Put a logical data model into a given workspace. You can pass an additional validator parameter which checks that for every data source id in the logical data model the corresponding data source exists.
store_ldm_to_disk(self, workspace_id: str, path: Path = Path.cwd())
Store the ldm layout in the directory for a given workspace. The directory structure below shows the output for the path set to Path("ldm_location").
ldm_location └── ldm ├── datasets │ └── dataset.yaml └── date_instances └── date_instance.yaml
load_ldm_from_disk(self, path: Path = Path.cwd())

The method is used to load ldm stored to disk using method store_ldm_to_disk.

store_declarative_ldm(workspace_id: str, layout_root_path: Path = Path.cwd())

Store logical data model layout in directory hierarchy.

gooddata_layouts
└── organization_id
        └── workspaces
                └── workspace_id
                        └── analytics_model
                                └── ldm
                                    ├── datasets
                                    │       └── dataset.yaml
                                    └── date_instances
                                            └── date_instance.yaml

load_declarative_ldm(workspace_id: str, layout_root_path: Path = Path.cwd())

Returns CatalogDeclarativeModel.

Load declarative LDM layout, which was stored using store_declarative_ldm.
load_and_put_declarative_ldm(workspace_id: str, layout_root_path: Path = Path.cwd(), validator: Optional[DataSourceValidator])

This method combines load_declarative_ldm and put_declarative_ldm methods to load and set layouts stored using store_declarative_ldm. You can pass an additional validator parameter which checks that for every data source id in the logical data model the corresponding data source exists.

Analytics Model

get_declarative_analytics_model(workspace_id: str)

Returns CatalogDeclarativeAnalytics.

Retrieve an analytics model layout.
put_declarative_analytics_model(workspace_id: str, analytics_model: CatalogDeclarativeAnalytics)

Put an analytics model into a given workspace.

store_analytics_model_to_disk(self, workspace_id: str, path: Path = Path.cwd())

Store the analytics model layout in the directory for a given workspace. The directory structure below shows the output for the path set to Path("analytics_model_location").

analytics_model_location
         └── analytics_model
                   ├── analytical_dashboards
                   │       └── analytical_dashboard.yaml
                   ├── dashboard_plugins
                   │       └── dashboard_plugin.yaml
                   ├── filter_contexts
                   │       └── filter_context.yaml
                   ├── metrics
                   │       └── metric.yaml
                   └── visualization_objects
                           └── visualization_object.yaml

load_analytics_model_from_disk(self, path: Path = Path.cwd())

The method is used to load analytics model stored to disk using method store_analytics_model_to_disk.

store_declarative_analytics_model(workspace_id: str, layout_root_path: Path = Path.cwd())

Store declarative analytics model layout in directory hierarchy.

gooddata_layouts
└── organization_id
        └── workspaces
                └── workspace_id
                        └── analytics_model
                                ├── analytical_dashboards
                                │       └── analytical_dashboard.yaml
                                ├── dashboard_plugins
                                │       └── dashboard_plugin.yaml
                                ├── filter_contexts
                                │       └── filter_context.yaml
                                ├── metrics
                                │       └── metric.yaml
                                └── visualization_objects
                                        └── visualization_object.yaml

load_declarative_analytics_model(workspace_id: str, layout_root_path: Path = Path.cwd())

Returns CatalogDeclarativeAnalytics.

Load declarative LDM layout, which was stored using store_declarative_analytics_model.
load_and_put_declarative_analytics_model(workspace_id: str, layout_root_path: Path = Path.cwd())

This method combines load_declarative_analytics_model and put_declarative_analytics_model methods to load and set layouts stored using store_declarative_analytics_model.

Example usage:

from gooddata_sdk import GoodDataSdk

# GoodData.CN host in the form of uri eg. "http://localhost:3000"
host = "http://localhost:3000"
# GoodData.CN user token
token = "some_user_token"
sdk = GoodDataSdk.create(host, token)

workspace_id = "demo"

# Get ldm object afterward you can modify it
ldm = sdk.catalog_workspace_content.get_declarative_ldm(workspace_id=workspace_id)

# Modify data source id for datasets
ldm.modify_mapped_data_source({"demo-test-ds": "demo-prod-ds"})

# Put ldm object back to server
sdk.catalog_workspace_content.put_declarative_ldm(workspace_id=workspace_id, ldm=ldm)

# Get analytics model object afterward you can modify it
analytics_model = sdk.catalog_workspace_content.get_declarative_analytics_model(workspace_id=workspace_id)

# Put analytics model object back to server
sdk.catalog_workspace_content.put_declarative_analytics_model(workspace_id=workspace_id,
                                                              analytics_model=analytics_model)

Catalog Data Source Service

The gooddata_sdk.catalog_data_source service enables you to manage data sources and list their tables. Data source object represents your database, which you integrate with GoodData.CN.

Generally there are two ways how to register data sources:

The default way works for all data source types: You specify jdbc url, data source type and relevant credentials.
Customized way for each of the different data source types. You specify custom attributes relevant for your data source and data source type and the url is set in background.

The service supports three types of methods:

Entity methods let you work with data sources on a high level using simplified CatalogDataSource entities.
Declarative methods allow you to work with data sources on a more granular level by fetching entire workspace layouts, including all of their nested objects.
Action methods let you perform an execution of some form of computation.

Entity methods

The gooddata_sdk.catalog_data_source supports the following entity API calls:

create_or_update_data_source(data_source: CatalogDataSource)

Create or update data source.
get_data_source(data_source_id: str)

Returns CatalogDataSource.

Retrieve data source using data source id.
delete_data_source(data_source_id: str)

Delete data source using data source id.
patch_data_source_attributes(data_source_id: str, attributes: dict)

Allows you to apply changes to the given data source.
list_data_sources()

Returns List[CatalogDataSource].

Lists all data sources.
list_data_source_tables(data_source_id: str)

Returns List[CatalogDataSourceTable]

Lists all tables for a data source specified by id.

Example Usage

from gooddata_sdk import GoodDataSdk
from gooddata_sdk import (
    CatalogDataSource,
    BasicCredentials,
    CatalogDataSourcePostgres,
    PostgresAttributes,
    CatalogDataSourceSnowflake,
    SnowflakeAttributes,
    CatalogDataSourceBigQuery,
    BigQueryAttributes,
    TokenCredentialsFromFile
)

# GoodData.CN host in the form of uri eg. "http://localhost:3000"
host = "http://localhost:3000"
# GoodData.CN user token
token = "some_user_token"
sdk = GoodDataSdk.create(host, token)

# Create (or update) data source using general interface - can be used for any type of data source
# If data source already exists, it is updated
sdk.catalog_data_source.create_or_update_data_source(
    CatalogDataSource(
        id="test",
        name="Test2",
        type="POSTGRESQL",
        url="jdbc:postgresql://localhost:5432/demo",
        schema="demo",
        credentials=BasicCredentials(
            username="demouser",
            password="demopass",
        ),
        enable_caching=False,
        url_params=[("param", "value")]
    )
)

# Use Postgres specific interface
sdk.catalog_data_source.create_or_update_data_source(
    CatalogDataSourcePostgres(
        id="test",
        name="Test2",
        db_specific_attributes=PostgresAttributes(
            host="localhost", db_name="demo"
        ),
        schema="demo",
        credentials=BasicCredentials(
            username="demouser",
            password="demopass",
        ),
        enable_caching=False,
        url_params=[("param", "value")]
    )
)

# Create Snowflake data source using specialized interface
sdk.catalog_data_source.create_or_update_data_source(
    CatalogDataSourceSnowflake(
        id="test",
        name="Test2",
        db_specific_attributes=SnowflakeAttributes(
            account="mycompany", warehouse="MYWAREHOUSE", db_name="MYDATABASE"
        ),
        schema="demo",
        credentials=BasicCredentials(
            username="demouser",
            password="demopass",
        ),
        enable_caching=False,
        url_params=[("param", "value")]
    )
)

# BigQuery requires path to credentials file, where service account definition is stored
sdk.catalog_data_source.create_or_update_data_source(
    CatalogDataSourceBigQuery(
        id="test",
        name="Test",
        db_specific_attributes=BigQueryAttributes(
            project_id="project_id"
        ),
        schema="demo",
        credentials=TokenCredentialsFromFile(
            file_path=Path("credentials") / "bigquery_service_account.json"
        ),
        enable_caching=True,
        cache_path=["cache_schema"],
        url_params=[("param", "value")]
    )
)

# Look for other CatalogDataSource classes to find your data source type

# List data sources
data_sources = sdk.catalog_data_source.list_data_sources()

# Get single data source
data_sources = sdk.catalog_data_source.get_data_source(data_source_id='test')

# Patch data source attribute(s)
sdk.catalog_data_source.patch_data_source_attributes(data_source_id="test",
                                                     attributes={"name": "Name2"})

# Delete data source
sdk.catalog_data_source.delete_data_source(data_source_id='test')

Declarative methods

The gooddata_sdk.catalog_data_source supports the following declarative API calls:

Data sources

get_declarative_data_sources()

Returns CatalogDeclarativeDataSources.

Retrieve all data sources, including their related physical model.
put_declarative_data_sources(declarative_data_sources: CatalogDeclarativeDataSources, credentials_path: Optional[Path] = None, test_data_sources: bool = False)

Set all data sources, including their related physical model.

store_declarative_data_sources(layout_root_path: Path = Path.cwd())

Store data sources layouts in directory hierarchy.

gooddata_layouts
└── organization_id
        └── data_sources
                ├── data_source_a
                │       ├── pdm
                │       │   ├── table_A.yaml
                │       │   └── table_B.yaml
                │       └── data_source_a.yaml
                └── data_source_b
                        └── pdm
                        │   ├── table_X.yaml
                        │   └── table_Y.yaml
                        └── data_source_b.yaml

load_declarative_data_sources(layout_root_path: Path = Path.cwd())

Returns CatalogDeclarativeDataSources.

Load declarative data sources layout, which was stored using store_declarative_data_sources.
load_and_put_declarative_data_sources(layout_root_path: Path = Path.cwd(), credentials_path: Optional[Path] = None, test_data_sources: bool = False)

This method combines load_declarative_data_sources and put_declarative_data_sources methods to load and set layouts stored using store_declarative_data_sources.

Physical data model (PDM)

get_declarative_pdm(data_source_id: str)

Returns CatalogDeclarativeTables.

Retrieve physical model for a given data source.
put_declarative_pdm(data_source_id: str, declarative_tables: CatalogDeclarativeTables)

Set physical model for a given data source.
store_pdm_to_disk(self, datasource_id: str, path: Path = Path.cwd())
Store the physical model layout in the directory for a given data source. The directory structure below shows the output for the path set to Path("pdm_location").
pdm_location └── pdm ├── table_A.yaml └── table_B.yaml
load_pdm_from_disk(self, path: Path = Path.cwd())

The method is used to load pdm stored to disk using method store_pdm_to_disk.

store_declarative_pdm(data_source_id: str, layout_root_path: Path = Path.cwd())

Store physical model layout in directory hierarchy for a given data source.

gooddata_layouts
└── organization_id
        └── data_sources
                └── data_source_a
                        └── pdm
                            ├── table_A.yaml
                            └── table_B.yaml

load_declarative_pdm(data_source_id: str, layout_root_path: Path = Path.cwd())

Returns CatalogDeclarativeTables.

Load declarative physical model layout, which was stored using store_declarative_pdm for a given data source.
load_and_put_declarative_pdm(self, data_source_id: str, layout_root_path: Path = Path.cwd())

This method combines load_declarative_pdm and put_declarative_pdm methods to load and set layouts stored using store_declarative_pdm.

Example usage:

from gooddata_sdk import GoodDataSdk
from pathlib import Path

# GoodData.CN host in the form of uri eg. "http://localhost:3000"
host = "http://localhost:3000"
# GoodData.CN user token
token = "some_user_token"
sdk = GoodDataSdk.create(host, token)

# Get all data sources
ds_objects = sdk.catalog_data_source.get_declarative_data_sources()

print(ds_objects.data_sources[0])
# CatalogDeclarativeDataSource(id=demo-test-ds, type=POSTGRESQL)

# Put data sources with credentials and test data source connection before put
sdk.catalog_data_source.put_declarative_data_sources(declarative_data_sources=ds_objects,
                                                    credentials_path=Path("credentials"),
                                                    test_data_sources=True)

Action methods

The gooddata_sdk.catalog_data_source supports the following action API calls:

Example usage:

from gooddata_sdk import GoodDataSdk, CatalogGenerateLdmRequest

# GoodData.CN host in the form of uri eg. "http://localhost:3000"
host = "http://localhost:3000"
# GoodData.CN user token
token = "some_user_token"
sdk = GoodDataSdk.create(host, token)

data_source_id = "demo-test-ds"

# Scan schemata of the data source
schemata = sdk.catalog_data_source.scan_schemata(data_source_id=data_source_id)
print(schemata)
# ['demo']

# Scan and put pdm
sdk.catalog_data_source.scan_and_put_pdm(data_source_id=data_source_id)

# Define request for generating ldm
generate_ldm_request = CatalogGenerateLdmRequest(separator="__")

# Generate ldm
declarative_model = sdk.catalog_data_source.generate_logical_model(data_source_id=data_source_id,
                                                                   generate_ldm_request=generate_ldm_request)

# Invalidate cache of your computed reports
sdk.catalog_data_source.register_upload_notification(data_source_id=data_source_id)

Catalog User Service

The gooddata_sdk.catalog_user service enables you to perform the following actions on users and user groups:

Get and list existing users and user groups
Update or delete existing users and user groups
Create new users and user groups
Store and restore users and user groups from directory layout structure

The service supports two types of methods:

Entity methods let you work with users and user groups on a high level using simplified CatalogUser and CatalogUserGroup entities.
Declarative methods allow you to work with users and user groups on a more granular level by fetching entire users and user groups layouts.

Entity methods

Users

The gooddata_sdk.catalog_user supports the following user entity API calls:

create_or_update_user(user: CatalogUser)

Create a new user or overwrite an existing user.
get_user(user_id: str)

Returns CatalogUser.

Get an individual user.
delete_user(user_id: str)

Delete a user.
list_users()

Returns List[CatalogUser].

Get a list of all existing users.

Example Usage

from gooddata_sdk import GoodDataSdk, CatalogUser

# GoodData.CN host in the form of uri eg. "http://localhost:3000"
host = "http://localhost:3000"
# GoodData.CN user token
token = "some_user_token"
sdk = GoodDataSdk.create(host, token)

# List users
users = sdk.catalog_user.list_users()

print(users)
# [
#   CatalogUser(id='demo2',
#               attributes=CatalogUserAttributes(authentication_id='CiRmYmNhNDkwOS04YzYxLTRmMTYtODI3NC1iNzI0Njk1Y2FmNTESBWxvY2Fs'),
#               relationships=CatalogUserRelationships(user_groups=CatalogUserGroupsData(data=[CatalogUserGroup(id='demoGroup', relationships=None)]))),
#   ...
# ]

# Define user
user = CatalogUser.init(user_id="abc", authentication_id="xyz",user_group_ids=["demoGroup"])

# Create user
sdk.catalog_user.create_or_update_user(user=user)

# Delete user
sdk.catalog_user.delete_user(user_id=user.id)

User groups

The gooddata_sdk.catalog_user supports the following user groups entity API calls:

create_or_update_user_group(user_group: CatalogUserGroup)

Create a new user group or overwrite an existing user group.
get_user_group(user_group_id: str)

Returns CatalogUserGroup.

Get an individual user group.
delete_user_group(user_group_id: str)

Delete a user group.
list_user_groups()

Returns List[CatalogUserGroup].

Get a list of all existing user groups.

Example Usage

from gooddata_sdk import GoodDataSdk, CatalogUserGroup

# GoodData.CN host in the form of uri eg. "http://localhost:3000"
host = "http://localhost:3000"
# GoodData.CN user token
token = "some_user_token"
sdk = GoodDataSdk.create(host, token)

# List user groups
user_groups = sdk.catalog_user.list_user_groups()

print(user_groups)
#[
#    CatalogUserGroup(id='adminGroup', relationships=None),
#    CatalogUserGroup(id='adminQA1Group',
#                     relationships=CatalogUserGroupRelationships(parents=CatalogUserGroupParents(data=[CatalogUserGroup(id='adminGroup', relationships=None)])))
#    ...
#]

# Define user
user_group = CatalogUserGroup.init(user_group_id="xyz", user_group_parent_ids=["demoGroup"])

# Create user
sdk.catalog_user.create_or_update_user_group(user_group=user_group)

# Delete user
sdk.catalog_user.delete_user_group(user_group_id=user_group.id)

Declarative methods

Users

The gooddata_sdk.catalog_user supports the following declarative user API calls:

get_declarative_users()

Returns CatalogDeclarativeUsers.

Retrieve all users including authentication properties.
put_declarative_users(users: CatalogDeclarativeUsers)

Set all users and their authentication properties.

store_declarative_users(layout_root_path: Path = Path.cwd())

Store users in directory hierarchy.

gooddata_layouts
└── organization_id
        └── users
                └── users.yaml

load_declarative_users(layout_root_path: Path = Path.cwd())

Load users from directory hierarchy.
load_and_put_declarative_users(layout_root_path: Path = Path.cwd())

This method combines load_declarative_users and put_declarative_users methods to load and set users stored using store_declarative_users.

Example Usage

from gooddata_sdk import GoodDataSdk

# GoodData.CN host in the form of uri eg. "http://localhost:3000"
host = "http://localhost:3000"
# GoodData.CN user token
token = "some_user_token"
sdk = GoodDataSdk.create(host, token)

# Get user layout
user_layout = sdk.catalog_user.get_declarative_users()

print(user_layout)
# CatalogDeclarativeUsers(
#          users=[
#                   CatalogDeclarativeUser(id='admin',
#                                          auth_id=None,
#                                          user_groups=[CatalogUserGroupIdentifier(id='adminGroup', type='userGroup')]),
#                   CatalogDeclarativeUser(id='demo',...
# ...

# Modify user layout
user_layout.users = []

# Update user layout
sdk.catalog_user.put_declarative_users(users=user_layout)

User groups

The gooddata_sdk.catalog_user supports the following declarative user groups API calls:

get_declarative_user_groups()

Returns CatalogDeclarativeUserGroups.

Retrieve all user-groups eventually with parent group.
put_declarative_user_groups(user_groups: CatalogDeclarativeUserGroups)

Set all user groups with their parents eventually.

store_declarative_user_groups(layout_root_path: Path = Path.cwd())

Store user groups in directory hierarchy.

gooddata_layouts
└── organization_id
        └── user_groups
                └── user_groups.yaml

load_declarative_user_groups(layout_root_path: Path = Path.cwd())

Returns CatalogDeclarativeUserGroups.

Load user groups from directory hierarchy.
load_and_put_declarative_user_groups(layout_root_path: Path = Path.cwd())

This method combines load_declarative_user_groups and put_declarative_user_groups methods to load and set user groups stored using store_declarative_user_groups.

Example Usage

from gooddata_sdk import GoodDataSdk

# GoodData.CN host in the form of uri eg. "http://localhost:3000"
host = "http://localhost:3000"
# GoodData.CN user token
token = "some_user_token"
sdk = GoodDataSdk.create(host, token)

# Get user layout
user_group_layout = sdk.catalog_user.get_declarative_user_groups()

print(user_group_layout)
# CatalogDeclarativeUserGroups(
#          user_groups=[
#                   CatalogDeclarativeUserGroup(id='adminGroup', parents=None),
# ...

# Modify user group layout
user_group_layout.user_groups = []

# Update user group layout
sdk.catalog_user.put_declarative_users(users=user_group_layout)

Users and user groups

The gooddata_sdk.catalog_user supports the following declarative users and user groups API calls:

get_declarative_users_user_groups()

Returns CatalogDeclarativeUsersUserGroups.

Retrieve all users and all user-groups.
put_declarative_users_user_groups(users_user_groups: CatalogDeclarativeUsersUserGroups)

Set all users and user groups.

store_declarative_users_user_groups(layout_root_path: Path = Path.cwd())

Store users and user groups in directory hierarchy.

gooddata_layouts
└── organization_id
        ├── users
        │      └── users.yaml
        └── user_groups
                └── user_groups.yaml

load_declarative_users_user_groups(layout_root_path: Path = Path.cwd())

Returns CatalogDeclarativeUsersUserGroups.

Load users and user groups from directory hierarchy.
load_and_put_declarative_users_user_groups(layout_root_path: Path = Path.cwd())

This method combines load_declarative_users_user_groups and put_declarative_users_user_groups methods to load and set users and user groups stored using store_declarative_users_user_groups.

Catalog Permission Service

The gooddata_sdk.catalog_permission service enables you to perform the following actions on permissions:

Get and set declarative permissions

Declarative methods

The gooddata_sdk.catalog_permission supports the following declarative API calls:

get_declarative_permissions(workspace_id: str)

Returns CatalogDeclarativeWorkspacePermissions.

Retrieve current set of permissions of the workspace in a declarative form.
put_declarative_permissions(workspace_id: str, declarative_workspace_permissions: CatalogDeclarativeWorkspacePermissions)

Set effective permissions for the workspace.

Example Usage

from gooddata_sdk import GoodDataSdk

# GoodData.CN host in the form of uri eg. "http://localhost:3000"
host = "http://localhost:3000"
# GoodData.CN user token
token = "some_user_token"
sdk = GoodDataSdk.create(host, token)

workspace_id = "demo"

# Get permissions in declarative from
declarative_permissions = sdk.catalog_permission.get_declarative_permissions(workspace_id=workspace_id)

declarative_permissions.permissions = []

# Update permissions on the server with your changes
sdk.catalog_permission.put_declarative_permissions(workspace_id=workspace_id,
                                                   declarative_workspace_permissions=declarative_permissions)

Catalog Organization Service

The gooddata_sdk.catalog_organization service enables you to perform the following actions on organization:

Update OIDC parameters
Update organization name

Entity methods

The gooddata_sdk.catalog_organization supports the following entity API calls:

update_oidc_parameters(oauth_issuer_location: Optional[str] = None, oauth_client_id: Optional[str] = None, oauth_client_secret: Optional[str] = None)

Update OIDC parameters of organization.
update_name(name: str)

Update name of organization.

Example Usage

from gooddata_sdk import GoodDataSdk

# GoodData.CN host in the form of uri eg. "http://localhost:3000"
host = "http://localhost:3000"
# GoodData.CN user token
token = "some_user_token"
sdk = GoodDataSdk.create(host, token)

# Update organization name
sdk.catalog_organization.update_name(name="new_organization_name")

# Update OIDC provider
sdk.catalog_organization.update_oidc_parameters(oauth_client_id="oauth_client_id",
                                                oauth_issuer_location="oauth_issuer_location",
                                                oauth_client_secret="oauth_client_secret")

Insights Service

The gooddata_sdk.insights service gives you access to insights stored in a workspace. It can retrieve all the insights from a workspace or one insight based on its name. Insight instance is the input for other services like a Table service

Entity methods

The gooddata_sdk.insights supports the following entity API calls:

get_insights(workspace_id: str)

Returns list[Insight].

Retrieve a list of Insight objects.

Example usage:

Read all insights in a workspace:

from gooddata_sdk import GoodDataSdk

# GoodData.CN host in the form of uri eg. "http://localhost:3000"
host = "http://localhost:3000"
# GoodData.CN user token
token = "some_user_token"
sdk = GoodDataSdk.create(host, token)

workspace_id = "demo"

# Reads insights from workspace
insights = sdk.insights.get_insights(workspace_id)
# Print all fetched insights
for insight in insights:
    print(str(insight))

Compute Service

The gooddata_sdk.compute service drives computation of analytics for GoodData.CN workspaces. The prescription of what to compute is encapsulated by the ExecutionDefinition which consists of attributes, metrics, filters and definition of dimensions that influence how to organize the data in the result.

Higher level services like Table service use Compute service to execute computation in GoodData.CN. Higher level service is also responsible for results presentation to the user e.g. in tabular form.

The gooddata_sdk.compute supports the following entity API calls:

for_exec_def(workspace_id: str, exec_def: ExecutionDefinition)

Returns Execution.

Starts computation in GoodData.CN workspace, using the provided execution definition.

Example:

from gooddata_sdk import GoodDataSdk, ExecutionDefinition, Attribute, SimpleMetric, ObjId

sdk = GoodDataSdk.create(host, token)
workspace_id = "demo"

exec_def = ExecutionDefinition(
    attributes=[
        Attribute(local_id="region", label="region"),
        Attribute(local_id="product_category", label="products.category"),
        Attribute(local_id="state", label="state"),
    ],
    metrics=[
        SimpleMetric(local_id="price", item=ObjId(id="price", type="fact")),
        SimpleMetric(local_id="order_amount", item=ObjId(id="order_amount", type="metric")),
    ],
    filters=[],
    dimensions=[["region", "state"], ["product_category", "measureGroup"]],
)
execution = sdk.compute.for_exec_def(workspace_id, exec_def)

# currently there is no dedicated service for exporting *Execution* results into XLSX/CSV, however it's possible to run it this way:

from gooddata_api_client.model.tabular_export_request import TabularExportRequest

filename = "export.xlsx"
export_request = sdk.client.actions_api.create_tabular_export(
    workspace_id,
    TabularExportRequest(
        execution_result=execution.result_id,
        file_name=filename,
        format="XLSX",
    )
)

while response := sdk.client.actions_api.get_tabular_export(workspace_id, export_request.export_result, _preload_content=False):
    if (response.status == 202):
        time.sleep(2)
        continue
    elif (response.status == 200):
        with open(filename, 'wb') as out_file:
            out_file.write(response.data)
            break

retrieve_result_cache_metadata(workspace_id: str, result_id: str)

Returns ResultCacheMetadata.

Gets execution result’s metadata from GoodData.CN workspace for given execution result ID.

Table Service

The gooddata_sdk.table service allows you to consume analytics in typical tabular format. The service allows free-form computations and computations of data for GoodData.CN Insights.

The gooddata_sdk.table supports the following entity API calls:

for_insight(workspace_id: str, insight: Insight)

Returns ExecutionTable.

Retrieve data as an ExecutionTable from the given insight.
for_items(workspace_id: str, items: list[Union[Attribute, Metric]], filters: Optional[list[Filter]] = None)

Returns ExecutionTable.

Retrieve data as an ExecutionTable from the given list of attributes/metrics, and filters.

Example usage:

Get tabular data for an insight defined on your GoodData.CN server:

from gooddata_sdk import GoodDataSdk

# GoodData.CN host in the form of uri eg. "http://localhost:3000"
host = "http://localhost:3000"
# GoodData.CN user token
token = "some_user_token"
sdk = GoodDataSdk.create(host, token)

workspace_id = "demo"
insight_id = "some_insight_id_in_demo_workspace"

# Reads insight from workspace
insight = sdk.insights.get_insight(workspace_id, insight_id)

# Triggers computation for the insight. the result will be returned in a tabular form
table = sdk.tables.for_insight(workspace_id, insight)

# This is how you can read data row-by-row and do something with it
for row in table.read_all():
    print(row)

# An example of data printed for insight top_10_products
# {'781952e728204dcf923142910cc22ae2': 'Biolid', 'fe513cef1c6244a5ac21c5f49c56b108': 'Outdoor', '77dc71bbac92412bac5f94284a5919df': 34697.71}
# {'781952e728204dcf923142910cc22ae2': 'ChalkTalk', 'fe513cef1c6244a5ac21c5f49c56b108': 'Home', '77dc71bbac92412bac5f94284a5919df': 17657.35}
# {'781952e728204dcf923142910cc22ae2': 'Elentrix', 'fe513cef1c6244a5ac21c5f49c56b108': 'Outdoor', '77dc71bbac92412bac5f94284a5919df': 27662.09}
# {'781952e728204dcf923142910cc22ae2': 'Integres', 'fe513cef1c6244a5ac21c5f49c56b108': 'Outdoor', '77dc71bbac92412bac5f94284a5919df': 47766.74}
# {'781952e728204dcf923142910cc22ae2': 'Magnemo', 'fe513cef1c6244a5ac21c5f49c56b108': 'Electronics', '77dc71bbac92412bac5f94284a5919df': 44026.52}
# {'781952e728204dcf923142910cc22ae2': 'Neptide', 'fe513cef1c6244a5ac21c5f49c56b108': 'Outdoor', '77dc71bbac92412bac5f94284a5919df': 99440.44}
# {'781952e728204dcf923142910cc22ae2': 'Optique', 'fe513cef1c6244a5ac21c5f49c56b108': 'Home', '77dc71bbac92412bac5f94284a5919df': 40307.76}
# {'781952e728204dcf923142910cc22ae2': 'PortaCode', 'fe513cef1c6244a5ac21c5f49c56b108': 'Electronics', '77dc71bbac92412bac5f94284a5919df': 18841.17}
# {'781952e728204dcf923142910cc22ae2': 'Slacks', 'fe513cef1c6244a5ac21c5f49c56b108': 'Clothing', '77dc71bbac92412bac5f94284a5919df': 18469.15}
# {'781952e728204dcf923142910cc22ae2': 'T-Shirt', 'fe513cef1c6244a5ac21c5f49c56b108': 'Clothing', '77dc71bbac92412bac5f94284a5919df': 17937.49}

API Reference

gooddata_sdk

The gooddata-sdk package aims to provide clean and convenient Python APIs to interact with GoodData.CN.