---
source_url: https://docs.dolphindb.cn/zh/funcs/k/keyedStreamTable.html
fetched_at: 2026-05-19T09:29:12Z
category: funcs
title: keyedStreamTable
sha1: e66667073fd2f0f59ec1f110a9321508033b6a3d
---

# keyedStreamTable

## 语法

`keyedStreamTable(keyColumn, X, [X1], [X2], .....)`

或

`keyedStreamTable(keyColumn, capacity:size, colNames, colTypes)`

## 详情

创建键值流数据表。该表的主键不允许包含重复值。主键支持一个或多个字段。

实际应用中，可能由于网络原因，会出现数据重复提交写入的情况；或者在上游采用了多路高可用的方式写入数据。面对上述场景，键值流数据表可以实现流数据的幂等性写入，即多次写入键值相同的数据，其结果与第一次写入的结果相同，从而避免数据重复写入。

需要注意的是，此处的键值唯一性并非全局唯一，而是指内存中数据的唯一性。为流数据表开启持久化，可以设置内存中保留的数据条数，一旦数据条数超过设定的上限，系统将一半旧的数据持久化至磁盘。这种方案确保了内存中数据键值的唯一性，而不是全局唯一性。尽管如此，已足以解决多路写入或网络延迟导致的重复提交写入的问题。

向表中添加新记录时，系统会自动检查新记录的主键值：

- 如果新记录的主键值与内存中已有记录的主键值重复时，已有的记录不会被更新。
- 一次性批量插入新记录时，若有多条记录具有相同的主键值，且该主键值与已有记录的主键值不同，只有第一条记录能成功插入。

## 参数

**keyColumn** 是一个字符串或向量，表示主键。主键的数据类型必须属于以下类别：INTEGRAL,
TEMPORAL, LITERAL 或 FLOATING。

第一种用法中，**X**, **X1**, **X2** ...
可以是向量、数组向量、矩阵或元组。每个向量、元组、数组向量的长度，以及矩阵中每列长度都必须相同。**当 Xk 是元组时：**

- 若 Xk 的元素是等长的向量，**元组的每个元素将作为表的一列。**元组的长度必须等于表的行数。
- 若 Xk 包含不同类型或不等长元素，**则将单独作为表的一列（列类型为 ANY），其每个元素将作为该列每行的元素值。**Xk
  的长度仍然必须和表的行数保持一致。

第二种用法中：

- **capacity** 是正整数，表示建表时系统为该表分配的内存（以记录数为单位）。当记录数超过 *capacity*
  时，系统首先会分配 *capacity*
  1.2~2倍的新的内存空间，然后复制数据到新的内存空间，最后释放原来的内存。对于规模较大的表，此类操作的内存占用会很高。因此，建议建表时预先分配一个合理的
  *capacity*。
- **size** 是整数，表示该表新建时的行数。若 *size* =0，创建一个空表。 若
  *size*>0，则建立一个只包含 size 条记录的表，记录初始值如下：

  - BOOL 类型默认值为 false；
  - 数值类型、时间类型、IPADDR、COMPLEX、POINT 的默认值为 0；
  - Literal, INT128 类型的默认值为 NULL。

  注：

  如果
  *colTypes* 指定为数组向量， *size* 必须为0。
- **colNames** 是一个向量，表示列名。
- **colTypes**
  是一个向量，表示每列的数据类型，允许主键外的其它列指定为数组向量类型或元组（ANY）类型。可使用表示数据类型的系统保留字或相应的字符串。

## 返回值

一个表。

## 例子

第一种用法：

```dolphindb
id=`A`B`C`D`E
x=1 2 3 4 5
t1=keyedStreamTable(`id, id, x)
t1;
```

| id | x |
| --- | --- |
| A | 1 |
| B | 2 |
| C | 3 |
| D | 4 |
| E | 5 |

第二种用法：

```dolphindb
t2=keyedStreamTable(`id,100:0,`id`x, [INT,INT])
insert into t2 values(1 2 3,10 20 30);
t2;
```

| id | x |
| --- | --- |
| 1 | 10 |
| 2 | 20 |
| 3 | 30 |

往表 t2 中插入重复主键值的数据：

```dolphindb
insert into t2 values(3 4 5,35 45 55)
t2;
```

| id | x |
| --- | --- |
| 1 | 10 |
| 2 | 20 |
| 3 | 30 |
| 4 | 45 |
| 5 | 55 |

可以看到，id=3 的记录并没有被覆盖。

主键为多个字段：

```dolphindb
t=keyedStreamTable(`sym`id,1:0,`sym`id`val,[SYMBOL,INT,DOUBLE])
insert into t values(`A`B`C`D`E,5 4 3 2 1,52.1 64.2 25.5 48.8 71.9);
insert into t values(`A`B`R`T`Y,5 8 3 2 1,152.3 164.6 125.5 148.8 171.6);
t;
```

| sym | id | val |
| --- | --- | --- |
| A | 5 | 52.1 |
| B | 4 | 64.2 |
| C | 3 | 25.5 |
| D | 2 | 48.8 |
| E | 1 | 71.9 |
| B | 8 | 164.6 |
| R | 3 | 125.5 |
| T | 2 | 148.8 |
| Y | 1 | 171.6 |
