QQL 0.1.5: One Query Language Across All Five Runtimes

Introduction

QQL 0.1.5 is a declarative query language release for Qdrant that unifies query execution across Rust crates, pyqql / pyqql-edge, @veristamp/nqql / @veristamp/nqql-edge, qql-wasm, and qql-cli.¹ A common source of confusion in client integrations is version mapping across artifacts. Package version 0.1.5 represents the distribution artifact published via package managers, whereas language version 1.2 defines the formal grammar specification parsed across target platforms.

When building microservices across Rust backends, Python data pipelines, and Node.js APIs, query logic frequently becomes fragmented. Python workers construct manual JSON payloads, Node services invoke client SDK chains, and Rust services call gRPC stubs directly. QQL 0.1.5 solves this fragmentation by compiling a single SQL-like query language into identical AST structures across all five runtime targets.

---

Key Definitions & Architecture Terms

• A Grammar Specification (1.2) is the formal QQL language contract accepted by the underlying qql-core compiler.
• A Distribution Package (0.1.5) is the versioned artifact published across crates.io, PyPI, and npm registries.
• Structural Multi-Vector Ingestion means defining explicit field-to-vector target mappings via ON FIELD and INTO clauses rather than relying on un-validated client conventions.
• AST Filter Injection refers to host-level query transformation (inject_filter) that merges mandatory tenant predicates into the root AND node of a parsed query tree.

---

1. How does QQL 0.1.5 unify query execution across five runtimes?

Building vector search applications across heterogeneous technology stacks often leads to fragmented query abstractions. Python data pipelines might construct raw JSON payloads, Node.js services rely on SDK method chains, and Rust microservices invoke gRPC stubs directly. QQL 0.1.5 eliminates this fragmentation by providing one unified parser, planner, and query intermediate representation across five distinct runtime surfaces:

1.1 The Cross-Platform Package Matrix

Target Surface	Package Artifact	Runtime Capability
Parser / Plan / Network	qql-core, qql-plan, qql, pyqql, @veristamp/nqql	Full REST and gRPC compilation targeting Qdrant clusters
Local In-Process Shard	qql-edge, pyqql-edge, @veristamp/nqql-edge	Embedded fastembed-rs vector search without server infrastructure
Browser Sandbox	qql-wasm	Offline query analysis, AST inspection, and optional client REST execution
Command Line Interface	qql-cli	Terminal-based query execution, explain output, and schema validation
Embeddings Engine	qql-embed	Local fastembed-rs model loading (via ort & tokenizers) and remote HTTP resolution

Installing the required package for your target runtime requires pinning version 0.1.5 across all service manifests:

# Python service workers and edge scripts
pip install pyqql==0.1.5 pyqql-edge==0.1.5

# Node.js backends and browser tooling
npm install @veristamp/[email protected] @veristamp/[email protected] [email protected]

# Rust microservices
cargo add [email protected] [email protected]

1.2 Architectural Decoupling in qql-core

Architecturally, qql-core remains isolated from network I/O. Statement planning lives in qql-plan, while vector embedding resolution is isolated within qql-embed. Downstream execution backends (RestQdrant, GrpcQdrant, and EdgeQdrant) lower the identical PlannedOperation intermediate representation into wire-level requests.¹

Having a single parser implementation across all language bindings ensures that query validation occurs before network packets hit database ports. Frontend browser sandboxes using qql-wasm evaluate identical syntax constraints as backend Rust microservices, preventing invalid syntax from traversing API gateways.

---

2. Why is multi-target UPSERT structural rather than convention?

Early vector databases assumed single-vector records or relied on implicit client naming conventions to route vectors to specific index fields. QQL 1.1 introduced explicit ON FIELD and INTO clause specifications for multi-vector UPSERT statements. QQL 0.1.5 preserves these structures while adding strict validation against empty targets and duplicate field assignments.

2.1 Multi-Vector Ingestion via Python Bindings

Consider a multi-vector ingestion payload parsed via Python bindings:

import pyqql
import json

query_source = """
UPSERT INTO documents VALUES {
  id: 42,
  title: 'System Architecture Notes',
  body: '''line1

line2'''
}
USING DENSE MODEL 'BAAI/bge-small-en-v1.5' ON FIELD body INTO dense_body,
      DENSE MODEL 'BAAI/bge-small-en-v1.5' ON FIELD title INTO dense_title
"""

statement = pyqql.parse(query_source)[0]
embedding_ast = statement.to_dict()["Upsert"]["embedding"]
print(json.dumps(embedding_ast, indent=2))

2.2 AST Structural Representation

The resulting Abstract Syntax Tree (AST) reflects explicit structural target mapping:

{
  "Multi": [
    {
      "Dense": {
        "model": "BAAI/bge-small-en-v1.5",
        "vector": "dense_body",
        "field": "body"
      }
    },
    {
      "Dense": {
        "model": "BAAI/bge-small-en-v1.5",
        "vector": "dense_title",
        "field": "title"
      }
    }
  ]
}

Notice that multiline triple-quoted string values preserve exact whitespace and newline characters ("line1\n\nline2"). This string handling model guarantees that raw payload formatting remains untruncated during ingestion.

When statement intent centers specifically on vector generation rather than point insertion, the explicit EMBED syntax provides direct target mapping:

EMBED body INTO dense_body MODEL 'BAAI/bge-small-en-v1.5' FOR POINT 42 IN documents;

Retrieval operations remain decoupled from ingestion semantics, referencing named vector targets during search:

QUERY TEXT 'how do named vectors work?' FROM documents
USING dense_body
LIMIT 5;

Structural target mapping prevents subtle data contamination bugs in production multi-vector systems. When title vectors and body vectors occupy different vector spaces, implicit routing can inadvertently push title embeddings into body indices. Enforcing explicit field bindings at the AST parser level prevents misrouted vectors before storage ingestion takes place.

---

3. How do string delimiters round-trip without escape theatre?

Handling raw paths, multiline prompts, and JSON payloads inside SQL-like syntax frequently leads to complex backslash escaping. QQL 0.1.5 supports four distinct string delimiter formats that all parse to identical internal string representations:

3.1 Supported String Delimiter Formats

String Form	Syntax Example	Primary Engineering Use Case
Single Quoted	'refund policy'	Standard literal strings and field values
Raw String	r'C:\Users\operator\docs'	File paths and regex patterns where backslashes stay literal
Triple Quoted	'''line1\n\nline2'''	Multiline context blocks, system prompts, and raw payloads
Backtick Quoted	`He said "keep quotes".`	String values containing inline double or single quote marks

3.2 Verification via Lexer Evaluation

The raw string parser evaluation can be verified programmatically:

import pyqql

raw_query = r"QUERY TEXT r'C:\Users\operator\docs' FROM d USING dense LIMIT 1"
statement = pyqql.parse(raw_query)[0]
extracted_text = statement.to_dict()["Query"]["expression"]["Nearest"]["input"]["Text"]["text"]

assert extracted_text == r"C:\Users\operator\docs"

A raw string delimiter is a lexer convenience, not a security boundary. It prevents the lexer from consuming backslash characters during parsing, but host applications must still parse, authorize, and validate user input prior to execution.

Supporting multiline triple-quoted strings simplifies the ingestion of raw LLM generation outputs, system prompts, and structured JSON documents. Developers can embed raw text directly into QQL statements without building custom string sanitization libraries or complex escape routines.

---

4. How are security isolation and physical routing separated?

An architectural refactoring in QQL 0.1.5 is the removal of inject_shard_key. Previous revisions mixed tenant security isolation with physical cluster routing. In 0.1.5, security isolation and cluster routing are decoupled into independent subsystems:

4.1 Security Isolation vs Physical Routing Matrix

Engineering Concern	Operational Mechanism	Qdrant Wire Representation
Security Isolation	WHERE clause or inject_filter()	Qdrant Filter payload comparison
Physical Routing	SHARD 'key' clause or stmt.shard_key	REST shard_key query param / gRPC ShardKeySelector
Index Configuration	CREATE INDEX … is_tenant = true	Tenant payload index optimization
Partition DDL	CREATE SHARD KEY 'key'	Cluster administration API

4.2 Production Shard Execution Pattern

This separation is reflected in production query execution:

-- Step 1: Provision physical partition (Admin operation)
CREATE SHARD KEY 'acme' ON COLLECTION tenants WITH (shards_number = 2);

-- Step 2: Route request to physical shard while enforcing mandatory tenant filter
QUERY TEXT 'security risk assessment' FROM tenants
USING dense
WHERE tenant_id = 'acme'
SHARD 'acme'
LIMIT 10;

Clause evaluation order is strictly enforced: USING → WHERE → SHARD → LIMIT. Placing a WHERE filter before a USING specification triggers a parse error with QQL-PARSE-CLAUSE-ORDER.²

import pyqql

statement = pyqql.parse("QUERY TEXT 'audit' FROM docs USING dense SHARD 'acme' LIMIT 5")[0]
assert statement.to_dict()["Query"]["shard_key"] == "acme"

# Programmatic host-level routing (decoupled from isolation filters):
statement.shard_key = "acme"

Local edge executors reject custom SHARD clauses at execution time, as physical sharding applies only to distributed Qdrant clusters. Further details on local execution and security filtering are available in our local edge search post and AST filter injection post.

Decoupling security isolation from node routing reinforces zero-trust principles. Routing directs network packets to specific cluster nodes for performance, while inject_filter guarantees that tenant boundaries remain enforced even if node routing configurations change. For gateway integration patterns, review our QQL Gateway guide and QQL Go Retrieval operations.

---

5. How do you implement a cross-runtime conformance test?

Relying solely on package release notes is insufficient for production deployments. Pinning package dependencies should be accompanied by an automated conformance fixture in your test suite:

5.1 Python Conformance Fixture

import pyqql

CONFORMANCE_TEST_CASES = [
    "QUERY TEXT r'C:\\tmp\\data' FROM docs USING dense LIMIT 1",
    "QUERY TEXT `quoted \"value\"` FROM docs USING dense LIMIT 1",
    """UPSERT INTO docs VALUES {id: 101, body: '''multiline
content'''} USING DENSE ON FIELD body INTO dense_body""",
    "QUERY TEXT 'audit' FROM docs USING dense WHERE tenant_id = 'acme' SHARD 'acme' LIMIT 5",
    "DELETE PAYLOAD legacy_tag FROM docs WHERE status = 'deprecated'",
]

def test_qql_grammar_conformance():
    for query in CONFORMANCE_TEST_CASES:
        parsed_statements = pyqql.parse(query)
        assert len(parsed_statements) == 1, f"Failed to parse: {query}"
        
        explanation = pyqql.explain(parsed_statements[0])
        assert explanation["ok"], f"Planning failed for {query}: {explanation}"

if __name__ == "__main__":
    test_qql_grammar_conformance()
    print("All QQL 0.1.5 conformance tests passed successfully.")

5.2 Multi-Language Test Execution

Running these fixtures across Python, Node.js (@veristamp/nqql), and browser environments (qql-wasm) ensures query compilation remains identical throughout your architecture. For browser testing details, refer to our WASM playground guide.

Automated conformance testing provides continuous verification during dependency updates. When upgrading QQL packages, running conformance suites validates that syntax parsing, plan generation, and error reporting maintain complete backwards compatibility across all deployment environments. Similar governance principles apply to schema-driven extraction pipelines as described in our Schema-First LLM Wiki post and Governed Code Mode guide.

---

Summary and Key Takeaways

QQL 0.1.5 delivers a declarative query interface across Rust microservices, Python workers, Node.js applications, browser tools, and local edge runners. By standardizing query parsing, AST generation, and fail-closed validation, QQL ensures vector search operations behave consistently regardless of runtime environment.

• Unified Language: Package 0.1.5 delivers grammar 1.2 across Rust, Python, Node, WASM, and CLI.
• Structural Multi-Vector: ON FIELD and INTO clauses enforce explicit target vector assignment.
• Delimiter Safety: Four string formats eliminate escaping complexities for raw paths and multiline prompts.
• Decoupled Architecture: WHERE / inject_filter handles security isolation while SHARD handles physical node routing.

Pin package version 0.1.5, incorporate automated conformance fixtures into CI pipelines, and explore our guides on AST filter injection and local edge search to optimize your vector retrieval stack.

Footnotes

1. QQL. Source repository, architecture specs, and release documentation for the 0.1.5 release line. GitHub(opens in a new tab). ↩ ↩²

2. QQL. Grammar specification and syntax reference guide. docs/syntax.md(opens in a new tab). ↩