# Редактор SQL

> Редактор SQL DuckDB в DuckLocal: вкладки запросов, форматирование, ошибки в строке, автодополнение с учётом схемы, планы Explain, профилирование по операторам и сочетания клавиш.

Source: https://ducklocal.app/docs/ru/sql-editor

Каждая вкладка запроса содержит собственный буфер редактора. Редактор
подсвечивает настоящий SQL с помощью tree-sitter, делает отступ в 2 пробела и
показывает номера строк.

## Вкладки

| Элемент | Что делает |
| --- | --- |
| `+` или **⌘T** | Добавляет новую вкладку запроса и переключается на неё |
| Щелчок по вкладке | Переключается на неё |
| **Ctrl+Tab** / **Ctrl+Shift+Tab** | Следующая / предыдущая вкладка |
| **⌘1** … **⌘8**, **⌘9** | С первой по восьмую вкладку; ⌘9 — последняя вкладка |
| Перетаскивание вкладки | Перемещает её по полосе |
| `×`, **⌘W** или щелчок средней кнопкой | Закрывает вкладку. Последнюю вкладку закрыть нельзя: её `×` скрыт, а ⌘W ничего не делает. Дашборд с несохранёнными изменениями сначала спросит |
| Правый щелчок по вкладке | **Закрыть вкладку**, **Закрыть другие вкладки**, **Закрыть вкладки справа**. Дашборды с несохранёнными изменениями остаются открытыми, а уведомление сообщает, сколько их |
| Двойной щелчок по вкладке | Редактирует её заголовок на месте. Enter или щелчок в другом месте сохраняет новый заголовок, Escape оставляет старый; пустой заголовок заменяется на `Query N` |

Открытые вкладки возвращаются при следующем запуске в прежнем порядке: вкладки
запросов с заголовками и SQL в редакторах, независимо от того, выполнялись ли
они, и вкладки дашбордов. Результаты — нет; выполните запрос заново. Новая
вкладка запроса начинается с `SELECT 'Hello, DuckLocal' AS greeting;`.

## Панель инструментов

Над редактором, слева направо:

| Кнопка | Что делает |
| --- | --- |
| **Выполнить** | Выполняет SQL редактора — см. [Выполнение SQL](#running-sql) |
| **Остановить** | Появляется, когда выполнение длится уже некоторое время; прерывает его |
| **Формат** | Переформатирует SQL — см. [Форматирование](#format) |
| **Explain** | Показывает план, который использовала бы DuckDB, без выполнения инструкции |
| **Profile** | Выполняет запрос и показывает, во сколько обошёлся каждый оператор |

**Explain** и **Profile** описаны в разделе [Explain и
Profile](#explain-and-profile).

## Выполнение SQL {#running-sql}

Нажмите **⌘↵** (Cmd+Enter), когда фокус в редакторе, или используйте кнопку
**Выполнить**.

Пока запрос выполняется, повторное нажатие «Выполнить» ничего не делает (как и
Explain с Profile), а рядом с «Выполнить» появляется кнопка **Остановить**, если
запрос идёт уже некоторое время. «Остановить» или **⌘.** прерывает запрос; он
завершается ошибкой DuckDB `Interrupted`, которая, как и любой сбой, записывается
в историю. Тайм-аута нет: без остановки запрос выполняется столько, сколько нужно
DuckDB, а остальная работа с базой данных ждёт в очереди.

Результаты поступают из DuckDB потоком, поэтому сканирование прекращается, как
только достигнут [предел строк](results-and-charts.md#row-limits) таблицы, а не
дочитывает остаток файла. Запрос, которому нужно увидеть все строки до первой, —
`ORDER BY`, `GROUP BY`, агрегат, оконная функция — всё равно вычисляется
полностью.

У каждой вкладки свои результаты. Результат, пришедший после переключения
вкладок, попадает во вкладку, которая его выполнила.

То, как обрабатывается инструкция, зависит от её первого ключевого слова.
`SELECT`, `WITH`, `SHOW`, `DESCRIBE`, `EXPLAIN`, `PRAGMA`, `SUMMARIZE`, `VALUES`,
`FROM`, `TABLE`, `PIVOT` и `CALL` дают набор результатов. Всё остальное —
инструкции DDL (определение данных) и DML (изменение данных) — вместо таблицы
сообщает `Done: N rows affected, took …`. Ведущие комментарии `--` при
определении пропускаются, блочные комментарии — нет.

### Скрипты

Редактор может содержать несколько инструкций. **Выполнить** выполняет их все по
порядку так, как оболочка DuckDB читает файл, и **останавливается на первой
ошибке**: выполнение `SELECT` после неудачного `ATTACH` лишь добавило бы вторую,
вводящую в заблуждение ошибку. Полоса над результатами перечисляет инструкции, у
каждой — число строк, *готово*, *ошибка* или *не выполнялась*; щёлкните по ней,
чтобы увидеть её результат. Ошибка подчёркивает инструкцию, в которой произошёл
сбой, а не весь скрипт.

Некоторые команды оболочки с точкой тоже работают, каждая на отдельной строке:

| Команда | Показывает |
| --- | --- |
| `.tables ?PATTERN?` | Таблицы и представления, при необходимости отфильтрованные шаблоном `ILIKE`, например `stat%` |
| `.schema ?PATTERN?` | Инструкции `CREATE` таблиц и представлений, при необходимости отфильтрованные |
| `.databases` | Присоединённые базы данных |
| `.help` | Этот список |

Любая другая команда с точкой (`.mode`, `.read`, …) — ошибка, в которой
перечислены работающие команды.

## Ошибки

Неудачная инструкция показывает предупреждение с заголовком *Запрос не выполнен* и
дословным сообщением DuckDB. Сообщение приходит от движка и всегда на английском,
независимо от языка интерфейса. В таблицу ничего не записывается, а попытка всё
равно фиксируется в [истории](schema-and-history.md) с отметкой об ошибке.

Когда сообщение указывает на позицию — так делают ошибки разбора и привязки, со
строкой `LINE n:` и знаком вставки, — редактор подчёркивает это место красной
волнистой линией: лексему, на которую указывает знак, или диапазон, который
покрывает цепочка знаков. Отметка следует за вашими правками и исчезает при
следующем выполнении. Ошибки времени выполнения не содержат позиции и отметки не
получают.

## Форматирование {#format}

**Формат** пропускает буфер через `sqlformat` с отступом в 2 пробела и ключевыми
словами в верхнем регистре, затем заменяет весь буфер. На пустом буфере ничего не
делает.

## Explain и Profile {#explain-and-profile}

Обе кнопки работают со всем текстом редактора, и обе принимают **ровно одну
инструкцию**. Если их две или больше — или если это команда с точкой, — они
отказываются: *Explain и Profile принимают одну инструкцию: поместите ту, которую
нужно посмотреть, в отдельную вкладку.* Завершающая `;` и завершающие
комментарии допустимы.

Пока занято одно из действий — «Выполнить», Explain или Profile, — два других
ничего не делают. Ни Explain, ни Profile не записываются в
[историю](schema-and-history.md#query-history). Их вывод заменяет таблицу на
вкладке **Результаты**, переключая на неё, если была открыта другая; при сбое
показывается предупреждение *Запрос не выполнен*, как и при неудачном выполнении.

### Explain

**Explain** выполняет `EXPLAIN <ваша инструкция>` и показывает план DuckDB в виде
обычного моноширинного текста с затраченным временем. Он только строит план:
инструкция не выполняется, поэтому объяснять `INSERT`, `UPDATE` или `DELETE`
безопасно.

### Profile

**Profile** выполняет инструкцию под `EXPLAIN (ANALYZE, FORMAT JSON)` и
показывает исполненный план в виде дерева: собственное время каждого оператора и
его долю в общем времени, выпущенные им строки в сравнении с оценкой оптимизатора
(помечаются при расхождении более чем в 10 раз), а также что он отфильтровал, по
чему соединял или что проецировал. Самый дорогой оператор назван вверху и выделен
красным. Как читать: [Вывод Explain и
Profile](results-and-charts.md#explain-and-profile).

**Профилирование действительно выполняет инструкцию** — именно так замеряется
время её операторов. Поэтому оно принимает только один запрос для чтения:

- **Принимается:** `SELECT`, `WITH … SELECT`, `FROM …`, `VALUES`, `TABLE`,
  `SHOW`, `DESCRIBE`, `SUMMARIZE`.
- **Отклоняется:** всё, что пишет (`INSERT`, `UPDATE`, `DELETE`,
  `CREATE`, …), `CALL`, `PRAGMA`, `COPY`, сам `EXPLAIN`, запись, скрытая
  за `WITH` (`WITH s AS (…) INSERT …`), и `PIVOT` без явного
  списка `IN (…)`.

Для отклонённой инструкции выводится *Профилировать можно только читающие
инструкции (SELECT, WITH, FROM…): профилирование выполняет инструкцию.* Это
решает собственный парсер DuckDB до какого-либо выполнения, а не первое ключевое
слово.

Профилирование длится столько же, сколько запрос, плюс затраты на измерение.
**Остановить** (или **⌘.**) прерывает его так же, как выполнение.

## Автодополнение

Меню дополнения учитывает каталог. Кандидаты ранжируются:

1. Таблицы и столбцы из схемы (до 35 записей)
2. Имена функций DuckDB
3. Ключевые слова SQL

Предлагается не более 50 элементов. Сопоставление — **по префиксу** без учёта
регистра с идентификатором непосредственно слева от курсора, поэтому `sel`
дополняется до `SELECT`, а `elect` — ни до чего. Функция вставляет своё имя и
открывающую скобку; идентификаторы, содержащие пробелы или специальные символы,
вставляются в двойных кавычках.

Списки ключевых слов и функций — отобранное подмножество: появятся не все функции
DuckDB.

## Сочетания клавиш

В Windows и Linux везде читайте **Ctrl** вместо **⌘**.

Собственные сочетания DuckLocal, все перечислены в строке меню:

| Сочетание | Действие |
| --- | --- |
| ⌘↵ | Выполнить запрос |
| ⌘. | Остановить выполняющийся запрос |
| ⌘T | Новая вкладка запроса |
| ⌘W | Закрыть вкладку |
| Ctrl+Tab / Ctrl+Shift+Tab | Следующая / предыдущая вкладка (Ctrl и на Mac) |
| ⌘1 … ⌘9 | Перейти к вкладке на этом месте; ⌘9 — последняя |
| ⌘O | Открыть данные |
| ⌘S | Сохранить исходник дашборда в его представлении исходника |
| ⌘B | Скрыть или показать боковую панель |
| ⌘+ / ⌘− / ⌘0 | Сделать интерфейс крупнее / мельче / размера по умолчанию — см. [Размер интерфейса](settings-and-data.md#interface-size) |
| ⌘Q | Завершить |

Собственные сочетания редактора, которые ведут себя как в любом текстовом поле:

| Сочетание | Действие |
| --- | --- |
| ⌘F / ⇧⌘F | Поиск / замена в редакторе |
| ⌘Z / ⇧⌘Z | Отменить / повторить |
| ⌘A | Выбрать всё |
| ⌘C / ⌘X / ⌘V | Копировать / вырезать / вставить |
| ⌥⌘↑ / ⌥⌘↓ | Добавить курсор выше / ниже |
| ⌘← / ⌘→ / ⌥← / ⌥→ | Перемещение по строкам / словам |
| ⌘↑ / ⌘↓ | Перейти к началу / концу документа |
| ⌘⌫ / ⌥⌫ | Удалить до начала строки / предыдущее слово |

## Меню

Строка меню содержит все команды окна с их сочетаниями клавиш:

| Меню | Команды |
| --- | --- |
| DuckLocal | Командная строка и ИИ, Проверить обновления…, Проверять обновления при запуске, Показать руководство, Открыть папку журналов, Завершить DuckLocal |
| File | Новый запрос, Открыть данные, Сохранить, Закрыть вкладку, Следующая вкладка, Предыдущая вкладка |
| Edit | Отменить, Повторить, Вырезать, Копировать, Вставить, Выбрать всё |
| Query | Выполнить, Остановить |
| View | Показать или скрыть боковую панель, Увеличить интерфейс, Уменьшить интерфейс, Размер по умолчанию, Онлайн-подложка (OpenStreetMap) |

В Windows и Linux строки меню нет; там **Показать руководство** и **Открыть папку
журналов** находятся в контекстном меню версии в правом конце строки состояния.

**Онлайн-подложка (OpenStreetMap)** — это пункт с флажком; см.
[Графики](results-and-charts.md#charts). У строк в боковой панели схемы тоже есть
контекстное меню; см. [Обозреватель схемы и
история](schema-and-history.md#right-click-menu). Палитры команд нет.
