HTTP reference

With --replication-token, /_replication is taken as well: the stream a replica is fed, its status, and a replica's promotion — see Replication. It asks for that token rather than --http-token, and a collection named _replication is then out of HTTP's reach.

/_schema compares a schema declared in code with the server's, in the engine every SDK's check goes through — see Schema in code. Its body is the description, {"format": 1, "fenecql": "create collection ...", "migrations": [...]} or its collections as JSON. A plan answers {"applied", "ran", "migrations", "statements", "refusals"}, and writes nothing; with ?mode=follow it says only what the code declares and the server lacks, which a scoped token may ask of the collections it reads. An apply takes the server's token, runs the migrations not yet recorded and the additions under the write lock as one block, and answers 409 with the refusals when anything is refused, having written nothing.

With --mcp, /_mcp is the Model Context Protocol's endpoint: an agent's schema, search, query and get tools, and write and a memory where asked for, each a statement held to the request's token as /query is — see Agents and MCP. Without the flag it answers 404.

/_metrics is the server's statements, latency and data in Prometheus's text format, readable with --http-token or the admin token — see Monitoring. The underscore keeps it out of the way of a collection called metrics; a collection called _metrics cannot be read over GET.

Values are parsed by the field's type: ?year=gte.2024 is an int, ?published=gte.2024-01-01 is a timestamp. An unknown field returns 404. where= exists for what the pattern cannot hold — or groups and function calls.

near is a POST rather than a query parameter because a 768-dimension embedding does not fit in a query string. Squeezing it into the URL — base64, truncation — is unreadable and runs into proxy and server URL ceilings. PostgREST's model does not cover fenecdb's headline feature, so near gets its own endpoint, and it takes a filter in the body.

If the collection has a single vector field, field can be left out. Filters in the query string are anded with the where in the body.

A vector in an answer, and a _score, is its f32s written as the shortest decimals that read back as them — 0.1 as it was written, the text pgvector gives — rather than the 0.10000000149011612 of the f64 each widens to. A reader that takes a number as an f64 and rounds it to f32, as a Float32Array does, gets every one back: the one f32 an f64 would round away, 7.038531e-26, is written as its f64.

A "match" makes it hybrid: BM25 over the collection's @text field ranks the same request, and the two rankings are fused by reciprocal rank (fuse). match_field names the text field when there are several; match_fuzzy (true, or 0 to 2 edits) and match_prefix read its words as match ... fuzzy and prefix do; fuse_k and candidates are the rank offset and how many candidates each side ranks.

curl -X POST http://127.0.0.1:8080/articles/near -d '{
  "vector": [0.1, 0.2, 0.3],
  "match": "borrow checker lifetimes",
  "limit": 10
}'

lookup=<name> names the collection once; every key prefixed with it configures the clause — on (required, the child's field holding the key), parent, select, order, limit, offset, required, where, and any field name as a condition, in the same op.value form the parent's filters use. Prefixing is what keeps the two sides apart in a query string, the way the clause's position does in FenecQL.

curl 'http://127.0.0.1:8080/shops?limit=20&select=name\
&lookup=orders,lines&orders.on=shop_id&orders.limit=3\
&lines.on=order_id&lines.limit=5'
# [{"name":"Merkez","orders":[{"code":"A","lines":[{...}]}, ...]}, ...]

A comma-separated list chains, read left to right, each name binding to the one before it and each level keeping its own prefix. A query string has no position to scope by, so the order is written out; the meaning is the same one FenecQL gets from position, up to the same 8 levels.

lookup is a reserved key here, so a field named lookup cannot be filtered over the REST path — the FenecQL and fenec-server paths are unaffected, as with the other reserved names.

A query with a lookup answers with the children nested under the collection's name — one object per parent, with an empty array where nothing matched, and a chain nests all the way down.

curl -X POST http://127.0.0.1:8080/query \
  -H 'content-type: application/json' \
  -d '{"query":"get products limit 20 lookup reviews on product_id limit 3"}'
# [{"id":1,"name":"Kahve","reviews":[{"id":1,"stars":5,"body":"guzel"}]}, ...]

Inside fenec-server started with --max-memory, the listener holds its writes to that ceiling: above it, a statement that grows the data — a put, a patch, a create index — is refused with 507, a batch stops there as at an error, and reads, deletes and compact go on, since they are the way out. The rule and why it is there are under Server.

GET /<name>/changes is a server-sent events stream: a seed carrying the current shape, then incremental diffs. No driver needed.

A subscription does not poll. fenec-core has no waiting primitive at all — there are no threads in wasm — it only reports that the change counter has reached a point, and fenec-http ties that to a Condvar. A 50 ms polling loop would take 20 read locks per second per subscriber and still add 50 ms of latency.

Every subscription is a connection and a thread, so they are counted separately from ordinary requests as well (--http-max-streams, default 64, a database's: on a tenant node each tenant's). Sharing one ceiling would let 100 subscribers shut the server to plain requests. A stream is also one of the node's --max-connections, the bound every tenant of a node shares, of which each tenant's streams take a quarter at most unless its quota says otherwise. The client-side layer built on this stream is Sync.

A row past its @ttl leaves every read at once and the file at the sweep, a minute and its grace later; a stream of its collection is told of it at its time. It works out when the next row of the collection reaches its time -- a step of the field's ordered index, again after each write to the collection -- sleeps until then if no write comes first, and reads the rows that reached it since it last looked, the shape ANDed in, telling each as a deletion as the sweep's delete would be told: a scoped stream of the rows it was sent alone, a shape that holds nothing (what FenecHttp.live opens) that something changed. Heard at the sweep, a courier whose phone went quiet stayed on a dispatcher's map 73 s after it had gone from every read; at its time, it is told about 10 ms after it. The sweep's delete comes after, a deletion of what is gone already.

What a stream costs, measured on an M1 with streams of a shape that holds nothing (what FenecHttp.live opens): 45 to 57 KB of resident memory and a thread each, and every write wakes every stream, which reads what it changed: a write's p50 went from 0.26 ms with none to 0.94 with 60 and 3.1 with 500. A page thousands view should not hold one a viewer; it polls (below).

Under a scoped token, a stream of a shape that holds nothing (where=false) is told of the writes to rows the token may read, and of nothing else: the server follows the token's own filter, keeps the ids it selects and sends none, and a write to one of them, or one of them leaving the token's rows, is a change holding no rows. ANDed with the token's filter, the shape matched nothing and FenecHttp.live never ran again; told of every write, the stream would hand the token the moments of other users' writes.

Whether a collection was written since a tag is the change ring's answer (Database::changed_collections_since): a tag older than the ring reaches, or a collection dropped since, counts as a change and the query runs. A read without the header is answered as before, no tag worked out. Over one keep-alive connection a 304 took 54 us at the median, against 55 for a read by key and 95 for a page of 24 run; the round trip is most of either. A browser keeps its connection between polls, so a public page polls through the site's own server or a proxy, which keeps few connections to fenec-server however many viewers it has.

A tag is a change of the copy that answered. A read replica holding that change of its history (Fenec-After) judges it as home does, but only up to where it stands: behind home it answers 304 to a write home holds, so FenecHttp.live polls home on a client reading near (Read replicas).

A subscription keeps a query's rows up to date, and a client that falls behind its ring of ids is sent the rows again. A service that must see every write — to index it elsewhere, send it on to Kafka, or keep a read model — reads GET /_changes instead: the writes on disk, documents and all, one JSON object a line, from any write the server still keeps.

• seq is the change counter's number for the write, and Fenec-Next the last one in the answer: sent back as the next since, nothing is missed or had twice. Keep it where your consumer keeps its own state, and commit the two together.
• Fenec-Seq on every answer is the last write the database holds, on disk or not yet, the writes the stream leaves out (a consumer's cursor, an idempotency key) among them. An answer whose Fenec-Next is that has every write there is: a worker that catches up before it serves knows it at once, where an empty page alone could not tell it from one whose writes are not on disk yet under --sync 250, and waited out pages to be sure. A Fenec-Next behind it has writes to come: read again with wait. A client that notes Fenec-Seq for Fenec-After reads a replica from there on.
• A batch's writes are one record on disk and come together, numbered one by one; a cursor inside one goes on after the write it names.
• Only what an fsync has covered is handed over, as a replica is fed: a write the server lost in a crash never reached a consumer.
• since left out is the last write on disk: what is written from now on. limit is 1 000 unless given, 10 000 at most; wait is how long an answer with nothing in it waits for a write first, in milliseconds, 30 000 at most.
• The server keeps as many writes as --replication-buffer holds (64 MiB unless given), written to disk or not yet. A cursor further back is answered 410 with the first since it does serve — which may be a write not on disk yet, whose read waits for it — never with writes missing from the middle; one past the last write — another database's cursor, or this one restored — 409. The feed starts at the change counter when the server starts.
• op is put, del, create, alter or drop; a put carries the document as it was written, as JSON writes a row.
• It needs --http-token or no token at all: a scoped token's filter could not hold back the deletion of a row it never saw, and is refused (403).

--cdc keeps the feed a primary keeps for its replicas and feeds none; with --replication-token it is kept already, and a tenant node's tenants have theirs at /t/<tenant>/_changes. It needs --file and a --sync other than off. Keeping it cost nothing measurable: 16 400 single puts a second over HTTP either way, and 9 000 rows of 128 dimensions read back at 283 000 a second.

A consumer that keeps no state of its own can have the server keep where it is, as a Kafka consumer group keeps its committed offset. Made with a POST — at the last write on disk unless the body names a since — it reads with ?consumer= from where it stands, and moves with a PATCH of since once it has done with what it read, or back to a since it wants to read from again.

A POST to a consumer that is there already changes nothing and answers 200 with where it stands; only a consumer it makes is 201. The since in its body is where a new consumer starts, as Kafka's auto.offset.reset applies only to a group with no committed offset, so a program can make its consumer with {"since": 0} every time it starts and still go on from its last commit. A since ahead of where an existing consumer stands is 409, {"error": …, "since": <where it stands>}: it is a commit sent as a POST, and answered 200 its client would read the same page forever. A program that must know it made the consumer reads the status. A PATCH of a consumer that is not there is 404 rather than making it: the POST is the one way to make one. Both answer with where the consumer stands afterwards and with Fenec-Seq, as a write does, so a read sent after it (Fenec-After), to a replica too, finds it there. A commit past nothing but other commits writes nothing and leaves the consumer where it was, which reads the same writes; its answer says so. A since past the last write the database holds is 409 for either.

So a consumer has each write at least once, and a write again after a crash between reading it and committing. The cursors are rows of a _consumers collection, written as any write is — on disk before the answer under --sync always, and on the replicas — and their own writes are left out of the stream, the cursor going past them. A replica reads from where the primary's consumer stands, refuses to make, move or delete one (403), and once promoted goes on from the same place. On a tenant node they are the tenant's writes: while it is being moved, or its node's lease is out, each is answered 503 to come back. A read with wait waits on past them too, so a consumer's own commit does not wake its next read, and a commit past nothing but cursors writes nothing: a consumer that commits after every answer, an empty one too, sits idle while nothing else is written. An unknown consumer is 404 rather than read from "now" each time, which would miss what is written between two reads. A consumer further behind than the server keeps is 410 with the first since it does keep, as a cursor is; a PATCH there goes on from it. The server keeps writes by their size, written to disk or not yet, so that since can be ahead of the last write on disk: a PATCH takes it, and the read from there waits for the disk. GET /_changes/consumers lists each consumer's since and how many writes it is behind.