findMany()

特定の条件に合致したすべての行を取り出したい場合に利用します。

使用できるキー

キー名	内容	省略	備考
where	取得条件の指定	可	書かない場合は全ての行を取得します
select	取得列の表示設定	可	`omit` / `include` と同時に使用できません。リレーションフィールドにオプション指定可
omit	取得列の除外設定	可	`select` と同時に使用できません
include	リレーション先の取得	可	詳細はこちら
orderBy	ソート設定	可	指定する列が 1 つの場合、配列の省略が可能です
take	取得数の設定	可	負数で末尾から取得
skip	スキップ数の設定	可	負数はエラー
distinct	重複削除の設定	可	指定する列が 1 つの場合、配列の省略が可能です
cursor	カーソル位置	可	カーソルベースページネーション

説明例用のシート

説明用シート

説明

上記例から以下の条件の行を取り出したいとします。

pref => Tokyo

この場合以下のコードとなります。

const gassma = new Gassma.GassmaClient();

// gassma.{{TARGET_SHEET_NAME}}.findMany
const result = gassma.sheet1.findMany({
  where: {
    pref: "Tokyo",
  },
});

戻り値は以下の形式です。

[
  { name: "sato", age: 31, pref: "Tokyo", postNumber: "160-0023" },
  { name: "endo", age: 55, pref: "Tokyo", postNumber: "160-0023" },
];

複数の条件を指定したい場合は以下のコードとなります。

const gassma = new Gassma.GassmaClient();

// gassma.{{TARGET_SHEET_NAME}}.findMany
const result = gassma.sheet1.findMany({
  where: {
    pref: "Tokyo",
    年齢: 31,
  },
});

演算子・部分一致

以上・以下や部分一致等の条件付き検索も可能です。例えば以下の条件で行を取り出したいとします。

age => 20 以上
age => 30 以下

この場合以下のコードとなります。

const gassma = new Gassma.GassmaClient();

// gassma.{{TARGET_SHEET_NAME}}.findMany
const result = gassma.sheet1.findMany({
  where: {
    age: {
      gte: 20,
      lte: 30,
    },
  },
});

条件付き検索に関連するキーは以下の通りです。

キー名	役割	例
equals	同値か	eauals: 20
not	同値ではないか	not: 20
in	指定したリストの中にあるか	in: [20, 21, 22]
notIn	指定したリストの中にないか	notIn: [23, 24. 25]
lt	未満	lt: 30
lte	以下	lte: 30
gt	超過	gt: 20
gte	以上	gte: 20
contains	対象データの中に指定した文字列が含まれているか	contains: "AB"
startsWith	対象データが指定した文字列から始まっているか	startsWith: "AB"
endsWith	対象データが指定した文字列で終わっているか	endsWith: "YZ"
mode	大文字小文字の区別設定	mode: "insensitive"

各演算子の値には固定値のほか、fields プロパティを使って同じ行の別の列の値を指定できます。詳しくは fields のリファレンスを参照してください。

mode: "insensitive"

equals、not、contains、startsWith、endsWith に mode: "insensitive" を指定すると、大文字小文字を区別せずに比較できます。

const gassma = new Gassma.GassmaClient();

// "alice"、"Alice"、"ALICE" すべてにマッチ
const result = gassma.sheet1.findMany({
  where: {
    name: {
      equals: "alice",
      mode: "insensitive",
    },
  },
});

contains、startsWith、endsWith でも同様に使用できます。

// "Hello World"、"HELLO WORLD" などにマッチ
const result = gassma.sheet1.findMany({
  where: {
    title: {
      contains: "hello",
      mode: "insensitive",
    },
  },
});

mode を指定しない場合、またはデフォルトの mode: "default" の場合は大文字小文字が区別されます。

AND, OR, NOT

複数条件での検索も可能です。

AND

例えば以下の条件で行を取り出したいとします。

age => 22
pref => Ibaraki

AND を利用して検索する場合以下のようになります。

const gassma = new Gassma.GassmaClient();

// gassma.{{TARGET_SHEET_NAME}}.findMany
const result = gassma.sheet1.findMany({
  where: {
    AND: [
      {
        age: 22,
      },
      {
        pref: "Ibaraki",
      },
    ],
  },
});

OR

例えば以下の条件で行を取り出したいとします。

age => 22 または 40

OR を利用して検索する場合以下のようになります。

const gassma = new Gassma.GassmaClient();

// gassma.{{TARGET_SHEET_NAME}}.findMany
const result = gassma.sheet1.findMany({
  where: {
    OR: [
      {
        age: 22,
      },
      {
        age: 40,
      },
    ],
  },
});

NOT

例えば以下の条件で行を取り出したいとします。

age => 22 ではない
age => 40 ではない

NOT を利用して検索する場合以下のようになります。

const gassma = new Gassma.GassmaClient();

// gassma.{{TARGET_SHEET_NAME}}.findMany
const result = gassma.sheet1.findMany({
  where: {
    NOT: [
      {
        age: 22,
      },
      {
        age: 40,
      },
    ],
  },
});

AND, OR, NOT の重ねがけ

例えば AND の下に OR や NOT を入れることができます。この入れ子構造は GAS のコールスタックが許す限り無限に可能です。

const gassma = new Gassma.GassmaClient();

// gassma.{{TARGET_SHEET_NAME}}.findMany
const result = gassma.sheet1.findMany({
  where: {
    NOT: {
      AND: [
        {
          name: "akahoshi",
        },
        {
          age: 22,
        },
      ],
    },
  },
});

where でのリレーションフィルタ

リレーション定義がある場合、where 内でリレーション先の条件を使ってフィルタリングできます（some、every、none、is、isNot）。

詳しくは where リレーションフィルタのリファレンスを参照してください。

select

戻り値に返るデータを制限することができます。

例えばageとprefのみ取得したい場合は以下のようになります。

const gassma = new Gassma.GassmaClient();

// gassma.{{TARGET_SHEET_NAME}}.findMany
const result = gassma.sheet1.findMany({
  where: {
    age: {
      gte: 20,
    },
  },
  select: {
    name: true,
    pref: true,
  },
});

戻り値は以下のようになります。

[
  { name: "akahoshi", pref: "Ibaraki" },
  { name: "sato", pref: "Tokyo" },
  { name: "suzuki", pref: "Osaka" },
  { name: "yamamoto", pref: "Aichi" },
  { name: "ono", pref: "Shiga" },
  { name: "kudo", pref: "Kyoto" },
  { name: "kondo", pref: "Tottori" },
  { name: "endo", pref: "Tokyo" },
  { name: "murakami", pref: "Fukuoka" },
];

select 内でのリレーションオプション指定

リレーション定義がある場合、select 内のリレーションフィールドに include と同様のオプションを指定できます。include を別途指定する代わりに、select 内でリレーション先のデータ取得を制御できます。

const gassma = new Gassma.GassmaClient({
  relations: {
    Users: {
      posts: { type: "oneToMany", to: "Posts", field: "id", reference: "authorId" },
    },
  },
});

const result = gassma.Users.findMany({
  select: {
    id: true,
    name: true,
    posts: {
      select: { id: true, title: true },
      where: { published: true },
      orderBy: { id: "desc" },
    },
    _count: true,
  },
});

リレーションフィールドに指定できるオプションは include のオプションと同じです（select、where、orderBy、include、omit、take、skip）。

深いネストも対応しています。

const result = gassma.Users.findMany({
  select: {
    id: true,
    posts: {
      select: {
        id: true,
        comments: {
          select: { id: true, text: true },
        },
      },
    },
  },
});

注意

トップレベルの select と include は同時に使用できません。リレーション先のデータが必要な場合は select 内でリレーションオプションを指定するか、include を単独で使用してください。

orderBy

取得した行をソートすることができます。

例えばageで昇順でソートする場合は以下のようになります。

const gassma = new Gassma.GassmaClient();

// gassma.{{TARGET_SHEET_NAME}}.findMany
const result = gassma.sheet1.findMany({
  where: {
    age: {
      gte: 20,
    },
  },
  orderBy: {
    age: "asc",
  },
});

指定できるデータは以下の通りです。

キー名	意味
asc	昇順
desc	降順

null 値の並び順制御

オブジェクト形式で nulls オプションを指定すると、null 値の並び位置を制御できます。

const gassma = new Gassma.GassmaClient();

// null 値を最後に配置
const result = gassma.sheet1.findMany({
  orderBy: {
    age: { sort: "asc", nulls: "last" },
  },
});
// => [20, 22, 31, 40, 55, null, null]

nulls の値	動作
`"first"`	null 値を先頭に配置
`"last"`	null 値を末尾に配置

nulls を指定しない場合、asc では null が先頭に、desc では null が末尾に配置されます。

また、複数ソートの条件を指定することもでき、例えば

ageで昇順でソート
ageの値が同じ行があればその部分はnameの昇順でソート

といったことを行いたい場合コードは以下のようになります。

const gassma = new Gassma.GassmaClient();

// gassma.{{TARGET_SHEET_NAME}}.findMany
const result = gassma.sheet1.findMany({
  where: {
    age: {
      gte: 20,
    },
  },
  orderBy: [{ age: "asc" }, { name: "asc" }],
});

※ソートの優先順位はインデックス番号の若い順となります。

リレーションフィールドでのソート

リレーション定義がある場合、manyToOne / oneToOne のリレーション先フィールドでソートできます。

const gassma = new Gassma.GassmaClient({
  relations: {
    Posts: {
      author: {
        type: "manyToOne",
        to: "Users",
        field: "authorId",
        reference: "id",
      },
    },
  },
});

// 投稿を著者名の昇順でソート
const result = gassma.Posts.findMany({
  orderBy: { author: { name: "asc" } },
});

FK が null のレコードは asc で先頭、desc で末尾に配置されます。

注意

oneToMany / manyToMany のリレーションではフィールドソートはできません。RelationOrderByUnsupportedTypeError がスローされます。

_count でのソート

oneToMany / manyToMany のリレーション件数でソートできます。

// 投稿数の多い順にユーザーをソート
const result = gassma.Users.findMany({
  orderBy: { posts: { _count: "desc" } },
});

スカラーソートと組み合わせることもできます。

// 投稿数の降順 → 同数なら名前の昇順
const result = gassma.Users.findMany({
  orderBy: [
    { posts: { _count: "desc" } },
    { name: "asc" },
  ],
});

注意

manyToOne / oneToOne のリレーションでは _count ソートはできません。RelationOrderByCountUnsupportedTypeError がスローされます。

take

取得数を指定できます。取得数はシートの上の行から順となります。

例えば条件に合致した行の中から上から 2 行を取得したい場合以下のようになります。

const gassma = new Gassma.GassmaClient();

// gassma.{{TARGET_SHEET_NAME}}.findMany
const result = gassma.sheet1.findMany({
  where: {
    age: {
      gte: 20,
    },
  },
  take: 2,
});

take に負数を指定した場合

take に負数を指定すると、末尾から N 件を取得します。

// 条件に合致した行の末尾 2 件を取得
const result = gassma.sheet1.findMany({
  where: {
    age: { gte: 20 },
  },
  take: -2,
});

take が負数の場合、skip の方向も逆転します。skip は末尾から除外する件数になります。

// 末尾 1 件を除外した後、残りの末尾 2 件を取得
const result = gassma.sheet1.findMany({
  take: -2,
  skip: 1,
});

skip

取得した行の中から特定行をスキップできます。

例えば条件に合致した行の中から上 1 つ目を省きたい場合、コードは以下のようになります。

const gassma = new Gassma.GassmaClient();

// gassma.{{TARGET_SHEET_NAME}}.findMany
const result = gassma.sheet1.findMany({
  where: {
    age: {
      gte: 20,
    },
  },
  skip: 1,
});

注意

skip に負数を指定すると GassmaSkipNegativeError がスローされます。

cursor

カーソルベースのページネーションを行えます。cursor にレコードを一意に特定するオブジェクトを指定すると、そのレコードを起点として取得します。

const gassma = new Gassma.GassmaClient();

// id: 3 のレコードを起点に、そこから 5 件取得
const result = gassma.sheet1.findMany({
  cursor: { id: 3 },
  take: 5,
});

take が正数の場合、cursor の位置から末尾方向に取得します。take が負数の場合、先頭から cursor の位置までを取得します。

// id: 3 を起点に、先頭方向のデータを取得
const result = gassma.sheet1.findMany({
  cursor: { id: 3 },
  take: -5,
});

skip と組み合わせると、cursor 位置からさらにスキップできます。

// id: 3 を起点に、1 件スキップして 5 件取得
const result = gassma.sheet1.findMany({
  cursor: { id: 3 },
  skip: 1,
  take: 5,
});

注記

cursor に指定したレコードが見つからない場合は空配列が返されます。

処理順序

cursor を含む場合の実行順序は以下の通りです。

where - フィルター
orderBy - ソート
distinct - 重複削除
cursor - カーソル位置で切り出し
skip / take - ページネーション
select / omit - フィールド整形

omit

戻り値から特定の列を除外することができます。select の逆の動作です。

例えばpostNumberを除外したい場合は以下のようになります。

const gassma = new Gassma.GassmaClient();

// gassma.{{TARGET_SHEET_NAME}}.findMany
const result = gassma.sheet1.findMany({
  where: {
    pref: "Tokyo",
  },
  omit: {
    postNumber: true,
  },
});

戻り値は以下のようになります。

[
  { name: "sato", age: 31, pref: "Tokyo" },
  { name: "endo", age: 55, pref: "Tokyo" },
];

注意

select と omit は同時に使用できません。両方指定すると GassmaFindSelectOmitConflictError がスローされます。

グローバル omit を設定している場合、クエリの omit で { field: false } を指定することでグローバル omit を上書きできます。詳しくはクエリ omit でグローバル omit を上書きを参照してください。

distinct

列名を指定し、もし値が被っている場合その行を省略できます。被っている場合は上の行のデータが優先されます。

例えばageの被りを省略する場合、コードは以下のようになります。

const gassma = new Gassma.GassmaClient();

// gassma.{{TARGET_SHEET_NAME}}.findMany
const result = gassma.sheet1.findMany({
  where: {
    age: {
      gte: 20,
    },
  },
  distinct: ["age"],
});

include

リレーション定義がある場合、リレーション先のデータを一緒に取得できます。

詳しくはinclude のリファレンスを参照してください。

使用できるキー​

説明例用のシート​

説明​

演算子・部分一致​

mode: "insensitive"​

AND, OR, NOT​

AND​

OR​

NOT​

AND, OR, NOT の重ねがけ​

where でのリレーションフィルタ​

select​

select 内でのリレーションオプション指定​

orderBy​

null 値の並び順制御​

リレーションフィールドでのソート​

_count でのソート​

take​

take に負数を指定した場合​

skip​

cursor​

処理順序​

omit​

distinct​

include​

使用できるキー

説明例用のシート

説明

演算子・部分一致

mode: "insensitive"

AND, OR, NOT

AND

OR

NOT

AND, OR, NOT の重ねがけ

where でのリレーションフィルタ

select

select 内でのリレーションオプション指定

orderBy

null 値の並び順制御

リレーションフィールドでのソート

_count でのソート

take

take に負数を指定した場合

skip

cursor

処理順序

omit

distinct

include