qql-cli 1.4.0__tar.gz → 2.0.0__tar.gz

qql_cli-2.0.0/PKG-INFO

@@ -0,0 +1,194 @@
+Metadata-Version: 2.4
+Name: qql-cli
+Version: 2.0.0
+Summary: QQL is a SQL-like query language and CLI for Qdrant vector database. Write INSERT, SEARCH, RECOMMEND, DELETE, and CREATE COLLECTION statements instead of Python SDK calls. Supports hybrid dense+sparse vector search, cross-encoder reranking, quantization (scalar, binary, product), WHERE clause filters, script execution, and collection dump/restore.
+Project-URL: Homepage, https://github.com/pavanjava/qql
+Project-URL: Repository, https://github.com/pavanjava/qql
+Project-URL: Documentation, https://pavanjava.github.io/qql
+Project-URL: Bug Tracker, https://github.com/pavanjava/qql/issues
+Author-email: Kameshwara Pavan Kumar Mantha <pavankumarmantha@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2026 Kameshwara Pavan Kumar Mantha
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: cli,embeddings,fastembed,hybrid-search,nlp,qdrant,query-language,rag,semantic-search,sql,vector-database,vector-search
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Database :: Front-Ends
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Text Processing :: Indexing
+Classifier: Topic :: Utilities
+Requires-Python: >=3.12
+Requires-Dist: click>=8.1.0
+Requires-Dist: prompt-toolkit>=3.0.0
+Requires-Dist: qdrant-client[fastembed]>=1.13.0
+Requires-Dist: rich>=13.0.0
+Description-Content-Type: text/markdown
+
+# QQL — Qdrant Query Language
+
+> SQL-like query language and CLI for [Qdrant](https://qdrant.tech) vector database.
+
+[![PyPI version](https://img.shields.io/pypi/v/qql-cli?color=blue&label=PyPI)](https://pypi.org/project/qql-cli/)
+[![Python 3.12+](https://img.shields.io/pypi/pyversions/qql-cli)](https://pypi.org/project/qql-cli/)
+[![MIT License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+[![Tests](https://img.shields.io/badge/tests-375%20passing-brightgreen)](tests/)
+
+Write `INSERT`, `SEARCH`, `RECOMMEND`, `DELETE`, and `CREATE COLLECTION` statements instead of Python SDK calls. Supports hybrid dense+sparse vector search, cross-encoder reranking, quantization (scalar, binary, product), SQL-style `WHERE` filters, script execution, and collection dump/restore.
+
+```
+qql> INSERT INTO COLLECTION notes VALUES {'text': 'Qdrant is a vector database', 'author': 'alice', 'year': 2024}
+✓ Inserted 1 point [3f2e1a4b-8c91-4d0e-b123-abc123def456]
+
+qql> SEARCH notes SIMILAR TO 'vector storage engines' LIMIT 3 WHERE year >= 2023
+✓ Found 1 result(s)
+ Score  │ ID                                   │ Payload
+────────┼──────────────────────────────────────┼──────────────────────────────────────
+ 0.8931 │ 3f2e1a4b-8c91-4d0e-b123-abc123def456 │ {'text': 'Qdrant is a ...', 'author': 'alice', 'year': 2024}
+
+qql> SEARCH notes SIMILAR TO 'vector databases' LIMIT 5 USING HYBRID RERANK
+✓ Found 1 result(s) (hybrid, reranked)
+ Score  │ ID                                   │ Payload
+────────┼──────────────────────────────────────┼──────────────────────────────────────
+ 5.3754 │ 3f2e1a4b-8c91-4d0e-b123-abc123def456 │ {'text': 'Qdrant is a ...', 'author': 'alice', 'year': 2024}
+```
+
+---
+
+## How It Works
+
+QQL is a thin translation layer between a SQL-like query language and the Qdrant Python client. Every statement you type goes through three stages:
+
+```
+Your query string
+      │
+      ▼
+  [ Lexer ]      — tokenizes the input into keywords, identifiers, literals
+      │
+      ▼
+  [ Parser ]     — builds a typed AST node (e.g. InsertStmt, SearchStmt)
+      │
+      ▼
+  [ Executor ]   — maps the AST node to a Qdrant client call
+      │
+      ▼
+  Qdrant instance
+```
+
+When you run `INSERT`, the `text` field is automatically converted into a dense vector using [Fastembed](https://github.com/qdrant/fastembed). In **hybrid mode** (`USING HYBRID`), a sparse BM25 vector is also generated alongside the dense vector, and searches use Qdrant's Reciprocal Rank Fusion (RRF) to merge the results of both retrieval methods.
+
+---
+
+## Installation
+
+**Requirements:** Python 3.12+, a running Qdrant instance.
+
+```bash
+pip install qql-cli
+```
+
+Connect to a Qdrant instance:
+
+```bash
+# Local
+qql connect --url http://localhost:6333
+
+# Qdrant Cloud
+qql connect --url https://<your-cluster>.qdrant.io --secret <your-api-key>
+```
+
+Then type `qql` to open the interactive shell.
+
+---
+
+## Documentation
+
+Full documentation lives in the [`docs/`](docs/) folder and at **[pavanjava.github.io/qql](https://pavanjava.github.io/qql)**:
+
+| Topic | Description |
+|---|---|
+| [Getting Started](docs/getting-started.md) | Installation, connecting, first queries |
+| [INSERT / INSERT BULK](docs/insert.md) | Adding documents, batch inserts, payload types |
+| [SEARCH / RECOMMEND / Hybrid / RERANK](docs/search.md) | Semantic search, hybrid, reranking, recommendations |
+| [WHERE Filters](docs/filters.md) | Full SQL-style filter operators |
+| [Collections & Quantization](docs/collections.md) | CREATE, DROP, QUANTIZE (scalar/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 |
+
+---
+
+## Quick Syntax Reference
+
+```sql
+-- Insert
+INSERT INTO COLLECTION articles VALUES {'text': '...', 'year': 2024}
+INSERT BULK INTO COLLECTION articles VALUES [{'text': '...'}, {'text': '...'}]
+
+-- Search
+SEARCH articles SIMILAR TO 'query' LIMIT 10
+SEARCH articles SIMILAR TO 'query' LIMIT 10 WHERE year >= 2020
+SEARCH articles SIMILAR TO 'query' LIMIT 10 USING HYBRID
+SEARCH articles SIMILAR TO 'query' LIMIT 10 USING HYBRID RERANK
+
+-- Recommend
+RECOMMEND FROM articles POSITIVE IDS (1001, 1002) LIMIT 5
+
+-- Collections
+CREATE COLLECTION articles
+CREATE COLLECTION articles HYBRID
+CREATE COLLECTION articles QUANTIZE SCALAR
+CREATE INDEX ON COLLECTION articles FOR year TYPE integer
+SHOW COLLECTIONS
+DROP COLLECTION articles
+
+-- Delete
+DELETE FROM articles WHERE id = '3f2e1a4b-...'
+DELETE FROM articles WHERE year < 2020
+
+-- Scripts
+EXECUTE /path/to/script.qql
+DUMP articles /path/to/backup.qql
+```
+
+---
+
+## Running Tests
+
+Tests do not require a running Qdrant instance — the Qdrant client is mocked.
+
+```bash
+pytest tests/ -v
+```
+
+Expected: **375 tests passing**.
+
+---
+
+## License
+
+MIT © [Kameshwara Pavan Kumar Mantha](https://github.com/pavanjava)

qql_cli-2.0.0/README.md

@@ -0,0 +1,143 @@
+# QQL — Qdrant Query Language
+
+> SQL-like query language and CLI for [Qdrant](https://qdrant.tech) vector database.
+
+[![PyPI version](https://img.shields.io/pypi/v/qql-cli?color=blue&label=PyPI)](https://pypi.org/project/qql-cli/)
+[![Python 3.12+](https://img.shields.io/pypi/pyversions/qql-cli)](https://pypi.org/project/qql-cli/)
+[![MIT License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+[![Tests](https://img.shields.io/badge/tests-375%20passing-brightgreen)](tests/)
+
+Write `INSERT`, `SEARCH`, `RECOMMEND`, `DELETE`, and `CREATE COLLECTION` statements instead of Python SDK calls. Supports hybrid dense+sparse vector search, cross-encoder reranking, quantization (scalar, binary, product), SQL-style `WHERE` filters, script execution, and collection dump/restore.
+
+```
+qql> INSERT INTO COLLECTION notes VALUES {'text': 'Qdrant is a vector database', 'author': 'alice', 'year': 2024}
+✓ Inserted 1 point [3f2e1a4b-8c91-4d0e-b123-abc123def456]
+
+qql> SEARCH notes SIMILAR TO 'vector storage engines' LIMIT 3 WHERE year >= 2023
+✓ Found 1 result(s)
+ Score  │ ID                                   │ Payload
+────────┼──────────────────────────────────────┼──────────────────────────────────────
+ 0.8931 │ 3f2e1a4b-8c91-4d0e-b123-abc123def456 │ {'text': 'Qdrant is a ...', 'author': 'alice', 'year': 2024}
+
+qql> SEARCH notes SIMILAR TO 'vector databases' LIMIT 5 USING HYBRID RERANK
+✓ Found 1 result(s) (hybrid, reranked)
+ Score  │ ID                                   │ Payload
+────────┼──────────────────────────────────────┼──────────────────────────────────────
+ 5.3754 │ 3f2e1a4b-8c91-4d0e-b123-abc123def456 │ {'text': 'Qdrant is a ...', 'author': 'alice', 'year': 2024}
+```
+
+---
+
+## How It Works
+
+QQL is a thin translation layer between a SQL-like query language and the Qdrant Python client. Every statement you type goes through three stages:
+
+```
+Your query string
+      │
+      ▼
+  [ Lexer ]      — tokenizes the input into keywords, identifiers, literals
+      │
+      ▼
+  [ Parser ]     — builds a typed AST node (e.g. InsertStmt, SearchStmt)
+      │
+      ▼
+  [ Executor ]   — maps the AST node to a Qdrant client call
+      │
+      ▼
+  Qdrant instance
+```
+
+When you run `INSERT`, the `text` field is automatically converted into a dense vector using [Fastembed](https://github.com/qdrant/fastembed). In **hybrid mode** (`USING HYBRID`), a sparse BM25 vector is also generated alongside the dense vector, and searches use Qdrant's Reciprocal Rank Fusion (RRF) to merge the results of both retrieval methods.
+
+---
+
+## Installation
+
+**Requirements:** Python 3.12+, a running Qdrant instance.
+
+```bash
+pip install qql-cli
+```
+
+Connect to a Qdrant instance:
+
+```bash
+# Local
+qql connect --url http://localhost:6333
+
+# Qdrant Cloud
+qql connect --url https://<your-cluster>.qdrant.io --secret <your-api-key>
+```
+
+Then type `qql` to open the interactive shell.
+
+---
+
+## Documentation
+
+Full documentation lives in the [`docs/`](docs/) folder and at **[pavanjava.github.io/qql](https://pavanjava.github.io/qql)**:
+
+| Topic | Description |
+|---|---|
+| [Getting Started](docs/getting-started.md) | Installation, connecting, first queries |
+| [INSERT / INSERT BULK](docs/insert.md) | Adding documents, batch inserts, payload types |
+| [SEARCH / RECOMMEND / Hybrid / RERANK](docs/search.md) | Semantic search, hybrid, reranking, recommendations |
+| [WHERE Filters](docs/filters.md) | Full SQL-style filter operators |
+| [Collections & Quantization](docs/collections.md) | CREATE, DROP, QUANTIZE (scalar/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 |
+
+---
+
+## Quick Syntax Reference
+
+```sql
+-- Insert
+INSERT INTO COLLECTION articles VALUES {'text': '...', 'year': 2024}
+INSERT BULK INTO COLLECTION articles VALUES [{'text': '...'}, {'text': '...'}]
+
+-- Search
+SEARCH articles SIMILAR TO 'query' LIMIT 10
+SEARCH articles SIMILAR TO 'query' LIMIT 10 WHERE year >= 2020
+SEARCH articles SIMILAR TO 'query' LIMIT 10 USING HYBRID
+SEARCH articles SIMILAR TO 'query' LIMIT 10 USING HYBRID RERANK
+
+-- Recommend
+RECOMMEND FROM articles POSITIVE IDS (1001, 1002) LIMIT 5
+
+-- Collections
+CREATE COLLECTION articles
+CREATE COLLECTION articles HYBRID
+CREATE COLLECTION articles QUANTIZE SCALAR
+CREATE INDEX ON COLLECTION articles FOR year TYPE integer
+SHOW COLLECTIONS
+DROP COLLECTION articles
+
+-- Delete
+DELETE FROM articles WHERE id = '3f2e1a4b-...'
+DELETE FROM articles WHERE year < 2020
+
+-- Scripts
+EXECUTE /path/to/script.qql
+DUMP articles /path/to/backup.qql
+```
+
+---
+
+## Running Tests
+
+Tests do not require a running Qdrant instance — the Qdrant client is mocked.
+
+```bash
+pytest tests/ -v
+```
+
+Expected: **375 tests passing**.
+
+---
+
+## License
+
+MIT © [Kameshwara Pavan Kumar Mantha](https://github.com/pavanjava)

qql_cli-2.0.0/docs/_config.yml

@@ -0,0 +1,10 @@
+theme: minima
+title: "QQL — Qdrant Query Language"
+description: "SQL-like query language and CLI for Qdrant vector database — INSERT, SEARCH, hybrid search, reranking, quantization, and more."
+url: "https://pavanjava.github.io/qql"
+baseurl: "/qql"
+repository: "pavanjava/qql"
+
+# Disable Jekyll processing of the HTML file (it has its own styling)
+include:
+  - index.html

qql_cli-2.0.0/docs/collections.md

@@ -0,0 +1,216 @@
+# Managing Collections
+
+---
+
+## SHOW COLLECTIONS — list collections
+
+Lists all collections in the connected Qdrant instance.
+
+```sql
+SHOW COLLECTIONS
+```
+
+**Output:**
+```
+✓ 3 collection(s) found
+┌──────────────────┐
+│ Collection       │
+├──────────────────┤
+│ articles         │
+│ notes            │
+│ products         │
+└──────────────────┘
+```
+
+---
+
+## 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.
+
+**Syntax:**
+```
+CREATE COLLECTION <collection_name>
+CREATE COLLECTION <collection_name> HYBRID
+CREATE COLLECTION <collection_name> USING MODEL '<model_name>'
+CREATE COLLECTION <collection_name> USING HYBRID
+CREATE COLLECTION <collection_name> USING HYBRID DENSE MODEL '<model>'
+```
+
+Any of the above forms can be followed by an optional `QUANTIZE` clause — see [Quantization](#quantization--quantize-clause) below.
+
+**Examples:**
+
+Dense-only collection (standard, uses default model dimensions):
+```sql
+CREATE COLLECTION research_papers
+```
+
+Dense-only collection pinned to a specific model (768-dimensional):
+```sql
+CREATE COLLECTION research_papers USING MODEL 'BAAI/bge-base-en-v1.5'
+```
+
+Hybrid collection (dense + sparse BM25, default models):
+```sql
+CREATE COLLECTION research_papers HYBRID
+```
+
+Hybrid collection with a custom dense model:
+```sql
+CREATE COLLECTION research_papers USING HYBRID DENSE MODEL 'BAAI/bge-base-en-v1.5'
+```
+
+When `USING MODEL` is omitted, the collection uses the **default embedding model's dimensions** (384 for `all-MiniLM-L6-v2`). If the collection already exists, the command succeeds with a message and does nothing.
+
+---
+
+## Quantization — QUANTIZE clause
+
+Quantization reduces the memory footprint of vector collections and speeds up search at the cost of a small, controllable accuracy loss. QQL supports all three Qdrant quantization strategies via an optional `QUANTIZE` clause appended to `CREATE COLLECTION`.
+
+**Three strategies:**
+
+| Type | Compression | Accuracy Loss | Best For |
+|---|---|---|---|
+| `SCALAR` | 4× (float32 → int8) | < 1% | Most collections — best balance |
+| `BINARY` | 32× (float32 → 1-bit) | Higher | High-dimensional vectors (768+), speed priority |
+| `PRODUCT` | 4× (configurable) | Variable | Memory-constrained deployments |
+
+**Full syntax:**
+```
+CREATE COLLECTION <name> ... QUANTIZE SCALAR [QUANTILE <0.0–1.0>] [ALWAYS RAM]
+CREATE COLLECTION <name> ... QUANTIZE BINARY  [ALWAYS RAM]
+CREATE COLLECTION <name> ... QUANTIZE PRODUCT [ALWAYS RAM]
+```
+
+- **`QUANTILE <float>`** — (scalar only) calibration quantile for the INT8 conversion; defaults to Qdrant's built-in default (0.99) when omitted.
+- **`ALWAYS RAM`** — keep the **quantized** vectors in RAM at all times, regardless of the collection's `on_disk` setting. Improves search throughput at the cost of higher RAM usage for the compressed index. The original full-precision vectors are stored and managed independently of this flag. Supported by all three quantization types.
+- **`QUANTIZE`** always appears **after** all other clauses (`HYBRID`, `USING MODEL`, etc.).
+- For `PRODUCT`, the compression ratio is fixed at **4×** in this version.
+- When used with `HYBRID` collections, quantization applies only to the **dense** vector.
+
+**Examples:**
+
+Scalar quantization (recommended default):
+```sql
+CREATE COLLECTION research_papers QUANTIZE SCALAR
+```
+
+Scalar with explicit calibration and quantized vectors pinned to RAM:
+```sql
+CREATE COLLECTION research_papers QUANTIZE SCALAR QUANTILE 0.95 ALWAYS RAM
+```
+
+Binary quantization for large high-dimensional embeddings:
+```sql
+CREATE COLLECTION research_papers QUANTIZE BINARY
+```
+
+Product quantization for maximum memory savings:
+```sql
+CREATE COLLECTION research_papers QUANTIZE PRODUCT ALWAYS RAM
+```
+
+Combined with hybrid collection:
+```sql
+CREATE COLLECTION research_papers HYBRID QUANTIZE SCALAR
+```
+
+Combined with a pinned model:
+```sql
+CREATE COLLECTION research_papers USING MODEL 'BAAI/bge-base-en-v1.5' QUANTIZE SCALAR QUANTILE 0.99
+```
+
+**Valid combinations:**
+
+| Base form | + QUANTIZE SCALAR | + QUANTIZE BINARY | + QUANTIZE PRODUCT |
+|---|---|---|---|
+| `CREATE COLLECTION name` | ✓ | ✓ | ✓ |
+| `... HYBRID` | ✓ | ✓ | ✓ |
+| `... USING MODEL 'x'` | ✓ | ✓ | ✓ |
+| `... USING HYBRID` | ✓ | ✓ | ✓ |
+| `... USING HYBRID DENSE MODEL 'x'` | ✓ | ✓ | ✓ |
+
+> INSERT and SEARCH on quantized collections work exactly the same as on non-quantized ones — no changes to INSERT or SEARCH syntax are needed.
+
+---
+
+## CREATE INDEX — create a payload index
+
+Creates a payload index on a collection field. Payload indexes speed up `WHERE` clause filtering by allowing Qdrant to efficiently match on indexed fields.
+
+**Syntax:**
+```
+CREATE INDEX ON COLLECTION <collection_name> FOR <field_name> TYPE <schema_type>
+```
+
+**Supported schema types:**
+
+| Type | Description |
+|---|---|
+| `keyword` | Exact string match (e.g. status, category) |
+| `integer` | Whole numbers |
+| `float` | Decimal numbers |
+| `bool` | Boolean values |
+| `text` | Full-text search (enables `MATCH` operators) |
+| `geo` | Geospatial coordinates |
+| `datetime` | Date/time values |
+
+**Examples:**
+
+```sql
+CREATE INDEX ON COLLECTION articles FOR category TYPE keyword
+CREATE INDEX ON COLLECTION articles FOR year TYPE integer
+CREATE INDEX ON COLLECTION articles FOR title TYPE text
+CREATE INDEX ON COLLECTION articles FOR meta.author TYPE keyword
+```
+
+**Rules:**
+- The collection must already exist. Raises an error otherwise.
+- Indexes are idempotent — creating the same index twice succeeds silently.
+
+---
+
+## DROP COLLECTION — delete a collection
+
+Permanently deletes a collection and **all points inside it**. This operation is irreversible.
+
+```sql
+DROP COLLECTION old_experiments
+```
+
+Raises an error if the collection does not exist.
+
+---
+
+## DELETE — remove points
+
+Deletes one or more points from a collection by specific ID or by a `WHERE` filter.
+
+**Syntax:**
+```
+DELETE FROM <collection_name> WHERE id = '<point_id>'
+DELETE FROM <collection_name> WHERE id = <integer_id>
+DELETE FROM <collection_name> WHERE <filter>
+```
+
+**Examples:**
+
+```sql
+-- Delete by UUID
+DELETE FROM articles WHERE id = '3f2e1a4b-8c91-4d0e-b123-abc123def456'
+
+-- Delete by integer ID
+DELETE FROM articles WHERE id = 42
+
+-- Delete all points matching a filter
+DELETE FROM articles WHERE category = 'archived'
+
+-- Delete with a compound filter
+DELETE FROM articles WHERE year < 2020 AND status = 'draft'
+```
+
+**Notes:**
+- If no points match the filter or ID, the operation succeeds silently with a count of 0.
+- The collection itself must exist; deleting from a non-existent collection raises an error.