全体検索
ファイルの検索用テキストを供給し、ファイル・Doc・レコード・カスタムプロンプトを grep して、必要な行範囲だけを読み取ります。
Busabase は、人と AI エージェントのために 1 つの正確な検索フローを提供します。
検索用テキストを供給 -> grep -> マッチした行範囲を読み取るPOST /api/v1/grep は、ファイル、Doc 本文、Base レコード内の現在マージ済みの値、そしてノードに保存されたカスタムエージェントプロンプトを検索します。結果にはソース、行、列、周辺コンテキストが含まれるため、呼び出し元は追加の内容を読む前に根拠の場所を特定できます。ファイルのマッチには、そのファイルが属するスキルやドライブも示されます。
どの検索を使うか
エージェントが何かを探す方法は 3 つあり、それぞれ答える問いが違います。
| 知りたいこと | 使うもの | 得られるもの |
|---|---|---|
| この作業に決まったやり方はあるか？ | playbooks search | 保存したスキルとカスタムプロンプトを、一致度順・近いもの優先で返します。エージェントはすべての指示の最初にこれを呼びます |
| このテキストは正確にどこにあるか？ | grep（このページ） | 現在の完全なデータ（ファイル、Doc 本文、マージ済みレコード、カスタムプロンプト）への正規表現マッチを、行・列・カバレッジ付きで返します |
| 関連するものは何か、一致度の高い順に？ | search | あいまい検索・ランク付け・ページング。保留中の変更リクエストの下書きも含みます。長いフィールド値は先頭 8,000 文字だけが対象なので、正確な文言は grep で確認してください |
検索対象
| ソース | grep が使用するテキスト |
|---|---|
| ファイル | Asset の検索用テキストスロット |
| Doc | 現在の Doc 本文 |
| レコード | 現在マージ済みのレコードフィールド |
| プロンプト | 各カスタムエージェントプロンプトのタイトルと本文（書かれているすべての言語） |
Markdown、JSON、CSV、ログ、ソースコードなどのテキストファイルは、自身の UTF-8 バイトを検索用テキストとして使用します。PDF、Office 文書、音声、動画、画像などのバイナリファイルは、外部ツールまたはエージェントでテキストを抽出・文字起こしし、その結果を Asset に供給する必要があります。
Busabase は供給されたテキストを保存して検索しますが、OCR、文字起こし、文書パーサーを内蔵して実行することはありません。
ファイルに検索用テキストを供給する
Asset は 4 つの textStatus のいずれかを返します。
| ステータス | 意味 | 次の操作 |
|---|---|---|
missing | 検索用テキストがまだ供給されていない | テキストを供給するか、抽出可能なテキストがないとマークする |
present | 現在の検索用テキストを利用できる | grep または読み取りを行い、より良い抽出結果があれば置き換える |
stale | テキスト供給後にソースファイルが変更された | 新しいファイルから生成したテキストを供給する |
none | 抽出可能なテキストがないと明示的にマークされている | OCR や文字起こしが利用可能になれば、後からテキストを供給する |
Asset 詳細ページにも、同じ供給・置換・プレビュー操作があります。API とエージェントクライアントでは、次の 3 つの書き込み方法を利用できます。
小さいテキスト：インラインで書き込む
1 MB 以下の UTF-8 テキストは、putText で直接書き込みます。
curl -X PUT "$BUSABASE_BASE_URL/api/v1/assets/$ASSET_ID/text" \
-H "Authorization: Bearer $BUSABASE_API_KEY" \
-H "Content-Type: application/json" \
--data '{"text":"抽出した契約書テキスト\n解約条項..."}'レスポンスは、保存済みステータスと件数を返します。
{
"assetId": "asset_contract_pdf",
"textStatus": "present",
"lineCount": 84,
"charCount": 4921,
"byteCount": 7610
}大きいテキスト：アップロードしてから紐付ける
1 MB を超えるテキストでは、ストリーミングに適した 3 段階のフローを使用します。
POST /api/v1/assets/text/upload-urlsで一時アップロード URL を取得します。- UTF-8 の
.txtバイトを、返されたuploadUrlにPUTします。 PUT /api/v1/assets/{assetId}/textで、返されたstorageKeyを紐付けます。
SIZE_BYTES=$(wc -c < extracted.txt | tr -d ' ')
curl -X POST "$BUSABASE_BASE_URL/api/v1/assets/text/upload-urls" \
-H "Authorization: Bearer $BUSABASE_API_KEY" \
-H "Content-Type: application/json" \
--data "{\"assetId\":\"$ASSET_ID\",\"sizeBytes\":$SIZE_BYTES}"
# -> { "uploadUrl": "...", "storageKey": "...", "expiresIn": 900 }
curl -X PUT "<uploadUrl>" \
-H "Content-Type: text/plain; charset=utf-8" \
--data-binary @extracted.txt
curl -X PUT "$BUSABASE_BASE_URL/api/v1/assets/$ASSET_ID/text" \
-H "Authorization: Bearer $BUSABASE_API_KEY" \
-H "Content-Type: application/json" \
--data '{"storageKey":"<storageKey>"}'最後の紐付け処理で、アップロード済みバイトと UTF-8 エンコーディングを検証し、テキストを検索可能にします。再度テキストを供給すると、以前の検索用テキストが置き換えられます。
抽出可能なテキストがない：none としてマークする
画像のみのファイルなど、テキストを抽出できない場合は、テキストスロットを明示的にマークします。
curl -X PUT "$BUSABASE_BASE_URL/api/v1/assets/$ASSET_ID/text" \
-H "Authorization: Bearer $BUSABASE_API_KEY" \
-H "Content-Type: application/json" \
--data '{"none":true}'その後、grep は Asset を繰り返し missing として報告せず、unsearchable に数えます。後からテキストを供給すれば、この状態を解除できます。
ファイル、Doc、レコード、プロンプトを横断して grep する
sources を省略すると 4 つすべてを検索します。必要なソースだけを選択することもできます。
curl -X POST "$BUSABASE_BASE_URL/api/v1/grep" \
-H "Authorization: Bearer $BUSABASE_API_KEY" \
-H "Content-Type: application/json" \
--data '{
"pattern":"termination",
"flags":"i",
"sources":["files","nodes","records","prompts"],
"contextLines":2
}'pattern は JavaScript の正規表現構文を使用します。単純な単語も有効な pattern です。大きな検索では、scope.files、scope.nodes、scope.records で対象を絞り込めます。
{
"matches": [
{
"source": "files",
"assetId": "asset_contract_pdf",
"fileName": "contract.pdf",
"drivePath": "legal/contract.pdf",
"owner": { "nodeId": "nod_legal", "nodeType": "drive", "nodeName": "Legal", "path": ["Company"] },
"line": 118,
"column": 1,
"text": "Termination requires 30 days notice.",
"before": ["..."],
"after": ["..."]
},
{
"source": "prompts",
"nodeId": "nod_contracts",
"nodeName": "Contracts",
"nodeType": "base",
"nodeSlug": "contracts",
"key": "check-termination",
"locale": "en",
"field": "body",
"line": 2,
"column": 12,
"text": "Flag any termination clause shorter than 30 days.",
"before": ["..."],
"after": []
}
],
"coverage": {
"files": { "scanned": 24, "missing": [], "stale": [], "unsearchable": 1, "errored": [], "notReached": 0 },
"nodes": { "scanned": 12, "errored": [], "notReached": 0 },
"records": { "scanned": 178, "errored": [], "notReached": 0 },
"prompts": { "scanned": 3, "errored": [], "notReached": 0 }
},
"truncated": false
}それぞれのマッチからわかること：
- ファイルのマッチには
ownerが付きます。ファイルが属するノード（nodeType、nodeName）と、その上にあるフォルダー（path）です。そのためSKILL.mdでのヒットは、どのスキルのものかがわかります。開く権限のないフォルダーはpathに含まれません。アップロード済みでまだどこにも配置されていないファイルにはownerがありません。 - プロンプトのマッチは、プロンプトが保存されているノード、プロンプトの
key、一致したfield（labelタイトルまたはbody本文）、そのテキストのlocale（言語ごとに分かれていない単一のテキストならdefault）を示します。エージェントが受け取るとおりにプロンプトを開くには、keyをplaybooks getに渡します。作業に合うプロンプトを探すにはplaybooks searchを使います。grep はすべてのマッチを列挙し、playbooks search は順位を付けます。
maxMatches は公平に配分されます。要求された各ソースには少なくとも maxMatches ÷ ソース数 件が保証され、使われなかった分はファイル、Doc、レコード、プロンプトの順で後ろのソースに回ります。マッチの多いソースが他のソースを押し出すことはありません。呼び出し全体で 1 つの制限時間を共有します。
マッチがないことを「存在しない」と判断する前に、必ず coverage を確認してください。missing、stale、errored、notReached、または truncated: true があれば、検索は完全ではありません。missing または stale のファイルには新しい検索用テキストが必要です。notReached や打ち切りがある場合は、maxMatches を増やすのではなく検索を絞り込みます。まず sources で必要なソースを選び、次にレコードは scope.records.baseSlugs、ファイルは scope.files.drivePath で絞り込みます。
マッチした周辺範囲だけを読み取る
ファイルが 118 行目でマッチしたら、抽出テキスト全体をダウンロードせず、周辺の範囲だけを読み取ります。
curl "$BUSABASE_BASE_URL/api/v1/assets/$ASSET_ID/text/lines?startLine=113&endLine=123" \
-H "Authorization: Bearer $BUSABASE_API_KEY"Doc のマッチでは、結果の nodeId を対応する Doc エンドポイントで使用します。
curl "$BUSABASE_BASE_URL/api/v1/docs/$NODE_ID/lines?startLine=113&endLine=123" \
-H "Authorization: Bearer $BUSABASE_API_KEY"Asset の 1 回の読み取りは 2,000 行までで、ストレージの範囲読み取りを使用します。そのため、grep してから読むフローは、非常に大きな供給テキストにも適しています。
putText と editContent は別の操作
この 2 つは変更対象もレビュールールも異なります。
| 操作 | 変更するもの | ソースファイル | レビュー |
|---|---|---|---|
assets.putText | grep と範囲読み取りに使う、再生成可能な派生テキスト | 変更しない | 直接書き込み、監査ログに記録 |
assets.editContent | Drive または Skill にマウントされた正規テキストファイルのバイト | マージ後に変更 | ChangeRequest を作成 — 書き込み権限があればその場でマージ、なければレビュー待ち |
PDF、文書、マウント済みテキストファイルそのものを編集するために putText を使わないでください。これは grep が読むテキスト表現を供給するための操作です。実ファイルを変更する必要がある場合は editContent を使用します。
Asset レスポンスには、インラインの asset.text フィールドを意図的に設けていません。大きなテキストは AssetVO の外に置かれます。asset.textStatus で状態を確認し、putText で書き込み、grep で検索し、readTextLines で必要な範囲だけを読み取ってください。