Merge pull request #133 from weaviate/jose/fix-collection-alias-data-creation

Support collection aliases in all data operations

Author: jfrancoa

.claude/skills/operating-weaviate-cli/SKILL.md

@@ -183,6 +183,8 @@ Key query options: `--properties "title,keywords"`, `--tenants "T1"`, `--target_
 
 **Note**: `--consistency_level` values must be **lowercase**: `one`, `quorum`, `all` (not `ONE`, `QUORUM`, `ALL`).
 
+**Alias support**: The `--collection` flag accepts collection aliases in all data commands. If the name isn't a direct collection, the CLI checks the alias list automatically.
+
 See [references/data.md](references/data.md) and [references/search.md](references/search.md).
 
 ### Tenants
@@ -213,7 +215,7 @@ weaviate-cli restore backup --backend s3 --backup_id my-backup --wait --json
 weaviate-cli cancel backup --backend s3 --backup_id my-backup --json
 ```
 
-Backends: `s3`, `gcs`, `filesystem`. Options: `--include`, `--exclude`, `--wait`, `--cpu_for_backup N`
+Backends: `s3`, `gcs`, `filesystem`. Options: `--include`, `--exclude`, `--wait`, `--cpu_for_backup N`, `--override-alias`
 
 See [references/backups.md](references/backups.md).
 

.claude/skills/operating-weaviate-cli/references/backups.md

@@ -23,6 +23,7 @@ weaviate-cli get backup --backend s3 --backup_id my-backup --restore --json
 ```bash
 weaviate-cli restore backup --backend s3 --backup_id my-backup --wait --json
 weaviate-cli restore backup --backend s3 --backup_id my-backup --include "Movies" --wait --json
+weaviate-cli restore backup --backend s3 --backup_id my-backup --override-alias --wait --json
 ```
 
 ## Cancel Backup
@@ -44,6 +45,7 @@ weaviate-cli cancel backup --backend s3 --backup_id my-backup --json
 - `--backend`, `--backup_id` -- Same as create
 - `--include`, `--exclude` -- Filter which collections to restore
 - `--wait` -- Wait for completion
+- `--override-alias` -- Override alias conflicts during restore. Use when the backup contains a collection with an alias that differs from the current cluster state (e.g., the backup had alias `Movies` pointing to `Movies_v1`, but the cluster now has `Movies` pointing to `Movies_v2`). Without this flag, the restore will fail due to the alias conflict.
 
 ## Prerequisites
 

.claude/skills/operating-weaviate-cli/references/data.md

@@ -50,6 +50,19 @@ weaviate-cli delete data --collection "Movies" --tenants "T1,T2" --limit 50 --js
 3. **For multi-tenant data ingestion:** tenants must be in `hot`/`active` state
 4. **For vectorizer-based ingestion (non-randomize):** the collection uses a built-in dataset; vectorizer API keys may be needed
 
+## Using Aliases
+
+The `--collection` flag accepts aliases in all data commands (`create data`, `query data`, `update data`, `delete data`). If the given name doesn't match a collection directly, the CLI checks the alias list and resolves it transparently.
+
+```bash
+# Create an alias, then use it for data operations
+weaviate-cli create alias MyAlias Movies --json
+weaviate-cli create data --collection MyAlias --limit 100 --randomize --json
+weaviate-cli query data --collection MyAlias --search_type fetch --limit 10 --json
+weaviate-cli update data --collection MyAlias --limit 50 --randomize --json
+weaviate-cli delete data --collection MyAlias --limit 50 --json
+```
+
 ## Notes
 
 - `--randomize` generates synthetic data with random vectors -- useful for testing

test/unittests/test_managers/test_data_manager.py

@@ -223,6 +223,118 @@ def test_fallback_no_tenants_with_auto_creation_returns_empty(self) -> None:
         assert result == []
 
 
+# ---------------------------------------------------------------------------
+# Alias resolution in data operations
+# ---------------------------------------------------------------------------
+
+
+class TestAliasResolution:
+    """Unit tests for alias resolution in create/update/delete/query data."""
+
+    def _setup_alias_mock(self, mock_client, alias_name="MyAlias"):
+        """Set up a mock client where collection doesn't exist but alias does."""
+        mock_collections = MagicMock()
+        mock_collections.exists.return_value = False
+        mock_client.collections = mock_collections
+
+        mock_alias = MagicMock()
+        mock_alias.list_all.return_value = {alias_name: MagicMock()}
+        mock_client.alias = mock_alias
+
+        mock_collection = MagicMock()
+        mock_collection.config.get.return_value = MagicMock(
+            multi_tenancy_config=MagicMock(
+                enabled=False,
+                auto_tenant_creation=False,
+                auto_tenant_activation=False,
+            )
+        )
+        mock_client.collections.get.return_value = mock_collection
+        return mock_collection
+
+    def test_create_data_with_alias(self, mock_client):
+        self._setup_alias_mock(mock_client)
+        manager = DataManager(mock_client)
+        manager.create_data(collection="MyAlias", limit=10, randomize=True)
+        mock_client.collections.get.assert_called_once_with("MyAlias")
+
+    def test_update_data_with_alias(self, mock_client):
+        self._setup_alias_mock(mock_client)
+        manager = DataManager(mock_client)
+        manager.update_data(collection="MyAlias", limit=10, randomize=True)
+        mock_client.collections.get.assert_called_once_with("MyAlias")
+
+    def test_delete_data_with_alias(self, mock_client):
+        col = self._setup_alias_mock(mock_client)
+        col.config.get.return_value.multi_tenancy_config.enabled = False
+        # delete_data iterates objects, mock the iterator
+        col.iterator.return_value = iter([])
+        manager = DataManager(mock_client)
+        manager.delete_data(collection="MyAlias", limit=10)
+        mock_client.collections.get.assert_called_once_with("MyAlias")
+
+    def test_query_data_with_alias(self, mock_client):
+        col = self._setup_alias_mock(mock_client)
+        col.config.get.return_value.multi_tenancy_config.enabled = False
+        col.query.fetch_objects.return_value = MagicMock(objects=[])
+        manager = DataManager(mock_client)
+        manager.query_data(collection="MyAlias", search_type="fetch", limit=5)
+        mock_client.collections.get.assert_called_once_with("MyAlias")
+
+    def _setup_not_found_mock(self, mock_client):
+        """Set up a mock client where neither collection nor alias exists."""
+        mock_collections = MagicMock()
+        mock_collections.exists.return_value = False
+        mock_client.collections = mock_collections
+        mock_alias = MagicMock()
+        mock_alias.list_all.return_value = {}
+        mock_client.alias = mock_alias
+
+    def test_create_data_not_collection_not_alias_raises(self, mock_client):
+        self._setup_not_found_mock(mock_client)
+        manager = DataManager(mock_client)
+        with pytest.raises(Exception, match="does not exist"):
+            manager.create_data(collection="NonExistent", limit=10, randomize=True)
+
+    def test_update_data_not_collection_not_alias_raises(self, mock_client):
+        self._setup_not_found_mock(mock_client)
+        manager = DataManager(mock_client)
+        with pytest.raises(Exception, match="does not exist"):
+            manager.update_data(collection="NonExistent", limit=10, randomize=True)
+
+    def test_delete_data_not_collection_not_alias_raises(self, mock_client):
+        self._setup_not_found_mock(mock_client)
+        manager = DataManager(mock_client)
+        with pytest.raises(Exception, match="does not exist"):
+            manager.delete_data(collection="NonExistent", limit=10)
+
+    def test_query_data_not_collection_not_alias_raises(self, mock_client):
+        self._setup_not_found_mock(mock_client)
+        manager = DataManager(mock_client)
+        with pytest.raises(Exception, match="does not exist"):
+            manager.query_data(collection="NonExistent", search_type="fetch", limit=5)
+
+    def test_create_data_direct_collection_skips_alias_check(self, mock_client):
+        """When collection exists directly, alias.list_all should not be called."""
+        mock_collections = MagicMock()
+        mock_collections.exists.return_value = True
+        mock_client.collections = mock_collections
+        mock_alias = MagicMock()
+        mock_client.alias = mock_alias
+        mock_collection = MagicMock()
+        mock_collection.config.get.return_value = MagicMock(
+            multi_tenancy_config=MagicMock(
+                enabled=False,
+                auto_tenant_creation=False,
+                auto_tenant_activation=False,
+            )
+        )
+        mock_client.collections.get.return_value = mock_collection
+        manager = DataManager(mock_client)
+        manager.create_data(collection="DirectCollection", limit=10, randomize=True)
+        mock_client.alias.list_all.assert_not_called()
+
+
 def test_ingest_data(mock_client):
     manager = DataManager(mock_client)
     mock_collections = MagicMock()

weaviate_cli/commands/restore.py

@@ -38,11 +38,18 @@ def restore() -> None:
     default=RestoreBackupDefaults.exclude,
     help="Collection to exclude in backup (default: None).",
 )
+@click.option(
+    "--override-alias",
+    is_flag=True,
+    help="Override the alias of the collection (default: False).",
+)
 @click.option(
     "--json", "json_output", is_flag=True, default=False, help="Output in JSON format."
 )
 @click.pass_context
-def restore_backup_cli(ctx, backend, include, exclude, backup_id, wait, json_output):
+def restore_backup_cli(
+    ctx, backend, include, exclude, backup_id, wait, override_alias, json_output
+):
     """Restore a backup in Weaviate."""
 
     client = None
@@ -55,6 +62,7 @@ def restore_backup_cli(ctx, backend, include, exclude, backup_id, wait, json_out
             include=include,
             exclude=exclude,
             wait=wait,
+            override_alias=override_alias,
             json_output=json_output,
         )
     except Exception as e:

weaviate_cli/defaults.py

@@ -237,6 +237,7 @@ class RestoreBackupDefaults:
     wait: bool = False
     include: Optional[str] = None
     exclude: Optional[str] = None
+    override_alias: bool = False
 
 
 @dataclass

weaviate_cli/managers/backup_manager.py

@@ -14,7 +14,7 @@
 
 class BackupManager:
     def __init__(self, client: WeaviateClient) -> None:
-        self.client = client
+        self.client: WeaviateClient = client
 
     def create_backup(
         self,
@@ -81,6 +81,7 @@ def restore_backup(
         include: Optional[str] = RestoreBackupDefaults.include,
         exclude: Optional[str] = RestoreBackupDefaults.exclude,
         wait: bool = RestoreBackupDefaults.wait,
+        override_alias: bool = RestoreBackupDefaults.override_alias,
         json_output: bool = False,
     ) -> None:
 
@@ -89,6 +90,7 @@ def restore_backup(
             backend=backend,
             include_collections=include.split(",") if include else None,
             exclude_collections=exclude.split(",") if exclude else None,
+            overwrite_alias=override_alias,
             wait_for_completion=wait,
         )
 

weaviate_cli/managers/data_manager.py

@@ -572,6 +572,7 @@ def __import_json(
         json_output: bool = False,
     ) -> int:
         counter = 0
+
         properties: List[wvc.Property] = collection.config.get().properties
 
         try:
@@ -657,8 +658,9 @@ def __ingest_data(
                 click.echo(f"Generating and ingesting {num_objects} objects")
             start_time = time.time()
 
-            # Determine vectorizer setup
+            # Determine vector dimensions based on vectorizer
             config = collection.config.get()
+
             if not config.vectorizer and config.vector_config:
                 named_vectors = list(config.vector_config.keys())
                 vectorizer = config.vector_config[
@@ -821,9 +823,11 @@ def create_data(
     ) -> Collection:
 
         if not self.client.collections.exists(collection):
-            raise Exception(
-                f"Class '{collection}' does not exist in Weaviate. Create first using <create class> command"
-            )
+            alias_list = self.client.alias.list_all()
+            if collection not in alias_list.keys():
+                raise Exception(
+                    f"Class '{collection}' does not exist in Weaviate. Create first using <create class> command"
+                )
 
         col: Collection = self.client.collections.get(collection)
         mt_config = col.config.get().multi_tenancy_config
@@ -1123,9 +1127,11 @@ def update_data(
     ) -> None:
 
         if not self.client.collections.exists(collection):
-            raise Exception(
-                f"Class '{collection}' does not exist in Weaviate. Create first using ./create_class.py"
-            )
+            alias_list = self.client.alias.list_all()
+            if collection not in alias_list.keys():
+                raise Exception(
+                    f"Class '{collection}' does not exist in Weaviate. Create first using ./create_class.py"
+                )
 
         col: Collection = self.client.collections.get(collection)
         try:
@@ -1277,9 +1283,11 @@ def delete_data(
     ) -> None:
 
         if not self.client.collections.exists(collection):
-            raise Exception(
-                f"Class '{collection}' does not exist in Weaviate. Create first using <create class> command."
-            )
+            alias_list = self.client.alias.list_all()
+            if collection not in alias_list.keys():
+                raise Exception(
+                    f"Class '{collection}' does not exist in Weaviate. Create first using <create class> command."
+                )
 
         col: Collection = self.client.collections.get(collection)
         mt_enabled = col.config.get().multi_tenancy_config.enabled
@@ -1297,6 +1305,7 @@ def delete_data(
         tenants = tenants_list if tenants_list is not None else existing_tenants
 
         total_deleted = 0
+
         for tenant in tenants:
             if tenant == "None":
                 ret = self.__delete_data(  # NOTE: call the correct delete impl
@@ -1408,9 +1417,11 @@ def query_data(
     ) -> None:
 
         if not self.client.collections.exists(collection):
-            raise Exception(
-                f"Class '{collection}' does not exist in Weaviate. Create first using <create class> command."
-            )
+            alias_list = self.client.alias.list_all()
+            if collection not in alias_list.keys():
+                raise Exception(
+                    f"Class '{collection}' does not exist in Weaviate. Create first using <create class> command."
+                )
 
         col: Collection = self.client.collections.get(collection)
         mt_enabled = col.config.get().multi_tenancy_config.enabled