Skip to main content

​
Query Structure

A query has two parts:
  1. Predicate: the rule name from your policy (e.g., has_permission).
  2. Constraints: values to match, or wildcards (_).
Oso Cloud only evaluates rules that have the same number of parameters as your constraints.

​
Constraint Types

​
Default types in CLI

When you omit the type in CLI queries, Oso Cloud assumes String:
  • view becomes String:view
  • admin becomes String:admin
Important: Type constraints match exactly. Subclasses don’t match parent types, even with Polar’s extends feature.

​
Common Query Patterns

Example policy:
Returns a matching fact or (no results).
Use User:_ to match any user. Returns all users who can view the organization.
Returns all permissions the user has on the organization.
The wildcard _ matches any resource type, not just organizations.
Global rules apply across the system and are not tied to specific resources.

​
How Query Results Work

Oso Cloud returns facts that satisfy your query constraints. Facts come from:
  • Literal facts – Defined directly in policies or added via the API.
  • Inferred facts – Derived by evaluating policies. For example, this query:
Makes Oso Cloud check if this policy rule applies:
Oso Cloud binds alice to user and acme to org, then searches for:
If this fact exists, Oso Cloud returns:
This demonstrates role-based access control (RBAC) - permissions granted through role membership.

​
Queries vs Other APIs

Queries form the basis for all Oso Cloud APIs:
  • authorize queries the allow predicate with your parameters.
  • list queries with wildcards to find accessible resources.
  • bulk-authorize runs multiple authorization queries.
Use direct queries for debugging, bulk operations, and custom checks.

​
Environment Scope

Each query runs against a single environment containing:
  • Your Polar policies (authorization logic)
  • Your facts (users, roles, and relationships)
Cross-environment queries are not supported.

​
Troubleshooting

  • Check that your facts exist with oso-cloud facts list
  • Verify policy syntax with oso-cloud policy validate
  • Use wildcards to broaden your search
  • Test individual policy rules in isolation
  • Check fact relationships with targeted role/permission queries
  • Use the policy editor’s test feature
Need help with queries? Schedule time with an Oso engineer - we’re happy to help.