Retriever query
log10x_retriever_queryFetch offloaded log events from your S3 bucket by pattern hash or variable value using Bloom-filter byte ranges; returns a preview plus S3 results location for audit or forensic retrieval.
Instructions
Fetch offloaded log events from the customer's own S3 bucket by pattern hash or by a variable value, reading only the byte ranges whose Bloom filters can hold a match, without a full scan. The use case: events the Receiver offloaded to the customer's S3 bucket instead of the SIEM, over any window the bucket holds. The Bloom filters cover each event's template hash and variable values. Matched events land as a list of *.jsonl objects in the customer's S3; the tool returns an in-context preview (capped by limit) PLUS data.results_location (the S3 bucket + prefix holding the full object set). A capable agent reads those objects directly to answer, or hands the S3 object list to the customer's own S3-to-SIEM path. No re-ingestion pipeline, no proprietary format. The envelope additionally carries per-pattern offload_status so retrieval results agree with the live metric-surface disposition (pass / sample / compact / drop) without a second tool call. Call for: offloaded events of a pattern; events filtered by a variable value that is not a faceted SIEM dimension (e.g. 'all payment_retry events for customer acme-corp 90 days ago'); compliance / audit / forensic exact retrieval; confirming what the Receiver offloaded for a given pattern. Optional JavaScript filters refine over payloads after the Bloom-scoped fetch. For a time-bucketed series instead of raw events, use log10x_retriever_series. The envelope carries by_severity / by_service / by_day rollups with a rollup_basis provenance stamp (qrs_summaries = whole-match from engine summaries; events_capped = derived from the capped download).
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | End of the query window. Same grammar as `from`. Default `now`. | now |
| from | Yes | Start of the query window. Accepts ISO8601 (`2026-01-15T00:00:00Z`), epoch millis, or relative (`now-1h`, `now-24h`, `now-7d`). Normalized to the engine's `now("-1h")` form before dispatch. | |
| view | No | summary returns the typed envelope (data.events_matched, data.events[], data.query_id, data.diagnostics, data.human_summary). The deprecated markdown view was removed; data.human_summary carries the prose distillation for chat rendering. | summary |
| debug | No | Escalate the CloudWatch log level to DEBUG for THIS query only: per-blob Bloom decisions, per-fetch S3 reads, per-event results-writer samples. Use only when normal-run diagnostics cannot explain a 0-result or truncated outcome (volume is ~100x higher). Default false. | |
| limit | No | Hard cap on events returned after merging per-worker result files. Default 500. Typical conversational queries want 10-100; the LLM will render only the first 50. | |
| format | No | `events` (default: raw events), `count` (total + severity/service rollups, no event bodies), `aggregated` (events bucketed into a time series, use with bucket_size), `ephemeral_series` (bucketed series in Prometheus range-query shape for cross-pillar correlation). All four formats are rolled up client-side from the same events stream. | events |
| search | No | Bloom-filter search expression using the TenX subset: `==`, `||`, `&&`, `includes(field, "substr")`. Example: `severity_level=="ERROR" && includes(text, "ECONNREFUSED")`. Selective values are dramatically cheaper than open-ended scans. REQUIRED unless `pattern_hash` is given: the engine rejects a blank search, so there is no unscoped full-window scan. To scope to one pattern pass `pattern_hash`, which is matched as a text token; a Reporter-named `pattern` cannot be matched against the archive at all and is refused with a remedy. | |
| target | No | Target app/service prefix to scope the index scan. Defaults to __SAVE_LOG10X_RETRIEVER_TARGET__ (env var). Required if no default is configured. | |
| filters | No | JavaScript filter expressions evaluated in-memory against each decoded event after the Bloom-scoped fetch. Full TenX JS API: `this.customer_id === "acme-corp"`, `this.http_code.startsWith("5")`. Filters are AND-combined. | |
| pattern | No | Reporter-named pattern (Symbol Message). NOT SUPPORTED against the offload bucket: passing it returns an error naming the remedy, rather than a silent empty result. A Symbol Message is a label DERIVED from the event, so it is never a token in the offloaded bytes, and the Bloom index holds only text tokens plus template hashes. (The field this once queried, `tenx_user_pattern`, does not exist in the engine at all, which is why name-scoped queries returned BLOOM_REJECTED_ALL.) Pass `pattern_hash` instead: top_patterns returns it on the same row as the name, and event_lookup resolves a name to a hash. | |
| bucket_size | No | Bucket size when format=aggregated or ephemeral_series. Examples: `1m`, `5m`, `1h`, `1d`. | 5m |
| environment | No | Environment nickname: required if multi-env. | |
| pattern_hash | No | Canonical pattern_hash from top_patterns / event_lookup. When provided, search is auto-built as `includes(text, "<hash>")` and no name resolution runs. It matches the stamped hash as a TEXT TOKEN because the offloaded events carry their own `tenx_hash` field, re-derived per multi-line group, so a field equality against a metrics-side hash matches nothing. This is the pattern hash emitted by top_patterns.payload.patterns[].pattern_hash: bypasses the name→hash resolver entirely. Precedence: `search` > `pattern_hash` > `pattern`. Example: `pattern_hash: "4Kjc7PHLWqY"`. | |
| result_target | No | Tier-1 result-sink redirect: write this query OUTPUT (events, summaries, markers) under tenx/<result_target>/ in the same bucket instead of the default target, e.g. to a prefix a SIEM connector watches. Omit to keep results under the scan target (default). Bare token [A-Za-z0-9_-]+. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| data | No | ||
| tool | Yes | ||
| view | No | summary | |
| images | No | ||
| actions | No | ||
| summary | Yes | ||
| warnings | No | ||
| truncated | No | ||
| next_cursor | No | ||
| render_hint | No | ||
| generated_at | Yes | ||
| schema_epoch | Yes | ||
| schema_version | Yes |