ユーザーガイド

このページはVeloDBユーザー向けです。管理者が既にVeloDB MCP Serviceをデプロイしているため、以下のことを知るだけで済みます：

サービスをAIエージェント（Claude Code / Cursor / Codex）に接続する方法
AI会話を通じてデータをクエリする方法

セマンティックモデルの定義と管理（管理者向け）については、Semantic Modelを参照してください。

AIエージェント（Claude Code / Cursor / Codex）の接続

開始前に、以下を取得してください：

MCP Connection URL：Connectionページ → Connection Methods を開き → MCP Connection URLをコピーします。
VeloDBのユーザー名とパスワード：認証に使用します（形式はusername:password、例：admin:admin）
ワークスペース名：セマンティックモデルを保持するワークスペース（デフォルトはexample）

Claude Codeの接続

ステップ1：MCPサーバーの追加

claude mcp add --transport http velodb https://<warehouse-id>.<region>.aws.velodb.io/mcp \
  --header "Authorization: Bearer admin:admin"

ステップ2: 接続を確認する

Claude Codeで、次のように入力します：

Check service health

AIは自動的にcheck_service_healthを呼び出し、VeloDBの接続状態と全てのワークスペースの状態を返します。"velodb": "connected"が表示されれば、接続が成功しています。

ステップ3: クエリを開始する

List all available metrics

AIは3段階のフローに従います：list_metrics → list_dimensions_for_metric → query_metric。

Cursor / VS Codeに接続する

プロジェクトルートに.cursor/mcp.jsonを作成するか、VS Code用の同等のMCP設定を作成します：

{
  "mcpServers": {
    "velodb": {
      "url": "https://<warehouse-id>.<region>.aws.velodb.io/mcp",
      "transport": "streamable-http",
      "headers": {
        "Authorization": "Bearer admin:admin"
      }
    }
  }
}

利用可能なツール（合計10個）

起動とヘルスチェック（会話開始時に最初に呼び出す）

ツール	パラメータ	目的
`get_query_guide`	—	最初にこれを呼び出す。完全なワークフローガイドを返す：セマンティックレイヤーと生SQLをいつ使うか、ツール呼び出しの順序、クエリ構文。これをスキップするとエージェントが回り道をする。
`check_service_health`	detail（オプション）	VeloDBの接続性と各ワークスペースのステータス（healthy / no_models / not_ready）およびメトリック数を返す。すべての会話の開始時に呼び出す。

セマンティッククエリ（推奨 — 正しいSQLを自動生成）

ツール	パラメータ	目的
`list_metrics`	workspace（必須）、page_size、page_token	利用可能なすべてのメトリック（名前+説明）をリストする。エージェントがメトリックをユーザーの意図にマッチさせる。
`list_dimensions_for_metric`	workspace（必須）、metric_name（必須）	メトリックの利用可能なgroup_byディメンション（名前+タイプ+説明）を返し、group_byが失敗しないようにする。
`query_metric`	workspace（必須）、metrics（必須）、group_by、where、order_by、limit、having、database、max_rows	コアクエリツール。セマンティッククエリをコンパイルして実行する。カウント、合計、比率、ランキング、トレンドに関わるものはすべてここを通る必要がある。集約結果をフィルタリングするHAVINGをサポート。`database`はターゲットデータベースを設定；`max_rows`は返される行数をハードキャップする（0 = デフォルトの10000）。
`reload_semantic_layer`	workspace（必須）	セマンティックレイヤーのリロードを手動でトリガーする。管理者がYAMLモデルを変更してコミットし、すぐに有効にする必要がある場合に使用；それ以外では、レイヤーは60秒ごとにポーリングする。

低レベルメタデータと生SQL（以下の2つのケースでのみ使用）

生SQLの2つのケース：

ケースA — セマンティックレイヤーが利用不可： check_service_healthが健全なワークスペースがないことを報告する（すべてがno_models / not_ready）。すべてのクエリはlist_databases → list_tables → describe_table → execute_queryを通る必要がある。
ケースB — マッチするメトリックがない： セマンティックレイヤーは健全だが、list_metricsでユーザーの意図にマッチするメトリックがない。同じ方法で生SQLパスにフォールバックする。

ツール	パラメータ	目的
`list_databases`	page_size、page_token	すべてのデータベースをリストする。探索中に有用だが、`list_metrics`の代替ではない。
`list_tables`	database（必須）、like、page_size、page_token	データベース内のテーブル名をリストする。テーブル名のみを返し、カラム情報は含まない。カラムを見るには`describe_table`を使用する。
`describe_table`	database（必須）、table（必須）、detail_level	物理テーブル構造（カラム名、タイプ）を表示する。detail_level: names/summary/full。
`execute_query`	sql（必須）、database、max_rows	生SQLフォールバック。読み取り専用のみ（SELECT/SHOW/DESCRIBE/EXPLAIN）。セマンティックレイヤーにマッチするメトリックがある場合は、`query_metric`を優先する。

推奨エージェントワークフロー

すべての会話の標準フロー：

get_query_guide() — 完全なガイドを取得（エージェントがいつどのツールを使うかを知るため）
check_service_health() — VeloDB接続を確認し、利用可能なワークスペースを確認
ルーティング決定：

ユーザーが「何個」「計算」「トレンド」「比率」を尋ねる場合 → セマンティックレイヤーを使用（4-5-6）

ユーザーが「テーブル構造を表示」「どのようなデータベースがあるか」を尋ねる場合 → メタデータツールを使用
セマンティックレイヤーが利用不可（健全なワークスペースがない） → 4-6をスキップして7に直行
list_metrics(workspace) — メトリックをリストし、ユーザーの意図にマッチさせる
list_dimensions_for_metric(workspace, metric_name) — 利用可能なディメンションを取得
query_metric(workspace, metrics, group_by, ...) — クエリを実行
フォールバック： ステップ4でマッチするメトリックが見つからない場合、list_databases → list_tables → describe_table → execute_queryで生SQLパスを使用

ハードルール：

セマンティックレイヤーが健全 + マッチするメトリックがある → query_metricをバイパスしてexecute_queryでSQLを直接書くことはしない。
セマンティックレイヤーが健全 + マッチするメトリックがない → 最初にユーザーに「セマンティックレイヤーはこのクエリをカバーしていません」と伝え、その後execute_queryを使用し、結果に警告を添付する。

会話例

User: What was the total order amount by channel last month?

AI reasoning:
  1. get_query_guide → got the guide ✓
  2. check_service_health → workspace "example" healthy, 5 metrics ✓
  3. Involves "total amount" and "channel" → use the semantic layer
  4. list_metrics(example) → total_amount (total order amount) ✓
  5. list_dimensions_for_metric(example, total_amount) → channel ✓
  6. query_metric(example, metrics=[total_amount], group_by=[channel],
                  where="order_date >= '2026-04-30'")

AI reply:
  channel  total_amount
  WEB      1,096.00
  APP      2,396.00
  MINI       298.00

クエリ機能

接続後、Claude Codeで平易な言語で質問すると、AIが自動的に適切なMCPツールを呼び出します。

メタデータ探索

やりたいこと	単に言うだけ	呼び出されるツール
データベースを確認	"List all databases"	`list_databases`
データベース内のテーブルを確認	"List the tables in the dw database"	`list_tables`
テーブルの構造を確認	"Show the columns of the orders table"	`describe_table`

SQLクエリ

やりたいこと	単に言うだけ	呼び出されるツール
データをクエリ	"Show the top 10 orders"	`execute_query`
集約分析	"Count orders by status"	`execute_query`

execute_queryは読み取り専用のSQLのみ許可します（SELECT / SHOW / DESCRIBE / EXPLAIN）。

セマンティックレイヤークエリ（管理者が設定したセマンティックモデルが必要）

VeloDBクラスターにセマンティックレイヤーが設定されている場合、エージェントは3つのステップでクエリを完了します：

list_metrics — 利用可能なすべてのメトリクス（名前 + 説明）をリスト
list_dimensions_for_metric — メトリクスの利用可能なディメンション（名前 + タイプ + 説明）を確認
query_metric — セマンティッククエリを実行（集約結果をフィルタリングするhavingをサポート）

やりたいこと	単に言うだけ	呼び出されるツール
メトリクスを確認	"List all metrics"	`list_metrics`
収益トレンドを確認	"Show revenue for the past 7 days, grouped by day"	`query_metric`
利用可能なディメンションを確認	"Which dimensions can total_amount be analyzed by?"	`list_dimensions_for_metric`
サービスステータスを確認	"Check service health"	`check_service_health`

すべてのセマンティックツールにはworkspaceパラメータが必要です（"example"がデフォルトで利用可能）。

クエリ例

例1：データ構造を探索

You: List all databases
AI: [calls list_databases]
    dw

You: What tables are in the dw database?
AI: [calls list_tables]
    orders, users, products, dim_date

You: Show the structure of the orders table
AI: [calls describe_table]
    Column      Type      Comment
    order_id    BIGINT    Order ID
    user_id     BIGINT    User ID
    amount      DECIMAL   Amount
    channel     VARCHAR   Channel
    status      VARCHAR   Status
    order_date  DATE      Order date

例2: データのクエリ

You: Show the order count and total amount by status for the past week
AI: [calls execute_query]
    status      count   total_amount
    completed   1234    567890.00
    pending     567     89012.00
    cancelled   89      12345.00

例3: セマンティックメトリクス

You: List all available metrics
AI: [calls list_metrics]
    total_amount      Total order amount
    order_count       Order count
    avg_amount        Average order value
    unique_users      Distinct ordering users
    user_count        User count

You: Show total order amount by channel for the past 7 days
AI: [calls list_dimensions_for_metric] → channel
    [calls query_metric]
    channel   total_amount
    Online    12345.00
    Offline   15678.00
    ...

FAQ

Q: 401で接続が失敗する

トークンの形式が正しいことを確認してください: username:password（ASCIIコロンで区切られている）。

Q: セマンティッククエリで「workspace not found」が返される

ワークスペース名が正しいことを確認してください。"example"はデフォルトで利用可能です。WebUIにサインインして利用可能なワークスペースを確認してください。

Q: 書き込み操作は実行できますか？

いいえ。execute_queryは読み取り専用のSQLのみを許可します（SELECT / SHOW / DESCRIBE / EXPLAIN）。

Q: クエリが遅い

大量のデータの場合は、AIにLIMITを追加するか時間範囲を絞るよう依頼してください。

Q: セマンティックレイヤーではどのメトリクスを使用できますか？

AIに「list all metrics」と依頼するか（list_metricsを呼び出します）、WebUIにサインインして各ワークスペースに設定されたメトリクスを確認してください。

Next Steps

Semantic Model — 管理者向け: YAMLでエンティティ、ディメンション、メジャー、メトリクスを定義します。

AIエージェント（Claude Code / Cursor / Codex）の接続​

Claude Codeの接続​

Cursor / VS Codeに接続する​

利用可能なツール（合計10個）​

推奨エージェントワークフロー​

会話例​

クエリ機能​

メタデータ探索​

SQLクエリ​

セマンティックレイヤークエリ（管理者が設定したセマンティックモデルが必要）​

クエリ例​

例1：データ構造を探索​

例2: データのクエリ​

例3: セマンティックメトリクス​

FAQ​

Q: 401で接続が失敗する​

Q: セマンティッククエリで「workspace not found」が返される​

Q: 書き込み操作は実行できますか？​

Q: クエリが遅い​

Q: セマンティックレイヤーではどのメトリクスを使用できますか？​

Next Steps​