Record Views

record_views

Module for managing Kaleidoscope record views and their operations.

This module provides classes and services for interacting with record views in the Kaleidoscope system.

Classes:

Name	Description
RecordTransfer	TypedDict defining the structure for transferring records with key field values.
ViewField	TypedDict defining the structure for view fields with data and lookup field references.
RecordView	Model representing a record view with methods for extending views.
RecordViewsService	Service class for managing record view operations and API interactions.

Example

    views = client.record_views.get_record_views()
    for view in views:
        print(f"View: {view.view_name}, Entity Slice: {view.entity_slice_id}")

    # View: Customer Records, Entity Slice: abc-123-def
    # View: Product Catalog, Entity Slice: xyz-456-ghi

RecordTransfer

Bases: TypedDict

TypedDict defining the structure for transferring records with key field values.

Attributes:

Name	Type	Description
record_id	str	The unique identifier of the record to transfer.
key_field_name_to_value	dict[str, Any]	A dictionary mapping key field names to their values.

ViewField

Bases: TypedDict

TypedDict defining the structure for view fields with data and lookup field references.

Attributes:

Name	Type	Description
data_field_id	str | None	The ID of the data field, if applicable.
lookup_field_id	str | None	The ID of the lookup field, if applicable.

FilterRuleType

Bases: str, Enum

Comparison rule applied by a RecordViewFilter.

RecordViewSort

Bases: TypedDict

Sort configuration on a record view.

Exactly one of key_field_id or view_field_id should be non-null.

Attributes:

Name	Type	Description
key_field_id	str | None	UUID of the key field to sort by, if any.
view_field_id	str | None	UUID of the view field to sort by, if any.
descending	bool	Sort direction.
plot_field_config	dict | None	Optional plot-field config when sorting by a plot field. Keep as raw dict; shape depends on the field's chart variant.

RecordViewFilter

Bases: TypedDict

Filter configuration on a record view.

Exactly one of key_field_id or view_field_id should be non-null.

Attributes:

Name	Type	Description
key_field_id	str | None	UUID of the key field to filter on.
view_field_id	str | None	UUID of the view field to filter on.
filter_type	str	The comparison rule. Use FilterRuleType values.
filter_prop	Any	The filter's argument (e.g. the value to compare against, a range, an array of options). Shape depends on filter_type; server accepts arbitrary JSON here.
plot_field_config	dict | None	Optional plot-field config when filtering by a plot field.

RecordViewColorFilter

Bases: TypedDict

Color rule on a record view: a filter plus the color to apply when rows match.

Same shape as RecordViewFilter with one extra field.

Attributes:

Name	Type	Description
key_field_id	str | None	UUID of the key field to filter on.
view_field_id	str | None	UUID of the view field to filter on.
filter_type	str	The comparison rule. Use FilterRuleType values.
filter_prop	Any	Filter argument.
plot_field_config	dict | None	Optional plot-field config.
color	str	Color string to apply to matching rows.

RecordView

Bases: _KaleidoscopeBaseModel

Represents a view of records in the Kaleidoscope system.

A RecordView defines how records are displayed and accessed: the entity slice it belongs to, associated programs/operations, visible fields, filters, sorts, color rules, and grouping config.

Attributes:

Name	Type	Description
id	str	UUID of the record view.
view_name	str	Display name of the view.
entity_slice_id	str	ID of the entity slice this view belongs to.
program_ids	list[str]	Programs associated with this view.
operation_ids	list[str] | None	Operations this view is attached to.
operation_definition_ids	list[str] | None	Operation definitions (experiment types) this view is attached to.
view_fields	list[ViewField]	Fields visible in this view.
filters	list[RecordViewFilter]	View filter configurations.
sorts	list[RecordViewSort]	View sort configurations.
color_filters	list[RecordViewColorFilter]	Color-filter configurations.
record_set_ids_filter	list[str]	Record set IDs restricting the view.
record_ids_filter	list[str]	Specific record IDs restricting the view.
incrementing_field_ids	list[str]	Incrementing field UUIDs.
sort_order	str | None	'alphabetical', 'created_date', 'manual', or None.
sort_descending	bool | None	Sort direction.
view_mode	str | None	Display mode (e.g. 'table').
parent_record_view_id	str | None	Parent view UUID, if this view was created from another.
is_archived	bool	Whether the view is archived.
is_template	bool	Whether this view is a reusable template. See kalbio.result_table_templates.ResultTableTemplate.
template_name	str | None	Human-readable template label, set only when is_template is True.
group_by_mode	str | None	Grouping mode.
group_by_field_id	str | None	Group-by field UUID.
workspace_id	str | None	UUID of the workspace.
created_by	str | None	UUID of the user who created the view.
last_updated_by	str | None	UUID of the user who last updated the view.
created_at	datetime | None	Creation timestamp.
updated_at	datetime | None	Last-updated timestamp.

Classes:

Name	Description
ExtendViewBody	TypedDict defining the body for extending a record view.
ReplaceKeyFieldsBody	TypedDict defining the body for replacing key fields on a record view.

Methods:

Name	Description
extend_view	Extends the current record view by adding a key field.
replace_key_fields	Atomically swap key fields on this record view.

ExtendViewBody

Bases: TypedDict

TypedDict defining the body for extending a record view.

Attributes:

Name	Type	Description
new_key_field_name	str	The name of the new key field to add.
records_to_transfer	list[RecordTransfer] | None	A list of records to transfer with their new key values.

ReplaceKeyFieldsBody

Bases: TypedDict

TypedDict defining the body for replacing key fields on a record view.

Attributes:

Name	Type	Description
add_key_field_names	list[str]	Names of key fields to add to the view.
remove_key_field_ids	list[str]	UUIDs of key fields to remove from the view.
records_to_transfer	list[RecordTransfer] | None	One entry per record currently on the view. Each entry's key_field_name_to_value must cover the FULL new key set (existing − removed + added) — the server rejects partial maps.

extend_view

extend_view(body: ExtendViewBody) -> None

Extends the current record view by adding a key field.

Parameters:

Name	Type	Description	Default
body	ExtendViewBody	The request body containing information about the key field to add.	required

Raises:

Type	Description
KalbioAPIError	If the API request fails.

Source code in kalbio/record_views.py

def extend_view(self, body: ExtendViewBody) -> None:
    """Extends the current record view by adding a key field.

    Args:
        body (ExtendViewBody): The request body containing information about the key field to add.

    Raises:
        KalbioAPIError: If the API request fails.
    """
    resp = self._client._put(
        "/record_views/" + self.id + "/add_key_field", dict(body)
    )
    if resp:
        for key, value in resp.items():
            if hasattr(self, key):
                setattr(self, key, value)

replace_key_fields

replace_key_fields(body: ReplaceKeyFieldsBody) -> RecordView | None

Atomically swap key fields on this record view.

The server creates (or reuses) the slice whose key set is (existing − removed + added), copies this view onto it, transfers any records via the transfer flow, and returns the NEW view. The new view has a different id and entity_slice_id, so this method returns a fresh RecordView rather than mutating self.

Parameters:

Name	Type	Description	Default
body	ReplaceKeyFieldsBody	Request body with adds (by name), removes (by id), and per-record key values for the new slice.	required

Returns:

Type	Description
RecordView | None	The new RecordView, or None if the request failed.

Source code in kalbio/record_views.py

def replace_key_fields(self, body: ReplaceKeyFieldsBody) -> Optional["RecordView"]:
    """Atomically swap key fields on this record view.

    The server creates (or reuses) the slice whose key set is
    ``(existing − removed + added)``, copies this view onto it, transfers
    any records via the transfer flow, and returns the NEW view. The new
    view has a different ``id`` and ``entity_slice_id``, so this method
    returns a fresh ``RecordView`` rather than mutating ``self``.

    Args:
        body: Request body with adds (by name), removes (by id), and
            per-record key values for the new slice.

    Returns:
        The new RecordView, or None if the request failed.
    """
    resp = self._client._put(
        "/record_views/" + self.id + "/replace_key_fields", dict(body)
    )
    if resp is None:
        return None
    new_view = RecordView.model_validate(resp)
    new_view._set_client(self._client)
    return new_view

RecordViewsService

RecordViewsService(client: KaleidoscopeClient)

Service class for managing record views in Kaleidoscope.

This service provides methods to interact with record views, including retrieving, creating, and managing RecordView objects. It handles the conversion of raw data into RecordView instances and ensures proper client association.

Example

views = client.record_views.get_record_views()
for view in views:
    print(f"View: {view.view_name}, Entity Slice: {view.entity_slice_id}")

# View: Customer Records, Entity Slice: abc-123-def
# View: Product Catalog, Entity Slice: xyz-456-ghi

Methods:

Name	Description
get_record_views	Retrieves the regular record views in the workspace.
get_data_fields_on_view	Get the data fields visible on a given record view.

Source code in kalbio/record_views.py

def __init__(self, client: KaleidoscopeClient):
    self._client = client

get_record_views cached

get_record_views() -> list[RecordView]

Retrieves the regular record views in the workspace.

Templates (where is_template is True) are excluded from this list. To retrieve templates, use client.result_table_templates.get_templates().

This method caches its values.

Returns:

Type	Description
list[RecordView]	List[RecordView]: Regular (non-template) record views in the workspace.

Source code in kalbio/record_views.py

@lru_cache
def get_record_views(self) -> List[RecordView]:
    """Retrieves the regular record views in the workspace.

    Templates (where `is_template` is True) are excluded from this list.
    To retrieve templates, use `client.result_table_templates.get_templates()`.

    This method caches its values.

    Returns:
        List[RecordView]: Regular (non-template) record views in the workspace.
    """
    resp = self._client._get("/record_views")
    all_views = self._create_record_views_list(resp)
    return [v for v in all_views if not v.is_template]

get_data_fields_on_view

get_data_fields_on_view(view_id: str, field_type: DataFieldTypeEnum | None = None) -> list[DataField]

Get the data fields visible on a given record view.

Walks the view's view_fields, resolves each data_field_id via client.entity_fields.get_data_field_by_id, and optionally filters by field_type.

Useful for discovering field UUIDs needed by activity-definition advanced settings (e.g. registration_status_field_id).

Parameters:

Name	Type	Description	Default
view_id	str	UUID of the record view.	required
field_type	DataFieldTypeEnum | None	Optional data field type to filter by.	None

Returns:

Type	Description
list[DataField]	DataField objects on the view, in the view's field order.
list[DataField]	Empty if the view is not found, has no data fields, or no
list[DataField]	fields match field_type.

Example

status_field = client.record_views.get_data_fields_on_view(
    view_id, DataFieldTypeEnum.STATUS
)[0]

Source code in kalbio/record_views.py

def get_data_fields_on_view(
    self,
    view_id: str,
    field_type: Optional["DataFieldTypeEnum"] = None,
) -> List["DataField"]:
    """Get the data fields visible on a given record view.

    Walks the view's `view_fields`, resolves each `data_field_id`
    via `client.entity_fields.get_data_field_by_id`, and optionally
    filters by `field_type`.

    Useful for discovering field UUIDs needed by activity-definition
    advanced settings (e.g. `registration_status_field_id`).

    Args:
        view_id: UUID of the record view.
        field_type: Optional data field type to filter by.

    Returns:
        DataField objects on the view, in the view's field order.
        Empty if the view is not found, has no data fields, or no
        fields match `field_type`.

    Example:
        ```python
        status_field = client.record_views.get_data_fields_on_view(
            view_id, DataFieldTypeEnum.STATUS
        )[0]
        ```
    """
    view = next(
        (v for v in self.get_record_views() if v.id == view_id),
        None,
    )
    if view is None:
        return []

    fields: List["DataField"] = []
    for vf in view.view_fields:
        data_field_id = vf.get("data_field_id")
        if not data_field_id:
            continue
        df = self._client.entity_fields.get_data_field_by_id(data_field_id)
        if df is None:
            continue
        if field_type is not None and df.field_type != field_type:
            continue
        fields.append(df)
    return fields