Filter-Syntax

CRM-Listen, gespeicherte Ansichten, Widgets, REST-Abfragen und das MCP-Tool query_crm_records nutzen dasselbe Abfragemodell. Ermitteln Sie den Typ mit discover_record_types und lesen Sie stabile Feld- und Beziehungs-IDs mit get_record_model. Jede Liste hat dieselbe Abfragestruktur, ob die KI-Einrichtung oder eine Person sie angelegt hat. Messaging-Tools besitzen eigene Filter.

Wo greifen Filter?

Eine Datensatzabfrage nennt einen typeId. filters prüfen Felder dieses Typs, relationships prüfen verknüpfte Datensätze und relatedFilters folgen einem definierten Beziehungspfad. Regeln innerhalb der Arrays werden mit UND verknüpft. search durchsucht lesbare Textfelder. Das Backend prüft Workspace- und Datensatzrechte auch entlang verknüpfter Pfade.

Wie filtere ich eine Liste in der App?

Öffnen Sie die Liste, zum Beispiel Ihre Deal-Liste, und klicken Sie in ihrer Toolbar auf Filter. Wählen Sie unter Filtern nach ein Feld oder tippen Sie seinen Namen in Filter hinzufügen…; verknüpfte Listen, etwa eine Organisationsliste, stehen dort ebenfalls. Wählen Sie die Bedingung und dann die Werte, und die Liste aktualisiert sich sofort. Aktive Filter erscheinen oben als Chips; einen entfernen Sie mit seinem ×, alle mit Leeren. Mate fragen im selben Fenster macht aus einer Beschreibung in eigenen Worten Filter. Jede Liste funktioniert so, und eine gespeicherte Ansicht zeigt dieselben Datensätze, statt sie zu kopieren.

Wie sieht eine Filterregel aus, und kann ich Filter mit ODER verknüpfen?

Ein Feldfilter enthält fieldId, operator, einen typisierten Skalar value (oder null) und bei Mengen oder Bereichen optional values. Beispiel:

{
  "typeId": "00000000-0000-4000-8000-000000000001",
  "filters": [
    {
      "fieldId": "00000000-0000-4000-8000-000000000002",
      "operator": "contains",
      "value": { "kind": "text", "value": "Acme" }
    }
  ]
}

in trifft einen von mehreren Werten desselben Felds. Für ODER über verschiedene Felder führen Sie getrennte Abfragen aus oder nutzen eine geeignete Abfrage verknüpfter Datensätze; normale Feldregeln werden mit UND verknüpft. Eine Abfrage erlaubt bis zu 50 Feldregeln und 500 Zeichen in search.

Welche Operatoren gibt es?

Der Datensatzvertrag unterstützt 16 Feldoperatoren. Feldtyp und Verhalten bestimmen, welche davon gültig sind; inkompatible Kombinationen weist das Backend zurück.

eq vergleicht Text exakt; contains und startsWith ignorieren Großschreibung. Währungsvergleiche verlangen eine passende Währung. Fehlend, null, eingeschränkt und Berechnungsfehler sind verschiedene Zustände; ein eingeschränktes Ergebnis darf über Filtern oder Sortieren keine verborgenen Eingaben preisgeben.

Welche Datums-Operatoren gibt es, etwa für die letzten 7 Tage?

Datums- und Zeitfelder unterstützen passende Vergleiche und between. Systemdaten verwenden system:createdAt und system:updatedAt als Feld-IDs. inLastDays und notInLastDays erwarten einen Dezimal-Skalar ohne Währung, etwa {"kind":"decimal","value":"7","currency":null}. inLastDays umfasst Werte ab Mitternacht UTC N Tage vor der Uhr der Abfrage; notInLastDays (Älter als… in der App) findet Werte strikt vor dieser Grenze, sodass notInLastDays 3 zusammen mit inLastDays 7 Werte von vor drei bis sieben Tagen findet. Relative Fenster nutzen die Uhr der Abfrage; gespeicherte Berechnungen ändern sich nicht unbemerkt mit der Zeit.

Welche Operatoren wirken auf Textfelder?

Text-, E-Mail-, Telefon- und URL-Felder unterstützen die zu ihrem Werttyp passenden Textoperatoren. Felder mit mehreren Werten werden elementweise durchsucht. Prozentzeichen und Unterstriche in Suchbegriffen sind Zeichen, keine SQL-Platzhalter.

Welche Operatoren gibt es für Beziehungen, etwa um Kontakte ohne Organisation zu finden?

Beziehungsfilter stehen getrennt von Feldfiltern. Geben Sie relationId, direction (outgoing oder incoming), operator (any oder none) und recordIds an. recordIds: null prüft beliebige zugängliche verknüpfte Datensätze; explizite IDs prüfen bestimmte Datensätze. none mit recordIds: null findet Datensätze ohne zugängliche Verknüpfung dieser Beziehung. Die Beziehungsdefinition legt Endpunkttypen und Kardinalität fest.

Kontakte ohne Organisation finden Sie mit der Kontakt-Organisations-Beziehung, operator: none und recordIds: null; die Beziehungs-ID stammt aus get_record_model.

Wie filtere ich nach einem eigenen Feld, und welche Operatoren wirken darauf?

Verwenden Sie die Feld-ID aus get_record_model und niemals die veränderbare Beschriftung. Ein Eingabe-, Formel-, Lookup- oder Rollup-Feld ist filterbar, wenn sein Werttyp den Operator unterstützt und die lesende Person den Wert sehen darf. Auswahlfilter nutzen stabile Options-IDs. Ein Mehrfachauswahl-Feld unterstützt in (enthält eine der Optionen), all (enthält alle), notIn (enthält keine, auch Datensätze ohne Wert), empty und notEmpty; es lässt sich nicht sortieren. Das gilt für die Felder jeder Liste.

Welche Feldnamen kann ich nutzen?

Verwenden Sie stabile Feld-IDs aus get_record_model. Die Systemschlüssel system:createdAt, system:updatedAt und system:assignedTo stehen zur Verfügung, sofern unterstützt. Beziehungen verwenden ihre Definitions-IDs in relationships statt Namen wie organizationIds. Umbenannte Felder, Typen und Beziehungen behalten ihre IDs; gespeicherte Ansichten und KI-Abfragen bleiben gültig.

Inbox-Listen bieten außerdem connectedAccountId, kontospezifische emailFolder, lastMessageDirection, lastMessageSentAt und lastMessageAt. Rufen Sie zuerst get_messaging_threads ohne Filter auf (oder manage_data_views mit action: "config", der Inbox-Oberfläche und section: "filters") und übernehmen Sie den exakten filterableFields.options[].value für Konto oder Ordner. emailFolder erlaubt in und notIn; jede Ordnerreferenz enthält ihr Konto. Ordneroptionen liefern groupKey als Kontoidentität und groupLabel als Überschrift, damit Konten auch bei gleichem Anzeigenamen getrennte Gruppen bleiben. lastMessageDirection erlaubt inbound/outbound mit in/notIn und ignoriert Entwürfe, ausgeblendete oder gelöschte Nachrichten und Systemereignisse. lastMessageSentAt filtert das Datum derselben letzten tatsächlichen Nachricht. Kombinieren Sie notInLastDays mit Wert 3 und inLastDays mit Wert 7 auf diesem Feld für drei bis sieben Tage alte Nachrichten; Konto-, Ordner- und Richtungsfilter lassen sich zusätzlich kombinieren. lastMessageAt filtert die letzte Aktivität einschließlich Entwürfen. Siehe Inbox-Filter.

Beispiele

Kontakte mit einer bestimmten Organisation:

{
  "relationships": [{
    "relationId": "00000000-0000-4000-8000-000000000003",
    "direction": "outgoing",
    "operator": "any",
    "recordIds": ["00000000-0000-4000-8000-000000000004"]
  }]
}

Für Datensätze ohne zugängliche Verknüpfung dieser Beziehung nutzen Sie "operator":"none" und "recordIds":null. Für ein Datumsfeld vor Juli 2024 nutzen Sie einen typisierten date-Wert mit lt. Für ein Auswahlfeld verwenden Sie in und die Options-IDs in values. In einer Abfrage lassen sich diese Bedingungen mit UND verbinden.

Soll ich search (Freitextsuche) oder einen Filter nutzen?

search ist geeignet, wenn die Phrase in irgendeinem lesbaren durchsuchbaren Textfeld stehen kann. filters ist geeignet, wenn es auf das genaue Feld oder den Vergleich ankommt. Suche und Filter werden mit UND verbunden. Identitätskanäle können nur bei einem Typ mit geschützter Personenidentitäts-Fähigkeit und mit entsprechenden Leserechten an der Suche teilnehmen; sie sind keine gewöhnlichen E-Mail-Felder.

Weiter

• Grundkonzepte: konfigurierte Felder und Beziehungen.
• MCP-Tool-Katalog: query_crm_records und Schema-Ermittlung.
• CRM-Datensätze: Listenfilter und gespeicherte Ansichten.