Row and Column AccessEnterprise

Restrict which sources each caller can query and which rows they see, with two annotations on the sources in your data model; where to put them, how to test them, and the reference for each

Access rules decide which sources each caller can query and which rows they see. The caller is whoever sends a query: a person signed in to Credible, or an API key acting as its group, from any surface (workspace chat, Slack, an agent over MCP, a dashboard, a data app or the APIs). Access rules are annotations on sources in the data model, and Credible applies them to every query that goes through the model.

Permissions decide who can reach an environment or package. Access rules work inside a package.

Restrict Who Can Query a Source

Two annotations control access to a source:

  • #(authorize) decides who can query the source. Anyone else is refused.
  • #(access_filter) decides which rows each person sees. Each caller gets only the rows that match them.

Both check the caller's identity, which Credible fills in from how they signed in (see Secure Givens).

In this example, only the support team can query tickets, and each person sees only the tickets for the customers assigned to them:

##! experimental.givens
given:
  #(secure)
  GROUPS :: string[]
  #(secure)
  TENANTS :: string[]

#(authorize) 'support' in $GROUPS
#(access_filter) tenant in $TENANTS
source: tickets is warehouse.table('support.tickets') extend {
  measure: ticket_count is count()
}

A source can have either annotation, both or neither. With both, #(authorize) is checked first, then the filter applies. No query can remove the filter. If an admin needs every row, give them a separate source.

Each annotation sits on its own line directly above the source: line.

Access Rules and Warehouse Controls

  • A rule sits on the source people query. Warehouse controls, such as row access policies in Snowflake or row-level security and policy tags in BigQuery, attach to each physical table and column. An access rule is written on the source a query starts from.
  • Rules are versioned with the model. They are reviewed, published and rolled back with it.
  • Rules are portable. They aren't written in any warehouse's policy syntax, so they keep working if you move to a different warehouse.

Access rules apply only to queries that go through the model. A BI tool or SQL client connected directly to the warehouse bypasses them, so warehouse permissions still govern direct access.

Where to Put Access Rules

Put access rules on the sources your package exports. A rule applies when a query starts from that source. It doesn't follow joins, so if an unrestricted source joins a restricted one, the restricted data can be read through it. Keep unrestricted sources that join restricted ones out of the exports.

Which sources a package exports, and which fields each one shows, is set in the model; see Exports and Field Visibility. A source that everyone who can reach the package may query needs no rule. Create one exported source per access decision.

Different Columns for Different Audiences

Field visibility can't vary by caller, so a column only some callers may see needs two exported sources: one without it, and one with it behind #(authorize). Hide the column with private, not internal, because a query can re-expose an internal field with extend. include blocks need ##! experimental.access_modifiers at the top of the file:

##! experimental.givens
##! experimental.access_modifiers
given:
  #(secure)
  GROUPS :: string[]

#(doc) Orders without the contact and card columns
source: orders is orders_core include {
  private: *
  public: order_id, status, amount, order_count
}

#(doc) Orders with the contact and card columns, for the billing team
#(authorize) 'billing' in $GROUPS
source: orders_billing is orders_core include {
  private: *
  public: order_id, status, amount, customer_email, credit_card_number, order_count
}

Secure Givens

An access rule reads the caller's identity from givens (opens in a new tab): named values a model declares at the top of the file and receives at query time, referenced with $. Access rules must read secure givens, which Credible fills in on the server from the caller's verified identity, ignoring anything the caller sends:

GivenDeclare it asFilled with
$GROUPS (built in)#(secure) then GROUPS :: string[]The names of the caller's groups in Users and Groups. For an API key or a shared workspace's agent, the group it acts as and every group that group belongs to
Custom#(secure) then NAME :: string[]Values you assign per user, group, or everyone on the Access Control page

A custom secure given must be set-valued (string[]) and read with in. A scalar secure given is not enforced.

Write access rules only on secure givens. Every other given is supplied by the caller, who can send any value and pass the rule. Use ordinary givens for parameterizing a query, never for access.

Assigning Values to a Custom Given

Values live in a lookup table on the Access Control page, not in the model. Each row grants a user (by email), a group, or everyone a list of values: the data values your rule compares against, such as tenant values. A custom given appears on that page after a published model declares it #(secure) as a string[].

At query time, Credible resolves the caller's email and groups and merges every applicable row into one set. For example, grant the support group ["acme"] and alice@yourco.com ["globex"]: Alice, a support member, sees both tenants, and her teammates see only acme. A caller with no applicable row is refused with a 403 that names the given, for every query on a model that declares it, even one that never reads it in a rule. A row that grants an empty list is a value: that caller is admitted and matches no rows. Changes to assignments take effect without republishing.

Values on the Access Control page apply to people who sign in. An API key and a shared workspace's agent act as a group, and a group never has values for a custom secure given. So a model that declares a custom secure given refuses every query from an API key or a shared workspace's agent, even if that query never reaches the restricted source. Keep sources those callers need in a model that declares only $GROUPS, and scope them with groups: an embedded product scopes each tenant with one group and key per tenant. See Tenant Isolation for Embedded Products.

Filtering on $GROUPS

$GROUPS values are group names, matched exactly, including case: a group named West doesn't match a west value. To filter rows by region, create a group per region (west, east, …), add users to their regions, and write #(access_filter) region in $GROUPS.

The agent in a person's own workspace, and an agent or client connected over MCP, gets exactly that person's access. The agent in a shared workspace, in the app, in Slack or on a schedule, runs with the workspace group's access under the person's identity: $GROUPS holds the workspace's group and the groups it belongs to, not the person's own groups. If you need identity resolved from something other than email, contact us.

Add Access Rules to a Package

Before you start, decide which sources your package exports (see Exports and Field Visibility) and where each caller's identity comes from: groups for $GROUPS, or a custom secure given whose values an organization admin assigns.

Pick a domain

Choose a set of questions that share one access rule, such as support metrics that each team may see only for its own customers.

Build the layers

Write the sources these questions build on, with each table's business fields public and its raw columns private.

Add the domain and export it

include only the fields the domain should expose, and export it from index.malloy.

Write the access rule

Declare the secure givens under ##! experimental.givens, and add #(authorize) and #(access_filter) above the domain. Test it locally first; see Test Access Rules.

Publish

Publish the package. A malformed access rule fails the publish.

Assign values

For a custom secure given, an organization admin assigns values to users, groups or everyone on the Access Control page. The attribute appears there after the published model declares it.

Test as real callers

Query as a caller outside the group, then as one inside it with a narrower grant. Check that the first is refused and the second gets only their rows. See Responses.

Test Access Rules

Access rules can only be written in the model; a rule in caller-submitted Malloy is rejected.

In Credible, secure givens always come from the identity of whoever runs the query, in a draft as well as a published package. Values you send for a secure given, through a report's Givens panel or the givens request parameter, are dropped and replaced. So in a Credible draft you can only test the rule as yourself.

To test as other callers before you publish, run the package locally. Publisher running on your machine trusts the givens you send, so you can supply GROUPS or a custom given and simulate any identity. After you publish, test as real callers: a user outside the group, a user inside it with a narrower grant, and an API key if one will query the source.

The #(authorize) Annotation

#(authorize) is a rule about the caller: it compares a quoted literal against a given and never reads a column.

##! experimental.givens
given:
  #(secure)
  GROUPS :: string[]

#(authorize) 'finance' in $GROUPS
source: margins is margins_core extend {
  measure: total_margin is sum(margin)
}

It can read any secure given, not just $GROUPS. For example, #(authorize) 'acme' in $TENANTS admits only callers whose assigned tenants include acme, so you can grant access to individuals without putting emails in the model.

  • #(authorize) false admits nobody. Use it on a base source that only its extensions should expose, each with a rule of its own. Keep a source nobody should query out of the exports instead.
  • #(authorize) true removes an #(authorize) rule inherited through extend. On a source with nothing to inherit it changes nothing and marks the source as open on purpose. It's refused beside another #(authorize) line, and it can't remove the rule from a source built by querying another source (->), which always keeps its base's rules.
  • Refused callers still see the source in their agent's context, and are refused if they query it. Its column values stay out of search for every caller, as described in Value Search and Materialization.
  • Comparison is exact and ignores your warehouse's collation: 'Finance' doesn't match ["finance"].
  • Refused callers can't compile against the source, so an author outside the group can't compile-check it.

The #(access_filter) Annotation

#(access_filter) is a rule about the row: it compares a column of the source against a given. Every caller who passes #(authorize) can query the source and sees only the rows their givens cover. Here cost_center is a column of the source:

##! experimental.givens
given:
  #(secure)
  GROUPS :: string[]

#(access_filter) cost_center in $GROUPS
source: margins_by_cost_center is margins_core extend {
  measure: total_margin is sum(margin)
}
  • A caller with no matching rows gets zero rows. To refuse a caller outright, use #(authorize). #(access_filter) false is refused at publish in favor of #(authorize) false.
  • Use it instead of a where: over a secure given. The filter is reported as the source's accessFilter in introspection, and it still applies when a derived source projects the filtered column away.
  • It can read through a join_one: #(access_filter) account.tenant_slug in $TENANTS. Paths through join_many or join_cross are refused, because the filter would multiply rows. Parent rows with no match have a null in the joined column, so they're dropped, as in an inner join.
  • Compiling isn't filtered. A caller who passes #(authorize) can compile against the source, and the SQL returned with includeSql doesn't include the filter's where:. The filter is applied when the query runs.
  • Rows are protected, not the schema. Callers who can query the source still see its fields and descriptions. If a column's existence is sensitive, put it in its own restricted source.
  • Dropping the filtered column refuses the query. If a derived source removes the column (except:, or an accept: that omits it), queries are refused rather than served unfiltered. A source that declares the filter fails to publish; one that inherits it publishes with a warning and refuses every query. Renaming a different column onto a dropped filtered column's name is refused too.

What an Access Rule May Say

An access rule is one or more terms joined by and. The term's shape decides which annotation it belongs on:

AnnotationTerm shapeExample
#(authorize)'literal' in $GIVEN'support' in $GROUPS
#(access_filter)column in $GIVENtenant in $TENANTS and region in $REGIONS
  • Repeating an annotation adds terms with and. Two #(access_filter) lines on one source are the same as one line joining both terms. Repeats combine only with the same annotation, never across the two.
  • The given's type fixes the operator: in for string[], = for a scalar. Access rules use in, since only set-valued secure givens are enforced.
  • A term on the wrong annotation is refused, and the error names the right one.
  • Every referenced given must resolve: declared in the rule's model or one import away.
  • No referenced given may have a default, and don't re-declare a base's givens in a model that imports its restricted sources.

Refused at load: or, not, !=, <, >, <=, >=, function calls such as upper(region), bare boolean dimensions, terms with no given (such as region = 'us-west'), and two terms naming the same given or the same column. Because there is no or, a rule that needs a choice between two conditions belongs in a boolean column the filter reads.

How Access Rules Apply to Extended and Joined Sources

An access rule is checked on the source a query starts from, never on a source joined in the model. A join the caller writes in a query is checked as if the caller queried that source.

If you build a source by…Its access rules
Extending another source (extend), or giving it a new nameKeeps the original's rules. A rule you add replaces the original rule of the same kind: #(authorize) replaces #(authorize), and #(access_filter) replaces #(access_filter).
Querying another source (source: x is margins -> { … })Always keeps the original's rules. Rules you add apply on top, so a caller has to pass both.
Joining another source into itNothing carries over through the join. Only the new source's own rules apply, which is why sources that join restricted ones shouldn't be exported.
Combining sources into a composite sourceUses the rules of whichever member source Malloy picks for the query, together with any rules on the composite source itself.
##! experimental.givens
given:
  #(secure)
  GROUPS :: string[]

#(authorize) 'finance' in $GROUPS
source: margins is margins_core extend {
  measure: total_margin is sum(margin)
}

source: margins_by_region is margins extend {
  dimension: region is upper(sales_region)
}

#(authorize) 'exec' in $GROUPS
source: margins_exec is margins extend {}

source: orders is orders_core extend {
  join_one: margins on product_id = margins.product_id
}

In this example:

  • margins_by_region keeps the finance rule, so only finance can query it.
  • margins_exec replaces the finance rule with its own, so only exec can query it.
  • orders has no rule. Anyone who can query orders can read total_margin through the join, so keep orders out of the exports or give it a rule of its own.

When a query collects rules from several sources, the caller has to pass every one.

Where the Annotation May Sit

PlacementValid?Effect
Above a standalone source:✅Applies to that source
On an item in a multi-definition source: block✅Applies to that item only
Above the source: keyword of a multi-definition block✅Applies to every item in the block
On a dimension:, measure:, join, or view: line❌Refused at load. Put sensitive fields in their own source
On a top-level query:❌Refused at load. Put the rule on the source the query reads
File level, ##(authorize)❌Refused at load. Put a rule on each source instead

Spell the tag exactly #(authorize) or #(access_filter). Variants such as #(AUTHORIZE), #authorize, #(access-filter), or extra spaces are refused at load, with the fix named.

Value Search and Materialization

Value search is off on most access-controlled sources. The search index is shared across callers, so values are withheld for everyone on a source that carries:

  • #(authorize), or an #(access_filter) that does more than compare columns with = to single-value givens
  • a #(secure) given, or $GROUPS
  • a given whose name any source in your organization declared #(secure), since that name is reserved organization-wide

A source whose only rule is an #(access_filter) comparing columns with = to ordinary single-value givens keeps value search, indexed per value.

Callers who can query the source still see it in get_context and can query the column with execute_query. To keep value search for a column, put it on an unrestricted source and restrict a sensitive companion source separately.

Materialization with #@ persist works on a source that reads an unrestricted source and declares its own #(access_filter), or whose rule is an #(authorize) (its own or inherited), whether the table is colocated in your warehouse or built with storage=. One table holds every caller's rows, and the rule is applied again each time the table is read, so each caller gets the same rows, or the same refusal, as a live query. Two consequences:

  • The rows are only as fresh as the last build. A row whose access decision changed, for example a record that moved to another tenant, is served under the old decision until the source is rebuilt.
  • A storage= table holds every caller's rows, unfiltered, in its destination. The rule holds only for queries through Credible; anyone with direct access to the destination can read all of them.

A materialized source built from a source that has an #(access_filter) is never built, even when it declares its own filter. Without its own #(access_filter), every caller is refused; with one, its queries are answered live. To persist it, build it from an unrestricted source and declare the #(access_filter) on the materialized source, as revenue_by_month does in The Data Model.

These are also not built or not used, and their queries are answered live:

  • a rule reached only through a join
  • a restricted source whose build would have to fill in a given
  • a #@ preaggregate pre-aggregate over a restricted source, which is never read in place of it

See Materialization and Performance.

Parameterization

Ordinary givens are also how a source exposes a per-query parameter, replacing the legacy #(filter) annotation. A presentation filter becomes a filter<string> given whose default f'' matches every row:

##! experimental.givens
given:
  manufacturer :: filter<string> is f''

source: recalls is warehouse.table('recalls') extend {
  where: manufacturer_name ~ $manufacturer
}

Callers supply values in the givens request parameter. The older filterParams parameter is deprecated.

#(filter) is deprecated. Don't add one to a model. Each case has a given: form:

  • #(filter, required) becomes a given with no default.
  • implicit filters are row-level security. Replace them with #(access_filter) over a #(secure) given, not an ordinary given.
  • Date and number ranges become a filter<date> or filter<number> given.

Responses

ResponseMeaning
404The package doesn't export the source.
403The caller was refused: #(authorize) didn't admit them, an access rule couldn't be applied, or the model declares a custom secure given the caller has no value for. Only the last says why, naming the given. Refusals are recorded like any other query; see Control Access and Monitoring.
200The caller gets only their rows, which can be zero rows.

A refused caller gets an error rather than an empty result, because an empty aggregate is a wrong answer: under a where: false, sum(salary) returns a row of NULL and count() returns 0, which reads like missing data.

When something goes wrong, Credible refuses the query rather than returning unfiltered data. An access rule that can't be applied at query time refuses the query, and a malformed access rule fails to publish.

Next Steps

On this page