---
url: /v6.2/user-attributes.md
---
# 用户属性

用户属性是每个用户具备的特性，不同用户的属性值会有差别。 在用户属性页面可以看到用户包含的所用属性列表。

![](/images/sys-mgt/user-role-020.png)

首先介绍用户属性涉及的基本概念，包括用户属性类别、数据类型、作用范围、开放级别。

### 用户属性类别

用户属性包括系统属性和自定义属性两种。

* 系统属性

  系统属性前缀为 sys.，是系统提供的属性，这些属性不可添加、编辑、删除。

* 自定义属性

  自定义属性是用户自己添加的属性，可进行 CRUD 操作，即可添加、查看、编辑、删除。

### 用户属性类型

用户属性的数据类型有以下几种：

* 文本：用文本字符串替换用户属性运算。
* 数字：用数字字符串替换用户属性运算。
* 日期：用日期字符串替换用户属性运算。
* 任意类型：可以转换为任何类型，比如可以在用户属性值中输入\[1,2,3]作为数组使用。

### 用户属性作用范围

在多租户场景下，有时候平台方需要统一管理租户的属性，此时就通过可以设置用户属性的作用范围来实现。作用范围有以下以下选项：

* 内部：作用范围为内部的用户属性，只能在租户内部使用，或者平台方内部自己使用，不能跨租户使用，租户之间也是隔离的。
* 全局：作用范围为全局的用户属性，可以在平台方内部使用，然后最重要的是，平台方可以按照不同的租户设置其值，然后租户内部可以读取到。

平台方的管理员，创建了作用范围为全局的属性之后，就可以在租户的编辑页面给单个租户设置属性值。这样操作之后这个租户下面的所有用户都具有这一属性值。

### 用户属性开放级别

在多租户或者多组织的场景下，数据可能是存放在不同数据库的实例、不同的数据库、不同的 schema、不同的表中。这时候一般可以使用用户属性来动态连接到这些不同的数据库中。

但是像密码等一些信息我们是不希望普通用户通过查看属性值看到的。这个时候就可以用到属性的开放级别来进行控制。

* 只读：开放级别为只读的用户属性，其属性值是开放给每个用户的，每个用户可以看到自身的属性值，也可以将其用在大部分分析场景中。
* 隐藏：开放级别为隐藏的用户属性，其属性值是不开放给普通用户的，普通用户是不能看到其具体的值。一般这一类隐藏的属性只能使用在数据连接中。在数据集/图表/仪表盘中不能使用。

### 用户属性相关操作

#### 添加用户属性

点击添加属性，在弹窗中输入属性名称、类型、作用范围、开放级别，手动输入属性的默认值，支持设置空值和 NULL 值。用户属性支持进行多值设置。

![](/images/sys-mgt/user-role-021.png)

> \[!TIP] 提示
>
> 1. 在租户管理中，平台方管理员、租户管理员都可以定义用户属性，用户属性本身的定义没有隔离，定义之后管理员都能看到它。
> 2. 多值功能一旦设置，不支持再次修改。 如添加用户属性时开启多值，则不支持关闭。 如果没有开启，后续也不支持开启。

#### 查看用户属性

可以查看自定义属性的详细信息，也支持查看每个用户中[自定义属性设置的值](#查看和编辑用户)。

#### 编辑用户属性

用户属性支持编辑修改，点击每个属性右侧的编辑页面，编辑自定义属性。自定义属性仅支持修改作用范围、开放级别、默认值。

![](/images/sys-mgt/user-role-022.png)

每个用户自己属性的具体值也支持修改。查看用户找到具体属性值时，点击修改即可。

#### 删除用户属性

点击用户自定义属性右侧的删除按钮，可删除用户自定义属性，用户中的用户属性也同时消除。

### 用户属性使用场景

用户可以在以下场景中使用用户属性：

* 创建数据连接
* 创建直连数据集选择表
* 创建 SQL 查询数据
* 创建数据集的过滤条件中
* 新增字段、新增指标的表达式中
* 图表、仪表盘的过滤器中
* 参考线的设置中
* 权限控制中

用户属性使用场景很多，下面展示一些典型使用场景。

#### 用户属性用法

|用途 |HE |表达式 |
|-----|-----|-------|
|用户属性| {“kind”: “attr”, “op”:”用户属性名”} |{{$用户属性名}}|
|用户属性值|  |{{$$用户属性名}}|

> \[!TIP] 提示
> 用户属性是单 dollar 符号，用户属性值是双 dollar 符号。
> 使用{{$用户属性名}}时，后端会转换成 HE 表达式，使用时不加引号。
> 使用{{$$用户属性名}}时，后端会直接查询用户属性的值，然后进行文本替换，可以根据需要加引号。
> 在衡石的高级表达式中，比如新增字段/指标表达式、图表过滤器表达式、新建数据集过滤表达式，必须使用{{$用户属性名}}。
> 创建数据连接、SQL 查询数据集时，必须使用用户属性值：{{$$用户属性名}}。

#### 创建数据连接时使用用户属性

用户属性可以用在创建数据连接处，参数不可以，因为参数是属于应用的，用户属性是属于系统的。

在创建连接时必须使用`用户属性值`{{$$用户属性名}}的形式。

在创建连接时，只有用户密码不可以使用用户属性，其他地方都可以使用用户属性。用户密码是输入什么就是什么，不会进行转换和计算。

图中的 dbhost 和 dbname 都是用户属性。

![](/images/sys-mgt/user-role-023.png)

#### 新建数据集的过滤条件中使用用户属性

简单过滤使用用户属性：

![](/images/sys-mgt/user-role-024.png)

表达式过滤使用用户属性，必须使用{{$用户属性名}}的形式：

![](/images/sys-mgt/user-role-025.png)

#### 创建 SQL 查询数据集时使用用户属性

创建 SQL 查询时必须使用`用户属性值`{{$$用户属性名}}的形式：

```sql
select * from movie where id > {{$$用户属性名}}

select * from {{$$用户属性名}}
```

#### 新建字段/指标时使用用户属性

新建字段或者指标时必须使用`用户属性`{{$用户属性名}}的形式：

```sql
{price} + {{$用户属性名}}
```

#### 在过滤器表达式中使用用户属性

在图表过滤器表达式中必须使用`用户属性`{{$用户属性名}}的形式：

```sql
{region} = {{$用户属性名}}
```