Elasticsearch/OpenSearch و GraphQL Awareness

دو upgrade پیشرفته‌نما، دو لایه‌ی کاملاً متفاوت

یک application همین حالا PostgreSQL query و REST endpoint دارد. Product از typo-tolerant catalog search، faceting و flexibility بیشتر برای mobile query حرف می‌زند. shortcut وسوسه‌کننده این است که همه‌ی این‌ها را یک «advanced data stack» ببینیم و هم Elasticsearch/OpenSearch و هم GraphQL را اضافه کنیم. مسئله همین‌جاست: search engine و GraphQL یک لایه را حل نمی‌کنند و هیچ‌کدام صرفاً به‌خاطر قدرت یا محبوبیتشان trigger adoption نیستند.

طبق documentation رسمی، OpenSearch یک distributed search and analytics engine برای search و analytical workload است. Elasticsearch نیز به‌عنوان distributed search/analytics engine با full-text، filter، vector و analytical retrieval capability توصیف می‌شود. این‌ها FACT مربوط به capability هستند، نه مجوز adoption در MAKNOW. [OPENSEARCH] [ELASTIC]

GraphQL یک query language متن‌باز برای API و یک server-side runtime مبتنی بر strongly typed schema است و به database مشخصی وابسته نیست. این هم FACT مربوط به API contract/runtime است؛ نه search engine است، نه persistence system، و نه authorization، resolver cost، consistency یا performance را خودکار حل می‌کند. [GRAPHQL]

Artifact درس Search-and-API Layer Fit Decision Matrix v1 است و دو row مستقل دارد: SEARCH_ENGINE و GRAPHQL. stateهای مجاز: USE، PILOT، NOT_NOW، UNKNOWN، EVIDENCE_INCOMPLETE، OWNER_MISSING، REVIEW_REQUIRED، HOLD، PARTIAL و DISPUTED. evidence گمشده هیچ‌وقت success نمی‌شود؛ trigger اندازه‌گیری‌شده و غایب می‌تواند NOT_NOW کاملاً صحیح بسازد.

زمان فعال برنامه‌ریزی‌شده: ۴۵ دقیقه.

این درس برای یادگیرنده‌ای است که باید search-engine decision و API query-layer decision را جداگانه و از روی problem fit، measured trigger، owner، source-of-truth/security boundary، cost/failure surface، simpler alternative و revisit evidence قابل ممیزی کند.

این درس Elasticsearch، OpenSearch، GraphQL، database، cluster یا production API را deploy/configure/migrate نمی‌کند و outcomeهای Redis/Temporal یا Microservices/Full Offline Studio را جذب نمی‌کند.

پیش‌نیاز HARD — AWR-001

قبل از Fast Path مرز لازم از AWR-001 را در یک جمله بگویید: چرا اسم technology به‌تنهایی trigger نیست؟ سپس problem مشخص، measured trigger، simpler alternative و accountable owner/cost boundary را از هم جدا کنید. اگر این چهار جزء برایتان مخلوط است، اول bounded bridge را فعال کنید.

Bounded bridge فقط این rule را بازیابی می‌کند: capability فناوری adoption evidence نیست؛ باید problem مشخص، trigger مشاهده‌پذیر، alternative ساده‌تر، owner و cost/failure boundary visible باشند و NOT_NOW می‌تواند تصمیم درست باشد. این bridge outcome قبلی را fabricate یا complete نمی‌کند.

پیش‌نیاز SOFT — AWR-002

اگر AWR-002 را گذرانده‌اید، فقط discipline evidence-first آن را بازیابی کنید: capability زیرساخت مجاور نباید به‌عنوان decision این درس وارد شود. ضعف این بخش entry را block نمی‌کند، اما ریسک «capability = need» را بالا می‌برد.

Bridge اختیاری: فقط مرز evidence-first را حمل کنید. outcome یا state مربوط به Redis/Valkey/Temporal را داخل rowهای Search Engine یا GraphQL وارد نکنید.

اول layer را تشخیص دهید، بعد اسم technology را بیاورید

چهار check سریع:

1. کاربر فقط exact ID/SKU lookup و چند filter پایدار می‌خواهد. آیا همین evidence یک dedicated search engine را justify می‌کند؟
2. typo tolerance، relevance ranking و faceting لازم است و capability فعلی database/search extension کافی نیست. آیا این evidence فقط row SEARCH_ENGINE را می‌تواند تغییر دهد؟
3. یک یا دو client با REST shape پایدار داریم. آیا «GraphQL flexible است» trigger کافی است؟
4. clientهای متعدد و مستقل nested representationهای متفاوت می‌خواهند و over/under-fetch تکراری است. آیا بدون schema owner، resolver boundary، authorization و query-cost control می‌توان GraphQL را PILOT کرد؟

۴/۴ → Fast Path. ۲–۳ → Repair Path. ۰–۱ → Foundation Path. Fast Path تعریف‌ها را کوتاه می‌کند اما source-of-truth، freshness، security، owner، cost، negative evidence و transfer را حذف نمی‌کند.

Self-check: database size را search trigger نگیرید، search index را source of truth فرض نکنید، client preference را API-contract trigger ننامید و typed schema را معادل authorization/performance solution ندانید.

مدل ذهنی: retrieval را از query shaping جدا کنید

SEARCH_ENGINE → retrieval problem → query pattern → full-text/filter/relevance/vector trigger → indexing pipeline → source of truth → freshness + consistency boundary → 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 → REST/RPC alternative → owner + cost/failure surface → bounded state

این دو chain به هم امتیاز نمی‌دهند. Search می‌تواند PILOT و GraphQL NOT_NOW باشد یا برعکس. Search engine داده را index/retrieve می‌کند؛ GraphQL مدل typed query/runtime برای API است. [OPENSEARCH] [ELASTIC] [GRAPHQL]

سه authority layer را جدا نگه دارید: external documentation برای FACT capability است؛ synthetic fixture evidence محلی را می‌دهد؛ MAKNOW DESIGN state vocabulary و gate adoption را تعیین می‌کند. اگر diagram render نشد، همین ordered text معادل کامل asset://AWR-003/AWR-003-ASSET-FLOW است.

Evidence Contract دو row

SEARCH_ENGINE

technology و layer را ثبت کنید، اما نام product را جای problem ننشانید. problem_class و query_pattern باید retrieval need را دقیق کنند. full_text_requirement، filter_aggregation_requirement، relevance_requirement و vector_requirement را جدا نگه دارید تا یک capability مد روز جای بقیه evidenceها را نگیرد. positive decision همچنین به indexing_pipeline، source_of_truth صریح، freshness_lag_tolerance محدود و consistency_requirement نیاز دارد. index نباید فقط چون search answer می‌دهد به authority اصلی داده تبدیل شود. [OPENSEARCH] [ELASTIC]

GRAPHQL

از client_query_variability شروع کنید، نه preference برای schema-first. positive evidence به schema_owner، resolver_boundary، authorization_boundary و treatment صریح n_plus_one_risk/query cost نیاز دارد. سیستم‌های underlying همچنان source of truth هستند؛ GraphQL storage engine نیست. [GRAPHQL]

در هر دو row، simpler_alternative، operational_owner، cost_risk، failure_surface، evidence_ref، authority_refs، decision_state، rationale نوشته‌ی learner، review_due و stop_or_pivot_trigger را نگه دارید. Reviewer باید بدون hidden reasoning بتواند state را بازسازی کند.

ساخت Search-and-API Layer Fit Decision Matrix v1

گام ۱: دو row مستقل بسازید. یک score واحد برای «advanced data stack» مجاز نیست.

گام ۲: problem را قبل از capability classify کنید. اگر مسئله typo-tolerant full-text retrieval، ranking، faceting، aggregation یا indexed retrieval مشابه است، در search row قرار می‌گیرد. اگر مسئله clientهای متعدد با nested response shape متفاوت، over/under-fetch تکراری یا evolution هماهنگ typed API است، در GraphQL row قرار می‌گیرد. یک محصول می‌تواند یکی، هر دو یا هیچ‌کدام را لازم داشته باشد.

گام ۳: search trigger را علیه سیستم موجود test کنید. database full-text/search extension می‌تواند simpler alternative باشد. اینکه OpenSearch یا Elasticsearch retrieval قوی دارد به‌تنهایی adoption را justify نمی‌کند. اگر trigger present بود، duplicate index obligation را visible کنید: ingestion/index pipeline، source of truth، lag مجاز، consistency، authorization filtering، operational owner و failure behavior. [OPENSEARCH] [ELASTIC]

گام ۴: GraphQL trigger را علیه REST/RPC فعلی بسنجید. client پایدار با shape قابل پیش‌بینی ممکن است با API فعلی بهتر سرو شود. اگر client query variability واقعاً بالا است، قبل از success باید schema ownership، resolver/data boundary، authorization، query-cost/N+1 control و operational ownership روشن باشد. GraphQL این responsibilityها را حذف نمی‌کند. [GRAPHQL]

گام ۵: برای هر row simpler alternative را مقایسه کنید. search alternative می‌تواند database search یا extension محدود باشد؛ API alternative می‌تواند REST resource بهتر، purpose-built endpoint یا RPC contract باشد. NOT_NOW فقط وقتی درست است که trigger measured absent باشد و alternative فعلی واقعاً نیاز را پوشش دهد.

گام ۶: uncertainty را preserve کنید. evidence گمشده NOT_NOW نیست و هرگز USE نمی‌شود. UNKNOWN/EVIDENCE_INCOMPLETE فقط برای decisive evidence حل‌نشده‌اند؛ OWNER_MISSING به نبود owner پاسخ‌گو نیاز دارد؛ REVIEW_REQUIRED فقط با evidence stale، خارج از tolerance، conflicting یا contradictory معتبر است؛ HOLD به marker صریح hold/blocked/waiting نیاز دارد؛ PARTIAL یعنی بخشی از decisive evidence resolved و بخشی unresolved است؛ و DISPUTED به conflict/contradiction صریح نیاز دارد. صرف محافظه‌کارانه‌بودن یک label دلیل انتخاب آن نیست.

گام ۷: decision را آخر بنویسید. success state به measured trigger، owner، cost/failure evidence و authority trace خودش نیاز دارد. هر row باید review date و stop/pivot trigger داشته باشد، چون assumptionها می‌توانند تغییر کنند.

Worked Example: یک محصول، دو answer متفاوت

Baseline: PostgreSQL source of truth است و application REST endpoint دارد. Product typo-tolerant catalog search، relevance ranking و faceting می‌خواهد. این requirement یک search-layer question واقعی می‌سازد. بااین‌حال matrix باید اول بپرسد capability فعلی database search کافی است یا نه؛ اگر کافی نبود، search-engine PILOT فقط وقتی دفاع‌پذیر است که index pipeline، freshness lag قابل‌قبول، non-authoritative index boundary، authorization filtering، owner، cost و failure surface تعریف شده باشد. [OPENSEARCH] [ELASTIC]

هم‌زمان فرض کنید clientها کم و response shapeها mostly stable هستند. «mobile flexibility بیشتر» به‌تنهایی ثابت نمی‌کند API layer به GraphQL نیاز دارد. اگر REST endpointهای فعلی cleanly قابل گسترش‌اند، GraphQL می‌تواند NOT_NOW بماند حتی وقتی search row به pilot می‌رود. [GRAPHQL]

حالا mutation مربوط به AWR-003-EX2 را اعمال کنید: typo tolerance و faceting حذف شده اما dedicated search engine هنوز USE است. positive state قبلی دیگر evidence ندارد و باید trigger را از نو محاسبه کنید؛ popularity یا sunk implementation effort evidence نیست.

asset://AWR-003/AWR-003-ASSET-TABLE canonical text-equivalent matrix است و عمداً full trigger/source-of-truth/owner/cost/state/rationale/review/authority fields را نگه می‌دارد، نه یک summary تزئینی.

Failure Modeهای رایج

1. Capability search engine به adoption evidence تبدیل می‌شود. «Elasticsearch vector دارد» یا «OpenSearch aggregation دارد» دلیل adoption فرض می‌شود. Repair: به measured retrieval problem و simpler alternative برگردید. [OPENSEARCH] [ELASTIC]
2. Index به source of truth تبدیل می‌شود. search result authoritative فرض می‌شود درحالی‌که freshness lag از tolerance بیشتر است. Repair: authority اصلی، lag tolerance و consistency boundary را restore کنید؛ در conflict از REVIEW_REQUIRED یا state غیرموفق استفاده کنید.
3. GraphQL = search بهتر. API query shaping جای indexed retrieval نشانده می‌شود. Repair: layer separation را برگردانید. [GRAPHQL]
4. GraphQL = API safety خودکار. typed schema را معادل authorization، resolver ownership و query-cost control می‌گیرید. Repair: هر boundary را explicit کنید.
5. Unknown → NOT_NOW. evidence decisive گم است ولی تصمیم بسته می‌شود. Repair: typed uncertainty را حفظ کنید.
6. Owner missing → positive. کسی index pipeline/schema/resolver/failure surface را own نمی‌کند اما state PILOT است. Repair: تا owner واقعی OWNER_MISSING بماند.
7. Adjacent scope absorption. outcome Redis/Temporal یا Microservices/Offline داخل این درس کشیده می‌شود. Repair: V13/C01 search/API boundary را restore کنید.

Bridge برای افراد باتجربه: تعریف را کوتاه، evidence را کامل نگه دارید

اگر search engine یا GraphQL را در production می‌شناسید، تعریف product را فشرده کنید اما decision evidence را حذف نکنید. برای search row بگویید کدام retrieval behavior اندازه‌گیری شده و کم است، database/search path فعلی چرا کافی نیست، indexing را چه کسی own می‌کند، source of truth چیست، چه lagی مجاز است و stale index چه failureی می‌سازد. برای GraphQL بگویید کدام client-contract pressure واقعی است، schema owner کیست، resolver کجا data boundary را قطع می‌کند، authorization چگونه enforce می‌شود، queryهای expensive/N+1 چگونه bounded هستند و چرا REST/RPC دیگر alternative ساده‌تر نیست.

بعد بگویید چه چیزی decision را برمی‌گرداند. pilot بدون stop condition bounded نیست. Experienced Path همچنان negative case، provenance و changed-context transfer می‌خواهد. familiarity زمان توضیح را کم می‌کند، نه evidence bar را.

قبل از اضافه‌کردن layer جدید، simpler alternative را مقایسه کنید

Database/search extension در برابر Elasticsearch/OpenSearch

Search engine جدا یک data path دیگر برای ingest، operation، security، observability و reconciliation می‌سازد. ارزش آن باید برای requirement واقعی از این هزینه بیشتر باشد. اگر exact lookup و filtering ساده کافی است، database-first path می‌تواند ساده‌تر بماند. اگر typo tolerance، relevance، faceting، analytical retrieval یا requirement indexed دیگری اندازه‌گیری شده و capability فعلی ناکافی است، bounded pilot منطقی‌تر می‌شود—به شرط اینکه source-of-truth و freshness explicit باشند. [OPENSEARCH] [ELASTIC]

REST/RPC در برابر GraphQL

GraphQL typed query model و selection انعطاف‌پذیر برای client می‌دهد، اما schema، resolver، authorization و query-cost responsibility ایجاد می‌کند. [GRAPHQL] اگر client shapeها stable هستند، REST/RPC روشن می‌تواند operational choice کوچک‌تری باشد. اگر clientهای متعدد مستقل مرتب nested representation متفاوت می‌خواهند، GraphQL trigger قوی‌تر می‌شود.

سؤال trade-off این نیست که «کدام technology مدرن‌تر است؟»؛ سؤال این است که «کوچک‌ترین layer اضافی که problem اثبات‌شده را حل می‌کند و ownership، consistency، security و failure behavior را auditable نگه می‌دارد کدام است؟»

Guided Practice و Independent Practice

Lab آفلاین lab://AWR-003/AWR-003-LAB1 را اجرا کنید. همه fixtureها synthetic و read-only هستند و به cluster، cloud account، credential، customer data یا production endpoint نیاز ندارند. starter evidence fieldها، state vocabulary و visible ruleها را می‌دهد اما final decision را prefill نمی‌کند.

Guided pass:

1. baseline fixture را انتخاب کنید.
2. دقیقاً دو record SEARCH_ENGINE و GRAPHQL بسازید.
3. فقط exact shipped evidence همان fixture را carry کنید.
4. state را قوی‌تر از evidence انتخاب نکنید.
5. rationale، review_due و stop_or_pivot_trigger را خودتان بنویسید.
6. checker را اجرا کنید و هر rule fail را به field visible برگردانید.

Independent pass: mutation بدون search trigger، index freshness خارج از tolerance، GraphQL بدون authorization، owner-missing و missing-evidence را بررسی کنید. در آخر transfer fixture را اجرا کنید: exact lookup ساده ولی clientهای متعدد با nested representation متفاوت. هر دو row را recompute کنید؛ baseline را کپی نکنید.

چه چیزی evidence package را قابل‌قبول می‌کند؟

Reviewer باید بتواند هر دو decision را از fieldهای visible بازسازی کند. برای search row: retrieval problem، query pattern، full-text/filter/relevance/vector requirement، indexing pipeline، source معتبر، lag tolerance، consistency/security boundary، simpler alternative، owner، cost/failure surface و evidence trace. برای GraphQL: client query variability، schema owner، resolver/data boundary، authorization، N+1/query-cost handling، underlying source-of-truth boundary، simpler alternative، owner و failure surface.

authority_refs باید FACT را از DESIGN جدا کند. OPENSEARCH و ELASTIC capability boundary search engine را پشتیبانی می‌کنند؛ GRAPHQL typed API query/runtime boundary را؛ claim AWR-003-K4 authority تصمیم MAKNOW را می‌دهد. [OPENSEARCH] [ELASTIC] [GRAPHQL]

Checker exact fixture binding و visible consistency ruleها را validate می‌کند و expected-verdict oracle مخفی ندارد. AI می‌تواند supplied evidence را organize کند و comparison deterministic را انجام دهد، اما measured trigger، owner، production approval، migration success یا operational evidence را invent نمی‌کند.

Assessment و Transfer

AWR-003-F1: owned search/API boundary و یک non-goal مجاور را بازیابی کنید.

AWR-003-F2: mutation حذف typo-tolerance و faceting را درحالی‌که dedicated search engine هنوز USE است diagnose کنید؛ invalid field/state و minimal repair را بنویسید.

AWR-003-F3: changed-context decision را recompute کنید و baseline را کپی نکنید.

AWR-003-S1: owned boundary و یک non-goal را توضیح دهید.

AWR-003-S2: از baseline synthetic fixture، Search-and-API Layer Fit Decision Matrix v1 کامل را بسازید.

AWR-003-S3: mutation حذف search trigger را با consequence و minimal repair diagnose کنید.

AWR-003-S4: محصول دوم exact lookup ساده دارد اما clientهای متعدد nested representationهای متفاوت و over/under-fetch تکراری می‌خواهند. matrix را recompute کنید و نشان دهید چرا GraphQL ممکن است به PILOT برود ولی dedicated search engine NOT_NOW بماند.

Transfer فقط وقتی پاس است که هر row به‌خاطر evidence خودش تغییر کند. «محصول دوم advancedتر است» دلیل قابل قبول نیست.

منابع و Freshness Boundary

OPENSEARCH — introduction رسمی OpenSearch؛ فقط FACT محدود مربوط به distributed search/analytics engine و search/analytics workload را پشتیبانی می‌کند. [OPENSEARCH]

ELASTIC — توضیح فعلی Elastic درباره Elasticsearch search/analytics و full-text/filter/vector retrieval capability. [ELASTIC]

GRAPHQL — overview رسمی GraphQL Foundation؛ FACT محدود مربوط به typed API query language و server-side runtime مستقل از storage engine مشخص را پشتیبانی می‌کند. [GRAPHQL]

این source identityها و claim boundaryها در 2026-09-03 ثبت شده‌اند و review_due=2026-12-02 دارند. در این authoring stage live refresh انجام نمی‌شود، چون policy locked می‌گوید در review date یا زودتر فقط در صورت تغییر مادی semantics منبع recheck شود. external documentation capability FACT است؛ trigger threshold، state vocabulary و adoption gate authority از MAKNOW DESIGN می‌آید. claim scope فراتر از Bible expand نشده است.