スクリプトからデータベースを操作する

スクリプトノードやファンクションから、synqlet:database/{テーブルのID} をインポートすると、そのテーブルの行を読み書きできます。

モジュールの型は テーブルのフィールド定義から自動生成 されるため、フィールド名や値の型をエディタ上で補完・チェックできます。

インポートする

エディタ右の「ライブラリ」パネル（またはエディタ上部のインポート欄）の「データベース」タブでテーブルを選び、「＋」を押すと import 文が挿入されます。ID を手入力する必要はありません。

import * as customers from "synqlet:database/{テーブルのID}";

使える関数

関数	説明
`list(parameter?)`	行を一覧取得する（非同期イテレーター。ページングは自動）
`get(id)`	行を1件取得する
`insertOne(input)`	行を1件作成する
`insertMany(input)`	行をまとめて作成する（最大1000件）
`updateOne(input)`	行を1件更新する（部分更新）
`updateMany(input)`	行をまとめて更新する（部分更新・最大1000件）
`deleteOne(id)`	行を1件削除する
`deleteMany(input)`	行をまとめて削除する（最大1000件）
`Id(id)`	文字列をこのテーブルの行ID型に変換する
`batchCreate(input)`	バッチ用の「1件作成」操作を作る → バッチ
`batchUpdate(input)`	バッチ用の「1件更新」操作を作る → バッチ
`batchDelete(id)`	バッチ用の「1件削除」操作を作る → バッチ

いずれの関数も失敗すると例外を投げます。呼び出し元で try / catch するか、そのままノードを失敗させてスクリプトノードのリトライに任せます。

行を取得する

list() は非同期イテレーターを返します。for await で回すと、次のページを自動的に取得しながら全件をたどれます。

import * as customers from "synqlet:database/{テーブルのID}";

export default async function () {
  for await (const row of customers.list({
    filter: { values: { status: { _eq: "active" } } },
    sort: [{ values: { name: { direction: "asc", nulls: "nullsLast" } } }],
    pageSize: 100,
  })) {
    console.log(row.id, row.values.name);
  }

  return {};
}

パラメータ	既定値	説明
`pageSize`	`50`	1回のリクエストで取得する件数（1〜200）
`filter`	`{}`	絞り込み条件 → フィルター
`sort`	`[]`	並び替え → 並び替え

1件だけ取得する場合は get() を使います。

const row = await customers.get(customers.Id("customer-001"));

取得した行は次の形です。

{
  id: Id; // 行ID
  createdAt: Temporal.Instant; // 作成日時
  updatedAt: Temporal.Instant; // 更新日時
  createdBy: string; // 作成ユーザーID
  updatedBy: string; // 更新ユーザーID
  values: RowValues; // フィールドの値
}

values の型はテーブルのフィールド定義から生成されます。値の型は次のように扱いやすい形に変換されています。

フィールドの型	スクリプト上の値
テキスト / メールアドレス / 電話番号	`string`
数値	`number`
真偽値	`boolean`
URL	`URL`
日時	`Temporal.Instant`
日付 / 時刻 / 年月	`Temporal.PlainDate` / `Temporal.PlainTime` / `Temporal.PlainYearMonth`
ファイル	`FileOutput` → ファイル型フィールドを扱う
レコード / リスト	オブジェクト / 配列

必須でないフィールドの値は null になることがあります。

行ID の型

行ID は、テーブルごとに区別される専用の型（Id）です。文字列から作るには Id() を使います。

const id = customers.Id("customer-001");

別のテーブルの行ID を渡すと型エラーになるため、テーブルを取り違えるミスを防げます。

行を作成する

// ID は自動で割り振られる
const created = await customers.insertOne({
  values: { name: "株式会社サンプル", status: "active" },
});

// ID を指定し、既にあれば更新する（upsert）
await customers.insertOne({
  id: customers.Id("customer-001"),
  values: { name: "株式会社サンプル", status: "active" },
  options: { upsert: true },
});

id を省略すると自動で割り振られます。
id を指定してその行が既に存在する場合、既定ではエラーになります。options.upsert に true を指定すると、既存の行を更新します。

まとめて作成するときは insertMany() を使います（1回につき最大1000件）。

await customers.insertMany({
  data: [
    { values: { name: "A社", status: "active" } },
    {
      id: customers.Id("customer-002"),
      values: { name: "B社", status: "active" },
    },
  ],
  options: { upsert: true },
});

行を更新する

更新は 部分更新 です。指定しなかったフィールドは変更されません。

await customers.updateOne({
  id: customers.Id("customer-001"),
  values: { status: "archived" },
});

await customers.updateMany({
  data: [
    { id: customers.Id("customer-001"), values: { status: "archived" } },
    { id: customers.Id("customer-002"), values: { status: "archived" } },
  ],
});

値を空にしたいときは null を指定します。ただし 必須フィールドは null にできません（省略はできます）。

行を削除する

await customers.deleteOne(customers.Id("customer-001"));

await customers.deleteMany({
  ids: [customers.Id("customer-001"), customers.Id("customer-002")],
});

複数テーブルをまとめて更新する

insertOne() などは呼び出すたびにリクエストが飛ぶため、途中で失敗すると 一部だけ反映された状態 になります。複数の書き込みをすべてまとめて成功・失敗させたいときは、synqlet:database の batchRequest()（結果を名前で受け取る batchRequestKeyed() もあります）を使います。

import { batchRequest } from "synqlet:database";
import * as customers from "synqlet:database/{テーブルのID}";
import * as orders from "synqlet:database/{テーブルのID}";

export default async function () {
  const [customer, order] = await batchRequest([
    customers.batchCreate({
      values: { name: "株式会社サンプル", status: "active" },
    }),
    orders.batchUpdate({
      id: orders.Id("order-001"),
      values: { status: "done" },
    }),
    orders.batchDelete(orders.Id("order-002")),
  ]);

  console.log(customer.id, order.values.status);
  return {};
}

各テーブルの batchCreate() / batchUpdate() / batchDelete() は 操作を作るだけ で、この時点では何も起きません。
batchRequest() に渡したときに 1回のリクエスト・1つのトランザクション でまとめて処理されます。1件でも失敗すると例外になり、途中までの変更は残りません（一部だけ反映されることはありません）。
操作は 配列の先頭から順に 処理されるため、「作成した行を後続の操作で更新する」といった依存のある並びも書けます。
戻り値は渡した操作と同じ順番で、作成・更新は その行、削除は undefined です。テーブルごとの型がそのまま付くので、customer.values は作成したテーブルの型になります。
1回につき 最大1000件 です。

名前で受け取る（batchRequestKeyed）

操作が増えてくると配列の位置で受け取るのは読みにくくなります。batchRequestKeyed() は操作に 名前をつけて渡し、同じ名前で結果を受け取る 版です（Promise.all に対する Promise.allKeyed のようなものです）。

import { batchRequestKeyed } from "synqlet:database";

const { customer, order } = await batchRequestKeyed({
  customer: customers.batchCreate({ values: { name: "株式会社サンプル" } }),
  order: orders.batchUpdate({
    id: orders.Id("order-001"),
    values: { status: "done" },
  }),
});

console.log(customer.values.name, order.values.status);

一貫性の扱いは batchRequest() と同じ（すべて1つのトランザクションで処理され、1件でも失敗すると全体が失敗）で、キーを書いた順 に処理されます。

インポートは、「ライブラリ」パネルの「データベース」タブの先頭にある「バッチ（複数テーブルをまとめて更新）」から挿入できます。

同じテーブル内で完結する一括操作であれば、insertMany() / updateMany() / deleteMany() でも1リクエスト・アトミックに処理されます。バッチはテーブルをまたぐ場合や、作成・更新・削除を混ぜたい場合に使ってください。

フィルター

filter には、システム項目（id / createdAt / updatedAt / createdBy / updatedBy）と、フィールドの値（values）に対する条件を指定します。同時に指定した条件は すべて満たす（AND）扱いです。

customers.list({
  filter: {
    createdAt: { _gte: Temporal.Instant.from("2026-07-01T00:00:00Z") },
    values: {
      name: { _contains: "サンプル" },
      score: { _gte: 50 },
      closedAt: { _isNull: true },
    },
  },
});

指定できる演算子は、フィールドの型によって変わります。

演算子	意味	使える型
`_eq`	等しい	すべて（ID・真偽値はこれのみ）
`_gt` / `_gte` / `_lt` / `_lte`	より大きい / 以上 / より小さい / 以下（日時系は後 / 以降 / 前 / 以前）	文字列系・数値・日時系
`_contains`	含む	文字列系（テキスト / メールアドレス / URL / 電話番号）
`_startsWith`	指定した文字列で始まる	文字列系
`_endsWith`	指定した文字列で終わる	文字列系
`_isNull`	`true` で値がない、`false` で値がある	必須でないフィールド

_contains / _startsWith / _endsWith は大文字・小文字を区別しません。
日時系の条件には Temporal の値をそのまま渡せます。
レコード型・リスト型は絞り込みの対象外です。ファイル型は name / mimeType / size / id で絞り込めます。

AND / OR / NOT を組み合わせる

_and / _or / _not で条件を組み合わせられます。_and / _or は 2件以上 を指定します。

customers.list({
  filter: {
    _or: [
      { values: { status: { _eq: "active" } } },
      { values: { score: { _gte: 80 } } },
    ],
    _not: { values: { name: { _startsWith: "テスト" } } },
  },
});

並び替え

sort は条件の配列です。配列の先頭ほど優先 され、1件につき1つの項目を指定します。direction（asc / desc）と nulls（nullsFirst / nullsLast）の両方が必要です。

customers.list({
  sort: [
    { values: { score: { direction: "desc", nulls: "nullsLast" } } },
    { createdAt: { direction: "asc", nulls: "nullsLast" } },
  ],
});

システム項目（id / createdAt / updatedAt / createdBy / updatedBy）と、フィールドの値（values）を指定できます。
レコード型・リスト型・ファイル型のフィールドは並び替えできません。
最後に行ID の昇順が自動的に追加されるため、ページをまたいでも並び順が安定します。

上限

項目	上限
`list()` の `pageSize`	1〜200（既定 50）
`insertMany()` / `updateMany()` / `deleteMany()` の件数	1000件
`batchRequest()` / `batchRequestKeyed()` の操作数	1000件

件数が多い場合は、1000件ずつに分けて呼び出してください。ファイル型フィールドを持つテーブルは1件ごとにファイルの確認が入るため、件数が多いと時間がかかります。

権限とセキュリティフラグ

スクリプトは、実行しているランナーが属する組織 のテーブル・行のみ読み書きできます。他の組織のテーブルは参照できません。
APIキーやトークンをスクリプト内に用意する必要はありません。ランナーが自動で認証します。
Synqlet API への通信は自動的に許可されるため、セキュリティフラグの「ネットワークアクセス」を設定しなくてもデータベースを操作できます。ファイル型フィールドを持つテーブルを参照している場合は、ファイルの保存先への通信も自動的に許可されます。