Руководство по эксплуатации

## Оглавление - [Конфигурация](#конфигурация) - [Конфигурация экземпляра SDVG](#конфигурация-экземпляра-sdvg) - [Описание полей конфигурации экземпляра SDVG](#описание-полей-конфигурации-экземпляра-sdvg) - [Примеры конфигурации экземпляра SDVG](#примеры-конфигурации-экземпляра-sdvg) - [Конфигурация генерации данных](#конфигурация-генерации-данных) - [Описание полей конфигурации генерации данных](#описание-полей-конфигурации-генерации-данных) - [Примеры конфигурации генерации данных](#примеры-конфигурации-генерации-данных) - [Запуск](#запуск) - [Генерация данных](#генерация-данных) - [Игнорирование конфликтов](#игнорирование-конфликтов) - [Продолжение генерации](#продолжение-генерации)

Конфигурация

SDVG использует два конфигурационных файла: файл конфигурации экземпляра SDVG и файл конфигурации генерации данных.

Конфигурация экземпляра SDVG

Описание полей конфигурации экземпляра SDVG

Конфигурация экземпляра SDVG содержит следующие поля:

• log_format: Формат логов. Поддерживаемые значения: text, json. По умолчанию text.
• http: Конфигурация HTTP сервера, описывается структурой HTTPConfig.
• open_ai: Конфигурация OpenAI, описывается структурой OpenAI.

Структура http используется для описания конфигурации HTTP сервера, который может быть запущен для взаимодействия с SDVG, и содержит следующие поля:

• listen_address: Адрес для прослушивания HTTP-сервера. По умолчанию :8080.
• read_timeout: Таймаут для чтения данных. По умолчанию 1m (1 минута).
• write_timeout: Таймаут для записи данных. По умолчанию 1m (1 минута).
• idle_timeout: Таймаут для ожидания бездействия. По умолчанию 1m (1 минута).

Структура open_ai используется для описания конфигурации OpenAI и содержит следующие поля:

• api_key: API ключ для доступа к OpenAI.
• base_url: Базовый URL для API OpenAI.
• model: Модель OpenAI.

Примеры конфигурации экземпляра SDVG

Пример конфига для HTTP сервера:

http:
  listen_address: localhost:8080
  read_timeout: 1m
  write_timeout: 30s
  idle_timeout: 1m30s

Пример конфига для OpenAI:

open_ai:
  api_key: "sk-123"
  base_url: "http://10.0.1.100:11434/v1"
  model: "deepseek-r1:70b-llama-distill-q8_0"

Конфигурация генерации данных

Данная конфигурация используется непосредственно для генерации данных после запуска SDVG.

Описание полей конфигурации генерации данных

Конфигурация генерации данных содержит следующие поля:

• random_seed: Сид для генерации случайных чисел. Если не указан или равен 0, используется случайное значение.
• workers_count: Количество потоков для генерации данных. По умолчанию равно количеству CPU умноженному на 4.
• batch_size: Размер пачки данных для генерации и отправки в выходное хранилище. По умолчанию 1000.
• models: Карта моделей данных, где ключ - имя модели, значение - структура models[*].
• models_to_ignore: Список моделей, которые не надо генерировать в данном запуске SDVG (внешние ключи на эти модели при этом будут работать, если сохраняются значения random_seed и rows_count).
• output: Конфигурация вывода сгенерированных данных, описывается структурой output.

Структура output описывает конфигурацию вывода сгенерированных данных:

• type: Тип выходного формата сгенерированных данных. Поддерживаемые значения: devnull, csv, parquet, http, tcs. По умолчанию csv.
• dir: Директория для записи сгенерированных данных. По умолчанию ./output.
• create_model_dir: Параметр, отвечающий за то, создавать ли при записи отдельные директории для каждой из моделей. По умолчанию false.
• params: Параметры для выбранного типа выходного формата, описываются структурой output.params.
• checkpoint_interval: Параметр, отвечающий за то, как часто будут обновляться файлы, содержащие текущий прогресс. По умолчанию 5s (5 секунд).

Структура models[*] описывает модель генерируемых данных и содержит следующие поля:

• rows_count: Количество строк для генерации. Обязательное поле.
• rows_per_file: Количество строк на один файл. Поддерживается для csv и parquet. По умолчанию равно rows_count.
• generate_from: Номер строки, с которой нужно начать генерацию. По умолчанию 0.
• generate_to: Номер строки, до которой нужно генерировать. По умолчанию равен rows_count.
• model_dir: Директория для записи сгенерированных данных конкретной модели относительно output_dir. По умолчанию название модели.
• columns: Список столбцов модели данных, описанных структурой models[*].columns.
• partition_columns: Список столбцов, участвующих в партиционировании данных. Поддерживается для parquet и csv.

Структура models[*].partition_columns описывает как столбец участвует в партиционировании данных:

• name: Имя столбца из схемы models[*].columns. Обязательное поле.
• write_to_output: Флаг, указывающий, нужно ли записывать партиционный столбец в конечные файлы с данными.

Структура models[*].columns описывает столбец модели данных и содержит следующие поля:

• name: Имя столбца. Обязательное поле.
• type: Тип данных столбца. Поддерживаемые значения: integer, float, string, datetime, uuid.
• type_params: Параметры для выбранного типа данных, описанные структурой models[*].columns[*].type_params.
• values: Перечисление возможных значений столбца. Не может использоваться вместе с параметрами distinct.
• ordered: Флаг, указывающий, должны ли значения в столбце быть упорядоченными (аналог sequence).
• distinct_percentage: Процент уникальных значений в столбце. Должен быть между 0 и 1. Не работает совместно с distinct_count.
• distinct_count: Количество уникальных значений в столбце. Должно быть больше 0. Не работает совместно с distinct_percentage.
• null_percentage: Процент пустых значений в столбце. Должен быть между 0 и 1.
• ranges: Набор диапазонов параметров для столбца, позволяющий указать несколько конфигураций с их процентным распределением (range_percentage). Каждый диапазон (ranges[*]) может содержать:
• type_params: Параметры для выбранного типа данных, описанные структурой models[*].columns[*].type_params.
• values: Перечисление возможных значений в данном диапазоне.
• ordered: Флаг упорядоченности значений.
• distinct_percentage: Процент уникальных значений в диапазоне.
• distinct_count: Количество уникальных значений в диапазоне.
• null_percentage: Процент пустых значений в диапазоне.
• range_percentage: Процентное соотношение этого диапазона относительно всей выборки.
• parquet_params: Параметры для форматирования значений в выходном формате parquet.
• foreign_key: Имя столбца в формате model_name.column_name, на который ссылается внешний ключ, значения будут браться из него. Не может использоваться вместе с другими параметрами столбца.
• foreign_key_order: Флаг, указывающий на то, что надо использовать порядок значений из внешнего ключа. Полезно, если необходимо сохранить соответствие значений между колонками из внешней таблицы.

Внимание: параметры ranges и прямое указание параметров на уровне столбца (values, type_params, distinct_percentage, distinct_count, null_percentage, ordered) взаимоисключающие. Использовать их одновременно нельзя.

Структура models[*].columns[*].parquet_params:

• encoding: Кодировка для столбца. Поддерживаемые значения: PLAIN, RLE_DICTIONARY, DELTA_BINARY_PACKED, DELTA_BYTE_ARRAY, DELTA_LENGTH_BYTE_ARRAY. По умолчанию PLAIN.

Структура models[*].columns[*].type_params для типа данных integer:

• bit_width: Ширина битов для целого числа. Поддерживаемые значения: 8, 16, 32, 64. По умолчанию 32.
• from: Минимальное значение для целого числа. По умолчанию минимальное значение для выбранной ширины битов.
• to: Максимальное значение для целого числа. По умолчанию максимальное значение для выбранной ширины битов.

Структура models[*].columns[*].type_params для типа данных float:

• bit_width: Ширина битов для вещественного числа. Поддерживаемые значения: 32, 64. По умолчанию 32.
• from: Минимальное значение для вещественного числа. По умолчанию минимальное значение для выбранной ширины битов.
• to: Максимальное значение для вещественного числа. По умолчанию максимальное значение для выбранной ширины битов.

Структура models[*].columns[*].type_params для типа данных string:

• min_length: Минимальная длина строки. По умолчанию 1.
• max_length: Максимальная длина строки. По умолчанию 32.
• logical_type: Логический тип строки. Поддерживаемые значения: first_name, last_name, phone, text.
• template: Шаблон для генерации строки. Символ A - любая большая буква, символ a - любая маленькая буква, символ 0 - любая цифра, символ # - любой символ. Остальные символы остаются как есть.
• locale: Локаль для генерации строк. Поддерживаемые значения: ru, en. По умолчанию en.
• without_large_letters: Флаг, указывающий, исключать ли большие буквы из строки.
• without_small_letters: Флаг, указывающий, исключать ли маленькие буквы из строки.
• without_numbers: Флаг, указывающий, исключать ли числа из строки.
• without_special_chars: Флаг, указывающий, исключать ли специальные символы из строки.

Структура models[*].columns[*].type_params для типа данных datetime:

• from: Минимальное значение для даты и времени. По умолчанию 01.01.1900.
• to: Максимальное значение для даты и времени. По умолчанию 01.01.2025.

Структура output.params для формата csv:

• float_precision: Точность чисел с плавающей запятой. По умолчанию 2.
• datetime_format: Формат даты и времени. По умолчанию 2006-01-02T15:04:05Z07:00.
• without_headers: Флаг, указывающий, исключать ли CSV заголовок из файлов с данными.
• delimiter: Односимвольный CSV разделитель. По умолчанию ,.

Структура output.params для формата parquet:

• compression_codec: Кодек сжатия. Поддерживаемые значения: UNCOMPRESSED, SNAPPY, GZIP, LZ4, ZSTD. По умолчанию UNCOMPRESSED.
• float_precision: Точность чисел с плавающей запятой. По умолчанию 2.
• datetime_format: Формат даты и времени. Поддерживаемые значения: millis, micros. По умолчанию millis.

Структура output.params для формата http:

• endpoint: Конечная точка для отправки данных.
• timeout: Таймаут для отправки данных, указывается в формате строки: комбинация h, m, s без пробелов, например: 1h, 5m30s, 2h5s. По умолчанию 1m (1 минута).
• batch_size: Размер отправляемого в одном запросе массива данных. По умолчанию 1000.
• workers_count: Количество потоков для записи данных. По умолчанию 1. Является экспериментальным полем.
• headers: Заголовки http запроса, указываются в формате словаря. По умолчанию отсутствуют.

• format_template: Формат отправляемых данных, конфигурируемый с помощью шаблонов Golang. Для использования в поле format_template доступны:

• поля:

  • ModelName - имя модели.
  • Rows - массив записей, где каждый элемент является словарем, который представляет собой строку данных. Ключи словаря соответствуют названиям столбцов, а значения — данным в этих столбцах.
• функции:
  • len - возвращает длину переданного элемента.
  • json - преобразует переданный элемент в JSON строку.

Пример значения поля format_template:

format_template: |
  {
    "table_name": "{{ .ModelName }}",
    "meta": {
      "rows_count": {{ len .Rows }}
    },
    "rows": [
      {{- range $i, $row := .Rows }}
        {{- if $i}},{{ end }}
        {
          "id": {{ index $row "id" }},
          "username": "{{ index $row "name" }}"
        }
      {{- end }}
    ]
  }

Значение поля format_template по умолчанию:

format_template: |
  {
    "table_name": {{ .ModelName }},
    "rows": {{ json .Rows }}
  }

Структура output.params для формата tcs:

Подобна структуре для формата http, за исключением того, что поле format_template неизменяемое и всегда равняется значению по умолчанию.

Примеры конфигурации генерации данных

Пример конфигурации модели данных:

workers_count: 32
batch_size: 1000
random_seed: 0
output:
  type: "devnull"
  dir: output-dir
models:
  token:
    rows_count: 500000
    model_dir: token_model
    columns:
      - name: id
        type: uuid
      - name: user_id
        foreign_key: user.id
      - name: session_id
        type: string
        type_params:
          min_length: 16
          max_length: 32
        distinct_percentage: 1
      - name: token_type
        type: string
        values:
          - "access"
          - "refresh"
  user:
    rows_count: 10000
    columns:
      - name: id
        type: integer
        type_params:
          from: 1
          to: 500000
        ordered: true
      - name: str_id
        type: string
        ordered: true
      - name: ru_phone
        type: string
        type_params:
          logical_type: phone
          locale: ru
      - name: first_name_ru
        type: string
        type_params:
          logical_type: first_name
          locale: ru
      - name: last_name_ru
        type: string
        type_params:
          logical_type: last_name
          locale: ru
      - name: first_name_en
        type: string
        type_params:
          logical_type: first_name
      - name: passport
        type: string
        type_params:
          template: AA 00 000 000
        distinct_percentage: 1
        ordered: true
      - name: rating
        type: float
        type_params:
          from: 0.0
          to: 5.0
      - name: created
        type: datetime
        type_params:
          from: 2020-01-01T00:00:00Z
        ordered: true
      - name: birthday
        type: datetime
        ranges:
          - type_params:
              from: 1900-01-01T00:00:00Z
          - values: [null]
            range_percentage: 0.1
          - values:
              - 2005-03-09T04:44:00Z

Пример конфигурации для генерации CSV файлов:

output:
  type: csv
  params:
    float_precision: 1
    datetime_format: 2006-01-02
models:
  user:
    rows_count: 10000
    columns:
      - name: id
        type: uuid
      - name: session_id
        type: string
      - name: last_seen_at
        type: datetime
    partition_columns:
      - name: id
        write_to_output: false
      - name: session_id
        write_to_output: false

Пример конфигурации для генерации parquet файлов:

output:
  type: parquet
  params:
    float_precision: 1
    datetime_format: millis
    compression_codec: UNCOMPRESSED
models:
  token:
    rows_count: 500000
    rows_per_file: 250000
    columns:
      - name: id
        type: uuid
      - name: session_id
        type: string
        parquet:
          encoding: RLE_DICTIONARY
        distinct_percentage: 1
    partition_columns:
      - name: id
        write_to_output: true

Пример конфигурации для отправки сгенерированных данных по http:

output:
  type: http
  params:
    endpoint: "http://127.0.0.1:8080/insert"
    timeout: 30s
    headers:
      Authorization: "Bearer <token>"
    format_template: |
      {
        "table_name": "{{ .ModelName }}",
        "meta": {
          "rows_count": {{ len .Rows }}
        },
        "rows": {{ json .Rows }}
      }

models:
  user:
    rows_count: 10000
    columns:
      - name: id
        type: uuid
      - name: session_id
        type: string

Пример конфигурации для отправки сгенерированных данных в tcs:

output:
  type: tcs
  params:
    endpoint: "http://127.0.0.1:7101/insert"
    timeout: 30s
models:
  user:
    rows_count: 10000
    columns:
      - name: id
        type: uuid
      - name: session_id
        type: string

Запуск

Для запуска в интерактивном режиме достаточно запустить бинарный файл SDVG:

sdvg

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

sdvg -h
sdvg --help
sdvg generate -h

Генерация данных

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

Для запуска генерации с указанием файла конфигурации генерации:

sdvg generate ./models.yml

Игнорирование конфликтов

Если вы хотите автоматически удалить конфликтующие файлы в выходной директории и продолжить генерацию без дополнительных сообщений, используйте флаг -F или --force:

sdvg generate --force ./models.yml

Продолжение генерации

Для продолжения генерации с последней записанной строки:

sdvg generate --continue-generation ./models.yml

Важно: для корректного продолжения генерации нельзя менять конфигурацию генерации и уже сгенерированные данные.