> ## 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.</Warning>

## 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);
```

<AccordionGroup>
  <Accordion title="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>

  <Accordion title="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>

  <Accordion title="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>

  <Accordion title="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>

  <Accordion title="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
    ```
  </Accordion>
</AccordionGroup>

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

<AccordionGroup>
  <Accordion title="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>

  <Accordion title="Unexpected results?">
    * Test individual policy rules in isolation
    * Check fact relationships with targeted role/permission queries
    * Use the policy editor's test feature
  </Accordion>
</AccordionGroup>

***

Need help with queries? [Schedule time with an Oso engineer](https://www.osohq.com/meet-eng) - we're happy to help.