نظرة عامة على الفلاتر

تشترك نقاط نهاية البحث في Pubrio (/companies/search، /people/search، /companies/advertisements/search) في محرك فلاتر واحد. تُنشئ نص الطلب مرة واحدة وتنطبق القواعد نفسها عبر نقاط النهاية — بما في ذلك طريقة دمج الفلاتر متعددة القيم، وكيفية مطابقة المواقع، وكيفية تجاوز المعامل الافتراضي عبر filter_conditions.

لماذا محرك فلاتر موحّد؟

مخطط واحد، ثلاث نقاط نهاية

فلاتر مستوى الشركة مثل technologies وverticals وfounded_dates تعمل بنفس الطريقة على /companies/search و/people/search وداخل company_filters في Monitor — تتعلمها مرة واحدة.

AND/OR لكل فلتر

القيمة الافتراضية هي OR (مطابقة أي قيمة). ارفع فلاترًا فردية إلى AND (مطابقة الكل) بإضافة عبارة واحدة إلى filter_conditions — دون المساس ببقية نص الطلب.

معاملات أصلية في Postgres

تُترجم فلاتر المصفوفة إلى معاملات Postgres أصلية — && (تداخل) لـ OR، و@> (احتواء) لـ AND. ملائمة للفهرسة، دون تصفية إضافية من جهة التطبيق.

نفس الفلاتر في Monitors

تقبل كتلة company_filters في Monitors الشكل نفسه، لذا فإن حمولة بحث تعمل هي أيضًا حمولة 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 بسيط يستخدم الطبقات الثلاث جميعًا:

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
  }'

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())

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 بالفعل، بحيث تنتقل الحمولات بسلاسة بين إعدادات البحث وMonitor. كلا الأسلوبين يعمل؛ يُسطِّح المحرك الشكل المُغلَّف إلى المستوى الأعلى قبل المعالجة، وتفوز مفاتيح المستوى الأعلى عند التعارض:

{
  "people_titles": ["VP of Engineering"],
  "company_filters": {
    "technologies": [37, 152],
    "founded_dates": [2015, 2023],
    "company_locations": ["US"]
  }
}

{
  "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، …) مصفوفة. يحدد المعامل معنى “المطابقة”:

OR (الافتراضي)
AND

مطابقة أي قيمة. يُرجع الصفوف التي تتداخل مصفوفتها مع المدخلات.

{
  "technologies": ["Python", "PostgreSQL", "Kubernetes"],
  "is_enable_similarity_search": true
}

تُدرَج الشركة إذا كانت حزمة تقنياتها تحتوي على قيمة واحدة على الأقل من Python أو PostgreSQL أو Kubernetes. تُترجم إلى column && ARRAY[...] في Postgres.استخدمها عندما: تريد نطاقًا واسعًا — “مهتم بـ أي من هذه”، “موجود في أي من هذه الدول”.

مطابقة كل قيمة. يُرجع الصفوف التي تحتوي مصفوفتها على كل قيمة من المدخلات.

{
  "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). انظر فلاتر الأشخاص + الشركة.

نصائح للأداء

صفِّ مبكرًا على الأعمدة المفهرَسة

المواقع، ونطاقات عدد الموظفين، وfounded_dates جميعها مفهرَسة وتُقلِّص مجموعة المرشحين أسرع من الفلاتر النصية الحرة أو فلاتر القطاعات. اجمعها مع فلتر أو فلترين دقيقين قبل اللجوء إلى البحث بالتشابه.

لا تُفرِط في استخدام AND على مصفوفات كبيرة

يتطلب column @> ARRAY[a, b, c, …] أن تكون كل قيمة موجودة. تنمو الأصالة العددية بسرعة — فتطبيق AND على 10 تقنيات في فئة متوسط وسومها 3 تقنيات يُرجع صفوفًا قريبة من الصفر ويفرض فحصًا كاملًا للجدول. فضِّل 2-4 قيم لكل فلتر AND؛ وانتقل إلى OR للاستعلامات الاستكشافية.

استخدم is_enable_similarity_search للمدخلات النصية الحرة

إذا تعذّر عليك توفير معرّفات 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 أو أقل”.

{
  "advertisement_active_ads": [1, null],
  "advertisement_formats": ["video"]
}

الترتيب داخل دولة

يحدّد advertisement_country_activity نطاق الترتيب والمئوية ودرجة الحجم لدولة واحدة في كل مرة — لأن ترتيب إعلانات شركة في الولايات المتحدة لا يقول شيئًا عن ترتيبها في ألمانيا، لذا فإن country مطلوب:

{
  "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 إعلان نشط على الأقل على مستوى الشركة”:

{
  "advertisement_country_activity": { "country": "US", "rank": [null, 500] },
  "advertisement_active_ads": [100, null]
}

الخطوات التالية

filter_conditions

صفحة مرجعية — كل مفتاح مدعوم، وكل قيمة افتراضية، ووصفات AND/OR جاهزة للنسخ.

فلاتر الأشخاص + الشركة

استخدم أي فلتر شركة داخل /people/search. الميزة الجديدة الأبرز للمحرك الموحّد.

مرجع بحث الشركات

مخطط الطلب/الاستجابة الكامل لـ /companies/search.

مرجع بحث الأشخاص

مخطط الطلب/الاستجابة الكامل لـ /people/search.

تبحث عن شرح التصفية من جانب لوحة التحكم؟ انظر تصفية جهات الاتصال وتصديرها في قاعدة المعرفة.

Monitor

البحث

المرشحات

الأشخاص

التوسع

نظرة عامة على الفلاتر

لماذا محرك فلاتر موحّد؟

مخطط واحد، ثلاث نقاط نهاية

AND/OR لكل فلتر

معاملات أصلية في Postgres

نفس الفلاتر في Monitors

تشريح طلب بحث

`company_filters`: إبقاء مفاتيح الشركة مجمّعة

نفس الشكل في نسختي `/search/similar`

AND مقابل OR — القرار الوحيد الذي تتخذه لكل فلتر

ما يمكنك تجاوزه

نقطة نهاية الشركة

نقطة نهاية الأشخاص

نقطة نهاية الإعلانات

نصائح للأداء

فلاتر النشاط الإعلاني

الترتيب داخل دولة

الخطوات التالية

filter_conditions

فلاتر الأشخاص + الشركة

مرجع بحث الشركات

مرجع بحث الأشخاص

​لماذا محرك فلاتر موحّد؟

مخطط واحد، ثلاث نقاط نهاية

AND/OR لكل فلتر

معاملات أصلية في Postgres

نفس الفلاتر في Monitors

​تشريح طلب بحث

​company_filters: إبقاء مفاتيح الشركة مجمّعة

​نفس الشكل في نسختي /search/similar

​AND مقابل OR — القرار الوحيد الذي تتخذه لكل فلتر

​ما يمكنك تجاوزه

نقطة نهاية الشركة

نقطة نهاية الأشخاص

نقطة نهاية الإعلانات

​نصائح للأداء

​فلاتر النشاط الإعلاني

​الترتيب داخل دولة

​الخطوات التالية

filter_conditions

فلاتر الأشخاص + الشركة

مرجع بحث الشركات

مرجع بحث الأشخاص

لماذا محرك فلاتر موحّد؟

تشريح طلب بحث

`company_filters`: إبقاء مفاتيح الشركة مجمّعة

نفس الشكل في نسختي `/search/similar`

AND مقابل OR — القرار الوحيد الذي تتخذه لكل فلتر

ما يمكنك تجاوزه

نصائح للأداء

فلاتر النشاط الإعلاني

الترتيب داخل دولة

الخطوات التالية