From c214f496a415c6a5696de1e2d881aa2d9d82e61a Mon Sep 17 00:00:00 2001 From: Chris Eberle Date: Tue, 8 Sep 2026 11:34:08 -0700 Subject: [PATCH 1/2] docs: document read field filters in manifest reference MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The manifest schema reference had no mention of read filters, so anyone searching that page for how to filter records found nothing and no pointer. `fieldFilters` is not a manifest field — it exists only in the installation config schema — so document it as such rather than as amp.yaml syntax. manifest-reference: - Pointer under the read object table drawing the which-fields vs which-records distinction. - Bullet in the backfill considerations noting the installation config's backfill object accepts fieldFilters, which amp.yaml does not. - New "Field filters" section under Details: JSON example, field table, AND semantics, provider support, and object-level vs backfill-scoped precedence. read-actions: - New "Filter field names" section documenting that fieldName must be the provider's API name and that field mappings are not resolved for read filters, unlike search actions. Also notes the filter field need not be in selectedFields. Co-Authored-By: Claude Opus 5 (1M context) --- src/manifest-reference.mdx | 43 ++++++++++++++++++++++++++++++++++++++ src/read-actions.mdx | 28 +++++++++++++++++++++++++ 2 files changed, 71 insertions(+) diff --git a/src/manifest-reference.mdx b/src/manifest-reference.mdx index 47c70d5a..4ff59400 100644 --- a/src/manifest-reference.mdx +++ b/src/manifest-reference.mdx @@ -209,6 +209,9 @@ Each object in the `objects` array defines a specific data type to read from the | `mapToName` | String | No | An optional name mapping for this object. Used to standardize object names across different providers. See [Object and Field Mapping](/object-and-field-mapping) for details. | | `mapToDisplayName` | String | No | An optional display name mapping for this object. Used for UI display. | +These fields control **which fields** are read. To control **which records** are read, use `fieldFilters`, which is set per-installation in the installation config rather than in `amp.yaml`. +> Learn more in [Field filters](#field-filters). + When configuring fields for a read object, keep these points in mind: @@ -312,9 +315,49 @@ Backfill Considerations - Setting `fullHistory: true` may result in longer initial sync times, especially for large datasets. - Some providers may have API rate limits that affect backfill performance. +- In the installation config, the `backfill` object accepts one additional key, `fieldFilters`, which restricts the records read during backfill. It is not available in `amp.yaml`. See [Field filters](#field-filters). - See [Read Actions backfill behavior](/read-actions#backfill-behavior) for detailed implementation guidance. +### Field filters + +Field filters restrict **which records** a read action returns, by matching against field values. Only matching records are read and delivered to your destination. + +Unlike every other field on this page, `fieldFilters` is **not part of the manifest schema** — it cannot be set in `amp.yaml`. It is set per-installation in the installation config, when creating or updating an installation via the [REST API](/reference/installation/create-a-new-installation) or Headless UI's [createInstallation method](/headless#create-update-and-delete-installations): + +```json +{ + "read": { + "objects": { + "contacts": { + "objectName": "contacts", + "selectedFields": { "email": true, "status": true }, + "fieldFilters": [ + { "fieldName": "status", "operator": "eq", "value": "active" } + ] + } + } + } +} +``` + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `fieldName` | String | Yes | The name of the field to filter on. This must match the field name in the provider's API — a `mapToName` from your manifest is not resolved here. Case-sensitive. See [Filter field names](/read-actions#filter-field-names). | +| `operator` | String | Yes | The comparison operator. Currently only `eq` (equals) is supported. | +| `value` | String, Boolean, or Number | Yes | The value the field must equal. | + +Multiple filters are joined with AND logic, and each field can only have one condition. + + +Field filter considerations + +- Filtered reads are currently only supported for **Salesforce** (CRM module) and **HubSpot**. For other providers the filter has no effect and all records are read. +- Object-level `fieldFilters` apply to scheduled reads, backfill, and [triggered reads](/read-actions#trigger-a-read). Setting `fieldFilters` inside `backfill` overrides them during backfill only — see [backfill-specific filters](/read-actions#backfill-specific-filters). +- Because filters live in the installation config rather than the manifest, each customer's installation can filter differently, and deploying a new manifest does not change them. +- See [Filter by field values](/read-actions#filter-by-field-values) for full details. + + ### Field In [Read Actions](#read-definition), fields can be configured in two main ways - either using a simple `fieldName` reference or using a mapped field approach (`mapToName`, `mapToDisplayName`, `prompt`, `default`). This flexibility allows for both direct field references and more sophisticated field mapping options. diff --git a/src/read-actions.mdx b/src/read-actions.mdx index 41574d84..2a41dbd8 100644 --- a/src/read-actions.mdx +++ b/src/read-actions.mdx @@ -202,6 +202,34 @@ If you want different filter behavior for backfill vs. incremental reads, you ca In this example, the backfill will only return contacts whose `firstname` equals "Brian", while subsequent incremental reads will only return contacts whose `status` equals "active". +### Filter field names + +The `fieldName` of a filter must be the field's name in the provider's API, and it is case-sensitive. + + +Read filters do **not** resolve [object and field mappings](/object-and-field-mapping). A `mapToName` from your `amp.yaml`, or a mapping your customer selected during installation, is not translated to the underlying provider field. This differs from [search actions](/search-actions#execute-a-search), which do accept mapped field names. + + +For example, if your manifest maps the provider field `mobilephone` to `phone`: + +```yaml +requiredFields: + - fieldName: mobilephone + mapToName: phone +``` + +then a filter on that field must still reference `mobilephone`: + +```json +// Correct — the provider's field name +{ "fieldName": "mobilephone", "operator": "eq", "value": "1234567890" } + +// Incorrect — mapToName is not resolved, so the read will fail or return no records +{ "fieldName": "phone", "operator": "eq", "value": "1234567890" } +``` + +The field you filter on does not have to be one of the object's `selectedFields`. You can filter on a field that you don't read. + ### Valid filter values The `value` field of the filter accepts strings, booleans, and numbers: From df40844c8a83a950874f793e66783e4663994d31 Mon Sep 17 00:00:00 2001 From: Chris Eberle Date: Mon, 14 Sep 2026 12:18:01 -0700 Subject: [PATCH 2/2] remove verbose stuff --- src/manifest-reference.mdx | 35 +---------------------------------- 1 file changed, 1 insertion(+), 34 deletions(-) diff --git a/src/manifest-reference.mdx b/src/manifest-reference.mdx index 4ff59400..78061206 100644 --- a/src/manifest-reference.mdx +++ b/src/manifest-reference.mdx @@ -323,40 +323,7 @@ Backfill Considerations Field filters restrict **which records** a read action returns, by matching against field values. Only matching records are read and delivered to your destination. -Unlike every other field on this page, `fieldFilters` is **not part of the manifest schema** — it cannot be set in `amp.yaml`. It is set per-installation in the installation config, when creating or updating an installation via the [REST API](/reference/installation/create-a-new-installation) or Headless UI's [createInstallation method](/headless#create-update-and-delete-installations): - -```json -{ - "read": { - "objects": { - "contacts": { - "objectName": "contacts", - "selectedFields": { "email": true, "status": true }, - "fieldFilters": [ - { "fieldName": "status", "operator": "eq", "value": "active" } - ] - } - } - } -} -``` - -| Field | Type | Required | Description | -|-------|------|----------|-------------| -| `fieldName` | String | Yes | The name of the field to filter on. This must match the field name in the provider's API — a `mapToName` from your manifest is not resolved here. Case-sensitive. See [Filter field names](/read-actions#filter-field-names). | -| `operator` | String | Yes | The comparison operator. Currently only `eq` (equals) is supported. | -| `value` | String, Boolean, or Number | Yes | The value the field must equal. | - -Multiple filters are joined with AND logic, and each field can only have one condition. - - -Field filter considerations - -- Filtered reads are currently only supported for **Salesforce** (CRM module) and **HubSpot**. For other providers the filter has no effect and all records are read. -- Object-level `fieldFilters` apply to scheduled reads, backfill, and [triggered reads](/read-actions#trigger-a-read). Setting `fieldFilters` inside `backfill` overrides them during backfill only — see [backfill-specific filters](/read-actions#backfill-specific-filters). -- Because filters live in the installation config rather than the manifest, each customer's installation can filter differently, and deploying a new manifest does not change them. -- See [Filter by field values](/read-actions#filter-by-field-values) for full details. - +Unlike every other field on this page, `fieldFilters` is **not part of the manifest schema** — it cannot be set in `amp.yaml`. It is set per-installation in the installation config, when creating or updating an installation via the [REST API](/reference/installation/create-a-new-installation) or Headless UI's [createInstallation method](/headless#create-update-and-delete-installations). See the linked documentation for more information. ### Field