How to modify global parameters in the config.xml file of an ApsaraDB for ClickHouse cluster-ApsaraDB for ClickHouse-阿里云帮助中心

Modify global parameters in the config.xml file of an ApsaraDB for ClickHouse cluster to optimize instance performance.

Background

An ApsaraDB for ClickHouse cluster uses default parameter values configured in config.xml and user.xml. You can modify these parameters to optimize your instance:

user.xml configuration file: Modify parameters by running the SET GLOBAL command. Changes take effect immediately without a restart. For more information, see Modify user.xml parameters.
config.xml configuration file: Modify parameters in the console.

Usage notes

For Community-Compatible Edition clusters, you can configure parameters in XML Mode and view the change history only if the cluster was created after December 1, 2021.
Enterprise Edition clusters do not support parameter configuration in XML Mode.
XML Mode does not support deleting parameters. The configurable parameters in XML Mode are the same as those in Default Mode.
If you modify parameters that require a restart to take effect, the cluster automatically restarts after the parameter modifications are complete. Before you submit the parameters, ensure that the cluster restart does not affect your business.

Impacts on the cluster

If the cluster is in the Changing Configurations or Restarting state, you can only view the cluster information. You cannot perform operations such as instance type upgrades, scale-outs, or scale-ins.
If you modify parameters that require a restart to take effect, the cluster automatically restarts after the parameter modifications are complete. Perform this operation during off-peak hours to avoid service disruptions.

Modify parameters

The procedure for modifying parameters varies by cluster edition.

Important

If you need to modify the prometheus.port or text_log parameters, refer to Important parameters.

Enterprise edition

Log on to the ApsaraDB for ClickHouse console.
In the upper-left corner of the page, select the region of your target cluster.
On the Clusters page, click the Enterprise Edition Clusters tab, and then click the ID of the target cluster.
In the left-side navigation pane, click Parameter Management.
In the Parameter Value column, click the Modify icon to edit the value. Enter a value within the valid range, and then click OK.
After modifying the desired parameters, click Submit Parameters in the upper-right corner of the page.
In the Save Settings dialog box, review the parameter values before and after the change, confirm the changes, provide a reason for the change, and then click OK.

Important
If you submit parameters that require a restart to take effect, the ClickHouse cluster automatically restarts after the parameter modifications are complete. Before you proceed, ensure that the restart does not affect your business.

After you submit the parameters, the system validates the parameter values. If a parameter value is invalid, an error message appears. ErrorCode 102 indicates that the entered value is invalid. Return to the previous step, enter a value within the valid range, and then submit the parameters again.

Community-compatible edition

Log on to the ApsaraDB for ClickHouse console.
In the upper-left corner of the page, select the region of your target cluster.
On the Clusters page, click the Clusters of Community-compatible Edition tab, and then click the ID of the target cluster.
In the left-side navigation pane, click Parameter Configuration.
Click the Settings tab. Select Default Mode or XML Mode to modify parameters.

Important
In the ApsaraDB for ClickHouse console, the value for the prometheus.port parameter must be in the range of 2182 to 3000.
- Default Mode: In the Parameter Value column, click the Modify icon to enter edit mode. Enter a value within the valid range, and then click OK.
- XML Mode: In the upper-right corner of the page, click Modify to modify the desired parameters in the file.
After modifying the desired parameters, click Submit Parameters in the upper-right corner of the page.
In the Save Settings dialog box, review the parameter values before and after the change, confirm the changes, provide a reason for the change, and then click Submit Parameters.
Important
- If you submit parameters that require a restart to take effect, the ClickHouse cluster automatically restarts after the parameter modifications are complete. Before you proceed, make sure that the restart does not affect your business.
- In XML Mode, if a parameter value is invalid, an error message appears. ErrorCode 102 indicates that the entered value is invalid. Return to the previous step, enter a value within the valid range, and then submit the parameters again.

Revert modifications

Note

You can only revert unsubmitted modifications.
For Enterprise Edition clusters and for Community-Compatible Edition clusters in XML Mode, you can only revert all parameter modifications at once.

To revert unsubmitted modifications, perform one of the following operations:

Revert a single parameter modification: Click the icon next to the parameter value. ApsaraDB for ClickHouse reverts the unsubmitted modification for that parameter to its previous value.
Revert all parameter modifications: Click Cancel in the upper-right corner of the parameter list. ApsaraDB for ClickHouse reverts all unsubmitted changes to their previous values.

View change history

Enterprise edition

Log on to the ApsaraDB for ClickHouse console.
In the upper-left corner of the page, select the region of your target cluster.
On the Clusters page, click the Enterprise Edition Clusters tab, and then click the ID of the target cluster.
In the left-side navigation pane, click Parameter Management.
Click the Change History tab to view the change history in one of the following ways:
- Click Last 30 Days or Last 7 Days to view changes from the corresponding period.
- Specify a time range to view the modification records within that period.

Community-compatible edition

Log on to the ApsaraDB for ClickHouse console.
In the upper-left corner of the page, select the region of your target cluster.
On the Clusters page, click the Clusters of Community-compatible Edition tab, and then click the ID of the target cluster.
In the left-side navigation pane, click Parameter Configuration.
Click the Change History tab to view the change history in one of the following ways:
- Click Last 30 Days or Last 7 Days to view changes from the corresponding period.
- Specify a time range and click Query to view the modification records within that period.

Important parameters

In the ApsaraDB for ClickHouse console, the prometheus.port parameter value is restricted to a port number in the range of 2182 to 3000.

In some cluster versions, text_log is not enabled or the value of text_log.level is too low. To view text logs, set the text_log.level parameter to an appropriate value based on your requirements:

Value	Description	Use cases
trace	The most detailed log level. It records all operations and events.	Tracing program execution during development and debugging.
debug	Includes detailed information useful during development, but less verbose than trace. It typically records function calls and variable states.	Debugging a program.
information	Records normal operations and status events, such as starting a service and completing a task. It usually indicates that the system is running normally with no errors.	N/A
warning	Indicates potential issues or non-fatal errors. The system continues to run, but some conditions may need attention.	Monitoring the system, analyzing potential issues, and optimizing the system.
error	Indicates that the system encountered errors that affect some features or operations. The system may still run, but you must address these errors.	Monitoring the system and analyzing errors to troubleshoot issues.