SHOW AGENTS

列出您具有访问权限的 Cortex Agent。

另请参阅：

CREATE AGENT、DROP AGENT、DESCRIBE AGENT

语法

SHOW AGENTS
  [ LIKE '<pattern>' ]
  [ IN { ACCOUNT | DATABASE <db_name> | SCHEMA [<db_name>.]<schema_name> } ]
  [ STARTS WITH '<string>' ]
  [ LIMIT <rows> [ FROM '<string_from>' ] ]
Copy

参数

LIKE 'pattern'

（可选）按对象名称筛选命令输出。筛选器使用 不区分大小写 的模式匹配，并支持 SQL 通配符（% 和 _）。

例如，以下模式返回 相同的 结果：

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

. 默认：无值（不对输出应用筛选）。

[ IN ... ]

（可选）指定命令的作用域。指定以下任一项：

ACCOUNT

返回整个账户的记录。

DATABASE、. DATABASE db_name

返回当前正在使用的数据库或指定数据库 (db_name) 的记录。

如果指定 DATABASE 而不指定 db_name，并且没有使用任何数据库，则关键字对输出没有影响。

备注

在数据库上下文中使用不带 IN 子句的 SHOW 命令，这样可能会导致结果低于预期。

如果不使用 IN 子句，则具有相同名称的多个对象只会显示一次。例如，如果您在 schema1 中具有表 t1 且在 schema2 中具有表 t1，并且两者都在您指定的数据库上下文的作用域内（即，您所选的数据库是 schema1 和 schema2 的父级），则 SHOW TABLES 只会显示其中一个 t1 表。

SCHEMA、. SCHEMA schema_name

返回当前正在使用的架构或指定架构 (schema_name) 的记录。

如果数据库正在使用中，或者指定了完全限定 schema_name （例如 db.schema），则 SCHEMA 是可选选项。

如果未使用任何数据库，则指定 SCHEMA 对输出没有影响。

如果您省略 IN ...，则命令的作用范围取决于会话当前是否正在使用数据库：

  • If a database is currently in use, the command returns the objects you have privileges to view in the database. This has the same effect as specifying IN DATABASE.

  • If no database is currently in use, the command returns the objects you have privileges to view in your account. This has the same effect as specifying IN ACCOUNT.

STARTS WITH 'name_string'

（可选）根据对象名称开头显示的字符筛选命令输出。该字符串必须放在单引号内并且 区分大小写。

例如，以下字符串会返回 不同的 结果：

... STARTS WITH 'B' ...
... STARTS WITH 'b' ...

. 默认：无值（不对输出应用筛选）

LIMIT rows

（可选）限制返回的最大行数。返回的实际行数可能小于指定的限制。例如，现有对象的数量小于指定的限制。

默认：无值（不对输出应用限制）。

输出

命令输出在以下列中提供 Cortex Agent 属性和元数据：

列

描述

created_on

创建代理时的时间戳。

name

代理的名称。

database_name

包含代理的数据库。

schema_name

包含代理的架构。

owner

代理的所有者角色。

comment

代理的注释文本。

profile

代理配置文件 JSON（显示名称、头像、颜色）。

访问控制要求

用于执行此 SQL 命令的 角色 必须至少具有以下 一项 权限：

权限

对象

备注

以下任何一项权限：OWNERSHIP、USAGE、MONITOR 或者 OPERATE

代理

要对架构中的任何对象执行操作，需要对父数据库和架构的 USAGE 权限。请注意，如果某个角色获授某个架构的任意权限，该角色便能够解析该架构。例如，若某角色被授予 CREATE 权限，则可以在该架构上创建对象，而无需 同时 被授予该架构的 USAGE 权限。

有关创建具有指定权限集的自定义角色的说明，请参阅 创建自定义角色。

有关对 安全对象 执行 SQL 操作的相应角色和权限授予的一般信息，请参阅 访问控制概述。

使用说明

  • 该命令不需要正在运行的仓库即可执行。

  • 该命令仅返回当前用户的当前角色已获授至少一项访问权限的对象。

  • MANAGE GRANTS 访问权限隐式允许其持有者查看账户中的每个对象。默认情况下，只有账户管理员（具有 ACCOUNTADMIN 角色的用户）和安全管理员（具有 SECURITYADMIN 角色的用户）才具有 MANAGE GRANTS 权限。

  • 要对该命令的输出进行后处理，可以使用 管道运算符 (->>) 或 RESULT_SCAN 函数。这两种构造都将输出视为可以查询的结果集。

    For example, you can use the pipe operator or RESULT_SCAN function to select specific columns from the SHOW command output or filter the rows.

    When you refer to the output columns, use double-quoted identifiers for the column names. For example, to select the output column type, specify SELECT "type".

    You must use double-quoted identifiers because the output column names for SHOW commands are in lowercase. The double quotes ensure that the column names in the SELECT list or WHERE clause match the column names in the SHOW command output that was scanned.

  • 该命令 最多 返回指定对象类型的 1 万条记录，由用于执行命令的角色的访问权限决定。即使应用了筛选器，也不会返回任何超出 1 万条限制后的记录。

    要查看存在超过 1 万条记录的结果，请在 Snowflake Information Schema 中查询相应的视图（如果存在）。

示例

列出当前架构中的所有代理：

SHOW AGENTS;
Copy

示例输出：

+--------------+---------+---------------+-------------+-----------+-----------------------+-------------------------------------+
| created_on         | name  | database_name | schema_name | owner     | comment          | profile                            |
|--------------+---------+---------------+-------------+-----------+-----------------------+-------------------------------------|
| 2025-09-15 17:04:37.263 +0000 | TEST_AGENT | EXAMPLE_DB   | AGENTS | TEST_ROLE | null | {"display_name":"test"} |
+--------------+---------+---------------+-------------+-----------+-----------------------+-------------------------------------+

以下示例列出了特定架构中的代理：

SHOW AGENTS IN SCHEMA mydb.myschema;
Copy

以下示例列出了特定数据库中的代理：

SHOW AGENTS IN DATABASE mydb;
Copy

以下示例列出了账户中的所有代理：

SHOW AGENTS IN ACCOUNT;
Copy

以下示例列出了名称以 my_agent 开头的代理：

SHOW AGENTS LIKE 'my_agent%';
Copy

以下示例列出了前 10 个代理。第二条语句列出从名为 AGENT_NAME 的代理开始的前 10 个代理。

SHOW AGENTS LIMIT 10;
SHOW AGENTS LIMIT 10 FROM 'AGENT_NAME';
Copy

以下示例以 JSON 格式列出代理资源：

SHOW AS RESOURCE AGENTS;
Copy
语言: 中文