surrealql

SurrealQL

SurrealDB データベースと対話するための SurrealQL クエリを作成・変更するためのスキルです。

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	1 つ以上のレコードまたはグラフエッジを挿入。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