Entity Fields

entity_fields

Module for managing entity fields in Kaleidoscope.

This module provides classes and services for working with entity fields, which are the schema definitions for data stored in the Kaleidoscope system. It includes:

• DataFieldTypeEnum: An enumeration of all supported field types
• EntityField: A model representing a field definition
• EntityFieldsService: A service class for retrieving and creating entity fields

Entity fields can be of two types:

• Key fields: Used to uniquely identify entities
• Data fields: Used to store additional information about entities

The service provides caching mechanisms to minimize API calls and includes error handling for all network operations.

Classes:

Name	Description
DataFieldTypeEnum	An enumeration of all supported field types
EntityField	A model representing a field definition
EntityFieldsService	A service class for retrieving and creating entity fields

Example

# Get all key fields
key_fields = client.entity_fields.get_key_fields()

# Create or get a data field
field = client.entity_fields.get_or_create_data_field(
    field_name="temperature",
    field_type=DataFieldTypeEnum.NUMBER
)

DataFieldTypeEnum

Bases: str, Enum

Enumeration of data field types supported by the system.

This enum defines all possible types of data fields that can be used in the application. Each field type represents a specific kind of data structure and validation rules.

Attributes:

Name	Type	Description
TEXT		Plain text field.
NUMBER		Numeric field for storing numbers.
QUALIFIED_NUMBER		Numeric field with additional qualifiers or units.
SMILES_STRING		Field for storing SMILES (Simplified Molecular Input Line Entry System) notation.
SELECT		Single selection field from predefined options.
MULTISELECT		Multiple selection field from predefined options.
MOLFILE		Field for storing molecular structure files.
RECORD_REFERENCE		Reference to another record by record_id.
FILE		Generic file attachment field.
IMAGE		Image file field.
DATE		Date field.
URL		Web URL field.
BOOLEAN		Boolean (true/false) field.
EMAIL		Email address field.
PHONE		Phone number field.
FORMULA		Field for storing formulas or calculated expressions.
PEOPLE		Field for referencing people/users.
VOTES		Field for storing vote counts or voting data.
XY_ARRAY		Field for storing XY coordinate arrays.
DNA_OLIGO		Field for storing DNA oligonucleotide sequences.
RNA_OLIGO		Field for storing RNA oligonucleotide sequences.
PEPTID		Field for storing peptide sequences.
PLASMID		Field for storing plasmid information.
GOOGLE_DRIVE		Field for Google Drive file references.
S3_FILE		Field for AWS S3 file references.
SNOWFLAKE_QUERY		Field for Snowflake database query references.

EntityField

Bases: _KaleidoscopeBaseModel

Represents a field within an entity in the Kaleidoscope system.

This class defines the structure and metadata for individual fields that belong to an entity, including type information, key status, and optional references.

Attributes:

Name	Type	Description
id	str	The UUID of the field.
created_at	datetime	Timestamp when the field was created.
is_key	bool	Indicates whether this field is a key field for the entity.
field_name	str	The name of the field.
field_type	DataFieldTypeEnum	The data type of the field.
ref_slice_id	str | None	Optional reference to a slice ID for relational fields.

Example

from kalbio.entity_fields import EntityField, DataFieldTypeEnum
from datetime import datetime

ef = EntityField(
    id="field_uuid",
    created_at=datetime.utcnow(),
    is_key=True,
    field_name="sample_id",
    field_type=DataFieldTypeEnum.TEXT,
    ref_slice_id=None,
)
print(str(ef))  # sample_id

EntityFieldIdentifier module-attribute

EntityFieldIdentifier: TypeAlias = EntityField | str

An Identifier Type for Entity Fields.

An EntityField should be able to be identified by:

• EntityField (object instance)
• UUID (str)
• field_name (str)

EntityFieldsService

EntityFieldsService(client: KaleidoscopeClient)

Service class for managing key fields and data fields in Kaleidoscope.

Entity fields can be of two types:

• Key fields: Used to uniquely identify entities
• Data fields: Used to store additional information about entities

Example

key_fields = client.entity_fields.get_key_fields()
temperature = client.entity_fields.get_or_create_data_field(
    field_name="temperature",
    field_type=DataFieldTypeEnum.NUMBER,
)

Methods:

Name	Description
get_key_fields	Retrieve key fields and cache the result.
get_key_field_by_id	Get a key field by an identifier.
get_or_create_key_field	Retrieve an existing key field by name or create it.
get_data_fields	Retrieve data fields and cache the result.
get_data_field_by_id	Get a data field by identifier.
get_or_create_data_field	Create a data field or return the existing one.

Source code in kalbio/entity_fields.py

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

get_key_fields cached

get_key_fields() -> list[EntityField]

Retrieve key fields and cache the result.

Returns:

Type	Description
list[EntityField]	Key field definitions for the workspace.

Notes

On error, the caches are cleared and an empty list is returned.

Example

key_fields = client.entity_fields.get_key_fields()

Source code in kalbio/entity_fields.py

@lru_cache
def get_key_fields(self) -> List[EntityField]:
    """Retrieve key fields and cache the result.

    Returns:
        Key field definitions for the workspace.

    Notes:
        On error, the caches are cleared and an empty list is returned.

    Example:
        ```python
        key_fields = client.entity_fields.get_key_fields()
        ```
    """
    try:
        resp = self._client._get("/key_fields")
        return TypeAdapter(List[EntityField]).validate_python(resp)
    except Exception as e:
        _logger.error(f"Error fetching key fields: {e}")
        self._clear_key_field_caches()
        return []

get_key_field_by_id

get_key_field_by_id(identifier: EntityFieldIdentifier) -> EntityField | None

Get a key field by an identifier.

Parameters:

Name	Type	Description	Default
identifier	EntityFieldIdentifier	Key field identifier. Data field identifiers will return None. This method will accept and resolve any type of EntityFieldIdentifier.	required

Returns:

Type	Description
EntityField | None	Matching key field if found. If not, returns None.

Example

key_field = client.entity_fields.get_key_field_by_id("sample_id")

Source code in kalbio/entity_fields.py

def get_key_field_by_id(
    self, identifier: EntityFieldIdentifier
) -> EntityField | None:
    """Get a key field by an identifier.

    Args:
        identifier: Key field identifier. Data field identifiers will return None.

            This method will accept and resolve any type of EntityFieldIdentifier.

    Returns:
        Matching key field if found. If not, returns None.

    Example:
        ```python
        key_field = client.entity_fields.get_key_field_by_id("sample_id")
        ```
    """

    id_map = self._get_key_field_id_map()
    field_id = self._resolve_key_field_id(identifier)

    if field_id:
        return id_map.get(field_id, None)
    else:
        return None

get_or_create_key_field

get_or_create_key_field(field_name: str) -> EntityField | None

Retrieve an existing key field by name or create it.

Parameters:

Name	Type	Description	Default
field_name	str	Name of the key field to fetch or create.	required

Returns:

Type	Description
EntityField | None	Existing or newly created key field, or None on error.

Example

key_field = client.entity_fields.get_or_create_key_field("sample_id")

Source code in kalbio/entity_fields.py

def get_or_create_key_field(self, field_name: str) -> EntityField | None:
    """Retrieve an existing key field by name or create it.

    Args:
        field_name: Name of the key field to fetch or create.

    Returns:
        Existing or newly created key field, or None on error.

    Example:
        ```python
        key_field = client.entity_fields.get_or_create_key_field("sample_id")
        ```
    """
    field = self.get_key_field_by_id(field_name)
    if field is not None:
        return field

    self._clear_key_field_caches()

    try:
        data = {"field_name": field_name}
        resp = self._client._post("/key_fields/", data)
        return EntityField.model_validate(resp)
    except Exception as e:
        _logger.error(f"Error getting or creating key field: {e}")
        return None

get_data_fields cached

get_data_fields() -> list[EntityField]

Retrieve data fields and cache the result.

Returns:

Type	Description
list[EntityField]	Data field definitions for the workspace.

Notes

On error, the caches are cleared and an empty list is returned.

Example

data_fields = client.entity_fields.get_data_fields()

Source code in kalbio/entity_fields.py

@lru_cache
def get_data_fields(self) -> List[EntityField]:
    """Retrieve data fields and cache the result.

    Returns:
        Data field definitions for the workspace.

    Notes:
        On error, the caches are cleared and an empty list is returned.

    Example:
        ```python
        data_fields = client.entity_fields.get_data_fields()
        ```
    """
    try:
        resp = self._client._get("/data_fields")
        return TypeAdapter(List[EntityField]).validate_python(resp)
    except Exception as e:
        _logger.error(f"Error fetching data fields: {e}")
        self._clear_data_field_caches()
        return []

get_data_field_by_id

get_data_field_by_id(identifier: EntityFieldIdentifier) -> EntityField | None

Get a data field by identifier.

Parameters:

Name	Type	Description	Default
identifier	EntityFieldIdentifier	Identifier for a data field. Key field identifiers return None. This method will accept and resolve any type of EntityFieldIdentifier.	required

Returns:

Type	Description
EntityField | None	Matching data field, if found.

Example

data_field = client.entity_fields.get_data_field_by_id("temperature")

Source code in kalbio/entity_fields.py

def get_data_field_by_id(
    self, identifier: EntityFieldIdentifier
) -> EntityField | None:
    """Get a data field by identifier.

    Args:
        identifier: Identifier for a data field. Key field identifiers return None.

            This method will accept and resolve any type of EntityFieldIdentifier.


    Returns:
        Matching data field, if found.

    Example:
        ```python
        data_field = client.entity_fields.get_data_field_by_id("temperature")
        ```
    """

    id_map = self._get_data_field_id_map()
    field_id = self._resolve_data_field_id(identifier)

    if field_id:
        return id_map.get(field_id, None)
    else:
        return None

get_or_create_data_field

get_or_create_data_field(field_name: str, field_type: DataFieldTypeEnum) -> EntityField | None

Create a data field or return the existing one.

Parameters:

Name	Type	Description	Default
field_name	str	Name of the data field to create or retrieve.	required
field_type	DataFieldTypeEnum	Data field type.	required

Returns:

Type	Description
EntityField | None	Existing or newly created data field, or None on error.

Example

concentration = client.entity_fields.get_or_create_data_field(
    field_name="concentration",
    field_type=DataFieldTypeEnum.NUMBER,
)

Source code in kalbio/entity_fields.py

def get_or_create_data_field(
    self, field_name: str, field_type: DataFieldTypeEnum
) -> EntityField | None:
    """Create a data field or return the existing one.

    Args:
        field_name: Name of the data field to create or retrieve.
        field_type: Data field type.

    Returns:
        Existing or newly created data field, or None on error.

    Example:
        ```python
        concentration = client.entity_fields.get_or_create_data_field(
            field_name="concentration",
            field_type=DataFieldTypeEnum.NUMBER,
        )
        ```
    """
    field = self.get_data_field_by_id(field_name)
    if field is not None:
        return field

    self._clear_data_field_caches()

    try:
        data: dict = {
            "field_name": field_name,
            "field_type": field_type.value,
            "attrs": {},
        }
        resp = self._client._post("/data_fields/", data)
        return EntityField.model_validate(resp)
    except Exception as e:
        _logger.error(f"Error getting or creating data field: {e}")
        return None