pixeltable 0.2.26__py3-none-any.whl → 0.5.7__py3-none-any.whl

pixeltable/index/__init__.py

@@ -1,3 +1,5 @@
+# ruff: noqa: F401
+
 from .base import IndexBase
-from .embedding_index import EmbeddingIndex
 from .btree import BtreeIndex
+from .embedding_index import EmbeddingIndex

pixeltable/index/base.py

@@ -1,11 +1,12 @@
 from __future__ import annotations
 
 import abc
-from typing import Any
 
 import sqlalchemy as sql
 
-from pixeltable import catalog, exprs
+import pixeltable.catalog as catalog
+import pixeltable.exprs as exprs
+import pixeltable.type_system as ts
 
 
 class IndexBase(abc.ABC):
@@ -18,39 +19,34 @@ class IndexBase(abc.ABC):
     """
 
     @abc.abstractmethod
-    def __init__(self, c: catalog.Column, **kwargs: Any):
-        pass
-
-    @abc.abstractmethod
-    def index_value_expr(self) -> exprs.Expr:
-        """Return expression that computes the value that goes into the index"""
-        pass
+    def create_value_expr(self, c: catalog.Column) -> exprs.Expr:
+        """
+        Validates that the index can be created on column c and returns an expression that computes the index value.
+        """
 
     @abc.abstractmethod
     def records_value_errors(self) -> bool:
         """True if index_value_expr() can raise errors"""
-        pass
 
     @abc.abstractmethod
-    def index_sa_type(self) -> sql.types.TypeEngine:
+    def get_index_sa_type(self, value_col_type: ts.ColumnType) -> sql.types.TypeEngine:
         """Return the sqlalchemy type of the index value column"""
-        pass
 
     @abc.abstractmethod
-    def create_index(self, index_name: str, index_value_col: catalog.Column, conn: sql.engine.Connection) -> None:
-        """Create the index on the index value column"""
-        pass
+    def sa_create_stmt(self, store_index_name: str, sa_value_col: sql.Column) -> sql.Compiled:
+        """Return a sqlalchemy statement for creating the index"""
+
+    @abc.abstractmethod
+    def drop_index(self, index_name: str, index_value_col: catalog.Column) -> None:
+        """Drop the index on the index value column"""
 
     @classmethod
     @abc.abstractmethod
-    def display_name(cls) -> str:
-        pass
+    def display_name(cls) -> str: ...
 
     @abc.abstractmethod
-    def as_dict(self) -> dict:
-        pass
+    def as_dict(self) -> dict: ...
 
     @classmethod
     @abc.abstractmethod
-    def from_dict(cls, c: catalog.Column, d: dict) -> IndexBase:
-        pass
+    def from_dict(cls, d: dict) -> IndexBase: ...

pixeltable/index/btree.py

@@ -1,58 +1,69 @@
-from typing import Optional, TYPE_CHECKING
+from typing import TYPE_CHECKING
 
 import sqlalchemy as sql
 
 # TODO: why does this import result in a circular import, but the one im embedding_index.py doesn't?
 # import pixeltable.catalog as catalog
 import pixeltable.exceptions as excs
-from pixeltable import catalog, exprs
+import pixeltable.exprs as exprs
+import pixeltable.type_system as ts
 from pixeltable.func.udf import udf
+
 from .base import IndexBase
 
 if TYPE_CHECKING:
-    import pixeltable.exprs
+    import pixeltable.catalog as catalog
+
 
 class BtreeIndex(IndexBase):
     """
     Interface to B-tree indices in Postgres.
     """
-    MAX_STRING_LEN = 256
 
-    value_expr: 'pixeltable.exprs.Expr'
+    MAX_STRING_LEN = 256
 
     @staticmethod
     @udf
-    def str_filter(s: Optional[str]) -> Optional[str]:
+    def str_filter(s: str | None) -> str | None:
         if s is None:
             return None
-        return s[:BtreeIndex.MAX_STRING_LEN]
+        return s[: BtreeIndex.MAX_STRING_LEN]
+
+    def __init__(self) -> None:
+        pass
 
-    def __init__(self, c: 'catalog.Column'):
+    def create_value_expr(self, c: 'catalog.Column') -> 'exprs.Expr':
         if not c.col_type.is_scalar_type() and not c.col_type.is_media_type():
             raise excs.Error(f'Index on column {c.name}: B-tree index requires scalar or media type, got {c.col_type}')
+        value_expr: exprs.Expr
         if c.col_type.is_media_type():
             # an index on a media column is an index on the file url
             # no validation for media columns: we're only interested in the string value
-            self.value_expr = exprs.ColumnRef(c, perform_validation=False)
+            value_expr = exprs.ColumnRef(c, perform_validation=False)
         else:
-            self.value_expr = (
+            value_expr = (
                 BtreeIndex.str_filter(exprs.ColumnRef(c)) if c.col_type.is_string_type() else exprs.ColumnRef(c)
             )
-
-    def index_value_expr(self) -> 'exprs.Expr':
-        return self.value_expr
+        return value_expr
 
     def records_value_errors(self) -> bool:
         return False
 
-    def index_sa_type(self) -> sql.types.TypeEngine:
+    def get_index_sa_type(self, val_col_type: ts.ColumnType) -> sql.types.TypeEngine:
         """Return the sqlalchemy type of the index value column"""
-        return self.value_expr.col_type.to_sa_type()
+        return val_col_type.to_sa_type()
+
+    def sa_create_stmt(self, store_index_name: str, sa_value_col: sql.Column) -> sql.Compiled:
+        """Return a sqlalchemy statement for creating the index"""
+        from sqlalchemy.dialects import postgresql
 
-    def create_index(self, index_name: str, index_value_col: 'catalog.Column', conn: sql.engine.Connection) -> None:
-        """Create the index on the index value column"""
-        idx = sql.Index(index_name, index_value_col.sa_col, postgresql_using='btree')
-        idx.create(bind=conn)
+        sa_idx = sql.Index(store_index_name, sa_value_col, postgresql_using='btree')
+        return sql.schema.CreateIndex(sa_idx, if_not_exists=True).compile(dialect=postgresql.dialect())
+
+    def drop_index(self, index_name: str, index_value_col: 'catalog.Column') -> None:
+        """Drop the index on the index value column"""
+        # TODO: implement
+        raise NotImplementedError()
 
     @classmethod
     def display_name(cls) -> str:
@@ -62,6 +73,5 @@ class BtreeIndex(IndexBase):
         return {}
 
     @classmethod
-    def from_dict(cls, c: 'catalog.Column', d: dict) -> 'BtreeIndex':
-        return cls(c)
-
+    def from_dict(cls, d: dict) -> 'BtreeIndex':
+        return cls()

pixeltable/index/embedding_index.py

@@ -1,16 +1,18 @@
 from __future__ import annotations
 
 import enum
-from typing import Any, Optional
+from typing import Any, ClassVar
 
 import numpy as np
 import pgvector.sqlalchemy  # type: ignore[import-untyped]
-import PIL.Image
 import sqlalchemy as sql
 
+import pixeltable.catalog as catalog
 import pixeltable.exceptions as excs
+import pixeltable.exprs as exprs
+import pixeltable.func as func
 import pixeltable.type_system as ts
-from pixeltable import catalog, exprs, func
+from pixeltable.env import Env
 
 from .base import IndexBase
 
@@ -31,70 +33,112 @@ class EmbeddingIndex(IndexBase):
         IP = 2
         L2 = 3
 
-    PGVECTOR_OPS = {
+    PGVECTOR_OPS: ClassVar[dict[Metric, str]] = {
         Metric.COSINE: 'vector_cosine_ops',
         Metric.IP: 'vector_ip_ops',
-        Metric.L2: 'vector_l2_ops'
+        Metric.L2: 'vector_l2_ops',
     }
 
+    metric: Metric
+    embeddings: dict[ts.ColumnType.Type, func.Function]
+
     def __init__(
-            self, c: catalog.Column, metric: str, string_embed: Optional[func.Function] = None,
-            image_embed: Optional[func.Function] = None):
+        self,
+        metric: str,
+        embed: func.Function | None = None,
+        string_embed: func.Function | None = None,
+        image_embed: func.Function | None = None,
+        audio_embed: func.Function | None = None,
+        video_embed: func.Function | None = None,
+    ):
+        if embed is None and string_embed is None and image_embed is None:
+            raise excs.Error('At least one of `embed`, `string_embed`, or `image_embed` must be specified')
         metric_names = [m.name.lower() for m in self.Metric]
         if metric.lower() not in metric_names:
             raise excs.Error(f'Invalid metric {metric}, must be one of {metric_names}')
-        if not c.col_type.is_string_type() and not c.col_type.is_image_type():
-            raise excs.Error(f'Embedding index requires string or image column')
-        if c.col_type.is_string_type() and string_embed is None:
-                raise excs.Error(f"Text embedding function is required for column {c.name} (parameter 'string_embed')")
-        if c.col_type.is_image_type() and image_embed is None:
-            raise excs.Error(f"Image embedding function is required for column {c.name} (parameter 'image_embed')")
-        if string_embed is not None:
-            # verify signature
-            self._validate_embedding_fn(string_embed, 'string_embed', ts.ColumnType.Type.STRING)
-        if image_embed is not None:
-            # verify signature
-            self._validate_embedding_fn(image_embed, 'image_embed', ts.ColumnType.Type.IMAGE)
+
+        self.embeddings = {}
+
+        # Resolve the specific embedding functions corresponding to the user-provided embedding functions.
+        # For string embeddings, for example, `string_embed` will be used if specified; otherwise, `embed` will
+        # be used as a fallback, if it has a matching signature.
+
+        for embed_type, embed_fn in (
+            (ts.ColumnType.Type.STRING, string_embed),
+            (ts.ColumnType.Type.IMAGE, image_embed),
+            (ts.ColumnType.Type.AUDIO, audio_embed),
+            (ts.ColumnType.Type.VIDEO, video_embed),
+        ):
+            if embed_fn is not None:
+                # Embedding function for the requisite type is specified directly; it MUST be valid.
+                resolved_fn = self._resolve_embedding_fn(embed_fn, embed_type)
+                if resolved_fn is None:
+                    raise excs.Error(
+                        f'The function `{embed_fn.name}` is not a valid {embed_type.name.lower()} '
+                        f'embedding: it must take a single {embed_type.name.lower()} parameter'
+                    )
+                self.embeddings[embed_type] = resolved_fn
+            elif embed is not None:
+                # General `embed` is specified; see if it has a matching signature.
+                resolved_fn = self._resolve_embedding_fn(embed, embed_type)
+                if resolved_fn is not None:
+                    self.embeddings[embed_type] = resolved_fn
+
+        if len(self.embeddings) == 0:
+            # `embed` was specified and contains no matching signatures.
+            assert embed is not None
+            raise excs.Error(
+                f'The function `{embed.name}` is not a valid embedding: '
+                'it must take a single string, image, audio, or video parameter'
+            )
+
+        # Now validate the return types of the embedding functions.
+        for _, embed_fn in self.embeddings.items():
+            self._validate_embedding_fn(embed_fn)
 
         self.metric = self.Metric[metric.upper()]
-        self.value_expr = string_embed(exprs.ColumnRef(c)) if c.col_type.is_string_type() else image_embed(exprs.ColumnRef(c))
-        assert isinstance(self.value_expr.col_type, ts.ArrayType)
-        self.string_embed = string_embed
-        self.image_embed = image_embed
-        vector_size = self.value_expr.col_type.shape[0]
-        assert vector_size is not None
-        self.index_col_type = pgvector.sqlalchemy.Vector(vector_size)
 
-    def index_value_expr(self) -> exprs.Expr:
-        """Return expression that computes the value that goes into the index"""
-        return self.value_expr
+    def create_value_expr(self, c: catalog.Column) -> exprs.Expr:
+        if c.col_type._type not in (
+            ts.ColumnType.Type.STRING,
+            ts.ColumnType.Type.IMAGE,
+            ts.ColumnType.Type.AUDIO,
+            ts.ColumnType.Type.VIDEO,
+        ):
+            raise excs.Error(f'Type `{c.col_type}` of column {c.name!r} is not a valid type for an embedding index.')
+        if c.col_type._type not in self.embeddings:
+            raise excs.Error(
+                f'The specified embedding function does not support the type `{c.col_type}` of column {c.name!r}.'
+            )
+
+        embed_fn = self.embeddings[c.col_type._type]
+        return embed_fn(exprs.ColumnRef(c))
 
     def records_value_errors(self) -> bool:
         return True
 
-    def index_sa_type(self) -> sql.types.TypeEngine:
-        """Return the sqlalchemy type of the index value column"""
-        return self.index_col_type
-
-    def create_index(self, index_name: str, index_value_col: catalog.Column, conn: sql.engine.Connection) -> None:
-        """Create the index on the index value column"""
-        idx = sql.Index(
-            index_name, index_value_col.sa_col,
-            postgresql_using='hnsw',
-            postgresql_with={'m': 16, 'ef_construction': 64},
-            postgresql_ops={index_value_col.sa_col.name: self.PGVECTOR_OPS[self.metric]}
+    def get_index_sa_type(self, val_col_type: ts.ColumnType) -> sql.types.TypeEngine:
+        assert isinstance(val_col_type, ts.ArrayType) and val_col_type.shape is not None
+        vector_size = val_col_type.shape[0]
+        assert vector_size is not None
+        return pgvector.sqlalchemy.Vector(vector_size)
+
+    def sa_create_stmt(self, store_index_name: str, sa_value_col: sql.Column) -> sql.Compiled:
+        """Return a sqlalchemy statement for creating the index"""
+        return Env.get().dbms.create_vector_index_stmt(
+            store_index_name, sa_value_col, metric=self.PGVECTOR_OPS[self.metric]
         )
-        idx.create(bind=conn)
 
-    def similarity_clause(self, val_column: catalog.Column, item: Any) -> sql.ColumnElement:
+    def drop_index(self, index_name: str, index_value_col: catalog.Column) -> None:
+        """Drop the index on the index value column"""
+        # TODO: implement
+        raise NotImplementedError()
+
+    def similarity_clause(self, val_column: catalog.Column, item: exprs.Literal) -> sql.ColumnElement:
         """Create a ColumnElement that represents '<val_column> <op> <item>'"""
-        assert isinstance(item, (str, PIL.Image.Image))
-        if isinstance(item, str):
-            assert self.string_embed is not None
-            embedding = self.string_embed.exec(item)
-        if isinstance(item, PIL.Image.Image):
-            assert self.image_embed is not None
-            embedding = self.image_embed.exec(item)
+        assert item.col_type._type in self.embeddings
+        embedding = self.embeddings[item.col_type._type].exec([item.val], {})
+        assert isinstance(embedding, np.ndarray)
 
         if self.metric == self.Metric.COSINE:
             return val_column.sa_col.cosine_distance(embedding) * -1 + 1
@@ -104,17 +148,11 @@ class EmbeddingIndex(IndexBase):
             assert self.metric == self.Metric.L2
             return val_column.sa_col.l2_distance(embedding)
 
-    def order_by_clause(self, val_column: catalog.Column, item: Any, is_asc: bool) -> sql.ColumnElement:
+    def order_by_clause(self, val_column: catalog.Column, item: exprs.Literal, is_asc: bool) -> sql.ColumnElement:
         """Create a ColumnElement that is used in an ORDER BY clause"""
-        assert isinstance(item, (str, PIL.Image.Image))
-        embedding: Optional[np.ndarray] = None
-        if isinstance(item, str):
-            assert self.string_embed is not None
-            embedding = self.string_embed.exec(item)
-        if isinstance(item, PIL.Image.Image):
-            assert self.image_embed is not None
-            embedding = self.image_embed.exec(item)
-        assert embedding is not None
+        assert item.col_type._type in self.embeddings
+        embedding = self.embeddings[item.col_type._type].exec([item.val], {})
+        assert isinstance(embedding, np.ndarray)
 
         if self.metric == self.Metric.COSINE:
             result = val_column.sa_col.cosine_distance(embedding)
@@ -132,44 +170,69 @@ class EmbeddingIndex(IndexBase):
         return 'embedding'
 
     @classmethod
-    def _validate_embedding_fn(cls, embed_fn: func.Function, name: str, expected_type: ts.ColumnType.Type) -> None:
-        """Validate the signature"""
+    def _resolve_embedding_fn(cls, embed_fn: func.Function, expected_type: ts.ColumnType.Type) -> func.Function | None:
+        """Find an overload resolution for `embed_fn` that matches the given type."""
         assert isinstance(embed_fn, func.Function)
-        sig = embed_fn.signature
+        for resolved_fn in embed_fn._resolved_fns:
+            # The embedding function must be a 1-ary function of the correct type. But it's ok if the function signature
+            # has more than one parameter, as long as it has at most one *required* parameter.
+            sig = resolved_fn.signature
+            if (
+                len(sig.parameters) >= 1
+                and len(sig.required_parameters) <= 1
+                and sig.parameters_by_pos[0].col_type.type_enum == expected_type
+            ):
+                # We found a valid signature. Now, if it has more than one parameter, we need to transform it into a
+                # 1-ary function by fixing all the other parameters to their defaults. This is to ensure that
+                # conditional_return_type resolves correctly.
+                if len(sig.parameters) == 1:
+                    unary_fn = resolved_fn
+                else:
+                    assert all(sig.parameters_by_pos[i].has_default for i in range(1, len(sig.parameters)))
+                    defaults = {param.name: param.default for param in sig.parameters_by_pos[1:]}
+                    unary_fn = resolved_fn.using(**defaults)
+                assert not unary_fn.is_polymorphic
+                assert len(unary_fn.signature.parameters) == 1
+                return unary_fn
+        return None
 
-        # The embedding function must be a 1-ary function of the correct type. But it's ok if the function signature
-        # has more than one parameter, as long as it has at most one *required* parameter.
-        if (len(sig.parameters) == 0
-            or len(sig.required_parameters) > 1
-            or sig.parameters_by_pos[0].col_type.type_enum != expected_type):
-            raise excs.Error(
-                f'{name} must take a single {expected_type.name.lower()} parameter, but has signature {sig}')
+    @classmethod
+    def _validate_embedding_fn(cls, embed_fn: func.Function) -> None:
+        """Validate the given embedding function."""
+        assert not embed_fn.is_polymorphic
+
+        return_type = embed_fn.signature.return_type
 
-        # validate return type
-        param_name = sig.parameters_by_pos[0].name
-        if expected_type == ts.ColumnType.Type.STRING:
-            return_type = embed_fn.call_return_type({param_name: 'dummy'})
-        else:
-            assert expected_type == ts.ColumnType.Type.IMAGE
-            img = PIL.Image.new('RGB', (512, 512))
-            return_type = embed_fn.call_return_type({param_name: img})
-        assert return_type is not None
         if not isinstance(return_type, ts.ArrayType):
-            raise excs.Error(f'{name} must return an array, but returns {return_type}')
-        else:
-            shape = return_type.shape
-            if len(shape) != 1 or shape[0] == None:
-                raise excs.Error(f'{name} must return a 1D array of a specific length, but returns {return_type}')
+            raise excs.Error(
+                f'The function `{embed_fn.name}` is not a valid embedding: '
+                f'it must return an array, but returns {return_type}'
+            )
+
+        shape = return_type.shape
+        if len(shape) != 1 or shape[0] is None:
+            raise excs.Error(
+                f'The function `{embed_fn.name}` is not a valid embedding: '
+                f'it must return a 1-dimensional array of a specific length, but returns {return_type}'
+            )
 
     def as_dict(self) -> dict:
-        return {
-            'metric': self.metric.name.lower(),
-            'string_embed': None if self.string_embed is None else self.string_embed.as_dict(),
-            'image_embed': None if self.image_embed is None else self.image_embed.as_dict()
-        }
+        d: dict[str, Any] = {'metric': self.metric.name.lower()}
+        for embed_type, embed_fn in self.embeddings.items():
+            key = f'{embed_type.name.lower()}_embed'
+            d[key] = embed_fn.as_dict()
+        return d
 
     @classmethod
-    def from_dict(cls, c: catalog.Column, d: dict) -> EmbeddingIndex:
-        string_embed = func.Function.from_dict(d['string_embed']) if d['string_embed'] is not None else None
-        image_embed = func.Function.from_dict(d['image_embed']) if d['image_embed'] is not None else None
-        return cls(c, metric=d['metric'], string_embed=string_embed, image_embed=image_embed)
+    def from_dict(cls, d: dict) -> EmbeddingIndex:
+        string_embed = func.Function.from_dict(d['string_embed']) if d.get('string_embed') is not None else None
+        image_embed = func.Function.from_dict(d['image_embed']) if d.get('image_embed') is not None else None
+        audio_embed = func.Function.from_dict(d['audio_embed']) if d.get('audio_embed') is not None else None
+        video_embed = func.Function.from_dict(d['video_embed']) if d.get('video_embed') is not None else None
+        return cls(
+            metric=d['metric'],
+            string_embed=string_embed,
+            image_embed=image_embed,
+            audio_embed=audio_embed,
+            video_embed=video_embed,
+        )

pixeltable/io/__init__.py

@@ -1,13 +1,18 @@
-from .external_store import ExternalStore, SyncStatus
-from .globals import create_label_studio_project, export_images_as_fo_dataset, import_json, import_rows
+"""Functions for importing and exporting Pixeltable data."""
+# ruff: noqa: F401
+
+from .datarows import import_json, import_rows
+from .external_store import ExternalStore
+from .globals import create_label_studio_project, export_images_as_fo_dataset
 from .hf_datasets import import_huggingface_dataset
+from .lancedb import export_lancedb
 from .pandas import import_csv, import_excel, import_pandas
-from .parquet import import_parquet, export_parquet
+from .parquet import export_parquet, import_parquet
 
-__default_dir = set(symbol for symbol in dir() if not symbol.startswith('_'))
-__removed_symbols = {'globals', 'hf_datasets', 'pandas', 'parquet'}
-__all__ = sorted(list(__default_dir - __removed_symbols))
+__default_dir = {symbol for symbol in dir() if not symbol.startswith('_')}
+__removed_symbols = {'globals', 'hf_datasets', 'pandas', 'parquet', 'datarows', 'lancedb'}
+__all__ = sorted(__default_dir - __removed_symbols)
 
 
-def __dir__():
+def __dir__() -> list[str]:
     return __all__

pixeltable/io/datarows.py

@@ -0,0 +1,140 @@
+from __future__ import annotations
+
+from typing import Any, Iterable
+
+import pixeltable as pxt
+import pixeltable.type_system as ts
+from pixeltable import exceptions as excs
+
+
+def _infer_schema_from_rows(
+    rows: Iterable[dict[str, Any]], schema_overrides: dict[str, ts.ColumnType], primary_key: list[str]
+) -> dict[str, ts.ColumnType]:
+    schema: dict[str, ts.ColumnType] = {}
+    cols_with_nones: set[str] = set()
+
+    for n, row in enumerate(rows):
+        for col_name, value in row.items():
+            if col_name in schema_overrides:
+                # We do the insertion here; this will ensure that the column order matches the order
+                # in which the column names are encountered in the input data, even if `schema_overrides`
+                # is specified.
+                if col_name not in schema:
+                    assert isinstance(schema_overrides[col_name], ts.ColumnType)
+                    schema[col_name] = schema_overrides[col_name]
+            elif value is not None:
+                # If `key` is not in `schema_overrides`, then we infer its type from the data.
+                # The column type will always be nullable by default.
+                col_type = ts.ColumnType.infer_literal_type(value, nullable=col_name not in primary_key)
+                if col_type is None:
+                    raise excs.Error(
+                        f'Could not infer type for column `{col_name}`; the value in row {n} '
+                        f'has an unsupported type: {type(value)}'
+                    )
+                if col_name not in schema:
+                    schema[col_name] = col_type
+                else:
+                    supertype = schema[col_name].supertype(col_type, for_inference=True)
+                    if supertype is None:
+                        raise excs.Error(
+                            f'Could not infer type of column `{col_name}`; the value in row {n} '
+                            f'does not match preceding type {schema[col_name]}: {value!r}\n'
+                            'Consider specifying the type explicitly in `schema_overrides`.'
+                        )
+                    schema[col_name] = supertype
+            else:
+                cols_with_nones.add(col_name)
+
+    entirely_none_cols = cols_with_nones - schema.keys()
+    if len(entirely_none_cols) > 0:
+        # A column can only end up in `entirely_none_cols` if it was not in `schema_overrides` and
+        # was not encountered in any row with a non-None value.
+        raise excs.Error(
+            f'The following columns have no non-null values: {", ".join(entirely_none_cols)}\n'
+            'Consider specifying the type(s) explicitly in `schema_overrides`.'
+        )
+    return schema
+
+
+def import_rows(
+    tbl_path: str,
+    rows: list[dict[str, Any]],
+    *,
+    schema_overrides: dict[str, Any] | None = None,
+    primary_key: str | list[str] | None = None,
+    num_retained_versions: int = 10,
+    comment: str = '',
+) -> pxt.Table:
+    """
+    Creates a new base table from a list of dictionaries. The dictionaries must be of the
+    form `{column_name: value, ...}`. Pixeltable will attempt to infer the schema of the table from the
+    supplied data, using the most specific type that can represent all the values in a column.
+
+    If `schema_overrides` is specified, then for each entry `(column_name, type)` in `schema_overrides`,
+    Pixeltable will force the specified column to the specified type (and will not attempt any type inference
+    for that column).
+
+    All column types of the new table will be nullable unless explicitly specified as non-nullable in
+    `schema_overrides`.
+
+    Args:
+        tbl_path: The qualified name of the table to create.
+        rows: The list of dictionaries to import.
+        schema_overrides: If specified, then columns in `schema_overrides` will be given the specified types
+            as described above.
+        primary_key: The primary key of the table (see [`create_table()`][pixeltable.create_table]).
+        num_retained_versions: The number of retained versions of the table
+            (see [`create_table()`][pixeltable.create_table]).
+        comment: A comment to attach to the table (see [`create_table()`][pixeltable.create_table]).
+
+    Returns:
+        A handle to the newly created [`Table`][pixeltable.Table].
+    """
+    return pxt.create_table(
+        tbl_path,
+        source=rows,
+        schema_overrides=schema_overrides,
+        primary_key=primary_key,
+        num_retained_versions=num_retained_versions,
+        comment=comment,
+    )
+
+
+def import_json(
+    tbl_path: str,
+    filepath_or_url: str,
+    *,
+    schema_overrides: dict[str, Any] | None = None,
+    primary_key: str | list[str] | None = None,
+    num_retained_versions: int = 10,
+    comment: str = '',
+    **kwargs: Any,
+) -> pxt.Table:
+    """
+    Creates a new base table from a JSON file. This is a convenience method and is
+    equivalent to calling `import_data(table_path, json.loads(file_contents, **kwargs), ...)`, where `file_contents`
+    is the contents of the specified `filepath_or_url`.
+
+    Args:
+        tbl_path: The name of the table to create.
+        filepath_or_url: The path or URL of the JSON file.
+        schema_overrides: If specified, then columns in `schema_overrides` will be given the specified types
+            (see [`import_rows()`][pixeltable.io.import_rows]).
+        primary_key: The primary key of the table (see [`create_table()`][pixeltable.create_table]).
+        num_retained_versions: The number of retained versions of the table
+            (see [`create_table()`][pixeltable.create_table]).
+        comment: A comment to attach to the table (see [`create_table()`][pixeltable.create_table]).
+        kwargs: Additional keyword arguments to pass to `json.loads`.
+
+    Returns:
+        A handle to the newly created [`Table`][pixeltable.Table].
+    """
+    return pxt.create_table(
+        tbl_path,
+        source=filepath_or_url,
+        schema_overrides=schema_overrides,
+        primary_key=primary_key,
+        num_retained_versions=num_retained_versions,
+        comment=comment,
+        extra_args=kwargs,
+    )