SQL 模板

SQL 模板提供在 MySQL 数据模型上执行 SQL 命令的方式，支持参数化查询和权限控制，可在小程序端、Web 端安全调用。

基础使用

创建模板

在数据模型管理页面创建 SQL 模板：

• 模板名称：英文、数字、下划线组合，全局唯一
• SQL 命令：支持 SELECT、INSERT、UPDATE、DELETE、REPLACE INTO
• 描述：可选，记录模板用途

初始化 SDK

请参考 SDK 初始化 中 node-sdk 初始化方式进行初始化

1. 安装

npm install @cloudbase/node-sdk --save

2. 初始化

import cloudbase from "@cloudbase/node-sdk"

// 初始化应用
const app = cloudbase.init({
    env: "your-env-id" // 替换为您的环境 ID
})

// 获取数据模型实例
const models = app.models

调用模板

调用sql模版

// 基础调用
const res = await app.models.modelName.runSQLTemplate({
    templateName: 'template_name',
    params: {
        key: 'value'
    }
});

// 指定环境
const res = await app.models.modelName.runSQLTemplate({
    templateName: 'template_name',
    envType: "pre", // pre: 体验环境, prod: 正式环境
    params: {
        key: 'value'
    }
});

HTTP API 调用方式参考 HTTP API 文档

SQL 语句规范

支持的命令

• SELECT
• INSERT INTO
• REPLACE INTO
• UPDATE
• DELETE

基本规则

1. 每个模板仅支持一条 SQL 命令
2. 主表必须是当前模型的表
3. 联表查询时子表可以是同库下任意表
4. INSERT/REPLACE 操作必须包含 owner 和 _openid 系统字段

参数语法

使用 {{ param }} 语法引入变量参数：

SELECT * FROM {{ model.tableName() }}
WHERE status = {{ status }}

内置函数

类别	函数	说明
模型	model.tableName()	获取当前模型表名
模型	model.tableName('model_name')	获取指定模型表名
模型	model.dataId()	生成数据ID
用户	user.userId()	获取用户ID
用户	user.openId()	获取用户openId
权限	auth.rowPermission()	获取当前模型行权限
权限	auth.rowPermission('model_name')	获取指定模型行权限
系统	system.currentEpoch()	获取秒级时间戳
系统	system.currentEpochMillis()	获取毫秒级时间戳

最佳实践

表名引用

-- 使用当前模型表
SELECT * FROM {{ model.tableName() }}

-- 联表查询
SELECT a.*, b.*
FROM {{ model.tableName() }} a
JOIN {{ model.tableName('other_model') }} b
ON a.id = b.ref_id

数据操作

-- 插入数据
INSERT INTO {{ model.tableName() }}
(_id, name, owner, _openid, createBy, updatedAt)
VALUES (
  {{ model.dataId() }},
  {{ name }},
  {{ user.userId() }},
  {{ user.openId() }},
  {{ user.userId() }},
  {{ system.currentEpochMillis() }}
)

-- 更新数据
UPDATE {{ model.tableName() }}
SET name = {{ name }},
    updatedAt = {{ system.currentEpochMillis() }}
WHERE _id = {{ id }}
  AND {{ auth.rowPermission() }}

-- 查询数据
SELECT * FROM {{ model.tableName() }}
WHERE status = {{ status }}
  AND {{ auth.rowPermission() }}

NULL 值处理

由于不支持 IS NULL 和 IS NOT NULL，使用以下替代语法：

-- 查询空值
WHERE column <=> NULL

-- 查询非空值
WHERE !(column <=> NULL)

注：更多高级用法和复杂查询示例，请参考SQL模板进阶指南