クエリー

.query() インスタンス メソッド

カスタム SurrealQL を実行します。

query(
  surql: string | object,
  vars?: { [p: string]: unknown },
  options?: ClientRpcOptions,
): Promise<unknown[]>;

引数

surql

SurrealQL の文字列または事前に準備されたクエリーです。

vars

SurrealQL の実行時に渡す変数です。変数名はドルマークから始まらないように注意してください。

options

PRC リクエストのオプションです。

返値

SurrealQL の実行結果の配列で解決される Promise オブジェクトを返します。ステートメントが 1 つ以上失敗した場合、それらのエラーメッセージを含む QueryFailedError で拒否します。

このメソッドが拒否されると実行結果を得る手段はありません。エラーハンドリングを手動で行う場合、.queryRaw() を使うことができます。

例

次の例ではクエリーの実行に成功します:

import { Surreal } from "@tai-kun/surrealdb";

const db = new Surreal();
await db.connect("ws://localhost:8000");

const results = await db.query(`
  CREATE ONLY user:foo CONTENT { age: 42 };
`);
console.log(results);
// [{
//   id: Thing { tb: 'user', id: 'foo' },
//   age: 42
// }]

await db.close();

次の例では一方のステートメントが失敗するため、クエリーは QueryFailedError で拒否されます:

import { Surreal } from "@tai-kun/surrealdb";

const db = new Surreal();
await db.connect("ws://localhost:8000");

const results = await db.query(`
  CREATE ONLY user:foo CONTENT { age: 42 };
  OUTPUT 42;
`); // throws QueryFailedError: Query failed with 1 error(s)

次の例では事前に準備されたクエリーを実行します:

import { surql, Surreal, Thing } from "@tai-kun/surrealdb";

const CreateUserQuery = surql`
  CREATE ONLY user:foo CONTENT { age: 42 };
`.returns<[{ id: Thing<"user">, age: number }]>()

const db = new Surreal();
await db.connect("ws://localhost:8000");

const results = await db.query(CreateUserQuery);
   // ^? const results: [{ id: Thing<"user">, age: number }]

await db.close();

.queryRaw() インスタンス メソッド

カスタム SurrealQL を実行します。

queryRaw(
  surql: string | object,
  vars?: { [p: string]: unknown },
  options?: ClientRpcOptions,
): Promise<QueryResult[]>;

引数

surql

SurrealQL の文字列または事前に準備されたクエリーです。

vars

SurrealQL の実行時に渡す変数です。変数名は $ から始まらないように注意してください。

options

PRC リクエストのオプションです。

返値

SurrealQL の実行結果の配列で解決される Promise オブジェクトを返します。

type QueryResult = {
  status: "OK";
  time: string;
  result: unknown;
} | {
  status: "ERR";
  time: string;
  result: string;
};