This blog post is part of a series of blogs I published about @sap/datasphere-cli. Find all blog posts related to this topic in my overview blog post here.

The Node.js-based Command-Line Interface (CLI) for SAP Datasphere, @sap/datasphere-cli hosted on npmjs.com, allows you to interact with your SAP Datasphere tenant from the terminal or command line. With version 2022.02 of the CLI you can create, read, update and delete definitions for tables and views in your spaces in your SAP Datasphere tenant.

Introduction

This blog is part of a blog post series about the Command-Line Interface (CLI) for SAP Datasphere. Find the full overview of all available blogs in the overview blog post here.

Working with definitions of tables and views you create in the Data Builder in your SAP Datasphere tenant is a daily task for any modeler in the SAP Datasphere world. In this blog, I explain how you can use the SAP Datasphere CLI tool to not only create, read, update, and delete spaces, but also create, read update, and delete definitions, more specifically tables and views, graphical as well as SQL views, in your SAP Datasphere tenant.

In other blogs I published earlier I already explain how to install and work with the CLI, plus how to automate the passcode retrieval process to embed the CLI into eg CI/CD processes.

Before you proceed, make sure to install the latest version of the CLI. If you are unsure how to get the latest version, check out my other blog post “New Command-Line Interface for SAP Datasphere – code your way to the cloud!”.

Initializing the CLI

From version 2022.02 and onwards of the CLI, before you can start sending commands to your SAP Datasphere tenant, you need to initialize the CLI. Initializing the CLI will download a JSON file from your SAP Datasphere tenant to your local machine. The JSON file contains a description of all available commands you can send to your SAP Datasphere tenant. Without initializing the CLI first, you will get the standard list of commands available independently of any tenant you work with. To see the available commands for a specific tenant, specify the tenant using the -H, –host option. Add -h, –help to print the list of commands:

$ datasphere -H https://datasphere-my-example-company.eu10.hcs.cloud.sap/ -h
Usage: datasphere [options] [command]

Command-Line Interface for SAP Datasphere.

Options:
  -v, --version           output the current version
  -H, --host <host>       specifies the url host where the tenant is hosted
  -h, --help              display help for command

Commands:
  cache                   work with the local CLI cache
  passcode-url [options]  print the passcode url
  help [command]          display help for command

To initialize the CLI, use the cache-init command:

$ datasphere cache init -H https://datasphere-my-example-company.eu10.hcs.cloud.sap/
✔ Do you want to retrieve a temporary authentication code from https://datasphere-my-example-company.authentication.eu10.hana.ondemand.com/passcode? … yes
✔ Enter your temporary authentication code: … **********

When then printing the list of commands for the same tenant again, you notice that it contains a spaces command:

$ datasphere -H https://datasphere-my-example-company.eu10.hcs.cloud.sap/ -h
Usage: datasphere [options] [command]

Command-Line Interface for SAP Datasphere.

Options:
  -v, --version           output the current version
  -H, --host <host>       specifies the url host where the tenant is hosted
  -h, --help              display help for command

Commands:
  cache                   work with the local CLI cache
  spaces [options]        manage and orchestrate spaces
  passcode-url [options]  print the passcode url
  help [command]          display help for command

Reading Definitions

In my previous blog, I already explained the general usage of the spaces command. With version 2022.02 of the CLI a new option -D, –definitions were added to the spaces read command, allowing you to request definitions of tables and views stored in the specified space:

$ datasphere spaces read -H https://datasphere-my-example-company.eu10.hcs.cloud.sap/ -h
Usage: datasphere spaces read [options]

fetch space details for a specified space

Options:
  -o, --output <output>            specifies the file to store the output of the command
  -S, --space <space>              space ID
  -n, --no-space-definition        read space definition
  -D, --definitions [definitions]  read definitions
  -V, --verbose                    print detailed log information to console (optional)
  -H, --host <host>                specifies the url host where the tenant is hosted
  -p, --passcode <passcode>        passcode for interactive session authentication (optional)
  -h, --help                       display help for command

You probably also notice that there are a few other changes, such as the space ID is now specified by option -S, –space instead of using an argument on the command line, and you can optionally save the returned JSON content in a file using the -o, –output option, which was possible before using the -f, –file-path option. If you only want to retrieve the definitions and omit the space metadata, you can add the -n, –no-space-definition option. If you do not specify the -D, –definitions option no definitions are retrieved from the tenant, and only the space metadata is returned.

To read the space metadata including all existing table and view definitions run

$ datasphere spaces read -H https://datasphere-my-example-company.eu10.hcs.cloud.sap/ -S MYSPACE -D -p somepassword
{
  "MYSPACE": {
    "spaceDefinition": {
      ...
    },
    "definitions": {
      "some_table": {
        "@EndUserText.label": "some table",
        "kind": "entity",
        "elements": {
          ...
        }
      },
      "some_other_table": {
        "@EndUserText.label": "some other table",
        "kind": "entity",
        "elements": {
          ...
        }
      },
      "another_table": {
        "@EndUserText.label": "another table",
        "kind": "entity",
        "elements": {
          ...
        }
      }
    }
  }
}

The -D, –definitions option lets you also specify a comma-separated array of table or view technical names to reduce the returned list of definitions:

$ datasphere spaces read -H https://datasphere-my-example-company.eu10.hcs.cloud.sap/ -S MYSPACE -D some_table,another_table -p somepassword
{
  "MYSPACE": {
    "spaceDefinition": {
      ...
    },
    "definitions": {
      "some_table": {
        "@EndUserText.label": "some table",
        "kind": "entity",
        "elements": {
          ...
        }
      },
      "another_table": {
        "@EndUserText.label": "another table",
        "kind": "entity",
        "elements": {
          ...
        }
      }
    }
  }
}

Creating and Updating Definitions

Creating new tables and views or updating definitions of existing entities is as simple as calling the spaces create command and pointing to a JSON file containing the list of definitions. You specify a new property definitions on the same level as the spaceDefinition property. To get a good overview of the correct syntax and available annotations, how to correctly build the SQL query for a view, and how to define table functions, simply retrieve the definition of a space of your choice including the entity definitions and use the returned JSON content as a template for other spaces or definitions you want to create using the CLI. When you created a JSON file, use the spaces create command to push it to your SAP Datasphere tenant:

$ datasphere spaces create -H https://datasphere-my-example-company.eu10.hcs.cloud.sap/ -f path/to/file.json

Deleting Definitions

Unfortunately, the CLI does not yet support deleting selected definitions of tables and views. You can only delete a complete space, including all its content, through the CLI using the spaces delete command:

$ datasphere spaces delete -H https://datasphere-my-example-company.eu10.hcs.cloud.sap/ -S MYSPACE -p somepasscode
✔ Do you really want to delete space MYSPACE? … yes

Conclusion

Being able to CRUD on definitions within spaces in SAP Datasphere is a super cool next step towards a “programmable” application. This is another great example of how CLI can improve your experience when working with SAP Datasphere to the next level.

I’d be happy to hear your thoughts, ideas, and comments on this tool and what you think would be a nice-to-have enhancement to the CLI, making your life and work with SAP Datasphere easier. Let me know in the comments!

Further Reading

Blog: New Command-Line Interface for SAP Datasphere – code your way to the cloud!

Blog: Automatically Add Members to Spaces in SAP Datasphere Using @sap/datasphere-cli

Command-Line Interface for SAP Datasphere on npmjs.com

Command-Line Interface for SAP Datasphere on SAP Help

Get your SAP Datasphere 30 Days Trial Account