> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kasoftware.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Snowflake Lookup 设置

> 从 Snowflake 检索值，并将其插入到工作流中的知行之桥消息中。

Lookup 操作从 Snowflake 检索值并将这些值插入到流中的现有知行之桥消息中。

<ol><li>在 知行之桥 的工作流中，从将为 Snowflake 端口提供输入的端口拖动一个箭头。</li>
<li>（可选）选择 **示例文件**。建议使用示例文件，因为它允许端口提供有关文件结构的更多上下文并帮助构建 [过滤器](#filters) 条件。</li>
<li>完成以下配置步骤后，在 知行之桥 的工作流中，将箭头从 Snowflake 端口拖动到希望生成的 XML 或消息头数据所在的端口。</li></ol>

## Lookup 配置

使用此部分定义要包含在查询中的表和列。[设计器模式](#designer-mode) 可帮助选择要作为查询目标的表和列，而不是要求构建自由形式的查询。但是，如果希望从头开始编写查询，则可以使用 [查询模式](#query-mode)。

### 设计器模式

按照以下步骤使用设计器为 Snowflake 端口配置查找操作。

![Lookup designer](https://docs.kasoftware.com/26.4/images/dbsa_lookup_designer.png)

<ol><li>使用 **表格** 下拉列表选择要包含的表格。</li>
<li>选择要从表中包含的 **列**。</li>
<li>**输出目标**：选择 **XPath** 将查询响应值插入到 XML 文件中，或选择 **Header** 将查询响应值插入到消息头中。
<ul><li>XPath：当选择 XPath 时，目标分为两部分。**父级 XPath** 应已存在于 XML 文档中。**新节点名称** 是注入到 XML 文档中以保存查找结果的节点的名称。查询中的每一列在此处提供的 XML 元素中都有自己的 XML 元素（叶级别）。父级 XPath 可以包含[前瞻语法](https://docs.kasoftware.com/26.4/self-hosted/zh/mapping/mapping-node-value-editor.md#前瞻)，以根据同级条件定位元素；上传示例文件可以更轻松地构建前瞻路径。</li>
<li>Header：当选择 Header 时，端口会向查询中每一列的输出消息添加一个消息头。从数据库返回的每条记录的值均以逗号分隔。</li></ul></li>
<li>使用 **Record Limit** 指定查询返回多个结果时应该发生的情况。
<ul><li>如果从下拉列表中选择 **使用第一个结果**，则可以使用 **如果多个结果时出错** 在返回多个结果时查看错误。</li>
<li>如果选择 **自定义限制**，则必须在显示的字段中指定限制。</li></ul></li>
<li>使用 **排序** 选择按哪一列对结果进行排序。</li>
<li>[过滤器](#filters) 部分允许创建过滤器来构建查询 WHERE 子句，包括对输入文件中的消息头或 XML 的引用。</li></ol>

### 过滤器

可以通过定义单个过滤器和/或过滤器组来构建复杂的过滤器。为了便于阅读，请单击栏右侧的扩展器图标 ![expander](https://docs.kasoftware.com/26.4/images/validate_expander.png) 展开 **Filters** 部分。

要添加过滤器，请单击 **添加过滤器** 或 **添加组**。

当构建过滤器时，请使用下拉菜单进行选择并选择运算符。然后指定要过滤的值。可以从以下选项中进行选择：

<ul><li>消息头</li>
<li>输入 XML</li>
<li>静态值</li></ul>

当为过滤器选择 **输入 XML** 时，如果已上传示例文件，编辑器将显示文档的树形表示形式，以便可以轻松找到所需的 XPath，如下图所示。

![Lookup filter configuration](https://docs.kasoftware.com/26.4/images/dbsa_lookup_filter.png)

XPath 还可以包含[前瞻语法](https://docs.kasoftware.com/26.4/self-hosted/zh/mapping/mapping-node-value-editor.md#前瞻)，以根据同级条件定位元素。这对于 EDI 限定符-值对非常有用。例如：`/Interchange/.../REF[REF01='IA']/REF02` 仅在其同级元素 REF01 等于 `IA` 时定位 REF02 的值。在此处输入方括号时无需转义，这与 *xpath()* 格式化器中使用的反斜杠转义形式不同。

> [!NOTE]
>
> <ul><li>\*\*支持的形式：\*\*存在性检查、相等性检查（与子路径、属性、当前文本或带引号的字面值进行比较），以及使用 AND 组合的多个条件。还支持单独使用的 `[last()]` 位置选择器。</li>
> <li>**不支持的形式会被拒绝**，而不会被静默地重新解释，因此如果 Lookup 拒绝了某个 XPath，请简化该 XPath。不支持的形式包括：任意 XPath 函数和运算符；在同一节点上将 `[last()]` 与其他条件组合使用；在一个路径中使用多个 `[last()]` 选择器；在同一节点上将数字选择器与其他条件组合使用；以及直接附加到末端属性上的条件（应改写为父级过滤器，例如 `/actor[@type='lead']/@type`）。</li>
> <li>\*\*性能：\*\*前瞻语法会使 Lookup 将文档加载到内存中，而不是以流式方式处理，因此会占用更多内存。对于非常大的 XML 输入，建议使用不含前瞻或使用数字位置的 XPath，或者在上游预处理输入，以使 Lookup 保持流式处理模式。</li></ul>

可以重新排序过滤器和组。单击手柄 ![handle](https://docs.kasoftware.com/26.4/images/xmlmap_condition_handle.png) 并将对象拖动到新位置。

### 查询模式

按照以下步骤使用查询模式为 Snowflake 端口配置查找操作。

![Lookup query mode](https://docs.kasoftware.com/26.4/images/dbsa_lookup_query.png)

<ol><li>**输出目标**：选择 **XPath** 将查询响应值插入到 XML 文件中，或选择 **Header** 将查询响应值插入到消息头中。
<ul><li>XPath：当选择 XPath 时，目标分为两部分。**父级 XPath** 应已存在于 XML 文档中。**新节点名称** 是注入到 XML 文档中以保存查找结果的节点的名称。查询中的每一列在此处提供的 XML 元素中都有自己的 XML 元素（叶级别）。父级 XPath 可以包含[前瞻语法](https://docs.kasoftware.com/26.4/self-hosted/zh/mapping/mapping-node-value-editor.md#前瞻)，以根据同级条件定位元素；上传示例文件可以更轻松地构建前瞻路径。</li>
<li>Header：当选择 Header 时，端口会向查询中每一列的输出消息添加一个消息头。从数据库返回的每条记录的值均以逗号分隔。</li></ul></li>
<li>在 **查询** 中，输入 SQL 查询以从 Snowflake 表检索数据。
<ul><li>XPath：将路径格式设置为 `${XPATH:/path/to/element}`。例如，`SELECT CustomerID FROM Customers WHERE CustomerName = ${XPATH:/Items/Invoices/Customer}`。XPath 还可以包含[前瞻语法](https://docs.kasoftware.com/26.4/self-hosted/zh/mapping/mapping-node-value-editor.md#前瞻)，以根据同级条件定位元素。例如，`${XPATH:/Interchange/.../REF[REF01='IA']/REF02}` 仅在其同级元素 REF01 等于 `IA` 时定位 REF02 的值。有关支持的前瞻形式和性能注意事项，请参阅[过滤器](#filters)。</li>
<li>Header：将路径格式设置为 `${HEADER:HeaderName}`。</li></ul></li>
<li>这两个复选框可让您配置当查询返回多个结果时应发生的情况。
<ul><li>选中 **使用第一个结果** 以始终使用第一个结果。</li>
<li>选中 **如果多个结果时出错** 以在返回多个结果时返回错误。</li></ul></li></ol>

## 高级设置

![Lookup advanced settings](https://docs.kasoftware.com/26.4/images/dbsa_lookup_advanced.png)
<ol><li>使用 **未找到匹配记录操作** 来指定如果未找到与查询匹配的记录时应执行的操作。</li>
<li>Snowflake 端口可以针对本地缓存执行 Lookup 查询，而不是直接为每个 Lookup 查询 Snowflake。这可以提高查询性能，尤其是对于较大的数据库。要启用此功能，请在 **查找缓存** 下选择 **启用** 并配置其余字段。
<ul><li>**查找缓存提供程序**：选择使用哪个驱动程序以方便连接到缓存数据库。</li>
<li>**查找缓存连接字符串**：设置后，端口将使用此处指定的数据库进行缓存。</li>
<li>**查找缓存容差**：控制端口向数据源发出查询以刷新缓存的频率。</li>
<li>**查找缓存容差单位**：**查找缓存容差** 的单位。选择分钟、小时或天。</li>
<li>**重置缓存**：清除所有缓存数据，并强制端口在下一次 Lookup 时重新查询 Snowflake。</li></ul></li></ol>

> [!NOTE]
>
> <ul><li>如果查询未从缓存返回结果，端口将直接查询 Snowflake。</li>
> <li>如果查询语句包含 `limit`、`offset` 或 `groupby` 参数，则缓存功能不起作用。这些查询直接转到 Snowflake。</li></ul>

## 测试 Lookup

使用 **测试 Lookup** 按钮检查配置并查看结果，而无需手动处理文件。使用 **保存示例数据** 按钮将输出保存为示例，以便稍后在流程中进行映射。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.