surrealql

SurrealQL

用于编写和修改 SurrealQL 查询，以便与 SurrealDB 数据库交互的技能。

SurrealQL 是 SurrealDB 的官方查询语言。这是一种现代、灵活且强大的查询语言，易于学习和使用。

何时使用此技能

在以下情况下，请参考这些指南：

• 编写、修改或排查 SurrealQL 查询
• 设计或管理架构
• 将其他查询语言转换为 SurrealQL

版本与文档

始终以最新的稳定版 SurrealDB 为目标。 SurrealQL 会在主要版本之间演进，旧版本（例如 SurrealDB 2.x）的语法是查询错误或无法通过验证的常见原因。除非用户明确要求使用旧版本，否则请生成当前的（3.x）语法。

生成与版本相关的语法前，请确定当前使用的版本：

• 如果已安装 SurrealDB CLI，请运行 surreal version。

• 否则，最新发布的版本会以纯字符串形式发布在 https://download.surrealdb.com（例如 v3.1.4）：

  curl -s https://download.surrealdb.com
  

https://surrealdb.com/docs 始终记录最新稳定版的文档——请将其视为当前语法的权威来源。如果不确定某个函数或形式是否仍适用（例如 type::* 辅助函数以及记录 ID 的构造方式），请查阅当前文档予以确认，而不要假定旧有行为仍然适用。

规则与约定

• SurrealQL 不是 ANSI-SQL。切勿假定适用于其他数据库的 SQL 知识也适用。请始终参考下方示例或 https://surrealdb.com/docs 上的文档，了解准确的语法和行为。
• 将 SurrealQL 存储在文件中时，文件扩展名应为 .surql。
• SurrealQL 是一种相对较新的语言，会在不同版本之间发生变化。默认使用最新的 SurrealDB 版本（参见版本与文档），并参考 https://surrealdb.com/docs 获取最新的语法。

语句

查询语句

语句	用途
SELECT	查询记录、遍历图、聚合数据
CREATE	创建新记录（如果记录已存在则报错）
INSERT	插入一条或多条记录或图边；支持 ON DUPLICATE KEY UPDATE
UPDATE	更新现有记录（如果记录不存在则不执行任何操作）
UPSERT	插入记录；如果记录已存在则更新
DELETE	删除记录或图边
RELATE	在记录之间创建图边
LIVE SELECT	实时流式传输表中的更改
KILL	取消正在运行的 LIVE SELECT 查询
LET	为参数赋值
RETURN	从代码块或函数返回值

架构与资源语句

语句	用途
DEFINE NAMESPACE	定义命名空间
DEFINE DATABASE	定义数据库
DEFINE TABLE	定义表（完整架构、无架构或视图）
DEFINE FIELD	定义字段的类型、默认值和断言
DEFINE INDEX	定义索引（唯一、搜索、向量）
DEFINE EVENT	定义表上的事件触发器
DEFINE FUNCTION	定义自定义函数
DEFINE ANALYZER	定义搜索分析器
DEFINE ACCESS	定义身份验证访问方式（Bearer、JWT、Record）
DEFINE API	定义 API 端点
DEFINE BUCKET	定义存储桶
DEFINE CONFIG	定义配置
DEFINE MODULE	定义 Surrealism 扩展模块
DEFINE PARAM	定义全局参数
DEFINE SEQUENCE	定义自增序列
DEFINE USER	定义系统用户
ALTER	修改现有资源定义
REMOVE	移除任何已定义的资源
REBUILD	重建索引
ACCESS	管理访问授权
USE	切换到其他命名空间或数据库
INFO	检查资源的定义
SHOW	查看表或数据库的变更流

控制流语句

语句	用途
BEGIN / COMMIT	开始并提交手动事务
CANCEL	取消事务
IF / ELSE	条件执行
FOR	遍历值
BREAK	提前退出 FOR 循环
CONTINUE	跳到 FOR 循环的下一次迭代
THROW	取消执行并返回错误
SLEEP	暂停执行一段时间

参考资料

有关详细的查询模式（筛选、图遍历、聚合、子查询），请参阅 references/querying.md。

有关架构管理模式（表、字段、索引、事件、访问），请参阅 references/schema.md。

有关 SurrealDB 记录中可存储的值的详细信息，请参阅 references/values.md。

验证

生成 SurrealQL 查询或修改现有查询时，如果可以使用 SurrealDB CLI，则应始终使用它进行验证。验证可能会因版本差异而失败，此时可以通过 surreal version 获取 SurrealDB CLI 版本。只能对完整查询或值进行验证，不能验证部分语句或语句片段。

用法

# Validate a single file:
surreal validate query.surql

# Validate glob pattern of files:
surreal validate queries/*.surql

# Validate from stdin (available since SurrealDB v3.1.0):
echo "SELECT * FROM person WHERE age > 18" | surreal validate --stdin

格式化

生成 SurrealQL 查询或 SQON 值时，如果有类似 NodeJS 的运行时，可以考虑使用 surqlfmt CLI 工具进行格式化。以下情况应始终进行格式化：

• 向用户展示查询时
• 生成迁移文件时
• 编写 .surql 文件时

用法

# Format a file and print to stdout:
npx @surrealdb/surql-fmt query.surql

# Format files in-place:
npx @surrealdb/surql-fmt --write migrations/*.surql

# Check if files are already formatted (exits with code 1 if not):
npx @surrealdb/surql-fmt --check src/**/*.surql

# Format from stdin:
echo "SELECT * FROM person WHERE age>18" | npx @surrealdb/surql-fmt --stdin