Salesforce field changes can affect source capture, Parquet exports, and Snowflake reporting separately. GRAX documents automatic schema discovery, but downstream loading and query logic still need appropriate configuration. This guide explains the documented boundaries and provides a practical sequence for investigating added fields, type changes, and missing values.
Why do Salesforce schema changes affect downstream pipelines?
Salesforce schema changes affect downstream pipelines because they alter the structure that connected systems are programmed to rely on when retrieving, processing, and interpreting data. So, when data is retrieved or processed from modified Salesforce structures, downstream systems that have their configurations based on the previous schema may not automatically recognize or accommodate the changes.
This can happen, for instance, when an organization adds a custom field to its Salesforce Account object to categorize customers as either Enterprise, Business, or Standard. Although the new field is available in Salesforce, the downstream data team may find that the field is missing from their reports because the report or view definition has not been updated to allow the change.
To understand how such differences emerge and how systems accommodate them, it is important to look into schema drift and schema evolution.
Schema drift occurs when the structure or attributes of a data source unexpectedly change, resulting in differences between the schema that downstream systems expect and the structure of the data they receive. An example of schema drift is what happens when an administrator adds a new field or removes a field from an object.
Schema evolution is the controlled adjustment of a schema to accommodate changes in incoming data. Whether a change is compatible depends on the receiving system and configuration. The goal is to ensure that the structural changes made are properly reflected in downstream data structures and processes without disrupting how existing data is being accessed and used.
Simply put, schema drift describes the changes or differences that emerge in a data structure, while schema evolution describes how those changes are accommodated across the data pipeline.
When a Salesforce field changes, the modification may affect different attributes of the field, including its label, API (Application Programming Interface) name, data type, and accessibility. The attributes of a field are each distinct, and a change to one of them does not mean that the others have changed. What changes to attributes can affect is how connected systems retrieve, process, and interpret the field.
For instance, a change to a field’s API name may affect integrations that reference the field when retrieving Salesforce records through APIs. Similarly, a change to its data type may require adjustments to ETL (Extract, Transform, Load) processes or SQL (Structured Query Language) queries that process and store its values. This is why it’s important to understand the nature of a schema change when identifying which parts of a downstream data pipeline may need to be adjusted.
For a broader overview, learn how Salesforce schema changes affect ETL pipelines.
Stop Losing Fields at the Source
GRAX finds and backs up new Salesforce fields automatically.
What does GRAX handle automatically and what remains downstream?
GRAX automatically discovers changes to the Salesforce organization by periodically examining its objects and schema. When new objects or fields are identified, GRAX adds them to its Backup system, depending on the access permissions assigned to its Salesforce integration user. This is what allows newly added fields and objects to be discovered and backed up without administrators having to manually configure each addition in GRAX.
Documentation checked November 2026: GRAX describes periodic schema discovery; capture remains subject to access and configuration.
GRAX also runs periodic scans to identify new and modified Salesforce records using Salesforce’s SystemModStamp. Whenever a record changes, Salesforce generally updates this timestamp, allowing GRAX to identify the record for backup. However, not every change in a field’s value updates the record’s SystemModStamp. For example, a formula field can return a different value when its underlying data changes without updating the timestamp of the record containing the formula.
Once the data has been captured, GRAX Data Lake documentation explains how captured data is written to configured cloud storage in Parquet format.
These files make backed-up Salesforce data available for use in external data warehouses and analytics platforms, including Snowflake. For enabled objects, GRAX Data Lake writes all fields by default; configured field exclusions limit subsequent writes.
GRAX’s export process, however, does not automatically update the structure of downstream systems. When new fields appear in Parquet exports, the receiving data warehouse must be set to accommodate them and handle the differences in data types. In Snowflake, this process may involve configuring schema evolution and column matching. The dependent SQL queries, views, and reports must also be reviewed by analytics engineers to ensure that they all reference the correct fields.
Data Team Responsibility Table
| Pipeline Layer | What needs attention | Responsible role |
| Salesforce | Object and field permissions | Salesforce administrator |
| GRAX Backup and Data Lake | Backup access, enabled objects and field inclusion settings | GRAX administrator |
| Snowflake | Parquet file loading, column matching, destination table settings and schema evolution settings | Data engineer |
| Reporting and analytics | SQL queries, views and reports that reference affected fields | Analytics engineer |
Salesforce Schema Change Response Matrix
| Salesforce change | Primary check | Recommended response |
| New field | Access and inclusion, exported schema, destination column. | Locate the first stage where the field is absent, then adjust that stage. |
| Display label only | Whether the API identifier and downstream references changed. | Keep API-based mappings if the API name is unchanged. Check any label-dependent mappings. |
| Actual API-name change | Whether the field permits the change, and which integrations reference the identifier. | Confirm the source restrictions, then review affected integrations and queries. |
| Field type or representation | File schema, destination compatibility, and business meaning. | Choose explicit conversion and error handling. Validate dependent reports. |
| Field deleted | Source metadata, retained exported files, and downstream dependencies. | Review affected references. Do not assume existing files or destination columns are removed. |
| Permissions or exclusion changed. | Integration-user access, object export status, and field configuration. | Apply the authorized access or configuration change. Assess whether a documented rewrite is needed. |
GRAX handles the discovery, capture, and export of accessible Salesforce data, while downstream teams remain responsible for configuring how that data is loaded, stored, and consumed.
What should you check when a new field is missing?
When a newly added Salesforce field is missing from a downstream report or data warehouse, the first action is to identify where the field disappears in the pipeline. The following sequence of checks can help you identify the source of the problem:
- Confirm source metadata and access: Check Salesforce object and field metadata to confirm that the new field exists and that its API name and data type are correct. Also, confirm that the GRAX integration user has permission to access the field through its field-level security permissions.
- Check object/field inclusion and capture status: The next step is to check whether the object is included in GRAX Backup and whether the integration user has access to the new field. GRAX provides a Missing Field Permissions tool under Settings (Diagnostics and Tools) to help identify the fields the integration user cannot access. Check the object’s backup status for exclusions or other permission issues. Then, review its Data Lake configuration to confirm that the object is enabled for export and the field is not excluded.
- Inspect representative Parquet exports: If the field exists in Salesforce and is accessible to GRAX, select and inspect a Parquet export to confirm whether the field appears in the exported file schema. Afterwards, compare the field’s API name and data type against Salesforce metadata. If it appears in the export, it then means that GRAX has included it in that particular file, and the investigation can move to the destination system. However, if the field is absent, investigate the capture configuration and export process to determine why it was not included.
- Inspect destination columns and the fields selected by views: If the field appears in the Parquet export but is missing from Snowflake, check whether the corresponding column exists in the destination table. Go over the loading configuration, column-matching settings, and schema evolution configuration.
If the column exists in Snowflake but is missing from a report, inspect the relevant SQL query or view projection. The query may not include the new column, or it may still reference an outdated field name.
A field missing from an exported file is different from a field that exists but contains empty values. An unavailable field is one that cannot be accessed or found at a particular stage of the pipeline. An empty historical value, however, occurs when the field exists and is available, but a particular record has no value stored for it.
Adding a field to Salesforce does not automatically populate it with values for existing records.
Do not assume a newly added field has a value in each existing record or retained version. Check the corresponding source record and captured version before treating an empty value as an export failure.
Here’s an example of how a newly added field can be checked across different stages of the pipeline.
| Pipeline stage | Field name | What to verify |
| Salesforce | Customer_Tier__c | Field exists in the Account object |
| GRAX Backup | Customer_Tier__c | Field is accessible and included |
| Parquet export | Customer_Tier__c | Field appears in the exported schema |
| Snowflake | Customer_Tier__c | Corresponding destination column exists |
| Reporting | Customer_Tier__c | View projection or SQL query includes the field |
This sequence helps to identify where a field becomes unavailable and which configuration needs attention. It also prevents teams from treating missing fields, empty values, and reporting omissions as the same problem.
Does changing a field label require changing the pipeline?
Changing a Salesforce field label does not necessarily require modifications to be made to the downstream data pipeline. To determine whether pipeline adjustments are needed when a field label is changed, you have to first confirm whether the change affects only the field’s display label or its API name, as these are separate attributes with different implications for connected systems.
A field label is the name that is displayed to users in the Salesforce interface, while its API name is the identifier that integrations and other processes use to reference the field. When only the display label changes, the API name can remain the same. In such cases, downstream systems that reference the field by its API name can generally continue retrieving and processing it without requiring changes to their configurations.
Changing a field label
Illustrative example: An organization changes the label of a custom field on its Salesforce Account object from Customer Category to Customer Segment.
| Field attribute | Before the change | After the change |
| Display label | Customer Category | Customer segment |
| API name | Customer_Category__c | Customer_Category__c |
| Data type | Picklist | Picklist |
Although the field’s label changes in this scenario, its underlying API identifier remains the same. An integration retrieving the field through the Salesforce API can continue to reference Customer_Category__c. By the same logic, downstream ETL (extract, transform, load) processes and SQL (Structured Query Language) queries that reference the API name do not necessarily need to change.
To decide whether pipeline adjustments are necessary, check how downstream processes reference the field. Review API references in integrations and ETL mappings, as well as column references in SQL queries and reporting views to know if the downstream processes depend on the field’s API name, its display label, or a corresponding column.
How can field type changes affect Parquet and Snowflake?
Changes made to Salesforce field data types can affect how data is represented in Parquet files and how Snowflake loads and processes those files. A change in data representation can result in differences between the structure of Parquet files generated before and after the Salesforce schema change.
How GRAX represents Salesforce fields in Parquet
GRAX Data Lake represents Salesforce fields in 2 main ways, including the raw/string representation and typed representations for non-string values.
The raw representation stores the field’s value as a plain text string, using the exact Salesforce field name. The typed representation, on the other hand, adds a short suffix to the original field name to reflect the data format.
For example, a Salesforce field named Customer_Score__c that contains numeric values may appear in a Parquet file as Customer_Score__c (string representation) and Customer_Score__c_f (typed numeric representation).
GRAX bases each Parquet file’s schema on the data that is contained in that file. Only the fields with non-empty values are included in a Parquet file’s data. However, the file’s schema may still list fields that have no value in that file. As a result, Parquet files can have different structures, even when they contain records from the same Salesforce object.
For field typing, review the actual exported schema. The GRAX manual contains inconsistent suffix examples; this guide does not infer a definitive mapping from them.
Documentation checked November 2026: The manual’s suffix examples are inconsistent. Inspect the actual export instead of inferring a universal mapping.
What happens when a field’s data type changes?
Illustrative example (Salesforce field type change): A company has a numerical Salesforce attribute called Customer_Score__c with values that represent numerical customer scores such as 75, 82 and 90. If at a later point, the company wants the attribute to contain descriptive text such as High, Medium, or Low, the change could affect how the field is represented in subsequent Parquet exports.
The earlier Parquet files may contain both the raw string representation and the typed numeric representation of the field. If subsequent values are descriptive text, the typed numeric representation may stop receiving values, while the raw string representation continues to hold the field’s values. This can result in differences between the schemas and data contained in files generated at different times.
When these 2 different files are loaded into Snowflake, there are 3 important questions the data engineering team needs to ask:
- Ingestion compatibility: Can Snowflake load the incoming Parquet files into the existing column names and data types? The team needs to check whether the destination schema is compatible with the representations in the incoming files. Snowflake’s MATCH_BY_COLUMN_NAME option, for example, requires matching column names and compatible data types
- Conversion rules: How should values be handled when their representations change? The team may need explicit conversion rules to standardize values before loading or using them downstream. For instance, converting a numeric value such as 75 to text is different from trying to convert descriptive text such as High into a number.
Conversion errors should be handled explicitly through validation, error reporting, or appropriate rejection and quarantine processes. Invalid values should not be silently converted to NULL, as this can conceal data-quality problems.
- Business meaning: Do the values still represent the same information? A numerical customer score and a descriptive classification such as High, Medium, or Low may serve related purposes, but they are not necessarily interchangeable. Even in scenarios where the values can be converted technically, the data team must establish whether existing calculations, reports, and business rules still make sense.
Snowflake supports automatic schema evolution for certain changes, including adding columns and dropping certain NOT NULL constraints when the required loading conditions are met. However, this does not guarantee automatic conversion or repair of incompatible data types.
For broader integration prerequisites, review Salesforce to Snowflake integration options.
What must be configured for Snowflake schema evolution?
For Snowflake to automatically accommodate new or certain schema changes in GRAX Data Lake Parquet exports, schema evolution has to be enabled on the destination table, and the file-loading process must use named-column matching. The role performing the load must also have the required privileges on the table.
Snowflake schema evolution requires 3 configurations:
- Enable schema evolution on the destination table: Set ENABLE_SCHEMA_EVOLUTION = TRUE on the standard Snowflake table. This can be done when creating a new table or by altering an existing one.
- Use named-column matching: The COPY INTO command must include MATCH_BY_COLUMN_NAME, so Snowflake maps the incoming Parquet fields to destination columns using their names
- Assign the required privileges: The role performing the load must have either the EVOLVE SCHEMA or OWNERSHIP privilege on the destination table
These requirements allow Snowflake to add new columns found in incoming files to the destination table. The feature can also drop a NOT NULL constraint when a column defined as NOT NULL in the table is missing from an incoming file. These configurations are part of the documented Snowflake schema evolution requirements.
Snowflake requirements checked in November 2026: This section covers file-based COPY loading into a standard table.
How does the file-loading process work?
The documented approach is file-based loading into a standard Snowflake table using COPY INTO <table>. The Parquet files must first be available in a Snowflake stage or supported external storage location. During loading, MATCH_BY_COLUMN_NAME instructs Snowflake to match fields in the files with destination table columns by name, not by their position in the file. The matching can be case-sensitive or case-insensitive.
There is, however, an important restriction. Snowflake does not allow MATCH_BY_COLUMN_NAME to be used with a SELECT statement that transforms data during the COPY INTO operation. These options must be used separately. If transformations are required, the files can first be loaded into a table using column matching, then transformed in a separate query or operation.
Snowflake restriction checked in November 2026: The named-column matching path described here cannot be combined with a transforming SELECT in the same COPY statement.
What does this mean for GRAX Data Lake exports?
When a new Salesforce field appears in a GRAX Parquet export, the configured Snowflake loading process can add a corresponding column to the destination table through automatic schema evolution. However, successful loading only confirms that Snowflake accepted the data. It does not guarantee that existing views, SQL queries, reports, or dashboards include the new column or interpret its values correctly. Those downstream components may still require updates.
How should you handle historical versions and repeated writes?
GRAX Data Lake writes record versions to Parquet files, not just the current state of each Salesforce record. When building downstream tables, you need to determine whether to retain one row per current record or preserve every historical version.
Each row represents the full state of a record version, which is identified by the combination of Id and source__modified. The Id identifies the Salesforce record, while source__modified records the time when that version was modified in Salesforce. GRAX also provides grax__idseq, a per-record sequence value that increases as the record changes.
A retained version shows the record state that is available at the time of the export and not a guaranteed export at every point in the record’s history.
If the reporting requirement is to show only the latest state of each record, the downstream process should retain the latest write for each Id. However, if the requirement is to preserve the record’s change history, each distinct version must remain available.
Let’s review this history example with the IDs, times, and sequence symbols simplified:
| Record ID | source__modified | grax__idseq | Name |
| 001 | 10:00 | a | Acme Ltd |
| 001 | 11:00 | b | Acme Limited |
| 001 | 12:00 | c | Acme Group |
| 001 | 11:00 | [later sequence] | Acme Limited |
Note that: The repeated row represents another write of the same record version and not a new business change. The record’s state and modification time remain the same while the sequence value identifies the later write.
A current-record table would retain only the latest version, Acme Group. A historical table, however, would retain all 3 versions so analysts can examine how the record changed over time.
Deduplicating these four rows using only Id can discard distinct historical versions. A history table should retain the three versions while resolving the repeated write.
How should repeated writes and out-of-order data be handled?
Duplicate records are an intentional approach to reduce write time and improve safety. The appropriate way to identify the latest write depends on whether the downstream table stores current records or historical versions:
- For the latest version of each record: Use Id and MAX(grax__idseq) to identify the latest write.
- For the latest write of each retained version: Use Id, source__modified and MAX(grax__idseq).
Data can also arrive out of order either within the same file or across different files. GRAX recommends not inferring version order from arrival but instead using the sequence guidance in GRAX’s Important Notes when ordering repeated writes.
Rewriting an Object and its importance
Rewriting is a documented option in GRAX Data Lake for accommodating changes such as the addition of new attributes or updates to field permissions. It involves removing an object from the Data Lake configuration and adding it again with the updated settings so that available backup data can be exported again using the updated configuration.
However, removing and re-adding an object does not delete the Parquet data that has already been written. Instead, the process can result in the previously captured records being written again, producing duplicate records in the GRAX dataset. It is important for downstream data processes to account for these duplicate records to avoid treating repeated writes as new historical changes.
A rewrite re-exports available backup data using the updated Data Lake configuration. It does not recover field values that were never captured in the backup.
To ensure that previously excluded fields remain excluded from subsequent Data Lake exports, GRAX recommends reviewing the object’s existing configuration and reapplying the exclusions when adding the object back.
Rewriting can therefore help to accommodate specific changes to an object’s configuration or field access permissions; it is not a default solution for every schema problem. It does not automatically resolve downstream deduplication, incompatible data types, or reporting issues.
The downstream handling of repeated writes depends on the structure and requirements of the receiving platform. Data engineers must determine how to identify repeated records and distinguish them from separate historical versions. For tables that retain only current records, this involves selecting the latest version of each record. For historical tables, the process must preserve distinct versions while accounting for repeated writes.
Keep History, Not Just Current State
Give analysts and AI the record history Salesforce overwrites.
How do you troubleshoot schema changes without assuming every issue is a schema error?
When a field is missing from a report, a data load fails, or duplicate rows appear in a Snowflake table, the problem may not necessarily be a schema change. The issue could originate in Salesforce field permissions, GRAX Data Lake configuration, Parquet exports, Snowflake loading, or downstream queries.
The first step is to identify where the problem occurs and verify what is happening at that stage of the data pipeline.
Here are some checks for possible causes and the recommended next steps.
| Symptom | Possible cause | Source-backed check | Recommended next step |
| Missing fields | The field is inaccessible to the GRAX integration user, excluded from the Data Lake configuration, or absent from the exported file schema. | Confirm that the field exists in Salesforce and that the integration user has field-level access. Check the object’s Data Lake configuration and inspect the Parquet schema to see whether the field is present. | Correct the relevant field permissions or Data Lake configuration. If the field is present in Parquet but missing from Snowflake, check the destination table and loading configuration. |
| Type mismatches | A Salesforce field’s data type or the representation of its values has changed, resulting in different typed fields across Parquet exports. | Compare the field’s representation and type in Parquet files generated before and after the change. GRAX documents that typed fields can vary over time as the underlying schema and data change. | Review the destination column’s data type and Snowflake loading requirements. Apply an appropriate conversion or loading adjustment where necessary. |
| Unexpected null values | The Salesforce record may not contain a value for the field, the field may have been added after the record was created, or the field may not be available in the exported data. | Check the field’s value in the corresponding Salesforce record, then compare it with the Parquet file. GRAX notes that only fields with non-empty values are considered for inclusion, although a file schema can contain fields with no values. | If the source value is truly missing, ask the Salesforce data owner whether it should be populated. Otherwise, investigate the affected capture, export, or load stage. |
| Stale reports | The Snowflake table may not have received the latest data, or the report’s query or view may not include the updated column or records. | Review Snowflake’s load history to confirm whether the relevant files were loaded and check the SQL queries and views used by the report. Snowflake’s COPY_HISTORY provides file names, load status, row counts, and error details. | Resolve any incomplete or failed loads, then update dependent queries, views, or reports where necessary. |
| Duplicate historical rows | GRAX Data Lake can produce duplicate records as part of its documented write behaviour. Rewriting an object can also cause previously written records to appear again. | Compare the Id, source__modified and grax__idseq values. GRAX documents using Id with MAX(grax__idseq) to identify the latest write for the latest record version, and all three fields to identify the latest write per version. | Adjust downstream deduplication to distinguish repeated writes from separate historical versions. Preserve distinct versions if the table is intended to retain record history. |
Note: A possible cause listed in this table is not a confirmed diagnosis. For example, a missing field does not automatically mean GRAX failed to capture it, just as a null value does not necessarily indicate a broken export. Each issue should be traced through the relevant stages before making changes.
Troubleshooting Checklist
When investigating a schema-related issue, work through the following steps in order:
- Identify the actual source change: Confirm whether a Salesforce field was added, deleted, renamed, or changed in data type. Check whether the issue started after that change.
- Confirm access and export configuration: Verify the GRAX integration user’s field permissions, the object’s Data Lake status, and whether the affected field is included in the export configuration.
- Inspect the Parquet file schema: Compare the affected field’s name, representation, and data type in the exported files. Check whether the field is present and whether its representation differs across files
- Review the Snowflake load status: Check the relevant file-loading history for successful, failed, or partially loaded files. Review any reported errors and confirm that the expected data reached the destination table
- Check dependent queries: Inspect SQL queries, views, and reports that reference the affected fields. Confirm that they include the correct columns and handle any changes in data representation.
- Document the chosen fix and verify it in your environment: Record what caused the issue, the configuration or query changes made, and the results of testing. Confirm that the affected data loads and downstream reports behave as expected.
Quick Recap
- Identify the source change and locate the first affected stage: capture, export, loading, or reporting
- Check field access and actual exported schemas before changing destination logic
- Treat loading compatibility, conversion errors, and reporting meaning as separate checks
- Choose current-record or version-history requirements before deduplicating repeated writes
If the issue involves GRAX Backup or Data Lake behavior and cannot be resolved through the documented checks, you can contact GRAX Support through the in-app Get Support tab.
Looking to review your Salesforce data pipeline? Discuss your Salesforce data pipeline with GRAX.
Pressure-Test Your Salesforce Pipeline
Walk through your Data Lake setup with the GRAX team.