Elasticsearch/OpenSearch and GraphQL Awareness

Two advanced-looking upgrades, two different layers

An application already uses PostgreSQL queries and REST endpoints. Product asks for typo-tolerant catalog search, faceting, and richer mobile query flexibility. It is tempting to answer with one “modern data stack” bundle: add Elasticsearch or OpenSearch and add GraphQL. That shortcut hides the decision. A search engine and GraphQL do not solve the same layer, and neither becomes mandatory because it is popular or powerful.

OpenSearch is described by its official documentation as a distributed search and analytics engine for search and analytical workloads. Elasticsearch is likewise described as a distributed search and analytics engine with full-text, filter, vector, and analytical retrieval capabilities. Those are capability FACTS, not MAKNOW adoption authority. [OPENSEARCH] [ELASTIC]

GraphQL is an open-source query language for APIs and a server-side runtime centered on a strongly typed schema; it is not tied to a particular database. That is an API-contract/runtime FACT, not evidence that the product needs a new search engine or that GraphQL automatically fixes authorization, resolver cost, consistency, or persistence. [GRAPHQL]

The lesson artifact is Search-and-API Layer Fit Decision Matrix v1. It carries two independent decision rows: SEARCH_ENGINE and GRAPHQL. Allowed states are USE, PILOT, NOT_NOW, UNKNOWN, EVIDENCE_INCOMPLETE, OWNER_MISSING, REVIEW_REQUIRED, HOLD, PARTIAL, and DISPUTED. A missing trigger never becomes a success state. A measured absent trigger can legitimately produce NOT_NOW.

Planned active time: 45 minutes.

This lesson is for a learner who must make search-engine and API-query-layer decisions independently auditable from problem fit, measured trigger, ownership, source-of-truth/security constraints, cost/failure surface, simpler alternative, and revisit evidence.

This lesson does not deploy, configure, or migrate Elasticsearch, OpenSearch, GraphQL, databases, clusters, production APIs, or adjacent Redis/Temporal/Microservices/Offline-Studio outcomes.

HARD prerequisite — AWR-001

Before entering the Fast Path, state the relevant AWR-001 boundary: why is a technology name not an adoption trigger? Then distinguish a concrete problem, a measured trigger, a simpler alternative, and an accountable owner/cost boundary. If these cannot be separated, use the bounded bridge before continuing.

Bounded bridge: recover only this rule—technology capability is not adoption evidence. A specific problem, observable trigger, simpler alternative, owner, and cost/failure boundary must be visible, and NOT_NOW can be correct. This bridge does not fabricate completion of AWR-001.

SOFT prerequisite — AWR-002

If you completed AWR-002, recall only its technology-awareness discipline: an adjacent infrastructure capability must not be imported as the decision for this lesson. Fragility here does not block entry, but it increases the chance of confusing capability with need.

Optional bridge: carry forward only the evidence-first boundary. Do not import Redis/Valkey/Temporal outcomes or their state into the search-engine or GraphQL rows.

Diagnose the layer before naming the technology

Four quick checks:

1. Users need exact ID/SKU lookup and a few stable filters. Does that alone justify a dedicated search engine?
2. Users need typo tolerance, relevance ranking, and faceting that current database/search extensions cannot meet. Can that evidence change only the SEARCH_ENGINE row?
3. One or two clients consume stable REST shapes. Does “GraphQL is flexible” establish a GraphQL trigger?
4. Many independently evolving clients need different nested representations and repeatedly over- or under-fetch. Can GraphQL move toward PILOT without explicit schema ownership, resolver boundaries, authorization, and query-cost controls?

4/4 → Fast Path. 2–3 → Repair Path. 0–1 → Foundation Path. The Fast Path compresses definitions; it never removes source-of-truth, freshness, security, owner, cost, negative-evidence, or changed-context transfer requirements.

Self-check: do not treat database size as a search trigger, a search engine as a source of truth, client preference as an API-contract trigger, or a typed schema as an automatic authorization/performance solution.

Mental model: separate retrieval from query shaping

SEARCH_ENGINE → retrieval problem → query pattern → full-text/filter/relevance/vector trigger → indexing pipeline → source of truth → freshness + consistency boundary → simpler database/search alternative → owner + cost/failure surface → bounded state

GRAPHQL → API query-shape problem → client variability → schema owner → resolver/data boundary → authorization + N+1/query-cost boundary → simpler REST/RPC alternative → owner + cost/failure surface → bounded state

The two chains do not score each other. Search can be PILOT while GraphQL is NOT_NOW; GraphQL can be PILOT while search is NOT_NOW. A search engine indexes and retrieves data; GraphQL changes how clients ask an API for typed data. [OPENSEARCH] [ELASTIC] [GRAPHQL]

Keep authority classes separate. External documentation describes FACT-level capabilities. The synthetic product fixture describes local evidence. MAKNOW DESIGN defines the state vocabulary, measured-trigger gates, and acceptance rules. If the diagram cannot render, the ordered text above is the complete text equivalent of asset://AWR-003/AWR-003-ASSET-FLOW.

Evidence contract for the two decision rows

SEARCH_ENGINE

Record technology and layer, but do not let the product name substitute for the problem. problem_class and query_pattern must make the retrieval need concrete. Keep full_text_requirement, filter_aggregation_requirement, relevance_requirement, and vector_requirement separate so one fashionable capability cannot stand in for the others. A positive decision also needs an indexing_pipeline, explicit source_of_truth, bounded freshness_lag_tolerance, and a consistency_requirement. The index must not silently become the authoritative system merely because it can answer search queries. [OPENSEARCH] [ELASTIC]

GRAPHQL

Start with client_query_variability, not with a preference for schema-first development. Positive evidence needs a schema_owner, visible resolver_boundary, authorization_boundary, and explicit n_plus_one_risk or query-cost treatment. The underlying systems remain the source of truth; GraphQL is an API query/runtime model rather than a storage engine. [GRAPHQL]

For both rows record simpler_alternative, operational_owner, cost_risk, failure_surface, evidence_ref, authority_refs, decision_state, learner-written rationale, review_due, and stop_or_pivot_trigger. These fields let a reviewer reproduce the state without hidden model reasoning.

Building Search-and-API Layer Fit Decision Matrix v1

Step 1: create two independent rows. Do not create one “advanced data stack” score.

Step 2: classify the problem before the capability. If the need is typo-tolerant full-text retrieval, ranking, faceting, aggregations, or another indexed retrieval pattern, it belongs in the search-engine row. If the need is many client-specific nested response shapes, repeated over/under-fetching, or coordinated typed API evolution, it belongs in the GraphQL row. A single product can have either, both, or neither.

Step 3: test the search trigger against the current system. Database full-text/search extensions may be the simpler alternative. A dedicated engine is not justified merely because OpenSearch or Elasticsearch supports powerful retrieval. If the trigger is present, expose duplicate-index obligations: ingestion/index pipeline, source of truth, acceptable lag, consistency semantics, authorization filtering, operational ownership, and failure behavior. [OPENSEARCH] [ELASTIC]

Step 4: test the GraphQL trigger against existing REST/RPC contracts. Stable clients with predictable shapes may be served by the current API. If client query variability is materially high, define schema ownership, resolver/data boundaries, authorization, query-cost/N+1 controls, and operational ownership before success. GraphQL capability does not erase those obligations. [GRAPHQL]

Step 5: compare a simpler alternative for each row. Search alternatives can include current database search or a bounded extension. API alternatives can include clearer REST resource design, purpose-built endpoints, or RPC contracts. NOT_NOW is defensible only when the trigger is measured absent and the simpler option actually serves the current need.

Step 6: preserve uncertainty. Missing trigger evidence is not NOT_NOW and is never USE. UNKNOWN/EVIDENCE_INCOMPLETE require unresolved decisive evidence; OWNER_MISSING requires absent accountable ownership; REVIEW_REQUIRED requires stale, out-of-tolerance, conflicting, or contradictory decisive evidence; HOLD requires an explicit hold/blocked/waiting marker; PARTIAL requires a visible mix of resolved and unresolved decisive evidence; and DISPUTED requires explicit conflict/contradiction. Do not choose a conservative label merely because it is conservative.

Step 7: write the decision last. Every success state needs its own measured trigger, owner, cost/failure evidence, and authority trace. Every row needs a review date and a stop/pivot trigger because the governing assumptions can change.

Worked example: one product, two different answers

Baseline: PostgreSQL is the source of truth and the application exposes REST endpoints. Product needs typo-tolerant catalog search, relevance ranking, and faceting. Those requirements create a real search-layer question. The matrix must still ask whether current database search capabilities are sufficient; if not, a bounded search-engine PILOT can be defensible only with a defined index pipeline, acceptable freshness lag, non-authoritative index boundary, authorization filtering, owner, cost, and failure surface. [OPENSEARCH] [ELASTIC]

At the same time, suppose the client set remains small and the response shapes are mostly stable. “Richer mobile flexibility” alone does not prove that the API layer needs GraphQL. If existing REST endpoints can be extended cleanly, the GraphQL row can remain NOT_NOW even while the search row moves to a pilot. [GRAPHQL]

Now apply the wrong-approach mutation from AWR-003-EX2: remove typo-tolerance and faceting requirements while keeping the dedicated search engine marked USE. The previous positive state is no longer justified. The changed trigger must be recomputed; popularity or already-written integration work is not evidence.

asset://AWR-003/AWR-003-ASSET-TABLE is the canonical text-equivalent evidence table. It deliberately carries the full set of trigger, source-of-truth, owner, cost, state, rationale, review, and authority fields rather than a decorative summary.

Common failure modes

1. Search-engine capability becomes adoption evidence. “Elasticsearch supports vectors” or “OpenSearch supports aggregations” is treated as the reason to adopt. Repair: return to the measured retrieval problem and simpler alternative. [OPENSEARCH] [ELASTIC]
2. Index becomes source of truth. Search results are treated as authoritative while freshness lag can exceed the product tolerance. Repair: restore the authoritative source, lag tolerance, and consistency boundary; use REVIEW_REQUIRED or another non-success state when they conflict.
3. GraphQL = better search. API query shaping is used as a substitute for indexed retrieval. Repair: restore layer separation. [GRAPHQL]
4. GraphQL = automatic API safety. A typed schema is treated as authorization, resolver ownership, and query-cost control. Repair: model each boundary explicitly.
5. Unknown becomes NOT_NOW. Decisive evidence is missing but the decision is closed anyway. Repair: preserve typed uncertainty.
6. Owner missing, state positive. No one owns the index pipeline/schema/resolver/failure surface, yet the row says PILOT. Repair: OWNER_MISSING until accountable ownership exists.
7. Adjacent outcome absorbed. Redis/Temporal or Microservices/Full Offline Studio outcomes are pulled into this lesson. Repair: restore the owned V13/C01 search/API boundary.

Experienced bridge: compress definitions, not evidence

If you already operate search engines or GraphQL systems, skip product-definition recitation and defend the decision with evidence. For the search row: which retrieval behavior is measurably missing, why is the current database/search path insufficient, what owns indexing, what is authoritative, what lag is acceptable, and what happens when the index is stale? For GraphQL: which client-contract pressure is real, who owns the schema, where do resolvers cross data boundaries, how is authorization enforced, how are expensive/N+1 queries bounded, and why is REST/RPC no longer the simpler fit?

Then state what would reverse the decision. A pilot without a stop condition is not bounded. Experienced learners still need one negative case, provenance, and changed-context transfer. Familiarity with the tools lowers explanation time, not the evidence bar.

Compare simpler alternatives before adding a new layer

Database/search extensions versus Elasticsearch/OpenSearch

A separate search engine creates another data path to ingest, operate, secure, observe, and reconcile. Its value must exceed that cost for the actual retrieval requirement. If exact lookup and basic filtering meet the need, a database-first path can remain simpler. If typo tolerance, relevance, faceting, analytical retrieval, or another indexed requirement is measured and current capabilities are inadequate, a bounded pilot can become reasonable—provided source-of-truth and freshness constraints are explicit. [OPENSEARCH] [ELASTIC]

REST/RPC versus GraphQL

GraphQL can give clients a typed query model and flexible selection of data, but that flexibility introduces schema, resolver, authorization, and query-cost responsibilities. [GRAPHQL] If client shapes are stable, clearer REST/RPC contracts may remain the smaller operational choice. If many clients evolve independently and repeatedly need different nested representations, the GraphQL trigger may become stronger.

The trade-off question is not “which technology is more modern?” It is “what is the smallest additional layer that addresses a demonstrated problem while keeping ownership, consistency, security, and failure behavior auditable?”

Guided and independent practice

Run the offline lab lab://AWR-003/AWR-003-LAB1. Every fixture is synthetic and read-only; no cluster, cloud account, credentials, customer data, or production endpoint is required. The starter exposes evidence fields, state vocabulary, and visible rules but never pre-fills the final decision.

Guided pass:

1. Choose the baseline fixture.
2. Build exactly two records: SEARCH_ENGINE and GRAPHQL.
3. Copy only the exact shipped evidence for the selected fixture.
4. Choose a state no stronger than that evidence.
5. Write your own rationale, review date, and stop/pivot trigger.
6. Run the deterministic checker and trace any failed rule back to a visible field.

Independent pass: analyze the no-search-trigger mutation, excessive index-lag mutation, GraphQL-without-authorization mutation, owner-missing fixture, and missing-evidence fixture. Finally use the transfer fixture: simple exact lookup but many client types with different nested representations. Recompute both rows; do not copy the baseline.

What makes the evidence package acceptable?

A reviewer must be able to reconstruct both decisions from visible fields. For the search row that means the retrieval problem, query pattern, full-text/filter/relevance/vector requirements, indexing pipeline, authoritative source, lag tolerance, consistency/security boundary, simpler alternative, owner, cost/failure surface, and traceable evidence. For GraphQL it means client query variability, schema owner, resolver/data boundary, authorization, N+1/query-cost handling, underlying source-of-truth boundary, simpler alternative, owner, and failure surface.

authority_refs must distinguish FACT from DESIGN. OPENSEARCH and ELASTIC support search-engine capability boundaries; GRAPHQL supports the typed API query/runtime boundary; claim AWR-003-K4 supplies MAKNOW decision authority. [OPENSEARCH] [ELASTIC] [GRAPHQL]

The checker validates exact fixture binding and visible consistency rules. It does not contain an expected-verdict oracle. AI may organize supplied evidence and deterministic comparisons, but it may not invent a measured trigger, owner, production approval, migration success, or operational evidence.

Assessment and transfer

AWR-003-F1: retrieve the owned search/API boundary and one adjacent non-goal.

AWR-003-F2: diagnose the mutation that removes typo-tolerance and faceting requirements while the dedicated search engine remains marked USE. Identify the invalid field/state and the minimal repair.

AWR-003-F3: recompute a changed-context decision instead of copying the baseline.

AWR-003-S1: explain the owned boundary and one non-goal.

AWR-003-S2: build the complete Search-and-API Layer Fit Decision Matrix v1 from the baseline synthetic fixture.

AWR-003-S3: diagnose the removed-search-trigger mutation, including consequence and minimal repair.

AWR-003-S4: a second product has simple exact lookup but many client types requiring different nested representations and frequent over/under-fetching. Recompute the matrix and show why GraphQL may move toward PILOT while a dedicated search engine remains NOT_NOW.

Transfer passes only when each row changes because its own evidence changes. “The second product is more advanced” is not an acceptable reason.

Sources and freshness boundary

OPENSEARCH — official OpenSearch introduction; supports the bounded FACT that OpenSearch is a distributed search and analytics engine used for search/analytics workloads. [OPENSEARCH]

ELASTIC — current Elastic description of Elasticsearch search, analytics, full-text/filter/vector retrieval capabilities. [ELASTIC]

GRAPHQL — GraphQL Foundation overview; supports the bounded FACT that GraphQL is a typed API query language and server-side runtime independent of a particular storage engine. [GRAPHQL]

These source identities and claim boundaries were retrieved on 2026-09-03 and carry review due 2026-12-02. No live refresh is performed in this authoring stage because the locked policy says to recheck at the declared review date or earlier only if cited platform semantics materially change. External documentation remains capability FACT authority; MAKNOW trigger thresholds, state vocabulary, and adoption gates remain DESIGN authority. Claim scope is not expanded beyond the Bible.