Schema

A Schema is a tree-like structure that describes the layout of an object, and every Table has a schema which describes the rows. Schemas also include properties for the Dashboard to know how to visualize the data correctly. For example, Schemas allow you to describe that a string in the dataset refers to images on disk, which in turn lets the 3LC Dashboard know to open and show them as images.

A Schema describes all serializable attributes of an object. Minimally, this includes describing the data type. In addition, the dimensionality, size, display name, number role, and more can be described by the schema.

For common data types, 3LC provides builtin schemas that can be used without exploring the details of Schemas. For more custom data, you may have to write out a schema yourself. See Column Types for an overview of data types and their builtin schemas, and how to build those schemas from scratch.

Atomic and Composite Schemas

A Schema can be either composite or atomic. This is signalled by the presence of either the value attribute, or the values attribute. If the value attribute is present, then the schema is atomic, and the data is described by the ScalarValue subclass stored in the value attribute of the schema. If the values attribute is present, then the attribute is composite, and the schema can be recursed by following the sub-attributes defined in the values attribute of the schema, which is of type dict[str, Schema].

Dimensionality

tlc does not have a separate notion of list- or array-schemas. Instead, the dimensionality and shape of an attribute is described by the size0, size1, …, size5 attributes of Schema, which are of type DimensionNumericValue.

Example

Enough theory, let’s look at an example which creates atomic schemas and combines them to a composite schema.

# Examples of creating schemas for object attributes
import tlc

# A schema describing a integer value between 0 and 100.
int_schema = tlc.Schema(
    display_name="Integer Value Schema",
    description="This is an example schema",
    writable=False,  # The value described by this schema is not writable
    value=tlc.Int32Value(value_min=0, value_max=100),
)

# A schema describing a variable sized array of floats.
float_array_schema = tlc.Schema(
    display_name="Float Array Schema",
    description="This is an example schema",
    writable=True,  # The value described by this schema is writable
    value=tlc.Float32Value(unit="ms"),
    size0=tlc.DimensionNumericValue(value_min=1, value_max=10),
)

# Create a composite schema from the atomic schemas
composite_schema = tlc.Schema(
    values={"float_array": float_array_schema, "int_value": int_schema},
)