Policy Preview

This feature is currently in beta and requires enablement. Contact us on Slack to get access.

Policy Preview Overview (Growth Plan)

Policy Preview is a beta CL feature that benchmarks query performance for a candidate policy — a new or modified policy you’re testing — and compares it to your current production policy. Use this tool to test policy changes during development or enforce performance checks in CI pipelines.

Requirements

Growth plan subscription
Oso Cloud CLI, version >= 0.35.1
A candidate policy to compare against your deployed policy
A list of queries to benchmark

Quick Start

Create a query manifest (e.g. queries.yaml)

A YAML file that defines queries to preview. See Query Manifest Reference for details.

# Example
queries:
  - name: "Admins can read repos"
    query_type: authorize
    actor_type: User
    actor_id: alice
    action: read
    resource_type: Repository
    resource_id: backend-repo

  - name: "List of repos Alice can read"
    query_type: list
    actor_type: User
    actor_id: alice
    action: read
    resource_type: Repository

Create a candidate policy with your proposed changes You can use a single .polar file (e.g. candidate.polar) or multiple .polar files (e.g. policies/*.polar).
Run the preview

oso-cloud experimental policy-preview --queries queries.yaml policies/*.polar

This command runs all queries against both your production and candidate policies, then displays a side-by-side performance comparison.

Configure Policy Preview options

You can configure thresholds that mark queries as failed when exceeded, adjust the timeout setting for individual queries, or toggle on cache state views:

Flag	Description
`-f,` `--fail-on-regression-percent`	Fail if any query is slower by this percentage (e.g., `20` for 20%)
`-i,` `--ignore-changes-under-ms`	Ignore regressions smaller than this threshold in milliseconds (e.g., `10`)
`--max-duration-ms`	Fail if any query exceeds this absolute duration in milliseconds (e.g., `750`)
`--max-regression-ms`	Fail if any query slows down by more than this many milliseconds (e.g., `200`)
`--query-timeout-ms`	Set maximum time to wait for any individual query (default: `1000` ms)

Queries that exceed thresholds appear as failed in the terminal output and cause the command to exit with code 1.

Query Manifest Reference

The manifest file defines the queries to execute during policy preview. It supports the following query types:

The query structure is similar to the HTTP API, with two additional required fields: name and query_type.

Manifest Structure

queries:
  - name: "Query name"
    query_type: <type>
    # Additional fields depend on query type

Query Types

Authorize Query

- name: <String> (must be unique)
  query_type: authorize
  actor_type: <String>
  actor_id: <String>
  action: <String>
  resource_type: <String>
  resource_id: <String>

List Query

- name: <String> (unique)
  query_type: list
  actor_type: <String>
  actor_id: <String>
  action: <String>
  resource_type: <String>

Actions Query

- name: <String> (unique)
  query_type: actions
  actor_type: <String>
  actor_id: <String>
  resource_type: <String>
  resource_id: <String>

Evaluate Query

- name: <String>
  query_type: evaluate_query
  predicate: [<String>]
  calls:
    - [<String>]
  constraints:
    <String>:
      type: <String>
      ids: [<String>]
    <String>:
      type: <String>

Required fields:

predicate: Array where first element is predicate name, the rest are variable names
constraints: Map of variable names to constraint definitions
- type: Entity type for the variable
- ids (optional): List of IDs to test
All variables in predicate or calls must be defined in constraints

Optional fields:

calls: Array of predicate calls formatted like predicate

Best Practices

Create Representative Query Sets

Include queries that represent:

Common authorization paths
Edge cases
Performance-critical queries
Recently changed policy rules

Troubleshooting

”Feature not enabled” error

Policy Preview must be enabled. Contact us on Slack to gain access.

YAML parsing errors

Check your manifest structure. Common issues include:

Missing required fields
Incorrect indentation
Unknown fields

Get Started

Develop

Deploy and Manage

Policy Preview Overview (Growth Plan)

Requirements

Quick Start

Query Manifest Reference

Manifest Structure

Query Types

Authorize Query

List Query

Actions Query

Evaluate Query

Best Practices

Create Representative Query Sets

Troubleshooting

”Feature not enabled” error

YAML parsing errors

​Policy Preview Overview (Growth Plan)

​Requirements

​Quick Start

​Query Manifest Reference

​Manifest Structure

​Query Types

​Authorize Query

​List Query

​Actions Query

​Evaluate Query

​Best Practices

​Create Representative Query Sets

​Troubleshooting

​”Feature not enabled” error

​YAML parsing errors

Policy Preview Overview (Growth Plan)

Requirements

Quick Start

Query Manifest Reference

Manifest Structure

Query Types

Authorize Query

List Query

Actions Query

Evaluate Query

Best Practices

Create Representative Query Sets

Troubleshooting

”Feature not enabled” error

YAML parsing errors