通过自然语言执行 SQL 查询

向模型发送自然语言提示和数据库模式，模型返回 SQL 查询，从数据库获取结果，用于其响应。

选项 

• 账户名称是此脚本步骤所使用的 AI 账户的文本表达式。在当前文件中，使用配置 AI 账户脚本步骤设置账户，并在此脚本步骤运行之前随时为其分配此名称。

• 模型是要使用的文本生成模型的名称。将模型名称指定为文本表达式。有关支持的模型，请参阅 FileMaker 技术规格。

• 提示是用于发送给模型的自然语言请求或问题的文本表达式。

• 指定的选项确定此脚本步骤的其他选项的配置方式。

  • 来自列表：使用以下设置单独配置选项。

  • 通过 JSON 数据：通过提供 JSON 对象来配置以下选项。此选项对于动态设置值很有用。JSON 对象必须包含与脚本步骤选项及其值相对应的键值对。支持的选项的对应键是：

    • 操作：与所需操作对应的字符串值："查询"，"仅查询数据"，"获取 SQL"，“仅获取第一个 SQL”，“获取 DDL”。

    • 数据表：JSON 字符串数组，其中每个字符串都是应包含模式的表的名称。例如：[“联系人”，“地址”]。

    • 流：流选项的字符串值（“开”或“关”）。

    例如：

    复制

    {
        "操作" : "获取 SQL",
        "数据表" : [ "产品", "发票" ],
        "流" : "关"
    }

• 操作指定要从模型中检索的回复类型。

  • 查询：以自然语言返回模型对用户提示的最终回复。

  • 仅查询数据：仅返回该脚本步骤执行的模型最后一个 SQL 查询检索的数据。

  • 获取 SQL：返回模型在整个交互期间生成的所有 SQL 语句。

  • 仅获取第一个 SQL：仅返回模型生成的第一个 SQL 语句。

  • 获取 DDL：返回此脚本步骤生成并发送到模型的数据库架构（以数据定义语言）。

• 数据表指示您希望如何为模型的表指定数据库架构。仅发送指定表的架构。

  • 来自列表：从列表中选择特定表格。

  • 通过名称：提供表格名称列表作为文本表达式。用回车符分隔多个表名称。

  • 通过 DDL：提供自定义 DDL 文本表达式。这允许您准确控制哪些架构信息发送到模型。

• 当数据表为来自列表时，表是您选择表的位置。

• 当操作为查询 时，流会确定回复的传递方式。

  • 开：检索回复并进行递增传递（逐字或按块）。这可让 FileMaker 客户端响应更快。

  • 关：在可用之前检索整个回复。这可能会导致 FileMaker 客户端在等待完整回复时出现无响应。

• 参数是 JSON 对象的文本表达式，由模型提供商支持的其他参数的键值对组成。例如：{"温度": 0.7，“种子”：42}.有关受支持参数的键名称及其有效范围，请参阅模型提供商的文档。

• 提示模板名称指定使用配置提示模板脚本步骤配置的自定义提示模板的名称。此选项用于设计额外的提示，以帮助从 AI 模型获得最佳回复。

• 回复目标指定要存储脚本步骤结果的字段或变量。

• 在 Web 查看器中执行 JavaScript 指定在脚本步骤完成后在目标 Web 查看器中执行的 JavaScript 代码。此选项类似于运行在 Web 查看器中执行 JavaScript 脚本步骤作为下一个脚本步骤，除了 Stream 选项为“开”时，回复目标可以传递到 JavaScript 函数，响应以流式传输到 Web 查看器。

  • Web 查看器指定当前布局上 Web 查看器的对象名称。

  • 函数名称是在 Web 查看器中调用的 JavaScript 函数的名称。

原始版本 

22.0

说明 

此脚本步骤允许您使用自然语言查询数据库，而不是直接编写 SQL 语句。它使用 AI 模型来解释自然语言提示，分析数据库模式，生成适当的 SQL 查询，然后在这个脚本步骤执行 SQL 查询后，模型可以用自然语言回复结果。您的任何 FileMaker 数据都不需要发送到模型。

此脚本步骤和模型之间的交互通常会执行以下步骤：

1. 此脚本步骤将提示和相关数据库架构（由数据表指定的 DDL）发送到配置的 AI 模型。（这包括可选提示模板中提供的提示。）

2. 该模型分析提示和模式，并生成一个或多个 SQL 查询，旨在从数据库中检索请求的信息。

3. 此脚本步骤从模型接收生成的 SQL 查询并执行它们。

4. 此脚本步骤将 SQL 查询执行的结果发回模型。

5. 如果模型确定结果需要进一步处理或完善以完全解决提示，它可能会生成额外的 SQL 查询（重复步骤 2-4）。这允许进行复杂的查询或多步数据检索。

6. 在模型获得足够的信息后，它根据收到的提示和 SQL 查询结果生成最终回复。

7. 此脚本步骤接收最终回复并将其存储在回复目标中。

操作选项确定在此过程的不同阶段返回回复目标的内容：

调试操作主要用于了解脚本步骤在测试脚本时如何与模型和数据库架构进行交互。

注释 

• 如果您指定提示模板名称，则此脚本步骤将使用通过配置提示模板脚本步骤配置的模板。这些模板可以使用 :schema:、:question:、:sql_query: 和 :sql_results: 等在执行过程中被动态替换的常量。可用的常量取决于模板类型和当前的操作。

• 您在“管理数据库”对话框中输入的字段注释包含在发送到模型的数据库架构中。为了提高模型生成有用的 SQL 语句的能力，您可以使用注释来解释该字段的目的（例如，当字段是标识相关表中记录的外来键时）。请参阅 DDL 和 SQL 查询生成中数据库架构的最佳实践。

• 在从模型中收到最终的自然语言回复之前，此脚本步骤无法确定哪一轮 SQL 生成和执行是最后的。

• 在执行查询或仅查询数据操作期间，此脚本步骤接收并存储模型生成的所有 SQL 语句以及上次执行的 SQL 查询的结果。这些分别是获取 SQL 和仅查询数据操作返回的相同结果。

• 当此脚本步骤执行时没有错误，但没有找到相关信息，回复目标中返回一条消息，Get (上一个错误)函数返回错误 0（“无错误”）。

• 在由 FileMaker Server、FileMaker Cloud、FileMaker Data API、OData API 和自定义 Web Publishing 运行的脚本中，不支持“在 Web 查看器中执行 JavaScript”选项。

示例 1 

配置 AI 账户，然后使用“通过自然语言执行 SQL 查询”脚本步骤来询问有关联系人表中数据的问题，该表中在“名称”和“公司”字段中包含数据。脚本步骤发送联系人表的架构和提示“Alea 在哪家公司工作？”到模型。模型生成必要的 SQL 查询，并执行此脚本步骤，然后模型提供存储在回复字段中的自然语言响应。

配置 AI 账户 [ 账户名称: "my-account" ; 模型提供商: OpenAI ; API 密钥: "sk-..." ]

通过自然语言执行 SQL 查询 [ 账户名称: "my-account" ; 模型: "gpt-4o" ; 提示: "Alea 在哪家公司工作？" ；指定选项：来自列表；操作：查询；数据表：来自列表；表...；流；回复目标：联系人::回复]

可能的回复存储在“联系人::回复”字段中：

Alea 在 Acme Anvils, Inc. 工作。

示例 2 

在自定义对话框中询问用户问题——其中默认按钮是“查询”，按钮 2 是“仅数据”，按钮 3 是“取消”——问题存储在 $$UserPrompt 变量中。然后设置 $options 变量，以反映用户对操作执行的选择：查询或仅查询数据。如果用户输入了问题，但没有单击“取消”，则运行“通过自然语言执行 SQL 查询”脚本步骤，传递 $$UserPrompt 和 $options，然后在 $$QueryResultData 中返回模型的结果，该结果显示在另一个自定义对话框中。查询仅限于“联系人”和“员工”表。

配置 AI 账户 [ 账户名称: "my-account" ; 模型提供商: OpenAI ; API 密钥: "sk-..." ]

显示自定义对话框 [ "询问数据为:" ; $$UserPrompt ]

设置变量 [ $options ; 值: 
    Let ( [
        $choice = Get ( LastMessageChoice ) ;
        action_choice = Case ( 
            $choice = 1 ; "查询" ;
            $choice = 2 ; "仅查询数据"
            ) 
        ] ; 
    
        JSONSetElement (
            ""; 
            [ "操作" ; action_choice ; JSONString ] ;
            [ "数据表" ; JSONMakeArray ( 
                    "Contacts¶Employees" ;
                    "¶" ; 
                    JSONString 
                ) ;
                JSONArray ] ; 
            [ "流" ; "关" ; JSONString ]
        )
    )
]

If [ not IsEmpty ( $$UserPrompt ) 和 $choice ≠ 3 ]

    通过自然语言执行 SQL 查询 [ 账户名称: "my-account" ; 模型: "gpt-4o" ; 提示: $$UserPrompt ; 指定的选项: 按 JSON 数据 ; 回复目标: $$QueryResultData ]
    
    显示自定义对话框 [ "数据结果:" ; $$QueryResultData ]
    
End If

可能的回复存储在 $$QueryResultData 中，假设提示是“Alea 在哪家公司工作？”然后用户点击了“仅数据”按钮：

Acme Anvils, Inc.

示例 3 

演示使用获取 SQL 和获取 DDL 操作进行调试。脚本首先检索为“产品”和“订单”表生成的 DDL，然后检索模型为特定提示生成的所有 SQL 语句，将每个语句存储在单独的变量中以供审查。

通过自然语言执行 SQL 查询 [ 账户名称: "my-account" ; 模型: "gpt-4o" ; 提示: " " ; 指定的选项: 来自列表 ; 操作: 获取 DDL ; 数据表: 按名称 ; "Products¶Orders" ; 回复目标: $$ProductsOrdersDDL ]

通过自然语言执行 SQL 查询 [ 账户名称: "my-account" ; 模型: "gpt-4o" ; 提示: "查找产品 ID 101 的订单总值" ; 指定的选项: 来自列表 ; 操作: 获取 SQL ; 数据表: 按名称 ; "Products¶Orders" ; 回复目标: $$GeneratedSQL ]

显示自定义对话框 [ "调试信息" ; "生成的 DDL:" & ¶ & $$ProductsOrdersDDL & ¶ & ¶ & "生成的 SQL:" & ¶ & $$GeneratedSQL ]

可能存储在 $$ProductsOrdersDDL 中的 DDL：

创建表 "产品" (
"产品 ID" int, /*唯一标识产品的主键*/
"产品名称" varchar(255), /*产品的描述性名称*/
"价格" int, /*以美元表示的产品价格*/
主键 (产品 ID)
);

创建表 "订单" (
"订单 ID" int, /*唯一标识订单的主键*/
"产品 ID" int, /*表示与产品表多一对关系的外部键*/
"数量" int, /*订单中产品的数量*/
主键 (订单 ID),
外部键 (产品 ID) 参考产品(产品 ID)
);

可能存储在 $$GeneratedSQL 中的 SQL 语句：

选择总和("数量" * "价格") 作为 "总值" 从 "订单" 加入 "产品" 开 "订单"."产品 ID" = "产品"。"产品 ID" WHERE "订单"。"产品 ID” = 101

相关主题 

• 配置 AI 账户脚本步骤

• 配置提示模板脚本步骤

• 在 Web 查看器中执行 JavaScript 脚本步骤。

• DDL 和 SQL 查询生成中数据库架构的最佳实践

• GetTableDDL函数

• 脚本步骤参考