类别：

上下文函数 （通用）

SYS_CONTEXT（SNOWFLAKE$SESSION 命名空间）

返回有关调用函数的会话的信息。

您可以在以下上下文中调用此函数：

  • 您可以直接在当前会话中调用此函数。

  • 您可以运行调用此函数的调用方权限可执行文件（例如，调用方权限存储过程）。

  • 只要所有者角色已被授予账户上的 READ SESSION 权限，您就可以运行调用此函数的所有者权限可执行文件（例如所有者权限存储过程）。

在任何其他上下文中，该函数返回 NULL。

另请参阅：

SYS_CONTEXT、SYS_CONTEXT（SNOWFLAKE$APPLICATION 命名空间）、SYS_CONTEXT（SNOWFLAKE$ENVIRONMENT 命名空间）、SYS_CONTEXT（SNOWFLAKE$ORGANIZATION 命名空间）

语法

用来检索属性的语法：

SYS_CONTEXT(
  'SNOWFLAKE$SESSION' ,
  '<property>'
)
Copy

用来调用函数的语法：

SYS_CONTEXT(
  'SNOWFLAKE$SESSION' ,
  '<function>' , '<argument>' [ , ... ]
)
Copy

实参

'SNOWFLAKE$SESSION'

指定要检索属性或调用函数以返回有关调用该函数的会话的信息。

'property'

要检索的属性的名称。您可以指定以下属性：

属性

描述

PRINCIPAL_NAME

启动了会话的主体的名称（用户、任务 或 SPCS 服务）。名称取决于 PRINCIPAL_TYPE 属性的值：

  • 如果 PRINCIPAL_TYPE 是以下值之一，PRINCIPAL_NAME 属性的值是用户的名称：

    • USER

    • USER_PERSON

    • USER_SERVICE

    • USER_LEGACY_SERVICE

  • 如果 PRINCIPAL_TYPE 是 TASK，值是任务的名称。

  • 如果 PRINCIPAL_TYPE 是 SNOWSERVICE，值是 SPCS 服务的名称。

PRINCIPAL_TYPE

启动会话的主体的类型。此属性可以具有以下值之一：

  • 如果用户启动了会话，则为 USER 或 USER_suffix。suffix 取决于用户的类型：

    • 如果用户对象没有 TYPE 属性，值为 USER。

    • 如果 TYPE 属性是 PERSON，值为 USER_PERSON。

    • 如果 TYPE 属性是 SERVICE，值为 USER_SERVICE。

    • 如果 TYPE 属性是 LEGACY_SERVICE，值为 USER_LEGACY_SERVICE。

  • 如果 任务 开始会话，则为 TASK。

  • 如果 SPCS 服务 开始会话，则为 SNOWSERVICE。

PRINCIPAL_EMAIL

与主体关联的电子邮件地址。如果没有关联的电子邮件地址，则此属性的值为 NULL。

PRINCIPAL_DATABASE

包含主体对象的数据库的名称。例如，如果主体是一项任务，则此属性的值是包含该任务的数据库的名称。

如果主体是账户级对象（例如用户），则此属性的值为 NULL。

PRINCIPAL_SCHEMA

包含主体对象的架构的名称。例如，如果主体是一项任务，则此属性的值是包含该任务的架构的名称。

如果主体是账户级对象（例如用户），则此属性的值为 NULL。

ID

调用函数的会话的标识符。

ROLE

调用函数的会话的主要角色。

ROLE_TYPE

主要角色的类型。此属性可以具有以下值之一：

  • 如果主要角色是账户角色，则为 ROLE。

ROLE_DATABASE

如果角色是数据库角色，则为包含该数据库角色的数据库名称。

SECONDARY_ROLES

会话中作为次要角色激活的账户级角色的 JSON 数组。激活的角色包括层级结构上位于所请求角色之下的角色。例如，假设用户执行了以下操作：

USE SECONDARY ROLES ACCOUNTADMIN;
Copy

此属性的 JSON 数组包含 ACCOUNTADMIN 角色，以及位于 ACCOUNTADMIN 角色之下的 SECURITYADMIN、SYSADMIN 和 USERADMIN 角色。

WANTED_SECONDARY_ROLES

用户请求的账户级角色的 JSON 数组。例如，假设用户执行了以下操作：

USE SECONDARY ROLES ACCOUNTADMIN;
Copy

的此属性的 JSON 数组仅包含 ACCOUNTADMIN 角色。

DATABASE

会话使用的当前数据库（如果调用该函数的角色具有访问数据库的权限）。

SCHEMA

会话使用的当前架构（如果调用函数的角色具有访问架构的权限）。

SCHEMAS

会话架构的当前 :ref:`搜索路径 <label-object_name_resolution_search_path>`（如果调用该函数的角色具有访问当前数据库的权限）。

WAREHOUSE

会话当前使用的仓库。
'function'

要调用的函数的名称。您可以调用以下函数：

'argument' [ , ... ]

要传递给要调用的函数的实参。

返回

该函数会返回 VARCHAR 值或 NULL：

使用说明

  • 如果您在 Shell 的双引号字符串中指定函数调用，请使用反斜杠 (\) 转义 $ 字符，以免 $SESSION 被解释为 Shell 变量。

    例如，如果您使用的是 Snowflake CLI，并且您 指定 SQL 语句作为命令行实参 放在双引号里：

    snow sql --query "SELECT SYS_CONTEXT('SNOWFLAKE\$SESSION', 'PRINCIPAL_NAME');"
    Copy

示例

以下示例演示如何检索有关会话的上下文信息：

检索有关主体的信息

以下示例返回调用该函数的主体的名称和类型：

SELECT SYS_CONTEXT('SNOWFLAKE$SESSION', 'PRINCIPAL_NAME') AS name,
  SYS_CONTEXT('SNOWFLAKE$SESSION', 'PRINCIPAL_TYPE') AS type,
  SYS_CONTEXT('SNOWFLAKE$SESSION', 'PRINCIPAL_EMAIL') AS email;
Copy
+--------------+-------------+---------------------+
| NAME         | TYPE        | EMAIL               |
|--------------+-------------+---------------------|
| MY_USER_NAME | USER_PERSON | my.user@example.com |
+--------------+-------------+---------------------+

检索有关角色的信息

以下示例返回调用函数的会话中主要角色的名称和类型：

SELECT SYS_CONTEXT('SNOWFLAKE$SESSION', 'ROLE') AS role,
  SYS_CONTEXT('SNOWFLAKE$SESSION', 'ROLE_TYPE') AS type;
Copy
+---------+------+
| ROLE    | TYPE |
|---------+------|
| MY_ROLE | ROLE |
+---------+------+

以下示例使用 ACCOUNTADMIN 角色作为次要角色。该示例随后返回会话中请求的次要角色列表 (ACCOUNTADMIN) 以及作为会话次要角色激活的账户级角色列表。

已激活角色列表包含层级结构上位于所请求角色之下的角色。因为激活 ACCOUTADMIN 角色后，列表包括 SECURITYADMIN、SYSADMIN 和 USERADMIN，它们位于 ACCOUNTADMIN 角色下。

USE SECONDARY ROLES ACCOUNTADMIN;

SELECT SYS_CONTEXT('SNOWFLAKE$SESSION', 'WANTED_SECONDARY_ROLES') AS requested_roles,
  SYS_CONTEXT('SNOWFLAKE$SESSION', 'SECONDARY_ROLES') AS requested_roles_with_child_roles;
Copy
+------------------+---------------------------------------------------------+
| REQUESTED_ROLES  | REQUESTED_ROLES_WITH_CHILD_ROLES                        |
|------------------+---------------------------------------------------------|
| ["ACCOUNTADMIN"] | ["ACCOUNTADMIN","SECURITYADMIN","SYSADMIN","USERADMIN"] |
+------------------+---------------------------------------------------------+

检索当前数据库、架构、搜索路径和仓库

以下示例返回会话使用的当前数据库、架构和仓库：

SELECT SYS_CONTEXT('SNOWFLAKE$SESSION', 'DATABASE') AS database,
  SYS_CONTEXT('SNOWFLAKE$SESSION', 'SCHEMA') AS schema,
  SYS_CONTEXT('SNOWFLAKE$SESSION', 'WAREHOUSE') AS warehouse;
Copy
+----------+--------+--------------+
| DATABASE | SCHEMA | WAREHOUSE    |
|----------+--------+--------------|
| MY_DB    | PUBLIC | MY_WAREHOUSE |
+----------+--------+--------------+

以下示例返回包含会话搜索路径的 JSON 数组：

SELECT SYS_CONTEXT('SNOWFLAKE$SESSION', 'SCHEMAS');
Copy
+---------------------------------------------+
| SYS_CONTEXT('SNOWFLAKE$SESSION', 'SCHEMAS') |
|---------------------------------------------|
| ["MY_DB.MY_SCHEMA","MY_DB.PUBLIC"]          |
+---------------------------------------------+

以下示例为搜索路径中的每个元素返回一行：

SELECT value::VARCHAR AS path_element
  FROM TABLE(
    FLATTEN(INPUT => PARSE_JSON(SYS_CONTEXT('SNOWFLAKE$SESSION', 'SCHEMAS'))));
Copy
+-----------------------+
| PATH_ELEMENT          |
|-----------------------|
| BOOKS_DB.BOOKS_SCHEMA |
| BOOKS_DB.PUBLIC       |
+-----------------------+
语言: 中文