> ## Documentation Index
> Fetch the complete documentation index at: https://www.osohq.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Query Oso Cloud

> Use queries to determine which users have specific permissions, which resources a user can access, or to debug authorization issues.

## 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

| Type | Format | Example | Description |
| - | - | - | - |
| **Exact value** | `Type:value` | `User:alice` | Match this value exactly |
| **Type wildcard** | `Type:_` | `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`

> [!WARNING]
>
> **Important**: Type constraints match exactly. Subclasses don't match parent types, even with Polar's `extends` feature.

## Common Query Patterns

Example policy:

```polar theme={null}
actor User {}
resource Organization {}

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

> [accordion] Check if a user has permission
>
> ```sh theme={null}
> oso-cloud query has_permission User:alice String:view Organization:acme
> ```
>
> Returns a matching fact or `(no results)`.

> [accordion] Find all users with a permission
>
> ```sh theme={null}
> oso-cloud query has_permission User:_ String:view Organization:acme
> ```
>
> Use `User:_` to match any user. Returns all users who can view the organization.

> [accordion] List a user's permissions
>
> ```sh theme={null}
> oso-cloud query has_permission User:alice String:_ Organization:acme
> ```
>
> Returns all permissions the user has on the organization.

> [accordion] Find all resources a user can access
>
> ```sh theme={null}
> oso-cloud query has_permission User:alice view _
> ```
>
> The wildcard `_` matches any resource type, not just organizations.

> [accordion] Global rules
>
> Global rules apply across the system and are not tied to specific resources.
>
> ```sh theme={null}
> # 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:

```sh theme={null}
oso-cloud query has_permission User:alice String:view Organization:acme
```

Makes Oso Cloud check if this policy rule applies:

```polar theme={null}
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

> [accordion] No results returned?
>
> * Check that your facts exist with `oso-cloud facts list`
> * Verify policy syntax with `oso-cloud policy validate`
> * Use wildcards to broaden your search

> [accordion] Unexpected results?
>
> * 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](https://www.osohq.com/meet-eng) - we're happy to help.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.