Создание и публикация датасетов

Для того чтобы датасеты заведенные в Apache Atlas стали опубликованными в маркетплейсе, необходимо выполнить ряд требований, как к датасетам, так и к бизнес-терминам. В этом разделе будут рассмотрено, что необходимо сделать, чтобы создать и опубликовать датасет, как управлять доступностью датасета и его полей.

В рамках платформы датасет является надстройкой над таблицей ClickHouse. Все основные средства управления датасетами такие как:

• Создание
• Редактирование
• Управление доступностью и конфиденциальностью

Реализовано с помощью Apache Atlas.

Датасет, как и бизнес-термин возможно создать или отредактировать 3-мя способами:

• Вручную, используя интерфейс Apache Atlas
• С помощью загрузки Excel-файла
• С помощью API Apache Atlas

Требования к публикации датасетов

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

1. К датасету должна быть обязательно привязана классификация agg_dataset_classification. У классификации обязательно должны быть заполнены поля:

   • clientAudienceSource
   • confidentiality
   • detailing
   • updateFrequency
   • visibilityArea

2. К датасету должна быть обязательно привязана таблица (entity с типом agg_dataset_table)

3. К каждому полю таблицы (entity с типом agg_dataset_table) обязательно должен быть привязан бизнес-термин с одной из следующих классификаций:

   • entity
   • static_attribute
   • computed_attribute

   Каждая из этих классификаций также имеет набор обязательных полей:

   1. entity и static_attribute Эти классификаторы бизнес терминов имеют обязательные поля:

      • confidentiality
      • status
      • visibilityArea

   2. computed_attribute Этот классификатор отличается от остальных дополнительными полями. Таким образом у этого классификатора есть следующие обязательные поля:

      • confidentiality
      • status
      • visibilityArea
      • aggregationMethodology
      • calculationMethod
      • measurementUnit
      • minimalCut

4. В наборе данных обязательно должен быть валидный атрибут “Согласия” и минимум 1 валидный атрибут матчинга

5. В рамках одного набора данных не должны повторяться значения атрибутов матчинга (например: у датасета не может быть 2-х полей с атрибутом матчинга phone).

6. Бизнес-термин с назначенным атрибутом матчинга должен привязываться к полю таблицы определенного типа:

   1. Бизнес-термины с атрибутами матчинга:

      • last_name
      • first_name
      • patronymic
      • phone
      • passport
      • birthday
      • email
      • gender

      Должны привязываться к полям с типом строка.

   2. Бизнес-термины с атрибутами матчинга:

      • agreement

      Должны привязываться к полям с типом число. Допустимые значения 0 и 1.

danger

При публикации датасета, обратите внимание на область видимости и конфиденциальность атрибутов матчинга. В случае если используемые в датасете бизнес термины с атрибутами матчинга будут не общедоступными (конфиденциальность = не конфиденциально и область видимости = доступно партнерам в группе компаний) ваши партнеры не смогут воспользоваться вашими опубликованными датасетами

note

Правила публикации распространяются на все датасеты, вне зависимости от выбранного метода создания датасета

Далее будут рассмотрены все 3 способа создания датасетов:

• Создание и публикация датасетов в интерфейсе Apache Atlas
• Создание и публикация датасетов при помощи загрузки Excel-файлов
• Создание и публикация датасетов с использованием API Apache Atlas

Создание и публикация датасетов в интерфейсе Apache Atlas

Датасет в рамках Apache Atlas является таким же entity, как и таблица, БД или поле таблицы.

В этом разделе будет рассмотрено как:

• Создать датасет
• Присвоит и заполнить классификатор датасета
• Присвоить полям таблицы бизнес термины

Создание датасета

Для того чтобы создать новый датасет, необходимо:

1. Перейти в Apache Atlas

2. В правом верхнем углу нажать на кнопку “Create Entity”

3. В появившемся модальном окне, в выпадающем списке выбрать agg_dataset. После в модальном окне будут отражены поля для заполнения.

4. Перевести переключатель required/all в положение all.

5. В полях модального окна необходимо заполнить поля:

• Description - описание датасета - это описание будет отображаться в ADCP в качестве описания
• NameEn - Английское наименование датасета - это описание будет отображаться в ADCP в качестве английского наименования
• NameRu - Русское наименование датасета - это описание будет отображаться в ADCP в качестве русского наименования
• QualifiedName - Техническое наименование датасета, аналог ID датасета в рамках Apache Atlas, обязательно должно быть уникальным.
• Table - Ссылка на таблицу, на базе которой будет строиться датасет. В поле необходимо указывать qualifiedName таблицы на которую должен ссылаться датасет.

6. Нажать на кнопку “Create”. После чего датасет и его связь с таблицей будет создана, и в текущей вкладке откроется детальная страница датасета. При переходе на вкладку “Relationships”, в блоке Table будет отображаться ссылка на таблицу на которую ссылается датасет.

После создания датасета, без назначения классификатора и присвоения бизнес терминов датасет не будет опубликован, но будет отображаться в ADCP в разделе “мои датасеты” как неопубликованный датасет. Такой датасет не будет доступен для работы с ним в маркетплейсе и остальных разделах системы.

Присвоение классификатора датасета

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

1. На детальной странице датасета, которая, например, открывается сразу после создания датасета нажать на кнопку “+” напротив надписи “Classification”

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

3. Заполните поля:

Наименование поля	Описание поля	Обязательное для заполнения для публикации
clientAudienceSource	Устаревшее поле. Ранее использовалось для указания является ли датасет источником уникальных клиентов. Для публикации выберите любое значение из выпадающего списка	да
confidentiality	Используется для указания уровня конфиденциальности датасета.	да
dataOwner	Указывается поле владельца данных - человека ответственного за датасет и его содержание	да
detailing	Уровень детализации датасета. Указывается насколько детальные данные в таблице, например когда каждая строка датасета относится к одному клиенту, но в детализации указывается “Клиент”	да
updateFrequency	Частота обновления, то с какой частотой планируется обновлять данные в датасете.	да
visibilityArea	Используется для указания уровня видимости датасета среди компаний партнеров	да

4. Нажмите на кнопку “Add”. После чего выбранная классификации и заполненные атрибуты присвоются датасету. На месте кнопки “+” напротив надписи Classification появится наименование классификатора. На вкладке Classifications вы увидите назначенный вами классификатор и значения атрибутов. После синхронизации датасета в ADCP он так-же останется не опубликованным, данные введенные в классификатор будут отображаться в описании датасета.

Назначения бизнес-терминов полям таблицы датасета

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

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

1. На детальной странице датасета открыть вкладку “Relations” и в поле table кликнуть на наименование таблицы. После нажатия должна будет открыться детальная страница таблицы.

2. На детальной странице таблицы, во вкладке “Relations” в поле “Fields” будет указан перечень полей таблицы. Необходимо открыть каждое поле в новой или в этой же вкладке.

3. На детальной странице поля необходимо нажать на кнопку “+” напротив terms. Откроется модальное окно для выбора бизнес-термина.

4. В модальном окне необходимо выбрать 1 термин, отражающий суть поля и нажать на кнопку “Assign”. По результату модальное окно закроется, на месте кнопки “+” будет отображено наименование бизнес-термина, на вкладке “Classifications” будут указаны значения классификаторов присвоенного бизнес-термина. После синхронизации данных в ADCP, в списке полей детесета вы увидите что напротив поля появился назначенный вами термин.

Такое действие необходимо будет выполнить для каждого поля таблицы.

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

Создание и публикация датасетов при помощи загрузки Excel-файлов

Бизнес-термины возможно создать с помощью экспорта Excel-Файла, в формате предоставленного шаблона.

Для этого необходимо:

1. Создать датасет

2. Указать связь таблиц и датасетов, полей таблиц и бизнес-терминов

Далее в инструкциях описана загрузка каждой страницы отдельно, на практике, вы можете единожды заполнить все страницы Excel-файла и загрузить всю информацию единожды.

Шаблон файла для загузки

Создание датасетов

Для того чтобы создать датасет, необходимо:

1. В шаблоне Excel-файла, на странице Набор данных заполнить поля соответствующие полям датасета и его классификатора:

Наименование поля	Значение поля	Обязательное поле	Возможные значения
Наименование (Рус)	Наименование датасета на русском, которое будет отображаться в маркетплейсе	да	Транзакции клиентов
Наименование (Eng)	Наименование датасета на английском, которое будет отображаться в маркетплейсе	да	Client transactions
Описание	Краткое описание содержимого датасета, позволяющее понять возможности его применения	да	Информация о среднем чеке покупок клиентов
Детализация	Уровень детализации датасета. Указывается насколько детальные данные в таблице, например когда каждая строка датасета относится к одному клиенту, но в детализации указывается “Клиент”	да	Клиент
Конфиденциальность	Используется для указания уровня конфиденциальности датасета	да	1 - «Доступно», 2 - «Конфиденциально», 3 - «Строго-конфиденциально»
Область видимости	Используется для указания уровня видимости датасета среди компаний партнеров	да	1 - Частные данные, 22 - Метаданные видимы только внутри экосистемы (группы компаний)
Организация-владелец	Используется для указания уровня конфиденциальности датасета	да	Vaultee
Владелец данных	Указывается имя владельца данных - человека ответственого за датасет и его содержание	да	Сергей Петров
Частота обновления	Частота обновления, то с какой частотой планируется обновлять данные в датасете.	да	Еженедельно
Бизнес-сущность	Ссылка на бизнес термин который может описать датасет	нет	Клиент

2. В интерфейсе ADCP перейти в раздел “Глоссарий”.

3. В верхнем правом углу нажать на кнопку загрузки.

4. В открывшемся модальном окне нажать на кнопку “Загрузить”.

5. Найти на вашем локальном компьютере файл с заполненным шаблоном и загрузить его.

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

Связь таблиц и датасетов, полей таблиц и бизнес терминов

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

1) В шаблоне Excel-файла, на странице связь НД с бизнес-термином заполнить поля соответствующие описав какой датасет с какой таблицей ассоциировать и каким полям таблицы назначить бизнес-термины:

Наименование поля	Значение поля	Обязательное поле	Возможные значения
Наименование набора данных	Русское наименование датасета который необходимо привязать к таблице	да	Транзакции клиентов
Наименование физической таблицы	Наименование таблицы, которая уже добавлена в Apache Atlas, в том виде, в котором она хранится в ClickHouse	да	some_table
Поле набора данных	Наименование поля, которая уже добавлена в Apache Atlas, в том виде, в котором оно хранится в ClickHouse	да	some_field
Наименование бизнес-термина	Русское наименование бизнес термина, который уже заведен в Apache Atlas	да	Клиент
Организация	Наименование вашей организации	да	Aггрегион

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

2) В интерфейсе ADCP перейти в раздел “Глоссарий”.

3) В верхнем правом углу нажать на кнопку загрузки.

4) В открывшемся модальном окне нажать на кнопку “Загрузить”.

5) Найти на вашем локальном компьютере файл с заполненным шаблоном и загрузить его.

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

Создание и публикация датасетов с использованием API Apache Atlas

Для создания набора данных в Apache Atlas c помощью API, необходимо выполнить запрос на создание экземпляра сущности и присвоить созданному экземпляру (entity) заранее созданный классификатор. Для корректной работы ADCP командой Vaultee была создана собственная модель данных для набора данных agg_dataset.

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

curl --location --request POST 'http://dcp_atlas_url/api/atlas/v2/entity' \
--header 'Authorization: Basic Y1111111111111=' \
--header 'Content-Type: application/json' \
--data-raw '{
        {
    "entity":
    {
        "typeName": "agg_dataset",
        "attributes":
        {
            "description": "Перечень клиентов",
            "nameEn": "Сlient",
            "nameRu": "Клиент",
            "qualifiedName": "Клиент",
            "replicatedFrom":
            [],
            "replicatedTo":
            []
        },
        "relationshipAttributes":
        {
            "meanings":
            [],
            "table":
            {
                "guid": "aed9cca7-58ba-49f6-8993-8d1d392aa8a2",
                "typeName": "agg_rdbms_table"
            }
        },
        "guid": -1
    },
    "referredEntities":
    {}
}'

Где:

typeName – наименование модели набора данных Vaultee

nameRu – наименование термина на русском. Обязательное для заполнения поле.

nameEn – наименование термина на английском. Обязательное для заполнения поле

qualifiedName – уникальное имя набора данных, в скрипте Vaultee используется русское наименование термина. Обязательное для заполнения поле.

description – описание набора данных. Обязательное для заполнения поле.

replicatedFrom – служебное поле, не требует заполнения

replicatedTo - служебное поле, не требует заполнения

meanings – ссылки связи набора данных с объектами глоссария (term в Apache Atlas). Не Обязательное для заполнения поле.

table – ссылка связи набора данных с таблицей, указывает на guid объекта (поле guid) с типом agg_rdbms_table (поле typeName). Обязательное для заполнения поле. Связь с Таблицей 1к1.

"guid": -1 – сигнализирует Apache Atlas о том, что это новый набор данных, который нужно создать.

После создания набора данных необходимо присвоить набору данных Классификатор agg_dataset_classification, для присвоения обязательных атрибутов.

Присвоение классификатора Набору данных

Для присвоения классификатора требуется выполнить запрос:

Где:

typeName - наименование классификатора, который необходимо присвоить бизнес-термину

attributes - массив атрибутов, свойственных этому классификатору (см. ниже пример)

propagate - признак наследуемости атрибутов классификатора бизнес-термина к объектам, к которым будет привязываться термин. Для корректной работы ADCP требуется указывать false

removePropagationsOnEntityDelete - признак наследуемости атрибутов при удалении. Для корректной работы ADCP требуется указывать false

validityPeriods - время валидности связи бизнес-термина и классификатора. Для корректной работы ADCP требуется оставлять пустым

entityGuids - массив с указанием guid бизнес-терминов, к которым привязывается классификатор

confidentiality - степень конфиденциальности Набора данных, обязательный для заполнения.

detailing - уровень детализации каждой сущности Набора данных, обязательный для заполнения.

clientAudienceSource - признак того является ли Набор данных эталонным списком клиентов, обязательный для заполнения.

visibilityArea - область видимости, обязательный для заполнения.

curl --location --request POST 'http://dcp_atlas_url/api/atlas/v2/entity/bulk/classification' \
--header 'Authorization: Basic Y1111111111111=' \
--header 'Content-Type: application/json' \
--data-raw '{
    "classification":
    {
        "typeName": "agg_dataset_classification",
        "attributes":
        {
            "confidentiality": enum,
            "detailing": "string",
            "clientAudienceSource": bool,
            "visibilityArea": enum
        },
        "propagate": false,
        "removePropagationsOnEntityDelete": false,
        "validityPeriods":
        []
    },
    "entityGuids":
    [
        "cce4e2e6-ebdc-48a0-94fd-1576ddd59675"
    ]
}'

Связь сущностей и бизнес-термина.

Для связи бизнес-термина и сущностей:

• Набор данных

• Поле

  Необходимо выполнить стандартный запрос Apache Atlas на связь entity и термина:

curl --location --request POST 'http://dcp_atlas_url/api/atlas/v2/glossary/terms/{{guid}}/assignedEntities' \
--header 'Authorization: Basic Y1111111111111=' \
--header 'Content-Type: application/json' \
--data-raw '
[{"guid":"94b3774c-7882-4ff3-bc1f-5a8515e638b3"}]
'

Где:

{{guid}} - в адресе guid бизнес-термина

guid - в теле запроса guid поля или набора данных

Матрица доступа к данным

Поскольку на доступность данных в датасете и сам датасет влияют атрибуты "Конфиденциальность" и "Область видимости" как самого датасета, так и его полей, понять как именно эти факторы влияют, может быть затруднительно.

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