ファイルの検索用テキストを供給し、ファイル・Doc・レコードを grep して、必要な行範囲だけを読み取ります。

全体検索

Busabase は、人と AI エージェントのために 1 つの正確な検索フローを提供します。

検索用テキストを供給 -> grep -> マッチした行範囲を読み取る

POST /api/v1/grep は、ファイル、Doc 本文、Base レコード内の現在承認済みの正規値を検索します。結果にはソース、行、列、周辺コンテキストが含まれるため、呼び出し元は追加の内容を読む前に根拠の場所を特定できます。

検索対象

ソース	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 を省略すると 3 つすべてを検索します。必要なソースだけを選択することもできます。

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","docs","records"],
    "contextLines":2
  }'

pattern は JavaScript の正規表現構文を使用します。単純な単語も有効な pattern です。大きな検索では、scope.files、scope.docs、scope.records で対象を絞り込めます。

{
  "matches": [
    {
      "source": "files",
      "assetId": "asset_contract_pdf",
      "fileName": "contract.pdf",
      "drivePath": "legal/contract.pdf",
      "line": 118,
      "column": 1,
      "text": "Termination requires 30 days notice.",
      "before": ["..."],
      "after": ["..."]
    }
  ],
  "coverage": {
    "files": { "scanned": 24, "missing": [], "stale": [], "unsearchable": 1, "errored": [], "notReached": 0 },
    "docs": { "scanned": 12, "errored": [], "notReached": 0 },
    "records": { "scanned": 178, "errored": [], "notReached": 0 }
  },
  "truncated": false
}

マッチがないことを「存在しない」と判断する前に、必ず coverage を確認してください。missing、stale、errored、notReached、または truncated: true があれば、検索は完全ではありません。missing または stale のファイルには新しい検索用テキストが必要です。notReached や打ち切りがある場合は、通常スコープや pattern を絞り込みます。

マッチした周辺範囲だけを読み取る

ファイルが 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 で必要な範囲だけを読み取ってください。

関連: REST API · MCP 連携 · コアコンセプト

全体検索

On this page