pixeltable 0.2.20__py3-none-any.whl → 0.2.22__py3-none-any.whl

pixeltable/catalog/table.py

@@ -5,14 +5,15 @@ import builtins
 import json
 import logging
 from pathlib import Path
-from typing import TYPE_CHECKING, Any, Callable, Iterable, Literal, Optional, Set, Tuple, Type, Union, overload
+from typing import _GenericAlias  # type: ignore[attr-defined]
+from typing import TYPE_CHECKING, Any, Callable, Iterable, Literal, Optional, Set, Sequence, Tuple, Type, Union, overload
 from uuid import UUID
 
 import pandas as pd
 import pandas.io.formats.style
 import sqlalchemy as sql
 
-import pixeltable
+import pixeltable as pxt
 import pixeltable.catalog as catalog
 import pixeltable.env as env
 import pixeltable.exceptions as excs
@@ -23,7 +24,7 @@ import pixeltable.type_system as ts
 from pixeltable.utils.filecache import FileCache
 
 from .column import Column
-from .globals import _ROWID_COLUMN_NAME, UpdateStatus, is_system_column_name, is_valid_identifier
+from .globals import _ROWID_COLUMN_NAME, UpdateStatus, is_system_column_name, is_valid_identifier, MediaValidation
 from .schema_object import SchemaObject
 from .table_version import TableVersion
 from .table_version_path import TableVersionPath
@@ -35,18 +36,30 @@ _logger = logging.getLogger('pixeltable')
 
 class Table(SchemaObject):
     """
-    Base class for table objects (base tables, views, snapshots).
-
-    Every user-invoked operation that runs an ExecNode tree (directly or indirectly) needs to call
-    FileCache.emit_eviction_warnings() at the end of the operation.
+    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.
     """
+    # Every user-invoked operation that runs an ExecNode tree (directly or indirectly) needs to call
+    # FileCache.emit_eviction_warnings() at the end of the operation.
 
     def __init__(self, id: UUID, dir_id: UUID, name: str, tbl_version_path: TableVersionPath):
         super().__init__(id, name, dir_id)
         self._is_dropped = False
         self._tbl_version_path = tbl_version_path
-        from pixeltable.func import QueryTemplateFunction
-        self._queries: dict[str, QueryTemplateFunction] = {}
+        self.__query_scope = self.QueryScope(self)
+
+    class QueryScope:
+        __table: 'Table'
+        _queries: dict[str, pxt.func.QueryTemplateFunction]
+
+        def __init__(self, table: 'Table') -> None:
+            self.__table = table
+            self._queries = {}
+
+        def __getattr__(self, name: str) -> pxt.func.QueryTemplateFunction:
+            if name in self._queries:
+                return self._queries[name]
+            raise AttributeError(f'Table {self.__table._name!r} has no query with that name: {name!r}')
 
     def _move(self, new_name: str, new_dir_id: UUID) -> None:
         super()._move(new_name, new_dir_id)
@@ -59,6 +72,29 @@ class Table(SchemaObject):
             conn.execute(stmt, {'new_dir_id': new_dir_id, 'new_name': json.dumps(new_name), 'id': self._id})
 
     def get_metadata(self) -> dict[str, Any]:
+        """
+        Retrieves metadata associated with this table.
+
+        Returns:
+            A dictionary containing the metadata, in the following format:
+
+                ```python
+                {
+                    'base': None,  # If this is a view or snapshot, will contain the name of its base table
+                    'schema': {
+                        'col1': StringType(),
+                        'col2': IntType(),
+                    },
+                    'version': 22,
+                    'schema_version': 1,
+                    'comment': '',
+                    'num_retained_versions': 10,
+                    'is_view': False,
+                    'is_snapshot': False,
+                    'media_validation': 'on_write',
+                }
+                ```
+        """
         md = super().get_metadata()
         md['base'] = self._base._path if self._base is not None else None
         md['schema'] = self._schema
@@ -66,6 +102,7 @@ class Table(SchemaObject):
         md['schema_version'] = self._tbl_version.schema_version
         md['comment'] = self._comment
         md['num_retained_versions'] = self._num_retained_versions
+        md['media_validation'] = self._media_validation.name.lower()
         return md
 
     @property
@@ -85,25 +122,24 @@ class Table(SchemaObject):
         if self._is_dropped:
             raise excs.Error(f'{self._display_name()} {self._name} has been dropped')
 
-    def __getattr__(
-            self, name: str
-    ) -> Union['pixeltable.exprs.ColumnRef', 'pixeltable.func.QueryTemplateFunction']:
-        """Return a ColumnRef or QueryTemplateFunction for the given name.
+    def __getattr__(self, name: str) -> 'pxt.exprs.ColumnRef':
+        """Return a ColumnRef for the given name.
         """
-        if name in self._queries:
-            return self._queries[name]
         return getattr(self._tbl_version_path, name)
 
-    def __getitem__(
-            self, index: object
-    ) -> Union[
-        'pixeltable.func.QueryTemplateFunction', 'pixeltable.exprs.ColumnRef', 'pixeltable.DataFrame'
-    ]:
+    @overload
+    def __getitem__(self, name: str) -> 'pxt.exprs.ColumnRef': ...
+
+    @overload
+    def __getitem__(self, index: Union[exprs.Expr, Sequence[exprs.Expr]]) -> 'pxt.DataFrame': ...
+
+    def __getitem__(self, index):
         """Return a ColumnRef or QueryTemplateFunction for the given name, or a DataFrame for the given slice.
         """
-        if isinstance(index, str) and index in self._queries:
-            return self._queries[index]
-        return self._tbl_version_path.__getitem__(index)
+        if isinstance(index, str):
+            return getattr(self, index)
+        else:
+            return self._df()[index]
 
     def list_views(self, *, recursive: bool = True) -> list[str]:
         """
@@ -112,6 +148,9 @@ class Table(SchemaObject):
         Args:
             recursive: If `False`, returns only the immediate successor views of this `Table`. If `True`, returns
                 all sub-views (including views of views, etc.)
+
+        Returns:
+            A list of view paths.
         """
         return [t._path for t in self._get_views(recursive=recursive)]
 
@@ -122,60 +161,55 @@ class Table(SchemaObject):
         else:
             return dependents
 
-    def _df(self) -> 'pixeltable.dataframe.DataFrame':
+    def _df(self) -> 'pxt.dataframe.DataFrame':
         """Return a DataFrame for this table.
         """
         # local import: avoid circular imports
-        from pixeltable.dataframe import DataFrame
-        return DataFrame(self._tbl_version_path)
+        return pxt.DataFrame(self._tbl_version_path)
 
-    def select(self, *items: Any, **named_items: Any) -> 'pixeltable.DataFrame':
+    @property
+    def queries(self) -> 'Table.QueryScope':
+        return self.__query_scope
+
+    def select(self, *items: Any, **named_items: Any) -> 'pxt.DataFrame':
         """Return a [`DataFrame`][pixeltable.DataFrame] for this table."""
-        # local import: avoid circular imports
-        from pixeltable.dataframe import DataFrame
-        return DataFrame(self._tbl_version_path).select(*items, **named_items)
+        return self._df().select(*items, **named_items)
 
-    def where(self, pred: 'exprs.Expr') -> 'pixeltable.DataFrame':
+    def where(self, pred: 'exprs.Expr') -> 'pxt.DataFrame':
         """Return a [`DataFrame`][pixeltable.DataFrame] for this table."""
-        # local import: avoid circular imports
-        from pixeltable.dataframe import DataFrame
-        return DataFrame(self._tbl_version_path).where(pred)
+        return self._df().where(pred)
 
-    def order_by(self, *items: 'exprs.Expr', asc: bool = True) -> 'pixeltable.DataFrame':
+    def order_by(self, *items: 'exprs.Expr', asc: bool = True) -> 'pxt.DataFrame':
         """Return a [`DataFrame`][pixeltable.DataFrame] for this table."""
-        # local import: avoid circular imports
-        from pixeltable.dataframe import DataFrame
-        return DataFrame(self._tbl_version_path).order_by(*items, asc=asc)
+        return self._df().order_by(*items, asc=asc)
 
-    def group_by(self, *items: 'exprs.Expr') -> 'pixeltable.DataFrame':
+    def group_by(self, *items: 'exprs.Expr') -> 'pxt.DataFrame':
         """Return a [`DataFrame`][pixeltable.DataFrame] for this table."""
-        from pixeltable.dataframe import DataFrame
-        return DataFrame(self._tbl_version_path).group_by(*items)
+        return self._df().group_by(*items)
 
-    def limit(self, n: int) -> 'pixeltable.DataFrame':
-        from pixeltable.dataframe import DataFrame
-        return DataFrame(self._tbl_version_path).limit(n)
+    def limit(self, n: int) -> 'pxt.DataFrame':
+        return self._df().limit(n)
 
-    def collect(self) -> 'pixeltable.dataframe.DataFrameResultSet':
+    def collect(self) -> 'pxt.dataframe.DataFrameResultSet':
         """Return rows from this table."""
         return self._df().collect()
 
     def show(
             self, *args, **kwargs
-    ) -> 'pixeltable.dataframe.DataFrameResultSet':
+    ) -> 'pxt.dataframe.DataFrameResultSet':
         """Return rows from this table.
         """
         return self._df().show(*args, **kwargs)
 
     def head(
             self, *args, **kwargs
-    ) -> 'pixeltable.dataframe.DataFrameResultSet':
+    ) -> 'pxt.dataframe.DataFrameResultSet':
         """Return the first n rows inserted into this table."""
         return self._df().head(*args, **kwargs)
 
     def tail(
             self, *args, **kwargs
-    ) -> 'pixeltable.dataframe.DataFrameResultSet':
+    ) -> 'pxt.dataframe.DataFrameResultSet':
         """Return the last n rows inserted into this table."""
         return self._df().tail(*args, **kwargs)
 
@@ -191,7 +225,7 @@ class Table(SchemaObject):
     @property
     def _query_names(self) -> list[str]:
         """Return the names of the registered queries for this table."""
-        return list(self._queries.keys())
+        return list(self.__query_scope._queries.keys())
 
     @property
     def _base(self) -> Optional['Table']:
@@ -212,11 +246,15 @@ class Table(SchemaObject):
     def _num_retained_versions(self):
         return self._tbl_version.num_retained_versions
 
+    @property
+    def _media_validation(self) -> MediaValidation:
+        return self._tbl_version.media_validation
+
     def _description(self) -> pd.DataFrame:
         cols = self._tbl_version_path.columns()
         df = pd.DataFrame({
             'Column Name': [c.name for c in cols],
-            'Type': [str(c.col_type) for c in cols],
+            'Type': [c.col_type._to_str(as_schema=True) for c in cols],
             'Computed With': [c.value_expr.display_str(inline=False) if c.value_expr is not None else '' for c in cols],
         })
         return df
@@ -239,7 +277,7 @@ class Table(SchemaObject):
             from IPython.display import display
             display(self._description_html())
         else:
-            print(self.__repr__())
+            print(repr(self))
 
     # TODO: Display comments in _repr_html()
     def __repr__(self) -> str:
@@ -267,75 +305,77 @@ class Table(SchemaObject):
         """Return a PyTorch Dataset for this table.
             See DataFrame.to_pytorch_dataset()
         """
-        from pixeltable.dataframe import DataFrame
-        return DataFrame(self._tbl_version_path).to_pytorch_dataset(image_format=image_format)
+        return self._df().to_pytorch_dataset(image_format=image_format)
 
     def to_coco_dataset(self) -> Path:
         """Return the path to a COCO json file for this table.
             See DataFrame.to_coco_dataset()
         """
-        from pixeltable.dataframe import DataFrame
-        return DataFrame(self._tbl_version_path).to_coco_dataset()
+        return self._df().to_coco_dataset()
 
     def __setitem__(self, col_name: str, spec: Union[ts.ColumnType, exprs.Expr]) -> None:
         """
         Adds a column to the table. This is an alternate syntax for `add_column()`; the meaning of
 
-        >>> tbl['new_col'] = IntType()
+        >>> tbl['new_col'] = pxt.Int
 
         is exactly equivalent to
 
-        >>> tbl.add_column(new_col=IntType())
+        >>> tbl.add_column(new_col=pxt.Int)
 
         For details, see the documentation for [`add_column()`][pixeltable.catalog.Table.add_column].
         """
         if not isinstance(col_name, str):
             raise excs.Error(f'Column name must be a string, got {type(col_name)}')
-        if not isinstance(spec, (ts.ColumnType, exprs.Expr)):
-            raise excs.Error(f'Column spec must be a ColumnType or an Expr, got {type(spec)}')
-        self.add_column(type=None, stored=None, print_stats=False, **{col_name: spec})
+        if not isinstance(spec, (ts.ColumnType, exprs.Expr, type, _GenericAlias)):
+            raise excs.Error(f'Column spec must be a ColumnType, Expr, or type, got {type(spec)}')
+        self.add_column(type=None, stored=None, print_stats=False, on_error='abort', **{col_name: spec})
 
     def add_column(
             self,
             *,
-            type: Optional[ts.ColumnType] = None,
+            type: Union[ts.ColumnType, builtins.type, _GenericAlias, None] = None,
             stored: Optional[bool] = None,
             print_stats: bool = False,
-            **kwargs: Union[ts.ColumnType, exprs.Expr, Callable]
+            on_error: Literal['abort', 'ignore'] = 'abort',
+            **kwargs: Union[ts.ColumnType, builtins.type, _GenericAlias, exprs.Expr, Callable]
     ) -> UpdateStatus:
         """
         Adds a column to the table.
 
         Args:
-            kwargs: Exactly one keyword argument of the form ``column-name=type|value-expression``.
-            type: The type of the column. Only valid and required if ``value-expression`` is a Callable.
+            kwargs: Exactly one keyword argument of the form `column_name=type` or `column_name=expression`.
+            type: The type of the column. Only valid and required if `value-expression` is a Callable.
             stored: Whether the column is materialized and stored or computed on demand. Only valid for image columns.
-            print_stats: If ``True``, print execution metrics.
+            print_stats: If `True`, print execution metrics during evaluation.
+            on_error: Determines the behavior if an error occurs while evaluating the column expression for at least one
+                row.
+
+                - If `on_error='abort'`, then an exception will be raised and the column will not be added.
+                - If `on_error='ignore'`, then execution will continue and the column will be added. Any rows
+                  with errors will have a `None` value for the column, with information about the error stored in the
+                  corresponding `tbl.col_name.errortype` and `tbl.col_name.errormsg` fields.
 
         Returns:
-            execution status
+            Information about the execution status of the operation.
 
         Raises:
             Error: If the column name is invalid or already exists.
 
         Examples:
-            Add an int column with ``None`` values:
+            Add an int column:
 
-            >>> tbl.add_column(new_col=IntType())
+            >>> tbl.add_column(new_col=pxt.Int)
 
             Alternatively, this can also be expressed as:
 
-            >>> tbl['new_col'] = IntType()
+            >>> tbl['new_col'] = pxt.Int
 
-            For a table with int column ``int_col``, add a column that is the factorial of ``int_col``. The names of
+            For a table with int column `int_col`, add a column that is the factorial of ``int_col``. The names of
             the parameters of the Callable must correspond to existing column names (the column values are then passed
             as arguments to the Callable). In this case, the column type needs to be specified explicitly:
 
-            >>> tbl.add_column(factorial=lambda int_col: math.factorial(int_col), type=IntType())
-
-            Alternatively, this can also be expressed as:
-
-            >>> tbl['factorial'] = {'value': lambda int_col: math.factorial(int_col), 'type': IntType()}
+            >>> tbl.add_column(factorial=lambda int_col: math.factorial(int_col), type=pxt.Int)
 
             For a table with an image column ``frame``, add an image column ``rotated`` that rotates the image by
             90 degrees. In this case, the column type is inferred from the expression. Also, the column is not stored
@@ -347,13 +387,9 @@ class Table(SchemaObject):
 
             >>> tbl['rotated'] = tbl.frame.rotate(90)
 
-            Do the same, but now the column is stored:
-
-            >>> tbl.add_column(rotated=tbl.frame.rotate(90), stored=True)
+            Do the same, but now the column is unstored:
 
-            Alternatively, this can also be expressed as:
-
-            >>> tbl['rotated'] = {'value': tbl.frame.rotate(90), 'stored': True}
+            >>> tbl.add_column(rotated=tbl.frame.rotate(90), stored=False)
         """
         self._check_is_dropped()
         # verify kwargs and construct column schema dict
@@ -365,26 +401,25 @@ class Table(SchemaObject):
         col_name, spec = next(iter(kwargs.items()))
         if not is_valid_identifier(col_name):
             raise excs.Error(f'Invalid column name: {col_name!r}')
-        if isinstance(spec, (ts.ColumnType, exprs.Expr)) and type is not None:
+        if isinstance(spec, (ts.ColumnType, builtins.type, _GenericAlias, exprs.Expr)) and type is not None:
             raise excs.Error(f'add_column(): keyword argument "type" is redundant')
 
         col_schema: dict[str, Any] = {}
-        if isinstance(spec, ts.ColumnType):
-            col_schema['type'] = spec
+        if isinstance(spec, (ts.ColumnType, builtins.type, _GenericAlias)):
+            col_schema['type'] = ts.ColumnType.normalize_type(spec, nullable_default=True)
         else:
             col_schema['value'] = spec
         if type is not None:
-            col_schema['type'] = type
+            col_schema['type'] = ts.ColumnType.normalize_type(type, nullable_default=True)
         if stored is not None:
             col_schema['stored'] = stored
 
         new_col = self._create_columns({col_name: col_schema})[0]
         self._verify_column(new_col, set(self._schema.keys()), set(self._query_names))
-        status = self._tbl_version.add_column(new_col, print_stats=print_stats)
+        status = self._tbl_version.add_column(new_col, print_stats=print_stats, on_error=on_error)
         FileCache.get().emit_eviction_warnings()
         return status
 
-
     @classmethod
     def _validate_column_spec(cls, name: str, spec: dict[str, Any]) -> None:
         """Check integrity of user-supplied Column spec
@@ -393,7 +428,7 @@ class Table(SchemaObject):
         (on account of containing Python Callables or Exprs).
         """
         assert isinstance(spec, dict)
-        valid_keys = {'type', 'value', 'stored'}
+        valid_keys = {'type', 'value', 'stored', 'media_validation'}
         has_type = False
         for k in spec.keys():
             if k not in valid_keys:
@@ -401,8 +436,8 @@ class Table(SchemaObject):
 
         if 'type' in spec:
             has_type = True
-            if not isinstance(spec['type'], ts.ColumnType):
-                raise excs.Error(f'Column {name}: "type" must be a ColumnType, got {spec["type"]}')
+            if not isinstance(spec['type'], (ts.ColumnType, type, _GenericAlias)):
+                raise excs.Error(f'Column {name}: "type" must be a type or ColumnType, got {spec["type"]}')
 
         if 'value' in spec:
             value_spec = spec['value']
@@ -420,6 +455,9 @@ class Table(SchemaObject):
                 if 'type' in spec:
                     raise excs.Error(f'Column {name}: "type" is redundant if value is a Pixeltable expression')
 
+        if 'media_validation' in spec:
+            _ = catalog.MediaValidation.validated(spec['media_validation'], f'Column {name}: media_validation')
+
         if 'stored' in spec and not isinstance(spec['stored'], bool):
             raise excs.Error(f'Column {name}: "stored" must be a bool, got {spec["stored"]}')
         if not has_type:
@@ -433,31 +471,38 @@ class Table(SchemaObject):
             col_type: Optional[ts.ColumnType] = None
             value_expr: Optional[exprs.Expr] = None
             primary_key: Optional[bool] = None
+            media_validation: Optional[catalog.MediaValidation] = None
             stored = True
 
-            if isinstance(spec, ts.ColumnType):
-                # TODO: create copy
-                col_type = spec
+            if isinstance(spec, (ts.ColumnType, type, _GenericAlias)):
+                col_type = ts.ColumnType.normalize_type(spec, nullable_default=True)
             elif isinstance(spec, exprs.Expr):
                 # create copy so we can modify it
                 value_expr = spec.copy()
             elif callable(spec):
-                raise excs.Error((
+                raise excs.Error(
                     f'Column {name} computed with a Callable: specify using a dictionary with '
-                    f'the "value" and "type" keys (e.g., "{name}": {{"value": <Callable>, "type": IntType()}})'
-                ))
+                    f'the "value" and "type" keys (e.g., "{name}": {{"value": <Callable>, "type": pxt.Int}})'
+                )
             elif isinstance(spec, dict):
                 cls._validate_column_spec(name, spec)
-                col_type = spec.get('type')
+                if 'type' in spec:
+                    col_type = ts.ColumnType.normalize_type(spec['type'], nullable_default=True)
                 value_expr = spec.get('value')
                 if value_expr is not None and isinstance(value_expr, exprs.Expr):
                     # create copy so we can modify it
                     value_expr = value_expr.copy()
                 stored = spec.get('stored', True)
                 primary_key = spec.get('primary_key')
+                media_validation_str = spec.get('media_validation')
+                media_validation = (
+                    catalog.MediaValidation[media_validation_str.upper()] if media_validation_str is not None
+                    else None
+                )
 
             column = Column(
-                name, col_type=col_type, computed_with=value_expr, stored=stored, is_pk=primary_key)
+                name, col_type=col_type, computed_with=value_expr, stored=stored, is_pk=primary_key,
+                media_validation=media_validation)
             columns.append(column)
         return columns
 
@@ -496,12 +541,13 @@ class Table(SchemaObject):
             name: The name of the column to drop.
 
         Raises:
-            Error: If the column does not exist or if it is referenced by a computed column.
+            Error: If the column does not exist or if it is referenced by a dependent computed column.
 
         Examples:
-            Drop column ``factorial``:
+            Drop the column `col` from the table `my_table`:
 
-            >>> tbl.drop_column('factorial')
+            >>> tbl = pxt.get_table('my_table')
+            ... tbl.drop_column('col')
         """
         self._check_is_dropped()
 
@@ -544,43 +590,59 @@ class Table(SchemaObject):
             new_name: The new name of the column.
 
         Raises:
-            Error: If the column does not exist or if the new name is invalid or already exists.
+            Error: If the column does not exist, or if the new name is invalid or already exists.
 
         Examples:
-            Rename column ``factorial`` to ``fac``:
+            Rename the column `col1` to `col2` of the table `my_table`:
 
-            >>> tbl.rename_column('factorial', 'fac')
+            >>> tbl = pxt.get_table('my_table')
+            ... tbl.rename_column('col1', 'col2')
         """
         self._check_is_dropped()
         self._tbl_version.rename_column(old_name, new_name)
 
     def add_embedding_index(
             self, col_name: str, *, idx_name: Optional[str] = None,
-            string_embed: Optional[pixeltable.Function] = None, image_embed: Optional[pixeltable.Function] = None,
+            string_embed: Optional[pxt.Function] = None, image_embed: Optional[pxt.Function] = None,
             metric: str = 'cosine'
     ) -> None:
-        """Add an index to the table.
+        """
+        Add an embedding index to the table. Once the index is added, it will be automatically kept up to data as new
+        rows are inserted into the table.
+
+        Indices are currently supported only for `String` and `Image` columns. The index must specify, at
+        minimum, an embedding of the appropriate type (string or image). It may optionally specify _both_ a string
+        and image embedding (into the same vector space); in particular, this can be used to provide similarity search
+        of text over an image column.
 
         Args:
-            col_name: name of column to index
-            idx_name: name of index, which needs to be unique for the table; if not provided, a name will be generated
-            string_embed: function to embed text; required if the column is a text column
-            image_embed: function to embed images; required if the column is an image column
-            metric: distance metric to use for the index; one of 'cosine', 'ip', 'l2'; default is 'cosine'
+            col_name: The name of column to index; must be a `String` or `Image` column.
+            idx_name: The name of index. If not specified, a name such as `'idx0'` will be generated automatically.
+                If specified, the name must be unique for this table.
+            string_embed: A function to embed text; required if the column is a `String` column.
+            image_embed: A function to embed images; required if the column is an `Image` column.
+            metric: Distance metric to use for the index; one of `'cosine'`, `'ip'`, or `'l2'`;
+                the default is `'cosine'`.
 
         Raises:
-            Error: If an index with that name already exists for the table or if the column does not exist.
+            Error: If an index with that name already exists for the table, or if the specified column does not exist.
 
         Examples:
-            Add an index to the ``img`` column:
+            Add an index to the `img` column of the table `my_table`:
 
-            >>> tbl.add_embedding_index('img', image_embed=...)
+            >>> tbl = pxt.get_table('my_table')
+            ... tbl.add_embedding_index('img', image_embed=my_image_func)
 
-            Add another index to the ``img`` column, using the inner product as the distance metric,
-            and with a specific name; ``string_embed`` is also specified in order to search with text:
+            Add another index to the `img` column, using the inner product as the distance metric,
+            and with a specific name; `string_embed` is also specified in order to search with text:
 
             >>> tbl.add_embedding_index(
-                'img', idx_name='clip_idx', image_embed=..., string_embed=..., metric='ip')
+            ...     'img',
+            ...     idx_name='clip_idx',
+            ...     image_embed=my_image_func,
+            ...     string_embed=my_string_func,
+            ...     metric='ip'
+            ... )
         """
         if self._tbl_version_path.is_snapshot():
             raise excs.Error('Cannot add an index to a snapshot')
@@ -599,37 +661,50 @@ class Table(SchemaObject):
         FileCache.get().emit_eviction_warnings()
 
     def drop_embedding_index(self, *, column_name: Optional[str] = None, idx_name: Optional[str] = None) -> None:
-        """Drop an embedding index from the table.
+        """
+        Drop an embedding index from the table. Either a column name or an index name (but not both) must be
+        specified. If a column name is specified, it must be a column containing exactly one embedding index;
+        otherwise the specific index name must be provided instead.
 
         Args:
-            column_name: The name of the column whose embedding index to drop. Invalid if the column has multiple
+            column_name: The name of the column from which to drop the index. Invalid if the column has multiple
                 embedding indices.
             idx_name: The name of the index to drop.
 
         Raises:
-            Error: If the index does not exist.
+            Error: If `column_name` is specified, but the column does not exist, or it contains no embedding
+                indices or multiple embedding indices.
+            Error: If `idx_name` is specified, but the index does not exist or is not an embedding index.
 
         Examples:
-            Drop embedding index on the ``img`` column:
+            Drop the embedding index on the `img` column of the table `my_table`:
 
-            >>> tbl.drop_embedding_index(column_name='img')
+            >>> tbl = pxt.get_table('my_table')
+            ... tbl.drop_embedding_index(column_name='img')
         """
         self._drop_index(column_name=column_name, idx_name=idx_name, _idx_class=index.EmbeddingIndex)
 
     def drop_index(self, *, column_name: Optional[str] = None, idx_name: Optional[str] = None) -> None:
-        """Drop an index from the table.
+        """
+        Drop an index from the table. Either a column name or an index name (but not both) must be
+        specified. If a column name is specified, it must be a column containing exactly one index;
+        otherwise the specific index name must be provided instead.
 
         Args:
-            column_name: The name of the column whose index to drop. Invalid if the column has multiple indices.
+            column_name: The name of the column from which to drop the index. Invalid if the column has multiple
+                indices.
             idx_name: The name of the index to drop.
 
         Raises:
-            Error: If the index does not exist.
+            Error: If `column_name` is specified, but the column does not exist, or it contains no
+                indices or multiple indices.
+            Error: If `idx_name` is specified, but the index does not exist.
 
         Examples:
-            Drop index on the ``img`` column:
+            Drop the index on the `img` column of the table `my_table`:
 
-            >>> tbl.drop_index(column_name='img')
+            >>> tbl = pxt.get_table('my_table')
+            ... tbl.drop_index(column_name='img')
         """
         self._drop_index(column_name=column_name, idx_name=idx_name)
 
@@ -682,7 +757,7 @@ class Table(SchemaObject):
         To insert multiple rows at a time:
         ``insert(rows: Iterable[dict[str, Any]], /, *, print_stats: bool = False, fail_on_exception: bool = True)``
 
-        To insert just a single row, you can use the more convenient syntax:
+        To insert just a single row, you can use the more concise syntax:
         ``insert(*, print_stats: bool = False, fail_on_exception: bool = True, **kwargs: Any)``
 
         Args:
@@ -698,24 +773,31 @@ class Table(SchemaObject):
                 If ``True``, raise an exception that aborts the insert.
 
         Returns:
-            execution status
+            An [`UpdateStatus`][pixeltable.UpdateStatus] object containing information about the update.
 
         Raises:
-            Error: if a row does not match the table schema or contains values for computed columns
+            Error: If one of the following conditions occurs:
+
+                - The table is a view or snapshot.
+                - The table has been dropped.
+                - One of the rows being inserted does not conform to the table schema.
+                - An error occurs during processing of computed columns, and `fail_on_exception=True`.
 
         Examples:
-            Insert two rows into a table with three int columns ``a``, ``b``, and ``c``. Column ``c`` is nullable.
+            Insert two rows into the table `my_table` with three int columns ``a``, ``b``, and ``c``.
+            Column ``c`` is nullable:
 
-            >>> tbl.insert([{'a': 1, 'b': 1, 'c': 1}, {'a': 2, 'b': 2}])
+            >>> tbl = pxt.get_table('my_table')
+            ... tbl.insert([{'a': 1, 'b': 1, 'c': 1}, {'a': 2, 'b': 2}])
 
-            Insert a single row into a table with three int columns ``a``, ``b``, and ``c``.
+            Insert a single row using the alternative syntax:
 
-            >>> tbl.insert(a=1, b=1, c=1)
+            >>> tbl.insert(a=3, b=3, c=3)
         """
         raise NotImplementedError
 
     def update(
-            self, value_spec: dict[str, Any], where: Optional['pixeltable.exprs.Expr'] = None, cascade: bool = True
+            self, value_spec: dict[str, Any], where: Optional['pxt.exprs.Expr'] = None, cascade: bool = True
     ) -> UpdateStatus:
         """Update rows in this table.
 
@@ -807,7 +889,7 @@ class Table(SchemaObject):
         FileCache.get().emit_eviction_warnings()
         return status
 
-    def delete(self, where: Optional['pixeltable.exprs.Expr'] = None) -> UpdateStatus:
+    def delete(self, where: Optional['pxt.exprs.Expr'] = None) -> UpdateStatus:
         """Delete rows in this table.
 
         Args:
@@ -836,17 +918,17 @@ class Table(SchemaObject):
         self._tbl_version.revert()
 
     @overload
-    def query(self, py_fn: Callable) -> 'pixeltable.func.QueryTemplateFunction': ...
+    def query(self, py_fn: Callable) -> 'pxt.func.QueryTemplateFunction': ...
 
     @overload
     def query(
             self, *, param_types: Optional[list[ts.ColumnType]] = None
-    ) -> Callable[[Callable], 'pixeltable.func.QueryTemplateFunction']: ...
+    ) -> Callable[[Callable], 'pxt.func.QueryTemplateFunction']: ...
 
     def query(self, *args: Any, **kwargs: Any) -> Any:
         def make_query_template(
                 py_fn: Callable, param_types: Optional[list[ts.ColumnType]]
-        ) -> 'pixeltable.func.QueryTemplateFunction':
+        ) -> 'pxt.func.QueryTemplateFunction':
             if py_fn.__module__ != '__main__' and py_fn.__name__.isidentifier():
                 # this is a named function in a module
                 function_path = f'{py_fn.__module__}.{py_fn.__qualname__}'
@@ -855,12 +937,11 @@ class Table(SchemaObject):
             query_name = py_fn.__name__
             if query_name in self._schema.keys():
                 raise excs.Error(f'Query name {query_name!r} conflicts with existing column')
-            if query_name in self._queries:
+            if query_name in self.__query_scope._queries and function_path is not None:
                 raise excs.Error(f'Duplicate query name: {query_name!r}')
-            import pixeltable.func as func
-            query_fn = func.QueryTemplateFunction.create(
+            query_fn = pxt.func.QueryTemplateFunction.create(
                 py_fn, param_types=param_types, path=function_path, name=query_name)
-            self._queries[query_name] = query_fn
+            self.__query_scope._queries[query_name] = query_fn
             return query_fn
 
             # TODO: verify that the inferred return type matches that of the template
@@ -877,7 +958,7 @@ class Table(SchemaObject):
     def external_stores(self) -> list[str]:
         return list(self._tbl_version.external_stores.keys())
 
-    def _link_external_store(self, store: 'pixeltable.io.ExternalStore') -> None:
+    def _link_external_store(self, store: 'pxt.io.ExternalStore') -> None:
         """
         Links the specified `ExternalStore` to this table.
         """
@@ -932,7 +1013,7 @@ class Table(SchemaObject):
             *,
             export_data: bool = True,
             import_data: bool = True
-    ) -> 'pixeltable.io.SyncStatus':
+    ) -> 'pxt.io.SyncStatus':
         """
         Synchronizes this table with its linked external stores.
 
@@ -954,9 +1035,7 @@ class Table(SchemaObject):
             if store not in all_stores:
                 raise excs.Error(f'Table `{self._name}` has no external store with that name: {store}')
 
-        from pixeltable.io import SyncStatus
-
-        sync_status = SyncStatus.empty()
+        sync_status = pxt.io.SyncStatus.empty()
         for store in stores:
             store_obj = self._tbl_version.external_stores[store]
             store_sync_status = store_obj.sync(self, export_data=export_data, import_data=import_data)