# はじめに

先進的なデータ探索を当たり前に。チームのためのデータノートブック。

<figure><img src="/files/nLUhlauAsXxg5yfME4r4" alt=""><figcaption></figcaption></figure>

## **Codatumとは？**

Codatumは、SQLに特化したデータ前処理と分析のための強力なツールです。

データウェアハウス上でシームレスにタスクを実行でき、大規模データセットの迅速かつ正確な分析を可能にします。Codatumを使えば、安全でコラボレーティブなデータ分析が可能になります。

Codatumと一緒に、データ分析の可能性を広げていきましょう！

## **Codatumで実現できること**

Codatumは、以下の主要な利点を通じて、チームの分析能力を大幅に向上させます。

* 制限のない深い分析:
  * SQLベースのツールであるCodatumは、GUIベースのツールにしばしば見られる制限なしに、複雑で詳細な分析を可能にします。この柔軟性により、データからより深い洞察を引き出すことができます。
* キーボードファーストデザインによる効率的なワークフロー:
  * Codatumは、SQLブロック、データテーブル、チャートをフローベースのエディタに統合しています。このキーボードファーストのアプローチにより、SQLクエリを迅速に記述し、結果を分析することができ、データ探索がより効率的で直感的になります。
* 安全で多様な共有:
  * 様々な共有オプションと詳細な権限設定により、Codatumは異なる要件に応じて安全に分析結果を共有できることを保証します。チームメンバーとコラボレーションしたり、ステークホルダーと結果を簡単に共有したりできます。
* リアルタイムで新鮮なデータ:
  * データウェアハウスに直接接続することで、Codatumは常に最新で信頼性の高いデータを提供します。このデータソースへの直接アクセスにより、分析の正確性と新鮮さが保証されます。
* 分析サイクルの加速:
  * Codatumを使用すると、データの前処理、モデリング、分析を1つの場所で行うことができます。この統合により、分析サイクルが加速し、反復的な調整と継続的な洞察が可能になります。

これらの利点を活用することで、Codatumはデータ分析プロセスを柔軟で効率的、かつコラボレーティブに変革します。

## 次のステップ

* [**クイックスタート**](/getting-started/quick-start)
  * Codatumを初めて使用しますか？このガイドでワークスペースを設定し、すぐに始めましょう。
* [**詳しい設計思想**](/concept-design/concept-further-reading)
  * Codatumの背後にあるアイデアに興味がありますか？コアコンセプトと解決する課題について深く掘り下げてみましょう。


# 詳しい設計思想

Codatumが解決するデータ分析の課題と、その先進的なアプローチを詳しく解説します。

<figure><img src="/files/8InlGEOqNztnRz8y0Xal" alt=""><figcaption></figcaption></figure>

## 現代のデータ分析における課題: 情報の分断による分析の遅延

現代の企業は、様々な形式で膨大なデータを保有しています。これらのデータは、異なるチームが様々なインターフェースを通じて加工、転送、集約、アクセスする必要があります。

このプロセスにより、すべてのデータへのアクセスや元データへの追跡が困難になり、チーム間のタスク調整も複雑化します。結果として、分析サイクル全体が停滞してしまいます。

## 解決策: 統一されたユーザーインターフェース

この問題を解決するには、大規模なデータから小規模なデータまで、そしてデータの再構築から分析まで、あらゆる作業を一元的に扱える統合ユーザーインターフェースが不可欠です。

#### SQLの課題とCodatumの解決策

SQLは長年、データ操作のための主要なインターフェースとして機能してきました。しかし、プレビューや保存、共有、クエリの分割などの面で課題があり、統一されたインターフェースとしては十分ではありませんでした。

Codatumは、SQLを最新のユーザーインターフェースと先進的な概念にシームレスに統合することで、これらの課題を解決します。これにより、データ、プロセス、チームの分断を解消し、企業の分析サイクルを大幅に加速できると考えています。

## Codatumが実現する解決方法

#### **「深い」分析**

多くのBIツールは使いやすさを重視し、ビジネスユーザーを対象にした簡単なタスク向けに設計されています。しかし、データ分析は本質的に複雑です。既存のツールでは、意味のある洞察を得るために必要な深い分析が難しく、データサイエンティストやエンジニアにとっては機能が制限されすぎています。

{% hint style="success" %}
Codatumを使用すると：

* 簡単なタスクにとどまらず、コーディングのような技術的知識を活かした、より深い分析が可能になります。
* 技術的なスキルを持つチームメンバーがデータ分析に全面的に参加できるようになります。
  {% endhint %}

#### **SQLの開発、管理、共有**

SQLはデータ分析の中心ですが、特に複雑なクエリを扱う際には管理や共有が困難です。

{% hint style="success" %}
Codatumを使用すると：

* キーボード中心のUIにより、SQLをモジュール化し、結果を見ながら開発できるため、複雑なデータを扱いやすくなります。
* コラボレーションを強化し、フォルダベースの管理を可能にし、共有のための美しいダッシュボードを作成できます。
  {% endhint %}

#### **新鮮で正確なデータ**

Jupyter Notebookは長い間、データ分析の定番でしたが、データレイクからデータマート、そしてPythonセッションへのデータ転送を含む従来のワークフローは、リアルタイム分析には時代遅れになりつつあります。これらのツールは、SQLにあまり焦点を当てておらず、効率的なデータ処理に必要な境界を曖昧にすることがよくあります。

{% hint style="success" %}
Codatumを使用すると：

データレイクやデータウェアハウスから直接、最新で正確なデータソースにアクセスでき、より精度の高いデータ分析が可能になります。
{% endhint %}

#### **モデリングと分析の迅速なサイクル**

質の高いデータを収集し整理することは、複雑な分析にとって重要です。また、分析は直線的ではなく反復的であるべきです。Codatumは、同じプラットフォーム上でデータモデリングと分析のためのシームレスなSQL統合を実現し、分析サイクル中の不要な遅延を削減します。

{% hint style="success" %}
Codatumを使用すると：

前処理、モデリング、SQLサブクエリ管理が1つのプラットフォームに統合され、データ準備と分析サイクルが加速します。
{% endhint %}

#### **分析の柔軟性を高める詳細なセキュリティ機能**

データ分析においてセキュリティとプライバシーは重要であり、リスクを最小限に抑えつつデータの有用性を最大化するために厳格なアクセス制御が必要です。詳細な権限設定がなければ、分析の柔軟性は大幅に制限され、データ資産の価値が低下します。

{% hint style="success" %}
Codatumを使用すると：

細かい権限管理によりセキュリティが強化され、データへのアクセスが拡大し、プライバシーを損なうことなく、必要な人にのみデータが届くことを保証します。
{% endhint %}

## 重要なポイント

Codatumは、データの力を活用してチームを強化するように設計されています。データの断片化を排除し、チーム間のコラボレーションを促進することで、Codatumはデータ駆動型のアプローチでチームの潜在能力を最大化します。Codatumを使用することで得られる利点をお楽しみください！

## 参考文献

ブロックエディタをセルベースのエディタよりも選んだ理由について、こちらで詳しくお読みください。

[なぜセルベースエディタではなくブロックエディタを選んだのか？](/concept-design/concept-further-reading/why-did-we-choose-block-editor-over-cell-based-editor)


# なぜセルベースエディタではなくブロックエディタを選んだのか？

Codatumがブロックエディタを選択した理由

Codatumでは、データ分析は使用するツールに制限されることなく、柔軟で使いやすいものであるべきだと考えています。私たちの目標は、ユーザーがノートブックで行うように自由に思考や分析を構築できるようにすることです。ブロックエディタを使用することで、ユーザーは直感的にコンテンツを構築し、メモ帳で思考を整理するように自由にブロックを移動できます。さらに、ブロックエディタは統一されたキーボード操作（SQLの実行などの特殊なショートカットを含む）で継続的な作業を可能にします。基本的に同じテキスト形式で構築されているため、ユーザーは思考プロセスを中断することなく作業に集中できます。

<figure><img src="/files/qD8u27TTMUNLxYXfGGZA" alt=""><figcaption></figcaption></figure>

2000年代以降、EvernoteやNotionのようなブロックエディタは急速に進化してきました。これらの現代的なインターフェースは、直感的な操作と柔軟性の比類のない組み合わせを提供し、ユーザーが思考を容易に管理できるようにしています。

セルベースのエディタにも、コードと出力の明確な区分けなどの利点がありますが、これらはやや古いアプローチを表しています。この方法は、より厳格な構造を強制することで、時として思考の流れを妨げる可能性があります。さらに、セルベースのエディタはリアルタイムコラボレーションが弱い傾向にあり、チームが効果的に協力して作業することを難しくします。

データ分析は一人で行うものではありません。それは協力して作業し、知識を共有することを含みます。Codatumでは、リアルタイムコラボレーションを優先しています。現代的なブロックエディタアプローチを採用することで、複数のユーザーが同時にドキュメントを編集でき、変更が即座に反映され、競合なくチームワークをスムーズかつ効率的に行うことができます。

Codatumでは、思考プロセスがスムーズで、リアルタイムコラボレーションがシームレスであることを確保するために、現代的なブロックエディタアプローチを選択しました。これにより、ユーザーは不必要な妨げなくデータ分析に集中でき、プロセスをできるだけスムーズかつ効率的にすることができます。


# 画面の見方と基本用語

このページでは、Codatumの基本的な画面操作、用語ついて説明します。

Codatumの画面は、**左端のナビゲーション(①)**、**中央のサイドバー(②)**、**右側のメインエリア(③)** の3つで構成されています。

<figure><picture><source srcset="/files/eF0FTBuHA42cCHMRWY1I" media="(prefers-color-scheme: dark)"><img src="/files/ScLuXKqpFuKuFiPMCMnP" alt="Codatumインターフェース概要"></picture><figcaption></figcaption></figure>

## 基本的な用語集

<table><thead><tr><th width="180">用語</th><th>概要</th></tr></thead><tbody><tr><td>ワークスペース</td><td>チームやプロジェクトごとに分けられた作業空間。部署やプロジェクト単位で使い分けます。フォルダを作って、そこにノートブックを作ることができるので、用途に合わせた分類が可能です。1人で複数のワークスペースに所属可能で、作業するワークスペースは左上のアイコンで切り替えられます。</td></tr><tr><td>データソース</td><td>会社のデータが保管されているデータベース（BigQuery、Snowflakeなど）。</td></tr><tr><td><a href="https://docs.codatum.jp/connect-and-manage-data/connection">コネクション</a></td><td>データソースとCODATUMをつなぐ接続設定。管理者が認証情報や接続先を設定し、ワークスペースのメンバーに共有することで、ノートブックやカタログでデータを利用できるようになります。複数のコネクションを使い分けることも可能です。</td></tr><tr><td><a href="https://docs.codatum.jp/connect-and-manage-data/catalog">カタログ</a></td><td>利用可能なテーブルを検索・閲覧できる機能。テーブルの中身をプレビューしたり、カラムの説明を確認できます。「どんなデータがあるか探す」時に使います。</td></tr><tr><td><a href="https://docs.codatum.jp/data-exploration/notebook">ノートブック</a></td><td>データ分析を行うメインの作業場。クエリ（データ取得）、チャート（グラフ）、テキスト（説明文）を1つのドキュメントにまとめられます。リアルタイム共同編集が可能です。</td></tr><tr><td><a href="https://docs.codatum.jp/data-exploration/notebook/doc-page">ドキュメントページ</a></td><td>ノートブックのページの種類の一つ。文書形式で、SQLや文章を書くことができ、分析プロセスの記録や説明付きレポート作成に適しています。</td></tr><tr><td><a href="https://docs.codatum.jp/data-exploration/notebook/grid-page">グリッドページ</a></td><td>ノートブックのページ形式の一つ。チャートやテーブルを自由に配置できるタイル形式で、ダッシュボードやKPI監視画面の作成に適しています。</td></tr><tr><td><a href="https://docs.codatum.jp/data-exploration/explorer">エクスプローラ</a></td><td>テーブルのデータを手軽に探索できる機能。ノートブックを作成せずに、フィルター、集計、グラフ化ができます。カタログから直接開けます。</td></tr><tr><td>テーブル</td><td>データが整理されて保存されている表。1つのデータソースに複数のテーブルが含まれます。</td></tr><tr><td>SQLブロック</td><td>ノートブック内のSQLの要素の単位。クエリの編集と実行、結果の表示、統計情報の確認、チャートの作成ができます。</td></tr><tr><td><a href="https://docs.codatum.jp/sharing/report">レポート</a></td><td>ノートブックを「完成版」として公開・共有する機能。読み取り専用で、定期的な自動更新も設定できます。</td></tr><tr><td><a href="https://docs.codatum.jp/sharing/signed-embed">埋め込み（Embed）</a></td><td>ノートブックやレポートを外部のウェブサイトやアプリに組み込む機能。社内ポータルや顧客向けダッシュボードなど、CODATUM外でもデータを共有できます。enterpriseプランでのご利用が可能です。</td></tr><tr><td><a href="https://docs.codatum.jp/workflow/workflow">ワークフロー</a></td><td>データ処理や通知を自動化する機能。ノートブックの定期実行、条件付き処理、複数タスクの連携など、複雑な自動化シナリオを設定できます。</td></tr><tr><td><a href="https://docs.codatum.jp/codatum-ai/ai-assistant">AIアシスタント</a></td><td>データ分析をサポートするAIアシスタント。SQL作成の補助、データの傾向説明、最適なグラフの提案など、分析作業を効率化します。</td></tr></tbody></table>

## ナビゲーション

画面の一番左にある、濃いグレーの細長いエリアです。ここでCodatumの主要機能を切り替えます。　　

<table><thead><tr><th width="100">アイコン</th><th width="150">名称</th><th>説明</th></tr></thead><tbody><tr><td><img src="/files/HmTBtu4AVhgCRqsEnRW6" alt="通知"></td><td>通知</td><td>新着通知の確認。未読がある場合は赤いドットが表示されます</td></tr><tr><td><img src="/files/uKGUPqeduFu2TsEdLKcN" alt="クイック検索"></td><td>クイック検索</td><td>ノートブックやテーブルを素早く検索できます</td></tr><tr><td><img src="/files/ouhQ62BHYLItONB2O1bb" alt="ノートブック"></td><td>ノートブック</td><td>ノートブックを使って、データ分析やグラフ生成、レポートの作成が可能です</td></tr><tr><td><img src="/files/ZrgBId0XSXN8nh852fsC" alt="クエリ"></td><td>クエリ</td><td>複数のノートブックで利用できる汎用的なクエリの作成が可能です（中〜上級者向け）</td></tr><tr><td><img src="/files/BDLks0i67zWwv9ERW8Y8" alt="カタログ"></td><td>カタログ</td><td>テーブルの検索やメタデータ管理。どんなデータがあるか知りたい時や、テーブルの中身を見たい時に利用できます</td></tr><tr><td><img src="/files/xvtYtusacKzPyHtycgXx" alt="ワークフロー"></td><td>ワークフロー</td><td>データ処理の自動化や定期的な処理をしたいときに利用できます</td></tr><tr><td><img src="/files/2AsuRpiyaNzR9yNoD4P0" alt="レポート"></td><td>レポート</td><td>作成したレポートを閲覧することができます</td></tr><tr><td><img src="/files/kAeZ35wuBOiAU3DYPGg2" alt="AI機能"></td><td>AI機能</td><td>AIアシスタントを使った分析支援を利用できます</td></tr><tr><td><img src="/files/isEIuTsSCXfZMvGXKcv8" alt="設定"></td><td>ワークスペースの設定</td><td>ユーザー管理やテーマ変更、コネクションの設定、プラン確認などが可能です</td></tr></tbody></table>

## サイドバー　　

ナビゲーションで選択した機能の中身を、さらに細かく分類して表示するエリアです。

| 名称             | 概要                                             |
| -------------- | ---------------------------------------------- |
| 全メンバー\_ワークスペース | ワークスペース内の全員がアクセスできるノートブックが表示されます。フォルダでの管理が可能です |
| 共有フォルダ         | ユーザーやユーザーの所属するグループに対して共有されているノートブック            |
| プライベート         | あなただけがアクセスできるノートブックが表示されます。他のアカウントは見ることができません  |

## メインエリア

実際の作業内容が表示される、一番広いエリアです。

ホームでは、現在ログインしているメンバーや、最近見たノートブック、自分が作成したノートブック等について最新の情報を見ることができます。


# クイックスタート

Codatumは、データ分析に関わるあらゆる役割のユーザーに対応したデータ分析プラットフォームです。データの接続から分析、可視化、共有まで、一連のプロセスをシームレスに効率化し、ビジネスインサイトの創出をサポートします。

## このページの構成

このガイドは、目的に応じて読み進められるよう2つのパートに分かれています。

* **Part 1**: これからワークスペースをセットアップする管理者の方向けです。データウェアハウスへの接続とチームメンバーの招待を行います。
* **Part 2**: ワークスペースのセットアップが完了している場合、全員がここから始められます。ノートブックの作成からクエリの実行、チャート化、共有までの分析の一連の流れを説明します。

なお、接続済みのデモデータを用いてPart2からCodatumの分析を体験いただける仕様となっております。

## Part 1. ワークスペースをセットアップする（管理者様向け）

### Step 1. データに接続する

まず、Codatumをデータソースに接続する必要があります。現在、Google BigQueryやSnowflakeをサポートしており、Codatumから直接大規模なデータセットにアクセスして分析できます。 接続方法の詳細な手順は[こちら](/connect-and-manage-data/supported-warehouses)を参照してください。

<figure><img src="/files/bXmePV4VGzWreBdnwbZo" alt=""><figcaption></figcaption></figure>

**コネクションを作成する方法**

1. **コネクションに移動**: ページの左下にある`ワークスペース設定`に移動し、`コネクション`メニューを選択し、`コネクションを追加`をクリックします。
2. **認証情報をアップロード**: サービスアカウントのJSONキーファイルをアップロードし、コネクション詳細を入力します。
3. **同期対象**: Google CloudプロジェクトIDを追加し、メタデータの同期用のデータセットを選択します。

データが接続されると、分析に取り掛かる準備が整います。

### Step 2. チームメンバーを招待する

Codatumでチームメンバーをコラボレーションに招待するには、次の手順で行います：

1. **`ワークスペース設定`に移動**: `ユーザー`セクションに移動します。
2. **メンバーを招待**: `ユーザーを招待`をクリックし、リンクまたはメールで招待を送信します。

さらに、`許可ドメイン`を指定することで、ワークスペースへの自動参加を設定できます。指定されたドメインに一致するメールアドレスを持つ人は、自動的にワークスペースに参加できるようになります。\
招待を含むユーザー管理については、[こちら](https://docs.codatum.jp/workspace-and-user-management/user-management)にて詳細を確認いただけます。

## Part 2. はじめての分析（セットアップ完了後の利用者様向け）

### Step 1. ノートブックを作ってクエリを実行する

Codatumのノートブックは、SQL中心で理解しやすい分析を実現するために設計されています。SQLの柔軟性とマークダウンの明確さを組み合わせて、1つのツールでインサイトを構築し、共有できます。

<figure><img src="/files/gjZqdbLneLOZpzE6YwPF" alt=""><figcaption></figcaption></figure>

#### ノートブックを作ってクエリを実行する方法

1. **ノートブックを作成**: 新しいノートブックを作成します。
2. **SQLブロックを作成**: ページの本文に`/sql`と入力して、表示されるメニューから新しいSQLブロックを作成します。SQLブロックの右上で適切なコネクションを選択してください。

   <figure><img src="/files/6ulrNAKGgGBvEaHjkyjH" alt="" width="563"><figcaption></figcaption></figure>
3. **SQLを記述して実行**: SQLブロックを使用してクエリを記述し、実行します。Codatumの統合されたクエリエディタは、シンタックスハイライトや自動補完を提供し、ワークフローを効率化します。
4. **クエリ実行結果を探索**: SQLブロックの下に表示される結果を確認します。これらの結果を他のSQLブロックで参照して、各ブロックをシンプルで読みやすく保ちながら、より複雑なクエリを構築できます。
5. **分析を文書化**: 同じドキュメント内でマークダウンを使用して、SQLクエリに注釈を付けたり、ロジックを説明したり、コンテキストを提供したりできます。これにより、チームメンバーやステークホルダーと分析を共有しやすくなります。

分析が完了したら、魅力的な可視化を作成する準備が整います。

### Step 2. チャートにする

データを可視化することで、データの概要を把握し、意思決定を行うのに役立ちます。Codatumは、データをわかりやすく表現したチャートやダッシュボードを作成するための直感的なツールを提供します。

#### チャートを追加する方法

1. **チャートを作成**: クエリ実行結果をチャートに変換するには、クエリ実行結果の上部バーを使用します。好みのチャートタイプを選択し、必要に応じてカスタマイズします。

   <figure><img src="/files/khgPmunvmynU4FWEsvsY" alt="" width="563"><figcaption></figcaption></figure>
2. **ダッシュボードを構築**: チャートをダッシュボードに整理するには、[グリッドページ](/data-exploration/notebook/grid-page)を使用します。ノートブックの左上にある`+`アイコンからグリッドページを追加します。

データの可視化が完了したら、次はそこから得られたインサイトを活用し、効果的に共有しましょう。

### Step 3. 共有する

Codatumで作成したノートブックは、閲覧者に応じてアクセスレベルを柔軟に設定できます：

* **リアルタイムコラボレーションのために共有**: ノートブックをチームメンバーと共有し、積極的にコラボレーションします。
* **外部ユーザー向けの完成したインタラクティブレポートとして共有**: チーム外のステークホルダーとノートブックの最終版をインタラクティブな形で共有する必要がある場合は、[レポート](/sharing/report)を作成します。
* **パブリックリンクとして共有**: 認証を必要とせず、静的で読み取り専用のドキュメントを共有する必要がある場合は、URLを知っていれば誰でもアクセスできる[パブリックリンク](/sharing/public-link-and-embed)を生成します。

共有オプションを調整することで、データとインサイトが適切な人々に適切な権限でアクセスできるようにできます。


# 困った時には

操作方法やデータ分析の進め方で困ったときに、どこを見ればよいかをまとめたページです。

Codatumを使っていて操作方法や分析の進め方に迷ったときのために、次のようなサポート手段を用意しています。気軽に活用してください。

* ドキュメントのAI検索窓
* CodatumAI（AIアシスタント・AIエージェント）
* チャットサポート

## ドキュメントのAI検索窓で調べる

このドキュメントサイトの右上には、AIによる検索窓があります。知りたいことをキーワードだけでなく自然な文章で入力すると、関連するページに加えて、内容を要約した回答が表示されます。

「〇〇のやり方がわからない」「〇〇とは何か」といった疑問は、まずここで検索してみるのが最も早い解決方法です。

## CodatumAIに聞いてみる

Notebook上で使えるAIアシスタント・AIエージェント（総称してCodatumAIと呼びます）は、SQLの生成や修正だけでなく、分析の進め方そのものについて相談する相手としても活用できます。

例えば、次のような場面で使ってみてください。

* 「このテーブルにどんなカラムがあるか教えて」と聞いて、ゼロからテーブル定義を調べる手間を省く
* 「売上を月次で集計するにはどう書けばいい？」とSQLの書き方を相談する
* 「このグラフから読み取れる傾向を教えて」と分析結果の解釈を手伝ってもらう
* 「〇〇について調べて、簡単な分析をしてまとめて」とNotebookの作成自体を任せる

操作に迷ったときも、まずCodatumAIに話しかけてみることで、自己解決できる範囲が大きく広がります。詳しい機能や使い方は以下を参照してください。

* [AIアシスタント](/codatum-ai/ai-assistant)
* [Codatum Agent (ベータ版)](/codatum-ai/ai-agent)

## チャットサポートに問い合わせる

チャットサポートでは、実際にCodatumのメンバーが対応します。機能の使い方についての質問はもちろん、プランやご契約に関するご相談、不具合のご報告など、人に直接相談したいときはチャットサポートをご利用ください。

Codatum画面左下の`？`マークをクリックすると、チャットサポートやプロダクトアップデートなどのメニューがポップアップで表示されます。ここから`チャットサポート`を選択すると、Codatumチームに直接質問を送ることができます。


# システム要件

## 推奨環境

### オペレーティングシステム

* **Windows**（最新バージョン）
* **macOS**（最新バージョン）

### ブラウザ

* **Windows**: Google Chrome、Microsoft Edge（最新バージョン）
* **macOS**: Google Chrome、Safari（最新バージョン）

## 注意事項

* **ブラウザ拡張機能の影響**\
  一部のブラウザ拡張機能がノートブックのパフォーマンスに影響を与える可能性があります。問題が発生した場合は、拡張機能を無効にしてお試しください。
  * **既知の問題のある拡張機能**
    * [DeepL翻訳（Chrome拡張機能）](https://chromewebstore.google.com/detail/deepl-ai-translator-and-w/cofdbpoegempjloogbagkncekinflcnj)
    * [Microsoft Translator（Edge アドオン）](https://microsoftedge.microsoft.com/addons/detail/microsoft-translator-bui/fbhhdpcmomckhopgphnkegobjdggdfhe)


# コネクション

データウェアハウスへの接続設定とテーブルのメタデータ管理

<figure><img src="/files/bXmePV4VGzWreBdnwbZo" alt=""><figcaption></figcaption></figure>

コネクションは、データウェアハウスへのアクセスを管理するために使用されます。ユーザーがアップロードした認証情報を使って、クエリの実行やテーブル情報の取得を行います。

## 主な機能

* クエリの実行:
  * [ノートブック](/data-exploration/notebook)、[レポート](/sharing/report)、クエリで認証付きのクエリを発行します。
    * 不要なジョブの実行を防ぐためのキャッシュ機能があります。詳しくは、[(補足)クエリ実行とキャッシュ](/data-exploration/appendix-cache)をご覧ください。
* メタデータの集約:
  * [テーブル同期](/connect-and-manage-data/connection/sync-table-metadata)により、テーブルのスキーマ等のメタデータを集約し、最新のデータを維持します。
* アクセス制御:
  * [アクセス制御](/access-control/access-control-for-resources/access-control-for-connection)により、どのユーザーやグループが、クエリの実行やその実行結果の取得をできるか権限制御を行います。

## デモデータの利用

Codatumでは、すぐにデータ分析を試せるようにデモデータ（サンプルデータ）を提供しています。

* デモデータを使用することで、自身のデータウェアハウスを設定する前にCodatumの機能を体験できます
* デモデータには、典型的なビジネスデータ（売上、顧客、製品など）が含まれています
* ノートブックやレポートの作成時に、デモデータを使用したクエリをすぐに実行できます

## 設定方法

* 認証情報のアップロードを含む設定を作成し、構成します。各ウェアハウスのセットアップガイドを参照してください。
  * [対応データウェアハウス](/connect-and-manage-data/supported-warehouses)
* 同期をトリガーして、テーブルのメタデータを取得し保存します。
  * [テーブルメタデータの同期](/connect-and-manage-data/connection/sync-table-metadata)


# テーブルメタデータの同期

テーブルメタデータの同期について

テーブルメタデータを同期することで、テーブルとカラムに関する最新の情報が定期的にCodatumに保存されます。

{% hint style="info" %}
定期更新は週次で実行されます。即時の更新が必要な場合は手動で同期を実行してください。
{% endhint %}

クエリの実行結果は、テーブルメタデータの同期状況に関係なく出力されます。実行結果が更新されない場合はキャッシュされた結果が表示されている可能性があります。詳しくは[(補足)クエリ実行とキャッシュ](/data-exploration/appendix-cache)をご確認ください。

## 主な機能

* テーブルメタデータの集約:
  * 以下を含むテーブル構造:
    * データセット名
    * スキーマ名
    * テーブル名
  * テーブルの説明
  * 行数
  * テーブルサイズ (バイト)
  * テーブルの作成日と更新日
  * カラム名、データ型、カラムの説明
* 自動同期ジョブの実行:
  * 間隔: 週次
* 手動同期:
  * 管理パネルから手動で同期をトリガー
* リアルタイムの同期ステータス追跡:
  * 以下のようなステータスでリアルタイムに同期状況を監視:
    * キュー中 (QUEUED)
    * 処理中 (PROCESSING)
    * 成功 (SUCCESS)
    * 警告 (WARNING)
    * 失敗 (FAILED)

## テーブルメタデータの表示先

同期されたテーブルメタデータは以下の機能において利用されます。

* [カタログ](/connect-and-manage-data/catalog)
* [SQLブロック](https://github.com/codatum/support-site-gitbook/blob/main/ja/data-exploration/notebook/sql-block/README.md)
  * 入力補完
* 各種機能におけるテーブルの概要で表示されるカラム情報

## 権限

* 同期されたテーブルメタデータへのアクセスは、そのテーブルに関連付けられたコネクションに対する読み取り権限を持つユーザーに限定されます。
* 複数のコネクションが同じテーブルを参照している場合、それらは単一のテーブルメタデータエントリとして扱われます。いずれかのコネクションに読み取り権限が付与されていれば、そのテーブルメタデータにアクセスできます。

## 制限事項

* テーブル数: プランによって異なります。
  * <https://codatum.com/pricing>
* スキーマごとに同期可能なテーブル数: 最大1,000。
* テーブルごとに同期可能なカラム数: 最大1,000。

## トラブルシューティング: データウェアハウス内のテーブルが見つからない場合

1. 同期ステータスを確認し、エラーがないことを確認します。
2. データベースとテーブルが同期対象に選択されていることを確認します。
3. コネクションの認証情報にテーブルを参照する権限があることを確認します。
4. 必要に応じて手動で同期を実行します。


# 対応データウェアハウス

Codatumでサポートされているデータウェアハウスの一覧

現在、以下のデータウェアハウスに対応しています。それぞれのデータウェアハウスとの接続方法については下記のページをご覧ください。他のデータソースに接続したい場合は、`support@codatum.dev` までご連絡ください。

{% content-ref url="/pages/BnfnfjaIDKrqtyqdcfP0" %}
[BigQuery](/connect-and-manage-data/supported-warehouses/bigquery)
{% endcontent-ref %}

{% content-ref url="/pages/N1iD6kiT61RXljrry7H0" %}
[Snowflake](/connect-and-manage-data/supported-warehouses/snowflake)
{% endcontent-ref %}

{% content-ref url="/pages/AEFD0ivTEU0KiKAejp1e" %}
[Redshift](/connect-and-manage-data/supported-warehouses/redshift)
{% endcontent-ref %}

{% content-ref url="/pages/4rcb4sZMgF1v7mDFdVXi" %}
[Databricks](/connect-and-manage-data/supported-warehouses/databricks)
{% endcontent-ref %}

{% content-ref url="/pages/UZLAJOpjFrKoFatK8x19" %}
[その他のデータウェアハウス](/connect-and-manage-data/supported-warehouses/other-warehouses)
{% endcontent-ref %}


# BigQuery

BigQueryへの接続設定方法と、利用時の追加ノートについて説明します。

<figure><img src="/files/A7HPMGHvlW4yiBb1s7zJ" alt=""><figcaption></figcaption></figure>

Codatumを使用してBigQueryに接続し、クエリの実行やデータの管理ができます。

## 設定方法

#### BigQuery側の作業

まず、BigQueryコンソールで以下の操作を行います:

* サービスアカウントとサービスアカウントキーを生成する
* 対象のプロジェクトに以下の役割または権限を付与する:
  * `BigQuery Job User（BigQuery ジョブユーザー）` ロールまたは以下の権限:
    * `bigquery.jobs.create`
  * `BigQuery Read Session User（BigQuery 読み取りセッション ユーザー）` ロールまたは以下の権限:
    * `bigquery.readsessions.create`
    * `bigquery.readsessions.getData`
    * `bigquery.readsessions.update`
  * あとで必要となるため、対象の `プロジェクトID` をメモしておいてください
* 対象のデータセットに以下の役割または権限を付与する:
  * `BigQuery Data Viewer（BigQuery データ閲覧者）` ロールまたは以下の権限:
    * `bigquery.tables.getData`
    * `bigquery.datasets.get`
    * `bigquery.tables.get`
    * `bigquery.tables.list`
* (オプション) プロジェクトIDの入力を省略してデータセットテーブル情報を同期したい場合は、対象のプロジェクトに以下の権限を付与してください：
  * `resourcemanager.projects.get`

#### Codatum側の作業

最後に、Codatumで新しいコネクションを作成します。

1. `ワークスペース設定`の`コネクション`から`コネクションを追加`を選択
2. `コネクション名`を入力
3. `アクセスレベル`を選択
4. `ファイルアップロード`を使ってサービスアカウントキーをアップロード
5. `プロジェクトID`を入力
   * 上記BigQuery側の作業でメモしておいた `プロジェクトID` を使用
6. `同期対象`にデータセットを追加

## INFORMATION\_SCHEMAを使用して検索する

対象のプロジェクトに`bigquery.admin`権限を付与すると、同期していないデータセットのテーブルもINFORMATION\_SCHEMAテーブルを使って検索できます。


# Snowflake

Snowflake接続の設定方法と使用に関する追加情報

<figure><img src="/files/fV2MOfWrVPkdbsqWpjkB" alt=""><figcaption></figcaption></figure>

Codatumを使用して、Snowflakeのデータに接続、クエリ、管理ができます。

## 設定方法

### 1. キーペアとSnowflakeユーザーの準備

現在、キーペア認証のみがサポートされています。キーペアの作成方法については、[Snowflakeユーザーガイドのキーペア認証](https://docs.snowflake.com/ja/user-guide/key-pair-auth)を参考に、コネクションで利用するSnowflakeユーザーに対して公開鍵を設定してください。

### 2. 必要な権限の付与

Snowflakeユーザーに割り当てられたロールに権限を付与する必要があります：

* ロールの準備
  * 新しいロールを作成するか、既存のロールを使用して、作成したユーザーに割り当てます。
* ウェアハウスの権限
  * 使用したいウェアハウスに対する`USAGE`権限をそのロールに付与します。
* データベースの権限
  * 使用したいデータベースに対する`USAGE`権限をそのロールに付与します。
* スキーマの権限
  * 使用したいスキーマに対する`USAGE`権限をそのロールに付与します。
* テーブルの権限
  * 使用したいテーブルに対する`SELECT`権限をそのロールに付与します。

### 3. CodatumにSnowflakeコネクションを登録する

最後に、CodatumでSnowflakeコネクションを作成します

1. `ワークスペース設定`の`コネクション`から`コネクションを追加`を選択
2. `コネクション名`を入力
3. `アクセスレベル`を選択
4. `組織名`を入力します
   * Snowflake組織の名前です。詳細については[Snowflakeユーザーガイドのアカウント識別子](https://docs.snowflake.com/en/user-guide/admin-account-identifier#label-account-name-find)を参照してください。
5. `アカウント名`を入力します
   * Snowflakeアカウントの名前です。 （組織名を含む完全なアカウント識別子と混同しないように注意してください）詳細については[Snowflakeユーザーガイドのアカウント識別子](https://docs.snowflake.com/en/user-guide/admin-account-identifier#label-account-name-find)を参照してください。
6. `ユーザー名`を入力します
   * ステップ1で準備したユーザー名を使用します。
7. `ロール`を入力します
   * ステップ2で準備したロール名を使用します。
8. `ウェアハウス名`を入力します
   * ステップ2で準備したウェアハウス名を使用します。
9. `データベース名`を入力します
   * ステートメントが実行されるデフォルトのデータベースを指定します（「名前空間」のようなもの）。この設定は、クエリできるテーブルやスキーマを制限するものではありません。
10. `秘密鍵`を入力します
    * ステップ1で準備した秘密鍵を使用します。
    * `\-----BEGIN PRIVATE KEY-----`と`-----END PRIVATE KEY-----`の行を含む秘密鍵全体を貼り付けます。
11. `同期対象`にデータセットを追加します

## ネットワークとファイアウォールの制限

現在、Codatumは接続用の固定IPアドレスを提供していません。セキュリティ上の理由からSnowflakeでIPアドレスをホワイトリストに登録する必要がある場合は、可能なオプションについて話し合うためにCodatumサポートにお問い合わせください。


# Redshift

Redshift接続の設定方法と利用方法について説明します。

Codatumを使用して、Redshiftのデータに接続、クエリ、管理ができます。

{% hint style="warning" %}
この機能は現在プライベートプレビューです。この機能のご利用を希望される場合は、Codatumサポートまでお問い合わせください。
{% endhint %}

## 設定方法

Redshift連携は、RA3ノードのクラスターとサーバーレスを対象とします。

### 1. AWSコンソールで必要な準備を行う

#### DBにおける必要な権限の付与

連携用のロールを作成し、権限を付与します。

* 使用したいスキーマに対する `USAGE` 権限をそのロールに付与する
* 使用したいテーブルに対する `SELECT` 権限をそのロールに付与する
* システムビュー `svv_table_info` に対する `SELECT` 権限をそのロールに付与する

#### IAMユーザーの作成とポリシーの付与

* 連携用のIAMユーザーを作成し、 `AmazonRedshiftFullAccess` ポリシーを付与する

#### Secrets ManagerでSecretの作成

* 接続したいData Warehouseを指定し、Secretを作成する
* 作成したSecretに `RedshiftDataFullAccess` というタグを追加する（Valueは空でOK）

### 2. CodatumにRedshiftコネクションを登録する

最後に、CodatumでRedshiftコネクションを作成します。

* `ワークスペース設定`の`コネクション`から`コネクションを追加`を選択
* `コネクション名`を入力
* `アクセスレベル`を選択
* `アカウントID` を入力
  * AWSのアカウントIDです。
* `リージョン` を入力
  * Redshiftリソースが属しているリージョンです。
* `接続タイプ` を選択
  * クラスターを選択した場合
    * `クラスター識別子` を入力
    * `デフォルトデータベース` を入力
      * 接続先のデータベースです。この設定は、クエリ可能なデータベース、スキーマ、テーブルを制限するものではありません。
  * サーバーレスを選択した場合
    * `サーバーレス 名前空間` を入力
    * `サーバーレス ワークグループ名` を入力
    * `デフォルトデータベース` を入力
      * 接続先のデータベースです。この設定は、クエリ可能なデータベース、スキーマ、テーブルを制限するものではありません。
* `AWS アクセスキー` を入力
  * ステップ1で準備したIAMユーザーのアクセスキーを使用します。
* `AWS シークレットアクセスキー` を入力
  * ステップ1で準備したIAMユーザーのシークレットアクセスキーを使用します。
* `シークレットARN` を入力
  * ステップ1で準備したSecretのシークレットARNを使用します。

入力が完了したら、接続テストを行った後、コネクションを保存してください。


# Databricks

Databricks接続の設定方法と利用方法について説明します。

Codatumを使用して、Databricksのデータの接続、クエリ実行、管理ができます。

{% hint style="warning" %}
この機能は現在プレビュー中の機能です。仕様については予告なく変更となる場合がございます。また、一部機能に制限がある場合がございます。
{% endhint %}

## 設定方法

Databricks連携は、サーバーレスSQLウェアハウスを対象とします。

### 1. Databricksコンソールで必要な準備を行う

連携用のサービスプリンシパルを作成して、適切な権限を付与します。

#### アカウント管理画面

* メニューのユーザー管理 > サービスプリンシパルから、連携用のサービスプリンシパルを作成する
* サービスプリンシパルの資格情報とシークレットタブで、OAuthシークレットを生成する。その際、クライアントIDとシークレットを保存しておく
* サービスプリンシパルのロールタブの設定は、全てOFFにしておく
* メニューのワークスペースから連携するワークスペースを選択し、権限タブから作成したサービスアカウントを追加する

#### ワークスペース管理画面

* 接続するSQL WarehouseのCan Use許可をサービスプリンシパルに付与する
  * メニューのSQLウェアハウスから連携するウェアハウスを選択
  * 右上の権限ボタンをクリックし、連携用のサービスプリンシパルに `使用可能` 権限を付与する
* カタログを利用する権限をサービスプリンシパルに付与する
  * メニューのカタログから、連携するカタログを選択
  * 権限タブで付与ボタンをクリックし、サービスプリンシパルの選択、`SELECT` 、`USE CATALOG` 、`USE SCHEMA` 権限を付与する

### 2. CodatumにDatabricksコネクションを登録する

* `ワークスペース設定`の `コネクション`から`コネクションの追加`を選択
* `コネクション名`を入力
* `アクセスレベル`を入力
* `サーバーホスト名`を入力
  * Databricksワークスペース管理画面のメニューにあるSQLウェアハウスから、連携するウェアハウスを選択し、接続の詳細タブ内にあるサーバーのホスト名（例：`<your_instance_name>.cloud.databricks.com` ）
* `HTTPパス`を入力
  * Databricksワークスペース管理画面のメニューにあるSQLウェアハウスから、連携するウェアハウスを選択し、接続の詳細タブ内にあるHTTPパス（例：`/sql/1.0/warehouses/<your_warehouse_id>` ）
* `ウェアハウス ID`を入力
  * メニューのSQLウェアハウスから連携するウェアハウスを選択し、概要タブ内の名前の横にあるID
* `クライアント ID`を入力
  * 1で作成したサービスプリンシパルのクライアントID
* `クライアントシークレット`を入力
  * 1で作成したサービスプリンシパルのクライアントシークレット

入力が完了したら接続テストを行い、コネクションを保存してください。


# その他のデータウェアハウス

その他のデータウェアハウス

<figure><img src="/files/rcNltrBBNadDDl3tlGKN" alt=""><figcaption></figcaption></figure>

その他のデータウェアハウスについても、順次対応を拡大していく計画です。ご希望のデータウェアハウスがあれば、`support@codatum.dev` までご連絡ください。


# カタログ

データメタデータを手動で拡張し、検索性を向上させる

<figure><img src="/files/plSbmYIVHTKvM7VNmSvd" alt=""><figcaption></figcaption></figure>

カタログは、テーブルとクエリのメタデータを管理するように設計されており、データの整理と検索を容易にします。

## 主な機能

* アノテーション:
  * テーブルと列に説明やタグを追加して、コンテキストを提供し、理解を深めることができます。
* 検索性の向上:
  * アノテーションやタグを使用してキーワード検索を改善し、必要なデータをすばやく見つけやすくなります。
* 人気度:
  * ノートブックで参照されているクエリの数に基づいてテーブルの人気度を追跡でき、最も頻繁に使用されているテーブルを特定できます。
* 参照:
  * テーブルを参照しているノートブックやジョブを特定でき、データの依存関係と使用状況を明確に把握できます。


# クイック検索

Codatumで様々なリソースを検索できます

<figure><img src="/files/K5yFLKUdzenBrYh6iwRA" alt=""><figcaption></figcaption></figure>

ワークスペース全体で、ノートブック、テーブル、クエリなど様々なリソースを検索できます。

## 主な機能

* 全文検索:
  * ノートブック: ノートブックの名前とSQL文を含む本文内を検索
  * テーブルとクエリ: 名前、スキーマ情報、カタログで付与された説明を検索


# データ探索の概要

ノートブック、チャート、エクスプローラ、パラメータを使用して、データの分析と可視化を簡単に行えます。

Codatumでは、ノートブック上でSQLブロックを使ってクエリを段階的に組み立てることができ、ひとつのブロックで定義したSQLを別のブロックから参照しながら、アドホックなデータ分析を行うことができます。さらに、これらの結果を様々なチャートで表示したり、パラメータやエクスプローラなどの機能を使用することで、GUIベースのインターフェースを通じて簡単にデータを深く掘り下げることができます。

## 主要なツールと機能

* ノートブック:
  * ノートブックはリアルタイムの共同編集をサポートしており、複数のユーザーが同時に作業を行い、コメントを追加したり、他のユーザーにメンションしたりすることができます。
  * フローベースのブロックエディタ（ドキュメントページ）とSQLブロックを使用して、アドホックなデータ抽出や複雑なデータ分析を行いながら、その過程に対する説明をリッチテキストで挿入できます。さらに、視覚的に魅力的なチャートを作成し、タイルベースのドキュメント（グリッドページ）に整理して配置することで、分析結果を観察・共有できます。
* チャート:
  * ノートブックで抽出したデータ分析の結果は、さまざまなチャートを使ってわかりやすく、そして美しく表現できます。データやインサイトに最適なチャートタイプを選んで可視化することが可能です。
  * これらのチャートは、レポートを通じて共有したり、ウェブサイトやブログに直接埋め込んで、より広く発信したりすることができます。
* エクスプローラ:
  * ノートブックやレポートで、ドラッグ＆ドロップやスプレッドシートのようなUIを使用して、コーディングなしでデータの絞り込み、抽出、集計、修正を簡単に行えます。
  * エクスプローラは、複雑なデータ操作を簡素化するグラフィカルインターフェースを提供し、あらゆるスキルレベルのユーザーにとってアクセスしやすくなっています。
* パラメータ:
  * ノートブックでパラメータウィジェットを使用することで、ノートブックやレポートを動的でインタラクティブなものにできます。これにより、SQLに直接アクセスすることなくパラメータを通じて埋め込みSQLを制御し、必要に応じてカスタマイズされた出力を得ることができます。


# ノートブック

リアルタイムのデータ分析と可視化のためのコラボレーティブスペース。

<figure><img src="/files/rkM9jWu7JYBQhgXgGX9B" alt=""><figcaption></figcaption></figure>

ノートブックはリアルタイムの共同編集機能を備えており、複数のユーザーが同時に作業でき、コメントの追加や他のユーザーへのメンションも可能です。

また、ドキュメントページとSQLブロックを使用して、アドホックなデータ抽出や複雑な分析が可能です。さらに、グリッドページでは、魅力的なチャートを整理して配置できます。

## 主な機能

* リアルタイム共同編集:
  * リアルタイムで共同編集が可能で、コメントの追加やユーザーへのメンションもできます。
* 2種類のページタイプ:
  * [ドキュメントページ](/data-exploration/notebook/doc-page)
    * アドホックな分析を行い、分析プロセスを記録できます。
  * [グリッドページ](/data-exploration/notebook/grid-page)
    * チャートを効果的に配置できます。
* [SQLブロック](/data-exploration/notebook/sql-block)
  * SQLを直感的に作成できる強力なエディタです。
* [バージョン](/data-exploration/notebook/version)
  * 分析の状態を自動および手動で保存・復元できます。
* ロック:
  * 完成したノートブックを誤って編集してしまわないように、ロックをかけることができます。
  * ロック状態には以下の3種類があります：
    * アンロック（デフォルト）:すべての編集が可能です。
    * クエリのみ:パラメータの編集とクエリの実行ができます。
    * ロック:コメントの編集のみ可能です。
* [ノートブックテーマ](/data-exploration/notebook/notebook-theme)
  * チャートの色やフォントサイズ・フォントファミリーのカスタマイズが行えます。


# ドキュメントページ

キーボード操作を重視したエディタで、効率的なアドホック分析と可視化を実現。

<figure><img src="/files/ZOjc4FATkec68oXbSIUy" alt=""><figcaption></figcaption></figure>

ドキュメントページはノートブックのページの一種で、データ分析の抽出、探索、可視化を行えます。素早いアドホック分析が可能で、作業過程も記録できます。キーボード操作を重視したユーザーインターフェースにより、スムーズな作業フローを実現します。

## 主な機能

* フロースタイルのブロックエディタ:
  * 縦方向に流れるエディタで、中断のない滑らかな記述が可能。キーボードとマウスの切り替えを最小限に抑え、作業に集中できます。
* 多様なブロックタイプ:
  * SQLブロック、チャート、画像、レイアウト、折りたたみリストなど、様々なブロックタイプを使ってページを構築できます。スラッシュコマンドで簡単にアクセスできます。
* コードとのシームレスな連携:
  * SQLとのスムーズな連携を実現します。
* キーボード操作重視のデザイン:
  * キーボード操作に最適化されており、開発者にとって使いやすいインターフェースです。
* 全文検索:
  * ドキュメント内の包括的な検索機能を提供します。
* パラメータ:
  * 埋め込みSQLやその他の動的要素を制御するためのパラメータ機能をサポートします。


# グリッドページ

グリッドレイアウトでSQLの実行結果やチャートをカスタマイズして配置できるページです。

<figure><img src="https://github.com/codatum/support-site-gitbook/blob/main/ja/data-exploration/.gitbook/assets/grid.png" alt=""><figcaption></figcaption></figure>

グリッドページは、ドキュメントページで作成したSQLの実行結果やチャートをグリッドレイアウトで自由に配置できるページです。

## 主な機能

* 直感的なGUIによる操作:
  * チャートコンポーネントを含む様々なコンポーネントを自由に配置、並び替え、サイズ変更、ドラッグ&ドロップできます。
* リアルタイム共同編集:
  * 他のユーザーによるグリッド上の変更がリアルタイムで反映されます。（ただし、チャートの設定などは明示的に保存するまで共有されません）
  * コメントの追加が可能です。
* パラメータ:
  * パラメータを配置し、簡単に操作できます。
* エクスプローラ:
  * エクスプローラを使ってデータの探索を行えます。
* クロスフィルタ（ベータ）:
  * 複数のチャートにおいて共通の凡例・軸をリンクし、データ表示の対象を同期させることが可能です。
  * 設定上の制約などは[クロスフィルタ](/data-exploration/notebook/grid-page/cross-filter)をご覧ください。

## 配置可能なコンポーネントの種類

グリッドに配置できるコンポーネントは以下の通りです:

* 見出し
  * 3つのレベルがあり、タイトルやセクションの区切りに使用できます。
* テキスト
  * 文書化に使用できるリッチテキストです。
* SQL実行結果テーブル
  * ドキュメントページで作成したSQLの実行結果を表示するテーブルです。
* チャート
  * ドキュメントページで作成したあらゆるチャートを配置できます。

## コンポーネント設定の同期について

一部の設定はグリッドページとドキュメントページで同期されますが、他の設定は独立しています。

* ドキュメントページと同期される設定:
  * チャートの設定（軸フィールド、チャートタイプなど）
* ドキュメントページと同期されない設定:
  * コンポーネントの設定（ヘッダ表示、コンポーネントタイトルなど）


# クロスフィルタ

複数のチャートにおいて共通の凡例・軸をリンクし、データ表示の対象を同期。

{% hint style="warning" %}
この機能はベータ版です。仕様については予告なく変更となる場合がございます。
{% endhint %}

クロスフィルタ機能を利用することで、特定のチャートで凡例・軸を絞り込んだ場合の表示対象を複数のチャートに同期することができます。

絞り込みはフロントエンド上で読み込まれたデータを対象に行われるため、フィルタの変更で追加のジョブの実行は発生しません。

## 動作

* 設定を行ったチャートを対象に凡例・軸の選択状況が同期されます
  * チャート上の凡例を選択した場合：選択した内容の凡例のデータのみが表示されます
  * チャートの表示内容にマウスオーバーした場合：マウスオーバーしている凡例のハイライトが同期されます
  * 軸を範囲選択した場合：選択した範囲のデータのみが表示されます

## 設定方法

* グリッドページ上のチャートにマウスオーバーした際に表示される右上のメニューからクロスフィルタを選択します
* `キー`を設定します
  * 同じ値で同期を行いたいチャートに対して、同一の`キー`を設定します
  * 選択したチャートに応じて「軸」「凡例」それぞれに`キー`を設定できます
    * テーブルチャートの場合は対象としたいカラム毎に`キー`を設定します

## 仕様

* 対象のチャート
  * XYチャート
  * XYZチャート
  * 円形チャート
  * ファンネルチャート
  * テーブルチャート
    * その他のチャートでの選択状況はテーブルチャートに反映されますが、テーブルチャート側での絞り込み内容はその他のチャートに反映されません
* 絞り込まれるデータの範囲
  * フロントエンド上に読み込まれたデータを対象に絞り込みを行います
  * SQLの再実行は行われないため、XYチャートの軸単位で表示するデータの期間を絞り込んだ場合の絞り込みを円グラフの集計に反映させるといったことはできません
* 凡例の絞り込み
  * 選択された凡例名の値の「文字列 or 数値」を元に絞り込みを行います
* 軸の絞り込み
  * 選択された軸の下限・上限の「文字列 or 数値」を元に範囲で絞り込みを行います

## 注意事項

* 凡例→軸の連携
  * 軸単位でのデータの表示対象は範囲での指定となります
  * そのため凡例側で複数の凡例を選択した場合、選択した凡例のみでなく、選択した凡例の範囲に含まれる対象が表示されます
* 軸→軸の連携
  * 軸が文字列で設定されている場合、範囲指定が表示順の影響を受けるため、表示順が異なっていると正しく連動されません


# SQLブロック

Codatumにおけるパワフルなサポートを備えたプロフェッショナルSQLエディタ

<figure><img src="/files/Mh9qgjisKj7GAleBUk73" alt=""><figcaption></figcaption></figure>

SQLブロックはノートブック内のブロックで、SQLの実行を可能にします。

SQLブロック内では、クエリの編集と実行、結果の表示、統計情報の確認、チャートの作成ができます。

## 主な機能

* パワフルなサポートを備えたプロフェッショナルSQLエディタ:
  * 関数や予約語の提案、オートコンプリート、シンタックスハイライト、フォーマッティングなどの機能を含みます。
* 即時結果プレビュー:
  * Ctrl + Returnを使用してクエリを実行し、リアルタイムで結果をプレビューできます。
* テーブル検索:
  * SQLブロック内で`/`コマンドを使用して、データセットとそのコネクションのテーブルを検索できます。カタログ内のメタデータやフィールド名での検索も可能です。
* コードスニペット:
  * 個人用のコードスニペットを作成したり、ワークスペース全体で共有したりできます。トリガーや補完後のカーソル位置などの設定をカスタマイズできます。
* 豊富なショートカットキー:
  * 様々なショートカットキーを利用でき、個人用にカスタマイズすることも可能です。
* SQLチェイン
  * SQLブロック内で他のSQLブロックを参照できます。これにより、複雑なSQLをより理解しやすく再利用可能なコンポーネントに分解して管理できます。
* フィールド統計:
  * 各フィールドのデータ型、NULL値の有無、ユニーク数、平均値、分位数、頻度、ヒストグラムなどの統計情報を簡単に取得できます。

## 使用方法

* SQLブロックの作成:
  * ドキュメントページ内の空の段落にフォーカスを当てた状態で、スラッシュコマンド（`/`）を使用してSQLブロックを選択し、作成します。
* 参照の作成:
  * SQLブロック内でスラッシュコマンドを使用して、他のSQLブロックやテーブルへの参照を作成できます。
  * パラメータや保存済みクエリへの参照も作成できます。


# バージョン

分析の状態を自動または手動で保存・復元できます

バージョンは自動または手動で保存・復元できます。データが破損した場合や以前の状態に戻す必要がある場合は、保存されたバージョンから復元できます。

## 主な機能

* 自動バージョン作成:
  * 変更があった際や一定期間経過後に自動的にバージョンを作成します。
  * 古いバージョンは自動的に削除され、スペースを節約できます。
* 手動での名前付きバージョン:
  * 手動でバージョンを作成し、名前を付けられます。
  * 手動で作成したバージョンは別々に管理され、自動バージョンによる上書きはされません。
* ノートブックの復元:
  * バージョンから新しいノートブックを作成できます(既存のノートブックへの上書きはできません)。
* ユーザー固有のパラメータ:
  * ノートブックでは、パラメータ値と関連する実行結果が複数のユーザー間で共有されます。しかし、バージョンでは、これらをユーザー個別に保持できます。
  * この機能はレポートでも実現できます。
* 差分比較機能
  * 「現在のノートブックと比較」から現在のノートブックと保存されたバージョンとの変更点を確認することができます。
  * この機能は「共有」メニューからも利用でき、公開済みのレポートやパブリックリンクとの比較も可能です。

## パラメータとURLの同期

バージョン内でパラメータを変更すると、変更されたパラメータの情報がURLに同期されます。そのため、URLを他のユーザーと共有することで、パラメータの値を共有することができます。詳細については、[URLからパラメータを指定する方法](/data-exploration/parameter-overview/set-parameters-via-url)を参照してください。

## SQLリザルトキャッシュの処理

SQLブロックキャッシュが有効な限り、SQL実行結果とチャートにアクセスできます。SQLブロックキャッシュがなくなった後でも、スナップショット内のSQLブロックを再実行すれば、実行結果とチャートが更新されます。

## **自動スナップショットの頻度**

変更ごとにスナップショットを作成するのではなく、複数の変更がまとめられ、1つのスナップショットとして保存されます。編集を続けると、約1時間の変更がまとめて保存されます。


# テーマ

ノートブックの外観のカスタマイズ

ノートブックテーマを設定することで、ノートブック内のチャートの色やフォントサイズ・フォントファミリーのカスタマイズが行えます。

## カスタマイズ可能な項目

### 共通項目

* 基準フォントサイズ
  * ここで指定されたサイズを基準に、テキストサイズや入力フォームの各要素のサイズ等が決定します
  * ただし、チャートの「詳細設定」で「基準フォントサイズ」を指定している場合、そちらが優先されます
* フォントファミリー
  * ここで指定されたフォントファミリーがノートブック内のテキストやチャート内のテキストに適用されます

### ライトテーマ・ダークテーマ毎の項目

* チャートカラー
  * 系列を塗り分けるための系列色と、グラデーションを塗り分けるためのグラデーション色を設定できます
* ステータスカラー
  * 成功、警告、危険の3色を設定できます
  * これらの色は、チャート内のステータス表現や、エラーメッセージ等で使用されます
* プライマリーカラー
* フォーカスカラー
* リンクカラー
* バックグラウンドカラー
* テキストカラー
* ボーダーカラー

※ プランによってカスタマイズ可能な項目に制限があります

## 設定方法

### ノートブックテーマの作成・編集

* 「ワークスペース設定」>「ノートブックテーマ」からテーマの作成・編集が行えます
  * ノートブックテーマの作成・編集を行うには「[ワークスペースオーナー](/access-control/access-control-for-workspace)」の権限が必要です

### ノートブックテーマの適用

* ノートブックページの画面右上の3点メニュー内の「ノートブックテーマ」から、既存のノートブックテーマを適用することができます
  * [ノートブックの編集](/access-control/access-control-for-resources/access-control-for-notebook)権限が必要です

## 影響範囲

* ノートブックテーマは、ノートブックから作成される以下のリソースに対しても適用されます
  * [レポート](/sharing/report)
  * [パブリックリンク](/sharing/public-link-and-embed)
  * [署名付き埋め込み](/sharing/signed-embed)
* 既存のノートブックテーマを変更すると、そのノートブックテーマが適用されているすべてのノートブックに対して、変更が反映されます
  * ただし、ノートブックから公開される上記リソースについては、リソースの「公開」処理を行うタイミングで変更が反映されます
* ノートブックテーマのデフォルト設定は、新規に作成されるノートブックに対して適用され、既存のノートブックには影響しません


# ノートブックに関するFAQ

Codatum ノートブックに関する重要な仕様

## ノートブック

#### ユーザ削除後そのユーザが作成したノートブックへは引き続きアクセス可能でしょうか？

PrivateなNotebookにはアクセスできなくなりますが、それ以外のNotebookは引き続きアクセス可能です。

#### パラメータやチャートの変更は、ユーザーごとに独立していますか？

パラメータ、SQL、チャートの変更は、同じページを閲覧しているすべてのユーザーに即座に反映され表示されます。これらの変更はノートブック内の状態として保存されます。

ただし、SQLブロックやリスト要素のトグル状態など、ページの外観に関する設定はユーザー間で同期されません。

#### `すべて実行`を実行する際にキャッシュは使用されますか？

`すべて実行`を実行する際には、利用可能なキャッシュが使用されます。

詳細については、[SQLブロックキャッシュ](/data-exploration/appendix-cache)ページをご参照ください。

データソースを更新した後など、キャッシュを使用したくない場合は、ページ右上から`最新データですべて実行`を選択して、すべてのSQLブロックを実行してください。

#### ノートブックに制限はありますか？

ノートブック1つあたりの最大サイズは**10MB**です。

大量のコンテンツがある場合、特に**読み込み時間や競合解決**のパフォーマンスに影響を与える可能性があります。スムーズなパフォーマンスを維持するために、ノートブックはコンパクトに保つことをお勧めします。ノートブックが大きくなりすぎた場合は、ページを追加する代わりに**新しいノートブックを作成**することを検討してください。

#### 大きなノートブックを管理するための推奨方法：

* **ノートブックをエクスポートし、新しいノートブックにページをインポートする**\
  ノートブックが大きくなりすぎた場合、元のノートブックをエクスポートし、新しいノートブックを作成して、そこにいくつかのページをインポートできます。ページを移動する際は、依存関係が壊れないように**参照されているSQLブロック**を適切に管理してください。
* **古いノートブックをアーカイブする**\
  大きなノートブックを編集する必要がなくなったが、内容を保持したい場合は、**複製**して、その複製を**読み取り専用**に設定してアーカイブ用にすることができます。その後、元のノートブックから**不要なページを削除**してサイズを縮小することができます。

## ドキュメントページ

#### ドキュメントページの内容が長くなった場合、複数のページに分割するタイミングはどのように判断すればよいですか？

ドキュメントページの内容が長くなると、分析の理解が難しくなります。

SQLブロックは他のページのSQLブロックを参照できるため、いつでもドキュメントページを分割して分析を続けることができます。

同様に、パラメータも異なるページ間で作成・参照することができます。

#### ページ数が増えた場合、ノートブックを分割するタイミングはどのように判断すればよいですか？

ページ数が増えると、特定の分析がどこで行われたかを見つけるのが難しくなります。

また、ページ内の要素数やページ数が増えると、ノートブック全体のパフォーマンスが低下する可能性があります。

ノートブック間でSQL文を共有したい場合は、クエリを使用して保存し、複数のノートブックから参照することができます。

ページ数が大幅に増えた場合は、再利用可能なSQL文のみをクエリとして保存し、新しいノートブックを作成してください。

## SQLブロック

#### SQLブロック内で参照しているテーブルのカラム名が提案されません。

カラム名のサジェストや、メタデータ・スキーマの表示は、「テーブルへの参照」または「SQLブロックへの参照」の実行結果に限定されています。

テーブルIDを文字列として使用する場合や、「保存済クエリへの参照」を参照する場合は、サジェストやスキーマ表示が利用できませんのでご注意ください。


# チャート

美しく多様なチャート

Codatumは、多様なデータに対応するために幅広い種類のチャートを提供しています。さらに、各チャートには数多くの設定があり、データに合わせてビジュアルをカスタマイズできます。

## チャートの種類

### [ビッグナンバー](/data-exploration/chart/bignumber)

重要な指標をテキスト形式、ゲージ形式で表示します。

| <picture><source srcset="/files/2VwH0ynqMTpq3D1XPBBV" media="(prefers-color-scheme: dark)"><img src="/files/uNuj5G3ugwzkYprB4HW0" alt="BigNumber Text"></picture> | <picture><source srcset="/files/d9VQFn9QqCXVNqQBa4A4" media="(prefers-color-scheme: dark)"><img src="/files/EZWclrN33PmaWq5A0Zay" alt="BigNumber Gauge"></picture> |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

### [XY チャート](/data-exploration/chart/xy-chart)

折れ線、棒、積み上げ棒、エリア、積み上げエリア、100%積み上げ棒、100%積み上げエリア、散布図、バブルチャートから選択できます。複合チャートも利用可能です。

| <picture><source srcset="/files/ktmRar9T6XFAYp9s7ZlN" media="(prefers-color-scheme: dark)"><img src="/files/7ea5VftzAvJnuk8xcd0E" alt="XY Line"></picture>    | <picture><source srcset="/files/T8oTKBaCXC6UKgHALSKj" media="(prefers-color-scheme: dark)"><img src="/files/6AmsbtyjMmIbshuciZEG" alt="XY Bar"></picture>          | <picture><source srcset="/files/BWhrnJe22KloAjXQwojZ" media="(prefers-color-scheme: dark)"><img src="/files/asV4mYL91xdPjA9HNCf7" alt="XY Stacked Bar"></picture>  |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| <picture><source srcset="/files/BgncFQZMg3DtG7mZ3VAm" media="(prefers-color-scheme: dark)"><img src="/files/Lu78CL9rgSHQp1qBIC1i" alt="XY Area"></picture>    | <picture><source srcset="/files/nPQj4ByyfVFZISP9vghJ" media="(prefers-color-scheme: dark)"><img src="/files/HIv1ikWyDfhzlJc38BmF" alt="XY Stacked Area"></picture> | <picture><source srcset="/files/Ly1LfskHbQ9MLXNolXrs" media="(prefers-color-scheme: dark)"><img src="/files/4ZTGedLQ3L8IGk5uvjRj" alt="XY Percent Bar"></picture>  |
| <picture><source srcset="/files/vH4O755ClE3Dd9Ai6yye" media="(prefers-color-scheme: dark)"><img src="/files/GuT0G3vKmyC2Pt24KEaf" alt="XY Scatter"></picture> | <picture><source srcset="/files/4F0xfb3f7uAupInFaiBx" media="(prefers-color-scheme: dark)"><img src="/files/DKjgAMXvk406gKnTNSu8" alt="XY Bubble"></picture>       | <picture><source srcset="/files/s0Q5MRtkIXDuMcfU3lPw" media="(prefers-color-scheme: dark)"><img src="/files/lb10uSfI8LFWmYFrtGW9" alt="XY Percent Area"></picture> |

### [円形チャート](/data-exploration/chart/radial-chart)

円グラフ、ドーナツチャート、レーダーチャートから選択できます。

| <picture><source srcset="/files/1D4vOvlvm1hK5U5wPQX9" media="(prefers-color-scheme: dark)"><img src="/files/O99atc6pCHFd136y7nEj" alt="Radial Pie"></picture> | <picture><source srcset="/files/U2Y5FIZ9mt4a774mTOsJ" media="(prefers-color-scheme: dark)"><img src="/files/vg1PDh6jd0nWbF0sg4gV" alt="Radial Donut"></picture> | <picture><source srcset="/files/2loNTEzg4uyuk4YBWtnS" media="(prefers-color-scheme: dark)"><img src="/files/A7J7JBYlS48Vf0cif6zy" alt="Radial Radar"></picture> |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |

### [XYZ チャート](/data-exploration/chart/xyz-chart)

散布図、バブルチャート、ヒートマップから選択できます。

| <picture><source srcset="/files/4TI5QQefz553TUlpEn3Q" media="(prefers-color-scheme: dark)"><img src="/files/dInhJtmryVbPTtXHNzx6" alt="XYZ Scatter"></picture> | <picture><source srcset="/files/IalhyKtE4iI3xBb5zdcg" media="(prefers-color-scheme: dark)"><img src="/files/Q2X4wR3PiXCPdvl6zWQB" alt="XYZ Bubble"></picture> | <picture><source srcset="/files/cWTpnV7Hw5k0JQqpwW2j" media="(prefers-color-scheme: dark)"><img src="/files/VOsb0eKUVyj9ACWwmih0" alt="XYZ Heatmap"></picture> |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |

### [階層チャート](/data-exploration/chart/hierarchy-chart)

ツリー、ツリーマップ、サンバースト、階層バーチャートから選択できます。

| <picture><source srcset="/files/xl1ACE4sVRkEtPJIWtms" media="(prefers-color-scheme: dark)"><img src="/files/E3linHIMapFBQFeTVDCw" alt="Hierarchy Tree"></picture> | <picture><source srcset="/files/BT5iYWwOeLSXFfcc22cy" media="(prefers-color-scheme: dark)"><img src="/files/75UAnEB9eAtwQJMwvuB9" alt="Hierarchy Treemap"></picture> | <picture><source srcset="/files/Q1gbbH3Snlv9iLq9xoeI" media="(prefers-color-scheme: dark)"><img src="/files/zxRg3zqyREYE3wEfHpFN" alt="Hierarchy Sunburst"></picture> |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <picture><source srcset="/files/w5m0pIovNs6zimboL1uL" media="(prefers-color-scheme: dark)"><img src="/files/AB67G3dH0pfkzfZgr4S8" alt="Hierarchy Bar"></picture>  |                                                                                                                                                                      |                                                                                                                                                                       |

### [グラフチャート](/data-exploration/chart/graph-chart)

グラフチャートとサンキーダイアグラムから選択できます。

| <picture><source srcset="/files/qUtc8t9mEKcmfP68Ke1o" media="(prefers-color-scheme: dark)"><img src="/files/5nplSobj4d3hj6vV8IiW" alt="Graph Chart"></picture> | <picture><source srcset="/files/Cqmn7NBYeIVwahspdiV3" media="(prefers-color-scheme: dark)"><img src="/files/2WkK8VNZH1k2ACpOrpyo" alt="Sankey Diagram"></picture> |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |

### [ファンネルチャート](/data-exploration/chart/funnel-chart)

縦型と横型のファンネルチャートから選択できます。

| <picture><source srcset="/files/8iLYqpkgK1XC8CzRPZuL" media="(prefers-color-scheme: dark)"><img src="/files/0KJKVRQ6fB4VV7SIetnt" alt="Funnel"></picture> |
| --------------------------------------------------------------------------------------------------------------------------------------------------------- |

### [ウォーターフォールチャート](/data-exploration/chart/waterfall-chart)

項目の増減を積み上げて表示します。

| <picture><source srcset="/files/mMPBVrP0b6ewfg0joQeE" media="(prefers-color-scheme: dark)"><img src="/files/618sOtti7U7DXPwpNSec" alt="Waterfall"></picture> |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------ |

### [テーブルチャート](/data-exploration/chart/table-chart)

希望するフィールドを選択して表示し、フィルタを適用したり、集計形式でデータを表示したりできます。

| <picture><source srcset="/files/0q3RCR2xy7GGLxBYJea9" media="(prefers-color-scheme: dark)"><img src="/files/ikNyBqstPVdnhFlbYYjd" alt="Table Raw"></picture> | <picture><source srcset="/files/xrfZtKGyM4QO5etA8nQk" media="(prefers-color-scheme: dark)"><img src="/files/N9otS0YMTZxRUTquAURf" alt="Table Aggregated"></picture> |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

### [ピボットテーブル](/data-exploration/chart/pivot-table)

行/列でデータを集計し、ピボットテーブルとして表示します。

| <picture><source srcset="/files/SQK9OUJk3e4kC6ZBrcmE" media="(prefers-color-scheme: dark)"><img src="/files/oFQwWQljHZbMxJdhbsVS" alt="Pivot Table"></picture> |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------- |

### [テキストパネル](/data-exploration/chart/text-panel)

Markdown形式でテキストを表示できます。生成AIとの併用によって、ダッシュボードへの動的な[AI生成サマリー](/best-practices/ai-generated-summary)の表示に利用できます。

| <picture><source srcset="/files/5UZLCbYU6tBtiGAvMCC7" media="(prefers-color-scheme: dark)"><img src="/files/lY7WetkCTJpccH7abOVl" alt="Text Panel Markdown"></picture> | <picture><source srcset="/files/k1RDwzsiDvzxYXVgsSLX" media="(prefers-color-scheme: dark)"><img src="/files/0m8i4DPBdCFWx0VYYySQ" alt="Text Panel Raw"></picture> |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |

### [地図チャート](/data-exploration/chart/map-chart)

緯度経度やジオハッシュ等のデータを元に地図上にデータを表示します。

| <picture><source srcset="/files/1RBHiExehOFeyVZQNTSc" media="(prefers-color-scheme: dark)"><img src="/files/7epHxnCpSugWliVLYGux" alt="Map Pin"></picture>     | <picture><source srcset="/files/yLioGikRVqOqWC8ANsdC" media="(prefers-color-scheme: dark)"><img src="/files/P8Q6fA3LdiR6QPKqazrD" alt="Map Bubble"></picture>   | <picture><source srcset="/files/n83dILkOW21xwpYQ2Rn7" media="(prefers-color-scheme: dark)"><img src="/files/5PgJJiPrtgL6p6O8HKlm" alt="Map Heatmap"></picture> |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <picture><source srcset="/files/QGzi9MzhurCyRa6kNkE3" media="(prefers-color-scheme: dark)"><img src="/files/IZdhQbZBQhPbYUQYUM1M" alt="Map Flow"></picture>    | <picture><source srcset="/files/W5v0fQfhfFdT9v5aXr58" media="(prefers-color-scheme: dark)"><img src="/files/OVIqVsFwa0l7LNJQ11gA" alt="Map Area"></picture>     | <picture><source srcset="/files/m08T6sAW1eIZkmDVE5br" media="(prefers-color-scheme: dark)"><img src="/files/bH28cQG64sUlPX8yPD7y" alt="Map Mesh"></picture>    |
| <picture><source srcset="/files/thSp99Mbxf36ZtCuADxi" media="(prefers-color-scheme: dark)"><img src="/files/4irbXV3mLVxrQ4k97vpm" alt="Map Polygon"></picture> | <picture><source srcset="/files/lCtF3QVUIurOtbTbvDwQ" media="(prefers-color-scheme: dark)"><img src="/files/aWNcpInfVGPGfLmUoWZf" alt="Map Polyline"></picture> |                                                                                                                                                                |

### [ワードクラウド](/data-exploration/chart/word-cloud)

ワードクラウド（タグクラウド）を表示します。

| <picture><source srcset="/files/QzxnX4zSRkGRLyuNlhIy" media="(prefers-color-scheme: dark)"><img src="/files/Q3QiAFEUBOqleaUWDISC" alt="Word Cloud"></picture> |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------- |


# チャート共通

チャート間で共通のコンセプトとTips

## チャート内でのデータ加工

### ディメンションとメトリクス <a href="#dimension-metric" id="dimension-metric"></a>

チャートのデータ集計では、**ディメンション**と**メトリクス**という概念があります。

* **ディメンション**: データをグループ化するための値。カテゴリや日付など、「何で分けるか」を決める
* **メトリクス**: 集計される数値。合計、平均、件数など、「何を測るか」を決める

SQLで表現すると、ディメンションは `GROUP BY` の対象となるカラム、メトリクスは `SUM()` や `COUNT()` などの集計関数で計算されるカラムに相当します。

### 日付フィールドの変換（切り捨て・抽出）

ディメンション（X軸、グループ化など）で日付型カラムを選択する際、日付を変換して使用できます。

* 設定方法
  * チャート編集画面「基本設定」において日付型カラムを選択し、「編集」を押下。変換モードと変換部分を選択する。
* 変換モード
  * 切り捨て：指定した単位で日付を切り捨てます
    * 例：2025-01-15 を MONTH で切り捨て → 2025-01-01
    * 用途：月別、週別、年別の集計
  * 抽出：日付から特定の部分のみを取り出します
    * 例：2025-01-15 から DAY を抽出 → 15
    * 用途：月内の日ごとパターン分析、時間帯分析（異なる月の同じ日は集約されます）

### インメモリ処理 <a href="#in-memory-processing" id="in-memory-processing"></a>

チャート用のデータ加工では、データソースのクエリの実行結果が1,000行以内で、カスタムSQLが指定されていない場合、新しいクエリを実行せずに同等の処理をユーザーのブラウザ上で行います。

この処理を「インメモリ処理」と呼び、チャートの「基本設定」>「インメモリ処理を無効化」から無効化することができます。

## Tips

### フレーム機能 <a href="#frame-feature" id="frame-feature"></a>

いくつかのチャートでは、特定のカラムをフレームとして設定することで、**そのカラムの値ごとにチャートを分割して表示**できます。フレームの表示方法は「フレームレイアウト」から「タイムライン」か「グリッド」を選択できます。

フレーム機能を使うことで、時系列の変化やカテゴリ間の比較を行いやすくなります。また、フレーム間で比較しやすいよう、Y軸の表示範囲・バブルサイズのスケール・ヒートマップの色スケールなどがデフォルトで全フレーム共通になっています。この動作は「詳細設定」>「フレーム」>「スケールを独立」から変更できます。

#### タイムラインレイアウト

タイムラインレイアウトでは、チャート下部にフレームコントロールが表示され、フレームの手動切替やアニメーション再生が可能になります。

| <picture><source srcset="/files/946p91RKOaqBM6OfELRO" media="(prefers-color-scheme: dark)"><img src="/files/yBEBM6Z6WTkUgbWUlzy1" alt="XY Frame Timeline"></picture> | <picture><source srcset="/files/2Yj4NRGteTHbGHdemsnq" media="(prefers-color-scheme: dark)"><img src="/files/7r2AtBkbaKbQjxcH8m0c" alt="Graph Frame Timeline"></picture> |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

#### グリッドレイアウト

グリッドレイアウトでは、全フレームをグリッド形式で表示します（**最大16件まで**）。

列数はデフォルトで自動調整され、なるべく正方形に近い配置になるよう決定されます（例：3件 → 2列×2行、5件 → 3列×2行）。列数は「詳細設定」>「フレーム」>「列数」から指定できます（チャート数が少ない場合は自動的に縮小されます）。

| <picture><source srcset="/files/tl44dpUqdUexqQjd6bHz" media="(prefers-color-scheme: dark)"><img src="/files/C1jj321h7PPQkMBvRGwo" alt="XY Frame Grid"></picture> | <picture><source srcset="/files/NsQZK5bmEaV45hzOZNih" media="(prefers-color-scheme: dark)"><img src="/files/pziifFWceOtEwcihK8oZ" alt="Radial Frame Grid"></picture> |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

#### フレーム機能に対応しているチャート

| チャート                                                     | 対応状況                     |
| -------------------------------------------------------- | ------------------------ |
| [XYチャート](/data-exploration/chart/xy-chart)               | 対応                       |
| [円形チャート](/data-exploration/chart/radial-chart)           | 対応                       |
| [XYZチャート](/data-exploration/chart/xyz-chart)             | 対応                       |
| [階層チャート](/data-exploration/chart/hierarchy-chart)        | 対応                       |
| [グラフチャート](/data-exploration/chart/graph-chart)           | 一部対応（「棒グラフ（ドリルダウン）」は非対応） |
| [ファンネルチャート](/data-exploration/chart/funnel-chart)        | 対応                       |
| [ウォーターフォールチャート](/data-exploration/chart/waterfall-chart) | 対応                       |
| [ワードクラウド](/data-exploration/chart/word-cloud)            | 対応                       |

### 値フォーマット

チャート内に表示される値やラベルのフォーマットは、デフォルトでは**アカウントの言語設定に応じて、最適化されます**。また、チャートの「詳細設定」からフォーマッタを変更することもできます。フォーマッタを変更している場合、言語設定に関わらず、フォーマッタの設定が優先されます。

#### 指定例

例えば、XYチャートの場合、以下のようにフォーマッタを指定することができます。

* X軸、Y軸のラベルフォーマット
  * 「詳細設定」>「X軸/Y軸」>「値フォーマット」から指定
* ツールチップ上のフォーマット
  * 「詳細設定」>「系列」>「(系列名)」>「値フォーマット」から指定
* 値ラベルのフォーマット（「値ラベル」を表示している場合）
  * 「詳細設定」>「系列」>「(系列名)」>「値ラベル」>「値ラベルフォーマット」から指定

#### 数値フォーマッタ

数値のフォーマッタは、[d3-format](https://d3js.org/d3-format)の書式を利用してフォーマットします。

例えば、以下のように指定することができます。

| 設定値    | 数値           | フォーマット結果 |
| ------ | ------------ | -------- |
| `.0f`  | `12345.6789` | `12346`  |
| `,.1r` | `12345.6789` | `10,000` |
| `-.1%` | `0.5`        | `50%`    |

また、d3-formatの書式を `{` と `}` で囲んで、前後にプレフィックスやサフィックスを指定することもできます。\
（これはd3-formatの書式ではなく、独自拡張の書式です。詳細は以下の設定例を確認ください）

| 設定値      | 数値        | フォーマット結果  |
| -------- | --------- | --------- |
| `{,d}円`  | `12345.6` | `12,346円` |
| `約{,d}%` | `50`      | `約50%`    |

#### 日付フォーマッタ

日付のフォーマッタは、[Day.js](https://day.js.org/docs/en/display/format)の書式を利用してフォーマットします。\
（数値フォーマッタと日付フォーマッタは、入力欄の左端にあるボタンで切り替え式になっている場合があります）

例えば、以下のように指定することができます。

| 設定値          | 日付           | フォーマット結果     |
| ------------ | ------------ | ------------ |
| `YYYY-MM-DD` | `2025-01-01` | `2025-01-01` |
| `YY/M/D`     | `2025-01-01` | `25/1/1`     |
| `YYYY年M月`    | `2025-01-01` | `2025年1月`    |

### 軸ラベルの表示幅を調整する

軸ラベルの最大幅(px) を設定することで、各軸のラベルの表示幅を制限できます。\
チャート設定画面「詳細設定」>「軸ラベルの最大幅(px)」に数値(例: `100`、`200`)を入力します。長いラベルテキストを省略表示したい場合に活用できます。


# ビッグナンバー

重要な指標を表示します

## 描画タイプ

ビッグナンバーには、テキストとゲージの2つの描画タイプがあります。

| <p>テキスト </p><p><picture><source srcset="/files/2VwH0ynqMTpq3D1XPBBV" media="(prefers-color-scheme: dark)"><img src="/files/uNuj5G3ugwzkYprB4HW0" alt="BigNumber Text"></picture></p> | <p>ゲージ </p><p><picture><source srcset="/files/d9VQFn9QqCXVNqQBa4A4" media="(prefers-color-scheme: dark)"><img src="/files/EZWclrN33PmaWq5A0Zay" alt="BigNumber Gauge"></picture></p> |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

## 仕様

### 集計の仕様

ビッグナンバーでは[ディメンションを指定せず、選択したメトリクスを集計](/data-exploration/chart/chart-common#dimension-metric)して1つの値として表示します。

| 項目   | 役割    | 補足             |
| ---- | ----- | -------------- |
| 指標   | メトリクス | 集計結果を1つの値として表示 |
| 補助指標 | メトリクス | ゲージ時は最大値として利用  |

#### 使用例

* 「全体の売上合計」をテキストで表示
  * 指標（メトリクス）: 売上の合計値
* 「達成率」をゲージで表示
  * 指標（メトリクス）: 実績の合計値
  * 補助指標（メトリクス）: 目標の合計値

### ゲージの仕様

* ゲージの達成率は「指標 ÷ 補助指標 × 100」で計算されます
* 補助指標が必須指定となり、数値型のデータを指定する必要があります

## Tips

### 条件付き書式

「詳細設定」から「条件付き書式」を設定することで、指標の値に応じてフォントカラーを変更することができます。 例えば、指標として達成率を指定して、達成率が80以下の時は危険色に、100以上の時は成功色に変更することができます。


# XYチャート

X軸の項目に対してY軸の値を集計して表示します

## 描画タイプ

XYチャートでは、以下の描画タイプと、それらを組み合わせた複合チャートを作成できます。

| <p>折れ線 </p><p><picture><source srcset="/files/ktmRar9T6XFAYp9s7ZlN" media="(prefers-color-scheme: dark)"><img src="/files/7ea5VftzAvJnuk8xcd0E" alt="XY Line"></picture></p>    | <p>棒 </p><p><picture><source srcset="/files/T8oTKBaCXC6UKgHALSKj" media="(prefers-color-scheme: dark)"><img src="/files/6AmsbtyjMmIbshuciZEG" alt="XY Bar"></picture></p>              | <p>積み上げ棒 </p><p><picture><source srcset="/files/BWhrnJe22KloAjXQwojZ" media="(prefers-color-scheme: dark)"><img src="/files/asV4mYL91xdPjA9HNCf7" alt="XY Stacked Bar"></picture></p>      |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| <p>面 </p><p><picture><source srcset="/files/BgncFQZMg3DtG7mZ3VAm" media="(prefers-color-scheme: dark)"><img src="/files/Lu78CL9rgSHQp1qBIC1i" alt="XY Area"></picture></p>      | <p>積み上げ面 </p><p><picture><source srcset="/files/nPQj4ByyfVFZISP9vghJ" media="(prefers-color-scheme: dark)"><img src="/files/HIv1ikWyDfhzlJc38BmF" alt="XY Stacked Area"></picture></p> | <p>100%積み上げ棒 </p><p><picture><source srcset="/files/Ly1LfskHbQ9MLXNolXrs" media="(prefers-color-scheme: dark)"><img src="/files/4ZTGedLQ3L8IGk5uvjRj" alt="XY Percent Bar"></picture></p>  |
| <p>散布図 </p><p><picture><source srcset="/files/vH4O755ClE3Dd9Ai6yye" media="(prefers-color-scheme: dark)"><img src="/files/GuT0G3vKmyC2Pt24KEaf" alt="XY Scatter"></picture></p> | <p>バブル </p><p><picture><source srcset="/files/4F0xfb3f7uAupInFaiBx" media="(prefers-color-scheme: dark)"><img src="/files/DKjgAMXvk406gKnTNSu8" alt="XY Bubble"></picture></p>         | <p>100%積み上げ面 </p><p><picture><source srcset="/files/s0Q5MRtkIXDuMcfU3lPw" media="(prefers-color-scheme: dark)"><img src="/files/lb10uSfI8LFWmYFrtGW9" alt="XY Percent Area"></picture></p> |

## 仕様

### 集計の仕様 <a href="#xy-xyz-diff" id="xy-xyz-diff"></a>

XYチャートでは、[X軸がディメンション、Y軸がメトリクス](/data-exploration/chart/chart-common#dimension-metric)となり、X軸ごとに集計されたY軸の値が系列として描画されます。（[XYZチャート](/data-exploration/chart/xyz-chart)では、X軸とY軸がディメンション、Z軸がメトリクスとなり、X軸とY軸の組み合わせごとにZ軸の値が集計される点が異なります）

| 項目     | 役割      | 補足             |
| ------ | ------- | -------------- |
| X軸     | ディメンション | 集計の単位（Xごとに集計）  |
| Y軸     | メトリクス   | メトリクスごとに系列が増える |
| グループ化  | ディメンション | 値ごとに系列が分割される   |
| バブルサイズ | メトリクス   | バブル描画時のみ指定     |

#### 使用例

* 「月別の売上合計」を折れ線で表示
  * X軸（ディメンション）: 月
  * Y軸（メトリクス）: 売上の合計値
* 「商品カテゴリごとの売上合計」を棒グラフで表示
  * X軸（ディメンション）: 商品カテゴリ
  * Y軸（メトリクス）: 売上の合計値

### X軸の仕様 <a href="#x-axis" id="x-axis"></a>

XYチャートでは、**X軸のデータ型**と**描画タイプの構成**でX軸の種類が決まります。

| X軸のデータ型 | 描画タイプの構成      | X軸の分類 |
| ------- | ------------- | ----- |
| 日付・日時型  | すべて           | 日時軸   |
| 数値型     | 散布図・バブル・折れ線のみ | 数値軸   |
| 数値型     | 棒・面・積み上げを含む   | カテゴリ軸 |
| 上記以外    | すべて           | カテゴリ軸 |

#### カテゴリ軸 <a href="#axis-category" id="axis-category"></a>

カテゴリ軸では、指定された値が数値型や日付・日時型であっても、離散的な値として等間隔に描画されます。

**軸の上限や下限の指定**

カテゴリ軸で軸の上限や下限を指定した場合、指定された値はデータの並び順のインデックス（0番目、1番目、2番目...）として扱われます。

| インデックス | X軸の値  |
| ------ | ----- |
| 0番目    | `1`   |
| 1番目    | `10`  |
| 2番目    | `20`  |
| 3番目    | `30`  |
| ...    | ...   |
| 10番目   | `100` |

この場合、軸の上限を `10` に設定すると、10番目のデータまで表示されるため、X軸の値が `100` まで表示されます。

#### 日時軸 <a href="#axis-time" id="axis-time"></a>

日時軸では、指定された日付・日時型のデータが連続的な時系列として描画されます。

* 軸のラベルは、指定された日付・日時のデータを元に動的に決定されます
* タイムゾーン付きの日時型のデータを指定した場合、ブラウザで指定されたタイムゾーンに変換して描画されます
  * 軸のラベルはブラウザで指定されたタイムゾーンに基づいて表示されるため、ブラウザ側のタイムゾーンとデータのタイムゾーンが一致しない場合、軸ラベルとデータラベルがズレて描画されます
  * タイムゾーンの無い日時型に変換することで、ブラウザ側のタイムゾーンの影響を受けないようにすることも可能です

#### 数値軸 <a href="#axis-value" id="axis-value"></a>

数値軸では、指定された数値型のデータが連続的な数値として描画されます。

## Tips

### 系列の複数指定 <a href="#multiple-views" id="multiple-views"></a>

複数の系列を設定すると、系列の設定内に「系列独自のY軸を設定」という項目が表示されます。この項目をオンにすると、対象の系列のY軸スケールが独立し、右側に描画されます。

独立したY軸のラベル等の設定は、「詳細設定」＞「独立軸」で行えます。

| <picture><source srcset="/files/5Oivv3918FNM94ZptJAK" media="(prefers-color-scheme: dark)"><img src="/files/4e8hYoFWa5RZYrTJUcmM" alt="XY Reference Line"></picture> |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

複数の系列を設定すると、「系列ごとに分割表示」という項目が、「系列」の設定項目の下に表示されます。この項目をオンにすると、各系列のY軸スケールが独立し、系列ごとに縦に並べて描画されます。

「系列ごとに分割表示」を有効にすると[フレーム機能](#frame-feature)は無効化されます。また、上記の「系列独自のY軸を設定」の項目が非表示になり、すべての系列が独立軸として扱われます。 系列ごとのY軸の設定は、「詳細設定」＞「独立軸」で行えます。

| <picture><source srcset="/files/4eBUlnmhYEJDHSgp3LZU" media="(prefers-color-scheme: dark)"><img src="/files/J2OH8mJsZgYNSvkVUD7M" alt="XY Reference Line"></picture> |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

### フレーム機能 <a href="#frame-feature" id="frame-feature"></a>

XYチャートはフレーム機能に対応しています。詳細は[フレーム機能](/data-exploration/chart/chart-common#frame-feature)を参照ください。

### 基準線 <a href="#reference-line" id="reference-line"></a>

XYチャートおよびXYZチャートでは、X軸とY軸に基準線を追加できます。目標値や許容範囲、危険ゾーンなど、チャートに目安となるラインや領域を表示することで、データの評価を視覚的に支援します。\
Y軸の基準線は横向き、X軸の基準線は縦向きに表示されます。

| <picture><source srcset="/files/zXNNUc4XMGNe2LisRkqp" media="(prefers-color-scheme: dark)"><img src="/files/Sf2WkQJeyDjZ4IzlULnq" alt="XY Reference Line"></picture> |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

* 設定方法
  * チャート編集画面「詳細設定」において、基準線を表示したい軸を選択し「基準線」＞「追加」を押下。表示したい基準線のタイプと値を入力します。
* できること
  * ライン：特定の値に破線を表示（例：売上目標、閾値、特定日付のマーカー）
  * バンド（範囲）：特定の範囲を半透明の帯で表示（例：許容範囲、危険ゾーン、注意期間）
  * 色・ラベル設定：成功（緑）、警告（黄）、危険（赤）から色を選択し、必要に応じてラベルを付与

### トレンド <a href="#trend" id="trend"></a>

XYチャートおよびXYZチャートでは、系列のトレンドライン（回帰直線や移動平均など）を表示できます。トレンドラインは元の系列とは別の系列として追加され、データの傾向を視覚的に把握するのに役立ちます。

| <picture><source srcset="/files/Np8pn8Z77UHccF2FRqHg" media="(prefers-color-scheme: dark)"><img src="/files/ieMmVeDzAjimJ8fWHujM" alt="XYZ Trend"></picture> |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------ |

* 設定方法
  * チャート編集画面「詳細設定」において「系列」＞「トレンド」＞「表示」を押下、表示したいトレンドの種類を選択。
  * トレンドラインは破線で表示され、移動平均以外のトレンドタイプでは方程式とR²（決定係数）がチャート上に表示されます。（決定係数は非表示にできます）

#### トレンドタイプ

| トレンドタイプ | 説明                            | 追加設定        |
| ------- | ----------------------------- | ----------- |
| 線形      | 線形回帰（y = mx + c）を表示します        | なし          |
| 多項式     | 多項式回帰を表示します                   | 次数を2〜5で指定   |
| 移動平均    | 移動平均を表示します                    | ウィンドウサイズを指定 |
| 指数      | 指数関数回帰（y = ae^(bx)）を表示します     | なし          |
| 対数      | 対数関数回帰（y = a + b ln(x)）を表示します | なし          |
| 累乗      | 累乗関数回帰（y = ax^b）を表示します        | なし          |

※データ件数が少ない場合や、指定したトレンドタイプの適用に失敗した場合は表示されません

### 統計 <a href="#statistics" id="statistics"></a>

XYチャートおよびXYZチャートでは、系列の統計値（平均値、中央値、最大値、最小値）を破線で表示することができます。

| <picture><source srcset="/files/3y65dFRSRaFEqC8Lllaw" media="(prefers-color-scheme: dark)"><img src="/files/8erULSMJRhLbtsQIt4te" alt="XY Statistics"></picture> |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |

* 設定方法
  * チャート編集画面「詳細設定」において「系列」＞「統計」＞「表示」を押下、表示したい統計値を選択。
  * 破線には統計タイプとその値がラベルとして表示されます。

#### トレンドとの違い

| 特徴          | 統計                  | トレンド               |
| ----------- | ------------------- | ------------------ |
| 表示形式        | 同じ系列として表示           | 別の系列（トレンドライン）として追加 |
| チャートのズーム時   | 表示されている範囲のデータのみで再計算 | 再計算されない（常に全データ基準）  |
| 積み上げグラフでの表示 | 積み上げっぽい差動になる        | 積み上げにならない          |


# 円形チャート

構成比や項目間の比較を可視化します

## 描画タイプ

円形チャートでは、以下の描画タイプが選択できます。

| <p>円グラフ </p><p><picture><source srcset="/files/1D4vOvlvm1hK5U5wPQX9" media="(prefers-color-scheme: dark)"><img src="/files/O99atc6pCHFd136y7nEj" alt="Radial Pie"></picture></p> | <p>ドーナツチャート </p><p><picture><source srcset="/files/U2Y5FIZ9mt4a774mTOsJ" media="(prefers-color-scheme: dark)"><img src="/files/vg1PDh6jd0nWbF0sg4gV" alt="Radial Donut"></picture></p> | <p>レーダーチャート </p><p><picture><source srcset="/files/2loNTEzg4uyuk4YBWtnS" media="(prefers-color-scheme: dark)"><img src="/files/A7J7JBYlS48Vf0cif6zy" alt="Radial Radar"></picture></p> |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

## 仕様

### 集計の仕様

円形チャートでは、[ラベル（ディメンション）ごとに値（メトリクス）を集計](/data-exploration/chart/chart-common#dimension-metric)して表示します。

| 項目    | 役割      | 補足                       |
| ----- | ------- | ------------------------ |
| ラベル   | ディメンション | 項目名（セグメント）になります          |
| 値     | メトリクス   | ラベルごとに集計されます             |
| グループ化 | ディメンション | 値ごとに系列が分割される（レーダーチャートのみ） |

#### 使用例

* 「商品カテゴリごとの売上合計」を円グラフで表示
  * ラベル（ディメンション）: 商品カテゴリ
  * 値（メトリクス）: 売上の合計値
* 「評価項目別の顧客満足度を部門別に比較」をレーダーチャートで表示
  * ラベル（ディメンション）: 評価項目
  * 値（メトリクス）: 顧客満足度の平均値
  * グループ化（ディメンション）: 部門

### 描画タイプごとの仕様

* 円グラフ・ドーナツチャートは「ラベル × 値」の1系列で描画されます
* レーダーチャートはラベルを軸として、グループ化の値ごとに系列が分割されます

## Tips

### フレーム機能

円形チャートはフレーム機能に対応しています。詳細は[フレーム機能](/data-exploration/chart/chart-common#frame-feature)を参照ください。


# XYZチャート

X軸とY軸の項目に対してZ軸の値を集計して表示します

## 描画タイプ

XYZチャートには、以下の描画タイプがあります。

| <p>散布図 </p><p><picture><source srcset="/files/4TI5QQefz553TUlpEn3Q" media="(prefers-color-scheme: dark)"><img src="/files/dInhJtmryVbPTtXHNzx6" alt="XYZ Scatter"></picture></p> | <p>バブル </p><p><picture><source srcset="/files/IalhyKtE4iI3xBb5zdcg" media="(prefers-color-scheme: dark)"><img src="/files/Q2X4wR3PiXCPdvl6zWQB" alt="XYZ Bubble"></picture></p> | <p>ヒートマップ </p><p><picture><source srcset="/files/cWTpnV7Hw5k0JQqpwW2j" media="(prefers-color-scheme: dark)"><img src="/files/VOsb0eKUVyj9ACWwmih0" alt="XYZ Heatmap"></picture></p> |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

## 仕様

### 集計の仕様

XYZチャートでは、[X軸とY軸がディメンション、Z軸がメトリクス](/data-exploration/chart/chart-common#dimension-metric)となり、X軸とY軸の組み合わせごとにZ軸の値が集計されます。（[XYチャート](/data-exploration/chart/xy-chart)では、X軸がディメンション、Y軸がメトリクスとなり、X軸ごとにY軸の値が集計される点が異なります）

| 項目    | 役割      | 補足               |
| ----- | ------- | ---------------- |
| X軸    | ディメンション | Xの値が軸になります       |
| Y軸    | ディメンション | Yの値が軸になります       |
| Z軸    | メトリクス   | バブル・ヒートマップで指定    |
| グループ化 | ディメンション | 散布図・バブルのみ（系列が分割） |

#### 使用例

* 「商品カテゴリ × 地域ごとの売上合計」をヒートマップで表示
  * X軸（ディメンション）: 商品カテゴリ
  * Y軸（ディメンション）: 地域
  * Z軸（メトリクス）: 売上の合計値
* 「広告費と売上の関係」をバブルで表示
  * X軸（ディメンション）: 広告費
  * Y軸（ディメンション）: 売上
  * Z軸（メトリクス）: 利益

### X軸の仕様

XYZチャートでは描画タイプによってX軸・Y軸の扱いが変わります。

* ヒートマップではX軸・Y軸ともにカテゴリ軸になります
* 散布図・バブルではX軸はデータ型に応じてカテゴリ/日時/数値のいずれか、Y軸は数値軸になります

各軸の挙動（カテゴリ軸・日時軸・数値軸の表示ルール）はXYチャートの [カテゴリ軸、日時軸、数値軸](/data-exploration/chart/xy-chart#x-axis) を参照ください。

## Tips

### フレーム機能

XYZチャートはフレーム機能に対応しています。詳細は[フレーム機能](/data-exploration/chart/chart-common#frame-feature)を参照ください。

### 基準線

XYZチャートでも基準線を表示できます。詳細はXYチャートの[基準線](/data-exploration/chart/xy-chart#reference-line)を参照ください。

### トレンド

XYZチャートでもトレンドを表示できます。詳細はXYチャートの[トレンド](/data-exploration/chart/xy-chart#trend)を参照ください。

### 統計

XYZチャートでも統計を表示できます。詳細はXYチャートの[統計](/data-exploration/chart/xy-chart#statistics)を参照ください。


# 階層チャート

階層構造を持つデータを可視化します

## 描画タイプ

階層チャートでは、以下の描画タイプが選択できます。

| <p>ツリー </p><p><picture><source srcset="/files/xl1ACE4sVRkEtPJIWtms" media="(prefers-color-scheme: dark)"><img src="/files/E3linHIMapFBQFeTVDCw" alt="Hierarchy Tree"></picture></p>         | <p>ツリーマップ </p><p><picture><source srcset="/files/BT5iYWwOeLSXFfcc22cy" media="(prefers-color-scheme: dark)"><img src="/files/75UAnEB9eAtwQJMwvuB9" alt="Hierarchy Treemap"></picture></p> | <p>サンバースト </p><p><picture><source srcset="/files/Q1gbbH3Snlv9iLq9xoeI" media="(prefers-color-scheme: dark)"><img src="/files/zxRg3zqyREYE3wEfHpFN" alt="Hierarchy Sunburst"></picture></p> |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| <p>棒グラフ（ドリルダウン） </p><p><picture><source srcset="/files/w5m0pIovNs6zimboL1uL" media="(prefers-color-scheme: dark)"><img src="/files/AB67G3dH0pfkzfZgr4S8" alt="Hierarchy Bar"></picture></p> |                                                                                                                                                                                           |                                                                                                                                                                                            |

## 仕様

### 集計の仕様

階層チャートでは、[階層（ディメンション）ごとに値（メトリクス）を集計](/data-exploration/chart/chart-common#dimension-metric)して階層構造を描画します。

| 項目 | 役割      | 補足                               |
| -- | ------- | -------------------------------- |
| 階層 | ディメンション | 上位から下位へ順番に指定（例：地域 → 都道府県 → 市区町村） |
| 値  | メトリクス   | 指定した場合は重みとして使われる                 |

#### 使用例

* 「地域 → 都道府県 → 市区町村の売上構成」をサンバーストで表示
  * 階層（ディメンション）: 地域、都道府県、市区町村
  * 値（メトリクス）: 売上の合計値
* 「組織階層ごとの件数」をツリーで表示
  * 階層（ディメンション）: 事業部、課、チーム
  * 値（メトリクス）: なし（行数で集計）

### 描画タイプごとの仕様

* ツリー／ツリーマップ／サンバーストは階層構造をそのまま描画します
* 棒グラフ（ドリルダウン）は最上位階層から表示し、要素のクリックで次階層へ遷移します
  * 2階層以上を指定し、描画タイプを「棒グラフ（ドリルダウン）」に設定します

## Tips

### フレーム機能

階層チャート（ツリー、ツリーマップ、サンバースト）はフレーム機能に対応しています。詳細は[フレーム機能](/data-exploration/chart/chart-common#frame-feature)を参照ください。


# グラフチャート

項目間の関係性や遷移を可視化します

## 描画タイプ

グラフチャートでは、以下の描画タイプが選択できます。

| <p>グラフ </p><p><picture><source srcset="/files/qUtc8t9mEKcmfP68Ke1o" media="(prefers-color-scheme: dark)"><img src="/files/5nplSobj4d3hj6vV8IiW" alt="Graph Chart"></picture></p> | <p>サンキー </p><p><picture><source srcset="/files/Cqmn7NBYeIVwahspdiV3" media="(prefers-color-scheme: dark)"><img src="/files/2WkK8VNZH1k2ACpOrpyo" alt="Sankey Diagram"></picture></p> |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

## 仕様

### 集計の仕様

グラフチャートでは、[ソースとターゲット（ディメンション）の組み合わせに対して重み（メトリクス）を集計](/data-exploration/chart/chart-common#dimension-metric)して、ノード間の関係を描画します。

| 項目    | 役割      | 補足                |
| ----- | ------- | ----------------- |
| ソース   | ディメンション | 接続元のノード           |
| ターゲット | ディメンション | 接続先のノード           |
| 重み    | メトリクス   | エッジの太さやノードのサイズに反映 |

#### 使用例

* 「ページ遷移数」をサンキーで表示
  * ソース（ディメンション）: 遷移元ページ
  * ターゲット（ディメンション）: 遷移先ページ
  * 重み（メトリクス）: 遷移回数の合計値
* 「SNSのユーザ間のメンション関係」をグラフで表示
  * ソース（ディメンション）: メンション元ユーザ
  * ターゲット（ディメンション）: メンション先ユーザ
  * 重み（メトリクス）: メンション回数の合計値

### 描画タイプごとの仕様

#### グラフ

* 有向／無向の切り替え
  * 無向の場合は A→B と B→A が統合されます
* フレーム機能
  * 指定したカラトを分割ムの値でチャーし、スライダーで切り替えることができます。時系列データの変化やカテゴリ別の比較に便利です。
* ヒートマップ表示
  * ノードの重みに応じて色を変更し、重要度を視覚的に表現できます。

#### サンキー図

* 流れの向きが視覚的に分かるように描画されます

## Tips

### フレーム機能

グラフチャートはフレーム機能に対応しています。詳細は[フレーム機能](/data-exploration/chart/chart-common#frame-feature)を参照ください。


# ファンネルチャート

段階的なプロセスの変化を可視化します

ファンネルチャートを描画します。

| <picture><source srcset="/files/8iLYqpkgK1XC8CzRPZuL" media="(prefers-color-scheme: dark)"><img src="/files/0KJKVRQ6fB4VV7SIetnt" alt="Funnel"></picture> |
| --------------------------------------------------------------------------------------------------------------------------------------------------------- |

## 仕様

### 集計の仕様

ファンネルチャートでは、[ラベル（ディメンション）ごとに値（メトリクス）を集計](/data-exploration/chart/chart-common#dimension-metric)して段階的に表示します。

| 項目  | 役割      | 補足         |
| --- | ------- | ---------- |
| ラベル | ディメンション | ファネルの各段階名  |
| 値   | メトリクス   | 各段階の値として表示 |

#### 使用例

* 「訪問 → 会員登録 → カート追加 → 購入 の件数」をファンネルで表示
  * ラベル（ディメンション）: 各段階の名前
  * 値（メトリクス）: 件数の合計値

### 並び順の仕様

* ソートが「ラベル順」の場合、並び替えは行わず先頭の値を基準に割合を計算します
* ソートが「値の昇順／降順」の場合、最大値を基準に割合を計算します

## Tips

### フレーム機能

ファンネルチャートはフレーム機能に対応しています。詳細は[フレーム機能](/data-exploration/chart/chart-common#frame-feature)を参照ください。


# ウォーターフォールチャート

項目の増減を積み上げて表示します

ウォーターフォールチャートを描画します。

| <picture><source srcset="/files/mMPBVrP0b6ewfg0joQeE" media="(prefers-color-scheme: dark)"><img src="/files/618sOtti7U7DXPwpNSec" alt="Waterfall"></picture> |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------ |

## 仕様

### 集計の仕様

ウォーターフォールチャートでは、[ラベル（ディメンション）ごとに値（メトリクス）を集計](/data-exploration/chart/chart-common#dimension-metric)して積み上げて表示します。

| 項目  | 役割      | 補足             |
| --- | ------- | -------------- |
| ラベル | ディメンション | ウォーターフォールの各項目名 |
| 値   | メトリクス   | 各項目の増減値として表示   |

#### 使用例

* 「期首残高 → 収益 → 費用 → その他」の増減をウォーターフォールで表示（損益やキャッシュフローの内訳など）
  * ラベル（ディメンション）: 期首、収益、費用、その他、期末 など各項目名
  * 値（メトリクス）: 各項目の金額（増減値）

## Tips

### フレーム機能

ウォーターフォールチャートはフレーム機能に対応しています。詳細は[フレーム機能](/data-exploration/chart/chart-common#frame-feature)を参照ください。


# テーブルチャート

テーブル型のチャートを作成します

## 描画タイプ

テーブルチャートでは、以下の描画タイプが選択できます。

| <p>ローテーブル </p><p><picture><source srcset="/files/0q3RCR2xy7GGLxBYJea9" media="(prefers-color-scheme: dark)"><img src="/files/ikNyBqstPVdnhFlbYYjd" alt="Table Raw"></picture></p> | <p>集計テーブル </p><p><picture><source srcset="/files/xrfZtKGyM4QO5etA8nQk" media="(prefers-color-scheme: dark)"><img src="/files/N9otS0YMTZxRUTquAURf" alt="Table Aggregated"></picture></p> |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

## 仕様

### ソースタイプ

テーブルチャートは2種類のソースタイプを持ち、選択したソースタイプによりデータの集計・表示の仕様が異なります。

| ソースタイプ        | 説明           | カラムの役割                                                                           |
| ------------- | ------------ | -------------------------------------------------------------------------------- |
| ローデータ（ローテーブル） | 取得した行をそのまま表示 | 表示対象のカラムの選択                                                                      |
| 集計データ（集計テーブル） | グループ化して集計    | [グループ化（ディメンション）、値（メトリクス）](/data-exploration/chart/chart-common#dimension-metric) |

## Tips

### 画像表示

カラムの値で画像URLを指定して、「詳細設定」>「カラム設定」>「画像URLプレビュー」から「有効化」をオンにすることで、カラムで指定したURLの画像をテーブルチャート内で表示できます。

| <picture><source srcset="/files/QnSNn1a0rcjEMIPKYviJ" media="(prefers-color-scheme: dark)"><img src="/files/FeVA1j0PgrqJtqhICORj" alt="Table Image Preview"></picture> |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

### リンク表示

カラムの値でURLを指定して、「詳細設定」>「カラム設定」>「リンクURLを有効化」をオンにすることで、カラムで指定したURLを新しいタブで開くリンクをテーブルチャート内で表示できます。

| <picture><source srcset="/files/51HRRQ3GIHx14N4Z7iGd" media="(prefers-color-scheme: dark)"><img src="/files/cakbIz16TdaiFmJlFFlc" alt="Table Link URL"></picture> |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |

#### レポートへのパラメータ付きリンクを作成する

SQLクエリで動的にURLを生成することで、テーブルの各行のデータをパラメータとして別のレポートページに渡すことができます。

1. レポートの作成とURLの取得
   * 遷移先のレポートにパラメータを設定し、ブラウザのアドレスバーからURLを取得します。
     * `URLの例：https://app.codatum.com/workspace/{workspace_id}/report/{report_id}/{page_id}`
   * パラメータIDの確認方法： レポート内のパラメータウィジェットのIDをメモしておきます（例：`68f369edf5e6f69036b8872d`）　　
2. SQLでURL列を作成
   * CONCAT関数を使って、各行のデータをパラメータに含むURLを生成しchartに挿入します。
   * 単一パラメータの例（国名）:

     ```sql
     CONCAT(
       'https://app.codatum.com/workspace/{workspace_id}/report/{report_id}/{page_id}?cdm.params.{パラメータID}=',
       country  --- パラメータに渡したい列名
     ) AS link
     ```
3. テーブルチャートでリンクを有効化
   * テーブルチャート設定 → カラム設定 → 該当列 → 「リンクURLを有効化」をオンにします。

補足

* countryの部分は、パラメータに渡したいデータベースの列名に置き換えてください
* パラメータウィジェットの現在値をSQL内で参照することはできません（固定値または列の値のみ）
* ユーザーがセルをクリックすると、新しいタブでレポートが開きます
* パラメータの設定方法詳細は[こちら](/data-exploration/parameter-overview/set-parameters-via-url)からご確認ください


# ピボットテーブル

二次元のクロス集計テーブルを作成します

行/列でデータを集計し、ピボットテーブルとして表示します。

| <picture><source srcset="/files/SQK9OUJk3e4kC6ZBrcmE" media="(prefers-color-scheme: dark)"><img src="/files/oFQwWQljHZbMxJdhbsVS" alt="Pivot Table"></picture> |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------- |

## 仕様

### フィールドの役割

ピボットテーブルは、[行・列をディメンション、値をメトリクスとして集計](/data-exploration/chart/chart-common#dimension-metric)して、集計結果をテーブル形式で表示します。

| 項目 | 役割      | 補足             |
| -- | ------- | -------------- |
| 行  | ディメンション | 1つ以上           |
| 列  | ディメンション | 任意             |
| 値  | メトリクス   | 数値/文字列メトリクスに対応 |

## Tips

### ドリルダウン

ピボットテーブルでは行を階層的に表示し、折りたたむことができます

設定方法

1. 行フィールドを複数設定
   * チャート設定の「行」に、大カテゴリ・小カテゴリなど2つ以上のフィールドを設定します。
   * 例: 都道府県（大カテゴリ）→ 市区町村（小カテゴリ）
2. ツリー表示に切り替え
   * 「詳細設定」→「レイアウト」→「デフォルトの階層タイプ」で「ツリー」を選択します。
     * グリッド: 従来の表形式
     * ツリー: 階層構造で表示、開閉アイコンで展開・折りたたみ可能
3. 初期状態を折りたたみに設定（オプション）
   * 「折りたたんで表示」にチェックを入れると、初期表示時に全階層が折りたたまれた状態になります。

補足

* 行フィールドが2つ以上の場合のみ設定可能です
* レポート閲覧者は自由に展開・折りたたみできます

### 加工方法による違い

ピボットテーブルでは、[インメモリ処理](/data-exploration/chart/chart-common#in-memory-processing)が行われた場合と、クエリによる加工処理が行われた場合で、表示される結果が異なります。

* インメモリ処理の場合
  * 行や列の数に制限がなく、集計されたすべてのデータを表示できます
* クエリによる加工処理の場合
  * 行と列はそれぞれ30個までに制限されます
    * 30個を超える場合、 `Others` という行または列にまとめられます


# テキストパネル

選択したカラムの最初の値を表示します

## 描画タイプ

テキストパネルでは、選択されたカラムの最初の値を指定された形式で表示します。 クエリの実行結果として、文章を表示したい場合に利用することを想定しています。

また、生成AIとの併用によって、ダッシュボードへの動的な[AI生成サマリー](/best-practices/ai-generated-summary)の表示にも利用できます。

| <p>マークダウン </p><p><picture><source srcset="/files/5UZLCbYU6tBtiGAvMCC7" media="(prefers-color-scheme: dark)"><img src="/files/lY7WetkCTJpccH7abOVl" alt="Text Panel Markdown"></picture></p> | <p>テキスト </p><p><picture><source srcset="/files/k1RDwzsiDvzxYXVgsSLX" media="(prefers-color-scheme: dark)"><img src="/files/0m8i4DPBdCFWx0VYYySQ" alt="Text Panel Raw"></picture></p> |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

## 仕様

### 集計の仕様

テキストパネルではデータの集計を行わず、選択されたカラムの最初の値を表示します。

### 描画タイプごとの仕様

「詳細設定」の「レンダリングモード」で描画タイプを選択することができます。

* マークダウン: 出力されたテキストをマークダウン形式として描画します
* テキスト: 出力されたテキストをそのまま表示します


# 地図チャート

緯度・経度、ジオハッシュ、ジオコード、GeoJSONを利用して地図上にデータを表示します

## データ形式

地図チャートでは以下のデータ形式を地図上に表示することができます。

### 緯度・経度

指定された緯度・経度の位置にオブジェクトを描画します。 緯度・経度はそれぞれ数値型のカラムを指定します。 以下の描画タイプで利用できます。

| ピン <picture><source srcset="/files/1RBHiExehOFeyVZQNTSc" media="(prefers-color-scheme: dark)"><img src="/files/7epHxnCpSugWliVLYGux" alt="Map Pin"></picture>         | バブル <picture><source srcset="/files/yLioGikRVqOqWC8ANsdC" media="(prefers-color-scheme: dark)"><img src="/files/P8Q6fA3LdiR6QPKqazrD" alt="Map Bubble"></picture> |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ヒートマップ <picture><source srcset="/files/n83dILkOW21xwpYQ2Rn7" media="(prefers-color-scheme: dark)"><img src="/files/5PgJJiPrtgL6p6O8HKlm" alt="Map Heatmap"></picture> | フロー\* <picture><source srcset="/files/QGzi9MzhurCyRa6kNkE3" media="(prefers-color-scheme: dark)"><img src="/files/IZdhQbZBQhPbYUQYUM1M" alt="Map Flow"></picture> |

\* フローでは2組（ソースとターゲット）の緯度・経度情報が必要になります。

### ジオハッシュ <a href="#geohash" id="geohash"></a>

[ジオハッシュ](https://ja.wikipedia.org/wiki/%E3%82%B8%E3%82%AA%E3%83%8F%E3%83%83%E3%82%B7%E3%83%A5)の形式で指定された位置にオブジェクトを描画します。

以下の描画タイプ（緯度・経度と同様）では、指定されたジオハッシュの中心点にオブジェクトを描画します。

* ピン
* バブル
* ヒートマップ
* フロー

以下の描画タイプでは、指定されたジオハッシュの領域を塗りつぶして描画します。 （指定するジオハッシュの精度によって、塗りつぶす領域の大きさが変化します）

| メッシュ <picture><source srcset="/files/m08T6sAW1eIZkmDVE5br" media="(prefers-color-scheme: dark)"><img src="/files/bH28cQG64sUlPX8yPD7y" alt="Map Mesh"></picture> |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |

#### ジオハッシュサンプル

以下にジオハッシュのサンプルを示します。

| ジオハッシュ   | 精度  | 位置の例   | 領域サイズ (約)     |
| -------- | --- | ------ | ------------- |
| xn       | 2文字 | 東京周辺   | 630km × 500km |
| xn7      | 3文字 | 東京都心部  | 78km × 78km   |
| xn76     | 4文字 | 東京駅エリア | 20km × 10km   |
| xn76u    | 5文字 | 東京駅周辺  | 2.4km × 2.4km |
| xn76ur   | 6文字 | 東京駅近辺  | 610m × 300m   |
| xn76urx  | 7文字 | 東京駅付近  | 76m × 76m     |
| xn76urxk | 8文字 | 東京駅周辺  | 19m × 9m      |

#### BigQuery の使用例

BigQuery では `ST_GEOHASH` 関数を使用して、緯度・経度のデータをジオハッシュに変換できます。 ジオハッシュに変換することで、緯度・経度を個別に扱うよりも効率的にエリア単位での集計やグルーピングが可能になります。

以下は、BigQuery の `ST_GEOHASH` 関数を使用して、緯度・経度のデータをジオハッシュに変換する例です。

```sql
SELECT
  ST_GEOHASH(ST_GEOGPOINT(longitude, latitude), 6) AS geohash,
  COUNT(*) AS station_count
FROM
  `bigquery-public-data.new_york_citibike.citibike_stations`
GROUP BY
  geohash
ORDER BY
  station_count DESC
```

### ジオコード <a href="#geocode" id="geocode"></a>

ジオコードに紐づく領域を塗りつぶして描画します。 以下の描画タイプで利用できます。

| エリア <picture><source srcset="/files/W5v0fQfhfFdT9v5aXr58" media="(prefers-color-scheme: dark)"><img src="/files/OVIqVsFwa0l7LNJQ11gA" alt="Map Area"></picture> |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------- |

ジオコードは、以下の形式の文字列で指定してください。

| 粒度              | ジオコードの形式                                                                                                                                                                                | ジオコードの例     |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| 国               | <p>2文字の国コード<br>(<a href="https://ja.wikipedia.org/wiki/ISO_3166-1">ISO3166-1</a>,大文字)</p>                                                                                               | JP          |
| 都道府県(日本のみ)      | <p>"JP-"+2桁の都道府県コード<br>(<a href="https://ja.wikipedia.org/wiki/%E5%85%A8%E5%9B%BD%E5%9C%B0%E6%96%B9%E5%85%AC%E5%85%B1%E5%9B%A3%E4%BD%93%E3%82%B3%E3%83%BC%E3%83%89">JIS X 0402</a>)</p> | JP-13       |
| 市区町村(日本のみ)      | <p>"JP-"+5桁の市区町村コード<br>(<a href="https://ja.wikipedia.org/wiki/%E5%85%A8%E5%9B%BD%E5%9C%B0%E6%96%B9%E5%85%AC%E5%85%B1%E5%9B%A3%E4%BD%93%E3%82%B3%E3%83%BC%E3%83%89">JIS X 0402</a>)</p> | JP-13101    |
| 郵便番号の上位2桁(日本のみ) | "JP-POST-"+郵便番号の上位2桁                                                                                                                                                                    | JP-POST-10  |
| 郵便番号の上位3桁(日本のみ) | "JP-POST-"+郵便番号の上位3桁                                                                                                                                                                    | JP-POST-100 |

塗りつぶしに使う地理空間データは、以下のデータを加工して軽量化したものです。

* 全世界の国境データ: [Natural Earth](https://www.naturalearthdata.com/)
* 日本国内の境界データ: [「国土数値情報（行政区画データ）」（国土交通省）](https://nlftp.mlit.go.jp/ksj/gml/datalist/KsjTmplt-N03-2025.html)
* 郵便番号の境界データ: [郵便番号境界データ（地図地理Sandbox）](https://hanishina.net/maps/yubindata.html)

なお、ジオコードの形式として有効であっても、上記データに含まれないジオコードは描画できません。

#### ジオコードサンプル

以下にジオコードのサンプルを示します。 指定可能なジオコードの一覧は[ジオコード一覧のCSVファイル](https://static.codatum.com/v/latest/public/geojson/codes.csv)を参照してください。

| ジオコード       | 名称        |
| ----------- | --------- |
| US          | アメリカ合衆国   |
| JP          | 日本        |
| JP-01       | 北海道       |
| JP-02       | 青森県       |
| JP-03       | 岩手県       |
| JP-01100    | 札幌市       |
| JP-01101    | 札幌市中央区    |
| JP-01102    | 札幌市北区     |
| JP-01103    | 札幌市東区     |
| JP-01202    | 函館市       |
| JP-01203    | 小樽市       |
| JP-01204    | 旭川市       |
| JP-POST-10  | 〒10X-XXXX |
| JP-POST-100 | 〒100-XXXX |

### GeoJSON <a href="#geojson" id="geojson"></a>

GeoJSON形式で指定されたジオメトリデータを地図上に描画します。 以下の描画タイプで利用できます。

| ポリゴン <picture><source srcset="/files/thSp99Mbxf36ZtCuADxi" media="(prefers-color-scheme: dark)"><img src="/files/4irbXV3mLVxrQ4k97vpm" alt="Map Polygon"></picture> | ポリライン <picture><source srcset="/files/lCtF3QVUIurOtbTbvDwQ" media="(prefers-color-scheme: dark)"><img src="/files/aWNcpInfVGPGfLmUoWZf" alt="Map Polyline"></picture> |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

以下のジオメトリ型のJSONを文字列型で指定してください。

* `Point`
* `LineString`
* `Polygon`
* `MultiPoint`
* `MultiLineString`
* `MultiPolygon`
* `GeometryCollection`

#### GeoJSONのサンプル

```json
{
  "type": "Polygon",
  "coordinates": [
    [
      [-73.9812, 40.7681],
      [-73.9581, 40.7681],
      [-73.9581, 40.8007],
      [-73.9812, 40.8007],
      [-73.9812, 40.7681]
    ]
  ]
}
```

#### BigQuery の使用例

BigQuery では `ST_ASGEOJSON` 関数を使用して、ジオメトリデータを GeoJSON 形式に変換できます。 以下は、`bigquery-public-data.geo_us_boundaries.counties` テーブルの `county_geom` カラムを GeoJSON 形式に変換する例です。

```sql
SELECT
  * EXCEPT (county_geom),
  ST_ASGEOJSON(county_geom) AS county_geom
FROM
  `bigquery-public-data.geo_us_boundaries.counties`
WHERE
  state_fips_code = '36'  -- New York
```

描画対象のジオメトリデータのサイズが大きい場合、クエリ実行結果のサイズ制限に抵触し、エラーになる場合があります。 その場合、`ST_SIMPLIFY` 関数を使用して、ジオメトリデータを簡略化してサイズを減らすことができます。 （巨大なジオメトリデータは、描画のパフォーマンスにも影響を与えるため、必要最低限のサイズに簡略化することをお勧めします）

```sql
SELECT
  * EXCEPT (county_geom),
  ST_ASGEOJSON(ST_SIMPLIFY(county_geom, 1000)) AS county_geom
FROM
  `bigquery-public-data.geo_us_boundaries.counties`
WHERE
  state_fips_code = '36'  -- New York
```

## 利用上の制限

地図チャートはWebGLを利用して地図を描画しているため、以下の制限があります。

* WebGLが利用できないブラウザでは描画できません
* WebGLのコンテキスト数の制限により、多数の地図チャートを同時に描画しようとすると、先に描画したチャートの表示が破棄される場合があります
  * 再描画を行えば再表示されますが、1ページあたりの地図チャートの数が増えすぎないように注意してください


# ワードクラウド

キーワードの出現頻度や重要度を視覚的に表示します

ワードクラウド（タグクラウド）を描画します。

| <picture><source srcset="/files/QzxnX4zSRkGRLyuNlhIy" media="(prefers-color-scheme: dark)"><img src="/files/Q3QiAFEUBOqleaUWDISC" alt="Word Cloud"></picture> |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------- |

## 仕様

### 集計の仕様

ワードクラウドでは、[ワード（ディメンション）ごとに値（メトリクス）を集計](/data-exploration/chart/chart-common#dimension-metric)して表示します。

| 項目  | 役割      | 補足            |
| --- | ------- | ------------- |
| ワード | ディメンション | ワードクラウドの各ワード  |
| 値   | メトリクス   | ワードの大きさを決定する値 |

#### 使用例

* コンテンツのタグをワードクラウドで表示
  * ワード（ディメンション）: タグ名
  * 値（メトリクス）: タグが付与されたコンテンツの数

## Tips

### ワードがすべて表示されない場合

ワードクラウドでは、値の大きい順にワードの描画を行い、**表示領域に収まらないワードは自動的に非表示になります**。そのため、値の小さいワードは表示されない場合があります。

ワードの数が多く、すべてのワードが表示されない場合は、「フォントサイズの範囲」や「ワードの間隔」の調整や、チャートの表示領域の調整を行ってください。

「ワードの自動縮小表示」を有効化することで、表示領域に収まらないワードのフォントサイズを自動調整することができますが、ワードの数が多い場合、フォントサイズの再計算処理によりチャートの動作が重くなることがあります。そのため、この機能はデフォルトで無効になっています。有効化する際はワード数にご注意ください。

### フレーム機能

ワードクラウドはフレーム機能に対応しています。詳細は[フレーム機能](/data-exploration/chart/chart-common#frame-feature)を参照ください。


# エクスプローラ

コーディング不要でデータのフィルタリング、抽出、集計、修正を簡単に行えるドラッグ＆ドロップとスプレッドシート風のUI。

<figure><img src="/files/oP6m1Q47LPAOxRIrBHWx" alt=""><figcaption></figcaption></figure>

エクスプローラを使用すると、データを表示しながらグラフィカルユーザーインターフェースを通じて一般的なデータ変換を実行できます。エクスプローラはノートブックやレポートのSQLブロックやチャートの実行結果に対して使用できます。

## 主な機能

* スプレッドシート風UIとドラッグ＆ドロップUI:
  * スプレッドシートと同様に、列ヘッダーからソート、フィルタ、値の選択ができます。
  * ドラッグ＆ドロップでフィールドの選択、フィルタの適用、データのソートができます。
* 集計:
  * ドラッグ＆ドロップで簡単な集計（グループ化）を実行できます。
* フィールド統計:
  * 列ヘッダーから統計情報を確認できます。
* チャートのリコメンド:
  * エクスプローラの操作結果をもとに、チャートの提案を行います。

## エクスプローラが利用可能な場所

エクスプローラは元のデータと直接やり取りするため、特定のコンテキストでのみ利用可能です。

* ノートブック (ドキュメントページ/グリッドページ)
* レポート
  * `レポートタイプ`で`インタラクティブレポート`を選択し、`エクスプローラを有効化`が選択されている場合
* 署名付き埋め込み
  * オプションで`エクスプローラを有効化`が選択されている場合

詳細については、以下のセクションを参照してください。

{% content-ref url="/pages/EZ1aZqo4Glz0nMWEeboK" %}
[共有方法](/sharing/sharing-overview)
{% endcontent-ref %}

## インメモリ処理

* エクスプローラでは、対象データが1000行以内でカスタムSQLが使われていない場合、新しいクエリを実行せずに同等の処理をユーザーのブラウザ上で行います。
* これらの処理は `インメモリ処理を無効化` をオンにすることで無効化できます。


# パラメータ

動的なノートブックとレポートを作成する

<figure><img src="/files/9fiO4WcdjjXQkhl46Ra1" alt=""><figcaption></figcaption></figure>

ノートブックでパラメータを使用することで、ノートブックやレポートを動的かつインタラクティブにすることができます。これにより、SQLに直接アクセスすることなくパラメータを通じて埋め込まれたSQLを制御し、必要に応じてカスタマイズされた出力を得ることができます。

## 主な機能

* 動的なノートブックとレポート:
  * ノートブックとレポートをダイナミックかつインタラクティブにします。
* [様々な種類のパラメータ](/data-exploration/parameter-overview/parameter-types):
  * 多様な入力ウィジェットとデータ型から選択できます。
* [エスケープ処理と動的な参照の生成](/data-exploration/parameter-overview/escape-and-dynamic-reference):
  * パラメータがSQL内のどのようなコンテキストで使用されるかに応じて、エスケープ処理が変わります。
* 2種類のスコープ:
  * ノートブック全体で使用するパラメータか、ページごとに使用するパラメータかを選択できます。
* パラメータの上書き:
  * SQLをチェインさせる際にパラメータを上書きすることで、きめ細かな制御が可能です。

## 使用方法

パラメータを作成して、ノートブック内のSQLブロックで`/param/{param_name}`と入力すると、パラメータへの参照をSQLブロック内に埋め込むことができます。

例えば、`param1`という名前の文字列パラメータを作成し、値として`val1`を入力した場合、以下のSQL：

```sql
SELECT {{param1}}
```

は以下のように変換されます：

```sql
SELECT 'val1'
```

## パラメータのスコープ

パラメータには次の2種類のスコープがあります。

* `ノートブック共通`
  * ノートブックのすべてのページで共有されるパラメータ
  * パラメータ定義はノートブック全体で共有されますが、値は各ページで保持されます
* `ページ固有`
  * 各ページに固有のパラメータ

複数のページから参照するSQLブロックで使うパラメータの場合は、`ノートブック共通`のパラメータを、そうでない場合は `ページ固有`のパラメータを使用してください。\
例えば、ドキュメントページで作成したチャートを、グリッドページで参照するような場合、チャートのデータソースとするSQLブロックでは `ノートブック共通` のパラメータを使用します。

## パラメータの上書き

<figure><img src="/files/Gg22i6zWsuiDANnqSrJl" alt=""><figcaption></figcaption></figure>

SQLをチェインさせる際に、パラメータの依存関係を切断したい場合があります。例えば：

* ページをまたいでSQLをチェインさせる際に、各ページで固有のパラメータを設定する。
* 同じベースSQLから派生した異なるSQLで異なるパラメータを使用する。

SQLブロックでSQLを参照している箇所にカーソルを合わせると表示されるポップアップで、パラメータを上書きできます。

## パラメータ値の同期

**ノートブックのパラメータ値と実行結果はユーザー間で同期されます**。ただし、ノートブックのバージョンやレポートを使用することで、パラメータ値と実行結果の変更がユーザー間で同期されず、値を変更したユーザーにのみ変更が反映されるようになります。

詳細については、[ノートブックバージョン](https://github.com/codatum/support-site-gitbook/blob/main/ja/data-exploration/parameter/notebook/version.md)を参照してください。

## レポート機能のノートブック共通パラメータ

設定したパラメータは、レポートのページ間で同期することができます。

レポート機能において同期設定を有効にすると、ノートブック共通のパラメータの値を変更したときに、任意のページ間で変更が同期されます。なお、ページ固有パラメータは連動しません。

詳細については、[レポート](/sharing/report)を参照してください。


# パラメータの種類

パラメータは、生成される入力フォームの種類と、そのデータ型によって、以下の種類があります。

## 1. テキスト入力 (`STRING`) <a href="#text-input" id="text-input"></a>

シンプルな文字列入力フィールドです。

* フォーマット:
  * SQLでは文字列としてエスケープされて展開されます。
  * 例：`'val1'`に変換されます
* 空の場合:
  * `''`

## 2. テキスト複数入力 (`STRING[]`) <a href="#text-multi-input" id="text-multi-input"></a>

複数の文字列を入力するフィールドです。

* フォーマット:
  * SQLでは,区切りの文字列としてエスケープされて展開されます。
  * 例：`'val1', 'val2'`に変換されます
* 空の場合:
  * `''`

## 3. テキスト選択 (`STRING`) <a href="#text-select" id="text-select"></a>

単一の文字列値を選択するドロップダウンです。

* ソースオプション:
  * 固定リストまたはテーブル値またはクエリ実行結果
* フォーマット:
  * SQLでは文字列としてエスケープされて展開されます。
* 空の場合:
  * `''`

## 4. テキスト複数選択 (`STRING[]`) <a href="#text-multi-select" id="text-multi-select"></a>

複数の文字列値を選択するドロップダウンです。

* ソースオプション:
  * 固定リストまたはテーブル値またはクエリ実行結果
* フォーマット:
  * SQLでは,区切りの文字列としてエスケープされて展開されます。
  * 例：`'val1', 'val2'`に変換されます
* 空の場合:
  * `''`

## 5. 数値入力 (`NUMBER`) <a href="#number-input" id="number-input"></a>

シンプルな数値入力フィールドです。

* オプション:
  * min, max, steps (間隔)
* 空の場合:
  * `0`

## 6. 数値選択 (`NUMBER`) <a href="#number-select" id="number-select"></a>

単一の数値を選択するドロップダウンです。

* ソースオプション:
  * 固定リストまたはテーブル値またはクエリ実行結果
* 空の場合:
  * `0`

## 7. 日付入力 (`DATE`) <a href="#date-input" id="date-input"></a>

シンプルな日付入力フィールドです。カレンダーからの選択または日付の入力が可能です。

* オプション:
  * `単位`:
    * 日, 週, 月, 年
  * `週の開始曜日`:
    * 日, 月, 火, 水, 木, 金, 土
  * `相対的な有効範囲`:
    * `今日から何日前まで`: この制限より前の日付は選択不可になります。例えば、'90'と入力すると、90日前より前の日付が選択不可になります。
    * `今日から何日後まで`: この制限より後の日付は選択不可になります。例えば、'0'と入力すると翌日以降の日付が選択不可に、'-1'と入力すると今日以降の日付が選択不可になります。
  * `絶対的な有効範囲`:
    * `下限日付`: 指定した日付より前の日付が選択不可になります。
    * `上限日付`: 指定した日付より後の日付が選択不可になります。
* フォーマット:
  * SQLでは`yyyy-MM-dd`形式で文字列として展開されます。
  * 例：`'2024-01-01'`に変換されます
* 空の場合:
  * `'1970-01-01'`
* デフォルト値を利用することで、[相対日付](/data-exploration/parameter-overview/relative-date-behavior)を設定することができます

## 8. 日付範囲 (`[DATE, DATE]`) <a href="#date-range" id="date-range"></a>

開始日と終了日をペアで指定します。

* オプション:
  * 日付入力（DATE）と同じ
* SQLでの参照構文:
  * 開始日：`{{param_name}}.StartDate`
  * 終了日：`{{param_name}}.EndDate`
* 空の場合:
  * 開始日、終了日ともに`'1970-01-01'`になります
* デフォルト値を利用することで、[相対日付](/data-exploration/parameter-overview/relative-date-behavior)を設定することができます

## 9. チェックボックス (`BOOLEAN`) <a href="#checkbox" id="checkbox"></a>

シンプルな真偽値のチェックボックスです。

* フォーマット:
  * SQLでは `true` または `false` として展開されます。


# 相対日付の利用方法

パラメータを使って最新の日付のデータにアクセスする方法

「日付入力」や「日付範囲」のパラメータにデフォルト値を設定することで、「今日」「昨日」「先週」などの相対日付をパラメータに簡単に設定することができるようになります。

## 相対日付を利用可能なパラメータ

* [日付入力](/data-exploration/parameter-overview/parameter-types#date-input)
* [日付範囲](/data-exploration/parameter-overview/parameter-types#date-range)

## 相対日付の設定方法

* パラメータの入力フォーム右上の3点アイコンをクリック
* `デフォルト値`の項目から、`相対日付`や`相対日付範囲`を選択して設定

## 相対日付が計算されるタイミング

パラメータの値をデフォルト値に変更するタイミングで、相対日付の計算が行われます。\
各機能ごとに、どのタイミングでパラメータの値がデフォルト値に変更されるかを以下に示します。

### ノートブック

* パラメータの入力フォームでユーザーが以下の操作を行った時
  * フォーム全体に対して`パラメータの値をデフォルト値にリセット`を行った時
  * パラメータ個別で`デフォルト値にリセット`を行った時

{% hint style="info" %}
ノートブックのパラメータの変更は、他のユーザーとリアルタイムに共有されるため、デフォルト値への変更はユーザーの明示的な操作が必要となります。 ノートブックを開いたタイミングで、相対日付の計算を行うことはできません。
{% endhint %}

### パブリックリンク

パラメータの変更はできないため、相対日付の機能は利用できません。

### レポート

* 以下の設定をすることで、レポートを開いたタイミングで、相対日付を適用できます
  * レポートのレポートタイプで`インタラクティブレポート`を選択
  * オプションで`自動実行を有効化`を選択し、`パラメータのデフォルト値を使用`を選択
    * `パラメータのデフォルト値を使用`を有効化しない場合、パラメータの値は**レポートの公開時点の値**になります
* パラメータの入力フォームでの操作は、ノートブックの場合と同様です

{% hint style="info" %}
レポートのパラメータ変更は、他のユーザーとは**共有されません**。
{% endhint %}

### 署名付き埋め込み

* 以下の設定をすることで、署名付き埋め込みを開いたタイミングで、相対日付を適用できます
  * パラメータを`クライアントサイドパラメータ`に指定（`サーバーサイドパラメータ`に指定しない）
  * `iframeの埋め込み`の`クライアントサイドパラメータ`で、`パラメータのデフォルト値を初期値として利用`を指定
    * 署名付き埋め込みの生成を行うスクリプトの変更が必要になります
    * `パラメータのデフォルト値を初期値として利用`を有効化しない場合、パラメータの値は**署名付き埋め込みの公開時点の値**になります
* パラメータを`サーバーサイドパラメータ`に指定している場合、相対日付の機能は利用できず、サーバーサイドで日付を指定する際に、別途相対日付の計算処理を行う必要があります。
* パラメータの入力フォームでの操作は、ノートブックの場合と同様です
  * ただし、入力フォームを非表示にしている場合、デフォルト値へのリセット処理の対象外となるため、相対日付の計算は行われません

{% hint style="info" %}
署名付き埋め込みのパラメータ変更は、他のユーザーとは**共有されません**。
{% endhint %}

## よくある質問

### Q: 相対日付を計算する基準の日時はどうなっているのですか？

**A:** ブラウザの現在時刻を基準にして相対日付を計算します。タイムゾーンはブラウザでの設定に従うため、同じ時刻でもタイムゾーンが異なる場合は、計算される相対日付が異なる場合があります。


# エスケープと動的参照

パラメータのエスケープ処理と動的なテーブル・カラムの参照方法

パラメータのコンテキストに基づいてSQLインジェクション保護と値のエスケープを処理します。この仕組みはセキュリティを担保するだけでなく、テーブル名やカラム名などの動的な識別子の生成も可能にします。

## パラメータのエスケープ処理

### 1. 通常のコンテキストでの文字列パラメータ

* パラメータは文字列としてエスケープされて展開されます
* エスケープ処理は、選択されているコネクションのSQL文法に従って行われます

```sql
-- パラメータ値が user's "data" の場合
WHERE name = {{str_param}}         -> WHERE name = 'user\'s \"data\"'

-- パラメータ値が O'Reilly's "Book" の場合
SELECT name = {{company}}          -> SELECT name = 'O\'Reilly\'s \"Book\"'
```

### 2. 引用符付きコンテキストでの文字列パラメータ

* パラメータがダブルクォートやシングルクォートなどの引用符内にある場合、パラメータはその引用符を加味して、元の構文を壊さないようにエスケープされます
* エスケープ処理は、選択されているコネクションのSQL文法に従って行われます

```sql
-- 以下は BigQuery のコネクションを使用した場合の例

-- ダブルクオート内（"と'の両方をエスケープ）
-- パラメータ値が user"s 'data' の場合
SELECT "{{str_param}}" as alias    -> SELECT "user\"s \'data\'" as alias

-- シングルクオート内（"と'の両方をエスケープ）
-- パラメータ値が user"s 'data' の場合
SELECT '{{str_param}}' as alias    -> SELECT 'user\"s \'data\'' as alias

-- バッククォート内（`のみをエスケープ）
-- パラメータ値が user"s 'data` の場合
SELECT `{{str_param}}` as alias    -> SELECT `user"s 'data\`` as alias
```

### 3. 日付パラメータの特別処理

* 通常のコンテキスト: 日付は `YYYY-MM-DD` 形式で文字列として展開されます
* ただし、BigQueryのコネクションを利用している場合、バックティック(\`)で囲まれた中では `YYYYMMDD` 形式（ハイフンなし）に展開されます

```sql
-- 以下は BigQuery のコネクションを使用した場合の例

-- 通常の日付パラメータ
SELECT {{date_param}} as normal         -> SELECT '2024-10-02' as normal

-- 引用符内の日付は同じエスケープルールに従います
SELECT '{{date_param}}' as single_quote -> SELECT '2024-10-02' as single_quote
SELECT "{{date_param}}" as double_quote -> SELECT "2024-10-02" as double_quote

-- 特殊ケース: BigQueryでのテーブル名生成
SELECT * FROM `table_{{date_param}}`    -> SELECT * FROM `table_20241002`
```

### 4. その他のパラメータ

* 数値、真偽値パラメータはエスケープ処理は行われず、そのまま展開されます

## 動的な参照の生成

* パラメータを引用符内に配置することで、テーブル名やカラム名などの識別子を安全に生成することができます

```sql
-- ダイナミックなテーブル名
SELECT * FROM `table_{{table_suffix}}` -> SELECT * FROM `table_sales_2024`

-- ダイナミックなフィールド選択
SELECT "column_{{field_type}}"         -> SELECT "column_revenue"
```

{% hint style="warning" %}
外側の引用符に応じて、構文が壊れないようにエスケープ処理を行いますが、**文字列パラメータの値には任意の文字列が指定可能**なため、SQLの書き方によっては意図しないテーブルやカラムが参照されてしまう可能性があります。動的に識別子を生成する場合は、**プレフィックスやサフィックスを固定**する、**意図しない値が指定された時にSQLがエラーになるようにSQLを記述する**、等の対策を考えてください。
{% endhint %}


# 動的な選択肢の生成

[テキスト選択](/data-exploration/parameter-overview/parameter-types#text-select)や[テキスト複数選択](/data-exploration/parameter-overview/parameter-types#text-multi-select)では、3種類の選択肢の生成方法をサポートしています。

## 1. `固定リスト`

固定の値から選択したい場合に使用します。

* 設定:
  * CSV Text:
    * CSV形式のテキストで選択肢を定義します。各項目は改行で区切ります。表示名を指定する場合は、同じ行にカンマ（,）で区切って記述します。

例：

```csv
value1,表示名1
value2,表示名2
```

## 2. `テーブル`

特定のテーブルのカラムから選択可能な値を生成したい場合に使用します。

* 設定:
  * `テーブル`: 値を取得するテーブルを選択します。
  * `選択肢にするカラム`: 選択肢の値として使用するカラムを指定します。
  * `表示名にするカラム`: 表示ラベルとして使用するカラムを指定します。

## 3. `クエリ実行結果`

指定したSQLの実行結果に基づいて選択肢を生成したい場合に使用します。

* 設定:
  * `コネクション`:
    * クエリに使用するデータベース接続を選択します。
  * `SQL`:
    * 選択肢の値を返すSQLを入力します。クエリが複数のカラムを返す場合、最初のカラムが選択肢の値として、2番目のカラム（存在する場合）が表示ラベルとして使用されます。

{% hint style="info" %}
選択肢用のSQLは頻繁に実行されるため、パフォーマンスを最適化するために、遅いクエリやリソースを多く消費するクエリの使用は避けてください。
{% endhint %}

## SQLの実行タイミング

パラメータの選択肢にSQLを使用する場合、以下のタイミングでクエリが実行されます：

1. **ノートブックページが読み込まれたとき**：
   * そのページで使用されているパラメータのSQLはページの初期化時に実行されます
   * 現在のページで使用されていないパラメータは初期化されず、そのSQLも実行されません
2. **パラメータのドロップダウンが開かれたとき**：
   * ドロップダウンメニューが最初に開かれたときにSQLクエリが実行されます
3. **検索フィールドに入力するとき**：
   * 初回のクエリ実行後は、すでに取得したデータを使用してクライアント側でフィルタリングが行われます
   * キーストロークごとにSQLが再実行されることはありません

## キャッシュの動作

パラメータ用のSQLは、通常のSQLブロックと同じキャッシュメカニズムを使用します：

* 結果はバックエンドで最大24時間キャッシュされます
* 同一のクエリ（パラメータ値を含む）はキャッシュされた結果を使用します
* フロントエンドも現在のセッション中はメモリキャッシュを維持します

これにより、パラメータ選択のドロップダウンが頻繁に開かれたとしても、実際のクエリはキャッシュ期間内に1回だけ実行され、パフォーマンスが大幅に向上します。


# URLからの指定方法

外部でリンクを作成する際に、パラメータを指定する方法

外部でリンクを作成する際に、URLにパラメータを指定することで、既存のパラメータの値を上書きすることができます

## 対象機能

以下の機能で、URLからパラメータを指定することができます。\
これらの機能では、パラメータを変更する度にURLが更新され、**URLを他のユーザーと共有することで、パラメータの値を共有することができます**。

* ノートブックの[バージョン](/data-exploration/notebook/version)
* [レポート](/sharing/report)
  * レポートタイプが`インタラクティブレポート`の状態で公開されている必要があります
  * `自動実行`の設定が有効になっている場合、これらのパラメータがマージされた後に自動的に実行されます
  * `パラメータのデフォルト値を使用`の設定が有効になっている場合でも、**URLで指定されたパラメータが優先されます**
    * パラメータ全体がデフォルト値にリセットされた後に、URLで指定されたパラメータの更新が反映されます

## パラメータの指定方法

パラメータはURLの `cdm.params` クエリパラメータと同期します。\
`cdm.params` クエリパラメータは以下のような形式になっています。

```typescript
// ページ遷移時にもパラメータを保持するために、ページID毎にパラメータが保持されます
type Params = {[pageId: string]: {[paramId: string]: string}};

// パラメータの各値は、JSON.stringifyで文字列化して指定します（詳細は後述）
// pageId や paramId は実際は 68783eb9c4b4b71483a1d617 のような文字列になります
const params: Params = {
  "page1": {
    "param1": JSON.stringify("value1"),
    "param2": JSON.stringify(123)
  },
  "page2": {
    "param3": JSON.stringify(true),
    "param4": JSON.stringify(["value1", "value2"])
  }
};

const query = `?cdm.params=${encodeURIComponent(JSON.stringify(params))}`;
```

## ショートカット形式での指定方法

`cdm.params` クエリパラメータを外部で直接生成するのが困難な場合、 `cdm.params.${paramId}` 形式のキーと値を指定することで、パラメータを追加指定することもできます。 `cdm.params` と `cdm.params.${paramId}` の両方が指定された場合、 `cdm.params.${paramId}` の値が優先され、両方の値がマージされた新しい `cdm.params` クエリパラメータが自動的に指定されます。

```typescript
const paramId = "param1";
// ショートカット形式の場合、パラメータの値は JSON.stringify の文字列化は不要です（詳細は後述）
const value = "string_value";  

const query = `?cdm.params.${paramId}=${encodeURIComponent(value)}`;

// ショートカット形式では空文字列を指定することで、パラメータを空の状態にすることができます
const queryEmpty = `?cdm.params.${paramId}=`;
```

## パラメータの値の指定方法

パラメータの値は、パラメータの種類に応じて以下のように指定します。\
ショートカット形式で指定する場合、`JSON.stringify` の文字列化は不要ですが、URLに指定する際の、`encodeURIComponent` エンコードは必要です。

| 種類                           | 指定方法                                             | ショートカット形式               |
| ---------------------------- | ------------------------------------------------ | ----------------------- |
| <p>テキスト入力,<br>テキスト選択</p>     | `JSON.stringify("string_value")`                 | `string_value`          |
| <p>テキスト複数入力,<br>テキスト複数選択</p> | `JSON.stringify(["item1", "item2"])`             | `item1,item2`           |
| <p>数値入力,<br>数値選択</p>         | `JSON.stringify(123)`                            | `123`                   |
| 日付入力                         | `JSON.stringify("2025-01-01")`                   | `2025-01-01`            |
| 日付範囲                         | `JSON.stringify(["2025-01-01", "2025-01-02"])`   | `2025-01-01,2025-01-02` |
| チェックボックス                     | `JSON.stringify(true)`または`JSON.stringify(false)` | `true`または`false`        |

### 指定方法の説明

* 配列型のパラメータは、ショートカット形式では `,` で区切って指定します。
* 日付入力や日付範囲では `YYYY-MM-DD` の形式で指定してください
* 無効なパラメータの値が指定された場合、エラー画面に切り替わります


# 【応用】SQLの高度な制御構造

Codatumのパラメータ機能を使用して、テンプレートエンジンのような機能を安全に実装する方法を学びます

パラメータ入力に基づいて処理を分岐したり、繰り返したり、再利用したりしたい場合があります。このような場合、多くのSQLツールではJinjaのようなテンプレートエンジンを使用して動的なSQLクエリを生成します。

しかし、CodatumではSQLインジェクションなどのセキュリティ上の懸念を優先し、テンプレートエンジンは使用できません。テンプレートエンジンを使わずに構文解析を行えるようにすることで、以下のような利点があります：

* コンテキストに基づく正確なエスケープ処理により、セキュリティリスクを軽減
* エラーの正確な位置を特定することで、デバッグが容易になる
* コンテキストに基づくサジェストにより、使いやすさが向上

これらのケースのほとんどは、標準的なSQL構文を活用することで対応できます。この記事では、Codatumで高度な制御構造を実装する方法を紹介します。

本セクションを読む前に、[パラメータ](/data-exploration/parameter-overview)や[エスケープと動的参照の生成](/data-exploration/parameter-overview/escape-and-dynamic-reference)のセクションも事前にご確認ください。

{% hint style="info" %}
**注意：** この記事のテンプレートエンジンの例は、Jinja2/Jinjaテンプレート言語の構文に基づいています。実際のツールでは、類似しているが異なる構文や独自の拡張機能を使用する場合があります。
{% endhint %}

## 1. 条件付きデータアクセス（If/Else）

パラメータに基づいて、どのフィールドまたはデータをSELECTするかを制御します。

### ユースケース

* 地域/国ごとに異なるビジネスロジックを適用する
* データ集計の粒度を動的に変更する
* ユーザーの権限レベルに基づいてデータアクセスを制限する
* 部門/チームごとに異なるデータビューを提供する

### Codatumのアプローチ

CASE式またはUNIONをパラメータと共に使用します：

```sql
-- 地域固有のビジネスロジックの例
SELECT
  order_id,
  CASE {{region}}
    WHEN 'EU' THEN amount * 1.20  -- EU: 20% VAT
    ELSE amount
  END as final_price,
  CASE {{region}}
    WHEN 'EU' THEN 'EU'
    ELSE 'Other'
  END as tax_region
FROM orders

-- 集計粒度の例
SELECT
  CASE {{granularity}}
    WHEN 'daily' THEN DATE_TRUNC('day', timestamp)
    WHEN 'weekly' THEN DATE_TRUNC('week', timestamp)
    ELSE DATE_TRUNC('month', timestamp)
  END as period
FROM events

-- 権限ベースの制限の例
SELECT * FROM (
  SELECT sensitive_column as data FROM sensitive_data WHERE {{is_admin}} = TRUE
  UNION ALL
  SELECT public_column as data FROM filtered_data WHERE {{is_admin}} = FALSE
) t
```

### テンプレートエンジンのアプローチ（Codatumでは使用不可）

参考までに、テンプレートエンジン（Jinja2）では以下のように実装されます：

```sql
-- 地域固有のビジネスロジックの例
{% raw %}
{% if region == 'EU' %}
  SELECT 
    order_id,
    amount * 1.20 as price_with_vat,  -- EU: 20% VAT
    'EU' as tax_region
  FROM orders
{% else %}
  SELECT 
    order_id,
    amount as price_without_vat,
    'Other' as tax_region
  FROM orders
{% endif %}

-- 集計粒度の例
SELECT
  {% if granularity == 'daily' %}
    DATE_TRUNC('day', timestamp) as period
  {% elif granularity == 'weekly' %}
    DATE_TRUNC('week', timestamp) as period
  {% else %}
    DATE_TRUNC('month', timestamp) as period
  {% endif %}
FROM events

-- 権限ベースの制限の例
{% if user.is_admin %}
  SELECT * FROM sensitive_data
{% else %}
  SELECT public_columns FROM filtered_data
{% endif %}
{% endraw %}

```

## 2. オプションのフィルタ条件（If/Else）

パラメータに基づいて、WHERE句に含める条件を制御します。

### ユースケース

* ユーザーが検索条件を柔軟に組み合わせられるようにする
* レポートのフィルタを動的に変更する
* 特定の条件が提供された場合にのみフィルタを適用する

### Codatumのアプローチ

空パラメータの処理を使用します：

```sql
SELECT * FROM orders
WHERE 1=1
  AND (order_date >= {{start_date}} OR {{start_date}} = '1970-01-01')
  AND (status = {{status}} OR {{status}} = '')
```

### テンプレートエンジンのアプローチ（Codatumでは使用不可）

参考までに、テンプレートエンジン（Jinja2）では以下のように実装されます：

```sql
SELECT * FROM orders
WHERE 1=1
{% raw %}
{% if start_date %}
  AND order_date >= {{start_date}}
{% endif %}
{% if status %}
  AND status = {{status}}
{% endif %}
{% endraw %}

```

## 3. マルチパラメータによる繰り返し（For Loop）

テキスト複数選択/入力パラメータを使用して繰り返しパターンを適用します。

### ユースケース

* 複数のメトリクスを同時に集計する
* ユーザーが選択したメトリクスのみを表示する
* 複数の列に類似の計算ロジックを適用する

### Codatumのアプローチ

テキスト複数選択/入力パラメータとCASE式を使用します：

```sql
SELECT
  SUM(CASE WHEN 'revenue' IN ({{selected_metrics}}) THEN revenue ELSE NULL END) as revenue_total,
  SUM(CASE WHEN 'cost' IN ({{selected_metrics}}) THEN cost ELSE NULL END) as cost_total,
  SUM(CASE WHEN 'profit' IN ({{selected_metrics}}) THEN profit ELSE NULL END) as profit_total
FROM sales
```

このアプローチはテンプレートエンジンよりもコードが多くなりますが、以下のような信頼性と保守性の向上が得られます：

* 各メトリクスが明示的に定義されているため、コンパイル時にエラーを検出しやすくなります
* カラム名とデータ型をSQLエンジンで検証できます
* テーブルスキーマの変更によってクエリが破損する可能性が低くなります

### テンプレートエンジンのアプローチ（Codatumでは使用不可）

参考までに、テンプレートエンジン（Jinja2）では以下のように実装されます：

```sql
SELECT
{% raw %}
{% for metric in metrics %}
  SUM({{metric}}) as {{metric}}_total,
{% endfor %}
{% endraw %}


FROM sales
```

## 4. 動的識別子の生成

パラメータに基づいて、クエリ対象のテーブルを制御します。

### ユースケース

* APIキーでテーブルを選択する
* 日付でパーティション分割されたテーブルにアクセスする
* スキーマやテーブル名を動的に生成する

### Codatumのアプローチ

クオート付きのパラメータを使用します：

```sql
-- APIキーベースのテーブル選択
SELECT * FROM `api_logs_{{api_key_suffix}}`  -- 例：api_logs_v1, api_logs_v2

-- 日付パーティションテーブルへのアクセス
SELECT * FROM `events_{{date_suffix}}`  -- 例：events_20240131
FROM `sales_{{region}}_{{date_suffix}}`  -- 例：sales_us_20240131

-- 動的な列名
SELECT 
  "{{metric_name}}" as metric,  -- 例：revenue_usd, revenue_eur
  "amount_{{currency}}" as amount  -- 例：amount_usd, amount_eur
FROM transactions
```

注：BigQueryのコネクションでは、テーブル名の日付パラメータは自動的に `YYYYMMDD` 形式でフォーマットされます。

### テンプレートエンジンのアプローチ（Codatumでは使用不可）

参考までに、テンプレートエンジン（Jinja2）では以下のように実装されます：

```sql
-- APIキーベースのテーブル選択
SELECT * FROM `api_logs_{{api_version}}`

-- 日付パーティションテーブルへのアクセス
SELECT * FROM `events_{{date.strftime('%Y%m%d')}}`

-- 動的な列名
SELECT 
  {{metric_name}} as metric,
  amount_{{currency}} as amount
FROM transactions
```

## 5. マクロ/関数の再利用

再利用可能な計算ロジックを関数にカプセル化します。

### ユースケース

* ドメイン固有の計算ロジックを標準化する
* 複数のクエリで計算ロジックを再利用する
* 複雑な条件付き計算をカプセル化する

### Codatumのアプローチ（BigQuery UDFを使用）

```sql
-- LTV計算関数
CREATE TEMP FUNCTION calculate_ltv(revenue FLOAT64, acquisition_cost FLOAT64, retention_months INT64)
RETURNS FLOAT64
AS (
  CASE
    WHEN retention_months = 0 THEN 0.0
    ELSE (revenue - acquisition_cost) * POWER(0.95, retention_months)
  END
);

SELECT
  user_id,
  calculate_ltv(total_revenue, acquisition_cost, months_active) as ltv,
FROM user_metrics
```

{% hint style="info" %}
UDFはデータベース固有の機能であり、表記法と機能はデータベースによって異なります。
{% endhint %}

### テンプレートエンジンのアプローチ（Codatumでは使用不可）

参考までに、テンプレートエンジン（Jinja2）では以下のように実装されます：

```sql
{% raw %}
{% macro calculate_ltv(revenue, acquisition_cost, retention_months) %}
  CASE
    WHEN {{retention_months}} = 0 THEN 0
    ELSE ({{revenue}} - {{acquisition_cost}}) * 
         POWER(0.95, {{retention_months}})  -- 5%の減衰率を適用
  END
{% endmacro %}
{% endraw %}

SELECT
  user_id,
  {{ calculate_ltv('total_revenue', 'acquisition_cost', 'months_active') }} as ltv
FROM user_metrics
```

## Codatumのアプローチの利点

テンプレートエンジンはより柔軟性を提供しますが、Codatumのパラメータベースのアプローチには以下の利点があります：

1. 適切なエスケープによるSQLインジェクション保護
2. 保守可能なSQL構造
3. クエリの分析と最適化の向上
4. パラメータの型安全性
5. 動的な値とSQL構造の明確な分離

テンプレートエンジンの機能が必要な場合は、以下を検討してください：

* 標準的なSQL機能を使用するようにクエリを再構築する
* 複雑なクエリを複数のシンプルなクエリに分割する
* クエリの整理にCTEを使用する
* 可能な場合はデータベース固有の機能を活用する


# クエリ（ベータ版）

複数のノートブックで利用できるSQLクエリを作成する

{% hint style="warning" %}
この機能はベータ版です。仕様については予告なく変更となる場合がございます。
{% endhint %}

「クエリ」を利用することで、複数のノートブックで利用できる汎用的なクエリをコネクション単位で保存することができます。

## 使用方法

* 「クエリ」の作成:
  * 「クエリ」画面での作成
    * 「クエリを作成」から新規作成し、コネクションを選択の上で「保存」します。
  * ノートブックからの作成
    * SQLブロック右上のメニューから「SQLを保存」を実行することで「クエリ」にSQLブロックの内容が保存されます。
      * 他のSQLブロックの参照は展開された状態で保存されます。
      * パラメータは値に置き換えられた状態で保存されます。
* 「クエリ」の用途
  * ノートブック間でクエリを共有することができます。

## 注意点

* パラメータの埋め込みや他の「クエリ」の参照は行えません。


# (補足) クエリ実行とキャッシュ

クエリ実行とキャッシュに関する追加情報

様々な場面で、クエリ実行ごとにキャッシュを作成・活用し、不要なバックグラウンドジョブを防いでいます。

これにより、スキャンするデータ量を削減し、実行結果をより速く取得することができます。

## **クエリ実行**

以下の機能においてクエリが実行されます。

* [ドキュメントページ](/data-exploration/notebook/doc-page)
  * すべて実行、最新データですべて実行
  * [SQLブロック](/data-exploration/notebook/sql-block)
    * 実行、最新データで実行
* [グリッドページ](/data-exploration/notebook/grid-page)
  * すべて実行、最新データですべて実行
* [レポート](/sharing/report)・[署名付き埋め込み](/sharing/signed-embed)
  * 更新
  * 自動実行
* クエリ
  * 実行
* 各種機能におけるテーブルのプレビュー機能

## **ウェアハウス側のキャッシュ**

SQL文が変更されない場合、ウェアハウス側のキャッシュ（例：[BigQueryのキャッシュされたクエリ実行結果](https://cloud.google.com/bigquery/docs/cached-results)）が使用されます。SQLチェインを使用する場合、中間SQLの結果は自動的にキャッシュテーブルを使用するように書き換えられます。

## **ノートブックとレポートの小規模キャッシュ**

* 1000行までのSQL実行結果は、ノートブックと紐づけてキャッシュとして保存されます。チャートなどのコンポーネントは、この1000行までの実行結果を利用できます。
* 24時間以内に同じSQLが再度実行された場合、保存された表示用データが取得され、新しいジョブの実行はスキップされます。
  * 新しいジョブで実行したい場合は `最新データですべて実行` を選択して結果を更新してください。
* レポートのキャッシュ有効時間はレポート設定から変更可能です。

{% hint style="info" %}
テーブルのプレビュー機能については閲覧時に都度データ取得されるため、キャッシュは利用されません。
{% endhint %}


# 共有方法

ノートブックを共有する方法の概要

<figure><img src="/files/2bsT5FEFa1n0ojvNUi2d" alt=""><figcaption></figcaption></figure>

ノートブックの中身を他のユーザーや外部に共有するには以下の方法があります

1. ノートブックの権限を付与する
   * ノートブックの基本権限を変更する
     * ノートブックへの基本権限は、ノートブックの保存されている（ルート）フォルダにより、以下のように決まります
       * `ワークスペース`: ワークスペース内の全メンバーがアクセスできる
       * [`チームスペース`](/sharing/teamspace): チームスペースに所属するメンバーのみがアクセスできる
       * `プライベート`: ノートブックの所有者だけがアクセスできる
     * ノートブックを異なるフォルダに移動することで、基本権限を変更することができます
   * ノートブックの追加権限を設定する
     * ノートブックの追加権限を設定することで、ワークスペース内の特定のメンバーやグループに対して、[ノートブックを共有](/sharing/shared-notebook)することができます
     * `ワークスペース`フォルダにあるノートブックは、既にワークスペース全体に共有されているため、追加権限の設定は行えません
2. ノートブックからスナップショットを作成して共有する
   * [レポート](/sharing/report): ノートブックをレポートに変換して、ワークスペースゲストを含む、ワークスペース内のユーザーに共有します
     * 外部のユーザーをゲストとして招待する場合、招待されたユーザーはCodatumアカウントを所有している必要があります
   * [パブリックリンク](/sharing/public-link-and-embed): URLを知っているユーザーは誰でもアクセスできるように、インターネット上に公開します
   * [署名付き埋め込み](/sharing/signed-embed): 外部のアプリケーションに組み込んで、そのアプリケーションのユーザーに共有します

## 各共有方法の違いの概要

<table data-full-width="true"><thead><tr><th width="171">方法</th><th width="106" data-type="checkbox">編集可能</th><th width="158">クエリ実行</th><th width="243">パラメータ</th><th width="136">エクスプローラ</th><th data-type="checkbox">埋め込み可能</th><th data-type="checkbox">ゲストアクセス</th><th data-type="checkbox">ログイン必須</th><th data-type="checkbox">コネクション権限必須</th><th data-type="checkbox">API認証必須</th></tr></thead><tbody><tr><td>権限の付与</td><td>true</td><td>可能</td><td>可能（値は共有）</td><td>可能</td><td>true</td><td>false</td><td>true</td><td>true</td><td>false</td></tr><tr><td>レポート</td><td>false</td><td>選択可能</td><td>選択可能（値はユーザーごと）</td><td>選択可能</td><td>true</td><td>true</td><td>true</td><td>false</td><td>false</td></tr><tr><td>パブリックリンク</td><td>false</td><td>不可</td><td>不可</td><td>不可</td><td>true</td><td>true</td><td>false</td><td>false</td><td>false</td></tr><tr><td>署名付き埋め込み</td><td>false</td><td>選択可能</td><td>選択可能（値はユーザーごと）</td><td>選択可能</td><td>true</td><td>false</td><td>false</td><td>false</td><td>true</td></tr></tbody></table>

* 編集可能: ユーザーがノートブックを編集できるかどうかを示します。
* クエリ実行: クエリの実行が可能かどうかを示します。
* [パラメータ](/data-exploration/parameter-overview): パラメータ機能が利用できるかどうかと、パラメータが他ユーザに共有されるか、ユーザー固有かを指定します。
* 埋め込み可能: HTMLのiframeを使用して他のプラットフォームにコンテンツを埋め込めるかどうかを示します。
* ゲストアクセス: ワークスペースゲストが共有コンテンツにアクセスできるかどうかを示します。
* ログイン必須: コンテンツにアクセスするためにCodatumへのログインが必要かどうかを示します。
* コネクション権限必須: クエリの実行や実行結果の表示に、コネクションの権限が必要かどうかを示します。

各共有方法をどのような場面で使うべきかは、[ユースケース](/sharing/use-case)を参照してください。


# ユースケース

共有方法の選択ガイドラインやよくある質問

## 共有方法の選択ガイドライン

状況に応じて適切な共有方法を選択してください。例えば：

### 権限の付与

* ノートブックの共同編集を行う場合

### レポート

* ノートブックの変更をリアルタイムに共有したくない場合
  * パラメータの変更を別々に行いたい場合は、ノートブックの[バージョン機能](/data-exploration/notebook/version)の使用も検討してください
* コネクションの権限を持たないワークスペース内のメンバーに共有したい場合
* ワークスペース内の他のデータは共有せずに、特定のノートブックの中身だけを共有したい場合
  * ワークスペースゲストとしてユーザーを招待して、閲覧権限を付与してください
    * 過去に別のアカウントでログインしたことがある場合など、招待メールのリンク遷移時にサインアップ画面が表示されない場合がありますが、その場合はシークレットモードにてサインアップが可能かお試しください

### パブリックリンク

* マーケティング目的で、特定多数に対して公開したい場合
  * ブログへの埋め込み
  * Twitter等のSNSでの拡散
* Notionなどの社内ツールにデータを埋め込みたい場合
  * ログインを強制したい場合は、レポートの使用もご検討ください

### 署名付き埋め込み

* 外部のアプリケーションに組み込んで、そのアプリケーションのユーザーに共有したい場合
* 自社の認証基盤で認証されたユーザーにのみアクセスを許可したい場合

## よくある質問

> チームスペースへのアクセス権限を持たないメンバーやグループに、チームスペース内のノートブックの閲覧権限を与えた場合、どうなりますか？

チームスペースに割り当てられた権限を持たないユーザーやグループは、`共有フォルダ`の下にノートブックが表示され、アクセスできるようになります。

> ノートブックをチームスペースの内外に移動することは可能ですか？

はい、可能です。ノートブックを移動する際、新しいフォルダ（ワークスペース/チームスペース/プライベート）に応じて新しい基本権限が設定されることに注意してください。


# チームスペース

チームスペースを使ったノートブックの共有

<figure><img src="/files/6piu6lHlFsAi9HyZLsrb" alt=""><figcaption></figcaption></figure>

チームスペースは、特定のチーム（メンバーやグループ）内でノートブックとフォルダを共同編集できる機能です。

チームスペースに対して権限を設定することで、チームスペース内のすべてのノートブックとフォルダに対するアクセス制限を適用でき、一貫したアクセス制御を確保できます。

## 主な機能

* 集中的なコラボレーション:
  * チームメンバーを専用のスペースに集め、共同編集とデータ分析を行えます。
* アクセス制御:
  * チームスペース内のユーザーやグループに特定の権限を割り当て、適切なアクセスレベルを確保します。
* フォルダとノートブックの管理:
  * チームスペース内にフォルダとノートブックを作成・整理し、構造化されたデータ管理を実現します。

## 設定方法

1. [このページ](https://app.codatum.com/workspace/last-accessed/setting/teamspaces)でチームスペースを作成します。
   * チームスペースへのアクセス権限をユーザーやグループに対して割り当てます。
2. チームスペース内にフォルダやノートブックを作成します。

よくある質問は[ユースケース](/sharing/use-case)を参照してください。


# ノートブック単位の共有

ノートブックの追加権限による共有

ノートブック単位で、特定のメンバーやグループに対して直接権限を付与して共有することができます。

## 主な機能

* 即時共有:
  * 特定のユーザーやグループと個別のノートブックを簡単に共有でき、迅速なコラボレーションが可能です。
* リアルタイムコラボレーション:
  * チームメンバーとリアルタイムで共同作業を行い、シームレスに編集や更新ができます。
* アクセス制御:
  * 共有された各ノートブックに対して、`ノートブック編集者`と`ノートブック閲覧者`のロールを選択でき、適切なアクセスレベルを確保できます。
* プライベート共有:
  * プライベートなノートブックを選択されたユーザーやグループと安全に共有できます。
* `共有`ボタンでの可視性:
  * ノートブックの共有先は、`共有`ボタンから簡単に確認できます

## 設定方法

1. ノートブックを選択
   * `ワークスペース`以外のフォルダにあるノートブックを選択します。
2. 追加権限を設定
   * ヘッダの`共有`を選択します。
   * `ノートブックごとの追加権限`で、共有したいメンバーやグループと設定するロール（`ノートブック閲覧者`または`ノートブック編集者`）を選択します。

参考： [ノートブックのアクセス制御](/access-control/access-control-for-resources/access-control-for-notebook)

{% hint style="info" %}
コネクションの権限は、ノートブックの権限とは独立しています。必要に応じて、コネクションの権限も設定してください。
{% endhint %}


# レポート

ノートブックをレポートに変換し、ゲストと共有

<figure><img src="/files/DNk6BPN3ekKHdeooSZaQ" alt=""><figcaption></figcaption></figure>

レポートは、コンテンツの閲覧のみが必要なユーザーへの共有を目的に設計された、ノートブックから作成されるスナップショットです。

レポートを作成することによって、コネクションへの権限を付与することなく、安全に分析結果を他のメンバーやゲストへと共有することができます。

## 主な機能

* ページを指定しての共有:
  * ノートブックの中の特定のページのみを選択して共有することができます。
* 閲覧専用のビュー:
  * レポートを使用することで、作成者は元データが変更される心配をせずにデータを共有することができます。閲覧者も内容を誤って変更することなく、重要な情報へとアクセスし、内容を確認することができます。これにより、作成者と閲覧者の両方が、共有されたデータが安全に保たれていることを確信できます。
* ゲストアクセス:
  * ゲストは特別なワークスペースロールで、レポートの閲覧のみができます。ノートブックやコネクションへのアクセスは不要なため、より幅広いユーザーと共有できます。
* コネクションロールが不要:
  * 元データへのアクセスを許可せずに、集計された統計データやチャートを共有できます。
* 高パフォーマンス:
  * 公開時点のデータの埋め込みや、キャッシュの活用により、無駄なクエリ実行を抑えつつ、表示速度の向上を実現。
* 利用用途に合わせたレポートタイプ:
  * レポート閲覧者に対して、クエリの再実行やパラメータの変更などを許可するかを選択できます。
* 固定パラメータによるデータ参照制御:
  * レポート公開時にパラメータ値を固定することで、閲覧者が参照できるデータの範囲を制限できます。パラメータ入力欄が非表示になり、値の変更もできなくなるため、マルチテナント環境で他テナントのデータへのアクセスを防止できます。
* パラメータとURLの同期:
  * レポート内でパラメータを変更すると、変更されたパラメータの情報がURLに同期されます。そのため、URLを他のユーザーと共有することで、パラメータの値を共有することができます。詳細については、[URLからパラメータを指定する方法](/data-exploration/parameter-overview/set-parameters-via-url)を参照してください。

## セットアップ方法

* ノートブックを開く
  * 共有したいノートブックを開きます。
  * ヘッダの`共有`ボタンをクリックし、`レポート`タブを選択します。
  * `レポートを作成`をクリックします。
* `公開するページ`を選択
  * 公開対象とするページを選択します。
* `レポートタイプ`を以下から選択
  * `インタラクティブレポート`
    * パラメータの変更とクエリの再実行を許可します。
    * データのダウンロードやエクスプローラ機能の利用等のオプションを選択できます。
  * `更新可能レポート`
    * クエリの再実行によるデータの更新を許可します。
  * `静的レポート`
    * レポート公開時のデータを固定で表示します。
* `レポートタイプ`に応じたオプションを設定（`静的レポート`以外の場合）
  * `固定パラメータ` を指定することで、閲覧可能なデータの範囲を更に制限することができます。
* 公開する
  * `公開`ボタンをクリックします。
  * （システムはバックグラウンドでノートブックを公開するために必要な権限があるかチェックします。確認後、レポートの作成が完了します。）
* レポートの権限を設定
  * レポートを開き、画面右上の`レポート設定`を開く
  * ワークスペース内のユーザーに対して権限を付与する場合は、`権限`からユーザーやグループを追加する
  * ワークスペースに存在しない外部ユーザーに対して権限を付与する場合は、`招待`からメールアドレスを入力してワークスペースゲストとして招待する
* `レポート設定`
  * オプションにて追加で下記の設定が可能です。
    * 自動実行
      * 有効にすることで、ページ読み込み時にクエリを自動実行させることができます。
    * パラメータのデフォルト値を使用
      * 「自動実行」が有効になっている時のみ有効にすることができます。
      * 有効にすると、パラメータのデフォルト値を使用してクエリが自動実行されます。相対日時などの動的なパラメータをパラメータのデフォルト値として設定しておくことで、動的なデータ表示を自動的に行うことが可能になります。
    * パラメータの変更をページ間で同期
      * 有効にすると、ノートブック共通のパラメータの値の変更がページ間で同期されます。
      * 「固定パラメータ ＞ パラメータの同期 ＞ パラメータのデフォルト値」の順で変更が反映されます。
    * キャッシュの有効期間
      * キャッシュの有効時間を変更できます。キャッシュの有効時間を短くすることで、クエリ実行の頻度を高め、より新しいデータを表示させることができます。
    * SQLブロックを非表示
      * ドキュメントページ内のSQLブロック（チャート等含む）を非表示にします。
    * SQLブロック内の結果のみ表示
      * ドキュメントページ内のSQLブロックのSQL部分を非表示にします。実行結果やチャートは表示されます。
    * コメントを無効化
      * コメントを無効化できます

## 注意事項

レポートに関連する操作、特に公開には、複雑な役割の組み合わせが必要です。詳細は以下のドキュメントを参照してください： [レポートのアクセス制御](/access-control/access-control-for-resources/access-control-for-report)


# パブリックリンク

ノートブックをURLを知っている人なら誰でもアクセスできる状態で共有

<figure><img src="/files/QWH32bvKSdoL628sxowd" alt=""><figcaption></figcaption></figure>

パブリックリンクを使用すると、公開リンクまたは埋め込みコードを作成してノートブックを広く共有できます。リンクを持っている人なら誰でも、ログインせずに共有コンテンツにアクセスできます。

## 主な機能

* パブリックアクセス:
  * リンクを持っている人なら誰でもコンテンツを閲覧できるため、アクセス制限なしで簡単に共有できます。
* 埋め込みコード:
  * 生成された埋め込みコードを使用して、ノートブックをウェブサイトやブログに簡単に埋め込むことができます。
* SEOコントロール:
  * パブリックリンクは「noindex」に設定されており、検索エンジンによるコンテンツのインデックス化を防ぎ、共有データのプライバシーと制御を確保します。
* カスタマイズ可能な有効期限:
  * 公開コンテンツに有効期限を設定し、指定した日数後に自動的に削除することで、セキュリティの追加層を提供します。
* 高パフォーマンス:
  * データは事前にフェッチされ、スナップショットとして保存されるため、表示速度が向上します。

## 設定方法

1. ノートブックを開く
   * 共有したいノートブックを開きます。
2. 権限を設定する
   * ヘッダの`共有`ボタンをクリックし、`パブリックリンク`タブを選択します。
   * `パブリックリンクを作成`をクリックします。
   * パブリックリンクに含めたい特定のページを選択します。
3. 有効期限を設定する（オプション）
   * 有効期限を設定したい場合は、有効期限オプションを有効にし、公開コンテンツが削除されるまでの日数を設定します。
4. 公開する
   * `公開`ボタンをクリックして、パブリックリンクを生成します。
5. 配布する
   * リンクまたは埋め込みコードをコピーし、必要に応じて配布します。


# 署名付き埋め込み

ノートブックを外部アプリケーションに統合

署名付き埋め込みを使用すると、既存の認証システムを活用しながら、Codatumノートブックをアプリケーションに直接埋め込むことができます。この統合により、アプリケーションユーザーはアプリケーション環境を離れることなく、Codatumノートブックやダッシュボードにアクセスできるようになります。

{% hint style="info" %}
この機能は、他のプラットフォームでは「ホワイトラベルエンベッド」や「エンベデッドアナリティクス」と呼ばれることもあります。
{% endhint %}

{% hint style="warning" %}
この機能はEnterpriseプラン向けのオプション機能となります。この機能のご利用を希望される場合は、Codatumサポートまでお問い合わせください。
{% endhint %}

## 主な機能

* 既存アプリケーションへの安全な埋め込み:
  * 認証トークンを使用した安全なアクセス制御
  * Codatumアカウントを必要とせず、既存のシステムを活用したユーザー認証
* マルチテナントデータアクセス:
  * 異なるクライアント向けにサーバーサイドの固定パラメータ値を設定することで、各顧客のデータアクセスを自身のデータサブセットに制限
  * 適切なデータ分離を備えた複数のクライアント組織に対応する単一のノートブックを作成
* インタラクティブな体験:
  * パーソナライズされた分析のためのパラメータ調整を可能に
  * エクスプローラ機能による詳細な探索
  * データダウンロード機能
* 柔軟な統合:
  * アプリケーションと埋め込まれたノートブック間でメッセージを交換

## 設定可能なオプション

* 公開設定
  * ページ選択:
    * 埋め込みビューに含める特定のページを選択
  * アクセス制御:
    * データダウンロードの有効化/無効化
    * エクスプローラ機能の有効化/無効化
* パラメータ:
  * サーバーサイドパラメータ:
    * 固定値: ユーザーによる変更不可なセキュアなパラメータ
    * 初期値: 初期値はサーバーサイドで設定されるが、ユーザーによる変更を許可するパラメータ
  * クライアントサイドパラメータ
    * サーバーサイドパラメータ以外のパラメータを指し、埋め込みの描画時に動的に指定できるパラメータ
* セキュリティ:
  * APIキー: 認証で利用可能なAPIキーを埋め込み毎に設定できます
  * 許可されたオリジン: ノートブックの埋め込みを許可するドメインを制限
* 表示オプション:
  * テーマ（ライト/ダーク）や、言語設定などがカスタマイズできます

## マルチテナント実装のヒント

マルチテナントデータアクセスにより、単一のノートブックで複数の顧客にサービスを提供しながら、各顧客が自分のデータのみを閲覧できるようにすることができます。

「固定値」パラメータを使用することで、クライアント識別子に基づいてデータをフィルタリングしたり、テーブル/スキーマを切り替えたりすることでデータ分離を作成できます。

## 次のステップ

セットアップ手順については、次のページを参照してください。

{% content-ref url="/pages/KFItalAM9WcxPFyUqDo7" %}
[署名付き埋め込みの設定方法](/sharing/signed-embed/integration)
{% endcontent-ref %}


# 署名付き埋め込みの設定方法

外部サービスにノートブックをシームレスに統合

## 設定方法

### 署名付き埋め込みの準備

* APIキーとAPIシークレットの準備
  * `ワークスペース設定`を開き、`APIキー`メニューをクリックします。
  * `APIキーを追加`ボタンをクリックして新しいAPIキーを作成します。
  * APIキーとAPIシークレット（後でAPIコールに使用します）をメモしておきます。
* ノートブックを開く
  * 共有したいノートブックを開きます。
  * ヘッダーの`共有`ボタンをクリックし、`署名付き埋め込み`タブを選択します。
* 署名付き埋め込みの公開
  * 公開対象のページの選択や、公開時のオプションを設定します。
  * `公開`ボタンをクリックします。
* 署名付き埋め込みの設定
  * `権限を付与するAPIキー`セクションで使用するAPIキーを追加します。
  * サーバーサイドでのトークン発行時に値を指定するパラメータを、`サーバーサイドパラメータ`セクションで設定します。

### サーバーからトークンを発行する

* トークンを発行するには以下のAPIを使用します
  * APIを呼び出すために必要な引数は `セットアップガイド`タブで確認できます。
  * **APIシークレット**が外部に漏れないようにするため、サーバーサイドでAPIコールを実行してください。
  * ユーザーセッションごとにトークンを発行し、再利用しないでください（デフォルトでは1時間後に期限切れになります）。

{% openapi src="<https://api.codatum.com/api/notebook/spec.json>" path="/api/notebook/issueToken" method="post" %}
<https://api.codatum.com/api/notebook/spec.json>
{% endopenapi %}

### フロントエンドへの組み込み

* [Codatum Embed SDK](https://github.com/codatum/codatum-embed-js) を使ってフロントエンドに組み込みます
  * 組み込みに必要な `embedUrl` は `セットアップガイド`タブで確認できます
  * `tokenProvider` には、サーバーサイドでトークンを発行するAPIを指定します
  * その他の設定可能な全オプションに関しては、[SDKのREADME](https://github.com/codatum/codatum-embed-js/tree/main/packages/embed#readme)を参照してください。

## 付録

### よくある質問

#### トークン発行時に "Missing param: xxx" エラーが出る場合

* トークン発行時には、全てのサーバーサイドパラメータをリクエスト内に含める必要があります
* "xxx" というパラメータIDのパラメータがリクエスト内に含まれていない場合、このエラーが発生します

#### クライアントサイドパラメータの送信時に "The following parameters must be set by the server" エラーが出る

* クライアントサイドパラメータの送信時にサーバーサイドパラメータを変更しようとしています
* サーバーサイドパラメータを変更するためには、新しいトークン発行が必要です

#### クライアントサイドパラメータの送信時にパラメータが変更されない場合

* 送信したパラメータがサーバーサイドパラメータとして指定されていないか確認してください
* `param_value`が正しいJSON文字列形式か確認してください
* `param_id`が実在するパラメータIDと一致しているか確認してください


# ユースケース

署名付き埋め込みのユースケース

## ケース: 小売業支援SaaSにおける埋め込みダッシュボードの活用

### シナリオ

小売業の店舗運営を支援するSaaSプラットフォームにおいて、店舗ごとの売上状況やKPIを把握するためのダッシュボードをSaaS内に埋め込むニーズを想定します。 この機能により、店舗マネージャーやエリアマネージャーがログインした際、自分の店舗に関連する情報だけを表示することができます。

### ノートブックのパラメータ

署名付き埋め込みのソースとなるノートブックには、以下のパラメータが設定されているものとします。

* `tenant_id`:
  * ログインしているユーザーが所属するテナントID
  * 「テキスト入力」型パラメータ
* `store_id`:
  * データの表示対象となる店舗ID
  * 「テキスト選択」型パラメータで、 選択肢は `tenant_id` で指定されたテナント内の店舗IDを選択可能
* `date_range`:
  * データの集計期間
  * 「日付範囲」型パラメータで、デフォルト値は相対日付で前日から7日間が指定されている
* `product_category`:
  * データの集計対象を絞り込むための商品カテゴリ
  * 「テキスト複数選択」型パラメータで、未選択の場合は全ての商品カテゴリを表示するようにSQL上で条件指定している

### 設定例A: 署名付き埋め込みのフォームを利用する場合

#### 前提となるノートブックの設計

* `tenant_id` を固定することで、ユーザーがアクセス可能なデータのセキュリティを担保できている
  * データを抽出する際のSQLには、 `tenant_id` がフィルタ条件として必ず指定されている
  * 例えば、店舗データを抽出する際も、 `store_id` だけでなく `tenant_id` もフィルタ条件に指定され、テナントが異なる店舗のデータは抽出できないようになっている
* `date_range` と `product_category` については、任意の値が指定可能という設計である

#### パラメータの設定

* `tenant_id`: **サーバーサイドパラメータの固定値**
* `store_id`: サーバサイドパラメータの初期値
* `date_range`: クライアントサイドパラメータ
* `product_category`: クライアントサイドパラメータ

#### 表示までの流れ

1. サーバーサイドでトークンを発行
   * ユーザーの所属する `tenant_id` をサーバーサイドパラメータの固定値として指定
   * `tenant_id` に紐づく `store_id` の中で、初期状態として表示する `store_id` をサーバーサイドパラメータの初期値として指定
2. フロントエンドでの初期描画処理
   * `SET_TOKEN` メッセージの送信時に、以下のクライアントサイドパラメータを一緒に送信します
     * `date_range` は相対日付の再計算を行うため、デフォルト値にリセットするように指定
     * `product_category` は空配列を初期値として指定
3. ユーザーによるダッシュボードの操作
   * ユーザーは `store_id`, `date_range`, `product_category` をダッシュボードのフォーム上から変更することができます

### 設定例B: SaaS側のフロントエンドでパラメータを管理する場合

#### 前提となるノートブックの設計

「設定例A」と同様の設計とします

#### パラメータの設定

* `tenant_id`: **サーバーサイドパラメータの固定値**
* `store_id`: クライアントサイドパラメータ
* `date_range`: クライアントサイドパラメータ
* `product_category`: クライアントサイドパラメータ

#### 表示までの流れ

1. サーバーサイドでトークンを発行
   * ユーザーの所属する `tenant_id` をサーバーサイドパラメータの固定値として指定
2. フロントエンドでの初期描画処理
   * `SET_TOKEN` メッセージの送信時に、以下のクライアントサイドオプションを一緒に送信します
     * パラメータはSaaS側で管理するため、パラメータフォームを非表示にするオプション(`displayOptions.hideParamsForm = true`)を指定
     * `store_id`, `date_range`, `product_category` には、SaaS側で管理している値を指定します
3. ユーザーによるダッシュボードの操作
   * SaaS側で管理している条件の変更等により、ダッシュボードの表示条件を変更する場合、次の手順を踏みます
   * 初期描画処理で利用したトークンを**再利用して**、更新されたクライアントサイドオプションと一緒に `SET_TOKEN` メッセージを再送信します
     * `SET_TOKEN` メッセージを再送信することで、新しく送信されたクライアントサイドオプションにより、ダッシュボードの再描画が行われます
     * この時に送信するクライアントサイドパラメータは、差分ではなく、全件（`store_id`, `date_range`, `product_category`）を送信する必要があります
     * 同一のユーザーが、同一のサーバーサイドパラメータの固定値を利用する場合、トークンの再利用が可能です（有効期限には注意してください）

### 設定例C: サーバーサイドパラメータの固定値を更新する場合

#### 前提となるノートブックの設計

* `tenant_id` と `store_id` の両方を固定することで、ユーザーがアクセス可能なデータのセキュリティを担保できている
  * 「設定例A」の場合と異なり、 `store_id` をサーバーサイドで固定する必要がある場合を想定します
* `date_range` と `product_category` については、「設定例A」と同様に、任意の値が指定可能という設計である

#### パラメータの設定

* `tenant_id`: **サーバーサイドパラメータの固定値**
* `store_id`: **サーバーサイドパラメータの固定値**
* `date_range`: クライアントサイドパラメータ
* `product_category`: クライアントサイドパラメータ

#### 表示までの流れ

1. サーバーサイドでトークンを発行
   * ユーザーの所属する `tenant_id` と、初期状態として表示する `store_id` をサーバーサイドパラメータの固定値として指定
2. フロントエンドでの初期描画処理
   * `SET_TOKEN` メッセージの送信時に、以下のクライアントサイドパラメータを一緒に送信します
     * `date_range` は相対日付の再計算を行うため、デフォルト値にリセットするように指定
     * `product_category` は空配列を初期値として指定
3. ユーザーによるダッシュボードの操作
   * `store_id` はサーバーサイドパラメータの固定値のため、ダッシュボード上のフォームからは変更できず、SaaS側で `store_id` を管理し、対象店舗の変更フォームを用意する必要があります
   * ユーザーからの操作により、 `store_id` を変更してダッシュボードを再描画する場合、次の手順を踏みます
   * サーバーサイドに対して、新しい `store_id` を指定して**トークンを新しく発行**し、新しいトークンとクライアントサイドパラメータを一緒に `SET_TOKEN` メッセージを送信します
     * サーバーサイドパラメータの固定値を変更するためには、トークンの再発行が必要となります
     * クライアントサイドパラメータは、差分ではなく、全件（`date_range`, `product_category`）を送信する必要があります
       * ユーザーの操作により変更された `date_range` や `product_category` を保持したい場合、 iframe から送信される `PARAM_CHANGED` メッセージを記録しておき、再描画時に送信するようにします
   * `date_range` と `product_category` については、ユーザーがダッシュボード上のフォームから表示内容を変更することができます


# アカウント

Codatumのアカウントの概要

Codatumにおいて、アカウントはCodatumにアクセスして利用できるユーザーを表します。アカウントには以下の機能が利用可能です。

## 主な機能

* 複数のワークスペースへのアクセス:
  * 1つのアカウントで複数のワークスペースに所属することができます
  * 例えば、個人用ワークスペースとチーム用ワークスペース両方に所属することが可能です
  * 画面左上にあるワークスペース選択から、簡単にワークスペースを切り替えることができます
* ワークスペースロールとアクセス制御:
  * アカウントは所属する各ワークスペースに対して、必ず1つの[ワークスペースロール](/access-control/access-control-for-workspace)が割り当てられます
  * [リソースロール](/access-control/access-control-for-resources)は、直接アカウントに割り当てるか、グループを通じて割り当てることができます
  * [グループ](/workspace-and-user-management/user-management/group)を使用することで、複数のアカウントを効率的に管理できます
  * ワークスペースロール、リソースロール、アクセス制御の設定に関する詳細は、[アクセス制御](/access-control/access-control-overview)を参照してください。


# アカウント設定

Codatumのアカウント設定の概要

Codatumのアカウント設定では、アバター画像やニックネーム等のプロフィール設定、テーマや言語の設定、認証方法の設定等が行えます。

{% hint style="warning" %}
アカウント設定で設定した項目は、所属するすべてのワークスペースで共用されます。 （通知設定はワークスペースごとに設定可能です）
{% endhint %}

## 主な機能

### プロフィール設定

* 氏名: 他のユーザーに表示される名前
* ニックネーム: ノートブックなどで略式表示される際に使用される短い名前です
* プロフィール画像: アバターとして使用される画像

### インターフェース設定

* テーマ: ライトモード、ダークモード、システム設定から選択可能
* 言語: 以下の項目に反映されます
  * UI表示: 現在は英語と日本語の2言語に対応（日本語以外を選択した場合は、英語表示になります）
  * チャート: 数値や日付のフォーマット処理に反映されます

### 認証方法

* Googleログイン: Googleアカウントを使用したシングルサインオン
* メール + パスワード: メールとパスワードによる認証
* 多要素認証（MFA）: メール + パスワード認証での使用を強く推奨
  * 認証アプリのサポート（Google Authenticator、Microsoft Authenticator）
  * 登録された電話番号によるSMS認証

### SQLエディタ設定

* タブサイズ: インデントのスペース数を調整
* 大文字/小文字: SQL関数とキーワードの表示を大文字または小文字に設定

### キーボードショートカットのカスタマイズ

* グローバル:
  * クイック検索
  * サイドバーの表示/非表示
  * AIアシスタントを開く
* ドキュメントページ:
  * テキストの検索と置換
  * テキストの書式設定（太字、ハイライトなど）
  * SQLエディタの操作（SQLの実行、フォーマット、コメント/コメント解除）
* グリッドページ:
  * 元に戻す/やり直し操作

### 通知設定

* 通知チャンネル: アプリ内通知とメール通知から選択可能
* 設定可能な通知イベント:
  * ノートブックとレポートへのコメント
  * 所有するコネクションを含むレポートやパブリックリンクの公開
  * コネクション同期ジョブの失敗時の通知

## アクセス方法

画面左下のプロフィールアイコンから`アカウント設定`を選択してください


# ワークスペース

Codatumの基本単位であるワークスペースの概念と管理について理解する

ワークスペースはCodatumを利用するための基本単位です。コネクション、ノートブック、レポートなどのリソースはすべてワークスペース内で管理され、[アクセス制御](/access-control/access-control-overview)機能を使用して、ユーザーに適切にリソースを紐付けることができます。

## 主な機能

* 基本的な管理単位:
  * ワークスペースごとにリソースを整理
  * ワークスペースごとの課金
  * 複数のワークスペースの管理
* リソース共有:
  * メンバーとリソースを共有
  * 権限設定による安全なアクセス

## ワークスペース基本設定

* ワークスペース名: あなたのワークスペースの名前
* 組織名: 契約と請求のための組織の正式名称
* 国: 請求と契約のための法的所在地
* [許可ドメイン](/workspace-and-user-management/user-management/invitation): 指定されたドメインのメールアドレスを持つユーザーのワークスペースへの参加を許可します


# ユーザー管理

ワークスペースのユーザー、グループ、アクセス権限を効率的に管理

Codatumは、ワークスペースへのアクセス管理とチーム編成のための柔軟なオプションを提供します。ご利用状況に合わせて適切な権限を設定することで、安全にワークスペースをご利用いただけます。

{% hint style="info" %}
ユーザー管理の機能は、ワークスペースオーナー権限を持つユーザーのみが利用できます。
{% endhint %}

* [招待](/workspace-and-user-management/user-management/invitation): ワークスペースにユーザーを招待する、さまざまな方法について説明します。
* [グループ](/workspace-and-user-management/user-management/group): 権限管理を効率化するための、ユーザーグループの作成と管理について説明します。
* [ワークスペースロール](/workspace-and-user-management/user-management/workspace-roles): ワークスペースで利用できる、各種ロールと権限レベルについて説明します。


# 招待

ワークスペースにユーザーを招待する様々な方法について説明します。

このページでは、チームメンバーをワークスペースに招待するための異なる方法について説明します。

## 招待方法

* 個別招待:
  * 特定のメールアドレスに招待メールを送信
  * 受信者は招待を明示的に承認して参加
  * 受信者は招待されたメールアドレス以外でも登録可能
* 許可ドメイン:
  * 許可されたドメインのメールアドレスを持つユーザーは自動的にワークスペースに参加可能
  * ドメインごとにデフォルトのロールとグループを設定
  * 他のドメインのユーザーも手動で招待可能
  * 組織メンバーのオンボーディングを効率化
* 招待リンク:
  * 共有可能なサインアップリンクを作成
  * リンク経由でサインアップしたユーザーは自動的にワークスペースに参加
  * 招待リンク経由で参加したユーザーにはワークスペースエディタロールが割り当てられる


# グループ

ワークスペース内のアクセス権限管理を効率化するユーザーグループ機能

グループは、複数のユーザーを一括管理し、リソースへのアクセス権限を効率的に割り当てることができる機能です。

## 主な機能

* 効率的なユーザー管理:
  * 複数のユーザーをグループ化
  * 部署、チーム、プロジェクトごとに整理
  * ユーザーは複数のグループに所属可能
* シンプルなアクセス制御:
  * グループレベルでの権限設定
  * ユーザー個別の権限設定を回避
  * 新規メンバーをグループに追加するだけで即座にアクセス可能
* 管理効率の向上:
  * 権限の一括変更が可能
  * 組織構造に合わせたグループ設定
  * メールドメインによるグループの自動割り当て


# ワークスペースロール

ワークスペースで利用できる、各種ロールと権限レベルについて説明します。

Codatumは、ワークスペース内でのユーザーの操作権限を制御するために、以下のロールタイプを提供しています。

* **ワークスペースオーナー**: ユーザー管理や課金を含む、ワークスペースの完全な管理権限を持ちます。
* **ワークスペースエディタ**: レポート、ノートブック、コネクションなどのコンテンツの作成や編集ができます。
* **ワークスペースビューア**: コンテンツの閲覧はできますが、編集はできません。
* **ワークスペースゲスト**: 明示的に共有された特定のリソース（レポート）にのみ、限定的にアクセスできます。

各ロールの詳細な権限と機能については、[ワークスペースのアクセス制御](/access-control/access-control-for-workspace)をご覧ください。

{% hint style="info" %}
Codatumでは、ワークスペースオーナー、ワークスペースエディタ、ワークスペースビューアを総称して「メンバー」と呼びます。ゲストロールを含める場合は「ユーザー」という総称が使用されます。この区別は重要ではありませんが、覚えておくと便利です。
{% endhint %}


# セキュリティの概要

ワークスペースのリソースへのアクセスを管理し、セキュリティ設定を行います。

セキュリティセクションでは、ワークスペースのセキュリティを強化し、誰がどこからリソースにアクセスしているかを追跡するための仕組みを提供します。

* [監査ログ](/security/audit-logs): ワークスペース内のユーザーアクションとシステムイベントの詳細な記録を確認できます。
* [IPアクセス制御 (ベータ版)](/security/ip-access-control): 特定のIPアドレスまたは範囲からのワークスペースへのアクセスを制限できます。
* [多要素認証制御 (ベータ版)](/security/multi-factor-authentication): パスワードログインユーザーの多要素認証を必須化できます。
* [パブリックリンクのモニタリング](/security/public-link-monitoring): 公開されているすべてのパブリックリンクを、作成者や共有時期を含めて確認できます。


# 監査ログ

ワークスペース内のユーザー活動とシステムイベントを監視

監査ログは、ワークスペース内で実行されたアクションの包括的な記録を提供します。誰が何をいつ行ったかを追跡でき、セキュリティ監視、コンプライアンス要件、トラブルシューティングに役立ちます。

## 主な機能

* 包括的なログ記録:
  * 重要なユーザーアクションとシステムイベント（APIベースの操作）を記録
  * ワークスペース全体の可視性を提供
* 一貫したフォーマット:
  * 各ログエントリには時間、ステータス、IPアドレス、ログ詳細が含まれます
  * ログ詳細: 以下の情報を含みます:
    * 操作（リソースの作成、更新、削除など）
    * アクションを実行したユーザー（APIキーを含む）
    * 影響を受けたリソース（ノートブック、コネクション、ワークスペースなど）
    * アクションに関連するリソース固有のプロパティ
* プライバシー保護:
  * アカウントのメールアドレスは部分的にマスク化（ドメイン部分のみ表示）
* 現在のログ範囲:
  * ログは完全なコンテンツではなく、リソースのメタデータを記録
  * 例えば、ノートブックのIDと名前は記録されますが、ノートブックの内容は記録されません
  * 注：ログに含まれる具体的なデータは今後のアップデートで変更される可能性があります
* フィルタリング機能:
  * 部分的なテキスト一致でログをフィルタリング
  * 特定のアクティビティを見つけるために結果を絞り込み
* 保持期間:
  * 監査ログは1年間保持されます

## 監査ログへのアクセス

すべてのログはワークスペース設定 > 監査ログからアクセスできます。ただし、各リソースタイプに関連する監査ログは以下の複数の場所からアクセス可能です：

* **ワークスペース設定**:
  * `基本設定` > `変更履歴`
  * `ユーザー` > `変更履歴`
  * `グループ` > `編集` > `変更履歴`
  * `チームスペース` > `編集` > `変更履歴`
  * `APIキー` > `変更履歴`
  * `コネクション` > `アクセスレベルと権限` > `編集` > `変更履歴`
* **レポート**:
  * 各レポートページ > `レポート設定` > `ログ`
* **ノートブック**:
  * 各ノートブックページ > `共有` > `パブリックリンク` > `変更履歴`

## 監査ログのカテゴリー

監査ログの操作は、アクティビティの性質を理解しやすいように6つの主要なタイプに分類されています：

* **ワークスペース管理**: ワークスペース管理に関連する操作
* **アクセス制御**: 権限設定とロール割り当てに関連する操作
* **データ権限**: データアクセス権限と設定に関する操作
* **データ閲覧**: データの閲覧とクエリに関する操作
* **コンテンツ編集**: コンテンツの変更（ノートブック、手動で書かれたコンテンツ、ファイル）に関する操作
* **コンテンツ閲覧**: 変更を伴わないコンテンツの閲覧に関する操作

## 監査ログ操作リスト

以下は、監査システムに記録される操作の一部リストです。このリストは完全ではなく、Codatumに新機能が追加されるにつれて変更される可能性があります：

| リソース        | 操作                            | ログカテゴリー       |
| ----------- | ----------------------------- | ------------- |
| ワークスペース     | ワークスペースの作成                    | ワークスペース管理     |
|             | ワークスペースの削除                    | ワークスペース管理     |
|             | ワークスペース設定の更新                  | ワークスペース管理     |
| ワークスペースユーザー | ワークスペースへのユーザー招待               | アクセス制御        |
|             | ワークスペース招待の削除                  | アクセス制御        |
|             | ワークスペース招待の再送信                 | アクセス制御        |
|             | ワークスペース招待の承認                  | アクセス制御        |
|             | ワークスペース招待の拒否                  | アクセス制御        |
|             | 招待リンクによるワークスペースへの参加           | アクセス制御        |
|             | ワークスペースへの招待リンクの生成             | アクセス制御        |
|             | 許可ドメインによるワークスペースへの参加          | アクセス制御        |
|             | ワークスペースロールの変更                 | アクセス制御        |
|             | ワークスペースからのユーザー削除              | アクセス制御        |
|             | ユーザーへの権限追加                    | アクセス制御        |
|             | ユーザーのリソースロールの変更               | アクセス制御        |
|             | ユーザーからの権限削除                   | アクセス制御        |
| グループ        | グループの作成                       | アクセス制御        |
|             | グループへのユーザー追加                  | アクセス制御        |
|             | グループからのユーザー削除                 | アクセス制御        |
|             | グループの削除                       | アクセス制御        |
|             | グループオーナーの追加                   | アクセス制御        |
|             | グループオーナーの削除                   | アクセス制御        |
|             | グループへの権限追加                    | アクセス制御        |
|             | グループの権限ロールの変更                 | アクセス制御        |
|             | グループからの権限削除                   | アクセス制御        |
| APIキー       | APIキーの作成                      | アクセス制御        |
|             | APIキーの削除                      | アクセス制御        |
|             | APIキーシークレットの取得                | アクセス制御        |
|             | APIキーシークレットの作成                | アクセス制御        |
|             | APIキーシークレットの削除                | アクセス制御        |
|             | APIキーの使用                      | データ閲覧、コンテンツ閲覧 |
| コネクション      | コネクションの作成                     | データ権限         |
|             | コネクションの削除                     | データ権限         |
|             | コネクションアクセスレベルの変更              | データ権限         |
|             | コネクションオーナーの追加                 | データ権限         |
|             | コネクションオーナーの削除                 | データ権限         |
|             | クエリジョブの実行                     | データ閲覧         |
|             | ジョブメタデータの取得                   | データ閲覧         |
|             | ジョブ結果の取得                      | データ閲覧         |
|             | ジョブ結果のダウンロード                  | データ閲覧         |
|             | クエリジョブのキャンセル                  | データ閲覧         |
|             | テーブルメタデータの取得                  | データ閲覧         |
|             | テーブル行の取得                      | データ閲覧         |
| チームスペース     | チームスペースの作成                    | アクセス制御        |
|             | チームスペースの削除                    | アクセス制御        |
|             | チームスペースオーナーの追加                | アクセス制御        |
|             | チームスペースオーナーの削除                | アクセス制御        |
| ノートブック      | ノートブックの作成                     | コンテンツ編集       |
|             | ノートブックの削除                     | コンテンツ編集       |
|             | ノートブックの名前変更                   | コンテンツ編集       |
|             | ノートブックを開く                     | コンテンツ閲覧       |
|             | ノートブックの更新                     | コンテンツ編集       |
|             | ノートブックの複製                     | コンテンツ編集       |
|             | バージョンからのノートブック復元              | コンテンツ編集       |
|             | ノートブックの移動                     | アクセス制御        |
|             | ノートブック共有権限の追加                 | アクセス制御        |
|             | ノートブック共有権限ロールの変更              | アクセス制御        |
|             | ノートブック共有権限の削除                 | アクセス制御        |
| ノートブックバージョン | ノートブックバージョンの作成                | コンテンツ編集       |
|             | ノートブックバージョンの削除                | コンテンツ編集       |
| ファイル        | メディアファイルのアップロード               | コンテンツ編集       |
|             | メディアファイルの署名付きURLの取得           | コンテンツ閲覧       |
| レポート        | レポートの閲覧                       | データ閲覧、コンテンツ閲覧 |
|             | レポートの公開                       | データ権限         |
|             | レポート変更の公開                     | データ権限         |
|             | レポートの削除                       | データ権限         |
|             | レポート共有権限の追加                   | アクセス制御        |
|             | レポート共有権限の削除                   | アクセス制御        |
|             | ゲストへのレポート共有                   | アクセス制御        |
|             | レポート招待の削除                     | アクセス制御        |
|             | レポートでのジョブメタデータの取得             | データ閲覧         |
|             | レポートでのジョブ結果の取得                | データ閲覧         |
|             | レポートでのテーブルメタデータの取得            | データ閲覧         |
|             | レポートでのテーブル行の取得                | データ閲覧         |
|             | レポートでのメディアファイル署名付きURLの取得      | データ閲覧         |
| パブリックリンク    | パブリックリンクの公開                   | データ権限         |
|             | パブリックリンク変更の公開                 | データ権限         |
|             | パブリックリンクの削除                   | データ権限         |
| 署名付き埋め込み    | 署名付き埋め込みの公開                   | データ権限         |
|             | 署名付き埋め込み変更の公開                 | データ権限         |
|             | 署名付き埋め込みの削除                   | データ権限         |
|             | 署名付き埋め込み許可オリジンの更新             | アクセス制御        |
|             | 署名付き埋め込みへのAPIキー追加             | アクセス制御        |
|             | 署名付き埋め込みからのAPIキー削除            | アクセス制御        |
|             | 署名付き埋め込みへのパラメータ追加             | アクセス制御        |
|             | 署名付き埋め込みからのパラメータ削除            | アクセス制御        |
|             | 署名付き埋め込みのトークン発行               | データ閲覧、コンテンツ閲覧 |
|             | 署名付き埋め込みを開く                   | データ閲覧、コンテンツ閲覧 |
|             | 署名付き埋め込み上でのメディアファイル署名付きURLの取得 | コンテンツ閲覧       |

## 重要な注意事項

* エクスポート機能は現在利用できません（必要な場合はサポートにお問い合わせください）


# IPアクセス制御 (ベータ版)

セキュリティ強化のため、特定のIPアドレスからのみワークスペースへのアクセスを許可

{% hint style="warning" %}
この機能は現在ベータ版で開発中の機能です。仕様については予告なく変更となる場合がございます。
{% endhint %}

IP アクセス制御を使用すると、IPアドレスに基づいてワークスペースへのアクセスを制限できます。指定されたIPアドレスまたはIPアドレス範囲からアクセスするユーザーのみがワークスペースにアクセスできるようになります。

## 設定方法

* `ワークスペース設定` > `セキュリティ` に移動
* `IPアクセス制御を有効化` のチェックボックスをオンにする
* `許可されたIPアドレス` に許可するIPアドレスを入力
* `保存` をクリックして制限を適用

## サポートされる形式

* CIDR表記（例：`192.168.1.0/24`）
* 単一のIPアドレス（例：`203.0.113.15`）
* IPv4とIPv6の両方のアドレスをサポート

## IP制限の適用範囲

IP アクセス制御は、以下のようにアクセスタイプごとに異なる影響を与えます：

* **ワークスペースのリソース**: ワークスペース内のすべてのリソース（<https://app.codatum.com/workspace/{workspaceId}/...）はIP制限の対象となります：>
  * ノートブック
  * クエリ
  * コネクション
  * ワークスペース設定
  * その他
  * **レポート**: 外部ゲストと共有されたレポートもワークスペース内に存在するため、IP制限の対象となります。
* **パブリックリンク**: インターネットユーザーと共有されたパブリックリンクはIP制限の対象外です。
* **署名付き埋め込み**: 署名付き埋め込みで埋め込まれたコンテンツはIP制限の対象外です。

## 重要な注意事項

* 変更は保存後、即座に反映されます
* 複数のIPアドレスまたは範囲を保存できます
* 変更を保存するには、指定したIPアドレスの少なくとも1つからアクセスしている必要があります（誤って自分自身をロックアウトすることを防ぐため）
* 誤ったIP制限を設定してアクセスできなくなった場合は、Codatumサポートにお問い合わせください


# 多要素認証制御 (ベータ版)

セキュリティ強化のため、ワークスペース内のユーザーに多要素認証制御を必須化する

{% hint style="warning" %}
この機能は現在ベータ版で開発中の機能です。仕様については予告なく変更となる場合がございます。
{% endhint %}

多要素認証制御を有効化すると、Passwordログイン時に多要素認証が必須化されます。

## 設定方法

* `ワークスペース設定` > `セキュリティ` に移動
* `多要素認証制御を有効化` のチェックボックスをオンにする
  * ゲストユーザーも多要素認証制御の対象としたい場合は `ゲストを含める` のチェックボックスをオンにする
* `保存` をクリックして制限を適用

## 適用範囲

* Googleでログインを選択している場合は多要素認証制御の対象となりません


# パブリックリンクのモニタリング

公開されているパブリックリンクを一覧で確認できます。

ワークスペースオーナーは、ワークスペースからリソースを共有するために作成されたすべてのパブリックリンクの完全なリストを確認できます。リストには以下の情報が含まれます：

* 共有されたリソース
* パブリックリンクの作成者
* リンクの作成日時
* 有効期限（設定されている場合）

この可視性により、共有されているすべてのコンテンツが承認され、適切であることを確認し、セキュリティを維持することができます。


# アクセス制御の概要

<figure><img src="/files/0Plf0zbzGAS7MhQwmRgp" alt=""><figcaption></figcaption></figure>

Codatumには、シンプルながら強力なロールベースのアクセス制御機構があります。

ユーザーは、ワークスペースやノートブックやコネクションなどの個々のリソースに対して、閲覧者や編集者などの役割を持つことができます。様々な操作の権限は、ユーザーが保持する役割の組み合わせに基づいて決定されます。

## **用語解説**

* **ユーザー**
  * ワークスペースに属するアカウントのこと。
* **グループ**
  * 一括で権限付与を行うことができるユーザーのグループ。1つのグループに対して、複数のリソースロールを割り当てることができます。
* **リソース**
  * Codatum内の様々なオブジェクトとその種類を表します。
  * 例: ノートブック、コネクション、チームスペース など
* **操作**
  * 個々のリソースやワークスペース全体に紐づく様々なアクションのこと。
  * 例: ユーザーの招待、ノートブックの編集 など。
* **ロール**
  * **ワークスペースロール**
    * ワークスペース内でユーザーに割り当てられるロール（すべてのユーザーに必須）です。ワークスペースレベルの操作に対する権限を決定します。
    * 例: ワークスペースオーナー → ワークスペース設定の管理やメンバー招待の権限が付与されます。
  * **リソースロール**
    * 個々のリソースに紐づくロール。グループまたは個々のユーザーに割り当てられます。
    * 例: ノートブック閲覧者 → ノートブックの閲覧権限が付与されます。
* **権限**
  * ユーザーまたはグループに割り当てられた、リソースロールまたはワークスペースロールの組み合わせによって、該当するリソースやワークスペースに関連する特定の操作を実行する権限が付与されます。

## アクセス制御ルールの基本

アクセス権は、定義された評価方法に従い、ユーザーが保持するロールの組み合わせに基づいて決定されます。

* ロールには階層性があり、下位のロールがアクセス権を持つ場合、上位のロールもそのアクセス権を持ちます。
* 操作が許可されるためには、ワークスペースロールとリソースロールの両方のロールがアクセスを許可する必要があります（ANDで評価されます）。
* ユーザーが同じリソースに対して複数のリソースロールを持つ場合（直接割り当てられているか、グループ経由で割り当てられているかに関わらず）、いずれかのリソースロールがアクセスを許可していれば、権限が付与されます（ORで計算されます）。

以下の概念図では、これらの原則を示しています。

<figure><img src="/files/iuokSMYOpLgKp72bQ1pX" alt=""><figcaption></figcaption></figure>

この図は、特定のリソースAに紐づけられた操作のパターンを示しています。

また、ワークスペースにのみ紐づけられ、特定のリソースにはリンクされない操作のパターンもあります。このパターンはより単純で、以下のように示されます。

<figure><img src="/files/6KB9h8rHStAH49LkCS9L" alt=""><figcaption></figcaption></figure>

このパターンでは、アクセス権はワークスペースロールのみによって決定されます。

これらの原則により、Codatum内で堅牢で柔軟なアクセス制御システムが実現されています。


# ワークスペースのアクセス制御

ワークスペースのロール、操作、アクセス制御ルール。

<figure><img src="/files/hEWkFjQsnv8BJ6XnbOYm" alt=""><figcaption></figcaption></figure>

## ワークスペースのロール

ワークスペースロールには4つのレベルがあります：

| ロール名                            | 説明                     | 概要                                                      |
| ------------------------------- | ---------------------- | ------------------------------------------------------- |
| <p>オーナー</p><p>(ワークスペースオーナー)</p> | ワークスペースを管理する権限を持つアカウント | ワークスペース設定の変更や、新しいメンバーのワークスペースへの招待ができます。                 |
| <p>エディタ</p><p>(ワークスペースエディタ)</p> | 複数のリソースを編集する権限を持つアカウント | ノートブックの編集やコネクションの作成ができます。ワークスペース設定の変更や新しいメンバーの招待はできません。 |
| <p>ビューア</p><p>(ワークスペースビューア)</p> | 複数のリソースを閲覧する権限を持つアカウント | ノートブックを閲覧できます。ノートブックの編集やコネクションの作成はできません。                |
| <p>ゲスト</p><p>(ワークスペースゲスト)</p>   | レポートのみに対する権限を持つアカウント   | <p>共有されたレポートのみを閲覧できます。<br>ゲストはどのグループにも所属できません。</p>      |

{% hint style="info" %}
Codatumでは、オーナー、エディタ、ビューアを総称して「メンバー」と呼びます。ゲストのロールを含める場合は、総称として「ユーザー」が使用されます。この区別は重要ではありませんが、覚えておくと役立つかもしれません。
{% endhint %}

## ワークスペースの操作とアクセス制御ルール

ここでは、ワークスペースで実行できる具体的なアクションと、それらを実行するために必要なロールについて詳しく説明します。

| 操作                                          | カテゴリ    | 必要なワークスペースロール |
| ------------------------------------------- | ------- | ------------- |
| <p>ユーザーの招待と削除</p><p>ユーザーアカウントのロールの変更</p>    | ユーザー    | ワークスペースオーナー   |
| 行動ログとユーザーアクティビティ履歴の閲覧                       | 行動ログ    | ワークスペースオーナー   |
| ワークスペースに関する情報の閲覧                            | ワークスペース | ワークスペースビューア   |
| すべてのグループの情報の閲覧                              | グループ    | ワークスペースビューア   |
| <p>グループの作成、削除、編集</p><p>グループへのユーザーの追加と削除</p> | グループ    | ワークスペースオーナー   |


# リソースのアクセス制御

各種リソースのアクセス制御

ここでは、リソースに関連するロール、操作、およびアクセス制御ルールについて説明します。アクセス制御に関連するリソースには、グループ、チームスペース、ノートブック、コネクション、レポートの5種類があります。

{% content-ref url="/pages/MHT12FcXTTUyvsOtx2hq" %}
[グループのアクセス制御](/access-control/access-control-for-resources/access-control-for-group)
{% endcontent-ref %}

{% content-ref url="/pages/JvEREJwo17POkWWey617" %}
[チームスペースのアクセス制御](/access-control/access-control-for-resources/access-control-for-teamspace)
{% endcontent-ref %}

{% content-ref url="/pages/qEFyuTXQEC8dPJq7XnSB" %}
[ノートブックのアクセス制御](/access-control/access-control-for-resources/access-control-for-notebook)
{% endcontent-ref %}

{% content-ref url="/pages/n6rLKzfTI7ZPWzQt41sL" %}
[コネクションのアクセス制御](/access-control/access-control-for-resources/access-control-for-connection)
{% endcontent-ref %}

{% content-ref url="/pages/FfZCsYDgnCMT6p3oZlWw" %}
[レポートのアクセス制御](/access-control/access-control-for-resources/access-control-for-report)
{% endcontent-ref %}


# グループのアクセス制御

グループのロール、操作、アクセス制御ルール。

## グループのリソースロール

以下のロールは、ユーザーがグループに対して実行できる操作を決定します。

| ロール名     | 概要                              |
| -------- | ------------------------------- |
| グループオーナー | ワークスペースオーナーのロールがなくてもグループを管理できます |
| グループメンバー | -                               |

## グループの操作とアクセス制御ルール

以下は、グループを管理するために実行できる操作と、それらを実行するために必要なロールです。

| 操作                                                    | 必要なロール                            |
| ----------------------------------------------------- | --------------------------------- |
| ワークスペース内のグループ一覧を表示する                                  | ワークスペースビューア                       |
| ワークスペースにグループを追加する                                     | ワークスペースオーナー                       |
| <p>グループを削除する<br>グループの設定を編集する<br>グループにメンバーを追加・削除する</p> | <p>ワークスペースオーナー<br>OR グループオーナー</p> |


# チームスペースのアクセス制御

チームスペースのロール、操作、アクセス制御ルール。

## チームスペースのリソースロール

チームスペースオーナーのロールはチームスペース編集者/閲覧者ロールとは別であり、互いに排他的ではありません。ロールが重複する場合、より高い権限を持つロールが優先されます。

| ロール名        | 概要                                 |
| ----------- | ---------------------------------- |
| チームスペースオーナー | ワークスペースオーナーのロールがなくてもチームスペースを管理できます |
| チームスペース編集者  | チームスペース内のノートブックとフォルダを編集できます        |
| チームスペース閲覧者  | チームスペース内のノートブックとフォルダを閲覧できます        |

## チームスペースの操作とアクセス制御ルール

以下は、チームスペースを管理するために実行できる操作と、それらを実行するために必要なロールです。

| 操作                                                                      | 必要なロール                                                       |
| ----------------------------------------------------------------------- | ------------------------------------------------------------ |
| すべてのチームスペース名の取得                                                         | ワークスペースビューア                                                  |
| チームスペースの作成                                                              | ワークスペースエディタ                                                  |
| <p>チームスペースの名前を変更<br>チームスペースオーナーの追加・削除<br>チームスペースの削除<br>チームスペースの権限変更</p> | <p>ワークスペースオーナー<br>OR (ワークスペースビューア<br>AND チームスペースオーナー) \*</p> |

\*: ユーザーがワークスペースビューアであっても、該当するチームスペースのチームスペースオーナーである場合、この操作を実行できます


# ノートブックのアクセス制御

ノートブックのアクセススコープ、ロール、操作、アクセス制御ルール。

## ノートブックのアクセススコープ

ノートブックのアクセス制御は、ノートブックの所属する（ルート）フォルダによって決まります。ノートブックには次の4種類のアクセススコープがあります。

| スコープ        | 説明                                           |
| ----------- | -------------------------------------------- |
| ワークスペース     | ワークスペース内の全てのユーザーがアクセスできます。                   |
| チームスペース     | チームスペースに所属するユーザーがアクセスできます。                   |
| プライベート      | 所有者のユーザーのみがアクセスできます                          |
| 共有されたノートブック | ノートブックごとの追加権限により、権限を付与されたユーザー・グループがアクセスできます。 |

## ノートブックのリソースロール

以下のロールは、ユーザーがノートブックで実行できる操作を決定します。

| ロール名      | 概要            |
| --------- | ------------- |
| ノートブック編集者 | ノートブックを編集できます |
| ノートブック閲覧者 | ノートブックを閲覧できます |

## ノートブックの操作とアクセス制御ルール

以下は、ノートブックで実行できる操作と、各スコープで必要なロールです。

{% hint style="warning" %}
ノートブックにあるSQLの実行やその結果取得は、ノートブックそのもののアクセス権ではなく、コネクションのアクセス権によって決まります。詳細については、[コネクションのアクセス制御](/access-control/access-control-for-resources/access-control-for-connection)を参照してください。
{% endhint %}

{% hint style="warning" %}
チームスペース内にあるノートブックへの権限は、チームスペースで付与されている権限によって決まります。詳細については、[チームスペースのアクセス制御](/access-control/access-control-for-resources/access-control-for-teamspace)を参照してください。
{% endhint %}

<table data-full-width="true"><thead><tr><th>操作</th><th>スコープ: ワークスペース</th><th>スコープ: チームスペース</th><th>スコープ: プライベート</th><th>スコープ: 共有されたノートブック</th></tr></thead><tbody><tr><td><p>コンテンツの閲覧</p><p>コメント</p></td><td>ワークスペースビューア</td><td>ワークスペースビューア<br>AND チームスペース閲覧者</td><td>ワークスペースエディタ</td><td>ワークスペースビューア<br>AND ノートブック閲覧者</td></tr><tr><td>ノートブックの編集</td><td>ワークスペースエディタ</td><td>ワークスペースエディタ<br>AND チームスペース編集者</td><td>ワークスペースエディタ</td><td>ワークスペースエディタ<br>AND ノートブック編集者</td></tr><tr><td><p>ノートブックの移動・削除</p><p>フォルダーの編集・削除</p></td><td>ワークスペースエディタ</td><td>ワークスペースエディタ<br>AND チームスペース編集者</td><td>ワークスペースエディタ</td><td>N/A</td></tr><tr><td>ユーザーやグループへの共有</td><td>N/A</td><td>ワークスペースビューア<br>AND チームスペース編集者</td><td>ワークスペースエディタ</td><td>N/A</td></tr></tbody></table>


# コネクションのアクセス制御

コネクションのロール、操作、アクセス制御ルール。

## コネクションのアクセスレベル

コネクションのアクセス制御は、アクセスレベルによって異なります。コネクションには3種類のアクセスレベルがあります：

| レベル     | 説明                                                                              |
| ------- | ------------------------------------------------------------------------------- |
| ワークスペース | ワークスペース内の全てのユーザーがアクセスできます。                                                      |
| 限定公開    | <p>アクセス権を付与されたユーザーのみがアクセスできます。<br>ワークスペースオーナーは権限を編集できます。</p>                    |
| プライベート  | <p>アクセス権を付与されたユーザーのみがアクセスできます。<br>ワークスペースオーナーでも権限を編集<strong>できません</strong>。</p> |

## コネクションのリソースロール

以下のロールは、ユーザーがコネクションで実行できる操作を決定します。

| ロール名       | 概要                                                        |
| ---------- | --------------------------------------------------------- |
| コネクションオーナー | コネクションの編集、削除、権限設定の変更が可能                                   |
| コネクション利用者  | <p>クエリの実行、クエリ実行結果とテーブルの閲覧が可能<br>コネクションに関連するレポートの公開が可能</p> |
| コネクション閲覧者  | クエリ実行結果とテーブルの閲覧が可能                                        |

## コネクションの操作とアクセス制御ルール

以下は、コネクションで実行できる操作と、各レベルで必要なロールです。

<table data-full-width="true"><thead><tr><th>操作</th><th>レベル: "ワークスペース"</th><th>レベル: "限定公開"</th><th>レベル: "プライベート"</th></tr></thead><tbody><tr><td>コネクションの作成</td><td>ワークスペースエディタ</td><td>ワークスペースエディタ</td><td>ワークスペースエディタ</td></tr><tr><td>コネクション名のリスト表示</td><td>ワークスペースビューア</td><td>ワークスペースビューア</td><td>ワークスペースビューア<br>AND コネクション閲覧者</td></tr><tr><td>コネクションの編集と削除</td><td>ワークスペースオーナー<br>OR コネクションオーナー</td><td>ワークスペースオーナー<br>OR (ワークスペースビューア<br>AND コネクションオーナー)</td><td>ワークスペースビューア<br>AND コネクションオーナー</td></tr><tr><td>コネクションの権限設定の変更</td><td>ワークスペースオーナー<br>OR コネクションオーナー</td><td>ワークスペースオーナー<br>OR (ワークスペースビューア<br>AND コネクションオーナー)</td><td>ワークスペースエディタ<br>AND コネクションオーナー</td></tr><tr><td>SQLの実行<br>実行結果のダウンロード</td><td>ワークスペースエディタ</td><td>ワークスペースエディタ<br>AND コネクション利用者</td><td>ワークスペースエディタ<br>AND コネクション利用者</td></tr><tr><td>SQL実行結果とテーブル情報の取得</td><td>ワークスペースビューア</td><td>ワークスペースビューア<br>AND コネクション閲覧者</td><td>ワークスペースビューア<br>AND コネクション閲覧者</td></tr></tbody></table>


# レポートのアクセス制御

レポートのロール、操作、アクセス制御ルール。

## レポートのリソースロール

レポートは読み取り専用のため、閲覧権限のみが存在します。また、レポート内のSQLの実行やその実行結果の取得は、コネクションの権限ではなく、レポートの権限に付随します。

| ロール名    | 概要                                           |
| ------- | -------------------------------------------- |
| レポート閲覧者 | レポートを閲覧でき、レポートが更新実行を許可している場合はクエリ実行結果を更新できます。 |

## レポートの操作とアクセス制御ルール

| 操作                        | 必要なロール  |
| ------------------------- | ------- |
| <p>レポートの表示</p><p>コメント</p> | レポート閲覧者 |

レポートの公開に関連する操作は、レポートの元となるノートブックのアクセススコープの影響を受けます。

<table data-full-width="true"><thead><tr><th>操作</th><th>スコープ: ワークスペース</th><th>スコープ: チームスペース</th><th>スコープ: プライベート</th><th>スコープ: 共有されたノートブック</th></tr></thead><tbody><tr><td><p>レポートを公開</p><p>レポートの権限を変更</p></td><td>ワークスペースエディタ<br>AND コネクション利用者 *</td><td>ワークスペースエディタ<br>AND チームスペース編集者<br>AND コネクション利用者 *</td><td>ワークスペースエディタ<br>AND コネクション利用者 *</td><td>N/A</td></tr><tr><td>レポートを削除</td><td>ワークスペースエディタ</td><td>ワークスペースエディタ<br>AND チームスペース編集者</td><td>ワークスペースエディタ</td><td>N/A</td></tr><tr><td>レポート設定を編集</td><td>ワークスペースエディタ</td><td>ワークスペースエディタ<br>AND チームスペース編集者</td><td>ワークスペースエディタ</td><td>N/A</td></tr></tbody></table>

\*: 公開対象のページに含まれるすべてのコネクションについて、コネクション利用者のロールが必要になります。


# Codatum CLI

ローカル環境からAIエージェントと共同でCodatumを操作できるコマンドラインツール

{% hint style="warning" %}
この機能は現在ベータ版です。仕様については予告なく変更となる場合がございます。
{% endhint %}

Codatum CLIは、Codatumの機能をローカル環境からAIエージェントと共同で操作できるコマンドラインツールです。

ノートブックの取得・編集・実行・反映から、SQLの実行、データソースの検索まで、ブラウザを開かなくてもコマンドラインだけで一通り完結できます。ノートブックはマークダウン形式（`.cnb.md`）のプレーンテキストファイルとして取得できるため、使い慣れたエディタで編集し、Gitでバージョン管理し、Pull Requestでレビューする——そんな「BI as Code」のワークフローが可能になります。

また、Cursor・Claude CodeなどのAIエージェントとの連携を前提に設計されており、Codatumの仕様をエージェントが直接参照できるため、ノートブックの編集を安心して任せることができます。

インストール方法や各コマンドの詳細は、Codatum CLIドキュメントをご覧ください。

{% embed url="<https://cli-docs.codatum.com/>" %}


# AIエージェント (ベータ版)

データや業務情報を横断的に探索し、調査・分析・外部サービスとの連携を支援するAIエージェント

{% hint style="warning" %}
この機能は現在ベータ版です。仕様については予告なく変更となる場合があります。
{% endhint %}

Codatum Agentは、Codatum上のデータやナレッジ、外部サービスを横断し、自然言語で調査・分析・業務上の操作を進めるためのAIエージェントです。カタログ、Notebook、Web、連携先サービスなどのコンテキストを参照し、目的に応じて必要な情報とツールを選択します。

Notebookの作成・編集は、分析結果や調査内容を整理して共有するためにCodatum Agentが利用できる手段の一つです。

## 主な機能

* テーブルやカラムの探索
* SQLの作成と実行
* 実行結果の分析
* Notebookの作成・編集
* SQLブロックやチャートの追加・編集
* Notebook、テーブル、保存済みクエリなどの参照
* Web検索とWebページの取得
* [エージェントコネクタ](/codatum-ai/agent-connector)を利用した外部サービスとの連携

利用できる機能は、ユーザーの権限、選択したAIプロファイル、操作モード、現在表示している画面によって異なります。

## 利用条件と有効化

Codatum Agentは、AIエージェント機能を利用できるプランで提供されます。ワークスペース管理者が`ワークスペース設定` > `オプション` > `Codatum AI`でAIエージェントを有効にすると利用できます。

AIエージェントが使用するモデルや権限は[AIプロファイル](/codatum-ai/ai-profile)で設定します。

## 表示モード

### サイドパネル

画面上のAIエージェントアイコンから開きます。Notebookを表示している場合は、現在のNotebookやページをコンテキストとして利用できます。

### フルページ

AIエージェントを独立した画面で表示します。特定のNotebookを起点としないデータ探索や、長い会話を確認する場合に利用できます。

サイドパネルとフルページでは、同じチャットセッションを継続できます。

## 操作モード

### Askモード

クエリの実行を含むデータ分析を行いますが、Notebookの作成・編集は行いません。Notebookを変更せずにデータを調べる場合に使用します。

### Agentモード

Askモードで利用できる操作に加えて、Notebookの作成・編集、SQLブロックやチャートの追加などを行います。

Notebookの書き込み権限がないユーザーはAskモードに固定されます。

## コンテキスト

Codatum Agentは、次の情報をコンテキストとして利用します。

* 現在表示しているページとNotebook
* メッセージ内で`@`を使って指定したテーブル、Notebook、保存済みクエリ
* 現在のNotebookで指定できるSQLブロックやチャート
* 自動読み込みされるエージェントコンテキスト
* AIプロファイルに設定された補足情報、Notebook、フォルダ

入力欄のコンテキスト使用量を開くと、自動読み込みされるコンテキストと使用量を確認できます。エージェントコンテキストの読み込み条件と推奨構成については、[エージェントコンテキスト](/codatum-ai/agent-context)を参照してください。

## 権限

Codatum Agentが実行できる操作は、次の条件をすべて満たす範囲に制限されます。

1. **ユーザーのアクセス権限**
   * ユーザーが閲覧または編集できるNotebook、テーブル、コネクションだけを利用できます。
2. **操作モード**
   * AskモードではNotebookを作成・編集するツールを利用できません。
3. **AIプロファイルの権限**
   * Notebookの参照範囲、利用可能なコネクション、Web検索・Webページ取得のドメイン、エージェントコネクタを制限できます。
4. **ツール実行時の承認**
   * SQLや外部サービスの操作について、実行前の確認を必須にできます。

AIプロファイルの権限は、ユーザー自身のアクセス権限を拡張するものではありません。

## ツール実行と承認

SQLの実行、MCPツールの実行、エージェントコネクタからのHTTPリクエストでは、実行前に承認を求める場合があります。

ユーザー設定では、次の操作の自動承認を設定できます。

* SQL実行
  * 全コネクション共通またはコネクション単位で設定できます。
  * BigQueryでは、ドライラン結果に基づく最大スキャンサイズを設定できます。
* `MCPツール実行`
* `Connector HTTPリクエスト`

{% hint style="warning" %}
自動承認を有効にすると、確認操作を挟まずにクエリや外部サービスの操作が実行されます。AIプロファイルの権限と接続先の権限を確認したうえで設定してください。
{% endhint %}

## Agent画面と設定

Agent画面では、次の操作ができます。

* 新しいチャットの開始
* 過去のチャット履歴の表示
* セッションの開始時刻やトークン使用量の確認
* サイドパネルとフルページの切り替え
* Codatumチームへのフィードバック送信

入力欄の設定メニューでは、次の項目を変更できます。

* AskモードとAgentモード
* 優先的に利用するコネクション
* SQL、MCPツール、Connector HTTPリクエストの自動承認
* 個人、チームスペース、Notebookのエージェントコンテキストの自動読み込み
* AIプロファイル
* 応答言語
* Enterキーの動作

異なる目的の分析を始める場合は、新しいチャットを開始することで、不要な会話履歴によるコンテキスト使用量の増加を避けられます。

## 利用状況

ワークスペース管理者は、`ワークスペース設定` > `エージェント利用状況`で、セッション数やトークン使用量などを確認できます。利用状況データの保持期間は30日です。

AIプロファイルで会話メッセージのログ保存が無効になっている場合、利用状況には統計情報が記録されますが、メッセージ本文は表示されません。

## データの取り扱い

Codatumが利用する外部LLMサービスは、送信されたデータをモデルの学習に使用しないことを規約で保証しています。

AIエージェントが分析や処理を行うため、次の情報が選択したLLMサービスへ送信される場合があります。

* 入力したメッセージ
* Notebookやページの内容
* `@`で指定した参照情報
* テーブルのスキーマやデータ
* SQLの実行結果
* エージェントコンテキスト

Codatum開発者は、品質改善のために利用日時、ユーザー・ワークスペースの識別情報、エラー、トークン使用量の目安、処理時間を記録します。入力・応答の本文、`@`で追加した参照情報、SQLの実行結果、データソースの実データは記録しません。

ご利用にあたっては、お客様の社内AI利用ポリシーをご確認ください。

## 関連ページ

* [エージェントコンテキスト](/codatum-ai/agent-context)
* [エージェントコネクタ](/codatum-ai/agent-connector)
* [AIプロファイル](/codatum-ai/ai-profile)


# エージェントコンテキスト

AIエージェントへ自動的に読み込まれる前提情報や、AIプロファイルに設定するコンテキストの仕様

エージェントコンテキストは、Codatum Agentへ自動的に渡す前提情報です。指標の定義、参照すべきNotebook、分析時の注意事項などを登録することで、毎回のメッセージに同じ説明を入力せずに利用できます。

{% hint style="info" %}
エージェントコンテキストはアクセス権限を変更する機能ではありません。Codatum Agentが参照できる情報と実行できる操作は、利用するユーザーと[AIプロファイル](/codatum-ai/ai-profile)の権限範囲に制限されます。
{% endhint %}

## コンテキストの種類

Codatum Agentでは、次のコンテキストを自動的に読み込みます。

| 種類       | 設定場所                                    | 読み込まれる条件                    |
| -------- | --------------------------------------- | --------------------------- |
| 個人       | プライベートフォルダ直下の`.agent`フォルダ               | Codatum Agentの利用時           |
| チームスペース  | チームスペース直下の`.agent`フォルダ                  | そのチームスペース内のNotebookを開いている場合 |
| Notebook | Notebook内の`.agent`ページ                   | そのNotebookを開いている場合          |
| AIプロファイル | AIプロファイルの補足情報、コンテキストNotebook、コンテキストフォルダ | そのAIプロファイルを利用している場合         |

プライベートフォルダとチームスペースの`.agent`フォルダでは、サブフォルダを含むすべてのNotebookが読み込まれます。AIプロファイルにフォルダを設定した場合も、サブフォルダを含むすべてのNotebookが読み込まれます。

## `.agent`フォルダ

プライベートフォルダまたはチームスペースのルートで追加メニューを開き、`新規エージェントコンテキストフォルダ`を選択すると、`.agent`フォルダと`Agent Context Index`ノートブックが作成されます。作成されたノートブックには、後述する推奨構成のテンプレートが入力されています。

`.agent`フォルダは次の場所に作成できます。

* プライベートフォルダの直下
* チームスペースの直下

ワークスペースフォルダの直下や、通常のサブフォルダ内には作成できません。

`.agent`フォルダ内のNotebookには、文章だけでなく、SQLブロックや保存済みの実行結果を含めることができます。SQLブロックを使用すると、指標の算出方法や標準クエリをコンテキストとして渡せます。

## Notebookの`.agent`ページ

Notebook内に`.agent`という名前のページを作成すると、そのNotebookを表示している場合にページの内容が読み込まれます。

Notebook固有の前提や注意事項には`.agent`ページを使用し、個人またはチーム共通の情報には`.agent`フォルダを使用します。

## AIプロファイルのコンテキスト

AIプロファイルには、次のコンテキストを設定できます。

* 補足情報
* コンテキストNotebook
* コンテキストフォルダ

コンテキストNotebookまたはフォルダを参照するには、利用するユーザーに対象の閲覧権限が必要です。参照できないNotebookが含まれるAIプロファイルは利用できません。

チームスペース内にコンテキスト専用のNotebookやフォルダを作成すると、チームスペースの権限によって編集者と閲覧者を管理できます。

## 自動読み込みの設定

Agent画面の入力欄にある設定メニューから、次のエージェントコンテキストを種類ごとに自動読み込みするか設定できます。

* 個人
* チームスペース
* Notebook

AIプロファイルに設定されたコンテキストは、選択したAIプロファイルの設定として読み込まれます。

入力欄のコンテキスト使用量を開くと、現在自動読み込みの対象になっているNotebookやページを確認できます。

## 常時読み込みと必要時の参照

遅延読み込みを有効にする設定項目はありません。常時読み込む情報と必要な場合だけ参照する情報は、Notebookの配置とAIプロファイルへの紐付けによって分けます。

| 読み込み方                  | 設定                                                              | 動作                                                           |
| ---------------------- | --------------------------------------------------------------- | ------------------------------------------------------------ |
| 個人のコンテキストを常時読み込む       | プライベートフォルダ直下の`.agent`フォルダにNotebookを配置し、自動読み込みの`個人`を有効にする        | Codatum Agentの実行時に、フォルダとサブフォルダ内のすべてのNotebookを読み込みます          |
| チームスペースのコンテキストを読み込む    | チームスペース直下の`.agent`フォルダにNotebookを配置し、自動読み込みの`チームスペース`を有効にする      | そのチームスペースのNotebookを開いている場合に、フォルダとサブフォルダ内のすべてのNotebookを読み込みます |
| Notebook固有のコンテキストを読み込む | Notebookに`.agent`ページを作成し、自動読み込みの`Notebook`を有効にする                | そのNotebookを開いている場合に`.agent`ページを読み込みます                        |
| AIプロファイルで常時読み込む        | AIプロファイルのプレーンテキスト、コンテキストNotebook、コンテキストフォルダに設定する                | そのAIプロファイルを使用するたびに読み込みます。フォルダを設定した場合はサブフォルダ内のNotebookも対象です   |
| 必要な場合だけ参照する            | Indexだけを上記のいずれかへ配置し、詳細なNotebookは通常のフォルダへ配置して、Indexから対象ページへリンクする | Indexは自動的に読み込み、詳細なNotebookは質問に応じてリンクから参照します                  |

自動読み込みの`個人`、`チームスペース`、`Notebook`を無効にすると、該当するコンテキストは自動的に読み込まれません。無効化は遅延読み込みへの切り替えではありません。また、この設定はAIプロファイルに設定されたコンテキストには適用されません。

必要時に詳細なNotebookを参照させるには、利用するユーザーが対象を閲覧でき、AIプロファイルのNotebookアクセスが`権限のある全てのノートブック`に設定されている必要があります。`表示中のノートブックのみ`の場合、現在のNotebook外に配置した詳細情報は参照できません。

## 推奨構成

`.agent`フォルダには詳細なナレッジを直接集約せず、必要な情報を探すためのIndexノートブックだけを置くことを推奨します。

`.agent`フォルダ内のNotebookはAgent実行時に自動読み込みされます。詳細な仕様や過去の分析を大量に配置すると、質問に関係のない情報にもコンテキストを使用し、必要な情報を判断しにくくなります。

詳細情報は通常のNotebookやフォルダに配置し、Indexノートブックには次の情報を記載します。

* どのような情報が存在するか
* どのような質問で参照するか
* 正本となるNotebookのページリンク
* Notebookの保存場所
* 検索に利用できるキーワード
* 情報が見つからない場合や判断できない場合の扱い

この構成では、Codatum Agentは最初にIndexだけを読み込み、質問に必要なページのリンクから詳細を参照できます。

{% hint style="warning" %}
参照先には、Notebook名だけでなく対象ページへのリンクを必ず設定してください。Notebook名や保存場所だけでは、Codatum Agentが`.agent`フォルダ外のページを直接特定できず、検索結果に依存します。対象ページをCodatumで開き、ページのURLをコピーしてIndexへリンクとして挿入します。
{% endhint %}

### Indexノートブックの構成例

```markdown
# Agent Context Index

## 共通ルール

* 指標の定義は「KPI定義」Notebookを正本とする
* 定義が見つからない場合は推測せず、ユーザーへ確認する
* SQLを作成する前に対象期間とタイムゾーンを確認する

## Knowledge Map

### 売上・受注

* 参照先: [売上・受注指標](https://app.codatum.com/workspace/WORKSPACE_ID/notebook/NOTEBOOK_ID/PAGE_ID)
* 保存場所: チームスペース「Data Knowledge」
* 利用する場面: 売上、受注、キャンセルに関する分析
* 検索キーワード: 売上、受注、キャンセル、GMV

### 顧客

* 参照先: [顧客定義](https://app.codatum.com/workspace/WORKSPACE_ID/notebook/NOTEBOOK_ID/PAGE_ID)
* 保存場所: チームスペース「Data Knowledge」
* 利用する場面: 新規顧客、既存顧客、継続率に関する分析
* 検索キーワード: 顧客、新規、既存、継続率
```

例の`WORKSPACE_ID`、`NOTEBOOK_ID`、`PAGE_ID`は、実際の対象ページのURLに置き換えます。リンクに加えてチームスペース名やフォルダ名も記載すると、参照先の目的と管理場所を判断しやすくなります。

## 避ける構成

次のような構成は推奨されません。

* `.agent`フォルダへ詳細な仕様書や過去の分析をすべて配置する
* 同じ指標の定義を複数のコンテキストへ重複して記載する
* 正本や参照先を示さず、要約だけを記載する
* 更新日や適用範囲が不明なルールを記載する
* コンテキストによってアクセス権限やツール実行範囲を制御しようとする

アクセス範囲や利用できるツールは、Notebook・チームスペースのアクセス権限とAIプロファイルの権限で設定してください。

## 関連ページ

* [Codatum Agent](/codatum-ai/ai-agent)
* [AIプロファイル](/codatum-ai/ai-profile)


# エージェントコネクタ

CodatumのAIエージェントから外部サービスのAPIやMCPサーバーに接続するための機能です。

エージェントコネクタは、CodatumのAIエージェントからGitHubやSlack、Notionなど外部サービスのAPIやMCP（Model Context Protocol）サーバーに接続するための機能です。あらかじめ用意された組み込みコネクタを選ぶだけで設定できるほか、任意のMCPサーバーやREST/GraphQL APIをカスタムコネクタとして登録することもできます。

## 主な機能

* 組み込みコネクタの追加:
  * GitHub、Slack、Notion、Atlassian（Jira/Confluence）、Salesforce、HubSpot、Linear、Airtable、PagerDuty、Sentry、Stripe、Datadog、dbt Cloud、Google Drive、Workatoなど、あらかじめ用意されたコネクタから選んで追加できます。
* カスタムコネクタの追加:
  * 組み込み以外のMCPサーバーや、独自のREST/GraphQL APIエンドポイントをコネクタとして登録できます。
* 認証情報の管理:
  * ワークスペース共通、またはユーザー個人単位で認証情報（OAuth・APIキーなど）を設定できます。
* 利用可能なツールの確認:
  * MCP型のコネクタでは、接続先から取得したツール一覧を確認できます。
* AIプロファイル単位でのアクセス制御:
  * AIプロファイルごとに、コネクタへのアクセスを「オフ」「選択したコネクタのみ許可」「全てのコネクタ」から設定できます。

## 種類

コネクタには2つの種別があります。

### MCP

外部のMCPサーバーに接続し、そのサーバーが提供するツールをAIエージェントが検索・実行します。Notion、Atlassian、Salesforce、Sentry、Stripeなど、MCPサーバーを提供しているサービスで利用します。

### Direct API

REST/GraphQL形式の外部APIに、登録したAPIキーなどを使って直接リクエストを送ります。

{% hint style="info" %}
GitHubはMCPサーバーとしてではなく、GitHub REST APIに直接アクセスするDirect API型のコネクタとして組み込まれています。GitHubのPersonal Access Tokenなどを認証情報として登録してご利用ください。
{% endhint %}

## 組み込みコネクタ一覧

| コネクタ             | 種別         | 概要                                                  |
| ---------------- | ---------- | --------------------------------------------------- |
| GitHub API       | Direct API | リポジトリ・Issue・Pull Request・ユーザー・Organizationの情報を取得します |
| Slack Web API    | Direct API | チャンネル・メッセージ・ユーザーなどを操作します                            |
| HubSpot API      | Direct API | CRMのコンタクト・会社・取引・チケットなどの情報を取得します                     |
| Linear API       | Direct API | Issue・プロジェクト・チーム・サイクルなどを取得します                       |
| Airtable API     | Direct API | Base・Table・Record・Fieldなどの業務データを取得します               |
| PagerDuty API    | Direct API | インシデント・サービス・オンコール予定などを取得します                         |
| Notion MCP       | MCP        | Notionワークスペースの検索・ページ操作・コンテンツ編集を行います                 |
| Atlassian MCP    | MCP        | JiraのIssueやConfluenceのナレッジベースに接続します                 |
| Salesforce MCP   | MCP        | Salesforceのレコードやクエリに接続します                           |
| Sentry MCP       | MCP        | Issue・プロジェクト・イベントなどのデバッグ情報に接続します                    |
| Stripe MCP       | MCP        | 顧客・請求・支払いなどの操作を行います                                 |
| Datadog MCP      | MCP        | ログ・メトリクス・トレース・インシデントなどに接続します                        |
| dbt Cloud MCP    | MCP        | Semantic Layer・Discovery・開発コンテキストに接続します             |
| Google Drive MCP | MCP        | Google Driveのファイルやドキュメントに接続します                      |
| Workato MCP      | MCP        | レシピ由来のツールや業務自動化コンテキストに接続します                         |

## 設定方法

1. 「ワークスペース設定」＞「エージェントコネクタ」から「コネクタを追加」を選択します。
2. 組み込みコネクタから選ぶか、カスタムコネクタ（MCPサーバーのURL、またはAPIのエンドポイント）を設定します。
3. 認証スコープ（ワークスペース共通／個人）を選択します。
4. 「コネクタ認証」画面で、対象コネクタの認証（OAuth連携、またはAPIキーなどのシークレットの入力）を行います。
5. 「AIプロファイル」の権限設定（コネクタアクセス）で、対象のAIプロファイルにこのコネクタへのアクセスを許可します。

設定が完了すると、AIエージェントが会話の中で必要に応じて対象のツールやAPIを検索・実行します。

## 実行時の承認

コネクタ経由でのツール実行やAPIリクエストは、既定では実行前にユーザーの承認を求めます。ユーザー設定から「MCPツール実行」「Connector HTTPリクエスト」を自動承認するように変更することも可能です。

{% hint style="warning" %}
コネクタが実行する操作の内容をよく確認したうえで承認してください。承認内容によっては外部サービス側のデータが変更される場合があります。
{% endhint %}

## 制限事項

* MCPコネクタのサーバーURLは、作成後に変更できません。変更する場合はコネクタを削除して再登録してください。
* コネクタへのアクセスは、AIプロファイルの権限設定で明示的に許可されている必要があります（既定は「オフ」）。
* 外部への接続には、社内ネットワークなど意図しない宛先への誤接続を防ぐための制限が適用されます。


# AIプロファイル

AIエージェントで利用するAIモデルのプロファイルを設定する機能

## 概要

AIプロファイルは、Codatum Agentで使用するAIモデル、コンテキスト、ツール権限などをまとめた設定です。用途ごとにAIプロファイルを作成し、Agent画面で切り替えて利用できます。

## 種類

### Managed AI Profile

Codatumが管理するAIモデルを使用します。APIキーの設定は不要です。使用するモデルの種類を選択できます。

AIプロバイダーやエンドポイントは指定できません。セキュリティ要件などにより利用するプロバイダーや認証情報を指定する必要がある場合は、Custom AI Profileを使用してください。

### Custom AI Profile

BYOAI（Bring Your Own AI）方式で、お客様が用意したAPIキーやサービスアカウントを設定して利用します。AIプロバイダー、モデル、推論量などを指定できます。

Google Vertex AIを利用する場合は、サービスアカウントに`Vertex AI User`ロールを付与する必要があります。登録したシークレットは暗号化して保存されます。

{% hint style="info" %}
Custom AI Profileは有料オプションです。詳細はチャットまたは`support@codatum.com`までお問い合わせください。
{% endhint %}

## 設定方法

`ワークスペース設定` > `オプション` > `AIプロファイル`から設定します。`AIプロファイルを作成`を選択し、Managed AI ProfileまたはCustom AI Profileを作成します。

設定できる項目は、AIプロファイルの種類やご利用のプランによって異なります。

## コンテキスト

AIプロファイルには、次の情報をコンテキストとして設定できます。

* **プレーンテキスト**
  * 前提、用語、解釈方針などの補足情報を入力します。
* **Notebook**
  * 指定したNotebookの内容を読み込みます。
* **フォルダ**
  * 指定したフォルダと、そのサブフォルダ内にあるすべてのNotebookを読み込みます。

Notebookとフォルダは、Agent実行時に利用するユーザーが閲覧できる場合に限り読み込まれます。閲覧できないNotebookが含まれる場合、そのユーザーはAIプロファイルを利用できません。

{% hint style="warning" %}
AIプロファイルに設定したNotebookとフォルダは、ゲストのReport AgentとWorkflow実行では読み込まれません。プレーンテキストはゲストのReport Agentにも適用されますが、Workflow実行では使用されません。
{% endhint %}

フォルダ内の情報をすべて読み込む必要がない場合は、情報の索引となるNotebookだけを設定し、必要な情報をAgentに検索させる構成を推奨します。詳しくは[エージェントコンテキスト](/codatum-ai/agent-context)を参照してください。

## ツール権限

AIプロファイルごとに、Codatum Agentが利用できる情報とツールを設定できます。

### Notebookアクセス

* `権限のある全てのノートブック`
* `表示中のノートブックのみ`

### コネクションアクセス

* `権限のある全てのコネクション`
* `選択したコネクションのみ許可`
* `選択したコネクションを拒否`

### Web検索・Webページ取得

Web検索とWebページ取得は個別に設定できます。

* `オフ`
* `特定のドメインで許可`
* `オン`

特定のドメインで許可する場合は、`example.com`または`*.example.com`の形式で許可するドメインを指定します。

### エージェントコネクタ

* `オフ`
* `選択したコネクタのみ許可`
* `全てのコネクタ`

コネクタの設定については[エージェントコネクタ](/codatum-ai/agent-connector)を参照してください。

{% hint style="info" %}
AIプロファイルのツール権限は、利用するユーザー自身のアクセス権限を拡張するものではありません。ユーザーの権限とAIプロファイルの権限の両方で許可されている範囲だけを利用できます。
{% endhint %}

## 共有設定

AIプロファイルを利用・管理できる対象を、ワークスペースメンバー、グループ、ユーザー単位で設定できます。

* `オーナー`
  * AIプロファイルの設定を変更できます。
* `ユーザー`
  * AIプロファイルをAgentで利用できます。

ワークスペースオーナーは、すべてのAIプロファイルのオーナーとして扱われます。

## 会話ログ

`会話メッセージの内容をログに保存`を有効にすると、そのAIプロファイルを利用したAgentセッションのユーザーとAIのメッセージをワークスペース管理者が`エージェント利用状況`で確認できます。

この設定によって、会話メッセージの内容がCodatum開発者に共有されることはありません。Codatum開発者が品質改善のために記録する情報については、[Codatum Agentのデータの取り扱い](/codatum-ai/ai-agent)を参照してください。

## カスタム振る舞いと開始画面

ご利用のプランによっては、Agentの振る舞いとチャットの開始画面をAIプロファイルごとに設定できます。

* **カスタム振る舞い**
  * Agentが質問、説明、分析を行う際の追加指示を設定します。
* **標準の振る舞い**
  * AIプロファイルへ適用しない標準指示を無効にできます。
* **開始画面**
  * ウェルカムタイトル、説明、おすすめの質問を設定します。


# AIアシスタント

LLMを活用したSQL生成、修正、修復、補完のための強力なアシスタント

{% hint style="info" %}
AIエージェント機能を利用できるワークスペースでは、AIアシスタントの代わりに[Codatum Agent](/codatum-ai/ai-agent)が表示されます。AIエージェントは、SQL生成に加えてデータ探索、クエリ実行、Notebookの作成・編集などに対応しています。
{% endhint %}

<figure><img src="/files/bXAfp6vPGCZSU00HYJCb" alt=""><figcaption></figcaption></figure>

AIアシスタントは、ユーザーの意図を理解し、必要なSQLを生成する機能です。

自然言語で実行したい分析や生成したいSQLを伝えることで、AIアシスタントはそれに応じてSQLを生成または修正します。

## 利用できる条件

AIアシスタントは、ご利用のプランでAIエージェント機能が提供されていないワークスペースで使用できます。AIエージェント機能を利用できるプランでは、同じ操作箇所にAIエージェントが表示され、AIアシスタントを個別に選択することはできません。

## セットアップ方法

`ワークスペース設定` > `オプション` > `Codatum AI`でAIアシスタントを有効にします。有効にした後、SQLブロックを選択し、右上のAIアイコンから使用できます。

## 主な機能と使用方法

* SQL生成:
  * SQLブロックを作成した後、アシスタントが参照するテーブルを選択し、実行したい分析を指定します。
* SQL修正:
  * 修正したいSQLブロックを選択し、どのように修正するかをアシスタントに指示します。
* SQL自動修正:
  * エラーのあるSQLブロックで`AIで修正`を選択すると、修正が必要なSQL文とエラーメッセージに基づいて、アシスタントが修正を行います。

## データプライバシー

これらのリクエストは、選択したLLMプラットフォームに送信されますが、トレーニング目的では使用されません。

主な機能に含まれるデータは以下の通りです：

* SQLブロック内のSQL文
* 参照テーブルのスキーマとSQL実行結果のスキーマ（以下で指定）:
  * SQLブロック内で参照されるテーブルとSQLブロック
  * GUI上で明示的に参照されるテーブル
* ユーザーが入力したリクエストメッセージ

{% hint style="info" %}
独自のAPIキーでSQLアシスタント機能を使用するには、チャットまたは`support@codatum.com`までお問い合わせください。
{% endhint %}


# ワークフロー(ベータ版)

スケジュール設定に基づきクエリを自動で実行し、通知などを送信。

{% hint style="warning" %}
この機能は現在ベータ版で開発中の機能です。仕様については予告なく変更となる場合がございます。
{% endhint %}

スケジュール設定を行うことでクエリを定期実行し、外部にデータを連携することができます。

Codatumのワークフローではクエリの実行結果をLiquid形式で利用し、外部への通知などに利用することが可能です。

## 主な機能

* スケジュール設定
  * 次の期間で設定することが可能です
    * 1時間ごと
    * 1日ごと
    * 1週間ごと
    * 1ヶ月ごと
  * タイムゾーンの設定が可能です
* Codatumアクション
  * クエリの実行
    * [「クエリ」](/data-exploration/query)に保存されたクエリを選択し実行します
    * 実行されたクエリの結果は最大20行まで取得され、Liquid形式で後続の処理で利用可能です
  * レポートを実行
    * 保存済みのレポートを選択して実行します
    * 「デフォルトパラメータを使用」を有効にすると、レポートに設定されたデフォルト値でパラメータをリセットして実行します
    * 「実行後にレポートを更新」を有効にすると、実行結果をレポートに保存します
  * スクリーンショット
    * レポートの特定のページをPNG形式でキャプチャします
    * テーマ（ライト／ダーク）とロケール（英語／日本語）を設定することができます
    * 生成された画像はファイルURLとして出力され、後続のEmailやSlackアクションの添付ファイルとして利用可能です。
    * 「レポートを実行」ステップの後に設定することで、最新データが反映された状態でキャプチャできます
  * Email
    * チーム内のメンバーを対象にメールを送信することができます
    * メール本文はHTML形式で設定が可能です
    * メールは `noreply@workflow.codatum.com` から送信され、Codatumのフッターが設定された状態で送信されます
  * LLM
    * LLMを呼び出し自然言語処理を行うことができます
    * Liquid形式でクエリの実行結果を与えることで、データの要約などをAIに作成させて送信するなどの用途があります
    * 利用するAIについては、[AIプロファイル](/workflow/workflow/ai-profile)で設定が可能です
  * 実行条件(任意)
    * 各アクションにおいてアクションを実行するかどうかの条件設定が可能です
    * `failure()`を設定することで、ワークフロー上でエラーが発生した際に実行されるアクションを設定することができます
      * ワークフロー上でエラーが発生した場合は`failure()`が設定されたアクションのみが実行され、その他のアクションは実行されません
* インテグレーション
  * Slack
    * Slackインテグレーションを作成し、選択することでワークフローの実行結果をSlackへ通知することが可能です
    * Slackメッセージに出力する内容はクエリの実行結果を元にLiquid形式で設定ができます
    * メンション設定など記法に関しての詳細な仕様は[Slack Developers:Formatting message text](https://docs.slack.dev/messaging/formatting-message-text/#basic-formatting)などをご覧ください。

上記記載以外のCodatumアクションやインテグレーションも順次追加される予定です。

## 使用方法

* ワークフローの作成
  * 次の2つの方法で作成することができます
    * ワークフロー画面の「ワークフローを作成」から作成
    * 「クエリ」に保存されたクエリの右サイドバーから作成
      * クエリの実行に保存されたクエリが選択された状態で作成されます

## ワークフロー管理

ワークフローの一覧から以下の設定・確認が行えます

* ワークフロー設定
  * オーナー権限の設定
    * ワークフローはオーナー権限を持つメンバーのみが閲覧・編集を行えます
  * 最終実行日時の確認
  * ワークフロー実行内容の確認
    * 実行されているクエリやインテグレーションによって送信される内容が確認できます
* 実行履歴
  * 過去の実行履歴が表示されます
  * どのステップで失敗しているかの確認に利用できます

## Liquidテンプレート

Codatumのワークフロー設定では「\</>(変数を挿入)」からUI上で利用したい変数を選択することが可能ですが、Liquid形式を理解することでより高度な設定が可能になります。

Liquidテンプレートの大部分が利用可能なので詳細は[Liauid Template Language](https://shopify.github.io/liquid/)をご覧ください。


# インテグレーションの追加

ワークフローで利用するインテグレーションを追加します。

* インテグレーションの追加は「ワークスペース設定」の「オプション」内の「インテグレーション」から追加できます

## Slack

### 追加の流れ

* 「インテグレーションを作成」から「Slack」を選択
* 「接続」をクリックするとSlackへの認証画面が表示されるので、「許可する」を選択し、Codatumを認証
  * Slackワークスペースにサインインしていない場合はSlackワークスペースへのサインインが必要になります
* Slackワークスペースに Codatum アプリが追加される

### 注意点

* Slackメッセージの送信には、メッセージを送信したいチャンネルに `Codatum` を追加する必要があります
  * /invite で `Codatum` をチャンネルに追加してください


# AIプロファイルの作成

ワークフローで利用するAIプロファイルを設定します。

* AIプロファイルの作成は「ワークスペース設定」の「オプション」内の「AIプロファイル」から実行できます

## 追加の流れ

* 「AIプロファイルを作成」を押し、以下の設定項目を入力し「作成」を押す
  * 名前
  * プロバイダー
    * OpenAI, Anthropic, Google Geminiが利用できます
  * モデル
  * APIキー
    * 各プロバイダーのプロバイダーやコンソールから取得ください


# ワークフローのユースケース

Codatumのワークフローを利用した実践例を紹介します。

## Slackへの通知の送信

### シナリオ：直近のアカウント作成数を通知する

直近1日以内に作成されたアカウントを集計するクエリを作成し、新規のアカウント作成があった場合のみSlackへの通知を行うワークフローを作成します。

#### クエリの作成

* 作成日時のカラムを元に直近1日分のデータを出力します

```sql
SELECT *
FROM `codatum-example.example.accounts`
WHERE created_at >= TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 1 DAY)
ORDER BY created_at DESC
```

#### スケジュール設定

* 日次で朝10時に実行する形で設定します
  * 繰り返す間隔： `1日ごと`
  * 開始時刻： `10:00 (GMT+09:00) 日本標準時`

#### ステップ1：Run Query

* 上記で作成したクエリを選択します
  * 「クエリ」画面からワークフローを作成した場合は、ステップ1に選択したクエリが入力された状態でワークフロー設定が開始されます

#### ステップ2：Slack（Codatum）

* 事前に[インテグレーションの追加](/workflow/workflow/add-integration)と通知したいSlackチャネルへのAppの追加を行います
* チャネル：`notification_codatum`
  * App追加済みのチャネルが一覧表示されます
* メッセージ本文：
  * 「最初の行」を元にメッセージ内で利用したい変数の記入方法を確認できます
    * account\_nameを選択すると、`{{ query.rows[0].account_name}}` のような形で入力されます
  * クエリの実行結果を複数行分取得し、行ごとに表示したい場合は 「\</> Rows」 を選択します
    * Liquid記法でループ処理が実現される形で自動的にに入力されます
    * 各ループでは`row`に値が入力されるので、 `{{ row.account_name }}`のような形で入力したい変数を選択してください
* スレッド
  * 複数のステップでSlackを送信する場合、前のステップで送信したメッセージに対してスレッドでメッセージを送信することができます
* Codatumへのリンクを含む
  * ワークフローへのリンクを付与することができます
  * ワークフローの閲覧にはワークフローのオーナー権限が必要です
* 実行条件(任意)
  * ステップ1のクエリに出力結果があるかどうかを以下の条件式で確認します
  * `{{ query.rowCount }} > 0`
    * 「\</>(変数を挿入)」からGUI上で「行数」を選択して入力することが可能です
    * `query` に 「Run Query」 の出力結果が格納されます
      * 「Run Query」 を複数設定している場合は、`query_1`のように識別用の数値が追加されます
* 条件式に当てはまらない場合はアクションの実行がされません

```liquid
直近1日以内に作成されたアカウント数： {{ query.rowCount }}
直近作成されたアカウント（最大5件表示）
{% for row in query.rows limit:5 %}
アカウント名：{{ row.account_name }}
作成日次：{{ row.created_at }}
{% endfor -%}
```


# AIでのサマリー生成

Codatumのテキストパネル機能とVertex AIを利用して、AI生成サマリーを追加する方法を学びます

ダッシュボードに付随するテキストサマリーはユーザーがデータを理解する手助けになります。しかし、人が記載するサマリーではパラメータ指定などのユーザー側でのアクションを反映させることができません。

この記事ではBigQueryを介してVertex AIを利用し、ユーザーがパラメータで指定したデータに応じたサマリーの生成を行う方法を紹介します。BigQuery以外のコネクションでも対応するAI機能を利用することで実現可能です。

Codatumにはマークダウン記法のテキスト表示のためのテキストパネルがあるので、ここではテキストパネルを利用してチャートへ表示します。

## 設定方法

* Vertex AIのセットアップ
* モデルの作成
* 集計データをモデルに渡す
* テキストパネルチャートを選択し、データを表示する

上記の流れで、ユーザーがパラメータを変更してクエリ実行されるたびに表示内容が異なるサマリーの追加が可能です。

## 実装例

* BigQueryパブリックデータの Chicago Taxi Trip を利用します
* パラメータで表示するデータの対象を変更するたびにサマリーを生成し、表示データに応じたサマリーを作成します

### モデルの作成

* この作業はBigQueryのクエリエディタ側でも実行できます。

```sql
CREATE OR REPLACE MODEL `codatum-example.example.vertex_ai`
REMOTE WITH CONNECTION `us.vertex_ai_test`
OPTIONS(
  ENDPOINT = 'gemini-2.0-flash'
)
```

上記クエリの完了後、BigQueryの `example` データセットに `vertex_ai` モデルが追加されます。

### データの集計

* 月次で企業ごと、支払い方法毎の乗車回数、乗車時間、乗車距離、乗車料金を集計します
  * 企業名、支払い方法は[パラメータ](/data-exploration/parameter-overview)で変更できるように設定します

```sql
SELECT
  DATE_TRUNC(trip_start_timestamp, month) as month,
  company,
  payment_type,
  COUNT(distinct unique_key) as trip_count,
  SUM(trip_seconds) / 60 as total_trip_min,
  AVG(trip_seconds) / 60 as average_trip_min,
  MAX(trip_seconds) / 60 as max_trip_min,
  MIN(trip_seconds) / 60 as min_trip_min,
  SUM(trip_miles) as total_trip_miles,
  AVG(trip_miles) as average_trip_miles,
  MAX(trip_miles) as max_trip_miles,
  MIN(trip_miles) as min_trip_miles,
  SUM(fare) as total_fare,
  AVG(fare) as average_fare,
  MAX(fare) as max_fare,
  MIN(fare) as min_fare
FROM
  `bigquery-public-data.chicago_taxi_trips.taxi_trips`
WHERE trip_start_timestamp >= '2017-01-01' AND trip_start_timestamp < '2018-01-01' -- 2017年のデータ
--外れ値除外
AND trip_seconds != 0 AND fare != 0 AND trip_miles != 0
AND trip_seconds < 21600
AND CASE {Company} WHEN '' THEN TRUE ELSE company = {Company} END
AND CASE {PaymentType} WHEN '' THEN TRUE ELSE payment_type = {PaymentType} END
GROUP BY DATE_TRUNC(trip_start_timestamp, month), company, payment_type
ORDER BY month
```

### AIモデルへのデータの受け渡し

Codatumでは、他のSQLブロックの結果を参照することが可能なので、データを集計するSQLブロックとデータを受け渡すSQLブロックを分けて管理することができます。

* 集計したデータをJSON形式に変換します

```sql
SELECT
  TO_JSON_STRING(STRUCT(
  average_fare,average_trip_miles,average_trip_min,company,max_fare,max_trip_miles,max_trip_min,min_fare,min_trip_miles,min_trip_min,month,payment_type,total_fare,total_trip_miles,total_trip_min,trip_count
  )) as input_text
FROM
  月毎利用状況サマリー
```

* 行毎のJSONデータを1つに結合します

```sql
SELECT
  CONCAT('[', STRING_AGG(input_text, ','), ']') AS all_input_texts
FROM
  JSON形式_利用状況サマリー
```

* 結合したJSONデータをAIモデルに渡します
  * プロンプトとJSONデータを結合して、作成したモデルに受け渡します

```sql
SELECT 
  JSON_VALUE(ml_generate_text_result.candidates[0].content.parts[0].text) as output,
FROM ML.GENERATE_TEXT(
  MODEL `codatum-example.example.vertex_ai`,
  (
    SELECT
      CONCAT(
        '以下のデータはCompany別、Payment_Type別の月次のタクシーの乗車データのサマリーです。',
        'サマリーの支払い方法別、月別の傾向をサマライズして、Markdown形式のレポートにしてください。',
        '総乗車回数や最多乗車月などのデータの概要を説明した後、特徴的な項目について複数項目をセクションを分けて説明して下さい。'
        'Markdown全体を囲う必要はありません。',
        'markdownの色々な要素を使うようにしてください。',
        '生成したサマリーで完結するようにしてください。サマリーを追加で編集することはありません。ただし追加の分析提案は可能です。',
        'サマリー内ではコードの実行ができないため、コードは埋め込まないでください。'
        '対象のタクシー乗車データの支払い方法は', CASE WHEN {PaymentType} = '' THEN '全て' ELSE {PaymentType} END,'で、',
        '対象企業は', CASE WHEN {Company} = '' THEN '全社' ELSE {Company} END, 'です。インプットデータ：',
        all_input_texts
      ) as prompt,
      *,
    FROM All_JSON形式_利用状況サマリー
  ),
    STRUCT(
      0.3 AS temperature,
      1000 AS max_output_tokens)
)
```

* モデルに渡すプロンプトの内容によって、サマリーの安定度が変わるので工夫してみてください

### テキストパネルチャートの追加

* チャートタイプを選択から`テキストパネル`を選択し追加します
  * テキストパネルは1行目の値を表示するので、複数のテキストデータが存在する場合は1つのみが表示されます

## 注意点

* Markdownが囲われている場合、テキストパネルでは適切に展開することができないので、AIのアウトプットがMarkdownを囲わないようにしてください


# Vertex AIのセットアップ

Google Cloud Platform上でのVertex AIのセットアップ

## 設定方法

BigQueryコンソールで以下の操作を行います:

* 「外部接続」の追加
  * エクスプローラの「データを追加」から `Vertex AI > BigQueryフェデレーション` を追加します
* 「外部接続」へのアクセス権の追加
  * 「IAMと管理」からアクセス権を付与します
    * 「アクセスを許可」を押し、「プリンシパルの追加」の「新しいプリンシパル」に 追加した「外部接続」のサービスアカウントIDを入力します
    * `Vertex AI ユーザー` ロールを割り当てます
* Codatumコネクションへ以下のロールを追加します:
  * `BigQuery Connection User`
  * 追加には以下の2種類の方法があります:
    * 外部接続に対して、プリンシパルを追加します
      * 「外部接続」から追加した外部接続を選択し、「共有 > プリンシパルを追加」にCodatumコネクションに利用しているサービスアカウントを入力します
    * Codatumコネクションに設定されているサービスアカウントにロールを追加します
      * 「IAMと管理」からCodatumコネクションに利用しているサービスアカウントを選択し、「ロールを割り当てる」からロールを追加します
* データセットの作成
  * モデルを登録するデータセットを作成します
* (オプション)モデルの追加
  * BigQueryのクエリエディタからモデルを追加します。参考：[Gemini モデルと ML.GENERATE\_TEXT 関数を使用してテキストを生成する](https://cloud.google.com/bigquery/docs/generate-text-tutorial-gemini?hl=ja)
  * モデルの追加はCodatum上で実行できます


# KARTE Datahubとの連携方法

ここでは、KARTE DatahubにあるデータにCodatumからアクセスするためのセットアップ方法を説明します。

### KARTE Datahub上での作業

1. Datahub設定画面にて、払い出しサービスアカウント（SA）を払い出す

* 「その他の設定」>「データハブ設定」 >「 サービスアカウント管理」を選択
* 「払い出しGoogleサービスアカウント」＞「Googleサービスアカウント作成」を押下し、ダウンロードするキータイプを選択の上、保存する（紛失すると復元不可のため、大切に保管してください）

2. 払い出したSAにジョブ実行権限を付与する

* 「BQクエリ実行権限付与済みアカウント」>「権限付与」を押下し、作成したSAを入力して権限を付与する

3. データセット画面にて、SAに閲覧権限を付与する

* サイドバー「データセット」にて、コネクションに用いるデータセット横の 「...」>「データセットの共有設定」を押下
* 「データセットを共有するメンバーを追加」から、作成したSAに閲覧権限を付与する

[こちらのドキュメント](https://developers.karte.io/docs/datahub-create-service-account)でも手順を確認いただけます。「外部サービス」がCodatumに該当します。

### Codatum上での作業

1. Codatumにサインアップする（[こちら](https://app.codatum.com/signup)）

* Codatumアカウントとワークスペースを作成

2. コネクションの作成

* 「ワークスペース設定」>「[コネクション](https://app.codatum.com/workspace/last-accessed/setting/connections)」を開く
* 「+コネクションを追加」からからGoogle BigQueryを選択
* 任意のコネクション名を指定する
* 任意のアクセスレベルを指定する
* KARTE Datahubからダウンロードしたファイルをアップロードする
* 「保存」を押下

3. 同期の設定

* 「コネクション」画面から作成したコネクションを選択し、「テーブル同期設定」>「同期対象」>「編集」を押下
* 「Projectを追加」を押下し、KARTE Datahubのプロジェクト名（例：karte-data）を入力。その後「datasetを追加」を押下し、参照したいdataset名（例：karte\_stream\_\[api\_key]）を選択した上で、「保存して同期」を押下

  <figure><img src="/files/hKmQPipXUVeYJaFQZKRQ" alt="KARTE DatahubのProject名とDataset名の入力画面" width="563"><figcaption></figcaption></figure>

4. そのコネクションを使って、ノートブックやクエリでSQLが実行できることを確認する

* ノートブックを開き、本文内で `/` と入力して、SQLブロックを挿入
* SQLブロックにDatahubで実行できるSQLを入力して Runボタンを押し、実行完了することを確認
  * このとき、コネクションを先程アップロードしたSAにすることを忘れないでください

    <figure><img src="/files/BFO5E6scpR5Z5bFMhMsR" alt="" width="563"><figcaption></figcaption></figure>

### 注意点

* 払い出しSAによるクエリは、1日5TBの制限があります。
* 払い出しSAによるクエリはKARTE Datahubのクエリ消費量に合算されます。
* `karte-data` の連携時に `karte-data: Internal Server Error: Error list datasets` のエラーメッセージが表示される場合があります。
  * データセットが多いことに起因するエラーでありクエリの実行などには影響しないことが多いので、クエリの実行やカタログでの閲覧など実行したいアクションが実行できる場合にはエラーを無視して構いません。
* 手順3の同期設定について、KARTEイベントデータであれば、テーブル名は `krt_pockyevent_v1_*` 、データセット名は `karte_stream_[api_key]` 、プロジェクト名は `karte-data` です。
  * `karte-data` はデータセット数が膨大で、データセット名も入力しないとSyncできません。そのため、Add project後に Add dataset ボタンが出てくるまで少し待ってください。
  * 「イベント」ログを格納する実体となるテーブルは、`karte_event` ではなく `krt_pockyevent_v1_*` となります。詳しくは[こちら](https://developers.karte.io/docs/datahub-karte_event-table#%E5%AE%9F%E9%9A%9B%E3%81%AE%E3%83%86%E3%83%BC%E3%83%96%E3%83%AB%E5%90%8D%E3%81%AFkarte_event%E3%83%86%E3%83%BC%E3%83%96%E3%83%AB%E3%81%A7%E3%81%AF%E3%81%AA%E3%81%84)をご覧ください。


# Signed Embed Light セットアップガイド

CodatumのノートブックをKARTE Datahub（Codatum BI）に安全に埋め込む手順

## 概要

**Signed Embed Light** を使用することで、Codatumで作成したダッシュボードやノートブックを、KARTEのDatahub上に「Codatum BI」として埋め込み活用することができます。埋め込まれたコンテンツはトークンベースで認証され、セキュアに表示されます。

Datahubの閲覧権限があるKARTEアカウントで、Codatumにアクセスせずともダッシュボードを閲覧できます。

## 設定方法

### Codatum側での準備

* APIキーとAPIシークレット、ワークスペースIDを取得する
  * `ワークスペース設定`を開きます（画面左下の歯車アイコンをクリック）
  * `APIキー`メニューをクリックします
  * `APIキーを追加`ボタンをクリックして新しいAPIキーを作成します
    * **APIキー**と**APIシークレット**が生成されます。両方の値を後ほど使用します
  * `基本設定`メニューでワークスペースIDを確認します（KARTE側で使用します）
* ノートブックを公開設定にする
  * 埋め込みたいノートブックを開きます
  * ヘッダーの`共有`ボタンをクリックし、`署名付き埋め込み`タブを選択します
  * `署名付き埋め込みを作成`をクリックします
  * `公開ページの選択`や`公開時のオプション`を設定します（どのページをKARTEに埋め込むかを指定します）
    * KARTEの管理画面上からデータソースをCSV形式で「ダウンロード」する機能の有効化
    * GUIで探索できる「エクスプローラ」機能の有効化
    * ※ パラメータなどの設定は不要です
  * `公開`ボタンをクリックします
  * 設定タブの`権限を付与するAPIキー`セクションで、先ほど作成したAPIキーを追加します
    * 埋め込み先でパラメータを活用する場合は、パラメータも追加します
* インテグレーションIDとページIDを確認する
  * 同じ画面の`セットアップガイド`タブをクリックします
  * **インテグレーションID**と**ページID**を確認・メモします（KARTE側で必要になります）

確認済み情報のメモ例:

```
ワークスペースID: codatum123456
インテグレーションID: 123456codatum
ページID: 123codatum456
APIキー: xxxxxxxxxxxxxxxx
APIシークレット: xxxxxxxxxxxxxxxxxxxxxxxx
```

### KARTE側での設定

* Codatum APIキーをKARTEに登録する（初回のみ）
  * KARTEの`Datahub`を開き、`Codatum BI`セクションに移動します
  * `APIキー`ボタン、続けて`作成`ボタンをクリックします
  * 以下を入力します
    * **名前**: 任意の名前（例：「プロダクション」「テスト環境」）
    * **APIキー**: Codatum側で取得したAPIキー
    * **APIシークレット**: Codatum側で取得したAPIシークレット
  * ダイアログを閉じます
* ノートブックをKARTEに追加する
  * `Codatumノートブックを追加`ボタンをクリックします
  * ダイアログに以下を入力します

    | 項目          | 説明                  | 入力例                        |
    | ----------- | ------------------- | -------------------------- |
    | ダッシュボード名    | KARTE内に表示される名前      | 「月間売上分析」                   |
    | 説明          | 簡単な説明（一覧に表示）        | 「売上推移とセグメント分析」             |
    | APIキー       | 登録したAPIキーをプルダウンから選択 | 「プロダクション」など                |
    | インテグレーションID | Codatum側で確認した値      | `6a0be605b82c28cfca0a3b87` |
    | ワークスペースID   | Codatum側で確認した値      | `68f6cf4aa62ec85afb3525bc` |
    | ページID       | Codatum側で確認した値      | `68f6cf4aa62ec85afb3525bc` |
  * `作成`ボタンをクリックすると、ダッシュボード一覧に追加されます
    * ダッシュボード名をクリックするとコンテンツが表示されます

## 開発者向け補足

### サーバーサイドでのトークン発行

フロントエンドで Codatum Embed SDK を使用する場合、以下の API エンドポイントからサーバーサイドでトークンを発行する必要があります。

**エンドポイント**

```
POST https://api.codatum.com/api/notebook/issueToken
```

**リクエスト例**

```json
{
  "api_key": "6729a28bc7100424ad4e2e5d",
  "api_secret": "c711defdff5f4e3e8e53d4f408579b9a",
  "integration_id": "671ef14b0d08cf6c657df7da",
  "page_id": "671ecbbf2990c63fea3b3a26",
  "token_user_id": "user123",
  "params": [
    {
      "param_id": "6722c7061b02448a4056d84d",
      "param_value": "\"Hello world\""
    }
  ],
  "expires_in": 3600,
  "cache_max_age": 86400
}
```

**レスポンス例**

```json
{
  "token": "(Generated-token)"
}
```

**パラメータ説明**

| パラメータ            | 説明                                |
| ---------------- | --------------------------------- |
| `api_key`        | Codatum APIキー                     |
| `api_secret`     | Codatum APIシークレット                 |
| `integration_id` | インテグレーションID（署名付き埋め込み設定で確認）        |
| `page_id`        | ページID（署名付き埋め込み設定で確認）              |
| `token_user_id`  | 埋め込み対象のユーザーID（KARTEのユーザーIDなど）     |
| `params`         | サーバーサイドで設定するパラメータ（オプション）          |
| `expires_in`     | トークン有効期限（秒）。デフォルト：3600秒（1時間）      |
| `cache_max_age`  | キャッシュ最大有効期間（秒）。デフォルト：86400秒（24時間） |

{% hint style="warning" %}
APIシークレットは外部に漏らさないよう、必ずサーバーサイドで実行してください。
{% endhint %}

### フロントエンドでの組み込み

[Codatum Embed SDK](https://github.com/codatum/codatum-embed-js) を使用してフロントエンドに組み込みます。詳細は[SDKのREADME](https://github.com/codatum/codatum-embed-js/tree/main/packages/embed#readme)を参照してください。

## 付録

### よくある質問

#### インテグレーションIDってなんですか？

Codatumで、このノートブックを外部に公開するための識別子です。署名付き埋め込み設定時に自動生成されます。

#### ワークスペースIDとページIDは同じですか？

異なります。

* **ワークスペースID**: あなたのCodatumワークスペース（組織）を識別するID
* **ページID**: 埋め込みたいノートブックの特定ページを識別するID

#### 複数のノートブックを埋め込めますか？

はい。「KARTE側での設定」の手順を繰り返すことで、複数のノートブックを埋め込めます。

#### APIシークレットを失くしてしまいました

新しいAPIキーを作成し直す必要があります。Codatumの`ワークスペース設定`＞`APIキー`から古いキーを削除し、新しいものを作成してください。

#### IDを間違えて入力してしまいました

KARTE側で該当ダッシュボードを削除して、新しく作成し直してください。正しいIDを確認してから再度設定します。

#### 「指定されたインテグレーション ID が見つかりません」エラーが出る場合

* Codatum側で該当ノートブックが公開状態になっているか確認してください
* `署名付き埋め込み`＞`セットアップガイド`でインテグレーションIDが正しく表示されているか確認してください
* KARTE側で入力したIDが正確か再度確認してください

#### ダッシュボードが表示されない場合

APIキーの認証に失敗している可能性があります。

* KARTE側のAPIキー設定で、APIキーとAPIシークレットが正確に入力されているか確認してください
* Codatum側でそのAPIキーが削除されていないか確認してください
* 必要に応じてAPIキーを作成し直してください


# BigQuery ジョブラベルからの利用実態取得

BigQuery のジョブラベルから、Codatum が発行したクエリの実行元（Notebook / Report 等）を取得する方法。

{% hint style="warning" %}
この機能は現在ベータ版です。仕様については予告なく変更となる場合がございます。
{% endhint %}

Codatum が BigQuery に発行するクエリジョブには、実行元（どの Notebook / Report / Query / Signed Embed から実行されたか）を示すラベルが付与されます。`INFORMATION_SCHEMA.JOBS` のラベルを参照することで、テーブルの棚卸しやコスト分析を Codatum の利用実態と突き合わせて自動化できます。

## 付与されるラベル

| ラベルキー                  | 内容                                                                                                        |
| ---------------------- | --------------------------------------------------------------------------------------------------------- |
| `source`               | 常に `codatum`                                                                                              |
| `cdm_source_type`      | `notebook` / `query` / `report` / `signed_embed` / `unknown`                                              |
| `cdm_<source_type>_id` | 主たる実行元 ID を **1 つ**（例 `cdm_notebook_id` / `cdm_report_id`）。優先順位 report > signed\_embed > notebook > query |
| `cdm_workspace_id`     | Workspace ID                                                                                              |
| `cdm_connection_id`    | Connection ID                                                                                             |
| `cdm_actor_type`       | `user` / `workflow` / `api_key` / `admin` / `system`                                                      |

> 付与対象は Notebook セル実行 / Saved Query / Report（定期実行）/ 外部 API / Signed Embed です。内部メタデータ取得系（DryRun・スキーマ取得・データプレビュー等）は対象外です。report 実行時は `cdm_notebook_id` ではなく `cdm_report_id` が載ります。

## 取得方法

```sql
SELECT
  job_id,
  creation_time,
  total_bytes_billed,
  (SELECT value FROM UNNEST(labels) WHERE key = 'cdm_source_type') AS source_type,
  (SELECT value FROM UNNEST(labels) WHERE key = 'cdm_notebook_id') AS notebook_id,
  (SELECT value FROM UNNEST(labels) WHERE key = 'cdm_report_id')   AS report_id
FROM `region-us`.INFORMATION_SCHEMA.JOBS
WHERE creation_time > TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 7 DAY)
  AND EXISTS (SELECT 1 FROM UNNEST(labels) WHERE key = 'source' AND value = 'codatum')
```

`region-us` の部分は、対象データセットのリージョンに合わせて変更してください。

## ユースケース

* **テーブル棚卸し**: どの Notebook / Report がどのテーブルを参照しているかを機械的に取得し、dbt の棚卸しなどを自動化する
* **コスト分析**: 課金額の大きいクエリやスロークエリを特定し、それを発行している Notebook / Report（ダッシュボード）を逆引きする

## 他のデータウェアハウス

BigQuery 以外でも、同等の実行元情報が付与されます。取得元はデータウェアハウスごとに異なります。

* **Snowflake**: `QUERY_TAG`（JSON）として付与されます。`QUERY_HISTORY` の `QUERY_TAG` を参照してください。
* **Redshift / Databricks**: 実行する SQL の先頭コメント `/* codatum source_type=... */` として付与されます。クエリ履歴のクエリ本文から参照してください。