> ## Documentation Index > Fetch the complete documentation index at: https://docs.pubrio.com/llms.txt > Use this file to discover all available pages before exploring further. # نظرة عامة على الفلاتر > كيف تعمل فلاتر بحث Pubrio — محرك الفلاتر الموحّد، دلالات AND/OR، ومتى تستخدم كلًا منهما. تشترك نقاط نهاية البحث في Pubrio (`/companies/search`، `/people/search`، `/companies/advertisements/search`) في محرك فلاتر واحد. تُنشئ نص الطلب مرة واحدة وتنطبق القواعد نفسها عبر نقاط النهاية — بما في ذلك طريقة دمج الفلاتر متعددة القيم، وكيفية مطابقة المواقع، وكيفية تجاوز المعامل الافتراضي عبر `filter_conditions`. ## لماذا محرك فلاتر موحّد؟ فلاتر مستوى الشركة مثل `technologies` و`verticals` و`founded_dates` تعمل بنفس الطريقة على `/companies/search` و`/people/search` وداخل `company_filters` في Monitor — تتعلمها مرة واحدة. القيمة الافتراضية هي OR (مطابقة أي قيمة). ارفع فلاترًا فردية إلى AND (مطابقة الكل) بإضافة عبارة واحدة إلى `filter_conditions` — دون المساس ببقية نص الطلب. تُترجم فلاتر المصفوفة إلى معاملات Postgres أصلية — `&&` (تداخل) لـ OR، و`@>` (احتواء) لـ AND. ملائمة للفهرسة، دون تصفية إضافية من جهة التطبيق. تقبل كتلة `company_filters` في [Monitors](/ar/developer-guides/introduction) الشكل نفسه، لذا فإن حمولة بحث تعمل هي أيضًا حمولة Monitor صالحة. *** ## تشريح طلب بحث يُبنى كل طلب بحث من ثلاث طبقات في نفس نص JSON: | الطبقة | مكانها | أمثلة | | --------------- | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------ | | فلاتر الأشخاص | مفاتيح المستوى الأعلى | `people_titles`، `management_levels`، `departments`، `people_locations` | | فلاتر الشركة | متداخلة تحت `company_filters: {...}` (موصى به) — تُقبل أيضًا في المستوى الأعلى | `technologies`، `verticals`، `founded_dates`، `employees`، `company_locations` | | تجاوزات المعامل | مصفوفة `filter_conditions` (داخل `company_filters` عند تجاوز مفاتيح الشركة) | `[{ "key": "technologies", "operator": "and" }]` | طلب `/people/search` بسيط يستخدم الطبقات الثلاث جميعًا: ```bash cURL theme={null} curl -X POST https://api.pubrio.com/people/search \ -H "Content-Type: application/json" \ -H "pubrio-api-key: YOUR_API_KEY" \ -d '{ "people_titles": ["VP of Engineering", "CTO"], "company_filters": { "technologies": ["Kubernetes", "Docker"], "is_enable_similarity_search": true, "company_locations": ["US"] }, "per_page": 25, "page": 1 }' ``` ```python Python theme={null} import requests response = requests.post( "https://api.pubrio.com/people/search", headers={ "Content-Type": "application/json", "pubrio-api-key": "YOUR_API_KEY", }, json={ "people_titles": ["VP of Engineering", "CTO"], "company_filters": { "technologies": ["Kubernetes", "Docker"], "is_enable_similarity_search": True, "company_locations": ["US"], }, "per_page": 25, "page": 1, }, ) print(response.json()) ``` ```javascript Node.js theme={null} const response = await fetch("https://api.pubrio.com/people/search", { method: "POST", headers: { "Content-Type": "application/json", "pubrio-api-key": "YOUR_API_KEY", }, body: JSON.stringify({ people_titles: ["VP of Engineering", "CTO"], company_filters: { technologies: ["Kubernetes", "Docker"], is_enable_similarity_search: true, company_locations: ["US"], }, per_page: 25, page: 1, }), }); console.log(await response.json()); ``` *** ## `company_filters`: إبقاء مفاتيح الشركة مجمّعة كائن الغلاف `company_filters: {...}` هو الطريقة الموصى بها لإرسال فلاتر مستوى الشركة — فهو يفصل بصريًا بين المفاتيح التي تصفّي *الشخص* والمفاتيح التي تصفّي *الشركة*، ويطابق الشكل الذي تستخدمه [Monitors](/ar/developer-guides/introduction) بالفعل، بحيث تنتقل الحمولات بسلاسة بين إعدادات البحث وMonitor. كلا الأسلوبين يعمل؛ يُسطِّح المحرك الشكل المُغلَّف إلى المستوى الأعلى قبل المعالجة، و**تفوز مفاتيح المستوى الأعلى عند التعارض**: ```json مُغلَّف (موصى به) theme={null} { "people_titles": ["VP of Engineering"], "company_filters": { "technologies": [37, 152], "founded_dates": [2015, 2023], "company_locations": ["US"] } } ``` ```json مُسطَّح (يعمل أيضًا) theme={null} { "people_titles": ["VP of Engineering"], "technologies": [37, 152], "founded_dates": [2015, 2023], "company_locations": ["US"] } ``` عند إضافة تجاوز `filter_conditions` لمفتاح على مستوى الشركة، ضعه **داخل** `company_filters` كي ينتقل مع المفاتيح التي يتجاوزها. ### نفس الشكل في نسختي `/search/similar` تقبل `POST /companies/search/similar` و`POST /people/search/similar` **نفس نص الفلاتر** الذي تقبله النسختان غير المشابهتان (بما في ذلك غلاف `company_filters` و`filter_conditions`). تضيف كل نقطة نهاية خطوة تشابه فوق ذلك: | | ما تحتاجه إضافيًا | ما تحصل عليه إضافيًا | | --------------------------- | ----------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | `/companies/search/similar` | شركة مرجعية — `domain_search_id`، `domain`، `linkedin_url`، أو `domains` | تحصل كل نتيجة على `similarity_score` (عدد عشري، 0-1) وتُرتَّب الصفوف تنازليًا حسب التشابه | | `/people/search/similar` | شخص/مسمى وظيفي مرجعي — واحد من `people_titles`، `people_search_id`، `linkedin_url`، `linkedin_urls`، أو `peoples` | نفس الشيء — `similarity_score` لكل صف، مرتّبة حسب التشابه | غلاف الاستجابة مطابق للنقطة القياسية `search` فيما عدا ذلك. تُضيّق الفلاتر مجموعة المرشحين *قبل* تطبيق ترتيب التشابه — لذا فإن دمج `company_locations: ["US"]` مع `/people/search/similar` يُرجع أقرب الأشخاص في الولايات المتحدة إلى مسمياتك الوظيفية المرجعية، وهو نمط "ابحث عن المزيد من الأشخاص المشابهين لـ X ضمن هذه القيود". خلافًا لنقاط نهاية `/search` القياسية، لا تُرجع `/search/similar` قيمة `pagination.total_entries` دقيقة — القيمة محدودة سقفًا لأن البحث بالتشابه يرتّب النتائج حسب الصلة ويُظهر فقط أفضل التطابقات. استخدم البحث بالتشابه لإيجاد *أفضل* التطابقات، وليس لحصر كل واحدة منها. *** ## AND مقابل OR — القرار الوحيد الذي تتخذه لكل فلتر تقبل الفلاتر متعددة القيم (`technologies`، `verticals`، `keywords`، `categories`، ...) مصفوفة. يحدد المعامل معنى "المطابقة": **مطابقة أي قيمة.** يُرجع الصفوف التي تتداخل مصفوفتها مع المدخلات. ```json theme={null} { "technologies": ["Python", "PostgreSQL", "Kubernetes"], "is_enable_similarity_search": true } ``` تُدرَج الشركة إذا كانت حزمة تقنياتها تحتوي على **قيمة واحدة على الأقل** من `Python` أو `PostgreSQL` أو `Kubernetes`. تُترجم إلى `column && ARRAY[...]` في Postgres. استخدمها عندما: تريد نطاقًا واسعًا — "مهتم بـ *أي* من هذه"، "موجود في *أي* من هذه الدول". **مطابقة كل قيمة.** يُرجع الصفوف التي تحتوي مصفوفتها على كل قيمة من المدخلات. ```json theme={null} { "technologies": [37, 152, 408], "filter_conditions": [ { "key": "technologies", "operator": "and" } ] } ``` تأتي معرّفات الوسم الرقمية من `GET /technologies?search_term=python` (وما شابهها). **لا تجمع بين `is_enable_similarity_search: true` وAND على نفس المفتاح** — يوسّع التشابه كل مصطلح نصي حر إلى العديد من معرّفات الوسم، ثم يتطلب `@>` أن يحتوي الصف عليها جميعًا، وهو ما يُرجع صفرًا في الغالب. تُدرَج الشركة فقط إذا كانت حزمة تقنياتها تحتوي على **كل** قيم `[37, 152, 408]`. تُترجم إلى `column @> ARRAY[...]` في Postgres. استخدمها عندما: تريد الدقة — "تستخدم *كل* هذه التقنيات معًا"، "موسومة بـ *كل* هذه القطاعات". الفلاتر غير المدرجة في `filter_conditions` تستخدم المعامل الافتراضي (OR داخل المصفوفة، AND بين مفاتيح الفلاتر المختلفة). تُعلن فقط التجاوزات — لا تحتاج أبدًا إلى كتابة القيم الافتراضية. *** ## ما يمكنك تجاوزه تقبل كل نقطة نهاية تجاوزات لمجموعة مختلفة من المفاتيح. تأتي المفاتيح من تعداد OpenAPI في كل مخطط `*_filter_conditions`: مفاتيح `company_filter_conditions`: `keywords`، `verticals`، `vertical_categories`، `vertical_sub_categories`، `technologies`، `categories`، `advertisement_target_locations`، `advertisement_exclude_target_locations`، `advertisement_search_terms`، `places`، `exclude_places`، `job_exclude_locations`. مفاتيح `people_filter_conditions` (تُفوَّض إلى محرك الشركة): `keywords`، `verticals`، `vertical_categories`، `vertical_sub_categories`، `technologies`، `categories`، `places`، `exclude_places`، إضافةً إلى `social_media`. مفاتيح `ads_filter_conditions`: `target_locations`، `exclude_target_locations`. مجموعة أصغر لأن الإعلانات تُصفَّى فقط حسب دولة الظهور. عند استخدام `/people/search`، يستخدم `filter_conditions[].key` لمواقع مستوى الشركة **الاسم المجرّد** من محرك الشركة — `places`، `exclude_places` — وليس اسم واجهة API الخاصة بالأشخاص ذا البادئة (`company_places`). انظر [فلاتر الأشخاص + الشركة](/ar/developer-guides/filters/people-with-company-filters#key-remap-reference). *** ## نصائح للأداء المواقع، ونطاقات عدد الموظفين، و`founded_dates` جميعها مفهرَسة وتُقلِّص مجموعة المرشحين أسرع من الفلاتر النصية الحرة أو فلاتر القطاعات. اجمعها مع فلتر أو فلترين دقيقين قبل اللجوء إلى البحث بالتشابه. يتطلب `column @> ARRAY[a, b, c, …]` أن تكون كل قيمة موجودة. تنمو الأصالة العددية بسرعة — فتطبيق AND على 10 تقنيات في فئة متوسط وسومها 3 تقنيات يُرجع صفوفًا قريبة من الصفر ويفرض فحصًا كاملًا للجدول. فضِّل 2-4 قيم لكل فلتر AND؛ وانتقل إلى OR للاستعلامات الاستكشافية. إذا تعذّر عليك توفير معرّفات slug (للقطاعات، والتقنيات، والفئات) ولديك فقط سلاسل نصية حرة، اضبط `is_enable_similarity_search: true` و`similarity_score: 0.7`. يحلّ المحرك التطابقات قبل تطبيق الفلتر — أرخص بكثير من فحص النص. `employees: [[201, 500], [501, 1000]]` (مصفوفة من الفئات) و`revenues: [1000000, 5000000]` (نطاق أدنى/أعلى واحد) أسرع وأكثر توافقًا مع الأسلوب من قوائم المعرّفات الطويلة. *** ## فلاتر النشاط الإعلاني يمكن لـ `/companies/search` التصفية حسب البصمة الإعلانية للشركة — عدد الإعلانات التي تُشغّلها، وما إذا كان أي منها نشطًا حاليًا، والمنصات والصيغ التي تستخدمها، وترتيبها مقارنةً بالمعلنين الآخرين في دولة معينة. تقبل `POST /companies/advertisements/search` كل هذه الفلاتر أيضًا (`advertisement_active_ads`، `advertisement_running_ads`، `advertisement_total_ads`، `advertisement_platform_count`، `advertisement_format_count`، `advertisement_impressions_estimate`، `advertisement_formats`، `advertisement_country_activity`) — يُدرَج الإعلان إذا استوفت الشركة المالكة له الشرط. | الفلتر | الشكل | النطاق | | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | | `advertisement_active_ads`، `advertisement_running_ads`، `advertisement_total_ads` | نطاق `[min, max]` | كل الدول | | `advertisement_platform_count`، `advertisement_format_count` | نطاق `[min, max]` | كل الدول | | `advertisement_impressions_estimate` | نطاق `[min, max]` | كل الدول | | `advertisement_formats` | مصفوفة — `image`، `video`، `text`، `carousel`، `dynamic_product`، `document`، `message`، `event`، `article`، `spotlight`، `follow`، `job`، `engagement` | كل الدول | | `advertisement_platforms` | مصفوفة — `linkedin`، `facebook`، `google`، `tiktok`، `apple` (تُقبل `meta` كاسم بديل لـ `facebook`) | كل الدول | | `advertisement_publisher_platforms`، `advertisement_exclude_publisher_platforms` | مصفوفة — `facebook`، `instagram`، `messenger`، `threads`، `audience_network` | كل الدول | | `advertisement_status` | مصفوفة — `currently_running` (لديها إعلانات مسجَّلة)، `active_last_30_min` (تغيّرت سجلات الإعلان خلال آخر 30 دقيقة) | كل الدول | | `advertisement_country_activity` | كائن، انظر أدناه | دولة واحدة | استخدم `null` لحد مفتوح — `[1, null]` تعني "على الأقل 1"، و`[null, 500]` تعني "500 أو أقل". ```json theme={null} { "advertisement_active_ads": [1, null], "advertisement_formats": ["video"] } ``` ### الترتيب داخل دولة يحدّد `advertisement_country_activity` نطاق الترتيب والمئوية ودرجة الحجم لدولة واحدة في كل مرة — لأن ترتيب إعلانات شركة في الولايات المتحدة لا يقول شيئًا عن ترتيبها في ألمانيا، لذا فإن `country` مطلوب: ```json theme={null} { "advertisement_country_activity": { "country": "US", "rank": [null, 500] } } ``` **يُحسَب `rank` تنازليًا بدءًا من أكبر منفِق، تمامًا مثل ترتيب سباق.** الرقم `1` هو أكبر معلن في تلك الدولة، ويرتفع الرقم كلما *انخفض* حجم الإنفاق الإعلاني. للعثور على **أكبر** المنفقين، صفِّ `rank` بحد أعلى **منخفض** — `[null, 500]` هي أفضل 500. أما تصفية `[500, null]` فتجد كل من هم **خارج** أفضل 499، وهو عكس معنى "منفق كبير". إذا أردت مقياسًا مستقلًا عن الحجم يعمل بالطريقة نفسها بغض النظر عن عدد المعلنين في تلك الدولة، استخدم `percentile` بدلًا من ذلك — فهو يعمل بالاتجاه المعاكس، بحيث يعني الرقم **الأعلى** منفقًا **أكبر**: `[90, null]` هي أفضل 10%. يمكنك دمج `advertisement_country_activity` مع الفلاتر السارية على كل الدول أعلاه في نفس الطلب — على سبيل المثال، "مرتبة ضمن أفضل 500 في الولايات المتحدة، ولديها 100 إعلان نشط على الأقل على مستوى الشركة": ```json theme={null} { "advertisement_country_activity": { "country": "US", "rank": [null, 500] }, "advertisement_active_ads": [100, null] } ``` *** ## الخطوات التالية صفحة مرجعية — كل مفتاح مدعوم، وكل قيمة افتراضية، ووصفات AND/OR جاهزة للنسخ. استخدم أي فلتر شركة داخل `/people/search`. الميزة الجديدة الأبرز للمحرك الموحّد. مخطط الطلب/الاستجابة الكامل لـ `/companies/search`. مخطط الطلب/الاستجابة الكامل لـ `/people/search`. تبحث عن شرح التصفية من جانب لوحة التحكم؟ انظر [تصفية جهات الاتصال وتصديرها](/ar/knowledge-base/concepts/search-filters) في قاعدة المعرفة.