SHOW EXTERNAL AGENTS

ユーザーにアクセス権限が付与されている外部エージェントをリストします。外部エージェントは、AI 可観測性 で使用するためのSnowflakeにおける生成型 AI アプリケーションを表します。

出力は、データベース、スキーマ、および外部エージェント名の辞書順に並べられたオブジェクトのメタデータとプロパティを返します（出力列の説明については、このトピックの 出力 を参照）。

こちらもご参照ください。

CREATE EXTERNAL AGENT, ALTER EXTERNAL AGENT, DROP EXTERNAL AGENT, DESCRIBE EXTERNAL AGENT

構文

SHOW EXTERNAL AGENTS [ LIKE '<pattern>' ]
                     [ IN { ACCOUNT | DATABASE [ <db_name> ] | SCHEMA [ <schema_name> ] } ]

パラメーター

LIKE 'pattern'

オプションで、オブジェクト名でコマンド出力をフィルタリングします。フィルターは、 SQL ワイルドカード文字（% および _）をサポートする、 大文字と小文字を区別しない パターンマッチングを使用します。

たとえば、次のパターンは 同じ 結果を返します。

... LIKE '%testing%' ...
... LIKE '%TESTING%' ...

. デフォルト: 値なし（フィルタリングは出力に非適用）。

IN ACCOUNT | DATABASE [ db_name ] | SCHEMA [ schema_name ]

必要に応じて、コマンドのスコープを指定します。これは、コマンドが外部エージェントを現在/指定のデータベースまたはスキーマのみにリストするか、アカウント全体に表示するかを決定します。

キーワード ACCOUNT を指定すると、コマンドは、現在のアカウントのデータベースすべてにあるすべてのスキーマの記録を取得します。

キーワード DATABASE を指定すると、次のようになります。

  • db_name を指定すると、コマンドは、指定されたデータベースのスキーマすべての記録を取得します。

  • :samp:`{db_name}`を指定しない場合、以下のようになります：

    • 現在のデータベースがある場合、コマンドは、現在のデータベースにあるスキーマすべての記録を取得します。

    • 現在のデータベースがない場合、コマンドは、アカウントにあるすべてのデータベースとスキーマの記録を取得します。

キーワード SCHEMA を指定すると、次のようになります。

  • 修飾されたスキーマ名（例: my_database.my_schema）を指定すると、コマンドは、指定されたデータベースとスキーマの記録を取得します。

  • 修飾されていない schema_name を指定すると、次のようになります。

    • 現在のデータベースがある場合、コマンドは、現在のデータベースにある指定されたスキーマの記録を取得します。

    • 現在のデータベースがない場合、コマンドは、エラー SQL compilation error: Object does not exist, or operation cannot be performed を表示します。

  • :samp:`{schema_name}`を指定しない場合、以下のようになります：

    • 現在のデータベースがある場合は、次のようになります。

      • 現在のスキーマがある場合、コマンドは、現在のデータベースにある現在のスキーマの記録を取得します。

      • 現在のスキーマがない場合、コマンドは、現在のデータベースにあるスキーマすべての記録を取得します。

    • 現在のデータベースがない場合、コマンドは、アカウントにあるすべてのデータベースとすべてのスキーマの記録を取得します。

デフォルト: セッションで現在使用中のデータベースがあるかどうかによって異なります。

  • データベース: DATABASE がデフォルトです（つまり、コマンドは、現在のデータベースでユーザーに表示するための権限が付与されているオブジェクトを返します）。

  • データベースなし:アカウントスコープはデフォルトです（つまり、コマンドは、ユーザーにアカウントで表示するための権限が付与されている外部エージェントを返します）。

出力

コマンド出力では、次の列に外部エージェントのプロパティとメタデータが表示されます。

列

説明

created_on

外部エージェントが作成された時点のタイムスタンプ。

name

外部エージェントの名前。

database_name

外部エージェントを含むデータベース。

schema_name

外部エージェントを含むスキーマ。

owner

外部エージェントを所有するロール。

comment

外部エージェントに関するコメント。

versions

外部エージェントのバージョンをリストした JSON 配列。

default_version_name

外部エージェントのデフォルトバージョン。

アクセス制御の要件

この SQL コマンドの実行に使用される ロール には、 最低 1 つ の次の 権限 が必要です。

権限

オブジェクト

メモ

次の権限のいずれか: OWNERSHIP、USAGE

外部エージェント

スキーマ内のオブジェクトを操作するには、親データベースの少なくとも1つの権限と、親スキーマの少なくとも1つの権限が必要です。

指定された権限のセットを使用してカスタムロールを作成する手順については、 カスタムロールの作成 をご参照ください。

セキュリティ保護可能なオブジェクト に対して SQL アクションを実行するためのロールと権限付与に関する一般的な情報については、 アクセス制御の概要 をご参照ください。

使用上の注意

  • このコマンドの実行には、稼働中のウェアハウスは必要ありません。

  • このコマンドは、現在のユーザーの現在のロールに少なくとも1つのアクセス権限が付与されているオブジェクトのみを返します。

  • MANAGE GRANTS アクセス権限により、所有者はアカウント内のすべてのオブジェクトを暗黙的に参照できます。デフォルトでは、アカウント管理者（ ACCOUNTADMIN ロールを持つユーザー）とセキュリティ管理者（ SECURITYADMIN ロールを持つユーザー）のみが MANAGE GRANTS 権限を持っています。

  • このコマンドの出力を後処理するには、 パイプ演算子 （->>）または RESULT_SCAN 関数。どちらのコンストラクトも、出力を クエリできる結果セットとして扱います。

    たとえば、パイプ演算子または RESULT_SCAN 関数を使用して、 SHOW コマンド出力から特定の列を選択したり、行をフィルター処理したりできます。

    出力列を参照する場合は、列名に:ref:二重引用符<label-delimited_identifier>`で囲まれた識別子を使用します。たとえば、出力列 ``type` を選択するには、 SELECT "type" を指定します。

    SHOW コマンドの出力列名は小文字のため、二重引用符で囲まれた識別子を使用する必要があります。二重引用符により、 SELECT リストまたは WHERE 句内の列名が、スキャンされた SHOW コマンド出力内の列名と一致することが保証されます。

例

現在のスキーマのすべての外部エージェントをリストします。

SHOW EXTERNAL AGENTS;

特定のスキーマの外部エージェントをリストします。

SHOW EXTERNAL AGENTS IN SCHEMA mydb.myschema;

特定のデータベースの外部エージェントをリストします。

SHOW EXTERNAL AGENTS IN DATABASE mydb;

アカウント内のすべての外部エージェントをリストします。

SHOW EXTERNAL AGENTS IN ACCOUNT;

パターンに一致する名前を持つ外部エージェントをリストします。

SHOW EXTERNAL AGENTS LIKE 'my_rag%';