Proto Reference

The gateway service is defined in proto/qql.proto. It uses Connect RPC — compatible with gRPC, gRPC-Web, and plain HTTP/1.1 JSON.

Full Definition

syntax = "proto3";

package qql;

option go_package = "github.com/srimon12/qql-go/gen/qqlpb";

// QQL is the Connect RPC service for executing QQL queries against Qdrant.
service QQL {
  // Exec parses and executes a single QQL query.
  rpc Exec(ExecRequest) returns (ExecResponse);

  // ExecBatch executes multiple queries in one round-trip.
  rpc ExecBatch(ExecBatchRequest) returns (ExecBatchResponse);

  // Explain returns the execution plan without running the query.
  rpc Explain(ExplainRequest) returns (ExplainResponse);

  // Health returns gateway and Qdrant connection status.
  rpc Health(HealthRequest) returns (HealthResponse);

  // Convert translates Qdrant REST JSON into QQL statements.
  rpc Convert(ConvertRequest) returns (ConvertResponse);
}

message ConvertRequest {
  string json_payload = 1;
}

message ConvertResponse {
  bool ok = 1;
  repeated string statements = 2;
  string error = 3;
}

message ExecRequest {
  string query = 1;
}

message ExecResponse {
  bool ok = 1;
  string operation = 2;
  string message = 3;
  bytes data = 4;   // JSON-encoded result data
}

message ExecBatchRequest {
  repeated ExecRequest queries = 1;
  bool stop_on_error = 2;
}

message ExecBatchResponse {
  repeated ExecResponse results = 1;
}

message ExplainRequest {
  string query = 1;
  bool json = 2;    // return structured JSON plan instead of text
}

message ExplainResponse {
  bool ok = 1;
  string query = 2;
  string plan = 3;
}

message HealthRequest {}

message HealthResponse {
  string version = 1;
  bool qdrant_connected = 2;
  string qdrant_status = 3;
}

Generated Code

The Go package is generated from this proto file:

gen/qqlpb/qql.pb.go          -- message types
gen/qqlpb/qql_grpc.pb.go     -- gRPC service stubs

Regenerate with:

Generate code

buf generate

HTTP JSON Mapping

Connect RPC maps proto RPCs to HTTP POST endpoints:

RPC	HTTP endpoint
Exec	POST /qql.QQL/Exec
ExecBatch	POST /qql.QQL/ExecBatch
Explain	POST /qql.QQL/Explain
Health	POST /qql.QQL/Health or GET /health
Convert	POST /qql.QQL/Convert

All endpoints accept Content-Type: application/json and return JSON.

buf.yaml

version: v1
modules:
  - directory: proto

buf.gen.yaml

version: v1
plugins:
  - plugin: go
    out: gen
    opt: paths=source_relative
  - plugin: go-grpc
    out: gen
    opt: paths=source_relative