API customization overview

API customization in watsonx.data provides a way for instance administrators to customize JVM, CONFIG, catalog, and Velox (Presto (C++)) properties for Presto (Java) and Presto (C++) engines through an API.

watsonx.data on IBM Software Hub

watsonx.data Developer edition

This customization method does not require you to add the parameters inside the pod, restart the pod (if there is CPD deployment), or reach out to support personnel (if there is SaaS deployment) for customization. It also does not require any special access and privileges to the backend system. API customization is a unified way to customize allowed properties in watsonx.data, regardless of the deployment. API customization is supported through the PATCH API. API endpoints and sample requests for Presto (Java) and Presto (C++) engines are as follows:

PATCH API (Presto (Java) engine)

Endpoint

/presto_engines/{engine_id}

Request body

Note: The API Customization patch must have the following as required fields configuration, jvm, catalog, event_listener, jmx_exporter_config, log_config, global and other fields as optional.

{
    "description": "updated description for presto engine",
    "engine_display_name": "sampleEngine",
    "engine_properties": {
        "configuration": {
            "coordinator": {
                "property_1": "property_value",
                "property_2": "property_value"
            },
            "worker": {
                "property_1": "property_value",
                "property_2": "property_value"
            }
        },
        "jvm": {
            "coordinator": {
                "property_1": "property_value",
                "property_2": "property_value"
            },
            "worker": {
                "property_1": "property_value",
                "property_2": "property_value"
            }
        },
        "catalog": {
                "property_1": "property_value",
                "property_2": "property_value"
        },
        "event_listener": {
            "property_1": "property_value",
            "property_2": "property_value"
        },
        "log_config": {
            "coordinator": {
                "property_1": "property_value",
                "property_2": "property_value"
            },
            "worker": {
                "property_1": "property_value",
                "property_2": "property_value"
            }
        },
        "global": {
            "enable-mixed-case-support": "true"
        }
    },
    "engine_restart": "force",
    "remove_engine_properties": {
        "configuration": {
            "coordinator": [
                "property1",
                "property2"
            ],
            "worker": [
                "property1",
                "property2"
            ]
        },
        "jvm": {
            "coordinator": [
                "property1",
                "property2"
            ],
            "worker": [
                "property1",
                "property2"
            ]
        },
        "event_listener": [
            "property1",
            "property2"
        ]
    },
    "catalog": {
        "catalog_name": [
            "property1",
            "property2"
        ]
    },
    "global": {},
    "tags": [
        "tag1",
        "tag2"
    ]
}

PATCH API (Presto (C++) engine)

Endpoint

/prestissimo_engines/{engine_id}

Request body

Note: The API Customization patch must have the following as required fields configuration, jvm, catalog, velox, log_config, global and other fields as optional.

{
    "description": "updated description for prestissimo engine",
    "engine_display_name": "sampleEngine",
    "engine_properties": {
        "configuration": {
            "coordinator": {
                "property_1": "property_value",
                "property_2": "property_value"
            },
            "worker": {
                "property_1": "property_value",
                "property_2": "property_value"
            }
        },
        "jvm": {
            "coordinator": {
                "property_1": "property_value",
                "property_2": "property_value"
            }
        },
        "catalog": {
            "catalog_name": {
                "coordinator": {
                    "property_1": "property_value",
                    "property_2": "property_value"
            },
            "worker": {
                "property_1": "property_value",
                "property_2": "property_value"
            }
          }
        },
        "velox": {
            "property_1": "property_value",
            "property_2": "property_value"
        },
        "log_config": {
            "coordinator": {
                "property_1": "property_value",
                "property_2": "property_value"
            },
            "worker": {
                "property_1": "property_value",
                "property_2": "property_value"
            }
        "optimizer_properties":{
                "property_1": "property_value",
                "property_2": "property_value"
        },
        "global": {
            "property_1": "property_value",
            "property_2": "property_value"
        }
    },
    "engine_restart": "force",
    "remove_engine_properties": {
        "configuration": {
            "coordinator": [
                "property1",
                "property2"
            ],
            "worker": [
                "property1",
                "property2"
            ]
        },
        "catalog": {
            "catalog_name": {
                "coordinator": [
                    "property1",
                    "property2"
                ],
                "worker": [
                    "property1",
                    "property2"
                ]
            }
        },
        "jvm": {
            "coordinator": [
                "property1",
                "property2"
            ]
        },
        "log_config": {
            "coordinator": [
                "property1",
                "property2"
            ],
            "worker": [
                "property1",
                "property2"
            ]
        },
        "velox": [
            "property1",
            "property2"
        ]
    },
    "tags": [
        "tag1",
        "tag2"
    ]
}

You can find the curl example for API customization in Update presto engine.

For the list of properties that can be customized through an API for Presto (Java), see:

Important: API customization is not supported for Presto (C++) engine in watsonx.data Developer edition.

For the list of properties that can be customized through an API for Presto (C++), see:

For properties that must be customized under the guidance of the watsonx.data support team, see Properties to be customized under support guidance.

Note: With IBM® watsonx.data 2.0.2 and later, you can get System Access Control (SAC) plug-in logs with DEBUG information. To enable DEBUG logs of SAC plug-in in Presto, trigger the customization API and add "com.ibm.openlakehouse.prestodb": "DEBUG" under log_config.

"log_config": {
            "coordinator": {
                "com.ibm.openlakehouse.prestodb": "DEBUG"
            },
            "worker": {}
        }

For more information, see Update presto engine.