Advanced capture queries with PacketQL

Advanced capture query lets you calculate a focused comparison over facts already prepared by the PacketSafari Core Engine. PacketQL is the bounded query language behind this workspace.

Use it when a report or dashboard has raised a specific follow-up question such as:

Which TCP streams carried the most observed bytes?
How are retransmissions distributed by transport protocol?
Which reset-bearing streams share the same termination outcome?
Which TCP streams contain the longest observed packet gaps?

PacketQL works from one retained, immutable Core generation. It does not reopen or rescan the PCAP, execute SQL or arbitrary code, or save query rows as another analysis result.

Open an advanced capture query

After Core Triage has prepared queryable data:

Open the capture and select More → Query.
Choose a fact family, or start with one of the available recipes.
Describe the operational purpose of the calculation.
Choose how to group, calculate, filter, and sort the retained facts.
Select Run query.

Agent also provides an advanced-query shortcut when you are already working in an investigation.

PacketQL itself does not use Agent or a model. If retained query data is absent, Re-run capture triage queues ordinary capture processing directly and keeps you in the Query workspace while Core prepares a new exact generation.

Only fact families emitted by that exact Core generation appear in the dialog. Available fields, units, calculations, and recipes therefore depend on the capture and the completed Core work.

Build the calculation

The analyst query workspace provides four controls:

Group by divides facts by one or two dimensions, such as transport protocol or TCP stream. With no grouping, PacketQL calculates one capture-level total for the selected family.
Metric counts rows or calculates a sum, average, minimum, or maximum over a compatible numeric field.
Filters limit the calculation using fields and operators allowed for the selected family.
Sort and result rows control which highest or lowest groups are returned.

The field picker describes the meaning and unit of each available value. This is important for fields such as connection bytes, packet gaps, retransmissions, and normalized endpoints, whose meaning may be more specific than their short label.

Recipes are editable starting points. They fill the same bounded controls as a custom query and do not use a separate analysis path.

Read the result as evidence

An advanced query result can include:

the grouped or capture-level calculation
the number of retained records examined and matched
omitted-group or result-limit notices
source coverage and other material warnings
exact packet anchors when the retained fact family provides them

Use View packets on an anchor to inspect the supporting frames in the Analyzer. A ranking or aggregate is useful for choosing where to investigate; it is not, by itself, a verified root-cause or security conclusion.

If the source fact family has partial or unavailable coverage, the query result keeps that limitation visible. PacketQL does not turn partial source evidence into a complete result.

Understand the bounds

PacketQL is deliberately constrained so a follow-up calculation cannot become an unbounded capture-processing job. The query dialog displays the active server limits before execution. The current analyst workspace allows:

one retained fact family per query
up to two grouping fields
one aggregate metric
up to two filters
up to 64 returned rows

The server also limits records examined, execution time, group state, packet anchors, request size, and returned bytes. If a bound is reached, PacketSafari reports the limitation instead of presenting a partial calculation as complete.

These are execution ceilings, not statements about how many packets or facts a capture may contain. The retained family can be larger than the amount one query is allowed to examine.

Retention and regeneration

Advanced query data is disposable. A completed Upload Triage keeps its exact generation in a bounded warm window (normally one hour). An active investigation can also lease its Core generation, and the Query workspace shows the current retention state and remaining time.

Where your role and deployment allow it, you can:

Keep or Extend the retained query data for the displayed period.
Delete the derived query data without deleting the original capture or persisted Core findings.
Re-run capture triage when the retained generation has expired or the required family was not produced.

Deleting or expiring advanced query data does not remove saved reports, persisted Core findings, or the PCAP. A later custom query requires a new Core Triage run.

Choose the right investigation surface

Use	Best when
Display filters and packet views	You know the frames, flow, stream, or protocol expression you want to inspect directly.
Statistics and specialist dashboards	You want a prepared visual or protocol-specific summary.
Advanced capture query	You want a bounded comparison or ranking over one retained Core fact family.
Copilot	You want an interactive explanation and expect to refine the question through follow-ups.
Agent	You want PacketSafari to plan, test, correlate, and report across an investigation.