Introduction

Use the Db2 Warehouse on Cloud API to access data, view and create database objects, administer, and monitor your Db2 Warehouse on Cloud service.
 

Attention: This is the DEPRECATED Version 1 of the Db2 Warehouse on Cloud REST API documentation. To view the latest version, click here.

To view other deprecated versions of the REST API documentation, click V2 and V3.

Root URL

The context root for the Db2 Warehouse on Cloud API is /dashdb-api/.

Error handling

This API uses standard HTTP response codes to indicate whether a method completed successfully. A 200 response indicates success. A 400 type response is some sort of failure.

Security

Every request must include the Authorization HTTP header with the value Bearer [access_token]. An access token can be obtained with the /auth/tokens endpoint, and it is used by Db2 Warehouse on Cloud to identify who you are. Db2 Warehouse on Cloud negotiates SSL connections using the TLS v1.2 protocol.

If you are using the latest version of cURL, protocol negotiation will
happen automatically using TLS v1.2.
If you are using an older version of cURL, you will need to specify the
`--tlsv1.2` option in your cURL commands.

Methods

List the contents of the home directory

List the files and folders contained in the home directory.

GET /home

Request

A timestamp in the format "yyyyMMdd HH:mm:ss z". When specified, the list contains only files and folders created after the specified timestamp.

Examples:
View

Response

Status Code

  • Ok

  • Bad Request

  • Unauthorized

  • Not Found

  • Method Not Allowed

No Sample Response

This method does not specify any sample responses.

Upload a file to the home directory

Uploads the specified source file to the home directory.

POST /home

Request

Form Parameters

  • Full path to the source data file on Windows, or relative path on UNIX based operating systems. For each additional file: -F '[name]=@"[filename]"', where [name] is a unique name.

Response

Status Code

  • Ok

  • Bad Request

  • Unauthorized

  • Not Found

  • Method Not Allowed

No Sample Response

This method does not specify any sample responses.

Delete a file or a folder in the home directory

If a file is specified, then that file is deleted. If a folder is specified, then that folder is deleted; the folder must be empty.

DELETE /home/{file_or_folder}

Request

Path Parameters

  • The path of a file or folder relative to the home directory.

Response

Status Code

  • Ok

  • Bad Request

  • Unauthorized

  • Not Found

  • Method Not Allowed

No Sample Response

This method does not specify any sample responses.

Get the contents of a file or list the contents of a folder relative to the home directory

If a file is specified, then the contents of the file is returned. If a folder is specified, then a list of its files and folders is returned.

GET /home/{file_or_folder}

Request

Custom Headers

  • Allowable values: [application/octet-stream,application/json]

Path Parameters

  • The path of a file or folder relative to the home directory.

A timestamp in the format "yyyyMMdd HH:mm:ss z". When specified, the list contains only files and folders created after the specified timestamp.

Examples:
View

Response

Status Code

  • Ok

  • Bad Request

  • Unauthorized

  • Not Found

  • Method Not Allowed

No Sample Response

This method does not specify any sample responses.

Upload a file to a folder relative to the home directory

Uploads the specified source file to a folder relative to the home directory. Folders in the path are created implicitly.

POST /home/{folder}

Request

Path Parameters

  • The target path of the folder relative to the home directory into which the file should be uploaded.

Form Parameters

  • Full path to the source data file on Windows, or relative path on UNIX based operating systems. For each additional file: -F '[name]=@"[filename]"', where [name] is a unique name.

Response

Status Code

  • Ok

  • Bad Request

  • Unauthorized

  • Not Found

  • Method Not Allowed

No Sample Response

This method does not specify any sample responses.

Load local delimited data into a table

Create a load job that streams delimited data from one or more CSV, XLS, or XLSX files and loads it into the specified table. This POST request is asynchronous and returns before the load job is complete. The parameters specified in the POST request apply to all files included in the same request. If different parameters are needed, load the data using a separate POST request.

Use the GET /load/{tableName} or GET /load/{loadID} endpoint to retrieve the status of the load job, and the GET /home/{filename} endpoint to retrieve a detailed load log file.

POST /load/local/del/{tableName}

Request

Path Parameters

  • The schema and table where the data is loaded (schema.'tableName'). The table must exist before the data is loaded.

Query Parameters

  • Indicates if the source data files include column names in a header row. If this option is selected for a multi-file load job, all files must contain a header row. Default value is "false".

    Default: false

  • Column delimiter used in the source file. Valid values are hexadecimal values 0x01 to 0x7F, excluding line-feed (0x0A), carriage return (0x0D), space (0x20), and decimal point (0x2E). You can enter either the hexadecimal or the character value. Default value is "," (corresponds to 0x2C). If a load job includes one or more XLS or XLSX files, all files must use the default delimiter (,).

    Default: ,

  • Specify if the data is inserted as new data or replaces the existing data in the target table. Valid values are "insert" or "replace". Default value is "insert".

    Allowable values: [insert,replace]

    Default: insert

  • The character encoding of the source file. Valid values are listed in Supported territory codes and code pages. Default value is "1208" (corresponds to UTF-8).

    Default: 1208

  • Indicates if the data contains date types. This sets the default date formats for Date (YYYY-MM-DD), Time (HH:MM:SS) and Timestamp (YYYY-MM-DD HH:MM:SS) if they aren't individually set. The default value is "false".

    Default: false

  • A valid date format, such as "DD-MM-YY", "YYYY-MMM-DD", "DD/MM/YYY", "M/D/YYYY", "M/DD", "YYYY". For a full list of supported formats, see 'Valid file type modifiers for the load utility: ASCII file formats (ASC/DEL)' in the LOAD command reference. Default value is "YYYY-MM-DD".

    Default: YYYY-MM-DD

  • A valid time format, such as "HH-MM-SS", "H:MM:SS TT", "HH:MM", "H:MM TT", "H:M", "H:M:S". For a full list of supported formats, see 'Valid file type modifiers for the load utility: ASCII file formats (ASC/DEL)' in the LOAD command reference. Default value is "HH:MM:SS".

    Default: HH:MM:SS

  • A valid timestamp format, such as "YYYY-MM-DD HH:MM:SS", "DD/MM/YYYY H:MM TT", "MMM DD YYYY HH:MM:SS TT". For a full list of supported formats, see 'Valid file type modifiers for the load utility: ASCII file formats (ASC/DEL)' in the LOAD command reference. Default value is "YYYY-MM-DD HH:MM:SS".

    Default: YYYY-MM-DD HH:MM:SS

Form Parameters

  • Full path to the source data file on Windows, or relative path on UNIX based operating systems. For each additional file: -F 'loadFile=@"/[filePath]/[fileName.csv]"', where loadFile is unique.

Response

Status Code

  • Ok

  • Bad Request

  • Unauthorized

  • Not Found

  • Method Not Allowed

Example responses
  • {
      "errorMessageCode": "NONE",
      "message": "LOAD started successfully.",
      "result": {
        "END_TIME": "",
        "LOAD_ID": 1234567890,
        "LOAD_LOGFILE": "loadlogs/load_1234567890_DASH123456_ORDER_DETAILS_20160101-094119-CST.json",
        "LOAD_STATUS": "RUNNING",
        "ROWS_COMMITTED": "",
        "ROWS_DELETED": "",
        "ROWS_LOADED": "",
        "ROWS_READ": "",
        "ROWS_REJECTED": "",
        "ROWS_SKIPPED": "",
        "SCHEMA": "DASH123456",
        "START_TIME": "20160101 09:41:19 CST",
        "TABLE": "ORDER_DETAILS"
      },
      "resultCode": "SUCCESS"
    }

Get information on load jobs based on loadID

Get detailed information about an active or completed load job with the specified loadID. The command will fail if there is no load job with the specified loadID that is associated with the current user.

GET /load/{loadID}

Request

Path Parameters

  • ID of the load job.

Response

Status Code

  • Ok

  • Bad Request

  • Unauthorized

  • Not Found

  • Method Not Allowed

Example responses
  • {
      "errorMessageCode": "NONE",
      "message": "LOAD retrieved successfully",
      "result": {
        "errorMessageCode": "NONE",
        "message": "Load completed successfully.",
        "result": {
          "END_TIME": "20160101 09:41:27 CST",
          "LOAD_ID": 1234567890,
          "LOAD_LOGFILE": "loadlogs/load_1234567890_DASH123456_ORDER_DETAILS_20160101-094119-CST.json",
          "LOAD_STATUS": "COMPLETE",
          "ROWS_COMMITTED": 334518,
          "ROWS_DELETED": 0,
          "ROWS_LOADED": 334518,
          "ROWS_READ": 334518,
          "ROWS_REJECTED": 0,
          "ROWS_SKIPPED": 0,
          "SCHEMA": "DASH123456",
          "START_TIME": "20160101 09:41:19 CST",
          "TABLE": "ORDER_DETAILS"
        },
        "resultCode": "SUCCESS"
      },
      "resultCode": "SUCCESS"
    }

Get information on load jobs based on tableName

Get detailed information about active or completed load jobs initiated by the current user to load data into the specified table. The command will fail if there are no jobs associated with the current user that load data into the specified table.

GET /load/{tableName}

Request

Path Parameters

  • Name of the target table.

Response

Status Code

  • Ok

  • Bad Request

  • Unauthorized

  • Not Found

  • Method Not Allowed

Example responses
  • {
      "errorMessageCode": "NONE",
      "message": "LOAD retrieved successfully",
      "result": [
        {
          "errorMessageCode": "NONE",
          "message": "Load completed successfully.",
          "result": {
            "END_TIME": "20160101 09:41:27 CST",
            "LOAD_ID": 1234567890,
            "LOAD_LOGFILE": "loadlogs/load_1234567890_DASH123456_ORDER_DETAILS_20160101-094119-CST.json",
            "LOAD_STATUS": "COMPLETE",
            "ROWS_COMMITTED": 334518,
            "ROWS_DELETED": 0,
            "ROWS_LOADED": 334518,
            "ROWS_READ": 334518,
            "ROWS_REJECTED": 0,
            "ROWS_SKIPPED": 0,
            "SCHEMA": "DASH123456",
            "START_TIME": "20160101 09:41:19 CST",
            "TABLE": "ORDER_DETAILS"
          },
          "resultCode": "SUCCESS"
        },
        {
          "errorMessageCode": "NONE",
          "message": "Load completed successfully.",
          "result": {
            "END_TIME": "20160101 09:55:03 CST",
            "LOAD_ID": 2345678901,
            "LOAD_LOGFILE": "loadlogs/load_2345678901_DASH123456_ORDER_DETAILS_20160101-095500-CST.json",
            "LOAD_STATUS": "COMPLETE",
            "ROWS_COMMITTED": 111505,
            "ROWS_DELETED": 0,
            "ROWS_LOADED": 111505,
            "ROWS_READ": 111505,
            "ROWS_REJECTED": 0,
            "ROWS_SKIPPED": 0,
            "SCHEMA": "DASH123456",
            "START_TIME": "20160101 09:55:00 CST",
            "TABLE": "ORDER_DETAILS"
          },
          "resultCode": "SUCCESS"
        }
      ],
      "resultCode": "SUCCESS"
    }

Run a temporary R script file

Run a temporary R script file in the home directory. After the script is run the temporary file is deleted.

Use the GET /home endpoint to find output files, and the GET /home/{filename} endpoint to retrieve output files.

POST /rscript

Request

Percent-encoded R script.

Response

Status Code

  • Ok

  • Bad Request

  • Unauthorized

  • Not Found

  • Method Not Allowed

No Sample Response

This method does not specify any sample responses.

Run an existing R script file

Run an R script file that is located in the home directory, such as the sample Db2 Warehouse on Cloud R scripts and scripts generated by the integrated RStudio.

Use the GET /home endpoint to find output files, and the GET /home/{filename} endpoint to retrieve output files.

POST /rscript/{filename}

Request

Path Parameters

  • The relative path of the R script file.

Arguments that will be passed to the R script and readable using 'args <- commandArgs(TRUE)'.

Response

Status Code

  • Ok

  • Bad Request

  • Unauthorized

  • Not Found

  • Method Not Allowed

No Sample Response

This method does not specify any sample responses.