keboola-config

Keboola の設定に関する知識

Keboola のプロジェクト構造、設定形式、データパイプライン管理のベストプラクティスに関する専門知識を提供します。

プロジェクト構造

ローカルに取得した Keboola プロジェクトは、次の構造になっています。

project-root/
├── .keboola/
│   └── manifest.json       # Project metadata and branch info
├── .env.local              # API token (never commit)
├── .env.dist               # Template for .env.local
├── .gitignore
└── [branch-name]/          # One directory per branch
    └── [component-id]/     # e.g., keboola.snowflake-transformation
        └── [config-name]/  # Configuration directory
            ├── config.json # Main configuration
            ├── meta.json   # Metadata (name, description)
            └── rows/       # Configuration rows (if applicable)

設定ファイル

manifest.json

.keboola/manifest.json にあり、以下の情報が含まれます。

• プロジェクト ID と API ホスト
• ブランチ情報
• 並べ替えと命名規則

config.json

各コンポーネントのメイン設定ファイルです。構造はコンポーネントの種類によって異なりますが、通常は以下が含まれます。

• parameters - コンポーネント固有の設定
• storage - 入出力テーブルのマッピング
• processors - 前処理／後処理の手順

meta.json

設定に関するメタデータです。

{
  "name": "Configuration Name",
  "description": "What this configuration does",
  "isDisabled": false
}

コンポーネントの種類

変換

データ処理用の SQL または Python/R 変換です。

Snowflake Transformation（keboola.snowflake-transformation）：

{
  "parameters": {
    "blocks": [
      {
        "name": "Block Name",
        "codes": [
          {
            "name": "Script Name",
            "script": ["SELECT * FROM table"]
          }
        ]
      }
    ]
  },
  "storage": {
    "input": {
      "tables": [
        {
          "source": "in.c-bucket.table",
          "destination": "table"
        }
      ]
    },
    "output": {
      "tables": [
        {
          "source": "output_table",
          "destination": "out.c-bucket.result"
        }
      ]
    }
  }
}

抽出ツール

外部ソース（データベース、API、ファイル）からデータを取得するコンポーネントです。

一般的な抽出ツール：

• keboola.ex-db-snowflake - Snowflake 抽出ツール
• keboola.ex-google-analytics-v4 - Google Analytics
• keboola.ex-generic-v2 - 汎用 HTTP API 抽出ツール

書き込みツール

外部の宛先にデータを送信するコンポーネントです。

一般的な書き込みツール：

• keboola.wr-db-snowflake - Snowflake 書き込みツール
• keboola.wr-google-sheets - Google Sheets 書き込みツール

オーケストレーション

複数の設定を順番に実行するワークフロー定義です。

keboola.orchestrator/ にあり、以下が含まれます。

• タスク定義
• 依存関係
• スケジュール設定

ベストプラクティス

設定を編集する場合

1. 変更前と変更後に必ず kbc diff を実行します
2. プッシュする前に JSON の構文を検証します
3. kbc validate を使用して設定の妥当性を確認します
4. meta.json の説明を最新の状態に保ちます

ストレージのマッピング

• 入力テーブル：ソーステーブルを作業用の名前にマッピングします
• 出力テーブル：結果テーブルを宛先バケットにマッピングします
• 一貫した命名規則を使用します

変換

• 複雑なロジックを複数のブロックに分割します
• ブロックとスクリプトには意味のある名前を付けます
• SQL にコメントを付けて説明します
• 可能な場合はローカルでテストします

一般的なタスク

変換に新しい入力テーブルを追加する

config.json の storage.input.tables に追加します。

{
  "source": "in.c-bucket.new_table",
  "destination": "new_table",
  "columns": []  // Empty = all columns
}

出力テーブルを追加する

config.json の storage.output.tables に追加します。

{
  "source": "result_table",
  "destination": "out.c-bucket.result",
  "primary_key": ["id"]
}

SQL スクリプトを変更する

該当するブロック／コードセクションの script 配列を編集します。配列の各要素は SQL ステートメントです。

トラブルシューティング

無効な設定

• JSON の構文を確認します（カンマや括弧の不足など）
• テーブル名がストレージに存在することを確認します
• マッピング内の列名を確認します

プッシュ時の競合

• まず最新の変更をプルします
• 設定ファイル内の競合を手動で解決します
• 解決後にもう一度プッシュします

テーブルが見つからない

• Keboola Storage に入力テーブルが存在することを確認します
• バケットの権限を確認します
• テーブル名が完全に一致していることを確認します（大文字と小文字を区別します）