qobrix_search_contacts
Search contacts with hard must-have filters and optional weighted soft criteria to rank results by relevance.
Instructions
Relevance-ranked contact search (F1-optimized). TWO-TIER: search = hard must-haves; boost[] = soft weighted preferences scored over up to max_scan candidates; limit = top-N returned. With boost: rows get _relevance + _matched; pagination.mode='ranked'. Call qobrix_search_dsl_help({resource:'Contacts'}) for DSL + fields. Examples: search='country == "CY"', boost=[{field:'city',op:'==',value:'Limassol',weight:2},{field:'is_company',op:'==',value:false,weight:1}], limit=10, max_scan=100. Hard-only: assigned_to == CURRENT_USER; name contains "Smith"; created >= THIS_MONTH.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number (default 1). Used on the fast path (no boost). Ignored when boost is set (ranking returns a single top-N page). | |
| sort | No | Sort by field name (maps to Qobrix OpenAPI sort[]). Prefix with - for descending. Comma-separated for multi-key (e.g. '-list_selling_price_amount,-created'). Examples: '-created' (newest first), 'name' (alphabetical), '-list_selling_price_amount' (highest list price first). | |
| boost | No | Soft relevance criteria (nice-to-haves). Never filters out rows — only ranks them. When present, the tool scans up to max_scan candidates matching `search`, scores each row as the sum of matched clause weights, and returns the top `limit` with _relevance and _matched. Put must-haves in `search`; put preferences here. Example: [{field:'sea_view',op:'==',value:true,weight:3},{field:'bedrooms',op:'>=',value:3,weight:2}]. | |
| limit | No | How many results to return (1-100, default 10). With boost: top-N after ranking. Without boost: page size. Raise when the user wants more options; keep low to avoid context overload. | |
| fields | No | Limit response to specific fields only (partial response). Reduces payload size. Example: ['id','name','status','list_selling_price_amount']. Omit to get all fields. | |
| search | No | Hard-filter Qobrix search expression (server-side precision). Operators: == != <> < > <= >=, contains, starts with, ends with, in [...], not in, ranges in a..b, and/or/not. Functions: DISTANCE_FROM, IN_POLYGON, TRANSLATED, MIN/MAX, DAYS_AGO(n), MONTHS_AGO(n), DAYS_FROM_NOW(n). Shortcuts: NOW, TODAY, THIS_WEEK, LAST_MONTH, THIS_YEAR, CURRENT_USER. Strings double-quoted; booleans true/false; association paths e.g. SalespersonUsers.Contacts.country. Example: status == "available" and sale_rent == "for_sale" and list_selling_price_amount <= 500000. For the full grammar + field cheatsheets call qobrix_search_dsl_help. For enum values call qobrix_get_field_options; for all fields call qobrix_get_schema. | |
| max_scan | No | Candidate pool size when boost is set (default 100, hard cap 500). When expand=true or media=true the effective scan is capped at 100 (pagination.scan_capped_reason='expand/media') to keep latency and payload size safe. Higher improves recall (less chance of missing a good listing) but costs more API pages. Ignored on the fast path (no boost). Each scanned page is response-cached. |