Источники данных
DuckLocal превращает файлы в представления в подключении DuckDB в памяти — или в файле базы данных, если вы его открыли. Рядом могут находиться другие базы данных. Настраивать ничего не нужно. Краткий путь от файлов к SQL, графикам и экспорту описан в сценарии локального анализа данных.
Способы открыть данные
Все они подчиняются одним и тем же правилам разрешения путей:
- Пути в командной строке —
ducklocal ./logs/ billing.parquet - Меню Открыть в строке заголовка: Открыть файлы, Открыть папку или Ввести путь или шаблон, которое открывает диалог Открыть данные для введённого пути или пути, выбранного в системном средстве выбора
- Перетаскивание файлов или папок в любое место окна
- На Mac — файлы, которые Finder передаёт DuckLocal; см. Открытие из Finder
Чтобы добавить базу данных рядом с открытой, а не заменить её, используйте Открыть → Присоединить базу данных… — см. Присоединённые базы данных.
В macOS можно дважды щёлкнуть файлы Parquet и DuckDB в Finder, чтобы открыть их, или нажать пробел, чтобы без запуска DuckLocal посмотреть в Quick Look первые строки файлов Parquet, DuckDB, CSV, TSV и JSON Lines.
Поддерживаемые форматы файлов
Расширения сопоставляются без учёта регистра.
| Расширение | Как читается |
|---|---|
.csv, .tsv, .txt | представление read_csv_auto |
.parquet | представление read_parquet |
.json, .ndjson, .jsonl | представление read_json_auto |
.xlsx, .xls, .xlsb, .ods | импортируется как таблица на каждый лист |
Текст, сжатый gzip, например .json.gz и .csv.gz, тоже считается файлом данных — в блоках schema, source и при присоединении файла; logs.json.gz становится представлением с именем logs. До 0.4.0 ducklocal schema пытался открыть такой файл как базу данных; в более старой версии читайте его в SQL через read_json или read_csv.
Всё остальное не является файлом данных — см. Файлы баз данных.
Книга Excel — единственный формат, который становится таблицами, а не представлениями, и импортирует каждый лист: первый лист получает имя файла без расширения, остальные называются {stem}_{sheet name}. Пустой лист пропускается. Типы столбцов определяются по ячейкам: целые числа становятся BIGINT, смесь целых и дробных — DOUBLE, даты — TIMESTAMP, а всё смешанное или нераспознанное — VARCHAR; пустые ячейки импортируются как NULL.
Папки и шаблоны
Каталог обходится рекурсивно, и каждый файл данных внутри становится представлением. При обходе действуют два правила:
- Скрытые элементы (имена, начинающиеся с
.) пропускаются, и в их поддеревья обход не заходит. - Символические ссылки не разыменовываются. Переход по ссылке вверх по дереву никогда бы не завершился, а каталог, на который указывает ссылка, обычно обходится там, где он действительно находится.
Файлы присоединяются в отсортированном порядке, поэтому одна и та же папка всегда даёт одно и то же рабочее пространство.
Шаблон может содержать * (любая последовательность символов) и ? (ровно один символ). Сопоставление выполняется по компонентам пути в файловой системе, поэтому шаблон может охватывать несколько каталогов:
ducklocal './data/2026-0*/*.parquet'Символа экранирования нет. ** не имеет особого смысла — ведёт себя как один * и не выполняет рекурсию. Шаблон, совпадающий с каталогом, пропускает его; присоединяются только файлы. Скрытые элементы здесь тоже пропускаются.
Шаблоны без кавычек раскрывает ваша оболочка ещё до того, как их увидит DuckLocal. Это нормально. Заключайте шаблон в кавычки, только если хотите, чтобы его раскрыл DuckLocal, — например, когда оболочка не находит совпадений и иначе выдала бы ошибку.
Много файлов CSV одновременно
Каждый присоединённый файл становится отдельным представлением с собственной определённой схемой, поэтому два несовпадающих CSV не ломают друг друга. Подводные камни появляются, когда одно чтение SQL охватывает много файлов:
SELECT * FROM read_csv('data/*.csv', union_by_name = true)Определение типов может расходиться между файлами. Читатель выводит тип столбца по выборке; столбец, который везде числовой, но в одном файле содержит случайную строку
'NULL', ломает всё чтение ошибкой преобразования, а приведение типа в спискеSELECTпроисходит слишком поздно — ошибка возникает при самом чтении. Читайте все столбцы как текст и приводите типы в SQL:sqlSELECT try_cast(amount AS DOUBLE) AS amount FROM read_csv('data/*.csv', union_by_name = true, all_varchar = true)union_by_name = trueтакже допускает файлы с разными наборами столбцов.Строка
'NULL'— это неNULL. Литерал'NULL'(или'N/A','null') в CSV — обычный текст, поэтомуWHERE amount IS NOT NULLего не отфильтрует. ИспользуйтеNULLIF(amount, 'NULL')илиWHERE amount <> 'NULL'.
Оба приёма сочетаются: try_cast(NULLIF(amount, 'NULL') AS DOUBLE).
Файлы баз данных
В DuckLocal одновременно есть одна основная база данных: в памяти или файл DuckDB, который вы открыли. Файлы данных становятся представлениями в основной базе данных. Кроме того, можно присоединить другие базы данных рядом с ней.
Любой существующий путь, который не является файлом данных, открывается как основная база данных, а не присоединяется как представление. Расширение не важно: путь .db, .duckdb или даже .md рассматривается как база данных, а DuckDB решает, можно ли её действительно открыть.
Стоит знать о нескольких последствиях:
- Новая база данных создаётся только из диалога «Открыть данные». Введите путь, оканчивающийся на
.duckdbи ещё не существующий, и DuckLocal создаст базу данных вместе с недостающими родительскими папками. Везде ещё — в командной строке, средствах выбора, при перетаскивании, в Finder — несуществующий путь сообщается какFile not found. - Открытие базы данных заменяет основную. Зарегистрированные файлы и присоединённые базы данных присоединяются заново к новому подключению. Учётные данные S3 — нет; настройте S3 заново.
- Если файл не удаётся открыть, DuckLocal сообщает причину (ниже). При запуске он переходит к рабочему пространству в памяти, а не завершается с ошибкой. Пока он работает, текущее рабочее пространство остаётся как было.
- Файл, который уже присоединён рядом с основной базой данных, сначала отсоединяется, а затем открывается как основная. Если открыть не удалось, присоединение возвращается. Открытие файла, который уже является основной базой данных, переиспользует его.
Присоединение файлов данных при открытом файле базы данных записывает эти представления в сам файл базы данных — они сохраняются там, а не только в сеансе.
Когда база данных не открывается
Когда DuckDB отклоняет файл, DuckLocal сам читает первые байты и, если они объясняют сбой, помещает причину и путь решения над собственным сообщением DuckDB. Сообщение DuckDB остаётся ниже для точной ошибки. Объяснение даётся на языке интерфейса.
| Что это за файл | Что сообщает DuckLocal |
|---|---|
| Файл DuckDB, записанный более новой версией DuckDB, чем встроенная в DuckLocal | Обе версии и SQL, который нужно выполнить в более новой DuckDB, чтобы скопировать файл в формат, понятный DuckLocal (ниже) |
| Файл DuckDB v0.9 или старше | Выполните EXPORT DATABASE 'dir' в той DuckDB, которая его записала, затем IMPORT DATABASE 'dir' в DuckLocal |
| База данных SQLite | Это не файл DuckDB; присоедините её — через Присоединить базу данных… или INSTALL sqlite; ATTACH '…' (TYPE sqlite); |
| Нечто иное, не являющееся файлом DuckDB | Откройте файлы CSV, Parquet, JSON или Excel как файлы данных |
Для файла из более новой DuckDB сообщение подставляет путь к файлу и версию DuckDB в DuckLocal. Выполните его в той DuckDB, которая создала файл, затем откройте compat.duckdb:
ATTACH '/path/to/file.duckdb' AS src (READ_ONLY);
ATTACH 'compat.duckdb' AS dst (STORAGE_VERSION 'v2.0.0');
COPY FROM DATABASE src TO dst;Файлы, записанные до DuckDB v1.2, не хранят сведений о том, какая версия их создала. Любой другой сбой — файл заблокирован другой программой или недоступен для чтения — показывает только сообщение DuckDB. См. Решение проблем.
Какой DuckDB может прочитать базу данных
Когда открыт файл базы данных, строка состояния показывает его путь. Наведите на неё курсор, чтобы увидеть формат хранения файла — самую старую версию DuckDB, которая его читает, например Формат хранения: читается DuckDB v1.0.0+, — и, если файл это записывает, версию, которая его создала (Создано DuckDB v1.4.3). Проверяйте это, прежде чем передать файл тому, у кого более старая DuckDB.
DuckLocal работает на DuckDB 2.0, но создаваемый им файл базы данных записывается в формате, который использовала DuckDB 1.x (читается DuckDB v1.0.0+), поэтому CLI duckdb, Python или DBeaver на DuckDB 1.x по-прежнему его открывают. Файл, записанный другой программой в собственном формате DuckDB 2.0 (v2.0.0+), тоже открывается и сохраняет этот формат: 1.x его прочитать не может.
Присоединённые базы данных
Присоедините другой файл DuckDB или SQLite рядом с основной базой данных, чтобы делать запросы по ним вместе — например, снимок рядом с сегодняшними данными.
- Откройте меню Открыть в строке заголовка и выберите Присоединить базу данных….
- Введите путь или нажмите Обзор, чтобы выбрать файл.
- Оставьте Только для чтения отмеченным, если не собираетесь менять файл. По умолчанию он отмечен.
- Нажмите Присоединить.
База данных получает псевдоним по имени файла, и вы запрашиваете её таблицы как alias.table (или alias.schema.table):
-- snap-2026-10-01.duckdb attached as snap_2026_10_01
SELECT t.id, t.amount, s.amount AS amount_last_week
FROM orders t
JOIN snap_2026_10_01.orders s USING (id);Как формируется псевдоним:
- Имя файла без расширения, в котором каждый символ, кроме буквы ASCII или цифры, заменён на
_. - Префикс
db_, если имя не начинается с буквы:2026-10 logs.duckdbстановитсяdb_2026_10_logs. - Счётчик, если имя занято:
snap, затемsnap_2.mainне используется никогда. - Повторное присоединение файла позже возвращает ему прежний псевдоним, поэтому написанный для него SQL продолжает работать.
Подробности:
- Файлы SQLite распознаются по содержимому и присоединяются через расширение
sqliteDuckDB. - Снятие флажка «Только для чтения» присоединяет файл для записи. Тогда несуществующий путь DuckDB создаётся как новая пустая база данных; в режиме только для чтения присоединение вместо этого завершается ошибкой.
- Один и тот же файл никогда не присоединяется дважды. Попытка присоединить уже открытый файл — как основную базу данных или как присоединённую — сообщает Эта база данных уже открыта как ….
В боковой панели
Каждая база данных показывается в дереве схемы — и основная, и присоединённые, включая пустые. Рядом с именем базы данных, где это применимо, отображается только для чтения или sqlite, а во всплывающей подсказке — её файл.
Щёлкните базу данных правой кнопкой, чтобы:
- Использовать как базу данных по умолчанию — выполняет
USE, поэтому имена таблиц без базы данных разрешаются там. Строка состояния показывает, где они разрешаются сейчас. - Отсоединить базу данных — отсоединяет её и забывает, поэтому в следующий раз она не вернётся. Если это была база данных по умолчанию, сеанс сначала переходит обратно к основной. Сам файл не затрагивается.
Остальная часть этого меню описана в разделе Обозреватель схемы и история.
Сохраняются между подключениями
Присоединённые базы данных хранятся в собственной базе данных истории DuckLocal вместе с псевдонимом и настройкой «только для чтения» и присоединяются заново при каждом новом подключении: при следующем запуске, после открытия другой базы данных и после Новая база данных в памяти.
- База данных, файл которой отсутствует, пропускается молча. Её регистрация сохраняется, поэтому она вернётся, когда файл снова появится, — DuckLocal никогда не создаёт вместо неё пустую базу данных.
- База данных, которая уже открыта — как основная или иначе, — не присоединяется второй раз.
- Если в новой основной базе данных уже есть база данных с таким псевдонимом, DuckLocal сообщает Не удалось присоединить …: имя … занято в открытой базе данных.
Открытие из Finder
На Mac Finder может передавать файлы DuckLocal напрямую:
| Файл | Двойной щелчок | «Открыть с помощью» или перетаскивание на значок в Dock |
|---|---|---|
.parquet | Открывается в DuckLocal | Да |
.duckdb, .ddb | Открывается в DuckLocal | Да |
.dash | Открывается в DuckLocal | Да |
.csv, .tsv, .json, .jsonl, .ndjson, .xlsx, .xls | Остаётся в приложении, которое уже их открывает (Numbers, Excel, текстовый редактор) | Да |
DuckLocal регистрирует себя по умолчанию только для форматов, на которые не претендует ничто другое на Mac. Если другая программа уже перехватила файлы Parquet или DuckDB, выберите DuckLocal в разделе Открыть с помощью — или воспользуйтесь в Finder пунктом Свойства → Открыть с помощью → Изменить всё…, чтобы сделать его программой по умолчанию.
Файл из Finder обрабатывается точно так же, как перетащенный в окно: файл данных становится представлением в текущем рабочем пространстве, файл базы данных открывается как основная база данных, а файл .dash открывается вкладкой дашборда. Если DuckLocal не запущен, он сначала запускается и открывает файл после завершения собственного запуска.
Предпросмотр Quick Look
На Mac выберите файл данных в Finder и нажмите Пробел, чтобы увидеть его столбцы и первые строки, ничего не открывая. Предпросмотр входит в состав DuckLocal.app; отдельно устанавливать ничего не нужно. Ему требуется macOS 12 или новее, как и приложению.
| Файл | Что показывает предпросмотр |
|---|---|
.parquet | Столбцы и типы, первые 50 строк и, из трейлера файла: число строк, группы строк, сжатие и программу записи |
.duckdb, .ddb | Число таблиц, формат хранения (Читается DuckDB …) и пять крупнейших таблиц, каждая с оценкой числа строк и первыми 50 строками |
.csv, .tsv | Столбцы с определёнными типами и первые 50 строк — таблица вместо сырого текста |
.jsonl, .ndjson | Столбцы и первые 50 строк |
Простой .json и файлы Excel оставлены собственным предпросмотрам macOS.
Что предпросмотр делает и чего не делает:
- Он никогда не записывает. База данных присоединяется только для чтения.
- Он никогда не сканирует файл целиком: строки ограничены
LIMIT, а число строк появляется только там, где формат его хранит (трейлер Parquet, оценка базы данных). - Он ничего не скачивает: расширения DuckDB не устанавливаются и не загружаются.
- Ячейки длиннее 200 символов обрезаются. Текст страницы — на английском.
- Для файла, который не удаётся прочитать, показывается страница с объяснением причины.
Если нажатие пробела не показывает предпросмотр DuckLocal:
- Убедитесь, что DuckLocal находится в Программах, и запустите его один раз. macOS регистрирует предпросмотр, когда впервые видит приложение.
- Сбросьте Quick Look в Терминале:
qlmanage -r. Затем повторите попытку. - Проверьте, что DuckLocal Preview включён в разделе Quick Look в настройках расширений «Настроек системы».
Именование
Представление файла называется по имени файла без расширения, приведённому к допустимому идентификатору. Если это имя уже занято в подключении, DuckLocal добавляет счётчик: events, затем events_2, events_3. Поэтому два файла с одинаковым именем в разных каталогах получают разные представления.
Дубликаты определяются по тексту пути в том виде, в каком он записан, поэтому ./a.csv и a.csv считаются двумя разными файлами.
Ограничения
- 256 файлов данных на один запрос открытия. Лимит охватывает все пути одного запроса вместе, а не каждую папку по отдельности; он существует, чтобы случайно перетащенный домашний каталог не занимал подключение минутами. При достижении лимита DuckLocal сообщает об этом и присоединяет первые 256 файлов.
- Файлы, повторно присоединяемые при запуске из предыдущего сеанса, под этот лимит не подпадают.
Управление зарегистрированными источниками
Зарегистрированные файлы появляются в группе Локальные файлы боковой панели, каждый со своим именем представления, именем файла и числом строк. При выборе файла для него создаётся запрос SELECT.
× в строке файла удаляет его после диалога подтверждения. Удаление уничтожает представление и забывает регистрацию; исходный файл остаётся нетронутым.
Обновить схему перезагружает каталог и зарегистрированные файлы.
Что запоминается
Список зарегистрированных файлов — их пути, имена представлений и типы — хранится в собственной базе данных истории DuckLocal и присоединяется заново при следующем запуске, поэтому вы возвращаетесь в то рабочее пространство, которое оставили. Так же и с присоединёнными базами данных. Файл основной базы данных не запоминается: каждый запуск начинается в памяти, если не указать базу данных.
Об расположении на диске см. в разделе Настройки и данные приложения.
