datalens

DataLens

DataLens は、データベースに接続し、データをデータセットにモデル化して、その上にグラフやダッシュボードを表示するビジネスインテリジェンスおよびデータ可視化システムです。Yandex Cloud のマネージドサービスとして提供されているほか、オンプレミスにデプロイしたり、Yandex 内部で実行したりできます。

このファイルは、概要を示して適切な項目に案内するものです。特定のインターフェースの使い方を説明するものではありません。以下からインターフェースを選び、そのインターフェースを担当するスキルに従ってください。

データフロー

database → connection → source → dataset → chart → dashboard

• 接続 — 1 つのデータベース用の認証情報とドライバーです。
• ソース — その接続で公開されるテーブルまたは SQL クエリです。
• データセット — モデリング層です。フィールド、計算フィールド、結合、パラメーター、行レベルのセキュリティを設定します。
• グラフ — 1 つの可視化です。ウィザードグラフはデータセット上に作成します。QL グラフはデータセットを経由せず、接続に直接クエリを実行します。エディターグラフはカスタム JavaScript で作成します。
• ダッシュボード — グラフを使ったタブ、ウィジェット、セレクター、レイアウトです。

左から右へ順に作成し、ID を使って参照します。上流のオブジェクトを削除すると、その下流にあるすべてのものが機能しなくなります。

オブジェクト ID と URL

明示的な型を持つオブジェクトの DataLens URL には、次のいずれかの形式を使用できます。

• /<object_type>/<object_id>-<readable_slug> — API には、読みやすいサフィックスより前のオブジェクト ID のみを渡します。
• /<object_type>/<object_id> — 読みやすいサフィックスがない場合、最後のパスセグメント全体がオブジェクト ID です。

ダッシュボードリンクには、追加の短縮形式があります。https://datalens.ru/<dashboard_id> です。URL がダッシュボードリンクと特定された場合、パスセグメントはダッシュボード ID のみで、オブジェクト型のセグメントはありません。たとえば、https://datalens.ru/bgquq1234567 はダッシュボード ID bgquq1234567 を指します。

型が明示されたオブジェクトの場合、https://datalens.ru/connections/r6wa2j1ww5cad-demo は接続 ID r6wa2j1ww5cad を指します。demo は人が読みやすい URL サフィックスです。URL が https://datalens.ru/connections/r6wa2j1ww5cad の場合は、同じセグメント全体を ID として使用します。同じルールは接続、データセット、グラフに適用されます。これらのオブジェクト型には、ルートレベルの短縮形式を適用しないでください。

オブジェクト ID は不透明な値として扱ってください。利用できる場合は、Copy ID の値、または API レスポンスの id フィールドを優先してください。URL が曖昧な場合や、これらの形式に一致しない場合は、ID を推測しないでください。オブジェクト ID を、表示名、読みやすい URL サフィックス、フィールド UUID と混同しないでください。

オブジェクトモデル

エントリーがどこに配置されるかは、上記のフローとは別の軸です。接続、データセット、グラフ、ダッシュボードはすべてエントリーであり、エントリーはコンテナツリーに格納されます。方式は 2 種類あり、どちらが利用できるかはインストールごとに異なります。

newer    collection
           ├── collection …            nested, arbitrarily deep
           └── workbook
                 └── entries           connection, dataset, chart, dashboard

older    folder tree, path-addressed   e.g. Users/someone/reports
           └── entries                 held directly, no workbook in between

新しい方式ではワークブックがグループ化と権限管理の単位となり、古い方式ではフォルダーパスがその役割を担います。どちらが利用できるかを決して決めつけないでください。インストールによっては一方だけ、もう一方だけ、または両方を利用できます。ワークブックのみのデプロイに対してパスベースのロジックを作成するのではなく、インターフェーススキルの指示に従って確認してください。

インストール環境

どの環境が使われているかを決して決めつけないでください。ホスト、認証方式、利用可能なコネクターやグラフの種類はすべて異なります。API を操作するものを書く前に、環境を確認してください。

インストール環境	UI	API ホスト	認証
Yandex Cloud	datalens.ru	api.datalens.tech	yc CLI IAM トークンと組織 ID
オンプレミス	ユーザーに確認	ユーザーに確認	デプロイ環境固有。多くの場合、環境変数内の OAuth トークン
Yandex Team（内部）	datalens.yandex-team.ru	api.datalens.yandex.net	内部

Yandex Cloud はマネージドサービスです。オンプレミスには、オープンソースのセルフホスト環境（docker compose、UI は :8080）と商用エンタープライズビルドの両方が含まれます。Yandex Team は Yandex 内部のインストール環境です。Yandex Team 固有の内容について回答する前に、以下のインストール環境固有の詳細を確認してください。

ツール固有のスキルがインストール環境を検出します。たとえば SDK には、環境を報告する事前チェック機能が含まれています。検出処理を独自に実装しないでください。

インターフェースの選び方

目的	使用するもの	スキル
Python からエンティティを管理する — 作成、更新、確認、エクスポート、複製	Python SDK（PyPI の datalens-sdk）	datalens-sdk
エージェントからツール経由で DataLens API を直接呼び出す	MCP サーバー（@datalens-tech/mcp）	— README を参照
それ以外のプログラムからの操作	パブリック HTTP API	— 以下を参照
探索する、クリックして操作する、レンダリングされたチャートを見る	ウェブ UI	— 人間向けの作業であり、エージェント向けではありません

SDK と MCP の比較。 スクリプト化、繰り返し実行、またはリポジトリへのコミットを行う場合は、SDK が標準の選択肢です。型付けされ、オブジェクトモデルが文書化されており、作業内容をコードとして残せます。MCP サーバーは、エージェントのセッション内で行う対話的な単発作業に適しています。起動時に API の OpenAPI 仕様を取得し、数百ものツールではなく、3 つのツールによるゲートウェイ（list_commands → describe_commands → invoke_command）を公開します。1 つのタスクで両方を併用しないでください。

どちらも適さない場合の HTTP API。 SDK と MCP サーバーはどちらも HTTP API を基盤としているため、それらでは対応できない場合に限り、API を直接利用してください。これは REST ではなく RPC 形式の HTTP API です。リソースではなく、名前付きコマンドを JSON ペイロードで呼び出します。また、自己記述型です。インストール先の API ホスト（上記の「インストール先」を参照。クラウドの場合は https://api.datalens.tech/json/）の /json/ から OpenAPI 仕様を取得し、コマンド名やペイロードの形式を推測せず、仕様を基に作業してください。クラウドでは組織 ID が必須で、x-dl-org-id ヘッダーで送信します。

インストール先ごとの詳細

2 つのインストール先では必要な情報の一部が公開されていません。どちらの場合も、自分で不足を補うのではなく、ユーザーに確認してください。

Yandex Team は、別途配布されているスキル datalens-yateam によって拡張されます。利用可能なスキルの一覧にこのスキルがあり、環境がこのインストール先を対象としている場合は、これを呼び出してください。このスキルはこのファイルに記載された内容にインストール先固有の詳細を追加し、一部を上書きします。両者が食い違う場合は、このスキルの内容が優先されます。タスクが Yandex Team に関するもので、スキルが一覧に ない 場合は、https://datalens.yandex-team.ru/get-skills の手順に従ってインストールするようユーザーに依頼し、作業を止めてください。その間、内容を再構成しないでください。回答のどの部分がインストール先に依存するのかを伝え、そのままにしてください。

オンプレミスではエンドポイントが公開されておらず、API が UI と同じホストにあるとは限りません。いずれかにアクセスする内容を書く前に、DataLens エンドポイントと DataLens API エンドポイントの両方をユーザーに確認し、作業を止めてください。一方から他方を推測したり、クラウドのデフォルトにフォールバックしたり、プレースホルダーのまま作業を続けたりしないでください。

対象外

隣接する解決策を即興で提示するのではなく、対象範囲を明示して作業を止めてください。

• ビジネス上、指標が何を意味するか、または数値が正しいように見えるかどうか。
• スクリーンショットの撮影やウェブ UI の操作。
• DataLens を別の製品に埋め込むこと、または iframe。
• DataLens のエンティティに関係しない SQL や分析。