How does TableModel work?

Annotations are stored columns. Assignments are computed columns. A subclass with base= and iterator= is a view. Applying the file creates or migrates the catalog to match the classes.

Multimodal data

What is a TableModel?

A TableModel is a Python class that declares tables, computed columns, and indexes. HTTP routes are a FastAPIRouter next to the class, not fields on it.

Updated 2026-09-29

How it works

Annotations are stored columns. Assignments are computed columns.
A subclass with base= and iterator= is a view.
Applying the file creates or migrates the catalog to match the classes.

What it is not

It is not an ORM mapped only to scalar SQL types, and it is not a notebook script that creates tables imperatively for the same objects.

TableModel: this, and the thing it is confused with

TableModel: this, and the thing it is confused with
	This	Not this
Form	Classes in one file	A sequence of create calls
Change	Edit the class and apply	A migration you write by hand
Serve	Routes declared beside the tables	A second app that copies rows

Where Pixeltable fits

Pixeltable’s schema file sets TableModel = pxt.model_base() and subclasses it. pxt schema update applies that file.

import pixeltable as pxt

TableModel = pxt.model_base()

class Docs(TableModel, name='docs'):
    text: pxt.String

Questions

How does TableModel work?: Annotations are stored columns. Assignments are computed columns. A subclass with base= and iterator= is a view. Applying the file creates or migrates the catalog to match the classes.
What is TableModel often confused with?: It is not an ORM mapped only to scalar SQL types, and it is not a notebook script that creates tables imperatively for the same objects.