IBM Cloud API Docs

Introduction

Last updated: 2025-08-27

IBM® watsonx.data is a data management solution for collecting, storing, querying, and analyzing all your enterprise data (structured, semi-structured, and unstructured) with a single unified data platform. It provides a flexible and reliable platform that is optimized to work on open data formats.

Endpoint URLs

The base URLs come from the service instance. To find the URL, view the service credentials by clicking the name of the service in the Resource list. Use the value of the URL. Add the method to form the complete API endpoint for your request.

Authentication

Required Purpose: To work with the API, you must use an IBM Cloud Identity and Access Management (IAM) access token. The token is used to determine the actions that a user or service ID has access to when they use the API.

You can generate an IAM token for an authenticated user or service ID by using the IAM Identity Services API. IAM tokens are generated by using the user or service ID's API key. For more information, see Generating an IBM Cloud IAM token by using an API key.

To use the API, add a valid IAM token to the HTTP Authorization request header, for example, -H 'Authorization: Bearer {TOKEN}'.

To retrieve your access token:

curl -X POST   "https://iam.cloud.ibm.com/identity/token"   --header 'Content-Type: application/x-www-form-urlencoded'   --header 'Accept: application/json'   --data-urlencode 'grant_type=urn:ibm:params:oauth:grant-type:apikey'   --data-urlencode 'apikey={API_KEY}'

Replace {API_KEY} with your IAM API key.

Auditing

Required if applicable Purpose: Describes that the API generates auditing events that can be consumed by the Activity Tracker service, and links to your related product docs for more information. Required only if any of the API's methods is enabled to generate auditing events.

Example:

You can monitor API activity within your account by using the IBM Cloud Activity Tracker service. Whenever an API method is called, an event is generated that you can then track and audit from within Activity Tracker. The specific event type is listed for each individual method.

For more information about how to track Certificate Manager activity, see Auditing events for Certificate Manager.

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 indicates a failure, and a 500 type response indicates an internal system error.

HTTP Error Code Description Recovery
200 Success The request was successful.
201 Created The requested resource successfully created in a synchronous manner.
204 No Content The server successfully processed the request and is not returning any content.
400 Bad Request The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request.
401 Unauthorized You are not authorized to make this request. Log in to IBM Cloud and try again. If this error persists, contact the account owner to check your permissions.
403 Forbidden The supplied authentication is not authorized to access '{namespace}'.
404 Not Found The requested resource could not be found.
409 Conflict The entity is already in the requested state.
500 Internal Server Error Your request could not be processed. Wait a few minutes and try again.

Pagination

Some API requests might return many results. To avoid performance issues, these results are returned one page at a time, with a limited number of results on each page. GET requests for the following resources use pagination:

  • /v1/statement

For the request that uses pagination, the response does include following urls to make subsequent requests :

  • infoUri: The URL for requesting the first page of results.
  • nextUri: The URL for requesting the next page of results.

Methods

Get list of milvus services

Get list milvus services

GET /milvus_services

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • lakehouse.milvus_service.read

Request

Custom Headers

  • AuthInstanceId
    string

    watsonx.data instance ID

    Possible values: 1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-\:/]+$

  • curl -X GET -H "content-type: application/json" -H "AuthInstanceId: {instance id}" https://{region}.lakehouse.cloud.ibm.com/lakehouse/api/v3/milvus_services"

Response

Response Body

MilvusServiceCollection

List milvus services

Status Code

  • 200

    Success

  • 400

    Error

  • 401

    Unauthorized

  • 403

    Forbidden

  • 404

    Not found

  • 500

    Internal server error

Example responses
  • {
  "milvus_services": [
    {
      "actions": [
        "update",
        "delete"
      ],
      "created_by": "username@domain.com",
      "created_at": 1700201877,
      "display_name": "test-milvus",
      "grpc_port": 31501,
      "host_name": "<formation_id>.<kubernetes_cluster>.databases.appdomain.cloud",
      "https_port": 31012,
      "id": "milvus76",
      "index_type": "flat",
      "proxy_port": 31019,
      "status": "running",
      "status_code": 11,
      "storage": {
        "storage_type": "ibm_cos",
        "root_path": "",
        "storage_name": "milvusstorage"
      },
      "tags": [
        "tag1"
      ],
      "tshirt_size": "small",
      "type": "milvus"
    }
  ]
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}

Create milvus service

Create milvus service

POST /milvus_services

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • lakehouse.milvus_service.create

Request

Custom Headers

  • AuthInstanceId
    string

    watsonx.data instance ID

    Possible values: 1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-\:/]+$

Request Body

Required*
MilvusServicePrototype

Create milvus service

  • curl -X POST -H "content-type: application/json" -H "accept: application/json" -d '{ 
  "display_name": "milvus-01", 
  "origin": "native", 
  "tshirt_size": "starter", 
  "storage_name": "cos-cypress-bucket", 
  "root_path": "/cos-cypress-bucket" 
}' "https://{cpd-host}.cp.fyre.ibm.com/lakehouse/api/v3/milvus_services"

Response

Response Body

MilvusService

milvus service details

Status Code

  • 202

    Success

  • 400

    Error

  • 401

    Unauthorized

  • 403

    Forbidden

  • 404

    Not found

  • 500

    Internal server error

Example responses
  • {
  "actions": [
    "update",
    "delete"
  ],
  "created_by": "username@domain.com",
  "created_at": 1700201877,
  "display_name": "test-milvus",
  "grpc_port": 31501,
  "host_name": "<formation_id>.<kubernetes_cluster>.databases.appdomain.cloud",
  "https_port": 31012,
  "id": "milvus76",
  "index_type": "flat",
  "milvus_service": null,
  "proxy_port": 31019,
  "status": "running",
  "status_code": 11,
  "storage": {
    "storage_type": "ibm_cos",
    "root_path": "",
    "storage_name": "milvusstorage"
  },
  "tags": [
    "tag1"
  ],
  "tshirt_size": "small",
  "type": "milvus",
  "vector": 20000,
  "vector_dimension": 384
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}

Get milvus service

Get milvus service

GET /milvus_services/{id}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • lakehouse.milvus_service.get

Request

Custom Headers

  • AuthInstanceId
    string

    watsonx.data instance ID

    Possible values: 1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-\:/]+$

Path Parameters

  • id
    Required*
    string

    id

    Possible values: 1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-]+$

  • curl -X 'GET' 'https://{region}.lakehouse.cloud.ibm.com/lakehouse/api/v3/milvus_services/{id}' -H 'accept: application/json' -H "AuthInstanceId: {instance id}"

Response

Response Body

MilvusService

milvus service details

Status Code

  • 200

    Success

  • 400

    Error

  • 401

    Unauthorized

  • 403

    Forbidden

  • 404

    Not found

  • 500

    Internal server error

Example responses
  • {
  "actions": [
    "update",
    "delete"
  ],
  "created_by": "username@domain.com",
  "created_at": 1700201877,
  "display_name": "test-milvus",
  "grpc_port": 31501,
  "host_name": "<formation_id>.<kubernetes_cluster>.databases.appdomain.cloud",
  "https_port": 31012,
  "id": "milvus76",
  "index_type": "flat",
  "milvus_service": null,
  "proxy_port": 31019,
  "status": "running",
  "status_code": 11,
  "storage": {
    "storage_type": "ibm_cos",
    "root_path": "",
    "storage_name": "milvusstorage"
  },
  "tags": [
    "tag1"
  ],
  "tshirt_size": "small",
  "type": "milvus",
  "vector": 20000,
  "vector_dimension": 384
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}

Delete milvus service

Delete milvus service

DELETE /milvus_services/{id}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • lakehouse.milvus_service.delete

Request

Custom Headers

  • AuthInstanceId
    string

    watsonx.data instance ID

    Possible values: 1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-\:/]+$

Path Parameters

  • id
    Required*
    string

    id

    Possible values: 1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-]+$

  • curl -X 'DELETE' 'https://{region}.lakehouse.cloud.ibm.com/lakehouse/api/v3/milvus_services/{id}' -H 'accept: application/json' -H "AuthInstanceId: {instance id}"

Response

Status Code

  • 204

    No Content

  • 400

    Error

  • 401

    Unauthorized

  • 403

    Forbidden

  • 404

    Not found

  • 500

    Internal server error

Example responses
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}

Update milvus service

Update details of milvus service

PATCH /milvus_services/{id}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • lakehouse.milvus_service.update

Request

Custom Headers

  • AuthInstanceId
    string

    watsonx.data instance ID

    Possible values: 1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-\:/]+$

Path Parameters

  • id
    Required*
    string

    id

    Possible values: 1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-]+$

Request Body

Required*
application/merge-patch+jsonMilvusServicePatch

Update milvus service

  • curl -X 'PATCH' 'https://{region}.lakehouse.cloud.ibm.com/lakehouse/api/v3/milvus_services/{id}' -H 'accept: application/json' -H 'Content-Type: application/merge-patch+json' -H "AuthInstanceId: {instance id}" -d '{  "description": "updated description for milvus service",  "display_name": "sampleService",  "tags": [    "tag1",    "tag2"  ]}'

Response

Response Body

MilvusService

milvus service details

Status Code

  • 200

    Success

  • 400

    Error

  • 401

    Unauthorized

  • 403

    Forbidden

  • 404

    Not found

  • 500

    Internal server error

Example responses
  • {
  "actions": [
    "update",
    "delete"
  ],
  "created_by": "username@domain.com",
  "created_at": 1700201877,
  "display_name": "test-milvus",
  "grpc_port": 31501,
  "host_name": "<formation_id>.<kubernetes_cluster>.databases.appdomain.cloud",
  "https_port": 31012,
  "id": "milvus76",
  "index_type": "flat",
  "milvus_service": null,
  "proxy_port": 31019,
  "status": "running",
  "status_code": 11,
  "storage": {
    "storage_type": "ibm_cos",
    "root_path": "",
    "storage_name": "milvusstorage"
  },
  "tags": [
    "tag1"
  ],
  "tshirt_size": "small",
  "type": "milvus",
  "vector": 20000,
  "vector_dimension": 384
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}

Pause milvus service

Pause a running milvus service

POST /milvus_services/{id}/pause

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • lakehouse.milvus_service.pause

Request

Custom Headers

  • AuthInstanceId
    string

    watsonx.data instance ID

    Possible values: 1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-\:/]+$

Path Parameters

  • id
    Required*
    string

    id

    Possible values: 1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-]+$

  • curl -X 'POST' 'https://{region}.lakehouse.cloud.ibm.com/lakehouse/api/v3/milvus_services/{id}/pause' -H 'accept: application/json' -H "AuthInstanceId: {instance id}" -d ''

Response

Response Body

SuccessResponse

Response of success

Status Code

  • 201

    Success

  • 400

    Error

  • 401

    Unauthorized

  • 403

    Forbidden

  • 404

    Not found

  • 500

    Internal server error

Example responses
  • {
  "message": "Successful message",
  "message_code": "success"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}

Resume milvus service

Resume a paused milvus service

POST /milvus_services/{id}/resume

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • lakehouse.milvus_service.resume

Request

Custom Headers

  • AuthInstanceId
    string

    watsonx.data instance ID

    Possible values: 1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-\:/]+$

Path Parameters

  • id
    Required*
    string

    id

    Possible values: 1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-]+$

  • curl -X 'POST' 'https://{region}.lakehouse.cloud.ibm.com/lakehouse/api/v3/milvus_services/{id}/resume' -H 'accept: application/json' -H "AuthInstanceId: {instance id}" -d ''

Response

Response Body

SuccessResponse

Response of success

Status Code

  • 201

    Success

  • 400

    Error

  • 401

    Unauthorized

  • 403

    Forbidden

  • 404

    Not found

  • 500

    Internal server error

Example responses
  • {
  "message": "Successful message",
  "message_code": "success"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}

Scale a milvus service

Scale an existing milvus service

POST /milvus_services/{id}/scale

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • lakehouse.milvus_service.scale

Request

Custom Headers

  • AuthInstanceId
    string

    watsonx.data instance ID

    Possible values: 1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-\:/]+$

Path Parameters

  • id
    Required*
    string

    id

    Possible values: 1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-]+$

Request Body

Required*
MilvusServiceScale

Scale Service Body

Examples: 
{
  "dc_cpu": 45,
  "dc_memory": 26,
  "dc_replicas": 5,
  "dw_cpu": 45,
  "dw_memory": 26,
  "dw_replicas": 5,
  "etcd_cpu": 45,
  "etcd_memory": 26,
  "index_type": "flat",
  "iw_cpu": 54,
  "iw_memory": 100,
  "iw_replicas": 2,
  "kafka_cpu": 45,
  "kafka_memory": 26,
  "proxy_cpu": 45,
  "proxy_memory": 26,
  "proxy_replicas": 5,
  "qc_cpu": 54,
  "qc_memory": 100,
  "qc_replicas": 2,
  "qw_cpu": 45,
  "qw_memory": 26,
  "qw_replicas": 5,
  "rc_cpu": 54,
  "rc_memory": 100,
  "rc_replicas": 2,
  "tshirt_size": "custom",
  "vector": 20000,
  "vector_dimension": 384
}
  • curl -X 'POST' 'https://{region}.lakehouse.cloud.ibm.com/lakehouse/api/v3/milvus_services/{id}/scale' -H 'accept: application/json' -H 'Content-Type: application/json' -H "AuthInstanceId: {instance id}" -d ''

Response

Response Body

SuccessResponse

Response of success

Status Code

  • 201

    Success

  • 400

    Error

  • 401

    Unauthorized

  • 403

    Forbidden

  • 404

    Not found

  • 500

    Internal server error

Example responses
  • {
  "message": "Successful message",
  "message_code": "success"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}

Get milvus service databases

Get milvus service databases

GET /milvus_services/{service_id}/databases

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • lakehouse.milvus_service_databases.get

Request

Custom Headers

  • AuthInstanceId
    string

    watsonx.data instance ID

    Possible values: 1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-\:/]+$

Path Parameters

  • service_id
    Required*
    string

    service id

    Possible values: 1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-]+$

Response
Response Body
MilvusServiceDatabases
List milvus service databases


Status Code
  • 200
    Success
    

  • 400
    Error
    

  • 401
    Unauthorized
    

  • 404
    Not found
    

  • 500
    Internal server error
    

Example responses
  • {
  "databases": [
    {
      "id": "default"
    },
    {
      "id": "db-02"
    }
  ]
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
Get milvus database collections
Get milvus database collections


GET /milvus_services/{service_id}/databases/{database_id}/collections
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.
  • lakehouse.milvus_database_collections.get
Request
Custom Headers
  • AuthInstanceId
    string
    watsonx.data instance ID
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-\:/]+$
Path Parameters
  • service_id
    Required*
    string
    service id
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-]+$
  • database_id
    Required*
    string
    database_id
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-]+$
Response
Response Body
MilvusDatabaseCollections
List Milvus database collections


Status Code
  • 200
    Success
    

  • 400
    Error
    

  • 401
    Unauthorized
    

  • 404
    Not found
    

  • 500
    Internal server error
    

Example responses
  • {
  "collections": [
    {
      "id": 12345,
      "name": "collection-1",
      "physical_channels": [
        "physical_channel_1"
      ],
      "virtual_channels": [
        "virtual_channel_1"
      ]
    },
    {
      "id": 67890,
      "name": "collection-2",
      "physical_channels": [
        "physical_channel_2a",
        "physical_channel_2b"
      ],
      "virtual_channels": [
        "virtual_channel_2a",
        "virtual_channel_2b"
      ]
    }
  ]
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
Get milvus database collection partitions
Get milvus database collection partitions


GET /milvus_services/{service_id}/databases/{database_id}/collections/{collection_id}/partitions
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.
  • lakehouse.milvus_database_collections.get
Request
Custom Headers
  • AuthInstanceId
    string
    watsonx.data instance ID
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-\:/]+$
Path Parameters
  • service_id
    Required*
    string
    service id
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-]+$
  • database_id
    Required*
    string
    database id
    

    Possible values:  1 ≤ length ≤ 1000, Value must match regular expression ^[a-zA-Z0-9\-]+$
  • collection_id
    Required*
    string
    collection id
    

    Possible values:  1 ≤ length ≤ 1000, Value must match regular expression ^[a-zA-Z0-9\-]+$
Response
Response Body
MilvusDatabasePartitions
List milvus database collection partitions


Status Code
  • 200
    Success
    

  • 400
    Error
    

  • 401
    Unauthorized
    

  • 404
    Not found
    

  • 500
    Internal server error
    

Example responses
  • {
  "partitions": [
    {
      "id": 1000,
      "name": "partition1"
    }
  ]
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
Update milvus service storage
Update details of milvus service bucket


PATCH /milvus_services/{id}/storage
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.
  • lakehouse.milvus_service.update.bucket
Request
Custom Headers
  • AuthInstanceId
    string
    watsonx.data instance ID
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-\:/]+$
Path Parameters
  • id
    Required*
    string
    service id
    

    Possible values:  1 ≤ length ≤ 1000, Value must match regular expression ^[a-zA-Z0-9\-]+$
Request Body
Required*
application/merge-patch+jsonMilvusServiceStoragePatch
Update milvus service bucket


  • curl -X 'PATCH' 'https://{region}.lakehouse.cloud.ibm.com/lakehouse/api/v3/milvus_services/{service_id}/storage' -H 'accept: application/json' -H 'Content-Type: application/merge-patch+json' -H "AuthInstanceId: {instance id}" -d '{  "description": "updated description for milvus service",  "display_name": "sampleService",  "tags": [    "tag1",    "tag2"  ]}'
Response
Response Body
MilvusService
milvus service details


Status Code
  • 200
    Success
    

  • 400
    Error
    

  • 401
    Unauthorized
    

  • 403
    Forbidden
    

  • 404
    Not found
    

  • 500
    Internal server error
    

Example responses
  • {
  "actions": [
    "update",
    "delete"
  ],
  "created_by": "username@domain.com",
  "created_at": 1700201877,
  "display_name": "test-milvus",
  "grpc_port": 31501,
  "host_name": "<formation_id>.<kubernetes_cluster>.databases.appdomain.cloud",
  "https_port": 31012,
  "id": "milvus76",
  "index_type": "flat",
  "milvus_service": null,
  "proxy_port": 31019,
  "status": "running",
  "status_code": 11,
  "storage": {
    "storage_type": "ibm_cos",
    "root_path": "",
    "storage_name": "milvusstorage"
  },
  "tags": [
    "tag1"
  ],
  "tshirt_size": "small",
  "type": "milvus",
  "vector": 20000,
  "vector_dimension": 384
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
Add/Create HDFS storage
Add or create a new HDFS database


POST /storage_hdfs_registrations
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.
  • lakehouse.storage_hdfs_registration.create
Request
Custom Headers
  • AuthInstanceId
    string
    watsonx.data instance ID
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-\:/]+$
Form Parameters
  • display_name
    Required*
    string
    Storage display name
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[^!@#$%^&*()=+:{}?<>';\`]*$
  • storage_type
    Required*
    string
    Storage type
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-_]+$
  • hms_thrift_uri
    Required*
    string
    HMS Thrift URI
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\/.@_:_-]+$
  • hms_thrift_port
    Required*
    integer
    HMS Thrift Port
    

    Possible values:  1 ≤ value ≤ 65535
  • core_site
    Required*
    string
    contents of core-site.xml file
    

    Possible values:  1 ≤ length ≤ 20000, Value must match regular expression ^[.*\s\S]*$
  • hdfs_site
    Required*
    string
    contents of hdfs-site.xml file
    

    Possible values:  1 ≤ length ≤ 20000, Value must match regular expression ^[.*\s\S]*$
  • kerberos
    Required*
    string
    Kerberos Flag
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^true$|^false$
  • catalog_name
    Required*
    string
    Catalog name
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-_]+$
  • catalog_type
    Required*
    string
    Catalog type
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\\-]+$
  • krb5_config
    string
    Kerberos configuration file
    

    Possible values:  1 ≤ length ≤ 20000, Value must match regular expression ^[.*\s\S]*$
  • hive_keytab
    binary
    Hive keytab file
    

    Possible values:  1 ≤ length ≤ 104857600
  • hdfs_keytab
    binary
    HDFS keytab file
    

    Possible values:  1 ≤ length ≤ 104857600
  • hive_server_principal
    string
    Hive server principal
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\/.@_:_-]+$
  • hive_client_principal
    string
    Hive client principal
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\/.@_:_-]+$
  • hdfs_principal
    string
    HDFS principal
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\/.@_:_-]+$
  • description
    string
    Database description
    

    Possible values:  1 ≤ length ≤ 1000, Value must match regular expression ^[a-zA-Z0-9~!@#$%^&*()_+=\[\]{}|;':\"`,./<>?\\=:\- ]*$
  • created_at
    string
    Created on
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\\-]+$
  • curl -X POST \-H "accept: application/json" \-H "AuthInstanceId: 00000000000" \-H "Content-Type: multipart/form-data" \-F "display_name=Sample_Hdfs" \-F "storage_type=hdfs" \-F "hms_thrift_uri=thrif://hms.example.com" \-F "hms_thrift_port=9083" \-F "core_site=<contents of core-site.xml file>" \-F "hdfs_site=<contents of hdfs-site.xml file>" \-F "kerberos=true" \-F "krb5_config=<contents of krb5.conf file>" \-F "hive_keytab=hive.keytab file" \-F "hdfs_keytab=hdfs.keytab file" \-F "hive_server_principal=hive/_HOST@EXAMPLE.COM" \-F "hive_client_principal=hive/_HOST@EXAMPLE.COM" \-F "hdfs_principal=hdfs/_HOST@EXAMPLE.COM" \-F "catalog_name=sample_catalog" \-F "catalog_type=hive-hadoop2" \-F "description=Sample  description" \-F "created_at=1686120645" \"https://us.lakehouse.cloud.ibm.com/lakehouse/api/v3/storage_hdfs_registrations"
Response
Response Body
HdfsStorageRegistration
HDFS storage registration


Status Code
  • 201
    Success
    

  • 400
    Error
    

  • 401
    Unauthorized
    

  • 404
    Not found
    

  • 500
    Internal server error
    

Example responses
  • {
  "actions": [
    "create",
    "update"
  ],
  "associated_catalog": {
    "catalog_name": "hive_data",
    "catalog_tags": [
      "tag1",
      "tag2"
    ],
    "catalog_type": "hive"
  },
  "created_at": "1699457595",
  "created_by": "username@domain.com",
  "description": "default hdfs",
  "display_name": "samplehdfsdisplayname",
  "id": "hdfs123",
  "managed_by": "customer",
  "state": "active",
  "tags": [
    "tag1",
    "tag2"
  ],
  "type": "hdfs"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
Get storage registrations
Get list of registered storages


GET /storage_registrations
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.
  • lakehouse.storage_registration.list
Request
Custom Headers
  • AuthInstanceId
    string
    watsonx.data instance ID
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-\:/]+$
  • curl -X GET -H "accept: application/json" -H "AuthInstanceId: {instance_id}" "https://{region}.lakehouse.cloud.ibm.com/lakehouse/api/v3/storage_registrations"
Response
Response Body
StorageRegistrationCollection
List storage registrations


Status Code
  • 200
    Success
    

  • 400
    Error
    

  • 401
    Unauthorized
    

  • 404
    Not found
    

  • 500
    Internal server error
    

Example responses
  • {
  "storage_registrations": [
    {
      "actions": [
        "browse",
        "view",
        "modify",
        "create",
        "grant",
        "revoke",
        "update",
        "remove",
        "activate",
        "register"
      ],
      "associated_catalogs": [
        {
          "catalog_name": "iceberg_catalog",
          "catalog_tags": []
        }
      ],
      "configuration": {
        "auth_mode": "account_key",
        "container_name": "conatiner_name",
        "endpoint": "https://s3.us-south.cloud-object-storage.appdomain.cloud/",
        "storage_account_name": "storage_account_name",
        "storage_name": "iceberg-storage"
      },
      "created_at": "1699457595",
      "created_by": "user",
      "description": "default storage",
      "display_name": "hive-storage",
      "id": "iceberg-storage",
      "managed_by": "ibm",
      "region": "us-south",
      "state": "active",
      "tags": [
        "tag1",
        "tag2"
      ],
      "type": "minio"
    },
    {
      "actions": [
        "browse",
        "view",
        "modify",
        "create",
        "grant",
        "revoke",
        "update",
        "remove",
        "activate",
        "register"
      ],
      "associated_catalogs": [
        {
          "catalog_name": "hive_data",
          "catalog_tags": []
        }
      ],
      "configuration": {
        "endpoint": "http://xyz-minio-svc:9000",
        "storage_name": "hive-storage"
      },
      "created_at": "1699457595",
      "created_by": "user",
      "description": "default storage",
      "display_name": "hive-storage",
      "id": "hive-storage",
      "managed_by": "ibm",
      "region": "us-south",
      "state": "active",
      "tags": [
        "tag1",
        "tag2"
      ],
      "type": "minio"
    }
  ]
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
Register storage
Register a new storage


POST /storage_registrations
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.
  • lakehouse.storage_registration.create
Request
Custom Headers
  • AuthInstanceId
    string
    watsonx.data instance ID
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-\:/]+$
Request Body
Required*
StorageRegistrationPrototype
Request body


  • curl -X POST 'https://{region}.lakehouse.cloud.ibm.com/lakehouse/api/v3/storage_registrations' -H 'accept: application/json' -H 'AuthInstanceId: {instance_id}' -H 'Content-Type: application/json' -d '{
    "display_name": "cos-cypress-bucket",
    "type": "ibm_cos",
    "description": "",
    "managed_by": "customer",
    "region": "us-south",
    "connection": {
        "name": "cos-cypress-bucket",
        "endpoint": "https://s3.us-west.cloud-object-storage.test.appdomain.cloud",
        "access_key": "ssdef",
        "secret_key": "29c92"
    },
    "associated_catalog": {
        "catalog_name": "testcat",
        "catalog_type": "iceberg"
    }
}'
Response
Response Body
StorageRegistration
Storage


Status Code
  • 201
    Success
    

  • 400
    Error
    

  • 401
    Unauthorized
    

  • 404
    Not found
    

  • 500
    Internal server error
    

Example responses
  • {
  "actions": [
    "create",
    "update"
  ],
  "associated_catalogs": [
    {
      "catalog_name": "hive_data",
      "catalog_tags": [
        "tag1",
        "tag2"
      ],
      "catalog_type": "hive"
    }
  ],
  "created_at": "1699457595",
  "created_by": "username@domain.com",
  "description": "default storage",
  "display_name": "samplestoragedisplayname",
  "endpoint": "https://s3.<region>.cloud-object-storage.appdomain.cloud/",
  "id": "samplestorageid",
  "managed_by": "ibm",
  "region": "us-south",
  "state": "active",
  "storage_name": "samplestorage",
  "tags": [
    "tag1",
    "tag2"
  ],
  "type": "minio"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
Get storage
Get a registered storage


GET /storage_registrations/{id}
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.
  • lakehouse.storage_registration.get
Request
Custom Headers
  • AuthInstanceId
    string
    watsonx.data instance ID
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-\:/]+$
Path Parameters
  • id
    Required*
    string
    storage id
    

    Possible values:  1 ≤ length ≤ 1000, Value must match regular expression ^[a-zA-Z0-9\\._\/-]+$
Query Parameters
  • skip_mds_call
    boolean
    Skip MDS call when Unity catalog is added
    

    Default: false
  • curl -X GET -H "accept: application/json" -H "AuthInstanceId: {instance_id}" "https://{region}.lakehouse.cloud.ibm.com/lakehouse/api/v3/storage_registrations/{id}"
Response
Response Body
StorageRegistration
Storage


Status Code
  • 200
    Success
    

  • 400
    Error
    

  • 401
    Unauthorized
    

  • 404
    Not found
    

  • 500
    Internal server error
    

Example responses
  • {
  "actions": [
    "create",
    "update"
  ],
  "associated_catalogs": [
    {
      "catalog_name": "hive_data",
      "catalog_tags": [
        "tag1",
        "tag2"
      ],
      "catalog_type": "hive"
    }
  ],
  "created_at": "1699457595",
  "created_by": "username@domain.com",
  "description": "default storage",
  "display_name": "samplestoragedisplayname",
  "endpoint": "https://s3.<region>.cloud-object-storage.appdomain.cloud/",
  "id": "samplestorageid",
  "managed_by": "ibm",
  "region": "us-south",
  "state": "active",
  "storage_name": "samplestorage",
  "tags": [
    "tag1",
    "tag2"
  ],
  "type": "minio"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
Unregister Storage
Unregister a storage


DELETE /storage_registrations/{id}
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.
  • lakehouse.storage_registration.delete
Request
Custom Headers
  • AuthInstanceId
    string
    watsonx.data instance ID
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-\:/]+$
Path Parameters
  • id
    Required*
    string
    storage id
    

    Possible values:  1 ≤ length ≤ 1000, Value must match regular expression ^[a-zA-Z0-9\\._\/-]+$
Query Parameters
  • skip_mds_call
    boolean
    Skip MDS call when Unity catalog is added
    

    Default: false
  • curl -X DELETE -H "accept:  */*" -H "AuthInstanceId: {instance_id}" "https://{region}.lakehouse.cloud.ibm.com/lakehouse/api/v3/storage_registrations/{id}"
Response
Status Code
  • 204
    No Content
    

  • 400
    Error
    

  • 401
    Unauthorized
    

  • 404
    Not found
    

  • 500
    Internal server error
    

Example responses
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
Update storage
Update storage details & credentials


PATCH /storage_registrations/{id}
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.
  • lakehouse.storage_registration.update
Request
Custom Headers
  • AuthInstanceId
    string
    watsonx.data instance ID
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-\:/]+$
Path Parameters
  • id
    Required*
    string
    storage id
    

    Possible values:  1 ≤ length ≤ 1000, Value must match regular expression ^[a-zA-Z0-9\\._\/-]+$
Query Parameters
  • skip_mds_call
    boolean
    Skip MDS call when Unity catalog is added
    

    Default: false
Request Body
Required*
application/merge-patch+jsonStorageRegistrationPatch
Request body


Examples:  
{
  "configuration": {
    "access_key": "<access_key>",
    "endpoint": "https://s3.us-south.cloud-object-storage.appdomain.cloud/",
    "secret_key": "secret_key",
    "storage_name": "sample-storage"
  },
  "description": "COS storage for customer data",
  "display_name": "samplestoragedisplayname",
  "system_storage_update_credentials": false,
  "tags": [
    "teststorage",
    "userstorage"
  ]
}
  • curl -X PATCH -H "accept: application/json" -H "AuthInstanceId: {instance_id}" -H "Content-Type: application/json" -d '{ "access_key": "<access_key>", "display_name": "sample-storage-displayname", "description": "COS storage for customer data", "secret_key": "<secret_key>", "tags": [ "teststorage", "userstorage" ] }' "https://{region}.lakehouse.cloud.ibm.com/lakehouse/api/v3/storage_registrations/{id}"
Response
Response Body
StorageRegistration
Storage


Status Code
  • 200
    Success
    

  • 400
    Error
    

  • 401
    Unauthorized
    

  • 404
    Not found
    

  • 500
    Internal server error
    

Example responses
  • {
  "actions": [
    "create",
    "update"
  ],
  "associated_catalogs": [
    {
      "catalog_name": "hive_data",
      "catalog_tags": [
        "tag1",
        "tag2"
      ],
      "catalog_type": "hive"
    }
  ],
  "created_at": "1699457595",
  "created_by": "username@domain.com",
  "description": "default storage",
  "display_name": "samplestoragedisplayname",
  "endpoint": "https://s3.<region>.cloud-object-storage.appdomain.cloud/",
  "id": "samplestorageid",
  "managed_by": "ibm",
  "region": "us-south",
  "state": "active",
  "storage_name": "samplestorage",
  "tags": [
    "tag1",
    "tag2"
  ],
  "type": "minio"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
Activate Storage
Activate a registered storage


POST /storage_registrations/{id}/activate
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.
  • lakehouse.storage_registration_activate.add
Request
Custom Headers
  • AuthInstanceId
    string
    watsonx.data instance ID
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-\:/]+$
Path Parameters
  • id
    Required*
    string
    storage id
    

    Possible values:  1 ≤ length ≤ 1000, Value must match regular expression ^[a-zA-Z0-9\\._\/-]+$
  • curl -X POST -H "accept: application/json" -H "AuthInstanceId: {instance_id}" -d "" "https://{region}.lakehouse.cloud.ibm.com/lakehouse/api/v3/storage_registrations/{storage_id}/activate"
Response
Response Body
ActivateStorageResponse
Activate storage


Status Code
  • 201
    Success
    

  • 400
    Error
    

  • 401
    Unauthorized
    

  • 404
    Not found
    

  • 500
    Internal server error
    

Example responses
  • {
  "response": {
    "message": "Activate storage",
    "message_code": "success"
  }
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
Add storage catalog
Add storage catalog


POST /storage_registrations/{storage_id}/catalogs
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.
  • lakehouse.catalog.create
Request
Custom Headers
  • AuthInstanceId
    string
    watsonx.data instance ID
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-\:/]+$
Path Parameters
  • storage_id
    Required*
    string
    storage id
    

    Possible values:  1 ≤ length ≤ 1000, Value must match regular expression ^[a-zA-Z0-9\\._\/-]+$
Query Parameters
  • skip_mds_call
    boolean
    Skip MDS call when Unity catalog is added
    

    Default: false
Request Body
Required*
StorageCatalogPrototype
Request body


Examples:  
{
  "base_path": "/iceberg_catalog/path1",
  "catalog_name": "iceberg_catalog",
  "catalog_tags": [
    "catalog_tag_1",
    "catalog_tag_2"
  ],
  "catalog_type": "iceberg"
}
  • curl -X POST -H "accept: application/json" -H "AuthInstanceId: {instance_id}" -H "Content-Type: application/json" -d '{ "associated_catalog": { "catalog_name": "<access_key>", "catalog_type": "sample-storage" } }' "https://{region}.lakehouse.cloud.ibm.com/lakehouse/api/v3/storage_registrations"
Response
Response Body
SuccessResponse
Response of success


Status Code
  • 201
    Success
    

  • 400
    Error
    

  • 401
    Unauthorized
    

  • 404
    Not found
    

  • 500
    Internal server error
    

Example responses
  • {
  "message": "Successful message",
  "message_code": "success"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
Get storage object properties
Get storage object properties


POST /storage_registrations/{storage_id}/object_properties
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.
  • lakehouse.storage.object.properties
Request
Custom Headers
  • AuthInstanceId
    string
    watsonx.data instance ID
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-\:/]+$
Path Parameters
  • storage_id
    Required*
    string
    storage id
    

    Possible values:  1 ≤ length ≤ 1000, Value must match regular expression ^[a-zA-Z0-9\\._\/-]+$
Request Body
Required*
StorageObjectSize
Request body


  • curl -X POST -H "accept: application/json" -H "AuthInstanceId: {instance_id}" -H "Content-Type: application/json" -d '{ "associated_catalog": { "catalog_name": "<access_key>", "catalog_type": "sample-storage" } }' "https://{region}.lakehouse.cloud.ibm.com/lakehouse/api/v3/storage_registrations"
Response
Response Body
StorageObjectProperties
muliple storage object properties


Status Code
  • 201
    Success
    

  • 400
    Error
    

  • 401
    Unauthorized
    

  • 404
    Not found
    

  • 500
    Internal server error
    

Example responses
  • {
  "object_properties": [
    {
      "content_type": "application/json",
      "file_type": "json",
      "last_modified": "utc-2014-07",
      "metadata": {
        "key1": "value1",
        "key2": "value2"
      },
      "path": "iceberg/test/data",
      "size": "1024"
    },
    {
      "content_type": "text/plain",
      "file_type": "txt",
      "last_modified": "utc-2023-01",
      "metadata": {
        "keyA": "valueA",
        "keyB": "valueB"
      },
      "path": "xyz/xyz/file",
      "size": "2048"
    }
  ]
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
List storage objects
Fetch all objects from a given storage


GET /storage_registrations/{storage_id}/objects
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.
  • lakehouse.storage_registration_object.list
Request
Custom Headers
  • AuthInstanceId
    string
    watsonx.data instance ID
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-\:/]+$
Path Parameters
  • storage_id
    Required*
    string
    storage id
    

    Possible values:  1 ≤ length ≤ 1000, Value must match regular expression ^[a-zA-Z0-9\\._\/-]+$
Query Parameters
  • path
    string
    path
    

    Possible values:  1 ≤ length ≤ 1000, Value must match regular expression ^[a-zA-Z0-9~!@#$%^&*()_+=\[\]{}|;':\"`,./<>?\\=:\- ]*$
  • curl -X GET -H "accept: application/json" -H "AuthInstanceId: {instance_id}" "https://{region}.lakehouse.cloud.ibm.com/lakehouse/api/v3/storage_registrations/{storage_id}/objects"
Response
Response Body
StorageRegistrationObjectCollection
List storage objects


Status Code
  • 200
    Success
    

  • 400
    Error
    

  • 401
    Unauthorized
    

  • 403
    Forbidden
    

  • 404
    Not found
    

  • 500
    Internal server error
    

  • default
    Success
    

Example responses
  • {
  "objects": [
    "/path/file1.json",
    "/path/file2.txt",
    "/path/file3.csv",
    "/path/file4.parquet"
  ]
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
Get list of Presto(Java) engines
Get list of all Presto(Java) engines


GET /presto_engines
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.
  • lakehouse.presto_engine.list
Request
Custom Headers
  • AuthInstanceId
    string
    watsonx.data instance ID
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-\:/]+$
  • curl -X GET -H "content-type: application/json" -H "AuthInstanceId: {instance id}" "https://{region}.lakehouse.cloud.ibm.com/lakehouse/api/v3/presto_engines"
Response
Response Body
PrestoEngineCollection
Collection of Presto engines.


Status Code
  • 200
    Success
    

  • 400
    Error
    

  • 401
    Unauthorized
    

  • 404
    Not found
    

  • 500
    Internal server error
    

Example responses
  • {
  "presto_engines": [
    {
      "actions": [
        "view",
        "use",
        "update",
        "select",
        "access_ui",
        "associate",
        "disassociate",
        "restart",
        "pause",
        "resume",
        "grant",
        "revoke",
        "delete",
        "create",
        "scale"
      ],
      "associated_catalogs": [
        "iceberg_data",
        "hive_data"
      ],
      "build_version": "1.1.0.0.0",
      "coordinator": {
        "node_type": "bx2.4x16",
        "quantity": 1
      },
      "display_name": "starter",
      "drivers": [],
      "external_host_name": "your-hostname.apps.your-domain.com",
      "group_id": "presto511",
      "host_name": "1234-xyz456-abc4321.databases.appdomain.cloud",
      "id": "presto511",
      "origin": "native",
      "port": 30156,
      "resource_groups": [],
      "size_config": "starter",
      "status": "running",
      "status_code": 200,
      "tags": [
        "tag1",
        "tag2"
      ],
      "type": "presto",
      "version": "v0.282",
      "worker": {
        "node_type": "bx2.4x16",
        "quantity": 1
      }
    }
  ]
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
Create presto engine
Create a new presto engine


POST /presto_engines
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.
  • lakehouse.presto_engine.create
Request
Custom Headers
  • AuthInstanceId
    string
    watsonx.data instance ID
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-\:/]+$
Request Body
Required*
PrestoEnginePrototype
Create Engine Body


  • curl -X POST "https://{region}.lakehouse.cloud.ibm.com/lakehouse/api/v3/presto_engines" -H "accept: application/json" -H "content-type: application/json" -d '{ 
  "description": "", 
  "configuration": { 
    "coordinator": { 
      "node_type": "bx2.4x16", 
      "quantity": 1 
    }, 
    "size_config": "custom", 
    "worker": { 
      "node_type": "bx2.4x16", 
      "quantity": 1 
    } 
  }, 
  "display_name": "presto-01", 
  "origin": "native", 
  "associated_catalogs": [], 
  "version": "v0.286", 
  "tags": [], 
  "region": "us-south" 
}'
Response
Response Body
PrestoEngine
Presto engine details.


Status Code
  • 201
    Success
    

  • 400
    Error
    

  • 401
    Unauthorized
    

  • 404
    Not found
    

  • 500
    Internal server error
    

Example responses
  • {
  "actions": [
    "view",
    "use",
    "update",
    "select",
    "access_ui",
    "associate",
    "disassociate",
    "restart",
    "pause",
    "resume",
    "grant",
    "revoke",
    "delete",
    "create",
    "scale"
  ],
  "associated_catalogs": [
    "iceberg_data",
    "hive_data"
  ],
  "build_version": "1.1.0.0.0",
  "coordinator": {
    "node_type": "bx2.4x16",
    "quantity": 1
  },
  "display_name": "starter",
  "drivers": [],
  "external_host_name": "your-hostname.apps.your-domain.com",
  "group_id": "presto511",
  "host_name": "1234-xyz456-abc4321.databases.appdomain.cloud",
  "id": "presto511",
  "origin": "native",
  "port": 30156,
  "resource_groups": [],
  "size_config": "starter",
  "status": "running",
  "status_code": 200,
  "tags": [
    "tag1",
    "tag2"
  ],
  "type": "presto",
  "version": "v0.282",
  "worker": {
    "node_type": "bx2.4x16",
    "quantity": 1
  }
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
Get presto engine catalogs
Get list of all catalogs attached to a presto engine


GET /presto_engines/{engine_id}/catalogs
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.
  • lakehouse.presto_engine_catalog.list
Request
Custom Headers
  • AuthInstanceId
    string
    watsonx.data instance ID
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-\:/]+$
Path Parameters
  • engine_id
    Required*
    string
    engine id
    

    Possible values:  1 ≤ length ≤ 1000, Value must match regular expression ^[a-zA-Z0-9\-]+$
  • curl -X 'GET' 'https://{region}.lakehouse.cloud.ibm.com/lakehouse/api/v3/presto_engines/{engine_id}/catalogs' -H 'accept: application/json' -H "AuthInstanceId: {instance id}"
Response
Response Body
CatalogCollection
Collection of catalogs


Status Code
  • 200
    Success
    

  • 400
    Error
    

  • 401
    Unauthorized
    

  • 404
    Not found
    

  • 500
    Internal server error
    

Example responses
  • {
  "catalogs": [
    {
      "actions": [
        "update",
        "delete"
      ],
      "associated_databases": [
        "database_1",
        "database_2"
      ],
      "associated_engines": [
        "engine_1",
        "engine_2"
      ],
      "associated_storage": [
        "bucket_1",
        "bucket_2"
      ],
      "base_path": "/abc/def",
      "catalog_sync_metadata": {
        "last_sync_at": "1765338982",
        "sync_description": "Table registration was successful",
        "sync_exception": [],
        "sync_status": "SUCCESS"
      },
      "created_at": "1765338982",
      "created_by": "<username>@<domain>.com",
      "days_left": "30",
      "description": "Iceberg catalog description",
      "location_uri": "s3a://testbucket",
      "managed_by": "ibm",
      "mds_connection_information": {
        "hostname": "example.example.lakehouse.dev.appdomain.cloud",
        "port": "3232"
      },
      "name": "sampleCatalog",
      "rest_uri": "https://samplehost-catalog:4352",
      "status": "running",
      "tags": [
        "tag1",
        "tag2"
      ],
      "thrift_uri": "thrift://samplehost-catalog:4354",
      "type": "iceberg"
    }
  ]
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
Associate catalogs to presto engine
Associate one or more catalogs to a presto engine


POST /presto_engines/{engine_id}/catalogs
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.
  • lakehouse.presto_engine_catalog.add
Request
Custom Headers
  • AuthInstanceId
    string
    watsonx.data instance ID
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-\:/]+$
Path Parameters
  • engine_id
    Required*
    string
    engine id
    

    Possible values:  1 ≤ length ≤ 1000, Value must match regular expression ^[a-zA-Z0-9\-]+$
Request Body
Required*
CatalogPrototype
Request body


  • curl -X POST 'https://{region}.lakehouse.cloud.ibm.com/lakehouse/api/v3/presto_engines/{engine_id}/catalogs' -H 'accept: application/json' -H 'Content-Type: application/json' -H 'AuthInstanceId: {instance id}' -d '{ 
  "catalog_names": [ 
    "hive_data" 
  ] 
}'
Response
Response Body
Catalog
Define the catalog details


Status Code
  • 201
    Success
    

  • 400
    Error
    

  • 401
    Unauthorized
    

  • 403
    Forbidden
    

  • 404
    Not found
    

  • 500
    Internal server error
    

Example responses
  • {
  "actions": [
    "select",
    "create",
    "update",
    "delete"
  ],
  "associated_databases": [
    "database_1",
    "database_2"
  ],
  "associated_engines": [
    "engine_1",
    "engine_2"
  ],
  "associated_storage": [
    "bucket_1",
    "bucket_2"
  ],
  "base_path": "/abc/def",
  "catalog_sync_metadata": {
    "last_sync_at": "1602839833",
    "sync_description": "Table registration was successful",
    "sync_exception": [
      "Table is corrupted",
      "Table metadata not available"
    ],
    "sync_status": "SUCCESS"
  },
  "created_at": "1602839833",
  "created_by": "user@example.com",
  "days_left": "30",
  "description": "Iceberg catalog description",
  "location_uri": "s3a://testbucket",
  "managed_by": "ibm",
  "mds_connection_information": {
    "hostname": "mds.host.lakehouse.dev",
    "port": "3232"
  },
  "name": "sampleCatalog",
  "rest_uri": "https://samplehost-catalog:4352",
  "status": "running",
  "tags": [
    "tag1",
    "tag2"
  ],
  "thrift_uri": "thrift://samplehost-catalog:4354",
  "type": "iceberg"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
Disassociate catalogs from a presto engine
Disassociate one or more catalogs from a presto engine


DELETE /presto_engines/{engine_id}/catalogs
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.
  • lakehouse.presto_engine_catalog.remove
Request
Custom Headers
  • AuthInstanceId
    string
    watsonx.data instance ID
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-\:/]+$
Path Parameters
  • engine_id
    Required*
    string
    engine id
    

    Possible values:  1 ≤ length ≤ 1000, Value must match regular expression ^[a-zA-Z0-9\-]+$
Query Parameters
  • catalog_names
    Required*
    string
    Catalog id(s) to be stopped, comma separated
    

    Possible values:  1 ≤ length ≤ 1000, Value must match regular expression ^[a-zA-Z0-9\-_,]+$
  • curl -X 'DELETE' 'https://{region}.lakehouse.cloud.ibm.com/lakehouse/api/v3/presto_engines/{engine_id}/catalogs?catalog_names=catalog_name1' -H 'accept: */*' -H "AuthInstanceId: {instance id}"
Response
Status Code
  • 204
    No Content
    

  • 400
    Error
    

  • 401
    Unauthorized
    

  • 403
    Forbidden
    

  • 404
    Not found
    

  • 500
    Internal server error
    

Example responses
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
Get presto engine catalog
Get catalog attached to presto engine


GET /presto_engines/{engine_id}/catalogs/{id}
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.
  • lakehouse.presto_engine_catalog.get
Request
Custom Headers
  • AuthInstanceId
    string
    watsonx.data instance ID
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-\:/]+$
Path Parameters
  • engine_id
    Required*
    string
    engine id
    

    Possible values:  1 ≤ length ≤ 1000, Value must match regular expression ^[a-zA-Z0-9\-_]+$
  • id
    Required*
    string
    catalog id
    

    Possible values:  1 ≤ length ≤ 1000, Value must match regular expression ^[a-zA-Z0-9\-_]+$
  • curl -X 'GET' 'https://{region}.lakehouse.cloud.ibm.com/lakehouse/api/v3/presto_engines/{engine_id}/catalogs/{id}' -H 'accept: application/json' -H "AuthInstanceId: {instance id}"
Response
Response Body
Catalog
Define the catalog details


Status Code
  • 200
    Success
    

  • 400
    Error
    

  • 401
    Unauthorized
    

  • 404
    Not found
    

  • 500
    Internal server error
    

Example responses
  • {
  "actions": [
    "select",
    "create",
    "update",
    "delete"
  ],
  "associated_databases": [
    "database_1",
    "database_2"
  ],
  "associated_engines": [
    "engine_1",
    "engine_2"
  ],
  "associated_storage": [
    "bucket_1",
    "bucket_2"
  ],
  "base_path": "/abc/def",
  "catalog_sync_metadata": {
    "last_sync_at": "1602839833",
    "sync_description": "Table registration was successful",
    "sync_exception": [
      "Table is corrupted",
      "Table metadata not available"
    ],
    "sync_status": "SUCCESS"
  },
  "created_at": "1602839833",
  "created_by": "user@example.com",
  "days_left": "30",
  "description": "Iceberg catalog description",
  "location_uri": "s3a://testbucket",
  "managed_by": "ibm",
  "mds_connection_information": {
    "hostname": "mds.host.lakehouse.dev",
    "port": "3232"
  },
  "name": "sampleCatalog",
  "rest_uri": "https://samplehost-catalog:4352",
  "status": "running",
  "tags": [
    "tag1",
    "tag2"
  ],
  "thrift_uri": "thrift://samplehost-catalog:4354",
  "type": "iceberg"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
Get presto engine
Get details of one presto engine


GET /presto_engines/{id}
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.
  • lakehouse.presto_engine.get
Request
Custom Headers
  • AuthInstanceId
    string
    watsonx.data instance ID
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-\:/]+$
Path Parameters
  • id
    Required*
    string
    engine id
    

    Possible values:  1 ≤ length ≤ 1000, Value must match regular expression ^[a-zA-Z0-9\-]+$
  • curl -X 'GET' 'https://{region}.lakehouse.cloud.ibm.com/lakehouse/api/v3/presto_engines/{id}' -H 'accept: application/json' -H "AuthInstanceId: {instance id}" 
Response
Response Body
PrestoEngine
Presto engine details.


Status Code
  • 200
    Success
    

  • 400
    Error
    

  • 401
    Unauthorized
    

  • 403
    Forbidden
    

  • 404
    Not found
    

  • 500
    Internal server error
    

Example responses
  • {
  "actions": [
    "view",
    "use",
    "update",
    "select",
    "access_ui",
    "associate",
    "disassociate",
    "restart",
    "pause",
    "resume",
    "grant",
    "revoke",
    "delete",
    "create",
    "scale"
  ],
  "associated_catalogs": [
    "iceberg_data",
    "hive_data"
  ],
  "build_version": "1.1.0.0.0",
  "coordinator": {
    "node_type": "bx2.4x16",
    "quantity": 1
  },
  "display_name": "starter",
  "drivers": [],
  "external_host_name": "your-hostname.apps.your-domain.com",
  "group_id": "presto511",
  "host_name": "1234-xyz456-abc4321.databases.appdomain.cloud",
  "id": "presto511",
  "origin": "native",
  "port": 30156,
  "resource_groups": [],
  "size_config": "starter",
  "status": "running",
  "status_code": 200,
  "tags": [
    "tag1",
    "tag2"
  ],
  "type": "presto",
  "version": "v0.282",
  "worker": {
    "node_type": "bx2.4x16",
    "quantity": 1
  }
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
Delete presto engine
Delete a presto engine


DELETE /presto_engines/{id}
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.
  • lakehouse.presto_engine.delete
Request
Custom Headers
  • AuthInstanceId
    string
    watsonx.data instance ID
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-\:/]+$
Path Parameters
  • id
    Required*
    string
    engine id
    

    Possible values:  1 ≤ length ≤ 1000, Value must match regular expression ^[a-zA-Z0-9\-]+$
  • curl -X 'DELETE' 'https://{region}.lakehouse.cloud.ibm.com/lakehouse/api/v3/presto_engines/{id}' -H 'accept: */*' -H "AuthInstanceId: {instance id}"
Response
Status Code
  • 204
    No Content
    

  • 400
    Error
    

  • 401
    Unauthorized
    

  • 403
    Forbidden
    

  • 404
    Not found
    

  • 500
    Internal server error
    

Example responses
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
Update presto engine
Update details of presto engine


PATCH /presto_engines/{id}
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.
  • lakehouse.presto_engine.update
Request
Custom Headers
  • AuthInstanceId
    string
    watsonx.data instance ID
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-\:/]+$
Path Parameters
  • id
    Required*
    string
    engine id
    

    Possible values:  1 ≤ length ≤ 1000, Value must match regular expression ^[a-zA-Z0-9\-]+$
Request Body
Required*
application/merge-patch+jsonPrestoEnginePatch
Update Engine Body


  • curl -X 'PATCH' 'https://{region}.lakehouse.cloud.ibm.com/lakehouse/api/v3/presto_engines/{id}' -H 'accept: application/json' -H 'Content-Type: application/merge-patch+json' -H "AuthInstanceId: {instance id}" -d '{  "description": "updated description for presto engine",  "display_name": "sampleEngine",  "tags": [    "tag1",    "tag2"  ]}'
Response
Response Body
PrestoEngine
Presto engine details.


Status Code
  • 200
    Success
    

  • 400
    Error
    

  • 401
    Unauthorized
    

  • 403
    Forbidden
    

  • 404
    Not found
    

  • 500
    Internal server error
    

Example responses
  • {
  "actions": [
    "view",
    "use",
    "update",
    "select",
    "access_ui",
    "associate",
    "disassociate",
    "restart",
    "pause",
    "resume",
    "grant",
    "revoke",
    "delete",
    "create",
    "scale"
  ],
  "associated_catalogs": [
    "iceberg_data",
    "hive_data"
  ],
  "build_version": "1.1.0.0.0",
  "coordinator": {
    "node_type": "bx2.4x16",
    "quantity": 1
  },
  "display_name": "starter",
  "drivers": [],
  "external_host_name": "your-hostname.apps.your-domain.com",
  "group_id": "presto511",
  "host_name": "1234-xyz456-abc4321.databases.appdomain.cloud",
  "id": "presto511",
  "origin": "native",
  "port": 30156,
  "resource_groups": [],
  "size_config": "starter",
  "status": "running",
  "status_code": 200,
  "tags": [
    "tag1",
    "tag2"
  ],
  "type": "presto",
  "version": "v0.282",
  "worker": {
    "node_type": "bx2.4x16",
    "quantity": 1
  }
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
Pause presto engine
Pause a running presto engine


POST /presto_engines/{id}/pause
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.
  • lakehouse.presto_engine.pause
Request
Custom Headers
  • AuthInstanceId
    string
    watsonx.data instance ID
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-\:/]+$
Path Parameters
  • id
    Required*
    string
    engine id
    

    Possible values:  1 ≤ length ≤ 1000, Value must match regular expression ^[a-zA-Z0-9\-]+$
  • curl -X 'POST' 'https://{region}.lakehouse.cloud.ibm.com/lakehouse/api/v3/presto_engines/{id}/pause' -H 'accept: application/json' -H "AuthInstanceId: {instance id}" -d ''
Response
Response Body
PrestoEngineSuccessResponse
Pause


Status Code
  • 200
    Success
    

  • 400
    Error
    

  • 401
    Unauthorized
    

  • 404
    Not found
    

  • 500
    Internal server error
    

Example responses
  • {
  "response": {
    "message": "Success",
    "message_code": "success"
  }
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
Explain presto query
Explain a query statement


POST /presto_engines/{id}/query_explain
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.
  • lakehouse.query_explain.create
Request
Custom Headers
  • AuthInstanceId
    string
    watsonx.data instance ID
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-\:/]+$
Path Parameters
  • id
    Required*
    string
    Engine id
    

    Possible values:  1 ≤ length ≤ 1000, Value must match regular expression ^[a-zA-Z0-9\-]+$
Request Body
Required*
ExplainPrototype
Request body


  • curl -X 'POST' 'https://{region}.lakehouse.cloud.ibm.com/lakehouse/api/v3/presto_engines/{id}/query_explain' -H 'accept: application/json' -H 'Content-Type: application/json' -H "AuthInstanceId: {instance id}" -d '{  "format": "json",  "statement": "show schemas in catalog_name",  "type": "io"}'
Response
Response Body
PrestoQueryExplain
ExplainStatement OK


Status Code
  • 200
    Success
    

  • 400
    Error
    

  • 401
    Unauthorized
    

  • 404
    Not found
    

  • 500
    Internal server error
    

Example responses
  • {
  "response": {
    "message": "Success",
    "message_code": "success"
  },
  "result": "- Output[PlanNodeId 8][Catalog] => [field:varchar(24)]\n    Estimates: {source: CostBasedSourceInfo, rows: 11 (605B), cpu: 1,210.00, memory: 605.00, network: 1,210.00}\n    Catalog := field\n- RemoteStreamingMerge[PlanNodeId 188][field ASC_NULLS_LAST] => [field:varchar(24)]\n    Estimates: {source: CostBasedSourceInfo, rows: 11 (605B), cpu: 1,210.00, memory: 605.00, network: 1,210.00}\n  - LocalMerge[PlanNodeId 210][field ASC_NULLS_LAST] => [field:varchar(24)]\n      Estimates: {source: CostBasedSourceInfo, rows: 11 (605B), cpu: 1,210.00, memory: 605.00, network: 605.00}\n    - PartialSort[PlanNodeId 189][field ASC_NULLS_LAST] => [field:varchar(24)]\n        Estimates: {source: CostBasedSourceInfo, rows: 11 (605B), cpu: 1,210.00, memory: 605.00, network: 605.00}\n      - RemoteStreamingExchange[PlanNodeId 187][REPARTITION] => [field:varchar(24)]\n          Estimates: {source: CostBasedSourceInfo, rows: 11 (605B), cpu: 605.00, memory: 0.00, network: 605.00}\n        - Values[PlanNodeId 0] => [field:varchar(24)]\n            Estimates: {source: CostBasedSourceInfo, rows: 11 (605B), cpu: 0.00, memory: 0.00, network: 0.00}\n            (VARCHAR'automation_blackhole')\n            (VARCHAR'automation_iceberg_ozone')\n            (VARCHAR'automation_localfile')\n            (VARCHAR'cos_catalog')\n            (VARCHAR'cosicebergcaatlog')\n            (VARCHAR'db2cat')\n            (VARCHAR'jmx')\n            (VARCHAR'ms_sql_cat')\n            (VARCHAR'system')\n            (VARCHAR'tpcds')\n            (VARCHAR'tpch')\n"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
Explain presto analyze
Return query metrics after query is complete


POST /presto_engines/{id}/query_explain_analyze
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.
  • lakehouse.query_explain_analyze.create
Request
Custom Headers
  • AuthInstanceId
    string
    watsonx.data instance ID
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-\:/]+$
Path Parameters
  • id
    Required*
    string
    Engine id
    

    Possible values:  1 ≤ length ≤ 1000, Value must match regular expression ^[a-zA-Z0-9\-]+$
Request Body
Required*
ExplainAnalyzePrototype
Request body


  • curl -X 'POST' 'https://{region}.lakehouse.cloud.ibm.com/lakehouse/api/v3/presto_engines/{id}/query_explain_analyze' -H 'accept: application/json' -H 'Content-Type: application/json' -H "AuthInstanceId: {instance id}" -d '{  "statement": "show schemas in catalog_name",  "verbose": true}'
Response
Response Body
PrestoQueryExplain
ExplainStatement OK


Status Code
  • 200
    Success
    

  • 400
    Error
    

  • 401
    Unauthorized
    

  • 404
    Not found
    

  • 500
    Internal server error
    

Example responses
  • {
  "response": {
    "message": "Success",
    "message_code": "success"
  },
  "result": "- Output[PlanNodeId 8][Catalog] => [field:varchar(24)]\n    Estimates: {source: CostBasedSourceInfo, rows: 11 (605B), cpu: 1,210.00, memory: 605.00, network: 1,210.00}\n    Catalog := field\n- RemoteStreamingMerge[PlanNodeId 188][field ASC_NULLS_LAST] => [field:varchar(24)]\n    Estimates: {source: CostBasedSourceInfo, rows: 11 (605B), cpu: 1,210.00, memory: 605.00, network: 1,210.00}\n  - LocalMerge[PlanNodeId 210][field ASC_NULLS_LAST] => [field:varchar(24)]\n      Estimates: {source: CostBasedSourceInfo, rows: 11 (605B), cpu: 1,210.00, memory: 605.00, network: 605.00}\n    - PartialSort[PlanNodeId 189][field ASC_NULLS_LAST] => [field:varchar(24)]\n        Estimates: {source: CostBasedSourceInfo, rows: 11 (605B), cpu: 1,210.00, memory: 605.00, network: 605.00}\n      - RemoteStreamingExchange[PlanNodeId 187][REPARTITION] => [field:varchar(24)]\n          Estimates: {source: CostBasedSourceInfo, rows: 11 (605B), cpu: 605.00, memory: 0.00, network: 605.00}\n        - Values[PlanNodeId 0] => [field:varchar(24)]\n            Estimates: {source: CostBasedSourceInfo, rows: 11 (605B), cpu: 0.00, memory: 0.00, network: 0.00}\n            (VARCHAR'automation_blackhole')\n            (VARCHAR'automation_iceberg_ozone')\n            (VARCHAR'automation_localfile')\n            (VARCHAR'cos_catalog')\n            (VARCHAR'cosicebergcaatlog')\n            (VARCHAR'db2cat')\n            (VARCHAR'jmx')\n            (VARCHAR'ms_sql_cat')\n            (VARCHAR'system')\n            (VARCHAR'tpcds')\n            (VARCHAR'tpch')\n"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
Restart a presto engine
Restart an existing presto engine


POST /presto_engines/{id}/restart
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.
  • lakehouse.presto_engine.refresh
Request
Custom Headers
  • AuthInstanceId
    string
    watsonx.data instance ID
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-\:/]+$
Path Parameters
  • id
    Required*
    string
    engine id
    

    Possible values:  1 ≤ length ≤ 1000, Value must match regular expression ^[a-zA-Z0-9\-_]+$
  • curl -X 'POST' 'https://{region}.lakehouse.cloud.ibm.com/lakehouse/api/v3/presto_engines/{id}/restart' -H 'accept: application/json' -H "AuthInstanceId: {instance id}" -d ''
Response
Response Body
PrestoEngineSuccessResponse
Pause


Status Code
  • 200
    Success
    

  • 400
    Error
    

  • 401
    Unauthorized
    

  • 403
    Forbidden
    

  • 404
    Not found
    

  • 500
    Internal server error
    

Example responses
  • {
  "response": {
    "message": "Success",
    "message_code": "success"
  }
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
Resume Presto(Java) engine
Resume a paused presto engine


POST /presto_engines/{id}/resume
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.
  • lakehouse.presto_engine.resume
Request
Custom Headers
  • AuthInstanceId
    string
    watsonx.data instance ID
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-\:/]+$
Path Parameters
  • id
    Required*
    string
    engine id
    

    Possible values:  1 ≤ length ≤ 1000, Value must match regular expression ^[a-zA-Z0-9\-]+$
  • curl -X 'POST' 'https://{region}.lakehouse.cloud.ibm.com/lakehouse/api/v3/presto_engines/{id}/resume' -H 'accept: application/json' -H "AuthInstanceId: {instance id}" -d ''
Response
Response Body
PrestoEngineSuccessResponse
Pause


Status Code
  • 200
    Success
    

  • 400
    Error
    

  • 401
    Unauthorized
    

  • 404
    Not found
    

  • 500
    Internal server error
    

Example responses
  • {
  "response": {
    "message": "Success",
    "message_code": "success"
  }
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
Scale a presto engine
Scale an existing presto engine


POST /presto_engines/{id}/scale
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.
  • lakehouse.presto_engine.scale
Request
Custom Headers
  • AuthInstanceId
    string
    watsonx.data instance ID
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-\:/]+$
Path Parameters
  • id
    Required*
    string
    engine id
    

    Possible values:  1 ≤ length ≤ 1000, Value must match regular expression ^[a-zA-Z0-9\-]+$
Request Body
Required*
PrestoEngineScale
Scale Engine Body


  • curl -X 'POST' 'https://{region}.lakehouse.cloud.ibm.com/lakehouse/api/v3/presto_engines/{id}/scale' -H 'accept: application/json' -H 'Content-Type: application/json' -H "AuthInstanceId: {instance id}" -d '{  "coordinator": {    "node_type": "worker",    "quantity": 0  },  "worker": {    "node_type": "worker",    "quantity": 0  }}'
Response
Response Body
PrestoEngineSuccessResponse
Pause


Status Code
  • 202
    Success
    

  • 400
    Error
    

  • 401
    Unauthorized
    

  • 404
    Not found
    

  • 500
    Internal server error
    

Example responses
  • {
  "response": {
    "message": "Success",
    "message_code": "success"
  }
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
Collection of Prestissimo engines
Collection of Prestissimo engines


GET /prestissimo_engines
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.
  • lakehouse.prestissimo_engine.list
Request
Custom Headers
  • AuthInstanceId
    string
    watsonx.data instance ID
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-\:/]+$
  • curl -X GET -H "accept: application/json" -H "AuthInstanceId: {instance_id}" "https://{region}.lakehouse.cloud.ibm.com/lakehouse/api/v3/prestissimo_engines"
Response
Response Body
PrestissimoEngineCollection
list Prestissimo Engines


Status Code
  • 200
    Success
    

  • 400
    Error
    

  • 401
    Unauthorized
    

  • 404
    Not found
    

  • 500
    Internal server error
    

Example responses
  • {
  "prestissimo_engines": [
    {
      "actions": [
        "view",
        "use",
        "update",
        "select",
        "access_ui",
        "associate",
        "disassociate",
        "restart",
        "pause",
        "resume",
        "grant",
        "revoke",
        "delete",
        "create",
        "scale"
      ],
      "associated_catalogs": [
        "hive_data"
      ],
      "build_version": "1.1.0.0.0",
      "coordinator": {
        "node_type": "bx2.4x16",
        "quantity": 1
      },
      "display_name": "starter",
      "id": "prestissimo511",
      "external_host_name": "your-hostname.apps.your-domain.com",
      "group_id": "prestissimo511",
      "host_name": "1234-xyz456-abc4321.databases.appdomain.cloud",
      "origin": "native",
      "port": 30156,
      "size_config": "starter",
      "status": "running",
      "status_code": 0,
      "tags": [
        "tag1",
        "tag2"
      ],
      "type": "prestissimo",
      "version": "v0.282",
      "worker": {
        "node_type": "bx2.4x16",
        "quantity": 1
      }
    }
  ]
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
Create prestissimo engine
Create a new prestissimo engine


POST /prestissimo_engines
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.
  • lakehouse.prestissimo_engine.create
Request
Custom Headers
  • AuthInstanceId
    string
    watsonx.data instance ID
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-\:/]+$
Request Body
Required*
PrestissimoEnginePrototype
Create Engine Body


  • curl -X POST 'https://{region}.lakehouse.cloud.ibm.com/lakehouse/api/v3/prestissimo_engines' -H 'accept: application/json' -H 'Content-Type: application/json' -d '{ 
  "description": "", 
  "configuration": { 
    "coordinator": { 
      "node_type": "bx2.4x16", 
      "quantity": 1 
    }, 
    "size_config": "custom", 
    "worker": { 
      "node_type": "bx2.4x16", 
      "quantity": 1 
    } 
  }, 
  "display_name": "prestissimo-01", 
  "origin": "native", 
  "associated_catalogs": [], 
  "version": "v0.286", 
  "tags": [], 
  "region": "us-south" 
}'
Response
Response Body
PrestissimoEngine
EngineDetail


Status Code
  • 201
    Success
    

  • 400
    Error
    

  • 401
    Unauthorized
    

  • 404
    Not found
    

  • 500
    Internal server error
    

Example responses
  • {
  "actions": [
    "update",
    "delete"
  ],
  "associated_catalogs": [
    "hive_data"
  ],
  "coordinator": {
    "node_type": "worker",
    "quantity": 1
  },
  "created_at": 16378838,
  "created_by": "<username>@<domain>.com",
  "description": "prestissimo engine for running sql queries",
  "display_name": "sampleEngine",
  "engine_id": "sampleEngine123",
  "external_host_name": "your-hostname.apps.your-domain.com",
  "group_id": "new_group_id",
  "host_name": "your-hostname.apps.your-domain.com",
  "origin": "native",
  "region": "us-south",
  "size_config": "starter",
  "status": "running",
  "status_code": 0,
  "tags": [
    "tag1",
    "tag2"
  ],
  "version": "1.2.0",
  "worker": {
    "node_type": "worker",
    "quantity": 1
  }
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
Get prestissimo engine catalog
Get catalog attached to a prestissimo engine


GET /prestissimo_engines/{engine_id}/catalogs/{id}
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.
  • lakehouse.prestissimo_engine_catalog.get
Request
Custom Headers
  • AuthInstanceId
    string
    watsonx.data instance ID
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-\:/]+$
Path Parameters
  • engine_id
    Required*
    string
    engine id
    

    Possible values:  1 ≤ length ≤ 1000, Value must match regular expression ^[a-zA-Z0-9\-]+$
  • id
    Required*
    string
    catalog id
    

    Possible values:  1 ≤ length ≤ 1000, Value must match regular expression ^[a-zA-Z0-9\-_]+$
  • curl -X 'GET' 'https://{region}.lakehouse.cloud.ibm.com/lakehouse/api/v3/prestissimo_engines/{engine_id}/catalogs/{catalog_id}' -H 'accept: application/json' -H "AuthInstanceId: {instance id}"
Response
Response Body
Catalog
Define the catalog details


Status Code
  • 200
    Success
    

  • 400
    Error
    

  • 401
    Unauthorized
    

  • 404
    Not found
    

  • 500
    Internal server error
    

Example responses
  • {
  "actions": [
    "select",
    "create",
    "update",
    "delete"
  ],
  "associated_databases": [
    "database_1",
    "database_2"
  ],
  "associated_engines": [
    "engine_1",
    "engine_2"
  ],
  "associated_storage": [
    "bucket_1",
    "bucket_2"
  ],
  "base_path": "/abc/def",
  "catalog_sync_metadata": {
    "last_sync_at": "1602839833",
    "sync_description": "Table registration was successful",
    "sync_exception": [
      "Table is corrupted",
      "Table metadata not available"
    ],
    "sync_status": "SUCCESS"
  },
  "created_at": "1602839833",
  "created_by": "user@example.com",
  "days_left": "30",
  "description": "Iceberg catalog description",
  "location_uri": "s3a://testbucket",
  "managed_by": "ibm",
  "mds_connection_information": {
    "hostname": "mds.host.lakehouse.dev",
    "port": "3232"
  },
  "name": "sampleCatalog",
  "rest_uri": "https://samplehost-catalog:4352",
  "status": "running",
  "tags": [
    "tag1",
    "tag2"
  ],
  "thrift_uri": "thrift://samplehost-catalog:4354",
  "type": "iceberg"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
Get prestissimo engine
Prestissimo engine details


GET /prestissimo_engines/{id}
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.
  • lakehouse.prestissimo_engine.get
Request
Custom Headers
  • AuthInstanceId
    string
    watsonx.data instance ID
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-\:/]+$
Path Parameters
  • id
    Required*
    string
    engine id
    

    Possible values:  1 ≤ length ≤ 1000, Value must match regular expression ^[a-zA-Z0-9\-]+$
  • curl -X 'GET' 'https://{region}.lakehouse.cloud.ibm.com/lakehouse/api/v3/prestissimo_engines/{engine_id}' -H 'accept: application/json' -H "AuthInstanceId: {instance id}" 
Response
Response Body
PrestissimoEngine
EngineDetail


Status Code
  • 200
    Success
    

  • 400
    Error
    

  • 401
    Unauthorized
    

  • 403
    Forbidden
    

  • 404
    Not found
    

  • 500
    Internal server error
    

Example responses
  • {
  "actions": [
    "update",
    "delete"
  ],
  "associated_catalogs": [
    "hive_data"
  ],
  "coordinator": {
    "node_type": "worker",
    "quantity": 1
  },
  "created_at": 16378838,
  "created_by": "<username>@<domain>.com",
  "description": "prestissimo engine for running sql queries",
  "display_name": "sampleEngine",
  "engine_id": "sampleEngine123",
  "external_host_name": "your-hostname.apps.your-domain.com",
  "group_id": "new_group_id",
  "host_name": "your-hostname.apps.your-domain.com",
  "origin": "native",
  "region": "us-south",
  "size_config": "starter",
  "status": "running",
  "status_code": 0,
  "tags": [
    "tag1",
    "tag2"
  ],
  "version": "1.2.0",
  "worker": {
    "node_type": "worker",
    "quantity": 1
  }
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
Delete prestissimo engine
Delete a prestissimo engine


DELETE /prestissimo_engines/{id}
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.
  • lakehouse.prestissimo_engine.delete
Request
Custom Headers
  • AuthInstanceId
    string
    watsonx.data instance ID
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-\:/]+$
Path Parameters
  • id
    Required*
    string
    engine id
    

    Possible values:  1 ≤ length ≤ 1000, Value must match regular expression ^[a-zA-Z0-9\-]+$
  • curl -X 'DELETE' 'https://{region}.lakehouse.cloud.ibm.com/lakehouse/api/v3/prestissimo_engines/{engine_id}' -H 'accept: */*' -H "AuthInstanceId: {instance id}"
Response
Status Code
  • 204
    No Content
    

  • 400
    Error
    

  • 401
    Unauthorized
    

  • 404
    Not found
    

  • 500
    Internal server error
    

Example responses
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
Update prestissimo engine
Update details of prestissimo engine


PATCH /prestissimo_engines/{id}
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.
  • lakehouse.prestissimo_engine.update
Request
Custom Headers
  • AuthInstanceId
    string
    watsonx.data instance ID
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-\:/]+$
Path Parameters
  • id
    Required*
    string
    engine id
    

    Possible values:  1 ≤ length ≤ 1000, Value must match regular expression ^[a-zA-Z0-9\-]+$
Request Body
Required*
application/merge-patch+jsonPrestissimoEnginePatch
Update prestissimo engine body


  • curl -X 'PATCH' 'https://{region}.lakehouse.cloud.ibm.com/lakehouse/api/v3/prestissimo_engines/{engine_id}' -H 'accept: application/json' -H 'Content-Type: application/merge-patch+json' -H "AuthInstanceId: {instance id}" -d '{  "description": "updated description for presto engine",  "display_name": "sampleEngine",  "tags": [    "tag1",    "tag2"  ]}'
Response
Response Body
PrestissimoEngine
EngineDetail


Status Code
  • 200
    Success
    

  • 400
    Error
    

  • 401
    Unauthorized
    

  • 404
    Not found
    

  • 500
    Internal server error
    

Example responses
  • {
  "actions": [
    "update",
    "delete"
  ],
  "associated_catalogs": [
    "hive_data"
  ],
  "coordinator": {
    "node_type": "worker",
    "quantity": 1
  },
  "created_at": 16378838,
  "created_by": "<username>@<domain>.com",
  "description": "prestissimo engine for running sql queries",
  "display_name": "sampleEngine",
  "engine_id": "sampleEngine123",
  "external_host_name": "your-hostname.apps.your-domain.com",
  "group_id": "new_group_id",
  "host_name": "your-hostname.apps.your-domain.com",
  "origin": "native",
  "region": "us-south",
  "size_config": "starter",
  "status": "running",
  "status_code": 0,
  "tags": [
    "tag1",
    "tag2"
  ],
  "version": "1.2.0",
  "worker": {
    "node_type": "worker",
    "quantity": 1
  }
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
Get prestissimo engine catalogs
Get list of all catalogs attached a prestissimo engine


GET /prestissimo_engines/{id}/catalogs
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.
  • lakehouse.prestissimo_engine_catalog.list
Request
Custom Headers
  • AuthInstanceId
    string
    watsonx.data instance ID
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-\:/]+$
Path Parameters
  • id
    Required*
    string
    engine id
    

    Possible values:  1 ≤ length ≤ 1000, Value must match regular expression ^[a-zA-Z0-9\-]+$
  • curl -X 'GET' 'https://{region}.lakehouse.cloud.ibm.com/lakehouse/api/v3/prestissimo_engines/{engine_id}/catalogs' -H 'accept: application/json' -H "AuthInstanceId: {instance id}"
Response
Response Body
CatalogCollection
Collection of catalogs


Status Code
  • 200
    Success
    

  • 400
    Error
    

  • 401
    Unauthorized
    

  • 404
    Not found
    

  • 500
    Internal server error
    

Example responses
  • {
  "catalogs": [
    {
      "actions": [
        "update",
        "delete"
      ],
      "associated_databases": [
        "database_1",
        "database_2"
      ],
      "associated_engines": [
        "engine_1",
        "engine_2"
      ],
      "associated_storage": [
        "bucket_1",
        "bucket_2"
      ],
      "base_path": "/abc/def",
      "catalog_sync_metadata": {
        "last_sync_at": "1765338982",
        "sync_description": "Table registration was successful",
        "sync_exception": [],
        "sync_status": "SUCCESS"
      },
      "created_at": "1765338982",
      "created_by": "<username>@<domain>.com",
      "days_left": "30",
      "description": "Iceberg catalog description",
      "location_uri": "s3a://testbucket",
      "managed_by": "ibm",
      "mds_connection_information": {
        "hostname": "example.example.lakehouse.dev.appdomain.cloud",
        "port": "3232"
      },
      "name": "sampleCatalog",
      "rest_uri": "https://samplehost-catalog:4352",
      "status": "running",
      "tags": [
        "tag1",
        "tag2"
      ],
      "thrift_uri": "thrift://samplehost-catalog:4354",
      "type": "iceberg"
    }
  ]
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
Associate catalogs to a prestissimo engine
Associate one or more catalogs to a prestissimo engine


POST /prestissimo_engines/{id}/catalogs
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.
  • lakehouse.prestissimo_engine_catalog.add
Request
Custom Headers
  • AuthInstanceId
    string
    watsonx.data instance ID
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-\:/]+$
Path Parameters
  • id
    Required*
    string
    engine id
    

    Possible values:  1 ≤ length ≤ 1000, Value must match regular expression ^[a-zA-Z0-9\-]+$
Request Body
Required*
CatalogPrototype
Request body


  • curl -X 'POST' 'https://{region}.lakehouse.cloud.ibm.com/lakehouse/api/v3/prestissimo_engines/{engine_id}/catalogs' -H 'accept: application/json' -d '{ "catalog_names": "catalog_name", }' -H "AuthInstanceId: {instance id}"
Response
Response Body
CatalogCollection
Collection of catalogs


Status Code
  • 201
    Success
    

  • 400
    Error
    

  • 401
    Unauthorized
    

  • 403
    Forbidden
    

  • 404
    Not found
    

  • 500
    Internal server error
    

Example responses
  • {
  "catalogs": [
    {
      "actions": [
        "update",
        "delete"
      ],
      "associated_databases": [
        "database_1",
        "database_2"
      ],
      "associated_engines": [
        "engine_1",
        "engine_2"
      ],
      "associated_storage": [
        "bucket_1",
        "bucket_2"
      ],
      "base_path": "/abc/def",
      "catalog_sync_metadata": {
        "last_sync_at": "1765338982",
        "sync_description": "Table registration was successful",
        "sync_exception": [],
        "sync_status": "SUCCESS"
      },
      "created_at": "1765338982",
      "created_by": "<username>@<domain>.com",
      "days_left": "30",
      "description": "Iceberg catalog description",
      "location_uri": "s3a://testbucket",
      "managed_by": "ibm",
      "mds_connection_information": {
        "hostname": "example.example.lakehouse.dev.appdomain.cloud",
        "port": "3232"
      },
      "name": "sampleCatalog",
      "rest_uri": "https://samplehost-catalog:4352",
      "status": "running",
      "tags": [
        "tag1",
        "tag2"
      ],
      "thrift_uri": "thrift://samplehost-catalog:4354",
      "type": "iceberg"
    }
  ]
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
Disassociate catalogs from a prestissimo engine
Disassociate one or more catalogs from a prestissimo engine


DELETE /prestissimo_engines/{id}/catalogs
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.
  • lakehouse.prestissimo_engine_catalog.remove
Request
Custom Headers
  • AuthInstanceId
    string
    watsonx.data instance ID
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-\:/]+$
Path Parameters
  • id
    Required*
    string
    engine id
    

    Possible values:  1 ≤ length ≤ 1000, Value must match regular expression ^[a-zA-Z0-9\-]+$
Query Parameters
  • catalog_names
    Required*
    string
    Catalog id(s) to be stopped, comma separated
    

    Possible values:  1 ≤ length ≤ 1000, Value must match regular expression ^[a-zA-Z0-9\-,_]+$
  • curl -X 'DELETE' 'https://{region}.lakehouse.cloud.ibm.com/lakehouse/api/v3/presto_engines/{engine_id}/catalogs?catalog_names=catalog_name1' -H 'accept: */*' -H "AuthInstanceId: {instance id}"
Response
Status Code
  • 204
    No Content
    

  • 400
    Error
    

  • 401
    Unauthorized
    

  • 403
    Forbidden
    

  • 404
    Not found
    

  • 500
    Internal server error
    

Example responses
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
Pause prestissimo engine
Pause a running prestissimo engine ie, only available is SAAS


POST /prestissimo_engines/{id}/pause
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.
  • lakehouse.prestissimo_engine.pause
Request
Custom Headers
  • AuthInstanceId
    string
    watsonx.data instance ID
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-\:/]+$
Path Parameters
  • id
    Required*
    string
    engine id
    

    Possible values:  1 ≤ length ≤ 1000, Value must match regular expression ^[a-zA-Z0-9\-]+$
  • curl -X 'POST' 'https://{region}.lakehouse.cloud.ibm.com/lakehouse/api/v3/prestissimo_engines/{engine_id}/pause' -H 'accept: application/json' -H "AuthInstanceId: {instance id}" -d ''
Response
Response Body
SuccessResponse
Response of success


Status Code
  • 200
    Success
    

  • 400
    Error
    

  • 401
    Unauthorized
    

  • 404
    Not found
    

  • 500
    Internal server error
    

Example responses
  • {
  "message": "Successful message",
  "message_code": "success"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
Explain query
Explain a query statement


POST /prestissimo_engines/{id}/query_explain
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.
  • lakehouse.query_explain.create
Request
Custom Headers
  • AuthInstanceId
    string
    watsonx.data instance ID
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-\:/]+$
Path Parameters
  • id
    Required*
    string
    Engine id
    

    Possible values:  1 ≤ length ≤ 1000, Value must match regular expression ^[a-zA-Z0-9\-]+$
Request Body
Required*
ExplainPrototype
Request body


  • curl -X 'POST' 'https://{region}.lakehouse.cloud.ibm.com/lakehouse/api/v3/prestissimo_engines/{engine_id}/query_explain' -H 'accept: application/json' -H 'Content-Type: application/json' -H "AuthInstanceId: {instance id}" -d '{  "format": "json",  "statement": "show schemas in catalog_name",  "type": "io"}'
Response
Response Body
ResultPrestissimoExplainStatement
ExplainStatement OK


Status Code
  • 200
    Success
    

  • 400
    Error
    

  • 401
    Unauthorized
    

  • 404
    Not found
    

  • 500
    Internal server error
    

Example responses
  • {
  "result": "explain"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
Explain analyze
Return query metrics after query is complete


POST /prestissimo_engines/{id}/query_explain_analyze
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.
  • lakehouse.query_explain_analyze.create
Request
Custom Headers
  • AuthInstanceId
    string
    watsonx.data instance ID
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-\:/]+$
Path Parameters
  • id
    Required*
    string
    Engine id
    

    Possible values:  1 ≤ length ≤ 1000, Value must match regular expression ^[a-zA-Z0-9\-]+$
Request Body
Required*
ExplainAnalyzePrototype
Request body


  • curl -X 'POST' 'https://{region}.lakehouse.cloud.ibm.com/lakehouse/api/v3/presto_engines/{engine_id}/query_explain_analyze' -H 'accept: application/json' -H 'Content-Type: application/json' -H "AuthInstanceId: {instance id}" -d '{  "statement": "show schemas in catalog_name",  "verbose": true}'
Response
Response Body
ResultRunPrestissimoExplainAnalyzeStatement
explainAnalyzeStatement OK


Status Code
  • 200
    Success
    

  • 400
    Error
    

  • 401
    Unauthorized
    

  • 404
    Not found
    

  • 500
    Internal server error
    

Example responses
  • {
  "result": "statement"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
Restart a prestissimo engine
Restart an existing prestissimo engine


POST /prestissimo_engines/{id}/restart
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.
  • lakehouse.prestissimo_engine.refresh
Request
Custom Headers
  • AuthInstanceId
    string
    watsonx.data instance ID
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-\:/]+$
Path Parameters
  • id
    Required*
    string
    engine id
    

    Possible values:  1 ≤ length ≤ 1000, Value must match regular expression ^[a-zA-Z0-9\-]+$
  • curl -X 'POST' 'https://{region}.lakehouse.cloud.ibm.com/lakehouse/api/prestissimo_engines/{engine_id}/restart' -H 'accept: application/json' -H "AuthInstanceId: {instance id}" -d ''
Response
Response Body
SuccessResponse
Response of success


Status Code
  • 200
    Success
    

  • 400
    Error
    

  • 401
    Unauthorized
    

  • 403
    Forbidden
    

  • 404
    Not found
    

  • 500
    Internal server error
    

Example responses
  • {
  "message": "Successful message",
  "message_code": "success"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
Resume prestissimo engine
Resume a paused prestissimo engine ie, only available is SAAS


POST /prestissimo_engines/{id}/resume
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.
  • lakehouse.prestissimo_engine.resume
Request
Custom Headers
  • AuthInstanceId
    string
    watsonx.data instance ID
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-\:/]+$
Path Parameters
  • id
    Required*
    string
    engine id
    

    Possible values:  1 ≤ length ≤ 1000, Value must match regular expression ^[a-zA-Z0-9\-]+$
  • curl -X 'POST' 'https://{region}.lakehouse.cloud.ibm.com/lakehouse/api/v3/prestissimo_engines/{engine_id}/resume' -H 'accept: application/json' -H "AuthInstanceId: {instance id}" -d ''
Response
Response Body
SuccessResponse
Response of success


Status Code
  • 200
    Success
    

  • 400
    Error
    

  • 401
    Unauthorized
    

  • 404
    Not found
    

  • 500
    Internal server error
    

Example responses
  • {
  "message": "Successful message",
  "message_code": "success"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
Scale a prestissimo engine
Scale an existing prestissimo engine ie, only available is SAAS


POST /prestissimo_engines/{id}/scale
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.
  • lakehouse.prestissimo_engine.scale
Request
Custom Headers
  • AuthInstanceId
    string
    watsonx.data instance ID
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-\:/]+$
Path Parameters
  • id
    Required*
    string
    engine id
    

    Possible values:  1 ≤ length ≤ 1000, Value must match regular expression ^[a-zA-Z0-9\-]+$
Request Body
Required*
PrestissimoEngineScale
Scale Engine Body


  • curl -X 'POST' 'https://{region}.lakehouse.cloud.ibm.com/lakehouse/api/v3/prestissimo_engines/{engine_id}/scale' -H 'accept: application/json' -H 'Content-Type: application/json' -H "AuthInstanceId: {instance id}" -d '{  "coordinator": {    "node_type": "worker",    "quantity": 0  },  "worker": {    "node_type": "worker",    "quantity": 0  }}'
Response
Response Body
SuccessResponse
Response of success


Status Code
  • 202
    Success
    

  • 400
    Error
    

  • 401
    Unauthorized
    

  • 404
    Not found
    

  • 500
    Internal server error
    

Example responses
  • {
  "message": "Successful message",
  "message_code": "success"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
Get list of db2 engines
Get list of all db2 engines


GET /db2_engines
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.
  • lakehouse.db2_engine.list
Request
Custom Headers
  • AuthInstanceId
    string
    watsonx.data instance ID
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-\:/]+$
  • curl -X GET -H "content-type: application/json" -H "AuthInstanceId: {instance_id}" "https://{region}.lakehouse.cloud.ibm.com/lakehouse/api/v3/db2_engines"
Response
Response Body
Db2EngineCollection
list db2 engines


Status Code
  • 200
    Success
    

  • 400
    Error
    

  • 401
    Unauthorized
    

  • 404
    Not found
    

  • 500
    Internal server error
    

Example responses
  • {
  "db2_engines": [
    {
      "actions": [
        "create"
      ],
      "created_at": 1700322436,
      "created_by": "user@test.com",
      "description": "db2 engine to run sql queries",
      "display_name": "db2",
      "engine_details": {
        "connection_string": "jdbc:db2://localhost:5480/database",
        "metastore_host": "thrift://mh-connection-string-sample.com"
      },
      "id": "db2505",
      "origin": "external",
      "status": "REGISTERED",
      "tags": [
        "tag1",
        "tag2"
      ],
      "type": "db2"
    }
  ]
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
Create db2 engine
Create a new db2 engine


POST /db2_engines
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.
  • lakehouse.db2_engine.create
Request
Custom Headers
  • AuthInstanceId
    string
    watsonx.data instance ID
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-\:/]+$
Request Body
Required*
Db2EnginePrototype
Create db2 engine body


  • curl -X POST -H "accept: application/json" -H "AuthInstanceId: {instance_id}" -H "Content-Type: application/json" -d '{ "description": "db2 engine description", "configuration": { "connection_string": "1.2.3.4" }, "display_name": "sampleEngine", "origin": "external", "tags": [ "tag1", "tag2" ], "type": "db2" }' "https://{region}.lakehouse.cloud.ibm.com/lakehouse/api/v3/db2_engines"
Response
Response Body
Db2Engine
Db2 engine details


Status Code
  • 201
    Success
    

  • 400
    Error
    

  • 401
    Unauthorized
    

  • 404
    Not found
    

  • 500
    Internal server error
    

Example responses
  • {
  "Db2Engine": null,
  "actions": [
    "update",
    "delete"
  ],
  "build_version": "1.0.3.0.0",
  "created_at": 1700322469,
  "created_by": "user@test.com",
  "description": "updated description for db2 engine.",
  "display_name": "db2-engine",
  "engine_details": {
    "connection_string\"": "jdbc:db2://localhost:5480/database",
    "metastore_host": "thrift://mh-connection-string-sample.com"
  },
  "host_name": "xyz-db2-01-db2-svc",
  "id": "db210",
  "origin": "external",
  "port": 3449,
  "status": "REGISTERED",
  "tags": [
    "tag1",
    "tag2"
  ],
  "type": "db2"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
Delete db2 engine
Delete a db2 engine


DELETE /db2_engines/{id}
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.
  • lakehouse.db2_engine.delete
Request
Custom Headers
  • AuthInstanceId
    string
    watsonx.data instance ID
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-\:/]+$
Path Parameters
  • id
    Required*
    string
    engine id
    

    Possible values:  1 ≤ length ≤ 1000, Value must match regular expression ^[a-zA-Z0-9\\-]+$
  • curl -X DELETE -H "accept: */*" -H "AuthInstanceId: {instance_id}" "https://{region}.lakehouse.cloud.ibm.com/lakehouse/api/v3/db2_engines/{id}"
Response
Status Code
  • 204
    No Content
    

  • 400
    Error
    

  • 401
    Unauthorized
    

  • 403
    Forbidden
    

  • 404
    Not found
    

  • 500
    Internal server error
    

Example responses
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
Update db2 engine
Update details of db2 engine


PATCH /db2_engines/{id}
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.
  • lakehouse.db2_engine.update
Request
Custom Headers
  • AuthInstanceId
    string
    watsonx.data instance ID
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-\:/]+$
Path Parameters
  • id
    Required*
    string
    engine id
    

    Possible values:  1 ≤ length ≤ 1000, Value must match regular expression ^[a-zA-Z0-9\\-]+$
Request Body
Required*
application/merge-patch+jsonDb2EnginePatch
Update Engine Body


  • curl -X PATCH -H "accept: application/json" -H "AuthInstanceId: {instance_id}" -H "Content-Type: application/merge-patch+json" -d '{ "description": "db2 engine updated description", "display_name": "sampleEngine", "tags": [ "tag1", "tag2" ] }' "https://{region}.lakehouse.cloud.ibm.com/lakehouse/api/v3/db2_engines/{id}"
Response
Response Body
Db2Engine
Db2 engine details


Status Code
  • 200
    Success
    

  • 400
    Error
    

  • 401
    Unauthorized
    

  • 403
    Forbidden
    

  • 404
    Not found
    

  • 500
    Internal server error
    

Example responses
  • {
  "Db2Engine": null,
  "actions": [
    "update",
    "delete"
  ],
  "build_version": "1.0.3.0.0",
  "created_at": 1700322469,
  "created_by": "user@test.com",
  "description": "updated description for db2 engine.",
  "display_name": "db2-engine",
  "engine_details": {
    "connection_string\"": "jdbc:db2://localhost:5480/database",
    "metastore_host": "thrift://mh-connection-string-sample.com"
  },
  "host_name": "xyz-db2-01-db2-svc",
  "id": "db210",
  "origin": "external",
  "port": 3449,
  "status": "REGISTERED",
  "tags": [
    "tag1",
    "tag2"
  ],
  "type": "db2"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
Get list of Netezza engines
Get list of all netezza engines


GET /netezza_engines
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.
  • lakehouse.netezza_engine.list
Request
Custom Headers
  • AuthInstanceId
    string
    watsonx.data instance ID
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-\:/]+$
  • curl -X GET -H "accept: application/json" -H "AuthInstanceId: {instance_id}" "https://{region}.lakehouse.cloud.ibm.com/lakehouse/api/v3/netezza_engines"
Response
Response Body
NetezzaEngineCollection
list Netezza engines


Status Code
  • 200
    Success
    

  • 400
    Error
    

  • 401
    Unauthorized
    

  • 404
    Not found
    

  • 500
    Internal server error
    

Example responses
  • {
  "netezza_engines": [
    {
      "actions": [
        "create"
      ],
      "configuration": {
        "connection_string": "jdbc:netezza://localhost:5480/database",
        "metastore_host": "thrift://mh-connection-string-sample.com"
      },
      "created_at": 1700322469,
      "created_by": "user@test.com",
      "description": "netezza engine for running sql queries",
      "display_name": "netezza",
      "id": "netezza170",
      "origin": "external",
      "status": "REGISTERED",
      "tags": [
        "tag1",
        "tag2"
      ],
      "type": "netezza"
    }
  ]
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
Create netezza engine
Create a new netezza engine


POST /netezza_engines
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.
  • lakehouse.netezza_engine.create
Request
Custom Headers
  • AuthInstanceId
    string
    watsonx.data instance ID
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-\:/]+$
Request Body
Required*
NetezzaEnginePrototype
Create netezza engine body


  • curl -X POST -H "accept: application/json" -H "AuthInstanceId: {instance_id}" -H "Content-Type: application/json" -d '{ "description": "netezza engine description", "engine_details": { "connection_string": "1.2.3.4" }, "display_name": "sampleEngine", "origin": "external", "tags": [ "tag1", "tag2" ], "type": "netezza" }' "https://{region}.lakehouse.cloud.ibm.com/lakehouse/api/v3/netezza_engines"
Response
Response Body
NetezzaEngine
Netezza engine details


Status Code
  • 201
    Success
    

  • 400
    Error
    

  • 401
    Unauthorized
    

  • 403
    Forbidden
    

  • 404
    Not found
    

  • 500
    Internal server error
    

Example responses
  • {
  "actions": [
    "update",
    "delete"
  ],
  "build_version": "1.0.3.0.0",
  "configuration": {
    "connection_string\"": "jdbc:netezza://localhost:5480/database",
    "metastore_host": "thrift://mh-connection-string-sample.com"
  },
  "created_at": 1700322469,
  "created_by": "user@test.com",
  "description": "updated description for netezza engine.",
  "display_name": "sample-netezza-engine",
  "host_name": "xyz-netezza-01-netezza-svc",
  "id": "netezza904",
  "origin": "external",
  "port": 3499,
  "status": "REGISTERED",
  "tags": [
    "tag1",
    "tag2"
  ],
  "type": "netezza"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
Delete netezza engine
Delete a netezza engine


DELETE /netezza_engines/{id}
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.
  • lakehouse.netezza_engine.delete
Request
Custom Headers
  • AuthInstanceId
    string
    watsonx.data instance ID
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-\:/]+$
Path Parameters
  • id
    Required*
    string
    engine id
    

    Possible values:  1 ≤ length ≤ 1000, Value must match regular expression ^[a-zA-Z0-9\\-]+$
  • curl -X DELETE -H "accept: */* " -H "AuthInstanceId: {instance_id}" "https://{region}.lakehouse.cloud.ibm.com/lakehouse/api/v3/netezza_engines/{id}"
Response
Status Code
  • 204
    No Content
    

  • 400
    Error
    

  • 401
    Unauthorized
    

  • 403
    Forbidden
    

  • 404
    Not found
    

  • 500
    Internal server error
    

Example responses
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
Update netezza engine
Update details of netezza engine


PATCH /netezza_engines/{id}
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.
  • lakehouse.netezza_engine.update
Request
Custom Headers
  • AuthInstanceId
    string
    watsonx.data instance ID
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-\:/]+$
Path Parameters
  • id
    Required*
    string
    engine id
    

    Possible values:  1 ≤ length ≤ 1000, Value must match regular expression ^[a-zA-Z0-9\\-]+$
Request Body
Required*
application/merge-patch+jsonNetezzaEnginePatch
Update Engine Body


  • curl -X PATCH -H "accept: application/json" -H "AuthInstanceId: {instance_id}" -H "Content-Type: application/merge-patch+json" -d '{ "description": "netezza engine updated description", "display_name": "sampleEngine", "tags": [ "tag1", "tag2" ] }' "https://{region}.lakehouse.cloud.ibm.com/lakehouse/api/v3/netezza_engines/{id}"
Response
Response Body
NetezzaEngine
Netezza engine details


Status Code
  • 200
    Success
    

  • 400
    Error
    

  • 401
    Unauthorized
    

  • 403
    Forbidden
    

  • 404
    Not found
    

  • 500
    Internal server error
    

Example responses
  • {
  "actions": [
    "update",
    "delete"
  ],
  "build_version": "1.0.3.0.0",
  "configuration": {
    "connection_string\"": "jdbc:netezza://localhost:5480/database",
    "metastore_host": "thrift://mh-connection-string-sample.com"
  },
  "created_at": 1700322469,
  "created_by": "user@test.com",
  "description": "updated description for netezza engine.",
  "display_name": "sample-netezza-engine",
  "host_name": "xyz-netezza-01-netezza-svc",
  "id": "netezza904",
  "origin": "external",
  "port": 3499,
  "status": "REGISTERED",
  "tags": [
    "tag1",
    "tag2"
  ],
  "type": "netezza"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
List all spark engines
List all spark engines


GET /spark_engines
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.
  • lakehouse.spark_engine.list
Request
Custom Headers
  • AuthInstanceId
    string
    watsonx.data instance ID
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-\:/]+$
  • curl -X GET -H "content-type: application/json" -H "AuthInstanceId: {instance_id}" "https://{region}.lakehouse.cloud.ibm.com/lakehouse/api/v3/spark_engines"
Response
Response Body
SparkEngineCollection
Collection of Spark engines.


Status Code
  • 200
    Success
    

  • 400
    Error
    

  • 401
    Unauthorized
    

  • 404
    Not found
    

  • 500
    Internal server error
    

Example responses
  • {
  "spark_engines": [
    {
      "actions": [
        "update",
        "delete"
      ],
      "associated_catalogs": [
        "iceberg_data",
        "hive_data"
      ],
      "configuration": {
        "connection_string": "https://xyz.region.ae.cloud.123.com/v3/analytics_engines/spark_iae_id",
        "endpoints": {
          "applications_api": "$HOST/v4/analytics_engines/<spark_id>/spark_applications/<application_id>",
          "history_server_endpoint": "$HOST/v2/spark/v3/instances/<spark_id>/spark_history_server",
          "spark_access_endpoint": "$HOST/analytics-engine/details/spark-<instance_id>",
          "spark_jobs_v4_endpoint": "$HOST/v4/analytics_engines/<spark_id>/spark_applications",
          "spark_kernel_endpoint": "$HOST/v4/analytics_engines/<spark_id>/jkg/api/kernels",
          "view_history_server": "View history server",
          "wxd_application_endpoint": "$HOST/v1/<wxd_instance_id>/engines/<engine_id>/applications"
        }
      },
      "created_at": 2147483647,
      "created_by": "<username>@<domain>.com",
      "description": "Spark engines for running spark applications",
      "display_name": "sparkEngine",
      "id": "spark123",
      "origin": "discover",
      "status": "REGISTERED",
      "tags": [
        "tag1",
        "tag2"
      ],
      "type": "spark"
    },
    {
      "actions": [
        "update",
        "delete"
      ],
      "associated_catalogs": [
        "iceberg_data",
        "hive_data"
      ],
      "configuration": {
        "default_config": {
          "key1": "value1",
          "key2": "value2",
          "spark.driver.cores": "1",
          "spark.driver.memory": "4G",
          "spark.executor.cores": "1",
          "spark.executor.memory": "4G"
        },
        "default_version": "4.8.3",
        "endpoints": {
          "applications_api": "$HOST/v4/analytics_engines/<spark_id>/spark_applications/<application_id>",
          "history_server_endpoint": "$HOST/v2/spark/v3/instances/<spark_id>/spark_history_server",
          "spark_access_endpoint": "$HOST/analytics-engine/details/spark-<instance_id>",
          "spark_jobs_v4_endpoint": "$HOST/v4/analytics_engines/<spark_id>/spark_applications",
          "spark_kernel_endpoint": "$HOST/v4/analytics_engines/<spark_id>/jkg/api/kernels",
          "view_history_server": "View history server",
          "wxd_application_endpoint": "$HOST/v1/<wxd_instance_id>/engines/<engine_id>/applications"
        },
        "engine_home": {
          "bucket_name": "test-spark-bucket"
        },
        "scale_config": {
          "auto_scale_enabled": true,
          "current_number_of_nodes": 2,
          "maximum_number_of_nodes": 5,
          "minimum_number_of_nodes": 1,
          "node_type": "medium",
          "number_of_nodes": 2
        }
      },
      "created_at": 2147483647,
      "created_by": "<username>@<domain>.com",
      "description": "spark engine for running spark applications",
      "display_name": "sampleEngineNative",
      "id": "sampleEngineNative123",
      "origin": "native",
      "status": "RUNNING",
      "tags": [
        "tag1",
        "tag2"
      ],
      "type": "spark"
    }
  ]
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
Create spark engine
Create a new spark  engine


POST /spark_engines
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.
  • lakehouse.spark_engine.create
Request
Custom Headers
  • AuthInstanceId
    string
    watsonx.data instance ID
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-\:/]+$
Request Body
Required*
SparkEnginePrototype
Create spark engine Body


  • curl -X POST -H "content-type: application/json" -H "accept: application/json" -H "AuthInstanceId: {instance_id}" -d '{ "description": "spark engine description", "configuration": { "api_key": "apikey", "connection_string": "1.2.3.4", "instance_id": "spark-id", "managed_by": "fully/self" }, "display_name": "sampleEngine", "origin": "discover/external", "tags": [ "tag1", "tag2" ], "type": "spark" }' "https://{region}.lakehouse.cloud.ibm.com/lakehouse/api/v3/spark_engines"
Response
Response Body
SparkEngine
Information on the Spark engine.


Status Code
  • 202
    Accepted
    

  • 400
    Error
    

  • 401
    Unauthorized
    

  • 404
    Not found
    

  • 500
    Internal server error
    

Example responses
  • {
  "actions": [],
  "associated_catalogs": [],
  "configuration": {
    "default_version": "3.3",
    "endpoints": {
      "wxd_application_endpoint": "{$HOST}/lakehouse/api/v2/{$INSTANCE_ID}/spark_engines/spark875/applications",
      "wxd_engine_endpoint": "{$HOST}/lakehouse/api/v2/{$INSTANCE_ID}/spark_engines/spark875",
      "wxd_history_server_endpoint": "{$HOST}/lakehouse/api/v2/{$INSTANCE_ID}/spark_engines/spark875/history_server"
    },
    "engine_home": {
      "volume": "cpd-instance::Spark-Volume"
    }
  },
  "created_at": 1709114146,
  "created_by": "cpadmin",
  "description": "",
  "display_name": "native-102",
  "id": "spark875",
  "origin": "native",
  "status": "running",
  "tags": [],
  "type": "spark"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
Get spark engine application details
Get spark engine application details


GET /spark_engines/{engine_id}/applications/{id}
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.
  • lakehouse.spark_engine_application.get
Request
Custom Headers
  • AuthInstanceId
    string
    watsonx.data instance ID
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-\:/]+$
Path Parameters
  • engine_id
    Required*
    string
    engine id
    

    Possible values:  1 ≤ length ≤ 1000, Value must match regular expression ^[a-zA-Z0-9\-]+$
  • id
    Required*
    string
    Application id
    

    Possible values:  1 ≤ length ≤ 1000, Value must match regular expression ^[a-zA-Z0-9\-]+$
  • curl -X GET -H "content-type: application/json" -H "AuthInstanceId: {instance_id}" "https://{region}.lakehouse.cloud.ibm.com/lakehouse/api/v3/spark_engines/{engine_id}/applications/{id}"
Response
Response Body
SparkEngineApplicationResponse
Engine Application Status


Status Code
  • 200
    Success
    

  • 400
    Error
    

  • 401
    Unauthorized
    

  • 404
    Not found
    

  • 500
    Internal server error
    

Example responses
  • {
  "application_details": {
    "application": "s3://mybucket/wordcount.py",
    "archives": "s3://mybucket/myarchive.zip",
    "arguments": [
      "people.txt"
    ],
    "class": "org.apache.spark.examples.SparkPi",
    "conf": {
      "additionalProp1": "key:value"
    },
    "env": {
      "additionalProp1": "ENV_VAR=value"
    },
    "files": "s3://mybucket/myfile.txt",
    "jars": "s3://mybucket/libs/dep1.jar",
    "name": "SparkApplication1",
    "packages": "org.apache.spark:example_1.2.3",
    "repositories": "https://repo1.maven.org/maven2/",
    "spark_version": "3.3"
  }
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
Stop Spark Applications
Stop a running spark application


DELETE /spark_engines/{engine_id}/applications/{id}
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.
  • lakehouse.spark_engine_application.delete
Request
Custom Headers
  • AuthInstanceId
    string
    watsonx.data instance ID
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-\:/]+$
Path Parameters
  • engine_id
    Required*
    string
    engine id
    

    Possible values:  1 ≤ length ≤ 1000, Value must match regular expression ^[a-zA-Z0-9\-]+$
  • id
    Required*
    string
    Application id
    

    Possible values:  1 ≤ length ≤ 1000, Value must match regular expression ^[a-zA-Z0-9\-]+$
  • curl -X DELETE -H "accept: */*" -H "AuthInstanceId: {instance_id}" "https://{region}.lakehouse.cloud.ibm.com/lakehouse/api/v3/spark_engines/{engine_id}/applications/{id}"
Response
Status Code
  • 204
    No Content
    

  • 400
    Error
    

  • 401
    Unauthorized
    

  • 404
    Not found
    

  • 500
    Internal server error
    

Example responses
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
Get spark engine catalog
Get catalog attached to spark engine


GET /spark_engines/{engine_id}/catalogs/{id}
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.
  • lakehouse.spark_engine_catalog.get
Request
Custom Headers
  • AuthInstanceId
    string
    watsonx.data instance ID
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-\:/]+$
Path Parameters
  • engine_id
    Required*
    string
    engine id
    

    Possible values:  1 ≤ length ≤ 1000, Value must match regular expression ^[a-zA-Z0-9\-]+$
  • id
    Required*
    string
    catalog id
    

    Possible values:  1 ≤ length ≤ 1000, Value must match regular expression ^[a-zA-Z0-9\-_]+$
  • curl -X 'GET' 'https://{region}.lakehouse.cloud.ibm.com/lakehouse/api/v3/spark_engines/{engine_id}/catalogs/{id}' -H 'accept: application/json' -H "AuthInstanceId: {instance id}"
Response
Response Body
Catalog
Define the catalog details


Status Code
  • 200
    Success
    

  • 400
    Error
    

  • 401
    Unauthorized
    

  • 404
    Not found
    

  • 500
    Internal server error
    

Example responses
  • {
  "actions": [
    "select",
    "create",
    "update",
    "delete"
  ],
  "associated_databases": [
    "database_1",
    "database_2"
  ],
  "associated_engines": [
    "engine_1",
    "engine_2"
  ],
  "associated_storage": [
    "bucket_1",
    "bucket_2"
  ],
  "base_path": "/abc/def",
  "catalog_sync_metadata": {
    "last_sync_at": "1602839833",
    "sync_description": "Table registration was successful",
    "sync_exception": [
      "Table is corrupted",
      "Table metadata not available"
    ],
    "sync_status": "SUCCESS"
  },
  "created_at": "1602839833",
  "created_by": "user@example.com",
  "days_left": "30",
  "description": "Iceberg catalog description",
  "location_uri": "s3a://testbucket",
  "managed_by": "ibm",
  "mds_connection_information": {
    "hostname": "mds.host.lakehouse.dev",
    "port": "3232"
  },
  "name": "sampleCatalog",
  "rest_uri": "https://samplehost-catalog:4352",
  "status": "running",
  "tags": [
    "tag1",
    "tag2"
  ],
  "thrift_uri": "thrift://samplehost-catalog:4354",
  "type": "iceberg"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
Get spark engine
Get spark engine by ID


GET /spark_engines/{id}
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.
  • lakehouse.spark_engine.get
Request
Custom Headers
  • AuthInstanceId
    string
    watsonx.data instance ID
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-\:/]+$
Path Parameters
  • id
    Required*
    string
    engine id
    

    Possible values:  1 ≤ length ≤ 1000, Value must match regular expression ^[a-zA-Z0-9\-]+$
  • curl -X GET -H "accept: */*" -H "AuthInstanceId: {instance_id}" "https://{region}.lakehouse.cloud.ibm.com/lakehouse/api/v3/spark_engines/{id}"
Response
Response Body
SparkEngine
Information on the Spark engine.


Status Code
  • 200
    Success
    

  • 400
    Error
    

  • 401
    Unauthorized
    

  • 403
    Forbidden
    

  • 404
    Not found
    

  • 500
    Internal server error
    

Example responses
  • {
  "actions": [],
  "associated_catalogs": [],
  "configuration": {
    "default_version": "3.3",
    "endpoints": {
      "wxd_application_endpoint": "{$HOST}/lakehouse/api/v2/{$INSTANCE_ID}/spark_engines/spark875/applications",
      "wxd_engine_endpoint": "{$HOST}/lakehouse/api/v2/{$INSTANCE_ID}/spark_engines/spark875",
      "wxd_history_server_endpoint": "{$HOST}/lakehouse/api/v2/{$INSTANCE_ID}/spark_engines/spark875/history_server"
    },
    "engine_home": {
      "volume": "cpd-instance::Spark-Volume"
    }
  },
  "created_at": 1709114146,
  "created_by": "cpadmin",
  "description": "",
  "display_name": "native-102",
  "id": "spark875",
  "origin": "native",
  "status": "running",
  "tags": [],
  "type": "spark"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
Delete spark engine
Delete a spark engine


DELETE /spark_engines/{id}
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.
  • lakehouse.spark_engine.delete
Request
Custom Headers
  • AuthInstanceId
    string
    watsonx.data instance ID
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-\:/]+$
Path Parameters
  • id
    Required*
    string
    engine id
    

    Possible values:  1 ≤ length ≤ 1000, Value must match regular expression ^[a-zA-Z0-9\-]+$
  • curl -X DELETE -H "accept: */*" -H "AuthInstanceId: {instance_id}" "https://{region}.lakehouse.cloud.ibm.com/lakehouse/api/v3/spark_engines/{id}"
Response
Status Code
  • 204
    No Content
    

  • 400
    Error
    

  • 401
    Unauthorized
    

  • 403
    Forbidden
    

  • 404
    Not found
    

  • 500
    Internal server error
    

Example responses
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
Update spark engine
Update details of spark engine


PATCH /spark_engines/{id}
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.
  • lakehouse.spark_engine.update
Request
Custom Headers
  • AuthInstanceId
    string
    watsonx.data instance ID
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-\:/]+$
Path Parameters
  • id
    Required*
    string
    engine id
    

    Possible values:  1 ≤ length ≤ 1000, Value must match regular expression ^[a-zA-Z0-9\-]+$
Request Body
Required*
application/merge-patch+jsonSparkEnginePatch
Update Engine Body


  • curl -X PATCH -H "content-type: application/json" -H "accept: application/json" -H "AuthInstanceId: {instance_id}" -d '{ "description": "updated description for spark engine", "display_name": "sampleEngine", "tags": [ "tag1", "tag2" ] }' "https://{region}.lakehouse.cloud.ibm.com/lakehouse/api/v3/spark_engines/{id}"
Response
Response Body
SparkEngine
Information on the Spark engine.


Status Code
  • 200
    Success
    

  • 400
    Error
    

  • 401
    Unauthorized
    

  • 403
    Forbidden
    

  • 404
    Not found
    

  • 500
    Internal server error
    

Example responses
  • {
  "actions": [],
  "associated_catalogs": [],
  "configuration": {
    "default_version": "3.3",
    "endpoints": {
      "wxd_application_endpoint": "{$HOST}/lakehouse/api/v2/{$INSTANCE_ID}/spark_engines/spark875/applications",
      "wxd_engine_endpoint": "{$HOST}/lakehouse/api/v2/{$INSTANCE_ID}/spark_engines/spark875",
      "wxd_history_server_endpoint": "{$HOST}/lakehouse/api/v2/{$INSTANCE_ID}/spark_engines/spark875/history_server"
    },
    "engine_home": {
      "volume": "cpd-instance::Spark-Volume"
    }
  },
  "created_at": 1709114146,
  "created_by": "cpadmin",
  "description": "",
  "display_name": "native-102",
  "id": "spark875",
  "origin": "native",
  "status": "running",
  "tags": [],
  "type": "spark"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
List all applications in a spark engine
List all applications in a spark engine


GET /spark_engines/{id}/applications
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.
  • lakehouse.spark_engine_application.list
Request
Custom Headers
  • AuthInstanceId
    string
    watsonx.data instance ID
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-\:/]+$
Path Parameters
  • id
    Required*
    string
    engine id
    

    Possible values:  1 ≤ length ≤ 1000, Value must match regular expression ^[a-zA-Z0-9\-]+$
Query Parameters
  • state
    string[]
    state
    

    Possible values:  1 ≤ number of items ≤ 1000, 1 ≤ length ≤ 100, Value must match regular expression ^[\w\s-]+$
  • submission_time_interval
    string
    Submission time interval in , format
    

    Possible values:  1 ≤ length ≤ 1000, Value must match regular expression ^[a-zA-Z0-9- :,]+$
  • start_time_interval
    string
    Start time interval in , format
    

    Possible values:  1 ≤ length ≤ 1000, Value must match regular expression ^[a-zA-Z0-9- :,]+$
  • end_time_interval
    string
    End time interval in , format
    

    Possible values:  1 ≤ length ≤ 1000, Value must match regular expression ^[a-zA-Z0-9- :,]+$
  • limit
    integer
    limit to specify the rows
    

    Possible values:  1 ≤ value ≤ 1000
    Default: 25
  • start
    string
    Token used to fetch the next or the previous page of the applications list
    

    Possible values:  1 ≤ length ≤ 84, Value must match regular expression ^[A-Za-z0-9_-]+$
  • curl -X GET -H "content-type: application/json" -H "AuthInstanceId: {instance_id}" "https://{region}.lakehouse.cloud.ibm.com/lakehouse/api/v3/spark_engines/{id}/applications"
Response
Response Body
SparkEngineApplicationCollection
Engine Application Detail


Status Code
  • 200
    Success
    

  • 400
    Error
    

  • 401
    Unauthorized
    

  • 404
    Not found
    

  • 500
    Internal server error
    

Example responses
  • {
  "applications": [
    {
      "auto_termination_time": "2023-11-04T15:37:57.775Z",
      "creation_time": "Saturday 28 October 2023 07:17:06.856+0000",
      "deploy_mode": "stand-alone",
      "end_time": "2023-11-01T15:38:07.188Z",
      "failed_time": "Saturday 28 October 2023 07:17:26.649+0000",
      "finish_time": "Saturday 28 October 2023 07:17:38.966+0000",
      "id": "id-ca61-454c-aab3-486d39d8c1d0",
      "runtime": {
        "spark_version": "3.4"
      },
      "spark_application_id": "<spark_application_id>",
      "spark_application_name": "PythonWordCount",
      "spark_ui": "$HOST/v1/1698311655308796/engines/spark817/applications/c7b3fccf-badb-46b0-b1ef-9b3154424021/ui",
      "spark_version": "3.4",
      "start_time": "Saturday 28 October 2023 07:17:26.649+0000",
      "state": "failed",
      "state_details": [
        {
          "code": "s",
          "message": "e",
          "type": "r"
        }
      ],
      "submission_time": "2023-11-01T15:37:30.982Z",
      "template_id": "spark-3.3-jaas-v2-cp4d-template",
      "wxd_application_ui_endpoint": "$HOST/v1/1698311655308796/engines/spark817/applications/c7b3fccf-badb-46b0-b1ef-9b3154424021/ui"
    }
  ],
  "first": {
    "href": "https://example.com/v1/applications?limit=100"
  },
  "limit": 100,
  "next": {
    "href": "https://example.com/v1/applications?limit=100&offset=100"
  }
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
Create spark engine application
Create spark engine application


POST /spark_engines/{id}/applications
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.
  • lakehouse.spark_engine_application.create
Request
Custom Headers
  • AuthInstanceId
    string
    watsonx.data instance ID
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-\:/]+$
Path Parameters
  • id
    Required*
    string
    engine id
    

    Possible values:  1 ≤ length ≤ 1000, Value must match regular expression ^[a-zA-Z0-9\-]+$
Request Body
Required*
SparkEngineApplicationPrototype
Create spark application parameters


  • curl -X POST -H "content-type: application/json" -H "accept: application/json" -H "AuthInstanceId: {instance_id}" -d '{ "application_details": { "application": "s3://mybucket/wordcount.py", "arguments": [ "people.txt" ], "conf": { "additionalProp1": "key:value", "additionalProp2": "key:value", "additionalProp3": "key:value" }, "env": { "additionalProp1": "key:value", "additionalProp2": "key:value", "additionalProp3": "key:value" }, "name": "SparkApplicaton1" }, "job_endpoint": "<host>/v4/analytics_engines/c7b3fccf-badb-46b0-b1ef-9b3154424021/engine_applications", "service_instance_id": "3FGeNUZqcdu6rOFbaHhGBoNdCHj98UoHd6nUFqkfsKhgacYD8ImM6iSA_F-TjHUdEZuVsoQTmOn", "type": "iae" }' "https://{region}.lakehouse.cloud.ibm.com/lakehouse/api/v3/spark_engines/{id}/applications"
Response
Response Body
SparkEngineApplicationSummary
Engine Application Status


Status Code
  • 201
    Success
    

  • 400
    Error
    

  • 401
    Unauthorized
    

  • 404
    Not found
    

  • 500
    Internal server error
    

Example responses
  • {
  "id": "9709ed13-b077-47be-858d-201840180ae2",
  "spark_ui": "",
  "state": "accepted"
}
  • {
  "id": "9709ed13-b077-47be-858d-201840180ae2",
  "spark_version": "4.0.0",
  "state": "accepted",
  "template_id": "spark-4.0-cpwd-wxd-template"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
Get spark engine catalogs
Get list of all catalogs attached to a spark engine


GET /spark_engines/{id}/catalogs
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.
  • lakehouse.spark_engine_catalog.list
Request
Custom Headers
  • AuthInstanceId
    string
    watsonx.data instance ID
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-\:/]+$
Path Parameters
  • id
    Required*
    string
    engine id
    

    Possible values:  1 ≤ length ≤ 1000, Value must match regular expression ^[a-zA-Z0-9\-]+$
  • curl -X 'GET' 'https://{region}.lakehouse.cloud.ibm.com/lakehouse/api/v3/spark_engines/{id}/catalogs' -H 'accept: application/json' -H "AuthInstanceId: {instance id}"
Response
Response Body
CatalogCollection
Collection of catalogs


Status Code
  • 200
    Success
    

  • 400
    Error
    

  • 401
    Unauthorized
    

  • 404
    Not found
    

  • 500
    Internal server error
    

Example responses
  • {
  "catalogs": [
    {
      "actions": [
        "update",
        "delete"
      ],
      "associated_databases": [
        "database_1",
        "database_2"
      ],
      "associated_engines": [
        "engine_1",
        "engine_2"
      ],
      "associated_storage": [
        "bucket_1",
        "bucket_2"
      ],
      "base_path": "/abc/def",
      "catalog_sync_metadata": {
        "last_sync_at": "1765338982",
        "sync_description": "Table registration was successful",
        "sync_exception": [],
        "sync_status": "SUCCESS"
      },
      "created_at": "1765338982",
      "created_by": "<username>@<domain>.com",
      "days_left": "30",
      "description": "Iceberg catalog description",
      "location_uri": "s3a://testbucket",
      "managed_by": "ibm",
      "mds_connection_information": {
        "hostname": "example.example.lakehouse.dev.appdomain.cloud",
        "port": "3232"
      },
      "name": "sampleCatalog",
      "rest_uri": "https://samplehost-catalog:4352",
      "status": "running",
      "tags": [
        "tag1",
        "tag2"
      ],
      "thrift_uri": "thrift://samplehost-catalog:4354",
      "type": "iceberg"
    }
  ]
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
Associate catalogs to spark engine
Associate one or more catalogs to a spark engine


POST /spark_engines/{id}/catalogs
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.
  • lakehouse.spark_engine_catalog.add
Request
Custom Headers
  • AuthInstanceId
    string
    watsonx.data instance ID
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-\:/]+$
Path Parameters
  • id
    Required*
    string
    engine id
    

    Possible values:  1 ≤ length ≤ 1000, Value must match regular expression ^[a-zA-Z0-9\-]+$
Request Body
Required*
CatalogPrototype
Request body


  • curl -X POST 'https://{region}.lakehouse.cloud.ibm.com/lakehouse/api/v3/spark_engines/{id}/catalogs' -H 'accept: application/json' -H 'Content-Type: application/json' -H 'AuthInstanceId: {instance id}' -d '{"catalog_names": ["hive_data"]}'
Response
Response Body
Catalog
Define the catalog details


Status Code
  • 201
    Success
    

  • 400
    Error
    

  • 401
    Unauthorized
    

  • 403
    Forbidden
    

  • 404
    Not found
    

  • 500
    Internal server error
    

Example responses
  • {
  "actions": [
    "select",
    "create",
    "update",
    "delete"
  ],
  "associated_databases": [
    "database_1",
    "database_2"
  ],
  "associated_engines": [
    "engine_1",
    "engine_2"
  ],
  "associated_storage": [
    "bucket_1",
    "bucket_2"
  ],
  "base_path": "/abc/def",
  "catalog_sync_metadata": {
    "last_sync_at": "1602839833",
    "sync_description": "Table registration was successful",
    "sync_exception": [
      "Table is corrupted",
      "Table metadata not available"
    ],
    "sync_status": "SUCCESS"
  },
  "created_at": "1602839833",
  "created_by": "user@example.com",
  "days_left": "30",
  "description": "Iceberg catalog description",
  "location_uri": "s3a://testbucket",
  "managed_by": "ibm",
  "mds_connection_information": {
    "hostname": "mds.host.lakehouse.dev",
    "port": "3232"
  },
  "name": "sampleCatalog",
  "rest_uri": "https://samplehost-catalog:4352",
  "status": "running",
  "tags": [
    "tag1",
    "tag2"
  ],
  "thrift_uri": "thrift://samplehost-catalog:4354",
  "type": "iceberg"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
Disassociate catalogs from a spark engine
Disassociate one or more catalogs from a spark engine


DELETE /spark_engines/{id}/catalogs
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.
  • lakehouse.spark_engine_catalog.remove
Request
Custom Headers
  • AuthInstanceId
    string
    watsonx.data instance ID
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-\:/]+$
Path Parameters
  • id
    Required*
    string
    engine id
    

    Possible values:  1 ≤ length ≤ 1000, Value must match regular expression ^[a-zA-Z0-9\-]+$
Query Parameters
  • catalog_names
    Required*
    string
    Catalog id(s) to be stopped, comma separated
    

    Possible values:  1 ≤ length ≤ 1000, Value must match regular expression ^[a-zA-Z0-9\-_,]+$
  • curl -X 'DELETE' 'https://{region}.lakehouse.cloud.ibm.com/lakehouse/api/v3/spark_engines/{id}/catalogs?catalog_names=catalog_name1' -H 'accept: */*' -H "AuthInstanceId: {instance id}"
Response
Status Code
  • 204
    No Content
    

  • 400
    Error
    

  • 401
    Unauthorized
    

  • 403
    Forbidden
    

  • 404
    Not found
    

  • 500
    Internal server error
    

Example responses
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
Get Spark history server details
Get Spark history server details


GET /spark_engines/{id}/history_server
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.
  • lakehouse.spark_engine_history_server.get
Request
Custom Headers
  • AuthInstanceId
    string
    watsonx.data instance ID
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-\:/]+$
Path Parameters
  • id
    Required*
    string
    engine id
    

    Possible values:  1 ≤ length ≤ 1000, Value must match regular expression ^[a-zA-Z0-9\-]+$
  • curl -X GET -H "content-type: application/json" -H "AuthInstanceId: {instance id}" "https://{region}.lakehouse.cloud.ibm.com/lakehouse/api/v3/spark_engines/{id}/history_server"
Response
Response Body
SparkHistoryServer
Native spark history server


Status Code
  • 200
    Success
    

  • 400
    Error
    

  • 401
    Unauthorized
    

  • 404
    Not found
    

  • 500
    Internal server error
    

Example responses
  • {
  "auto_termination_time": "2022-02-24T07:37:47Z",
  "cores": "1",
  "memory": "4G",
  "start_time": "2022-02-21T07:37:47Z",
  "state": "started"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
Start spark history server
Start spark history server


POST /spark_engines/{id}/history_server
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.
  • lakehouse.spark_engine_history_server.start
Request
Custom Headers
  • AuthInstanceId
    string
    watsonx.data instance ID
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-\:/]+$
Path Parameters
  • id
    Required*
    string
    engine id
    

    Possible values:  1 ≤ length ≤ 1000, Value must match regular expression ^[a-zA-Z0-9\-]+$
Request Body
SparkHistoryServerPrototype
Start history server parameter


  • curl -X POST -H "content-type: application/json" -H "AuthInstanceId: {instance id}" "https://{region}.lakehouse.cloud.ibm.com/lakehouse/api/v3/spark_engines/{id}/history_server"
Response
Response Body
SparkHistoryServer
Native spark history server


Status Code
  • 201
    Success
    

  • 400
    Error
    

  • 401
    Unauthorized
    

  • 404
    Not found
    

  • 500
    Internal server error
    

Example responses
  • {
  "auto_termination_time": "2022-02-24T07:37:47Z",
  "cores": "1",
  "memory": "4G",
  "start_time": "2022-02-21T07:37:47Z",
  "state": "started"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
Stop spark history server
Stop spark history server


DELETE /spark_engines/{id}/history_server
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.
  • lakehouse.spark_engine_history_server.stop
Request
Custom Headers
  • AuthInstanceId
    string
    watsonx.data instance ID
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-\:/]+$
Path Parameters
  • id
    Required*
    string
    engine id
    

    Possible values:  1 ≤ length ≤ 1000, Value must match regular expression ^[a-zA-Z0-9\-]+$
  • curl -X DELETE -H "content-type: application/json" -H "AuthInstanceId: {instance id}" "https://{region}.lakehouse.cloud.ibm.com/lakehouse/api/v3/spark_engines/{id}/history_server"
Response
Status Code
  • 204
    No Content
    

  • 400
    Error
    

  • 401
    Unauthorized
    

  • 404
    Not found
    

  • 500
    Internal server error
    

Example responses
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
Pause engine
Pause engine. this feature is only available in SAAS


POST /spark_engines/{id}/pause
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.
  • lakehouse.spark_engine.pause
Request
Custom Headers
  • AuthInstanceId
    string
    watsonx.data instance ID
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-\:/]+$
Path Parameters
  • id
    Required*
    string
    engine id
    

    Possible values:  1 ≤ length ≤ 1000, Value must match regular expression ^[a-zA-Z0-9\-]+$
Request Body
PauseSparkEnginePrototype
Pause spark engine parameters


  • curl -X POST -H "content-type: application/json" -H "AuthInstanceId: {instance id}" -d '{"force": true}' "https://{region}.lakehouse.cloud.ibm.com/lakehouse/api/v3/spark_engines/{id}/pause"
Response
Response Body
SuccessResponse
Response of success


Status Code
  • 200
    Success
    

  • 400
    Error
    

  • 401
    Unauthorized
    

  • 404
    Not found
    

  • 500
    Internal server error
    

Example responses
  • {
  "message": "pause spark engine",
  "message_code": "success"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
Resume engine. This feature is only available in SAAS
Resume engine. This feature is only available in SAAS


POST /spark_engines/{id}/resume
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.
  • lakehouse.spark_engine.resume
Request
Custom Headers
  • AuthInstanceId
    string
    watsonx.data instance ID
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-\:/]+$
Path Parameters
  • id
    Required*
    string
    engine id
    

    Possible values:  1 ≤ length ≤ 1000, Value must match regular expression ^[a-zA-Z0-9\-]+$
  • curl -X POST -H "content-type: application/json" -H "AuthInstanceId: {instance id}" "https://{region}.lakehouse.cloud.ibm.com/lakehouse/api/v3/spark_engines/{id}/resume"
Response
Response Body
SuccessResponse
Response of success


Status Code
  • 200
    Success
    

  • 400
    Error
    

  • 401
    Unauthorized
    

  • 404
    Not found
    

  • 500
    Internal server error
    

Example responses
  • {
  "message": "resume spark engine",
  "message_code": "success"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
Scale engine. This feature is only available in SAAS
Scale engine. This feature is only available in SAAS


POST /spark_engines/{id}/scale
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.
  • lakehouse.spark_engine.scale
Request
Custom Headers
  • AuthInstanceId
    string
    watsonx.data instance ID
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-\:/]+$
Path Parameters
  • id
    Required*
    string
    engine id
    

    Possible values:  1 ≤ length ≤ 1000, Value must match regular expression ^[a-zA-Z0-9\-]+$
Request Body
Required*
SparkEngineScalePrototype
Scale spark application parameters


  • curl -X POST -H "content-type: application/json" -H "AuthInstanceId: {instance id}" "https://{region}.lakehouse.cloud.ibm.com/lakehouse/api/v3/spark_engines/{id}/scale"-d '{  "number_of_nodes": 2}'
Response
Response Body
SuccessResponse
Response of success


Status Code
  • 202
    Success
    

  • 400
    Error
    

  • 401
    Unauthorized
    

  • 404
    Not found
    

  • 500
    Internal server error
    

Example responses
  • {
  "message": "scale spark engine",
  "message_code": "success"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
List all registered catalogs
List all registered catalogs


GET /catalogs
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.
  • lakehouse.catalog.list
Request
Custom Headers
  • AuthInstanceId
    string
    watsonx.data instance ID
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-\:/]+$
  • Secret
    string
    API Authentication service token
    

    Possible values:  1 ≤ length ≤ 1000, Value must match regular expression ^[a-zA-Z0-9\-_]+$
Query Parameters
  • default_catalogs
    boolean
    Default catalogs flag for cornerstone feature
    

    Default: false
  • view
    string
    Internal view parameter for cornerstone feature
    

    Possible values:  0 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-_]+$
  • curl -X 'GET' 'https://{region}.lakehouse.cloud.ibm.com/lakehouse/api/v3/catalogs' 'https://{region}.lakehouse.cloud.ibm.com/lakehouse/api/v3/catalogs' -H 'accept: application/json' -H 'AuthInstanceId: {instance_id}'
Response
Response Body
CatalogCollection
Collection of catalogs


Status Code
  • 200
    Success
    

  • 400
    Error
    

  • 401
    Unauthorized
    

  • 404
    Not found
    

  • 500
    Internal server error
    

Example responses
  • {
  "catalogs": [
    {
      "actions": [
        "update",
        "delete"
      ],
      "associated_databases": [
        "database_1",
        "database_2"
      ],
      "associated_engines": [
        "engine_1",
        "engine_2"
      ],
      "associated_storage": [
        "bucket_1",
        "bucket_2"
      ],
      "base_path": "/abc/def",
      "catalog_sync_metadata": {
        "last_sync_at": "1765338982",
        "sync_description": "Table registration was successful",
        "sync_exception": [],
        "sync_status": "SUCCESS"
      },
      "created_at": "1765338982",
      "created_by": "<username>@<domain>.com",
      "days_left": "30",
      "description": "Iceberg catalog description",
      "location_uri": "s3a://testbucket",
      "managed_by": "ibm",
      "mds_connection_information": {
        "hostname": "example.example.lakehouse.dev.appdomain.cloud",
        "port": "3232"
      },
      "name": "sampleCatalog",
      "rest_uri": "https://samplehost-catalog:4352",
      "status": "running",
      "tags": [
        "tag1",
        "tag2"
      ],
      "thrift_uri": "thrift://samplehost-catalog:4354",
      "type": "iceberg"
    }
  ]
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
External Iceberg table registration
Synchronize the external Iceberg table registration for a catalog identified by catalog_id.


POST /catalogs/{id}/sync
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.
  • lakehouse.catalog_sync.update
Request
Custom Headers
  • AuthInstanceId
    string
    watsonx.data instance ID
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-\:/]+$
Path Parameters
  • id
    Required*
    string
    catalog ID
    

    Possible values:  1 ≤ length ≤ 1000, Value must match regular expression ^[a-zA-Z0-9\-_]+$
Request Body
Required*
application/merge-patch+jsonSyncPrototype
Request body


  • curl -X 'POST' 'https://{region}.lakehouse.cloud.ibm.com/lakehouse/api/v3/catalogs/{id}/sync' -H 'accept: application/json' -H 'AuthInstanceId: {instance_id}' -H 'Content-Type: application/merge-patch+json' -d '{ 
  "auto_add_new_tables": true, 
  "sync_iceberg_md": true 
  "sync_existing_tables": true 
  "register_new_tables": true 
}'
Response
Response Body
SuccessResponsePrototype
success response prototype


Status Code
  • 200
    Success
    

  • 400
    Error
    

  • 401
    Unauthorized
    

  • 404
    Not found
    

  • 500
    Internal server error
    

Example responses
  • {
  "response": {
    "message": "Rollback to a table snapshot",
    "message_code": "success"
  }
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
Get catalog properties by catalog_id
Get catalog properties of a catalog identified by catalog_id


GET /catalogs/{name}
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.
  • lakehouse.catalog.get
Request
Custom Headers
  • AuthInstanceId
    string
    watsonx.data instance ID
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-\:/]+$
Path Parameters
  • name
    Required*
    string
    catalog name
    

    Possible values:  1 ≤ length ≤ 1000, Value must match regular expression ^[a-zA-Z0-9\-_]+$
  • curl -X 'GET' 'https://{region}.lakehouse.cloud.ibm.com/lakehouse/api/v3/catalogs/{name}' -H 'accept: application/json' -H 'AuthInstanceId: {instance_id}'
Response
Response Body
Catalog
Define the catalog details


Status Code
  • 200
    Success
    

  • 400
    Error
    

  • 401
    Unauthorized
    

  • 404
    Not found
    

  • 500
    Internal server error
    

Example responses
  • {
  "actions": [
    "select",
    "create",
    "update",
    "delete"
  ],
  "associated_databases": [
    "database_1",
    "database_2"
  ],
  "associated_engines": [
    "engine_1",
    "engine_2"
  ],
  "associated_storage": [
    "bucket_1",
    "bucket_2"
  ],
  "base_path": "/abc/def",
  "catalog_sync_metadata": {
    "last_sync_at": "1602839833",
    "sync_description": "Table registration was successful",
    "sync_exception": [
      "Table is corrupted",
      "Table metadata not available"
    ],
    "sync_status": "SUCCESS"
  },
  "created_at": "1602839833",
  "created_by": "user@example.com",
  "days_left": "30",
  "description": "Iceberg catalog description",
  "location_uri": "s3a://testbucket",
  "managed_by": "ibm",
  "mds_connection_information": {
    "hostname": "mds.host.lakehouse.dev",
    "port": "3232"
  },
  "name": "sampleCatalog",
  "rest_uri": "https://samplehost-catalog:4352",
  "status": "running",
  "tags": [
    "tag1",
    "tag2"
  ],
  "thrift_uri": "thrift://samplehost-catalog:4354",
  "type": "iceberg"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
Delete catalog catalog_id
Delete catalog identified by catalog_id


DELETE /catalogs/{name}
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.
  • lakehouse.catalog.delete
Request
Custom Headers
  • AuthInstanceId
    string
    watsonx.data instance ID
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-\:/]+$
Path Parameters
  • name
    Required*
    string
    catalog name
    

    Possible values:  1 ≤ length ≤ 1000, Value must match regular expression ^[a-zA-Z0-9\-_]+$
Query Parameters
  • skip_mds_call
    boolean
    Skip MDS call when Unity catalog is added
    

    Default: false
  • curl -X 'DELETE' 'https://{region}.lakehouse.cloud.ibm.com/lakehouse/api/v3/catalogs/{catalog_id}' -H 'accept: application/json' -H 'AuthInstanceId: {instance_id}'
Response
Status Code
  • 204
    No Content
    

  • 400
    Error
    

  • 401
    Unauthorized
    

  • 404
    Not found
    

  • 500
    Internal server error
    

Example responses
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
List all tables
List all tables in a schema in a catalog for a given engine


GET /catalogs/{catalog_name}/schemas/{schema_name}/tables
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.
  • lakehouse.table.list
Request
Custom Headers
  • AuthInstanceId
    string
    watsonx.data instance ID
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-\:/]+$
Path Parameters
  • catalog_name
    Required*
    string
    catalog name
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-_]+$
  • schema_name
    Required*
    string
    URL encoded schema name
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-_!@#%&_=\]}<> ]+$
Query Parameters
  • engine_id
    Required*
    string
    Engine id of presto/prestissimo/spark/db2/netezza other engine
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-]+$
  • curl -X 'GET' 'https://{region}.lakehouse.cloud.ibm.com/lakehouse/api/v3/catalogs/{catalog_name}/schemas/{schema_name}/tables?engine_id={engine_id}' -H 'accept: application/json' -H 'AuthInstanceId: {instance_id}'
Response
Response Body
TableCollection
tables list


Status Code
  • 200
    Success
    

  • 400
    Error
    

  • 401
    Unauthorized
    

  • 404
    Not found
    

  • 500
    Internal server error
    

Example responses
  • {
  "tables": [
    "customer-data",
    "user-data"
  ]
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
Get table details
Get details of a given table in a catalog and schema


GET /catalogs/{catalog_name}/schemas/{schema_name}/tables/{table_name}
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.
  • lakehouse.table.get
Request
Custom Headers
  • AuthInstanceId
    string
    watsonx.data instance ID
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-\:/]+$
Path Parameters
  • catalog_name
    Required*
    string
    catalog name
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-_]+$
  • schema_name
    Required*
    string
    URL encoded schema name
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9~!@#$%^&*()_+=\[\]{}|;':\"`,./<>?\\=:\- ]*$
  • table_name
    Required*
    string
    URL encoded table name
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9~!@#$%^&*()_+=\[\]{}|;':\"`,./<>?\\=:\- ]*$
Query Parameters
  • engine_id
    Required*
    string
    Engine id of presto/prestissimo/spark/db2/netezza other engine
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-]+$
  • type
    string
    URL encoded table type (view,base table)
    

    Possible values:  1 ≤ length ≤ 10, Value must match regular expression ^[a-zA-Z0-9\-_ ]+$
  • curl -X 'GET' 'https://{region}.lakehouse.cloud.ibm.com/lakehouse/api/v3/catalogs/{catalog_name}/schemas/{schema_name}/tables/{table_name}?engine_id={engine_id}' -H 'accept: application/json' -H 'AuthInstanceId: {instance_id}'
Response
Response Body
Table
Table details


Status Code
  • 200
    Success
    

  • 400
    Error
    

  • 401
    Unauthorized
    

  • 404
    Not found
    

  • 500
    Internal server error
    

Example responses
  • {
  "columns": [
    {
      "column_name": "expenses",
      "comment": "expenses column",
      "extra": "varchar",
      "type": "varchar"
    }
  ],
  "name": "newtable"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
Delete table
Delete table for a given schema and catalog


DELETE /catalogs/{catalog_name}/schemas/{schema_name}/tables/{table_name}
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.
  • lakehouse.table.delete
Request
Custom Headers
  • AuthInstanceId
    string
    watsonx.data instance ID
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-\:/]+$
Path Parameters
  • catalog_name
    Required*
    string
    catalog name
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-_]+$
  • schema_name
    Required*
    string
    URL encoded schema name
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9~!@#$%^&*()_+=\[\]{}|;':\"`,./<>?\\=:\- ]*$
  • table_name
    Required*
    string
    URL encoded table name
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9~!@#$%^&*()_+=\[\]{}|;':\"`,./<>?\\=:\- ]*$
Query Parameters
  • engine_id
    Required*
    string
    Engine id of presto/prestissimo/spark/db2/netezza other engine
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-]+$
  • type
    string
    URL encoded table type (view,base table)
    

    Possible values:  1 ≤ length ≤ 10, Value must match regular expression ^[a-zA-Z0-9\-_ ]+$
  • curl -X 'DELETE' 'https://{region}.lakehouse.cloud.ibm.com/lakehouse/api/v3/catalogs/{catalog_name}/schemas/{schema_name}/tables/{table_name}?engine_id={engine_id}&type={type}' -H 'accept: */*' -H 'AuthInstanceId: {instance_id}'
Response
Status Code
  • 204
    No Content
    

  • 400
    Error
    

  • 401
    Unauthorized
    

  • 404
    Not found
    

  • 500
    Internal server error
    

Example responses
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
Rename table
Rename table


PATCH /catalogs/{catalog_name}/schemas/{schema_name}/tables/{table_name}
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.
  • lakehouse.table.update
Request
Custom Headers
  • AuthInstanceId
    string
    watsonx.data instance ID
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-\:/]+$
Path Parameters
  • catalog_name
    Required*
    string
    catalog name
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-_]+$
  • schema_name
    Required*
    string
    URL encoded schema name
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9~!@#$%^&*()_+=\[\]{}|;':\"`,./<>?\\=:\- ]*$
  • table_name
    Required*
    string
    URL encoded table name
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9~!@#$%^&*()_+=\[\]{}|;':\"`,./<>?\\=:\- ]*$
Query Parameters
  • engine_id
    Required*
    string
    Engine id of presto/prestissimo/spark/db2/netezza other engine
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-]+$
  • type
    string
    URL encoded table type (view,base table)
    

    Possible values:  1 ≤ length ≤ 10, Value must match regular expression ^[a-zA-Z0-9\-_ ]+$
Request Body
Required*
application/merge-patch+jsonTablePatch
Request body


  • curl -X 'PATCH' 'https://{region}.lakehouse.cloud.ibm.com/lakehouse/api/v3/catalogs/{catalog_name}/schemas/{schema_name}/tables/{table_name}?engine_id={engine_id}' -H 'accept: application/json' -H 'AuthInstanceId: {instance_id}' -H 'Content-Type: application/merge-patch+json' -d '{ 
  "new_table_name": "updated_table_name", 
}'
Response
Response Body
Table
Table details


Status Code
  • 200
    Success
    

  • 400
    Error
    

  • 401
    Unauthorized
    

  • 404
    Not found
    

  • 500
    Internal server error
    

Example responses
  • {
  "columns": [
    {
      "column_name": "expenses",
      "comment": "expenses column",
      "extra": "varchar",
      "type": "varchar"
    }
  ],
  "name": "newtable"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
Rollback snapshot
Rollback table to snapshot


POST /catalogs/{catalog_name}/schemas/{schema_name}/tables/{table_name}/rollback
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.
  • lakehouse.table_rollback.set
Request
Custom Headers
  • AuthInstanceId
    string
    watsonx.data instance ID
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-\:/]+$
Path Parameters
  • catalog_name
    Required*
    string
    Catalog name
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-_]+$
  • schema_name
    Required*
    string
    Schema name
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9~!@#$%^&*()_+=\[\]{}|;':\"`,./<>?\\=:\- ]*$
  • table_name
    Required*
    string
    Table name
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9~!@#$%^&*()_+=\[\]{}|;':\"`,./<>?\\=:\- ]*$
Query Parameters
  • engine_id
    Required*
    string
    Engine id
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-]+$
Request Body
Required*
RollbackPrototype
Request body


  • curl -X 'POST' 'https://{region}.lakehouse.cloud.ibm.com/lakehouse/api/v3/catalogs/{catalog_name}/schemas/{schema_name}/tables/{table_name}/rollback?engine_id={engine_id}' -H 'accept: application/json' -d '{ "snapshot_id": "snapsshot_id", }' -H 'AuthInstanceId: {instance_id}'
Response
Response Body
SuccessResponsePrototype
success response prototype


Status Code
  • 201
    Success
    

  • 400
    Error
    

  • 401
    Unauthorized
    

  • 404
    Not found
    

  • 500
    Internal server error
    

Example responses
  • {
  "response": {
    "message": "Rollback to a table snapshot",
    "message_code": "success"
  }
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
Get table snapshots
List all table snapshots


GET /catalogs/{catalog_name}/schemas/{schema_name}/tables/{table_name}/snapshots
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.
  • lakehouse.table_snapshot.list
Request
Custom Headers
  • AuthInstanceId
    string
    watsonx.data instance ID
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-\:/]+$
Path Parameters
  • catalog_name
    Required*
    string
    Catalog name
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-_]+$
  • schema_name
    Required*
    string
    Schema name
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9~!@#$%^&*()_+=\[\]{}|;':\"`,./<>?\\=:\- ]*$
  • table_name
    Required*
    string
    Table name
    

    Possible values:  1 ≤ length ≤ 1024, Value must match regular expression ^[a-zA-Z0-9~!@#$%^&*()_+=\[\]{}|;':\"`,./<>?\\=:\- ]*$
Query Parameters
  • engine_id
    Required*
    string
    Engine name
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-]+$
  • curl -X 'GET' 'https://{region}.lakehouse.cloud.ibm.com/lakehouse/api/v3/catalogs/{catalog_name}/schemas/{schema_name}/tables/{table_name}/snapshots?engine_id={engine_id}' -H 'accept: application/json' -H 'AuthInstanceId: {instance_id}'
Response
Response Body
TableSnapshotCollection
Collection of tablesnapshots


Status Code
  • 200
    Success
    

  • 400
    Error
    

  • 401
    Unauthorized
    

  • 404
    Not found
    

  • 500
    Internal server error
    

Example responses
  • {
  "snapshots": [
    {
      "committed_at": "2025-01-29T08:36:21.717Z",
      "operation": "alter",
      "snapshot_id": "2332342122211222",
      "summary": {}
    }
  ]
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
Delete schema
Delete a schema


DELETE /catalogs/{catalog_name}/schemas/{schema_name}
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.
  • lakehouse.schema.delete
Request
Custom Headers
  • AuthInstanceId
    string
    watsonx.data instance ID
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-\:/]+$
Path Parameters
  • catalog_name
    Required*
    string
    Catalog name
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-_]+$
  • schema_name
    Required*
    string
    URL encoded Schema name
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9~!@#$%^&*()_+=\[\]{}|;':\"`,./<>?\\=:\- ]*$
Query Parameters
  • engine_id
    Required*
    string
    Engine id of presto/prestissimo/spark/db2/netezza other engine
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-_]+$
  • curl -X 'DELETE' 'https://{region}.lakehouse.cloud.ibm.com/lakehouse/api/v3/catalogs/{catalog_name}/schemas/{schema_name}?engine_id={engine_id}' -H 'accept: */*' -H 'AuthInstanceId: {instance_id}'
Response
Status Code
  • 204
    No Content
    

  • 400
    Error
    

  • 401
    Unauthorized
    

  • 404
    Not found
    

  • 500
    Internal server error
    

Example responses
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
List all schemas
List all schemas in catalog


GET /catalogs/{id}/schemas
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.
  • lakehouse.schema.list
Request
Custom Headers
  • AuthInstanceId
    string
    watsonx.data instance ID
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-\:/]+$
Path Parameters
  • id
    Required*
    string
    Catalog id
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-_]+$
Query Parameters
  • engine_id
    Required*
    string
    Engine id
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-_]+$
  • curl -X 'GET' 'https://{region}.lakehouse.cloud.ibm.com/lakehouse/api/v3/catalogs/{id}/schemas?engine_id={engine_id}' -H 'accept: application/json' -H 'AuthInstanceId: {instance_id}'
Response
Response Body
SchemasCollection
Collection of schemas


Status Code
  • 200
    Success
    

  • 400
    Error
    

  • 401
    Unauthorized
    

  • 404
    Not found
    

  • 500
    Internal server error
    

Example responses
  • {
  "schemas": [
    "schema1",
    "schema2"
  ]
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
Create schema
Create a new schema


POST /catalogs/{id}/schemas
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.
  • lakehouse.schema.create
Request
Custom Headers
  • AuthInstanceId
    string
    watsonx.data instance ID
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-\:/]+$
Path Parameters
  • id
    Required*
    string
    Catalog id
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-_]+$
Query Parameters
  • engine_id
    Required*
    string
    Engine id
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-_]+$
Request Body
Required*
SchemaPrototype
Request body


Examples:  
{
  "bucket_name": "sample-bucket",
  "custom_path": "sample-path",
  "hostname": "hdfs://example-host:9000",
  "name": "SampleSchema1",
  "port": 4553
}
  • curl -X 'POST' 'https://{region}.lakehouse.cloud.ibm.com/lakehouse/api/v3/catalogs/{id}/schemas?engine_id={engine_id}' -H 'accept: application/json' -H 'AuthInstanceId: {instance_id}' -H 'Content-Type: application/json' -d '{
  "bucket_name": "sample-bucket", 
  "custom_path": "sample-path", 
  "schema_name": "SampleSchema1" 
}'
Response
Response Body
SchemaPrototype
Schema creation request details


Status Code
  • 201
    Success
    

  • 400
    Error
    

  • 401
    Unauthorized
    

  • 404
    Not found
    

  • 500
    Internal server error
    

Example responses
  • {
  "bucket_name": "sample-bucket",
  "custom_path": "sample-path",
  "hostname": "hdfs://example-host:9000",
  "name": "SampleSchema1",
  "port": 4553
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
List all columns of a table
List all columns of a table in a given a schema for a given catalog


GET /catalogs/{catalog_name}/schemas/{schema_name}/tables/{table_name}/columns
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.
  • lakehouse.column.list
Request
Custom Headers
  • AuthInstanceId
    string
    watsonx.data instance ID
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-\:/]+$
Path Parameters
  • catalog_name
    Required*
    string
    catalog name
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9_\-]+$
  • schema_name
    Required*
    string
    URL encoded schema name
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-_!@#%&_=\]}<> ]+$
  • table_name
    Required*
    string
    URL encoded table name
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-%_]+$
Query Parameters
  • engine_id
    Required*
    string
    engine id
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-]+$
  • curl -X 'GET' 'https://{region}.lakehouse.cloud.ibm.com/lakehouse/api/v3/catalogs/{catalog_name}/schemas/{schema_name}/tables/{table_name}/columns?engine_id={engine_id}' -H 'accept: application/json' -H 'AuthInstanceId: {instance_id}'
Response
Response Body
ColumnCollection
collection of columns in a table


Status Code
  • 200
    Success
    

  • 400
    Error
    

  • 401
    Unauthorized
    

  • 404
    Not found
    

  • 500
    Internal server error
    

Example responses
  • {
  "columns": [
    {
      "column_name": "customer_data",
      "comment": "customer_data column",
      "extra": "varchar",
      "type": "varchar"
    },
    {
      "column_name": "user_data",
      "comment": "user_data column",
      "extra": "varchar",
      "type": "varchar"
    }
  ]
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
Add column(s)
Add one or multiple columns to a table in a schema for a given catalog


POST /catalogs/{catalog_name}/schemas/{schema_name}/tables/{table_name}/columns
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.
  • lakehouse.column.create
Request
Custom Headers
  • AuthInstanceId
    string
    watsonx.data instance ID
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-\:/]+$
Path Parameters
  • catalog_name
    Required*
    string
    catalog name
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9_\-]+$
  • schema_name
    Required*
    string
    URL encoded schema name
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-_!@#%&_=\]}<> ]+$
  • table_name
    Required*
    string
    URL encoded table name
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-%_]+$
Query Parameters
  • engine_id
    Required*
    string
    engine id
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-]+$
Request Body
Required*
ColumnPrototype
Request body


Examples:  
{
  "columns": [
    {
      "column_name": "expenses",
      "comment": "expenses column",
      "extra": "varchar",
      "type": "varchar"
    }
  ]
}
  • curl -X 'POST' 'https://{region}.lakehouse.cloud.ibm.com/lakehouse/api/v3/catalogs/{catalog_name}/schemas/{schema_name}/tables/{table_name}/columns?engine_id={engine_id}' -H 'accept: application/json' -H 'AuthInstanceId: {instance_id}' -H 'Content-Type: application/json' -d '{
  "bucket_name": "sample-bucket", 
  "custom_path": "sample-path", 
  "schema_name": "SampleSchema1" 
}'
Response
Response Body
ColumnCollection
collection of columns in a table


Status Code
  • 201
    Success
    

  • 400
    Error
    

  • 401
    Unauthorized
    

  • 404
    Not found
    

  • 500
    Internal server error
    

Example responses
  • {
  "columns": [
    {
      "column_name": "customer_data",
      "comment": "customer_data column",
      "extra": "varchar",
      "type": "varchar"
    },
    {
      "column_name": "user_data",
      "comment": "user_data column",
      "extra": "varchar",
      "type": "varchar"
    }
  ]
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
Delete column
Delete column in a table for a given schema and catalog


DELETE /catalogs/{catalog_name}/schemas/{schema_name}/tables/{table_name}/columns/{column_name}
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.
  • lakehouse.column.delete
Request
Custom Headers
  • AuthInstanceId
    string
    watsonx.data instance ID
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-\:/]+$
Path Parameters
  • catalog_name
    Required*
    string
    catalog name
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-_]+$
  • schema_name
    Required*
    string
    URL encoded schema name
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-_!@#%&_=\]}<> ]+$
  • table_name
    Required*
    string
    URL encoded schema name
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-%_]+$
  • column_name
    Required*
    string
    Url encoded column name
    

    Possible values:  1 ≤ length ≤ 1024, Value must match regular expression ^[a-zA-Z0-9\[\]!@#%&()_\-=\{\},<>:]+$
Query Parameters
  • engine_id
    Required*
    string
    engine id
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-]+$
  • curl -X 'DELETE' 'https://{region}.lakehouse.cloud.ibm.com/lakehouse/api/v3/catalogs/{catalog_name}/schemas/{schema_name}/tables/{table_name}/columns/{column_name}?engine_id={engine_id}' -H 'accept: */*' -H 'AuthInstanceId: {instance_id}'
Response
Status Code
  • 204
    No Content
    

  • 400
    Error
    

  • 401
    Unauthorized
    

  • 404
    Not found
    

  • 500
    Internal server error
    

Example responses
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
Alter column
Update the given column - rename column


PATCH /catalogs/{catalog_name}/schemas/{schema_name}/tables/{table_name}/columns/{column_name}
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.
  • lakehouse.column.update
Request
Custom Headers
  • AuthInstanceId
    string
    watsonx.data instance ID
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-\:/]+$
Path Parameters
  • catalog_name
    Required*
    string
    catalog name
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-_]+$
  • schema_name
    Required*
    string
    URL encoded schema name
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-_!@#%&_=\]}<> ]+$
  • table_name
    Required*
    string
    URL encoded schema name
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-%_]+$
  • column_name
    Required*
    string
    Url encoded column name
    

    Possible values:  1 ≤ length ≤ 1024, Value must match regular expression ^[a-zA-Z0-9\[\]!@#%&()_\-=\{\},<>:]+$
Query Parameters
  • engine_id
    Required*
    string
    engine id
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-]+$
Request Body
Required*
application/merge-patch+jsonColumnPatch
Request body


Examples:  
{
  "new_column_name": "expenses"
}
  • curl -X 'PATCH' 'https://{region}.lakehouse.cloud.ibm.com/lakehouse/api/v3/catalogs/{catalog_name}/schemas/{schema_name}/tables/{table_name}/columns/{column_name}?engine_id={engine_id}' -H 'accept: application/json' -H 'AuthInstanceId: {instance_id}' -H 'Content-Type: application/merge-patch+json' -d '{\n  "column_name": "expenses"\n}'
Response
Response Body
Column
Column details


Status Code
  • 200
    Success
    

  • 400
    Error
    

  • 401
    Unauthorized
    

  • 404
    Not found
    

  • 500
    Internal server error
    

Example responses
  • {
  "column_name": "expenses",
  "comment": "expenses column",
  "extra": "varchar",
  "type": "varchar"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
List ingestion jobs
Get list of ingestion jobs.


GET /ingestion/jobs
Request
Custom Headers
  • AuthInstanceId
    Required*
    string
    Lakehouse Instance ID
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-\:/]+$
Query Parameters
  • start
    string
    Page offset
    

    Possible values:  1 ≤ length ≤ 500, Value must match regular expression ^(0|[1-9][0-9]*)$
  • limit
    int32
    Page size
    

    Possible values:  -1 ≤ value ≤ 100
    Default: 10
Response
Response Body
IngestionJobCollection
Paged result for Ingestion Jobs


Status Code
  • 200
    Ok
    

  • 400
    Bad Request
    

  • 401
    Unauthorized
    

  • 403
    Forbidden
    

  • 404
    Not Found
    

  • 500
    Internal Server Error
    

Example responses
  • {
  "offset": 0,
  "limit": 10,
  "total_count": 100,
  "next": {
    "href": "https://api.example.com/v1/ingestion/jobs?limit=50&token=2b6067d0-8d50-49d9-8cd6-23223d3f24e0"
  },
  "jobs": [
    {}
  ]
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
Submit a Spark ingestion job
Submit a Spark ingestion job with the provided source and target details.


POST /ingestion/jobs
Request
Custom Headers
  • AuthInstanceId
    Required*
    string
    Lakehouse Instance ID
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-\:/]+$
Request Body
Required*
IngestionJobPrototype
Input parameters for submitting a lite Spark ingestion job.


Response
Response Body
IngestionJob
Ingestion job


Status Code
  • 201
    Ingestion job submitted successfully
    

  • 400
    Bad Request
    

  • 401
    Unauthorized
    

  • 403
    Forbidden
    

  • 404
    Not Found
    

  • 500
    Internal server error
    

Example responses
  • {
  "application_id": "1956d96f-805a-4ddf-a230-b767964895a0",
  "engine_id": "spark604",
  "engine_name": "spark",
  "instance_id": "1111111111",
  "job_id": "ingestion-12345678",
  "start_timestamp": "2025-05-04T15:27:51.523Z",
  "status": "starting",
  "target_table": "catalog_name.schema_name.table_name"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
Get ingestion job by ID
Get ingestion job by ID.


GET /ingestion/jobs/{id}
Request
Custom Headers
  • AuthInstanceId
    Required*
    string
    Lakehouse Instance ID
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-\:/]+$
Path Parameters
  • id
    Required*
    string
    Ingestion Job ID
    

    Possible values:  1 ≤ length ≤ 1024, Value must match regular expression ^[a-zA-Z0-9\-_.@]+$
Response
Response Body
IngestionJob
Ingestion job


Status Code
  • 200
    Ok
    

  • 400
    Bad Request
    

  • 401
    Unauthorized
    

  • 403
    Forbidden
    

  • 404
    Not Found
    

  • 500
    Internal Server Error
    

Example responses
  • {
  "application_id": "c36115dc-a9e2-489e-a846-710106c1115a",
  "details": "Ingestion-Parameters:",
  "end_timestamp": "2025-05-04T15:27:51.523Z",
  "engine_id": "spark220",
  "instance_id": "1746348510473722",
  "is_new_schema": false,
  "is_new_table": false,
  "job_id": "ingestion-1747665516617",
  "source_data_files": "s3://example_bucket/wxd-local-ingestion/95/1mb_file.csv.gz",
  "start_timestamp": "2025-05-04T15:27:51.523Z",
  "status": "completed",
  "target_table": "iceberg_data.testSchema.testTable",
  "username": "admin"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
Get databases
Get list of databases


GET /database_registrations
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.
  • lakehouse.database_registration.list
Request
Custom Headers
  • AuthInstanceId
    string
    watsonx.data instance ID
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-\:/]+$
  • curl -X GET -H "accept: application/json" -H "AuthInstanceId: {instance_id}" "https://{region}.lakehouse.cloud.ibm.com/lakehouse/api/v3/database_registrations"
Response
Response Body
DatabaseRegistrationCollection
Database registrations collection


Status Code
  • 200
    Success
    

  • 400
    Error
    

  • 401
    Unauthorized
    

  • 404
    Not found
    

  • 500
    Internal server error
    

Example responses
  • {
  "database_registrations": [
    {
      "actions": [
        "update",
        "delete"
      ],
      "associated_catalog": {
        "catalog_name": "hive_data",
        "catalog_tags": [
          "catalog_tag_1",
          "catalog_tag_2"
        ],
        "catalog_type": "hive"
      },
      "connection": {
        "database_name": "new_database",
        "hostname": "netezza://ps.fyre.com",
        "password": "samplepassword",
        "port": 4353,
        "sasl_mechanism": "plain",
        "ssl": true,
        "tables": "netezza_table_name",
        "username": "sampleuser"
      },
      "created_at": "1686792721",
      "created_by": "user1@bim.com",
      "description": "Description of the external database",
      "display_name": "new_database",
      "id": "netezza23",
      "properties": [
        {
          "encrypt": true,
          "key": "abc",
          "value": "xyz"
        }
      ],
      "tables": [
        {
          "created_at": "1686792721",
          "file_contents": "qweerty",
          "file_name": "test.json",
          "schema_name": "testschema123",
          "table_name": "customer"
        }
      ],
      "tags": [
        "testdatabase",
        "userdatabase"
      ],
      "topics": [
        {
          "created_at": "1686792721",
          "file_contents": "qweerty",
          "file_name": "test.json",
          "topic_name": "customer"
        }
      ],
      "type": "netezza"
    }
  ]
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
Add/Create database
Add or create a new database


POST /database_registrations
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.
  • lakehouse.database_registration.create
Request
Custom Headers
  • AuthInstanceId
    string
    watsonx.data instance ID
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-\:/]+$
Request Body
Required*
DatabaseRegistrationPrototype
Request body


  • curl -X POST -H "accept: application/json" -H "AuthInstanceId: {instance_id}" -H "Content-Type: application/json" -d '{
  "display_name": "BLUDB",
  "properties": [],
  "description": "",
  "tags": [],
  "type": "db2",
  "connection": {
    "name": "BLUDB",
    "hostname": "db2w-pxuepuj.us-south.db2w.cloud.ibm.com",
    "port": 50001,
    "username": "username",
    "password": "password",
    "ssl": true,
    "certificate": "certificate    "certificate_extension": "pem"
  },
  "associated_catalog": {
    "catalog_name": "db2_automation"
  }
}' "https://{region}.lakehouse.cloud.ibm.com/lakehouse/api/v3/database_registrations"
Response
Response Body
DatabaseRegistration
Database registration object


Status Code
  • 201
    Success
    

  • 400
    Error
    

  • 401
    Unauthorized
    

  • 404
    Not found
    

  • 500
    Internal server error
    

Example responses
  • {
  "actions": [
    "update",
    "delete"
  ],
  "associated_catalog": {
    "catalog_name": "iceberg_data",
    "catalog_tags": [
      "tag1",
      "tag2"
    ],
    "catalog_type": "iceberg"
  },
  "connection": {
    "database_name": "new_database",
    "hostname": "netezza://abc.efg.com",
    "password": "samplepassword",
    "port": 4353,
    "ssl": true,
    "tables": "netezza_table_name",
    "username": "sampleuser"
  },
  "created_at": "1686792721",
  "created_by": "user1@bim.com",
  "description": "Description of the database",
  "display_name": "new_database",
  "id": "netezza123",
  "properties": [
    {
      "encrypt": true,
      "key": "abc",
      "value": "xyz"
    }
  ],
  "tables": [
    {
      "created_at": "1686792721",
      "file_contents": "qweerty",
      "file_name": "test.json",
      "schema_name": "testschema123",
      "table_name": "customer"
    }
  ],
  "tags": [
    "testdatabase",
    "userdatabase"
  ],
  "topics": [
    {
      "created_at": "1686792721",
      "file_contents": "qweerty",
      "file_name": "test.json",
      "topic_name": "customer"
    }
  ],
  "type": "netezza"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
Post database catalog
Add catalog to a registered database


POST /database_registrations/{database_id}/catalogs
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.
  • lakehouse.catalog.create
Request
Custom Headers
  • AuthInstanceId
    string
    watsonx.data instance ID
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-\:/]+$
Path Parameters
  • database_id
    Required*
    string
    database id
    

    Possible values:  1 ≤ length ≤ 1000, Value must match regular expression ^[a-zA-Z0-9\\-]+$
Request Body
Required*
DatabaseCatalogName
Request body


Examples:  
{
  "catalog_name": "iceberg_catalog"
}
  • curl -X POST -H "accept: application/json" -H "AuthInstanceId: {instance_id}" "https://{region}.lakehouse.cloud.ibm.com/lakehouse/api/v3/database_registrations/{database_id}/catalogs"
Response
Response Body
SuccessResponse
Response of success


Status Code
  • 201
    Success
    

  • 400
    Error
    

  • 401
    Unauthorized
    

  • 404
    Not found
    

  • 500
    Internal server error
    

Example responses
  • {
  "message": "Successful message",
  "message_code": "success"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
Get database
Get a registered databases


GET /database_registrations/{id}
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.
  • lakehouse.database_registration.get
Request
Custom Headers
  • AuthInstanceId
    string
    watsonx.data instance ID
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-\:/]+$
Path Parameters
  • id
    Required*
    string
    database id
    

    Possible values:  1 ≤ length ≤ 1000, Value must match regular expression ^[a-zA-Z0-9\\-]+$
  • curl -X GET -H "accept: application/json" -H "AuthInstanceId: {instance_id}" "https://{region}.lakehouse.cloud.ibm.com/lakehouse/api/v3/database_registrations/{id}"
Response
Response Body
DatabaseRegistration
Database registration object


Status Code
  • 200
    Success
    

  • 400
    Error
    

  • 401
    Unauthorized
    

  • 404
    Not found
    

  • 500
    Internal server error
    

Example responses
  • {
  "actions": [
    "update",
    "delete"
  ],
  "associated_catalog": {
    "catalog_name": "iceberg_data",
    "catalog_tags": [
      "tag1",
      "tag2"
    ],
    "catalog_type": "iceberg"
  },
  "connection": {
    "database_name": "new_database",
    "hostname": "netezza://abc.efg.com",
    "password": "samplepassword",
    "port": 4353,
    "ssl": true,
    "tables": "netezza_table_name",
    "username": "sampleuser"
  },
  "created_at": "1686792721",
  "created_by": "user1@bim.com",
  "description": "Description of the database",
  "display_name": "new_database",
  "id": "netezza123",
  "properties": [
    {
      "encrypt": true,
      "key": "abc",
      "value": "xyz"
    }
  ],
  "tables": [
    {
      "created_at": "1686792721",
      "file_contents": "qweerty",
      "file_name": "test.json",
      "schema_name": "testschema123",
      "table_name": "customer"
    }
  ],
  "tags": [
    "testdatabase",
    "userdatabase"
  ],
  "topics": [
    {
      "created_at": "1686792721",
      "file_contents": "qweerty",
      "file_name": "test.json",
      "topic_name": "customer"
    }
  ],
  "type": "netezza"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
Delete database
Delete a database


DELETE /database_registrations/{id}
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.
  • lakehouse.database_registration.delete
Request
Custom Headers
  • AuthInstanceId
    string
    watsonx.data instance ID
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-\:/]+$
Path Parameters
  • id
    Required*
    string
    database id
    

    Possible values:  1 ≤ length ≤ 1000, Value must match regular expression ^[a-zA-Z0-9\\-]+$
  • curl -X DELETE -H "accept: */*" -H "AuthInstanceId: {instance_id}" "https://{region}.lakehouse.cloud.ibm.com/lakehouse/api/v3/database_registrations/{id}"
Response
Status Code
  • 204
    No Content
    

  • 400
    Error
    

  • 401
    Unauthorized
    

  • 404
    Not found
    

  • 500
    Internal server error
    

Example responses
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
Update database
Update database details


PATCH /database_registrations/{id}
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.
  • lakehouse.database_registration.update
Request
Custom Headers
  • AuthInstanceId
    string
    watsonx.data instance ID
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-\:/]+$
Path Parameters
  • id
    Required*
    string
    database id
    

    Possible values:  1 ≤ length ≤ 1000, Value must match regular expression ^[a-zA-Z0-9\\-]+$
Request Body
Required*
application/merge-patch+jsonDatabaseRegistrationPatch
Request body


  • curl -X PATCH -H "accept: application/json" -H "AuthInstanceId: {instance_id}" -H "Content-Type: application/merge-patch+json" -d '{ "connection": { "password": "samplepassword", "username": "sampleuser" }, "display_name": "new_database", "description": "External database description", "tags": [ "testdatabase", "userdatabase" ] }' "https://{region}.lakehouse.cloud.ibm.com/lakehouse/api/v3/database_registrations/{id}"
Response
Response Body
DatabaseRegistration
Database registration object


Status Code
  • 200
    Success
    

  • 400
    Error
    

  • 401
    Unauthorized
    

  • 404
    Not found
    

  • 500
    Internal server error
    

Example responses
  • {
  "actions": [
    "update",
    "delete"
  ],
  "associated_catalog": {
    "catalog_name": "iceberg_data",
    "catalog_tags": [
      "tag1",
      "tag2"
    ],
    "catalog_type": "iceberg"
  },
  "connection": {
    "database_name": "new_database",
    "hostname": "netezza://abc.efg.com",
    "password": "samplepassword",
    "port": 4353,
    "ssl": true,
    "tables": "netezza_table_name",
    "username": "sampleuser"
  },
  "created_at": "1686792721",
  "created_by": "user1@bim.com",
  "description": "Description of the database",
  "display_name": "new_database",
  "id": "netezza123",
  "properties": [
    {
      "encrypt": true,
      "key": "abc",
      "value": "xyz"
    }
  ],
  "tables": [
    {
      "created_at": "1686792721",
      "file_contents": "qweerty",
      "file_name": "test.json",
      "schema_name": "testschema123",
      "table_name": "customer"
    }
  ],
  "tags": [
    "testdatabase",
    "userdatabase"
  ],
  "topics": [
    {
      "created_at": "1686792721",
      "file_contents": "qweerty",
      "file_name": "test.json",
      "topic_name": "customer"
    }
  ],
  "type": "netezza"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
List other engines
list all other engine details


GET /other_engines
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.
  • lakehouse.other_engine.list
Request
Custom Headers
  • AuthInstanceId
    string
    watsonx.data instance ID
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-\:/]+$
  • curl -X GET -H "content-type: application/json" -H "AuthInstanceId: {instance_id}" "https://{region}.lakehouse.cloud.ibm.com/lakehouse/api/v3/other_engines"
Response
Response Body
OtherEngineCollection
list other engines


Status Code
  • 200
    Success
    

  • 400
    Error
    

  • 401
    Unauthorized
    

  • 404
    Not found
    

  • 500
    Internal server error
    

Example responses
  • {
  "other_engines": [
    {
      "actions": [
        "create",
        "update"
      ],
      "configuration": {
        "connection_string": "https://other-connection-string-sample.com",
        "type": "netezza"
      },
      "created_at": 1234567890,
      "created_by": "<username>@<domain>.com",
      "description": "other engine for running queries",
      "display_name": "sampleEngine",
      "id": "sampleEngine123",
      "origin": "external",
      "status": "registered",
      "tags": [
        "tag1",
        "tag2"
      ],
      "type": "other"
    }
  ]
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
Create other engine
Create a new engine


POST /other_engines
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.
  • lakehouse.other_engine.create
Request
Custom Headers
  • AuthInstanceId
    string
    watsonx.data instance ID
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-\:/]+$
Request Body
Required*
OtherEnginePrototype
Create other Engine Body


  • curl -X POST -H "content-type: application/json" -H "accept: application/json" -H "AuthInstanceId: {instance_id}" -d '{ "description": "external engine description", "engine_details": { "connection_string": "1.2.3.4", "engine_type": "netezza", "metastore_host": "1.2.3.4" }, "display_name": "sampleEngine01", "tags": [ "tag1", "tag2" ] }' "https://{region}.lakehouse.cloud.ibm.com/lakehouse/api/v3/other_engines"
Response
Response Body
OtherEngine
external engine details


Status Code
  • 201
    Success
    

  • 400
    Error
    

  • 401
    Unauthorized
    

  • 404
    Not found
    

  • 500
    Internal server error
    

Example responses
  • {
  "actions": [
    "update",
    "delete"
  ],
  "configuration": {
    "connection_string": "1.2.3.4",
    "type": "netezza"
  },
  "created_at": 1234567890,
  "created_by": "<username>@<domain>.com",
  "description": "other engine for running sql queries",
  "display_name": "sampleEngine",
  "host_name": "xyz-netezza-01-netezza-svc",
  "id": "sampleEngine123",
  "origin": "external",
  "port": 1243,
  "status": "registered",
  "tags": [
    "tag1",
    "tag2"
  ],
  "type": "other"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
Delete engine
Delete an engine from lakehouse


DELETE /other_engines/{id}
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.
  • lakehouse.other_engine.delete
Request
Custom Headers
  • AuthInstanceId
    string
    watsonx.data instance ID
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-\:/]+$
Path Parameters
  • id
    Required*
    string
    engine id
    

    Possible values:  1 ≤ length ≤ 1000, Value must match regular expression ^[a-zA-Z0-9\-]+$
  • curl -X DELETE -H "accept: */*" -H "AuthInstanceId: {instance_id}" "https://{region}.lakehouse.cloud.ibm.com/lakehouse/api/v3/other_engines/{id}"
Response
Status Code
  • 204
    No Content
    

  • 400
    Error
    

  • 401
    Unauthorized
    

  • 404
    Not found
    

  • 500
    Internal server error
    

Example responses
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
Register delta and hudi tables
Register delta and hudi tables


POST /catalogs/{catalog_id}/schemas/{schema_id}/register
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.
  • lakehouse.table.register
Request
Custom Headers
  • AuthInstanceId
    string
    watsonx.data instance ID
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-\:/]+$
Path Parameters
  • catalog_id
    Required*
    string
    catalog id
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-_]+$
  • schema_id
    Required*
    string
    URL encoded schema name
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-_!@#%&_=\]}<> ]+$
Request Body
Required*
RegisterTableBody
Request body


  • curl -X 'POST' 'https://{region}.lakehouse.cloud.ibm.com/lakehouse/api/v3/catalogs/{catalog_id}/schemas/{schema_id}/register' -H 'accept: application/json' -H 'AuthInstanceId: {instance_id}' -H 'Content-Type: application/merge-patch+json' -d '{ 
  "table_name": "table1", 
  "metadata_location": "s3a://bucketname/path/to/table/metadata_location/_delta_log" 
}'
Response
Response Body
RegisterTableCreatedBody
Register table


Status Code
  • 201
    Success
    

  • 400
    Error
    

  • 401
    Unauthorized
    

  • 404
    Not found
    

  • 500
    Internal server error
    

Example responses
  • {
  "response": {
    "message": "Register table success",
    "message_code": "success"
  }
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
Load delta and hudi tables metadata
Load delta and hudi tables metadata


GET /catalogs/{catalog_id}/schemas/{schema_id}/tables/{table_id}/metadata
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.
  • lakehouse.table.load
Request
Custom Headers
  • AuthInstanceId
    string
    watsonx.data instance ID
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-\:/]+$
Path Parameters
  • catalog_id
    Required*
    string
    catalog id
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-_]+$
  • schema_id
    Required*
    string
    URL encoded schema name
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-_!@#%&_=\]}<> ]+$
  • table_id
    Required*
    string
    URL encoded table name
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-%_]+$
  • curl -X 'GET' 'https://{region}.lakehouse.cloud.ibm.com/lakehouse/api/v3/catalogs/{catalog_id}/schemas/{schema_id}/tables/{table_id}/metadata' -H 'accept: application/json' -H 'AuthInstanceId: {instance_id}' 
Response
Response Body
LoadTableResponse
Load table metadata


Status Code
  • 200
    Success
    

  • 400
    Error
    

  • 401
    Unauthorized
    

  • 404
    Not found
    

  • 500
    Internal server error
    

Example responses
  • {
  "metadata_location": "s3a://test/spark-hudi-warehouse/hudi/spark_hudi_table1/.hoodie",
  "table_path": "s3a://test/spark-hudi-warehouse/hudi/spark_hudi_table1"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
To validate an integration
To validate an integration


POST /integration_validation
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.
  • lakehouse.integration_validation.evaluate
Request
Custom Headers
  • AuthInstanceId
    string
    watsonx.data instance ID
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-\:/]+$
Request Body
Required*
ValidateIntegrationPrototype
Integration validation parameters


Response
Response Body
ValidateIntegration
Validate Integration prototype


Status Code
  • 200
    Success
    

  • 400
    Error
    

  • 401
    Unauthorized
    

  • 404
    Not found
    

  • 500
    Internal Server Error
    

Example responses
  • {
  "message": "Integration credentials validated successfully",
  "message_code": "Success",
  "resources": [
    {
      "name": "test01",
      "type": "presto"
    }
  ]
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
Get all existing Integrations
Get all existing Integrations


GET /integrations
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.
  • lakehouse.integration.listall
Request
Custom Headers
  • AuthInstanceId
    string
    watsonx.data instance ID
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-\:/]+$
  • Secret
    string
    API Authentication service token
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-_]+$
Query Parameters
  • type
    string[]
    type
    

    Possible values:  0 ≤ number of items ≤ 2, 0 ≤ length ≤ 100, Value must match regular expression ^[a-zA-Z0-9~!@#$%^&*()_+=\[\]{}|;':\"`,./<>?\\=:\- ]*$
  • state
    string[]
    state
    

    Possible values:  0 ≤ number of items ≤ 2, 0 ≤ length ≤ 100, Value must match regular expression ^[a-zA-Z0-9~!@#$%^&*()_+=\[\]{}|;':\"`,./<>?\\=:\- ]*$
Response
Response Body
IntegrationCollection
list all existing integrations


Status Code
  • 200
    Success
    

  • 400
    Error
    

  • 401
    Unauthorized
    

  • 404
    Not found
    

  • 500
    Internal server error
    

Example responses
  • {
  "integrations": [
    {
      "config_properties": "ikc-env.password=ibmlhenc__0001__uMkFATDDZNnxJ7z6BA/QqA==\\\\nikc-env.url=ikc\\\\nikc-username=\\\\nikc-enabled-catalogs=\\\\nlh-unique-identifier=1711796957622126\\\\nlh-crn=1711796957622126",
      "governance_properties": "query-governance.name=external",
      "id": "ikc543",
      "modified_at": 1716878292,
      "modified_by": "admin",
      "state": "active",
      "storage_catalogs": {
        "catalog_names": [
          "iceberg_data",
          "hive_data"
        ]
      },
      "type": "ikc",
      "url": "ikc.url",
      "username": "admin"
    },
    {
      "enable_data_policy_within_wxd": true,
      "id": "ranger743",
      "modified_at": 1716878292,
      "modified_by": "admin",
      "resource": "presto-01",
      "state": "active",
      "type": "ranger",
      "url": "http://lh-ranger.fyre.ibm.com:7080/",
      "username": "admin"
    }
  ]
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
To register an integration
To register an integration


POST /integrations
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.
  • lakehouse.integration.create
Request
Custom Headers
  • AuthInstanceId
    string
    watsonx.data instance ID
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-\:/]+$
Request Body
Required*
IntegrationPrototype
Integration registration parameters


Response
Response Body
Integration
Response body for the POST/GET/PATCH Request for an integration in watsonx.Data


Status Code
  • 201
    Success
    

  • 400
    Error
    

  • 401
    Unauthorized
    

  • 404
    Not found
    

  • 500
    Internal server error
    

Example responses
  • {
  "auth_url": "https://iam.abc.com",
  "config_properties": "ikc-env.password=ibmlhenc__0001__uMkFATDDZNnxJ7z6BA/QqA==\\\\nikc-env.url=ikc\\\\nikc-username=\\\\nikc-enabled-catalogs=\\\\nlh-unique-identifier=1711796957622126\\\\nlh-crn=1711796957622126",
  "cross_account_integration": true,
  "enable_data_policy_within_wxd": true,
  "governance_properties": "query-governance.name=external",
  "id": "ranger743",
  "ikc_user_account_id": "abcdefghijklmnopqrstuvwxyz",
  "manta_url": "https://abcd.com/gov_lineage/v2/lineage_events/openlineage",
  "modified_at": 1716878292,
  "modified_by": "admin",
  "resource": "presto-01",
  "state": "active",
  "storage_catalogs": {
    "catalog_names": [
      "iceberg_data",
      "hive_data"
    ]
  },
  "type": "ranger",
  "url": "http://lh-ranger.fyre.ibm.com:7080/",
  "username": "admin"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
Get an Integration
Get an Integration


GET /integrations/{id}
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.
  • lakehouse.integration.get
Request
Custom Headers
  • AuthInstanceId
    string
    watsonx.data instance ID
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-\:/]+$
Path Parameters
  • id
    Required*
    string
    Unique id to identigy the integration
    

    Possible values:  1 ≤ length ≤ 1000, Value must match regular expression ^[a-z0-9]+$
Response
Response Body
Integration
Response body for the POST/GET/PATCH Request for an integration in watsonx.Data


Status Code
  • 200
    Success
    

  • 400
    Error
    

  • 401
    Unauthorized
    

  • 404
    Not found
    

  • 500
    Internal server error
    

Example responses
  • {
  "auth_url": "https://iam.abc.com",
  "config_properties": "ikc-env.password=ibmlhenc__0001__uMkFATDDZNnxJ7z6BA/QqA==\\\\nikc-env.url=ikc\\\\nikc-username=\\\\nikc-enabled-catalogs=\\\\nlh-unique-identifier=1711796957622126\\\\nlh-crn=1711796957622126",
  "cross_account_integration": true,
  "enable_data_policy_within_wxd": true,
  "governance_properties": "query-governance.name=external",
  "id": "ranger743",
  "ikc_user_account_id": "abcdefghijklmnopqrstuvwxyz",
  "manta_url": "https://abcd.com/gov_lineage/v2/lineage_events/openlineage",
  "modified_at": 1716878292,
  "modified_by": "admin",
  "resource": "presto-01",
  "state": "active",
  "storage_catalogs": {
    "catalog_names": [
      "iceberg_data",
      "hive_data"
    ]
  },
  "type": "ranger",
  "url": "http://lh-ranger.fyre.ibm.com:7080/",
  "username": "admin"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
Remove an Integration
Remove an Integration


DELETE /integrations/{id}
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.
  • lakehouse.integration.delete
Request
Custom Headers
  • AuthInstanceId
    string
    watsonx.data instance ID
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-\:/]+$
Path Parameters
  • id
    Required*
    string
    Unique id to identigy the integration
    

    Possible values:  1 ≤ length ≤ 1000, Value must match regular expression ^[a-z0-9]+$
Response
Status Code
  • 204
    No Content
    

  • 400
    Error
    

  • 401
    Unauthorized
    

  • 404
    Not found
    

  • 500
    Internal server error
    

Example responses
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
Update an existing Integration
Update an existing Integration


PATCH /integrations/{id}
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.
  • lakehouse.integration.update
Request
Custom Headers
  • AuthInstanceId
    string
    watsonx.data instance ID
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-\:/]+$
  • Secret
    string
    API Authentication service token
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-_]+$
Path Parameters
  • id
    Required*
    string
    Unique id to identigy the integration
    

    Possible values:  1 ≤ length ≤ 1000, Value must match regular expression ^[a-z0-9]+$
Request Body
Required*
application/merge-patch+jsonIntegrationPatch
Integration update parameters


Response
Response Body
Integration
Response body for the POST/GET/PATCH Request for an integration in watsonx.Data


Status Code
  • 200
    Success
    

  • 400
    Error
    

  • 401
    Unauthorized
    

  • 404
    Not found
    

  • 500
    Internal server error
    

Example responses
  • {
  "auth_url": "https://iam.abc.com",
  "config_properties": "ikc-env.password=ibmlhenc__0001__uMkFATDDZNnxJ7z6BA/QqA==\\\\nikc-env.url=ikc\\\\nikc-username=\\\\nikc-enabled-catalogs=\\\\nlh-unique-identifier=1711796957622126\\\\nlh-crn=1711796957622126",
  "cross_account_integration": true,
  "enable_data_policy_within_wxd": true,
  "governance_properties": "query-governance.name=external",
  "id": "ranger743",
  "ikc_user_account_id": "abcdefghijklmnopqrstuvwxyz",
  "manta_url": "https://abcd.com/gov_lineage/v2/lineage_events/openlineage",
  "modified_at": 1716878292,
  "modified_by": "admin",
  "resource": "presto-01",
  "state": "active",
  "storage_catalogs": {
    "catalog_names": [
      "iceberg_data",
      "hive_data"
    ]
  },
  "type": "ranger",
  "url": "http://lh-ranger.fyre.ibm.com:7080/",
  "username": "admin"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
Get semantic automation layer Integration of the instance
Get basic details of the semantic automation layer(SAL) integration with IBM Knowledge Catalog(IKC)


GET /sal_integration
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.
  • lakehouse.sal_integration.get
Request
Custom Headers
  • AuthInstanceId
    string
    watsonx.data instance ID
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-\:/]+$
  • curl -X GET -H "accept: application/json" -H "AuthInstanceId: {instance_id}" "https://{region}.lakehouse.cloud.ibm.com/lakehouse/api/v3/sal_integration"
Response
Response Body
SalIntegration
Basic Semantic Automation Layer(SAL) integration settings


Status Code
  • 200
    Success
    

  • 400
    Error
    

  • 401
    Unauthorized
    

  • 404
    Not found
    

  • 500
    Internal server error
    

Example responses
  • {
  "category_id": "10e64285-bf37-4d5d-b759-bc6a46589234",
  "engine_id": "presto-01",
  "errors": [],
  "instance_id": "18b49d7a-9519-4539-8db5-ff080623c226",
  "status": "active",
  "storage_resource_crn": "crn:v1:staging:public:cloud-object-storage:global:a/04e9bc47612523rr19ac22759cb69bebd:asd23df-6ada-45ff-bfe8-4343222",
  "storage_type": "bmcos_object_storage",
  "timestamp": "1715056266",
  "trial_plan": false
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
Create semantic automation layer integration with IBM Knowledge Catalog
Create semantic automation layer integration(SAL) with IBM Knowledge Catalog(IKC)


POST /sal_integration
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.
  • lakehouse.sal_integration.create
Request
Custom Headers
  • AuthInstanceId
    string
    watsonx.data instance ID
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-\:/]+$
Request Body
Required*
SalIntegrationPrototype
Request body


Response
Response Body
SalIntegration
Basic Semantic Automation Layer(SAL) integration settings


Status Code
  • 201
    Success
    

  • 400
    Error
    

  • 401
    Unauthorized
    

  • 404
    Not found
    

  • 500
    Internal server error
    

Example responses
  • {
  "category_id": "10e64285-bf37-4d5d-b759-bc6a46589234",
  "engine_id": "presto-01",
  "errors": [],
  "instance_id": "18b49d7a-9519-4539-8db5-ff080623c226",
  "status": "active",
  "storage_resource_crn": "crn:v1:staging:public:cloud-object-storage:global:a/04e9bc47612523rr19ac22759cb69bebd:asd23df-6ada-45ff-bfe8-4343222",
  "storage_type": "bmcos_object_storage",
  "timestamp": "1715056266",
  "trial_plan": false
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
Delete Semantic Automation Layer(SAL) integration
Remove Semantic automation layer integration


DELETE /sal_integration
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.
  • lakehouse.sal_integration.delete
Request
No Request Parameters
This method does not accept any request parameters.
Response
Status Code
  • 204
    No Content
    

  • 400
    Error
    

  • 401
    Unauthorized
    

  • 404
    Not found
    

  • 500
    Internal server error
    

Example responses
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
Patch Semantic automation layer integration
Update Semantic automation layer(SAL) integration properties


PATCH /sal_integration
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.
  • lakehouse.sal_integration.update
Request
Custom Headers
  • AuthInstanceId
    string
    watsonx.data instance ID
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-\:/]+$
Request Body
Required*
application/merge-patch+jsonSalIntegrationPatch
Request body


Response
Response Body
SalIntegration
Basic Semantic Automation Layer(SAL) integration settings


Status Code
  • 200
    Success
    

  • 400
    Error
    

  • 401
    Unauthorized
    

  • 404
    Not found
    

  • 500
    Internal server error
    

Example responses
  • {
  "category_id": "10e64285-bf37-4d5d-b759-bc6a46589234",
  "engine_id": "presto-01",
  "errors": [],
  "instance_id": "18b49d7a-9519-4539-8db5-ff080623c226",
  "status": "active",
  "storage_resource_crn": "crn:v1:staging:public:cloud-object-storage:global:a/04e9bc47612523rr19ac22759cb69bebd:asd23df-6ada-45ff-bfe8-4343222",
  "storage_type": "bmcos_object_storage",
  "timestamp": "1715056266",
  "trial_plan": false
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
create enrichment jobs of schema(or tables in schema)
create enrichment job of schemas, notifing the schema(tables) changes to IBM Knowledge Catalog(IKC) and kick off an import and metadata enrichment job


POST /sal_integration/enrichment
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.
  • lakehouse.sal_integration_enrichment.create
Request
Custom Headers
  • AuthInstanceId
    string
    watsonx.data instance ID
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-\:/]+$
Request Body
Required*
SalEnrichmentPrototype
Request body


Response
Status Code
  • 204
    No Content
    

  • 400
    Error
    

  • 401
    Unauthorized
    

  • 404
    Not found
    

  • 500
    Internal server error
    

Example responses
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
List semantic enriched data_assets in IBM Knowledge catalog
List semantic enrichment data_assets(enriched tables) associated with the schema by IBM Knowledge Catalog project id, which can be fetched from /sal_integration/mappings


GET /sal_integration/enrichment/data_assets
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.
  • lakehouse.sal_integration_enrichment_assets.list
Request
Custom Headers
  • AuthInstanceId
    string
    watsonx.data instance ID
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-\:/]+$
Query Parameters
  • project_id
    Required*
    string
    project id of enriched schema in IBM Knowledge Catalog
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-]+$
Response
Response Body
SalEnrichmentDataAssetCollection
Collection if SAL enriched assets in IKC


Status Code
  • 200
    Success
    

  • 400
    Error
    

  • 401
    Unauthorized
    

  • 404
    Not found
    

  • 500
    Internal server error
    

Example responses
  • {
  "data_assets": [
    {
      "attributes": [
        "data_asset",
        "discovered_asset",
        "metadata_enrichment_info"
      ],
      "id": "ee0383b9-dcab-4c1a-b03d-bf521837b6ed",
      "name": "newtable",
      "resource_key": "0000:0000:0000:0000:0000:FFFF:9EB0:04E2|31134|:/iceberg_data/new_schema/sampletable",
      "schema_name": "sampleschema"
    },
    {
      "attributes": [
        "data_asset",
        "processed_asset",
        "metadata_enrichment_info"
      ],
      "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
      "name": "another_table",
      "resource_key": "0000:0000:0000:0000:0000:FFFF:1234:5678|4321|:/iceberg_data/sample_schema/another_table",
      "schema_name": "anotherschema"
    }
  ]
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
Get semantic enrichment data_asset associated with the table
Get semantic enrichment data_asset associated with the table by IBM Knowledge Catalog project id and asset id, which can be retrived by /sal_integration/enrichement/data_assets


GET /sal_integration/enrichment/data_assets/{id}
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.
  • lakehouse.sal_integration_enrichment_assets_by_id.get
Request
Custom Headers
  • AuthInstanceId
    string
    watsonx.data instance ID
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-\:/]+$
Path Parameters
  • id
    Required*
    string
    enrichment data asset id in IBM Knowledge Catalog
    

    Possible values:  1 ≤ length ≤ 10000, Value must match regular expression ^[a-zA-Z0-9\-]+$
Query Parameters
  • project_id
    Required*
    string
    enrichment project id in IBM Knowledge Catalog
    

    Possible values:  1 ≤ length ≤ 10000, Value must match regular expression ^[a-zA-Z0-9\-]+$
Response
Response Body
SalEnrichmentDataAsset
SAL encrichmed asset in IKC associated with table in Watsonx.data


Status Code
  • 200
    Success
    

  • 400
    Error
    

  • 401
    Unauthorized
    

  • 404
    Not found
    

  • 500
    Internal server error
    

Example responses
  • {
  "attributes": [
    "data_asset",
    "discovered_asset",
    "metadata_enrichment_info"
  ],
  "id": "ee0383b9-dcab-4c1a-b03d-bf521837b6ed",
  "name": "newtable",
  "resource_key": "0000:0000:0000:0000:0000:FFFF:9EB0:04E2|31134|:/iceberg_data/new_schema/sampletable",
  "schema_name": "sampleschema"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
Get metadata enrichment global settings
Get metadata enrichment global settings


GET /sal_integration/enrichment/global_settings
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.
  • lakehouse.sal_integration_enrichment_global_settings.get
Request
Custom Headers
  • AuthInstanceId
    string
    watsonx.data instance ID
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-\:/]+$
Response
Response Body
SalEnrichmentSettings
Request payload object of SAL Integration Enrichment Global Settings


Status Code
  • 200
    Success
    

  • 400
    Error
    

  • 401
    Unauthorized
    

  • 404
    Not found
    

  • 500
    Internal server error
    

Example responses
  • {
  "expansion": {
    "description": true,
    "description_configuration": {
      "assignment_threshold": 0.14,
      "suggestion_threshold": 0.9
    },
    "name": true,
    "name_configuration": {
      "assignment_threshold": 0.1,
      "suggestion_threshold": 0.1
    }
  },
  "term_assignment": {
    "class_based_assignments": false,
    "evaluate_negative_assignments": false,
    "llm_based_assignments": false,
    "ml_based_assignments_custom": false,
    "ml_based_assignments_default": false,
    "name_matching": false,
    "term_assignment_threshold": 0.3,
    "term_suggestion_threshold": 0.4
  }
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
Create or update metadata enrichment global settings
Create or update metadata enrichment global settings


PUT /sal_integration/enrichment/global_settings
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.
  • lakehouse.sal_integration_enrichment_global_settings.put
Request
Custom Headers
  • AuthInstanceId
    string
    watsonx.data instance ID
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-\:/]+$
Request Body
Required*
SalEnrichmentSettings
Request body


Response
Response Body
SalEnrichmentSettings
Request payload object of SAL Integration Enrichment Global Settings


Status Code
  • 200
    Success
    

  • 400
    Error
    

  • 401
    Unauthorized
    

  • 404
    Not found
    

  • 500
    Internal server error
    

Example responses
  • {
  "expansion": {
    "description": true,
    "description_configuration": {
      "assignment_threshold": 0.9,
      "suggestion_threshold": 0.75
    },
    "name": true,
    "name_configuration": {
      "assignment_threshold": 0.9,
      "suggestion_threshold": 0.75
    }
  },
  "term_assignment": {
    "class_based_assignments": false,
    "evaluate_negative_assignments": false,
    "llm_based_assignments": false,
    "ml_based_assignments_custom": false,
    "ml_based_assignments_default": false,
    "name_matching": false,
    "term_assignment_threshold": 0.3,
    "term_suggestion_threshold": 0.4
  }
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
List semantic enrichment jobs associated with the schema
List semantic enrichment jobs in wkc that associated with the schema by project id(in the given project from IBM Knowledge Catalog perspective)


GET /sal_integration/enrichment/jobs
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.
  • lakehouse.sal_integration_enrichment_jobs.list
Request
Custom Headers
  • AuthInstanceId
    string
    watsonx.data instance ID
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-\:/]+$
Query Parameters
  • project_id
    Required*
    string
    IBM Knowledge Catalog project id
    

    Possible values:  1 ≤ length ≤ 10000, Value must match regular expression ^[a-zA-Z0-9\-]+$
Response
Response Body
SalEnrichmentJobs
Collection of SAL integration enrichment jobs


Status Code
  • 200
    Success
    

  • 400
    Error
    

  • 401
    Unauthorized
    

  • 404
    Not found
    

  • 500
    Internal server error
    

Example responses
  • {
  "jobs": [
    "{ \"metadata\": { \"name\": \"SAL_MDE job\", \"asset_id\": \"ea73ce44-8aa0-4c75-bd69-6ca7074a1030\", \"owner_id\": \"IBMid-55000832RK\", \"version\": 0, }, \"entity\": { \"job\": { \"asset_ref_type\": \"metadata_enrichment_area\", \"configuration\": { \"env_type\": \"\", \"env_variables\": [] }, \"schedule_info\": {}, \"last_run_initiator\": \"deprecated field\", \"last_run_time\": \"deprecated field\", \"last_run_status\": \"deprecated field\", \"last_run_status_timestamp\": 0, \"future_scheduled_runs\": [], \"enable_notifications\": false, \"task_credentials_support\": { \"task_credentials_enabled\": true, \"user_id\": \"IBMid-55000832RK\", \"account_id\": \"04e9bc4761254b719ac22759cb69bebd\", }, \"project_name\": \"SAL Mapping /iceberg_data/new_schema 9aae5be3-87cf-4c31-b17d-9256ab42c14e\", \"asset_ref\": \"8688a3b6-a946-499e-a93c-b7d099db80dd\", \"schedule_id\": \"\", \"schedule_creator_id\": \"\", }, }, }"
  ]
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
List semantic enrichment job runs associated with the schema
List runs of an SAL enrichement job associated with the schema(project in IBM Knowledge Catalog perspective)


GET /sal_integration/enrichment/jobs/{job_id}/runs
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.
  • lakehouse.sal_integration_enrichment_job_runs.list
Request
Custom Headers
  • AuthInstanceId
    string
    watsonx.data instance ID
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-\:/]+$
Path Parameters
  • job_id
    Required*
    string
    enrichment job id, refered as 'asset_id' in '/Sal_integration/enrichment/jobs'
    

    Possible values:  1 ≤ length ≤ 10000, Value must match regular expression ^[a-zA-Z0-9\-_]+$
Query Parameters
  • project_id
    Required*
    string
    enrichment project id
    

    Possible values:  1 ≤ length ≤ 10000, Value must match regular expression ^[a-zA-Z0-9\-_]+$
Response
Response Body
SalEnrichmentJobRuns
Collection of job runs for a specific enrichment job


Status Code
  • 200
    Success
    

  • 400
    Error
    

  • 401
    Unauthorized
    

  • 404
    Not found
    

  • 500
    Internal server error
    

Example responses
  • {
  "runs": [
    "{ metadata: name: \"job run\" asset_id: \"da428d4b-50f2-4bb4-acec-d878c748cdf4\" owner_id: \"IBMid-697000CI7N\" created: \"1738200305392\" created_at: \"2025-01-30T01:25:05Z\" usage: last_update_time: 1738200318511 last_updated_at: \"2025-01-30T01:25:18Z\" entity: job_run: job_ref: \"4bd723e7-d734-4b34-be0f-ebfd0979d026\" job_name: \"SAL_MDE job (Publishing)\" job_type: \"metadata_enrichment_area_publish\" state: \"Completed\" isScheduledRun: false configuration: metadata_enrichment_area_id: \"65d31e36-004e-4942-af6c-4d62f64b7924\" env_type: \"metadata_enrichment_area_publish\" env_variables: [] skip_notifications: true catalog_id: \"b2b4bb75-f02a-47e2-a2cd-ff02dd87841d\" duplicate_action: \"UPDATE\" asset_ids: - \"16db5c29-90eb-42d9-9f98-f79ba985f17d\" - \"ae7c6ff8-175d-499c-b1e9-ac945c1fe8c3\" - \"171c1cf8-7270-447f-a8cb-0e38a6f9bee3\" - \"c8d7fdfe-1ef4-4f77-a19d-5fdbf6b5d72e\" project_name: \"SAL Mapping /iceberg_data/retail b2b4bb75-f02a-47e2-a2cd-ff02dd87841d\" last_state_change_timestamp: \"2025-01-30T01:25:18Z\" duration: 12 location_definition: physical_location_code: \"DAL\" physical_location_code_assigned_by: \"IBMid-697000CI7N\" physical_location_code_rds_id: \"c57cb90f-2126-3800-9c9f-9eab82021cdf\" physical_location_code_rds_version: \"00002024-0613-4175-8306-512505000000_4\" physical_location_code_assignment_method: \"INFERRED\" physical_location_code_added_on: \"1738199864932 }"
  ]
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
Get semantic enrichment job run logs associated with the job run
Get semantic enrichment job run logs associated with the job run


GET /sal_integration/enrichment/jobs/{job_id}/runs/{run_id}/logs
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.
  • lakehouse.sal_integration_enrichment_job_run_logs.get
Request
Custom Headers
  • AuthInstanceId
    string
    watsonx.data instance ID
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-\:/]+$
Path Parameters
  • job_id
    Required*
    string
    IBM Knowledge Catalog enrichment job id
    

    Possible values:  1 ≤ length ≤ 10000, Value must match regular expression ^[a-zA-Z0-9\-]+$
  • run_id
    Required*
    string
    IBM Knowledge Catalog enrichment job run id
    

    Possible values:  1 ≤ length ≤ 10000, Value must match regular expression ^[a-zA-Z0-9\-]+$
Query Parameters
  • project_id
    Required*
    string
    IBM Knowledge Catalog project id
    

    Possible values:  1 ≤ length ≤ 10000, Value must match regular expression ^[a-zA-Z0-9\-]+$
Response
Response Body
SalEnrichmentJobRunLogs
collection of the enrichment job run log results


Status Code
  • 200
    Success
    

  • 400
    Error
    

  • 401
    Unauthorized
    

  • 404
    Not found
    

  • 500
    Internal server error
    

Example responses
  • {
  "results": [
    "Size: 28 Blocks: 0 IO Block: 4096 directory",
    "Device: 3000eeh/3145966d    Inode: 453833649 Links: 3",
    "Access: (0755/drwxr-xr-x) Uid: ( 0/ root) Gid: ( 0/ root)",
    "Access: 2019-04-08 19:12:21.930122905 +0000",
    "Modify: 2019-04-08 19:12:21.932122894 +0000",
    "Change: 2019-04-08 19:12:21.932122894 +0000",
    "DONE"
  ],
  "total_count": 100
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
get metadata enrichment settings for a IBM Knowledge Catalog project(schema)
get metadata enrichment settings for a IBM Knowledge Catalog project(schema)


GET /sal_integration/enrichment/project_settings
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.
  • lakehouse.sal_integration_enrichment_project_settings.get
Request
Custom Headers
  • AuthInstanceId
    string
    watsonx.data instance ID
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-\:/]+$
Query Parameters
  • project_id
    Required*
    string
    IBM Knowledge Catalog project id
    

    Possible values:  1 ≤ length ≤ 10000, Value must match regular expression ^[a-zA-Z0-9\-]+$
Response
Response Body
SalEnrichmentSettings
Request payload object of SAL Integration Enrichment Global Settings


Status Code
  • 200
    Success
    

  • 400
    Error
    

  • 401
    Unauthorized
    

  • 404
    Not found
    

  • 500
    Internal server error
    

Example responses
  • {
  "expansion": {
    "description": true,
    "description_configuration": {
      "assignment_threshold": 0.14,
      "suggestion_threshold": 0.9
    },
    "name": true,
    "name_configuration": {
      "assignment_threshold": 0.1,
      "suggestion_threshold": 0.1
    }
  },
  "term_assignment": {
    "class_based_assignments": false,
    "evaluate_negative_assignments": false,
    "llm_based_assignments": false,
    "ml_based_assignments_custom": false,
    "ml_based_assignments_default": false,
    "name_matching": false,
    "term_assignment_threshold": 0.3,
    "term_suggestion_threshold": 0.4
  }
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
Create or update project level metadata enrichment settings
Create or update metadata enrichment settings for a IBM Knowledge Catalog project(enriched schema)


PUT /sal_integration/enrichment/project_settings
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.
  • lakehouse.sal_integration_enrichment_project_settings.put
Request
Custom Headers
  • AuthInstanceId
    string
    watsonx.data instance ID
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-\:/]+$
Query Parameters
  • project_id
    Required*
    string
    IBM Knowledge Catalog project id
    

    Possible values:  1 ≤ length ≤ 10000, Value must match regular expression ^[a-zA-Z0-9\-]+$
Request Body
Required*
SalEnrichmentSettings
Request body


Response
Status Code
  • 202
    No Content
    

  • 400
    Error
    

  • 401
    Unauthorized
    

  • 404
    Not found
    

  • 500
    Internal server error
    

Example responses
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
Get list of uploaded glossary terms
Get list of uploaded glossary terms


GET /sal_integration/glossary/terms
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.
  • lakehouse.sal_integration_glossary_terms.get
Request
Custom Headers
  • AuthInstanceId
    string
    watsonx.data instance ID
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-\:/]+$
Response
Response Body
SalGlossaryTerms
Sal Integration Glossary terms list


Status Code
  • 200
    Success
    

  • 400
    Error
    

  • 401
    Unauthorized
    

  • 404
    Not found
    

  • 500
    Internal server error
    

Example responses
  • {
  "glossary_terms": [
    {
      "description": "Inventory ID",
      "name": "inventoryID"
    },
    {
      "description": "Inventory date",
      "name": "inv_date_sk"
    }
  ]
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
Upload semantic enrichment business terms glossary
Upload semantic enrichment business terms glossary


POST /sal_integration/glossary/upload_processes
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.
  • lakehouse.sal_integration_upload_glossary.post
Request
Custom Headers
  • AuthInstanceId
    string
    watsonx.data instance ID
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-\:/]+$
Form Parameters
  • replace_option
    Required*
    string
    glossary upload replace option
    

    Allowable values: [all,specified,empty]
    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-_]+$
  • glossary_csv
    binary
    Glossary CSV file
    

    Possible values:  1 ≤ length ≤ 52428800
    Example: Glossary.cvs
Response
Response Body
SalGlossaryUploadProcess
Sal Integration Upload Glossary Process


Status Code
  • 201
    Success
    

  • 400
    Error
    

  • 401
    Unauthorized
    

  • 404
    Not found
    

  • 500
    Internal server error
    

Example responses
  • {
  "id": "18b49d7a-9519-4539-8db5-ff080623c226"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
Get status of glossary uploading process(job)
Get status of glossary uploading process(job)


GET /sal_integration/glossary/upload_processes/{id}/status
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.
  • lakehouse.sal_integration_upload_glossary_status.get
Request
Custom Headers
  • AuthInstanceId
    string
    watsonx.data instance ID
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-\:/]+$
Path Parameters
  • id
    Required*
    string
    upload process id
    

    Possible values:  1 ≤ length ≤ 10000, Value must match regular expression ^[a-zA-Z0-9\-]+$
Response
Response Body
SalGlossaryUploadStatus
Sal Integration Upload Glossary


Status Code
  • 200
    Success
    

  • 400
    Error
    

  • 401
    Unauthorized
    

  • 404
    Not found
    

  • 500
    Internal server error
    

Example responses
  • {
  "response": "completed"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
Post watsonx.data schema to fetch mapped catalog and project
use the list of watsonx.data catalog and schema to fetch mapped IKC project id and catalog id


GET /sal_integration/mappings
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.
  • lakehouse.sal_integration_mappings.list
Request
Custom Headers
  • AuthInstanceId
    string
    watsonx.data instance ID
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-\:/]+$
Query Parameters
  • catalog_name
    string
    catalog name in Watsonx.data
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-_]+$
  • schema_name
    string
    schema name in Watsonx.data
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-_]+$
  • next
    string
    reference as an continue of reading results from earlier query (if the results exceed 100)
    

    Possible values:  1 ≤ length ≤ 300, Value must match regular expression ^[a-zA-Z0-9\-_\.]$
Response
Response Body
SalIntegrationMappings
Collection of SAL Mapping details of given watsonx.data schemas


Status Code
  • 200
    Success
    

  • 400
    Error
    

  • 401
    Unauthorized
    

  • 404
    Not found
    

  • 500
    Internal server error
    

Example responses
  • {
  "mappings": [
    {
      "wkc_catalog_id": "18b49d7a-9519-4539-8db5-ff080623c226",
      "wkc_project_id": "9519bd7a-9519-8db5-4539-ff080623c226",
      "wxd_catalog_name": "iceberg_data",
      "wxd_schema_name": "test_schema"
    },
    {
      "wkc_catalog_id": "22a73c5e-91bc-4e76-8e59-3f1db8ef75a2",
      "wkc_project_id": "7451bc19-98de-4bc3-85f9-8125aa789d52",
      "wxd_catalog_name": "retail_data",
      "wxd_schema_name": "sales_schema"
    }
  ]
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
  • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
List Semantic Search queries snapshot
List Semantic Search queries snapshot


GET /sal_integration/semantic_search/queries
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.
  • lakehouse.semantic_search_queries.list
Request
Custom Headers
  • AuthInstanceId
    string
    watsonx.data instance ID
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-\:/]+$
Query Parameters
  • engine_id
    string
    engine id
    

    Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-]+$
  • schema_search_enabled
    boolean
    enable schemas search
    

    Default: true
  • column_search_enabled
    boolean
    enable columns search
    

    Default: true
  • max_result_number
    integer
    max history records limitation
    

    Possible values:  1 ≤ value ≤ 30
    Default: 5
  • run_search
    boolean
    if the response include actual search result
    

    Response
    Response Body
    SemanticSearchList
    collection of query results of Semantic search history queries response object
    

    Status Code
    • 200
      Success
      

    • 400
      Error
      

    • 401
      Unauthorized
      

    • 404
      Not found
      

    • 500
      Internal server error
      

    Example responses
    • {
  "queries": [
    {
      "id": "1",
      "last_search_time": "2024-09-15T14:30:00Z",
      "results": [
        {
          "artifact_type": "data_asset",
          "asset_id": "7f9d8270-496f-4bda-96b9-9891b35c80e9",
          "catalog_name": "iceberg",
          "description": "Customer transaction data",
          "highlight": {
            "metadata.name": [
              "<em>Customer</em>_Transactions"
            ],
            "metadata.semantic_name": [
              "<em>Customer</em> Transactions"
            ]
          },
          "matched_columns": [
            {
              "asset_id": "7f9d8270-496f-4bda-96b9-9891b35c80e9:customer_id",
              "description": "Primary key of the customer table",
              "highlight": {
                "column.name": [
                  "<em>customer</em>_id"
                ]
              },
              "name": "customer_id",
              "semantic_description": "Unique identifier for a customer",
              "semantic_name": "Customer ID"
            }
          ],
          "name": "table1",
          "path": "/iceberg/california_school/table1",
          "project_id": "b94b3f1c-3808-44d2-b7e6-4df8d5861950",
          "provider_type": "cams",
          "schema_name": "california_school",
          "search_score": 92.5,
          "semantic_description": "Table contains details of customer transactions",
          "semantic_name": "Customer Transactions",
          "state": "active",
          "table_name": "table1",
          "tags": [
            "analytics",
            "customer"
          ],
          "terms": [
            "customer",
            "transactions"
          ]
        }
      ],
      "search_query": "catalog_table"
    }
  ]
}
    • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
    • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
    • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
    • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
    Trigger a global search among IBM Knowledge Catalog metadata by given query
    Execute a query of global search among IBM Knowledge Catalog metadata
    

    POST /sal_integration/semantic_search/queries
    Authorization
    To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.
    • lakehouse.semantic_search_queries.create
    Request
    Custom Headers
    • AuthInstanceId
      string
      watsonx.data instance ID
      

      Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-\:/]+$
    Request Body
    Required*
    SemanticSearchBody
    Request body
    

      Response
      Response Body
      SemanticSearch
      semantic search object of the returning result
      

      Status Code
      • 201
        Success
        

      • 400
        Error
        

      • 401
        Unauthorized
        

      • 404
        Not found
        

      • 500
        Internal server error
        

      Example responses
      • {
  "last_search_time": "2024-09-15T14:30:00Z",
  "results": [
    {
      "artifact_type": "data_asset",
      "asset_id": "7f9d8270-496f-4bda-96b9-9891b35c80e9",
      "catalog_name": "iceberg",
      "description": "Customer transaction data",
      "highlight": {
        "metadata.name": [
          "<em>Customer</em>_Transactions"
        ],
        "metadata.semantic_name": [
          "<em>Customer</em> Transactions"
        ]
      },
      "matched_columns": [
        {
          "asset_id": "7f9d8270-496f-4bda-96b9-9891b35c80e9:customer_id",
          "description": "Primary key of the customer table",
          "highlight": {
            "column.name": [
              "<em>customer</em>_id"
            ]
          },
          "name": "customer_id",
          "semantic_description": "Unique identifier for a customer",
          "semantic_name": "Customer ID"
        }
      ],
      "name": "table1",
      "path": "/iceberg/california_school/table1",
      "project_id": "b94b3f1c-3808-44d2-b7e6-4df8d5861950",
      "provider_type": "cams",
      "schema_name": "california_school",
      "search_score": 92.5,
      "semantic_description": "Table contains details of customer transactions",
      "semantic_name": "Customer Transactions",
      "state": "active",
      "table_name": "table1",
      "tags": [
        "analytics",
        "customer"
      ],
      "terms": [
        "customer",
        "transactions"
      ]
    }
  ],
  "search_query": "catalog_table"
}
      • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
      • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
      • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
      • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
      Clear semantic search query history
      Delete the history records of semantic search in batch, if no batch_size given, entire semantic search history list will be removed
      

      DELETE /sal_integration/semantic_search/queries
      Authorization
      To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.
      • lakehouse.semantic_search_queries.delete
      Request
      Custom Headers
      • AuthInstanceId
        string
        watsonx.data instance ID
        

        Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-\:/]+$
      Query Parameters
      • batch_size
        integer
        max number to queries to be deleted (most recent to least), if no number provided all queries history will be clear
        

        Possible values:  1 ≤ value ≤ 30
        Response
        Status Code
        • 204
          No Content
          

        • 400
          Error
          

        • 401
          Unauthorized
          

        • 404
          Not found
          

        • 500
          Internal server error
          

        Example responses
        • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
        • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
        • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
        • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
        Delete semantic search query history by record id
        Delete the history records of semantic search by record id
        

        DELETE /sal_integration/semantic_search/queries/{id}
        Authorization
        To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.
        • lakehouse.semantic_search_queries_by_id.delete
        Request
        Custom Headers
        • AuthInstanceId
          string
          watsonx.data instance ID
          

          Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-\:/]+$
        Path Parameters
        • id
          Required*
          string
          id of the semanric search query record
          

          Possible values:  1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9\-]+$
        Response
        Status Code
        • 204
          No Content
          

        • 400
          Error
          

        • 401
          Unauthorized
          

        • 404
          Not found
          

        • 500
          Internal server error
          

        Example responses
        • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
        • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
        • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
        • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
        Delete Semantic automation layer(SAL) integration metadata
        Delete SAL integration metadata
        

        DELETE /sal_metadata
        Authorization
        To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.
        • lakehouse.sal_metadata.delete
        Request
        No Request Parameters
        This method does not accept any request parameters.
        Response
        Status Code
        • 204
          No Content
          

        • 400
          Error
          

        • 401
          Unauthorized
          

        • 404
          Not found
          

        • 500
          Internal server error
          

        Example responses
        • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
        • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
        • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
        • {
  "errors": [
    {
      "code": "bad_request",
      "message": "The 'email' field is required.",
      "more_info": "https://api.example.com/docs/errors/bad_request"
    }
  ],
  "exception": "BadRequestException: Missing required field",
  "message": "Invalid request",
  "message_code": "ERR4001",
  "more_info": "https://api.example.com/docs/errors/ERR4001",
  "status_code": 400,
  "trace": "123e4567-e89b-12d3-a456-426614174000"
}
        id=curlclassName=tab-item-selected
        Privacy statement