---
metadata:
  - name: generator
    content: Diplodoc Platform v5.50.4
alternate:
  - https://ydb.tech/docs/en/dev/streaming-query/checkpoints.md
  - https://ydb.tech/docs/ru/dev/streaming-query/checkpoints.md
sourcePath: ru/core/dev/streaming-query/checkpoints.md
---
> **Documentation Index:** Fetch the complete configuration index at https://ydb.tech/docs/ru/llms.txt

# Чекпоинты

Чекпоинт — это сохранённое состояние работающего [потокового запроса](https://ydb.tech/docs/ru/concepts/streaming-query/streaming-query.md), необходимое для восстановления после сбоев обработки. YDB периодически сохраняет чекпоинты всех запущенных потоковых запросов.

## Содержимое чекпоинта {#contents}

Чекпоинт содержит:

- [смещения](https://ydb.tech/docs/ru/concepts/datamodel/topic.md#consumer-offset) во входных топиках — позиции, до которых события были прочитаны и обработаны;
- состояния агрегаций — промежуточные результаты операций, например накопленные значения в [GROUP BY HOP](https://ydb.tech/docs/ru/yql/reference/syntax/select/group-by.md#group-by-hop).

YDB хранит смещения чтения в собственных чекпоинтах, а не полагается на смещения [потребителя (consumer)](https://ydb.tech/docs/ru/concepts/datamodel/topic.md#consumer) во внешней системе. Это означает, что при удалении запроса ([DROP STREAMING QUERY](https://ydb.tech/docs/ru/yql/reference/syntax/drop-streaming-query.md)) смещения удаляются вместе с чекпоинтом — внешняя система не знает, до какого места запрос дочитал топик.

## Восстановление после сбоя {#recovery}

При сбое обработки (перезапуск вычислительного узла, сетевой разрыв, таймаут) запрос автоматически перезапускается и восстанавливает состояние из последнего чекпоинта: возобновляет чтение с сохранённых смещений и восстанавливает состояния агрегаций.

```mermaid
sequenceDiagram
    participant Топик
    participant Запрос as Запрос<br/>GROUP BY HOP (1 мин)
    participant Приемник

    Note over Запрос: Чекпоинт сохранён<br/>смещение = 2, sum = 10
    Топик->>Запрос: value = 3 (смещение 3)
    Note over Запрос: sum = 13
    Топик->>Запрос: value = 7 (смещение 4)
    Note over Запрос: sum = 20
    Запрос-xЗапрос: Сбой обработки
    Note over Запрос: Восстановление из чекпоинта<br/>смещение = 2, sum = 10
    Топик->>Запрос: value = 3 (повторно)
    Note over Запрос: sum = 13
    Топик->>Запрос: value = 7 (повторно)
    Note over Запрос: sum = 20
    Note over Запрос: Окно закрыто
    Запрос->>Приемник: sum = 20
```

События, поступившие между последним чекпоинтом и моментом сбоя, будут обработаны повторно. Это обеспечивает гарантию [at-least-once](https://ydb.tech/docs/ru/dev/streaming-query/guarantees.md#at-least-once) — каждое событие будет обработано минимум один раз.

Сохранение и выбор чекпоинта для восстановления происходит автоматически. Старые чекпоинты удаляются после успешного сохранения нового.

## Удаление чекпоинта при пересоздании запроса {#drop-checkpoint}

При удалении запроса ([DROP STREAMING QUERY](https://ydb.tech/docs/ru/yql/reference/syntax/drop-streaming-query.md)) чекпоинт удаляется вместе с ним. Поскольку смещения хранятся только в чекпоинте, новый запрос ([CREATE STREAMING QUERY](https://ydb.tech/docs/ru/yql/reference/syntax/create-streaming-query.md)) не имеет сохранённой позиции и начинает чтение с конца топика. Все события, поступившие в топик между удалением старого запроса и стартом нового, не будут прочитаны.

```mermaid
sequenceDiagram
    participant Топик
    participant Запрос v1
    participant Запрос v2

    Топик->>Запрос v1: События A..D
    Note over Запрос v1: Чекпоинт: смещение = 4
    Note over Запрос v1: DROP STREAMING QUERY<br/>(чекпоинт удалён)
    Note over Топик: События E, F поступают в топик
    Note over Запрос v2: CREATE STREAMING QUERY<br/>(старт с конца топика)
    Топик--xЗапрос v2: E, F (не прочитаны)
    Топик->>Запрос v2: G (новое)
```

Аналогичная ситуация возникает, если данные, на которые указывает смещение в чекпоинте, уже удалены из топика по [TTL](https://ydb.tech/docs/ru/concepts/datamodel/topic.md#message-retention).

Подробнее о влиянии этого поведения на гарантии доставки — в разделе [Потеря событий при пересоздании запроса](https://ydb.tech/docs/ru/dev/streaming-query/guarantees.md#incomplete-windows-restart).

## Отключение чекпоинтов {#disable}

Для снижения накладных расходов можно отключить сохранение чекпоинтов с помощью прагмы `ydb.DisableCheckpoints`.

{% note warning %}

При отключении чекпоинтов отсутствуют гарантии консистентности данных при пользовательских или внутренних перезапусках запроса. Используйте исключительно для отладки.

{% endnote %}

```sql
CREATE STREAMING QUERY query_without_checkpoints AS
DO BEGIN

PRAGMA ydb.DisableCheckpoints = "TRUE";

INSERT INTO
    ydb_source.output_topic
SELECT
    *
FROM
    ydb_source.input_topic;

END DO
```

## См. также

- [Гарантии доставки данных](https://ydb.tech/docs/ru/dev/streaming-query/guarantees.md) — гарантии доставки данных и наблюдаемые аномалии.
- [Потоковые запросы](https://ydb.tech/docs/ru/concepts/streaming-query/streaming-query.md) — общее описание потоковых запросов.