diff --git a/src/manifest-reference.mdx b/src/manifest-reference.mdx index 47c70d5a..78061206 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,16 @@ 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). See the linked documentation for more information. + ### 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: