Snowflake-managed Apache Iceberg tables can be read and written by outside engines through Snowflake Horizon Catalog's Iceberg REST Catalog (IRC) endpoint. On its own, that raises an obvious governance question: if the engine reads Parquet files directly from storage, what happens to the masking policy on your email column?

The answer is that the policies travel with the data. When a table carries policies that apply to the caller, Snowflake stops handing out storage credentials and instead plans the scan server-side, materializing a masked and filtered result before the engine reads anything. When the policies do not apply to the caller, the engine gets credentials and can write as normal. Either way, every operation is audited, and the audit record names the policies that were evaluated.

This guide has you build that end to end: two governed Iceberg tables, two roles, an Apache Spark session that speaks nothing but Iceberg REST, and the audit query that proves enforcement happened.

Everything here works over the open protocol. There is no Snowflake-specific client, driver, or connector anywhere in the engine configuration.

Two Snowflake-managed Iceberg tables, each carrying a different kind of policy, queried and written by a plain Spark session over Iceberg REST — once as a role the policies exempt, and once as a role they apply to, so you can see enforcement happen and then find it in the audit trail.

Create a database, a warehouse, and two roles. FULL_ROLE will be exempt from both policies; RESTRICTED_ROLE will not.

Grant both roles what they need. Scan planning runs on a warehouse, so the querying role must be able to use one — this is a common source of confusing failures later.

Now create the first Iceberg table with a masking policy on its email column. These are Snowflake-managed Iceberg tables: EXTERNAL_VOLUME = 'SNOWFLAKE_MANAGED' is a keyword rather than the name of a volume you have to create, and there is no BASE_LOCATION — Snowflake chooses the layout.

Then a second table with a row access policy instead, so you can see both policy kinds behave identically from the engine's point of view.

USER_INFO is the table you will write to, and a write over Iceberg REST needs the whole DML set — SELECT, INSERT, UPDATE, DELETE and TRUNCATE. TRUNCATE is the one most often left out, because nothing in this guide truncates anything and a Snowflake MERGE does not require it. Omit it and the engine's commit fails on a privilege check that names none of the statements you actually ran.

Note that RESTRICTED_ROLE is granted the full write set as well. That is deliberate — later you will see Snowflake refuse its writes anyway, because the decision is made on policy applicability, not on the SQL grant. Getting the grants right first is what makes that later refusal meaningful: with a privilege missing, both roles fail and you learn nothing.

The engine authenticates with a programmatic access token bound to a single role. Create a service user for each role.

Now generate the two tokens. A programmatic access token is displayed exactly once, when it is created, and cannot be retrieved afterwards. Open somewhere to keep them — a password manager, or a scratch buffer you will clear — before you run the next statement. If you lose a token, your only option is to remove it and add a new one.

Create the first token and copy the token_secret value from the result:

With that one saved, create the second and copy it too:

Label them as you paste — the two tokens are indistinguishable by eye, and swapping them produces a confusing result rather than an error, because both are valid credentials for different roles.

Point a standard Iceberg REST catalog at Horizon. The catalog URI is your account URL plus the Horizon IRC path, and the warehouse property is the Snowflake database name.

There is no fallback catalog, no JDBC URL, and no Snowflake connector. Every step that follows runs through that one catalog handle.

iceberg-aws-bundle is what lets Iceberg use the credentials Snowflake vends. Without it the first read fails with Failed to get file system for path: s3://…, which looks like a storage problem but is a missing client library. On Azure, substitute iceberg-azure-bundle.

Run this in a notebook or a pyspark shell, where PySpark starts the JVM and resolves spark.jars.packages for you. Under spark-submit the JVM is already running by the time the builder executes, so the same two packages have to go on the command line instead:

The remaining steps assume a persistent session, in Spark and in Snowflake alike. Keep one Snowflake worksheet for the SQL, because each block builds on the database, schema and role the preceding blocks set.

Reads always work on a governed table. What changes is what comes back.

Run the same query as each role, changing only SESSION_ROLE and PAT_TOKEN in the preceding configuration.

As FULL_ROLE, three rows come back with email addresses in the clear. As RESTRICTED_ROLE, the same three rows come back with usernames untouched and every email reading ****@****.***. Masking is column-level, so only the sensitive values change.

The row access policy removes rows rather than altering values.

FULL_ROLE gets 5. RESTRICTED_ROLE gets 3. Those two rows are not filtered on the client — they never leave Snowflake, and Spark has no way to know they exist.

When the policies apply to the caller, the loadTable response contains no storage credentials. Instead it signals that the scan will be planned server-side:

The engine then submits its filters and column projection as a scan plan. Snowflake evaluates the policies for the calling role, runs the query on your warehouse, materializes the masked and filtered result as temporary Iceberg files, and returns a plan plus credentials scoped to those temporary files only. The engine reads already-governed Parquet and never touches the underlying table files.

Horizon plans asynchronously: it answers a submission with a plan id, and the client polls until the plan is ready. Spark 3.5 with Iceberg 1.11.0 or later does this. Clients that do not poll will stall on the first governed read even though they otherwise implement the scan API.

A policy does not make a table read-only to the outside world. Snowflake asks a sharper question than "does this table have a policy?" — it asks whether the policy would change anything for the role that is asking.

As FULL_ROLE, which both policies exempt, a write behaves like a write to any ordinary table.

That commits, producing a new snapshot Snowflake sees immediately. Appends, updates and deletes behave the same.

Run the identical statement as RESTRICTED_ROLE and it fails. Confirm in Snowflake that nothing changed:

Check the table contents rather than trusting the absence of an error, because "the write failed" and "the write silently stored masked values" look identical from the client side.

The refusal arrives at one of two places, depending on the statement, and the two look nothing like each other:

The message names a column you did not remove, which is why it reads as a schema bug rather than the governance decision it is. What matters is where it happens: the plan is refused, so no file is written and nothing is read. A MERGE reads existing rows to decide what to change, so a client that could read masked values and write them back would overwrite real email addresses with ****@****.***. That cannot happen, because the plan is refused before the read.

This is the case that matters most for safety.

The wording points at credential expiry, and the underlying reason is not visible from the client. What is observable is the outcome: no snapshot is committed and the table is unchanged. Be aware, though, that an append is not stopped as early as a MERGE is - it is refused at storage rather than at planning, so data files may be written and abandoned.

Two further properties are worth understanding:

Every catalog operation an external engine performs lands in ACCESS_HISTORY alongside Snowflake's own SQL records. Filter on EVENT_SOURCE = 'horizon_irc' to isolate them.

Two things are specific to governed tables. First, the scan-planning handshake is audited in its own right: a governed read produces PlanTableScan when the engine submits its plan and FetchPlanningResult when it collects the answer, alongside the ordinary LoadTable. Second, and more useful, the POLICIES_REFERENCED column names which policies were evaluated, down to the column:

A masking policy nests under the column it protects. A row access policy has no column to attach to, so it sits at the table level instead — this is what the REGIONS read records:

Each payload also carries numeric objectId, columnId and policyId fields, omitted here for readability. Because the two policy kinds land in different places, a query that reads only one of them silently misses the other. Flatten both to answer the question an auditor actually asks — was the mask applied when that engine read the table?

Each read of USER_INFO names MASK_EMAIL against the EMAIL column, and each read of REGIONS names RAP_PUBLIC_ONLY at the table level. A table with masks on two columns produces one row per masked column.

One caveat matters for control design: only successful operations are logged. The write that Snowflake refused leaves no row at all. Enforcement is real but the refusal is invisible here, so do not build a detection that looks for denied writes in this view.

ACCESS_HISTORY requires Enterprise Edition or higher, and records are retained for 365 days.

One timing note before you run the query: ACCESS_HISTORY is not real time. Records can take up to about three hours to appear, so an empty result immediately after the Spark reads means the view has not caught up yet — not that enforcement failed. Wait and re-run.

Four failure modes look like infrastructure problems and are not.

When a policy applies to your writing role, an INSERT fails at the storage step with The provided token has expired from your cloud provider. Nothing in that message mentions Snowflake, masking, or governance, and the wording sends you after the wrong thing: reissuing the token does not help. Forgetting to exempt the writing role is the most likely misconfiguration, and it presents as a credential-rotation problem that does not exist.

A MERGE, UPDATE or DELETE fails earlier, with Invalid select field: '_file' does not exist in the table schema. The column is not missing from your table - this is what a refused row-level write looks like on a governed table. Read it as a governance decision, not a schema problem.

For either error, check the policies attached to the table and whether they are no-ops for your role before investigating cloud permissions:

Scan planning evaluates policies and materializes results on a warehouse, so the calling role needs a usable default warehouse. Without one, plan submission fails and the error does not point at compute. Confirm the service user has a default warehouse and the role has USAGE on it.

If your client implements the scan API but hangs or errors on the first governed read, check whether it polls for asynchronous plans. Horizon returns a plan id and expects the client to poll. A client that treats the submission response as final will never collect the result.

An engine speaking nothing but Iceberg REST queried tables carrying masking and row access policies and received already-governed data, without knowing anything about Snowflake's policy language. Where those policies did not apply to it, it wrote to the same tables. Every operation left an audit record naming the policies evaluated.

Governed no longer means cordoned off. The rules travel with the data in both directions, and the table stays a first-class citizen of your lakehouse either way.

To clean up: