# Performance Tuning ## Purpose Pinot query costs vary widely depending on workload characteristics, data distribution, and cluster topology. This section provides the operator-facing knobs for improving latency, throughput, and resource efficiency across a Pinot cluster. Use these guides after your tables are ingesting data and you have baseline metrics to compare against. ## Tuning categories ### Query routing and fanout Control how brokers select servers and how many servers participate in each query. Reducing unnecessary fanout is the single highest-leverage tuning action for tail latency. | Page | What it covers | | --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | | [Optimizing Scatter and Gather](/operate-pinot/tuning/routing.md) | Partition pruning, time pruning, replica-group routing, single-replica routing, preferred pool routing, broker tag enforcement | | [Adaptive Server Selection](/operate-pinot/tuning/query-routing-using-adaptive-server-selection.md) | Route queries to the fastest available server using latency and in-flight request stats | | [Segment Pruning](/operate-pinot/tuning/segment-pruning.md) | Broker-side and server-side pruning strategies (time, partition, bloom filter, column value) to skip irrelevant segments | ### Query scheduling and resource isolation Prioritize production traffic over ad-hoc queries and prevent noisy-neighbor problems. | Page | What it covers | | --------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | | [Query Scheduling](/operate-pinot/tuning/query-scheduling.md) | FCFS, bounded FCFS, and token-bucket schedulers for controlling query concurrency on servers | | [Workload-Based Query Isolation](/operate-pinot/tuning/workload-query-isolation.md) | Binary workload and named-workload schedulers with per-workload CPU and memory budgets | | [OOM Protection](/operate-pinot/tuning/oom-protection-using-automatic-query-killing.md) | Heap monitoring and automatic query killing to prevent server out-of-memory crashes | ### Memory and storage Tune how Pinot maps segment data into memory and controls disk I/O. | Page | What it covers | | ----------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | | [Tuning Default MMAP Advice](/operate-pinot/tuning/tuning-default-mmap-advice.md) | Configure `posix_madvise` hints (RANDOM, SEQUENTIAL, WILL\_NEED) for memory-mapped segment files | | [Performance Optimization Configurations](/operate-pinot/tuning/performance-optimization-configurations.md) | Predicate reordering, streaming segment download, Netty native TLS and transport | | [Segment Operations Throttling](/operate-pinot/tuning/segment-operations-throttling.md) | Limit parallelism of segment download, index rebuild, and StarTree preprocessing to protect server resources | ### Real-time ingestion tuning Optimize memory, throughput, and segment sizing for tables consuming from streaming sources. | Page | What it covers | | ----------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | | [Tuning Real-time Performance](/operate-pinot/tuning/realtime.md) | Off-heap allocation, consuming segment row thresholds, completed-segment placement, split commit protocol, RealtimeProvisioningHelper | | [Pauseless Consumption](/operate-pinot/tuning/pauseless-consumption.md) | Eliminate ingestion pauses during segment commit by consuming into a new segment in parallel with build and upload | | [Pause Ingestion Based on Resource Utilization](/operate-pinot/tuning/pause-ingestion-based-on-resource-utilization.md) | Automatically pause and resume real-time ingestion when disk utilization exceeds a threshold | ## Where to start 1. **Measure first.** Collect baseline query latency (p50, p95, p99), `numSegmentsQueried`, `numDocsScanned`, and server CPU/memory utilization before changing any configuration. 2. **Reduce fanout.** Enable time and partition pruning, and consider replica-group routing if your table spans many servers. 3. **Right-size consuming segments.** Use the `RealtimeProvisioningHelper` to choose optimal segment sizes and flush thresholds for real-time tables. 4. **Protect production traffic.** Enable adaptive server selection and consider workload isolation if ad-hoc queries share the same cluster. 5. **Tune memory mapping.** On Linux, experiment with `RANDOM` madvise if your workload is point-lookup heavy, or keep the default if scans dominate. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.pinot.apache.org/operate-pinot/tuning.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.