C++ 语言集成查询

语言集成查询（WCDB Integrated Language Query，简称 WINQ），是 WCDB 的一项基础特性。它使得开发者能够通过 C++ 的语法特性去完成 SQL 语句。

WCDB::OptionalValueArray<Sample> objects = database.getAllObjects<Sample>("sampleTable", WCDB_FIELD(Sample::identifier) > 1);

其中第二个参数 WCDB_FIELD(Sample::identifier) > 1 就是语言集成查询的其中一个写法。其虽然是 identifier 和数字 1 的比较，但其结果并不为 Bool 值，而是 WCDB::Expression。该 WCDB::Expression 作为 SQL 的 where 参数，用于数据库查询。

语言集成查询基于 SQLite 的 SQL 语法实现。只要是 SQL 支持的语句，都能使用语言集成查询完成。也因此，语言集成查询具有和 SQL 语法一样的复杂性，本文不可能将所有涉及的接口和类都介绍一遍。而是结合 WCDB，介绍常用的类型，并在最后说明如何将已有 SQL 转换为语言集成查询的写法。

Column

Column 代表数据库内的一个字段，如 Insert 语句中的 column-name，指定了需要插入的数据所属的字段。它可通过字段名创建。

WCDB::Column identifierColumm = WCDB::Column("identifier");
WCDB::StatementInsert insert = WCDB::StatementInsert()
    .insertIntoTable("sampleTable")
    .column(identifierColumm).value(1);
printf("%s", insert.getDescription().data()); // 输出 "INSERT INTO sampleTable(identifier) VALUES(1)"

ResultColumn

ResultColumn 通常代表数据库查询中的结果，如 Select 语句中的 result-column，指定了期望查询的结果。

WCDB::Column identifierColumm = WCDB::Column("identifier");
WCDB::ResultColumn identifierResultColumm = WCDB::ResultColumn(identifierColumm);
WCDB::StatementSelect select = 
    WCDB::StatementSelect().select(identifierResultColumm).from("sampleTable");
printf("%s", select.getDescription().data()); // 输出 "SELECT identifier FROM sampleTable"

Convertible

细心观察语法中的描述可以发现，许多节点的参数可以不止一种。以刚才提到的 ResultColumn 为例。

WINQ-Column-Result

可以看到，Expression 也可以转换为 ResultColumn。

我们再回到 StatementSelect 语句的 select 函数，倘若它只接受 ResultColumn 类作为参数，那么每次调用时，都需要将 Expression 转换为 ResultColumn。

// 以下为示例代码，并非 WCDB 真正的实现
class StatementSelect {
    StatementSelect& select(const ResultColumns& resultColumns);
    // ...
}

WCDB::Column identifierColumm = WCDB::Column("identifier");
WCDB::Expression identifierExpression = WCDB::Expression(identifierColumm);
WCDB::ResultColumn identifierResultColumm = WCDB::ResultColumn(identifierExpression);
WCDB::StatementSelect select = 
    WCDB::StatementSelect().select(identifierResultColumm).from("sampleTable");
printf("%s", select.getDescription().data()); // 输出 "SELECT identifier FROM sampleTable"

可以看到，需要 3 重转换，才能将 Column 转换为我们需要的 ResultColumn。

为了解决这个问题，WCDB 根据 C++ 的 SFINEA 机制，定义了一系列 Convertible 类，用于语法中可互相转换的类型。下面给出ResultColumnConvertible的代码示例

template<typename T, typename Enable = void>
class ResultColumnConvertible final : public std::false_type {
public:
    static ResultColumn asResultColumn(const T&);
};

template<>
class ResultColumnConvertible<Expression> final : public std::true_type {
public:
    static ResultColumn asResultColumn(const Expression& expression);
};

class ResultColumn {
    template<typename T,
             typename Enable = typename std::enable_if<ResultColumnConvertible<T>::value>::type>
    ResultColumn(const T& t)
    : ResultColumn(ResultColumnConvertible<T>::asResultColumn(t))
    {
    }
}

基于 Convertible 类，select 接口的参数虽然限定为 ResultColumns，但所有实现了 ResultColumnConvertible 的类型，都能作为 select 函数的参数。

在 SQL 语法中，Expression 是能转换为 ResultColumn 的类型；而 Column 是能转换为 Expression 的类型，因此其也同时是能转换为 ResultColumn 的类型。

// WCDB 内部的代码示例
template<>
class ExpressionConvertible<Column> final : public std::true_type {
public:
    static Expression asExpression(const Column& column);
};

template<typename T>
class ResultColumnConvertible<T, typename std::enable_if<ExpressionConvertible<T>::value>::type> final
: public std::true_type {
public:
    static ResultColumn asResultColumn(const T& t)
    {
        return ExpressionConvertible<T>::asExpression(t);
    }
};

因此，原来的 select 语句可以直接简写为：

WCDB::Column identifierColumm = WCDB::Column("identifier");
WCDB::StatementSelect select = 
    WCDB::StatementSelect().select(identifierColumm).from("sampleTable");
printf("%s", select.getDescription().data()); // 输出 "SELECT identifier FROM sampleTable"

WCDB 内的 Convertible 类型转换类较多，这里不一一赘述。开发者也无需逐一了解，在使用时再查阅接口即可。

Field

WCDB::Field 严格来说不属于语言集成查询的一部分，它们是语言集成查询和模型绑定结合的产物。

当需要通过对象来操作数据库时，如"get object"或者"update with object"等，WCDB 不仅需要知道查找数据的哪个字段（即 Column 所完成的事情，WCDB::Field实际继承了Column），还需要知道这个字段对应模型绑定中的哪个变量。

const WCDB::Field& field = WCDB_FIELD(Sample::identifier);
    WCDB::OptionalValueArray<Sample> objects = database.getAllObjectsWithFields<Sample>("sampleTable", field);

而 Field 就是存储了数据库字段和模型绑定字段的映射关系，而且还可以分离这个映射，具体用法可参考高级用法一章的查询重定向。

基于模型绑定，开发者可以完全摆脱通过字符串创建 Column，更便捷地操作数据库。Field 是继承了Column来实现的，WINQ中所有使用Column的地方都可以使用Field 。

WCDB::StatementSelect select = 
     WCDB::StatementSelect().select(WCDB_FIELD(Sample::identifier)).from("sampleTable")
printf("%s", select.getDescription().data());// 输出 "SELECT identifier FROM sampleTable"

Expression

Expression 可以算是 SQL 里最复杂的一个了。它在许多语句中都出现，比如查询语句的 where、groupBy、having、limit、offset，更新语句的 value、where、limit、offset等等。同时，它的完整定义也很长，甚至还包含了递归。

从单个 Expression 的语法角度来看，它支持从数字、字符串、字段创建。而 WCDB 将其扩展为支持所有字段映射类型，包括内建的类型和自定义的类型。

WCDB::Expression expressionInt = WCDB::Expression(1);
WCDB::Expression expressionDouble = WCDB::Expression(2.0);
WCDB::Expression expressionString = WCDB::Expression("3");
WCDB::Expression expressionColumn = WCDB::Expression(WCDB::Column( "identifier"));

除此之外，还有内建的绑定参数 WCDB::BindParameter 也可以转成 Expression 类型，甚至WCDB::StatementSelect也能转成 Expression 类型，因为有些场景子查询的结果也能作为判断条件。

多个 Expression 之间可以通过函数或运算符的方式进行操作，如：

WCDB::Expression expression = expressionColumn.between(expressionInt, expressionDouble);
printf("%s", expression.getDescription().data()); // 输出 "identifier BETWEEN 1 AND 2.0"

Expression 语法所支持的运算符有十多个，WCDB 基本都支持，但在语义上改为更符合 C++ 的习惯。例如

|| 运算符在 SQL 语法中用于字符串链接，而在 WCDB 中则是用于"或"的逻辑运算。
<> 运算符在 SQL 语法中用于不等比较，而在 WCDB 中则是直接使用较为习惯的 != 运算符。

WCDB::Expression expression1 = expressionInt + expressionDouble;
printf("%s", expression1.getDescription().data()); // 输出 "(1 + 2.0)"

WCDB::Expression expression2 = expressionColumn >= expression1;
printf("%s", expression2.getDescription().data()); // 输出 "(identifier >= (1 + 2.0))"

// 基础类型 -1 可以直接转换为 Expression
WCDB::Expression expression3 = expressionColumn < -1 || expression2;
printf("%s", expression3.getDescription().data()); // 输出 "((identifier < -1) OR (identifier >= (1 + 2.0)))"

WCDB::Expression statementSelect = WCDB::StatementSelect()
    .select(WCDB_FIELD(Sample::identifier))
    .from("sampleTable")
    .where(expression3);
printf("%s", statementSelect.getDescription().data()); // 输出 "SELECT identifier FROM sampleTable WHERE ((identifier < -1) OR (identifier >= (1 + 2.0)))"

ExpressionOperable

显然，每个类都要转换成 Expression 来进行这些操作，虽然也可以，但这就太麻烦了。

WCDB::Expression expression = WCDB::Expression(WCDB_FIELD(Sample::identifier)) > 1;
printf("%s", expression.getDescription().data());

因此，WCDB 将 Expression支持的函数操作和运算符操作定义成了多种 ExpressionOperable 基类：

ExpressionUnaryOperable一元运算符；
ExpressionBinaryOperable二元运算符；
ExpressionInOperable in操作，包括一系列in和notIn操作；
ExpressionBetweenOperablebetween操作
ExpressionCollateOperable给Expression指定字符串比对函数，具体见Collation。
CoreFunctionOperable给Expression调用SQLite内置函数，包括abs、hex、length等，具体见Core Function。
AggregateFunctionOperable给Expression调用SQLite内置聚合函数，包括avg、count、max、min等，具体见Aggregate Function。
FTSFunctionOperable给Expression调用FTS函数，包括highlight、matchinfo等。

继承这些ExpressionOperable 基类的类都可以与 Expression 的类似，使用函数或运算符进行语言集成查询，目前包括可以作为表达式左值的Column、Expression这两个。也因此，基于模型绑定，开发者可以完全摆脱通过拼装 Expression，更便捷地操作数据库。

WCDB::StatementSelect select = WCDB::StatementSelect().select(WCDB_FIELD(Sample::identifier))
                                       .from("sampleTable")
                                       .where(WCDB_FIELD(Sample::identifier) < -1 || WCDB_FIELD(Sample::identifier) >= 3.0);
printf("%s", select.getDescription().data()); // 输出 "SELECT identifier FROM sampleTable WHERE ((identifier < -1) OR (identifier >= 3.0))"

Statement

Statement 在前文已经接触到不少了，如查询 StatementSelect、插入 StatementInsert 等。它是一个最基本的完整可被执行的 SQL 语句。

SQLite 共包含 27 种 Statement，WCDB 都支持了。根据语法规则创建的 Statement，可以通过HandleOperation::execute() 函数直接执行，也可以使用Database、Handle和Table下面的这些接口获取执行Statement的结果，

getValueFromStatement执行Statement并获取一个结果。
getOneRowFromStatement执行Statement并获取一行结果，结果为一维数组。
getOneColumnFromStatement执行Statement并获取一列结果，结果为一维数组。
getAllRowsFromStatement执行Statement并获取多行结果，以二维数组的方式返回。

试考虑，表中的数据可以想象为一个矩阵的存在，假设其数据如下：

identifier	content
1	"sample1"
2	"sample1"
3	"sample2"
4	"sample2"
5	"sample2"

以下是使用Statement进行查询操作的示例代码：

// 获取所有内容
WCDB::OptionalMultiRows allRows = database.getAllRowsFromStatement(WCDB::StatementSelect().select(Sample::allFields()).from("sampleTable"));
printf("%lld", allRows.value()[2][0].intValue()); // 输出 3

// 获取第二行
WCDB::OptionalOneRow secondRow = database.getOneRowFromStatement(WCDB::StatementSelect().select(Sample::allFields()).from("sampleTable").offset(1));
printf("%lld", secondRow.value()[0].intValue()); // 输出 2

// 获取第二行 content 列的值
WCDB::OptionalOneColumn contentColumn = database.getOneColumnFromStatement(WCDB::StatementSelect().select(WCDB_FIELD(Sample::content)).from("sampleTable"));
printf("%s", contentColumn.value()[3].textValue().data()); // 输出 "sample2"

// 获取 identifier 的最大值
WCDB::OptionalValue maxId = database.getValueFromStatement(WCDB::StatementSelect().select(WCDB_FIELD(Sample::identifier).max()).from("sampleTable"));
printf("%lld", maxId.value().intValue());// 输出 5

// 获取不同的 content 数
WCDB::OptionalValue distinctContentCount = database.getValueFromStatement(WCDB::StatementSelect().select(WCDB_FIELD(Sample::content).count().distinct()).from("sampleTable"));
printf("%lld", distinctContentCount.value().intValue());// 输出 2

Statement 还可以通过 StatementOperation::prepare() 创建 WCDB::PreparedStatement 对象，来精细控制Statement的执行过程，这个我们会在高级接口的Handle一节详细介绍。

SQL 到语言集成查询

如前文所说，SQL 的复杂性决定了不可能介绍每一个类型及语句。因此，这里将介绍如何将一个已有的 SQL，转写为语言集成查询。开发者可以以此为例子，触类旁通。

对于已有的 SQL：

在语法中确定其所属的 Statement。
对照对应 Statement 的语法，根据关键字对已有的 SQL 进行断句。
逐个通过语言集成查询的函数调用进行实现。

以如下 SQL 为例：

SELECT min(identifier) FROM sampleTable WHERE (identifier > 0 || identifier / 2 == 0 ) && description NOT NULL ORDER BY identifier ASC LIMIT 1, 100

归类

根据 Statement 的列表，显然这个 SQL 属于 StatementSelect。

WCDB::StatementSelect statementSelect = WCDB::StatementSelect()

断句

根据 StatementSelect 的语法规则，按关键词（即语法中的大写字母）进行断句：

SELECT min(identifier) 
FROM sampleTable 
WHERE (identifier > 0 || identifier / 2 == 0 ) && description NOT NULL 
ORDER BY identifier ASC 
LIMIT 1, 100

调用语言集成查询

根据每个关键词，找到语言集成查询中对应的函数，并完成其参数。

如 SELECT 关键词对应 StatementSelect 的 select() 函数和from() 函数，以及AggregateFunctionOperable中的min函数：

statementSelect.select(WCDB_FIELD(Sample::identifier).min().distinct())
statementSelect.from("sampleTable")

WHERE 的参数虽然较复杂，但也都能找到对应的函数：

statementSelect.where((WCDB_FIELD(Sample::identifier) > 0 || WCDB_FIELD(Sample::identifier) / 2 == 0) && WCDB_FIELD(Sample::content).notNull())

其他语句也同理：

statementSelect.order(WCDB_FIELD(Sample::identifier).asOrder(WCTOrderedAscending))
statementSelect.limit(1, 100)

根据 SQL 语法结构图拼装 WINQ

SQLite的官网给出了它支持的全部SQL语法的结构图，还是以最复杂的select语句为例：

WINQ的整体设计思路是把整个select语句包装成一个StatementSelect对象，把图中的圆角方框的连接点包装成StatementSelect对象的成员函数，如：with、select、from、where、groupby、having、orderBy、limit等等这些函数。

图中直角方框的内容则是设计成StatementSelect对象的成员函数的入参。一些简单的入参则是支持使用基础类型，比如from函数可以传入一个字符串表示表名，一些复杂的入参则是继续包装成一个对象，比如前面提到的ResultColumn和Expression，其他的还有CommonTableExpression、Join、WindowDef等等这些对象。

所以在编写复杂SQL语句时，可以先找到对应的Statement对象，然后找到需要调用的方法，最后再根据方法需要的入参传入具体值。按照这个思路，可以根据SQL的语法结构图编写出所有SQLite支持的SQL语句。

Provide feedback

Saved searches

Use saved searches to filter your results more quickly