跳到主要内容

RPC 调用

通过 JS SDK 调用 PostgreSQL 数据库中的自定义函数（Stored Procedures / Functions）。

💡 提示：RPC 调用基于 PostgREST 协议，可以调用在 PostgreSQL 中创建的任何自定义函数。

初始化 SDK​

import cloudbase from "@cloudbase/js-sdk";

const app = cloudbase.init({
  env: "your-env-id", // 替换为您的环境id
});

const db = app.rdb();

基础语法​

db.rpc(functionName, params, options);

参数​

参数名类型必填描述
functionNamestring是要调用的数据库函数名称
paramsobject否传递给函数的参数，以键值对形式
optionsobject否选项配置

options 参数详情​

参数名类型必填描述
headboolean否如果为 true，则不返回数据，仅返回 count 值（需配合 count 选项使用）
countstring否计数算法，可选值为 "exact"、"planned" 或 "estimated"
getboolean否如果为 true，使用 HTTP GET 请求调用函数（仅适用于 IMMUTABLE 或 STABLE 的只读函数）

创建函数​

在调用 RPC 之前，需要先在 PostgreSQL 数据库中创建函数。可以通过 DMC 数据库管理工具执行 SQL 创建函数。

-- 创建一个简单的加法函数
CREATE OR REPLACE FUNCTION add_numbers(a integer, b integer)
RETURNS integer AS $$
  SELECT a + b;
$$ LANGUAGE sql;

-- 创建一个查询文章的函数
CREATE OR REPLACE FUNCTION search_articles(keyword text)
RETURNS SETOF articles AS $$
  SELECT * FROM articles WHERE title ILIKE '%' || keyword || '%';
$$ LANGUAGE sql;

-- 创建一个统计函数
CREATE OR REPLACE FUNCTION get_article_stats()
RETURNS json AS $$
  SELECT json_build_object(
    'total', COUNT(*),
    'latest', MAX(published_at)
  ) FROM articles;
$$ LANGUAGE sql;

代码示例​

带参数调用​

// 调用加法函数
const { data, error } = await db.rpc("add_numbers", { a: 1, b: 2 });
console.log(data); // 3

无参数调用​

// 调用统计函数
const { data, error } = await db.rpc("get_article_stats");
console.log(data);
// { total: 15, latest: "2026-04-01T00:00:00Z" }

调用返回表数据的函数​

当函数返回 SETOF <table> 时，返回值为数组格式，并且支持链式调用过滤器和修饰符。

// 搜索包含关键字的文章
const { data, error } = await db.rpc("search_articles", {
  keyword: "云开发",
});

对返回结果进行过滤和排序​

当函数返回表数据时，可以像普通查询一样使用过滤器和修饰符。

// 搜索文章，按发布时间降序排列，限制返回 5 条
const { data, error } = await db
  .rpc("search_articles", { keyword: "云开发" })
  .select("title, published_at")
  .order("published_at", { ascending: false })
  .limit(5);

返回单条记录​

// 获取单条记录
const { data, error } = await db
  .rpc("search_articles", { keyword: "云开发" })
  .limit(1)
  .single();

使用过滤器​

// 对 RPC 返回的表数据应用过滤条件
const { data, error } = await db
  .rpc("search_articles", { keyword: "云开发" })
  .eq("status", "published")
  .gte("published_at", "2026-01-01");

使用 GET 请求调用只读函数​

对于标记为 IMMUTABLE 或 STABLE 的只读函数，可以使用 GET 请求调用以获得更好的缓存效果。

// 使用 GET 请求调用只读函数
const { data, error } = await db.rpc(
  "add_numbers",
  { a: 1, b: 2 },
  { get: true }
);

获取行数统计​

// 仅获取行数统计，不返回数据
const { count, error } = await db.rpc(
  "search_articles",
  { keyword: "云开发" },
  { count: "exact", head: true }
);
console.log(count); // 返回匹配的记录数

函数参数类型​

PostgREST 支持多种 PostgreSQL 函数参数类型：

参数类型说明JS SDK 传参示例
integer整数{ id: 1 }
text / varchar文本{ name: "test" }
boolean布尔值{ active: true }
json / jsonbJSON 对象{ data: { key: "value" } }
integer[]整数数组{ ids: [1, 2, 3] }
text[]文本数组{ names: ["a", "b"] }