请注意，您正在查看 Looker 文档。如需查看 Looker Studio 文档，请访问 https://support.google.com/looker-studio。

此页面由 Cloud Translation API 翻译。

开放的 SQL 接口

借助 Looker LookML 语义建模层，数据分析师能够定义 SQL 数据库中的维度、聚合、计算和数据关系。LookML 模型可提供代码可重用性和 Git 集成。结构合理的 LookML 模型可让用户自助探索和报告数据。

LookML 模型是 Looker 所请求任何数据的基础，无论该请求来自 Looker 界面中的 Looker 探索界面、公司门户中的嵌入式可视化内容或其他第三方应用，还是使用 Looker API 开发的自定义应用。开放 SQL 接口可让任何支持 Java 数据库连接 (JDBC) 的第三方应用访问 LookML 模型。应用可以连接到 LookML 模型，就像它是一个数据库一样，这使用户可以在 LookML 模型中利用数据分析师完成的所有工作，同时使用他们最熟悉的任何工具。

Open SQL 接口如何显示 LookML 项目元素

如需了解 Open SQL 接口如何呈现 LookML 项目的元素，请务必了解 LookML 项目的结构。

LookML 项目是一组文件，用于描述用于在 Looker 中执行 SQL 查询的对象、数据库连接和用户界面元素（如需了解详情，请参阅 LookML 术语和概念）。以下 LookML 项目概念与开放式 SQL 接口相关：

LookML model会指定数据库连接以及一个或多个探索。开放式 SQL 接口将模型显示为数据库架构。
探索是一个或多个视图的逻辑分组，以及这些视图之间的联接关系。开放式 SQL 接口将“探索”显示为数据库表。
视图定义了一组字段（维度和测量）。视图通常基于数据库中的表或派生表。视图可以包含底层数据库表中的列，以及最终用户可能需要的任何自定义维度或测量。Open SQL 接口将视图名称和字段名称的组合显示为“数据库列名称”。例如，order_items 视图中的 id 维度在 Open SQL 接口中显示为名为 order_items.id 的数据库列。

Looker 探索可以定义多个视图之间的联接关系。由于一个视图的字段可能与另一个视图中的字段同名，因此 Open SQL 接口在引用列时同时包含视图名称和字段名称。因此，在将查询发送到 Open SQL 接口时，请使用以下格式来引用列名称：

`<view_name>.<field_name>`

例如，如果有一个名为 order_items 的探索将一个名为 customer 的视图与一个名为 product 的视图联接，并且这两个视图都有 id 维度，您会分别以 `customer.id` 和 `product.id` 引用这两个 id 字段。如果还要将完全限定名称与“Explore”名称一起使用，则需要引用 `order_items`.`customer.id` 和 `order_items`.`product.id` 这两个字段。（如需了解在引用数据库标识符时将反引号置于何处，请参阅在数据库标识符周围使用反引号。）

设置 Open SQL 接口

如需使用 Open SQL 接口，请执行以下步骤：

验证是否满足要求。
在 Looker 实例上启用 Open SQL 接口。
下载 Open SQL Interface JDBC 驱动程序文件。

以下部分介绍了这些步骤。

使用要求

使用 Open SQL 接口需要以下组件：

一个 Looker 托管且运行 Looker 23.18 或更高版本的 Looker 实例。
使用来自 Google BigQuery 连接的数据的 LookML 项目。（LookML 项目必须具有一个model文件，用于在其 connection 参数中指定 Google BigQuery 连接）。
Looker 用户角色，对您希望通过 Open SQL 界面访问的 LookML 模型拥有 explore 权限。

在 Looker 实例上启用 Open SQL 接口

通过执行以下步骤，在您的实例上启用开放式 SQL 接口：

对于 Looker（原始版本）实例，请在 Looker 实例上启用 SQL 接口实验性实验室功能。
对于 Looker (Google Cloud Core) 实例，请填写 Looker SQL 接口非正式版协议意向调查表。Google 团队将为您的实例启用开放式 SQL 接口功能。

下载 Open SQL Interface JDBC 驱动程序

Looker Open SQL Interface JDBC 驱动程序称为 avatica-<release_number>-looker.jar。访问 https://github.com/looker-open-source/calcite-avatica/releases，从 GitHub 下载最新版本。

JDBC 驱动程序需要以下网址格式：

jdbc:looker:url=https://your Looker instance URL

例如：

jdbc:looker:url=https://myInstance.cloud.looker.com

JDBC 驱动程序类如下：

org.apache.calcite.avatica.remote.looker.LookerDriver

在 Open SQL 接口进行身份验证

开放 SQL 接口支持三种身份验证方法：

OAuth
使用 API 密钥生成访问令牌
API 密钥

OAuth

可以将支持 OAuth 的 JDBC 客户端配置为使用 Looker 实例的 OAuth 服务器。请按照以下步骤配置 OAuth 身份验证：

使用 API Explorer 扩展程序向 Looker 实例注册 JDBC OAuth 客户端，以便 Looker 实例能够识别 OAuth 请求。有关说明，请参阅注册 OAuth 客户端应用。
使用 OAuth 登录 Looker 以请求访问令牌。如需查看示例，请参阅使用 OAuth 执行用户登录。
打开与 Open SQL 接口的 JDBC 连接时，使用属性对象传递 OAuth 凭据。

以下是使用 DriverManager#getConnection(<String>, <Properties>`) 的示例：

String access_token = getAccessToken() //uses the Looker OAuth flow to get a token
String URL = "jdbc:looker:url=https://myInstance.cloud.looker.com"
Properties info = new Properties( );
info.put("token", access_token);
Connection conn = DriverManager.getConnection(URL, info);

使用 API 密钥生成访问令牌

您可以按照以下步骤，使用 Looker API 生成可传递给 Open SQL Interface JDBC 驱动程序的访问令牌，而不是使用标准 OAuth 流程生成访问令牌：

按照管理员设置 - 用户页面中的说明，为您的 Looker 用户生成 API 密钥。
使用 Looker 实例的 login API 端点。响应包含一个格式为 Authorization: token <access_token> 的访问令牌。以下是发出此请求的 curl 命令示例：
```
  curl -k -d "client_id=<client_id>&client_secret=<client_secret>" https://<looker_host>/login\
```
将响应的 <access_token> 值作为令牌传递给 Properties 对象，以便在打开与 Open SQL 接口的 JDBC 连接时传递 OAuth 凭据。

API 密钥

您还可以使用 API 密钥代替用户名和密码进行身份验证。API 密钥被视为的安全性低于 OAuth，并且可能仅在 Open SQL 接口预览版期间可用。如需了解如何为 Looker 实例创建 API 密钥，请参阅 API 密钥。

使用 Looker API 密钥的客户端 ID 部分作为用户名。使用客户端密钥部分作为密码。

使用 SQL 开放式界面运行查询

使用开放 SQL 接口运行查询时，请注意以下准则：

开放式 SQL 接口接受遵循 GoogleSQL 语法的 SQL 查询。
Open SQL 接口需要在模型、Explore 和字段标识符前后加上反引号 (`)。如需了解详情和示例，请参阅在数据库标识符两边使用反引号。
开放式 SQL 接口支持大多数 BigQuery 运算符。如果您需要使用不受支持的运算符，请向 looker-sql-interface@google.com 发送电子邮件请求。
对于 Open SQL 接口，您必须通过将测量值（包括反引号）封装在特殊函数 AGGREGATE() 中，以指定查询中包含的任何 LookML 测量结果。请参阅使用 AGGREGATE() 指定 LookML 措施部分。

LookML 限制

将查询发送到 Open SQL 接口时，请注意以下 LookML 限制：

Open SQL 接口仅支持 Looker 维度和测量。开放式 SQL 接口不支持 LookML 参数 filter 或 parameter。
Open SQL 接口不能用于替换 LookML 模型中定义的 always_filter 和 conditionally_filter 的值。

SQL 限制

将查询发送到 Open SQL 接口时，请注意以下 SQL 限制：

开放式 SQL 接口仅支持 SELECT 查询。Open SQL 接口不支持 UPDATE 和 DELETE 语句，也不支持任何其他数据定义语言 (DDL)、数据操纵语言 (DML) 或数据控制语言 (DCL) 语句。
开放式 SQL 接口不支持 JOIN 运算符。
- 您不能将包含 JOIN 运算符的查询发送到 Open SQL 接口，以在同一探索内或两个不同的探索之间创建联接。
- 如果要在数据库中的两个表之间创建联接，可以在 LookML 模型中通过在 LookML 项目的模型文件内的探索定义中创建与一个或多个视图的联接来实现此目的。
Open SQL 接口不支持窗口函数调用。
Open SQL 接口不支持子查询。
Open SQL 接口不支持时区转换。LookML 模型中的日期时间的 DATETIME 类型采用您的设置（用户时区、应用时区或数据库时区设置）中指定的时区。
Open SQL 接口不支持 BigQuery 数据类型地理位置、JSON 和时间。

在数据库标识符前后使用反引号

将查询发送到 Open SQL 接口时，对架构、表和列标识符使用反引号。以下是使用反引号和 Looker 术语来指定数据库元素的方法：

schema：`<model_name>`
表格：`<explore_name>`
列：`<view_name>.<field_name>`

注意：<view_name> 和 <field_name> 元素合并在一组反引号内。

以下是使用这些元素的 SELECT 语句格式示例：

SELECT `view.field`
  FROM `model`.`explore`
  LIMIT 10;

使用 `AGGREGATE()` 指定 LookML 测量

数据库表通常只包含维度，即描述表中行的单个属性的数据。不过，LookML 项目可以定义维度和测量指标。测量是跨多个行的数据汇总，例如 SUM、AVG、MIN 或 MAX。（还支持其他类型的测量，如需查看受支持的 LookML 测量类型的完整列表，请参阅测量类型页面。）

对于 Open SQL 接口，您必须通过将测量值（包括反引号）封装在特殊函数 AGGREGATE() 中，以指定查询中包含的任何 LookML 测量结果。例如，可以使用以下代码指定 orders 视图中的 count 衡量：

AGGREGATE(`orders.count`)

无论测量是在 SELECT 子句、HAVING 子句还是 ORDER BY 子句中，都必须将 LookML 测量封装在 AGGREGATE() 函数中。

如果您不确定某个字段是否为 LookML 测量，可以使用 DatabaseMetaData.getColumns 方法访问 LookML 项目的元数据。对于任何 LookML 度量，IS_GENERATEDCOLUMN 列将指示 YES；对于 LookML 维度，此列将指示 NO。如需了解详情，请参阅访问数据库元数据部分。

示例

下面是一个同时使用维度和测量的示例查询。此查询会从 customers 视图中检索 state 和 city 维度，并从 orders 视图中检索 total amount。在电子商务模型中，这两个视图都会合并到 orders 探索中。对于订单数超过 10 的城市，此查询响应会显示订单金额排名前 5 的城市：

SELECT `customers.state`, `customers.city`,
  AGGREGATE(`orders.total_amount`)
FROM `ecommerce`.`orders`
GROUP BY `customers.state`, `customers.city`
HAVING AGGREGATE(`orders.count`) > 10
ORDER BY 3 DESC LIMIT 5;

使用 `JSON_OBJECT` 指定仅限过滤条件的字段和参数

开放式 SQL 接口支持参数和仅限过滤条件的字段。

使用 Open SQL 接口运行查询时，您可以通过添加具有以下格式的 JSON_OBJECT 构造函数调用，将参数和仅限过滤条件的字段应用于查询：

JSON_OBJECT(
    '<view>.<parameter name>', '<parameter value>',
    '<view>.<filter name>', '<Looker filter expression>'
)

JSON 对象可以包含零个或多个过滤条件键值对，以及零个或多个参数键值对。

JSON_OBJECT 构造函数中的键必须是仅限过滤条件的字段或参数的名称。
对于仅限过滤条件的字段，每个键的值都必须是 Looker 字符串过滤条件表达式。
对于参数，每个键的值必须是 parameter 定义中定义的普通值。

如需查看如何在开放式 SQL 接口中使用参数和仅限过滤条件的字段的示例，请参阅以下部分。

参数示例

例如，使用带有 Open SQL 接口的 parameter 示例，如果 customers 视图在 Looker 中定义了一个参数，如下所示：

parameter: segment {
  type: string
  allowed_value: {
    label: "Small (less than 500)"
    value: "small_customers"
  }
  allowed_value: {
    label: "Larger (greater than 10,000)"
    value: "large_customers"
  }
  allowed_value: {
    label: "Medium customers (Between 500 and 10,000)"
    value: "medium_customers"
  }
}

您可以将此查询发送到 Open SQL 接口，以将 medium_customers 的 segment 参数值应用于该查询：

SELECT `customers.segment_size`,
  AGGREGATE(`orders.total_amount`)
FROM `ecommerce`.`orders`(JSON_OBJECT(
    'customers.segment', 'medium_customers'
))
GROUP BY `customers.state`, `customers.city`
HAVING AGGREGATE(`orders.count`) > 10
ORDER BY 3 DESC LIMIT 5;

开放式 SQL 接口会将此参数值传递给 Looker 中的查询，Looker 会将 medium_customers 值应用于“探索”中配置为使用 segment 参数的所有字段。如需了解参数在 Looker 中的工作原理，请参阅 parameter 文档。

仅过滤条件字段示例

您可以通过开放式 SQL 接口使用 filter 字段。例如，如果 products 视图在 Looker 中有一个维度和一个仅限过滤条件的字段，如下所示：

filter: brand_select {
  type: string
  }

dimension: brand_comparitor {
  sql:
    CASE
      WHEN {% condition brand_select %} ${products.brand_name} {% endcondition %}
      THEN ${products.brand_name}
      ELSE "All Other Brands"
    END ;;
    }

您可以通过发送如下所示的查询，将 brand_select 过滤条件与 Open SQL 接口结合使用：

SELECT `products.brand_comparator`, `products.number_of_brands`,
  AGGREGATE(`products.total_revenue`)
FROM `ecommerce`.`orders`(JSON_OBJECT(
    'products.brand_select', '%Santa Cruz%'
))
GROUP BY `products.brand_comparator`
ORDER BY 3 DESC LIMIT 5;

打开 SQL 接口会将 Looker 字符串过滤条件表达式 %Santa Cruz% 应用于 Looker 中的查询。如需了解 Looker 中仅限过滤条件的字段的工作原理，请参阅 filter 文档。

访问数据库元数据

开放 SQL 接口支持标准 JDBC DatabaseMetaData 接口的一部分，该接口用于获取有关底层数据库的信息。您可以使用 DatabaseMetaData 接口的以下方法获取有关 LookML 模型的信息：

DatabaseMetadata.getSchemas
DatabaseMetaData.getTables
DatabaseMetaData.getColumns

注意：开放式 SQL 接口只会返回用户有权访问的模型、探索和字段的结果。

DatabaseMetadata.getSchemas

下表描述了在 DatabaseMetadata.getSchemas 接口方法的响应中，LookML 模型与标准数据库结构之间的关系。

“`getSchemas`”回答列	说明
`TABLE_SCHEM`	LookML 模型名称
`TABLE_CATALOG`	(null)

DatabaseMetadata.getTables

下表描述了在 DatabaseMetaData.getTables 接口方法的响应中，LookML 模型与数据库结构之间的关系。响应包含标准 JDBC 元数据和 Looker 专用元数据：

“`getTables`”回答列	说明
JDBC 标准元数据
`TABLE_CAT`	(null)
`TABLE_SCHEM`	LookML 模型名称
`TABLE_NAME`	LookML 探索名称
`TABLE_TYPE`	始终返回值 `TABLE_TYPE`
Looker 专用元数据
`DESCRIPTION`	浏览说明
`LABEL`	探索 label
`TAGS`	探索代码

DatabaseMetadata.getColumns

下表描述了在 DatabaseMetaData.getColumns 接口方法的响应中，LookML 模型与数据库结构之间的关系。响应包含标准 JDBC 元数据和 Looker 专用元数据：

“`getColumns`”回答列	说明
JDBC 标准元数据
`TABLE_CAT`	(null)
`TABLE_SCHEM`	LookML 模型名称
`TABLE_NAME`	LookML 探索名称
`COLUMN_NAME`	采用 `<view_name>.<field_name>` 格式的 LookML 字段名称。例如 `orders.amount`。
`DATA_TYPE`	列的 `java.sql.Types` 代码。例如，Looker `yesno` 字段是 SQL 类型代码 `16` (BOOLEAN)。
`ORDINAL_POSITION`	探索中字段的从 1 开始的序数（按视图名称和字段名称的字母顺序混合维度和测量值）
`IS_NULLABLE`	始终返回值 `YES`
`IS_GENERATEDCOLUMN`	`YES` 表示测量，`NO` 表示尺寸
Looker 专用的元数据
`DIMENSION_GROUP`	维度组的名称（如果该字段是维度组的一部分）。如果该字段不属于维度组，则此值为 null。
`DRILL_FIELDS`	为维度或测量设置的深入分析字段列表（如果有）
`FIELD_ALIAS`	字段的别名（如果有）
`FIELD_CATEGORY`	该字段是 `dimension` 还是 `measure`
`FIELD_DESCRIPTION`	字段 description
`FIELD_GROUP_VARIANT`	如果该字段显示在字段组标签下，则 `FIELD_GROUP_VARIANT` 将指定显示在组标签下的字段的较短名称。
`FIELD_LABEL`	字段 label
`FIELD_NAME`	维度或测量的名称
`HIDDEN`	相应字段是否在“探索”工具 (`TRUE`) 的字段选择器中隐藏，或者该字段是否显示在“探索”工具中的字段选择器 (`FALSE`)。
`LOOKER_TYPE`	维度或衡量的 LookML 字段类型
`REQUIRES_REFRESH_ON_SORT`	是否必须刷新 SQL 查询才能对字段的值重新排序 (`TRUE`)，还是可以对字段的值重新排序，而无需刷新 SQL 查询 (`FALSE`)。
`SORTABLE`	字段可排序 (`TRUE`) 还是不可排序 (`FALSE`)
`TAGS`	字段标记
`USE_STRICT_VALUE_FORMAT`	字段是否使用严格值格式 (`TRUE`) 或不使用 (`FALSE`)
`VALUE_FORMAT`	字段的值格式字符串
`VIEW_LABEL`	字段的查看标签
`VIEW_NAME`	在 LookML 项目中定义字段的视图的名称

识别 Looker 界面中的 Open SQL 接口查询

Looker 管理员可以使用 Looker 界面确定哪些查询来自 Open SQL 界面：

在查询管理页面中，来自 Open SQL 界面的查询的来源值为“SQL 接口”。用户值将显示运行查询的 Looker 用户的名称。
在系统活动历史记录探索中，来自 Open SQL 接口的查询的源值为“sql_interface”。用户电子邮件地址值将显示运行查询的 Looker 用户的电子邮件地址。您只需在此网址的开头处插入 Looker 实例地址，即可直接转到根据“sql_interface”过滤的历史记录探索：
```
https://your Looker instance URL/explore/system__activity/history?fields=history.source,history.completed_date&f[history.source]=sql_interface
```

对 Open SQL 接口的反馈

如果您对开放式 SQL 接口有任何疑问或功能请求，请发送电子邮件至 looker-sql-interface@google.com。