developing-in-lightdash

Lightdash での開発

YAML ファイルや dbt ファイルを扱う CLI ユーザーおよびライトバックサンドボックス向けです。

Lightdash の分析プロジェクトをビルドしてデプロイします。このスキルでは、セマンティックレイヤー（メトリクス、ディメンション、結合）とコンテンツ（チャート、ダッシュボード）を扱います。

使用するタイミング

• Lightdash の YAML ファイル（チャート、ダッシュボード、コードとしてのモデル）を扱う場合
• lightdash CLI（deploy、upload、download、preview、lint、warehouse-catalog、sql）を使用する場合
• dbt または純粋な Lightdash プロジェクトでメトリクス、ディメンション、結合、テーブルを定義する場合
• コードとしてチャートやダッシュボードを作成または編集する場合
• データアプリをダウンロード、アップロード、またはローカルで開発する場合（エンタープライズ）
• Chart Studio で構築したカスタムチャートタイプを作成、ダウンロード、編集、またはアップロードする場合（エンタープライズ）
• 組織の Data App テーマを作成、編集、移行、ダウンロード、またはアップロードする場合

使用しない場合： Lightdash アプリケーション自体の開発（コードベースの CLAUDE.md を使用してください）、Lightdash のメタデータを含まない一般的な dbt 作業、または Lightdash モデルに関連しない生の SQL。

できること

タスク	コマンド	参考資料
ウェアハウスのメタデータから純粋な Lightdash プロジェクトを作成する	Lightdash または認証済みのウェアハウス CLI を使用してカタログのメタデータと集計プロファイルを調べます	ウェアハウスカタログからの作成
ウェアハウスのテーブルとフィールドを検出する	lightdash warehouse-catalog --json	CLI リファレンス
データウェアハウスの値を調べる	lightdash sql で生の SQL を実行し、.csv の結果を読み取ります	CLI リファレンス
メトリクスとディメンションを定義する	dbt YAML または Lightdash YAML を編集します	メトリクス、ディメンション
チャートを作成または編集する	UI、Lightdash AI エージェント、MCP、または lightdash download/upload を使った YAML	コンテンツのワークフロー、チャートタイプ
期間比較を追加する	チャート YAML に PoP の追加メトリクスを追加します	期間ごとの比較
ダッシュボードを作成または編集する	UI、Lightdash AI エージェント、MCP、または lightdash download/upload を使った YAML	コンテンツのワークフロー、ダッシュボードのリファレンス
プロジェクトと組織のリソースにまたがるコンテンツをコードとして管理する	lightdash download、lightdash upload	コードとしてのコンテンツ
データアプリをコードとして管理する（エンタープライズ）	lightdash download --apps <ref>（1 つのアプリ）または --include-apps（すべて）、バンドルを編集し、lightdash upload --apps <ref> を実行します。ローカル開発には lightdash apps create/preview/validate を使用します	データアプリ、コードとしてのコンテンツ
カスタムチャートタイプを構築または編集する（エンタープライズ）	lightdash apps create "<name>" --chart-type または lightdash download --chart-types <ref> を実行し、chart-types/<slug>/src/ を編集して、lightdash upload --chart-types <ref> を実行します	カスタムチャートタイプ
組織の Data App テーマをコードとして管理する	lightdash download --organization を実行し、themes/<slug>/ を編集して、lightdash upload --organization を実行します	Data App テーマ
データアプリの外部接続を管理する（エンタープライズ）	lightdash download --include-external-connections を実行し、YAML を編集して、lightdash upload を実行します	コードとしてのコンテンツ
yaml ファイルを Lint する	lightdash lint	CLI リファレンス
ウェアハウス接続を設定する	profiles.yml から lightdash set-warehouse を実行します	CLI リファレンス
変更をデプロイする	lightdash deploy（セマンティックレイヤー）、lightdash upload（コンテンツ）	CLI リファレンス
変更をテストする	lightdash preview	ワークフロー

よくある間違い

間違い	結果	防止策
フィルター値を推測する	大文字と小文字の不一致（'Payment' と 'payment' など）により、グラフがデータを返さずに終了します	必ず lightdash sql "SELECT DISTINCT column FROM table LIMIT 50" -o values.csv を実行し、完全に一致する値を使用します
グラフ名を変更した後にダッシュボードのタイルを更新しない	ダッシュボードのタイルには古いタイトルが表示されます。title と chartName は独立した上書き項目であり、自動更新されません	ダッシュボードをダウンロードし、一致する chartSlug を持つタイルを見つけて、title と chartName を一致するよう更新します（チェックリストを参照）
metricQuery に未使用のディメンションを含める	「結果が不正確な可能性があります」という警告が表示されます。余分なディメンションによって SQL のグループ化が変わり、数値が誤ります	metricQuery.dimensions 内のすべてのディメンションが、グラフ設定にも含まれている必要があります。直積グラフの場合は、layout.xField、layout.yField、または pivotConfig.columns に含めます
YAML のキーを並べ替えない	lightdash upload に「unsorted YAML keys」という警告が表示され、差分が見づらくなります	すべてのネストレベルで、常にキーをアルファベット順に並べ替えます。CLI は sortKeys: true を指定して書き込みます
誤ったプロジェクトにデプロイする	本番環境のコンテンツが上書きされます	デプロイ前に、必ず lightdash config get-project を実行します
コンテンツを dbt プロジェクトにダウンロードしてコミットする	ダッシュボード、グラフ、またはデータアプリのファイルがリポジトリに追加されますが、誰も保守せず、UI で誰かがコンテンツを編集するとすぐに古くなります	一時ディレクトリにダウンロードしてアップロードし、その後削除します。ユーザーから依頼された場合、またはリポジトリがすでに追跡している場合に限り、コンテンツをコミットします（コンテンツのワークフローを参照）
contentType フィールドがない	ディレクトリ構造に頼らなければ、コンテンツの種類を判別できません	必ずトップレベルに contentType: chart、contentType: dashboard、または contentType: sql_chart を含めます
--apps <ref> の選択時に --include-apps を追加する	--include-apps は常にプロジェクト内のすべてのアプリを要求し（上限は 50 件）、指定したアプリだけでなく、すべてのアプリと ref をダウンロードします	--apps <ref> だけを指定すると、そのアプリのみをダウンロードまたはアップロードします（slug、アプリ URL、または UUID で指定）。すべてのアプリが必要な場合にのみ --include-apps を使用します
同梱スキルを読まずにデータアプリを編集する	アプリコードが SDK のみを使用するデータアクセスと依存関係の境界に違反し（直接の fetch、pnpm add、ベンダー提供ライブラリなど）、アップロードが拒否されたり、デプロイ後にアプリが壊れたりします	すべてのアプリバンドルには developing-data-apps-locally と lightdash-data-app のスキルが含まれています。アプリフォルダー内のファイルを編集する前に、必ずこれらを読みます（データアプリを参照）
再利用可能なグラフを Vega-Lite の custom グラフとして作成する	可視化が保存済みグラフの中だけに存在し、再利用したり、エクスプローラーのグラフ種類ピッカーから選択したりできません	再利用可能な可視化を新しく作成する場合は、カスタムグラフ種類を作成します（カスタムグラフ種類を参照）。Vega-Lite は、既存の chartConfig.type: custom グラフ、またはプロジェクトにカスタムグラフ種類がない場合（エンタープライズ版）にのみ使用します
同梱スキルを読まずにグラフ種類を編集する	コンポーネントが自らデータをクエリまたは取得したり、vizSchema が src/ の読み取り内容と食い違ったりして、グラフ種類が壊れるか、グラフ種類ピッカーに表示されなくなります	すべてのグラフ種類フォルダーには AGENTS.md と reusable-visualization、developing-chart-types-locally のスキルが含まれています。chart-types/<slug>/ 内のファイルを編集する前に、必ず3つすべてを読みます
テーマ専用の CLI コマンドをでっち上げる、またはフォルダーがないことを削除とみなす	コマンドが存在しないか、削除したはずのリモートテーマが次回のダウンロード時に再び現れます	組織のダウンロード／アップロードを使用し、themes/ を変更する前にデータアプリのテーマを読みます

始める前に

lightdash download または lightdash upload を実行する場合は、必ずコンテンツのワークフローに従ってください。ファイルはユーザーのリポジトリではなく、一時ディレクトリに配置し、ユーザーから依頼されない限りコミットしません。

lightdash download または lightdash upload を使うタスクでは、特に一括編集、スペースとアクセス権、スケジュールされたコンテンツ、AI エージェント、データアプリ、カスタムチャートタイプ、組織テーマ、外部接続、ユーザー、グループ、カスタムロールに関する場合は、まずコードとしてのコンテンツを読み、その手順に従ってください。プロジェクトと組織のコンテンツには個別のコマンドが必要であり、デフォルトのダウンロードでは完全なスナップショットになりません。

組織のデータアプリテーマを作成、編集、移行、ダウンロード、アップロード、テストするタスクでは、themes/に触れる前に必ずデータアプリテーマを読み、その手順に従ってください。テーマパッケージは複数ファイルからなる厳密なリソースであり、組織へのアップロードにはテーマ専用モードがなく、lightdash lintでも検証されません。

対象プロジェクトを確認する

**デプロイ先のプロジェクトを必ず確認してください。**誤ったプロジェクトにデプロイすると、本番環境のコンテンツを上書きする可能性があります。

lightdash config get-project        # Show current project
lightdash config list-projects      # List available projects
lightdash config set-project --name "My Project"  # Switch project

プロジェクトの種類を判別する

プロジェクトの種類によって、YAML の構文は大きく異なります。

種類	判別方法	主な違い
dbt プロジェクト	dbt_project.ymlがある	メタデータをmeta:の下にネストする
dbt Fusion / dbt 1.10+	dbt_project.ymlがあり、dbt Fusion または dbt >= 1.10 を使用している	メタデータをconfig: meta:の下にネストする
Pure Lightdash	lightdash.config.ymlがあり、dbt を使用していない	トップレベルのプロパティ

ls dbt_project.yml 2>/dev/null && echo "dbt project" || echo "Not dbt"
ls lightdash.config.yml 2>/dev/null && echo "Pure Lightdash" || echo "Not pure Lightdash"

dbt Fusion / dbt 1.10+: Lightdash のメタデータはmeta:ではなく、config: meta:の下にネストする必要があります。プロパティは同じで、ネストの場所だけが変わります。例：

models:
  - name: orders
    config:
      meta:
        metrics:
          total_revenue:
            type: sum
            sql: "${TABLE}.amount"

構文の比較

dbt YAML（meta:の下にメタデータを記述）：

models:
  - name: orders
    meta:
      metrics:
        total_revenue:
          type: sum
          sql: "${TABLE}.amount"
    columns:
      - name: status
        meta:
          dimension:
            type: string

Pure Lightdash YAML（トップレベル）：

type: model
name: orders
sql_from: 'DB.SCHEMA.ORDERS'

metrics:
  total_revenue:
    type: sum
    sql: ${TABLE}.amount

dimensions:
  - name: status
    sql: ${TABLE}.STATUS
    type: string

データウェアハウス接続の設定

プロジェクトで別のデータウェアハウス接続が必要な場合（例：Postgres から BigQuery への切り替え）、profiles.yml から接続を更新します。

lightdash set-warehouse --project-dir ./dbt --profiles-dir ./profiles --assume-yes

このコマンドは profiles.yml から認証情報を読み取り、現在選択されているプロジェクトのデータウェアハウス接続を更新して、再コンパイルを実行します。lightdash deployの前に実行してください。

特定のプロジェクトを対象にする場合：

lightdash set-warehouse --project-dir ./dbt --profiles-dir ./profiles --project <uuid> --assume-yes

基本的なワークフロー

使用前にフィルター値を確認する

重要：フィルター値を推測してはいけません。大文字と小文字の不一致（例：'Payment'と'payment'）があると、チャートがデータを返さずに処理されることがあります。

フィルターでは、デフォルトで大文字と小文字が区別されます。case_sensitiveキーは、次の優先順位で設定を上書きできます。

• ディメンションのメタデータ
• モデル／探索のメタデータ
• lightdash.config.ymlのdefaults.case_sensitive

文字列フィルターを書く前に、データウェアハウスから実際の値をクエリしてください。

lightdash sql "SELECT DISTINCT category FROM payments LIMIT 50" -o category_values.csv

CSV を読み取り、フィルター YAML には完全に一致する値を使用してください。これは、チャートとダッシュボードで文字列値を使うすべてのequals／notEqualsフィルターに適用されます。

メトリクスとディメンションの編集

1. モデルの YAML ファイルを探します（dbt：models/*.yml、Pure Lightdash：lightdash/models/*.yml）
2. プロジェクトの種類に合った構文でメトリクス／ディメンションを編集します
3. 検証します：lightdash lint（Pure Lightdash）またはdbt compile（dbt プロジェクト）
4. デプロイします：lightdash deploy

設定オプションについては、メトリクスリファレンスとディメンションリファレンスを参照してください。

ウェアハウスカタログから純粋な Lightdash プロジェクトを作成する

準備済みのプロジェクトに利用可能な dbt プロジェクトがなく、ウェアハウスのメタデータからセマンティックレイヤーをブートストラップする場合は、データを調査したり YAML を記述したりする前に、必ずウェアハウスカタログから作成するを読んで、その手順に従ってください。これは、選択した Lightdash プロジェクト経由でウェアハウスにアクセスする場合も、Snowflake CLI や bq など、すでに認証済みのウェアハウス CLI を利用する場合も同様です。既存の dbt セマンティックレイヤーを拡張できる場合は、このワークフローを使用しないでください。

コンテンツのワークフロー

これは、チャート、ダッシュボード、データアプリ、カスタムチャートタイプなど、あらゆるコンテンツで使う唯一のループです。以下のセクションでは、各リソースに固有の内容のみを補足します。

コンテンツの作成。 チャートとダッシュボードは、Lightdash の UI、Lightdash AI エージェント、Lightdash MCP サーバー、または CLI を使った YAML で作成できます。どの方法も同等に有効なので、ユーザーの希望に従ってください。

Lightdash が信頼できる唯一の情報源です。 ダウンロードしたファイルは一時的な作業用コピーであり、コミットするファイルではありません。ファイルとしてコンテンツを編集する場合、または YAML として作成する場合は、次の手順に従ってください。

1. 対象を確認する：lightdash config get-project
2. スクラッチディレクトリにダウンロードする。ユーザーのリポジトリ内や dbt プロジェクト内には保存しないでください：

   LD_DIR="$(mktemp -d)/lightdash"
   lightdash download --dashboards executive-summary --path "$LD_DIR"   # or --charts <slug>, --apps <ref>, ...
   

   コンテンツを作成する場合は、ダウンロードを省略し、$LD_DIR に新しい YAML を記述します。
3. $LD_DIR 内のファイルを編集する。下記のチェックリストに沿って作業します。
4. Lint を実行する：lightdash lint --path "$LD_DIR"
5. 同じセレクターを使ってアップロードする：lightdash upload --dashboards executive-summary --path "$LD_DIR"
6. $LD_DIR を削除する。ファイルをリポジトリにコピーしたり、git add したり、コミットしたりしないでください。

一括変更やスコープをまたぐ変更（スペースとアクセス、ユーザー、グループ、ロール、スケジュールされたコンテンツ、AI エージェント）については、代わりにコードとしてのコンテンツのエージェントセーフワークフローに従ってください。

コンテンツを git に含める場合。 ユーザーから依頼された場合、またはリポジトリですでにコンテンツが追跡されている場合（たとえば、git ls-files lightdash/ がコンテンツファイルを返す場合）に限ります。これには、バージョン管理されたテンプレート、コンテンツの CI/CD デプロイ、コードレビューを伴う厳格な変更管理が該当します。エージェントを使ったダッシュボードの編集を参照してください。これはコンテンツにのみ適用されます。dbt モデル、メトリクス、ディメンション、その他のセマンティックレイヤーの YAML はリポジトリに保存し、lightdash deploy とともにデプロイします。

チャートとダッシュボードのチェックリスト

• フィルター値：文字列フィルターを追加または変更した場合は、まず実際の値をクエリしてください（フィルター値を使用する前に確認するを参照）。
• ダッシュボードタイルのタイトル：saved_chart タイルの title と chartName はそれぞれ独立した上書き設定であり、チャートの名前を変更しても自動更新されません。チャートの名前または用途を変更した場合は、chartSlug が一致するタイルを含むすべてのダッシュボードをダウンロードし、両方のプロパティを更新して、それらのダッシュボードもアップロードしてください：

  tiles:
    - type: saved_chart
      properties:
        chartSlug: total-revenue-kpi
        title: "Gross Profit"        # ← Update this when chart name/purpose changes
        chartName: "Gross Profit"    # ← Update this too
  

• チャートの設定：チャートタイプとダッシュボードリファレンスを参照してください。

データアプリを操作する（Enterprise）

データアプリは、単一の YAML ファイルではなく、lightdash-app.yml マニフェストを含む apps/<app-folder>/ 配下の複数ファイルで構成された React バンドルです。フラグの完全なセマンティクスとマニフェストの詳細については、Content as Code を参照してください。

アプリはコンテンツワークフローに従います。スクラッチディレクトリで作業し、ユーザーから依頼がない限りバンドルをコミットしないでください。以下のコマンドは、アプリ固有のフラグです。

アプリを 1 つダウンロードする — --apps <ref> だけでコマンドは完結します（ref = slug、アプリの URL、または UUID。スペースに追加されていないアプリも検索します）。

lightdash download --apps revenue-explorer --path "$LD_DIR"

ダウンロード対象を「絞り込む」ために --include-apps を追加しないでください。このフラグは、常にプロジェクト内のすべてのアプリを要求します（よくある間違いを参照）。

すべてのアプリをダウンロードする：lightdash download --include-apps（上限は 50 です。--apps-limit <n> で引き上げられます）。チャート、ダッシュボード、スペースを省略するには、--apps-only を追加します。

アップロードする：

lightdash upload --apps revenue-explorer --path "$LD_DIR"   # one app (slug = folder name, URL, or UUID)
lightdash upload --include-apps --path "$LD_DIR"            # every app folder on disk

• --app-space <spaceRef> — このアップロードで作成するアプリのスペース（slug または UUID）を指定します。既存のアプリは現在のスペースを維持します。
• --create-new — lightdash-app.yml で参照されているアプリを更新する代わりに、新しいアプリ（新しい slug）を作成します。
• --allow-custom-dependencies — カスタム npm 依存関係を宣言しているアプリを非対話形式でアップロードする場合に必須です。

lightdash apps サブコマンドグループを使ってローカルで開発する：

lightdash apps create "Revenue Explorer" --path "$LD_DIR"   # scaffold a new app under $LD_DIR/apps/
lightdash apps preview                     # run the app locally against your real Lightdash instance, authenticated as you
lightdash apps validate                    # check source, manifest, dependencies, and semantic-layer references

作成またはダウンロードしたすべてのアプリバンドルには、アプリフォルダー内に独自のスキルが含まれています：

• developing-data-apps-locally — 編集 → 検証 → アップロードのサイクル、ローカルプレビュー、SDK のみを使ったデータアクセス、依存関係の境界について説明します
• lightdash-data-app — アプリのソースコード向けに @lightdash/query-sdk を解説します

アプリフォルダー内のファイルを編集する際は、まず同梱されているスキルを読んでください。これらはアプリとバージョンが一致しており、ローカル開発に関する正式な情報源です。このスキルでは、アプリをディスクと Lightdash の間で移動する方法のみを説明します。

カスタムチャートタイプを操作する（Enterprise）

カスタムチャートタイプは、Chart Studio で作成する再利用可能なビジュアライゼーションです。Lightdash がクエリ結果と設定を渡す React コンポーネント 1 つで構成され、プロジェクト内のすべてのチャートについて、エクスプローラーのチャートタイプピッカーに表示されます。ディスク上では、コンポーネントが読み取るフィールドとオプションを vizSchema で定義した lightdash-app.yml マニフェストを含む、chart-types/<slug>/ 配下の複数ファイルで構成されたバンドルです。データアプリではなく（独自にクエリを実行しません）、従来の Vega-Lite custom チャートでもありません。

チャートタイプはコンテンツワークフローに従います。スクラッチディレクトリで作業し、ユーザーから依頼がない限りバンドルをコミットしないでください。

ローカルで作成する：

lightdash apps create "Radial Gauge" --chart-type --path "$LD_DIR"   # scaffolds $LD_DIR/chart-types/radial-gauge/

ダウンロードする — --chart-types <ref> だけでコマンドは完結します（ref = slug、URL、または UUID）：

lightdash download --chart-types radial-gauge --path "$LD_DIR"
lightdash download --include-chart-types   # every chart type in the project (capped at 50; raise with --chart-types-limit <n>)
lightdash download --chart-types-only      # chart types only, skipping charts, dashboards, and spaces

カスタムチャートタイプで表示されるチャートをダウンロードすると、そのチャートタイプもダウンロードされます。チャート YAML では、バインディングは chartConfig.type: data_app_viz であり、config.dataAppVizSlug、fieldMapping、optionValues を使用します。

アップロードする：

lightdash upload --chart-types radial-gauge --path "$LD_DIR"   # one chart type (slug = folder name, URL, or UUID)
lightdash upload --include-chart-types --path "$LD_DIR"        # every chart type folder on disk

dataAppVizSlug でチャートタイプを指定するチャート YAML は、対象プロジェクトにそのチャートタイプが存在しないとアップロードに失敗します。先にチャートタイプをアップロードするか、同じ実行で --chart-types <ref> を渡してください（チャートタイプはチャートより先にアップロードされます）。

フォルダー内で編集する。 chart-types/<slug>/ に移動し、src/ を編集する前にそのフォルダーの AGENTS.md と、reusable-visualization および developing-chart-types-locally の各スキルを読んでください：

• reusable-visualization — コンポーネントの仕様です。ホストとの唯一の通信手段は useVizContext() であり、コンポーネント自身がクエリやデータ取得を行うことはありません
• developing-chart-types-locally — vizSchema とコンポーネントの同期、lightdash apps validate --build、フィクスチャプレビュー、アップロードと検証のサイクルについて説明します

これらのファイルはチャートタイプとバージョンが一致しており、その編集に関する正式な情報源です。このスキルでは、チャートタイプをディスクと Lightdash の間で移動する方法のみを説明します。

組織データアプリのテーマを扱う

組織データアプリのテーマは themes/<slug>/ 配下の複数ファイルからなるパッケージであり、lightdash download --organization と lightdash upload --organization に自動的に参加します。これらには独立したコマンドグループやテーマ固有のセレクターはありません。

テーマを作成、編集、移行、同期、またはテストする前に、マニフェストの契約、アセットのルール、同期の動作、および生成の境界について、データアプリのテーマ を読んで従ってください。

プレビューでのテスト

より大きな変更については、分離された環境でテストしてください:

lightdash preview --name "my-feature"
# Make changes and iterate
lightdash stop-preview --name "my-feature"

CLI クイックリファレンス

コマンド	目的
lightdash deploy	セマンティックレイヤー (メトリクス、ディメンション) を同期する
lightdash upload	チャート/ダッシュボードをアップロードする
lightdash download	チャート/ダッシュボードを YAML としてダウンロードする
lightdash lint	YAML をローカルで検証する
lightdash preview	一時的なテストプロジェクトを作成する
lightdash warehouse-catalog --json	ウェアハウスの生テーブルを検出する
lightdash sql "..." -o file.csv	ウェアハウスに対して SQL クエリを実行する
lightdash run-chart -p chart.yml	チャート YAML のクエリをウェアハウスに対して実行する
lightdash apps create <name>	新しいデータアプリをローカルでスキャフォールドする (エンタープライズ)
lightdash apps create <name> --chart-type	新しいカスタムチャートタイプをローカルでスキャフォールドする (エンタープライズ)
lightdash apps preview	データアプリを Lightdash インスタンスに対してローカルで実行する
lightdash apps validate	データアプリまたはチャートタイプのソース、マニフェスト、およびセマンティック参照を検証する
lightdash download --chart-types <ref> / lightdash upload --chart-types <ref>	カスタムチャートタイプをディスクと Lightdash の間で移動する (エンタープライズ)

完全なコマンドのドキュメントについては、CLI リファレンス を参照してください。

セマンティックレイヤー

セマンティックレイヤーはデータモデルを定義します。完全な設定については、個々のリファレンスを参照してください:

• テーブルリファレンス — クエリ可能なエンティティ、ラベル、結合
• メトリクスリファレンス — 集約計算 (count、sum、average、min、max、number など)
• ディメンションリファレンス — グループ化/フィルタリング用の属性 (string、number、boolean、date、timestamp)
• 結合リファレンス — テーブル間の関係
• ユーザー属性リファレンス — SQL 変数、行レベルセキュリティ、アクセス制御

チャートタイプ

すべてのチャートは共通の基本構造を共有します:

chartConfig:
  config: {}        # Type-specific — see individual references
  type: <type>
contentType: chart              # Required: chart, dashboard, or sql_chart
dashboardSlug: my-dashboard  # Optional: scopes chart to dashboard (won't appear in space)
metricQuery:
  dimensions:
    - my_explore_category
  exploreName: my_explore     # Required: which explore to query
  filters: {}
  limit: 500
  metrics:
    - my_explore_total_sales
  sorts: []
name: "Chart Name"
slug: unique-chart-slug
spaceSlug: target-space
tableConfig:
  columnOrder: []
tableName: my_explore           # Required: top-level explore/table name
version: 1

キーの順序: すべての YAML キーは、すべてのネストレベルでアルファベット順にソートする必要があります。CLI は sortKeys: true でファイルを書き込み、アップロード時にキーがソートされていない場合は警告します。YAML を手作業で作成または編集する際は、警告やノイズの多い差分を避けるために、キーをアルファベット順に保ってください。

チャートのスコープ: spaceSlug は共有チャートにのみ使用してください。チャートを特定のダッシュボードにスコープするには dashboardSlug を追加します (スペースには表示されません)。

ネストされたスペース: スペースはネストできます。YAML では、spaceSlug は parent/child 構文を使用してサブスペースを指定します — / は階層を表します。例:

spaceSlug: sales              # Top-level space "sales"
spaceSlug: sales/maps         # Sub-space "maps" inside "sales"
spaceSlug: sales/eu/forecasts # Deeper nesting works the same way

各パスセグメントは、そのレベルに存在する (または作成予定の) スペースのスラッグでなければなりません。sales-maps のような単なるスラッグはフラットなトップレベルスペースであり、サブスペースではありません — スラッシュだけが階層を作成します。

適切なチャートタイプの選択

データパターン	推奨チャート	理由
時間の経過に伴う傾向	折れ線またはエリア（cartesian）	X 軸に時間を配置し、連続的な変化を表示します
カテゴリの比較	棒（cartesian）	個別のカテゴリを視覚的に簡単に比較できます
全体に占める割合の関係	pie または treemap	合計が 100% となる割合を表示します
単一の KPI 指標	big_number	重要な値 1 つに焦点を当てます
コンバージョンの段階	funnel	連続するステップ間の離脱を可視化します
目標に対する進捗	gauge	目標に対する現在値を表示します
地理データ	map	地図上にデータポイントまたは地域をプロットします
カテゴリ間のフロー	sankey	ソースノードからターゲットノードへ値がどのように移動するかを表示します
詳細なレコード	table	並べ替えと書式設定が可能な生データを表示します
上記のいずれでもカバーできない可視化	カスタムチャートタイプ	チャートタイプ選択メニューで提供される、再利用可能な React コンポーネントです。カスタムチャートタイプを参照してください
Vega-Lite チャート	custom（レガシー）	すでに chartConfig.type: custom で保存されているチャート、またはカスタムチャートタイプがないプロジェクト（エンタープライズ向け）用です

タイプ	用途	リファレンス
cartesian	棒、折れ線、エリア、散布図	直交座標系
pie	全体に占める割合	円グラフ
table	データテーブル	テーブル
big_number	KPI	ビッグナンバー
funnel	コンバージョンファネル	ファネル
gauge	進捗インジケーター	ゲージ
treemap	階層データ	ツリーマップ
map	地理データ	地図
sankey	フローダイアグラム	サンキー
custom	レガシーの Vega-Lite カスタムチャート	カスタム可視化
data_app_viz	カスタムチャートタイプでレンダリングされるチャート	カスタムチャートタイプ

SQL チャート（contentType: sql_chart）は、explore ではなく、ウェアハウスの生 SQL から保存されます。SQL チャートリファレンスを参照してください。

ダッシュボード

ダッシュボードでは、チャートとコンテンツをグリッドレイアウトに配置します。YAML 構造、タイルタイプ、タブ、フィルターについては、ダッシュボードリファレンスを参照してください。

ウェアハウスの探索

モデルの構築時にデータを探索するには、lightdash sql を使用します。

# Preview table structure
lightdash sql "SELECT * FROM orders LIMIT 5" -o preview.csv

# Check distinct values for a dimension
lightdash sql "SELECT DISTINCT status FROM orders" -o statuses.csv

# Test metric calculations
lightdash sql "SELECT SUM(amount) FROM orders" -o test.csv

ワークフローパターン

パターン	使用する場面
直接（deploy + upload）	個人開発、迅速な反復
プレビュー優先	チーム、複雑な変更
CI/CD	マージ時の自動化

詳しい例と CI/CD の設定については、ワークフローリファレンスを参照してください。

リソース

セマンティックレイヤー

• ウェアハウスカタログからの作成
• ディメンションリファレンス
• メトリクスリファレンス
• テーブルリファレンス
• 結合リファレンス
• ユーザー属性リファレンス

チャート

• 直交座標系チャートのリファレンス - 棒グラフ、折れ線グラフ、面グラフ、散布図
• 円グラフのリファレンス
• テーブルチャートのリファレンス
• ビッグナンバーのリファレンス
• ファネルチャートのリファレンス
• ゲージチャートのリファレンス
• ツリーマップチャートのリファレンス
• マップチャートのリファレンス
• サンキーチャートのリファレンス
• カスタム可視化のリファレンス - レガシーな Vega-Lite の custom チャート
• 期間比較のリファレンス - 期間比較（前年比、前月比など）
• SQL チャートのリファレンス - ウェアハウスの生 SQL から保存されたチャート

ダッシュボードとワークフロー

• ダッシュボードのリファレンス
• ダッシュボードのベストプラクティス
• データアプリテーマのリファレンス
• コンテンツ・アズ・コードのリファレンス
• CLI リファレンス
• ワークフローのリファレンス

外部

• Lightdash ドキュメント