AI CLI と公式スキル
タスク中心の概要は ローカルデータのための AI エージェント向け SQL を参照してください。このページはコマンドと出力の完全なリファレンスです。
ウィンドウなしで実行する
ducklocal --help は 10 個のサブコマンドを一覧表示します:
| コマンド | 内容 |
|---|---|
ducklocal query | 1 つの SQL ステートメントを実行し、結果を JSON で出力します |
ducklocal schema | クエリできる対象を列とともに一覧表示します。--stats で 1 つのリレーションの列統計を表示します |
ducklocal open | 実行中のウィンドウに SQL、ダッシュボード、データを表示します。--state で表示内容を読み戻します |
ducklocal check | .dash ダッシュボードを検証します |
ducklocal metrics | セマンティックモデルの指標を一覧表示します。compile や query でコンパイル・実行します |
ducklocal comments | ダッシュボードに付けられたレビューコメントを読み、返信します |
ducklocal propose | ダッシュボードの変更を提案し、人がレビューして適用できるようにします |
ducklocal project | ポータブルな分析フォルダーとその必要なものを確認します。relink は移動したパスを修復します |
ducklocal session | 分析がどのように現在の状態に至ったかを読み戻します |
ducklocal presence | 開いているダッシュボードで誰が作業しているか、編集がどこに反映されるかを表示します |
エディタが .dash ファイルのために起動する言語サーバー ducklocal lsp と、schema --stats の従来の別名である ducklocal profile は引き続き動作しますが、--help には表示されません。
propose、project、session、および --restricted、--wait、--if-revision オプションは 0.4.0 で追加され、エージェントのワークフロー で説明しています。metrics と --format html は 0.4.1 より新しい機能です。main ブランチにあり、次のリリースで提供されます。metrics は セマンティック指標 で説明しています。
ducklocal query は、GUI、履歴、登録済みファイル、言語設定、GUI のグローバル接続を初期化せずに SQL を実行します。呼び出しごとに専用の接続を作成します。コマンドを付けずに DuckLocal を起動した場合、またはファイルパス、ディレクトリ、glob パターンだけを指定した場合は、通常の GUI が開きます。コマンド名(query、schema、open、check、metrics、comments、propose、project、session、presence、profile、lsp)と同名の GUI パスを開くには、./query のように ./ を前に付けます。
コマンドを入手する
DuckLocal は Apple silicon 上の macOS 12 以降、Windows(x86_64)、Linux(x86_64)をサポートします。CLI はアプリケーションの実行ファイルから直接動作するため、別途 DuckDB CLI のバイナリをインストールする必要はありません。
PATH に追加する最短の方法はアプリから行うことです(0.1.1 以降)。コマンドラインと AI…(タイトルバーのロボットボタン、または DuckLocal メニュー)を開き、コマンドをインストール をクリックします。同じダイアログで AI エージェント向けのスキルもインストールできます。詳しくは 公式スキルをインストールする を参照してください。インストールせずに使う場合は、実行ファイルをその場所で呼び出します:
# macOS
/Applications/DuckLocal.app/Contents/MacOS/ducklocal --help
# Linux: wherever you extracted the tarball
./ducklocal-linux-x86_64/ducklocal --help
# Windows (PowerShell): wherever you extracted the zip
.\ducklocal-windows-x86_64\ducklocal.exe --helpソースのチェックアウトからは、cargo build --locked で ./target/debug/ducklocal をビルドできます。以下の例では ducklocal が PATH にあることを前提としています。古いリリースには query がない場合があるため、まず --help を確認してください。JSON と Parquet のサポートは同梱されており、クエリ時にダウンロードされることはありません。
クエリのオプション
ducklocal --help
ducklocal --version
ducklocal query --help
ducklocal query --sql "SELECT 1 AS n"
ducklocal query --sql "SELECT 1 AS n" --format md
ducklocal query --sql-file analysis.sql --limit 100
ducklocal query --sql-file - < analysis.sql
ducklocal query --database warehouse.duckdb --sql "SHOW TABLES"--sql SQLと--sql-file FILEのどちらか一方が必須です。ファイルは UTF-8 である必要があり、-は標準入力を読みます。SQL には 1 つのステートメントだけを含める必要があります。DuckDB のパーサーが、対象データベースを開く前、何かを実行する前にこれを検証します。コメント、引用符で囲まれたセミコロン、末尾のセミコロンは問題ありません。スクリプトは部分的に実行されることなく、拒否されます。--database PATHは 既存のファイルを、デフォルトでは読み取り専用で 開きます。省略すると新しいインメモリデータベースになります。--read-writeは--databaseを必要とし、書き込みとデータベースの作成(親ディレクトリは対象外)を明示的に許可します。データベースのエラーがメモリにフォールバックすることはありません。DuckDB がファイルを拒否した場合、エラーメッセージは DuckDB 自身のメッセージより前に、DuckLocal がファイルのヘッダーから読み取った理由(より新しい DuckDB で書かれた、v0.9 時代のファイル、SQLite ファイル、データベースではない)と、代わりに実行すべきこと(より新しいファイルなら、そのリリースで作成するATTACH … (STORAGE_VERSION)/COPY FROM DATABASEのコピー、SQLite ならそれを読み取るATTACH)で始まります。--limit Nは正の整数で、デフォルトは 1000 で、返される行数の上限です。2,000,000 セルの予算も適用されます。上限に達した後も、CLI は値をエンコードせずに最大 100,000 行までカウントを続け、total_rowsとtotal_rows_exactを報告します。これは出力を制限するもので、計算やメモリを制限するものではありません。並べ替えや集計は入力全体を処理する可能性があります。出力の上限に達した後に発生した実行エラーでも、コマンドは失敗します。--format json(デフォルト)は以下の契約です。--format mdは同じ結果を Markdown の表として描画し、ドキュメントやそれを読むエージェント向けです。--format htmlは自己完結した 1 つの Web ページとして描画します。HTML 出力 を参照してください。それ以外は何も変わりません。同じ SQL、同じ上限、同じエラーです。- フラグの重複や不明なフラグ、値の欠落、空の SQL、不正な上限はエラーです。オプションは
--flag=valueではなく、値を別に指定します。相対パスは SQL ファイルのディレクトリではなく、プロセスの作業ディレクトリを基準に解決されます。シェルのパスは引用符で囲み、SQL 内ではアポストロフィを 2 つ重ねます('O''Brien.csv')。SQL の識別子は二重引用符を使います。
読み取り専用は、ファイルシステムやネットワークのサンドボックスではありません。 データベースが読み取り専用でも、COPY などの SQL はファイルを書き込めます。実行前に、出力パス、上書き、データベースの変更、拡張機能のインストール、外部アクセスを承認してください。DuckLocal は拡張機能を自動でインストールしたり、操作を再試行したりしません。承認があれば、明示的な INSTALL/LOAD SQL は引き続き可能です。インストールされた拡張機能は自動読み込みされる場合があります。失敗したコマンドがすでに副作用を実行している可能性があります(たとえば出力の失敗の前など)。再試行する前に出力先を確認してください。
Markdown 出力
--format md は描画であり、2 つ目の契約ではありません。値は JSON が保持しているもので、結果グリッドでの表示方法で書かれます。
| 値 | 表示 |
|---|---|
NULL | NULL |
| 整数、decimal、float | 値が持つ桁そのまま — DECIMAL(38,10) はスケールを保持し、NaN/inf/-inf はそのまま表記されます |
DATE | YYYY-MM-DD |
TIMESTAMP | YYYY-MM-DD HH:MM:SS[.fffffffff]。小数部は値にある場合のみ、その桁数だけ付きます。タイムゾーンは付加されません。--format json は生のカウントを保持します |
TIME | HH:MM:SS[.ffffff] |
INTERVAL | DuckDB が書くとおり: 1 month 2 days 00:00:00.000003 |
BLOB, GEOMETRY | 0x00ff。長い場合は … で省略されます |
LIST, STRUCT, MAP | [1, 2]、{x: 1}。120 文字を超えると … で省略されます |
セル内の | はエスケープされ、改行は <br> になるため、値が入っている表を壊すことはありません。行のない結果の後には _0 rows._ が付き、--limit やセルの予算で途中で切られた結果には _Truncated at 2 of 5000 rows, so this is not the whole answer._(100,000 行のカウントを超える場合は of at least …)が付きます。プレビューは完全な回答のように読めるべきではありません。エラーは変わりません。stderr に JSON、stdout は空です。
HTML 出力
ducklocal query --sql "SELECT * FROM 'sales.csv'" --format html > sales.html--format html は --format md と同じ値を 1 つの Web ページとして書き出します:
- 行数と列数、経過時間、結果のもとになった SQL(折りたたみ表示)。
- 列名とその型。数値は右寄せされ、
NULLには印が付きます。 - 見出しをクリックすると並べ替えます。
NULLは常に最後です。フィルター欄に入力すると、一致する行だけが残ります。 --limitやセル数の上限で途中までになった結果は、Markdown と同じくその旨を表示します。
スタイルとスクリプトはインラインで、ページは何も取得しません。そのためディスクから直接開け、GitHub Pages などにそのまま公開できます。すべてのセルは HTML エスケープされます。
クエリできる対象を把握する
ducklocal schema は「何があり、その列は何か」を 1 回の呼び出しで答えます。DESCRIBE はリレーションを 1 つずつ答えるものです。エージェントが最初に実行すべきコマンドです。
ducklocal schema ./data/ # files, folders, globs
ducklocal schema --database warehouse.duckdb # tables and views
ducklocal schema warehouse.duckdb --table orders # one relation, whole
ducklocal schema ./logs/ --full # everything, however largePATH はウィンドウへのドロップと同じように展開されます。フォルダーのデータファイルは再帰的に(隠しファイルはスキップし、最大 256 件)、glob は一致したもの、データベースファイルは --database で指定した場合と同じように扱います。1 つの JSON オブジェクトが返ります:
{"detail":"full","relations":[{"name":"data/orders.csv","kind":"file","from":"'data/orders.csv'","rows":null,"column_count":2,"path":"data/orders.csv","columns":[{"name":"channel","type":"VARCHAR"},{"name":"amount","type":"BIGINT"}]}],"without_columns":0}| フィールド | 意味 |
|---|---|
name | 指定されたとおりのファイルのパス(作業ディレクトリ配下なら作業ディレクトリからの相対パス)、またはこの接続の SQL が到達するテーブル名。デフォルトスキーマでは裸の名前、それ以外では schema.table |
kind | file、glob、table、view、workbook のいずれか |
from | それを読む SQL で、FROM の後にそのまま置けます。引用符で囲んだパス、または必要な場合は引用符で囲んだ識別子 |
rows | テーブルではカタログの推定値、Parquet では正確な値(フッターから)、知るのにスキャンが必要な場合(CSV、JSON、ビュー)は null |
column_count, columns | DuckDB が記述するとおりの列 |
files | glob の場合、一致するファイル数 |
一致するものがすべて同じ形式の glob は 1 つのリレーションで、.dash の source が読むように読み取られます(ducklocal schema 'logs/*.csv')。--stats もそれを 1 つとしてプロファイルします。形式が混在する glob とフォルダーは、ファイルを 1 つずつ一覧表示します。
小さいカタログは全体が返ります("detail": "full")。12 リレーションまたは 400 列を超えると、代わりにサマリー("detail": "summary")になります。行数が最も多い 5 つのリレーションは列を保持し、残りは名前、種類、行数、列数のみを一覧表示し、without_columns がその数を示します。さらに取得するには、hint が 2 つの方法を挙げます。1 つのリレーションには --table NAME(名前、裸のテーブル名、ファイル名で一致)、すべてには --full です。ワークブックはテーブル関数を持たないため、sheets とともに列なしで一覧表示されます。--stats は最初のシートを読みます。存在しない PATH、または何も指さない --table は終了コード 2 です。
.json.gz や .csv.gz のような gzip 圧縮されたテキストは、source ブロックやウィンドウと同様に、ここでもデータファイルとして扱われます。レコードが 1 つのリストに入っているファイル(たとえば CloudTrail の {"Records": [...]})は、hint を付けて返ります。1 行 1 列のままではラッパーしか説明できないため、hint にはそのレコードを行として読む SQL が示されます。
ファイルを調べて変換する
実際のファイルが存在することを確認した後で:
ducklocal query --sql "DESCRIBE SELECT * FROM 'sales.csv'"
ducklocal query --sql "SELECT * FROM 'sales.csv'" --limit 20
ducklocal query --sql "SELECT sum(amount) AS total FROM 'sales.csv'"
# Only after authorizing this output path:
ducklocal query --sql "COPY (SELECT * FROM 'sales.csv') TO 'sales.parquet' (FORMAT PARQUET)"
ducklocal query --sql "SELECT count(*), sum(amount) FROM 'sales.parquet'"
ducklocal query --sql "DESCRIBE SELECT * FROM 'events.json'"amount が存在すると推測しないでください。まず ducklocal schema または DESCRIBE を実行します。切り詰められたプレビューを合計するのではなく、SQL で全体の集計を計算します。CLI の呼び出しは、GUI の登録済みビューや、互いのインメモリテーブルを共有しません。必要な場合は明示的に永続化します:
# These are separate statements and separate invocations, with explicit write permission.
ducklocal query --database warehouse.duckdb --read-write --sql "CREATE TABLE sales AS SELECT * FROM 'sales.csv'"
ducklocal query --database warehouse.duckdb --sql "SELECT count(*) FROM sales"データベースのロック競合はエラーです。もう一方の書き込み側(GUI を含む)を閉じるか、承認されたコピーを使います。ロックファイルを削除したり、別のデータベースを黙って作成したりしないでください。
JSONL とネストした JSON
read_ndjson_objects は改行区切り JSON(1 行に 1 オブジェクト、.jsonl/.ndjson)のリーダーです。read_json/read_json_auto は JSON ドキュメント(配列または単一のオブジェクト)を読みます。JSONL ファイルでは自動検出に頼らず、リーダーを明示的に指定してください。json_extract_string(col, '$.a.b[0].c') はオブジェクトのキーと配列のインデックスからなるネストしたパスをたどり、VARCHAR を返します:
ducklocal query --sql "SELECT json_extract_string(event, '$.payload.items[0].sku') AS sku, count(*) AS n FROM read_ndjson_objects('events.jsonl') GROUP BY 1 ORDER BY n DESC"リーフが文字列ではなく、JSON として得たい場合は、代わりに json_extract を使います。
列の統計
ducklocal schema --stats は、グラフ、スケール、数値の書式を決める問いに、それらを作る前に答えます。DESCRIBE は列が DOUBLE だと述べますが、統計は小数点以下を 2 桁使っていること、最大値が中央値の 1000 倍であること、日付が途中で 11 日飛んでいることを示します。
ducklocal schema sales.csv --stats
ducklocal schema ./exports/ --table orders.parquet --stats
ducklocal schema --database warehouse.duckdb --table "my orders" --stats--stats は 1 つのリレーションをプロファイルします。引数が指す唯一のもの、または --table が選ぶものです。--table なしで 2 つ以上を指定すると終了コード 2 になり、その旨のヒントが表示されます。--full とは併用できません。以前のリリースの ducklocal profile TARGET [--database PATH] は同じレポートで、引き続き動作します。
リレーションはデータファイル(csv、tsv、txt、parquet、json、ndjson、jsonl)、ワークブック(xlsx、xls、xlsb、ods。最初のシートが TEMP テーブルとしてインポートされ、プロファイルされます)、または --database がある場合はテーブル名かビュー名です。ドット付きの名前は schema.table として読まれ、各部分は引用符で囲まれるため、スペースや大文字を含む名前も書いたとおりに動作します。何も指さないリレーションは、SQL のエラーではなく引数のエラー(終了コード 2)です。
1 つの JSON オブジェクトが返ります。target、relation(統計を実行した対象の SQL)、row_count、elapsed_ms、およびリレーション自身の順序での columns です。列ごとに:
| フィールド | 意味 |
|---|---|
name, type | DESCRIBE が報告するとおり |
nulls | 列が NULL である行 |
distinct | 推定ではなく正確な値 |
unique | distinct が row_count と等しい場合に存在し true |
min, max | テキストとして。DECIMAL が桁を保持します |
decimals | 列が 実際に使っている 小数点以下の桁数。宣言されたスケールではありません |
median | 列が保持する値そのもので、2 つの値の間の補間ではありません |
max_over_median | 最大値が中央値の何倍か。線形軸と対数軸のどちらにするかを決める数値です |
covered_days, span_days, missing_days | 列が示す日数、その両端の間の日数、その差。0 は連続した系列で、それ以外は線が上を通ってしまう穴です |
decimals、median、max_over_median は数値の列に現れ、日のフィールドは日付とタイムスタンプに現れます。LIST、STRUCT、MAP、UNION の列は nulls のみを報告します。min と max はこれらには定義されていません。
数値と 1 つの短い単語(R の NA など)を含むテキスト列は、null_marker と null_marker_rows も報告します。その場合、レポートには列を数値として読む read_csv 呼び出しを示す hint が追加されます。
統計は正確でリレーション全体を読むため、フルスキャンのコストがかかります。--limit は適用されません。サンプルのプロファイルはプロファイルではありません。
実行中のウィンドウに作業を表示する
ducklocal open は、すでに実行中の DuckLocal ウィンドウに何かを渡し(なければ起動し)、そのウィンドウを前面に出します。エージェントが自分の作業を人の前に出し、そこから続けてもらうための方法です:
ducklocal open --title "Revenue by channel" --run --sql "SELECT channel, sum(amount) AS total FROM 'orders.csv' GROUP BY 1"
ducklocal open sales.dash # a dashboard tab
ducklocal open ./data/ --sql-file analysis.sql
echo "SELECT 42" | ducklocal open --sql-file - --no-launch- PATH はウィンドウへのドロップと同じように開きます。
.dashファイルはタブ、DuckDB データベースファイルはウィンドウのデータベース、データファイル、フォルダー、glob はビューとしてアタッチされます。相対 PATH はコマンドのディレクトリを基準に解決されます。ウィンドウの起動中に届いたリクエストは、起動時の open が完了するまで待機します。 --sqlまたは--sql-file(-は標準入力を読む)は、--titleというタイトルで新しいクエリタブを開きます。--runは PATH がアタッチされた後にそれを実行します。--no-launchはウィンドウを起動せずに、種類not_runningで失敗します。頼まれずにウィンドウが現れるのを好まないマシン向けです。
成功すると {"delivered": true, "launched": BOOL} を出力します。結果ではなく、配信の成否です。開かれたものはウィンドウ自身のセッション(その接続、アタッチされたビュー、履歴)で実行され、エラーは stdout ではなくそこに表示されます。引数のエラーは終了コード 2、それ以外は終了コード 1 で、種類は not_running(到達できるウィンドウがない)、refused(ウィンドウがリクエストを拒否した)、launch です。
ウィンドウはループバックポートで待ち受けます。ポートとランダムなトークンを、あなたのアカウントだけが読めるファイルに書き込みます(設定とアプリデータ を参照)。同じマシンの別のユーザーや、localhost を狙う Web ページからは到達できません。
ウィンドウの表示内容を読み取る
ducklocal open --state は逆方向です。何も開かず、ウィンドウも起動せず、実行中のウィンドウが表示している内容を出力します。これにより、エージェントは人にクエリを貼り付けてもらう代わりに、人がやめたところから引き継げます。
ducklocal open --state
ducklocal open --state sales.dash
ducklocal open --state --active{"database":":memory:","attached":[{"path":"/Users/me/data/orders.csv","name":"orders","rows":224}],"active_tab":1,"tabs":[{"kind":"query","title":"Query 1","active":false,"sql":"SELECT …","result":{"status":"rows","columns":[…],"row_count":5,"truncated":false,"preview":[["Web","132771.24"],…],"sql":"SELECT …","elapsed_ms":4}},{"kind":"dashboard","title":"sales","active":true,"path":"/Users/me/data/sales.dash","unsaved":false,"dashboard":{"running":false,"error":null,"stale":null,"plots":[…],"filters":[{"name":"channel","plot":"revenue_by_channel","column":"channel","picked":true,"value":"Web"}]}}]}databaseは開いているデータベースファイル、または":memory:"です。attachedはウィンドウがビューとして登録したファイルを、ビューのnameとともに一覧表示します。CLI のクエリはこれらのビューを読めません。pathを使ってください。- クエリ タブは、実行されたかどうかに関係なくエディタのテキストである
sqlと、resultを持ちます。statusはempty、running、rows、affected、failed、explain、profileのいずれかです。行の場合はcolumns、row_count、truncated、preview(グリッドでの表示どおりの最初の 20 行、文字列として)、elapsed_ms、およびそれらを生成したsql、affectedの場合はcountとelapsed_ms、失敗の場合はerrorです。 - 人がグラフタブで列を選ぶと、結果には
chartも含まれます。type、x、y、split、および同じグラフをダッシュボードで描画するqueryブロックとplotブロックであるdashです。 explainは Explain が表示するものです。DuckDB のEXPLAIN出力をテキスト行の配列にしたplanと、elapsed_msです。profileは Profile が表示するものです(SQL エディタ を参照)。EXPLAIN ANALYZEが計測した演算子ツリーをルートの配列にしたplanで、各要素は{operator, seconds, rows, estimated, children}です。secondsは子を除いた演算子自身の時間、rowsは生成した行数、estimatedはオプティマイザーが推定したrows(プランに記載がない場合はnull)、childrenは同じ形です。operator_secondsはすべての演算子自身の時間の合計で、シェアが合計する対象であり、実時間ではありません。elapsed_msは実行全体です。- ダッシュボード タブは
path、unsaved、dashboardを持ちます。dashboardにはcomments_fileのパス、plots(名前、種類、タイトル、クエリ、行数、open_comments、描画できない場合のfailure)、および各フィルターが選んだ値を持つfiltersがあります。filtersの各要素はpicked、value(最初の値)、values(選ばれたすべての値、順序どおり)、multipleを持ちます。value: nullとpicked: trueは NULL 値が選ばれたことを意味します。
--state sales.dash を使うとそのダッシュボードを表示しているタブだけを、--state --active を使うとアクティブなタブだけを取得できます。開いていないパスは終了コード 1、種類 not_open を返し、ヒントに開いているダッシュボードが示されます。active_tab は返された tabs 内でのアクティブなタブのインデックスで、そこに含まれない場合は null です。database と attached は引き続き含まれます。
--state は 1 つの .dash PATH か --active のどちらかを受け付け、両方は受け付けません。--no-launch は受け付けられますが何も変わりません。--sql や --run を含むその他のオプションは無効です(終了コード 2)。ウィンドウが起動していない場合は終了コード 1、種類 not_running、5 秒以内に応答しない場合は timeout です。
ダッシュボードの仕様を検証する
形式そのもの(ブロック、属性、グラフの種類、SQL のルール、よくあるメッセージ)は ダッシュボード(.dash) で説明しています。このセクションではコマンドについて説明します。
.dash ファイルは、Terraform がインフラを宣言するのと同じように、ダッシュボードをスクリプトで書くのではなく宣言します。クエリとグラフをブロックとして記述し、それらの間で参照します。人にもエージェントにも書きやすく、差分も取りやすい形式です。
query "latency" {
sql = <<SQL
SELECT timestamp, service, avg(latency) AS latency
FROM logs
GROUP BY timestamp, service
SQL
}
plot "latency" {
type = "line"
query = query.latency
x = timestamp
y = latency
series = service
}ducklocal check dashboard.dash
ducklocal check dashboard.dash --database warehouse.duckdb
ducklocal check dashboard.dash --summarysource ブロックは、クエリが読むデータファイルを .dash ファイルからの相対パスで指定し、view ブロックは複数のクエリが共有する SQL を保持します。query ブロックは 1 つの sql 属性、つまりヒアドキュメントか文字列で書かれた 1 つの読み取り専用ステートメントを持ちます。SELECT、WITH、FROM で始まるもの、VALUES、SHOW、DESCRIBE、SUMMARIZE、PIVOT が受け付けられます。書き込みの可能性があるもの(DDL、DML、COPY、ATTACH、INSTALL)は診断となり、GUI はその実行を拒否します。ダッシュボードのクエリはファイルを開くたびに実行されるためです。plot ブロックは type(line、bar、stacked_bar、area、scatter、pie、heatmap、histogram、map、timeline、table、card、text のいずれか)、query(同じファイル内のクエリブロックへの query.latency のような参照)、その列、および省略可能な title と width を持ちます。filter ブロックは棒グラフや表をクリック可能にし、1 つの値、または棒グラフでは multiple = true で複数の値を選べるようにします。クエリは選ばれた値を $name として読み取ります。# と // は行末までコメントになります。すべての属性は ダッシュボード(.dash) にあります。
text グラフは例外で、title、text、またはその両方を持ち、query を取りません。カードは note と tone も使えます。カードとテキストパネル を参照してください。
まず静的チェックを行います。各クエリの SQL を、query が実行前に検証するのと同じ方法で、使い捨ての接続上で実際の DuckDB パーサーに通し、すべての $name をフィルターブロックと照合します。SQL は各 $name を TRUE として解析・実行されます。これはダッシュボードが何も選ばれる前に実行する内容です。
次に、すべてのクエリが、ダッシュボードを開いたときとまったく同じように実行され(読み取り専用、ソース付き、同じコードパスと同じ行予算)、各グラフの列がクエリが実際に返す列と照合されます。数値でない y はすべてのグラフの種類でエラーであり、map の数値でない座標や size も同様です。また、グラフのクエリが返さない column を持つフィルターもエラーです。
--databaseなし の場合、クエリはメモリ内で実行されます。独自のsourceファイルを使うダッシュボードにはこれで十分です。ソースが定義していないテーブルを読むクエリは、検証に渡されなかったデータベースを対象としている可能性があります。その場合は失敗ではなくunresolved(クエリ、行、理由)に一覧表示され、そのグラフの列はチェックされません。--database PATHあり(既存のファイル、読み取り専用)の場合、そのデータベース上で実行されます。クエリがデータベースのテーブルを読む場合は常に指定してください。unresolvedにあるものはチェックされていません。
フィルターを読むすべてのクエリは、そのバリアントを実行することなく、選ばれた値でも束縛されます。これにより、最初の $name = TRUE のバージョンが動作していても、消費するクエリからフィルターの列が欠けていることを検出できます。フィルターは、それを選ぶグラフが返す列も参照している必要があります。
計画だけでなく実行することが重要です。ビルドが実行できないキャストや、変換できない値など、一部の失敗は行を読んだ後に初めて現れます。それらを見逃す検証は、描画できないダッシュボードを渡してしまうことになります。クエリは全体が実行されるため、大きなデータベースに対する検証はダッシュボードを開くのと同じくらいの時間がかかります。
成功すると、ファイルのソース(それぞれの resolved パス付き)、ビュー、クエリ(結果の列と rows、何も選ばれていない状態で返した行数、ダッシュボードの行予算で切られた場合は truncated: true 付き)、フィルター(それぞれを読む queries 付き)、グラフ、unresolved、および empty(実行されて 0 行を返したクエリ)を一覧表示する 1 つの JSON オブジェクトが返ります。空のクエリは他のすべてのチェックに合格しますが、通常は正規表現、フィルター、結合が何にも一致しなかったことを意味するため、それぞれを確認してください。--summary を指定すると、成功時は 1 行のコンパクトな JSON になります:
{"file":"sales.dash","ok":true,"sources":1,"views":0,"queries":3,"filters":1,"plots":6,"unresolved":[],"empty":[]}5 つのブロックのフィールドは件数です。unresolved はチェックできなかったクエリ、empty は 0 行を返したクエリを一覧表示します。
不具合のあるブロックは除外され、有効なブロックは検証を続けます。仕様のエラーとクエリの失敗は同じ実行で収集され、それぞれ 1 つの file:line: message になります。仕様の診断が 1 つでもある場合、終了コードは 2 で種類は spec です。SQL の実行または束縛だけが失敗する場合は、終了コードは 1 で種類は sql です。データベースと I/O の失敗も終了コード 1 です。--summary は診断を隠しません。
同じファイルは GUI でダッシュボードのタブとして開きます。ducklocal dashboard.dash、ducklocal open dashboard.dash、またはウィンドウへのドラッグです。グラフは 12 列のグリッドに配置され、描画できないグラフは理由をその場に表示します。ダッシュボード(.dash) を参照してください。
セマンティックモデルの指標
ducklocal metrics # ./model.ossie.yaml
ducklocal metrics compile --metric error_count,event_count --by events.ip
ducklocal metrics query --metric event_count --by events.event_time:day \
--views reports/investigation.dash --restricted --allow-read dataducklocal metrics は Apache Ossie のモデル model.ossie.yaml を読み、その指標とフィールドを一覧表示します。compile はリクエストに答える DuckDB の SELECT を 1 つ出力し、データは読みません。query はそれを ducklocal query と同じように実行し、SQL とモデルの sha256 を記した semantic オブジェクトを付けます。モデルが正確に答えられないリクエストは、metric_fanout などの kind 付きで拒否され、終了コードは 2 です。モデルの形式、すべてのオプション、すべての拒否理由は セマンティック指標 にあります。
ダッシュボードのレビューコメント
人はウィンドウでグラフにコメントすることでダッシュボードをレビューします。グラフにカーソルを合わせ、吹き出しをクリックします(コメントでレビューする を参照)。ducklocal comments はエージェント側で、ウィンドウなしでスレッドを読み、返信します。
ducklocal comments sales.dash [--all]
ducklocal comments sales.dash --reply c1 --text "Sorted by revenue, descending" [--resolve]
ducklocal comments sales.dash --resolve c1
ducklocal comments sales.dash --reopen c1
ducklocal comments sales.dash --add revenue_by_channel --text "Is this net of refunds?"- アクションを指定しない場合、開いているスレッドを出力します:
{file, comments_file, open, threads}。--allは解決済みのものも含めます。 - 各スレッドには
id、plot、およびエージェントが仕様内でそれを見つけるために必要な情報(plot_title、plot_query、plotブロックの最初と最後の行であるplot_lines(仕様が解析できない場合はnull))があります。その名前のグラフが残っていない場合はplot_missingがtrueです。続いてresolvedとcommentsがあり、それぞれにauthor(userまたはagent)があり、エージェントのコメントにはname(presenceが表示する名前)、text、at(RFC 3339、ローカル時刻)があります。 --reply ID --text TEXTはエージェントの回答を追加します。解決済みのスレッドへの返信は、--resolveも指定しない限り、そのスレッドを再び開きます。--resolve IDと--reopen IDはスレッドの状態を変更します。--add PLOT --text TEXTはスレッドを開始し、エージェントとして署名します。- スレッドの番号は ID として使えます。
--reply 1はc1を意味します。--addは仕様にないグラフを拒否し(終了コード 2)、ヒントにそのグラフの一覧が表示されます。 - アクションは変更後の
{thread}を出力します。
スレッドは仕様の隣の FILE.comments.json に保存されます。実行中のウィンドウは 1 秒以内に変更を検知し、グラフ上に表示します。不明なスレッド ID は終了コード 2 で、スレッドを一覧表示するヒントが付きます。存在しない仕様ファイルは終了コード 1 です。
レビューの流れを最初から最後まで: 開いているスレッドを読み、仕様を編集し、ducklocal check を実行し、変更内容を各スレッドに返信して --resolve します。人に質問を返したい場合は、--resolve なしで --reply を使います。
エージェントのアクティビティを表示する
check と comments は、エージェントがどのダッシュボードで作業しているかを実行中のウィンドウに自動的に伝えます。presence は編集が行われる前にそれを通知できます:
ducklocal presence sales.dash --doing editing --plot revenue_by_channel,daily_revenue
ducklocal presence sales.dash --doing reading --agent "Analyst"
ducklocal presence sales.dash --doing idle--doingはreading、editing、idleを受け付けます(doneはidleの別名です)。--plotはカンマ区切りのグラフ名を取ります。editingの場合、新しい名前も許可され、プレースホルダーとして表示されます。readingまたはidleの場合、不明な名前は終了コード 2 です。- 表示される名前は
--agent、次にDUCKLOCAL_AGENT、次に検出されたエージェント環境(Claude、Codex、Cursor、Gemini)から取得され、どれもなければAgentになります。 - 出力は
{delivered}です。実行中のウィンドウがない場合は、エラーもウィンドウの起動もなしに{"delivered":false}を返します。
コマンドがセッションをアクティブに保つ間、名前はダッシュボードの隅に表示されます。クリックするとアクティビティログが開きます。30 秒間の無音または --doing idle でセッションは終了します。変更・追加されたグラフは表示されるまでマークが残り、削除されたグラフの通知は閉じられるまで残ります。エージェントの作業を表示する を参照してください。
LSP でダッシュボードの仕様を編集する
ducklocal lsp は、エディタが起動する .dash ファイル用の Language Server Protocol サーバーで、stdio 経由で動作します。LSP に対応したあらゆるエディタに、GUI 自体の仕様エディタと同じ機能を提供します:
- 診断:
checkが報告するもので、開くたび、変更するたびに公開されます(ドキュメント全体の同期、すべて重大度 Error です。スタイルではなく誤りです)。 - 補完: ブロックの種類、属性名、グラフの種類、
query.とplot.の後の名前。それぞれに入力中の単語を置き換えるテキスト編集が付きます。 - ホバー: ブロック、属性、参照のドキュメント。
- 定義へ移動:
query.nameまたはplot.nameの参照から、そのブロックの名前に移動します。
--database PATH を指定すると、各クエリの SQL が check --database と同じ方法で、実際の DuckDB パーサーによって追加で検証されます。
エディタの汎用 LSP サポートを *.dash ファイルに対して ducklocal lsp に向けてください。このコマンドはドキュメント引数を取らず、エディタは stdio で通信します。Neovim(0.10 以降)の場合:
vim.api.nvim_create_autocmd("FileType", {
pattern = "dash",
callback = function(event)
vim.lsp.start({
name = "ducklocal",
cmd = { "ducklocal", "lsp" },
root_dir = vim.fs.dirname(vim.api.nvim_buf_get_name(event.buf)),
})
end,
})VS Code では、汎用 LSP 拡張機能がコマンド ducklocal、引数 ["lsp"]、ドキュメントセレクター dash で同じことを行います。終了コード: 正常な shutdown/exit の後は 0、クライアントがそれをせずに消えた場合は 1、不正なコマンドラインまたはプロトコルハンドシェイクの失敗は 2 です。
JSON の契約
成功したクエリは、stdout に 1 つの JSON オブジェクトを書き込み、その後ろに改行を付けます:
{"columns":[{"name":"n","type":"Int32"}],"rows":[[1]],"row_count":1,"truncated":false,"total_rows":1,"total_rows_exact":true,"elapsed_ms":1}columns と各行は列の順序と重複した列名を保持します。type は Arrow のデバッグ表現 であり、元の DuckDB SQL の型名ではありません(たとえば HUGEINT と DECIMAL が同じ Arrow のキャリアを共有できます)。row_count は返された行数を数えます。total_rows は生成された行数を数え、出力の上限の後に数えたものも含みます。total_rows_exact: false は最大 100,000 行の追加カウントの後に数えるのをやめたことを意味するため、その合計は下限です。どちらのカウントも影響を受けた行数ではありません。elapsed_ms は準備、実行、行のエンコードを計測し、ファイルの読み込みや接続の設定は含みません。0 行の結果もメタデータを保持します。DDL/DML は実際の DuckDB の結果を公開し、Count 列も含みます。INSERT/COPY は通常 [[N]] を返し、CREATE TABLE は通常行を返しません。最初の SQL キーワードから分類されることはありません。
セルのエンコード:
| SQL の値 | JSON のエンコード |
|---|---|
| NULL | null(文字列 "NULL" にはなりません) |
| Boolean、有限の float | JSON の真偽値/数値 |
| ±9,007,199,254,740,991 以内の整数 | JSON の数値 |
| それより大きい整数(HUGEINT/UHUGEINT を含む) | {"encoding":"integer","value":"9007199254740992"} |
| Decimal | {"encoding":"decimal","value":"123.450"}。正確な decimal のテキスト付き |
| テキスト、enum | JSON の文字列 |
| Blob、geometry | {"encoding":"hex","value":"00ff"}。小文字のバイト列、geometry は WKB を使用 |
| Date | {"encoding":"date","unit":"Day","value":"1","iso":"1970-01-02"}。1970-01-01 からの日数 |
| Timestamp | {"encoding":"timestamp","unit":"Nanosecond","value":"123456789","iso":"1970-01-01T00:00:00.123456789"}。Unix エポックからの符号付きカウント。単位は Second/Millisecond/Microsecond の場合もあります |
| Time | {"encoding":"time","unit":"Microsecond","value":"123456","iso":"00:00:00.123456"}。深夜 0 時からのカウント |
| Interval | {"encoding":"interval","months":1,"days":2,"nanos":"3000"} |
| NaN、正/負の無限大 | {"encoding":"float","value":"NaN"} / "inf" / "-inf" |
| List、array | JSON の配列で、再帰的にエンコードされます(ネストした null を含む) |
| Struct | {"encoding":"struct","fields":[["name",VALUE],...]} |
| Map | {"encoding":"map","entries":[[KEY,VALUE],...]}。JSON オブジェクトではないため、キーは型を保持します |
| Union | {"encoding":"union-value","value":VALUE}。アクティブな値のみで、メンバーのタグは保持されません |
時間値の value は正確なカウントであるため、小数の精度は失われません。日付/タイムスタンプの無限大のセンチネルは生のカウントのままです。それぞれの隣の iso は、読み取り用に ISO 8601 のテキストにした同じ値で、単位が保持するのと同じ桁数の小数部を持ちます。タイムゾーン付きの列(Arrow メタデータ)のタイムスタンプは UTC の瞬間で、その iso は Z で終わります。--format md も日付とタイムスタンプを読みやすく描画します。固定された DuckDB の Arrow ラッパーはネストした HUGEINT、UHUGEINT、DECIMAL(38,0) を区別できないため、null でない値が出現すると、符号や精度を黙って変える代わりに明確なエラーを出します。そのようなフィールドは SQL で明示的に VARCHAR にキャストしてください。未知の未サポートの型もエラーになります。エラーを空の結果と間違えないでください。Union のエンコードはアクティブな値の表現であり、ロスレスな union の往復ではありません。
エラーは stderr に 1 つの JSON オブジェクトを書き、stdout は空のままにします:
{"error":{"kind":"argument","message":"Unknown query option: --limt","hint":"Did you mean --limit?"}}hint は、次のステップがこの CLI 自身の言葉でわかる場合に含まれます。綴りを間違えたフラグが意図していたフラグ、読み取り専用データベースで拒否された書き込みに対する --read-write、存在しないテーブルに対する ducklocal schema、変換できない値に対する TRY_CAST、複数のステートメントを含むスクリプトの分割、裸の列の別名として使われたキーワードに対する AS(SELECT count(*) AS minutes、または引用符で囲む)などです。エージェントは SQL を書き直す前にそれに従うべきです。構文エラーなど、DuckDB 自身のメッセージに付け加えることがない場合は含まれません。
終了コード: 成功は 0、無効な引数やステートメント数は 2、SQL、データベース、I/O、出力の失敗は 1 です。エラーの種類は argument、sql、database、io、output、check の場合は spec、open の場合は not_running、not_open、refused、timeout、launch です。stdout を解析する前に終了ステータスを確認し、完全性を報告する前に truncated を確認してください。ヘルプとバージョンはプレーンテキストの例外です。stdout のパイプが閉じられたなどの転送の失敗は、空または完全な出力ストリームを保証できません。
公式スキルをインストールする
このスキルは、エージェントの回答を誠実に保つ習慣を教えます。スキーマを確認し、上限付きのサンプルをプレビューし、SQL で集計を計算し、truncated を確認し、返された値から答えます。スキーマの確認、列の統計、変換、データベースのクエリ、.dash ダッシュボードとそのレビューコメント、ウィンドウへの作業の受け渡しと読み戻しを扱います。S3 のブラウズ、空間専用のコマンド、セッションの記憶、MCP サーバーは提供しません。
アプリから。 コマンドラインと AI…(タイトルバーのロボットボタン、または DuckLocal メニュー)を開きます:
- コマンドをインストール は
ducklocalをPATHに追加し、エージェントのシェルから実行できるようにします。 - Claude Code に追加 はスキルを
~/.claude/skills/ducklocalに書き込み、Claude Code がすべてのプロジェクトで見つけられるようにします。書き込まれるのはスキル自身の 2 つのファイルだけです。そのフォルダーにある他のものは保持されます。DuckLocal の更新で新しいスキルが提供されると、ダイアログに スキルを更新 が表示されます。 - 概要をコピー は、他のエージェント(Codex、Cursor、チャットウィンドウ)向けの短い説明をコピーします。説明にはコマンド名とその使い方が含まれます。
手動で。 スキルは skills/ducklocal です。代わりに 1 つのプロジェクトに追加する場合(Claude Code の例):
# Run from the DuckLocal checkout; replace the destination with your project.
mkdir -p /path/to/your-project/.claude/skills
cp -R skills/ducklocal /path/to/your-project/.claude/skills/ローカルの変更を上書きする前に、既存の出力先を確認してください。他のエージェントは、サポートされているスキルディレクトリで同じ SKILL.md と references/cli.md を使えます。
