SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场surrealdb

surrealdb

编程与开发

查看项目

更新于 10-15 07:43

技能介绍

用途

该技能面向 SurrealDB 3 的架构设计、应用开发与运维工作，追踪 v3.1.4+ 版本。它把 SurrealQL、数据建模、图查询、向量检索、安全、部署、性能、SDK 与生态工具等主题整理为可按需查阅的规则文档，并配套若干 Python 脚本用于环境体检、schema 内省与上游源变更检查。

主要能力

  • SurrealQL 全面覆盖：CREATE、SELECT、UPDATE、UPSERT、DELETE、RELATE、INSERT、LIVE SELECT、DEFINE、REMOVE、INFO、子查询、事务、future，以及数组、crypto、duration、geo、math、meta、object、parse、rand、string、time、type、vector 等内置函数。
  • 多模型数据建模：在单一数据库与单一查询语言下设计文档集合、图边、关系引用、向量嵌入、时序数据与地理空间坐标。
  • 图查询：用 RELATE 建立带类型边，通过 ->、<-、<-> 操作符遍历，支持任意深度的过滤、聚合与递归，无需 JOIN。
  • 向量检索：基于 HNSW 索引（v3 的向量索引类型，索引构建/重建期间可回退为暴力检索）实现相似度搜索，支持 cosine、euclidean、manhattan、minkowski 距离度量，配合 vector::similarity::* 函数构建 RAG 与语义搜索。
  • 安全与权限：通过 DEFINE TABLE ... PERMISSIONS 实现行级安全，命名空间/数据库/记录级访问控制，DEFINE ACCESS 支持 JWT/token 鉴权，DEFINE USER 定义系统用户，$auth/$session 运行期变量用于权限谓词。
  • 部署与运维：单二进制部署、Docker、Kubernetes（Helm charts）、存储引擎选择（memory、RocksDB、SurrealKV、TiKV 分布式）、备份恢复、监控与生产加固。
  • 性能调优：唯一索引、搜索索引、向量 HNSW 索引策略，EXPLAIN 查询优化，连接池，存储引擎取舍，批量操作与资源限制。
  • SDK 集成：JavaScript/TypeScript（Node.js、Deno、Bun、浏览器）、Python、Go、Rust、Java、Kotlin、.NET、C、PHP、Swift（iOS/macOS/visionOS）、Ruby 官方 SDK，涵盖连接协议、认证流程、实时查询订阅与带类型记录处理。

使用方式

技能提供以下脚本命令（脚本位于 {baseDir}/scripts/ 下）：

# 为 AI 智能体输出完整能力清单、决策树与输出契约
uv run {baseDir}/scripts/onboard.py --agent

# 健康检查：验证 surreal CLI、连通性、版本
uv run {baseDir}/scripts/doctor.py
uv run {baseDir}/scripts/doctor.py --check   # 仅返回退出码
uv run {baseDir}/scripts/doctor.py --endpoint http://my-server:8000

# Schema 内省
uv run {baseDir}/scripts/schema.py introspect
uv run {baseDir}/scripts/schema.py tables
uv run {baseDir}/scripts/schema.py table <table_name>
uv run {baseDir}/scripts/schema.py export --format surql
uv run {baseDir}/scripts/schema.py export --format json

# 检查上游仓库是否有变更
uv run {baseDir}/scripts/check_upstream.py
uv run {baseDir}/scripts/check_upstream.py --json
uv run {baseDir}/scripts/check_upstream.py --stale

前置条件：surreal CLI（macOS 可用 brew install surrealdb/tap/surreal）；Python 3.10+；uv（brew install uv 或 pip install uv）。可选：Docker（docker run surrealdb/surrealdb:v3）与任意官方 SDK。

环境变量：SURREAL_ENDPOINT（默认 http://localhost:8000）、SURREAL_USER（默认 root）、SURREAL_PASS（默认 root）、SURREAL_NS（默认 test）、SURREAL_DB（默认 test）。

快速启动示例（仅限本地开发）：

surreal start memory --user root --pass root --bind 127.0.0.1:8000
surreal start rocksdb://data/mydb.db --user root --pass root
surreal start surrealkv://data/mydb --user root --pass root
surreal sql --endpoint http://localhost:8000 --user root --pass root --ns test --db test
surreal import --endpoint http://localhost:8000 --user root --pass root --ns test --db test schema.surql
surreal export --endpoint http://localhost:8000 --user root --pass root --ns test --db test backup.surql
surreal version

凭据警告：上述示例中的 root/root 仅用于本地开发，切勿用于生产或共享实例，非本地环境应创建最小权限的作用域用户。

安全提示：该技能只记录包管理器与容器安装方式，建议通过 Homebrew、apt/dnf、Cargo、npm 或 Docker 等可审计渠道安装，而非远程一行式 shell 安装脚本。

规则文档索引

rules/ 目录下按主题组织：surrealql.md（语法、语句、函数、操作符）、data-modeling.md（schema 设计、记录 ID、字段类型、关系与规范化）、graph-queries.md（RELATE 与图遍历）、vector-search.md（向量字段与 HNSW 索引）、security.md（权限与鉴权）、deployment.md（安装、存储引擎、Docker、Kubernetes、surrealdb/setup-surreal@v2 GitHub Action，仅用于 CI）、performance.md（索引与 EXPLAIN 优化）、sdks.md、surrealism.md（WASM 扩展）、surrealml.md（预览阶段）、surrealmcp.md、editor-tooling.md（LSP、tree-sitter、CodeMirror 与各编辑器扩展）、langchain.md（仅 Python 的 langchain-surrealdb 0.2.1）、ecosystem-integrations.md（n8n、AI 框架文档索引、CodeMirror、agent-skills 仓库）、surrealist.md、surreal-sync.md、surrealfs.md、surrealkit.md、gotchas.md（跨领域边界情况）。

生态工具

Surrealist（官方 IDE 与 GUI，含 schema 设计器、查询编辑器、图可视化）；Surreal-Sync（CDC 迁移）；SurrealFS（基于 SurrealDB 的 AI 智能体文件系统）；SurrealKit（期望态 schema 同步、基于 rollout 的迁移、种子数据与声明式测试）；SurrealML（预览阶段 .surml 工具）；SurrealMCP（模型上下文协议服务器）；n8n 社区节点包；CodeMirror 语法包；setup-surreal GitHub Action。

SurrealMCP 为官方 MCP 服务器（surrealdb/surrealmcp），可让 Claude Desktop、Cursor、VS Code 中 GitHub Copilot、Zed、n8n 等 MCP 兼容宿主通过单一配置读写 SurrealDB；需从源码（cargo install --path .）或 Docker 安装，未发布到 crates.io 或 npm；二进制需 start 子命令；工具线名为 snake_case。

输出约定

技能内所有 Python 脚本采用双输出模式：stderr 输出 Rich 格式化的人类可读内容，stdout 输出机器可读 JSON，便于智能体程序化消费（2>/dev/null 可隐藏人类输出）。

版本与来源快照

该技能于 2026-06-17 刷新，上游来源包括：surrealdb/surrealdb v3.1.4（2026-06-10）、surrealdb/surrealist surrealist-v3.9.0（2026-06-16）、surrealdb/surrealdb.js v2.0.3、surrealdb/surrealdb.py v2.0.0（PyPI，main 3.0.0 未发布）、surrealdb/surrealkit v0.7.0、surrealdb/surrealmcp v0.4.0（3.1+ 内置 MCP）；文档快照 surrealdb.com/docs 2026-06-17；机器可读来源信息见 SOURCES.json。

限制

SurrealML 属于预览/不稳定阶段：GitHub 有 v0.1.2 发布，但截至该快照 PyPI 上最新包仍为 surrealml 0.0.4；.surml 制品格式与 [sklearn]、[torch]、[tensorflow] extra 是稳定的已记录边界；v1.4.0 中关于 DEFINE MODEL、INFO FOR MODEL、REMOVE MODEL、ml::name<version>(...)、surreal ml import、db.upload_ml(...) 以及 SurMlFile.from_<framework>(...) 工厂方法的文档已在 v1.4.1 撤回；当前 Python 安装路径在 LOCAL_BUILD 非 TRUE 时会从 GitHub Releases 下载原生库，生产使用前需锁定版本并审计。此外，Spectron / Agent Memory Context 仅处于路线图阶段，不应作为生产 API 呈现；部分编辑器扩展的命令面板与设置仍需以各扩展 README 为准。