معاملات AND / OR

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

البنية

{
  "filter_conditions": [
    { "key": "technologies", "operator": "and" },
    { "key": "verticals",    "operator": "or"  }
  ]
}

type FilterCondition = {
  /** اسم الفلتر المراد تجاوزه. انظر "المفاتيح المدعومة" أدناه. */
  key: string;
  /** غير حساس لحالة الأحرف: "and" | "or". القيمة الافتراضية للمصفوفات هي "or". */
  operator: "and" | "or";
};

type SearchRequest = {
  // …بقية فلاترك…
  filter_conditions?: FilterCondition[];
};

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

لماذا يهم هذا الأمر

المعامل الافتراضي هو OR لأن معظم سير عمل استكشاف العملاء المحتملين يريد نطاقًا واسعًا: “أشخاص في أي من هذه الدول”، “شركات موسومة بـ أي من هذه القطاعات”. أما للاستهداف عالي الدقة — “تستخدم كل من Salesforce + HubSpot + Marketo” — فأنت بحاجة إلى AND. تكلفة الخطأ:

أردت AND وحصلت على OR: تستدعي الاستجابة نتائج أكثر من اللازم — سترى شركات تطابق وسمًا واحدًا فقط، وليس كامل المجموعة. سهل الملاحظة، ويكلّفك جودة النتائج.
أردت OR وحصلت على AND: تستدعي الاستجابة نتائج أقل من اللازم — عادةً ما تُرجع فلاتر AND متعددة القيم صفوفًا قريبة من الصفر لأن المصفوفات في الواقع نادرًا ما تحتوي كل قيمة مطلوبة. سهل الملاحظة، ويبدو وكأنه استعلام معطوب.

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

المفاتيح المدعومة

تعتمد مجموعة المفاتيح الدقيقة على نقطة النهاية التي تستدعيها:

المفتاح	`/companies/search`	`/people/search`	`/companies/advertisements/search`	الافتراضي	ماذا يعني `and`
`technologies`	نعم	نعم	—	OR	تمتلك كل تقنية في القائمة
`categories`	نعم	نعم	—	OR	موسومة بكل فئة
`verticals`	نعم	نعم	—	OR	تنتمي إلى كل قطاع
`vertical_categories`	نعم	نعم	—	OR	ضمن كل فئة قطاع
`vertical_sub_categories`	نعم	نعم	—	OR	ضمن كل فئة قطاع فرعية
`keywords`	نعم	نعم	—	OR	يحتوي الوصف على كل كلمة مفتاحية
`places`	نعم	نعم	—	OR	مدرجة في كل مكان
`exclude_places`	نعم	نعم	—	OR	مستبعدة من كل مكان
`advertisement_target_locations`	نعم	—	—	OR	الإعلان يستهدف كل دولة (نقطة نهاية الشركة)
`advertisement_exclude_target_locations`	نعم	—	—	OR	الإعلان يستبعد كل دولة
`advertisement_search_terms`	نعم	—	—	OR	نص الإعلان يحتوي على كل مصطلح
`job_exclude_locations`	نعم	—	—	OR	إعلان الوظيفة يستبعد كل موقع
`social_media`	—	نعم	—	OR	الشخص لديه كل حسابات التواصل الاجتماعي المدرجة
`target_locations`	—	—	نعم	OR	الإعلان يستهدف كل دولة (نقطة نهاية الإعلانات)
`exclude_target_locations`	—	—	نعم	OR	الإعلان يستبعد كل دولة

تعكس المفاتيح أعلاه مصفوفات enum في مواصفة OpenAPI (company_filter_conditions، people_filter_conditions، ads_filter_conditions). إرسال مفتاح غير مدعوم لنقطة نهاية معينة يُتجاهل بصمت.

وصفات جاهزة

كل التقنيات معًا (شركات)
أي من المواقع + استبعاد
حملات إعلانية متعددة المناطق
أشخاص في شركات متعددة التقنيات

الهدف: شركات تستخدم كل من Python وPostgreSQL وKubernetes — وليس واحدة فقط.

curl -X POST https://api.pubrio.com/companies/search \
  -H "Content-Type: application/json" \
  -H "pubrio-api-key: YOUR_API_KEY" \
  -d '{
    "technologies": [37, 152, 408],
    "filter_conditions": [
      { "key": "technologies", "operator": "and" }
    ],
    "per_page": 25,
    "page": 1
  }'

import requests

response = requests.post(
    "https://api.pubrio.com/companies/search",
    headers={
        "Content-Type": "application/json",
        "pubrio-api-key": "YOUR_API_KEY",
    },
    json={
        "technologies": [37, 152, 408],
        "filter_conditions": [
            { "key": "technologies", "operator": "and" }
        ],
        "per_page": 25,
        "page": 1,
    },
)
print(response.json())

const response = await fetch("https://api.pubrio.com/companies/search", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "pubrio-api-key": "YOUR_API_KEY",
  },
  body: JSON.stringify({
    technologies: [37, 152, 408],
    filter_conditions: [
      { key: "technologies", operator: "and" }
    ],
    per_page: 25,
    page: 1,
  }),
});
console.log(await response.json());

احذف عبارة filter_conditions لتوسيع البحث ليشمل أيًا من التقنيات الثلاث.

الهدف: شركات في أي من الولايات المتحدة أو كندا أو المملكة المتحدة، لكن ليس في سان فرانسيسكو أبدًا.OR هو الافتراضي بالفعل لـ locations، لذا نتركه ضمنيًا. تتعامل exclude_places مع فلتر الاستبعاد بشكل مستقل — دون الحاجة إلى تجاوز.

curl -X POST https://api.pubrio.com/companies/search \
  -H "Content-Type: application/json" \
  -H "pubrio-api-key: YOUR_API_KEY" \
  -d '{
    "locations": ["US", "CA", "GB"],
    "exclude_places": ["San Francisco"],
    "per_page": 25,
    "page": 1
  }'

import requests

response = requests.post(
    "https://api.pubrio.com/companies/search",
    headers={
        "Content-Type": "application/json",
        "pubrio-api-key": "YOUR_API_KEY",
    },
    json={
        "locations": ["US", "CA", "GB"],
        "exclude_places": ["San Francisco"],
        "per_page": 25,
        "page": 1,
    },
)
print(response.json())

const response = await fetch("https://api.pubrio.com/companies/search", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "pubrio-api-key": "YOUR_API_KEY",
  },
  body: JSON.stringify({
    locations: ["US", "CA", "GB"],
    exclude_places: ["San Francisco"],
    per_page: 25,
    page: 1,
  }),
});
console.log(await response.json());

الهدف: إعلانات تستهدف بالفعل كلًا من الاتحاد الأوروبي والولايات المتحدة (حملات متعددة المناطق) — وليس إعلانات سوق واحد. يستخدم مخطط ads_filter_conditions المخصص بمفتاح target_locations.

curl -X POST https://api.pubrio.com/companies/advertisements/search \
  -H "Content-Type: application/json" \
  -H "pubrio-api-key: YOUR_API_KEY" \
  -d '{
    "target_locations": ["US", "DE", "FR"],
    "filter_conditions": [
      { "key": "target_locations", "operator": "and" }
    ],
    "start_dates": ["2026-01-01"],
    "end_dates":   ["2026-04-22"],
    "per_page": 25,
    "page": 1
  }'

import requests

response = requests.post(
    "https://api.pubrio.com/companies/advertisements/search",
    headers={
        "Content-Type": "application/json",
        "pubrio-api-key": "YOUR_API_KEY",
    },
    json={
        "target_locations": ["US", "DE", "FR"],
        "filter_conditions": [
            { "key": "target_locations", "operator": "and" }
        ],
        "start_dates": ["2026-01-01"],
        "end_dates":   ["2026-04-22"],
        "per_page": 25,
        "page": 1,
    },
)
print(response.json())

const response = await fetch("https://api.pubrio.com/companies/advertisements/search", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "pubrio-api-key": "YOUR_API_KEY",
  },
  body: JSON.stringify({
    target_locations: ["US", "DE", "FR"],
    filter_conditions: [
      { key: "target_locations", operator: "and" }
    ],
    start_dates: ["2026-01-01"],
    end_dates:   ["2026-04-22"],
    per_page: 25,
    page: 1,
  }),
});
console.log(await response.json());

تستخدم نقطة نهاية الإعلانات مخططها الخاص ads_filter_conditions (مجموعة مفاتيح أصغر: target_locations، exclude_target_locations). المفاتيح التي يمكنك تجاوزها في /companies/search و/people/search لا تنطبق هنا.

الهدف: أشخاص يعملون في شركات لديها كلا من Salesforce وHubSpot مثبَّتين — إشارة كلاسيكية على استبدال نظام CRM. يوضّح هذا المحرك الموحّد: نفس مفتاح technologies، ونفس المعامل، لكن على /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": ["RevOps", "Sales Operations"],
    "technologies": [114, 287],
    "filter_conditions": [
      { "key": "technologies", "operator": "and" }
    ],
    "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": ["RevOps", "Sales Operations"],
        "technologies": [114, 287],
        "filter_conditions": [
            { "key": "technologies", "operator": "and" }
        ],
        "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: ["RevOps", "Sales Operations"],
    technologies: [114, 287],
    filter_conditions: [
      { key: "technologies", operator: "and" }
    ],
    per_page: 25,
    page: 1,
  }),
});
console.log(await response.json());

أخطاء شائعة

نسيان key وإرسال operator فقط

لا يوجد مفتاح “معامل افتراضي” عام. يجب أن تسمّي كل عبارة فلترًا محددًا:

// يُتجاهل — لا يوجد key
{ "filter_conditions": [{ "operator": "and" }] }

// صحيح — يتجاوز فلتر technologies فقط
{ "filter_conditions": [{ "key": "technologies", "operator": "and" }] }

توقّع أن تتركّب العبارات معًا

العبارات هي تجاوزات مستقلة لكل مفتاح — لا تتسلسل. إدراج كل من technologies وverticals لا يُنشئ تعبيرًا منطقيًا بينهما؛ كل عبارة فقط تضبط معامل مصفوفتها الخاصة.الجمع بين مفاتيح الفلاتر المختلفة يكون دائمًا AND (يجب أن يطابق كل فلتر). لا يمكنك دمج فلترين مختلفين بعلاقة OR عبر filter_conditions. إذا كنت بحاجة إلى بحث حقيقي بعلاقة OR بين فلاتر مختلفة، شغّل طلبين ودمج النتائج من جهة العميل.

استخدام AND على مصفوفة طويلة

AND هو column @> ARRAY[…] — يجب أن تكون كل قيمة موجودة. مع 8 قيم أو أكثر تحصل غالبًا على صفر صفوف لأن الوسم في الواقع الفعلي متناثر. أبقِ المصفوفات المُتجاوَزة بـ AND عند 2-4 قيم؛ استخدم OR للتصفية الاستكشافية أو على مستوى الفئة.

مفتاح خاطئ في فلاتر الشركة داخل /people/search

في /people/search، اسم واجهة API الخاصة بالأشخاص هو company_places / company_locations. لكن داخل filter_conditions[].key يجب استخدام اسم المحرك — places، locations. تحدث إعادة التعيين داخليًا قبل أن يُستشار filter_conditions.

// لن يُطبَّق — المحرك لا يرى "company_places" كمفتاح فلتر
{ "filter_conditions": [{ "key": "company_places", "operator": "and" }] }

// صحيح
{ "filter_conditions": [{ "key": "places", "operator": "and" }] }

جدول إعادة التعيين الكامل في صفحة فلاتر الأشخاص + الشركة.

عند الشك، احذف filter_conditions أولًا وتحقق من عدد النتائج مقابل توقعاتك. أضف التجاوزات فقط للفلاتر التي لا يطابق فيها الافتراضي نيتك — هذا يبقي حمولة الطلب أصغر وأسهل في تصحيح الأخطاء.

طالع أيضًا

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

النموذج الذهني — ابدأ هنا إذا كانت filter_conditions محطتك الأولى.

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

كيفية دمج فلاتر الشركة داخل /people/search، بما في ذلك إعادة تعيين المفاتيح.

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

مخطط الطلب الكامل لـ /companies/search (يتضمن company_filter_conditions).

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

مخطط الطلب الكامل لـ /people/search (يتضمن people_filter_conditions).

Monitor

البحث

المرشحات

الأشخاص

التوسع

البنية

لماذا يهم هذا الأمر

المفاتيح المدعومة

وصفات جاهزة

أخطاء شائعة

طالع أيضًا

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

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

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

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

​البنية

​لماذا يهم هذا الأمر

​المفاتيح المدعومة

​وصفات جاهزة

​أخطاء شائعة

​طالع أيضًا

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

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

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

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

البنية

لماذا يهم هذا الأمر

المفاتيح المدعومة

وصفات جاهزة

أخطاء شائعة

طالع أيضًا