Skipping the absolute basics, this chapter builds the mental model you need before touching architecture: how OpenSearch actually stores and finds text, and how a domain is organized internally.

The Inverted Index, Precisely

An inverted index is not just “a fast lookup table.” It is a structure that maps every unique term to a sorted list of document IDs (a postings list) in which that term appears, along with positional and frequency data. When you search for “dragons,” OpenSearch does not scan documents — it jumps straight to the “dragons” entry and intersects its postings list with the postings lists of any other terms in your query. This is why full-text search on billions of documents can still return in single-digit milliseconds: the expensive scanning work was already done at indexing time, not at query time.

You may likeAWS Batch→

Documents, Mappings, and Field Types

A document in OpenSearch is a JSON object, but how each field inside it is stored is controlled by a mapping — essentially a schema. Two field types matter most at the intermediate level: text fields are analyzed (broken into tokens, lowercased, stemmed) so they support fuzzy full-text search, while keyword fields are stored exactly as-is and are used for filtering, sorting, and aggregations. Mixing these up is one of the most common sources of “why isn’t my search working” bugs.

Analyzers: The Text Processing Pipeline

An analyzer is a chain of three stages: a character filter (strips or replaces raw characters, like HTML tags), a tokenizer (splits text into individual tokens, usually on whitespace and punctuation), and one or more token filters (lowercasing, stemming, removing stop-words like “the” and “a”). OpenSearch ships a “standard” analyzer by default, but production systems almost always customize this — for example, adding a synonym filter so “car” and “automobile” match each other.

Segments: The Real Unit of Storage

Underneath every shard sits Lucene, and Lucene never modifies data in place. Every batch of new documents is written to a brand-new, immutable file called a segment. A shard is really a living collection of many segments, searched together and periodically merged into fewer, larger segments in the background. Understanding segments is the single biggest unlock for reasoning about indexing performance, memory use, and search latency — nearly every performance conversation about OpenSearch eventually comes back to segment behavior.

A domain is not one server pretending to be smart — it’s a coordinated group of specialized nodes, each with a job.

Node Roles Inside a Domain

Every node in an OpenSearch domain can be assigned one or more roles, and AWS lets you size each role independently for cost and performance control.

Cluster Manager Election and Cluster State

The elected master node — internally called the cluster manager — holds the single source of truth for the cluster: the mapping of every index to its shards, which node holds each shard copy, and the domain’s settings. Every other node keeps a cached copy of this cluster state and updates it whenever the master publishes a change. If the current master node fails, the remaining master-eligible nodes run an election (based on the Raft-like protocol OpenSearch uses) to pick a new one, typically completing within seconds.

OpenSearch Dashboards and Plugins

Every domain can optionally run OpenSearch Dashboards, a visualization and exploration layer, on its own dedicated nodes so dashboard traffic never competes with search or indexing workloads. AWS also bundles several plugins directly into the managed service: the Security plugin (fine-grained access control), the Alerting plugin (threshold-based notifications), the Anomaly Detection plugin (unsupervised outlier detection), and the k-NN plugin (vector similarity search, widely used for machine-learning and generative-AI retrieval use cases).

graph TD
    Client[Client Application] --> LB[Domain Endpoint]
    LB --> C1[Coordinating Node]
    C1 --> D1[Data Node 1 - Shard 0]
    C1 --> D2[Data Node 2 - Shard 1]
    C1 --> D3[Data Node 3 - Shard 2]
    M1[Master Node 1] -.cluster state.-> D1
    M1 -.cluster state.-> D2
    M1 -.cluster state.-> D3
    M2[Master Node 2] -.standby.-> M1
    M3[Master Node 3] -.standby.-> M1
        

Every search request that looks instant to a user is actually a two-phase, distributed protocol underneath.

The Query-Then-Fetch Protocol

When a search request arrives at a coordinating node, it does not simply ask every shard “give me your top 10 results.” Instead, OpenSearch runs a query phase first: it broadcasts the query to one copy (primary or replica) of every shard in the target index, and each shard returns only the IDs and relevance scores of its local top matches — not the full documents. The coordinating node merges these scored ID lists into a single globally ranked list and figures out exactly which documents are needed for the final page of results. Only then does the fetch phase begin: the coordinating node requests the full document bodies for just that final set of IDs from the shards that hold them. This two-step dance is why deep pagination (asking for result number 50,000) is expensive — the query phase still has to rank far more candidates than the fetch phase ultimately returns.

BM25: How Relevance Is Actually Scored

OpenSearch’s default relevance algorithm, BM25, scores a document higher when a query term appears more frequently inside it (term frequency), but with diminishing returns so that a document repeating a word fifty times doesn’t dominate unfairly. It also boosts terms that are rare across the whole index (inverse document frequency) — matching on the word “the” counts for almost nothing, while matching on a rare product code counts for a great deal. A field-length normalization factor further ensures that a short field matching a term scores higher than a very long field matching the same term by coincidence.

Refresh, Flush, and Merge

A newly indexed document is not immediately searchable. It first sits in an in-memory buffer. A background refresh operation (by default every second) writes that buffer into a new, searchable-but-not-yet-durable Lucene segment. Separately, a flush operation periodically writes an on-disk transaction log (the translog) to guarantee durability, and a merge process continuously combines many small segments into fewer, larger ones to keep search fast and reclaim space from deleted documents. These three background jobs run independently and are the real engine behind everything you experience as “OpenSearch performance.”

Data in OpenSearch has a full life story — from the moment it’s written to the moment it’s aged out and deleted.

The Indexing Path

A write request first lands on a coordinating node, which routes it to the correct primary shard using a hash of the document’s routing value (by default, its ID). The primary shard indexes the document, writes it to its translog, and then forwards the same operation to every replica shard in parallel. The client only receives a success response once the primary and all in-sync replicas have acknowledged the write — this replica acknowledgment is what gives OpenSearch its durability guarantee.

sequenceDiagram
    participant App as Application
    participant Coord as Coordinating Node
    participant Primary as Primary Shard
    participant Replica as Replica Shard
    App->>Coord: Index document
    Coord->>Primary: Route by document ID
    Primary->>Primary: Write to translog + memory buffer
    Primary->>Replica: Replicate operation
    Replica-->>Primary: Acknowledge
    Primary-->>Coord: Acknowledge
    Coord-->>App: Success response
        

Index State Management (ISM) and the Hot-Warm-Cold Model

For time-series data such as logs and metrics, OpenSearch offers Index State Management, a policy engine that automatically moves indices through lifecycle states as they age: hot (actively written and queried, on fast instance storage), warm (read-mostly, moved to cheaper UltraWarm storage backed by Amazon S3), and cold (rarely accessed, kept in S3 and only attached back to the domain on demand). A typical ISM policy might say: “roll over to a new index every 50GB or 24 hours, move to warm after 7 days, move to cold after 30 days, delete after 90 days.” This turns a manual operational chore into a hands-off, cost-optimized pipeline.

Snapshots as a Lifecycle Safety Net

Independent of ISM, OpenSearch domains take automated daily snapshots to a managed Amazon S3 repository at no extra storage cost, and you can also configure manual snapshots to your own S3 bucket. Snapshots are incremental — only new or changed segment files are copied after the first full snapshot — which makes even frequent backups cheap in both time and storage.

Scalability in OpenSearch is really a shard-sizing problem wearing a performance-tuning costume.

Shard Sizing: The Single Biggest Performance Lever

AWS’s general guidance is to keep individual shard sizes between roughly 10GB and 50GB. Too many tiny shards waste memory and CPU on coordination overhead (every shard has fixed per-shard cost, regardless of size), while shards that grow too large become slow to search, slow to recover after a node failure, and slow to relocate during scaling events. Because shard count is fixed at index-creation time for the primary shards, this decision has to be made upfront based on projected data volume — getting it wrong later means reindexing into a new index.

You may likeEC2 Auto Scaling→

Bulk Indexing and Throughput Tuning

Indexing documents one at a time is dramatically slower than batching them, because every individual write incurs network round-trip and coordination overhead. The bulk API amortizes that cost across hundreds or thousands of documents per request. For very high-throughput ingestion, temporarily increasing the refresh interval (so segments are created less often during a bulk load) and temporarily setting the number of replicas to zero (re-enabling them after the load finishes) can multiply indexing throughput several times over.

Caching Layers That Speed Up Repeated Queries

Auto-Tune

Amazon OpenSearch Service includes an Auto-Tune feature that continuously monitors a domain’s performance and automatically adjusts internal settings such as queue sizes and JVM garbage collector parameters, applying changes during low-traffic windows to avoid disrupting production workloads.

A search cluster that goes down during an incident is worse than no search cluster at all — availability design here is non-negotiable.

Zone Awareness Across Availability Zones

When zone awareness is enabled, AWS spreads a domain’s nodes across two or three Availability Zones and ensures that primary and replica copies of the same shard never live in the same zone. If an entire Availability Zone loses power or network connectivity, every shard still has an intact copy running in a healthy zone, and the domain keeps serving both reads and writes without manual intervention.

graph LR
    subgraph AZ1[Availability Zone A]
    P0[Primary Shard 0]
    R1[Replica Shard 1]
    end
    subgraph AZ2[Availability Zone B]
    P1[Primary Shard 1]
    R0[Replica Shard 0]
    end
    subgraph AZ3[Availability Zone C]
    M[Master Node]
    end
        

Replica Shards as the First Line of Defense

Every replica is a full, independent copy of a primary shard’s data. Replicas serve two purposes at once: they let search requests be load-balanced across more copies of the data for higher read throughput, and they act as an automatic failover target — if a primary shard’s node dies, OpenSearch instantly promotes one of its replicas to primary with no data loss, as long as that replica was fully in sync.

Snapshot and Restore for Disaster Recovery

Beyond the automated daily snapshot, teams running mission-critical domains configure manual snapshots to a customer-owned S3 bucket and, for the highest tier of resilience, use cross-cluster replication to maintain a warm-standby domain in a separate AWS Region entirely, ready to take over if an entire Region becomes unavailable.

Search domains often hold an organization’s most sensitive aggregated data — logs, user records, transaction history — so security is layered, not optional.

Network-Level Isolation with VPC Access

A domain can be placed inside a VPC, making it reachable only from within that private network (or through VPN/Direct Connect), rather than exposing a public endpoint on the internet. AWS strongly recommends VPC access for any production domain handling sensitive data.

Identity: IAM Policies and Fine-Grained Access Control

Two separate but complementary layers control who can do what. IAM-based access policies attached to the domain control coarse-grained access — which AWS principals can reach the domain endpoint at all. The Fine-Grained Access Control feature, built on the OpenSearch Security plugin, then controls access at the index, document, and even field level — for example, letting a support-team role see only their own tenant’s documents inside a shared index, or masking a sensitive field like a customer’s email address for a particular role.

Audit Logging

The Security plugin can emit detailed audit logs recording authentication attempts, index-level access, and configuration changes, which can be streamed to Amazon CloudWatch Logs for long-term retention and compliance review — an essential capability for regulated industries.

You cannot tune what you cannot see — OpenSearch domains expose a rich set of operational signals.

You may likeAmazon Timestream→

CloudWatch Metrics That Actually Matter

Slow Logs and the Performance Analyzer

OpenSearch can log any search or indexing operation that exceeds a configurable latency threshold into a dedicated slow log, streamed to CloudWatch Logs, making it easy to spot the specific queries dragging down a cluster. The Performance Analyzer plugin goes further, exposing granular, near-real-time metrics — thread pool queues, disk I/O, shard-level latency — that are invaluable when diagnosing a live incident rather than reconstructing it after the fact.

Alerting on Anomalies

The built-in Alerting plugin lets you define monitors — scheduled queries against your data — paired with triggers that fire when a condition is met, sending notifications through Amazon SNS, Slack, or email. Combined with the Anomaly Detection plugin, which uses an unsupervised machine-learning algorithm to learn a metric’s normal pattern, teams can get notified of unusual spikes (a sudden surge in failed logins, for example) without hand-writing a threshold for every possible scenario.

Choosing how to run a domain is a real architectural decision, not just a checkbox.

Provisioned Domains vs. Amazon OpenSearch Serverless

A traditional provisioned domain requires you to choose instance types and counts for data, master, and optionally warm/ingest nodes — giving full control but requiring capacity planning. Amazon OpenSearch Serverless removes this entirely: it automatically provisions and scales compute capacity in units, charging based on actual usage, which suits unpredictable or spiky workloads at the cost of some configuration flexibility.

Instance Types and Reserved Instances

AWS offers general-purpose, compute-optimized, memory-optimized, and storage-dense (I3/I4) instance families for OpenSearch nodes, letting you match hardware to workload — memory-optimized instances for aggregation-heavy analytics dashboards, storage-dense instances for high-volume log retention. For steady-state production workloads, Reserved Instances offer a significant discount over on-demand pricing in exchange for a one- or three-year commitment.

Cross-Cluster Search and Replication

Cross-cluster search lets a single query span multiple domains, useful when data is intentionally partitioned across Regions or business units but still needs to be queried together. Cross-cluster replication, by contrast, continuously copies indices from a leader domain to one or more follower domains, commonly used for both disaster recovery and to serve read traffic closer to users in another Region.

Most OpenSearch outages trace back to one of a handful of well-known anti-patterns.

Pattern: The Time-Based Index Pattern

Rather than one enormous index growing forever, time-series workloads create a fresh index per day, week, or rollover threshold (for example, logs-2026.09.10), aliased under a single writable name. This makes deleting old data as cheap as dropping an entire index — instantaneous compared to searching for and deleting individual documents — and pairs naturally with Index State Management for automated lifecycle transitions.

Pattern: Alias-Based Zero-Downtime Reindexing

Because shard count cannot change after index creation, fixing a mis-sized or mis-mapped index requires creating a new index with correct settings, using the reindex API to copy data over, and then atomically flipping a read/write alias from the old index to the new one — all without the application ever needing to know the underlying index name changed.

Not directly — primary shard count is fixed at creation. You reindex into a new index with the desired shard count and switch a read/write alias over, which can be done with zero application downtime.

The managed service runs the open-source OpenSearch engine but adds AWS-specific operational features on top — automated patching, dedicated master nodes, IAM integration, UltraWarm/cold storage tiers, and Auto-Tune — that you would otherwise have to build yourself.

No — they solve different problems. VPC access controls network-level reachability; fine-grained access control governs what an already-authenticated caller is allowed to see or do. Production systems typically use both together.

Whenever old data still has occasional query or compliance value. If data truly has zero future value, an ISM policy that deletes it outright after a retention period is simpler and cheaper than moving it to a warm tier first.

Not necessarily. Each additional replica improves read throughput and fault tolerance, but also multiplies indexing work and storage cost, since every replica must independently receive and store every write.

Amazon OpenSearch Service takes the distributed, segment-based search engine at the heart of OpenSearch and wraps it in managed infrastructure, AWS-native security, and cost-optimized storage tiers. Everything from relevance scoring to disaster recovery ultimately traces back to a small set of core mechanics — shards, segments, the query-then-fetch protocol, and replica-based replication — so understanding those internals well pays off across every operational decision you’ll make: sizing, security, monitoring, and lifecycle management alike.

You may likeAWS PrivateLink→