Wire Protocol

VeltrixDB speaks two protocols over the same TCP port: a human-readable text protocol for ad-hoc use with nc or telnet, and a compact binary protocol that every official SDK uses by default. The server auto-detects which one a connection is speaking from the first byte.

Text protocol

The text protocol is line-oriented — one command per line, a plain-text response per line — which makes it usable directly from nc, telnet, or any tool that can write to a TCP socket. It's the fastest way to sanity-check a running server.

SET is an alias of PUT, DELETE of DEL, EXIT of QUIT, and CLUSTER of TOPOLOGY. Commands are case-insensitive. A malformed command answers ERR usage: ...; an unknown one answers ERR unknown command: ... with the supported list.

Text commands added in v1.1.0

v1.1.0 brings the text protocol to parity with operations that were previously binary-only (TTL writes, atomics, batch get) and adds the new list and set data types. The usage lines below are exactly what the server prints on a malformed invocation (ERR usage: ...):

Search, index and query commands

Search commands answer id score lines then END, or one ERR ... line. What they do — ranking, filters, memory layouts, cluster fan-out — is on Vector & Hybrid Search.

Option clauses may come in any order, each at most once; the floats or the QUERY text come last. Because the text protocol is whitespace-split, filter values cannot contain spaces and TSET text cannot contain newlines — use the binary search opcodes for those.

Other text commands

Worked example

Start a server and drive it with nc:

$ docker run -p 9000:9000 ghcr.io/veltrixdb/veltrixdb:latest

$ nc localhost 9000
PUT hello world
OK
GET hello
world
PUT counter 41
OK
GET counter
41
DEL hello
OK
GET hello
ERR
PING
PONG
INFO
keys=1 writes=3 reads=3 ...
QUIT
BYE

Or pipe a whole session in one shot, as shown in the project's own quick-start:

echo -e "PUT hello world\nGET hello\nPING" | nc localhost 9000

Binary protocol

The binary protocol is what every official SDK (Go, Python, Node.js, Java, Rust, C++) speaks by default (only the Go client implements the search opcodes), and it's what the server assumes once it sees a leading byte that matches a known opcode rather than ASCII command text — no handshake or negotiation is required, the server simply auto-detects the framing per connection.

Frame layout

Request:  [1B cmd][2B keyLen][4B valLen][key][value]
Response: [1B status][4B payloadLen][payload]

Opcodes

Every opcode below is defined in cmd/server/main.go (handlers for 0x20–0x29, 0x08, 0x1C, 0x1E and 0x1F in cmd/server/ext_ops.go). 0x1D is unused. New opcodes take free slots at or below 0x29, because a first byte above it is read as text.

The atomic opcodes 0x18–0x1B use extended frames that carry the extra operands (expected value, delta, TTL) — as of v1.1.0 the same four operations are also available as text commands (CAS/INCR/DECR/SETNX, above) and in every official SDK:

CAS:   [1B 0x18][2B keyLen][4B expectedLen] + [4B newLen][4B ttl] + key + expected + new
INCR:  [1B 0x19][2B keyLen][4B 0]           + [8B delta int64] + [4B ttl] + key
DECR:  [1B 0x1A][2B keyLen][4B 0]           + [8B delta int64] + [4B ttl] + key
SETNX: [1B 0x1B][2B keyLen][4B valLen]      + [4B ttl] + key + value

Vector and search frames

Each frame starts with the standard 7-byte header [1B cmd][2B][4B], whose two fields are reinterpreted per opcode; all integers are little-endian, floats are IEEE-754 float32 LE. Writes answer the standard OK/ERR frame.

VSET     0x26: [1B][2B keyLen][4B dim] + key + dim×4B
VSEARCH  0x27: [1B][2B k][4B dim]      + dim×4B
VSETNS   0x08: [1B][2B idLen][4B dim]  + [2B nsLen] + ns + id + dim×4B
VSEARCHX 0x1E: [1B][2B k][4B dim]      + [2B nsLen][2B ef][2B fieldLen][2B opLen][2B valLen]
               + ns + field + op + value + dim×4B      (fieldLen 0 = no filter, ef 0 = default)
VDEL     0x1F: [1B][2B idLen][4B nsLen] + ns + id

SEARCH   0x1C: [1B][2B subop][4B payloadLen] + payload of [4B len][bytes] fields
  1 VCREATE: ns, dim u32, quant ("" | none | int8 | pq)
             [, pqM u32, pqTrainAt u32, graph ("" | memory | disk)]          → OK
  2 TSET:    ns, id, text                                                     → OK
  3 TDEL:    ns, id                                                           → OK
  4 TSEARCH: ns, k u32, query, filterField, filterOp, filterValue             → matches
  5 HSEARCH: ns, k u32, ef u32, alpha f32 (NaN = default 0.5), candidates u32,
             vec (dim×4B, may be empty), query, filterField, filterOp, filterValue → matches
  (filterField "" = no filter)

Matches (VSEARCH, VSEARCHX, TSEARCH, HSEARCH):
  [1B OK][4B count] + count × [2B idLen][4B score float32][id]

The trailing VCREATE fields (pqM, pqTrainAt, graph) are new in v1.12 and optional, so older clients that send only the first three fields keep working. The Go client is the only official SDK that implements these frames (VSetNS, VSearchWithOptions, VDel, VCreateWithOptions, TSet, TDel, TSearch, HSearch).

Status codes

Protocol auto-detection

Both protocols share the same TCP listener (-addr, default :9000). A single connection is either all-text or all-binary — the server determines this from the leading byte of the first request — 0x01–0x29 selects binary, anything else is read as a text line — and does not switch mid-connection. You never need to configure which protocol to use; connecting with nc/telnet naturally speaks text, and every official SDK's connection pool speaks binary. This applies to the default --net=go front-end; see below for the opt-in C++ front-end.

Which front-end serves which commands New in v1.7

The --net server flag selects the network front-end that listens on -addr: