Решение проблем
Найдите симптом, прочитайте причину и примените решение. Если вашей проблемы нет в списке, откройте issue, описав, что вы делали и что произошло.
Установка и запуск
| Симптом | Причина и решение |
|---|---|
| Приложение не открывается на Intel Mac | Выпуск для macOS собран только для Apple silicon. Соберите из исходного кода на Intel |
| Сочетания клавиш из этой документации ничего не делают в Windows или Linux | Читайте Ctrl вместо ⌘: там ⌘↵ — это Ctrl+Enter |
ducklocal: command not found | Образ диска устанавливает приложение, а не команду. Слинкуйте бинарный файл в PATH |
| Терминал занят, пока открыто окно | Запуск GUI из терминала выполняется на переднем плане. Запускайте приложение из «Программ» или оставьте этот терминал ему |
| История, настройки или запомненные файлы перестают сохраняться | Работает второй экземпляр DuckLocal и держит файл данных приложения. Закройте другой и запустите заново |
| В прошлый раз DuckLocal завершился неожиданно | Он аварийно завершился и сохранил отчёт в папке журналов. Нажмите Показать отчёт и приложите его к issue — см. где что хранится |
| Не удалось проверить обновления | Наведите курсор, чтобы увидеть причину: нет сети, прокси или загрузка не совпала с контрольной суммой. Нажмите, чтобы повторить, или скачайте выпуск с GitHub — см. Проверка обновлений |
Открытие данных
| Симптом | Причина и решение |
|---|---|
File not found для указанного вами пути | Путь не существует или отсчитывается от другого каталога, чем вы думаете. Используйте абсолютный путь, чтобы быть уверенным |
| Папка сообщает, что файлов данных нет | Ничто внутри не совпало с .csv, .tsv, .txt, .parquet, .json, .ndjson, .jsonl, .xlsx, .xls, .xlsb или .ods |
| Папка дала меньше файлов, чем ожидалось | Скрытые элементы и символические ссылки пропускаются, а один запрос открытия присоединяет не более 256 файлов. Открывайте подпапки отдельно |
| Путь неожиданно открылся как база данных | Любой существующий файл, не являющийся файлом данных, рассматривается как база данных DuckDB. Если она не открывается, DuckLocal сообщает причину; при запуске он переходит к памяти. См. Открытие базы данных |
| Not attached …: the database already has a table or view named … | База данных уже содержит таблицу или представление с тем же именем, что у запомненного файла. DuckLocal никогда не заменяет её. Переименуйте или удалите одну из двух либо удалите файл из Локальных файлов и откройте снова, чтобы получить новое имя |
| Cannot restore relative path … | Файл был запомнен по относительному пути, который нельзя разрешить в новом сеансе. Удалите его из Локальных файлов и откройте снова |
Представление показывает sales_2 вместо sales | Другой файл или таблица уже имели это имя, поэтому новое получило суффикс |
| Представление файла устарело | Представления читают файл при каждом запросе. Если столбцы CSV изменили форму, используйте Обновить схему в боковой панели |
Открытие базы данных
| Симптом | Причина и решение |
|---|---|
| Сообщение говорит, что база данных создана более новой версией DuckDB | Файл использует формат хранения более новый, чем читает встроенная в DuckLocal DuckDB. Выполните строки ATTACH … COPY FROM DATABASE из сообщения в той DuckDB, которая создала файл, затем откройте копию. См. Когда база данных не открывается |
| Сообщение говорит, что база данных из DuckDB v0.9 или старше | Выполните EXPORT DATABASE 'dir' в той DuckDB, которая её записала, затем IMPORT DATABASE 'dir' в DuckLocal |
| Сообщение говорит, что это база данных SQLite | Присоедините её через Открыть → Присоединить базу данных…, а не открывайте |
| Сообщение говорит, что файл не является базой данных DuckDB | Его расширение не относится к тем, что DuckLocal читает как данные, поэтому его попробовали как базу данных. Дайте ему поддерживаемое расширение или прочитайте его в SQL, например SELECT * FROM read_csv('export.dat') |
| DuckDB сообщает, что не удалось установить блокировку файла | Другая программа — другая DuckDB, скрипт, второе приложение — держит базу данных открытой для записи, а DuckDB позволяет писать в файл только одному процессу. Закройте её там и снова откройте файл |
| DuckDB сообщает об отказе в доступе | Ваша учётная запись не может прочитать файл или не может записать его: основная база данных открывается для записи. Исправьте права на файл или присоедините его с отмеченным флажком Только для чтения |
| Открытие базы данных завершилось неудачей, и ничего не изменилось | Так и должно быть, пока DuckLocal работает: неудачное открытие оставляет рабочее пространство прежним. Прочитайте уведомление о причине |
| Подсказка в строке состояния говорит читается DuckDB v1.x+, а коллега не может открыть файл | Его DuckDB старше этой версии. Ему нужно обновиться, или вы копируете файл со старым STORAGE_VERSION — см. Какой DuckDB может прочитать базу данных |
Присоединённые базы данных
| Симптом | Причина и решение |
|---|---|
| Присоединённая база данных пропала после перезапуска | Её файла не было по запомненному пути при запуске, поэтому она была пропущена. Регистрация сохранена; верните файл на место, и он вернётся при следующем подключении |
| Эта база данных уже открыта как … | Файл уже является основной базой данных или присоединён под этим именем. Запрашивайте её по этому имени |
| Не удалось присоединить …: имя … занято в открытой базе данных. | Что-то ещё в подключении уже использует запомненный псевдоним — например, база данных, присоединённая вами в SQL под тем же именем. Выполните DETACH для неё, затем снова откройте базу данных или перезапустите |
| Запись в присоединённую базу данных не удаётся | Она была присоединена только для чтения, что и является значением по умолчанию. Используйте Отсоединить базу данных в боковой панели, затем присоедините её снова со снятым флажком Только для чтения |
| Присоединение создало пустую базу данных | Со снятым Только для чтения несуществующий путь DuckDB создаётся. Отсоедините её, удалите пустой файл и проверьте путь |
| Имя таблицы без базы данных находит не ту таблицу | Имена без базы данных разрешаются в базе данных по умолчанию. Щёлкните базу данных правой кнопкой и выберите Использовать как базу данных по умолчанию или пишите alias.table |
Finder и Quick Look
Всё это только для macOS.
| Симптом | Причина и решение |
|---|---|
Двойной щелчок по файлу .parquet или .duckdb открывает другую программу | Эта программа уже выбрана по умолчанию. В Finder: Свойства → Открыть с помощью, выберите DuckLocal, затем Изменить всё… |
| Двойной щелчок по CSV или Excel не открывает DuckLocal | Так задумано: DuckLocal не перехватывает эти форматы. Используйте Открыть с помощью → DuckLocal или перетащите файл на значок в Dock |
| DuckLocal не предлагается в Открыть с помощью, или пробел не показывает предпросмотр DuckLocal | macOS ещё не зарегистрировала приложение. Переместите его в «Программы» и запустите один раз. Для предпросмотра затем выполните qlmanage -r в Терминале и проверьте, что DuckLocal Preview включён в разделе Quick Look в настройках расширений «Настроек системы» |
Простой файл .json или файл Excel не показывает предпросмотр DuckLocal | Так задумано: они оставлены собственным предпросмотрам macOS. Файлы .jsonl и .ndjson показываются |
| Предпросмотр показывает только 50 строк | Так задумано: предпросмотр никогда не сканирует файл целиком. Откройте файл в DuckLocal, чтобы увидеть остальное |
Предпросмотр файла .duckdb показывает ошибку | Предпросмотр читает файл собственной DuckDB DuckLocal, поэтому файл из более новой DuckDB не открывается и там. См. Открытие базы данных |
Выполнение запросов
| Симптом | Причина и решение |
|---|---|
| Выполнить ничего не делает | Запрос уже выполняется. Нажмите Остановить рядом с «Выполнить» или ⌘., чтобы прервать его |
Запрос завершился ошибкой Interrupted | Кто-то нажал Остановить (или ⌘.), пока он выполнялся. Запустите его снова |
| Часть SQL подчёркнута красной волнистой линией | Там произошёл сбой при последнем выполнении. Прочитайте сообщение Запрос не выполнен; отметка исчезнет при следующем выполнении |
| ⌘↵ показывает редактор вместо выполнения | На экране первого запуска ⌘↵ означает «дайте мне редактор». Нажмите ещё раз, чтобы выполнить |
| Результаты обрываются раньше с уведомлением об усечении | Достигнут предел в 100 000 строк или 2 000 000 ячеек. Сузьте запрос; постраничного вывода нет |
| Отметки времени выглядят смещёнными | Таблица отображает отметки времени в UTC, а не в местном времени |
Значение TIMETZ потеряло смещение, а значение BIT или BIGNUM выглядит как байты | Эти типы нельзя отличить от обычных значений на пути в DuckLocal. CAST(column AS VARCHAR) в SQL покажет настоящее значение |
| Сортировка не добавляет строки за пределами предпросмотра | Сортировка по заголовку лишь переставляет загруженные строки. Используйте ORDER BY в SQL, чтобы упорядочить полный результат до усечения |
| Запросу нужно расширение, которое не установлено | Недостающие расширения больше не скачиваются автоматически. Установите его явно на вкладке Расширения, затем загрузите его или повторите запрос |
| Запрос, работавший до 0.3.0, сообщает, что расширение не установлено или функции не существует | DuckLocal 0.3.0 работает на DuckDB 2.0, которая хранит установленные расширения отдельно для каждой версии. Установите их снова на вкладке Расширения — см. Расширения |
Простой псевдоним столбца вроде minutes вызывает ошибку разбора | Это ключевое слово SQL. Напишите AS minutes или заключите его в кавычки: SELECT count(*) AS "minutes" FROM events |
| Щелчок по таблице или записи истории стёр мой SQL | Такие щелчки заменяют весь буфер редактора. Используйте новую вкладку запроса для черновой работы |
| Экспорт молча заменил файл | Экспорт пишет по указанному вами пути, не спрашивая. Выберите новое имя |
S3
| Симптом | Причина и решение |
|---|---|
| Учётные данные S3 забылись | Они действуют только в течение сеанса, так задумано, и открытие или смена базы данных их очищает. Настройте S3 заново |
| Настройка S3 не удаётся без сети | При первом использовании выполняется INSTALL httpfs, который скачивает расширение. Подключитесь один раз, и оно будет в кэше |
| Временные (STS) учётные данные отклоняются | Токен сеанса не отправляется. Используйте долгоживущие ключи — см. S3 и httpfs |
| Бакет выглядит меньше, чем есть | Перечисление останавливается на 1 000 записей на уровень. Запрашивайте шаблоном, например 's3://bucket/prefix/*.parquet' |
Дашборды
| Симптом | Причина и решение |
|---|---|
| График дашборда сообщает, что запрос должен быть только для чтения | Запрос .dash попытался писать (DDL, DML, COPY, ATTACH, …). Дашборды выполняют только инструкции чтения; перенесите подготовку в редактор SQL |
| Агент не увидел мои комментарии | Комментарии никуда не отправляются: агент должен их прочитать. Попросите его выполнить ducklocal comments FILE или «ответь на комментарии в FILE», если у него есть официальный навык |
| Ответ или правка агента не отображается | Окно следит и за спецификацией, и за FILE.comments.json в течение секунды. Спецификация, которая больше не проходит проверку, сохраняет последний рабочий дашборд, а причина показывается над ним; откройте Просмотр спецификации, чтобы увидеть файл |
PIVOT в дашборде отклоняется | PIVOT, вложенный в SELECT или WITH, должен называть свои значения. Перечислите их: PIVOT t ON channel IN ('Web', 'Store') USING sum(revenue), или начинайте запрос с PIVOT |
Внешний вид
| Симптом | Причина и решение |
|---|---|
| Тема сбрасывается на светлую при каждом запуске | Тема не сохраняется между запусками; язык сохраняется |
| Текст или значки слишком малы или слишком велики | Используйте кнопку Aa в строке заголовка или ⌘+ / ⌘− / ⌘0. См. Размер интерфейса |
| Интерфейс на неправильном языке | Используйте кнопку EN / 中 в строке заголовка; выбор запоминается |
Начать заново
Чтобы очистить историю, запомненные файлы, открытые вкладки и настройки, закройте DuckLocal и удалите каталог данных приложения:
bash
rm -rf ~/Library/Application\ Support/DuckLocalВаши файлы данных никогда не затрагиваются — удаляются только собственные записи DuckLocal. О том, что там хранится, см. в разделе Настройки и данные приложения.
