Page tree
Skip to end of metadata
Go to start of metadata

We’ve recently released a new Logical Data Model (LDM) API that allows you to create logical data models in GoodData without having to use our CloudConnect LDM Modeler application or manually compose low-level MAQL DDL scripts.

Contents:

Overview

The two main use cases are:

  • Creating a new model in empty project
  • Updating an existing model

You will need to create a JSON payload that describes your data model and post it to this API. The API will generate a complete and valid MAQL script that you can execute using our ldm/manage2 API.

See the LDM API documentation.

How to Use It

Let’s say we are going to create new logical data model for our well known HR Demo.

The corresponding JSON definition looks as follows:

{
    "projectModel": {
        "datasets": [
            {
                "dataset": {
                    "identifier": "dataset.department",
                    "title": "Department",
                    "anchor": {
                        "attribute": {
                            "identifier": "attr.department.department",
                            "title": "Department",
                            "labels": [
                                {
                                    "label": {
                                        "identifier": "label.department.department",
                                        "title": "Department"
                                    }
                                }
                            ]
                        }
                    }
                }
            },
            {
                "dataset": {
                    "identifier": "dataset.employee",
                    "title": "Employee",
                    "anchor": {
                        "attribute": {
                            "identifier": "attr.employee.employee",
                            "title": "Employee",
                            "folder": "Employee",
                            "labels": [
                                {
                                    "label": {
                                        "identifier": "label.employee.employee",
                                        "title": "Employee",
                                        "dataType": "INT",
                                        "type": "GDC.text"
                                    }
                                },
                                {
                                    "label": {
                                        "identifier": "label.employee.employee.name",
                                        "title": "Employee Name",
                                        "dataType": "VARCHAR(128)",
                                        "type": "GDC.text"
                                    }
                                }
                            ]
                        }
                    },
                    "facts": [
                        {
                            "fact": {
                                "identifier": "fact.employee.age",
                                "title": "Employee Age",
                                "folder": "Employee"
                            }
                        }
                    ],
                    "references": [
                        "dataset.department"
                    ]
                }
            },
            {
                "dataset": {
                    "identifier": "dataset.salary",
                    "title": "Salary",
                    "anchor": {
                        "attribute": {
                            "identifier": "attr.salary.factsof",
                            "title": "Records of Salary",
                            "folder": "Salary"
                        }
                    },
                    "facts": [
                        {
                            "fact": {
                                "identifier": "fact.salary.payment",
                                "title": "Payment",
                                "folder": "Salary",
                                "dataType": "DECIMAL(12,2)"
                            }
                        }
                    ],
                    "references": [
                        "dataset.employee",
                        "payment"
                    ]
                }
            }
        ],
        "dateDimensions": [
            {
                "dateDimension": {
                    "name": "payment",
                    "title": "Payment"
                }
            }
        ]
    }
}


This structure is much more compatible for integrations using your favorite programming language such as Ruby, Python etc. You can store this definition easily in database, add datasets and provision those models.

How do you create this model using the new API?

  1. Simply POST the payload above to the following resource:

    https://secure.gooddata.com/gdc/projects/{project-id}/model/diff


    As a response, you will receive the link to asynchronous task and once you GET this link, you are able to see the result:

    ...
    ...
    ...
    "updateScripts": [
                {
                    "updateScript": {
                        "maqlDdl": "GENERATED-MAQL-SCRIPT",
                        "preserveData": true,
                        "cascadeDrops": false
                    }
                }
    ...
    ...
    ...
  2. Extract the MAQL from the response body, update to comply with the JSON payload for the ldm/manage2 API and use the POST request:

    https://secure.gooddata.com/gdc/md/{project-id}/ldm/manage2
    {
       "manage" : {
          "maql" : "PREVIOUSLY-GENERATED-MAQL-SCRIPT"
       }
    }

    preserveData: true | false -> this flag identifies MAQL with/without “preserve data” statement
    cascadeDrops: true | false -> this flag tells you if the MAQL script contains cascade drops

Making Changes to the Data Model

Making changes is similar to and just as easy as creating a new model. All you need to do is to POST the new model to:

 https://secure.gooddata.com/gdc/projects/{project-id}/model/diff

As a result, you will receive the link to the “update MAQL” script. Once you GET it (see the previous step) - you can POST it to the ldm/manage2 API.

If you are just adding some objects to the model, you don’t need to worry about losing something. If you are deleting something be sure to check the result. All reports and dashboards will be dropped with corresponding objects.

Tip For Developers

With this functionality you can store datasets in the database and create a custom model programmatically. Using this approach, you are able to build a modular solution on the top of GoodData Platform. Imagine a use case where you have 5 (or 50) data sources - each one is single dataset - but you want to select just 2 for client A and other 3 for client B. Using this API you are able to automate this process.