Query a Folderbase

Status: Unstable Beta. folderbase.query-index@0.1.0 is an optional experimental capability, not part of Compatibility Contract v1 and not required for Folderbase sync, Cloud storage, sharing, or ordinary agent access. Discover it at runtime and pin the exact capability version before integrating it.

The name Query currently means a bounded, structured metadata inventory. It filters the files and historical records that Folderbase already knows about. It does not search inside files, execute SQL, traverse a knowledge graph, create embeddings, or ask a model to interpret content.

What Query does

Query can select one current filesystem observation or one exact historical Folderbase Version, then filter its rows by:

• exact path or component-aware path prefix;
• filesystem kind: directory, regular file, symlink, or nested Folderbase;
• logical byte range;
• live or deleted lifecycle;
• stable Knowledge Object ID; or
• exact Object Version ID.

Every ordinary format remains opaque. Markdown, repositories, PDFs, CSV files, SQLite databases, office documents, archives, videos, sparse 10 GiB files, and unknown formats are represented only by safe metadata. Query never opens, hashes, or searches their content.

Who it is for

Query is primarily a machine integration surface for:

• an App filtering a large Folderbase or displaying exact historical state;
• an agent harness requesting a structured inventory before choosing files;
• a remote workspace materializer inspecting identities and deleted records;
• scripts and third-party applications that need deterministic paginated JSON; and
• independent Folderbase implementations proving the same metadata behavior.

Humans normally use Query indirectly through an App. An agent working in an ordinary materialized folder should continue to use familiar tools such as rg, grep, find, Git, or a format-specific reader for content. Query adds Folderbase identity, history, boundary, and large-file metadata that those tools do not provide.

When not to use it

Do not put Query in the critical path for:

• observing and capturing local changes;
• generating or transferring chunks;
• publishing or fetching a Remote Head;
• downloading and verifying Cloud bytes;
• enforcing permissions or resolving a Live Folder share; or
• listing a small ordinary workspace when folderbase workspace list is sufficient.

Cloud may use PostgreSQL internally, but that is unrelated to this local query/index capability.

First confirm that the executable advertises the capability:

folderbase protocol contract --json

Run a live query

Requests are JSON on standard input. This example returns up to 100 regular files under docs or data that are at least one byte:

printf '%s' '{
  "format": "folderbase-query-request-v1",
  "scope": {"kind": "live"},
  "filters": {
    "path_prefixes": ["data", "docs"],
    "kinds": ["regular_file"],
    "minimum_bytes": 1
  },
  "page": {"limit": 100}
}' | folderbase query run . --json

Rows are deterministic and metadata-first. A 10 GiB movie can therefore be listed by path, kind, and logical byte size without loading its content.

Explain before integrating

Use the same request with explain to inspect normalized filters, ordering, scope source, excluded paths, and whether the command used a bounded scan or the private index:

printf '%s' '{
  "format": "folderbase-query-request-v1",
  "scope": {"kind": "live"},
  "page": {"limit": 100}
}' | folderbase query explain . --json

Inspect and rebuild the disposable index

Queries remain correct without an index. The index is private, local, rebuildable state under .folderbase/local/query-index-v1; it is not portable authority and must not be synced as Folderbase data.

folderbase index status . --json
folderbase index rebuild . --json
folderbase index status . --json

Only the explicit rebuild command may replace that namespace. Query, explain, and status do not mutate ordinary files or portable Folderbase records.

Continue a page safely

Copy page.next_cursor into the next request while keeping the rest of the request identical. A cursor is bound to the exact root, normalized request, manifest, ignore policy, Local Head, and observed metadata generation. If any bound state changes, the command returns query_snapshot_changed instead of mixing rows from two observations. Start again without the old cursor.

For historical queries, use:

{
  "format": "folderbase-query-request-v1",
  "scope": {
    "kind": "historical",
    "folderbase_version_id": "fbversion_019f0000-0000-7000-8000-000000000001"
  },
  "page": {"limit": 100}
}

See the query/index wire reference for bounds, result formats, errors, exit statuses, and the public conformance runner.