SkimmerDB Docs
API reference

Search

Text, regex, filters, vectors, counts.

Kept in this tab only and sent only to api.skimmerdb.com. Requests run against your account and count as usage. Make a key.

Search (query string)

GET /v1/namespaces/{name}/search metered: query

Text search as GET, the same answer as POST. Counts as one query (metered; see Usage).

Parameters

namestring · pathrequiredThe namespace's name.
qstring · queryText (or a regex with regex=1); empty lists documents.
regexboolean · queryq is an RE2 pattern.
filterstring · queryA filter as JSON text, e.g. {"status":"open"}.
limitinteger · queryHits a page (20).
cursorstring · queryThe next of the previous page.
scanboolean · queryAllow a regex the index can't narrow to scan a big namespace.

Answer

namespacestring
hitsHit[]Newest first (text) or nearest first (vector).
hits[].idstring
hits[].matchstringText search: the matched text.
hits[].linestringText search: the line around the match.
hits[].scorenumberVector search: cosine similarity (cosine namespaces) or euclidean distance.
hits[].metaobject
hits[].written_atstring
nextstringText search: pass as cursor for the next page (empty: no more).
docsintegerDocuments in the namespace.
took_msnumber
partialbooleanObject storage failed for some reads: hits may be missing.
scannedintegerVector search: candidates estimated.
rerankedintegerVector search: candidates reranked.
temperaturestringHow warm the namespace was: warm (open), local (opened from the server's disk) or cold (opened from object storage).
store_getsintegerObject-storage reads this query made (0 when warm).
store_bytesintegerBytes those reads fetched.
cpu_msnumberCPU the query used (metered, not billed).
timed_outbooleanThe query ran past the plan's time limit (query_seconds): the answer is partial.

Status codes

200OK
400Malformed: not the JSON expected.
401No key, or an unknown or revoked one.
402The free plan's included usage this period is used up (queries, query CPU, object-storage reads, bytes returned, writes or storage; the message says which), or its namespace count or daily namespace creations are reached (code namespace_limit): upgrade to pro.
403The key's scope or namespaces don't allow it, or the tenant is suspended.
404No such namespace, document, key or tenant (or one this key may not see: the same answer).
422Invalid: the message says why (code invalid with fields: which input fields; query_timeout: past the plan's time limit; scan_refused: send scan: true).
429Over the tenant's or the key's rate, concurrency or cap, or writes arriving faster than the namespace commits them (code write_busy): retry after Retry-After seconds.
503Object storage failed: retry (nothing was written, unless the code is write_unknown: then it may have been; retrying a write is safe).
curl -s https://api.skimmerdb.com/v1/namespaces/support/search \
  -H "Authorization: Bearer $KEY"
from skimmerdb import SkimmerDB
from skimmerdb._api.api.search import search_get

db = SkimmerDB()  # SKIMMERDB_KEY
answer = search_get.sync("support", client=db.api)
import { SkimmerDB } from "skimmerdb";
import { searchGet } from "skimmerdb/api";

const db = new SkimmerDB(); // SKIMMERDB_KEY
const { data } = await searchGet({ client: db.client, path: { name: "support" } });

Count

POST /v1/namespaces/{name}/count metered: query

Exact: every visible document that matches. exact: false estimates from a sample (lo..hi a 95% interval). Counts as one query (metered; see Usage).

Parameters

namestring · pathrequiredThe namespace's name.

Body application/json

qstringDefault "".
regexbooleanDefault false.
filterFilterEvery key must hold. {"status": "open"} equal; {"status": ["open", "pending"]} or {"status": {"in": [...]}} one of; {"priority": {"gte": 2, "lt": 5}} a numeric range (gt, gte, lt, lte); {"team": {"ne": "api"}} not equal (a missing key counts as not equal). Numbers compare as numbers.
exactbooleanfalse: estimate from a sample of the candidates (fast on big namespaces; no filters). Default true.
sampleintegerEstimates: candidates checked (2,000).
scanbooleanAllow a regex the index can't narrow to scan a big namespace (otherwise 422 scan_refused). Default false.

Answer

namespacestring
countinteger
exactbooleanfalse: count is an estimate (lo..hi is its 95% interval).
samplestring[]Some matching ids.
docsinteger
took_msnumber
partialboolean
temperaturestringHow warm the namespace was: warm (open), local (opened from the server's disk) or cold (opened from object storage).
store_getsinteger
store_bytesinteger
lointeger
hiinteger
candidatesinteger
cpu_msnumber

Status codes

200OK
400Malformed: not the JSON expected.
401No key, or an unknown or revoked one.
402The free plan's included usage this period is used up (queries, query CPU, object-storage reads, bytes returned, writes or storage; the message says which), or its namespace count or daily namespace creations are reached (code namespace_limit): upgrade to pro.
403The key's scope or namespaces don't allow it, or the tenant is suspended.
404No such namespace, document, key or tenant (or one this key may not see: the same answer).
422Invalid: the message says why (code invalid with fields: which input fields; query_timeout: past the plan's time limit; scan_refused: send scan: true).
429Over the tenant's or the key's rate, concurrency or cap, or writes arriving faster than the namespace commits them (code write_busy): retry after Retry-After seconds.
503Object storage failed: retry (nothing was written, unless the code is write_unknown: then it may have been; retrying a write is safe).
curl -s https://api.skimmerdb.com/v1/namespaces/support/count \
  -H "Authorization: Bearer $KEY" \
  -d '{"q":"refund","filter":{"status":"open"}}'
from skimmerdb import SkimmerDB
from skimmerdb._api.api.search import count
from skimmerdb._api.models import CountRequest

db = SkimmerDB()  # SKIMMERDB_KEY
answer = count.sync("support", client=db.api, body=CountRequest.from_dict({"q":"refund","filter":{"status":"open"}}))
import { SkimmerDB } from "skimmerdb";
import { count } from "skimmerdb/api";

const db = new SkimmerDB(); // SKIMMERDB_KEY
const { data } = await count({ client: db.client, path: { name: "support" }, body: {"q":"refund","filter":{"status":"open"}} });
200 answer
{
  "namespace": "support",
  "count": 1,
  "exact": true,
  "sample": [
    "t-1"
  ],
  "docs": 2,
  "took_ms": 0.2,
  "partial": false,
  "temperature": "warm",
  "store_gets": 0,
  "store_bytes": 0,
  "lo": 1,
  "hi": 1,
  "candidates": 1,
  "cpu_ms": 0.05
}

Count (query string)

GET /v1/namespaces/{name}/count metered: query

Count as GET. Counts as one query (metered; see Usage).

Parameters

namestring · pathrequiredThe namespace's name.
qstring · queryText (or a regex with regex=1); empty lists documents.
regexboolean · queryq is an RE2 pattern.
filterstring · queryA filter as JSON text, e.g. {"status":"open"}.
scanboolean · queryAllow a regex the index can't narrow to scan a big namespace.
exactboolean · query0: estimate.
sampleinteger · queryEstimates: candidates checked.

Answer

namespacestring
countinteger
exactbooleanfalse: count is an estimate (lo..hi is its 95% interval).
samplestring[]Some matching ids.
docsinteger
took_msnumber
partialboolean
temperaturestringHow warm the namespace was: warm (open), local (opened from the server's disk) or cold (opened from object storage).
store_getsinteger
store_bytesinteger
lointeger
hiinteger
candidatesinteger
cpu_msnumber

Status codes

200OK
400Malformed: not the JSON expected.
401No key, or an unknown or revoked one.
402The free plan's included usage this period is used up (queries, query CPU, object-storage reads, bytes returned, writes or storage; the message says which), or its namespace count or daily namespace creations are reached (code namespace_limit): upgrade to pro.
403The key's scope or namespaces don't allow it, or the tenant is suspended.
404No such namespace, document, key or tenant (or one this key may not see: the same answer).
422Invalid: the message says why (code invalid with fields: which input fields; query_timeout: past the plan's time limit; scan_refused: send scan: true).
429Over the tenant's or the key's rate, concurrency or cap, or writes arriving faster than the namespace commits them (code write_busy): retry after Retry-After seconds.
503Object storage failed: retry (nothing was written, unless the code is write_unknown: then it may have been; retrying a write is safe).
curl -s https://api.skimmerdb.com/v1/namespaces/support/count \
  -H "Authorization: Bearer $KEY"
from skimmerdb import SkimmerDB
from skimmerdb._api.api.search import count_get

db = SkimmerDB()  # SKIMMERDB_KEY
answer = count_get.sync("support", client=db.api)
import { SkimmerDB } from "skimmerdb";
import { countGet } from "skimmerdb/api";

const db = new SkimmerDB(); // SKIMMERDB_KEY
const { data } = await countGet({ client: db.client, path: { name: "support" } });

Warm a namespace

POST /v1/namespaces/{name}/warm metered: query

Opens the namespace and fetches what these searches will need, so an agent about to work on it gets warm answers from its first query. Counts as one query (metered; see Usage).

Parameters

namestring · pathrequiredThe namespace's name.

Body application/json

queriesstring[]Searches about to be made: their document lists are fetched now.
regexbooleanDefault false.

Answer

namespacestring
temperaturestringBefore warming: warm, local or cold.
store_getsinteger
store_bytesinteger
took_msnumber

Status codes

200OK
400Malformed: not the JSON expected.
401No key, or an unknown or revoked one.
402The free plan's included usage this period is used up (queries, query CPU, object-storage reads, bytes returned, writes or storage; the message says which), or its namespace count or daily namespace creations are reached (code namespace_limit): upgrade to pro.
403The key's scope or namespaces don't allow it, or the tenant is suspended.
404No such namespace, document, key or tenant (or one this key may not see: the same answer).
422Invalid: the message says why (code invalid with fields: which input fields; query_timeout: past the plan's time limit; scan_refused: send scan: true).
429Over the tenant's or the key's rate, concurrency or cap, or writes arriving faster than the namespace commits them (code write_busy): retry after Retry-After seconds.
503Object storage failed: retry (nothing was written, unless the code is write_unknown: then it may have been; retrying a write is safe).
curl -s https://api.skimmerdb.com/v1/namespaces/support/warm \
  -H "Authorization: Bearer $KEY" \
  -d '{"queries":["refund","ERR-404"]}'
from skimmerdb import SkimmerDB
from skimmerdb._api.api.search import warm_namespace
from skimmerdb._api.models import WarmRequest

db = SkimmerDB()  # SKIMMERDB_KEY
answer = warm_namespace.sync("support", client=db.api, body=WarmRequest.from_dict({"queries":["refund","ERR-404"]}))
import { SkimmerDB } from "skimmerdb";
import { warmNamespace } from "skimmerdb/api";

const db = new SkimmerDB(); // SKIMMERDB_KEY
const { data } = await warmNamespace({ client: db.client, path: { name: "support" }, body: {"queries":["refund","ERR-404"]} });
200 answer
{
  "namespace": "support",
  "temperature": "cold",
  "store_gets": 3,
  "store_bytes": 18211,
  "took_ms": 41.5
}