# データベース実行クエリ \[プラミング] 一連のクエリを一緒に実行します。 > \[!NOTE] > このコンテンツでは、CodeQL CLI の最新リリースについて説明します。 このリリースについて詳しくは、 をご覧ください。 > > 以前のリリースの、このコマンドで使えるオプションを詳しく確認するには、ターミナルで `--help` オプションを指定してコマンドを実行してください。 ## 概要 ```shell copy codeql database run-queries [--threads=] [--ram=] ... -- ... ``` ## Description ``` \[プラミング] 一連のクエリを一緒に実行します。 ``` CodeQL データベースに対して 1 つ以上のクエリを実行し、結果をデータベース ディレクトリの results サブディレクトリに保存します。 結果は後から [codeql database interpret-results](/ja/code-security/reference/code-scanning/codeql/codeql-cli-manual/database-interpret-results) によって、読み取り可能な形式に変換することや、[codeql bqrs decode](/ja/code-security/reference/code-scanning/codeql/codeql-cli-manual/bqrs-decode) または [codeql bqrs interpret](/ja/code-security/reference/code-scanning/codeql/codeql-cli-manual/bqrs-interpret) を使用してクエリ用クエリに変換することができます。 クエリによって、ソース コード アラートとして解釈できる形式で結果が生成される場合、それらを実行するのに [codeql database analyze](/ja/code-security/reference/code-scanning/codeql/codeql-cli-manual/database-analyze) の方が便利な場合があります。 [codeql database analyze](/ja/code-security/reference/code-scanning/codeql/codeql-cli-manual/database-analyze) は、codeql database run-queries と [codeql database interpret-results](/ja/code-security/reference/code-scanning/codeql/codeql-cli-manual/database-interpret-results) を 1 つのステップで結合します。 特に、[codeql database analyze](/ja/code-security/reference/code-scanning/codeql/codeql-cli-manual/database-analyze) では、さまざまなアラート ビューアーで使用できる SARIF 形式の出力を生成できます。 または、実行するクエリが 1 つだけの場合は、[codeql query run](/ja/code-security/reference/code-scanning/codeql/codeql-cli-manual/query-run) をお勧めします。これを使用すると、デバッグ時に、人間が判読できる出力を表示して結果をすばやく検査できます。 ## オプション ### 主なオプション #### `` ``` \[必須] クエリを実行する CodeQL データベースのパス。 ``` #### `...` 実行するクエリ。 各引数は、`scope/name@range:path` の形式になります。ここで、 * ``` `scope/name` は、CodeQL パックの修飾名です。 ``` * ``` `range` は、semver の範囲です。 ``` * ``` `path` は、ファイル システムのパスです。 `scope/name` を指定する場合、`range` と `path` は省略可能です。 `range` がない場合は、指定したパックの最新バージョンを意味します。 `path` がない場合は、指定したパックのデフォルトのクエリ スイートを意味します。 `path` は、`*.ql` クエリ ファイル、1 つまたは複数のクエリを含むディレクトリ、または `.qls` クエリ スイート ファイルのいずれかにすることができます。 パック名を指定しない場合は、`path` を指定する必要があり、現在のプロセスの現在の作業ディレクトリからの相対パスとして解釈されます。 ``` リテラル `path` または `@` を含む `:` を指定するには、引数のプレフィックスとして `path:` を使います (例: `path:directory/with:and@/chars`)。 ``` `scope/name` と `path` を指定する場合、`path` を絶対パスにすることはできません。 これは、CodeQL パックのルートを基準にしていると見なされます。 ``` クエリを指定しない場合、実行する適切なクエリ セットが CLI によって自動的に決定されます。 具体的には、データベースの作成時に `--codescanning-config` を使って Code Scanning の構成ファイルを指定した場合は、そのクエリが使われます。 それ以外の場合は、分析されている言語の既定のクエリが使われます。 #### `--no-rerun` 既に BQRS の結果が出力場所に格納されていると思われるクエリの評価を省略します。 #### `--no-database-extension-packs` ``` \[詳細設定] コード スキャン構成ファイルから、または分析されたコードベースの 'extensions' ディレクトリに格納されている拡張ファイルからデータベースを作成する際に、データベースに格納されている拡張パックを省略します。 ``` #### `--no-database-threat-models` ``` \[詳細設定] コード スキャン構成ファイルからデータベースを作成する際に、データベースに格納されている脅威モデルの構成を省略します。 ``` ### 使用するモデル パックを制御するためのオプション #### ``` `--model-packs=<` >... ``` 評価するクエリをカスタマイズするためにモデル パックとして使用する CodeQL パック名のリスト (それぞれがオプションのバージョン範囲を含む)。 ### 使用する脅威モデルを制御するためのオプション #### `--threat-model=...` 有効または無効にする脅威モデルの一覧。 引数は脅威モデルの名前であり、必要に応じて '!' が付けられます。 '!' が付いていない場合、その名前付き脅威モデルとそのすべての子孫が有効になります。 '!' が付いている場合、その名前付き脅威モデルとそのすべての子孫が無効になります。 "default" 脅威モデルはデフォルトで有効になっていますが、'--threat-model !default' を指定することで無効にすることができます。 "all" 脅威モデルを使用して、すべての脅威モデルを有効または無効にすることができます。 \--threat-model オプションは順番に処理されます。 たとえば、'--threat-model local --threat-model !environment' を指定すると、'environment' 脅威モデルを除き、'local' グループ内のすべての脅威モデルが有効になります。 このオプションは、脅威モデルをサポートする言語にのみ有効です。 ``` `v2.15.3` 以降で使用できます。 ``` ### クエリ エバリュエーターを制御するためのオプション #### `--[no-]tuple-counting` ``` \[詳細設定] クエリ エバリュエーター ログの各評価ステップのタプル数を表示します。 `--evaluator-log` オプションを指定すると、コマンドで生成されるテキストベースのログと構造化された JSON ログの両方にタプル数が含まれます (これは、複雑な QL コードのパフォーマンス最適化に役立ちます)。 ``` #### `--timeout=` ``` \[詳細設定] クエリ評価のタイムアウトの長さを秒単位で設定します。 ``` タイムアウト機能は、複雑なクエリの評価に "かなり長い時間" がかかるケースを検出することを目的としています。 クエリの評価にかかる合計時間を制限するのは効果的な方法ではありません。 評価は、計算の個別に時間指定された各部分がタイムアウト内に完了する限り続行できます。 現在、これらの個別に時間指定された部分は、最適化されたクエリの "RA レイヤー" ですが、将来変更される可能性があります。 タイムアウトが指定されていない場合、またはタイムアウトに 0 が指定されている場合、タイムアウトは設定されません (デフォルトのタイムアウトが 5 分である [codeql test run](/ja/code-security/reference/code-scanning/codeql/codeql-cli-manual/test-run) を除きます)。 #### `-j, --threads=` この数のスレッドをクエリの評価に使用します。 既定値は 1 です。 0 を渡して、コンピューター上のコアごとに 1 つのスレッドを使用したり、*N* を渡して、*N* 個のコアを未使用のままにしたりすることができます (ただし、その場合でも、少なくとも 1 つのスレッドが使用されます)。 #### `--[no-]save-cache` ``` \[[非推奨] \[Advanced] このフラグは何も行いません。 ``` #### `--[no-]expect-discarded-cache` ``` \[詳細設定] クエリの実行後にキャッシュが破棄されるという前提に基づいて、評価する述語とディスク キャッシュに書き込む内容を決定します。 ``` #### `--[no-]keep-full-cache` ``` \[詳細設定] 評価が完了した後、ディスク キャッシュをクリーンアップしません。 ``` これにより、後で [codeql dataset cleanup](/ja/code-security/reference/code-scanning/codeql/codeql-cli-manual/dataset-cleanup) または [codeql database cleanup](/ja/code-security/reference/code-scanning/codeql/codeql-cli-manual/database-cleanup) を実行する場合に時間を節約できます。 #### `--max-disk-cache=` 中間クエリ結果のディスク キャッシュで使用できる最大容量を設定します。 このサイズが明示的に構成されていない場合、エバリュエーターによって、データセットのサイズとクエリの複雑さに基づき、"妥当な" 量のキャッシュ スペースを使うことが試みられます。 このデフォルトの使用量よりも高い制限を明示的に設定すると、追加のキャッシュが有効になり、後のクエリが高速化されます。 #### `--min-disk-free=` ``` \[詳細設定] ファイル システムの空き領域の目標量を設定します。 `--max-disk-cache` が指定されていない場合、ファイル システムの空き容量がこの値を下回ると、エバリュエーターによってディスク キャッシュの使用量を抑えることが試みられます。 ``` #### `--min-disk-free-pct=` ``` \[詳細設定] ファイル システムの空き領域の目標割合を設定します。 `--max-disk-cache` が指定されていない場合、ファイル システムの空き容量がこの割合を下回ると、エバリュエーターはディスク キャッシュの使用量を抑えようとします。 ``` #### `--external==` 外部述語 *\* の行を含む CSV ファイル。 複数の `--external` オプションを指定できます。 #### `--xterm-progress=` ``` \[詳細設定] xterm 制御シーケンスを使用して、QL 評価中に進行状況の追跡を表示するかどうかを制御します。 使用可能な値は次のとおりです。 `no`: 派手な進行状況を生成せず、バカ端末と見なします。 `auto` (デフォルト値): コマンドが適切なターミナルで実行されているかどうかを自動検出します。__ `yes`: ターミナルで xterm 制御シーケンスを認識できると見なします。 この機能は、ターミナルの "サイズ" を自動検出できることに依存しており (Windows では実装されていません)、__ が指定された場合は無効になります。`-q` `25x80` (またはこれに類する値): `yes` と同様。ターミナルのサイズも明示的に指定します。 (`yes` とは異なり、これは Windows でも機能します) `25x80:/dev/pts/17` (またはこれに類する値): stderr とは "異なる" ターミナルにファンシーな進行状況を表示します。__ 主に内部テストに役立ちます。 ``` ### エバリュエーターに関する構造化ログの出力を制御するためのオプション #### `--evaluator-log=` ``` \[詳細設定] 指定されたファイルにエバリュエーターのパフォーマンスに関する構造化ログを出力します。 このログ ファイルの形式は、予告なく変更される場合がありますが、2 つの改行文字 (デフォルト) または `--evaluator-log-minify` オプションが渡された場合は 1 つの改行文字で区切られた JSON オブジェクトのストリームになります。 このファイルのより安定した概要を生成するために `codeql generate log-summary ` を使用し、ファイルを直接解析しないようにしてください。 ファイルが既に存在している場合は上書きされます。 ``` #### `--evaluator-log-minify` ``` \[詳細設定] `--evaluator-log` オプションが渡された場合、このオプションも渡されると、生成される JSON ログのサイズは最小限に抑えられますが、人間が判読しにくいものになります。 ``` ### RAM の使用を制御するためのオプション #### `-M, --ram=` クエリ エバリュエーターは、合計メモリ使用量をこの値未満に維持しようと努めます。 ただし、大規模なデータベースでは、メモリ不足の場合にディスクにスワップできるファイル バックド メモリマップにより、しきい値が超えられる可能性があります。 値は少なくとも 2,048 MB (メガバイト) にする必要があります。より小さい値を指定した場合も、透過的に切り上げられます。 ### QL コンパイルを制御するためのオプション #### `--warnings=` QL コンパイラからの警告を処理する方法。 つぎのいずれかです。 ``` `hide`: 警告を表示しません。 `show` (デフォルト値): 警告を出力しますが、コンパイルを続行します。__ `error`: 警告をエラーとして扱います。 ``` #### `--no-debug-info` デバッグ目的で RA にソースの場所情報を出力しないでください。 #### `--[no-]fast-compilation` ``` \[非推奨] \[詳細設定] 特に速度の遅い最適化手順を省略します。 ``` #### `--no-release-compatibility` ``` \[詳細設定] 移植性を犠牲にして、最新のコンパイラ機能を使用します。 ``` 場合によっては、新しい QL 言語機能とエバリュエーターの最適化が、それらが QL コンパイラにおいてデフォルトで有効になる数リリース前に、QL エバリュエーターによってサポートされます。 これにより、最新の CodeQL リリースでクエリを開発するときに生じるパフォーマンスを、コード スキャンまたは CI 統合にまだ使用されている可能性がある少し古いリリースと一致させることができます。 クエリが他の (以前または以降の) CodeQL リリースと互換性があるかどうかを気にする必要がない場合は、このフラグを使用してコンパイラの最近の改善を早期に有効にすることで、パフォーマンスを多少向上させることができます。 リリースに有効にすべき最近の改善がない場合、このオプションは通知することなく何も実行しません。 このため、グローバル CodeQL 構成ファイルで一度にすべて設定しても安全です。 ``` `v2.11.1` 以降で使用できます。 ``` #### `--[no-]local-checking` 使用される QL ソースの部分に対してのみ最初のチェックを実行します。 #### `--no-metadata-verification` QLDoc コメントに埋め込まれたクエリ メタデータの有効性はチェックされません。 #### `--compilation-cache-size=` ``` \[詳細設定] コンパイル キャッシュ ディレクトリの、デフォルトの最大サイズをオーバーライドします。 ``` #### `--fail-on-ambiguous-relation-name` ``` \[詳細設定] コンパイル中にあいまいな関係名が生成された場合、コンパイルを失敗とします。 ``` ### コンパイル環境を設定するためのオプション #### `--search-path=[:...]` QL パックが見つかる可能性があるディレクトリの一覧。 各ディレクトリは、QL パック (またはルートに `.codeqlmanifest.json` ファイルを含むパックのバンドル)、または 1 つ以上のこのようなディレクトリの直接の親ディレクトリのいずれかです。 パスに複数のディレクトリを含める場合は、それらの順序で、それらの間の優先順位を定義します。解決する必要があるパック名が複数のディレクトリ ツリーで一致する場合は、最初に指定したものが優先されます。 オープンソースの CodeQL リポジトリのチェックアウトでこれを指定すると、そこにある言語の 1 つを照会するときに機能するはずです。 CodeQL リポジトリを、アンパックされた CodeQL ツールチェーンの兄弟としてチェックアウトしている場合、このオプションを指定する必要はありません。このような兄弟ディレクトリは、他の方法では見つからない QL パックについて常に検索されます (このデフォルトが機能しない場合は、ユーザーごとの構成ファイルで `--search-path` を一度だけ設定することを強くお勧めします)。 (注: Windows では、パスの区切り記号は `;` です)。 #### `--additional-packs=[:...]` このディレクトリの一覧が指定されている場合、パックは、`--search-path` 内のディレクトリの前に、これらのディレクトリで検索されます。 これらの間の順序は重要ではありません。このリストの 2 か所でパック名が見つかった場合は、エラーです。 これは、デフォルトのパスにも表示される新しいバージョンのパックを一時的に開発している場合に役立ちます。 一方、構成ファイルでこのオプションをオーバーライドすることは "お勧めしません"。内部アクションによっては、このオプションがオンザフライで追加され、構成済みの値がオーバーライドされます。\_\_ (注: Windows では、パスの区切り記号は `;` です)。 #### `--library-path=[:...]` ``` \[詳細設定] QL ライブラリの生インポート検索パスに追加するオプションのディレクトリ リスト。 これを使う必要があるのは、QL パックとしてパッケージ化されていない QL ライブラリを使用する場合のみです。 ``` (注: Windows では、パスの区切り記号は `;` です)。 #### `--dbscheme=` ``` \[詳細設定] どの dbscheme クエリに対してコンパイルする必要があるかを明示的に定義します。 これは、自分が何をしているかを確信している呼び出し元のみが指定する必要があります。 ``` #### `--compilation-cache=` ``` \[詳細設定] コンパイル キャッシュとして使用する追加のディレクトリを指定します。 ``` #### `--no-default-compilation-cache` ``` \[詳細設定] クエリを含む QL パックや CodeQL ツールチェーン ディレクトリなどの標準の場所でコンパイル キャッシュを使用しません。 ``` ### CodeQL パッケージ マネージャーを構成するためのオプション #### `--registries-auth-stdin` ``` \ = \ ペアのコンマ区切りのリストを渡して、GitHub Enterprise Server コンテナー レジストリに対して認証を行います。 ``` たとえば、`https://containers.GHEHOSTNAME1/v2/=TOKEN1,https://containers.GHEHOSTNAME2/v2/=TOKEN2` を渡して、 2 つの GitHub Enterprise Server インスタンスに対して認証を行うことができます。 これを使って、CODEQL\_REGISTRIES\_AUTH および GITHUB\_TOKEN 環境変数をオーバーライドします。 github.com コンテナー レジストリに対する認証のみが必要な場合は、代わりに、より単純な `--github-auth-stdin` オプションを使って認証できます。 #### `--github-auth-stdin` 標準入力を介して github.com GitHub Apps トークンまたは個人用アクセス トークンを渡して、github.com コンテナー レジストリに対して認証を行います。 GitHub Enterprise Server コンテナー レジストリに対して認証を行うには、`--registries-auth-stdin` を渡すか、CODEQL\_REGISTRIES\_AUTH 環境変数を使います。 これを使って、GITHUB\_TOKEN 環境変数をオーバーライドします。 ### 共通オプション #### `-h, --help` このヘルプ テキストを表示します。 #### `-J=` ``` \[詳細設定] コマンドを実行している JVM にオプションを指定します ``` (スペースを含むオプションは正しく処理されないことに注意してください)。 #### `-v, --verbose` 出力される進行状況メッセージの数を段階的に増やします。 #### `-q, --quiet` 出力される進行状況メッセージの数を段階的に減らします。 #### `--verbosity=` ``` \[詳細設定] 詳細レベルを、errors、warnings、progress、progress+、progress++、progress+++ のいずれかに明示的に設定します。 `-v` と `-q` がオーバーライドされます。 ``` #### `--logdir=` ``` \[詳細設定] タイムスタンプと実行中のサブコマンドの名前を含む生成された名前を使用して、指定されたディレクトリ内の 1 つまたは複数のファイルに詳細なログを書き込みます ``` (完全に制御できる名前でログ ファイルを書き込むには、代わりに `--log-to-stderr` を指定し、必要に応じて stderr をリダイレクトします)。 #### `--common-caches=` ``` \[[詳細設定] ダウンロードした QL パックやコンパイル済みクエリ プランなど、CLI の複数の実行間に保持される、ディスク上でキャッシュされたデータの場所を制御します。 明示的に設定されない場合、デフォルトではユーザーのホーム ディレクトリに名前が付けられた `.codeql` ディレクトリになります。まだ存在しない場合は作成されます。 `v2.15.2` 以降で使用できます。 ```