deltacat 2.0.0b11__py3-none-any.whl → 2.0.0b12__py3-none-any.whl

deltacat/tests/catalog/main/test_catalog_impl_table_operations.py

@@ -3,18 +3,29 @@ import tempfile
 
 import pytest
 import pyarrow as pa
+import pandas as pd
+import polars as pl
+import numpy as np
+import ray.data as rd
+import daft
 
 import deltacat.catalog.main.impl as catalog
 from deltacat.catalog import get_catalog_properties
-from deltacat.storage.model.schema import Schema
+from deltacat.storage.model.schema import (
+    Schema,
+    Field,
+)
+from deltacat.storage.model.types import SchemaConsistencyType
 from deltacat.storage.model.sort_key import SortKey, SortScheme, SortOrder, NullOrder
-from deltacat.storage.model.table import TableProperties
-from deltacat.storage.model.namespace import NamespaceProperties
 from deltacat.storage.model.types import LifecycleState
 from deltacat.exceptions import (
     TableAlreadyExistsError,
     TableNotFoundError,
+    TableValidationError,
+    SchemaValidationError,
 )
+from deltacat.types.tables import TableWriteMode, TableProperty, SchemaEvolutionMode
+from deltacat.types.media import ContentType
 
 
 @pytest.fixture(scope="class")
@@ -69,6 +80,24 @@ def sample_sort_keys():
 
 
 class TestCatalogTableOperations:
+    """Test catalog table operations including table creation, existence checks, etc."""
+
+    @classmethod
+    def setup_class(cls):
+        cls.temp_dir = tempfile.mkdtemp()
+        cls.catalog_properties = get_catalog_properties(root=cls.temp_dir)
+
+        # Create a test namespace
+        cls.test_namespace = "test_write_operations"
+        catalog.create_namespace(
+            namespace=cls.test_namespace,
+            inner=cls.catalog_properties,
+        )
+
+    @classmethod
+    def teardown_class(cls):
+        shutil.rmtree(cls.temp_dir)
+
     def test_create_table(self, test_namespace, sample_arrow_schema, sample_sort_keys):
         """Test creating a table with schema and properties"""
         namespace_name, catalog_properties = test_namespace
@@ -78,20 +107,18 @@ class TestCatalogTableOperations:
         schema = Schema(arrow=sample_arrow_schema)
 
         # Create table properties
-        table_properties = TableProperties(
-            {"owner": "test-user", "department": "engineering"}
-        )
+        table_properties = {"owner": "test-user", "department": "engineering"}
 
         # Create namespace properties
-        namespace_properties = NamespaceProperties({"description": "Test Namespace"})
+        namespace_properties = {"description": "Test Namespace"}
 
         # Create the table
         table_definition = catalog.create_table(
-            name=table_name,
+            table=table_name,
             namespace=namespace_name,
             schema=schema,
             sort_keys=sample_sort_keys,
-            description="Test table for unit tests",
+            table_description="Test table for unit tests",
             table_properties=table_properties,
             namespace_properties=namespace_properties,
             inner=catalog_properties,
@@ -99,7 +126,9 @@ class TestCatalogTableOperations:
 
         # Verify table was created
         assert catalog.table_exists(
-            table_name, namespace=namespace_name, inner=catalog_properties
+            table_name,
+            namespace=namespace_name,
+            inner=catalog_properties,
         )
 
         table = table_definition.table
@@ -109,7 +138,7 @@ class TestCatalogTableOperations:
         assert table_version.table_name == table_name
         assert table_version.namespace == namespace_name
         assert table_version.description == "Test table for unit tests"
-        assert table_version.state == LifecycleState.CREATED
+        assert table_version.state == LifecycleState.ACTIVE
         assert table.properties.get("owner") == "test-user"
         assert table.properties.get("department") == "engineering"
         assert table_version.schema.arrow.names == sample_arrow_schema.names
@@ -123,15 +152,17 @@ class TestCatalogTableOperations:
 
         # Create the table
         catalog.create_table(
-            name=table_name,
+            table=table_name,
             namespace=namespace_name,
-            description="First creation",
+            table_description="First creation",
             inner=catalog_properties,
         )
 
         # Verify table exists
         assert catalog.table_exists(
-            table_name, namespace=namespace_name, inner=catalog_properties
+            table_name,
+            namespace=namespace_name,
+            inner=catalog_properties,
         )
 
         # Try to create the same table again, should raise TableAlreadyExistsError
@@ -140,9 +171,9 @@ class TestCatalogTableOperations:
             match=f"Table {namespace_name}.{table_name} already exists",
         ):
             catalog.create_table(
-                name=table_name,
+                table=table_name,
                 namespace=namespace_name,
-                description="Second creation attempt",
+                table_description="Second creation attempt",
                 inner=catalog_properties,
             )
 
@@ -153,21 +184,23 @@ class TestCatalogTableOperations:
 
         # Create the table with original description
         catalog.create_table(
-            name=table_name,
+            table=table_name,
             namespace=namespace_name,
-            description="Original description",
+            table_description="Original description",
             inner=catalog_properties,
         )
 
         assert catalog.table_exists(
-            table_name, namespace=namespace_name, inner=catalog_properties
+            table_name,
+            namespace=namespace_name,
+            catalog=catalog_properties,
         )
 
         # Create the same table with fail_if_exists=False
         table_definition = catalog.create_table(
-            name=table_name,
+            table=table_name,
             namespace=namespace_name,
-            description="Updated description",
+            table_description="Updated description",
             fail_if_exists=False,
             inner=catalog_properties,
         )
@@ -185,22 +218,30 @@ class TestCatalogTableOperations:
 
         # Create the table
         catalog.create_table(
-            name=table_name, namespace=namespace_name, inner=catalog_properties
+            table=table_name,
+            namespace=namespace_name,
+            inner=catalog_properties,
         )
 
         # Verify table exists
         assert catalog.table_exists(
-            table_name, namespace=namespace_name, inner=catalog_properties
+            table_name,
+            namespace=namespace_name,
+            inner=catalog_properties,
         )
 
         # Drop the table
         catalog.drop_table(
-            name=table_name, namespace=namespace_name, inner=catalog_properties
+            table=table_name,
+            namespace=namespace_name,
+            inner=catalog_properties,
         )
 
         # Verify table no longer exists
         assert not catalog.table_exists(
-            table_name, namespace=namespace_name, inner=catalog_properties
+            table_name,
+            namespace=namespace_name,
+            inner=catalog_properties,
         )
 
     def test_drop_table_not_exists(self, test_namespace):
@@ -209,15 +250,57 @@ class TestCatalogTableOperations:
 
         # Verify table doesn't exist
         assert not catalog.table_exists(
-            table_name, namespace=namespace_name, inner=catalog_properties
+            table_name,
+            namespace=namespace_name,
+            inner=catalog_properties,
         )
 
         # Try to drop the table, should raise TableNotFoundError
         with pytest.raises(TableNotFoundError, match=table_name):
             catalog.drop_table(
-                name=table_name, namespace=namespace_name, inner=catalog_properties
+                table=table_name,
+                namespace=namespace_name,
+                inner=catalog_properties,
             )
 
+    def test_rename_namespace(self, test_namespace):
+        namespace_name, catalog_properties = test_namespace
+        original_name = "test_original_table"
+        new_name = "test_renamed_namespace"
+
+        # Create the table with original name
+        catalog.create_table(
+            table=original_name,
+            namespace=namespace_name,
+            table_description="Table to in namespace to be renamed",
+            inner=catalog_properties,
+        )
+
+        # Verify original table exists
+        assert catalog.table_exists(
+            original_name,
+            namespace=namespace_name,
+            inner=catalog_properties,
+        )
+
+        # Rename the namespace
+        catalog.alter_namespace(
+            namespace=namespace_name,
+            new_namespace=new_name,
+            inner=catalog_properties,
+        )
+
+        # Verify new namespace exists and old namespace doesn't
+        assert catalog.namespace_exists(new_name, inner=catalog_properties)
+        assert not catalog.namespace_exists(namespace_name, inner=catalog_properties)
+
+        # Verify we can still discover the table in the new namespace
+        assert catalog.table_exists(
+            original_name,
+            namespace=new_name,
+            inner=catalog_properties,
+        )
+
     def test_rename_table(self, test_namespace):
         namespace_name, catalog_properties = test_namespace
         original_name = "test_original_table"
@@ -225,15 +308,17 @@ class TestCatalogTableOperations:
 
         # Create the table with original name
         catalog.create_table(
-            name=original_name,
+            table=original_name,
             namespace=namespace_name,
-            description="Table to be renamed",
+            table_description="Table to be renamed",
             inner=catalog_properties,
         )
 
         # Verify original table exists
         assert catalog.table_exists(
-            original_name, namespace=namespace_name, inner=catalog_properties
+            original_name,
+            namespace=namespace_name,
+            inner=catalog_properties,
         )
 
         # Rename the table
@@ -246,10 +331,14 @@ class TestCatalogTableOperations:
 
         # Verify new table exists and old table doesn't
         assert catalog.table_exists(
-            new_name, namespace=namespace_name, inner=catalog_properties
+            new_name,
+            namespace=namespace_name,
+            inner=catalog_properties,
         )
         assert not catalog.table_exists(
-            original_name, namespace=namespace_name, inner=catalog_properties
+            original_name,
+            namespace=namespace_name,
+            inner=catalog_properties,
         )
 
     def test_rename_table_not_exists(self, test_namespace):
@@ -259,7 +348,9 @@ class TestCatalogTableOperations:
 
         # Verify table doesn't exist
         assert not catalog.table_exists(
-            original_name, namespace=namespace_name, inner=catalog_properties
+            original_name,
+            namespace=namespace_name,
+            inner=catalog_properties,
         )
 
         # Try to rename the table, should raise TableNotFoundError
@@ -278,17 +369,23 @@ class TestCatalogTableOperations:
 
         # Create a table
         catalog.create_table(
-            name=existing_table, namespace=namespace_name, inner=catalog_properties
+            table=existing_table,
+            namespace=namespace_name,
+            inner=catalog_properties,
         )
 
         # Check existing table
         assert catalog.table_exists(
-            existing_table, namespace=namespace_name, inner=catalog_properties
+            existing_table,
+            namespace=namespace_name,
+            inner=catalog_properties,
         )
 
         # Check non-existing table
         assert not catalog.table_exists(
-            non_existing_table, namespace=namespace_name, inner=catalog_properties
+            non_existing_table,
+            namespace=namespace_name,
+            inner=catalog_properties,
         )
 
     def test_create_table_with_default_namespace(self, catalog_setup):
@@ -297,7 +394,7 @@ class TestCatalogTableOperations:
 
         # Create table with default namespace
         table_definition = catalog.create_table(
-            name=table_name, inner=catalog_properties
+            table=table_name, inner=catalog_properties
         )
 
         table = table_definition.table
@@ -305,7 +402,9 @@ class TestCatalogTableOperations:
         default_ns = catalog.default_namespace()
         assert table.namespace == default_ns
         assert catalog.table_exists(
-            table_name, namespace=default_ns, inner=catalog_properties
+            table_name,
+            namespace=default_ns,
+            inner=catalog_properties,
         )
 
     def test_create_table_with_missing_namespace(self, catalog_setup):
@@ -318,11 +417,15 @@ class TestCatalogTableOperations:
 
         # Try to create table with non-existent namespace
         catalog.create_table(
-            name=table_name, namespace=new_namespace, inner=catalog_properties
+            table=table_name,
+            namespace=new_namespace,
+            inner=catalog_properties,
         )
 
         assert catalog.table_exists(
-            table_name, namespace=new_namespace, inner=catalog_properties
+            table_name,
+            namespace=new_namespace,
+            inner=catalog_properties,
         )
         assert catalog.namespace_exists(new_namespace, inner=catalog_properties)
 
@@ -332,17 +435,15 @@ class TestCatalogTableOperations:
 
         # Create initial schema and properties
         schema = Schema.of(schema=sample_arrow_schema)
-        initial_properties = TableProperties(
-            {"owner": "original-user", "department": "engineering"}
-        )
+        initial_properties = {"owner": "original-user", "department": "engineering"}
 
         # Create the table with initial properties
         table = catalog.create_table(
-            name=table_name,
+            table=table_name,
             namespace=namespace_name,
             schema=schema,
             sort_keys=sample_sort_keys,
-            description="Initial description",
+            table_description="Initial description",
             table_properties=initial_properties,
             inner=catalog_properties,
         )
@@ -350,39 +451,37 @@ class TestCatalogTableOperations:
 
         # Verify table was created with initial properties
         assert catalog.table_exists(
-            table_name, namespace=namespace_name, inner=catalog_properties
-        )
-
-        # Create updated schema
-        updated_arrow_schema = pa.schema(
-            [
-                pa.field("count", pa.float64()),  # Added field
-            ]
+            table_name,
+            namespace=namespace_name,
+            inner=catalog_properties,
         )
 
-        new_schema = old_schema.add_subschema(
-            name="updated_schema",
-            schema=updated_arrow_schema,
-        )
+        # Create schema update operations to add a new field
+        new_field = Field.of(pa.field("count", pa.float64(), nullable=True))
+        schema_update = old_schema.update().add_field(new_field)
 
         # Create updated properties
-        updated_properties = TableProperties(
-            {"owner": "new-user", "department": "data-science", "priority": "high"}
-        )
+        updated_properties = {
+            "owner": "new-user",
+            "department": "data-science",
+            "priority": "high",
+        }
 
-        # Alter the table with new properties
+        # Alter the table with new properties and schema updates
         catalog.alter_table(
             table=table_name,
             namespace=namespace_name,
-            schema_updates=new_schema,
-            description="Updated description",
-            properties=updated_properties,
+            schema_updates=schema_update,
+            table_description="Updated description",
+            table_properties=updated_properties,
             inner=catalog_properties,
         )
 
         # Get the updated table definition
         updated_table_def = catalog.get_table(
-            table_name, namespace=namespace_name, inner=catalog_properties
+            table_name,
+            namespace=namespace_name,
+            inner=catalog_properties,
         )
 
         updated_table = updated_table_def.table
@@ -390,11 +489,23 @@ class TestCatalogTableOperations:
 
         # Verify table properties were updated
         assert updated_table_version.description == "Updated description"
-        assert updated_table_version.state == LifecycleState.CREATED
+        assert updated_table_version.state == LifecycleState.ACTIVE
         assert updated_table.properties.get("owner") == "new-user"
         assert updated_table.properties.get("department") == "data-science"
         assert updated_table.properties.get("priority") == "high"
 
+        # Verify schema was updated with new field
+        updated_schema = updated_table_version.schema
+        assert updated_schema.field("count") is not None
+        assert updated_schema.field("count").arrow.type == pa.float64()
+        assert updated_schema.field("count").arrow.nullable is True
+        assert (
+            updated_schema.field("count").id == 3
+        )  # Next sequential ID after id(0), name(1), value(2)
+
+        # Verify schema ID was incremented (proving SchemaUpdate was used)
+        assert updated_schema.id == old_schema.id + 1
+
     def test_alter_table_not_exists(self, test_namespace):
         """Test altering a table that doesn't exist"""
         namespace_name, catalog_properties = test_namespace
@@ -402,7 +513,9 @@ class TestCatalogTableOperations:
 
         # Verify table doesn't exist
         assert not catalog.table_exists(
-            nonexistent_table, namespace=namespace_name, inner=catalog_properties
+            nonexistent_table,
+            namespace=namespace_name,
+            inner=catalog_properties,
         )
 
         # Try to alter the nonexistent table, should raise TableNotFoundError
@@ -410,10 +523,276 @@ class TestCatalogTableOperations:
             catalog.alter_table(
                 table=nonexistent_table,
                 namespace=namespace_name,
-                description="Updated description",
+                table_description="Updated description",
+                inner=catalog_properties,
+            )
+
+    def test_alter_table_with_multiple_schema_operations(
+        self, test_namespace, sample_arrow_schema
+    ):
+        """Test altering a table with multiple schema update operations."""
+        namespace_name, catalog_properties = test_namespace
+        table_name = "test_alter_table_multiple_ops"
+
+        # Create initial schema
+        schema = Schema.of(schema=sample_arrow_schema)
+        print("schema.max_field_id", schema.max_field_id)
+
+        # Create the table
+        table = catalog.create_table(
+            table=table_name,
+            namespace=namespace_name,
+            schema=schema,
+            table_description="Initial description",
+            inner=catalog_properties,
+        )
+
+        original_schema = table.table_version.schema
+
+        # Create multiple schema update operations
+        new_field1 = Field.of(pa.field("count", pa.int64(), nullable=True))
+        new_field2 = Field.of(
+            pa.field("status", pa.string(), nullable=False),
+            past_default="active",
+        )
+
+        schema_update = (
+            original_schema.update().add_field(new_field1).add_field(new_field2)
+        )
+        print("original_schema.max_field_id", original_schema.max_field_id)
+        print(
+            "schema_update.base_schema.max_field_id",
+            schema_update.base_schema.max_field_id,
+        )
+
+        # Alter the table
+        catalog.alter_table(
+            table=table_name,
+            namespace=namespace_name,
+            schema_updates=schema_update,
+            table_description="Updated with multiple fields",
+            inner=catalog_properties,
+        )
+
+        # Get the updated table
+        updated_table_def = catalog.get_table(
+            table_name,
+            namespace=namespace_name,
+            inner=catalog_properties,
+        )
+
+        updated_schema = updated_table_def.table_version.schema
+
+        # Verify both fields were added
+        assert updated_schema.field("count") is not None
+        assert updated_schema.field("count").arrow.type == pa.int64()
+        assert (
+            updated_schema.field("count").id == 3
+        )  # Next sequential ID after id(0), name(1), value(2)
+
+        assert updated_schema.field("status") is not None
+        assert updated_schema.field("status").arrow.type == pa.string()
+        assert (
+            updated_schema.field("status").id == 4
+        )  # Next sequential ID after count(3)
+        assert updated_schema.field("status").past_default == "active"
+
+        # Verify schema ID was incremented
+        assert updated_schema.id == original_schema.id + 1
+
+    def test_alter_table_with_remove_operation(self, test_namespace):
+        """Test altering a table with field removal (requires allow_incompatible_changes)."""
+        namespace_name, catalog_properties = test_namespace
+        table_name = "test_alter_table_remove"
+
+        # Create schema with multiple fields
+        initial_fields = [
+            Field.of(
+                pa.field("id", pa.int64(), nullable=False),
+                is_merge_key=True,
+                field_id=1,
+            ),
+            Field.of(pa.field("name", pa.string(), nullable=True), field_id=2),
+            Field.of(pa.field("temp_field", pa.float64(), nullable=True), field_id=3),
+        ]
+        schema = Schema.of(initial_fields)
+
+        # Create the table
+        table = catalog.create_table(
+            table=table_name,
+            namespace=namespace_name,
+            schema=schema,
+            inner=catalog_properties,
+        )
+        original_schema = table.table_version.schema
+        temp_field = original_schema.field("temp_field")
+        assert temp_field is not None
+
+        schema_update = original_schema.update(True).remove_field("temp_field")
+
+        catalog.alter_table(
+            table=table_name,
+            namespace=namespace_name,
+            schema_updates=schema_update,
+            inner=catalog_properties,
+        )
+
+        # If successful, verify the field was removed
+        updated_table_def = catalog.get_table(
+            table_name,
+            namespace=namespace_name,
+            inner=catalog_properties,
+        )
+        updated_schema = updated_table_def.table_version.schema
+
+        # temp_field should be removed
+        with pytest.raises(KeyError):
+            updated_schema.field("temp_field")
+
+        # all other fields should be present
+        assert updated_schema.field("id") is not None
+        assert updated_schema.field("id").arrow.type == pa.int64()
+        assert updated_schema.field("id").id == 1
+        assert updated_schema.field("name") is not None
+        assert updated_schema.field("name").arrow.type == pa.string()
+        assert updated_schema.field("name").id == 2
+
+    def test_alter_table_with_update_operation(self, test_namespace):
+        """Test altering a table with field update operation."""
+        namespace_name, catalog_properties = test_namespace
+        table_name = "test_alter_table_update"
+
+        # Create schema with a field to update
+        initial_fields = [
+            Field.of(
+                pa.field("id", pa.int64(), nullable=False),
+                is_merge_key=True,
+                field_id=1,
+            ),
+            Field.of(pa.field("value", pa.int32(), nullable=True), field_id=2),
+        ]
+        schema = Schema.of(initial_fields)
+
+        # Create the table
+        table = catalog.create_table(
+            table=table_name,
+            namespace=namespace_name,
+            schema=schema,
+            inner=catalog_properties,
+        )
+
+        original_schema = table.table_version.schema
+
+        # Update the value field to int64 (compatible type widening)
+        schema_update = original_schema.update().update_field_type("value", pa.int64())
+
+        # Alter the table
+        catalog.alter_table(
+            table=table_name,
+            namespace=namespace_name,
+            schema_updates=schema_update,
+            inner=catalog_properties,
+        )
+
+        # Get the updated table
+        updated_table_def = catalog.get_table(
+            table_name,
+            namespace=namespace_name,
+            inner=catalog_properties,
+        )
+
+        updated_schema = updated_table_def.table_version.schema
+
+        # Verify field was updated
+        assert updated_schema.field("value").arrow.type == pa.int64()
+        assert updated_schema.field("value").id == 2
+
+        # Verify schema ID was incremented
+        assert updated_schema.id == original_schema.id + 1
+
+    def test_alter_table_with_schema_evolution_disabled(self, test_namespace):
+        """Test that alter_table raises TableValidationError when schema evolution is disabled."""
+        namespace_name, catalog_properties = test_namespace
+        table_name = "test_alter_table_schema_evolution_disabled"
+
+        # Create initial schema
+        initial_fields = [
+            Field.of(
+                pa.field("id", pa.int64(), nullable=False),
+                is_merge_key=True,
+                field_id=1,
+            ),
+            Field.of(pa.field("value", pa.int32(), nullable=True), field_id=2),
+        ]
+        schema = Schema.of(initial_fields)
+
+        # Create table with SCHEMA_EVOLUTION_MODE.DISABLED
+        table_properties = {
+            TableProperty.SCHEMA_EVOLUTION_MODE: SchemaEvolutionMode.DISABLED
+        }
+
+        table = catalog.create_table(
+            table=table_name,
+            namespace=namespace_name,
+            schema=schema,
+            table_properties=table_properties,
+            inner=catalog_properties,
+        )
+
+        original_schema = table.table_version.schema
+
+        # Try to add a new field - this should be blocked
+        new_field = Field.of(pa.field("description", pa.string(), nullable=True))
+        schema_update = original_schema.update().add_field(new_field)
+
+        # Alter table with schema updates should raise TableValidationError
+        with pytest.raises(
+            TableValidationError,
+            match="Schema evolution is disabled for this table. Please enable schema evolution or remove schema updates.",
+        ):
+            catalog.alter_table(
+                table=table_name,
+                namespace=namespace_name,
+                schema_updates=schema_update,
                 inner=catalog_properties,
             )
 
+        # Verify the schema wasn't changed
+        unchanged_table_def = catalog.get_table(
+            table_name,
+            namespace=namespace_name,
+            inner=catalog_properties,
+        )
+        unchanged_schema = unchanged_table_def.table_version.schema
+
+        # Schema should be unchanged
+        assert unchanged_schema.id == original_schema.id
+        assert len(unchanged_schema.fields) == len(original_schema.fields)
+
+        # Verify the new field was not added
+        field_names = [field.arrow.name for field in unchanged_schema.fields]
+        assert "description" not in field_names
+
+        # Test that alter_table works without schema_updates even when schema evolution is disabled
+        catalog.alter_table(
+            table=table_name,
+            namespace=namespace_name,
+            table_description="Updated description without schema changes",
+            inner=catalog_properties,
+        )
+
+        # Verify that table description was updated but schema remains unchanged
+        final_table_def = catalog.get_table(
+            table_name,
+            namespace=namespace_name,
+            inner=catalog_properties,
+        )
+        assert (
+            final_table_def.table_version.description
+            == "Updated description without schema changes"
+        )
+        assert final_table_def.table_version.schema.id == original_schema.id
+
     def test_drop_with_purge_validation(self, test_namespace):
         """Test that using purge flag raises ValidationError"""
         namespace_name, catalog_properties = test_namespace
@@ -421,7 +800,9 @@ class TestCatalogTableOperations:
 
         # Create the table
         catalog.create_table(
-            name=table_name, namespace=namespace_name, inner=catalog_properties
+            table=table_name,
+            namespace=namespace_name,
+            inner=catalog_properties,
         )
 
         # Try to drop with purge=True, should raise ValidationError
@@ -429,8 +810,1163 @@ class TestCatalogTableOperations:
             NotImplementedError, match="Purge flag is not currently supported"
         ):
             catalog.drop_table(
-                name=table_name,
+                table=table_name,
                 namespace=namespace_name,
                 purge=True,
                 inner=catalog_properties,
             )
+
+    def test_create_table_basic(self):
+        """Test basic table creation"""
+        table_name = "test_create_table_basic"
+        schema = Schema.of(
+            schema=pa.schema(
+                [
+                    ("id", pa.int64()),
+                    ("name", pa.string()),
+                ]
+            )
+        )
+
+        table_def = catalog.create_table(
+            table=table_name,
+            namespace=self.test_namespace,
+            schema=schema,
+            inner=self.catalog_properties,
+        )
+
+        assert table_def.table.table_name == table_name
+        assert table_def.table_version.schema.equivalent_to(schema)
+
+        # Verify table exists
+        assert catalog.table_exists(
+            table=table_name,
+            namespace=self.test_namespace,
+            inner=self.catalog_properties,
+        )
+
+    def test_create_table_already_exists_fail_if_exists_true(self):
+        """Test creating a table that already exists with fail_if_exists=True"""
+        table_name = "test_create_table_exists"
+        schema = Schema.of(schema=pa.schema([("id", pa.int64())]))
+
+        # Create table first
+        catalog.create_table(
+            table=table_name,
+            namespace=self.test_namespace,
+            schema=schema,
+            inner=self.catalog_properties,
+        )
+
+        # Try to create again with fail_if_exists=True (default)
+        with pytest.raises(TableAlreadyExistsError):
+            catalog.create_table(
+                table=table_name,
+                namespace=self.test_namespace,
+                schema=schema,
+                fail_if_exists=True,
+                inner=self.catalog_properties,
+            )
+
+    def test_create_table_already_exists_fail_if_exists_false(self):
+        """Test creating a table that already exists with fail_if_exists=False"""
+        table_name = "test_create_table_exists_ok"
+        schema = Schema.of(schema=pa.schema([("id", pa.int64())]))
+
+        # Create table first
+        table_def1 = catalog.create_table(
+            table=table_name,
+            namespace=self.test_namespace,
+            schema=schema,
+            inner=self.catalog_properties,
+        )
+
+        # Create again with fail_if_exists=False should return existing table
+        table_def2 = catalog.create_table(
+            table=table_name,
+            namespace=self.test_namespace,
+            schema=schema,
+            fail_if_exists=False,
+            inner=self.catalog_properties,
+        )
+
+        assert table_def1.table.table_name == table_def2.table.table_name
+
+
+class TestWriteToTable:
+    """Test the write_to_table implementation with different modes and data types."""
+
+    @classmethod
+    def setup_class(cls):
+        cls.temp_dir = tempfile.mkdtemp()
+        cls.catalog_properties = get_catalog_properties(root=cls.temp_dir)
+
+        # Create a test namespace
+        cls.test_namespace = "test_write_to_table"
+        catalog.create_namespace(
+            namespace=cls.test_namespace, inner=cls.catalog_properties
+        )
+
+    @classmethod
+    def teardown_class(cls):
+        shutil.rmtree(cls.temp_dir)
+
+    def _create_test_pandas_data(self):
+        """Create test pandas DataFrame"""
+        return pd.DataFrame(
+            {
+                "id": [1, 2, 3, 4, 5],
+                "name": ["Alice", "Bob", "Charlie", "Dave", "Eve"],
+                "age": [25, 30, 35, 40, 45],
+                "city": ["NYC", "LA", "Chicago", "Houston", "Phoenix"],
+            }
+        )
+
+    def _create_test_pyarrow_data(self):
+        """Create test PyArrow Table"""
+        return pa.table(
+            {
+                "id": [1, 2, 3, 4, 5],
+                "name": ["Alice", "Bob", "Charlie", "Dave", "Eve"],
+                "age": [25, 30, 35, 40, 45],
+                "city": ["NYC", "LA", "Chicago", "Houston", "Phoenix"],
+            }
+        )
+
+    def _create_test_polars_data(self):
+        """Create test Polars DataFrame"""
+        return pl.DataFrame(
+            {
+                "id": [1, 2, 3, 4, 5],
+                "name": ["Alice", "Bob", "Charlie", "Dave", "Eve"],
+                "age": [25, 30, 35, 40, 45],
+                "city": ["NYC", "LA", "Chicago", "Houston", "Phoenix"],
+            }
+        )
+
+    def _create_second_batch_pandas_data(self):
+        """Create second batch of test data for append tests"""
+        return pd.DataFrame(
+            {
+                "id": [6, 7, 8],
+                "name": ["Frank", "Grace", "Henry"],
+                "age": [50, 55, 60],
+                "city": ["Boston", "Seattle", "Denver"],
+            }
+        )
+
+    def _create_test_ray_data(self):
+        """Create test Ray Dataset for schema inference testing."""
+        import ray
+
+        # Initialize Ray if not already initialized
+        # Note: Use distributed mode (not local_mode=True) to avoid Ray 2.46.0 internal bug
+        if not ray.is_initialized():
+            ray.init()
+
+        data = pa.table(
+            {
+                "id": [1, 2, 3, 4, 5],
+                "name": ["Alice", "Bob", "Charlie", "Dave", "Eve"],
+                "age": [25, 30, 35, 40, 45],
+                "city": ["NYC", "LA", "Chicago", "Houston", "Phoenix"],
+            }
+        )
+        return rd.from_arrow(data)
+
+    def _create_test_daft_data(self):
+        """Create test Daft DataFrame for schema inference testing."""
+        data = {
+            "id": [1, 2, 3],
+            "name": ["Alice", "Bob", "Charlie"],
+            "age": [25, 30, 35],
+            "city": ["NYC", "LA", "Chicago"],
+        }
+        return daft.from_pydict(data)
+
+    def _create_test_numpy_1d_data(self):
+        """Create test 1D numpy array for schema inference testing."""
+        return np.array([1, 2, 3, 4, 5])
+
+    def _create_test_numpy_2d_data(self):
+        """Create test 2D numpy array for schema inference testing."""
+        return np.array([[1, 25], [2, 30], [3, 35]], dtype=np.int64)
+
+    def _create_table_with_merge_keys(self, table_name: str):
+        """Create a table with merge keys for testing MERGE mode"""
+        from deltacat.storage.model.schema import Schema, Field
+
+        # Create schema with merge keys
+        schema = Schema.of(
+            [
+                Field.of(pa.field("id", pa.int64()), is_merge_key=True),  # merge key
+                Field.of(pa.field("name", pa.string())),
+                Field.of(pa.field("age", pa.int32())),
+                Field.of(pa.field("city", pa.string())),
+            ]
+        )
+
+        catalog.create_table(
+            table=table_name,
+            namespace=self.test_namespace,
+            schema=schema,
+            inner=self.catalog_properties,
+        )
+
+        return schema
+
+    def _create_table_without_merge_keys(self, table_name: str):
+        """Create a table without merge keys for testing APPEND mode"""
+        # Use schema inference with no merge keys
+        data = self._create_test_pandas_data()
+        catalog.write_to_table(
+            data=data,
+            table=table_name,
+            namespace=self.test_namespace,
+            mode=TableWriteMode.CREATE,
+            inner=self.catalog_properties,
+        )
+
+    # Test TableWriteMode.AUTO
+    def test_write_to_table_auto_create_new_table_pandas(self):
+        """Test AUTO mode creating a new table with pandas data"""
+        table_name = "test_auto_create_pandas"
+        data = self._create_test_pandas_data()
+
+        # Table doesn't exist, AUTO should create it
+        catalog.write_to_table(
+            data=data,
+            table=table_name,
+            namespace=self.test_namespace,
+            mode=TableWriteMode.AUTO,
+            inner=self.catalog_properties,
+        )
+
+        # Verify table was created
+        assert catalog.table_exists(
+            table=table_name,
+            namespace=self.test_namespace,
+            inner=self.catalog_properties,
+        )
+
+        # Verify table has correct schema
+        table_def = catalog.get_table(
+            table=table_name,
+            namespace=self.test_namespace,
+            inner=self.catalog_properties,
+        )
+        assert table_def.table_version.schema is not None
+
+    def test_write_to_table_auto_create_new_table_pyarrow(self):
+        """Test AUTO mode creating a new table with PyArrow data"""
+        table_name = "test_auto_create_pyarrow"
+        data = self._create_test_pyarrow_data()
+
+        catalog.write_to_table(
+            data=data,
+            table=table_name,
+            namespace=self.test_namespace,
+            mode=TableWriteMode.AUTO,
+            inner=self.catalog_properties,
+        )
+
+        assert catalog.table_exists(
+            table=table_name,
+            namespace=self.test_namespace,
+            inner=self.catalog_properties,
+        )
+
+    def test_write_to_table_auto_create_new_table_polars(self):
+        """Test AUTO mode creating a new table with Polars data"""
+        table_name = "test_auto_create_polars"
+        data = self._create_test_polars_data()
+
+        catalog.write_to_table(
+            data=data,
+            table=table_name,
+            namespace=self.test_namespace,
+            mode=TableWriteMode.AUTO,
+            inner=self.catalog_properties,
+        )
+
+        assert catalog.table_exists(
+            table=table_name,
+            namespace=self.test_namespace,
+            inner=self.catalog_properties,
+        )
+
+    def test_write_to_table_auto_append_existing_table(self):
+        """Test AUTO mode appending to existing table"""
+        table_name = "test_auto_append"
+        data1 = self._create_test_pandas_data()
+        data2 = self._create_second_batch_pandas_data()
+
+        # First write creates table
+        catalog.write_to_table(
+            data=data1,
+            table=table_name,
+            namespace=self.test_namespace,
+            mode=TableWriteMode.AUTO,
+            inner=self.catalog_properties,
+        )
+
+        # Second write should append
+        catalog.write_to_table(
+            data=data2,
+            table=table_name,
+            namespace=self.test_namespace,
+            mode=TableWriteMode.AUTO,
+            inner=self.catalog_properties,
+        )
+
+        # Verify table still exists
+        assert catalog.table_exists(
+            table=table_name,
+            namespace=self.test_namespace,
+            inner=self.catalog_properties,
+        )
+
+    # Test TableWriteMode.CREATE
+    def test_write_to_table_create_new_table(self):
+        """Test CREATE mode with new table"""
+        table_name = "test_create_new"
+        data = self._create_test_pandas_data()
+
+        catalog.write_to_table(
+            data=data,
+            table=table_name,
+            namespace=self.test_namespace,
+            mode=TableWriteMode.CREATE,
+            inner=self.catalog_properties,
+        )
+
+        assert catalog.table_exists(
+            table=table_name,
+            namespace=self.test_namespace,
+            inner=self.catalog_properties,
+        )
+
+    def test_write_to_table_create_existing_table_fails(self):
+        """Test CREATE mode fails when table exists"""
+        table_name = "test_create_fail"
+        data = self._create_test_pandas_data()
+
+        # Create table first
+        catalog.write_to_table(
+            data=data,
+            table=table_name,
+            namespace=self.test_namespace,
+            mode=TableWriteMode.CREATE,
+            inner=self.catalog_properties,
+        )
+
+        # Try to create again should fail
+        with pytest.raises(
+            TableAlreadyExistsError, match="already exists and mode is CREATE"
+        ):
+            catalog.write_to_table(
+                data=data,
+                table=table_name,
+                namespace=self.test_namespace,
+                mode=TableWriteMode.CREATE,
+                inner=self.catalog_properties,
+            )
+
+    # Test TableWriteMode.APPEND
+    def test_write_to_table_append_existing_table(self):
+        """Test APPEND mode with existing table"""
+        table_name = "test_append_existing"
+        data1 = self._create_test_pandas_data()
+        data2 = self._create_second_batch_pandas_data()
+
+        # Create table first
+        catalog.write_to_table(
+            data=data1,
+            table=table_name,
+            namespace=self.test_namespace,
+            mode=TableWriteMode.CREATE,
+            inner=self.catalog_properties,
+        )
+
+        # Append to existing table
+        catalog.write_to_table(
+            data=data2,
+            table=table_name,
+            namespace=self.test_namespace,
+            mode=TableWriteMode.APPEND,
+            inner=self.catalog_properties,
+        )
+
+    def test_write_to_table_append_nonexistent_table_fails(self):
+        """Test APPEND mode fails when table doesn't exist"""
+        table_name = "test_append_fail"
+        data = self._create_test_pandas_data()
+
+        with pytest.raises(
+            TableNotFoundError,
+            match="does not exist and write mode is append. Use CREATE or AUTO mode",
+        ):
+            catalog.write_to_table(
+                data=data,
+                table=table_name,
+                namespace=self.test_namespace,
+                mode=TableWriteMode.APPEND,
+                inner=self.catalog_properties,
+            )
+
+    def test_write_to_table_append_with_merge_keys_fails(self):
+        """Test APPEND mode fails when table has merge keys"""
+        table_name = "test_append_with_merge_keys"
+
+        # Create a table with merge keys
+        self._create_table_with_merge_keys(table_name)
+
+        # Create test data that matches the schema
+        data = pd.DataFrame(
+            {
+                "id": [1, 2, 3],
+                "name": ["Alice", "Bob", "Charlie"],
+                "age": [25, 30, 35],
+                "city": ["NYC", "LA", "Chicago"],
+            }
+        )
+
+        # APPEND mode should fail since table has merge keys
+        with pytest.raises(
+            SchemaValidationError,
+            match="APPEND mode cannot be used with tables that have merge keys",
+        ):
+            catalog.write_to_table(
+                data=data,
+                table=table_name,
+                namespace=self.test_namespace,
+                mode=TableWriteMode.APPEND,
+                inner=self.catalog_properties,
+            )
+
+    def test_write_to_table_append_without_merge_keys_succeeds(self):
+        """Test APPEND mode works when table has no merge keys"""
+        table_name = "test_append_no_merge_keys"
+
+        # Create a table without merge keys
+        self._create_table_without_merge_keys(table_name)
+
+        # Add more data to the table
+        data2 = self._create_second_batch_pandas_data()
+
+        # APPEND mode should work since table has no merge keys
+        catalog.write_to_table(
+            data=data2,
+            table=table_name,
+            namespace=self.test_namespace,
+            mode=TableWriteMode.APPEND,
+            inner=self.catalog_properties,
+        )
+
+        # Table should still exist
+        assert catalog.table_exists(
+            table=table_name,
+            namespace=self.test_namespace,
+            inner=self.catalog_properties,
+        )
+
+    # Test explicit schema specification
+    def test_write_to_table_explicit_schema(self):
+        """Test writing with explicit schema specification"""
+        table_name = "test_explicit_schema"
+        data = self._create_test_pandas_data()
+
+        # Define explicit schema with COERCE consistency types to preserve exact types
+        explicit_schema = Schema.of(
+            schema=[
+                Field.of(
+                    pa.field("id", pa.int64()),
+                    consistency_type=SchemaConsistencyType.COERCE,
+                ),
+                Field.of(
+                    pa.field("name", pa.string()),
+                    consistency_type=SchemaConsistencyType.COERCE,
+                ),
+                Field.of(
+                    pa.field("age", pa.int32()),
+                    consistency_type=SchemaConsistencyType.COERCE,
+                ),  # Different from inferred schema
+                Field.of(
+                    pa.field("city", pa.string()),
+                    consistency_type=SchemaConsistencyType.COERCE,
+                ),
+            ]
+        )
+
+        catalog.write_to_table(
+            data=data,
+            table=table_name,
+            namespace=self.test_namespace,
+            mode=TableWriteMode.CREATE,
+            schema=explicit_schema,
+            inner=self.catalog_properties,
+        )
+
+        # Verify schema was used
+        table_def = catalog.get_table(
+            table=table_name,
+            namespace=self.test_namespace,
+            inner=self.catalog_properties,
+        )
+        assert table_def.table_version.schema.equivalent_to(explicit_schema)
+
+    def test_write_to_table_explicit_schema_none(self):
+        """Test writing with explicit schema=None to create schemaless table"""
+        table_name = "test_explicit_schema_none"
+        data = self._create_test_pandas_data()
+
+        catalog.write_to_table(
+            data=data,
+            table=table_name,
+            namespace=self.test_namespace,
+            mode=TableWriteMode.CREATE,
+            schema=None,  # Explicitly set schema=None
+            inner=self.catalog_properties,
+        )
+
+        # Verify table was created with schema=None (schemaless)
+        table_def = catalog.get_table(
+            table=table_name,
+            namespace=self.test_namespace,
+            inner=self.catalog_properties,
+        )
+
+        # The table should exist but have a None/empty schema
+        assert table_def is not None
+        # Note: The exact behavior of schemaless tables may vary by storage implementation
+        # We're mainly testing that the create_table call succeeded with schema=None
+
+    def test_schema_behavior_comparison(self):
+        """Test that demonstrates the difference between no schema vs explicit schema=None"""
+        data = self._create_test_pandas_data()
+
+        # Case 1: No schema argument - should infer schema
+        table_name_inferred = "test_schema_inferred"
+        catalog.write_to_table(
+            data=data,
+            table=table_name_inferred,
+            namespace=self.test_namespace,
+            mode=TableWriteMode.CREATE,
+            # No schema argument provided - should infer from data
+            inner=self.catalog_properties,
+        )
+
+        # Case 2: Explicit schema=None - should create schemaless table
+        table_name_schemaless = "test_schema_none"
+        catalog.write_to_table(
+            data=data,
+            table=table_name_schemaless,
+            namespace=self.test_namespace,
+            mode=TableWriteMode.CREATE,
+            schema=None,  # Explicitly set schema=None
+            inner=self.catalog_properties,
+        )
+
+        # Verify both tables were created
+        table_inferred = catalog.get_table(
+            table=table_name_inferred,
+            namespace=self.test_namespace,
+            inner=self.catalog_properties,
+        )
+
+        table_schemaless = catalog.get_table(
+            table=table_name_schemaless,
+            namespace=self.test_namespace,
+            inner=self.catalog_properties,
+        )
+
+        # Both tables should exist
+        assert table_inferred is not None
+        assert table_schemaless is not None
+
+        # The inferred schema table should have a schema with the expected columns
+        inferred_schema = table_inferred.table_version.schema.arrow
+        assert "id" in inferred_schema.names
+        assert "name" in inferred_schema.names
+        assert "age" in inferred_schema.names
+        assert "city" in inferred_schema.names
+
+    # Test schema inference from different data types
+    def test_schema_inference_pandas(self):
+        """Test schema inference from pandas DataFrame"""
+        table_name = "test_schema_inference_pandas"
+        data = pd.DataFrame(
+            {
+                "int_col": [1, 2, 3],
+                "float_col": [1.1, 2.2, 3.3],
+                "str_col": ["a", "b", "c"],
+                "bool_col": [True, False, True],
+            }
+        )
+
+        catalog.write_to_table(
+            data=data,
+            table=table_name,
+            namespace=self.test_namespace,
+            mode=TableWriteMode.CREATE,
+            inner=self.catalog_properties,
+        )
+
+        table_def = catalog.get_table(
+            table=table_name,
+            namespace=self.test_namespace,
+            inner=self.catalog_properties,
+        )
+
+        schema = table_def.table_version.schema.arrow
+        assert "int_col" in schema.names
+        assert "float_col" in schema.names
+        assert "str_col" in schema.names
+        assert "bool_col" in schema.names
+
+    def test_schema_inference_pyarrow(self):
+        """Test schema inference from PyArrow Table"""
+        table_name = "test_schema_inference_pyarrow"
+        data = pa.table(
+            {
+                "int64_col": pa.array([1, 2, 3], type=pa.int64()),
+                "string_col": pa.array(["x", "y", "z"], type=pa.string()),
+                "double_col": pa.array([1.1, 2.2, 3.3], type=pa.float64()),
+            }
+        )
+
+        catalog.write_to_table(
+            data=data,
+            table=table_name,
+            namespace=self.test_namespace,
+            mode=TableWriteMode.CREATE,
+            inner=self.catalog_properties,
+        )
+
+        table_def = catalog.get_table(
+            table=table_name,
+            namespace=self.test_namespace,
+            inner=self.catalog_properties,
+        )
+
+        schema = table_def.table_version.schema.arrow
+        assert schema.field("int64_col").type == pa.int64()
+        assert schema.field("string_col").type == pa.string()
+        assert schema.field("double_col").type == pa.float64()
+
+    def test_schema_inference_polars(self):
+        """Test schema inference from Polars DataFrame"""
+        table_name = "test_schema_inference_polars"
+        data = pl.DataFrame(
+            {
+                "int_col": [1, 2, 3],
+                "str_col": ["a", "b", "c"],
+                "float_col": [1.1, 2.2, 3.3],
+            }
+        )
+
+        catalog.write_to_table(
+            data=data,
+            table=table_name,
+            namespace=self.test_namespace,
+            mode=TableWriteMode.CREATE,
+            inner=self.catalog_properties,
+        )
+
+        table_def = catalog.get_table(
+            table=table_name,
+            namespace=self.test_namespace,
+            inner=self.catalog_properties,
+        )
+
+        schema = table_def.table_version.schema.arrow
+        assert "int_col" in schema.names
+        assert "str_col" in schema.names
+        assert "float_col" in schema.names
+
+    def test_schema_inference_ray_dataset(self):
+        """Test schema inference from Ray Dataset"""
+        table_name = "test_schema_inference_ray"
+        ray_data = self._create_test_ray_data()
+
+        catalog.write_to_table(
+            data=ray_data,
+            table=table_name,
+            namespace=self.test_namespace,
+            mode=TableWriteMode.CREATE,
+            inner=self.catalog_properties,
+        )
+
+        table_def = catalog.get_table(
+            table=table_name,
+            namespace=self.test_namespace,
+            inner=self.catalog_properties,
+        )
+
+        schema = table_def.table_version.schema.arrow
+        assert "id" in schema.names
+        assert "name" in schema.names
+        assert "age" in schema.names
+        assert "city" in schema.names
+
+    def test_schema_inference_daft_dataframe(self):
+        """Test schema inference from Daft DataFrame"""
+        table_name = "test_schema_inference_daft"
+        data = self._create_test_daft_data()
+
+        catalog.write_to_table(
+            data=data,
+            table=table_name,
+            namespace=self.test_namespace,
+            mode=TableWriteMode.CREATE,
+            inner=self.catalog_properties,
+        )
+
+        table_def = catalog.get_table(
+            table=table_name,
+            namespace=self.test_namespace,
+            inner=self.catalog_properties,
+        )
+
+        schema = table_def.table_version.schema.arrow
+        assert "id" in schema.names
+        assert "name" in schema.names
+        assert "age" in schema.names
+        assert "city" in schema.names
+
+    def test_schema_inference_numpy_1d(self):
+        """Test schema inference from 1D numpy array"""
+        table_name = "test_schema_inference_numpy_1d"
+        data = self._create_test_numpy_1d_data()
+
+        catalog.write_to_table(
+            data=data,
+            table=table_name,
+            namespace=self.test_namespace,
+            mode=TableWriteMode.CREATE,
+            inner=self.catalog_properties,
+        )
+
+        table_def = catalog.get_table(
+            table=table_name,
+            namespace=self.test_namespace,
+            inner=self.catalog_properties,
+        )
+
+        schema = table_def.table_version.schema.arrow
+        assert (
+            "0" in schema.names
+        )  # pandas converts 1D numpy array with column name "0"
+        assert len(schema.names) == 1
+
+    def test_schema_inference_numpy_2d(self):
+        """Test schema inference from 2D numpy array"""
+        table_name = "test_schema_inference_numpy_2d"
+        data = self._create_test_numpy_2d_data()
+
+        catalog.write_to_table(
+            data=data,
+            table=table_name,
+            namespace=self.test_namespace,
+            mode=TableWriteMode.CREATE,
+            inner=self.catalog_properties,
+        )
+
+        table_def = catalog.get_table(
+            table=table_name,
+            namespace=self.test_namespace,
+            inner=self.catalog_properties,
+        )
+
+        schema = table_def.table_version.schema.arrow
+        assert (
+            "0" in schema.names
+        )  # pandas converts 2D numpy array with column names "0", "1"
+        assert "1" in schema.names
+        assert len(schema.names) == 2
+
+    def test_numpy_3d_array_error(self):
+        """Test that 3D numpy arrays raise an error"""
+        table_name = "test_numpy_3d_error"
+        data = np.array([[[1, 2], [3, 4]], [[5, 6], [7, 8]]])  # 3D array
+
+        with pytest.raises(
+            ValueError, match="NumPy arrays with 3 dimensions are not supported"
+        ):
+            catalog.write_to_table(
+                data=data,
+                table=table_name,
+                namespace=self.test_namespace,
+                mode=TableWriteMode.CREATE,
+                inner=self.catalog_properties,
+            )
+
+    # Test different content types
+    def test_write_to_table_different_content_types(self):
+        """Test writing with different content types"""
+        data = self._create_test_pandas_data()
+
+        content_types = [
+            ContentType.PARQUET,
+            ContentType.CSV,
+            ContentType.JSON,
+        ]
+
+        for i, content_type in enumerate(content_types):
+            table_name = f"test_content_type_{content_type.value}_{i}"
+
+            catalog.write_to_table(
+                data=data,
+                table=table_name,
+                namespace=self.test_namespace,
+                mode=TableWriteMode.CREATE,
+                content_type=content_type,
+                inner=self.catalog_properties,
+                schema=None,
+            )
+
+            assert catalog.table_exists(
+                table=table_name,
+                namespace=self.test_namespace,
+                inner=self.catalog_properties,
+            )
+
+    # Test table creation parameters
+    def test_write_to_table_with_table_properties(self):
+        """Test writing with table creation parameters"""
+        table_name = "test_table_properties"
+        data = self._create_test_pandas_data()
+
+        catalog.write_to_table(
+            data=data,
+            table=table_name,
+            namespace=self.test_namespace,
+            mode=TableWriteMode.CREATE,
+            table_description="Test table with properties",
+            lifecycle_state=LifecycleState.ACTIVE,
+            inner=self.catalog_properties,
+        )
+
+        table_def = catalog.get_table(
+            table=table_name,
+            namespace=self.test_namespace,
+            inner=self.catalog_properties,
+        )
+
+        assert table_def.table.description == "Test table with properties"
+        # Note: lifecycle_state defaults to ACTIVE in create_table, but may be overridden
+        # We'll accept either ACTIVE or CREATED as both are valid for our test purpose
+        assert table_def.table_version.state in [
+            LifecycleState.ACTIVE,
+            LifecycleState.CREATED,
+        ]
+
+    # Test error conditions
+    def test_write_to_table_unsupported_data_type(self):
+        """Test error when data type cannot be inferred"""
+        table_name = "test_unsupported_data"
+
+        # Use a plain dict which doesn't have schema inference
+        unsupported_data = {"key": "value"}
+
+        with pytest.raises(
+            ValueError, match="No schema inference function found for table type"
+        ):
+            catalog.write_to_table(
+                data=unsupported_data,
+                table=table_name,
+                namespace=self.test_namespace,
+                mode=TableWriteMode.CREATE,
+                inner=self.catalog_properties,
+            )
+
+    def test_write_to_table_replace_mode(self):
+        """Test REPLACE mode creating a new stream to replace existing data"""
+        table_name = "test_replace_mode"
+        data1 = self._create_test_pandas_data()
+        data2 = self._create_second_batch_pandas_data()
+
+        # First, create the table
+        catalog.write_to_table(
+            data=data1,
+            table=table_name,
+            namespace=self.test_namespace,
+            mode=TableWriteMode.CREATE,
+            inner=self.catalog_properties,
+        )
+
+        # Verify table exists
+        assert catalog.table_exists(
+            table=table_name,
+            namespace=self.test_namespace,
+            inner=self.catalog_properties,
+        )
+
+        # Now use REPLACE mode to replace all existing data
+        catalog.write_to_table(
+            data=data2,
+            table=table_name,
+            namespace=self.test_namespace,
+            mode=TableWriteMode.REPLACE,
+            inner=self.catalog_properties,
+        )
+
+        # Table should still exist
+        assert catalog.table_exists(
+            table=table_name,
+            namespace=self.test_namespace,
+            inner=self.catalog_properties,
+        )
+
+    def test_write_to_table_merge_mode_with_merge_keys(self):
+        """Test MERGE mode works when table has merge keys"""
+        table_name = "test_merge_mode_with_keys"
+
+        # Create a table with merge keys
+        self._create_table_with_merge_keys(table_name)
+
+        # Create test data that matches the schema
+        data = pd.DataFrame(
+            {
+                "id": [1, 2, 3],
+                "name": ["Alice", "Bob", "Charlie"],
+                "age": [25, 30, 35],
+                "city": ["NYC", "LA", "Chicago"],
+            }
+        )
+
+        # MERGE mode should work since table has merge keys
+        catalog.write_to_table(
+            data=data,
+            table=table_name,
+            namespace=self.test_namespace,
+            mode=TableWriteMode.MERGE,
+            inner=self.catalog_properties,
+        )
+
+        # Table should still exist
+        assert catalog.table_exists(
+            table=table_name,
+            namespace=self.test_namespace,
+            inner=self.catalog_properties,
+        )
+
+    def test_write_to_table_merge_mode_without_merge_keys_fails(self):
+        """Test MERGE mode fails when table has no merge keys"""
+        table_name = "test_merge_mode_no_keys"
+
+        # Create a table without merge keys
+        self._create_table_without_merge_keys(table_name)
+
+        data = self._create_test_pandas_data()
+
+        # MERGE mode should fail since table has no merge keys
+        with pytest.raises(
+            TableValidationError,
+            match="MERGE mode requires tables to have at least one merge key",
+        ):
+            catalog.write_to_table(
+                data=data,
+                table=table_name,
+                namespace=self.test_namespace,
+                mode=TableWriteMode.MERGE,
+                inner=self.catalog_properties,
+            )
+
+    # Test default namespace behavior
+    def test_write_to_table_default_namespace(self):
+        """Test writing to table using default namespace"""
+        table_name = "test_default_namespace"
+        data = self._create_test_pandas_data()
+
+        # Don't specify namespace, should use default
+        catalog.write_to_table(
+            data=data,
+            table=table_name,
+            mode=TableWriteMode.CREATE,
+            inner=self.catalog_properties,
+        )
+
+        # Should be able to find table in default namespace
+        default_ns = catalog.default_namespace(inner=self.catalog_properties)
+        assert catalog.table_exists(
+            table=table_name, namespace=default_ns, inner=self.catalog_properties
+        )
+
+    def test_write_to_table_append_creates_separate_deltas(self):
+        """Test that APPEND mode creates separate deltas in the same partition"""
+        from deltacat.catalog.main.impl import _get_storage
+
+        table_name = "test_append_separate_deltas"
+        data1 = self._create_test_pandas_data()
+        data2 = self._create_second_batch_pandas_data()
+
+        # Create table with first batch
+        catalog.write_to_table(
+            data=data1,
+            table=table_name,
+            namespace=self.test_namespace,
+            mode=TableWriteMode.CREATE,
+            inner=self.catalog_properties,
+        )
+
+        # Get the table definition to access stream information
+        table_def = catalog.get_table(
+            table=table_name,
+            namespace=self.test_namespace,
+            inner=self.catalog_properties,
+        )
+
+        # Get storage interface
+        storage = _get_storage(inner=self.catalog_properties)
+
+        # Get the stream
+        stream = storage.get_stream(
+            namespace=self.test_namespace,
+            table_name=table_name,
+            table_version=table_def.table_version.table_version,
+            inner=self.catalog_properties,
+        )
+
+        # Get the partition (should be only one for unpartitioned table)
+        partition = storage.get_partition(
+            stream_locator=stream.locator,
+            partition_values=None,  # unpartitioned
+            inner=self.catalog_properties,
+        )
+
+        # List deltas before second write
+        deltas_before = storage.list_partition_deltas(
+            partition_like=partition,
+            inner=self.catalog_properties,
+        ).all_items()
+
+        assert (
+            len(deltas_before) == 1
+        ), f"Expected 1 delta before append, got {len(deltas_before)}"
+
+        # Append second batch using APPEND mode
+        catalog.write_to_table(
+            data=data2,
+            table=table_name,
+            namespace=self.test_namespace,
+            mode=TableWriteMode.APPEND,
+            inner=self.catalog_properties,
+        )
+
+        # Get the same partition again (should be the same partition object)
+        partition_after = storage.get_partition(
+            stream_locator=stream.locator,
+            partition_values=None,  # unpartitioned
+            inner=self.catalog_properties,
+        )
+
+        # Verify it's the same partition
+        assert (
+            partition.partition_id == partition_after.partition_id
+        ), "APPEND should reuse the same partition"
+
+        # List deltas after second write
+        deltas_after = storage.list_partition_deltas(
+            partition_like=partition_after,
+            inner=self.catalog_properties,
+        ).all_items()
+
+        # Should now have 2 deltas in the same partition
+        assert (
+            len(deltas_after) == 2
+        ), f"Expected 2 deltas after append, got {len(deltas_after)}"
+
+        # Verify deltas have different stream positions
+        stream_positions = [delta.stream_position for delta in deltas_after]
+        assert (
+            len(set(stream_positions)) == 2
+        ), "Deltas should have different stream positions"
+        assert min(stream_positions) == 1, "First delta should have stream position 1"
+        assert max(stream_positions) == 2, "Second delta should have stream position 2"
+
+    def test_write_to_table_partitioned_table_raises_not_implemented(self):
+        """Test that write_to_table raises NotImplementedError for partitioned tables"""
+        from deltacat.storage.model.partition import (
+            PartitionScheme,
+            PartitionKey,
+            PartitionKeyList,
+        )
+        from deltacat.storage.model.transform import IdentityTransform
+
+        table_name = "test_partitioned_table"
+        data = self._create_test_pandas_data()
+
+        # Create a partition scheme with partition keys
+        partition_keys = [
+            PartitionKey.of(
+                key=["city"],
+                name="city_partition",
+                transform=IdentityTransform.of(),
+            )
+        ]
+        partition_scheme = PartitionScheme.of(
+            keys=PartitionKeyList.of(partition_keys),
+            name="test_partition_scheme",
+            scheme_id="test_partition_scheme_id",
+        )
+
+        # Try to create a partitioned table using write_to_table
+        with pytest.raises(
+            NotImplementedError,
+            match="write_to_table does not yet support partitioned tables",
+        ):
+            catalog.write_to_table(
+                data=data,
+                table=table_name,
+                namespace=self.test_namespace,
+                mode=TableWriteMode.CREATE,
+                partition_scheme=partition_scheme,  # This makes it partitioned
+                inner=self.catalog_properties,
+            )
+
+    def test_write_to_table_sorted_table_raises_not_implemented(self):
+        """Test that write_to_table raises NotImplementedError for tables with sort keys"""
+        from deltacat.storage.model.sort_key import SortScheme, SortKey, SortKeyList
+        from deltacat.storage.model.types import SortOrder, NullOrder
+
+        table_name = "test_sorted_table"
+        data = self._create_test_pandas_data()
+
+        # Create sort scheme with sort keys
+        sort_scheme = SortScheme.of(
+            keys=SortKeyList.of(
+                [
+                    SortKey.of(
+                        key=["id"],
+                        sort_order=SortOrder.ASCENDING,
+                        null_order=NullOrder.AT_END,
+                    )
+                ]
+            ),
+            name="test_sort_scheme",
+            scheme_id="test_sort_scheme_id",
+        )
+
+        # Create table with sort keys
+        catalog.create_table(
+            table=table_name,
+            namespace=self.test_namespace,
+            sort_keys=sort_scheme,
+            inner=self.catalog_properties,
+        )
+
+        # Attempt to write to the sorted table should raise NotImplementedError
+        with pytest.raises(NotImplementedError) as exc_info:
+            catalog.write_to_table(
+                data=data,
+                table=table_name,
+                namespace=self.test_namespace,
+                mode=TableWriteMode.APPEND,
+                inner=self.catalog_properties,
+            )
+
+        # Verify the error message contains expected information
+        assert "sort keys" in str(exc_info.value)
+        assert "sort scheme with 1 sort key(s)" in str(exc_info.value)
+        assert "id" in str(exc_info.value)