# Начало работы

> Установите DuckLocal на macOS, Windows или Linux, добавьте CLI ducklocal, откройте файл CSV, Parquet, JSON или Excel и выполните свой первый SQL-запрос к DuckDB.

Source: https://ducklocal.app/docs/ru/getting-started

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

## 1. Установка {#install}

DuckLocal работает на macOS, Windows и Linux. Ссылки ниже скачивают последнюю версию с `dl.ducklocal.app`; те же файлы и примечания к выпуску есть на [GitHub](https://github.com/JetSquirrel/DuckLocal/releases/latest).

Эти руководства обновлены для [v0.4.1](https://github.com/JetSquirrel/DuckLocal/releases/tag/v0.4.1), выпущенной 15 ноября 2026 года. Версия 0.4.0 добавила [сценарии работы с агентами](agent-workflows.md): ограниченный SQL, проверяемую передачу в окно, предложения дашбордов, записи анализа и переносимые проекты. Версия 0.4.1 добавляет фильтры с множественным выбором, часовой пояс и график временной шкалы для дашбордов, блоки `view`, которые хранят общий SQL один раз, расширения сообщества, такие как `mssql`, на вкладке «Расширения», а также запрос на сохранение таблиц, созданных во встроенной базе данных. Если вы обновляетесь с версии до 0.3.0, переустановите расширения: в том выпуске DuckLocal перешёл на DuckDB 2.0.

### Mac

Нужна **macOS 12 или новее на Apple silicon** (M1 или новее).

1. Скачайте [`ducklocal-macos-arm64.dmg`](https://dl.ducklocal.app/latest/ducklocal-macos-arm64.dmg).
2. Откройте его и перетащите **DuckLocal** в **Программы**.
3. Запустите DuckLocal из папки «Программы» или через Spotlight.

Образ диска подписан и нотаризован Apple, поэтому открывается без каких-либо
обходных путей для Gatekeeper.

### Windows

Нужна **64-битная Windows 10 или новее**.

1. Скачайте [`ducklocal-windows-x86_64.zip`](https://dl.ducklocal.app/latest/ducklocal-windows-x86_64.zip) и распакуйте его.
2. Запустите `ducklocal.exe` из распакованной папки. Сборка пока не
   подписана кодом, поэтому при первом запуске может появиться **Windows
   защитила ваш компьютер** — выберите **Подробнее**, затем **Выполнить
   в любом случае**.

### Linux

Нужна система **x86_64** с **glibc 2.35 или новее** (Ubuntu 22.04,
Debian 12, Fedora 36 или новее) и графические драйверы с поддержкой Vulkan.

```bash
curl -LO https://dl.ducklocal.app/latest/ducklocal-linux-x86_64.tar.gz
tar -xzf ducklocal-linux-x86_64.tar.gz
./ducklocal-linux-x86_64/ducklocal
```

::: details Сборка из исходного кода
Нужен стабильный Rust 1.85.1 или новее и цепочка инструментов C++ (Xcode Command
Line Tools). DuckDB компилируется из включённых исходников, поэтому первая
сборка занимает несколько минут и несколько гигабайт диска.

```bash
git clone https://github.com/JetSquirrel/DuckLocal
cd DuckLocal
cargo build --release
./target/release/ducklocal
```

Бинарный файл — `./target/release/ducklocal`; используйте его везде, где в этом
руководстве указано `ducklocal`. О сборке `.app` см. в разделе
[Разработка](development.md).
:::

## 2. Добавьте команду `ducklocal` (необязательно) {#add-command}

Всё в приложении работает без терминала. Если вы также хотите открывать данные
из командной строки — или позволить ИИ-агенту анализировать их через
[CLI](cli.md) — добавьте команду из приложения:

1. Нажмите кнопку с роботом в строке заголовка или выберите
   **DuckLocal → Командная строка и ИИ…** в строке меню.
2. Нажмите **Установить команду**. На Mac система запросит пароль
   для записи в `/usr/local/bin`.
3. Откройте новый терминал и проверьте: `ducklocal --version`.

Команда — это ссылка на приложение, поэтому обновление DuckLocal обновляет и
команду. Чтобы обновиться, нажмите на версию в правом конце строки состояния:
более новая версия скачается и установится при перезапуске (см.
[Проверку обновлений](settings-and-data.md#update-check)). На Mac команда
размещается в `/usr/local/bin`, на Linux — в `~/.local/bin`; в Windows папка
приложения добавляется в `Path`.

В том же диалоге **Добавить в Claude Code** устанавливает навык DuckLocal, чтобы
Claude Code знал, как запрашивать ваши файлы, а **Скопировать краткую справку**
копирует короткое объяснение для вставки в любой другой ИИ-агент. См.
[CLI для ИИ и официальный навык](cli.md#install-the-official-skill).

::: details Добавление вручную
```bash
sudo mkdir -p /usr/local/bin
sudo ln -sf /Applications/DuckLocal.app/Contents/MacOS/ducklocal /usr/local/bin/ducklocal
```

Чтобы удалить: `sudo rm /usr/local/bin/ducklocal`. На Linux слинкуйте
распакованный бинарный файл в `~/.local/bin`; в Windows добавьте распакованную
папку в `Path`.
:::

## 3. Откройте данные

При первом запуске открывается короткое руководство, которое ведёт утка:
подключение ИИ-агента, открытие данных, боковая панель, выполнение запроса и
чтение результатов. **Пропустить** закрывает его на любом шаге. Чтобы увидеть
его снова, выберите **Показать руководство** в меню **DuckLocal** на Mac или в
контекстном меню версии в правом конце строки состояния.

За ним — экран с заголовком **Перетащите сюда свои данные**. Отсюда данные
добавляются любым из способов:

- **Перетащите** файлы CSV, TSV, Parquet, JSON или Excel — или целую папку — в
  окно.
- Нажмите **Открыть файлы** или **Открыть папку**.
- На Mac **дважды щёлкните** файл `.parquet` или `.duckdb` в Finder или
  выберите DuckLocal в разделе **Открыть с помощью** для файлов CSV, JSON и
  Excel. См. [Открытие из Finder](data-sources.md#open-from-finder).
- Из терминала укажите пути:

  ```bash
  ducklocal ./sales.csv         # one file
  ducklocal ./logs/             # every data file under a folder, recursively
  ducklocal './data/*.parquet'  # a pattern — quote it so the shell does not expand it first
  ducklocal warehouse.duckdb    # an existing DuckDB database
  ```

Каждый файл становится представлением (view) с именем по имени файла —
`sales.csv` превращается в `sales` — и появляется в **Локальных файлах** в
боковой панели со своими столбцами и числом строк. DuckLocal читает файлы там,
где они лежат; ничего не копируется и не загружается.

Открытые файлы запоминаются, поэтому следующий запуск начинается с тем же
рабочим пространством. Подробности о форматах, папках, шаблонах и базах данных —
в разделе [Источники данных](data-sources.md).

На Mac можно также заглянуть в файл до открытия: выберите его в Finder и нажмите
**Пробел**. [Предпросмотр Quick Look](data-sources.md#quick-look) в DuckLocal
показывает столбцы и первые строки файлов Parquet, DuckDB, CSV, TSV и JSON Lines.

::: tip Нет подходящих данных под рукой?
В [учебнике для первых 10 минут](tutorial.md) шаг за шагом разбирается небольшой
файл с примером.
:::

## 4. Выполните запрос

Нажмите **Новый запрос** (или откройте данные — редактор появится сам). Введите
SQL и нажмите **⌘↵** (Cmd+Enter; в Windows и Linux — Ctrl+Enter):

```sql
SELECT * FROM sales LIMIT 20;
```

Замените `sales` на любое имя представления из боковой панели.

Результат появится на панели под редактором. Переключите её на **График**, чтобы
быстро увидеть картину, или экспортируйте результат в CSV или Parquet. На панели
инструментов над редактором есть **Выполнить**, **Формат** и **EXPLAIN**.

Полезный приём: в боковой панели нажмите кнопку воспроизведения рядом с таблицей,
чтобы получить готовый `SELECT * … LIMIT 100`, или имя столбца, чтобы выбрать
только этот столбец.

## Что дальше

- [Ваши первые 10 минут](tutorial.md) — пошаговое знакомство с данными из примера
- [Источники данных](data-sources.md) — форматы, папки, шаблоны, базы данных, Finder и Quick Look
- [Редактор SQL](sql-editor.md) — вкладки, сочетания клавиш, автодополнение, EXPLAIN
- [Результаты и графики](results-and-charts.md) — фильтрация, экспорт, графики, обзор столбцов
- [Дашборды (.dash)](dashboards.md) — дашборды как текстовые файлы и их рецензирование с ИИ-агентом
- [Решение проблем](troubleshooting.md) — когда что-то ведёт себя не так
