title: “Serialization” redirect_from:

  • /docs/latest/enterprise-guide/serialization

Сериализация

{% include plans-blockquote.html feature=”Serialization” %}

Как только вы действительно разберетесь с Glarus BI, часто бывает так, что у вас будет более одного развернутого экземпляра Glarus BI. У вас может быть пара тестовых или разрабатываемых экземпляров и несколько продов, или, может быть, у вас есть отдельная Glarus BI для каждого офиса или региона.

Чтобы помочь вам в таких ситуациях, Glarus BI имеет функцию сериализации, которая позволяет вам создать экспорт содержимого Glarus BI, который затем может быть импортирован в одну или несколько Glarus BI.

Экспорт сериализует содержимое исходной Glarus BI ​​в виде файлов YAML.

Импорт читает эти экспортированные файлы YAML и создает или обновляет элементы в целевой Glarus BI на основе содержимого, сериализованного в этих файлах YAML.

Есть два способа запустить эти команды export и import:

Мы заинтересованы в том, как мы можем улучшить сериализацию, чтобы она соответствовала вашему рабочему процессу. Поднять существующую проблему чтобы дать нам знать, что это важно для вас. Если соответствующей проблемы еще нет, пожалуйста, создайте ее и сообщите нам, что вам нужно.

Примеры использования сериализации

  • Среды подготовки. Включите рабочий процесс подготовки к производству для важных панелей мониторинга, экспортировав их из экземпляра подготовки Glarus BI, а затем импортировав их в ваши прод экземпляры.

  • Управление версиями. Проверьте экспортированные файлы в системе контроля версий и проверьте изменения в них, так как файлы YAML, содержащиеся в экспорте, довольно читабельны.

Ознакомьтесь с нашими руководствами по:

Сериализация не предназначена для таких случаев использования, как дублирование активов или подкачка источников данных в одном экземпляре Glarus BI. Если вы используете сериализацию для дублирования сущностей, ознакомьтесь с Как работает экспорт, Как работает импорт, и указания для вашего варианта использования в Другие варианты использования сериализации

Как работает экспорт

Что экспортируется

Metabase будет включать только некоторые артефакты в свой экспорт:

  • Коллекции (но персональные коллекции не экспортируются, если они явно не указаны через параметры экспорта)

  • Дашборды

  • Записанные запросы

  • Действия

  • Модели

  • SQL вырезки

  • Модель данных и метаданные таблицы

  • Сегменты и метрики, определенные в метаданных таблицы

  • Настройки общего доступа для запросов и дашбордов

  • Общие настройки Glarus BI

  • События и временные шкалы

  • Строки подключения к базе данных (только если указано через опции экспорта)

Glarus BI экспортирует свои артефакты в каталог файлов YAML. Экспорт включает:

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

  • действия

  • коллекции

  • карточки

  • дашборды

  • временные шкалы

  • базы данных

При сериализации через API каталог экспорта будет сжат в файл .tar.gz.

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

Общие настройки Glarus BI, которые экспортируются

Вот список общих настроек, которые Glarus BI экспортирует в файле settings.yaml. Подробнее о настройках Glarus BI см. в Настройка Glarus BI.

humanization-strategy
native-query-autocomplete-match-style
site-locale
report-timezone-short
report-timezone-long
application-name
enable-xrays
show-homepage-pin-message
source-address-header
enable-nested-queries
custom-geojson-enabled
start-of-week
custom-geojson
available-timezones
unaggregated-query-row-limit
aggregated-query-row-limit
hide-embed-branding?
search-typeahead-enabled
enable-sandboxes?
application-font
available-locales
landing-page
enable-embedding
application-colors
application-logo-url
application-favicon-url
show-homepage-xrays
show-metabot
enable-whitelabeling?
show-homepage-data
site-name
application-font-files
loading-message
report-timezone
show-lighthouse-illustration
persisted-models-enabled
enable-content-management?
subscription-allowed-domains
breakout-bins-num
available-fonts
custom-formatting

Настройте экспортируемые данные

Вы можете настроить экспортируемые данные. Вы можете указать Glarus BI:

  • Экспортировать определенные коллекции

  • Не экспортировать коллекции

  • Не экспортировать настройки Glarus BI

  • Не экспортировать метаданные таблиц

  • Включить образцы значений полей (исключено по умолчанию)

  • Включить сведения о подключении к базе данных (исключено по умолчанию)

См. параметры экспорта в командах CLI или экспортировать параметры в вызовах API.

Пример сериализованного вопроса

Вопросы можно найти в каталоге cards каталога коллекций. Вот пример файла YAML карточки для вопроса, написанного с помощью SQL, который использует фильтр полей и имеет визуализацию в виде диаграммы областей:

name: Products by week
description: Area chart of products created by week
entity_id: r6vC_vLmo9zG6_r9sAuYG
created_at: "2024-05-08T19:10:24.348808Z"
creator_id: admin@metabase.local
display: area
archived: false
collection_id: onou5H28Wvy3kWnjxxdKQ
collection_preview: true
collection_position: null
query_type: native
dataset: false
cache_ttl: null
database_id: Sample Database
table_id: null
enable_embedding: false
embedding_params: null
made_public_by_id: null
public_uuid: null
parameters:
  - default:
      - Gizmo
    id: c37d2f38-05fa-48c4-a208-19d9dba803c6
    name: Pick a category
    slug: category_filter
    target:
      - dimension
      - - template-tag
        - category_filter
    type: string/=
parameter_mappings: []
dataset_query:
  database: Sample Database
  native:
    query: |-
      SELECT
        category,
        date_trunc ('week', created_at) AS "Week",
        count(*) AS "Count"
      FROM
        products
      WHERE
        {{category_filter}}
      GROUP BY
        category,
        "Week"
    template-tags:
      category_filter:
        default:
          - Gizmo
        dimension:
          - field
          - - Sample Database
            - PUBLIC
            - PRODUCTS
            - CATEGORY
          - base-type: type/Text
        display-name: Pick a category
        id: c37d2f38-05fa-48c4-a208-19d9dba803c6
        name: category_filter
        type: dimension
        widget-type: string/=
  type: native
result_metadata:
  - base_type: type/Text
    display_name: CATEGORY
    effective_type: type/Text
    field_ref:
      - field
      - CATEGORY
      - base-type: type/Text
    name: CATEGORY
    semantic_type: null
  - base_type: type/DateTime
    display_name: Week
    effective_type: type/DateTime
    field_ref:
      - field
      - Week
      - base-type: type/DateTime
    name: Week
    semantic_type: null
  - base_type: type/BigInteger
    display_name: Count
    effective_type: type/BigInteger
    field_ref:
      - field
      - Count
      - base-type: type/BigInteger
    name: Count
    semantic_type: type/Quantity
visualization_settings:
  column_settings: null
  graph.dimensions:
    - Week
    - CATEGORY
  graph.metrics:
    - Count
serdes/meta:
  - id: r6vC_vLmo9zG6_r9sAuYG
    label: products_created_by_week
    model: Card
initially_published_at: null
metabase_version: v1.49.7 (f0ff786)
type: question

Glarus BI использует идентификаторы сущностей для идентификации и ссылки на элементы Glarus BI

Glarus BI назначает уникальный идентификатор сущности каждому элементу (дашборд, запрос, модель, коллекция и т. д.). Идентификаторы сущностей используют формат NanoID.

Вы можете увидеть идентификаторы сущностей элементов в экспортированных файлах YAML в поле entity_id. Например, в Примере сериализованного вопроса, вы увидите идентификатор сущности этого запроса:

entity_id: r6vC_vLmo9zG6_r9sAuYG

Этот идентификатор также отображается в поле serdes/meta → id (эти идентификаторы должны совпадать):

serdes/meta:
  - id: r6vC_vLmo9zG6_r9sAuYG

Чтобы устранить неоднозначность сущностей с одинаковыми именами, Glarus BI включает идентификаторы сущностей в имена файлов и каталогов для экспортируемых сущностей.

r6vC_vLmo9zG6_r9sAuYG_products_by_week.yaml
IA96oUzmUbYfNFl0GzhRj_accounts_model.yaml
KUEGiWvoBFEc5oGQCEnPg_converted_customers.yaml

Например, в Примере сериализованного вопроса выше, вы можете видеть поле collection_id:

collection_id: onou5H28Wvy3kWnjxxdKQ

Этот идентификатор относится к коллекции, в которой был сохранен вопрос. В реальном экспорте вы сможете найти файл YAML для этой коллекции, имя которого начинается с ее идентификатора: onou5H28Wvy3kWnjxxdKQ.

Базы данных, схемы, таблицы и поля идентифицируются по имени

По умолчанию Glarus BI экспортирует некоторые параметры базы данных и модели данных. Экспорт по умолчанию исключает строки подключения к базе данных. Вы можете явно включить строки подключения к базе данных. Вы также можете полностью исключить модель данных.

Glarus BI сериализует базы данных и таблицы в каталоге databases. Он будет включать файлы YAML для каждой базы данных, таблицы, поля, сегмента и метрики.

Базы данных, таблицы и поля упоминаются по их именам (в отличие от элементов, специфичных для Metabase, которые упоминаются по идентификаторам сущностей).

Например, в Примере сериализованного вопроса, есть несколько ключей YAML, которые ссылаются на Sample Database:

database_id: Sample Database
---
dataset_query:
  database: Sample Database

В описании фильтра поля (category_filter:) в этом примере вы можете увидеть ссылку на поле, которое используется для заполнения параметров фильтра.:

dimension:
  - field
  - - Sample Database
    - PUBLIC
    - PRODUCTS
    - CATEGORY

Он ссылается на поле CATEGORY в таблице PRODUCTS в схеме PUBLIC в Sample Database. Сериализованная Sample Database в каталоге databases также будет включать файлы YAML для этого поля и таблицы.

Как работает импорт

Во время импорта Glarus BI будет читать предоставленные файлы YAML и создавать элементы в соответствии со спецификациями YAML. Пример сериализованного вопроса как Glarus BI записывает информацию, необходимую для реконструкции элемента.

Metabase не будет удалять элементы из целевого экземпляра во время импорта, но перезапишет элементы, которые уже существуют.

Glarus BI опирается на Идентификаторы сущностей чтобы выяснить, какие элементы создать или перезаписать, и каковы отношения между элементами. При импорте в экземпляр, в котором уже есть какой-то контент, имейте в виду:

  • Если вы импортируете элемент с entity_id, который уже существует в вашей целевой Glarus BI, существующий элемент будет перезаписан.

    В частности, это означает, что если вы экспортируете вопрос, затем вносите изменения в экспортированный файл YAML — например, переименовываете вопрос, напрямую редактируя поле name — а затем импортируете отредактированный файл обратно, Glarus BI попытается применить внесенные вами изменения к YAML.

  • Если вы импортируете элемент с пустым entity_id (и пустым serdes/meta → id), Glarus BI создаст новый элемент.

  • Все элементы и источники данных, на которые есть ссылки в YAML, должны либо уже существовать в целевой Glarus BI, либо быть включены в импорт.

Например, если экспортированный YAML имеет поле collection_id: onou5H28Wvy3kWnjxxdKQ, то коллекция onou5H28Wvy3kWnjxxdKQ должна уже существовать в целевом экземпляре, или должен быть файл YAML с экспортом коллекции, имеющей этот идентификатор.

Лучшие практики сериализации

Используйте одну и ту же версию Glarus BI для исходного и целевого экземпляра

В настоящее время сериализация работает только в том случае, если исходная и целевая Glarus BI имеют одинаковую основную версию. Если вы используете команды сериализации CLI, версия файла .jar, которую вы используете для запуска команд сериализации, должна соответствовать как исходной, так и целевой версиям Glarus BI.

Если вы используете H2 в качестве базы данных приложения, вам необходимо остановить Glarus BI перед импортом или экспортом

Если вы используете Postgres или MySQL в качестве базы данных приложения, вы можете импортировать и экспортировать, пока Glarus BI все еще работает.

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

Просто примечание: сериализация не предназначена для резервного копирования вашей Glarus BI.

См. Резервное копирование.

Если вместо этого вы хотите выполнить однократную миграцию из базы данных H2 по умолчанию, включенной в Glarus BI, в MySQL/Postgres, то воспользуйтесь руководством по миграции.

Glarus BI добавляет журналы в экспорт и импорт

Экспорт: Glarus BI добавляет журналы в сжатый каталог как export.log.

Импорт: Вы можете добавить флаг -o - для экспорта журналов непосредственно в терминал или -o import.log для сохранения в файл.

Сериализация с помощью команд CLI

Glarus BI предоставляет экспорт и импорт с CLI коммандами.

См как работает экспорт, как работает импорт, и лучшие практики сериализации для получения общей информации о сериализации.

Экспорт с CLI

Чтобы экспортировать содержимое экземпляра Glarus BI, перейдите в каталог, в котором запущен Glarus BI JAR, и выполните:

java -jar metabase.jar export dir_name

Где dir_name может быть любым именем, которое вы хотите использовать для названия каталога.

опции export

Чтобы просмотреть список опций export, используйте команду help:

java -jar metabase.jar help export

Который запустится и выведет на экран что-то вроде:

export path & options
	 Serialize Metabase instance into directory at `path`.
	 Options:
	   -c, --collection ID             Export only specified ID; may occur multiple times.
	   -C, --no-collections            Do not export any content in collections.
	   -S, --no-settings               Do not export settings.yaml
	   -D, --no-data-model             Do not export any data model entities; useful for subsequent exports.
	   -f, --include-field-values      Include field values along with field metadata.
	   -s, --include-database-secrets  Include database connection details (in plain text; use caution).

--collection

По умолчанию Glarus BI включит все коллекции (кроме личных) в экспорт. Чтобы включить личные коллекции, необходимо явно добавить их с помощью флага --collection.

Флаг --collection (псевдоним -c) позволяет указать по идентификатору одну или несколько коллекций для включения в экспорт. Идентификатор коллекции можно найти в URL-адресе коллекции, например, для коллекции по адресу: your-metabase.com/collection/42-terraforming-progress идентификатор будет 42.

Если вы хотите указать несколько коллекций, разделите идентификаторы запятыми. Например,

java -jar metabase.jar export export_name --collection 1,2,3

--no-collections

Флаг --no-collections (псевдоним -C) сообщает Glarus BI о необходимости исключить все коллекции из экспорта.

--no-settings

Флаг --no-settings (псевдоним -S) сообщает Glarus BI о необходимости исключить файл settings.yaml, который включает настройки для всего сайта, который экспортируется по умолчанию.

--no-data-model

Флаг --no-data-model (псевдоним -D) сообщает Glarus BI исключить настройки метаданных таблицы из экспорта. Администраторы определяют настройки метаданных на вкладке Метаданные таблицы настроек администратора.

--include-field-values

Флаг --include-field-values (псевдоним -f) сообщает Glarus BI включить выборочные значения для значений полей, которые она использует для представления раскрывающихся меню. По умолчанию Glarus BI исключает эти выборочные значения полей.

--include-database-secrets

Флаг --include-database-secrets (псевдоним -s) сообщает Glarus BI о необходимости включить сведения о подключении, включая имя пользователя и пароль базы данных. По умолчанию она исключает эти секреты подключения к базе данных. Если вы не используете этот флаг, вам нужно будет вручную ввести учетные данные в целевой Glarus BI.

Импорт с CLI

Чтобы импортировать экспортированные артефакты в экземпляр Glarus BI, перейдите в каталог, в котором запущена целевая Glarus BI (в которую вы хотите импортировать), и используйте следующую команду, где path_to_export — это путь к экспорту, который вы хотите импортировать:

java -jar metabase.jar import path_to_export

В настоящее время вы можете импортировать экспортированные артефакты только в экземпляр Glarus BI, созданный из той же версии Glarus BI.

import options

Большинство опций определяются при экспорте данных из Glarus BI. Чтобы просмотреть список флагов импорта, выполните:

java -jar metabase help import

который выводит:

import path & options
         Load serialized Metabase instance as created by the [[export]] command from directory `path`.

Другое использование сериализации

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

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

Использование сериализации для дублирования контента в пределах одной метабазы

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

Прежде чем начать это опасное путешествие, ознакомьтесь с как работает экспорт и как работает импорт.

Вам нужно помнить:

  • Импорт элемента с уже существующим идентификатором сущности перезапишет существующий элемент. Чтобы использовать существующий файл YAML для создания нового элемента, вам нужно либо a) создать новый идентификатор сущности, либо b) очистить идентификатор сущности.

  • Два элемента не могут иметь одинаковые идентификаторы сущности.

  • Поля entity_id и serdes/meta → id в файле YAML должны совпадать.

  • Если поля entity_id и serdes/meta → id в файле YAML для элемента пустые, Glarus BI создаст новый элемент с новым идентификатором сущности.

  • Все элементы и источники данных, на которые ссылается элемент, должны либо уже существовать в целевой Glarus BI, либо быть включены в импорт.

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

Это означает, что вам может потребоваться многоэтапный экспорт/импорт: сначала создайте некоторые необходимые вам элементы (например, коллекции) в Glarus BI, экспортируйте их, чтобы получить их идентификаторы сущностей, затем экспортируйте то, что вы хотите дублировать, и используйте эти идентификаторы в элементах, которые ссылаются на них.

Например, чтобы дублировать коллекцию, содержащую только вопросы, которые построены непосредственно на необработанных данных (не на моделях или других сохраненных вопросах), не меняя источник данных для вопросов, вы можете использовать такой процесс:

  1. В Glarus BI создайте коллекцию «шаблонов» и добавьте элементы, которые вы хотите дублировать.

  2. В Glarus BI создайте новую коллекцию, которая будет служить целью для дублируемых элементов.

  3. Экспортируйте коллекцию шаблонов и целевую коллекцию (вы можете использовать параметры экспорта чтобы экспортировать только несколько коллекций). Файлы YAML для шаблонов вопросов в экспорте будут иметь собственные идентификаторы сущностей и ссылаться на идентификатор сущности коллекции шаблонов.

  4. Получите идентификатор сущности целевой коллекции из ее экспорта.

  5. В файлах YAML для вопросов в экспорте коллекции шаблонов:

  • Очистите значения полей entity_id и serdes/meta → id для вопросов. Это гарантирует, что вопросы-шаблоны не будут перезаписаны, и вместо этого Glarus BI создаст новые вопросы.

  • Замените ссылки collection_id на коллекцию шаблонов на идентификатор новой коллекции

  1. Импортируйте отредактированные файлы.

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

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

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

Использование сериализации для замены источника данных для запросов в одном экземпляре

Если вы хотите изменить источник данных для некоторых запросов в вашей Glarus BI — например, только для заросов в одной коллекции — вы можете сериализовать вопросы вручную, а затем отредактировать экспортированные файлы YAML.

Если вы хотите переключить каждый запрос, созданный на основе базы данных A, на использование базы данных B, а база данных B имеет точно такую ​​же схему, как база данных A, вам не нужно использовать сериализацию: вы можете просто поменять строку подключения в Администрирование > Базы данных

Ваши базы данных должны иметь один и тот же движок, и в идеале они должны иметь одинаковую схему.

Вам нужно помнить:

  • Базы данных, таблицы и поля упоминаются в Glarus BI по имени

  • Данные о подключении к базе данных не экспортируются по умолчанию. Чтобы экспортировать данные о подключении к базе данных, вам нужно указать это в параметрах экспорта.

  • Базы данных, таблицы и поля, на которые ссылается элемент, должны либо уже существовать в целевой Glarus BI, либо быть включены в импорт.

Например, если вы хотите переключить все вопросы в коллекции Обзоры фильмов, чтобы использовать базу данных Романтика вместо базы данных Ужасы, и обе базы данных имеют одинаковую схему, вы можете выполнить следующий процесс:

1.В Glarus BI добавьте новое подключение к базе данных в Администрирование > Базы данных и назовите его Романтика.

  1. Экспортируйте коллекцию Обзоры фильмов.

Вы можете указать Glarus BI экспортировать одну коллекцию или экспортировать все коллекции и просто работать с файлами в папке для коллекции Обзоры фильмов

  1. В файлах YAML для элементов из этой коллекции замените все ссылки на базу данных Ужасы ссылками на Романтика

  2. Импортируйте отредактированные файлы.

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

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

Переход со старых команд сериализации

Если вы обновляетесь с Glarus BI версии 46.X или более ранней, вот что вам нужно знать:

  • Команда export заменяет команду dump.

  • Команда import заменяет команду load.

Еще несколько изменений, на которые стоит обратить внимание:

  • Экспортированные файлы YAML имеют немного другую структуру:

  • Glarus BI будет добавлять к каждому файлу префикс в виде 24-символьного идентификатора сущности (например, IA96oUzmUbYfNFl0GzhRj_accounts_model.yaml). Вы можете запустить команду Glarus BI, чтобы удалить идентификаторы сущностей перед эксопртом.

    • Дерево файлов немного отличается.

  • Чтобы сериализовать личные коллекции, вам просто нужно включить идентификаторы личных коллекций в список идентификаторов, разделенных запятыми, после параметра -c (сокращение от --collection).

Если вы написали скрипты для автоматизации сериализации, вам нужно:

  • Повторно сериализовать вашу Glarus BI с помощью обновленной Glarus BI (которая использует новые команды export и import). Обратите внимание, что сериализация будет работать только в том случае, если вы экспортируете и импортируете свою Glarus BI с помощью той же версии Glarus BI.

  • Обновите эти скрипты новыми командами. Смотрите новые опции экспорта.

  • Если ваши скрипты выполняют какую-либо постобработку экспортированных файлов YAML, вам может потребоваться обновить скрипты, чтобы учесть немного отличающиеся структуры каталогов и файлов YAML.

Еще почитать