Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

创建和管理参数化视图

您可以基于 Bigtable 中的逻辑视图创建参数化视图，然后对参数化视图执行操作。

在阅读本页内容之前，请先熟悉参数化视图概览。

准备工作

如果您计划使用 Google Cloud CLI，请按以下步骤操作：

安装 Google Cloud CLI。

注意：如果您之前安装了 gcloud CLI，请确保通过运行 gcloud components update 来获得最新版本。
配置 gcloud CLI 以使用您的联合身份。

如需了解详情，请参阅使用联合身份登录 gcloud CLI。
如需初始化 gcloud CLI，请运行以下命令：
```
gcloud init
```

所需的角色

如需获得创建和管理参数化视图所需的权限，请让您的管理员为您授予实例的 Bigtable Admin (roles/bigtable.admin) 角色。

或者，您可以在实例级层请求以下权限：

创建：bigtable.logicalViews.create
更新：bigtable.logicalViews.update
删除：bigtable.logicalViews.delete
列表：bigtable.logicalViews.list

如需创建参数化视图，您还必须至少拥有源表的 bigtable.tables.readRows 权限。

创建参数化视图

参数化视图是由 SQL SELECT 语句定义的虚拟表，该语句可以包含 VIEW_PARAMETERS() 函数。

控制台

在 Google Cloud 控制台中，打开 Bigtable 实例列表。

打开实例列表
从列表中选择一个实例。
在导航窗格中，点击 Bigtable Studio。
点击 “新标签页”菜单，然后选择编辑器，以打开新标签页。
在查询编辑器中，编写 SQL 查询。查询定义必须调用 VIEW_PARAMETERS() 函数来指定一个或多个视图参数。例如：
```
SELECT *
FROM TABLE_ID
WHERE STARTS_WITH(_key, CAST(VIEW_PARAMETERS('PARAM_NAME') AS BYTES))
```
替换以下内容：
- TABLE_ID：源表的 ID。
- PARAM_NAME：视图参数的名称（用英文单引号括起来），作为实参传递给 VIEW_PARAMETERS() 函数。此属性定义的是参数名称，而不是其运行时值。您可以在查询参数化视图时提供运行时值。
如果查询是有效的 SQL，则会显示“有效”消息。
可选：如需以 SQL 样式设置语句的格式，请点击格式化。
点击保存，然后选择另存为逻辑视图。
在保存逻辑视图对话框中，为视图输入一个名称，然后点击保存。

该视图会显示在探索器窗格的逻辑视图列表中，并带有variable_add形参化视图图标。

如需详细了解如何使用查询编辑器，请参阅使用 Bigtable Studio 管理数据。

gcloud

如需创建参数化视图，请使用 gcloud bigtable logical-views create 命令。

gcloud bigtable logical-views create VIEW \
  --instance=INSTANCE \
  --query="SELECT * FROM TABLE_ID WHERE STARTS_WITH(_key, CAST(VIEW_PARAMETERS('PARAM_NAME') AS BYTES))"

替换以下内容：

VIEW：新参数化视图的 ID，长度上限为 128 个字符。该 ID 在实例中的所有表 ID 和视图 ID 中必须是唯一的。
INSTANCE：要在其中创建参数化视图的实例的 ID。
TABLE_ID：源表的 ID。
PARAM_NAME：视图参数的名称（用英文单引号括起来），作为实参传递给 VIEW_PARAMETERS() 函数。这定义了形参名称，而不是其运行时值。您可以在查询参数化视图时提供运行时值。

可选：

如需防止参数化视图被删除，请在命令中附加 --deletion-protection 标志。如果您未应用此设置，则可以删除视图。您还可以通过附加 --no-deletion-protection 来明确允许删除视图。如需了解详情，请参阅本文档的更新参数化视图部分。

创建具有结构化行键的参数化视图

如果您的表使用结构化行键，则可以按行键的特定段进行过滤。如需了解详情，请参阅管理行键架构。

例如，如果交易记录表中的行键存储了用户、购买日期的时间戳和订单 ID（以 # 符号分隔），您可以按如下方式指定行架构：

field {
    field_name: "user_id"
    type: { bytesType { encoding { raw {} } } }
  }
  field {
    field_name: "reversed_timestamp"
    type: { timestampType { encoding { unixMicrosInt64 { encoding: {           orderedCodeBytes: {} } } } } }
  }
  field {
    field_name: "order_id"
    type: { stringType { encoding { utf8Bytes {} } } }
  }
  encoding {
    delimitedBytes { delimiter "#" }
  }

然后，您可以创建一个按用户 ID 字段进行过滤的数据视图：

控制台

在 Bigtable Studio 中，打开查询编辑器并输入按行键段进行过滤的 SQL 查询：
```
SELECT *
FROM TABLE_ID
WHERE user_id = CAST(VIEW_PARAMETERS('user_id') AS BYTES)
```
将 TABLE_ID 替换为源表的 ID。
点击保存，然后选择另存为逻辑视图。
在保存逻辑视图对话框中，为视图输入一个名称，然后点击保存。

该视图会显示在探索器窗格的逻辑视图列表中，并带有 variable_add 参数化视图图标。

gcloud

如需创建具有结构化行键的参数化视图，请使用 gcloud bigtable logical-views create 命令。

gcloud bigtable logical-views create VIEW \
    --instance=INSTANCE \
    --query="SELECT * FROM TABLE_ID WHERE user_id = CAST(VIEW_PARAMETERS('user_id') AS BYTES)"

替换以下内容：

VIEW：新参数化视图的 ID，长度上限为 128 个字符。该 ID 在实例中的所有表 ID 和视图 ID 中必须是唯一的。
INSTANCE：要在其中创建参数化视图的实例的 ID。
TABLE_ID：源表的 ID。

更新参数化视图

您可以通过与更新逻辑视图相同的方式更新参数化视图。

删除参数化视图

您可以通过与删除逻辑视图相同的方式删除参数化视图。

查看有关参数化视图的信息

您可以通过与查看实例的逻辑视图列表相同的方式查看参数化视图列表。

控制台

在 Google Cloud 控制台中，打开 Bigtable 实例列表。

打开实例列表
从列表中选择一个实例。
在导航窗格中，点击 Bigtable Studio。
在探索器窗格中，展开逻辑视图。

参数化视图会显示在列表中，并带有 variable_add 参数化视图图标，以便与标准逻辑视图区分开来。
如果实例的观看次数超过 10 次，请点击显示更多以加载接下来的 10 次观看。

gcloud

如需查看实例的逻辑视图列表，请使用 gcloud bigtable logical-views list 命令。

gcloud bigtable logical-views list --instance=INSTANCE

将 INSTANCE 替换为实例 ID。

查询参数化视图

您可以通过与查询常规表类似的方式查询参数化视图，但需要在请求中提供 view_parameters 映射。

控制台

在 Google Cloud 控制台中，打开 Bigtable 实例列表。

打开实例列表
从列表中选择一个实例。
在导航窗格中，点击 Bigtable Studio。
在探索器窗格中，展开逻辑视图。
在要查询的参数化视图旁边，点击 more_vert 查看操作菜单，然后点击查询视图。

系统会打开“参数”窗格，其中预先填充了视图参数名称。
在查看参数中，在值字段中输入每个必需参数的运行时值。

参数值以字符串形式传递。如果视图定义中的某个形参被强制转换为其他类型（例如整数或字节），请输入原始字符串值。
可选：如需添加更多参数，请点击添加参数，然后输入参数名称和值。参数名称在视图参数中必须是唯一的。
点击保存。
在查询编辑器中，点击运行。

查询结果会显示在结果表中。

如果您在未提供必需的视图参数的情况下运行查询，则结果部分会显示一条错误消息，其中包含修改参数按钮。点击修改参数以打开参数窗格，然后输入缺少的参数值。

为每个查询编辑器标签页配置参数值。如果您在会话期间离开 Bigtable Studio，然后返回，则系统会保留您打开的标签页、查询、结果和配置的参数。

Java

以下示例展示了如何查询名为 purchase_history_pv 的参数化视图，该视图会根据用户 ID 过滤数据：

// Assumes 'purchase_history_pv' was created with the definition:
// SELECT * FROM purchases WHERE user_id = CAST(VIEW_PARAMETERS('user_id') AS BYTES)

String query = "SELECT customer_info[email], order_details[status], order_info[items] from purchase_history_pv";
PreparedStatement preparedStatement = dataClient.prepareStatement(query);
BoundStatement boundStatement = preparedStatement.bind().build();

// The user ID is now passed out-of-band in a view parameters map.
Map<String, Value> viewParameters = new HashMap<>();
viewParameters.put("user_id", Value.newBuilder().setType(stringType()).setStringValue(userId).build());

// Execute the query, passing the view parameters using a proto field in the request.
ResultSet rs = dataClient.executeQuery(
    boundStatement,
    viewParameters
);

这样可防止用户在查询本身中看到或操纵 user_id 参数，从而实现清晰的逻辑分离。

后续步骤

在智能体应用中使用参数化视图