Not verified hands-on. This article was written from primary documentation rather than reproduced in an org, so it carries no tested-release badge. If you run it and something differs, say so in the comments and it gets tested and corrected.

Field Audit Trail extends field history retention well past the standard window, raises how many fields you can track per object, and moves aged history into a big object called FieldHistoryArchive that you query with SOQL. There is no Setup page for it. You configure it by deploying a HistoryRetentionPolicy through the Metadata API, and that surprises almost everyone the first time.

What standard field history gives you

Without Field Audit Trail, tracked field changes land in the object’s history related list and its corresponding history object, and they are retained for a limited period measured in months rather than years. You can track a modest number of fields per object. For most orgs that is adequate for operational questions and inadequate for anything a regulator asks.

Field Audit Trail raises both ceilings. The field count per object goes up substantially, and retention can be defined in years rather than months. If you are in financial services, healthcare, or anywhere with a statutory record-keeping obligation, this is the feature that meets it.

The retention policy

A HistoryRetentionPolicy attaches to an object and has three parts that matter:

  • archiveAfterMonths. How long history stays in the normal history object and visible in the related list.
  • archiveRetentionYears. How long the archived rows are kept after that.
  • gracePeriodDays. A buffer before archiving actually begins.

It is deployed as part of the object’s metadata, not clicked together in Setup. In practice that means writing the policy into your source, deploying it to a sandbox, confirming it applied, and promoting it like any other change. Salesforce applies a default policy to enabled objects if you do not define one, so check what is in place before assuming nothing is happening.

<historyRetentionPolicy>
    <archiveAfterMonths>18</archiveAfterMonths>
    <archiveRetentionYears>10</archiveRetentionYears>
    <description>Regulatory retention</description>
</historyRetentionPolicy>

Querying the archive

Archived rows live in FieldHistoryArchive, a big object. Big objects are not regular objects and the differences matter more than the similarities.

The index is composite, built from the history type, the parent record Id and the created date, in that order. Your WHERE clause has to follow that order from the left. You can filter on the first field alone, or the first two, or all three. You cannot skip one.

SELECT FieldHistoryType, ParentId, Field, OldValue, NewValue, CreatedDate
FROM FieldHistoryArchive
WHERE FieldHistoryType = 'Account'
  AND ParentId = '001xx000003DGb2AAG'
  AND CreatedDate > 2020-01-01T00:00:00Z

A query that does not respect the index order fails rather than running slowly, which is at least honest. There are no reports over big objects in the way you are used to, so surfacing this data to a business user means building something: a Lightning component, an Apex-backed page, or an export into whatever analytics tool you already run.

Practical constraints

  • Archived data is effectively immutable. Treat the policy as a one-way decision and think carefully before enabling it on an object with enormous change volume.
  • Deleting a record removes its ordinary field history. Archived rows are a separate store, which is the point of an archive but also something your data deletion process has to account for.
  • History only exists for fields you tracked at the time the change happened. Turning on tracking today does not create history for yesterday, and this is the single most common disappointment when an audit request arrives.
  • Not every field type can be tracked. Long text, multi-select picklists and formula fields have limitations worth checking before you promise coverage.

Deciding what to track

Pick fields by the question you will be asked, not by importance. “Who changed the approved credit limit and when” is a question. “The account is important” is not. A short list of fields with ten-year retention is more useful than every field with an inconsistent policy.

Write the reason for each tracked field somewhere durable. In three years the person answering the auditor will not be you, and the field list on its own explains nothing.

Frequently asked

Do I need Shield for Field Audit Trail? It is licensed as part of the Shield family or as an add-on. Confirm what your contract actually includes before designing a retention policy around it.

Can I see archived history in the related list? No. Once rows archive they leave the related list and are only reachable through SOQL against the big object.

Does it track deletions of records? No. It tracks field value changes on tracked fields. Record deletion is a different problem, and the Recycle Bin is not an audit control.

Can I turn a policy off later? You can change the policy, but data already archived behaves according to the rules in force when it was written. Plan the policy properly rather than iterating on it in production.