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

Загрузка JSON

Следующие примеры предоставляют очень простой пример загрузки структурированных и полуструктурированных данных JSON. Для более сложного JSON, включая вложенные структуры, смотрите руководство Проектирование схемы JSON.

Загрузка Структурированного JSON

В этом разделе мы предполагаем, что данные JSON находятся в формате NDJSON (JSON с разделителями строк), известном как JSONEachRow в ClickHouse, и хорошо структурированы, т.е. имена и типы колонок являются фиксированными. NDJSON является предпочтительным форматом для загрузки JSON благодаря своей краткости и эффективному использованию пространства, но другие форматы также поддерживаются для входа и выхода.

Рассмотрим следующий пример JSON, представляющий строку из набора данных Python PyPI:

Для загрузки этого объекта JSON в ClickHouse необходимо определить схему таблицы.

В этом простом случае наша структура статична, наши имена колонок известны, и их типы определены.

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

Предпочитайте статические схемы, когда это возможно

В случаях, когда ваши колонки имеют фиксированные имена и типы, и не ожидаются новые колонки, всегда предпочтительнее использовать статически определённую схему в продакшене.

Тип JSON предпочтителен для высоко динамических данных, где имена и типы колонок могут изменяться. Этот тип также полезен в прототипировании и исследовании данных.

Простая схема для этого показана ниже, где ключи JSON сопоставляются с именами колонок:

Ключи сортировки

Мы выбрали ключ сортировки здесь с помощью предложения ORDER BY. Для получения дополнительных сведений о ключах сортировки и том, как их выбирать, смотрите здесь.

ClickHouse может загружать данные JSON в нескольких форматах, автоматически выводя тип из расширения и содержимого. Мы можем читать JSON-файлы для вышеуказанной таблицы, используя функцию S3:

Обратите внимание, что нам не требуется указывать формат файла. Вместо этого мы используем шаблон glob для чтения всех *.json.gz файлов в ведре. ClickHouse автоматически определяет формат как JSONEachRow (ndjson) по расширению файла и содержимому. Формат можно указать вручную через параметр функции в случае, если ClickHouse не может его распознать.

Сжатые файлы

Вышеуказанные файлы также сжаты. Это автоматически обнаруживается и обрабатывается ClickHouse.

Чтобы загрузить строки из этих файлов, мы можем использовать INSERT INTO SELECT:

Строки также могут быть загружены инлайн с помощью FORMAT clause, например

Эти примеры предполагают использование формата JSONEachRow. Поддерживаются также другие распространенные форматы JSON, примеры загрузки которых приведены здесь.

Загрузка Полуструктурированного JSON

Private preview in ClickHouse Cloud

Наш предыдущий пример загружал JSON, который был статичным с известными именами ключей и типами. Это часто не так - ключи могут быть добавлены или их типы могут измениться. Это часто встречается в таких случаях, как данные мониторинга.

ClickHouse обрабатывает это через специализированный тип JSON.

Рассмотрим следующий пример из расширенной версии вышеуказанного набора данных Python PyPI. Здесь мы добавили произвольную колонку tags с случайными парами ключ-значение.

Колонка tags здесь непредсказуема и, следовательно, невозможно ее смоделировать. Чтобы загрузить эти данные, мы можем использовать нашу предыдущую схему, но добавить дополнительную колонку tags типа JSON:

Мы заполняем таблицу, используя тот же подход, что и для первоначального набора данных:

Обратите внимание на разницу в производительности при загрузке данных. Колонка JSON требует вывода типа во время вставки, а также дополнительного места, если существуют колонки, которые имеют более одного типа. Хотя тип JSON может быть настроен (смотрите Проектирование схемы JSON) для эквивалентной производительности с явным объявлением колонок, он изначально имеет намеренную гибкость. Тем не менее, эта гибкость имеет свою цену.

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

Используйте тип JSON, когда ваши данные:

  • Имеют непредсказуемые ключи, которые могут изменяться со временем.
  • Содержат значения разного типа (например, путь может иногда содержать строку, а иногда число).
  • Требуется гибкость схемы, где строгая типизация невозможна.

Если структура ваших данных известна и последовательна, редко возникает необходимость в типе JSON, даже если ваши данные находятся в формате JSON. В частности, если ваши данные имеют:

  • Плоскую структуру с известными ключами: используйте стандартные типы колонок, например String.
  • Предсказуемую вложенность: используйте кортеж, массив или вложенные типы для этих структур.
  • Предсказуемую структуру с изменяющимися типами: рассмотрите использование динамических или вариантивных типов вместо этого.

Вы также можете комбинировать подходы, как мы сделали в приведенном выше примере, используя статические колонки для предсказуемых ключей верхнего уровня и одну колонку JSON для динамической части полезной нагрузки.