@squadbase/vantage-template 0.0.2-dev.7c29258 → 0.1.0-dev.47d956c
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
|
@@ -0,0 +1,118 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: adamas-automation
|
|
3
|
+
description: automation(データパイプライン)の作り方。automation/<name>/ のファイル配置、automation.yml v1 の書き方(GitHub Actions サブセット)、adamas @task / outputs / partition の宣言 API、実行と検証の流れ(lintAutomations → runAutomation dryRun → 本実行)。外部データを定期的に取り込んで Squadbase DB に同期するパイプラインを作る・直すときに参照する。
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Automation(adamas データパイプライン)
|
|
7
|
+
|
|
8
|
+
外部データを定期取得して project の Squadbase DB へ同期するパイプライン。定義の正本は
|
|
9
|
+
この repo の `automation/` ディレクトリで、コミットすると platform に自動同期される。
|
|
10
|
+
ダッシュボード(`src/`)とは独立していて、互いのファイルには触れない。
|
|
11
|
+
|
|
12
|
+
## ファイル配置
|
|
13
|
+
|
|
14
|
+
```
|
|
15
|
+
automation/
|
|
16
|
+
├── pyproject.toml # 共有 Python 環境(全 automation で 1 つ)。依存は `uv add`
|
|
17
|
+
├── uv.lock
|
|
18
|
+
└── <name>/ # automation 名 = ディレクトリ名 = ^[a-z0-9][a-z0-9_-]{0,63}$
|
|
19
|
+
├── automation.yml # 宣言(トリガ・ステップ)。1 automation = 1 ファイル
|
|
20
|
+
└── tasks.py # adamas @task の実装(pipeline step が暗黙に読む。ファイル名固定)
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
- 初回だけ `automation/pyproject.toml` を作り `uv add adamas` する(全 automation で共有。
|
|
24
|
+
automation ごとに venv を作らない)
|
|
25
|
+
- `automation/` が無いディレクトリ構成でも、上の形で新規作成すればよい
|
|
26
|
+
|
|
27
|
+
## automation.yml v1 — GitHub Actions のサブセット
|
|
28
|
+
|
|
29
|
+
GHA ワークフロー YAML の意味論をそのまま使う。**GHA との差分は次の 7 点だけ**。
|
|
30
|
+
それ以外の書き方(`on:` / `steps:` / `- id:` / `if:` / `${{ }}` / `steps.<id>.outputs.<name>`)
|
|
31
|
+
は GHA の知識どおりに書く:
|
|
32
|
+
|
|
33
|
+
| # | 差分 |
|
|
34
|
+
|---|---|
|
|
35
|
+
| 1 | step は `uses:`/`run:` でなく型付きキー 1 個(`pipeline` / `agent` / `query` / `write` / `notify`)。v1 で実行できるのは `pipeline` のみ(他は宣言だけで UI に載る) |
|
|
36
|
+
| 2 | `on.schedule` は単一オブジェクトで `timezone` / `enabled` を持つ(cron 配列は不可) |
|
|
37
|
+
| 3 | 手動トリガは `on.manual`(GHA の `workflow_dispatch` の改名) |
|
|
38
|
+
| 4 | inputs の `type` は `string | boolean | daterange` の 3 種 |
|
|
39
|
+
| 5 | 式 `${{ }}` は dot 参照のみ(関数・演算子・パイプは不可)。context は `trigger.inputs.<name>` と `steps.<id>.outputs.<name>` だけ。前方・自己参照は不可 |
|
|
40
|
+
| 6 | pipeline step のタスク実体は同ディレクトリ `tasks.py` 固定(automation 1 個につき pipeline step は最大 1) |
|
|
41
|
+
| 7 | pipeline step に `destination`(取り込み先 Squadbase DB の connection uuid)を書ける。省略時は project 唯一の Squadbase DB が既定 |
|
|
42
|
+
|
|
43
|
+
例(実行可能な最小形):
|
|
44
|
+
|
|
45
|
+
```yaml
|
|
46
|
+
version: 1
|
|
47
|
+
name: Daily ad spend sync
|
|
48
|
+
on:
|
|
49
|
+
schedule: { cron: "0 6 * * *", timezone: Asia/Tokyo }
|
|
50
|
+
manual:
|
|
51
|
+
inputs:
|
|
52
|
+
backfill: { type: daterange, required: false }
|
|
53
|
+
steps:
|
|
54
|
+
- id: sync
|
|
55
|
+
pipeline:
|
|
56
|
+
backfill: ${{ trigger.inputs.backfill }}
|
|
57
|
+
connections: # ctx.connection(name) で使う接続の配線(任意)
|
|
58
|
+
warehouse: <connection-uuid>
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
- スケジュールは年 2 回以上の頻度が必要(それ未満は同期時に拒否される)
|
|
62
|
+
- `agent` / `query` / `write` / `notify` step を含む automation はスケジュール実行できない
|
|
63
|
+
(宣言と UI 表示のみ)
|
|
64
|
+
|
|
65
|
+
## tasks.py — adamas の宣言 API
|
|
66
|
+
|
|
67
|
+
```python
|
|
68
|
+
from adamas import task, output, by_date, source
|
|
69
|
+
|
|
70
|
+
@task(
|
|
71
|
+
name="ad-spend", # 出力データセット名(省略時は関数名)
|
|
72
|
+
table="ad_spend", # Squadbase DB のテーブル名
|
|
73
|
+
pk=["date", "campaign_id"], # upsert / ignore では必須
|
|
74
|
+
mode="upsert", # append | ignore(先勝ち) | upsert(後勝ち)
|
|
75
|
+
schema={"date": "string", "campaign_id": "string", "cost": "float64"},
|
|
76
|
+
partition=by_date("2026-01-01"), # 1 日 1 パーティション(付けると増分実行になる)
|
|
77
|
+
inputs=[source.connection("warehouse")],
|
|
78
|
+
)
|
|
79
|
+
def ad_spend(ctx):
|
|
80
|
+
date = ctx.partition.inputs["date"] # 自分のスライスは ctx.partition.inputs から読む
|
|
81
|
+
conn = ctx.connection("warehouse") # automation.yml の connections で配線した接続
|
|
82
|
+
yield from conn.query(
|
|
83
|
+
f"SELECT ... WHERE date = '{date}'", chunk_rows=10_000
|
|
84
|
+
)
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
押さえること:
|
|
88
|
+
|
|
89
|
+
- 戻り値は pandas/polars DataFrame・pyarrow Table、またはそれらの yield(チャンクで
|
|
90
|
+
メモリ有界にする)。複数出力は `outputs={...}` + `yield ("<dataset>", chunk)`
|
|
91
|
+
- `schema` は Parquet 型を固定する列型宣言。**schema の無い出力は Squadbase DB へ
|
|
92
|
+
取り込まれない**ので必ず書く。pk 列は schema に含める
|
|
93
|
+
- partition プランは `by_date(start)`(日次)か `by_list(keys)`(キー列挙)。
|
|
94
|
+
partition 付きタスクは単一出力
|
|
95
|
+
- 1 テーブル 1 書き手(別タスクが同じテーブルを書くとエラー)
|
|
96
|
+
- 抽出・再試行・冪等性(どこまで取ったか)は adamas と台帳が管理する。自前で
|
|
97
|
+
チェックポイントや重複排除を実装しない
|
|
98
|
+
|
|
99
|
+
## 検証と実行の流れ
|
|
100
|
+
|
|
101
|
+
1. ファイルを作成・編集したら **`lintAutomations`** で検証し、指摘を直す
|
|
102
|
+
2. **`runAutomation` を `dryRun: true` で実行**(オフライン: ローカル一時ディレクトリに
|
|
103
|
+
書き、platform の台帳・ストレージには何も書かない)。まず 1 パーティションだけ
|
|
104
|
+
`partitions: ["2026-01-01"]` のように絞ると速い
|
|
105
|
+
3. コミットすると宣言が platform に自動同期され、スケジュールが有効になる
|
|
106
|
+
4. 本実行(`dryRun` なし)はユーザーがデータを求めたときだけ。結果の `adamasStatus` に
|
|
107
|
+
タスクごとの done / failed / outstanding と失敗の内訳(error / category)が載るので、
|
|
108
|
+
それを根拠に報告・修正する
|
|
109
|
+
5. 失敗を直したら `retryFailed: true` で失敗パーティションだけ再実行。過去範囲の
|
|
110
|
+
取り直しは `backfill: "START:END"`(両端含む)
|
|
111
|
+
|
|
112
|
+
## 落とし穴
|
|
113
|
+
|
|
114
|
+
- automation 名にハイフンは使えるが、Python module 名には使わない(module は常に
|
|
115
|
+
`tasks.py` 固定なので気にしなくてよい)
|
|
116
|
+
- `${{ }}` に式や関数を書かない(`| length > 0` などの Jinja 方言は不可)
|
|
117
|
+
- cron は 5 フィールド・64 文字以内
|
|
118
|
+
- `automation.yml` に未知のキーを書くと lint エラー(黙って無視されない)
|