Версии и формат хранения

Совместимость

Обратная совместимость

Обратная совместимость означает возможность использования более новой версии DuckDB для чтения файлов хранения, созданных более старой версией DuckDB. Версия 0.10 — первая версия DuckDB, поддерживающая обратную совместимость в формате хранения. DuckDB версии 0.10 может читать и обрабатывать файлы, созданные предыдущей версией DuckDB — DuckDB версии 0.9.

В будущих версиях DuckDB наша цель — обеспечить возможность любой версии DuckDB, выпущенной после текущей, читать файлы, созданные предыдущими версиями, начиная с этой версии. Мы хотим гарантировать полную обратную совместимость формата файлов. Это позволит вам сохранить данные, хранящиеся в файлах DuckDB, и гарантирует, что вы сможете читать эти файлы без необходимости знать, какой версией DuckDB был создан файл, или без необходимости конвертировать файлы между версиями.

Прямая совместимость

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

Прямая совместимость обеспечивается на основе лучших усилий. Хотя стабильность формата хранения важна, мы все еще хотим внести много улучшений и инноваций в формат хранения в будущем. Поэтому прямая совместимость может быть (частично) нарушена.

Как переместить данные между форматами хранения

При обновлении DuckDB и открытии старого файла базы данных вы можете столкнуться с сообщением об ошибке о несовместимости форматов хранения, которое укажет на эту страницу. Чтобы переместить вашу базу данных(ы) в более новый формат, вам понадобятся только старая и новая исполняемые программы DuckDB.

Откройте файл базы данных со старой версией DuckDB и выполните SQL-запрос EXPORT DATABASE 'tmp'. Это позволит вам сохранить все состояние текущей базы данных в папке tmp. Содержание папки tmp будет перезаписано, поэтому выберите пустое/ещё не существующее место. Затем запустите новую версию DuckDB и выполните IMPORT DATABASE 'tmp' (указав ранее заполненную папку), чтобы загрузить базу данных, которую затем можно сохранить в указанный файл.

Один из вариантов в bash (для адаптации к именам файлов и расположениям исполняемых файлов):

/older/version/duckdb mydata.db -c "EXPORT DATABASE 'tmp'" && /newer/duckdb mydata.new.db -c "IMPORT DATABASE 'tmp'"

После этого mydata.db останется в старом формате, mydata.new.db будет содержать те же данные, но в формате, доступном для более новой версии DuckDB, а папка tmp будет содержать те же данные в универсальном формате в виде различных файлов.

Дополнительные сведения о синтаксисе см. в документации по EXPORT.

Заголовок хранения

Файлы DuckDB начинаются с uint64_t, содержащего контрольную сумму основного заголовка, за которым следуют четыре магических байта (DUCK), а затем номер версии хранения в uint64_t.

hexdump -n 20 -C mydata.db

00000000  01 d0 e2 63 9c 13 39 3e  44 55 43 4b 2b 00 00 00  |...c..9>DUCK+...|
00000010  00 00 00 00                                       |....|
00000014

Ниже приведен простой пример чтения версии хранения с помощью Python.

import struct

pattern = struct.Struct('<8x4sQ')

with open('test/sql/storage_version/storage_version.db', 'rb') as fh:
    print(pattern.unpack(fh.read(pattern.size)))

Таблица версий хранения

Ознакомьтесь с журналом изменений на GitHub для получения информации о внесённых изменениях в каждой версии. Чтобы увидеть коммиты, изменившие каждую версию хранения, см. журнал коммитов.

Сжатие

DuckDB использует лёгкое сжатие. Обратите внимание, что сжатие применяется только к постоянным базам данных и не применяется к экземплярам в оперативной памяти.

Алгоритмы сжатия

Поддерживаемые DuckDB алгоритмы сжатия включают:

• Константное кодирование
• Кодирование по длине серии (RLE)
• Упаковку бит
• Система отсчёта (FOR)
• Кодирование словаря
• Быстрая статическая таблица символов (FSST) – статья VLDB 2020
• Адаптивное без потерь сжатие чисел с плавающей точкой (ALP) – статья SIGMOD 2024
• Chimp – статья VLDB 2022
• Patas

Использование дискового пространства

Использование дискового пространства форматом DuckDB зависит от ряда факторов, включая тип данных и распределение данных, используемые методы сжатия и т. д. Приблизительно, загрузка 100 ГБ нескомпрессированных CSV-файлов в базу данных DuckDB потребует 25 ГБ дискового пространства, а загрузка 100 ГБ Parquet-файлов — 120 ГБ.

Группы строк

Формат хранения DuckDB хранит данные в группах строк, т. е. горизонтальных разделах данных. Это понятие эквивалентно группам строк Parquet. Несколько функций в DuckDB, включая параллелизм и сжатие, основаны на группах строк.

Устранение неполадок

Сообщение об ошибке при открытии несовместимого файла базы данных

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

Error: unable to open database "...": Serialization Error: Failed to deserialize: ...

Сообщение подразумевает, что файл базы данных был создан более новой версией DuckDB и использует функции, обратная совместимость которых с версией DuckDB, используемой для чтения файла, отсутствует.

Существует два возможных решения:

1. Обновите свою версию DuckDB до последней стабильной версии.
2. Откройте базу данных с помощью последней версии DuckDB, экспортируйте её в стандартный формат (например, Parquet), а затем импортируйте её в любую версию DuckDB. Подробнее см. в EXPORT/IMPORT DATABASE.