ClickHouse/docs/en/operations/settings/index.md

---
sidebar_label: Settings Overview
sidebar_position: 1
slug: /en/operations/settings/
pagination_next: en/operations/settings/settings
---

# Settings Overview

There are multiple ways to define ClickHouse settings. Settings are configured in layers, and each subsequent layer redefines the previous values of a setting.

The order of priority for defining a setting is:

1. Settings in user profiles. Set user profiles either by:
  - SQL (recommended)
  - adding one or more XML or YAML files to `/etc/clickhouse-server/users.d`

2. Session settings

    - Send `SET setting=value` from the ClickHouse console client in interactive mode.
    Similarly, you can use ClickHouse sessions in the HTTP protocol. To do this, you need to specify the `session_id` HTTP parameter.

3. Query settings

    - When starting the ClickHouse console client in non-interactive mode, set the startup parameter `--setting=value`.
    - When using the HTTP API, pass CGI parameters (`URL?setting_1=value&setting_2=value...`).
    - Define settings in the [SETTINGS](../../sql-reference/statements/select/index.md#settings-in-select-query) clause of the SELECT query. The setting value is applied only to that query and is reset to the default or previous value after the query is executed.

View the [Settings](./settings.md) page for a description of the ClickHouse settings.

## Examples

These examples all set the value of the `async_insert` setting to `1`, and show how to examine 
the settings in a running system.

### Using SQL to create a user profile

```sql
CREATE
SETTINGS PROFILE log_ingest SETTINGS async_insert = 1
```

```sql
CREATE USER ingester
IDENTIFIED WITH sha256_hash BY '7e099f39b84ea79559b3e85ea046804e63725fd1f46b37f281276aae20f86dc3'
# highlight-next-line
SETTINGS PROFILE log_ingest
```

#### Examine the user profile and assignment

```sql
SHOW ACCESS
```

```response
┌─ACCESS─────────────────────────────────────────────────────────────────────────────┐
│ CREATE USER default IDENTIFIED WITH sha256_password                                │
# highlight-next-line
│ CREATE USER ingester IDENTIFIED WITH sha256_password SETTINGS PROFILE log_ingest   │
│ CREATE SETTINGS PROFILE default                                                    │
# highlight-next-line
│ CREATE SETTINGS PROFILE log_ingest SETTINGS async_insert = true                    │
│ CREATE SETTINGS PROFILE readonly SETTINGS readonly = 1                             │
│ ...                                                                                │
└────────────────────────────────────────────────────────────────────────────────────┘
```

### Using XML to create a user profile

```xml title=/etc/clickhouse-server/users.d/users.xml
<clickhouse>
# highlight-start
    <profiles>
        <log_ingest>
            <async_insert>1</async_insert>
        </log_ingest>
    </profiles>
# highlight-end

    <users>
        <ingester>
            <password_sha256_hex>7e099f39b84ea79559b3e85ea046804e63725fd1f46b37f281276aae20f86dc3</password_sha256_hex>
# highlight-start
            <profile>log_ingest</profile>
# highlight-end
        </ingester>
        <default replace="true">
            <password_sha256_hex>7e099f39b84ea79559b3e85ea046804e63725fd1f46b37f281276aae20f86dc3</password_sha256_hex>
            <access_management>1</access_management>
            <named_collection_control>1</named_collection_control>
        </default>
    </users>
</clickhouse>
```

#### Examine the user profile and assignment

```sql
SHOW ACCESS
```

```response
┌─ACCESS─────────────────────────────────────────────────────────────────────────────┐
│ CREATE USER default IDENTIFIED WITH sha256_password                                │
# highlight-next-line
│ CREATE USER ingester IDENTIFIED WITH sha256_password SETTINGS PROFILE log_ingest   │
│ CREATE SETTINGS PROFILE default                                                    │
# highlight-next-line
│ CREATE SETTINGS PROFILE log_ingest SETTINGS async_insert = true                    │
│ CREATE SETTINGS PROFILE readonly SETTINGS readonly = 1                             │
│ ...                                                                                │
└────────────────────────────────────────────────────────────────────────────────────┘
```

## Converting a Setting to its Default Value

If you change a setting and would like to revert it back to its default value, set the value to `DEFAULT`. The syntax looks like:

```sql
SET setting_name = DEFAULT
```

For example, the default value of `max_insert_block_size` is 1048449. Suppose you change its value to 100000:

```sql
SET max_insert_block_size=100000;

SELECT value FROM system.settings where name='max_insert_block_size';
```

The response is:

```response
┌─value──┐
│ 100000 │
└────────┘
```

The following command sets its value back to 1048449:

```sql
SET max_insert_block_size=DEFAULT;

SELECT value FROM system.settings where name='max_insert_block_size';
```

The setting is now back to its default:

```response
┌─value───┐
│ 1048449 │
└─────────┘
```


## Custom Settings {#custom_settings}

In addition to the common [settings](../../operations/settings/settings.md), users can define custom settings.

A custom setting name must begin with one of predefined prefixes. The list of these prefixes must be declared in the [custom_settings_prefixes](../../operations/server-configuration-parameters/settings.md#custom_settings_prefixes) parameter in the server configuration file.

```xml
<custom_settings_prefixes>custom_</custom_settings_prefixes>
```

To define a custom setting use `SET` command:

```sql
SET custom_a = 123;
```

To get the current value of a custom setting use `getSetting()` function:

```sql
SELECT getSetting('custom_a');
```

**See Also**

- [Server Configuration Settings](../../operations/server-configuration-parameters/settings.md)