furl_retrieve
Expand compressed data by hash to get the original content, search all stored entries, or project specific fields, lines, or rows.
Instructions
Retrieve original uncompressed content by hash. Use this when you need full details from previously compressed content. The hash comes from furl_compress results or from compression markers like [N items compressed... hash=abc123]. Two extra modes: (1) OMIT hash and pass query to search across ALL stored entries (returns ranked hash/score/preview matches to retrieve individually); (2) pass hash with pattern/fields/line_range, or a select_field row-filter (keep the rows of a JSON array by exact value or numeric range), to project just part of the original. Filters cannot be combined with query. Examples: furl_retrieve(hash) -> the whole original; furl_retrieve(hash, pattern="ERROR") -> only the matching lines; furl_retrieve(hash, select_field="id", select_equals=42) -> the rows where id==42.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| raw | No | Return each matched row byte-identical to its source bytes instead of a re-serialized, pretty-printed copy — for hashing, diffing, or signature checks where the exact formatting must survive. Requires select_field (only a row-select yields whole source rows) and cannot be combined with fields (a projection has no source span). Every returned row is byte-exact; the rows are rejoined with fresh JSON array punctuation, so the blob as a whole is not a contiguous slice. If more rows match than 'limit', a single trailing {"__ccr_truncated__": ...} object is appended as a synthetic marker (NOT a source row); strip that one element by its key before hashing, or raise 'limit' to avoid truncation. Default false keeps the re-serialized output. | |
| hash | No | Hash key from compression (e.g., 'abc123' from hash=abc123). Omit to search across all entries via 'query'. | |
| limit | No | Max rows returned by a select_field row-select OR a fields projection; a positive integer. A select without an explicit limit defaults to 1000; a fields projection without a limit is unbounded. When more rows match than the limit, only the first 'limit' ship plus one explicit truncation-marker row. It does not bound a pattern or line_range window, which line_range bounds instead. | |
| query | No | Search query. WITH a hash: return only items in that entry matching the query. WITHOUT a hash: full-text search (BM25-ranked) across every stored entry, returning top matches as hash/score/preview. Mutually exclusive with pattern/fields/line_range. | |
| fields | No | For a JSON-array original: project only these keys out of each object element (requires a hash, no query). Errors if the original is not a JSON array. Cannot be combined with pattern/line_range; composes with select_field (projects the columns of the kept rows). | |
| pattern | No | Regex applied line-by-line to the full original (requires a hash, no query). Returns matching lines (prefixed with 1-based line numbers) plus 'context_lines' lines of surrounding context. Invalid regex returns an error. | |
| line_range | No | [start, end] 1-based inclusive line window over the full original (requires a hash, no query). Either bound may be null for an open end. Composes with 'pattern' (the range is applied first). | |
| select_max | No | Numeric-range mode: keep rows whose select_field is a number <= select_max (inclusive; open upper bound when omitted). Must be >= select_min. Mutually exclusive with select_equals. | |
| select_min | No | Numeric-range mode: keep rows whose select_field is a number >= select_min (inclusive; open lower bound when omitted). A row whose field is missing or non-numeric is skipped, never an error. Mutually exclusive with select_equals. | |
| select_field | No | Row-select over a JSON array of objects (requires a hash, no query): the field/column name to match on. It anchors the whole select family — select_equals / select_min / select_max / limit are honored ONLY alongside select_field (any of them without it is an error). Reads a top-level JSON array of objects OR a JSON object with exactly one dominant inner array (e.g. a '{metadata, traceEvents:[...]}' trace). Composes with 'fields'; cannot be combined with pattern/line_range or query. | |
| context_lines | No | Lines of context to include on each side of a 'pattern' match (default 0, max 50). | |
| select_equals | No | Equality mode: keep rows whose select_field equals this JSON scalar (string/number/boolean/null; a list or object is rejected). Bool-safe — true never matches the number 1. Mutually exclusive with select_min/select_max. |