API 参考 · BteloDB

Docs · L1（追加与订阅）

POST/v1/tables/{table}/docs

追加一条 JSON 文档或数组（≤1000 且 ≤8MB）。自动建表。带 Idempotency-Key 免费 exactly-once。200 ⇒ 已 fsync 落 WAL；偏移严格单调、写完即读。

MALFORMED_JSONRESERVED_FIELDPAYLOAD_TOO_LARGERATE_LIMITEDQUOTA_EXCEEDEDBACKPRESSURE

GET/v1/tables/{table}/docs?from_offset&max_count&max_wait_ms

按偏移拉取，热内存表与冷 S3 Parquet 间无缝跨越。max_wait_ms>0 长轮询至有新数据或超时。

TABLE_NOT_FOUNDOFFSET_OUT_OF_RANGEINVALID_ARGUMENT

GET/v1/tables/{table}/tail?from_offset=<u64|latest>

实时订阅（SSE）。id:<偏移> + data:<文档>；15s 心跳；Last-Event-ID 续传。同路径支持 WebSocket 变体。

TABLE_NOT_FOUNDOFFSET_OUT_OF_RANGERATE_LIMITED

KV · L2（单键线性一致）

GET/v1/kv/{bucket}/{key}

读取 value + version + expires_at。过期键读作不存在（惰性过期）。

KEY_NOT_FOUND

PUT/v1/kv/{bucket}/{key}?ttl_seconds

写入 / CAS（If-Match）/ 仅创建（If-None-Match: *）。无条件 = 覆盖写。ttl_seconds 设 TTL；不带则清除。

CAS_CONFLICTALREADY_EXISTSPAYLOAD_TOO_LARGEKEY_NOT_FOUNDQUOTA_EXCEEDED

DELETE/v1/kv/{bucket}/{key}

删除（可选 If-Match）。版本序列不复用（G-NO-ABA）。

KEY_NOT_FOUNDCAS_CONFLICT

POST/v1/kv/{bucket}/{key}/increment

原子自增（i64 delta，可负）。并发无丢失更新。SDK 绝不盲重试。

INVALID_ARGUMENT

GET/v1/kv/{bucket}?prefix&cursor&limit

前缀列举（key 字典序，快照一致）。过期条目不出现。

POST/v1/kv/{bucket}/{key}/expire

对存活键设置 / 重置 / 清除 TTL（ttl_seconds 数字或 null）。版本 +1。

KEY_NOT_FOUNDINVALID_ARGUMENT

Query · 对表的 SQL

POST/v1/query

单语句 SELECT。位置参数 $1..$n。JSON 路径 data['a']['b']、全文 contains/token_match/regexp_like、vector_distance kNN。快照一致（含已提交 mutation）。JSON 或 Arrow 输出。

INVALID_SQLUNSUPPORTED_SQLUNSUPPORTED_TRANSACTIONSCAN_LIMIT_EXCEEDEDRATE_LIMITEDTABLE_NOT_FOUND

Mutations · L3（批量 UPDATE/DELETE）

POST/v1/tables/{table}/mutations

提交批量 update/delete（op, where, params, set, dry_run）。202 异步；提交点 = manifest 版本推进，原子可见。每表 10/分钟，串行 FIFO。

INVALID_SQLINVALID_ARGUMENTTABLE_NOT_FOUND

GET/v1/mutations/{mutation_id}

查询变更状态（pending|running|applied|failed）+ affected_rows + committed_manifest_version。

MUTATION_NOT_FOUND

Tables · 管理

PUT/v1/tables/{table}

建表 / 改配置（ttl_days, description）。幂等。

INVALID_ARGUMENT

GET/v1/tables

列出表：name, doc_count, bytes, max_offset, ttl_days。

GET/v1/tables/{table}

单表详情 + 当前推断 schema。

TABLE_NOT_FOUND

DELETE/v1/tables/{table}

异步整表删除（不可逆）。需头 X-Confirm-Delete: {table}。

INVALID_ARGUMENT

系统

GET/v1/usage

当前用量 + 层级限额（摄取/扫描/存储/kv）。

GET/healthz

存活探针（免认证）。返回 200 "ok"。

从这里开始

5 分钟快速上手 · Docker 镜像

完整的 /v1 表面。