Pixeltable

Import conventions:

import pixeltable as pxt

Insertable tables, views, and snapshots all have a tabular interface and are generically referred to as "tables" below.

Overview

Table Operations
`pxt.create_table`	Create a new (insertable) table
`pxt.create_view`	Create a new view
`pxt.drop_table`	Delete a table
`pxt.get_table`	Get a handle to a table
`pxt.list_tables`	List the tables in a directory

Directory Operations
`pxt.create_dir`	Create a directory
`pxt.list_dirs`	List the directories in a directory
`pxt.drop_dir`	Remove a directory

Misc
`pxt.configure_logging`	Configure logging
`pxt.init`	Initialize Pixeltable runtime now (if not already initialized)
`pxt.move`	Move a schema object to a new directory and/or rename a schema object

pixeltable

configure_logging

configure_logging(
    *,
    to_stdout: Optional[bool] = None,
    level: Optional[int] = None,
    add: Optional[str] = None,
    remove: Optional[str] = None
) -> None

Configure logging.

Parameters:

to_stdout (Optional[bool], default: None ) –

if True, also log to stdout
level (Optional[int], default: None ) –

default log level
add (Optional[str], default: None ) –

comma-separated list of 'module name:log level' pairs; ex.: add='video:10'
remove (Optional[str], default: None ) –

comma-separated list of module names

create_dir

create_dir(path_str: str, ignore_errors: bool = False) -> Dir

Create a directory.

Parameters:

path_str (str) –

Path to the directory.
ignore_errors (bool, default: False ) –

if True, silently returns on error

Raises:

Error –

If the path already exists or the parent is not a directory.

Examples:

>>> cl.create_dir('my_dir')

Create a subdirectory:

>>> cl.create_dir('my_dir.sub_dir')

create_table

create_table(
    path_str: str,
    schema: dict[str, Any],
    *,
    primary_key: Optional[Union[str, list[str]]] = None,
    num_retained_versions: int = 10,
    comment: str = ""
) -> InsertableTable

Create a new InsertableTable.

Parameters:

path_str (str) –

Path to the table.
schema (dict[str, Any]) –

dictionary mapping column names to column types, value expressions, or to column specifications.
num_retained_versions (int, default: 10 ) –

Number of versions of the table to retain.

Returns:

InsertableTable –

The newly created table.

Raises:

Error –

if the path already exists or is invalid.

Examples:

Create a table with an int and a string column:

>>> table = cl.create_table('my_table', schema={'col1': IntType(), 'col2': StringType()})

create_view

create_view(
    path_str: str,
    base: Union[Table, DataFrame],
    *,
    schema: Optional[dict[str, Any]] = None,
    filter: Optional[Expr] = None,
    is_snapshot: bool = False,
    iterator: Optional[tuple[type[ComponentIterator], dict[str, Any]]] = None,
    num_retained_versions: int = 10,
    comment: str = "",
    ignore_errors: bool = False
) -> View

Create a new View.

Parameters:

path_str (str) –

Path to the view.
base (Union[Table, DataFrame]) –

Table (i.e., table or view or snapshot) or DataFrame to base the view on.
schema (Optional[dict[str, Any]], default: None ) –

dictionary mapping column names to column types, value expressions, or to column specifications.
filter (Optional[Expr], default: None ) –

predicate to filter rows of the base table.
is_snapshot (bool, default: False ) –

Whether the view is a snapshot.
iterator (Optional[tuple[type[ComponentIterator], dict[str, Any]]], default: None ) –

The iterator to use for this view. If specified, then this view will be a one-to-many view of the base table.
num_retained_versions (int, default: 10 ) –

Number of versions of the view to retain.
ignore_errors (bool, default: False ) –

if True, fail silently if the path already exists or is invalid.

Returns:

View –

The newly created view.

Raises:

Error –

if the path already exists or is invalid.

Examples:

Create a view with an additional int and a string column and a filter:

>>> view = cl.create_view(
    'my_view', base, schema={'col3': IntType(), 'col4': StringType()}, filter=base.col1 > 10)

Create a table snapshot:

>>> snapshot_view = cl.create_view('my_snapshot_view', base, is_snapshot=True)

Create an immutable view with additional computed columns and a filter:

>>> snapshot_view = cl.create_view(
    'my_snapshot', base, schema={'col3': base.col2 + 1}, filter=base.col1 > 10, is_snapshot=True)

drop_table

drop_table(path: str, force: bool = False, ignore_errors: bool = False) -> None

Drop a table.

Parameters:

path (str) –

Path to the table.
force (bool, default: False ) –

If True, will also drop all views or sub-views of this table.
ignore_errors (bool, default: False ) –

Whether to ignore errors if the table does not exist.

Raises:

Error –

If the path does not exist or does not designate a table and ignore_errors is False.

Examples:

>>> cl.drop_table('my_table')

get_table

get_table(path: str) -> Table

Get a handle to a table (including views and snapshots).

Parameters:

path (str) –

Path to the table.

Returns:

Table –

A InsertableTable or View object.

Raises:

Error –

If the path does not exist or does not designate a table.

Examples:

Get handle for a table in the top-level directory:

>>> table = cl.get_table('my_table')

For a table in a subdirectory:

>>> table = cl.get_table('subdir.my_table')

For a snapshot in the top-level directory:

>>> table = cl.get_table('my_snapshot')

init

init() -> None

Initializes the Pixeltable environment.

list_tables

list_tables(dir_path: str = '', recursive: bool = True) -> list[str]

List the tables in a directory.

Parameters:

dir_path (str, default: '' ) –

Path to the directory. Defaults to the root directory.
recursive (bool, default: True ) –

Whether to list tables in subdirectories as well.

Returns:

list[str] –

A list of table paths.

Raises:

Error –

If the path does not exist or does not designate a directory.

Examples:

List tables in top-level directory:

>>> cl.list_tables()
['my_table', ...]

List tables in 'dir1':

>>> cl.list_tables('dir1')
[...]

list_dirs

list_dirs(path_str: str = '', recursive: bool = True) -> list[str]

List the directories in a directory.

Parameters:

path_str (str, default: '' ) –

Path to the directory.
recursive (bool, default: True ) –

Whether to list subdirectories recursively.

Returns:

list[str] –

List of directory paths.

Raises:

Error –

If the path does not exist or does not designate a directory.

Examples:

>>> cl.list_dirs('my_dir', recursive=True)
['my_dir', 'my_dir.sub_dir1']

move

move(path: str, new_path: str) -> None

Move a schema object to a new directory and/or rename a schema object.

Parameters:

path (str) –

absolute path to the existing schema object.
new_path (str) –

absolute new path for the schema object.

Raises:

Error –

If path does not exist or new_path already exists.

Examples:

Move a table to a different directory:

>>>> cl.move('dir1.my_table', 'dir2.my_table')

Rename a table:

>>>> cl.move('dir1.my_table', 'dir1.new_name')

drop_dir

drop_dir(
    path_str: str, force: bool = False, ignore_errors: bool = False
) -> None

Remove a directory.

Parameters:

path_str (str) –

Path to the directory.

Raises:

Error –

If the path does not exist or does not designate a directory or if the directory is not empty.

Examples:

>>> cl.drop_dir('my_dir')

Remove a subdirectory:

>>> cl.drop_dir('my_dir.sub_dir')