Tables¶

A Table is the central object in 3LC. It connects your training code, the Dashboard, and storage. Tables let you visualize, analyze and modify data in the Dashboard, and consume those changes directly in Python through tlc.Tables — which offer a familiar access interface similar to PyTorch Datasets, Pandas DataFrames, and Hugging Face Datasets, and are interoperable with common ML/Python tabular types. Edits are non-destructive and tracked in a revision model, so your original data is never modified.

Quick Start¶

The fastest way to create a Table is with TableWriter and a convenience schema for each column:

import tlc
from PIL import Image

writer = tlc.TableWriter(
    project_name="My Project",
    dataset_name="train",
    schema={
        "image": tlc.schemas.ImageSchema(),
        "label": tlc.schemas.CategoricalLabelSchema(classes=["cat", "dog", "bird"]),
    },
)

for path, label in my_data:
    writer.add_row({"image": Image.open(path), "label": label})

table = writer.finalize()

The schema tells the Dashboard how to display each column and determines how data is stored and loaded back. See Column Types for the full list of available schemas.

If your data is already in a standard format (such as COCO or YOLO), you can also import it directly — see Import.

Reading Data Back¶

Tables support indexing to get training-ready Python objects, just like PyTorch Datasets:

sample = table[0]
# {"image": <PIL.Image ...>, "label": 0, "weight": 1.0}

Under the hood, 3LC stores data in a serialized row view and transforms it into Python objects in the sample view when you access it. You don’t need to worry about this distinction to get started, but it becomes useful when working with custom sample types or bulk data.

Going Deeper¶

Topic	When to read
Import	Importing data from COCO, YOLO, Hugging Face, CSV, and other formats
Column Types	Available schemas, parameters, Dashboard features, and framework integration
Schema	Common schema parameters and building custom schemas from scratch
Sample View	How `table[i]` transforms stored data into Python objects
Row View	What’s actually stored on disk (URLs, primitives, nested lists)
Bulk Data	Controlling where and how externalized files (images, arrays) are stored
Custom Sample Types	Defining new data types not covered by built-ins
Revisions	Non-destructive editing and revision history
Sample Transforms	Applying on-the-fly transforms to table data via `Table.with_transform()`
Row Cache	Table caching behavior
Export	Exporting data to CSV, COCO, YOLO, JSON, and custom formats