用途
SurrealQL 是一个用于编写和修改 SurrealQL 查询、以便与 SurrealDB 数据库交互的技能。SurrealQL 是 SurrealDB 的官方查询语言，被描述为一种现代、灵活且强大的查询语言，设计目标是易于学习和使用。
在以下情况应参考本技能的指南：
- 编写、修改或排查 SurrealQL 查询
- 设计或管理模式（schema）
- 将其他查询语言转换为 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 | 定义表（schemafull、schemaless、as view） |
| DEFINE FIELD | 定义字段，含类型、默认值、断言 |
| DEFINE INDEX | 定义索引（unique、search、vector） |
| 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 | 查看表或数据库的变更流（changefeed） |
控制流语句
| 语句 | 用途 |
|---|---|
| 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 版本。校验只能针对完整查询或值执行，不能针对部分或片段式语句。
用法：
# 校验单个文件：
surreal validate query.surql
# 校验 glob 模式的文件：
surreal validate queries/*.surql
# 从 stdin 校验（自 SurrealDB v3.1.0 起可用）：
echo "SELECT * FROM person WHERE age > 18" | surreal validate --stdin
格式化
在生成 SurrealQL 查询或 SQON 值时，如果存在类 NodeJS 运行时，可以决定使用 surqlfmt CLI 工具对其进行格式化。在以下情况应始终格式化：
- 向用户展示查询时
- 生成迁移文件时
- 编写 .surql 文件时
用法：
# 格式化文件并打印到 stdout：
npx @surrealdb/surql-fmt query.surql
# 就地格式化文件：
npx @surrealdb/surql-fmt --write migrations/*.surql
# 检查文件是否已格式化（未格式化则以退出码 1 退出）：
npx @surrealdb/surql-fmt --check src/**/*.surql
# 从 stdin 格式化：
echo "SELECT * FROM person WHERE age>18" | npx @surrealdb/surql-fmt --stdin
适用场景
- 编写、修改或排查 SurrealQL 查询
- 设计或管理 SurrealDB 模式
- 将其他查询语言转换为 SurrealQL
限制
- SurrealQL 不是 ANSI-SQL，不能套用其他数据库的 SQL 知识。
- SurrealQL 在主要版本之间会变化，旧版本语法可能导致查询无法通过校验。
- 校验只能针对完整查询或值，不能针对部分或片段式语句。
- 格式化需要类 NodeJS 运行时。
- 关于收费、价格、平台支持范围等信息，资料中暂未提供。