Row-Level Access Control

Row-Level Access Control is currently in beta. Contact your customer success manager for a private preview.

Row-Level Access Control allows you to restrict access to a subset of rows within a table for specific entities (users, groups, or tokens). This provides more granular control than traditional table-level permissions.

Row-Level Access Control builds upon StarTree’s Role-Based Access Control (RBAC) system. Ensure you have RBAC enabled before implementing row-level policies.

How Row-Level Access Control Works

Unlike table-level RBAC which provides all-or-nothing access to a table, Row-Level Access Control allows you to define conditions that determine which rows a user can access within a table. When a user with row-level policies queries a table, StarTree automatically:

Identifies the user’s assigned roles and associated row-level policies
Extracts the row filter conditions from the policies
Applies these conditions as additional WHERE clauses to the query
Returns only the rows that match both the original query and the row filter conditions

Policy Configuration

Row-level policies use the same structure as standard RBAC policies but include a conditions section with rowFilters:

{
  "version": "v1",
  "statements": [
    {
      "description": "Allow access to specific user data only",
      "resources": ["srn2:cluster#pinot:table#pageviews"],
      "effect": "allow",
      "actions": ["query"],
      "conditions": {
        "rowFilters": ["user_id = 18314973"]
      }
    }
  ]
}

Row Filter Syntax

Single Condition Filters

Row filters are valid SQL expressions that can be used in WHERE clauses:

{
  "conditions": {
    "rowFilters": ["user_id = 12345"]
  }
}

{
  "conditions": {
    "rowFilters": ["region = 'US'"]
  }
}

Multi-Condition Filters

Combine multiple conditions using SQL operators:

{
  "conditions": {
    "rowFilters": ["user_id = 18314973 AND session_value > 1000"]
  }
}

{
  "conditions": {
    "rowFilters": ["user_id IN (18314973, 18314974, 18314975) AND total_time_spent >= 10000"]
  }
}

{
  "conditions": {
    "rowFilters": ["data_region = 'EU' AND compliance_flag = 'GDPR'"]
  }
}

Dynamic Row Filters (available from Startree release 0.17)

Static row filters work well when you can enumerate every value up front — for example, writing one policy per vendor ID. For multi-tenant applications where the tenant (or user, region, account, etc.) isn’t known until query time, you can write one policy with a placeholder, and have StarTree fill it in automatically from a value the caller supplies with the query.

Dynamic row filters use the same policy structure as static row filters — the only difference is the filter text contains a placeholder instead of a literal value.

Placeholder Syntax

A placeholder has the form ${parameterName} or ${parameterName:TYPE}:

{
  "conditions": {
    "rowFilters": ["tenant_id = ${tenant_id}"]
  }
}

{
  "conditions": {
    "rowFilters": ["account_id = ${account_id:LONG}"]
  }
}

If no type is given, the placeholder defaults to STRING. Supported types:

Type	Accepts
`STRING`	Any text up to 1024 characters (default)
`INT`	A 32-bit integer
`LONG`	A 64-bit integer
`FLOAT` / `DOUBLE`	A numeric value, with or without a decimal point
`BOOLEAN`	`true` or `false`

A placeholder must stand in for a whole value being compared to a column — for example on the right-hand side of =, >, BETWEEN, or inside an IN (...) list:

{
  "conditions": {
    "rowFilters": ["tenant_id = ${tenant_id} AND signup_date >= ${min_date:LONG}"]
  }
}

Supplying Values at Query Time

The caller supplies each placeholder’s value as a URL query parameter on the HTTP request to the query endpoint — it is not part of the SQL text itself. For example, with the policy above (tenant_id = ${tenant_id}), the query request becomes:

curl -X POST "https://<broker-host>/query/sql?tenant_id=acme_corp" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"sql": "SELECT * FROM orders LIMIT 10"}'

StarTree reads tenant_id=acme_corp off the request URL, substitutes it into the policy’s row filter as a properly typed, escaped literal, and applies it the same way a static row filter is applied — the caller never needs to (and cannot) write the filter into the SQL itself. This is particularly useful for embedded or white-labeled dashboards, where a single widget or service account queries on behalf of many tenants, and the tenant identifier is known to the embedding application at query time but shouldn’t be hard-coded per-tenant into a policy.

Validation and Error Handling

Every value is validated before the query runs; nothing partial is ever returned:

A required parameter that is missing or empty fails the query.
A parameter supplied more than once (ambiguous) fails the query.
A value that doesn’t match its declared type (for example, non-numeric text for an INT placeholder) fails the query.

A failed validation returns an error response identifying which parameter was the problem, so the caller can correct the request.

Implementation Steps

Row-Level Access Control follows the same implementation process as any other RBAC policy:

Create a policy with row filter conditions in the Security Manager
Create a role and attach the policy to it
Assign the role to users or groups

The process is identical to standard RBAC - the only difference is adding the conditions section with rowFilters to your policy configuration. You can use the StarTree Security Manager UI to apply these policies.

Use Cases

Vendor Data Isolation

Allow vendors to see only their own orders in a shared table:

{
  "version": "v1",
  "statements": [
    {
      "description": "Vendor can only see their own orders",
      "resources": ["srn2:cluster#pinot:table#orders"],
      "effect": "allow",
      "actions": ["query"],
      "conditions": {
        "rowFilters": ["vendor_id = 'VENDOR_123'"]
      }
    }
  ]
}

Sales Territory Management

Restrict sales reps to view only their assigned accounts:

{
  "version": "v1",
  "statements": [
    {
      "description": "Sales rep can only access assigned territories",
      "resources": ["srn2:cluster#pinot:table#customer_accounts"],
      "effect": "allow",
      "actions": ["query"],
      "conditions": {
        "rowFilters": ["sales_rep_id = 'REP_456' AND territory = 'West'"]
      }
    }
  ]
}

Regional Data Compliance

Enforce data residency by region within a global table:

{
  "version": "v1",
  "statements": [
    {
      "description": "EU users can only access EU data",
      "resources": ["srn2:cluster#pinot:table#user_analytics"],
      "effect": "allow",
      "actions": ["query"],
      "conditions": {
        "rowFilters": ["data_region = 'EU' AND compliance_flag = 'GDPR'"]
      }
    }
  ]
}

Multi-Tenant Embedded Dashboards

Serve every tenant from one policy, with the embedding application supplying the tenant at query time:

{
  "version": "v1",
  "statements": [
    {
      "description": "Each embedded dashboard sees only its own tenant's data",
      "resources": ["srn2:cluster#pinot:table#events"],
      "effect": "allow",
      "actions": ["query"],
      "conditions": {
        "rowFilters": ["tenant_id = ${tenant_id}"]
      }
    }
  ]
}

Limitations

Row-level policies may take up to one hour to propagate and become effective after creation or modification.
Dynamic row filter values must be supplied as URL query parameters on the HTTP request to the query endpoint. This is not available on access paths that don’t expose a URL query string.
Exactly one value is required per placeholder on each request — zero, empty, or multiple values for the same parameter name fail the query.
Placeholder values are strictly typed (STRING, INT, LONG, FLOAT, DOUBLE, BOOLEAN); a value that doesn’t match its declared type fails the query rather than being coerced.
String placeholder values are limited to 1024 characters and may not contain control characters.
The parameter names sql, trace, getcursor, numrows, and offset are reserved by the query API and cannot be used as placeholder names.

Next Steps

Learn about Custom Policy Configuration
Explore RBAC API usage
Review Security Actions available for policies

Get Started

Ingestion

External Tables

Query Data

Manage Data

Observability

Visualize Data

Cluster Operations

Manage Security

Release Notes

Reference

Row-Level Access Control

How Row-Level Access Control Works

Policy Configuration

Row Filter Syntax

Single Condition Filters

Multi-Condition Filters

Dynamic Row Filters (available from Startree release 0.17)

Placeholder Syntax

Supplying Values at Query Time

Validation and Error Handling

Implementation Steps

Use Cases

Vendor Data Isolation

Sales Territory Management

Regional Data Compliance

Multi-Tenant Embedded Dashboards

Limitations

Next Steps