rdblue commented on code in PR #13879:
URL: https://github.com/apache/iceberg/pull/13879#discussion_r3399489739
##########
open-api/rest-catalog-open-api.yaml:
##########
@@ -3632,6 +3632,343 @@ components:
additionalProperties:
type: string
+ ReadRestrictions:
+ type: object
+ description: >
+ Read restrictions for a table, including column projections and row
filter expressions.
+
+ A client SHOULD support the read-restrictions field. If a client
supports
+ read-restrictions, it MUST fail if it cannot apply any returned
restriction
+ (including unrecognized action or expression types). Read
restrictions returned
+ in a loadTable response apply to every read operation on the loaded
table
+ performed using this response, including subsequent planTableScan and
+ fetchScanTasks calls.
+
+ In this section, "reader" refers to the read-side actor that applies
restrictions
+ per row or per column. "Engine" refers to the broader
query-execution context
+ that defines query lifetime and scope (e.g. a SQL session, a single
PyIceberg
+ scan), and is the actor responsible for query-scoped behavior such
as salt
+ generation in sha-256-query-local.
+
+ These restrictions apply only to the authenticated principal, user,
or account
+ associated with the request. They MUST NOT be interpreted as global
policy and
+ MUST NOT be applied beyond the entity identified by the
Authentication header
+ (or other applicable authentication mechanism).
+
+ An empty ReadRestrictions object (no required-column-projections and
no
+ required-row-filter) imposes no restrictions and is equivalent to
the field
+ being absent from the response.
+ A server MUST NOT return an action for a column whose type is not
listed in
+ that action's "Applicable to" set.
+
+ NULL handling is action-specific. Each action's description
specifies its
+ behavior on NULL input.
+
+ If a column projection targets a struct-typed field, other column
projections
+ in the same ReadRestrictions MUST NOT target any of that struct's
subfields
+ (at any depth). This avoids ambiguity about which action governs a
given
+ leaf value.
+
+ Example:
+
+ {
+ "required-column-projections": [
+ { "field-id": 4, "action": "show-last-4" },
+ { "field-id": 6, "action": "replace-with-null" },
+ { "field-id": 8, "action": "truncate-to-year" },
+ { "field-id": 10, "action": "sha-256-global" },
+ { "field-id": 12, "action": "mask-alphanum" }
+ ],
+ "required-row-filter": {
+ "type": "eq",
+ "term": "region",
+ "value": "US"
+ }
+ }
+ properties:
+ required-column-projections:
+ description: >
+ A list of columns that require specific actions to be applied when
reading.
+
+ If this property is absent, a reader MAY access all columns of the
table as-is
+ without any mandatory transformations.
+
+ If this property is present, each listed column MUST have its
specified
+ action applied. Columns not listed in required-column-projections
+ are not subject to any read restrictions.
+
+ When this list is present:
+
+ 1. For each column listed in required-column-projections, the
reader MUST apply
+ the specified action before returning values for that column.
+
+ 2. The reader MUST replace all output references to the column
with the result
+ of the action, presenting the result under the original column
name. For
+ example, if the action for column cc is mask-alphanum, the
reader MUST
+ return the masked value as cc in the query output.
+
+ 3. Columns not listed in required-column-projections MAY be
projected normally
+ by the reader without any mandatory transformations.
+
+ 4. A column MUST appear at most once in
required-column-projections.
+
+ 5. If a projected column's action cannot be evaluated by the
reader (including
+ unrecognized action types), the reader MUST fail the query with
an error to
+ the caller. The reader MUST NOT silently return raw, partial, or
empty
+ results to mask the failure.
+
+ 6. Each action defines the output type for its column. For all
predefined
+ actions, the output type matches the input column type.
+
+ type: array
+ items:
+ $ref: '#/components/schemas/Action'
+ required-row-filter:
+ description: >
+ An expression that filters rows in the table that the
authenticated principal does not have access to.
+
+ 1. The expression MUST evaluate to a boolean (TRUE or FALSE;
Iceberg expressions
+ never produce NULL). A reader MUST discard any row for which
+ the filter evaluates to FALSE, and no information derived from
discarded rows
+ MAY be included in the query result.
+
+ 2. Row filters MUST be evaluated against the original,
untransformed column values.
+ Required projections MUST be applied only after row filters are
applied.
Review Comment:
Order of evaluation probably belongs on the read restrictions description,
not here.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
