模型

模型为您的表提供了一个逻辑层，允许您增强其语义而不影响实际数据。通过模型，您可以仅公开您打算公开的特定数据。

定义模型

模型是您物理表的引用。Wren 引擎有一些用于描述模型的属性。通常，我们可以将模型描述为一个 JSON 对象

{
  "name": "Course",
  "properties": {},
  "refSql": "select * from \"bq-project\".spider.\"college_3-Course\"",
  "columns": [
    {
      "name": "CID",
      "type": "VARCHAR",
      "notNull": false,
      "isCalculated": false,
      "expression": "CID",
      "properties": {}
    },
    {
      "name": "CName",
      "type": "VARCHAR",
      "notNull": false,
      "isCalculated": false,
      "expression": "CName",
      "properties": {}
    }
  ],
  "primaryKey": "CID"
}

模型定义包含

引用: 指向物理表的指针。
列: 您打算公开的列列表。
属性: 用于描述模型的通用属性。

通用属性

name : 模型的名称。您将通过此名称查询模型。
primaryKey: 模型的主键。它用于关系查询。它应该是唯一的。
properties: 模型的附加描述。它用于增强 LLM 上下文的语义或可读性。它应该是字符串到字符串的键值对。

表的引用

Wren 引擎提供了 2 种引用物理表的方式。您应该选择其中一种来表示引用

refSql: 使用 SQL 查询结果作为引用。您可以在此部分操作 SQL 以获得所需的结果集。唯一需要注意的是，此处的 SQL 语法必须遵循 Wren 引擎的语法。
```
{
  "name": "CS_Course",
  "properties": {},
  "refSql": "select * from \"bq-project\".spider.\"college_3-Course\" where CName = 'CS'"
}
```
tableReference: 用于指向物理表的特定引用。
```
{
  "name": "CS_Course",
  "properties": {},
  "tableReference": {
	  "catalog": "canner-cml",
	  "schema": "spider",
	  "table": "college_3-Course"
  }
}
```
- 在某些数据库中，使用 tableReference 更利于查询优化。我们将在模型如何工作中讨论这一点。

列

定义引用后，需要为模型分配列。一个模型必须至少包含一列。这些列是可以在模型中操作的组件。

使用 columns 属性构建列列表。

{
    "name": "Course",
    "properties": {},
    "refSql": "select * from \"bq-project\".spider.\"college_3-Course\"",
    "columns": [
        {
            "name": "Course_ID",
            "type": "VARCHAR",
            "notNull": false,
            "expression": "CID",
            "properties": {}
        },
        {
            "name": "CName",
            "type": "VARCHAR",
            "notNull": false,
            "expression": "CName",
            "properties": {}
        }
    ]
}

如上面的示例所示，每列都有许多属性来定义其特性。

列属性

您可以使用一些属性来描述一列

name : 列的名称。如果未设置 expression，则 column 应该是引用物理表中的一列。
type : 列的数据类型。Wren 引擎遵循 Postgres 类型。更多信息请参见字段和类型。
notNull: 表示列是否可为空。
expression: 您可以使用 SQL 表达式表示一列。有时，原始名称在语义上没有意义。您可以使用 expression 引用它，并相应地通过 name 重命名该列。如果设置了 expression，则 name 将成为此列的别名。
- 关于表达式的访问范围，它只能访问引用物理表的列。
properties: 与模型的属性相同。

列有两种变体，可以通过设置特定属性来使用。

关系字段
计算字段

它们都与 Wren 引擎中的一个关键概念 Relationship 相关。我们将在关系中讨论它们。

查询模型

定义建模定义语言（MDL）时，需要为其设置 catalog 和 schema。例如

{
    "catalog": "my_catalog",
    "schema": "my_schema",
    "models": [
        {
            "name": "Course",
            "properties": {},
            "refSql": "select * from \"bq-project\".spider.\"college_3-Course\"",
            "columns": [
            {
                "name": "Course_ID",
                "type": "VARCHAR",
                "notNull": false,
                "expression": "CID",
                "properties": {}
            },
            {
                "name": "CName",
                "type": "VARCHAR",
                "notNull": false,
                "expression": "CName",
                "properties": {}
            }
            ]
        }
    ]
}

所有数据集（模型、指标或视图等）都将放在搜索路径 my_catalog.my_schema 中。然后，我们可以使用 Wren 引擎 SQL 查询已定义的模型

SELECT Course_ID FROM my_catalog.my_schema.Course

您可以像查询传统 RDBMS 一样查询它们。然后 Wren 引擎会将您的 SQL 转换为特定数据源的可执行 SQL。

模型如何工作

Wren 引擎有一个语句分析机制来确定运行时需要哪些数据集。基本上，如果您查询了如下 SQL

SELECT Course_ID FROM my_catalog.my_schema.Course

Wren 引擎会将 SQL 翻译为

WITH Course as (
    SELECT
        CID as Course_ID,
        CName
    FROM
        (
            select * from "bq-project".spider."college_3-Course"
        )
)
SELECT Course_ID FROM Course

您可以看到 CTE 的列是您在模型中设置的。

TableReference 和 RefSql

如示例所示，您可能会注意到子查询是在 refSql 中定义的。Wren 引擎如何访问您的数据源取决于您的设置。大多数情况下，人们更喜欢从物理表中选择所有列。然而，这种方法并不总是利于 SQL 优化。理想情况下，SQL 引擎应根据您在运行时的使用情况执行列投影。不幸的是，我们无法保证所有数据源都能有效地处理这个问题。这就是为什么我们提供 tableReference 作为引用的替代选项。

让我们看看 tableReference 如何工作。给定如下 MDL

{
	"catalog": "my_catalog",
	"schema": "my_schema",
	"models": [
		{
		  "name": "Course",
		  "tableReference": {
			  "catalog": "canner-cml",
			  "schema": "spider",
			  "table": "college_3-Course"
		  },
		  "columns": [
		    {
		      "name": "Course_ID",
		      "type": "VARCHAR",
		      "expression": "CID",
		    },
		    {
		      "name": "CName",
		      "type": "VARCHAR",
		      "expression": "CName",
		    }
		  ]
		}
	]
}

如果我们提交相同的 SQL

SELECT Course_ID FROM my_catalog.my_schema.Course

Wren 引擎会将其翻译为

WITH Course as (
    SELECT
        CID as Course_ID,
        CName
    FROM
        "bq-project".spider."college_3-Course"

)
SELECT Course_ID FROM Course

此 CTE 作为任何数据源的显式投影，减轻了对数据源端 SQL 优化问题的担忧。如果您不需要在 refSql 中执行任何特殊操作，建议考虑改用 tableReference。

定义模型​

通用属性​

表的引用​

列​

列属性​

查询模型​

模型如何工作​

TableReference 和 RefSql​