検索と絞り込み

SDKからのページング、フィルタービルダー、参照展開、フィールド選択の実例。

list()とgetAll()は、検索・絞り込み・並び替えを指定できます。getAll()ではページングを内部で行うため、limit／offsetは指定できません。

以下の応用例は、blogにcategory（単一セレクト）、featured（真偽値）、priority（数字）、author（参照）を追加した場合を想定しています。スキーマを変更したらpullで型を同期してください。

ページングと並び替え

import { genko } from "@/lib/client";

const page = 2;
const pageSize = 10;
const result = await genko.apis.blog.list({
  limit: pageSize,
  offset: (page - 1) * pageSize,
  orders: "-publishedAt",
});

const hasNext = result.offset + result.contents.length < result.totalCount;

orders: "-priority,title"なら優先度の降順、同じ優先度ではタイトルの昇順です。使えるフィールド種類と最大キー数はクエリ仕様で確認できます。

フィールドで絞り込む

import { buildFilters } from "@genko-me/sdk";
import { genko } from "@/lib/client";

const filters = buildFilters()
  .equals("featured", true)
  .and()
  .greaterThan("priority", 3);

const result = await genko.apis.blog.list({ filters });

文字列の"featured[equals]true[and]priority[greater_than]3"を渡しても同じ条件です。ビルダーは文字列の組み立てを補助しますが、フィールドIDとスキーマの整合性を型検査するものではありません。

メソッド	意味
`equals` / `notEquals`	完全一致／不一致
`contains` / `notContains`	部分一致、または配列要素の一致／不一致
`greaterThan` / `lessThan`	境界を含まない大小比較
`exists` / `notExists`	値の存在／不在
`and` / `or`	条件の連結

値には文字列・数値・真偽値・Dateを渡せます。DateはISO 8601へ変換されます。existsとnotExistsは値を取りません。

同じ式でandとorを混ぜると例外になります。演算子と種類が一致しない場合などは、配信APIが400を返します。

テキスト検索と組み合わせる

const result = await genko.apis.blog.list({
  q: "新機能",
  filters: "category[equals]news",
  orders: "-publishedAt",
});

テキスト系フィールドの部分一致で「新機能」を含み、かつカテゴリがnewsの記事を取得します。qは関連度によるランキングや画像内文字の検索ではありません。

参照の展開を指定する

const post = await genko.apis.blog.getOrNull("abcDEF123456", { depth: 1 });
const author = post?.author;

if (author && typeof author === "object" && "name" in author) {
  if (typeof author.name === "string") console.log(author.name);
}

参照は生成型がunknownなので、上の例では形を確認して使います。depth: 0ではID、depth: 1では1階層、depth: 2では2階層展開します。非公開の参照先や参照設定の欠損も考慮してください。

必要な項目だけ取得する

const { contents } = await genko.apis.blog.list({
  fields: ["title", "publishedAt"],
  depth: 0,
});

for (const post of contents) {
  console.log(post.id, post.title);
}

idは常に返ります。指定しなかった本文などはレスポンスに含まれません。戻り値のTypeScript型は自動で縮小されないため、型チェックが通ってもpost.bodyが実際にあるとは限りません。

HTTPとSDKに共通する全パラメータの既定値・上限はクエリ仕様を参照してください。