feat: add SHOW COLLECTION command and diagnostics to documentation and implementation

Author: srimon12

README.md

@@ -84,7 +84,7 @@ Full documentation lives in the [`docs/`](docs/) folder and at **[pavanjava.gith
 | [INSERT / INSERT BULK](docs/insert.md) | Adding documents, batch inserts, payload types |
 | [SEARCH / SELECT / SCROLL / RECOMMEND / Hybrid / RERANK](docs/search.md) | Semantic search, point retrieval, pagination, hybrid, reranking, recommendations |
 | [WHERE Filters](docs/filters.md) | Full SQL-style filter operators |
-| [Collections & Quantization](docs/collections.md) | CREATE, DROP, QUANTIZE (scalar/turbo/binary/product), CREATE INDEX |
+| [Collections & Quantization](docs/collections.md) | SHOW, CREATE, DROP, QUANTIZE (scalar/turbo/binary/product), CREATE INDEX |
 | [Scripts: EXECUTE / DUMP](docs/scripts.md) | Script files, collection backup/restore |
 | [Programmatic Usage](docs/programmatic.md) | Use QQL as a Python library |
 | [Reference: Models / Config / Errors](docs/reference.md) | Embedding models, config file, error reference |
@@ -125,6 +125,7 @@ CREATE COLLECTION articles QUANTIZE TURBO BITS 2
 CREATE COLLECTION articles QUANTIZE TURBO BITS 1.5 ALWAYS RAM
 CREATE INDEX ON COLLECTION articles FOR year TYPE integer
 SHOW COLLECTIONS
+SHOW COLLECTION articles
 DROP COLLECTION articles
 
 -- Delete

docs/collections.md

@@ -24,6 +24,64 @@ SHOW COLLECTIONS
 
 ---
 
+## SHOW COLLECTION — inspect one collection
+
+Returns collection diagnostics for a single collection using Qdrant's collection info.
+
+**Syntax:**
+```sql
+SHOW COLLECTION <collection_name>
+```
+
+**What it shows:**
+
+- Point count
+- Indexed vector count
+- Segment count
+- Vector names, dimensions, and distance metrics
+- Dense vs hybrid topology
+- Sparse vector modifiers when present
+- Quantization mode
+- HNSW configuration
+- Payload indexes detected by Qdrant
+- Shard, replica, and write consistency settings
+
+**Example:**
+```sql
+SHOW COLLECTION research_papers
+```
+
+**Output:**
+```
+OK Collection 'research_papers' diagnostics
+Collection: research_papers
+  Status               : green
+  Points               : 12450
+  Indexed vectors      : 12450
+  Segments             : 3
+  Topology             : hybrid
+  Vector 'dense'       : 768 dims, Cosine distance
+  Sparse 'sparse'      : modifier=idf
+  Quantization         : scalar
+  HNSW M               : 16
+  HNSW ef_construct    : 100
+  Payload indexes:
+    category: keyword
+    year: integer
+  Shards               : 1
+  Replicas             : 1
+  Write consistency    : 1
+```
+
+**Notes:**
+
+- `Topology` is `dense` for standard collections and `hybrid` when sparse vectors are configured alongside dense vectors.
+- Dense collections with named vectors still report their vector names and dimensions.
+- If no payload indexes exist, QQL prints `Payload indexes      : none`.
+- Raises an error if the collection does not exist.
+
+---
+
 ## CREATE COLLECTION — create a collection
 
 Explicitly creates a new empty collection. Collections are also created automatically on the first INSERT, so this command is optional — use it when you want to pre-create a collection before inserting data.

docs/getting-started.md

@@ -144,6 +144,9 @@ SCROLL FROM notes LIMIT 10
 -- List all collections
 SHOW COLLECTIONS
 
+-- Inspect one collection's diagnostics
+SHOW COLLECTION notes
+
 -- Retrieve a point by ID
 SELECT * FROM notes WHERE id = 1
 ```

docs/programmatic.md

@@ -80,6 +80,15 @@ result = run_query(
     url="http://localhost:6333",
 )
 print(result.message)   # "Deleted N point(s)"
+
+# Inspect collection diagnostics
+result = run_query(
+    "SHOW COLLECTION notes",
+    url="http://localhost:6333",
+)
+print(result.data["topology"])         # "dense" or "hybrid"
+print(result.data["vectors"])          # {"": {...}} or {"dense": {...}, ...}
+print(result.data["payload_schema"])   # {"field": "keyword", ...} or None
 ```
 
 ---
@@ -132,6 +141,7 @@ class ExecutionResult:
 | SCROLL | `{"points": [{"id": str, "payload": dict}, ...], "next_offset": str \| None}` |
 | RECOMMEND | `[{"id": str, "score": float, "payload": dict}, ...]` |
 | SHOW COLLECTIONS | `["name1", "name2", ...]` |
+| SHOW COLLECTION | `{"name": str, "status": str, "points_count": int \| None, "indexed_vectors_count": int \| None, "segments_count": int, "topology": str, "vectors": dict, "sparse_vectors": dict \| None, "quantization": str \| None, "hnsw_config": dict, "payload_schema": dict \| None, "sharding": dict}` |
 | CREATE COLLECTION | `None` |
 | CREATE INDEX | `None` |
 | DROP COLLECTION | `None` |

src/qql/__init__.py

@@ -21,6 +21,7 @@
     "Executor",
     "Lexer",
     "Parser",
+    "load_config",
     "run_query",
 ]
 

src/qql/cli.py

@@ -141,7 +141,7 @@ def connect(url: str, secret: str | None) -> None:
 
     cfg = QQLConfig(url=url, secret=secret)
     save_config(cfg)
-    console.print(f"[bold green]Connected.[/bold green] Config saved to ~/.qql/config.json\n")
+    console.print("[bold green]Connected.[/bold green] Config saved to ~/.qql/config.json\n")
     _launch_repl(cfg)
 
 
@@ -262,7 +262,7 @@ def dump(collection: str, output: str, batch_size: int) -> None:
         f"\n[bold green]Done.[/bold green] "
         f"{written} point(s) written"
         + (f", [yellow]{skipped} skipped[/yellow] (no 'text' field)" if skipped else "")
-        + f"."
+        + "."
     )
 
 
@@ -416,7 +416,7 @@ def _format_collection_diagnostics(data: dict) -> str:
     # Sharding
     sh = data["sharding"]
     lines.append(f"  Shards               : {sh['shard_number']}")
-    lines.append(f"  Replicas              : {sh['replication_factor']}")
+    lines.append(f"  Replicas             : {sh['replication_factor']}")
     lines.append(f"  Write consistency    : {sh['write_consistency_factor']}")
 
     return "\n".join(lines)

src/qql/config.py

@@ -1,7 +1,6 @@
 from __future__ import annotations
 
 import json
-import os
 from dataclasses import asdict, dataclass
 from pathlib import Path
 

src/qql/executor.py

@@ -85,12 +85,12 @@
 )
 from .config import QQLConfig
 from .embedder import CrossEncoderEmbedder, Embedder, SparseEmbedder
+from .exceptions import QQLRuntimeError
 
 _RERANK_FETCH_MULTIPLIER = 4
 _HYBRID_PREFETCH_MULTIPLIER = 4
 _COLLECTION_VISIBILITY_TIMEOUT_SECONDS = 5.0
 _COLLECTION_VISIBILITY_POLL_SECONDS = 0.05
-from .exceptions import QQLRuntimeError
 
 
 @dataclass
@@ -431,27 +431,31 @@ def _execute_show_collection(self, node: ShowCollectionStmt) -> ExecutionResult:
 
         # ── Vector topology ────────────────────────────────────────────────
         vectors = params.vectors  # type: ignore[union-attr]
+        sparse_vector_params = params.sparse_vectors or {}
         if isinstance(vectors, dict):
-            topology = "hybrid"
             vector_details = {}
             for vname, vconfig in vectors.items():
                 vector_details[vname] = {
                     "size": vconfig.size,
                     "distance": str(vconfig.distance) if vconfig.distance else None,
                 }
+        elif vectors is None:
+            raise QQLRuntimeError(
+                f"Collection '{node.collection}' has no vector configuration"
+            )
         else:
-            topology = "dense"
             vector_details = {
                 "": {
                     "size": vectors.size,
                     "distance": str(vectors.distance) if vectors.distance else None,
                 }
             }
+        topology = "hybrid" if sparse_vector_params else "dense"
 
         # ── Sparse vector config ───────────────────────────────────────────
         sparse_vectors = {}
-        if params.sparse_vectors:
-            for sname, sconfig in params.sparse_vectors.items():
+        if sparse_vector_params:
+            for sname, sconfig in sparse_vector_params.items():
                 sparse_vectors[sname] = {
                     "modifier": str(sconfig.modifier) if sconfig.modifier else None,
                 }
@@ -488,7 +492,7 @@ def _execute_show_collection(self, node: ShowCollectionStmt) -> ExecutionResult:
 
         # ── Payload schema / indexes ───────────────────────────────────────
         payload_indexes = {}
-        for field_name, idx_info in info.payload_schema.items():
+        for field_name, idx_info in (info.payload_schema or {}).items():
             payload_indexes[field_name] = str(idx_info.data_type)
 
         # ── Sharding / replication ─────────────────────────────────────────

tests/test_dumper.py

@@ -7,7 +7,6 @@
 from qql.dumper import (
     _DEFAULT_DUMP_BATCH_SIZE,
     _is_hybrid,
-    _serialize_dict,
     _serialize_value,
     dump_collection,
 )

tests/test_executor.py

@@ -454,6 +454,45 @@ def test_show_collection_hybrid(self, executor, mock_client, mocker):
         assert data["vectors"]["dense"]["size"] == 768
         assert data["sparse_vectors"]["sparse"]["modifier"] == "idf"
 
+    def test_show_collection_named_dense_is_not_reported_as_hybrid(self, executor, mock_client, mocker):
+        from qdrant_client.models import (
+            CollectionStatus,
+            Distance,
+            VectorParams,
+        )
+
+        mock_client.collection_exists.return_value = True
+
+        mock_info = mocker.MagicMock()
+        mock_info.status = CollectionStatus.GREEN
+        mock_info.points_count = 3
+        mock_info.indexed_vectors_count = 3
+        mock_info.segments_count = 1
+        mock_info.config.params.vectors = {
+            "body": VectorParams(size=384, distance=Distance.COSINE),
+            "title": VectorParams(size=128, distance=Distance.DOT),
+        }
+        mock_info.config.params.sparse_vectors = None
+        mock_info.config.params.shard_number = 1
+        mock_info.config.params.replication_factor = 1
+        mock_info.config.params.write_consistency_factor = 1
+        mock_info.config.hnsw_config.m = 16
+        mock_info.config.hnsw_config.ef_construct = 100
+        mock_info.config.hnsw_config.full_scan_threshold = None
+        mock_info.config.hnsw_config.max_indexing_threads = None
+        mock_info.config.hnsw_config.on_disk = None
+        mock_info.config.hnsw_config.payload_m = None
+        mock_info.config.quantization_config = None
+        mock_info.payload_schema = {}
+
+        mock_client.get_collection.return_value = mock_info
+
+        result = executor.execute(ShowCollectionStmt(collection="named_dense"))
+
+        assert result.success is True
+        assert result.data["topology"] == "dense"
+        assert result.data["sparse_vectors"] is None
+
     def test_show_collection_with_payload_schema(self, executor, mock_client, mocker):
         from qdrant_client.models import (
             CollectionStatus,
@@ -494,6 +533,41 @@ def test_show_collection_with_payload_schema(self, executor, mock_client, mocker
         assert result.success is True
         assert result.data["payload_schema"] == {"category": "keyword"}
 
+    def test_show_collection_handles_missing_payload_schema(self, executor, mock_client, mocker):
+        from qdrant_client.models import (
+            CollectionStatus,
+            Distance,
+            VectorParams,
+        )
+
+        mock_client.collection_exists.return_value = True
+
+        mock_info = mocker.MagicMock()
+        mock_info.status = CollectionStatus.GREEN
+        mock_info.points_count = 0
+        mock_info.indexed_vectors_count = 0
+        mock_info.segments_count = 0
+        mock_info.config.params.vectors = VectorParams(size=384, distance=Distance.COSINE)
+        mock_info.config.params.shard_number = 1
+        mock_info.config.params.replication_factor = 1
+        mock_info.config.params.write_consistency_factor = 1
+        mock_info.config.params.sparse_vectors = None
+        mock_info.config.hnsw_config.m = 16
+        mock_info.config.hnsw_config.ef_construct = 100
+        mock_info.config.hnsw_config.full_scan_threshold = None
+        mock_info.config.hnsw_config.max_indexing_threads = None
+        mock_info.config.hnsw_config.on_disk = None
+        mock_info.config.hnsw_config.payload_m = None
+        mock_info.config.quantization_config = None
+        mock_info.payload_schema = None
+
+        mock_client.get_collection.return_value = mock_info
+
+        result = executor.execute(ShowCollectionStmt(collection="docs"))
+
+        assert result.success is True
+        assert result.data["payload_schema"] is None
+
     def test_show_collection_nonexistent_raises(self, executor, mock_client):
         mock_client.collection_exists.return_value = False
         node = ShowCollectionStmt(collection="ghost")
@@ -1227,7 +1301,6 @@ def test_hybrid_insert_uses_custom_dense_model(
         )
         executor.execute(node)
         # Embedder should have been called with the custom dense model name
-        call_args = mocker.patch.object  # already patched by mock_embedder fixture
         # Verify through the dense vector in the upsert call
         point = mock_client.upsert.call_args.kwargs["points"][0]
         assert "dense" in point.vector