【PostgreSQL内核学习（二十九）—— 执行器（ExecCreateTableAs）】

执行器（ExecCreateTableAs）

ExecCreateTableAs 函数
- RangeVarGetCreationNamespace 函数
- - RangeVar 结构体
  - IntoClause 结构体

声明：本文的部分内容参考了他人的文章。在编写过程中，我们尊重他人的知识产权和学术成果，力求遵循合理使用原则，并在适用的情况下注明引用来源。
本文主要参考了 postgresql-10.1 的开源代码和《OpenGauss数据库源码解析》和《PostgresSQL数据库内核分析》一书

ExecCreateTableAs 函数

ExecCreateTableAs 函数的主要功能是基于 SELECT 查询结果创建一个新表或物化视图。函数处理了多种情况，包括检查表是否已存在（并在IF NOT EXISTS条件下跳过创建）、处理物化视图的特殊要求、以及处理带有 WITH NO DATA 选项的情况（即不填充数据）。整个流程包括查询重写、查询规划、执行计划的准备和执行，最终创建表并将查询结果插入到新表中。对于物化视图，额外处理了安全上下文和配置变量（GUC），以保证创建过程的安全性和一致性。函数源码如下所示：（路径：postgresql-10.1\src\backend\commands\createas.c）

ObjectAddress
ExecCreateTableAs(CreateTableAsStmt *stmt, const char *queryString,
                  ParamListInfo params, QueryEnvironment *queryEnv,
                  char *completionTag)
{
    Query       *query = castNode(Query, stmt->query); // 将stmt中的查询语句强制转换为Query类型
    IntoClause  *into = stmt->into; // 获取INTO子句，包含新表的信息
    bool        is_matview = (into->viewQuery != NULL); // 检查是否为创建物化视图的命令
    DestReceiver *dest; // 声明一个结果接收器
    Oid         save_userid = InvalidOid; // 保存当前用户ID
    int         save_sec_context = 0; // 保存当前安全上下文
    int         save_nestlevel = 0; // 保存当前的GUC嵌套等级
    ObjectAddress address; // 声明一个对象地址，用于返回创建的表或物化视图的地址
    List        *rewritten; // 声明一个列表，用于存放重写后的查询
    PlannedStmt *plan; // 声明一个计划语句
    QueryDesc   *queryDesc; // 声明一个查询描述符

    if (stmt->if_not_exists) // 如果指定了IF NOT EXISTS选项
    {
        Oid         nspid;

        nspid = RangeVarGetCreationNamespace(stmt->into->rel); // 获取新表应该创建在哪个命名空间（schema）中

        if (get_relname_relid(stmt->into->rel->relname, nspid)) // 如果表已经存在
        {
            ereport(NOTICE,
                    (errcode(ERRCODE_DUPLICATE_TABLE),
                     errmsg("relation \"%s\" already exists, skipping",
                            stmt->into->rel->relname))); // 发出通知，表已存在，跳过创建
            return InvalidObjectAddress; // 返回一个无效的对象地址
        }
    }

    // 创建结果接收器，用于处理查询结果并将结果存入新表
    dest = CreateIntoRelDestReceiver(into);

    // 如果查询本身是一个EXECUTE命令或者其他非SELECT命令
    if (query->commandType == CMD_UTILITY &&
        IsA(query->utilityStmt, ExecuteStmt))
    {
        ExecuteStmt *estmt = castNode(ExecuteStmt, query->utilityStmt);

        Assert(!is_matview); // 确认不是在创建物化视图
        ExecuteQuery(estmt, into, queryString, params, dest, completionTag); // 执行查询

        // 获取由intorel_startup函数保存的对象地址
        address = ((DR_intorel *) dest)->reladdr;

        return address; // 返回对象地址
    }
    Assert(query->commandType == CMD_SELECT); // 确认查询类型为SELECT

    // 对物化视图进行额外的安全和GUC变量设置
    if (is_matview)
    {
        GetUserIdAndSecContext(&save_userid, &save_sec_context); // 获取当前用户ID和安全上下文
        SetUserIdAndSecContext(save_userid,
                               save_sec_context | SECURITY_RESTRICTED_OPERATION); // 设置安全限制操作的上下文
        save_nestlevel = NewGUCNestLevel(); // 创建一个新的GUC嵌套等级
    }

    // 如果指定了WITH NO DATA，意味着不需要填充数据
    if (into->skipData)
    {
        // 不通过查询重写和执行器，直接定义一个空表
        address = create_ctas_nodata(query->targetList, into);
    }
    else
    {
        // 正常路径：需要通过规则重写器、查询规划器和执行器来创建表和填充数据

        // 首先对查询进行重写
        rewritten = QueryRewrite(copyObject(query));

        // 确保重写结果是一个SELECT查询
        if (list_length(rewritten) != 1)
            elog(ERROR, "unexpected rewrite result for %s",
                 is_matview ? "CREATE MATERIALIZED VIEW" :
                 "CREATE TABLE AS SELECT");
        query = linitial_node(Query, rewritten);
        Assert(query->commandType == CMD_SELECT);

        // 规划查询，注意禁用并行查询
        plan = pg_plan_query(query, 0, params);

        // 使用更新了命令ID的快照，以确保查询能看到之前查询的结果
        PushCopiedSnapshot(GetActiveSnapshot());
        UpdateActiveSnapshotCommandId();

        // 创建一个查询描述符
        queryDesc = CreateQueryDesc(plan, queryString,
                                    GetActiveSnapshot(), InvalidSnapshot,
                                    dest, params, queryEnv, 0);

        // 准备执行计划
        ExecutorStart(queryDesc, GetIntoRelEFlags(into));

        // 执行计划
        ExecutorRun(queryDesc, ForwardScanDirection, 0L, true);

        // 如果需要，保存行数
        if (completionTag)
            snprintf(completionTag, COMPLETION_TAG_BUFSIZE,
                     "SELECT " UINT64_FORMAT,
                     queryDesc->estate->es_processed);

        // 获取由intorel_startup函数保存的对象地址
        address = ((DR_intorel *) dest)->reladdr;

        // 清理执行器
        ExecutorFinish(queryDesc);
        ExecutorEnd(queryDesc);

        // 释放查询描述符
        FreeQueryDesc(queryDesc);

        // 恢复快照
        PopActiveSnapshot();
    }

    // 如果是创建物化视图，需要回滚GUC变更并恢复用户ID和安全上下文
    if (is_matview)
    {
        AtEOXact_GUC(false, save_nestlevel); // 回滚GUC变更
        SetUserIdAndSecContext(save_userid, save_sec_context); // 恢复用户ID和安全上下文
    }

    return address; // 返回新创建的表或物化视图的对象地址
}

RangeVarGetCreationNamespace 函数

RangeVarGetCreationNamespace 函数的作用是根据提供的 RangeVar 结构（通常描述了一个将要创建的关系，比如表或视图）来决定这个关系应该在哪个命名空间（schema）中创建。函数源码如下所示：（路径：postgresql-10.1\src\backend\catalog\namespace.c）

Oid
RangeVarGetCreationNamespace(const RangeVar *newRelation)
{
	Oid			namespaceId;

	// 如果指定了catalog名称（即数据库名称），则进行检查，目前不支持跨数据库的引用。
	if (newRelation->catalogname)
	{
		// 如果catalog名称（数据库名称）与当前数据库不匹配，则报错
		if (strcmp(newRelation->catalogname, get_database_name(MyDatabaseId)) != 0)
			ereport(ERROR,
					(errcode(ERRCODE_FEATURE_NOT_SUPPORTED),
					 errmsg("cross-database references are not implemented: \"%s.%s.%s\"",
							newRelation->catalogname, newRelation->schemaname,
							newRelation->relname)));
	}

	// 如果指定了schema名称
	if (newRelation->schemaname)
	{
		// 如果schema名称为"pg_temp"，则表示要在临时schema中创建
		if (strcmp(newRelation->schemaname, "pg_temp") == 0)
		{
			// 如果这是第一次访问临时schema，则进行初始化
			if (!OidIsValid(myTempNamespace))
				InitTempTableNamespace();
			return myTempNamespace;
		}
		// 否则，使用指定的schema名称
		namespaceId = get_namespace_oid(newRelation->schemaname, false);
		// 注意：此处没有检查USAGE权限
	}
	else if (newRelation->relpersistence == RELPERSISTENCE_TEMP)
	{
		// 如果没有指定schema，但指定为临时表，则也初始化临时schema
		if (!OidIsValid(myTempNamespace))
			InitTempTableNamespace();
		return myTempNamespace;
	}
	else
	{
		// 如果既没有指定schema，也不是临时表，则使用默认的创建命名空间
		recomputeNamespacePath();
		if (activeTempCreationPending)
		{
			// 如果需要，初始化临时schema
			InitTempTableNamespace();
			return myTempNamespace;
		}
		namespaceId = activeCreationNamespace;
		// 如果没有找到有效的创建命名空间，则报错
		if (!OidIsValid(namespaceId))
			ereport(ERROR,
					(errcode(ERRCODE_UNDEFINED_SCHEMA),
					 errmsg("no schema has been selected to create in")));
	}

	// 注意：调用者会在适当的时候检查CREATE权限

	return namespaceId;
}

功能描述
这个函数主要用于确定新创建的数据库对象（如表或视图）应该位于哪个命名空间（schema）中。它首先检查是否指定了数据库名称（catalogname）和模式名称（schemaname），并据此做出决策。该函数考虑了以下几种情况：

如果提供了 catalogname，但不支持跨数据库引用，将报错。
如果提供了 schemaname 为 “pg_temp”，或者没有提供 schemaname 但指定为临时对象，则对象将在临时 schema 中创建。
如果提供了 schemaname，则使用该指定的 schema。
如果没有提供 schemaname 且不是临时对象，则使用默认的创建命名空间。

此外，该函数还会在首次创建临时表时初始化临时 schema，并在无法确定合适的命名空间时报错。这保证了新对象的创建总是在一个明确且合法的命名空间中进行。

RangeVar 结构体

RangeVar 结构体在 PostgreSQL 中代表一个范围变量（range variable）。范围变量通常用在 FROM 子句中指定表名，也用于表示实用程序语句中的表名。在一些上下文中，它还携带了是否是临时表的标志。下面是对这个结构体每一行代码的详细中文注释：（路径：postgresql-10.1\src\include\nodes\primnodes.h）

typedef struct RangeVar
{
    NodeTag     type;           // 节点类型标识符，用于标识这是一个节点结构
    char       *catalogname;    // 目录（数据库）名称，如果没有指定则为NULL
    char       *schemaname;     // 模式（schema）名称，如果没有指定则为NULL
    char       *relname;        // 关系（表）/序列名称
    bool        inh;            // 是否通过继承扩展关系？是否递归地作用于子表？
    char        relpersistence; // 表的持久性属性，对应于pg_class.h中的RELPERSISTENCE_*
    Alias      *alias;          // 表别名及可选的列别名
    int         location;       // 代表这个节点在查询字符串中的位置，如果未知则为-1
} RangeVar;

功能描述
RangeVar 结构体在 PostgreSQL 的查询解析和处理过程中扮演了非常重要的角色。它主要用于：

指定 FROM 子句中的表：在 SQL 查询的 FROM 子句中，每个指定的表都会被解析为一个 RangeVar 结构体，通过这个结构体，查询处理器能够知道查询涉及到哪些表和视图。
表示实用程序语句中的表名：在涉及表的实用程序命令（如 ALTER TABLE, DROP TABLE 等）中，RangeVar 用于指定要操作的表。
递归操作和继承：通过 inh 字段，RangeVar 能够指示操作是否需要递归地应用到继承的子表中。这在使用表继承特性时非常有用。
别名和列别名：通过 alias 字段，RangeVar 还可以携带查询中为表指定的别名以及列的别名。
位置信息：location 字段记录了这个 RangeVar 在原始查询字符串中的具体位置，这在生成错误消息和警告时有助于提供准确的上下文信息。

总之，RangeVar 是 PostgreSQL 中用于表示查询中涉及表的基本结构体，它提供了表的名称、别名、递归操作等关键信息，使得查询处理器能够准确理解和处理查询语句。

IntoClause 结构体

IntoClause 结构体用于在 SELECT INTO、CREATE TABLE AS 和 CREATE MATERIALIZED VIEW 语句中指定目标信息。这个结构体封装了目标表的名称、列名、选项和其他相关信息。下面是对这个结构体每一行代码的详细中文注释：（路径：postgresql-10.1\src\include\nodes\primnodes.h）

typedef struct IntoClause
{
	NodeTag		type;           // 节点类型标识符，用于标识这是一个节点结构

	RangeVar   *rel;			// 目标关系（表或视图）的名称
	List	   *colNames;		// 指定的列名列表，如果没有指定则为NIL
	List	   *options;		// 来自WITH子句的选项列表
	OnCommitAction onCommit;	// 事务提交时的操作（如删除、保存等）
	char	   *tableSpaceName; // 使用的表空间名称，如果没有指定则为NULL
	Node	   *viewQuery;		// 物化视图的SELECT查询，如果不是创建物化视图则为NULL
	bool		skipData;		// 对于WITH NO DATA选项，此值为true
} IntoClause;

功能描述
IntoClause 结构体在 PostgreSQL 的查询处理中用于存储 SELECT INTO、CREATE TABLE AS 和 CREATE MATERIALIZED VIEW 语句中涉及的目标表或视图的信息，具体包括：

目标表/视图名称： 通过 rel 字段，IntoClause 存储了目标表或视图的名称，这是一个 RangeVar 结构体，包含了表名、模式名等信息。
列名： colNames 字段存储了用户指定的列名列表，这在 SELECT INTO 或 CREATE TABLE AS 时指定列名非常有用。
WITH子句选项： options 字段包含了 WITH 子句中指定的各种选项，比如压缩方法或其他表级选项。
事务提交行为： onCommit 字段描述了在事务提交时对这个表进行什么操作，比如是否需要在事务提交后保留数据。
表空间名称： tableSpaceName 字段允许指定表或物化视图应该位于哪个表空间，如果未指定，则使用默认表空间。
物化视图的SELECT查询： viewQuery 字段存储了创建物化视图时的 SELECT 查询。这个字段只在创建物化视图时使用，其他情况下为 NULL。
是否跳过数据： skipData 字段标记了是否应该跳过数据加载。这在使用 WITH NO DATA 选项创建物化视图时非常有用，表示只创建视图结构而不加载数据。