> ## 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.
# معاملات AND / OR
> تجاوز معامل AND/OR الافتراضي لأي فلتر متعدد القيم — مرجع كامل مع أمثلة جاهزة للنسخ.
`filter_conditions` هي مصفوفة اختيارية واحدة في نص الطلب. ترفع كل عبارة فلترًا واحدًا متعدد القيم من سلوك OR الافتراضي ("مطابقة أي قيمة") إلى AND ("مطابقة جميع القيم")، أو العكس. الفلاتر التي لا تذكرها تبقى على قيمها الافتراضية.
## البنية
```json JSON theme={null}
{
"filter_conditions": [
{ "key": "technologies", "operator": "and" },
{ "key": "verticals", "operator": "or" }
]
}
```
```typescript TypeScript theme={null}
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 — وليس واحدة فقط.
```bash cURL theme={null}
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
}'
```
```python Python theme={null}
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())
```
```javascript Node.js theme={null}
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` مع فلتر الاستبعاد بشكل مستقل — دون الحاجة إلى تجاوز.
```bash cURL theme={null}
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
}'
```
```python Python theme={null}
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())
```
```javascript Node.js theme={null}
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`.
```bash cURL theme={null}
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
}'
```
```python Python theme={null}
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())
```
```javascript Node.js theme={null}
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`.
```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": ["RevOps", "Sales Operations"],
"technologies": [114, 287],
"filter_conditions": [
{ "key": "technologies", "operator": "and" }
],
"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": ["RevOps", "Sales Operations"],
"technologies": [114, 287],
"filter_conditions": [
{ "key": "technologies", "operator": "and" }
],
"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: ["RevOps", "Sales Operations"],
technologies: [114, 287],
filter_conditions: [
{ key: "technologies", operator: "and" }
],
per_page: 25,
page: 1,
}),
});
console.log(await response.json());
```
***
## أخطاء شائعة
لا يوجد مفتاح "معامل افتراضي" عام. يجب أن تسمّي كل عبارة فلترًا محددًا:
```json theme={null}
// يُتجاهل — لا يوجد key
{ "filter_conditions": [{ "operator": "and" }] }
// صحيح — يتجاوز فلتر technologies فقط
{ "filter_conditions": [{ "key": "technologies", "operator": "and" }] }
```
العبارات هي تجاوزات مستقلة لكل مفتاح — لا تتسلسل. إدراج كل من `technologies` و`verticals` لا يُنشئ تعبيرًا منطقيًا بينهما؛ كل عبارة فقط تضبط معامل مصفوفتها الخاصة.
الجمع *بين* مفاتيح الفلاتر المختلفة يكون دائمًا AND (يجب أن يطابق كل فلتر). لا يمكنك دمج فلترين مختلفين بعلاقة OR عبر `filter_conditions`. إذا كنت بحاجة إلى بحث حقيقي بعلاقة OR بين فلاتر مختلفة، شغّل طلبين ودمج النتائج من جهة العميل.
AND هو `column @> ARRAY[…]` — يجب أن تكون كل قيمة موجودة. مع 8 قيم أو أكثر تحصل غالبًا على صفر صفوف لأن الوسم في الواقع الفعلي متناثر. أبقِ المصفوفات المُتجاوَزة بـ AND عند 2-4 قيم؛ استخدم OR للتصفية الاستكشافية أو على مستوى الفئة.
في `/people/search`، اسم واجهة API الخاصة بالأشخاص هو `company_places` / `company_locations`. لكن داخل `filter_conditions[].key` يجب استخدام **اسم المحرك** — `places`، `locations`. تحدث إعادة التعيين داخليًا قبل أن يُستشار `filter_conditions`.
```json theme={null}
// لن يُطبَّق — المحرك لا يرى "company_places" كمفتاح فلتر
{ "filter_conditions": [{ "key": "company_places", "operator": "and" }] }
// صحيح
{ "filter_conditions": [{ "key": "places", "operator": "and" }] }
```
جدول إعادة التعيين الكامل في صفحة [فلاتر الأشخاص + الشركة](/ar/developer-guides/filters/people-with-company-filters#key-remap-reference).
عند الشك، احذف `filter_conditions` أولًا وتحقق من عدد النتائج مقابل توقعاتك. أضف التجاوزات فقط للفلاتر التي لا يطابق فيها الافتراضي نيتك — هذا يبقي حمولة الطلب أصغر وأسهل في تصحيح الأخطاء.
***
## طالع أيضًا
النموذج الذهني — ابدأ هنا إذا كانت `filter_conditions` محطتك الأولى.
كيفية دمج فلاتر الشركة داخل `/people/search`، بما في ذلك إعادة تعيين المفاتيح.
مخطط الطلب الكامل لـ `/companies/search` (يتضمن `company_filter_conditions`).
مخطط الطلب الكامل لـ `/people/search` (يتضمن `people_filter_conditions`).