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

TypeFormatExampleDescription
Exact valueType:valueUser:aliceMatch this value exactly
Type wildcardType:_User:_Match any value of this type
Universal wildcard__Match any value of any type

​
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: 
actor User {}
resource Organization {}

has_permission(user: User, "view", org: Organization) if
  has_role(user, "member", org);

oso-cloud query has_permission User:alice String:view Organization:acme
Returns a matching fact or (no results).
oso-cloud query has_permission User:_ String:view Organization:acme
Use User:_ to match any user. Returns all users who can view the organization.
oso-cloud query has_permission User:alice String:_ Organization:acme
Returns all permissions the user has on the organization.
oso-cloud query has_permission User:alice view _
The wildcard _ matches any resource type, not just organizations.
Global rules apply across the system and are not tied to specific resources.
# Find global admins
oso-cloud query has_role User:_ admin

# Check global permission
oso-cloud query has_permission User:alice edit

​
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:
oso-cloud query has_permission User:alice String:view Organization:acme
Makes Oso Cloud check if this policy rule applies: 
has_permission(user: User, "view", org: Organization) if
  has_role(user, "member", org);
Oso Cloud binds alice to user and acme to org, then searches for: 
has_role(User:alice, "member", Organization:acme)
If this fact exists, Oso Cloud returns: 
has_permission User:alice view Organization:acme
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.