类别：

上下文函数 （会话）

SET_SYS_CONTEXT

为指定命名空间中的指定键设置值，稍后可以使用 SYS_CONTEXT 检索该值。

此函数有两种操作模式：

  • **不可变会话属性**（SNOWFLAKE$SESSION_ATTRIBUTES 命名空间）：设置自定义会话属性，这些属性一经设置便不可变，并在会话持续期间一直存在。对于跟踪有关会话的元数据非常有用，例如应用程序上下文、用户属性或审计信息。

  • **会话变量**（其他命名空间）：行为类似于 SET 命令，用于设置可以更新的会话变量。返回变量的上一个值。

另请参阅：

SYS_CONTEXT、SYS_CONTEXT（SNOWFLAKE$SESSION_ATTRIBUTES 命名空间）、SET

语法

CALL SET_SYS_CONTEXT( '<namespace>', '<key>', '<value>' )

实参

'namespace'

用于存储键值对的命名空间。支持的命名空间：

  • SNOWFLAKE$SESSION_ATTRIBUTES – 存储不可变的自定义会话属性。属性名称 区分大小写。

  • 任何其他字符串（或 NULL）– 将命名空间视为会话变量名称的前缀，类似于 SET 命令。命名空间 区分大小写。

'key'

要设置的属性或变量的名称。所有键名均 区分大小写。

'value'

要分配的值。该值必须是字符串或计算结果为字符串的表达式。

返回

该函数会返回 VARCHAR 值：

  • 对于 SNOWFLAKE$SESSION_ATTRIBUTES 命名空间：始终返回 NULL（因为不可变属性不能有先前的值）。如果已在当前会话中设置该属性，则该函数将引发错误。

  • 对于其他命名空间：返回会话变量的先前值，如果变量先前不存在，则返回 NULL。这与 SET 命令的行为一致。

访问控制要求

设置自定义会话属性不需要特殊权限。任何用户都可以在自己的会话中设置属性。

使用说明

对于 SNOWFLAKE$SESSION_ATTRIBUTES 命名空间（不可变属性）：

  • 属性 不可变。设置属性后，任何再次设置该属性的尝试（即使设置为相同的值）都将导致错误。

  • 属性名称 区分大小写。app_context、App_Context 和 APP_CONTEXT 被视为三个不同的属性。

  • 属性是 会话范围。它们在会话期间持续存在，并且对其他会话不可见。

  • 要检索属性值，请使用 SYS_CONTEXT（SNOWFLAKE$SESSION_ATTRIBUTES 命名空间）：SYS_CONTEXT('SNOWFLAKE$SESSION_ATTRIBUTES', '<key>')。

对于其他命名空间（会话变量）：

  • 变量名称 区分大小写。user_id 和 USER_ID 被视为不同的变量。

  • 变量可以 更新。设置已存在的变量将返回以前的值，并使用新值对其进行更新。

  • 命名空间（如果提供）用作前缀：SET_SYS_CONTEXT('myns', 'mykey', 'val') 创建一个名为 myns.mykey 的变量。

  • 可以使用 SYS_CONTEXT('<namespace>', '<key>') 检索变量，设置变量时必须使用完全一样的大小写。

一般注意事项：

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

示例

示例 1：不可变的会话属性（SNOWFLAKE$SESSION_ATTRIBUTES 命名空间）

设置自定义属性以跟踪应用程序上下文：

CALL SET_SYS_CONTEXT('SNOWFLAKE$SESSION_ATTRIBUTES', 'app_context', 'production');

检索属性值（注意：属性名称区分大小写）：

SELECT SYS_CONTEXT('SNOWFLAKE$SESSION_ATTRIBUTES', 'app_context');

+---------------------------------------------------------------+
| SYS_CONTEXT('SNOWFLAKE$SESSION_ATTRIBUTES', 'app_context')   |
|---------------------------------------------------------------|
| production                                                    |
+---------------------------------------------------------------+

设置属性后，尝试更改它会导致错误：

-- This will fail because the attribute is immutable
CALL SET_SYS_CONTEXT('SNOWFLAKE$SESSION_ATTRIBUTES', 'app_context', 'development');

SQL compilation error: Cannot overwrite context value: app_context

属性名称区分大小写：

-- This succeeds because it's a different attribute name (different case)
CALL SET_SYS_CONTEXT('SNOWFLAKE$SESSION_ATTRIBUTES', 'APP_CONTEXT', 'staging');

SELECT SYS_CONTEXT('SNOWFLAKE$SESSION_ATTRIBUTES', 'app_context') AS lower_case,
       SYS_CONTEXT('SNOWFLAKE$SESSION_ATTRIBUTES', 'APP_CONTEXT') AS upper_case;

+------------+------------+
| LOWER_CASE | UPPER_CASE |
|------------+------------|
| production | staging    |
+------------+------------+

示例 2：会话变量（其他命名空间）

设置带有命名空间前缀的会话变量：

CALL SET_SYS_CONTEXT('myapp', 'user_id', '12345');

+---------------------------------------------------+
| SET_SYS_CONTEXT('myapp', 'user_id', '12345')     |
|---------------------------------------------------|
| NULL                                              |
+---------------------------------------------------+

变量会以提供的完全大小写形式进行存储：myapp.user_id。进行检索：

SELECT SYS_CONTEXT('myapp', 'user_id');

+----------------------------------+
| SYS_CONTEXT('myapp', 'user_id')  |
|----------------------------------|
| 12345                            |
+----------------------------------+

更新变量（返回上一个值）：

CALL SET_SYS_CONTEXT('myapp', 'user_id', '67890');

+---------------------------------------------------+
| SET_SYS_CONTEXT('myapp', 'user_id', '67890')     |
|---------------------------------------------------|
| 12345                                             |
+---------------------------------------------------+