ユーザーガイド

このページは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`	—	最初にこれを呼び出してください。完全なワークフローガイドを返します：セマンティック層とraw 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秒ごとにポーリングします。

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

2つのraw SQLケース：

ケースA — セマンティック層が利用不可： check_service_healthでワークスペースがhealthyでないことが報告される（すべてno_models / not_ready）。すべてのクエリはlist_databases → list_tables → describe_table → execute_queryを通る必要があります。
ケースB — 一致するメトリックなし： セマンティック層は正常だが、list_metricsにユーザーの意図と一致するメトリックがない。同じ方法でraw 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	Raw 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で一致するメトリックが見つからない場合、raw SQLパスにlist_databases → list_tables → describe_table → execute_queryを使用

厳格なルール：

セマンティック層が正常 + 一致するメトリックがある → execute_queryで直接SQLを書くことでquery_metricをバイパスしてはいけません。
セマンティック層が正常 + 一致するメトリックなし → 最初にユーザーに「セマンティック層はこのクエリをカバーしていません」と伝え、次に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​