convex-runtime

Convex のランタイム機能（HTTP アクション、ファイルストレージ、検索（全文検索＋ベクトル検索）、スケジューリング）を実装します。 - **HTTP アクション**: https://docs.convex.dev/functions/http-actions - **ファイルストレージ**: https://docs.convex.dev/file-storage - **ファイルのアップロード**: https://docs.convex.dev/file-storage/upload-files - **ファイルの配信**: https://docs.convex.dev/file-storage/serve-files - **ファイルのメタデータ**: https://docs.convex.dev/file-storage/file-metadata - **全文検索**: https://docs.convex.dev/search/text-search - **ベクトル検索**: https://docs.convex.dev/search/vector-search - **スケジューリング**: https://docs.convex.dev/scheduling - **スケジュール済み関数**: https://docs.convex.dev/scheduling/scheduled-functions - **Cron ジョブ**: https://docs.convex.dev/scheduling/cron-jobs - 全文検索：`searchField` と任意の `filterFields` を指定した `searchIndex` を使用します。関連度順に並び、最後の語句は前方一致で検索されます。あいまい検索は非推奨です。上限は、語句が 16 個、フィルターが 8 個、スキャン数が 1024 件です。 - ベクトル検索：`vectorField` と `dimensions`（2〜4096）を指定した `vectorIndex` を使用します。ベクトルフィールドは `v.array(v.float64())` です。アクションでのみ使用でき、上限は、結果が 256 件、フィルターが 64 個、テーブルあたりのベクトルインデックスが 4 個です。 - スケジューリング：スケジュール済み関数は永続性があり、DB に保存されます。Cron ジョブは固定スケジュールで実行されます。認証情報は引き継がれないため、ID を明示的に渡す必要があります。 - ファイルストレージ：大きなファイルにはアップロード URL を使用します。HTTP アクションでのアップロード上限は 20MB です。メタデータは `_storage` に保存されます。

ランタイム操作

• HTTP アクション：httpAction でハンドラーを定義し、httpRouter を使って convex/http.ts に登録します（デフォルトエクスポートが必須です）。
• HTTP 構文：

  http.route({
    path: "/api/echo", // Exact path
    method: "POST",
    handler: httpAction(async (ctx, req) => {
      const body = await req.bytes();
      return new Response(body, { status: 200 });
    }),
  });
  

• HTTP アクションは https://<deployment>.convex.site で公開する必要があります。
• アップロード URL のフロー：URL を生成するミューテーション → クライアントから POST → storageId を保存します。URL の有効期限は 1 時間です。
• HTTP アップロードのフロー：ctx.storage.store(blob) の後にミューテーションを実行します。HTTP アクション経由のアップロード上限は 20MB です。
• ファイルの配信：クエリ／ミューテーション内で ctx.storage.getUrl(storageId) を使用します。署名付き URL または null を返します。
• ファイルのメタデータ：ctx.db.system.get("_storage", id) または query("_storage") を使用します。storage.getMetadata() は非推奨です。
• スケジューリング：ctx.scheduler.runAfter/runAt を使用します。Cron ジョブは cronJobs() を使って convex/crons.ts に定義します。
• Cron スケジューリング：crons.interval または crons.cron を使用する必要があります。crons.hourly、crons.daily、crons.weekly などの非推奨ヘルパーは使用してはいけません。
• Cron の内部呼び出し：Cron が内部関数を呼び出す場合、同じファイルで定義されている場合でも、_generated/api から internal オブジェクトをインポートして参照する必要があります。

コアのルール

• HTTP アクションは convex/http.ts のデフォルトエクスポート経由でのみルーティングする必要があります。
• HTTP アクションではバリデーターがサポートされないため、Request を手動で解析する必要があります。
• 検索の例：

  const messages = await ctx.db.query("messages")
    .withSearchIndex("search_body", (q) =>
      q.search("body", "hello hi").eq("channel", "#general")
    ).take(10);
  

• ベクトル検索はアクションでのみ使用する必要があります。結果はリアクティブではありません。
• 検索の動作：全文検索は関連度順に並び、最後の語句は前方一致で検索されます。あいまい検索は非推奨です。
• インデックス定義とクエリのフィルターでは、検索／ベクトルフィルターを優先して使用してください。
• スケジュール済み関数の引数は、後方互換性を維持する必要があります。