convex-queries

Convex クエリスキル

このスキルでは、Convex のクエリ関数の実装に関する専門的なガイダンスを提供します。関数の定義、登録、呼び出しパターン、ページネーション、インデックス、全文検索のベストプラクティスを含みます。

このスキルを使用するタイミング

次のような場合に、このスキルを使用してください：

• Convex データベースからデータを取得する新しいクエリ関数を定義するとき
• 大量の結果をページネーションで処理するとき
• 効率的なクエリのためにインデックスを設定するとき
• 全文検索機能を使用するとき
• 他の Convex 関数からクエリを呼び出すとき
• クエリのパフォーマンスを最適化するとき

スキルのリソース

このスキルには、次の内容を網羅したリファレンスドキュメント references/query-guidelines.md が含まれています：

クエリ開発の基礎

• 新しい関数構文を使用した関数定義の構文
• クエリの登録（query と internalQuery）
• 引数バリデーターとその使い方
• 関数の呼び出しパターン（ctx.runQuery）
• 関数参照（api オブジェクトと internal オブジェクト）
• クエリパスのファイルベースルーティング

クエリの最適化

• クエリのガイドライン（filter を避け、withIndex でインデックスを使用する）
• .order('asc') と .order('desc') による結果の並べ替え
• 単一のドキュメントを取得するための .unique() の使用
• for await 構文による非同期反復処理
• クエリの上限とパフォーマンスに関する考慮事項

高度なクエリ機能

• ページネーション：paginationOptsValidator を使用したページネーション付きクエリの実装
  • paginationOpts（numItems と cursor）の理解
  • ページネーションされた結果の読み取り（page、isDone、continueCursor）
• 全文検索：検索インデックスの設定とクエリ
• インデックス作成：効率的な検索のためのインデックスの作成と使用
  • 組み込みインデックス（by_id、by_creation_time）
  • カスタムのインデックス名とフィールドの順序
  • 複数のインデックスを使ったネストされたクエリ

データベースクエリ

• ctx.db.query() による Convex データベースからの読み取り
• .withIndex() によるインデックスの使用
• .collect() と .take(n) による結果の収集

このスキルの使用方法

1. リファレンスドキュメント references/query-guidelines.md を読み、クエリのパターンをすべて理解します
2. 構文の例に従い、適切なバリデーターを使ってクエリ関数を定義します
3. filter メソッドの代わりにインデックスを使用して、効率的にフィルタリングします
4. 大規模なデータセットを扱う場合は、ページネーションを実装します
5. テキストに基づくフィルタリングが必要な場合は、全文検索を活用します
6. Convex が結果をどのように並べ替えるかを理解し、順序を最適化します

クエリの主なガイドライン

• すべてのクエリ関数には、必ず引数バリデーターを含めてください
• クエリで filter を使用しないでください。代わりに withIndex を使用してください
• ミューテーションやアクションからクエリを呼び出すには、ctx.runQuery を使用してください
• 同じファイル内でクエリを呼び出す場合は、戻り値の型注釈を指定してください（TypeScript の循環参照を回避する方法です）
• クエリの実行時間は最大 1 秒で、最大 16384 件のドキュメントを読み取れます
• クエリに明示的な戻り値がない場合、暗黙的に null を返します

例：インデックスを使った基本的なクエリ

import { query } from "./_generated/server";
import { v } from "convex/values";

export const getMessagesByChannel = query({
  args: {
    channelId: v.id("channels"),
  },
  handler: async (ctx, args) => {
    return await ctx.db
      .query("messages")
      .withIndex("by_channel", (q) => q.eq("channelId", args.channelId))
      .order("desc")
      .take(20);
  },
});

詳しい情報やその他のパターンについては、リファレンスドキュメント全文を参照してください。