class pixeltable.Table
A handle to a table, view, or snapshot. This class is the primary interface through which table operations (queries, insertions, updates, etc.) are performed in Pixeltable.method add_column()
Signature
kwargs(type | ColumnSpec): Exactly one keyword argument of the formcol_name=typeorcol_name=col_spec_dict, wherecol_spec_dictis aColumnSpecdict.if_exists(Literal['error', 'ignore', 'replace', 'replace_force'], default:'error'): Determines the behavior if the column already exists. Must be one of the following:'error': an exception will be raised.'ignore': do nothing and return.'replace'or'replace_force': drop the existing column and add the new column, if it has no dependents.
UpdateStatus: Information about the execution status of the operation.
add_columns:
method add_columns()
Signature
add_computed_column() instead.
The format of the schema argument is a dict mapping column names to their types.
Parameters:
-
schema(Mapping[str, type | ColumnSpec]): A dictionary mapping column names to atypeor aColumnSpecdict. -
if_exists(Literal['error', 'ignore', 'replace', 'replace_force'], default:'error'): Determines the behavior if a column already exists. Must be one of the following:'error': an exception will be raised.'ignore': do nothing and return.'replace' or 'replace_force': drop the existing column and add the new column, if it has no dependents.
if_existsparameter is applied to all columns in the schema. To apply different behaviors to different columns, please useadd_column()for each column.
UpdateStatus: Information about the execution status of the operation.
my_table:
method add_computed_column()
Signature
-
kwargs(exprs.Expr): Exactly one keyword argument of the formcol_name=expression. -
stored(bool | None): Whether the column is materialized and stored or computed on demand. -
destination(str | Path | None): An object store reference for persisting computed files. -
print_stats(bool, default:False): IfTrue, print execution metrics during evaluation. -
on_error(Literal['abort', 'ignore'], default:'abort'): Determines the behavior if an error occurs while evaluating the column expression for at least one row.'abort': an exception will be raised and the column will not be added.'ignore': execution will continue and the column will be added. Any rows with errors will have aNonevalue for the column, with information about the error stored in the correspondingtbl.col_name.errormsgandtbl.col_name.errortypefields.
-
if_exists(Literal['error', 'ignore', 'replace'], default:'error'): Determines the behavior if the column already exists. Must be one of the following:'error': an exception will be raised.'ignore': do nothing and return.'replace' or 'replace_force': drop the existing column and add the new column, iff it has no dependents.
UpdateStatus: Information about the execution status of the operation.
frame, add an image column rotated that rotates the image by 90 degrees:
method add_embedding_index()
Signature
Array column, an
embedding UDF. String, Image, Video, Audio and Array columns are currently supported.
For Array columns, which are assumed to contain precomputed embeddings, an embedding function is optional;
if provided, it will be used to convert query values into embeddings for similarity search.
Parameters:
column(str | ColumnRef): The name of, or reference to, the column to be indexed; must be aString,ImageorArraycolumn.idx_name(str | None): An optional name for the index. If not specified, a name such as'idx0'will be generated automatically. If specified, the name must be unique for this table and a valid pixeltable column name.embedding(pxt.Function | None): The UDF to use for the embedding. Must be a UDF that accepts a single argument of typeStringorImage(as appropriate for the column being indexed) and returns a fixed-size 1-dimensional array of floats.string_embed(pxt.Function | None): An optional UDF to use for the string embedding component of this index. Can be used in conjunction withimage_embedto construct multimodal embeddings manually, by specifying different embedding functions for different data types.image_embed(pxt.Function | None): An optional UDF to use for the image embedding component of this index. Can be used in conjunction withstring_embedto construct multimodal embeddings manually, by specifying different embedding functions for different data types.metric(Literal['cosine', 'ip', 'l2'], default:'cosine'): Distance metric to use for the index; one of'cosine','ip', or'l2'. The default is'cosine'.precision(Literal['fp16', 'fp32'], default:'fp16'): level of precision for the embeddings; one of'fp16'or'fp32'.if_exists(Literal['error', 'ignore', 'replace', 'replace_force'], default:'error'): Directive for handling an existing index with the same name. Must be one of the following:'error': raise an error if an index with the same name already exists.'ignore': do nothing if an index with the same name already exists.'replace'or'replace_force': replace the existing index with the new one.
img column of the table my_table:
img column may be specified by name:
similarity pseudo-function:
img column, using the inner product as the distance metric, and with a specific name:
method batch_update()
Signature
rows(Iterable[dict[str, Any]]): an Iterable of dictionaries containing values for the updated columns plus values for the primary key columns.cascade(bool, default:True): if True, also update all computed columns that transitively depend on the updated columns.if_not_exists(Literal['error', 'ignore', 'insert'], default:'error'): Specifies the behavior if a row to update does not exist:'error': Raise an error.'ignore': Skip the row silently.'insert': Insert the row.
name and age columns for the rows with ids 1 and 2 (assuming id is the primary key). If either row does not exist, this raises an error:
name and age columns for the row with id 1 (assuming id is the primary key) and insert the row with new id 3 (assuming this key does not exist):
method collect()
Signature
method columns()
Signature
method count()
Signature
method delete()
Signature
where('exprs.Expr' | None): a predicate to filter rows to delete.
a is greater than 5:
method describe()
Signature
method distinct()
Signature
method drop_column()
Signature
column(str | ColumnRef): The name or reference of the column to drop.if_not_exists(Literal['error', 'ignore'], default:'error'): Directive for handling a non-existent column. Must be one of the following:'error': raise an error if the column does not exist.'ignore': do nothing if the column does not exist.
col from the table my_table by column name:
col from the table my_table by column reference:
col from the table my_table if it exists, otherwise do nothing:
method drop_embedding_index()
Signature
-
column(str | ColumnRef | None): The name of, or reference to, the column from which to drop the index. The column must have only one embedding index. -
idx_name(str | None): The name of the index to drop. -
if_not_exists(Literal['error', 'ignore'], default:'error'): Directive for handling a non-existent index. Must be one of the following:'error': raise an error if the index does not exist.'ignore': do nothing if the index does not exist.
if_not_existsparameter is only applicable when anidx_nameis specified and it does not exist, or whencolumnis specified and it has no index.if_not_existsdoes not apply to non-exisitng column.
img column of the table my_table by column name:
img column of the table my_table by column reference:
idx1 of the table my_table by index name:
idx1 of the table my_table by index name, if it exists, otherwise do nothing:
method drop_index()
Signature
-
column(str | ColumnRef | None): The name of, or reference to, the column from which to drop the index. The column must have only one embedding index. -
idx_name(str | None): The name of the index to drop. -
if_not_exists(Literal['error', 'ignore'], default:'error'): Directive for handling a non-existent index. Must be one of the following:'error': raise an error if the index does not exist.'ignore': do nothing if the index does not exist.
if_not_existsparameter is only applicable when anidx_nameis specified and it does not exist, or whencolumnis specified and it has no index.if_not_existsdoes not apply to non-exisitng column.
img column of the table my_table by column name:
img column of the table my_table by column reference:
idx1 of the table my_table by index name:
idx1 of the table my_table by index name, if it exists, otherwise do nothing:
method get_metadata()
Signature
'TableMetadata': A TableMetadata instance containing this table’s metadata.
method get_versions()
Signature
get_versions() is intended for programmatic access to version metadata; for human-readable
output, use history() instead.
Parameters:
n(int | None): if specified, will return at mostnversions
list[VersionMetadata]: A list of VersionMetadata dictionaries, one per version retrieved, most recent first.
tbl:
tbl:
method group_by()
Signature
Query.group_by for more details.
method head()
Signature
method history()
Signature
history() is intended for human-readable output of version metadata; for programmatic access,
use get_versions() instead.
Parameters:
n(int | None): if specified, will return at mostnversions
pd.DataFrame: A report with information about each version, one per row, most recent first.
method insert()
Signatures
-
source(TableDataSource | None): A data source from which data can be imported. -
kwargs(Any): (if inserting a single row) Keyword-argument pairs representing column names and values. (if inserting multiple rows) Additional keyword arguments are passed to the data source. -
source_format(Literal['csv', 'excel', 'parquet', 'json'] | None): A hint about the format of the source data -
schema_overrides(dict[str, ts.ColumnType] | None): If specified, then columns inschema_overrideswill be given the specified types -
on_error(Literal['abort', 'ignore'], default:'abort'): Determines the behavior if an error occurs while evaluating a computed column or detecting an invalid media file (such as a corrupt image) for one of the inserted rows.- If
on_error='abort', then an exception will be raised and the rows will not be inserted. - If
on_error='ignore', then execution will continue and the rows will be inserted. Any cells with errors will have aNonevalue for that cell, with information about the error stored in the correspondingtbl.col_name.errortypeandtbl.col_name.errormsgfields.
- If
-
print_stats(bool, default:False): IfTrue, print statistics about the cost of computed columns.
UpdateStatus: AnUpdateStatusobject containing information about the update.
my_table with three int columns a, b, and c. Column c is nullable:
pxt.Int columns a and b:
method join()
Signature
method limit()
Signature
n(int): Number of rows to select.offset(int | None): Number of rows to skip before returning results. Default is None (no offset).
'pxt.Query': A Query with the specified limited rows.
method list_views()
Signature
Table.
Parameters:
recursive(bool, default:True): IfFalse, returns only the immediate successor views of thisTable. IfTrue, returns all sub-views (including views of views, etc.)
list[str]: A list of view paths.
method order_by()
Signature
Query.order_by for more details.
method pull()
Signature
method push()
Signature
method recompute_columns()
Signature
columns(str | ColumnRef): The names or references of the computed columns to recompute.where('exprs.Expr' | None): A predicate to filter rows to recompute.errors_only(bool, default:False): If True, only run the recomputation for rows that have errors in the column (ie, the column’serrortypeproperty indicates that an error occurred). Only allowed for recomputing a single column.cascade(bool, default:True): if True, also update all computed columns that transitively depend on the recomputed columns.
c1 and c2 for all rows in this table, and everything that transitively depends on them:
c1 for all rows in this table, but don’t recompute other columns that depend on it:
c1 and its dependents, but only for rows with c2 == 0:
c1 and its dependents, but only for rows that have errors in it:
method rename_column()
Signature
old_name(str): The current name of the column.new_name(str): The new name of the column.
col1 to col2 of the table my_table:
method revert()
Signature
method sample()
Signature
Query.sample for more details.
method select()
Signature
Query.select for more details.
method show()
Signature
method sync()
Signature
stores(str | list[str] | None): If specified, will synchronize only the specified named store or list of stores. If not specified, will synchronize all of this table’s external stores.export_data(bool, default:True): IfTrue, data from this table will be exported to the external stores during synchronization.import_data(bool, default:True): IfTrue, data from the external stores will be imported to this table during synchronization.
method tail()
Signature
method unlink_external_stores()
Signature
stores(str | list[str] | None): If specified, will unlink only the specified named store or list of stores. If not specified, will unlink all of this table’s external stores.ignore_errors(bool, default:False): IfTrue, no exception will be thrown if a specified store is not linked to this table.delete_external_data(bool, default:False): IfTrue, then the external data store will also be deleted. WARNING: This is a destructive operation that will delete data outside Pixeltable, and cannot be undone.
method update()
Signature
value_spec(dict[str, Any]): a dictionary mapping column names to literal values or Pixeltable expressions.where('exprs.Expr' | None): a predicate to filter rows to update.cascade(bool, default:True): if True, also update all computed columns that transitively depend on the updated columns.
UpdateStatus: AnUpdateStatusobject containing information about the update.
int_col to 1 for all rows:
int_col to 1 for all rows where int_col is 0:
int_col to the value of other_int_col + 1:
int_col by 1 for all rows where int_col is 0:
method where()
Signature
Query.where for more details.