docs/npm/network-flows/visualization/overview.md
The Network Flows view exposes the same query engine through five panel types: Sankey, Table, Time-Series, maps (country / state / city), and the 3D globe. The panels share their inputs (filters, group-by, time range, top-N) and their constraints (limits, timeout, FTS rules). This page documents what's common across them; each panel has its own page for the panel-specific reading.
The dashboard sends one of two query modes to the plugin:
flows — the normal aggregation request. Returns top-N groups, sums of bytes and packets, optional facet counts.autocomplete — for the filter ribbon. Returns up to 256 retained facet values or generated CIDR candidates. Matching policy for retained values is per-field: text fields use substring matching, IP and numeric fields use prefix. For IP address fields, / generates canonical IPv4/IPv6 CIDRs and returns only networks containing an address in that field's compact retention-wide vocabulary. Term is capped at 256 bytes. Retained-value lookup runs against in-memory facet snapshots and on-disk FST sidecars; CIDR validation uses only the in-memory typed IP vocabulary. Neither path scans flow tiers. Selected non-IP values use exact equality; selected IP values use exact-address or CIDR containment.A flows query carries:
after / before). If you omit both, the plugin uses the last 15 minutes.group_by fields (up to 10).selections — per-field IN-lists for filtering. The six IP address facets accept exact IPv4/IPv6 addresses and canonical CIDRs.facets to enrich the response with per-facet value counts.top_n (one of 25, 50, 100, 200, 500).sort_by (bytes or packets).query (full-text search; forces the raw tier).view (table-sankey, timeseries, country-map, state-map, city-map).Defaults if you don't specify: time range = last 15 minutes, group_by = ["SRC_AS_NAME", "PROTOCOL", "DST_AS_NAME"], top_n = 25, sort_by = bytes, view = table-sankey.
The plugin enforces a hard timeout of 30 seconds per query. If your query is too wide, narrow the time range, add a filter that lets a coarser tier serve it, or reduce the group-by depth.
query_max_groups (default 50000) caps the total number of distinct group keys an aggregation can build. Past this, additional groups are folded into a synthetic __overflow__ bucket and the response carries a warning. The limit exists to protect the query worker from accidentally wide group-by combinations exhausting memory.
If you see __overflow__ rows, the query is too wide for the current limit. Narrow the filter, drop a high-cardinality group_by field, or raise the limit (carefully).
The search box at the top of the filter ribbon performs a regex match against the raw journal payload bytes. Three things to know:
8.8.8.8 is a regex where each . matches any byte — so it can match 8a8b8c8, 888x888, etc. To match the literal string, escape with backslashes: 8\.8\.8\.8.Use full-text search for the cases where you don't have an indexed handle for what you're looking for. For everything else, the filter ribbon (which uses indexed fields and is much faster) is the right tool.
The dashboard URL preserves all of: time range, view, top-N, sort, group-by, selections, full-text search. Copy the URL and share it — the recipient sees exactly what you see, provided they have access to the same Netdata Cloud space.
The dashboard also remembers your last selections per session, so subsequent visits land on whatever you had open last time.
Filtering uses a structured representation (per-field IN-lists) that's easy to encode as a JSON payload but awkward to URL-encode by hand. The dashboard handles this transparently for sharing — if you script your own queries against the function, use JSON-payload requests, not GET-style args. See Filters and Facets for the details.
Each panel suits a different question:
query_max_groups).