Query Size Limit

Reject or observe MongoDB messages that exceed a configured byte threshold.

This page belongs to the immutable 0.2.0 Private Preview documentation.

At a glance

Property	Value
Pipeline phase	Request
Category	Security
Canonical minimum tier	Free
Legacy dashboard tier label	Free
Legacy rendered name	Query Size Limit
Legacy rendered summary	Block oversized requests that could overwhelm your MongoDB cluster.
Canonical entitlement	Yes
Supported deployment contract	Yes
Release status	Reconciled and executable. After edits, reconcile the owning NexoProxy and verify the active graph revision.

Release accuracy

• 0.2.0 Private Preview: Reconciled and executable. After edits, reconcile the owning NexoProxy and verify the active graph revision.

The detailed material below preserves every section rendered by the legacy dashboard. Where it conflicts with the release status above, the release status is authoritative. Legacy field names and examples are not a substitute for the selected bundle's CRD and runtime contract. Unsafe legacy wording is retained in metadata for traceability but is corrected in the rendered guidance.

Release-aware feature flow. The diagram is explanatory; the release status on this page is authoritative.

Diagram resources: Open the SVG full screen · Download the editable Excalidraw source

Performance impact

:::warning Legacy, unverified performance claims

These numbers are preserved for documentation parity with the legacy dashboard. They are not current benchmarks or service guarantees and have not been verified by the current test suite.

:::

Percentile	Legacy claim
P50	0.02ms
P95	0.05ms
P99	0.08ms

Legacy note: Single integer comparison — the fastest possible step. Zero allocations.

Overview

The Query Size Limit step enforces a maximum request body size at the proxy layer — before the query reaches MongoDB. This protects your cluster from accidental (or malicious) oversized bulk inserts, large document writes, or runaway aggregation pipelines.

When a request exceeds the limit, the proxy returns a synthetic error response to the client without forwarding the request to MongoDB, preserving server resources.

When to use

• Protecting MongoDB from accidental bulk inserts that exceed memory limits
• Enforcing API contracts where request size should be bounded
• Preventing a single client from saturating network bandwidth to the cluster
• Defense-in-depth alongside MongoDB's built-in 16MB BSON limit

How it works

1. Request phase only: Reads the OP_MSG body length from the wire protocol header (no BSON parsing needed).
2. Compares against the configured max size.
3. If exceeded: returns a synthetic OP_MSG error response (\{ok: 0, errmsg: "request too large"\}) and short-circuits the pipeline.
4. If within limit: passes through unchanged.

Configuration

The table preserves the legacy dashboard field reference. “Not specified” means the legacy source did not declare required semantics.

Field	Legacy UI type	Legacy default	Required	Description
max_size_bytes	number	4194304	Yes	Maximum allowed request body size in bytes
action	select	block	No	What to do when limit is exceeded: block or warn

Settings reference

The legacy page did not render an additional anchored settings reference.

Examples

Block requests over 4MB

steps:
  - name: builtin:query-size-limit
    config:
      max_size_bytes: 4194304
      action: block

Warn but allow (monitoring mode)

steps:
  - name: builtin:query-size-limit
    config:
      max_size_bytes: 8388608
      action: warn

Best practices

• Set to 4MB (4194304) as a sensible default — most legitimate queries are under 1MB
• Use "warn" mode first in production to understand your baseline before blocking
• Pair with Metrics step to track nexo_oversized_requests_total counter

Limitations

• Checks total message size, not individual document size within a batch
• Cannot differentiate between insert and query payloads (applies uniformly)

Security and operational guidance

• Account for legitimate bulk operations
• The limit applies to the complete message rather than each document
• Roll out with observation before rejection where possible
• The pinned Proxy controller does not watch NexoQuerySizeLimit directly

Related steps

• filter
• rate-limit

Release availability

• 0.2.0 Private Preview: Reconciled and executable. After edits, reconcile the owning NexoProxy and verify the active graph revision.

See the component catalog for the complete comparison matrix.