# Обозреватель схемы и история

> Просматривайте базы данных, таблицы и столбцы в боковой панели схемы DuckLocal, создавайте запросы SELECT, управляйте расширениями DuckDB и повторно используйте прошлые запросы.

Source: https://ducklocal.app/docs/ru/schema-and-history

В боковой панели три вкладки: **Схема**, **История** и **Расширения**
(по-китайски **表结构**, **查询历史** и **扩展**). Кнопка слева в строке заголовка
или **⌘B** скрывает боковую панель и возвращает её; кнопка в любом случае остаётся
на месте. Скрыта ли боковая панель, запоминается.

## Дерево схемы

Сверху вниз дерево показывает **Локальные файлы**, **Дашборды**, **Метрики** и **S3** как
небольшие серые заголовки разделов, за которыми идут ваши базы данных жирными
строками:

- **Локальные файлы** — зарегистрированные файлы данных, каждый назван по своему
  представлению, с числом строк. Его дочерние элементы — столбцы представления.
  - Имя файла показывается рядом с именем представления, только если они
    различаются (`sales_2` из `sales.csv`).
  - Папка показывается, когда два файла имеют одно имя представления.
  - Наведите на строку, чтобы увидеть полный путь.
- **Дашборды** — дашборды `.dash`, которые вы недавно открывали, отсортированные
  по имени, чтобы строка не смещалась при щелчке.
  - Щёлкните по одному, чтобы снова открыть его вкладкой, как файл.
  - У двух дашбордов с одинаковым именем рядом показывается папка. Один файл,
    доступный по двум вариантам написания пути (`E:\Proj` и `E:\proj`, или
    относительный и абсолютный путь), — это одна запись, и открывает он одну
    вкладку.
  - Крестик × при наведении убирает его из списка, не трогая его файлы и открытую
    вкладку.
  - Запись, путь которой больше не существует, удаляется из списка.
- **Метрики** — появляется, когда рядом с одним из этих дашбордов лежит
  `model.ossie.yaml`. По строке на метрику; щелчок компилирует её в редактор
  запросов и запускает. См. [Семантические метрики](metrics.md#sidebar). Новее
  0.4.1.
- **S3** — появляется после [настройки S3](s3.md). Загружается лениво.
- Затем каждая база данных, её схемы, таблицы и представления, столбцы. База
  данных, с которой открылось окно, идёт первой; базы данных,
  [присоединённые рядом с ней](data-sources.md#attached-databases), следуют за
  ней и помечаются `read-only`, если присоединены так.

Таблицы показывают оценочное число строк; представления — нет. Записи столбцов
показывают типы данных DuckDB. Системная база данных и схемы `information_schema`,
`pg_catalog` и `system` скрыты.

Поле поиска над деревом (**Поиск таблиц и столбцов**) оставляет только строки,
имена которых содержат введённый текст без учёта регистра, и строки над ними. У
таблицы, чьё имя совпало, сохраняются все столбцы; таблица, оставленная из-за
совпавшего столбца, раскрывается, чтобы показать его. Очистите поле, чтобы вернуть
всё дерево.

### Базы данных {#databases}

Открытая база данных идёт первой, затем каждая
[присоединённая база данных](data-sources.md#attached-databases) — отдельной
группой, с числом таблиц рядом с именем.

- Присоединённая база данных показывается, даже когда она пуста. Открытая база
  данных не показывается, пока в ней нет таблиц, — именно так начинается новый
  сеанс в памяти.
- Приглушённая подсказка рядом с именем сообщает **только для чтения**, а если это
  не DuckDB, то и тип файла (**sqlite**).
- Наведите на имя, чтобы увидеть путь к файлу базы данных.

Щёлкните базу данных правой кнопкой, чтобы сделать её базой данных по умолчанию
или отсоединить — см. [Контекстное меню](#right-click-menu).

Кнопка обновления рядом с вкладками (**Обновить схему**) перезагружает каталог и
список зарегистрированных файлов.

## Генерация SELECT

Все перечисленные ниже щелчки **заменяют весь буфер** активной вкладки — они не
вставляют текст в позицию курсора. То же относится к щелчку по записи истории.
Сохраните всё важное, прежде чем щёлкать.

При щелчке в активный редактор попадает:

| Щелчок | Сгенерированный SQL |
| --- | --- |
| Кнопка воспроизведения у таблицы | `SELECT * FROM db.schema.table LIMIT 100;` |
| Флажок столбца или его имя | `SELECT col FROM db.schema.table LIMIT 100;` |
| Дополнительные столбцы той же таблицы | `SELECT a, b FROM db.schema.table LIMIT 100;` |
| Объект S3, являющийся файлом данных | `SELECT * FROM 's3://bucket/key' LIMIT 100;` |

У каждого столбца — таблицы, представления или локального файла — есть флажок.
Отметка столбцов или щелчок по их именам, который их отмечает, строит `SELECT` из
отмеченных столбцов в порядке столбцов таблицы, а не в том порядке, в каком вы их
отмечали. Если снять отметку с последнего, получится `SELECT *`. Отметки
принадлежат одной таблице: отметка столбца другой таблицы начинает всё заново там.

Сгенерированный SQL занимает три строки (`SELECT …`, `FROM …`, `LIMIT 100;`).
Имена таблиц записываются настолько кратко, насколько позволяют текущая база
данных и схема по умолчанию: `orders` для таблицы в схеме по умолчанию,
`main.orders` для другой схемы той же базы данных и `database.schema.table` в
остальных случаях. После **Использовать как базу данных по умолчанию** для `snap`
предпросмотр одной из его таблиц читается как `FROM orders`. Пока не выполнен
первый запрос, имена указываются полностью.

Имя заключается в двойные кавычки, только когда содержит символы, отличные от
букв, цифр и подчёркиваний.

## Контекстное меню {#right-click-menu}

Каждая команда, которую предлагают кнопки при наведении на строку, есть и в её
контекстном меню, поэтому команду можно найти без наведения:

| Строка | Меню |
| --- | --- |
| Таблица или представление | Сгенерировать запрос SELECT, Обзор столбцов, Копировать имя, Копировать сведения о таблице |
| Столбец | Сгенерировать запрос SELECT, Копировать имя, Изменить тип данных… (только столбцы таблиц) |
| Присоединённая база данных | Использовать как базу данных по умолчанию, Отсоединить базу данных |
| Список бакетов S3 | Обновить бакеты |
| Недавний дашборд | Удалить из списка |
| Локальный файл | Сгенерировать запрос SELECT, Обзор столбцов, Копировать имя, Копировать сведения о таблице, Удалить из локальных файлов |

**Копировать имя** копирует голое имя — только имя таблицы, столбца или
представления, без базы данных и схемы и без кавычек.

**Копировать сведения о таблице** копирует всю таблицу в виде Markdown, готового
для вставки в чат, issue или запрос к ИИ-агенту: имя, которое использует запрос,
что это такое, его размер и каждый столбец с типом:

```md
memory.main.orders (table, ~224 rows, 3 columns)

| column | type |
|---|---|
| date | DATE |
| channel | VARCHAR |
| revenue | DOUBLE |
```

**Обзор столбцов** заменяет текст активного редактора на `FROM <table>;`,
выполняет его и открывает панель результатов на её вкладке **Обзор**, которая
сводит воедино каждый столбец всей таблицы: null-значения, уникальные значения,
диапазон и небольшой график по его значениям. См. [Обзор
столбцов](results-and-charts.md#overview).

**Использовать как базу данных по умолчанию** выполняет `USE` для этой базы
данных, поэтому имена таблиц без базы данных разрешаются там, а сгенерированные
запросы становятся короче (см. выше). Для базы данных, которая уже является
базой данных по умолчанию, пункт не предлагается.

**Отсоединить базу данных** отсоединяет присоединённую базу данных и забывает её,
поэтому в следующий раз она не присоединяется. Если она была базой данных по
умолчанию, сеанс сначала переходит к другой. Файл не затрагивается. Саму
открытую базу данных отсоединить нельзя, поэтому в её меню такого пункта нет.
Подробнее в разделе [Присоединённые
базы данных](data-sources.md#attached-databases).

## Изменение типа столбца

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

```sql
ALTER TABLE db.schema.table ALTER COLUMN col SET DATA TYPE <what you typed>
```

Здесь имя таблицы всегда указывается полностью, а имя столбца заключается в
кавычки, только когда это необходимо.

Средства выбора и списка проверки нет — подходит любая строка типа DuckDB,
включая параметризованные, такие как `DECIMAL(10,2)`. Неверный тип возвращается
уведомлением об ошибке. При успехе каталог перезагружается.

Переименование и удаление столбцов, а также правка комментариев к столбцам
недоступны.

## Удаление зарегистрированного файла

**×** в строке файла запрашивает подтверждение, затем уничтожает представление и
забывает регистрацию. **Файл на диске не затрагивается.**

Чтобы удалить несколько регистраций сразу, выделите их строки в **Локальных
файлах**:

- **⌘-щелчок** в macOS или **Ctrl-щелчок** в Windows/Linux добавляет или убирает
  один файл из выделения.
- **Shift-щелчок** выделяет последовательный диапазон.
- Нажмите **×** у выделенного файла или воспользуйтесь действием удаления в
  контекстном меню, чтобы подтвердить удаление выделенных регистраций. В меню
  показано, сколько файлов будет удалено.

Так удаляются представления и регистрации, а исходные файлы остаются на диске.
Такое выделение файлов не выделяет таблицы базы данных или фильтры дашборда.

## Расширения {#extensions}

Вкладка **Расширения** перечисляет все расширения DuckDB, известные движку:
сначала загруженные, затем установленные, затем остальные, каждая группа по
имени.

Каждая строка показывает:

- имя расширения и тег состояния: **Загружено**, **Установлено** или
  **Не установлено**;
- однострочное описание от DuckDB;
- версию и источник: **встроено** или репозиторий, из которого оно установлено
  (`core`, `community` или URL).

Что означают состояния:

| Состояние | Значение |
| --- | --- |
| Загружено | Активно в текущем подключении: его функции, читатели и типы работают в запросах сейчас |
| Установлено | Скачано на этот компьютер, но не загружено в это подключение |
| Не установлено | Известно DuckDB, но пока отсутствует на этом компьютере |

**Встроенные** расширения скомпилированы в DuckLocal — среди них `parquet` и
`json`, оба загружены с самого начала. Их никогда не устанавливают и не
обновляют.

Расширения сообщества устанавливаются так же. Начиная с 0.4.1 вкладка обращается
и к репозиторию сообщества DuckDB, и к основному, поэтому такое расширение, как
`mssql` (SQL Server), можно установить и загрузить, не выходя из приложения; тег
репозитория в строке будет `community`.

Строка предлагает действия, которые к ней применимы:

| Кнопка | Показывается, когда | Выполняет |
| --- | --- | --- |
| **Установить** | Не установлено | `INSTALL name` |
| **Загрузить** | Установлено, не загружено | `LOAD name` |
| **Обновить** | Установлено из репозитория | `UPDATE EXTENSIONS (name)` |

- **Установить** и **Обновить** скачивают из репозитория расширений DuckDB,
  поэтому им нужна сеть. **Загрузить** читает установленный файл и сети не
  требует.
- Установка не загружает. После неё нажмите **Загрузить** или выполните
  `LOAD name`.
- Установленное расширение остаётся установленным: это файл на диске, в
  собственной папке расширений DuckDB. Загрузка действует только для текущего
  подключения.
- Эта папка зависит от версии DuckDB (`~/.duckdb/extensions/v2.0.0/…`). Когда
  обновление переводит DuckLocal на новую версию DuckDB, как 0.3.0 сделала с
  DuckDB 2.0, имевшиеся расширения отображаются как **Не установлено**, пока вы
  не установите их снова.
- Одновременно выполняется одно действие; остальные кнопки на это время
  недоступны. Уведомление сообщает *Установлено …*, *Загружено …* или
  *Обновлено …* либо причину сбоя.
- После загрузки или обновления дерево схемы перезагружается, так как расширение
  может принести с собой таблицы и функции.

Список читается из `duckdb_extensions()` каждый раз при открытии вкладки, после
каждого действия, при смене подключения, пока вкладка открыта, и при нажатии
кнопки обновления рядом с вкладками (**Обновить расширения**). Поэтому он
показывает и расширение, загруженное другим способом — через `LOAD`, введённый во
вкладке запроса, или самим DuckDB.

Начиная с v0.2.1 ни окно, ни CLI не скачивают недостающее расширение
автоматически, когда оно нужно запросу. Установите его явно в **Расширениях** или
через `INSTALL name`. Расширения, уже установленные на этом компьютере, по-прежнему
могут загружаться автоматически.

### Открытие DuckDB UI {#duckdb-ui}

[DuckDB UI](https://duckdb.org/2025/03/12/duckdb-ui) — собственный блокнот DuckDB
для браузера, созданный MotherDuck, — это расширение, как и любое другое, поэтому
оно работает и внутри DuckLocal:

1. На вкладке **Расширения** нажмите **Установить** в строке `ui`, затем
   **Загрузить**.
2. Во вкладке запроса выполните:

   ```sql
   CALL start_ui();
   ```

   Ваш браузер откроет UI по адресу `http://localhost:4213`. Чтобы запустить
   сервер, не открывая браузер, выполните вместо этого `CALL start_ui_server();`.

![Вкладка «Расширения» с загруженным расширением ui](../assets/duckdb-ui.png)

UI работает на том экземпляре DuckDB, из которого был запущен, — здесь это
экземпляр DuckLocal. Кое-что стоит знать:

- **Ей нужна сеть.** Установка `ui` скачивает её, как любое расширение. И при
  каждом запуске локальный сервер расширения загружает собственные файлы UI с
  `https://ui.duckdb.org`. Ваши запросы и данные по-прежнему выполняются локально.
- **Она живёт, пока жив DuckLocal.** Завершение DuckLocal закрывает его экземпляр
  DuckDB, а вместе с ним и сервер. `CALL stop_ui_server();` останавливает его
  раньше.
- **Блокноты сохраняет расширение, а не DuckLocal,** в
  `~/.duckdb/extension_data/ui/`. История запросов DuckLocal не включает то, что
  вы выполняете в UI.
- **Она не может работать напрямую с базой данных только для чтения.**
  Присоедините такую базу данных из блокнота через `ATTACH '…' (READ_ONLY)`.

[DuckDB UI vs DuckLocal](https://ducklocal.app/ru/blog/duckdb-ui-vs-ducklocal/)
сравнивает оба варианта и объясняет, когда какой использовать.

## История запросов {#query-history}

Каждое выполнение записывается — и успешное, и неудачное — с отметкой времени по
местному времени, длительностью в миллисекундах, числом строк (или числом
затронутых строк для DML) и текстом ошибки, если она была. Неудачные записи
показываются красным с тегом *Ошибка*.

Список показывает последние **200** записей. Щелчок по строке снова заполняет
активный редактор этим SQL и ставит на него фокус, заменяя то, что там было.

Политики хранения и очистки нет: таблица истории растёт без ограничений, а
интерфейс просто показывает последние 200 записей. Также нет поиска, фильтра,
экспорта и способа удалить запись из интерфейса.

История хранится в собственном файле базы данных DuckLocal, а не в открытой вами
базе данных, поэтому переживает смену баз данных и потерю рабочего пространства.
О том, где она лежит, см. в разделе [Настройки и данные
приложения](settings-and-data.md).
