検索と絞り込み

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"なら優先度の降順、同じ優先度ではタイトルの昇順です。使えるフィールド種類と最大キー数はクエリ仕様で確認できます。

累計閲覧数の多い順はorders: "-views"、少ない順はorders: "views"です。未計測の記事は0として扱います。PV(ページビュー)で計測を設定できます。

const popular = await genko.apis.blog.list({ orders: "-views", limit: 4 });

フィールドで絞り込む

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階層展開します。非公開の参照先や参照設定の欠損も考慮してください。参照先APIがキーの対象外の場合もIDのままで、展開されません。

必要な項目だけ取得する

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に共通する全パラメータの既定値・上限はクエリ仕様を参照してください。

言語を指定して取得する

多言語を有効にしたAPIでは、langにサブ言語のコードを渡します。省略するとメイン言語の結果です。次の例では、英語版が公開されている原稿だけを取得します。

import { genko } from "@/lib/client";
const { contents, totalCount } = await genko.apis.blog.list({  lang: "en",  include: ["_langs"],});const article = await genko.apis.blog.getOrNull("abcDEF123456", {  lang: "en",  include: ["_langs"],});const allEnglish = await genko.apis.blog.getAll({ lang: "en" });
for (const post of contents) {  console.log(post.id, post._langs?.current, post._langs?.available);}

getAll()は各ページの取得に同じ言語指定を使います。オブジェクト形式ではgenko.apis.profile.get({ lang: "en" })を使います。指定言語の公開版がない場合だけ公開中のメイン言語を使いたいときはlangFallback: trueを追加します。既定ではフォールバックしません。_langs.currentは実際に返した言語、_langs.availableは公開中の言語一覧です。

言語を指定した一覧の検索・絞り込み・並び替え・総件数は、実際に返す言語の値で計算されます。URLのパラメータとエラー条件はクエリ仕様を参照してください。