One interesting issue we hit during one of the GoldenGate DAA to Microsoft Fabric Lakehouse testing was not really a replication failure. GoldenGate was running fine, the Replicat was not abended, the trail was being read, and stats were showing that records were getting processed. So from a GoldenGate side, everything looked healthy. But when we checked the Fabric Lakehouse, the files were not showing up where we expected them.

That made the issue a little tricky at first. Usually, when something is wrong with GoldenGate, we expect to see an abend, an authentication error, a trail read issue, or something obvious in the report file. In this case, GoldenGate was doing its job. The problem was that the output path being used by the OneLake handler was not the folder structure the team wanted. The target was Microsoft Fabric Lakehouse, and the GoldenGate property file had the usual OneLake entries: workspace, lakehouse, tenant ID, OneLake endpoint, app registration client ID/secret, classpath, and datatype mapping options. Something like this:

gg.target=fabric_lakehouse

gg.eventhandler.onelake.workspace=<workspace_name>
gg.eventhandler.onelake.lakehouse=<lakehouse_name>
gg.eventhandler.onelake.tenantId=<tenant_id>
gg.eventhandler.onelake.endpoint=https://onelake.dfs.fabric.microsoft.com

gg.eventhandler.onelake.clientId=<client_id>
gg.eventhandler.onelake.clientSecret=<client_secret>

gg.handler.onelake.format.enableDecimalLogicalType=true
gg.handler.onelake.format.mapOracleNumbersAsStrings=false
gg.handler.onelake.format.mapLargeNumbersAsStrings=false
gg.handler.onelake.format.enableTimestampLogicalType=true
gg.format.timestamp=yyyy-MM-dd HH:mm:ss.SSS

With this basic configuration, files were getting created, but GoldenGate was using its own default folder pattern. That default structure was not what the downstream team wanted to consume. The expectation was simple. We wanted the files to go under a clean Lakehouse folder, something like:

Files/<business-folder>/<schema>/<table>

But the actual folder structure was coming out differently. At one point, we saw folder names with .schema in them, like:

Files/<business-folder>/<schema>.schema/<table>

At first, it was easy to think this might be a Fabric artifact or something automatically added by GoldenGate. But after checking the property file carefully, we realized the .schema suffix was coming from our own path mapping template. The property had been set like this:

gg.eventhandler.onelake.pathMappingTemplate=${catalogname}.lakehouse/Files/<business-folder>/${schemaname}.schema/${tablename}

So GoldenGate was doing exactly what we told it to do. Because the template had ${schemaname}.schema, it created folders with .schema in the name. The fix was simple once we identified it. We removed .schema from the template:

gg.eventhandler.onelake.pathMappingTemplate=${catalogname}.lakehouse/Files/<business-folder>/${schemaname}/${tablename}

After this change, the Lakehouse folder structure became much cleaner … Files/<business-folder>/<schema>/<table> and that solved the issue.

The second feedback was around parquet file names. The files were being generated with the GoldenGate process name as a prefix. That can be useful in some cases, but here the team wanted a cleaner name based only on schema, table, and timestamp. So instead of file names like this —> <replicat_name>_<schema>.<table>_<timestamp>.parquet and the expected format was —> <schema>.<table>_<timestamp>.parquet

To control that, I’ve added this property:

gg.eventhandler.onelake.fileNameMappingTemplate=${schemaname}.${tablename}_${currentTimestamp[yyyy-MM-dd_HH-mm-ss.SSS]}.parquet

With that, the file names became much easier to understand from the Fabric side. The final important part of the property file looked like this:

gg.eventhandler.onelake.pathMappingTemplate=${catalogname}.lakehouse/Files/<business-folder>/${schemaname}/${tablename}
gg.eventhandler.onelake.fileNameMappingTemplate=${schemaname}.${tablename}_${currentTimestamp[yyyy-MM-dd_HH-mm-ss.SSS]}.parquet

Once those changes were made, we restarted the target process. For a normal CDC flow, a stop/start would be enough for new files to follow the new format. But because this was a test and we wanted to validate the full output from the beginning, we cleaned the old test folder in Lakehouse and replayed the trail from the start. That is an important point. If you are testing folder or file naming changes and you do not clean the previous output, it can become confusing very quickly. Old files and new files can sit together, and then it becomes hard to tell which setting produced which folder or file.

The way we diagnosed this was also a good reminder. We did not start by changing random properties. First, we confirmed GoldenGate was actually processing data. Then we checked the target Lakehouse. Since files were being created, we knew authentication and basic OneLake writing were working. That narrowed the issue down to path and file naming.

In the end, this was not a GoldenGate failure. It was a configuration alignment issue between GoldenGate’s OneLake handler and the folder structure expected by the Fabric team. The main lesson is: when GoldenGate DAA is writing to Fabric Lakehouse and files are landing in the wrong place, check these two properties first

gg.eventhandler.onelake.pathMappingTemplate and gg.eventhandler.onelake.fileNameMappingTemplate

Small strings inside those templates make a big difference. If the template contains .schema, the folder will contain .schema. If the file name template includes the process name, the file will include the process name. GoldenGate is very literal here.

Once we controlled both the path and file name templates, the output started landing exactly where we wanted it in the Lakehouse, with a much cleaner structure for the downstream team.

Hope It Helped!
Prashant Dixit