Skip to content

usage.md

Latest commit

 

History

History
155 lines (102 loc) · 3.42 KB

usage.md

File metadata and controls

155 lines (102 loc) · 3.42 KB

ChronosDB Usage Guide

This document is a comprehensive ChronosDB CLI and core protocol usage guide, modeled after Ocular's style (clear sections, choice exposition, and explicit examples).

1. Goals

ChronosDB provides:

  • Write path fully consistent through Raft:
    • INSERT, UPDATE, DELETE
  • Vector search and time-travel query path:
    • SELECT, GET, HISTORY, AS OF
  • Native RETURNING id on write operations with wire-flag support.
  • No implicit SQL translation in the client—command->opcodes are explicit.

2. Running the CLI

Start a local Chronos node

cargo run --release -- --node-id 1 --addr 127.0.0.1:9000 --raft-port 20001 --control-port 20002 --bootstrap

Start CLI

cargo run --bin chronos-cli -- --host 127.0.0.1:9000

Non-interactive script mode

cat > script.sql <<'EOS'
INSERT INTO VECTORS VALUES ([0.1, 0.2, 0.3], "hello") RETURNING id;
SELECT FROM VECTORS WHERE VECTOR NEAR [0.1, 0.2, 0.3] LIMIT 5;
EOS

cargo run --bin chronos-cli -- --script script.sql --host 127.0.0.1:9000 --script-continue-on-error

3. Command Reference

Insert

INSERT INTO VECTORS VALUES ([0.1, 0.2, ...], "payload")

Inserts a new version record with vector and payload. Node auto-pads vectors shorter than 128 dims.

Update

UPDATE VECTORS SET PAYLOAD="updated" WHERE ID='uuid'

Appends a new version with updated payload.

Delete

DELETE FROM VECTORS WHERE ID='uuid'

Soft delete (tombstone): history remains.

Get

GET 'uuid'

Retrieves the latest payload for the given ID.

Time Travel

SELECT FROM VECTORS WHERE ID='uuid' AS OF 1670000000

Returns the version valid at the specified timestamp.

History

HISTORY 'uuid'

Returns full version timeline of the record.

Vector Search

SELECT FROM VECTORS WHERE VECTOR NEAR [0.1, 0.2, ...] LIMIT 5

Returns nearest records using HNSW index.

4. RETURNING Support

Write commands now support explicit RETURNING id in the query.

Example:

INSERT INTO VECTORS VALUES ([0.1, 0.2, ...], "payload") RETURNING id;
UPDATE VECTORS SET PAYLOAD="updated" WHERE ID='uuid' RETURNING id;
DELETE FROM VECTORS WHERE ID='uuid' RETURNING id;

Wire behavior

  • Request includes 1-byte flags:
    • 0x01: RETURNING id requested
    • 0x00: none
  • Server response:
    • 1-byte status (0=OK, 1=ERR)
    • 4-byte little-endian payload length
    • binary payload (UUID when returning id)

5. Low-level protocol mapping

OpCode map

  • INSERT -> OP_INSERT (0x01)
  • GET -> OP_GET (0x02)
  • SEARCH -> OP_SEARCH (0x03)
  • HISTORY -> OP_HISTORY (0x04)
  • DELETE -> OP_DELETE (0x05)
  • UPDATE -> OP_UPDATE (0x06)
  • GET AS OF -> OP_GET_AS_OF (0x07)

Write payload format

[flags=1][id=16][vector=128*4][payload...]

Read payload format

  • GET/HISTORY/SEARCH etc uses its own body structures (see code).

6. Script mode behavior

Use --script-continue-on-error to keep processing on errors; each result contains success, exit_code, output, and error fields.

7. Troubleshooting

  • Raft Write Error: APIError(ForwardToLeader(...)) means a follower received a write; retry with leader address.
  • No record found valid at time means no version existed in the requested interval.

8. Next steps

  • expand support to RETURNING payload and RETURNING vector.
  • add configurable CLI autocompletion and explicit connection health checks.