Про що ця стаття "Як написати контракт з даними англійською мовою"?

Повний посібник для інженерів з обробки даних: що таке договір з обробки даних, як його написати англійською мовою, необхідні розділи, словник і готові до використання шаблони.

Чи безкоштовна ця стаття?

Так. Усі статті на CoderSlingo, включно з цією, доступні безкоштовно без реєстрації.

Коли опубліковано цю статтю?

Цю статтю опубліковано у 2026 році.

Як написати контракт з даними англійською мовою

Договір з даними є формальною угодою між виробником набору даних і його споживачами, що визначає структуру, якість, свіжість і семантику даних. Оскільки архітектури мережі даних і платформи даних дозріли, контракти даних стали основним інструментом комунікації - і написання їх чітко англійською мовою є професійним вмінням, необхідним кожному інженеру даних. Цей посібник охоплює всю структуру, словниковий запас і мовні шаблони.

Що таке контракт на дані?

** Договір щодо даних ** — це формальна специфікація, яка описує:

Які дані надає виробник
Яка схема (поля, типи, формати) має дані
Які гарантії якості дає виробник
Який рівень обслуговування споживач може очікувати (свіжість, доступність)
Кому принадлежат данные и с кем связываться, когда что-то не так

Контракти з даними кодують * неявну * угоду між командами в * явний *, версійний документ — запобігаючи класичній проблемі, коли зміни схеми руйнують нижні користувачі без попередження.

“Перед тим, як ми дозволимо будь-якій команді використовувати тему замовлень у Kafka, вони підписують контракт на дані. Будь-яка зміна схеми вимагає нової версії договору і повідомлення споживача»

Для чого потрібні дані?

Без контрактів на дані, зміни, що призвели до розриву, зникають безслідно:

Стовпчик перейменовано → перерваний аналітичний панелі
Формат часових позначок змінюється → Конвейєр функцій ML зазнав невдачі
Додано нове поле з можливістю нульового завершення → перерви обробки нульових завершень

З контрактами даних:

Зміни версуються і оголошуються
Споживачі знають, на які гарантії стабільності вони можуть покластися
Продюсери знають, хто буде зачеплений, перш ніж вони щось змінять

Контрактна структура даних

Розділ 1: Заголовок / Метадані

# orders-v2.data-contract.yaml

id: "orders-v2"
version: "2.1.0"
status: "active"  # draft | active | deprecated
title: "Customer Orders"
description: >
  Contract for the customer orders dataset. Contains all confirmed orders
  placed through the web and mobile channels, refreshed hourly.
owner: "data-platform-team@acme.com"
contact:
  slack: "#data-platform"
  oncall: "https://pagerduty.com/teams/data-platform"
created: "2024-06-01"
updated: "2026-03-15"

** Ключові терміни: **

** Стан ** — стан життєвого циклу. * чернетка * означає ще нестабільний; * активний * означає у використанні; * застарілий * означає, що користувачам слід перейти на нову версію.

** Версії (семантичне версування): **

** Головна версія ** (2. 0. 0 → 3. 0. 0) — зміна, що призвела до розриву (вилучено поле, змінено тип)
** Minor version ** (2. 0. 0 → 2. 1. 0) — зворотньо сумісний додаток (нове необмежене поле)
** Латка ** (2. 0. 0 → 2. 0. 1) — лише оновлення документації або метаданих

«Це різка зміна — ми вилучаємо поле legacy_id. Це вимагає великої версії бум з v2 до v3.”

Розділ 2: Визначення схеми

У розділі ** схема ** описано кожне поле у наборі даних.

schema:
  - name: order_id
    type: string
    required: true
    description: "Unique identifier for the order (UUID v4)"
    example: "550e8400-e29b-41d4-a716-446655440000"

  - name: customer_id
    type: string
    required: true
    description: "Foreign key referencing the customers table"
    example: "cust-12345"

  - name: status
    type: string
    required: true
    description: "Current order status"
    enum: ["pending", "confirmed", "shipped", "delivered", "cancelled"]

  - name: total_amount
    type: decimal(10,2)
    required: true
    description: "Total order value in EUR, excluding VAT"
    constraints:
      minimum: 0.01

  - name: placed_at
    type: timestamp
    required: true
    description: "Timestamp of order placement in UTC (ISO 8601)"
    example: "2026-03-15T14:30:00Z"

  - name: metadata
    type: object
    required: false
    description: "Optional unstructured metadata from the order source"
    nullable: true

** Схема словника: **

** Обов’ язкове / нульове ** — чи має бути поле присутнім і не нульовим. * “Поле placed_at є обов’ язковим і не нульовим — будь- який запис, у якому його немає, є помилкою виробника.” *

** Enum ** — явний список коректних значень для поля. * « Поле стану є enum — будь- яке значення, яке не вказано у цьому списку, вказує на проблему з якістю даних. » *

** Точність типу ** — використовувати точні типи: decimal(10,2) замість просто « число »; timestamp with timezone замість просто « дата ».

Розділ 3: Якість SLOs (Цілі рівня обслуговування)

У цьому розділі визначається, які гарантії якості виробник зобов’ язується виконувати.

quality:
  completeness:
    - field: order_id
      threshold: 100%
      description: "Every record must have an order_id"
    - field: customer_id
      threshold: 99.9%
      description: "Occasional nulls accepted for guest checkouts"

  freshness:
    lag_slo: "< 30 minutes"
    description: "New orders must appear in the dataset within 30 minutes of confirmation"

  volume:
    daily_min: 1000
    daily_max: 500000
    description: "Expected daily record volume range. Alerts fire outside this range."

  uniqueness:
    - field: order_id
      constraint: "Must be globally unique — no duplicates"

** Якість словника: **

SLO (Service Level Objective) — цільова метрика, до якої зобов’язаний виробник. “Наша свіжість SLO становить 30 хвилин — якщо дані старіші за 30 хвилин, це інцидент.”

SLA (Service Level Agreement) — контрактне зобов’ язання з наслідками за порушення. “SLA говорить, що ми виправимо порушення якості даних протягом 4 годин в робочі години.”

** Повнота ** — відсоток записів з ненульовими значеннями у обов’ язкових полях.

** Обмеження унікальності ** — гарантія того, що поле (або комбінація полів) не містить дублікатів значень.

Розділ 4: Свежесть і доступність

freshness:
  schedule: "0 * * * *"  # every hour, on the hour
  lag_slo: "< 30 minutes"
  availability_slo: "99.5%"
  history:
    retention: "3 years"
    description: "Rolling 3-year history retained in the warehouse"

Словник свіжості:

Затримка — затримка між подією, що відбувається в джерелі, і її появою в наборі даних нижче. “Наша поточна затримка становить 45 хвилин — ми порушили 30-хвилинний SLO.”

** Доступність ** — відсоток часу, протягом якого набір даних/ кінцева точка є доступними і поточним.

Retention — як довго зберігаються історичні дані. “Контракт гарантує зберігання даних протягом 3 років — не залежно від того, чи є дані доступними раніше.”

Розділ 5: Власність і підтримка

support:
  owner: "data-platform-team"
  steward: "alice@acme.com"  # day-to-day contact
  oncall: "https://pagerduty.com/teams/data-platform"
  incident_slo:
    critical: "< 1 hour"  # data missing for >1 hour
    major: "< 4 hours"    # quality SLO breach
    minor: "< 24 hours"   # documentation issue

Словник власника:

** Власник даних ** — команда, яка відповідає за якість і доступність набору даних.

** Data steward ** — особа, яка відповідає за щоденну якість даних і підтримку користувачів.

** Інциденти SLO ** — як швидко команда зобов’ язується підтвердити і розв’ язати проблеми з даними за тяжкістю.

Розділ 6: Менеджмент змін

versioning:
  policy: "Semantic versioning (semver)"
  deprecation_notice: "30 days"
  breaking_changes:
    - "Field removal"
    - "Type narrowing"
    - "Enum value removal"
    - "Required field added to previously optional list"
  backward_compatible:
    - "New optional field added"
    - "Enum value added"
    - "Description updated"

** Змінити фрази керування: **

«Це перейменування поля є зміною, яка перерве — ми дамо споживачам 30-денне повідомлення і опублікуємо контракт v3 перед тим, як відмовитися від v2»

«Додання додаткового поля є зворотньо сумісним — ми будемо збивати незначну версію і повідомляти споживачів, але їм не потрібно робити ніяких змін»

«Ми встановлюємо v2 статус на «застаріле». Споживачі мають до Q3, щоб перейти до v3»

Примітка на обкладинці при спільному використанні контракту

Під час надсилання електронною поштою або повідомленням договору на надання даних до команди користувачів:

«Привіт [Команда], я долучив договір з набором даних замовлень (версія 2.1.0). Ключові моменти для вашої інтеграції:

Схема в orders-v2.data-contract.yaml

Свежесть SLO: 30-минутная гарантия

Поле metadata не можна замінити на нуль — будь ласка, обробляйте нульові значення у вашому конвеєрі

Зміни, що стосуються ключових питань: ми повідомимо вас за 30 днів до їх внесення

Нет, не надо Будь ласка, перегляньте і підтвердіть, що ви дотримуєтеся умов контракту перед тим, як створювати ваш трубопровод. Дай мені знати, якщо у тебе є питання»

Practice

Створення словника інженерії даних за допомогою ** Набір вправ з інженерії даних. Name ** і ** Інженер з обробки даних **.