> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-mintlify-8a08bda2.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Асинхронные вставки (async_insert)
> Используйте асинхронные вставки как альтернативу батчингу данных.
Асинхронные вставки в ClickHouse — это эффективная альтернатива, когда пакетирование на стороне клиента невозможно. Это особенно важно для задач обсервабилити, где сотни или тысячи agent-ов непрерывно отправляют данные — журналы, метрики, трассировки, — часто небольшими полезными нагрузками в реальном времени. Буферизация данных на стороне клиента в таких средах усложняет архитектуру, поскольку требует централизованной очереди, чтобы отправлять достаточно крупные батчи.
Отправлять много небольших батчей в синхронном режиме не рекомендуется, так как это приводит к созданию множества частей. Это ухудшает производительность запросов и вызывает ошибки ["too many part"](/ru/resources/support-center/knowledge-base/troubleshooting/exception-too-many-parts).
Асинхронные вставки переносят ответственность за пакетирование с клиента на сервер: входящие данные записываются в буфер в памяти, а затем сбрасываются в хранилище при достижении настраиваемых порогов. Такой подход значительно снижает накладные расходы на создание частей, уменьшает нагрузку на CPU и обеспечивает эффективную ингестию даже при высоком параллелизме.
Основное поведение управляется через настройку [`async_insert`](/ru/reference/settings/session-settings#async_insert).
Асинхронные вставки поддерживаются как через HTTP, так и через native TCP interface.
Когда они включены (`async_insert = 1`), вставки буферизуются и записываются на диск только после выполнения одного из условий сброса:
* Буфер достигает заданного размера данных ([`async_insert_max_data_size`](/ru/reference/settings/session-settings#async_insert_max_data_size), по умолчанию 100 MiB).
* Проходит заданный интервал времени ([`async_insert_busy_timeout_ms`](/ru/reference/settings/session-settings#async_insert_busy_timeout_max_ms), по умолчанию 200 мс или 1000 мс в Cloud).
* Накапливается максимальное количество запросов на вставку ([`async_insert_max_query_number`](/ru/reference/settings/session-settings#async_insert_max_query_number), по умолчанию 450).
Сброс выполняется при достижении первого из этих порогов.
Этот процесс пакетирования прозрачен для клиентов и помогает ClickHouse эффективно объединять трафик вставки из нескольких источников. Однако до сброса данные недоступны для запросов. Важно, что для каждой комбинации формы вставки и настроек существует несколько буферов, а в кластерах буферы поддерживаются отдельно на каждом узле, что позволяет гибко управлять ими в многопользовательских средах. Во всем остальном механика вставки идентична описанной для [синхронных вставок](/ru/concepts/best-practices/selecting-an-insert-strategy#synchronous-inserts-by-default).
### Выбор режима возврата
Поведение асинхронных вставок дополнительно настраивается с помощью параметра [`wait_for_async_insert`](/ru/reference/settings/session-settings#wait_for_async_insert).
Если установлено значение 1 (по умолчанию), ClickHouse подтверждает вставку только после того, как данные успешно сбрасываются на диск. Это обеспечивает строгие гарантии сохранности данных и упрощает обработку ошибок: если во время сброса что-то пойдет не так, ошибка будет возвращена клиенту. Этот режим рекомендуется для большинства production-сценариев, особенно если отказы вставки нужно надежно отслеживать.
[Бенчмарки](https://clickhouse.com/blog/asynchronous-data-inserts-in-clickhouse) показывают, что этот режим хорошо масштабируется при параллелизме — как с 200, так и с 500 клиентами — благодаря адаптивным вставкам и стабильному созданию частей.
Параметр `wait_for_async_insert = 0` включает режим "fire-and-forget". В этом случае сервер подтверждает вставку сразу после буферизации данных, не дожидаясь их записи в хранилище.
Это обеспечивает сверхнизкую latency вставок и максимальный throughput, что идеально подходит для высокоскоростных, но некритичных данных. Однако здесь есть компромиссы: нет гарантии, что данные будут сохранены, ошибки проявляются только во время сброса, а dead-letter queue для неудачных вставок отсутствует — для трассировки сбоев приходится постфактум проверять серверные журналы и системные таблицы. Используйте этот режим только в том случае, если ваша рабочая нагрузка допускает потерю данных.
[Бенчмарки также показывают](https://clickhouse.com/blog/asynchronous-data-inserts-in-clickhouse) существенное сокращение количества частей и снижение загрузки CPU, когда буфер сбрасывается нечасто (например, каждые 30 секунд), однако риск незаметного сбоя сохраняется.
Мы настоятельно рекомендуем использовать `async_insert=1,wait_for_async_insert=1`, если вы используете асинхронные вставки. Использование `wait_for_async_insert=0` очень рискованно, потому что ваш INSERT-клиент может не узнать о наличии ошибок, а также это может привести к перегрузке, если клиент продолжит быстро записывать данные в ситуации, когда серверу ClickHouse нужно замедлить запись и создать обратное давление, чтобы обеспечить надежность сервиса.
### Адаптивные асинхронные вставки
Начиная с версии 24.2, ClickHouse по умолчанию использует адаптивные тайм-ауты сброса буфера ([`async_insert_use_adaptive_busy_timeout`](/ru/reference/settings/session-settings#async_insert_use_adaptive_busy_timeout)). Вместо фиксированного интервала сброса тайм-аут динамически подстраивается между минимальным значением ([`async_insert_busy_timeout_min_ms`](/ru/reference/settings/session-settings#async_insert_busy_timeout_min_ms), по умолчанию 50 мс) и максимальным ([`async_insert_busy_timeout_max_ms`](/ru/reference/settings/session-settings#async_insert_busy_timeout_max_ms), по умолчанию 200 мс или 1000 мс в Cloud) в зависимости от скорости поступления данных.
Когда данные поступают часто, тайм-аут остается ближе к минимальному значению, чтобы сброс происходил раньше и уменьшалась сквозная задержка. Когда данные поступают редко, он увеличивается в сторону максимального значения, чтобы накапливать более крупные батчи. Это особенно полезно в режиме по умолчанию (`wait_for_async_insert=1`), где фиксированный большой тайм-аут заставлял бы клиентов ждать весь интервал, даже если данные уже готовы к сбросу.
### Обработка ошибок
Проверка схемы и разбор данных происходят при сбросе буфера, а не в момент получения вставки. Если в какой-либо строке запроса на вставку есть ошибка разбора данных или несоответствие типа, **никакие данные из этого запроса не сбрасываются на диск** — отклоняется вся полезная нагрузка запроса. В режиме по умолчанию (`wait_for_async_insert=1`) ошибка возвращается клиенту. В режиме fire-and-forget ошибки записываются в серверный журнал и в таблицу [`system.asynchronous_inserts`](/ru/reference/system-tables/asynchronous_inserts).
Каждый сброс создает как минимум одну часть для каждого отдельного значения ключа партиционирования в буфере. Даже для таблиц без ключа партиционирования один сброс может создать несколько частей, если объем буферизованных данных превышает [`max_insert_block_size`](/ru/reference/settings/session-settings#max_insert_block_size) (по умолчанию \~1 миллион строк).
Несмотря на использование асинхронных вставок, вы все равно можете столкнуться с ошибками ["too many parts"](/ru/resources/support-center/knowledge-base/troubleshooting/exception-too-many-parts), если ключ партиционирования имеет высокую мощность.
### Дедупликация и надежность
По умолчанию ClickHouse автоматически выполняет дедупликацию для синхронных вставок, что делает повторные попытки безопасными в случае сбоев. Однако для асинхронных вставок она отключена, если только вы не включили ее явно (ее не следует включать, если у вас есть зависимые materialized views — [см. issue](https://github.com/ClickHouse/ClickHouse/issues/66003)).
На практике, если дедупликация включена и одна и та же вставка выполняется повторно — например, из-за тайм-аута или сбоя сети, — ClickHouse может безопасно проигнорировать дубликат. Это помогает сохранять идемпотентность и избежать повторной записи данных.
### Включение асинхронных вставок
Асинхронные вставки можно включить для конкретного пользователя или для конкретного запроса:
* Включение асинхронных вставок на уровне пользователя. В этом примере используется пользователь `default`; если вы создадите другого пользователя, подставьте его имя:
```sql theme={null}
ALTER USER default SETTINGS async_insert = 1
```
* Вы можете указать настройки асинхронной вставки с помощью секции SETTINGS в запросах вставки:
```sql theme={null}
INSERT INTO YourTable SETTINGS async_insert=1, wait_for_async_insert=1 VALUES (...)
```
* Вы также можете указать настройки асинхронной вставки как параметры подключения при использовании клиентской библиотеки ClickHouse для языка программирования.
Например, вот как это можно сделать в строке подключения JDBC, если вы используете драйвер ClickHouse Java JDBC для подключения к ClickHouse Cloud:
```bash theme={null}
"jdbc:ch://HOST.clickhouse.cloud:8443/?user=default&password=PASSWORD&ssl=true&custom_http_params=async_insert=1,wait_for_async_insert=1"
```
Асинхронные вставки не применяются к запросам `INSERT INTO ... SELECT`. Если вставка содержит секцию `SELECT`, запрос всегда выполняется синхронно, независимо от настройки `async_insert`.
### Сброс буферов при завершении работы
Чтобы сбросить все буферы async insert с ожидающими записи данными — например, при корректном завершении работы или перед обслуживанием, — выполните:
```sql theme={null}
SYSTEM FLUSH ASYNC INSERT QUEUE
```
Это гарантирует, что все буферизованные данные будут записаны в хранилище перед остановкой сервера.
### Сравнение с буферными таблицами
Асинхронные вставки — современная замена [буферным таблицам](/ru/reference/engines/table-engines/special/buffer). Ключевые различия:
* **Изменения DDL не требуются.** Асинхронные вставки прозрачны — достаточно включить настройку, а не создавать дополнительные таблицы.
* **Буферизация по форме запроса.** Асинхронные вставки поддерживают отдельные буферы для каждой уникальной формы запроса и комбинации настроек, что позволяет применять более гибкие политики сброса. Буферные таблицы используют один буфер на целевую таблицу.
* **Надёжность.** В режиме по умолчанию (`wait_for_async_insert=1`) данные записываются на диск до того, как клиент получит подтверждение. Буферные таблицы работают по принципу fire-and-forget — при сбое буферизованные данные теряются.
* **Поведение в кластере.** В кластерах буферы асинхронных вставок поддерживаются на каждом узле. Для буферных таблиц их нужно явно создавать на каждом узле.