surrealql

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

SurrealQL

A skill for writing and modifying SurrealQL queries to interact with SurrealDB databases.

SurrealQL is the official query language for SurrealDB. It is a modern, flexible, and powerful query language that is designed to be easy to learn and use.

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

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

When to use this skill

何时使用此技能

Reference these guidelines when:

Writing, modifying, or troubleshooting SurrealQL queries
Designing or managing schemas
Converting other query languages to SurrealQL

在以下场景中参考本指南：

编写、修改或排查SurrealQL查询语句
设计或管理数据库模式
将其他查询语言转换为SurrealQL

Rules & Conventions

规则与约定

SurrealQL is NOT ANSI-SQL. Never assume SQL knowledge from other databases applies. Always refer to the examples below or the documentation at https://surrealdb.com/docs for accurate syntax and behavior.
When SurrealQL is stored in a file, it should have a
```
.surql
```
extension.
SurrealQL is a relatively young language, and new features are being added regularly. Refer to the documentation at https://surrealdb.com/docs for the most up-to-date information.

SurrealQL 并非ANSI-SQL。切勿假设其他数据库的SQL知识适用于它。如需准确的语法和行为说明，请始终参考以下示例或官方文档：https://surrealdb.com/docs
当SurrealQL语句存储为文件时，应使用
```
.surql
```
扩展名。
SurrealQL是一门相对较新的语言，会定期添加新特性。如需最新信息，请参考官方文档：https://surrealdb.com/docs

Statements

语句类型

Query Statements

查询语句

Statement	Purpose
SELECT	Query records, traverse graphs, aggregate data
CREATE	Create new records (errors if record exists)
INSERT	Insert one or more records or graph edges; supports `ON DUPLICATE KEY UPDATE`
UPDATE	Update existing records (no-op if record doesn't exist)
UPSERT	Insert a record, or update it if it already exists
DELETE	Delete records or graph edges
RELATE	Create graph edges between records
LIVE SELECT	Stream real-time changes to a table
KILL	Cancel an active LIVE SELECT query
LET	Assign a value to a parameter
RETURN	Return a value from a block or function

语句	用途
SELECT	查询记录、遍历图、聚合数据
CREATE	创建新记录（记录已存在时抛出错误）
INSERT	插入一条或多条记录或图边；支持 `ON DUPLICATE KEY UPDATE`
UPDATE	更新现有记录（记录不存在时无操作）
UPSERT	插入记录，若记录已存在则更新
DELETE	删除记录或图边
RELATE	在记录之间创建图边
LIVE SELECT	流式传输表的实时变更
KILL	取消活跃的LIVE SELECT查询
LET	为参数赋值
RETURN	从代码块或函数返回值

Schema & Resource Statements

模式与资源语句

Statement	Purpose
DEFINE NAMESPACE	Define a namespace
DEFINE DATABASE	Define a database
DEFINE TABLE	Define a table (schemafull, schemaless, as view)
DEFINE FIELD	Define a field with type, default, assertion
DEFINE INDEX	Define an index (unique, search, vector)
DEFINE EVENT	Define event triggers on a table
DEFINE FUNCTION	Define a custom function
DEFINE ANALYZER	Define a search analyzer
DEFINE ACCESS	Define authentication access methods (Bearer, JWT, Record)
DEFINE API	Define an API endpoint
DEFINE BUCKET	Define a storage bucket
DEFINE CONFIG	Define a configuration
DEFINE MODULE	Define a Surrealism extension module
DEFINE PARAM	Define a global parameter
DEFINE SEQUENCE	Define an auto-incrementing sequence
DEFINE USER	Define a system user
ALTER	Alter an existing resource definition
REMOVE	Remove any defined resource
REBUILD	Rebuild an index
ACCESS	Manage access grants
USE	Switch to a different namespace or database
INFO	Inspect definitions for a resource
SHOW	View changefeed for a table or database

语句	用途
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	查看表或数据库的变更日志

Control Flow Statements

控制流语句

Statement	Purpose
BEGIN / COMMIT	Begin and commit a manual transaction
CANCEL	Cancel a transaction
IF / ELSE	Conditional execution
FOR	Iterate over values
BREAK	Exit a FOR loop early
CONTINUE	Skip to next iteration in a FOR loop
THROW	Cancel execution and return an error
SLEEP	Pause execution for a duration

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

References

参考文档

For detailed querying patterns (filtering, graph traversal, aggregation, subqueries), see references/querying.md.

For schema management patterns (tables, fields, indexes, events, access), see references/schema.md.

For in-depth information about the values that can be stored in SurrealDB records, see references/values.md.

如需详细的查询模式（过滤、图遍历、聚合、子查询），请参阅references/querying.md。

如需模式管理模式（表、字段、索引、事件、访问权限），请参阅references/schema.md。

如需了解SurrealDB记录中可存储的值的详细信息，请参阅references/values.md。

Validation

验证

When generating SurrealQL queries, or modifying existing queries, you should always validate them using the SurrealDB CLI if available. Validation may fail to due version differences, at which point you can retrieve your SurrealDB CLI version with

surreal version

. Validation can only be performed against full queries or values, not partial or fragmentary statements.

当生成或修改SurrealQL查询语句时，如果有SurrealDB CLI可用，务必使用它进行验证。版本差异可能导致验证失败，此时可以通过

surreal version

命令查看你的SurrealDB CLI版本。验证仅适用于完整的查询语句或值，不适用于部分或片段化的语句。

Usage

使用方法

bash

undefined

bash

undefined

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):

从标准输入验证（SurrealDB v3.1.0及以上版本可用）:

echo "SELECT * FROM person WHERE age > 18" | surreal validate --stdin

undefined

echo "SELECT * FROM person WHERE age > 18" | surreal validate --stdin

undefined

Formatting

格式化

When generating SurrealQL queries or SQON values you may decide to format them using the

surqlfmt

CLI tool if a NodeJS-like runtime is available. Situations in which you should always format include:

When presenting queries to users
When generating migration files
When writing
```
.surql
```
files

当生成SurrealQL查询语句或SQON值时，如果有类NodeJS运行环境可用，可以使用

surqlfmt

CLI工具对其进行格式化。以下情况务必进行格式化：

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

Usage

使用方法

bash

undefined

bash

undefined

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):

检查文件是否已格式化（未格式化则退出码为1）:

npx @surrealdb/surql-fmt --check src/**/*.surql

Format from stdin:

从标准输入格式化:

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

undefined

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

undefined