diff --git a/pages/datamodule-usage.md b/pages/datamodule-usage.md new file mode 100644 index 0000000..f28098e --- /dev/null +++ b/pages/datamodule-usage.md @@ -0,0 +1,95 @@ +## Структура модуля данных + +## Подключение модуля данных к базовому модулю + +Чтобы модуль данных можно было использовать в базовом модуле, его нужно подключить, создав компонент `DataBox` специального типа - ссылку на модуль данных. + +```yaml +apiVersion: "unified-platform.cs.hse.ru/v1" +kind: DataBox +metadata: + name: dataref + namespace: pu-username-pa-appname +spec: + datasetReference: + datasetComponentRef: + name: some-data-collection + namespace: pu-otheruser-pa-datamodulename +``` + +- `dataref` - имя `DataBox` в текущем модуле - в `pu-username-pa-appname` +- `some-data-collection` - название компонента `DatasetComponent` в модуле данных. +- `pu-otheruser-pa-datamodulename` - название "модуля" в модуле данных. + +Модуль данных разворачивается так же, как и базовый модуль, и тоже содержит набор компонентов, определяемых манифестами в формате YAML. Поэтому, чтобы указать ссылку на компонент данных, нужно знать его полное имя: "имя модуля" + "имя компонента". + +## Использование модуля данных в пайплайне + +Чтобы подключить модуль данных к пайплайну, нужно + +1. Использовать MLDev-пайплайн +2. Подключить сам модуль данных к пайплайну через атрибут `mountDataset` в разделе `connectedBoxes`. +3. Использовать класс `StageSrc` вместо `StageVar` при указании переменной. +4. Указать, откуда монтируется переменная, через `mountFrom`. + +Например, в файле с определением `UnipPipeline`, + +```yaml +stage_prepare: !BasicStage &stage_prepare + name: stage_prepare + inputs: + - !StageSrc # Пункт 3 - переменная типа StageSrc + name: preparation_data + path: ./data/preparation + version: v1 + outputs: + - !StageVar + name: internal_state + script: + - python src/prepare.py + +... +# остальные этапы, если есть +... + +pipeline: !UnipPipeline + name: my-project + namespace: pu-username-pa-appname + variables: + - name: preparation_data + mountFrom: # Пункт 4 - переменная из ящика mydataset + box: + name: mydataset + - name: internal_state + - name: user_report + runs: + - *container_stage_prepare + - *container_stage_complete + connected_boxes: + - name: user-box + path: /userdata/ + default: true + mount_s3_box: + s3_box_name: users + - name: mydataset + mount_dataset: # Пункт 2 - подключение ящика dataref к пайплайну под именем mydataset + dataset_reference_name: dataref +``` + +Подключенный таким образом модуль данных можно использовать как обычную переменную пайплайна, дальнейшая работа с модулем данных не отличается от работы с другими переменными. + +## Доступ к модулю данных через API + +Модуль данных поддерживает работу через API, аналогичную [файловому API](./api-module.md). + +Основные отличия: + +1. Поддерживаются только запросы GET, то есть данные можно только считывать, но не записывать. +2. В ссылках вместо `files` используется ключевое слово `datasets`, а вместо названия компонента DataBox - название компонента DatasetComponent. + +Пример: + + +```sh +curl -X GET https://platform.stratpro.hse.ru/pu-otheruser-pa-datamodulename/datasets/some-data-collection/data/my_dir/my_file.txt -H "Content-Type: application/json" -u "username:password" +```