# Record数据表

## 概述

数据表相关函数

## getById

返回查询的数据表记录信息

```javascript
Record.getById(tableId, recordId)
```

| 参数       | 类型     | 描述      |
|----------|--------|---------|
| tableId  | `String` | 数据表的标识符 |
| recordId | `String` | 记录ID    |

**返回值**

类型 `Object`
数据表记录信息，如果不存在则返回`null`

**示例**

```javascript
Record.getById('order', 'z2koxrkxtp854')//{amount=11, name=测试采购单, id=z2koxrkxtp854} 
```



## getFieldValue

返回数据表记录的字段值

```javascript
Record.getFieldValue(tableId, recordId, fieldId)
```

| 参数       | 类型     | 描述      |
|----------|--------|---------|
| tableId  | `String` | 数据表的标识符 |
| recordId | `String` | 记录ID    |
| fieldId  | `String` | 字段标识符   |


**返回值** 

类型 `Object`
数据表记录的字段值，如果记录不存在则返回`null`，如果属性不存在则返回`null`。
如果数据表不存在则抛出异常

**示例**

```javascript
//{amount=11, name=测试采购单, id=z2koxrkxtp854} 
Record.getFieldValue('order','z2koxrkxtp854','amount')//11
```



## getByField

根据单个字段过滤数据表记录列表

```javascript
Record.getByField(tableId, fieldId, opt, value)
```

| 参数      | 类型     | 描述                                           |
|---------|--------|----------------------------------------------|
| tableId | `String` | 数据表的标识符                                      |
| fieldId | `String` | 过滤的字段                                        |
| opt     | `String` | 操作符，关于操作符参见`ConditionOpt` |
| value   | `Object` | 过滤条件的值                                       |

**返回值**

类型 `Array<Record>`
返回满足条件的记录列表，最多返回10000条记录，如果没有满足条件的数据，返回空数组。
如果数据表不存在则抛出异常
 
**示例**

```javascript
//{amount=11, name=测试采购单, id=z2koxrkxtp854} 
Record.getByField('order', 'amount', 'eq', 11)//[{amount=11, name=测试采购单, id=z2koxrkxtp854}]
```



## getByFields

根据多个字段过滤数据表记录列表

```javascript
Record.getByFields(tableId, conditions)
```

| 参数         | 类型     | 描述                                           |
|------------|--------|----------------------------------------------|
| tableId    | `String` | 数据表的标识符                                      |
| conditions | `Array`  | 过滤条件，关于过滤条件参见[Condition](../script/model.html#condition) |

**返回值**

类型 `Array<Record>`
返回满足条件的记录列表，最多返回10000条记录，如果没有满足条件的数据，返回空数组。
如果数据表不存在则抛出异常

**示例**

```javascript
//{amount=11, text=13, id=z2koxrkxtp854} 
Record.getByFields('tab', [{ "fieldId": 'text', "opt": "eq", "value": '13' }])//[{amount=11, text=13, id=z2koxrkxtp854}]
```



## getRecordOptionName

返回单个选项值的名称

```javascript
Record.getRecordOptionName(tableId, fieldId, value)
```

| 参数      | 类型     | 描述      |
|---------|--------|---------|
| tableId | `String` | 数据表的标识符 |
| fieldId | `String` | 字段的标识符  |
| value   | `String` | 选项值     |

**返回值** 

类型 `String`
返回选项值的名称，如果选项值在选项列表中不存在，则返回传入的选项值
如果数据表不存在则抛出异常

**示例**

```javascript
//选项值列表：a:'选项1',b:'选项2'
//{amount=11, name=测试采购单, id=z2koxrkxtp854,type=a} 
Record.getRecordOptionName('order', 'type', 'a')//选项1
Record.getRecordOptionName('order', 'type', 'c')//c
```



## getRecordOptionNames

返回多个选项值的名称并且拼接到一起

```javascript
Record.getRecordOptionNames(tableId, fieldId, valueList, join)
```

| 参数        | 类型              | 描述      |
|-----------|-----------------|---------|
| tableId   | `String`          | 数据表的标识符 |
| fieldId   | `String`          | 字段的标识符  |
| valueList | `Array<String>` | 选项值列表   |
| join      | `String`          | 拼接的字符串  |

**返回值** 

类型 `String`
返回拼接的选项值的名称，如果选项值在选项列表中不存在，则使用选项值拼接。
如果数据表不存在则抛出异常

**示例**

```javascript
//选项值列表：a:'选项1',b:'选项2'
//{amount=11, name=测试采购单, id=z2koxrkxtp854,type=a} 
Record.getRecordOptionNames('order', 'type', ['a', 'b'], ',')//选项1,选项2
Record.getRecordOptionNames('order', 'type', ['a', 'b', 'c'], ',')//选项1,选项2,c
```



## getRecordOptions

返回选项值列表

```javascript
Record.getRecordOptions(tableId, fieldId)
```

| 参数      | 类型     | 描述      |
|---------|--------|---------|
| tableId | `String` | 数据表的标识符 |
| fieldId | `String` | 字段的标识符  |

**返回值**

类型 `Array<Option>`
返回选项值列表，如果字段不是`列表选择` `树形选择` `级联选择`则返回null。
如果数据表不存在则抛出异常

**示例**

```javascript
//选项值列表：a:'选项1',b:'选项2'
Record.getRecordOptions('order', 'type')//[{id:'a',name:'选项1'},{id:'b',name:'选项2'}]
```



## getRelationList

返回查询的数据表关联列表字段的值

```javascript
Record.getRelationList(tableId, fieldId, recordId)
```

| 参数       | 类型     | 描述      |
|----------|--------|---------|
| tableId  | `String` | 数据表的标识符 |
| fieldId  | `String` | 字段的标识符  |
| recordId | `String` | 记录ID    |

**返回值** 

类型 `Array<Record>`
返回关联列表的值，如果字段不是`关联列表`则返回空数组。
如果数据表不存在则抛出异常

**示例**
```javascript
Record.getRelationList('order','orderDetail','z2koxrkxtp854')
```

## getCountByField

根据单个字段过滤数据表记录数量

```javascript
Record.getCountByField(tableId, fieldId, opt, value)
```

| 参数      | 类型     | 描述                                           |
|---------|--------|----------------------------------------------|
| tableId | `String` | 数据表的标识符                                      |
| fieldId | `String` | 过滤的字段                                        |
| opt     | `String` | 操作符，关于操作符参见`ConditionOpt` |
| value   | `Object` | 过滤条件的值                                       |

**返回值**

类型 `Number`
返回满足条件的记录数量。
如果数据表不存在则抛出异常
 
**示例**

```javascript
//{amount=11, name=测试采购单, id=z2koxrkxtp854} 
Record.getCountByField('order', 'amount', 'eq', 11)//1
```

## getCountByFields

根据多个字段过滤数据表记录数量

```javascript
Record.getCountByFields(tableId, conditions)
```

| 参数         | 类型     | 描述                                           |
|------------|--------|----------------------------------------------|
| tableId    | `String` | 数据表的标识符                                      |
| conditions | `Array`  | 过滤条件，关于过滤条件参见[Condition](../script/model.html#condition) |

**返回值**

类型 `Number`
返回满足条件的记录数量。
如果数据表不存在则抛出异常

**示例**

```javascript
//{amount=11, text=13, id=z2koxrkxtp854} 
Record.getCountByFields('tab', [{ "fieldId": 'text', "opt": "eq", "value": '13' }])//1
```

## count

根据多个字段过滤数据表记录数量（与getCountByFields类似）

```javascript
Record.count(tableId, conditions)
```

| 参数         | 类型     | 描述                                           |
|------------|--------|----------------------------------------------|
| tableId    | `String` | 数据表的标识符                                      |
| conditions | `Array`  | 过滤条件，关于过滤条件参见[Condition](../script/model.html#condition) |

**返回值**

类型 `Number`
返回满足条件的记录数量。
如果数据表不存在则抛出异常

**示例**

```javascript
//{amount=11, text=13, id=z2koxrkxtp854} 
Record.count('tab', [{ "fieldId": 'text', "opt": "eq", "value": '13' }])//1
```

## stream

创建数据表记录流，用于链式调用过滤和查询

```javascript
Record.stream(tableId)
```

| 参数      | 类型     | 描述      |
|---------|--------|---------|
| tableId | `String` | 数据表的标识符 |

**返回值**

类型 `RecordStream`
返回一个记录流对象，可以链式调用过滤条件并执行查询。

**示例**

```javascript
Record.stream('order')
  .filter('amount', 'eq', 11)
  .limit(10)
  .list()
```

```javascript
// 使用orderBy按字段排序
Record.stream('order')
  .filter('status', 'eq', 'completed')
  .orderBy('createdAt', 'desc')  // 按创建时间降序排序
  .orderBy('amount', 'asc')      // 再按金额升序排序
  .limit(20)
  .list()
```

### RecordStream 方法

RecordStream 对象提供以下链式方法：

#### limit

设置返回记录的最大数量

```javascript
stream.limit(limit)
```

| 参数    | 类型     | 描述      |
|-------|--------|---------|
| limit | `Number` | 最大记录数量 |

**返回值** `RecordStream` 自身，用于链式调用。

#### id

按ID过滤记录

```javascript
stream.id(recordId)
```

| 参数       | 类型     | 描述   |
|----------|--------|------|
| recordId | `String` | 记录ID |

**返回值** `RecordStream` 自身，用于链式调用。

#### filter

添加过滤条件

```javascript
stream.filter(fieldId, opt, value)
stream.filter(fieldId, opt, value, func)
```

| 参数      | 类型     | 描述                                           |
|---------|--------|----------------------------------------------|
| fieldId | `String` | 过滤的字段                                        |
| opt     | `String` | 操作符，关于操作符参见`ConditionOpt` |
| value   | `Object` | 过滤条件的值                                       |
| func    | `String` | 可选，函数名，如`date`用于日期函数                     |

**返回值** `RecordStream` 自身，用于链式调用。

#### orderBy

添加排序条件

```javascript
stream.orderBy(fieldId, type)
```

| 参数      | 类型     | 描述                     |
|---------|--------|------------------------|
| fieldId | `String` | 排序字段                   |
| type    | `String` | 排序类型：`asc` 或 `desc` |

**返回值** `RecordStream` 自身，用于链式调用。

**示例**

```javascript
// 按创建时间降序排序
stream.orderBy('createdAt', 'desc')

// 按金额升序排序  
stream.orderBy('amount', 'asc')

// 链式调用多个排序条件
stream
  .orderBy('status', 'asc')
  .orderBy('createdAt', 'desc')
```

#### list

执行查询并返回记录列表

```javascript
stream.list()
```

**返回值**

类型 `Array<Record>`
返回满足条件的记录列表，数量受limit限制。

#### count

执行查询并返回记录数量

```javascript
stream.count()
```

**返回值**

类型 `Number`
返回满足条件的记录数量。

#### first

执行查询并返回第一条记录

```javascript
stream.first()
```

**返回值**

类型 `Record`
返回第一条记录，如果没有满足条件的记录则返回`null`。

#### firstProp

执行查询并返回第一条记录的指定字段值

```javascript
stream.firstProp(fieldId)
```

| 参数      | 类型     | 描述      |
|---------|--------|---------|
| fieldId | `String` | 字段标识符   |

**返回值**

类型 `Object`
返回第一条记录的指定字段值，如果没有满足条件的记录则返回`null`。


