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

Logical Data Model (LDM) API 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.

For more details, 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 Data Analysis 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:
    (see Generate a MAQL DDL script API documentation)

    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

This functionality allows you to 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. By using this API you can easily automate this process.