# roles

## Description

Exposes metadata about roles defined in the organization. Only roles on which the current role has USAGE privileges are returned. The `granted_to` and `granted_roles` fields are JSON arrays showing the role hierarchy.

## Syntax

```sql
SELECT * FROM deltastream.sys."roles";
```

## Columns

| Column                    | Type           | Nullable | Description                                                         |
| ------------------------- | -------------- | -------- | ------------------------------------------------------------------- |
| `name`                    | VARCHAR        | No       | Name of the role.                                                   |
| `owner`                   | VARCHAR        | No       | The role that owns this resource.                                   |
| `granted_to`              | VARCHAR        | Yes      | JSON array of role names this role has been granted to.             |
| `granted_roles`           | VARCHAR        | Yes      | JSON array of role names that have been granted to this role.       |
| `member_count`            | INTEGER        | No       | Number of users who are members of this role.                       |
| `created_by_role`         | VARCHAR        | No       | The role that created this resource.                                |
| `created_by_role_deleted` | BOOLEAN        | No       | Whether the creating role has since been deleted.                   |
| `created_by`              | VARCHAR        | No       | The user that created this resource.                                |
| `created_at`              | TIMESTAMP\_LTZ | No       | Timestamp when this resource was created.                           |
| `updated_by_role`         | VARCHAR        | No       | The role that last updated this resource.                           |
| `updated_by_role_deleted` | BOOLEAN        | No       | Whether the last updating role has since been deleted.              |
| `updated_by`              | VARCHAR        | No       | The user that last updated this resource.                           |
| `updated_at`              | TIMESTAMP\_LTZ | No       | Timestamp when this resource was last updated.                      |
| `organization_id`         | VARCHAR        | No       | The unique identifier of the organization this resource belongs to. |

## Examples

List all roles:

```sql
SELECT * FROM deltastream.sys."roles";
```

```sh
[{"name":"public","owner":"","granted_to":null,"granted_roles":null,"member_count":0,"created_by_role":"n/a","created_by_role_deleted":false,"created_by":"n/a","created_at":"2025-05-22T23:21:22.962Z","updated_by_role":"n/a","updated_by_role_deleted":false,"updated_by":"n/a","updated_at":"2025-05-22T23:21:22.962Z","organization_id":"00000000-0000-0000-0000-000000000001"},{"name":"sysadmin","owner":"orgadmin","granted_to":"[\"orgadmin\"]","granted_roles":"[\"abc\", \"def\"]","member_count":2,"created_by_role":"sysadmin","created_by_role_deleted":false,"created_by":"user@example.com","created_at":"2025-05-22T23:21:22.962Z","updated_by_role":"orgadmin","updated_by_role_deleted":false,"updated_by":"user@example.com","updated_at":"2026-02-02T13:14:53.038Z","organization_id":"00000000-0000-0000-0000-000000000001"}]
```

## See Also

* [System Tables Overview](https://docs.deltastream.io/reference/sql-syntax/systables)
* [LIST ROLES](https://docs.deltastream.io/reference/sql-syntax/command/list-roles)
* [CREATE ROLE](https://docs.deltastream.io/reference/sql-syntax/ddl/create-role)
* [role\_privileges](https://docs.deltastream.io/reference/sql-syntax/systables/role-privileges)