向量数据类型

向量是用于预先计算的嵌入的列数据类型。向量列在每一行中保存一个浮点数数组，即您已在使用的嵌入模型的输出。该数组存放在普通项目表中，与描述它的文本、键、金额和维度位于同一行。由于它是普通表中的普通列，因此可以与事实表联接，也可以通过与其他列相同的导入和转换步骤加载。无需单独配置、填充向量存储，也无需让它与其余数据保持同步。

随后，AI：向量搜索步骤会查找与一个或多个查询向量最接近的行，因此相似度查找与其他任何步骤一样，只是工作流中的一个步骤。

声明向量列

向量显示在数据类型列表的半结构化组中，与 JSON 和 Bitmap 并列，出现于工作流步骤的输出列映射和表的列属性中。它不会作为导入步骤的源数据类型提供：文件中的值以数字列表的形式到达，并落入已设为向量类型的列中。在要求单一标量类型的位置也不提供该类型，例如工作流变量的声明类型。

该类型本身不携带维度。系统并非按宽度提供一系列类型，而是只有一种向量类型，再为每一列声明其向量的宽度。

向量宽度

打开表的列详细信息面板，选择向量列，然后将向量宽度设置为每个嵌入包含的值的个数，例如 768、1024、1536，具体取决于您的模型输出。该字段仅出现在 Lakehouse v2 (StarRocks) 项目中的向量列上，其他位置均不出现。

声明的宽度会在每条加载路径上强制执行。向量长度不同的行会在任何数据落入之前被拒绝，拒绝信息会指明文件、列、行、实际找到的长度以及您声明的宽度，让您确切了解是哪个值不一致、相差多少；对于文件加载，行从文件的第 1 行开始计数。这样，截断的文件或被替换的嵌入模型就会变成一次可以读懂的失败运行。

该检查涵盖嵌入到达表中的所有途径：

Parquet 导入。
REST 连接器，包括 QuickBooks、Xero、Sage 和 Monday.com。
Singer tap。
直接对源运行的针对远程数据库的查询。
向表中写入数据帧的工作流步骤。
归档导入或归档还原，此时拒绝信息会指明归档文件。
表包导入。表包导出会将向量列写为真正的向量，因此表包往返后宽度保持不变。

以下两种情况不在检查范围内：

CSV 导入不做检查，也无法检查。 转换会在检查宽度之前将数组转为文本，因此 CSV 是唯一可能将不同宽度的数据放入该列的途径。
行级写入，即保存单个行或记录，以及由带键连接器落入一行，会在写入时能够识别该列为向量的情况下进行检查。这是常见情形，而非无条件的保证。

如果列上仍保留宽度声明，但表已不再将该列定为向量类型，则该宽度不再适用。重新设置该列的类型后，该声明将不再约束落入其中的内容。

这很重要，因为各行宽度不同的列无法搜索。对其进行向量搜索时，会返回底层引擎的原始错误，而不是指明该列的消息。因此，如果以 CSV 加载嵌入，请确保文件生成的宽度与您声明的宽度一致，或者先将数组暂存为 Parquet 再导入，这样系统会为您执行检查。

请在加载之前声明宽度。向量宽度取 1 或更大的整数，没有可以回退到的空值，清空该字段只会恢复已存储的值，因此请将该声明视为列设计的一部分。

搜索也以该宽度为依据。如果列没有声明宽度，搜索需要先抽样一行来了解存储的向量有多宽，然后才能将查询与它们进行核对。

加载向量

使用标准的导入和转换步骤加载向量列。最直接的途径是使用列为 32 位浮点数列表的 Parquet 文件：导入 Parquet 步骤会将其直接落入向量列。

典型的端到端流程全部使用标准步骤：

导入 Parquet（或任何其他导入步骤）：将嵌入及其业务键落入一个表，该表的嵌入列已设为向量类型并声明了向量宽度。
Table Inner Join 步骤：按业务键将该表与嵌入所描述的事实表或参考表联接。
AI：向量搜索：查找与查询向量最接近的行，并将匹配项写入目标表。
Table Lookup 步骤：将要显示的描述性列带回匹配行。

可读取文件的位置

检查宽度需要单独读取向量列，这要求文档账户能够按列读取。S3、Google Cloud Storage 和 Azure Blob Storage 可以做到。从任何其他文档账户向声明了向量宽度的表执行 Parquet 导入时，会被拒绝而不是不经检查就加载，因此请将文件暂存到 S3、Google Cloud Storage 或 Azure Blob Storage，再从那里导入。从此类账户还原归档时也是如此：还原属于恢复操作，因此请将归档保存在还原能够读取的账户上。未声明向量宽度的表不受影响，其他所有导入步骤也不受影响。

搜索最近的行

AI：向量搜索步骤接受要搜索的表、一个或多个查询向量，以及每个查询要保留的匹配数，并将最近的行连同用于排序的距离一起写入目标表。

提供两种距离度量，两者都是距离越小，行越近：

余弦：两个向量之间的夹角，忽略其大小。这是文本嵌入的合适默认选择。
欧氏（L2）：直线距离，会考虑向量的大小。

系统有意不提供内积。对于未归一化的向量，内积根本不是距离，向量与自身的距离会是负数，因此针对它设置的任何阈值以及步骤显示的任何分数都没有意义，即使排序碰巧是对的。对于已归一化的嵌入，按余弦排序得到的顺序与内积相同，因此不会损失任何功能。

有关完整的参数列表，请参阅 AI：向量搜索。

搜索是精确的，而非近似的

该步骤会将每个通过其筛选器的行与每个查询向量进行比较。没有向量索引，也没有近似：结果就是真正最近的集合，工作量随搜索的行数乘以查询向量数的积增长。

请据此确定规模。使用步骤的筛选器将候选行缩小到重要的部分，例如一个实体、一个期间、一个文档集，而不是为了回答只涉及其中一部分的问题而扫描整个语料库。按您始终筛选的维度拆分嵌入表，并搜索相关的表，是缩短搜索时间最有效的一个办法。

无法度量的行会被排除

距离无法度量的行会被排除在匹配项之外，而不会被当作最近的行返回。在开启诊断模式的情况下运行工作流，日志会报告每个查询排除了多少行，或者说明该步骤已度量其搜索的每一行。

如果存储的向量数组内部缺少某个值，则会被拒绝而不是被跳过：无法针对包含缺失值的数组度量距离，因此搜索会停止并指明该列，而不是返回部分结果。

向量列不能做什么

嵌入是坐标，而不是键或度量，因此在把它当作键或度量的角色中，向量列会被拒绝：

不能作为联接键。 请按向量旁边的业务键联接。
不能作为分组列。 按原始嵌入对行分组，会让每一行各自成组。
不能作为聚合目标。 嵌入的总和、平均值、最小值或最大值没有意义。

这三种情况都会被拒绝，并给出指明列和角色的消息：在保存步骤时拒绝，对于之前已保存的步骤，则在运行时再次拒绝。包含上述任何一种情况的工作流不会运行，也不会悄悄产生错误的数字。将向量作为普通输出列在步骤中传递是可以的，对行计数和对不同值计数也可以。

向量列还会被排除在表资源管理器的列分析和值列表之外，不能在仪表板上绘制图表，在数据编辑器中为只读，也不能链接到维度。对嵌入求最小值、平均值或最常见值的列表没有意义，嵌入也不是任何事物的成员。

读回向量值

读取整个向量列时，无论是在预览、导出中，还是通过 MCP 使用 AI 助手，返回的都是数组的文本呈现形式，而不是数字。要取回数字，请单独读取各个元素。

在数据网格中，值显示为以宽度开头的简短预览，例如 1536-dim [0.013,-0.046,0.079, ...]，这样一列嵌入保持可读，而不必在每个单元格中显示上千个数字。