// --- Cursor エンコード/デコード ---
 
/**
 * カーソルデータをBase64urlエンコードする。
 * Base64url を使う理由:
 *   - URL safe（+, /, = を使わない）
 *   - クエリパラメータにそのまま渡せる
 *   - クライアントにとって不透明（opaque）
 */
function encodeCursor(data) {
  return Buffer.from(JSON.stringify(data)).toString('base64url');
}
 
/**
 * Base64urlエンコードされたカーソルをデコードする。
 * 不正なカーソルに対してはエラーを投げる。
 */
function decodeCursor(cursor) {
  try {
    const decoded = JSON.parse(
      Buffer.from(cursor, 'base64url').toString()
    );
    // バリデーション: 必要なフィールドが存在するか
    if (!decoded.id) {
      throw new Error('Invalid cursor: missing id');
    }
    return decoded;
  } catch (err) {
    throw new ApiError(400, 'Invalid cursor format');
  }
}
 
// --- Cursorページネーション ---
async function listUsers(params) {
  const {
    cursor,
    limit = 20,
    sort = 'createdAt',
    order = 'desc',
  } = params;
 
  // limit の上限を設ける（DoS防止）
  const take = Math.min(Math.max(limit, 1), 100);
 
  // ソートフィールドのホワイトリスト検証
  const allowedSortFields = ['createdAt', 'updatedAt', 'name', 'email'];
  if (!allowedSortFields.includes(sort)) {
    throw new ApiError(400, `Invalid sort field: ${sort}`);
  }
 
  let where = {};
  if (cursor) {
    const decoded = decodeCursor(cursor);
    // 複合カーソル: ソートキー + ID でタイブレーク
    // (created_at, id) の複合比較で一意性を保証
    where = {
      OR: [
        {
          [sort]: order === 'desc'
            ? { lt: decoded[sort] }
            : { gt: decoded[sort] },
        },
        {
          [sort]: decoded[sort],
          id: order === 'desc'
            ? { lt: decoded.id }
            : { gt: decoded.id },
        },
      ],
    };
  }
 
  // take + 1 件取得して hasNextPage を判定する技法
  // 余分な1件が取れたら「次のページが存在する」
  const items = await prisma.user.findMany({
    where,
    orderBy: [{ [sort]: order }, { id: order }],
    take: take + 1,
  });
 
  const hasNextPage = items.length > take;
  const data = hasNextPage ? items.slice(0, take) : items;
 
  return {
    data,
    meta: {
      hasNextPage,
      nextCursor: hasNextPage
        ? encodeCursor({
            [sort]: data[data.length - 1][sort],
            id: data[data.length - 1].id,
          })
        : null,
      hasPrevPage: !!cursor,
      prevCursor: data.length > 0
        ? encodeCursor({
            [sort]: data[0][sort],
            id: data[0].id,
          })
        : null,
      limit: take,
    },
  };
}

-- 複合ソート: priority DESC, created_at DESC, id DESC
-- カーソル位置: priority=3, created_at='2024-06-01', id=500
 
-- 方法1: OR条件の展開（全DBで動作）
SELECT * FROM tasks
WHERE
  (priority < 3)
  OR (priority = 3 AND created_at < '2024-06-01')
  OR (priority = 3 AND created_at = '2024-06-01' AND id < 500)
ORDER BY priority DESC, created_at DESC, id DESC
LIMIT 20;
 
-- 方法2: 行値比較（PostgreSQL, MySQL 8.0+ で動作）
SELECT * FROM tasks
WHERE (priority, created_at, id) < (3, '2024-06-01', 500)
ORDER BY priority DESC, created_at DESC, id DESC
LIMIT 20;
 
-- 方法2 は簡潔だが、混合ソート順（ASC/DESC混在）には使えない。
-- 混合ソート順の場合は方法1のOR展開が必須。

// 複合ソートキーのカーソル実装（Node.js）
function buildCursorWhere(sortKeys, cursorData, orders) {
  // sortKeys: ['priority', 'createdAt', 'id']
  // cursorData: { priority: 3, createdAt: '2024-06-01', id: 500 }
  // orders: ['desc', 'desc', 'desc']
 
  const conditions = [];
 
  for (let i = 0; i < sortKeys.length; i++) {
    const condition = {};
 
    // 前のキーが全て等しい
    for (let j = 0; j < i; j++) {
      condition[sortKeys[j]] = cursorData[sortKeys[j]];
    }
 
    // 現在のキーが比較条件を満たす
    const op = orders[i] === 'desc' ? 'lt' : 'gt';
    condition[sortKeys[i]] = { [op]: cursorData[sortKeys[i]] };
 
    conditions.push(condition);
  }
 
  return { OR: conditions };
}
 
// 使用例
const where = buildCursorWhere(
  ['priority', 'createdAt', 'id'],
  { priority: 3, createdAt: '2024-06-01T00:00:00Z', id: 500 },
  ['desc', 'desc', 'desc']
);
// → { OR: [
//      { priority: { lt: 3 } },
//      { priority: 3, createdAt: { lt: '2024-06-01T00:00:00Z' } },
//      { priority: 3, createdAt: '2024-06-01T00:00:00Z', id: { lt: 500 } },
//   ]}

const crypto = require('crypto');
 
const CURSOR_SECRET = process.env.CURSOR_SECRET; // 十分な長さのランダム文字列
 
/**
 * 署名付きカーソルを生成する。
 * フォーマット: base64url(JSON) + "." + hmac_signature
 */
function encodeSecureCursor(data) {
  const payload = Buffer.from(JSON.stringify(data)).toString('base64url');
  const hmac = crypto
    .createHmac('sha256', CURSOR_SECRET)
    .update(payload)
    .digest('base64url');
  return `${payload}.${hmac}`;
}
 
/**
 * 署名付きカーソルを検証・デコードする。
 * 署名が不正な場合は例外を投げる。
 */
function decodeSecureCursor(cursor) {
  const [payload, signature] = cursor.split('.');
  if (!payload || !signature) {
    throw new ApiError(400, 'Invalid cursor format');
  }
 
  // HMAC検証（タイミング攻撃を防ぐため timingSafeEqual を使用）
  const expected = crypto
    .createHmac('sha256', CURSOR_SECRET)
    .update(payload)
    .digest('base64url');
 
  if (!crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  )) {
    throw new ApiError(400, 'Invalid cursor signature');
  }
 
  return JSON.parse(Buffer.from(payload, 'base64url').toString());
}

# Connection 仕様に準拠した GraphQL スキーマ
 
type Query {
  # 前方ページネーション: first + after
  # 後方ページネーション: last + before
  users(
    first: Int
    after: String
    last: Int
    before: String
    filter: UserFilter
    orderBy: UserOrderBy
  ): UserConnection!
}
 
type UserConnection {
  edges: [UserEdge!]!
  pageInfo: PageInfo!
  totalCount: Int        # 拡張: 総件数
}
 
type UserEdge {
  cursor: String!
  node: User!
}
 
type PageInfo {
  hasNextPage: Boolean!
  hasPreviousPage: Boolean!
  startCursor: String
  endCursor: String
}
 
type User {
  id: ID!
  name: String!
  email: String!
  role: UserRole!
  createdAt: DateTime!
}
 
input UserFilter {
  role: UserRole
  status: UserStatus
  createdAfter: DateTime
  createdBefore: DateTime
  search: String
}
 
input UserOrderBy {
  field: UserSortField!
  direction: SortDirection!
}
 
enum UserSortField {
  CREATED_AT
  NAME
  EMAIL
}
 
enum SortDirection {
  ASC
  DESC
}
 
enum UserRole {
  ADMIN
  EDITOR
  VIEWER
}
 
enum UserStatus {
  ACTIVE
  INACTIVE
  SUSPENDED
}

// GraphQL Relay Connection リゾルバ実装（Node.js + Prisma）
 
const resolvers = {
  Query: {
    users: async (_, args, context) => {
      const {
        first, after,
        last, before,
        filter, orderBy,
      } = args;
 
      // first と last の同時指定は禁止
      if (first != null && last != null) {
        throw new UserInputError(
          'Cannot specify both "first" and "last"'
        );
      }
 
      // どちらも指定なしの場合はデフォルト
      const limit = first ?? last ?? 20;
      const clampedLimit = Math.min(Math.max(limit, 1), 100);
 
      // フィルタ条件の構築
      const where = buildFilterWhere(filter);
 
      // ソート条件の構築
      const sort = orderBy
        ? { field: orderBy.field, dir: orderBy.direction }
        : { field: 'CREATED_AT', dir: 'DESC' };
 
      const sortField = sortFieldMap[sort.field]; // CREATED_AT → createdAt
      const sortDir = sort.dir.toLowerCase();
 
      // カーソルのデコードと WHERE 条件の追加
      if (after) {
        const cursorData = decodeCursor(after);
        const cursorWhere = buildCursorWhere(
          [sortField, 'id'],
          cursorData,
          [sortDir, sortDir]
        );
        Object.assign(where, cursorWhere);
      }
 
      if (before) {
        const cursorData = decodeCursor(before);
        // before の場合は逆方向
        const reverseDir = sortDir === 'desc' ? 'asc' : 'desc';
        const cursorWhere = buildCursorWhere(
          [sortField, 'id'],
          cursorData,
          [reverseDir, reverseDir]
        );
        Object.assign(where, cursorWhere);
      }
 
      // クエリ実行（take + 1 で hasMore 判定）
      let items = await context.prisma.user.findMany({
        where,
        orderBy: [
          { [sortField]: last ? reverseSortDir(sortDir) : sortDir },
          { id: last ? reverseSortDir(sortDir) : sortDir },
        ],
        take: clampedLimit + 1,
      });
 
      // last の場合は結果を反転
      if (last) {
        items = items.reverse();
      }
 
      const hasMore = items.length > clampedLimit;
      const nodes = hasMore ? items.slice(0, clampedLimit) : items;
 
      // totalCount の取得（オプション）
      const totalCount = await context.prisma.user.count({ where });
 
      // Connection オブジェクトの構築
      const edges = nodes.map(node => ({
        cursor: encodeCursor({
          [sortField]: node[sortField],
          id: node.id,
        }),
        node,
      }));
 
      return {
        edges,
        pageInfo: {
          hasNextPage: first != null ? hasMore : !!before,
          hasPreviousPage: last != null ? hasMore : !!after,
          startCursor: edges.length > 0 ? edges[0].cursor : null,
          endCursor: edges.length > 0
            ? edges[edges.length - 1].cursor
            : null,
        },
        totalCount,
      };
    },
  },
};
 
function reverseSortDir(dir) {
  return dir === 'desc' ? 'asc' : 'desc';
}
 
const sortFieldMap = {
  CREATED_AT: 'createdAt',
  NAME: 'name',
  EMAIL: 'email',
};

# 前方ページネーション（最初の10件、その後続き）
query GetUsers {
  users(first: 10, filter: { role: ADMIN }) {
    edges {
      cursor
      node {
        id
        name
        email
        role
        createdAt
      }
    }
    pageInfo {
      hasNextPage
      hasPreviousPage
      startCursor
      endCursor
    }
    totalCount
  }
}
 
# 次のページを取得（endCursor を after に渡す）
query GetNextPage {
  users(first: 10, after: "eyJjcmVhdGVkQXQiOiIyMDI0LTAxLTE1IiwiaWQiOjEwMH0") {
    edges {
      cursor
      node {
        id
        name
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}
 
# 後方ページネーション（最後の5件を取得）
query GetLastUsers {
  users(last: 5) {
    edges {
      cursor
      node {
        id
        name
      }
    }
    pageInfo {
      hasPreviousPage
      startCursor
    }
  }
}

// フィルタパーサーの実装例（セキュリティ考慮済み）
 
/**
 * クエリパラメータからフィルタ条件を抽出する。
 * filter[field][operator] 形式をパースする。
 *
 * セキュリティ上の重要ポイント:
 * - 許可されたフィールドのみ受け付ける（ホワイトリスト）
 * - 許可された演算子のみ受け付ける
 * - 値のサニタイゼーション
 */
function parseFilters(query, schema) {
  const filters = {};
 
  // スキーマ定義（許可フィールドと型情報）
  const allowedFields = schema || {
    status:    { type: 'enum',    values: ['active', 'inactive', 'suspended'] },
    role:      { type: 'enum',    values: ['admin', 'editor', 'viewer'] },
    age:       { type: 'integer', min: 0, max: 200 },
    name:      { type: 'string',  maxLength: 100 },
    email:     { type: 'string',  maxLength: 254 },
    createdAt: { type: 'datetime' },
  };
 
  const allowedOperators = [
    'eq', 'ne', 'gt', 'gte', 'lt', 'lte',
    'in', 'nin', 'contains', 'starts', 'exists', 'between',
  ];
 
  for (const [key, value] of Object.entries(query)) {
    // filter[field][operator] パターンのパース
    const match = key.match(/^filter\(\w+)\\])?$/);
    if (!match) continue;
 
    const field = match[1];
    const operator = match[2] || 'eq';
 
    // フィールド検証
    if (!allowedFields[field]) {
      continue; // 未知のフィールドは無視（エラーにしてもよい）
    }
 
    // 演算子検証
    if (!allowedOperators.includes(operator)) {
      continue;
    }
 
    // 値のバリデーション
    const validated = validateFilterValue(
      value, allowedFields[field], operator
    );
    if (validated === null) continue;
 
    if (!filters[field]) filters[field] = {};
 
    if (operator === 'in' || operator === 'nin') {
      filters[field][operator] = value.split(',').map(v => v.trim());
    } else if (operator === 'between') {
      const [min, max] = value.split(',').map(v => v.trim());
      filters[field]['gte'] = min;
      filters[field]['lte'] = max;
    } else {
      filters[field][operator] = validated;
    }
  }
 
  return filters;
}
 
/**
 * フィルタ値のバリデーション
 */
function validateFilterValue(value, fieldSchema, operator) {
  switch (fieldSchema.type) {
    case 'enum':
      if (operator === 'in' || operator === 'nin') {
        const values = value.split(',');
        return values.every(v => fieldSchema.values.includes(v.trim()))
          ? value : null;
      }
      return fieldSchema.values.includes(value) ? value : null;
 
    case 'integer': {
      const num = parseInt(value, 10);
      if (isNaN(num)) return null;
      if (fieldSchema.min != null && num < fieldSchema.min) return null;
      if (fieldSchema.max != null && num > fieldSchema.max) return null;
      return num;
    }
 
    case 'string':
      if (value.length > (fieldSchema.maxLength || 1000)) return null;
      // SQLインジェクション対策: パラメータバインディングで処理するため
      // ここでのエスケープは不要だが、長さは制限する
      return value;
 
    case 'datetime': {
      const date = new Date(value);
      return isNaN(date.getTime()) ? null : value;
    }
 
    default:
      return value;
  }
}
 
// Prisma WHERE句への変換
function filtersToPrismaWhere(filters) {
  const where = {};
  const operatorMap = {
    eq: 'equals', ne: 'not', gt: 'gt', gte: 'gte',
    lt: 'lt', lte: 'lte', in: 'in', nin: 'notIn',
    contains: 'contains', starts: 'startsWith',
    exists: (v) => v === 'true' ? { not: null } : null,
  };
 
  for (const [field, ops] of Object.entries(filters)) {
    where[field] = {};
    for (const [op, value] of Object.entries(ops)) {
      const prismaOp = operatorMap[op];
      if (typeof prismaOp === 'function') {
        where[field] = prismaOp(value);
      } else {
        where[field][prismaOp] = value;
      }
    }
  }
 
  return where;
}

// ソートパーサー（安定ソート保証付き）
function parseSort(sortParam, allowedFields) {
  const DEFAULT_SORT = [{ createdAt: 'desc' }, { id: 'desc' }];
 
  if (!sortParam) return DEFAULT_SORT;
 
  const orderBy = sortParam.split(',').map(field => {
    const desc = field.startsWith('-');
    const name = desc ? field.slice(1) : field;
 
    // ホワイトリスト検証
    if (!allowedFields.includes(name)) {
      throw new ApiError(400, `Invalid sort field: ${name}`);
    }
 
    // snake_case → camelCase 変換
    const camelName = name.replace(/_([a-z])/g, (_, c) => c.toUpperCase());
 
    return { [camelName]: desc ? 'desc' : 'asc' };
  });
 
  // 安定ソートのため、最後に id を追加（重複がなければ）
  const hasId = orderBy.some(o => 'id' in o);
  if (!hasId) {
    // 最初のソートの方向に合わせる
    const firstDir = Object.values(orderBy[0])[0];
    orderBy.push({ id: firstDir });
  }
 
  return orderBy;
}
 
// 使用例
const orderBy = parseSort(
  req.query.sort,    // "-created_at,name"
  ['created_at', 'name', 'email', 'updated_at']
);
// → [{ createdAt: 'desc' }, { name: 'asc' }, { id: 'desc' }]

// フィールド選択の実装
function parseFields(fieldsParam, allowedFields) {
  if (!fieldsParam) return undefined; // 全フィールド返却
 
  const requested = fieldsParam.split(',').map(f => f.trim());
 
  // ホワイトリスト検証
  const valid = requested.filter(f => allowedFields.includes(f));
 
  // id は常に含める
  if (!valid.includes('id')) {
    valid.unshift('id');
  }
 
  // Prisma の select に変換
  const select = {};
  for (const field of valid) {
    select[field] = true;
  }
 
  return select;
}
 
// 使用例
const select = parseFields(
  req.query.fields,
  ['id', 'name', 'email', 'role', 'createdAt', 'updatedAt']
);
// fields=name,email → { id: true, name: true, email: true }

-- PostgreSQL での全文検索セットアップ
 
-- 1. tsvector カラムの追加
ALTER TABLE users ADD COLUMN search_vector tsvector;
 
-- 2. トリガーで自動更新
CREATE OR REPLACE FUNCTION update_search_vector()
RETURNS trigger AS $$
BEGIN
  NEW.search_vector :=
    setweight(to_tsvector('simple', COALESCE(NEW.name, '')), 'A') ||
    setweight(to_tsvector('simple', COALESCE(NEW.email, '')), 'B') ||
    setweight(to_tsvector('simple', COALESCE(NEW.bio, '')), 'C');
  RETURN NEW;
END;
$$ LANGUAGE plpgsql;
 
CREATE TRIGGER users_search_vector_trigger
  BEFORE INSERT OR UPDATE ON users
  FOR EACH ROW EXECUTE FUNCTION update_search_vector();
 
-- 3. GIN インデックスの作成
CREATE INDEX idx_users_search_vector ON users USING GIN (search_vector);
 
-- 4. 検索クエリ
SELECT
  id, name, email,
  ts_rank(search_vector, query) AS relevance
FROM users,
  to_tsquery('simple', 'taro') AS query
WHERE search_vector @@ query
ORDER BY relevance DESC
LIMIT 20;
 
-- 5. 前方一致（オートコンプリート用）
SELECT id, name
FROM users
WHERE name ILIKE 'tar%'
ORDER BY name
LIMIT 10;
 
-- 6. pg_trgm による類似検索（typo耐性）
CREATE EXTENSION IF NOT EXISTS pg_trgm;
CREATE INDEX idx_users_name_trgm ON users USING GIN (name gin_trgm_ops);
 
SELECT id, name, similarity(name, 'trao') AS sim
FROM users
WHERE name % 'trao'  -- similarity threshold (default 0.3)
ORDER BY sim DESC
LIMIT 10;

// routes/users.js - 統合的なリスト取得エンドポイント
 
const express = require('express');
const router = express.Router();
 
/**
 * GET /api/v1/users
 *
 * クエリパラメータ:
 *   - page / per_page     : Offset方式ページネーション
 *   - cursor / limit      : Cursor方式ページネーション
 *   - filter[field][op]   : フィルタリング
 *   - sort                : ソート（-prefix で降順）
 *   - fields              : フィールド選択
 *   - q                   : 全文検索
 *   - include_total       : 総件数を含めるか
 */
router.get('/users', async (req, res, next) => {
  try {
    const {
      page, per_page, cursor, limit,
      sort, fields, q, include_total,
    } = req.query;
 
    // --- ページネーション方式の判定 ---
    const useCursor = cursor != null || (page == null && cursor == null);
    // cursor パラメータがある、または何も指定なしの場合は Cursor 方式
 
    // --- フィルタの解析 ---
    const filters = parseFilters(req.query, USERS_FILTER_SCHEMA);
    const where = filtersToPrismaWhere(filters);
 
    // --- 全文検索の統合 ---
    if (q) {
      // PostgreSQL 全文検索を WHERE に統合
      where.searchVector = {
        search: q.split(/\s+/).join(' & '),
      };
    }
 
    // --- ソートの解析 ---
    const orderBy = parseSort(sort, USERS_SORT_FIELDS);
 
    // --- フィールド選択 ---
    const select = parseFields(fields, USERS_ALLOWED_FIELDS);
 
    let result;
 
    if (useCursor) {
      // --- Cursor 方式 ---
      result = await cursorPaginate({
        model: prisma.user,
        where,
        orderBy,
        select,
        cursor,
        limit: limit ? parseInt(limit, 10) : 20,
      });
    } else {
      // --- Offset 方式 ---
      const pageNum = Math.max(parseInt(page, 10) || 1, 1);
      const perPage = Math.min(
        Math.max(parseInt(per_page, 10) || 20, 1),
        100
      );
 
      result = await offsetPaginate({
        model: prisma.user,
        where,
        orderBy,
        select,
        page: pageNum,
        perPage,
        includeTotal: include_total === 'true',
      });
    }
 
    // --- レスポンスヘッダの設定 ---
    if (result.meta.total != null) {
      res.set('X-Total-Count', result.meta.total.toString());
    }
 
    // Link ヘッダ（RFC 8288）
    if (result.links) {
      const linkParts = Object.entries(result.links)
        .filter(([, url]) => url != null)
        .map(([rel, url]) => `<${url}>; rel="${rel}"`);
      if (linkParts.length > 0) {
        res.set('Link', linkParts.join(', '));
      }
    }
 
    res.json(result);
  } catch (err) {
    next(err);
  }
});
 
// --- Cursor ページネーション関数 ---
async function cursorPaginate({ model, where, orderBy, select, cursor, limit }) {
  const take = Math.min(Math.max(limit, 1), 100);
 
  if (cursor) {
    const decoded = decodeCursor(cursor);
    const sortField = Object.keys(orderBy[0])[0];
    const sortDir = Object.values(orderBy[0])[0];
    const cursorWhere = buildCursorWhere(
      [sortField, 'id'],
      decoded,
      [sortDir, sortDir]
    );
    // 既存の where と AND 結合
    if (cursorWhere.OR) {
      where.AND = where.AND || [];
      where.AND.push(cursorWhere);
    }
  }
 
  const items = await model.findMany({
    where,
    orderBy,
    select,
    take: take + 1,
  });
 
  const hasNextPage = items.length > take;
  const data = hasNextPage ? items.slice(0, take) : items;
 
  const sortField = Object.keys(orderBy[0])[0];
 
  return {
    data,
    meta: {
      hasNextPage,
      nextCursor: hasNextPage
        ? encodeCursor({
            [sortField]: data[data.length - 1][sortField],
            id: data[data.length - 1].id,
          })
        : null,
      hasPrevPage: !!cursor,
      prevCursor: data.length > 0
        ? encodeCursor({
            [sortField]: data[0][sortField],
            id: data[0].id,
          })
        : null,
      limit: take,
    },
  };
}
 
// --- Offset ページネーション関数 ---
async function offsetPaginate({
  model, where, orderBy, select, page, perPage, includeTotal,
}) {
  const skip = (page - 1) * perPage;
 
  const [data, total] = await Promise.all([
    model.findMany({
      where,
      orderBy,
      select,
      skip,
      take: perPage,
    }),
    includeTotal ? model.count({ where }) : Promise.resolve(null),
  ]);
 
  const totalPages = total != null ? Math.ceil(total / perPage) : null;
  const baseUrl = '/api/v1/users'; // 実際にはリクエストから構築
 
  return {
    data,
    meta: {
      total,
      page,
      perPage,
      totalPages,
      hasNextPage: totalPages != null ? page < totalPages : data.length === perPage,
      hasPrevPage: page > 1,
    },
    links: {
      self:  `${baseUrl}?page=${page}&per_page=${perPage}`,
      first: `${baseUrl}?page=1&per_page=${perPage}`,
      prev:  page > 1 ? `${baseUrl}?page=${page - 1}&per_page=${perPage}` : null,
      next:  (totalPages == null || page < totalPages)
               ? `${baseUrl}?page=${page + 1}&per_page=${perPage}`
               : null,
      last:  totalPages != null
               ? `${baseUrl}?page=${totalPages}&per_page=${perPage}`
               : null,
    },
  };
}
 
module.exports = router;

-- Offset 方式の実行計画（問題のあるケース）
EXPLAIN ANALYZE
SELECT * FROM users
ORDER BY created_at DESC
LIMIT 20 OFFSET 100000;
 
-- 結果（例）:
-- Limit  (cost=12345.67..12346.00 rows=20)
--   -> Sort  (cost=12345.67..15000.00 rows=1000000)
--         Sort Key: created_at DESC
--         Sort Method: top-N heapsort  Memory: 30kB
--         -> Seq Scan on users  (cost=0.00..10000.00 rows=1000000)
-- Planning Time: 0.5ms
-- Execution Time: 580ms  ← 遅い
 
-- Cursor 方式の実行計画（改善後）
EXPLAIN ANALYZE
SELECT * FROM users
WHERE (created_at, id) < ('2024-01-15', 100)
ORDER BY created_at DESC, id DESC
LIMIT 20;
 
-- 結果（例）:
-- Limit  (cost=0.56..1.80 rows=20)
--   -> Index Scan using idx_users_created_id on users
--         (cost=0.56..5000.00 rows=100000)
--         Index Cond: (created_at, id) < ('2024-01-15', 100)
-- Planning Time: 0.3ms
-- Execution Time: 1.2ms  ← 高速

// ETag を使った条件付きリクエスト
 
// サーバー側
router.get('/users', async (req, res) => {
  const result = await listUsers(req.query);
 
  // データのハッシュから ETag を生成
  const etag = generateETag(result.data);
 
  // If-None-Match ヘッダのチェック
  if (req.headers['if-none-match'] === etag) {
    return res.status(304).end(); // Not Modified
  }
 
  res.set('ETag', etag);
  res.set('Cache-Control', 'private, max-age=30');
  res.json(result);
});
 
function generateETag(data) {
  const crypto = require('crypto');
  const hash = crypto
    .createHash('md5')
    .update(JSON.stringify(data))
    .digest('hex');
  return `"${hash}"`;
}

// 解答例
router.get('/products', async (req, res) => {
  // 1. パラメータの解析とバリデーション
  const page = Math.max(parseInt(req.query.page, 10) || 1, 1);
  const perPage = Math.min(
    Math.max(parseInt(req.query.per_page, 10) || 20, 1),
    100
  );
 
  // 2. ソートの解析
  const SORT_FIELDS = ['created_at', 'name', 'price', 'updated_at'];
  const orderBy = parseSort(req.query.sort || '-created_at', SORT_FIELDS);
 
  // 3. データ取得（Promise.all で並列実行）
  const skip = (page - 1) * perPage;
  const [products, total] = await Promise.all([
    prisma.product.findMany({
      where: { status: 'active' },
      orderBy,
      skip,
      take: perPage,
    }),
    prisma.product.count({ where: { status: 'active' } }),
  ]);
 
  // 4. メタデータとリンクの構築
  const totalPages = Math.ceil(total / perPage);
  const baseUrl = `${req.protocol}://${req.get('host')}/api/v1/products`;
 
  res.json({
    data: products,
    meta: {
      total,
      page,
      perPage,
      totalPages,
      hasNextPage: page < totalPages,
      hasPrevPage: page > 1,
    },
    links: {
      self:  `${baseUrl}?page=${page}&per_page=${perPage}`,
      first: `${baseUrl}?page=1&per_page=${perPage}`,
      prev:  page > 1 ? `${baseUrl}?page=${page - 1}&per_page=${perPage}` : null,
      next:  page < totalPages ? `${baseUrl}?page=${page + 1}&per_page=${perPage}` : null,
      last:  `${baseUrl}?page=${totalPages}&per_page=${perPage}`,
    },
  });
});

// 解答例（核となるロジック）
const ORDER_FILTER_SCHEMA = {
  status: {
    type: 'enum',
    values: ['pending', 'processing', 'shipped', 'delivered', 'cancelled'],
  },
  total: { type: 'decimal', min: 0, max: 99999999.99 },
  createdAt: { type: 'datetime' },
};
 
const ORDER_SORT_FIELDS = ['created_at', 'total', 'item_count', 'updated_at'];
 
router.get('/orders', authenticate, async (req, res) => {
  const { cursor, limit: limitParam, sort: sortParam } = req.query;
  const limit = Math.min(Math.max(parseInt(limitParam, 10) || 20, 1), 50);
 
  // フィルタの解析
  const filters = parseFilters(req.query, ORDER_FILTER_SCHEMA);
  const where = filtersToPrismaWhere(filters);
 
  // 認証ユーザーのデータのみに制限
  where.userId = req.user.id;
 
  // ソートの解析（安定ソート保証）
  const orderBy = parseSort(sortParam || '-created_at', ORDER_SORT_FIELDS);
 
  // カーソルの処理
  if (cursor) {
    const decoded = decodeSecureCursor(cursor);
    const sortField = Object.keys(orderBy[0])[0];
    const sortDir = Object.values(orderBy[0])[0];
    const cursorWhere = buildCursorWhere(
      [sortField, 'id'], decoded, [sortDir, sortDir]
    );
    where.AND = where.AND || [];
    where.AND.push(cursorWhere);
  }
 
  // データ取得
  const items = await prisma.order.findMany({
    where,
    orderBy,
    take: limit + 1,
    select: {
      id: true, status: true, total: true,
      itemCount: true, createdAt: true, updatedAt: true,
    },
  });
 
  const hasNextPage = items.length > limit;
  const data = hasNextPage ? items.slice(0, limit) : items;
 
  const sortField = Object.keys(orderBy[0])[0];
  res.json({
    data,
    meta: {
      hasNextPage,
      nextCursor: hasNextPage
        ? encodeSecureCursor({
            [sortField]: data[data.length - 1][sortField],
            id: data[data.length - 1].id,
          })
        : null,
      hasPrevPage: !!cursor,
      limit,
    },
  });
});

// 解答例（GraphQL リゾルバ）
const resolvers = {
  Query: {
    searchProducts: async (_, args, ctx) => {
      const {
        query, first, after, last, before,
        filter, orderBy,
      } = args;
 
      // パラメータ検証
      if (first != null && last != null) {
        throw new UserInputError('first と last は同時に指定できません');
      }
      const limit = Math.min(first ?? last ?? 20, 100);
 
      // 検索条件の構築
      const where = {};
      if (query) {
        where.OR = [
          { name: { contains: query, mode: 'insensitive' } },
          { description: { contains: query, mode: 'insensitive' } },
          { brand: { contains: query, mode: 'insensitive' } },
        ];
      }
      if (filter?.category) where.category = { in: filter.category };
      if (filter?.minPrice) where.price = { ...where.price, gte: filter.minPrice };
      if (filter?.maxPrice) where.price = { ...where.price, lte: filter.maxPrice };
      if (filter?.minRating) where.rating = { gte: filter.minRating };
 
      // ソート
      const sortMap = {
        RELEVANCE: query ? undefined : [{ createdAt: 'desc' }],
        PRICE_ASC: [{ price: 'asc' }, { id: 'asc' }],
        PRICE_DESC: [{ price: 'desc' }, { id: 'desc' }],
        RATING: [{ rating: 'desc' }, { id: 'desc' }],
        NEWEST: [{ createdAt: 'desc' }, { id: 'desc' }],
      };
      const sort = sortMap[orderBy?.field || 'NEWEST'];
 
      // カーソル処理
      if (after) {
        const cursor = decodeCursor(after);
        const sortField = Object.keys(sort[0])[0];
        const sortDir = Object.values(sort[0])[0];
        where.AND = where.AND || [];
        where.AND.push(
          buildCursorWhere([sortField, 'id'], cursor, [sortDir, sortDir])
        );
      }
      if (before) {
        const cursor = decodeCursor(before);
        const sortField = Object.keys(sort[0])[0];
        const sortDir = Object.values(sort[0])[0] === 'desc' ? 'asc' : 'desc';
        where.AND = where.AND || [];
        where.AND.push(
          buildCursorWhere([sortField, 'id'], cursor, [sortDir, sortDir])
        );
      }
 
      // データ取得 + ファセット集計を並列実行
      const [items, totalCount, categoryFacets, ratingFacets] = await Promise.all([
        ctx.prisma.product.findMany({
          where,
          orderBy: last ? sort.map(s => {
            const [k, v] = Object.entries(s)[0];
            return { [k]: v === 'desc' ? 'asc' : 'desc' };
          }) : sort,
          take: limit + 1,
        }),
        ctx.prisma.product.count({ where }),
        ctx.prisma.product.groupBy({
          by: ['category'],
          where,
          _count: { category: true },
          orderBy: { _count: { category: 'desc' } },
        }),
        ctx.prisma.product.groupBy({
          by: ['rating'],
          where,
          _count: { rating: true },
          orderBy: { rating: 'desc' },
        }),
      ]);
 
      // last の場合は結果を反転
      let nodes = last ? [...items].reverse() : items;
      const hasMore = nodes.length > limit;
      nodes = hasMore ? nodes.slice(0, limit) : nodes;
 
      const sortField = Object.keys(sort[0])[0];
      const edges = nodes.map(node => ({
        cursor: encodeCursor({ [sortField]: node[sortField], id: node.id }),
        node,
      }));
 
      return {
        edges,
        pageInfo: {
          hasNextPage: first != null ? hasMore : !!before,
          hasPreviousPage: last != null ? hasMore : !!after,
          startCursor: edges[0]?.cursor ?? null,
          endCursor: edges[edges.length - 1]?.cursor ?? null,
        },
        totalCount,
        facets: {
          categories: categoryFacets.map(f => ({
            value: f.category,
            count: f._count.category,
          })),
          priceRanges: buildPriceRangeFacets(nodes),
          ratings: ratingFacets.map(f => ({
            value: f.rating.toString(),
            count: f._count.rating,
          })),
        },
      };
    },
  },
};
 
function buildPriceRangeFacets(products) {
  const ranges = [
    { label: '0-1000', min: 0, max: 1000 },
    { label: '1001-5000', min: 1001, max: 5000 },
    { label: '5001-10000', min: 5001, max: 10000 },
    { label: '10001+', min: 10001, max: Infinity },
  ];
  return ranges.map(range => ({
    value: range.label,
    count: products.filter(
      p => p.price >= range.min && p.price <= range.max
    ).length,
  }));
}

# FastAPI + SQLAlchemy でのカーソルページネーション
 
from fastapi import FastAPI, Query, HTTPException
from sqlalchemy import select, and_, or_, func
from sqlalchemy.ext.asyncio import AsyncSession
from pydantic import BaseModel
from typing import Optional, List
from base64 import urlsafe_b64encode, urlsafe_b64decode
import json
 
app = FastAPI()
 
 
class UserResponse(BaseModel):
    id: int
    name: str
    email: str
    created_at: str
 
 
class CursorMeta(BaseModel):
    has_next_page: bool
    next_cursor: Optional[str]
    has_prev_page: bool
    prev_cursor: Optional[str]
    limit: int
 
 
class PaginatedResponse(BaseModel):
    data: List[UserResponse]
    meta: CursorMeta
 
 
def encode_cursor(data: dict) -> str:
    return urlsafe_b64encode(
        json.dumps(data).encode()
    ).decode().rstrip("=")
 
 
def decode_cursor(cursor: str) -> dict:
    # パディング補完
    padding = 4 - len(cursor) % 4
    if padding != 4:
        cursor += "=" * padding
    try:
        return json.loads(urlsafe_b64decode(cursor))
    except Exception:
        raise HTTPException(status_code=400, detail="Invalid cursor")
 
 
@app.get("/api/v1/users", response_model=PaginatedResponse)
async def list_users(
    cursor: Optional[str] = Query(None),
    limit: int = Query(20, ge=1, le=100),
    sort: str = Query("-created_at"),
    status: Optional[str] = Query(None),
    db: AsyncSession = Depends(get_db),
):
    # ソートの解析
    desc = sort.startswith("-")
    sort_field = sort.lstrip("-")
    allowed = {"created_at", "name", "email"}
    if sort_field not in allowed:
        raise HTTPException(400, f"Invalid sort: {sort_field}")
 
    column = getattr(User, sort_field)
    order = column.desc() if desc else column.asc()
    id_order = User.id.desc() if desc else User.id.asc()
 
    # WHERE 条件
    conditions = []
    if status:
        conditions.append(User.status == status)
 
    if cursor:
        cur = decode_cursor(cursor)
        cur_val = cur.get(sort_field)
        cur_id = cur.get("id")
        if desc:
            conditions.append(
                or_(
                    column < cur_val,
                    and_(column == cur_val, User.id < cur_id),
                )
            )
        else:
            conditions.append(
                or_(
                    column > cur_val,
                    and_(column == cur_val, User.id > cur_id),
                )
            )
 
    # クエリ実行
    query = (
        select(User)
        .where(and_(*conditions) if conditions else True)
        .order_by(order, id_order)
        .limit(limit + 1)
    )
    result = await db.execute(query)
    items = result.scalars().all()
 
    has_next = len(items) > limit
    data = items[:limit] if has_next else items
 
    return PaginatedResponse(
        data=[UserResponse.from_orm(u) for u in data],
        meta=CursorMeta(
            has_next_page=has_next,
            next_cursor=(
                encode_cursor({
                    sort_field: str(getattr(data[-1], sort_field)),
                    "id": data[-1].id,
                })
                if has_next else None
            ),
            has_prev_page=cursor is not None,
            prev_cursor=(
                encode_cursor({
                    sort_field: str(getattr(data[0], sort_field)),
                    "id": data[0].id,
                })
                if data else None
            ),
            limit=limit,
        ),
    )