# Resource model (/docs/concepts/resource-model)



Resource model [#resource-model]

RawTree contains databases, tables, users, roles, and other database entities.
RawTree Cloud and RawTree BYOC organize access to database clusters through
service organizations and memberships.

Different entities belong to different layers:

| Layer                         | Objects and responsibilities                                                                                      |
| ----------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| RawTree                       | Databases, tables, users, roles, policies, settings profiles, workloads, and resources.                           |
| RawTree Cloud or RawTree BYOC | Organizations, memberships, service accounts, API keys, cluster provisioning, connectors, and workflow schedules. |

The service can create and manage database objects. For example, creating a
database-role API key provisions a database user with the selected roles.
The service owns the credential lifecycle, while RawTree (the database) enforces the grants.

Organizations and members [#organizations-and-members]

An organization groups its members and clusters. A member has the `admin` or
`member` membership level. Organization management requires a signed-in user.
API keys can list their bound organization, but they are not organization members
and return a `null` membership role.

<SnippetTabs label="List organizations" surfaces="[&#x22;API&#x22;, &#x22;CLI&#x22;]">
  <SnippetTab value="API">
    ```bash
    # List organizations for your signed-in user.
    # RAWTREE_SESSION_TOKEN holds your user session token.
    curl -X GET "https://api.rawtree.com/v1/organizations" \
      -H "Authorization: Bearer $RAWTREE_SESSION_TOKEN"
    ```
  </SnippetTab>

  <SnippetTab value="CLI">
    ```bash
    # List organizations for your signed-in user.
    # Use a user session from rtree login.
    rtree organization list --api-url https://api.rawtree.com --json
    ```
  </SnippetTab>
</SnippetTabs>

An organization admin can create clusters and manage members. Members can use
resources that their access permits. See [Manage members](/docs/guides/operate/manage-members).

Clusters [#clusters]

A cluster contains databases and their tables.

<SnippetTabs label="List clusters" surfaces="[&#x22;API&#x22;, &#x22;CLI&#x22;]">
  <SnippetTab value="API">
    ```bash
    # List clusters in team-alpha with your user session token.
    curl -X GET "https://api.rawtree.com/v1/clusters?organization=team-alpha" \
      -H "Authorization: Bearer $RAWTREE_SESSION_TOKEN"
    ```
  </SnippetTab>

  <SnippetTab value="CLI">
    ```bash
    # List clusters in team-alpha with your signed-in user.
    rtree cluster list --org team-alpha --api-url https://api.rawtree.com --json
    ```
  </SnippetTab>
</SnippetTabs>

The `sizes` method of the cluster API returns available replica sizes for provisioning.
Each size reports CPU cores and memory per replica. The API also returns minimum and maximum replica
counts; these values can vary by environment.

<SnippetTabs label="List cluster sizes" surfaces="[&#x22;API&#x22;, &#x22;CLI&#x22;]">
  <SnippetTab value="API">
    ```bash
    # List available replica sizes and replica limits.
    # This endpoint requires a user session or user OAuth token.
    curl -X GET "https://api.rawtree.com/v1/clusters/sizes" \
      -H "Authorization: Bearer $RAWTREE_SESSION_TOKEN"
    ```
  </SnippetTab>

  <SnippetTab value="CLI">
    ```bash
    # List available replica sizes and replica limits.
    # Use a user session from rtree login.
    rtree cluster sizes --api-url https://api.rawtree.com --json
    ```
  </SnippetTab>
</SnippetTabs>

An admin can stop a cluster and resume it later. A confirmed paused cluster
returns `409` with `cluster_paused` for data requests. Cluster management routes
remain available while the cluster is paused.

Databases and tables [#databases-and-tables]

Each cluster has databases. The API key's cluster scope limits which databases
and tables a given API key can reach.

<SnippetTabs label="List databases">
  <SnippetTab value="API">
    ```bash test
    # List databases in the API key's cluster.
    # Use a key with read permission.
    curl -X GET "https://api.rawtree.com/v1/databases" \
      -H "Authorization: Bearer $RAWTREE_API_KEY"
    ```
  </SnippetTab>

  <SnippetTab value="CLI">
    ```bash test
    # List databases in the API key's cluster.
    # Use a key with read permission.
    rtree database list --api-url https://api.rawtree.com --json
    ```
  </SnippetTab>

  <SnippetTab value="SQL">
    ```sql test
    -- List databases visible to the current database user.
    SELECT name
    FROM system.databases
    ORDER BY name;
    ```
  </SnippetTab>
</SnippetTabs>

Aside from user generated databases, RawTree exposes metadata and system telemetry in
the `system` database, which is protected from deletion.

Tables belong to a database. A table's columns and data are available through
the Query API when the key has the required permission.

<SnippetTabs label="List tables">
  <SnippetTab value="API">
    ```bash test
    # List tables in the analytics database.
    curl -X GET "https://api.rawtree.com/v1/tables?database=analytics" \
      -H "Authorization: Bearer $RAWTREE_API_KEY"
    ```
  </SnippetTab>

  <SnippetTab value="CLI">
    ```bash test
    # List tables in the analytics database.
    rtree table list --database analytics --api-url https://api.rawtree.com --json
    ```
  </SnippetTab>

  <SnippetTab value="SQL">
    ```sql test
    -- List tables in the analytics database.
    SELECT name
    FROM system.tables
    WHERE database = 'analytics'
    ORDER BY name;
    ```
  </SnippetTab>
</SnippetTabs>

Bear in mind the read-only API-key database role has `SELECT` grants on `*.*` and can query `system` tables. See
[API reference](/docs/reference/api/databases) and
[Monitor usage](/docs/guides/operate/monitor-usage).

User accounts and service accounts [#user-accounts-and-service-accounts]

A **user account** represents a person. The user signs in to RawTree Cloud or
RawTree BYOC and accesses organizations through their memberships. The dashboard,
CLI user sessions, and user OAuth tokens act on behalf of that person.

A **service account** represents an application, agent, or automated job within
one organization. It uses API keys or
[workload federation](/docs/concepts/access-control#workload-identity-federation)
instead of an interactive sign-in. Organization admins manage these accounts.

A service account's API keys retain their own permissions or database roles.
They remain valid if the person who created them leaves the organization.
Deleting the service account revokes its keys. Personal keys instead depend on
the owner's organization membership.

See [Query identity in the database](/docs/concepts/access-control#query-identity-in-the-database)
for how these credentials map to database users and query logs.

API keys and cluster-scoped objects [#api-keys-and-cluster-scoped-objects]

An API key is bound to an organization and cluster. It can also store a default
database. The key does not grant organization membership or access to cluster
management routes.

<SnippetTabs label="List API keys" surfaces="[&#x22;API&#x22;, &#x22;CLI&#x22;]">
  <SnippetTab value="API">
    ```bash
    # List API keys in the current key's cluster.
    # RAWTREE_API_KEY must hold an admin API key.
    # The response includes key hints, not complete secrets.
    curl -X GET "https://api.rawtree.com/v1/keys" \
      -H "Authorization: Bearer $RAWTREE_API_KEY"
    ```
  </SnippetTab>

  <SnippetTab value="CLI">
    ```bash
    # List API keys in the current key's cluster.
    # RAWTREE_API_KEY must hold an admin API key.
    # The response includes key hints, not complete secrets.
    rtree key list --api-url https://api.rawtree.com --json
    ```
  </SnippetTab>
</SnippetTabs>

Cluster-scoped objects use the organization and cluster as their scope. For
example, connectors and workflows require those values when you list or manage
them. This keeps their resources separate across clusters.

See [API keys](/docs/reference/api/keys), [connectors](/docs/reference/api/connectors),
and [workflows](/docs/reference/api/workflows).

Related [#related]

* [Storage and compute](/docs/concepts/storage-and-compute)
* [Access control](/docs/concepts/access-control)