使用自然语言问题生成 SQL 查询

本页面介绍了如何使用 AlloyDB AI 自然语言设置、配置和生成 SQL 语句。借助自然语言，您可以使用自然语言创建面向用户的生成式 AI 应用来查询数据库。

如需启用 alloydb_ai_nl 扩展程序（即 AlloyDB for PostgreSQL 自然语言支持 API），请执行以下概要步骤：

  1. 安装 alloydb_ai_nl 扩展程序。
  2. 为应用定义自然语言配置。
  3. 注册架构。
  4. 添加上下文。
  5. 添加查询模板。
  6. 定义概念类型并创建值索引。
  7. 使用自然语言界面生成 SQL 语句。

准备工作

启用必需的扩展程序

在安装和使用 AlloyDB AI 自然语言之前，您必须通过添加 alloydb_ai_nl.enabled 标志来启用该扩展程序。

由于在主实例上创建的 AlloyDB AI 自然语言对象会传播到只读副本和跨区域副本，因此请确保在每个 AlloyDB for PostgreSQL 实例上启用 AlloyDB AI 自然语言标志。如需了解详情，请参阅配置实例的数据库标志。

创建集群并启用 Vertex AI 集成

  1. 创建 AlloyDB 集群和实例。 您可以使用 AlloyDB 实例来创建应用数据库和架构。
  2. 启用 Vertex AI 集成。如需了解详情，请参阅与 Vertex AI 集成。

所需的角色

如需安装 alloydb_ai_nl 扩展程序并向其他用户授予访问权限，您必须在所使用的 Google Cloud 项目中具有以下 Identity and Access Management (IAM) 角色：

如需了解详情，请参阅使用标准身份验证管理 PostgreSQL 用户。

准备环境

为了准备生成自然语言查询，您必须安装所需的扩展程序、创建配置并注册架构。

安装 alloydb_ai_nl 扩展程序

alloydb_ai_nl 扩展程序使用 google_ml_integration 扩展程序，该扩展程序与大语言模型 (LLM)（包括 Vertex AI 上的 Gemini 模型）互动。

如需安装 alloydb_ai_nl 扩展程序，请连接到数据库并运行以下命令：

CREATE EXTENSION alloydb_ai_nl cascade;

升级 alloydb_ai_nl 扩展程序

确保您使用的是最新版 alloydb_ai_nl 扩展程序。如果您已安装该扩展程序，请检查是否有新的扩展程序版本可用，如果您使用的不是最新版本，请升级该扩展程序。 如需详细了解 alloydb_ai_nl 扩展程序，请参阅 AlloyDB AI 自然语言概览。

  1. 确定是否需要升级扩展程序。如果 default_version 晚于 installed_version，请升级扩展程序。

    SELECT * FROM pg_available_extensions where name = 'alloydb_ai_nl';

  2. 升级扩展程序。

    ALTER EXTENSION alloydb_ai_nl UPDATE;

创建自然语言配置并注册架构

AlloyDB AI 自然语言使用 nl_config 将应用关联到特定架构、查询模板和模型端点。 nl_config 是一种配置，用于将应用关联到架构、模板和其他上下文。大型应用还可以针对应用的不同部分使用不同的配置，只要您在从应用的该部分发送问题时指定正确的配置即可。您可以注册整个架构，也可以注册特定的架构对象，例如表、视图和列。

  1. 如需创建自然语言配置，请使用以下示例：

    SELECT
  alloydb_ai_nl.g_create_configuration(
    'my_app_config'        -- configuration_id
  );

    gemini-2.0-flash:generateContent 是模型端点。

  2. 请使用以下示例为指定的配置注册架构：

    SELECT
  alloydb_ai_nl.g_manage_configuration(
    operation => 'register_schema',
    configuration_id_in => 'my_app_config',
    schema_names_in => '{my_schema}'
  );

添加上下文

上下文包含您可以用来回答最终用户问题的任何类型的信息，例如：

  • 架构结构和关系
  • 列的摘要和说明
  • 列值及其语义
  • 特定于应用或网域的业务逻辑的规则或语句

为应用特定的规则添加常规上下文

常规上下文项包括应用特定的规则、业务逻辑语句，或未与特定架构对象关联的任何应用和网域特定的术语。

如需为应用特定的规则和应用或网域特定的术语添加常规上下文，请按照以下步骤操作：

  1. 如需为指定的配置添加常规上下文项，请运行以下查询：

    SELECT
  alloydb_ai_nl.g_manage_configuration(
    'add_general_context',
    'my_app_config',
    general_context_in => '{"If the user asks for a good seat, assume that means a window or aisle seat."}'
  );

    上述语句可帮助 AlloyDB AI 自然语言为用户的自然语言问题提供更优质的响应。

  2. 如需查看指定配置的常规上下文，请运行以下查询：

    SELECT alloydb_ai_nl.list_general_context(nl_config TEXT);

生成并查看架构上下文

架构上下文描述了架构对象，包括表、视图、物化视图和列。此上下文存储为每个架构对象的 COMMENT。

  1. 如需为架构对象生成上下文，请调用以下 API。为获得最佳效果，请确保数据库表包含代表性的数据。

    -- For all schema objects (tables, views, materialized views and columns)
-- within the scope of a provided nl_config.
SELECT
  alloydb_ai_nl.generate_schema_context(
    'my_app_config' -- nl_config
  );

  2. 通过运行以下查询，查看生成的架构上下文：

    SELECT schema_object, object_context
FROM alloydb_ai_nl.generated_schema_context_view;

    生成的架构上下文存储在上述视图中。

  3. 可选：更新生成的架构上下文。

    SELECT
  alloydb_ai_nl.update_generated_relation_context(
    'my_schema.my_table',
    'This table contains archival records, if you need latest records use records_new table.'
  );

SELECT
  alloydb_ai_nl.update_generated_column_context(
    'my_schema.my_table.column1',
    'The seat_class column takes single letters like "E" for economy, "P" for premium economy, "B" for business and "F" for First.'
  );

  4. 应用上下文。当您应用上下文时，上下文会立即生效，并从视图 generated_schema_context_view 中删除。

    -- For all schema objects (tables, views, materialized views and columns)
-- within the scope of nl_config.
SELECT
  alloydb_ai_nl.apply_generated_schema_context(
    'my_app_config' --nl_config
  );

  5. 可选：验证生成的上下文。借助以下 API，您可以检查架构上下文，在生成 SQL 语句时会使用这些上下文。

    -- For table, view or materialized view.
SELECT
  alloydb_ai_nl.get_relation_context(
    'my_schema.my_table'
  );

-- For column.
SELECT
  alloydb_ai_nl.get_column_context(
    'my_schema.my_table.column1'
  );

  6. 可选：手动设置架构上下文。

    -- For table, view or materialized view.
SELECT
  alloydb_ai_nl.set_relation_context(
    'my_schema.my_table',
    'One-to-many mapping from product to categories'
  );

-- For column.
SELECT
  alloydb_ai_nl.set_column_context(
    'my_schema.my_table.column1',
    'This column provides additional tagged info for the product in  Json format, e.g., additional color or size information of the product - tags: { "color": "red", "size": "XL"}'
  );

创建查询模板

如需提高使用 LLM 构建的生成式 AI 应用的质量，您可以添加模板。查询模板是一组精选的代表性或常见的自然语言问题，其中包含相应的 SQL 查询以及说明，以便为自然语言到 SQL (NL2SQL) 生成提供声明性依据。模板主要由应用指定，但模板也可以由 alloydb_ai_nl 扩展程序根据常用 SQL 查询自动生成。每个模板都必须与 nl_config 关联。

alloydb_ai_nl 扩展程序使用 template_store 在生成 SQL 语句的过程中动态合并相关 SQL 模板，以回答最终用户的问题。template_store 执行以下操作：

  • 识别与最终用户提出的自然语言问题意图类似的模板。
  • 用于标识相应的参数化 SQL 语句。
  • 通过使用自然语言问题中的值实例化参数来合成 SQL 语句。

如果没有与最终用户提出的问题具有相同意图的模板，alloydb_ai_nl 会使用每个相关的模板和上下文来编写 SQL 语句。

将模板添加到模板存储区

您可以通过指定问题（使用名为 intent 的参数）和 SQL 查询，来添加模板。

如需将模板添加到模板存储区，请运行以下查询：

SELECT
  alloydb_ai_nl.add_template(
    nl_config_id => 'my_app_config',
    intent => 'How many accounts associated with loans are located in the Prague region?',
    sql => 'SELECT COUNT(T1.account_id)
            FROM bird_dev_financial.account AS T1
            INNER JOIN bird_dev_financial.loan AS T2
              ON T1.account_id = T2.account_id
            INNER JOIN bird_dev_financial.district AS T3
              ON T1.district_id = T3.district_id
            WHERE T3."A3" = ''Prague''',
    check_intent => TRUE
  );

当 check_intent 为 TRUE 时，alloydb_ai_nl 会执行语义检查，以确认所提供的 intent 与传入的 SQL 语句匹配。如果 intent 与 SQL 语句不匹配，系统不会添加模板。

SQL 和 intent 通过 alloydb_ai_nl 进行参数化。alloydb_ai_nl.template_store_view 视图会显示参数化 SQL 语句及其意图。

SELECT psql
FROM alloydb_ai_nl.template_store_view
WHERE intent = 'How many accounts associated with loans are located in the Prague region?';

此语句会返回以下内容：

SELECT COUNT(T1.account_id)
FROM account AS T1 INNER JOIN loan AS T2
  ON T1.account_id = T2.account_id
INNER JOIN district AS T3
  ON T1.district_id = T3.district_id WHERE T3."A3" = $1

提供自定义形参化

如需使用 add_template 函数的手动界面为 SQL 语句提供自定义形参化，请运行以下示例中的语句：

SELECT
  alloydb_ai_nl.add_template(
     nl_config_id => 'my_app_config',
     intent => 'Among the accounts opened, how many customers born before 1950 resided in Slokolov at the time of account opening?',
     sql => $$SELECT COUNT(DISTINCT T2.client_id)
              FROM district AS T1 INNER JOIN client AS T2
                ON T1.district_id = T2.district_id
             INNER JOIN account AS T3 ON T2.client_id IN (
                   SELECT client_id FROM disp WHERE account_id = T3.account_id)
             WHERE to_char(T2.birth_date::timestamp, 'YYYY') < '1950'
               AND T1."A2" = 'Slokolov'$$,
  parameterized_sql => $$SELECT COUNT(DISTINCT T2.client_id)
                         FROM district AS T1 INNER JOIN client AS T2
                           ON T1.district_id = T2.district_id
                   INNER JOIN account AS T3 ON T2.client_id IN (
                         SELECT client_id FROM disp WHERE account_id = T3.account_id)
                   WHERE to_char(T2.birth_date::timestamp, 'YYYY') < $2
                     AND T1."A2" = $1$$,
  parameterized_intent => $$Among the accounts opened, how many customers born before $2 resided in $1 at the time of account opening?$$,
  manifest => $$Among the accounts opened, how many customers born before a given date resided in a given city at the time of account opening?$$,
  check_intent => TRUE);

在上述定义中，提供了 SQL 语句的形参化。对于 Slokolov 和 1950，参数分别为 $1 和 $2。清单以意图的泛化版本形式提供，其中字面量的值替换为值的通用说明。

在此示例中，intent 中的 1950 值替换为 a given date，清单中的 Slokolov 值替换为 a given city。如果为可选实参 check_intent 提供 TRUE 值，则在 add_template 期间会执行基于 LLM 的意图验证。在此检查期间，如果提供的 SQL 语句未捕获所提供的 intent 语句的用途和目标，则 add_template 会失败，并以输出形式提供原因。

在以下示例中，模板的用途（如 intent 中所示）是检索与负载相关联且位于某个区域中的账号的账号 ID。所提供的 SQL 语句会返回账号数量，而不是账号 ID 列表，如以下示例所示。

SELECT
  alloydb_ai_nl.add_template(
    nl_config_id => 'my_app_config',
    intent => 'List the account id for all accounts that associated with loans and are located in the Prague region.',
    sql => 'SELECT COUNT(T1.account_id)
            FROM account AS T1 INNER JOIN loan AS T2
              ON T1.account_id = T2.account_id
            INNER JOIN district AS T3
              ON T1.district_id = T3.district_id
            WHERE T3."A3" = ''Prague''',
    check_intent => TRUE
  );

当 check_intent 设置为 TRUE 时，您无法将前面的模板添加到模板商店。如果您运行上述语句，系统会返回类似于以下内容的错误：

ERROR:  Checking intent failed, for nl_question:List the account id for all accounts that associated with loans and are located in the Prague region...reason:The SQL query only counts the number of account IDs, but the question asks for a list of the account IDs.

管理模板

您可以使用以下 API 管理模板商店中的模板：

-- To disable a template:
SELECT alloydb_ai_nl.disable_template(INPUT template_id);

-- To enable a template which has been disabled:
SELECT alloydb_ai_nl.enable_template(INPUT template_id);

-- To permanently remove a template:
SELECT alloydb_ai_nl.drop_template(INPUT template_id);

创建模板时，系统会默认启用此功能。已停用的模板会保留在模板存储区中，但 alloydb_ai_nl 不会使用它来合成查询。您可以使用 alloydb_ai_nl.enable_template 启用已停用的模板。运行 alloydb_ai_nl.drop_template 会从模板库中永久移除模板。

您可以根据模板的内容使用 alloydb_ai_nl.template_store_view 提取模板的 template_id。例如，如需查找具有意图 accounts that associated with loans 的模板的标识符，请运行以下查询，该查询会返回模板标识符，并标识模板是否已从 alloydb_ai_nl.template_store_view 启用：

SELECT id, enabled
FROM alloydb_ai_nl.template_store_view
WHERE intent ILIKE '%accounts that associated with loans%';

更新模板

使用 alloydb_ai_nl.template_store_view 中的模板时，请确保每个模板的意图都符合以下条件：

  • SQL 语句
  • 参数化 SQL 语句
  • 参数化 intent
  • 模板的清单

如果为模板维护的嵌入与模板内容相对应，alloydb_ai_nl 可以检索相关模板。

如需更新模板，请按以下步骤操作：

  1. 使用 alloydb_ai_nl.template_store_view 识别 template_id。
  2. 移除模板。
  3. 使用 alloydb_ai_nl.add_template 函数重新定义新模板，并进行必要的修改。

创建查询 fragment

您可以在查询时使用 fragment 来专门化模板，这有助于查询模板执行分面搜索，就像自然语言问题一样。片段是一组精选的代表性或常见自然语言条件，其中包含相应的 SQL 谓词。片段应由应用指定。

每个 fragment 都必须与一个 nl_config_id 相关联，并且与一个包含别名的表和视图数组相关联，该别名是 fragment 谓词所适用的。当实参 check_intent 设置为 TRUE 时，您可以验证 fragment 的用途。alloydb_ai_nl 扩展程序可以使用包含多个片段的模板来合成自然语言查询的答案。

alloydb_ai_nl 扩展程序使用 fragment_store 在生成 SQL 语句的过程中动态合并相关片段中的条件，以回答最终用户的问题。首先，template_store 会识别与最终用户提出的自然语言问题具有类似意图的模板。接下来，系统会检索可为已识别的模板提供专业化功能的 fragment。 参数替换会应用于模板和 fragment，以合成 SQL 语句。

参数值从自然语言问题中提取，并由 LLM 使用相关模板和片段中隐含的模式进行替换。不过，如果模板和 fragment 的组合与最终用户提出的问题没有相同的用途，alloydb_ai_nl 会使用每个相关的模板和上下文来编写 SQL 语句。

添加 fragment

如需添加 fragment，请使用 alloydb_ai_nl.add_fragment 函数运行以下示例查询。每个 fragment 都必须与应用中的 nl_config_id 标识符相关联。

-- A fragment that cannot be parameterized.
SELECT alloydb_ai_nl.add_fragment(
  nl_config_id => 'my_app_config',
  table_aliases => ARRAY['account AS T'],
  intent => 'Accounts with issuance after transaction',
  fragment => 'T.frequency = ''POPLATEK PO OBRATU''',
  check_intent => True);

-- A fragment that can be parameterized.
SELECT alloydb_ai_nl.add_fragment(
  nl_config_id => 'my_app_config',
  table_aliases => ARRAY['district AS T'],
  intent => 'Average salary between 6000 and 10000',
  fragment => 'T."A11" BETWEEN 6000 AND 10000',
  check_intent => True);

当 alloydb_ai_nl.add_fragment 运行时，alloydb_ai_nl 扩展程序会从提供的 intent 中提取清单，并尽可能对 intent 和 fragment 的条件进行参数化。可用 fragment 由 alloydb_ai_nl.fragment_store_view 等视图公开，如以下示例所示：

SELECT manifest, scope, fragment, intent, pfragment, pintent
FROM alloydb_ai_nl.fragment_store_view
WHERE intent = 'Average salary between 6000 and 10000';

该查询会返回类似于以下内容的结果集：

manifest  | Average salary between a given number and a given number
scope     | district AS T
fragment  | T."A11" BETWEEN 6000 AND 10000
intent    | Average salary between 6000 and 10000
pfragment | T."A11" BETWEEN $2 AND $1
pintent   | Average salary between $2 and $1

fragment 中的清单会自动根据 intent 生成，它表示 intent 的广义版本。例如，intent 中的数字 6000 和 10000 各自替换为清单中的 a given number。这些数字分别替换为 pfragment 和 pintent 列中的 $2 和 $1。alloydb_ai_nl.fragment_store_view 中的列 pfragment 和 pintent 分别是 fragment 和 intent 的形参化表示形式。

如需提供 fragment 的自定义形参化，请使用 alloydb_ai_nl.add_fragment 的手动版本，如以下示例所示：

SELECT alloydb_ai_nl.add_fragment(
  nl_config_id => 'my_app_config',
  table_aliases => ARRAY['bird_dev_financial.district AS T'],
  intent => $$districts in 'Prague'$$,
  parameterized_intent => $$districts in $1$$,
  fragment => $$T."A3" = 'Prague'$$,
  parameterized_fragment => $$T."A3" = $1$$,
  manifest => $$districts in a given city$$,
  check_intent => TRUE);

管理 fragment

如需管理 fragment，请使用以下 API：

-- To disable a fragment:
SELECT alloydb_ai_nl.disable_fragment(INPUT fragment_id);

-- To enable a fragment which has been disabled:
SELECT alloydb_ai_nl.enable_fragment(INPUT fragment_id);

-- To permanently remove a fragment:
SELECT alloydb_ai_nl.drop_fragment(INPUT fragment_id);

您可以使用视图 alloydb_ai_nl.fragment_store_view 根据 fragment 的内容提取其 fragment_id。例如，如需查找具有 intent Average salary between 6000 and 10000 的 fragment 的标识符，请运行以下示例查询：

SELECT id
FROM alloydb_ai_nl.fragment_store_view
WHERE intent = "Average salary between 6000 and 10000";

更新 fragment

更新 fragment 时，请确保 fragment intent 与以下内容保持一致：

  • fragment 的清单和 SQL 语句
  • 参数化 SQL 语句
  • 参数化 intent

如需在更新 fragment 时保持一致性，请按以下步骤操作：

  1. 使用 alloydb_ai_nl.drop_fragment 函数移除要修改的 fragment。
  2. 使用 alloydb_ai_nl.add_fragment 函数插入更新后的 fragment。

自动生成模板

在表中添加了代表性数据集后，我们建议您运行与最终用户可能提出的常见问题相对应的 SQL 查询。请务必确保查询具有完整的查询计划，并且查询性能良好。

运行查询后，AlloyDB AI 自然语言可以根据查询历史记录自动生成模板。您可以调用以下 API 来生成模板。您需要先查看并应用生成的模板，然后才能使其生效。

模板自动生成基于查询日志 google_db_advisor_workload_statements 中最常用的查询。查询会根据以下条件进行过滤：

  • SELECT 语句
  • 可执行文件：查询可以通过 EXPLAIN 命令成功处理。
  • 无重复：查询之前尚未用于生成模板。
  • 所有引用的表和视图都在 nl_config 的范围内。

如需自动生成、查看和应用模板，请按照以下步骤操作：

  1. 请求 AlloyDB 根据您的查询历史记录生成模板：

    SELECT
  alloydb_ai_nl.generate_templates(
    'my_app_config',
);

    使用提供的视图 alloydb_ai_nl.generated_templates_view 查看 generated_templates。

    以下输出显示了生成的模板数量：

    -[ RECORD 1 ]------+--
generate_templates | 1

  2. 使用 generated_templates_view 视图查看生成的模板。

    SELECT *
FROM alloydb_ai_nl.generated_templates_view;

    以下是返回的输出示例：

    -[ RECORD 1 ]----------------------------------------------------------------
id          | 1
config      | my_app_config
type        | Template
manifest    | How many clients have a birth year of a given number?
nl          | How many clients have a birth year of 1997?
sql         | select count(*) from public.client as T where
             to_char(T.birth_date::timestamp, 'YYYY') = '1997';
intent      | How many clients have a birth year of 1997?
psql        | select count(*) from public.client as T where
             to_char(T.birth_date::timestamp, 'YYYY') = $1;
pintent     | How many clients have a birth year of $1?
comment     |
explanation |
weight      | 1

    返回输出中的 manifest 是一个通用模板，或对问题类型或可执行的操作的宽泛描述。pintent 是 intent 的参数化版本，它通过将特定值 (1997) 替换为占位符 ($1) 来泛化 intent。

  3. 如需更新生成的模板，请运行以下示例语句：

    SELECT alloydb_ai_nl.update_generated_template(
  id => 1,
  manifest => 'How many clients are born in a given year?',
  nl => 'How many clients are born in 1997?',
  intent => 'How many clients are born in 1997?',
  pintent => 'How many clients are born in $1?'

);

  4. 应用模板。您应用的模板会立即添加到模板存储区中，并从审核视图中删除。

    -- For all templates generated under the nl config.
SELECT
  alloydb_ai_nl.apply_generated_templates('my_app_config');

为自然语言配置安全性

如需为 AlloyDB AI 自然语言配置安全性，请参阅使用参数化安全视图管理数据应用安全性。

定义概念类型和值索引

您可以定义概念类型和值索引，以更深入地了解所提出的问题。概念类型是实体的类别或类，用于标识字词和短语的语义，而不仅仅是其字面形式。

例如，即使一个国家/地区名称是大写（例如 USA），而另一个国家/地区名称是小写（例如 usa），这两个国家/地区名称也可能相同。在此示例中，国家/地区名称是概念类型。概念类型的其他示例包括人员姓名、城市名称和日期。

值索引是基于与每列关联的概念类型的、对属于自然语言配置 nl_config 的列中的值进行的索引。借助值索引，可以高效地匹配所提问题的值短语和数据库中的值。

如需定义概念类型和值索引，请使用提供的示例按照以下步骤操作。这些示例将列与概念类型关联，创建和刷新值索引，并使用同义词集执行值搜索。

  1. 如需将列与概念类型关联，请运行以下查询：

    SELECT
  alloydb_ai_nl.associate_concept_type(
    column_names_in => 'my_schema.country.country_name',
    concept_type_in => 'country_name',
    nl_config_id_in => 'my_app_config'
  );

  2. 如需根据属于自然语言配置且与概念类型关联的所有列创建值索引，请运行以下语句：

    SELECT
  alloydb_ai_nl.create_value_index(
    nl_config_id_in => 'my_app_config'
  );

  3. 将概念类型关联到新列时，刷新值索引以反映更改。

    SELECT
  alloydb_ai_nl.refresh_value_index(
    nl_config_id_in => 'my_app_config'
  );

  4. 如需让 AlloyDB AI 自然语言匹配某个值的同义词，请运行以下示例语句：

    SELECT
  alloydb_ai_nl.insert_synonym_set(
    ARRAY [
      'USA',
      'US',
      'United States',
      'United States of America'
    ]
  );

    虽然表中的数据可能会使用特定值（例如，如果 United States 用于标识国家/地区），但您可以定义一个同义词集，其中包含 United States 的所有同义词。如果自然语言问题中出现任何同义词，AlloyDB AI 自然语言会将同义词与表中的值匹配。

  5. 在给定一系列值短语的情况下，执行值搜索以查找正确的数据库值。

    SELECT
  alloydb_ai_nl.get_concept_and_value(
    value_phrases_in => ARRAY['United States'],
    nl_config_id_in  => 'my_app_config'
  );

    例如，如果用户使用以下 get_sql 查询提出“美国的人口是多少？”之类的问题，AlloyDB AI 自然语言会将 get_concept_and_value 函数与值短语 United States 结合使用，以对值索引执行模糊搜索。模糊搜索是一种搜索技术，即使搜索查询与相应数据不完全匹配，也能找到匹配项。

    自然语言会找到一个与搜索查询相近的结果（值 USA），并使用该结果生成 SQL 查询。

    SELECT
  alloydb_ai_nl.get_sql(
    nl_config_id    => 'my_app_config',
    nl_question     => 'What is the population of the United States?',
    additional_info => json_build_object('enrich_nl_question', TRUE)
  ) ->> 'sql';

    下表列出了 AlloyDB AI 自然语言定义的内置概念类型。

    概念名称 说明
    generic_entity_name 单个字符串类型列可用于通用实体名称。例如：
      SELECT alloydb_ai_nl.associate_concept_type('public.item.item_name', 'generic_entity_name')
    country_name、city_name、region_name 国家/地区、城市和区域的名称。用法与 generic_entity_name 概念类型完全相同。
    full_person_name 联系人姓名，包括名字、姓氏和中间名。最多可以使用三个字符串类型列来表示人员全名。将名称列与 full_person_name 关联时，可以跳过任意列。例如：
      SELECT alloydb_ai_nl.associate_concept_type('public.person.last_name,public.person.first_name,public.person.middle_name','full_person_name')
    ssn 包含社会保障号的单个字符串列。例如：
      SELECT alloydb_ai_nl.associate_concept_type('public.person.ssn','ssn')
    date 日期或时间戳。例如：
     SELECT alloydb_ai_nl.associate_concept_type('public.person.date_col','date')

自动生成概念类型关联

如需自动将列与概念类型相关联，请使用 AlloyDB AI Natural Language API 的自动概念类型关联功能。概念类型关联用于定义概念类型与一个或多个数据库列之间的关系，这是创建值索引的前提条件。

如需自动生成概念类型关联，请按以下步骤操作：

  1. 如需生成关联，请调用以下 API。

    -- To cover all relations within the scope of a provided nl_config.
SELECT alloydb_ai_nl.generate_concept_type_associations(
  nl_config => 'my_app_config'
);

-- To cover a specific relation.
SELECT alloydb_ai_nl.generate_concept_type_associations(
  nl_config => 'my_app_config',
  relation_name => 'my_app_table'
);

  2. 运行以下查询，查看生成的关联。

    SELECT * FROM alloydb_ai_nl.generated_value_index_columns_view;

  3. 可选：更新生成的关联。

    -- NULL means keeping the original value.
SELECT alloydb_ai_nl.update_generated_concept_type_associations(
  id => 1,
  column_names => NULL,
  concept_type => 'generic_entity_name',
  additional_info => NULL
);

  4. 可选：移除生成的关联。

    SELECT alloydb_ai_nl.drop_generated_concept_type_association(id => 1);

  5. 应用生成的关联。

    -- To apply all associations under a nl config.
SELECT alloydb_ai_nl.apply_generated_concept_type_associations(
  nl_config => 'my_app_config'
);

-- To apply a specific association by id.
SELECT alloydb_ai_nl.apply_generated_concept_type_association(
  id => 1
);

  6. 刷新值索引以反映更改。

    SELECT alloydb_ai_nl.refresh_value_index(
  nl_config_id_in => 'my_app_config'
);

通过自然语言输入生成 SQL 语句

您可以使用 AlloyDB AI 自然语言，通过自然语言输入生成 SQL 语句。当您运行生成的 SQL 语句时，它会从数据库中提供您需要的数据，来回答自然语言问题。

  1. 如需使用自然语言通过 alloydb_ai_nl.get_sql 函数从数据库中获取结果，请使用以下示例：

    SELECT
  alloydb_ai_nl.get_sql(
    'my_app_config', -- nl_config
    'What is the sum that client number 4''s account has following transaction 851?' -- nl question
  );

    系统会返回以下 JSON 输出：

    {
  "sql": "SELECT T3.balance FROM public.client AS T1 INNER JOIN public.account AS T2 ON T1.district_id = T2.district_id INNER JOIN public.trans AS T3 ON T2.account_id = T3.account_id WHERE T1.client_id = 4 AND T3.trans_id = 851",
  "prompt": "",
  "retries": 0,
  "error_msg": "",
  "nl_question": "What is the sum that client number 4's account has following transaction 851?"
}

  2. 可选：如需将生成的 SQL 查询提取为文本字符串，请添加 ->>'sql'：

    SELECT
  alloydb_ai_nl.get_sql(
    'my_app_config', -- nl_config
    'What is the sum that client number 4''s account has following transaction 851?' -- nl question
  ) ->> 'sql';

    ->> 运算符用于将 JSON 值提取为文本。alloydb_ai_nl.get_sql 函数会返回一个 JSON 对象，该对象是用于检索与键 sql 关联的值的语句的一部分。此值为生成的 SQL 查询。

根据自然语言输入生成结果摘要

您可以使用 AlloyDB AI 自然语言，通过自然语言输入生成结果摘要。alloydb_ai_nl.get_sql_summary 函数可在底层表格上安全地执行自然语言问题，总结结果集样本，并以自然语言返回摘要。

如需为数据库中的自然语言问题生成结果摘要，请使用 alloydb_ai_nl.get_sql_summary 函数，如以下示例所示：

SELECT
  alloydb_ai_nl.get_sql_summary(
    nl_config_id => 'my_app_config',
    nl_question => 'Give me the total number of accounts and the earliest opening date and other information for accounts who choose issuance after transaction are staying in east Bohemia region?');

调用上述语句会生成以下 JSON 对象示例：

{
  "answer": "The result set indicates that there are 13 accounts that chose issuance after a transaction and are located in the East Bohemia region. The earliest opening date among these accounts is August 21, 1993. Other information about these accounts is not provided in the result set."
}

您可以使用一个或多个参数化安全视图来保护 alloydb_ai_nl.get_sql_summary 中查询访问的表和视图。参数名称及其值可供应用使用，并且是 alloydb_ai_nl.get_sql_summary 所必需的。

例如，应用可能希望为用户 ID 为 123 的已通过身份验证的用户提供 user_id 参数。您可以通过提供 param_names 和 param_values 输入来实现此目的，如以下示例所示：

SELECT
  alloydb_ai_nl.get_sql_summary(
    nl_config_id => 'my_app_config',
    nl_question => 'Give me the total number of accounts and the earliest opening date and other information for accounts who choose issuance after transaction are staying in east Bohemia region?',
    param_names => ARRAY ['user_id'],
    param_values => ARRAY ['123']
);

提供 param_names 和 param_values 实参可确保，当 nl_question 可通过参数化安全视图强制执行的 SQL 语句回答时，在生成结果集和摘要时应用指定的安全过滤条件。

测试并优化

如需改进自动生成的查询，请修改或添加更完善的上下文、查询模板和值索引，然后迭代，直到获得所需的结果。

后续步骤