This documentation page is also available as an interactive notebook. You can launch the notebook in
Kaggle or Colab, or download it for use with an IDE or local Jupyter installation, by clicking one of the
above links.
Pixeltable’s Pydantic integration enables type-safe data insertion using
Pydantic models. Instead of inserting raw dictionaries, you can define
structured models with validation and insert them directly into
Pixeltable tables.
Benefits
Type Safety: Pydantic validates data before insertion
IDE Support: Autocomplete and type hints for your data
Self-Documenting: Models serve as schema documentation
Validation: Built-in data validation via Pydantic
Important notes
Pydantic model fields map to Pixeltable columns by name
Computed columns are automatically skipped during insertion
Nested Pydantic models map to JSON columns
%pip install -qU pixeltable pydantic
import pixeltable as pxtpxt.drop_dir('pydantic_demo', force=True)pxt.create_dir('pydantic_demo')
Connected to Pixeltable database at: postgresql+psycopg://postgres:@/pixeltable?host=/Users/asiegel/.pixeltable/pgdata
Created directory ‘pydantic_demo’.
<pixeltable.catalog.dir.Dir at 0x12e01b2b0>
Basic usage: scalar types
Define a Pydantic model with fields that match your table columns.
Pixeltable automatically maps Python types to Pixeltable types:
For media columns (Image, Video, Audio, Document), use str or Path
fields in your Pydantic model to specify file paths or URLs.
from pathlib import Pathclass ImageRecord(pydantic.BaseModel): title: str image_url: str # URLs or file paths as strings tags: list[str]# Create table with Image columnimages = pxt.create_table( 'pydantic_demo/images', { 'title': pxt.String, 'image_url': pxt.Image, # Media column 'tags': pxt.Json, },)
Created table ‘images’.
# Insert image records with URLsbase_url = 'https://raw.githubusercontent.com/pixeltable/pixeltable/main/docs/resources/images'image_data = [ ImageRecord( title='Sample Image', image_url=f'{base_url}/000000000036.jpg', tags=['sample', 'test', 'image'], )]images.insert(image_data)images.select(images.title, images.image_url, images.tags).collect()
Inserted 1 row with 0 errors in 0.27 s (3.74 rows/s)
Working with Computed Columns
Pydantic models work seamlessly with computed columns. Simply omit
computed column fields from your model - Pixeltable will skip them
during insertion.
# Model only includes input columnsclass Article(pydantic.BaseModel): title: str content: str# Create table with computed columnarticles = pxt.create_table( 'pydantic_demo/articles', {'title': pxt.String, 'content': pxt.String})# Add a computed columnarticles.add_computed_column( word_count=pxt.functions.string.count(articles.content, r'\S+'))
Created table ‘articles’.
Added 0 column values with 0 errors in 0.01 s
No rows affected.
# Insert data - computed columns are automatically calculatedarticle_data = [ Article( title='Getting Started with Pixeltable', content='Pixeltable is a powerful tool for building AI applications. It provides automatic versioning and incremental computation.', ), Article( title='Type Safety in Python', content='Using Pydantic with Pixeltable provides type safety and validation for your data pipelines.', ),]articles.insert(article_data)articles.select(articles.title, articles.word_count).collect()
Inserted 2 rows with 0 errors in 0.01 s (186.43 rows/s)
Optional Fields and Defaults
Pydantic’s optional fields with defaults work naturally with
Pixeltable’s nullable columns.