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 转换（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 中
• 检查存储桶权限
• 确认表名完全一致（区分大小写）