pixeltable 0.4.2__py3-none-any.whl → 0.4.4__py3-none-any.whl

pixeltable/catalog/table_version_path.py

@@ -76,7 +76,7 @@ class TableVersionPath:
         elif self._cached_tbl_version is not None:
             return
 
-        with Catalog.get().begin_xact(for_write=False):
+        with Catalog.get().begin_xact(tbl_id=self.tbl_version.id, for_write=False):
             self._cached_tbl_version = self.tbl_version.get()
 
     def clear_cached_md(self) -> None:

pixeltable/catalog/tbl_ops.py

@@ -0,0 +1,44 @@
+# This file contains all dataclasses related to schema.PendingTableOp:
+# - TableOp: the container for each log entry
+# - <>Op: the actual operation, which is performed by TableVersion.exec_op(); each <>Op class contains
+#   enough information for exec_op() to perform the operation without having to reference data outside of
+#   TableVersion
+
+import dataclasses
+from typing import Any, Optional
+
+
+@dataclasses.dataclass
+class CreateStoreTableOp:
+    pass
+
+
+@dataclasses.dataclass
+class LoadViewOp:
+    view_path: dict[str, Any]  # needed to create the view load plan
+
+
+@dataclasses.dataclass
+class DeleteTableMdOp:
+    pass
+
+
+@dataclasses.dataclass
+class DeleteTableMediaFilesOp:
+    pass
+
+
+@dataclasses.dataclass
+class DropStoreTableOp:
+    pass
+
+
+@dataclasses.dataclass
+class TableOp:
+    tbl_id: str  # uuid.UUID
+    op_sn: int  # sequence number within the update operation; [0, num_ops)
+    num_ops: int  # total number of ops forming the update operation
+    needs_xact: bool  # if True, op must be run as part of a transaction
+
+    create_store_table_op: Optional[CreateStoreTableOp] = None
+    load_view_op: Optional[LoadViewOp] = None

pixeltable/catalog/update_status.py

@@ -0,0 +1,179 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from IPython.lib.pretty import RepresentationPrinter
+
+
+@dataclass(frozen=True)
+class RowCountStats:
+    """
+    Statistics about the counts of rows affected by a table operation.
+    """
+
+    ins_rows: int = 0  # rows inserted
+    del_rows: int = 0  # rows deleted
+    upd_rows: int = 0  # rows updated
+    num_excs: int = 0  # total number of exceptions
+    # TODO: disambiguate what this means: # of slots computed or # of columns computed?
+    computed_values: int = 0  # number of computed values (e.g., computed columns) affected by the operation
+
+    @property
+    def num_rows(self) -> int:
+        return self.ins_rows + self.del_rows + self.upd_rows
+
+    def insert_to_update(self) -> 'RowCountStats':
+        """
+        Convert insert row count stats to update row count stats.
+        This is used when an insert operation is treated as an update.
+        """
+        return RowCountStats(
+            ins_rows=0,
+            del_rows=self.del_rows,
+            upd_rows=self.upd_rows + self.ins_rows,
+            num_excs=self.num_excs,
+            computed_values=self.computed_values,
+        )
+
+    def __add__(self, other: 'RowCountStats') -> 'RowCountStats':
+        """
+        Add the stats from two RowCountStats objects together.
+        """
+        return RowCountStats(
+            ins_rows=self.ins_rows + other.ins_rows,
+            del_rows=self.del_rows + other.del_rows,
+            upd_rows=self.upd_rows + other.upd_rows,
+            num_excs=self.num_excs + other.num_excs,
+            computed_values=self.computed_values + other.computed_values,
+        )
+
+
+@dataclass(frozen=True)
+class UpdateStatus:
+    """
+    Information about changes to table data or table schema
+    """
+
+    updated_cols: list[str] = field(default_factory=list)
+    cols_with_excs: list[str] = field(default_factory=list)
+
+    # stats for the rows affected by the operation
+    row_count_stats: RowCountStats = field(default_factory=RowCountStats)
+
+    # stats for changes cascaded to other tables
+    cascade_row_count_stats: RowCountStats = field(default_factory=RowCountStats)
+
+    # stats for the rows affected by the operation in an external store
+    ext_row_count_stats: RowCountStats = field(default_factory=RowCountStats)
+
+    @property
+    def num_rows(self) -> int:
+        return self.row_count_stats.num_rows + self.cascade_row_count_stats.num_rows
+
+    @property
+    def num_excs(self) -> int:
+        return self.row_count_stats.num_excs + self.cascade_row_count_stats.num_excs
+
+    @property
+    def num_computed_values(self) -> int:
+        return self.row_count_stats.computed_values + self.cascade_row_count_stats.computed_values
+
+    def insert_to_update(self) -> 'UpdateStatus':
+        """
+        Convert the update status from an insert operation to an update operation.
+        This is used when an insert operation is treated as an update.
+        """
+        return UpdateStatus(
+            updated_cols=self.updated_cols,
+            cols_with_excs=self.cols_with_excs,
+            row_count_stats=self.row_count_stats.insert_to_update(),
+            cascade_row_count_stats=self.cascade_row_count_stats.insert_to_update(),
+            ext_row_count_stats=self.ext_row_count_stats,
+        )
+
+    def to_cascade(self) -> 'UpdateStatus':
+        """
+        Convert the update status to a cascade update status.
+        This is used when an operation cascades changes to other tables.
+        """
+        return UpdateStatus(
+            updated_cols=self.updated_cols,
+            cols_with_excs=self.cols_with_excs,
+            row_count_stats=RowCountStats(),
+            cascade_row_count_stats=self.cascade_row_count_stats + self.row_count_stats,
+            ext_row_count_stats=self.ext_row_count_stats,
+        )
+
+    def __add__(self, other: 'UpdateStatus') -> UpdateStatus:
+        """
+        Add the update status from two UpdateStatus objects together.
+        """
+        return UpdateStatus(
+            updated_cols=list(dict.fromkeys(self.updated_cols + other.updated_cols)),
+            cols_with_excs=list(dict.fromkeys(self.cols_with_excs + other.cols_with_excs)),
+            row_count_stats=self.row_count_stats + other.row_count_stats,
+            cascade_row_count_stats=self.cascade_row_count_stats + other.cascade_row_count_stats,
+            ext_row_count_stats=self.ext_row_count_stats + other.ext_row_count_stats,
+        )
+
+    @property
+    def insert_msg(self) -> str:
+        """Return a message describing the results of an insert operation."""
+        if self.num_excs == 0:
+            cols_with_excs_str = ''
+        else:
+            cols_with_excs_str = (
+                f' across {len(self.cols_with_excs)} column{"" if len(self.cols_with_excs) == 1 else "s"}'
+            )
+            cols_with_excs_str += f' ({", ".join(self.cols_with_excs)})'
+        msg = (
+            f'Inserted {self.num_rows} row{"" if self.num_rows == 1 else "s"} '
+            f'with {self.num_excs} error{"" if self.num_excs == 1 else "s"}{cols_with_excs_str}.'
+        )
+        return msg
+
+    @classmethod
+    def __cnt_str(cls, cnt: int, item: str) -> str:
+        assert cnt > 0
+        return f'{cnt} {item}{"" if cnt == 1 else "s"}'
+
+    def _repr_pretty_(self, p: 'RepresentationPrinter', cycle: bool) -> None:
+        messages = []
+        # Combine row count stats and cascade row count stats
+        stats = self.row_count_stats + self.cascade_row_count_stats
+        if stats.ins_rows > 0:
+            messages.append(f'{self.__cnt_str(stats.ins_rows, "row")} inserted')
+        if stats.del_rows > 0:
+            messages.append(f'{self.__cnt_str(stats.del_rows, "row")} deleted')
+        if stats.upd_rows > 0:
+            messages.append(f'{self.__cnt_str(stats.upd_rows, "row")} updated')
+        if stats.computed_values > 0:
+            messages.append(f'{self.__cnt_str(stats.computed_values, "value")} computed')
+        if stats.num_excs > 0:
+            messages.append(self.__cnt_str(stats.num_excs, 'exception'))
+        p.text(', '.join(messages) + '.' if len(messages) > 0 else 'No rows affected.')
+
+    @property
+    def pxt_rows_updated(self) -> int:
+        """
+        Returns the number of Pixeltable rows that were updated as a result of the operation.
+        """
+        return (self.row_count_stats + self.cascade_row_count_stats).upd_rows
+
+    @property
+    def external_rows_updated(self) -> int:
+        return self.ext_row_count_stats.upd_rows
+
+    @property
+    def external_rows_created(self) -> int:
+        return self.ext_row_count_stats.ins_rows
+
+    @property
+    def external_rows_deleted(self) -> int:
+        return self.ext_row_count_stats.del_rows
+
+    @property
+    def ext_num_rows(self) -> int:
+        return self.ext_row_count_stats.num_rows

pixeltable/catalog/view.py

@@ -9,7 +9,6 @@ import pixeltable.exceptions as excs
 import pixeltable.metadata.schema as md_schema
 import pixeltable.type_system as ts
 from pixeltable import catalog, exprs, func
-from pixeltable.env import Env
 from pixeltable.iterators import ComponentIterator
 
 if TYPE_CHECKING:
@@ -17,11 +16,13 @@ if TYPE_CHECKING:
 
 
 from .column import Column
-from .globals import _POS_COLUMN_NAME, MediaValidation, UpdateStatus
+from .globals import _POS_COLUMN_NAME, MediaValidation
 from .table import Table
-from .table_version import TableVersion
+from .table_version import TableVersion, TableVersionMd
 from .table_version_handle import TableVersionHandle
 from .table_version_path import TableVersionPath
+from .tbl_ops import CreateStoreTableOp, LoadViewOp, TableOp
+from .update_status import UpdateStatus
 
 if TYPE_CHECKING:
     from pixeltable.globals import TableDataSource
@@ -44,9 +45,18 @@ class View(Table):
         if not snapshot_only:
             self._tbl_version = tbl_version_path.tbl_version
 
-    @classmethod
-    def _display_name(cls) -> str:
-        return 'view'
+    def _display_name(self) -> str:
+        name: str
+        if self._tbl_version_path.is_snapshot():
+            name = 'snapshot'
+        elif self._tbl_version_path.is_view():
+            name = 'view'
+        else:
+            assert self._tbl_version_path.is_replica()
+            name = 'table'
+        if self._tbl_version_path.is_replica():
+            name = f'{name}-replica'
+        return name
 
     @classmethod
     def select_list_to_additional_columns(cls, select_list: list[tuple[exprs.Expr, Optional[str]]]) -> dict[str, dict]:
@@ -79,7 +89,7 @@ class View(Table):
         media_validation: MediaValidation,
         iterator_cls: Optional[type[ComponentIterator]],
         iterator_args: Optional[dict],
-    ) -> View:
+    ) -> tuple[TableVersionMd, Optional[list[TableOp]]]:
         from pixeltable.plan import SampleClause
 
         # Convert select_list to more additional_columns if present
@@ -166,11 +176,10 @@ class View(Table):
             for col in columns:
                 if col.name in iterator_col_names:
                     raise excs.Error(
-                        f'Duplicate name: column {col.name} is already present in the iterator output schema'
+                        f'Duplicate name: column {col.name!r} is already present in the iterator output schema'
                     )
             columns = iterator_cols + columns
 
-        session = Env.get().session
         from pixeltable.exprs import InlineDict
 
         iterator_args_expr: exprs.Expr = InlineDict(iterator_args) if iterator_args is not None else None
@@ -199,51 +208,26 @@ class View(Table):
             iterator_args=iterator_args_expr.as_dict() if iterator_args_expr is not None else None,
         )
 
-        id, tbl_version = TableVersion.create(
-            dir_id,
-            name,
-            columns,
-            num_retained_versions,
-            comment,
-            media_validation=media_validation,
-            # base_path=base_version_path,
-            view_md=view_md,
+        md = TableVersion.create_initial_md(
+            name, columns, num_retained_versions, comment, media_validation=media_validation, view_md=view_md
         )
-        if tbl_version is None:
-            # this is purely a snapshot: we use the base's tbl version path
-            view = cls(id, dir_id, name, base_version_path, snapshot_only=True)
-            _logger.info(f'created snapshot {name}')
+        if md.tbl_md.is_pure_snapshot:
+            # this is purely a snapshot: no store table to create or load
+            return md, None
         else:
-            view = cls(
-                id,
-                dir_id,
-                name,
-                TableVersionPath(
-                    TableVersionHandle(tbl_version.id, tbl_version.effective_version), base=base_version_path
-                ),
-                snapshot_only=False,
-            )
-            _logger.info(f'Created view `{name}`, id={tbl_version.id}')
-
-            from pixeltable.plan import Planner
-
-            try:
-                plan, _ = Planner.create_view_load_plan(view._tbl_version_path)
-                _, status = tbl_version.store_tbl.insert_rows(plan, v_min=tbl_version.version)
-            except:
-                # we need to remove the orphaned TableVersion instance
-                del catalog.Catalog.get()._tbl_versions[tbl_version.id, tbl_version.effective_version]
-                base_tbl_version = base.tbl_version.get()
-                if tbl_version.effective_version is None and not base_tbl_version.is_snapshot:
-                    # also remove tbl_version from the base
-                    base_tbl_version.mutable_views.remove(TableVersionHandle.create(tbl_version))
-                raise
-            Env.get().console_logger.info(
-                f'Created view `{name}` with {status.num_rows} rows, {status.num_excs} exceptions.'
+            tbl_id = md.tbl_md.tbl_id
+            view_path = TableVersionPath(
+                TableVersionHandle(UUID(tbl_id), effective_version=0 if is_snapshot else None), base=base_version_path
             )
-
-        session.commit()
-        return view
+            ops = [
+                TableOp(
+                    tbl_id=tbl_id, op_sn=0, num_ops=2, needs_xact=False, create_store_table_op=CreateStoreTableOp()
+                ),
+                TableOp(
+                    tbl_id=tbl_id, op_sn=1, num_ops=2, needs_xact=True, load_view_op=LoadViewOp(view_path.as_dict())
+                ),
+            ]
+            return md, ops
 
     @classmethod
     def _verify_column(cls, col: Column) -> None:
@@ -275,6 +259,12 @@ class View(Table):
         md = super()._get_metadata()
         md['is_view'] = True
         md['is_snapshot'] = self._tbl_version_path.is_snapshot()
+        base_tbl = self._get_base_table()
+        if base_tbl is None:
+            md['base'] = None
+        else:
+            base_version = self._effective_base_versions[0]
+            md['base'] = base_tbl._path() if base_version is None else f'{base_tbl._path()}:{base_version}'
         return md
 
     def insert(
@@ -288,16 +278,21 @@ class View(Table):
         print_stats: bool = False,
         **kwargs: Any,
     ) -> UpdateStatus:
-        raise excs.Error(f'{self._display_name()} {self._name!r}: cannot insert into view')
+        raise excs.Error(f'{self._display_str()}: Cannot insert into a {self._display_name()}.')
 
     def delete(self, where: Optional[exprs.Expr] = None) -> UpdateStatus:
-        raise excs.Error(f'{self._display_name()} {self._name!r}: cannot delete from view')
+        raise excs.Error(f'{self._display_str()}: Cannot delete from a {self._display_name()}.')
 
     def _get_base_table(self) -> Optional['Table']:
+        if self._tbl_version_path.base is None and not self._snapshot_only:
+            return None  # this can happen for a replica of a base table
         # if this is a pure snapshot, our tbl_version_path only reflects the base (there is no TableVersion instance
         # for the snapshot itself)
+        from pixeltable.catalog import Catalog
+
         base_id = self._tbl_version_path.tbl_id if self._snapshot_only else self._tbl_version_path.base.tbl_id
-        return catalog.Catalog.get().get_table_by_id(base_id)
+        with Catalog.get().begin_xact(tbl_id=base_id, for_write=False):
+            return catalog.Catalog.get().get_table_by_id(base_id)
 
     @property
     def _effective_base_versions(self) -> list[Optional[int]]:
@@ -308,8 +303,7 @@ class View(Table):
             return effective_versions[1:]
 
     def _table_descriptor(self) -> str:
-        display_name = 'Snapshot' if self._snapshot_only else 'View'
-        result = [f'{display_name} {self._path()!r}']
+        result = [self._display_str()]
         bases_descrs: list[str] = []
         for base, effective_version in zip(self._get_base_tables(), self._effective_base_versions):
             if effective_version is None:

pixeltable/config.py

@@ -25,19 +25,26 @@ class Config:
 
     __home: Path
     __config_file: Path
+    __config_overrides: dict[str, Any]
     __config_dict: dict[str, Any]
 
-    def __init__(self) -> None:
+    def __init__(self, config_overrides: dict[str, Any]) -> None:
         assert self.__instance is None, 'Config is a singleton; use Config.get() to access the instance'
 
-        self.__home = Path(os.environ.get('PIXELTABLE_HOME', str(Path.home() / '.pixeltable')))
+        for var in config_overrides:
+            if var not in KNOWN_CONFIG_OVERRIDES:
+                raise excs.Error(f'Unrecognized configuration variable: {var}')
+
+        self.__config_overrides = config_overrides
+
+        self.__home = Path(self.lookup_env('pixeltable', 'home', str(Path.home() / '.pixeltable')))
         if self.__home.exists() and not self.__home.is_dir():
-            raise RuntimeError(f'{self.__home} is not a directory')
+            raise excs.Error(f'Not a directory: {self.__home}')
         if not self.__home.exists():
             print(f'Creating a Pixeltable instance at: {self.__home}')
             self.__home.mkdir()
 
-        self.__config_file = Path(os.environ.get('PIXELTABLE_CONFIG', str(self.__home / 'config.toml')))
+        self.__config_file = Path(self.lookup_env('pixeltable', 'config', str(self.__home / 'config.toml')))
 
         self.__config_dict: dict[str, Any]
         if os.path.isfile(self.__config_file):
@@ -46,6 +53,12 @@ class Config:
                     self.__config_dict = toml.load(stream)
                 except Exception as exc:
                     raise excs.Error(f'Could not read config file: {self.__config_file}') from exc
+            for section, section_dict in self.__config_dict.items():
+                if section not in KNOWN_CONFIG_OPTIONS:
+                    raise excs.Error(f'Unrecognized section {section!r} in config file: {self.__config_file}')
+                for key in section_dict:
+                    if key not in KNOWN_CONFIG_OPTIONS[section]:
+                        raise excs.Error(f"Unrecognized option '{section}.{key}' in config file: {self.__config_file}")
         else:
             self.__config_dict = self.__create_default_config(self.__config_file)
             with open(self.__config_file, 'w', encoding='utf-8') as stream:
@@ -65,10 +78,18 @@ class Config:
 
     @classmethod
     def get(cls) -> Config:
-        if cls.__instance is None:
-            cls.__instance = cls()
+        cls.init({})
         return cls.__instance
 
+    @classmethod
+    def init(cls, config_overrides: dict[str, Any]) -> None:
+        if cls.__instance is None:
+            cls.__instance = cls(config_overrides)
+        elif len(config_overrides) > 0:
+            raise excs.Error(
+                'Pixeltable has already been initialized; cannot specify new config values in the same session'
+            )
+
     @classmethod
     def __create_default_config(cls, config_path: Path) -> dict[str, Any]:
         free_disk_space_bytes = shutil.disk_usage(config_path.parent).free
@@ -76,14 +97,23 @@ class Config:
         file_cache_size_g = free_disk_space_bytes / 5 / (1 << 30)
         return {'pixeltable': {'file_cache_size_g': round(file_cache_size_g, 1), 'hide_warnings': False}}
 
-    def get_value(self, key: str, expected_type: type[T], section: str = 'pixeltable') -> Optional[T]:
+    def lookup_env(self, section: str, key: str, default: Any = None) -> Any:
+        override_var = f'{section}.{key}'
         env_var = f'{section.upper()}_{key.upper()}'
+        if override_var in self.__config_overrides:
+            return self.__config_overrides[override_var]
         if env_var in os.environ:
-            value = os.environ[env_var]
-        elif section in self.__config_dict and key in self.__config_dict[section]:
+            return os.environ[env_var]
+        return default
+
+    def get_value(self, key: str, expected_type: type[T], section: str = 'pixeltable') -> Optional[T]:
+        value = self.lookup_env(section, key)  # Try to get from environment first
+        # Next try the config file
+        if value is None and section in self.__config_dict and key in self.__config_dict[section]:
             value = self.__config_dict[section][key]
-        else:
-            return None
+
+        if value is None:
+            return None  # Not specified
 
         try:
             if expected_type is bool and isinstance(value, str):
@@ -91,7 +121,7 @@ class Config:
                     raise excs.Error(f'Invalid value for configuration parameter {section}.{key}: {value}')
                 return value.lower() == 'true'  # type: ignore[return-value]
             return expected_type(value)  # type: ignore[call-arg]
-        except ValueError as exc:
+        except (ValueError, TypeError) as exc:
             raise excs.Error(f'Invalid value for configuration parameter {section}.{key}: {value}') from exc
 
     def get_string_value(self, key: str, section: str = 'pixeltable') -> Optional[str]:
@@ -105,3 +135,37 @@ class Config:
 
     def get_bool_value(self, key: str, section: str = 'pixeltable') -> Optional[bool]:
         return self.get_value(key, bool, section)
+
+
+KNOWN_CONFIG_OPTIONS = {
+    'pixeltable': {
+        'home': 'Path to the Pixeltable home directory',
+        'config': 'Path to the Pixeltable config file',
+        'pgdata': 'Path to the Pixeltable postgres data directory',
+        'db': 'Postgres database name',
+        'file_cache_size_g': 'Size of the file cache in GB',
+        'time_zone': 'Default time zone for timestamps',
+        'hide_warnings': 'Hide warnings from the console',
+        'verbosity': 'Verbosity level for console output',
+        'api_key': 'API key for Pixeltable cloud',
+    },
+    'anthropic': {'api_key': 'Anthropic API key'},
+    'bedrock': {'api_key': 'AWS Bedrock API key'},
+    'deepseek': {'api_key': 'Deepseek API key'},
+    'fireworks': {'api_key': 'Fireworks API key'},
+    'gemini': {'api_key': 'Gemini API key'},
+    'groq': {'api_key': 'Groq API key'},
+    'label_studio': {'api_key': 'Label Studio API key', 'url': 'Label Studio server URL'},
+    'mistral': {'api_key': 'Mistral API key'},
+    'openai': {'api_key': 'OpenAI API key'},
+    'replicate': {'api_token': 'Replicate API token'},
+    'together': {'api_key': 'Together API key'},
+    'pypi': {'api_key': 'PyPI API key (for internal use only)'},
+}
+
+
+KNOWN_CONFIG_OVERRIDES = {
+    f'{section}.{key}': info
+    for section, section_dict in KNOWN_CONFIG_OPTIONS.items()
+    for key, info in section_dict.items()
+}

pixeltable/dataframe.py

@@ -15,7 +15,7 @@ import sqlalchemy as sql
 
 from pixeltable import catalog, exceptions as excs, exec, exprs, plan, type_system as ts
 from pixeltable.catalog import Catalog, is_valid_identifier
-from pixeltable.catalog.globals import UpdateStatus
+from pixeltable.catalog.update_status import UpdateStatus
 from pixeltable.env import Env
 from pixeltable.plan import Planner, SampleClause
 from pixeltable.type_system import ColumnType
@@ -1185,7 +1185,7 @@ class DataFrame:
         """
         self._validate_mutable('delete', False)
         if not self._first_tbl.is_insertable():
-            raise excs.Error('Cannot delete from view')
+            raise excs.Error('Cannot use `delete` on a view.')
         with Catalog.get().begin_xact(tbl=self._first_tbl, for_write=True, lock_mutable_tree=True):
             return self._first_tbl.tbl_version.get().delete(where=self.where_clause)
 
@@ -1196,14 +1196,27 @@ class DataFrame:
             op_name: The name of the operation for which the test is being performed.
             allow_select: If True, allow a select() specification in the Dataframe.
         """
+        self._validate_mutable_op_sequence(op_name, allow_select)
+
+        # TODO: Reconcile these with Table.__check_mutable()
+        assert len(self._from_clause.tbls) == 1
+        if self._first_tbl.is_snapshot():
+            raise excs.Error(f'Cannot use `{op_name}` on a snapshot.')
+        if self._first_tbl.is_replica():
+            raise excs.Error(f'Cannot use `{op_name}` on a replica.')
+
+    def _validate_mutable_op_sequence(self, op_name: str, allow_select: bool) -> None:
+        """Tests whether the sequence of operations on this DataFrame is valid for a mutation operation."""
         if self.group_by_clause is not None or self.grouping_tbl is not None:
-            raise excs.Error(f'Cannot use `{op_name}` after `group_by`')
+            raise excs.Error(f'Cannot use `{op_name}` after `group_by`.')
         if self.order_by_clause is not None:
-            raise excs.Error(f'Cannot use `{op_name}` after `order_by`')
+            raise excs.Error(f'Cannot use `{op_name}` after `order_by`.')
         if self.select_list is not None and not allow_select:
-            raise excs.Error(f'Cannot use `{op_name}` after `select`')
+            raise excs.Error(f'Cannot use `{op_name}` after `select`.')
         if self.limit_val is not None:
-            raise excs.Error(f'Cannot use `{op_name}` after `limit`')
+            raise excs.Error(f'Cannot use `{op_name}` after `limit`.')
+        if self._has_joins():
+            raise excs.Error(f'Cannot use `{op_name}` after `join`.')
 
     def as_dict(self) -> dict[str, Any]:
         """