API Schema Reference

This page documents all request/response schemas used by the XplainClient API.

Note

This file is auto-generated. Do not edit it directly. Regenerate with:

python xplain-openapi/generate_client.py

SessionResponse

The current session state, including loaded objects, dimensions, attributes, open requests and their results. Most method calls return this structure.

ErrorResponse

Property	Type	Description
`error`	`str`	Human-readable error message
`errorType`	`str`	Machine-readable error type One of: `XplainCheckedException`, `XplainInvalidRequestException`, `XplainNoSuchArtifactException`.

FileDescriptor

Property	Type	Description
`fileType`	`str`	File type identifier (e.g. XTABLE, XANALYSIS, XSELECTION, XMODEL, XMODELRESULT, XSCRIPT). Set automatically if missing.
`ownership`	`str`	Access level for the file One of: `PUBLIC`, `TEAM`, `USER`.
`team`	`str`	Team name (required when ownership is TEAM)
`user`	`str`	User name (required when ownership is USER)
`filePath`	list of `str`	Required. Path components to the file (list of path segments)

Example

filePath:
- Patient.xtable
fileType: XTABLE
ownership: PUBLIC

AttributePath

Property	Type	Description
`object`	`str`	Required. XObject (table) name
`dimension`	`str`	Required. Dimension name
`attribute`	`str`	Required. Attribute name

Example

attribute: Age Group
dimension: Age Group
object: Patient

XElementPath

Property	Type	Description
`object`	`str`	Required. XObject (table) name
`dimension`	`str`	Dimension name (optional)
`attribute`	`str`	Attribute name (optional, requires dimension)
`state`	`str`	State name (optional, requires attribute)
`level`	`str`	Hierarchy level name (optional, requires attribute)

Example

attribute: Age Group
dimension: Age Group
object: Patient

AggregationUIModel

Defines a statistical aggregation (measure) for a statistics request. Either aggregationType or type must be provided.

Property	Type	Description
`aggregationName`	`str`	Optional name for this aggregation
`aggregationType`	`str`	The aggregation function to apply. Identical to the type field (one of the two must be set). One of: `COUNT`, `SUM`, `AVG`, `MIN`, `MAX`, `VAR`, `VARP`, `STDEV`, `STDEVP`, `COUNTENTITY`, `COUNTDISTINCT`, `FIRSTKEY`, `QUANTILE`, `COMPUTED_MEASURE`.
`type`	`str`	Alias for aggregationType One of: `COUNT`, `SUM`, `AVG`, `MIN`, `MAX`, `VAR`, `VARP`, `STDEV`, `STDEVP`, `COUNTENTITY`, `COUNTDISTINCT`, `FIRSTKEY`, `QUANTILE`, `COMPUTED_MEASURE`.
`object`	`str`	XObject (table) name to aggregate over
`dimension`	`str`	Dimension (measure dimension) name. Required for SUM, AVG, MIN, MAX, VAR, VARP, STDEV, STDEVP, COUNTENTITY, COUNTDISTINCT, QUANTILE.
`attribute`	`str`	Attribute name. Required for COUNTDISTINCT to specify which attribute to count distinct values of.
`states`	list of `str`	Optional list of state names to restrict counting distinct values to (for COUNTDISTINCT).
`level`	`str`	Hierarchy level name for COUNTDISTINCT. When given, all states at this level are used instead of the explicit states list.
`complementMissingBranches`	`bool`	For COUNTDISTINCT: whether to complement missing branches in the hierarchy.
`firstKey`	`str`	For FIRSTKEY aggregation: name of the cycle dimension. Only the first occurrence of this key triggers the inner aggregation.
`firstAggregation`	AggregationUIModel	For FIRSTKEY aggregation: the inner aggregation applied to the first occurrence.
`expression`	`str`	For COMPUTED_MEASURE: a mathematical expression referencing other aggregations by name in curly braces, e.g. “{SUM(Income)} / {# Person}”.
`quantiles`	list of `float`	For QUANTILE aggregation: list of quantile values between 0.0 and 1.0, e.g. [0.1, 0.25, 0.5, 0.75, 0.9].
`inheritedFormat`	`str`	Format string inherited from the dimension (read-only, set by server).

Example

aggregationType: SUM
dimension: Income
object: Customer

GroupByUIModel

Defines a group-by dimension for a statistics request. Either attribute (for a one-dimensional group-by) or subGroupings (for a multi-dimensional group-by) must be provided.

Property	Type	Description
`groupByName`	`str`	Optional name for this group-by
`attribute`	AttributePath	The attribute to group by (for one-dimensional group-bys)
`groupByLevel`	`str`	Name of the hierarchy level to group by. If given, states at this level are used. Takes precedence over groupByLevelNumber.
`groupByLevelNumber`	`int`	Depth of the hierarchy level (1-based; 0 = root, 1 = first level). Used when groupByLevel is not given.
`includeUpperLevels`	`bool`	Whether to include states from levels above the specified groupByLevel in the result. Defaults to false (only the exact level states).
`expandedStates`	list of `str`	States whose children are included in the group-by (for tree-style navigation). The state itself and its direct children are included.
`groupByStates`	list of `str`	Explicit list of state names to use as group-by states. Takes effect only when no logical build information (groupByLevel, expandedStates) is available.
`subGroupings`	list of GroupByUIModel	For multi-dimensional group-bys: list of one-dimensional sub-groupings.

Example

attribute:
  attribute: Gender
  dimension: Gender
  object: Customer

SelectionActionUIModel

A single selection action (SELECT or DESELECT) applied to a set of states.

Property	Type	Description
`actionType`	`str`	Required. Whether to select or deselect the given states One of: `SELECT`, `DESELECT`.
`states`	list of `str`	Required. List of state names to select or deselect

SelectionUIModel

Defines a selection (filter) on a specific attribute. Either selectedStates or selectActions must be provided.

Property	Type	Description
`attribute`	AttributePath	The attribute on which the selection is applied
`selectedStates`	list of `str`	Simple list of state names to select. All other states are excluded.
`selectActions`	list of SelectionActionUIModel	Sequential list of SELECT/DESELECT actions for complex selections.
`negate`	`bool`	If true, the selection is negated (select everything EXCEPT the specified states).

Example

attribute:
  attribute: Region
  dimension: Region
  object: Patient
selectedStates:
- Berlin
- Munich

StatisticsRequestUIModel

A complete statistics request defining what data to compute. Contains group-bys (dimensions to slice by), aggregations (measures to compute), and optional selections (filters).

Property	Type	Description
`requestId`	`str`	Unique identifier / name for this request
`requestName`	`str`	[Deprecated] Deprecated alias for requestId. Use requestId instead.
`groupBys`	list of GroupByUIModel	Dimensions to group/slice the data by
`aggregations`	list of AggregationUIModel	Measures/aggregations to compute
`selections`	list of SelectionUIModel	Fixed selections (filters) for this request. These are kept constant and not affected by global selections (for openRequest).
`externalSelections`	`str`	Name of an external selection set to use as additional filter (e.g. “globalSelections”).
`restrictToSelectedStates`	`bool`	If true, the group-by states are restricted to currently selected states only.
`isPaused`	`bool`	If true, the request is paused and will not be recomputed automatically.
`omitNullValueResults`	`bool`	If true, result rows where all aggregation values are null/zero are omitted from the response.

Example

aggregations:
- aggregationType: COUNT
  object: Customer
groupBys:
- attribute:
    attribute: Gender
    dimension: Gender
    object: Customer
requestId: My Request
selections:
- attribute:
    attribute: Region
    dimension: Region
    object: Customer
  selectedStates:
  - Berlin