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

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

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

インポートする

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

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

ノート

テーブルのフィールドを変更すると、生成される型も自動的に追従します。存在しないフィールドを参照しているとエディタ上で型エラーになります。

使える関数

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

いずれの関数も失敗すると例外を投げます。呼び出し元で 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回につき最大100件）。

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")],
});

フィルター

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() の件数	100件

件数が多い場合は、100件ずつに分けて呼び出してください。

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

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

注意

外部 API の呼び出しなど、データベース以外の通信を行う場合は、これまでどおり「ネットワークアクセス」の許可が必要です。

関連ページ

• ファイル型フィールドを扱う
• テーブルとフィールドを設計する
• スクリプトを書く
• データベースの REST API