Перейти к основному содержимому

metawarc (WARC)

metawarc — инструмент Ruarxive для работы с уже собранными WARC-коллекциями. В отличие от wparc, ydiskarc и filegetter, которые собирают данные, metawarc занимается следующим этапом: индексацией, поиском, извлечением метаданных и анализом архивов. Создавать или упаковывать файлы в WARC metawarc не умеет.

Репозиторий: github.com/ruarxive/metawarc · Документация: ruarxive.org/metawarc · Лицензия: MIT · Python 3.10+

Зачем нужен​

WARC — бинарный контейнер с ответами сервера, HTTP-заголовками и телами ресурсов. Чтобы ответить на вопросы «сколько в коллекции PDF?», «что лежало по адресу X?», «где встречается слово Y?», нужен индекс. metawarc строит версионированный каталог DuckDB с Parquet-сайдкарами:

  • исходные WARC не изменяются;
  • каталог (.db) хранит список архивов, состояние и ссылки на сайдкары;
  • Parquet-сайдкары с записями, заголовками, ссылками, текстами и метаданными лежат в каталоге <имя базы>.data/;
  • запросы выполняются по каталогу без копирования WARC.

Команды​

КомандаЧто делает
indexИндексирует WARC/WARC.GZ: записи и HTTP-заголовки. Режимы --mode add|update|rescan|force, --resume
ingestПланирует и выполняет инкрементальное добавление; есть --dry-run
catalog, statsСписок архивов в каталоге; статистика по MIME-типам или расширениям
list-filesСписок записей с типизированными фильтрами; вывод в таблицу, CSV или JSONL
dump, getВыгрузка содержимого записей в файлы с JSONL-манифестом и SHA-256; выгрузка одной записи
index-contentИзвлечение метаданных (--type links|pdfs|images|ooxmldocs|oledocs|videos|audio|fonts) и текста (--text)
dump-metadataВыгрузка извлечённых метаданных одного типа в JSON Lines
analyzeОтчёты: summary, metadata, hashes, duplicates, links, integrity
searchПоиск фразы по извлечённым текстам
export-cdxjЭкспорт CDXJ-индекса для внешних систем просмотра, например pywb
serve (replay)REST API и локальный просмотр сохранённых сайтов
mcpMCP-сервер только для чтения для ИИ-агентов
jobsФоновые задачи экспорта: submit, list, get, wait, cancel
doctor, rebind, cleanupПроверка и ремонт каталога, привязка перемещённого архива, очистка устаревших файлов

История версий​

  • 2022 год — появление инструмента: в канале @ruarxive он представлен в посте #61 от 29.06.2022: извлечение метаданных из изображений и документов внутри WARC и статистика по MIME-типам.
  • Обновление 2025 года (пост #160 от 30.06.2025): хранение переведено с SQLite на DuckDB + Parquet. Раньше база метаданных могла достигать 20 % от объёма WARC; после переписывания метаданные WARC-файла размером 4,5 ГБ занимают 3,5 МБ (0,07 %, сжатие примерно в 285 раз).
  • Версия 2.0 вышла 8 августа 2026 года (пост #190): стабильные идентификаторы архивов, схема каталога версии 2, REST API, MCP-сервер, фоновые задачи и просмотр сохранённых сайтов. В посте сказано о проигрывании «через библиотеку pywb»; по README и коду 2.0 просмотр встроен в сам metawarc (FastAPI), а с pywb он связан через экспорт CDXJ.
  • Текущая версия на PyPI — 2.0.3 (6 октября 2026 года).

Установка​

# Базовый CLI
pip install metawarc

# С REST API и просмотром сайтов
pip install 'metawarc[api]'

# С MCP-сервером
pip install 'metawarc[mcp]'

# Все интерфейсы
pip install 'metawarc[all]'

Требуется Python 3.10 или новее. Без metawarc[api] команда serve завершится сообщением о необходимости установить дополнение.

Команды сверены с README, исходным кодом и --help версии 2.0.3, а также проверены на тестовом WARC (октябрь 2026).

Быстрый старт​

# 1. Проиндексировать коллекцию (с продолжением прерванной индексации)
metawarc index 'archives/**/*.warc*' --dbfile collection.db --resume

# 2. Посмотреть, что попало в каталог
metawarc catalog --dbfile collection.db
metawarc stats --dbfile collection.db --mode mimes

# 3. Найти PDF и выгрузить первые 100
metawarc list-files --dbfile collection.db --mimes application/pdf
metawarc dump --dbfile collection.db --exts pdf --limit 100 --output exported

# 4. Извлечь ссылки, метаданные PDF и текст для поиска
metawarc index-content --dbfile collection.db --type links --type pdfs --text
metawarc search "бюджет" --dbfile collection.db

# 5. Запустить локальный просмотр (нужен metawarc[api])
metawarc serve --dbfile collection.db
# → http://127.0.0.1:8000/ — список сохранённых сайтов

Архитектура кратко​

  • Рабочее пространство — файл базы (по умолчанию warcindex.db) и каталог <имя базы>.data/ с сайдкарами; его можно перенести через --data-dir.
  • Таблицы DuckDB: archives, catalog_state, checkpoints, meta, runs, sidecars. Сами записи, заголовки, ссылки, тексты и метаданные лежат в Parquet-файлах, перечисленных в таблице sidecars.
  • Схема версии 2 — стабильные ID архивов, версионированные сайдкары, атомарная публикация.
  • Типизированные запросы — фильтры проходят через список разрешённых полей и связанные параметры. Сырой SQL доступен только в CLI через явно названную опцию --unsafe-where и не доступен через REST и MCP.

Подробнее — архитектура в документации.

Форматы для извлечения метаданных​

  • Документы: PDF; Office Open XML (DOCX, XLSX, PPTX и шаблоны, включая файлы с макросами); старые DOC, XLS, PPT.
  • Изображения: JPEG, PNG, GIF, TIFF, JPEG 2000, BMP, ICO, WebP, SVG, PSD и другие форматы, которые читает библиотека hachoir.
  • Видео: MP4/QuickTime, AVI, WebM/Matroska, Ogg, MPEG, ASF/WMV, FLV.
  • Аудио: MP3, WAV, AIFF, FLAC, Ogg/Opus, M4A, WMA, MIDI, RealAudio.
  • Шрифты: TTF, OTF, коллекции шрифтов, WOFF, WOFF2, EOT.
  • Ссылки из HTML и текст HTML, PDF и OOXML для поиска.

Как устроен выбор экстрактора — на странице metawarc: экстракторы.

Когда использовать​

Подходит, если у вас уже есть WARC-коллекция (собранная wget, Browsertrix, Heritrix, grab-site, wparc warc или filegetter с write_warc) и нужно:

  • узнать, что внутри (типы, объёмы, хосты);
  • извлечь метаданные PDF, изображений и документов;
  • найти фразу в извлечённом тексте;
  • выгрузить подмножество файлов, например все PDF;
  • быстро посмотреть сохранённый сайт локально;
  • дать дашборду или агенту доступ к коллекции только на чтение.

Для сбора WARC metawarc не нужен — см. инструменты сбора.

Сравнение с похожими инструментами​

ИнструментНазначениеОтличие от metawarc
warcioPython-библиотека чтения и записи WARCmetawarc строит готовый к запросам каталог; с warcio нужно писать свои скрипты
warctoolsУтилиты командной строки (warcvalid, warcdump)metawarc даёт типизированные запросы, REST и MCP
Archives UnleashedАнализ WARC на Sparkmetawarc работает на одной машине без Spark
pywbПросмотр веб-архивову metawarc простой встроенный просмотр без переписывания JavaScript; для полного воспроизведения он экспортирует CDXJ для pywb

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

  • Не сборщик и не упаковщик: работает только с существующими WARC.
  • Python 3.10+.
  • MCP-сервер только читает: нет инструментов изменения, удаления, сырого SQL и выдачи содержимого записей.
  • Встроенный просмотр переписывает только HTML и CSS; JavaScript не переписывается. Для сложных сайтов экспортируйте CDXJ и используйте pywb.
  • Поиск — последовательный просмотр столбца текстов в DuckDB, а не полнотекстовый индекс; на больших коллекциях он медленный.

Расширенные разделы​

Переменные окружения​

Переменные читаются в metawarc/settings.py и действуют на serve (REST API и просмотр):

ПеременнаяПо умолчаниюНазначение
METAWARC_API_TOKENне заданаBearer-токен REST API (то же, что serve --token)
METAWARC_HOST127.0.0.1Адрес, на котором слушает serve
METAWARC_PORT8000Порт serve
METAWARC_MAX_PAGE500Максимальный limit для /records/list и /records/search
METAWARC_MAX_PAYLOAD_BYTES134217728 (128 МиБ)Максимальный объём отдаваемого содержимого записи
METAWARC_REQUEST_TIMEOUT30Таймаут одного HTTP-запроса, секунды
METAWARC_MAX_CONCURRENCY16Одновременно обрабатываемых HTTP-запросов
METAWARC_JOB_MAX_CONCURRENT4Одновременно выполняемых фоновых задач
METAWARC_JOB_TIMEOUT300Таймаут одной фоновой задачи, секунды

В settings.py есть также METAWARC_DB_PATH, METAWARC_DATA_DIR и METAWARC_MCP_PORT, но команды serve и mcp берут путь к базе из --dbfile/--data-dir, а порт MCP — из --port (по умолчанию 8191).

export METAWARC_API_TOKEN='замените-на-случайную-строку'
export METAWARC_JOB_TIMEOUT=1800
metawarc serve --dbfile collection.db

Опция --unsafe-where​

Обычные фильтры (--mimes, --exts, --url-pattern, --host-pattern, --status-min/--status-max, --date-from/--date-to, --size-min/--size-max) передаются в запрос как параметры. Для разового анализа на своей машине у list-files и dump есть опция --unsafe-where с сырым SQL-условием:

# Безопасно: типизированные фильтры
metawarc list-files --dbfile collection.db --mimes text/html --limit 100

# Сырой SQL — только локально и только для своих данных
metawarc list-files --dbfile collection.db --unsafe-where "status_code >= 400"

Через REST и MCP эта опция недоступна.

Выгрузка содержимого: dump и get​

dump сохраняет содержимое выбранных записей в отдельные файлы и пишет рядом manifest.jsonl (архив, ID записи, URL, тип, путь к файлу, размер, SHA-256). Существующие файлы не перезаписываются.

metawarc dump --dbfile collection.db --mimes application/pdf --limit 1000 --output ./pdfs
metawarc get 'urn:uuid:<id записи>' --dbfile collection.db --output page.html

Опции dump: --archive-ids, -m/--mimes, -e/--exts, --url-pattern, --unsafe-where, --offset, --limit (по умолчанию 1000, максимум 100 000), --max-bytes, -o/--output (по умолчанию dump).

Табличные выгрузки списка записей делают list-files -o records.csv --output-format csv (или jsonl; не больше 1000 строк за вызов, дальше — через --offset) и фоновые задачи jobs (JSON, CSV, Parquet).

Просмотр сохранённых сайтов​

metawarc serve (или его синоним metawarc replay) поднимает просмотр по адресам:

ПутьЧто показывает
/ или /replayHTML-список сохранённых хостов со ссылками
/replay/sitesТо же в JSON: хост, стартовый URL, число снимков, путь для просмотра
/replay/<штамп>/<URL>Ближайший по времени снимок точного URL, HTML и CSS переписаны
/replay/<штамп>mp_/<URL>То же, явный режим с переписыванием
/replay/<штамп>id_/<URL>Исходное содержимое без переписывания

Штамп — ровно 14 цифр ГГГГММДДччммсс, допускаются только суффиксы mp_ и id_. Сокращённые штампы и шаблоны вроде 2026* возвращают ошибку 422. Параметр ?policy=exact требует точного совпадения времени (по умолчанию closest).

http://127.0.0.1:8000/replay/20260315102345mp_/https://example.com/news/article

Что делает просмотр: переписывает ссылки в HTML и CSS и заголовок Location у редиректов в адреса просмотра; сохраняет исходную кодировку (UTF-8, windows-1251, KOI8-R) и отдаёт страницу в UTF-8. JavaScript не переписывается, поэтому страницы, которые строят адреса скриптами, могут работать неполно. Для таких сайтов экспортируйте CDXJ и используйте pywb:

metawarc export-cdxj --dbfile collection.db -o collection.cdxj --path-index paths.tsv

Сохранённые скрипты могут быть небезопасны: без токена держите сервер на 127.0.0.1.

Фоновые задачи (jobs)​

Задачи нужны для выгрузок, которые не укладываются в таймаут HTTP-запроса. Зарегистрирован один вид задачи — export-records: выгрузка списка записей (как у list-files) в JSON, CSV или Parquet в каталог <имя базы>.data/jobs/<id задачи>/.

# Поставить задачу (опции группы, например --dbfile, указываются до подкоманды)
metawarc jobs --dbfile collection.db submit --format csv --limit 1000 --mimes application/pdf

# Список, статус, ожидание, отмена
metawarc jobs --dbfile collection.db list --status running
metawarc jobs --dbfile collection.db get <job_id>
metawarc jobs --dbfile collection.db wait <job_id> --poll-seconds 2 --timeout 600
metawarc jobs --dbfile collection.db cancel <job_id>

Фильтры submit: --archive-ids, --mimes, --exts, --url-pattern, --host-pattern, --status-min/--status-max, --size-min/--size-max. Статусы: pending, running, succeeded, failed, cancelled. Состояние задач сохраняется между перезапусками.

Команда jobs submit только ставит задачу в очередь. Выполняет задачи фоновый обработчик metawarc serve: задачи, ожидающие в очереди, он подхватывает при запуске. Без работающего serve задача останется в статусе pending, а jobs wait завершится по таймауту.

Ограничение версии 2.0.3: хотя --limit принимает значения до 100 000, при выполнении задача проверяет лимит запроса к каталогу и с limit больше 1000 завершается статусом failed («limit must be between 1 and 1000»). Задачи через REST описаны на странице metawarc REST API.

Как выбрать интерфейс​

КритерийCLIRESTMCPSQL в DuckDB
Для чегоСкрипты, CIДашборды, интеграцииИИ-агентыИсследования
ДоступЛокальноBearer-токенstdio или локальный HTTP без авторизацииЛокально
Содержимое записейdump, get/records/get/.../data/...НетЧерез WARC
Долгие выгрузкиjobs (выполняет serve)/jobsНетСвои скрипты

Совместимость и обслуживание каталога​

Рабочее пространство 2.0 использует схему версии 2. Каталоги версий 1.2/1.3 (с таблицами files/tables) распознаются: перед переносом путей в новый каталог делается резервная копия. Если перенос неоднозначен, doctor выдаёт рекомендации по пересборке и не трогает исходные WARC.

metawarc doctor --dbfile collection.db                    # проверка
metawarc doctor --dbfile collection.db --repair # план ремонта (без изменений)
metawarc doctor --dbfile collection.db --repair --apply # применить план
metawarc rebind <archive_id> /new/path/file.warc.gz --dbfile collection.db
metawarc cleanup --dbfile collection.db --retention-days 7 --apply

Полезные ссылки​

Связанные материалы​