デバッグとトラブルシューティング

このページは、何かがうまくいかないときのためのものです。プログラムが検査で拒否される、Runが失敗したり止まったりする、結果が期待と違う。そんなときに確認する場所を、問題に出会う順に並べています。

調べる順番Copy Anchor Link

問題が表面化する場所は4つあり、それぞれに対応するツールがあります。

上から順に見てください。失敗の大半は、どのシステムにも触れずに check で見つかります。--profile mock なら、認証情報なしでCheckpointまでプログラムを動かせます。

Checkの失敗Copy Anchor Link

check は、見つけられる問題をすべて、名前の付いた理由と場所とともに報告します。

$ actql check churn-risk.aql
Check  failed
  expression_type_mismatch   line 7
    risk.value.level = 1   level is STRING, got INT64
  parameter_undeclared       line 3
    @since is used but not declared

理由の名前は固定されていて、Checkの理由カタログに一覧があります。よく見かけるものは次のとおりです。

check --json は同じ報告をデータとして返します。エージェントは、書き直す前にこれを読みます。警告だけなら check は 0 を返し、エラーがあれば 1 を返します。

どの理由も、プログラムが間違っているという意味ではありません。3つのことが別々に報告されます。プログラムが不正である（query_syntax_invalid、expression_type_mismatch。テキストを直す）。検査が未完了である（値が足りない parameter_value_required、検査の上限に達した analysis_budget_exhausted、権限の範囲で解決できない unresolved_protected。値を渡すか、確認する。プログラム自体は正しいかもしれない）。あるいは、正しいプログラムをこのHostが実行できない（implementation_limit）。判定、検査の完全性、実行環境の対応は3つの事実として読み、1つの深刻度にまとめないでください。

Planの問題Copy Anchor Link

check は通るのに explain が拒否するなら、プログラムは正しいものの、Hostが上限を決められていません。件数の上限がない読み取り元、項目数を確定できないLLMのステップ、プログラムが頼りにしているのに接続が宣言していないCapability、などです。メッセージは、足りない上限やCapabilityの名前を示します。LIMIT か MAX ITEMS のガードか、読み取り元が評価できる絞り込みを足してください。配置の決まり方はPlanとプッシュダウンにあります。

Runの失敗Copy Anchor Link

failed で終わったRunは、どこで失敗したかを示します。

$ actql status run_…
Run run_…
  Status   failed
  Failed   read snowflake.usage_30d
           ACTQL_E_SOURCE_READ_FAILED  Snowflake: SQL compilation error: Object 'USAGE_30D' does not exist
  Effects  none sent

状態ごとの読み方です。

Runが黙って途中で打ち切られることはありません。超えた上限は失敗の中に名前で示され、途中までの結果が完全なものとして出てくることもありません。どのエラーにも固定の ACTQL_E_* コードがあり、status --json はRunの完全な状態とともにそれを返します。

同じプログラムをもう一度実行すると、新しいRunができます。古いRunは証跡とともに保持期間のあいだStoreに残るので、比較できます。

結果が期待と違うときCopy Anchor Link

• INFER のあとのレコードが思ったより少ない。 結果が ok でないレコードは value = NULL になり、WHERE risk.value.level = 'high' でこぼれ落ちます。まず結果を見てください。|> AGGREGATE COUNT(*) GROUP BY risk.outcome です。
• 絞り込みが無視されているように見える。 適用はされています。読み取り元の中で動いているか（explain）、そして読み取り元の意味が違っていないか、たとえば文字列の比較で大文字と小文字が区別されるか、を確認してください。
• LLMの答えがおかしい。 保証されているのは型であって、判断ではありません。mockプロファイルは決まった答えを返すので、プロンプトの良し悪しは分かりません。mockで確かめるのはLLMの前後、つまり入力の列、型、失敗したレコードの扱い、Effectです。タスクの指示の2つのバージョンを比べるには、同じ評価用のレコードに対して、本物のプロバイダーで両方を動かします。
• Effectの結果がプレビューと合わない。 4つのものを区別してください。承認されたプレビュー（ActQLが変えようとした内容）、送信の記録（何をいつ送ったか）、ConnectorのOutcome Receipt（applied、accepted、failed、unknown）、そして外部システムの現在の値です。プレビューは承認された変更内容を固定しますが、外部システムで成功したことは保証しませんし、そのあとで第三者が変えたことについては何も言いません。unknown の結果は突き合わせの対象です。

環境Copy Anchor Link

actql doctor はインストールを確認します。Host、Storeのディレクトリとその鍵、見つかった設定ファイル、そして設定した各接続とプロバイダーに届くかどうかです。actql catalog show <connection> は、接続が公開しているものを表示します。そこにリソースや列がなければ、外部システム側にあっても、プログラムからは見えません。

問い合わせに添える情報Copy Anchor Link

問題を報告したり相談したりするときは、actql check --json --redact、actql explain --json --redact、actql status <run> --json --redact の出力を添えてください。--redact は、システム名、リソース名、パラメーターの値、プレビューの値を安定したプレースホルダーに置き換え、構造、コード、位置は残します。自分のシステムやデータを開示せずに診断できる形です。--redact なしの出力には接続名やリソース名が入り、status ならプレビューの値も入るので、データそのものと同じ扱いをしてください。

次に読むCopy Anchor Link

• Checkの理由カタログ：check が報告しうるすべての理由
• Runのライフサイクルと復旧：状態と突き合わせ
• CLIリファレンス：各コマンドの --json 出力