کوئری GraphQL در Weaviate چیست و از کجا اجرا میشود؟
کوئری GraphQL در Weaviate یک رشتهٔ متنی به زبان GraphQL است که با یک درخواست HTTP به endpoint «POST /v1/graphql» فرستاده میشود و Weaviate در پاسخ، دقیقاً همان فیلدهایی را که خواستهاید بهصورت JSON برمیگرداند. برخلاف REST معمولی که برای هر کار endpoint جداگانه دارد، اینجا یک دروازه وجود دارد و داخل بدنهٔ درخواست میگویید چه میخواهید: کدام کالکشن، با کدام عملگر جستجو و با کدام فیلدها.
| کلیدواژه | نقش | ورودی کلیدی | خروجی |
|---|---|---|---|
| Get | بازیابی خود اشیاء | عملگر جستجو (nearText، bm25، hybrid، ...) + فیلتر where + limit/offset/after | آرایهای از اشیاء با فیلدهای دلخواه و _additional |
| Aggregate | تجمیع آماری روی کالکشن | groupBy، فیلتر where، حتی nearText با objectLimit | count، mean، median، maximum، sum، topOccurrences |
| Explore | جستجوی قدیمی مبتنی بر مفاهیم | concepts و moveTo/moveAwayFrom | نتایج بینکالکشن؛ امروزه توصیه نمیشود |
برای نوشتن اولین کوئری به چه چیزهایی نیاز دارم؟
خبر خوب این است که برای کوئرینویسی GraphQL هیچ SDK خاصی لازم نیست؛ هر کلاینتی که بتواند HTTP POST با بدنهٔ JSON بفرستد کافی است. آنچه واقعاً به آن وابستهاید، یک نمونهٔ در حال اجرای Weaviate و یک کالکشن حاوی داده است — بدون داده، کوئریها فنی درستاند ولی خروجی خالی برمیگردانند و اشکالزدایی برای مبتدی گیجکننده میشود.
- یک نمونهٔ در حال اجرای Weaviate محلی (مثلاً با Docker) یا یک سندباکس Weaviate Cloud — پیشفرض مستندات رسمی آدرس http://localhost و پورت 8080 است.
- یک کالکشن نمونه (در مثالهای این مقاله: Article) با چند شیء و ویژگیهای متنی مثل title و content و wordCount.
- ابزار ارسال درخواست: curl، یا Python با کتابخانهٔ requests، یا Node.js 18+ با fetch داخلی.
- (اختیاری) ماژول vectorizer/generative فعال اگر میخواهید server-side embedding یا جستجوی مولد تست کنید.
- (اختیاری، فقط برای بخش RAG) کلید API از apx24.ir/account/api-keys برای مرحلهٔ تولید پاسخ با مدل زبانی.
چطور اولین کوئری Get را با curl، Python و JavaScript اجرا کنم؟
کوئری Get یعنی «اشیاء این کالکشن را بیاور». سادهترین شکل آن بدون هیچ عملگر جستجویی است و فقط چند شیء اول را با فیلدهای دلخواه برمیگرداند؛ بهترین نقطه برای تست سلامتِ اتصال. سه نمونهٔ زیر دقیقاً یک کار را در سه زبان انجام میدهند تا ببینید رابط GraphQL واقعاً وابسته به زبان نیست.
- 1
ساخت رشتهٔ GraphQL
کلیدواژهٔ Get را با نام کالکشن و فیلدهای دلخواه بنویسید؛ این رشته همان «سفارش» شماست.
- 2
ارسال با POST و هدر JSON
رشته را داخل کلید query یک شیء JSON قرار دهید و به /v1/graphql بفرستید.
- 3
تفسیر پاسخ و بررسی errors
پاسخ JSON دو مسیر دارد: data.Get.Article برای نتایج و errors برای خطا. اول errors را چک کنید بعد به data امیدوار شوید.
جستجوی برداری با nearText چطور کار میکند؟
قلب جستجوی معنایی در Weaviate عملگر nearText است: شما یک یا چند «مفهوم» متنی میدهید، Weaviate آن مفهوم را به بردار تبدیل میکند (با ماژول vectorizer کالکشن) و نزدیکترین اشیاء را به ترتیب شباهت برمیگرداند. اگر بردار آماده دارید، بهجای nearText از nearVector با پارامتر vector استفاده میشود؛ این دقیقاً همان نقطهای است که وکتورهای ساختهشده با سرویس Embeddings سازگار با OpenAI (مثل APX24) وارد بازی میشوند.
چطور نتایج را با فیلتر where دقیق کنیم؟
جستجوی معنایی «مشابه» پیدا میکند، اما گاهی میخواهید فقط بین زیرمجموعهای خاص بگردد: مقالات منتشرشده، محصولات با قیمت بالاتر از سقفی مشخص، یا سندهایی که کلمهٔ خاصی در عنوان دارند. فیلتر where همینجا وارد میشود و با هر عملگر جستجویی ترکیب میشود — مثلاً «نزدیکترینها به این مفهوم، اما فقط از سال ۲۰۲۴ به بعد».
| عملگر | کاربرد | نمونهٔ مقدار |
|---|---|---|
| Equal / NotEqual | تساوی و نابرابری | valueBoolean: true |
| GreaterThan / GreaterThanEqual | بزرگتر و بزرگتر یا مساوی (و معادلهای LessThan) | valueInt: 1000 |
| Like | تطبیق الگو با wildcard ستاره | valueText: "*هوش*" |
| ContainsAny / ContainsAll | داشتن حداقل یکی یا همهٔ اعضای آرایه | valueTextArray: ["a", "b"] |
| ContainsNone | نداشتن هیچیک از اعضای آرایه | valueStringArray: ["spam"] |
| WithinGeoRange | نزدیکی مکانی به یک نقطهٔ جغرافیایی | valueText با geoCoordinates |
| And / Or / Not | ترکیب شرطها با operands | operands: [...] |
bm25 و hybrid چه زمانی بهتر از جستجوی برداری خالصاند؟
nearText برای «معنا» عالی است، اما وقتی کاربر دنبال یک واژهٔ دقیق است — نام محصول، کد خطا، یا اصطلاح تخصصی — جستجوی کلماتکلیدی bm25 گاهی دقیقتر جواب میدهد. عملگر hybrid دو دنیا را ترکیب میکند: یک جستجوی BM25F و یک جستجوی برداری، با وزن alpha و روش ادغام fusionType. برای جستجوی واقعی محصول، hybrid معمولاً انتخاب پیشفرض هوشمندانه است.
| مورد | نوع تطبیق | ورودی اصلی | سنجهٔ امتیاز در _additional | سناریوی ایدهآل |
|---|---|---|---|---|
| bm25 | کلماتکلیدی (BM25F) | query + properties | score و explainScore | جستجوی دقیق واژه، کد خطا، نام محصول |
| nearText / nearVector | معنایی (برداری) | concepts یا vector | certainty (cosine) یا distance | پیدا کردن مفاهیم مشابه حتی بدون اشتراک لفظی |
| hybrid | ترکیبی (کلماتکلیدی + برداری) | query (+ alpha، properties، vector اختیاری) | score و explainScore | جستجوی اصلی محصول با پوشش هر دو دنیا |
Aggregate چطور آمار کالکشن را محاسبه میکند؟
اگر Get «اشیاء» را برمیگرداند، Aggregate «آمار» را برمیگرداند: چند شیء داریم، میانگین و بیشینهٔ ویژگیهای عددی چیست، و پرتکرارترین مقادیر یک ویژگی متنی کداماند. برای داشبوردهای محتوا، مانیتورینگ کیفیت داده و ساخت فیلترهای رابط کاربری، Aggregate جایگزین «کشیدن همهٔ داده و شمارش سمت کلاینت» است — کار سنگینی که با رشد کالکشن عملاً غیرممکن میشود.
- برای هر ویژگی عددی/صحیح: count، type، minimum، maximum، mean، median، mode و sum.
- برای ویژگیهای متنی: count و topOccurrences (با آرگومان limit) که پرتکرارترین مقادیر و تعداد تکرارشان را میدهد.
- meta { count } تعداد کل اشیاء (یا اعضای گروه) را میدهد.
- برای ویژگیهای مرجع (reference): pointingTo و type نشان میدهد به کدام کالکشن و چقدر اشاره میشود.
- داخل Aggregate میتوان فیلتر where گذاشت و حتی با nearText و objectLimit، آمار را فقط روی نتایج یک جستجوی برداری حساب کرد.
چطور خروجی کوئری را به RAG و APX24 وصل کنم؟
تا اینجا مرحلهٔ «بازیابی» را ساختید؛ RAG یک گام جلوتر میرود: خروجی کوئری را به مدل زبانی بدهید تا پاسخ طبیعی بسازد. دو مسیر دارید. مسیر اول جستجوی مولد درون Weaviate است — فیلد generate در _additional یک پرامپت را روی نتایج اعمال میکند (نیازمند ماژول تولید فعال در نمونهٔ شما). مسیر دوم که کنترل کامل و مقیاسپذیری بهتری به شما میدهد، فراخوانی مستقیم یک API سازگار با OpenAI مثل APX24 با همان نتایج است؛ در ادامه هر دو را میبینید.
خطاهای رایج کوئری GraphQL را چطور دیباگ کنم؟
اولین تفاوت ذهنی که باید با REST جایگزین کنید: در GraphQL خطا معمولاً «کد HTTP جداگانه» ندارد و در بدنهٔ پاسخ با کلید errors برمیگردد — گاهی حتی با status 200. پس هر کدی که فقط raise_for_status صدا میزند و بعد سراغ data میرود، دیر یا زود روی None کرش میکند. الگوی درست: اول errors، بعد data.
GraphQL منسوخ شده؛ چطور به REST Search API و کلاینتهای v4 مهاجرت کنم؟
این بخش همان چیزی است که کدهای شما را «فردا-پسند» میکند. طبق مستندات رسمی، رابط GraphQL منسوخ شده و کلاینتهای v4 کوئری را از طریق gRPC میفرستند؛ برای کار مستقیم با HTTP هم REST Search API معادلهای تمیزتر هر عملگر را داده است. مهاجرت سخت نیست — نگاشت تقریباً یکبهیک است — اما باید از الان در برنامهٔ نسخهگذاری پروژه باشد، مخصوصاً اگر روی Weaviate Cloud هستید.
| کوئری GraphQL | معادل REST Search API |
|---|---|
| Get { ... nearText: {...} } | POST /v1/search/{collection}/near-text |
| Get { ... nearVector: {...} } | POST /v1/search/{collection}/near-vector |
| Get { ... nearObject: {...} } | POST /v1/search/{collection}/near-object |
| Get { ... bm25: {...} } | POST /v1/search/{collection}/bm25 |
| Get { ... hybrid: {...} } | POST /v1/search/{collection}/hybrid |
| Aggregate { ... } | قابلیتهای تجمیعی از مسیرهای REST/کلاینتهای v4 — صفحهٔ REST Search را برای وضعیت فعلی ببینید |
- 1
فهرستبرداری از کوئریهای GraphQL
همهٔ کوئریهای Get و Aggregate موجود در کد را پیدا کنید و کنار هرکدام عملگر جستجو و فیلدهای برگشتی را بنویسید.
- 2
معادلسازی با /v1/search/... یا کلاینت v4
هر عملگر را با جدول نگاشت بالا به endpoint REST یا API کلاینت v4 تبدیل کنید؛ اگر کلاینت رسمی استفاده میکنید، مهاجرت به v4 یعنی رفتن روی gRPC.
- 3
آزمون موازی (shadow run)
هر دو مسیر را کنار هم اجرا کنید و خروجی (عناوین، فاصلهها، مرتبسازی) را مقایسه کنید تا آستانههای certainty/alpha قبلی معنا حفظ کنند.
- 4
بریدن مسیر قدیمی و مانیتورینگ
کوئریهای GraphQL را حذف/غیرفعال کنید و متریک خطای مسیر جدید را مانیتور کنید — قبل از ۲۰۲۷-۰۵-۰۱ نه بعد از آن.





