Filter-Syntax

Customermates-Filter (genutzt von den Model-Context-Protocol-Tools (MCP), der REST-API und der App-UI) sind Arrays von Feld-Operator-Wert-Regeln. Sechzehn Operatoren decken Equality, Vergleich, Set-Membership, Range, Aktualität, Null-Checks und Relationship-Membership ab.

Wo Filter greifen

• Das list_records MCP-Tool und die Messaging-Filter auf get_messaging_threads und get_activities.
• entityFilters und dealFilters auf Widgets.
• timelineFilters auf Aktivitäts-Widgets. Aktivitätsfilter erlauben höchstens eine Regel pro Feld; ODER-Alternativen gehören in das Werte-Array einer einzigen in-Regel.
• Gespeicherte Views in der UI (intern dieselbe Form).

Die Form

[
  { "field": "firstName", "operator": "contains", "value": "acme" },
  { "field": "createdAt", "operator": "gte",       "value": "2024-01-01" }
]

Regeln sind UND-verknüpft. Für ODER: zwei Queries laufen lassen und client-seitig mergen, oder den in-Operator gegen eine Liste.

Operatoren

Datums-Operatoren

Datumsfelder wie createdAt und updatedAt akzeptieren gt, gte, lt, lte, between und inLastDays. Nutzen Sie inLastDays mit einer ganzzahligen Anzahl von Tagen für ein rollierendes Aktualitätsfenster, zum Beispiel { "field": "createdAt", "operator": "inLastDays", "value": 7 } für Datensätze der letzten Woche.

Relationship- und Teilnehmer-Operatoren

Relationship-Arrays (organizationIds, dealIds, userIds, contactIds, serviceIds, taskIds) akzeptieren in, notIn, hasNone und hasSome. Das Teilnehmer-Verknüpfungsfeld auf get_messaging_threads nutzt hasUnset und allSet, um Threads danach zu filtern, ob ihre Teilnehmer mit Datensätzen verknüpft sind.

Feldnamen

field ist, was get_record_schema unter filterableFields für diese Entity zurückgibt. Enthält:

• Standard-Skalare (z.B. createdAt, updatedAt).
• Relationship-Arrays (organizationIds, dealIds, userIds, contactIds). Kombinieren Sie sie mit in, notIn, hasNone, hasSome.
• Custom-Column-IDs. Nutzen Sie die UUID der Spalte als Feldname.

Immer get_record_schema zuerst, wenn Sie unsicher sind, was filterbar ist. Die Fehlermeldung bei unbekanntem Feld listet alle verfügbaren Felder mit erlaubten Operatoren.

Beispiele

Contacts in einer von drei Organizations:

{ "field": "organizationIds", "operator": "in", "value": ["org_1","org_2","org_3"] }

Deals aus 2024, deren Custom-singleSelect-Spalte (identifiziert über ihre UUID) einem gewählten Optionswert entspricht:

[
  { "field": "createdAt", "operator": "between", "value": ["2024-01-01","2024-12-31"] },
  { "field": "col_uuid",  "operator": "equals",  "value": "option_value" }
]

Contacts ohne Organization:

{ "field": "organizationIds", "operator": "hasNone" }

Datensätze der letzten 30 Tage:

{ "field": "createdAt", "operator": "inLastDays", "value": 30 }

Freitext vs Filter

list_records akzeptiert auch searchTerm, eine Freitextsuche über die Namensfelder (firstName+lastName für Contacts, name für den Rest). Für "Contacts, deren Name 'acme' enthält" ist das searchTerm, nicht eine Filter-Regel auf firstName. Filter-Regeln auf firstName werden nicht unterstützt.

Weiter

• Kernkonzepte: Feldtypen und Beziehungen.
• MCP-Tool-Katalog: wo Filter auftauchen.