Starburst Documentation
Starburst Galaxy
  •  Get started
  •  Working with data
  •  Data engineering
  •  Developer tools
  •  Cluster administration
  •  Security and compliance
  •  Troubleshooting
  • Galaxy status
  •  Reference

    • starburst galaxy > reference > expressions > Policy matching expressions

    Policy matching expressions #

    The matching expression is a boolean expression that determines whether the policy is applicable to an entity. Matching expressions are defined using a custom language.

    Parentheses are also supported and can be used to make complex expressions. The following example shows a matching expression that returns true if either the set of tags on an entity includes the tag sales_department or includes tag marketing_department as well as tag sales_liaison:

    HAS_TAG(sales_department) OR (HAS_TAG(marketing_department) AND HAS_TAG(sales_liaison))

    Supported base expressions #

    Base expressions are simple expressions that look exclusively at some piece of data and do not rely on any other expressions for their evaluation. Supported expressions can evaluate tags, user attributes, or the names of entities.

    Here is the full list of supported base expressions:

    Expression Description
    true or false Booleans are acceptable expressions.
    has_tag($TAG_NAME) Test whether $TAG_NAME is associated with an entity. Tags can be associated with one or more catalogs, schemas, tables, views, or columns.
    has_tag($TAG_NAME.*) Test whether parent tag $TAG_NAME (or any tag that starts with $TAG_NAME.) is associated with an entity. $TAG_NAME in this case is considered a parent tag (example pii). Child tag names have the tag name as the prefix and are separated by a period (example pii.email).
    user_attribute_exists('$ATTR') Test whether the user has an attribute that exists entitled $ATTR. Only enabled with SSO integrations.
    See more details here.
    user_has_attribute('$ATTR', '$VAL') Test whether the user has an attribute that exists entitled $ATTR and at least one corresponding value equals $VAL. Only enabled with SSO integrations.
    See more details here.
    catalog_name_matches('$NAME*') Private preview
    Test whether the catalog name matches the given pattern. The scope of the policy must be one or more catalogs, or ALL_CATALOGS.
    See more details here.
    schema_name_matches('$NAME*') Private preview
    Test whether the schema name matches the given pattern. The scope of the policy must be one or more catalogs or schemas, or ALL_CATALOGS.
    See more details here.
    table_name_matches('$NAME*') Private preview
    Test whether the table name matches the given pattern. The scope of the policy at or above the level of a table or ALL_CATALOGS.
    See more details here.

    Compound expressions #

    Compound expressions take in one or more of the above base expressions to create more expressive access control policies. All compound expressions are listed below; any usage of $EXPRESSION can be replaced by any of the base expressions listed above.

    Expression Description Example
    NOT $EXPRESSION Evaluates to true if $EXPRESSION evaluates to false. NOT has a higher precedence than AND and OR. NOT has_tag(pii)
    $EXPRESSION AND $EXPRESSION Evaluates to true if both expressions evaluates to true, false otherwise. AND has a higher precedence than OR. has_tag(pii) AND table_name_matches('foo*')
    $EXPRESSION OR $EXPRESSION Evaluates to true if either expression evaluates to true, false if both are false. has_tag(pii) OR table_name_matches('foo*')

    For compound expressions, it may be useful to use parentheses for clarity and to avoid ambiguity around operator precedence. For example, the following two expressions are equivalent because AND has a higher precedence than OR:

    HAS_TAG(pii.email) OR HAS_TAG(pii.phone) AND HAS_TAG(pii.address)
HAS_TAG(pii.email) OR (HAS_TAG(pii.phone) AND HAS_TAG(pii.address))

    User attribute predicates #

    User attributes can be imported into Galaxy from your identity provider, such as Okta. A total of 7KB in attribute statements is supported. Statements exceeding 7KB may result in attributes being dropped.

    For more information on importing attribute statements from Okta, see Okta SAML setup.

    User attributes in policy expressions #

    User attribute statements as sent from Okta or any other SSO provider can be evaluated as part of a policy expression.

    These expression are supported as part of the policy language:

    • user_attribute_exists('attributeName') evaluates to true when attributeName is sent from your IdP and at least one value corresponding to attributeName is not NULL.
    • user_has_attribute('attributeName', 'attributeValue') evaluates to true when attributeName is sent from your IdP and at least one value corresponding to attributeName equals attributeValue.

    Note that attributeName and attributeValue are placeholders and can be replaced with any values you specify in your IdP. Additionally, strings can be escaped using a backslash \. For example, an expression such as user_attribute_exists('it\'s an example') is valid and matches with the SSO attribute name it's an example.

    User attributes in row filter expressions #

    User attribute statements can also be substituted in row filter expressions automatically on a per user basis. There are two special expressions that allow for this substitution:

    • $USER_ATTRIBUTE('attributeName') replaces the first matching attribute for the name attributeName as sent from your SSO provider. If no values for attributeName are found, NULL is returned.
    • $USER_ATTRIBUTE_LIST('attributeName') replaces the matching attributes for attributeName with a list in the form of (val1, val2, ...)

    The standard convention is to use $USER_ATTRIBUTE('attributeName') when checking for strict equality in the filter expression, and $USER_ATTRIBUTE_LIST('attributeName') when you want to match any value in the list. Note that there is no validation performed on the row filter expression.

    Wildcard name predicates #

    Policy expressions can also support wildcard resource name wildcard matching on catalog, schema, and table names. The name to match is entered as an argument to the matching function. The character * represents the wildcard matching character.

    Predicate supported include:

    • catalog_name_matches('foo*') evaluates to true if the name of the catalog starts with or equals foo.
    • schema_name_matches('*foo') evaluates to true if the name of the schema ends with or equals foo.
    • table_name_matches('foo*') evaluates to true if the name of the table starts with or equals foo.

    Limitations of wildcard name matcher predicates #

    There is a maximum of one wildcard * marker allowed in a wildcard matcher expression.

    When considering catalog or schema visibility, if there is a policy that grants an ALLOW on a privilege and contains a wildcard expression in scope whose predicate operates below the level being checked for visibility, the container entity is considered visible unless there is a corresponding DENY grant on that privilege.

    For example, consider a policy on all catalogs with the predicate table_name_matches('foo*') which grants ALLOW SELECT access to all tables that match. If a role were to query SHOW CATALOGS, Galaxy does not look for tables in those catalogs that match foo*. Galaxy treats all catalogs as visible. Similarly, the statement SHOW SCHEMAS FROM mycatalog shows all schemas in the catalog even if there are no tables in schemas that match foo*.

    The above example only applies to policies that grant ALLOW on a privilege. DENY privilege grants, row filters, or column masks do not affect visibility in this case.