# Источники данных

> Выполняйте SQL-запросы DuckDB к файлам CSV, Parquet, JSON и Excel локально. Открывайте папки и шаблоны, присоединяйте базы данных, оставляя данные на своём компьютере.

Source: https://ducklocal.app/docs/ru/data-sources

DuckLocal превращает файлы в представления в подключении DuckDB в памяти — или
в файле базы данных, если вы его открыли. Рядом могут находиться другие базы
данных. Настраивать ничего не нужно. Краткий путь от файлов к SQL, графикам и
экспорту описан в [сценарии локального анализа данных](https://ducklocal.app/ru/use-cases/local-data-analysis/).

## Способы открыть данные

Все они подчиняются одним и тем же правилам разрешения путей:

1. Пути в командной строке — `ducklocal ./logs/ billing.parquet`
2. Меню **Открыть** в строке заголовка: **Открыть файлы**, **Открыть папку** или
   **Ввести путь или шаблон**, которое открывает диалог **Открыть данные** для
   введённого пути или пути, выбранного в системном средстве выбора
3. Перетаскивание файлов или папок в любое место окна
4. На Mac — файлы, которые Finder передаёт DuckLocal; см.
   [Открытие из Finder](#open-from-finder)

Чтобы добавить базу данных рядом с открытой, а не заменить её, используйте
**Открыть → Присоединить базу данных…** — см. [Присоединённые
базы данных](#attached-databases).

В macOS можно дважды щёлкнуть файлы Parquet и DuckDB в Finder, чтобы открыть их,
или нажать пробел, чтобы без запуска DuckLocal посмотреть в Quick Look первые
строки файлов Parquet, DuckDB, CSV, TSV и JSON Lines.

## Поддерживаемые форматы файлов {#supported-file-formats}

Расширения сопоставляются без учёта регистра.

| Расширение | Как читается |
| --- | --- |
| `.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`.

Всё остальное не является файлом данных — см. [Файлы баз данных](#database-files).

Книга Excel — единственный формат, который становится **таблицами**, а не
представлениями, и импортирует **каждый лист**: первый лист получает имя файла
без расширения, остальные называются `{stem}_{sheet name}`. Пустой лист
пропускается. Типы столбцов определяются по ячейкам: целые числа становятся
`BIGINT`, смесь целых и дробных — `DOUBLE`, даты — `TIMESTAMP`, а всё смешанное
или нераспознанное — `VARCHAR`; пустые ячейки импортируются как `NULL`.

## Папки и шаблоны {#folders-and-patterns}

**Каталог** обходится рекурсивно, и каждый файл данных внутри становится
представлением. При обходе действуют два правила:

- Скрытые элементы (имена, начинающиеся с `.`) пропускаются, и в их поддеревья
  обход не заходит.
- Символические ссылки не разыменовываются. Переход по ссылке вверх по дереву
  никогда бы не завершился, а каталог, на который указывает ссылка, обычно
  обходится там, где он действительно находится.

Файлы присоединяются в отсортированном порядке, поэтому одна и та же папка
всегда даёт одно и то же рабочее пространство.

**Шаблон** может содержать `*` (любая последовательность символов) и `?` (ровно
один символ). Сопоставление выполняется по компонентам пути в файловой системе,
поэтому шаблон может охватывать несколько каталогов:

```bash
ducklocal './data/2026-0*/*.parquet'
```

Символа экранирования нет. `**` не имеет особого смысла — ведёт себя как один `*`
и не выполняет рекурсию. Шаблон, совпадающий с каталогом, пропускает его;
присоединяются только файлы. Скрытые элементы здесь тоже пропускаются.

Шаблоны без кавычек раскрывает ваша оболочка ещё до того, как их увидит
DuckLocal. Это нормально. Заключайте шаблон в кавычки, только если хотите, чтобы
его раскрыл DuckLocal, — например, когда оболочка не находит совпадений и иначе
выдала бы ошибку.

## Много файлов CSV одновременно {#many-csv-files-at-once}

Каждый присоединённый файл становится отдельным представлением с собственной
определённой схемой, поэтому два несовпадающих CSV не ломают друг друга.
Подводные камни появляются, когда одно чтение SQL охватывает много файлов:

```sql
SELECT * FROM read_csv('data/*.csv', union_by_name = true)
```

- **Определение типов может расходиться между файлами.** Читатель выводит тип
  столбца по выборке; столбец, который везде числовой, но в одном файле содержит
  случайную строку `'NULL'`, ломает всё чтение ошибкой преобразования, а
  приведение типа в списке `SELECT` происходит слишком поздно — ошибка возникает
  при самом чтении. Читайте все столбцы как текст и приводите типы в SQL:

  ```sql
  SELECT 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)`.

## Файлы баз данных {#database-files}

В DuckLocal одновременно есть одна **основная база данных**: в памяти или файл
DuckDB, который вы открыли. Файлы данных становятся представлениями в основной
базе данных. Кроме того, можно [присоединить другие базы данных рядом с
ней](#attached-databases).

Любой **существующий** путь, который не является файлом данных, открывается как
основная база данных, а не присоединяется как представление. Расширение не важно:
путь `.db`, `.duckdb` или даже `.md` рассматривается как база данных, а DuckDB
решает, можно ли её действительно открыть.

Стоит знать о нескольких последствиях:

- **Новая база данных создаётся только из диалога «Открыть данные».** Введите
  путь, оканчивающийся на `.duckdb` и ещё не существующий, и DuckLocal создаст
  базу данных вместе с недостающими родительскими папками. Везде ещё — в
  командной строке, средствах выбора, при перетаскивании, в Finder —
  несуществующий путь сообщается как `File not found`.
- **Открытие базы данных заменяет основную.** Зарегистрированные файлы и
  присоединённые базы данных присоединяются заново к новому подключению. Учётные
  данные S3 — нет; настройте S3 заново.
- **Если файл не удаётся открыть**, DuckLocal сообщает причину
  ([ниже](#when-a-database-will-not-open)). При запуске он переходит к рабочему
  пространству в памяти, а не завершается с ошибкой. Пока он работает, текущее
  рабочее пространство остаётся как было.
- **Файл, который уже присоединён** рядом с основной базой данных, сначала
  отсоединяется, а затем открывается как основная. Если открыть не удалось,
  присоединение возвращается. Открытие файла, который уже является основной базой
  данных, переиспользует его.

Присоединение файлов данных при открытом файле базы данных **записывает эти
представления в сам файл базы данных** — они сохраняются там, а не только в
сеансе.

### Когда база данных не открывается {#when-a-database-will-not-open}

Когда DuckDB отклоняет файл, DuckLocal сам читает первые байты и, если они
объясняют сбой, помещает причину и путь решения над собственным сообщением
DuckDB. Сообщение DuckDB остаётся ниже для точной ошибки. Объяснение даётся на
языке интерфейса.

| Что это за файл | Что сообщает DuckLocal |
| --- | --- |
| Файл DuckDB, записанный **более новой версией DuckDB**, чем встроенная в DuckLocal | Обе версии и SQL, который нужно выполнить в более новой DuckDB, чтобы скопировать файл в формат, понятный DuckLocal (ниже) |
| Файл DuckDB **v0.9 или старше** | Выполните `EXPORT DATABASE 'dir'` в той DuckDB, которая его записала, затем `IMPORT DATABASE 'dir'` в DuckLocal |
| База данных **SQLite** | Это не файл DuckDB; присоедините её — через [Присоединить базу данных…](#attached-databases) или `INSTALL sqlite; ATTACH '…' (TYPE sqlite);` |
| Нечто иное, **не являющееся файлом DuckDB** | Откройте файлы CSV, Parquet, JSON или Excel как файлы данных |

Для файла из более новой DuckDB сообщение подставляет путь к файлу и версию
DuckDB в DuckLocal. Выполните его в той DuckDB, которая создала файл, затем
откройте `compat.duckdb`:

```sql
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. См.
[Решение проблем](troubleshooting.md#opening-a-database).

### Какой DuckDB может прочитать базу данных {#storage-version}

Когда открыт файл базы данных, строка состояния показывает его путь. Наведите на
неё курсор, чтобы увидеть формат хранения файла — самую старую версию 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 его прочитать не может.

## Присоединённые базы данных {#attached-databases}

Присоедините другой файл DuckDB или SQLite рядом с основной базой данных, чтобы
делать запросы по ним вместе — например, снимок рядом с сегодняшними данными.

1. Откройте меню **Открыть** в строке заголовка и выберите **Присоединить
   базу данных…**.
2. Введите путь или нажмите **Обзор**, чтобы выбрать файл.
3. Оставьте **Только для чтения** отмеченным, если не собираетесь менять файл. По
   умолчанию он отмечен.
4. Нажмите **Присоединить**.

База данных получает **псевдоним** по имени файла, и вы запрашиваете её таблицы
как `alias.table` (или `alias.schema.table`):

```sql
-- 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** распознаются по содержимому и присоединяются через расширение
  `sqlite` DuckDB.
- **Снятие флажка «Только для чтения»** присоединяет файл для записи. Тогда
  несуществующий путь DuckDB создаётся как новая пустая база данных; в режиме
  только для чтения присоединение вместо этого завершается ошибкой.
- **Один и тот же файл никогда не присоединяется дважды.** Попытка присоединить
  уже открытый файл — как основную базу данных или как присоединённую — сообщает
  *Эта база данных уже открыта как …*.

### В боковой панели {#in-the-sidebar}

Каждая база данных показывается в дереве схемы — и основная, и присоединённые,
включая пустые. Рядом с именем базы данных, где это применимо, отображается
**только для чтения** или **sqlite**, а во всплывающей подсказке — её файл.

Щёлкните базу данных правой кнопкой, чтобы:

- **Использовать как базу данных по умолчанию** — выполняет `USE`, поэтому имена
  таблиц без базы данных разрешаются там. Строка состояния показывает, где они
  разрешаются сейчас.
- **Отсоединить базу данных** — отсоединяет её и забывает, поэтому в следующий
  раз она не вернётся. Если это была база данных по умолчанию, сеанс сначала
  переходит обратно к основной. Сам файл не затрагивается.

Остальная часть этого меню описана в разделе
[Обозреватель схемы и история](schema-and-history.md).

### Сохраняются между подключениями {#kept-across-connections}

Присоединённые базы данных хранятся в собственной базе данных истории DuckLocal
вместе с псевдонимом и настройкой «только для чтения» и присоединяются заново при
каждом новом подключении: при следующем запуске, после открытия другой базы
данных и после **Новая база данных в памяти**.

- База данных, файл которой **отсутствует**, пропускается молча. Её регистрация
  сохраняется, поэтому она вернётся, когда файл снова появится, — DuckLocal
  никогда не создаёт вместо неё пустую базу данных.
- База данных, которая **уже открыта** — как основная или иначе, — не
  присоединяется второй раз.
- Если в новой основной базе данных уже есть база данных с таким псевдонимом,
  DuckLocal сообщает *Не удалось присоединить …: имя … занято в открытой базе
  данных.*

## Открытие из Finder {#open-from-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` открывается вкладкой
[дашборда](dashboards.md). Если DuckLocal не запущен, он сначала запускается и
открывает файл после завершения собственного запуска.

## Предпросмотр Quick Look {#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:

1. Убедитесь, что DuckLocal находится в **Программах**, и запустите его один раз.
   macOS регистрирует предпросмотр, когда впервые видит приложение.
2. Сбросьте Quick Look в Терминале: `qlmanage -r`. Затем повторите попытку.
3. Проверьте, что **DuckLocal Preview** включён в разделе Quick Look в настройках
   расширений «Настроек системы».

## Именование

Представление файла называется по имени файла без расширения, приведённому к
допустимому идентификатору. Если это имя уже занято в подключении, DuckLocal
добавляет счётчик: `events`, затем `events_2`, `events_3`. Поэтому два файла с
одинаковым именем в разных каталогах получают разные представления.

Дубликаты определяются по тексту пути в том виде, в каком он записан, поэтому
`./a.csv` и `a.csv` считаются двумя разными файлами.

## Ограничения

- **256 файлов данных на один запрос открытия.** Лимит охватывает все пути одного
  запроса вместе, а не каждую папку по отдельности; он существует, чтобы
  случайно перетащенный домашний каталог не занимал подключение минутами. При
  достижении лимита DuckLocal сообщает об этом и присоединяет первые 256 файлов.
- Файлы, повторно присоединяемые при запуске из предыдущего сеанса, под этот
  лимит не подпадают.

## Управление зарегистрированными источниками

Зарегистрированные файлы появляются в группе **Локальные файлы** боковой панели,
каждый со своим именем представления, именем файла и числом строк. При выборе
файла для него создаётся запрос `SELECT`.

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

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

## Что запоминается

Список зарегистрированных файлов — их пути, имена представлений и типы — хранится
в собственной базе данных истории DuckLocal и присоединяется заново при следующем
запуске, поэтому вы возвращаетесь в то рабочее пространство, которое оставили. Так
же и с [присоединёнными базами данных](#kept-across-connections). Файл основной
базы данных *не* запоминается: каждый запуск начинается в памяти, если не указать
базу данных.

Об расположении на диске см. в разделе [Настройки и данные
приложения](settings-and-data.md).
