Documentation

Build with PerceptDB

The live multimodal data cloud. Store objects, embeddings, events, and metadata — query with SQL, API, CLI, or natural language.

Quickstart

From zero to first query in 5 minutes

Concepts

Objects, records, embeddings, events, traces

Search Studio

Natural language → query plan

Quickstart

A complete pipeline from RTSP camera to natural-language search.

1Install the CLI

curl -fsSL https://percept.dev/install.sh | sh
percept login

2Create a project

percept project create warehouse-demo \
  --region us-central-1 \
  --use-case "video + event search"

3Connect a camera stream

percept stream create dock-cam-4 \
  --type rtsp \
  --url rtsp://camera.local/stream \
  --tier hot \
  --retention 72h

4Deploy a pipeline

percept pipeline deploy templates/package-delivery.yaml

5Search

percept search "did the package get delivered and was the door left open?" \
  --project warehouse-demo \
  --since 24h \
  --evidence

Core concepts

Five primitives. Everything is built from these.

Object

A file or media asset — image, video, PDF, audio, document, blob

Record

A structured row — camera, delivery, customer, shipment, claim

Embedding

A vector representation — image, text, video segment, audio, multimodal

Event

A timestamped meaningful occurrence — package delivered, door opened, signature detected

Trace

The provenance chain — raw object → segment → embedding → event → query result → evidence

SDKs

Python

from perceptdb import Client

db = Client(api_key="...")

results = db.search(
    project="warehouse-demo",
    query="package delivered and door left open",
    sources=["dock-cam-4"],
    since="24h",
    evidence=True,
)

TypeScript

import { Percept } from "@perceptdb/sdk";

const percept = new Percept({ apiKey: process.env.PERCEPT_KEY });

const results = await percept.search({
  query: "person in red hoodie entering loading dock",
  project: "warehouse-demo",
  since: "7d",
  evidence: true,
});

Percept SQL

Postgres-compatible plus multimodal functions.

Vector + metadata hybrid query

SELECT segment_id, start_time,
  VECTOR_SCORE(embedding, 'person carrying cardboard box') AS score
FROM video_segments
WHERE site_id = 'austin_dc'
  AND start_time > NOW() - INTERVAL '24 hours'
  AND VECTOR_MATCH(embedding, 'person carrying cardboard box') > 0.82
ORDER BY score DESC
LIMIT 20;

OBJECT_SEARCH (table function)

SELECT *
FROM OBJECT_SEARCH(
  bucket  => 'raw-video',
  query   => 'white delivery van backing into loading dock',
  time_range => INTERVAL '7 days',
  filters => OBJECT_CONSTRUCT('site_id', 'austin_dc')
)
WHERE score > 0.85
LIMIT 50;

Function reference

VECTOR_MATCH()

Returns bool · ANN lookup

VECTOR_SCORE()

Returns float in [0, 1]

OBJECT_SEARCH()

Table-valued hybrid search

SPATIAL_CONTAINS()

Geo + zone polygon

TEMPORAL_OVERLAPS()

Interval logic

EVIDENCE_CHAIN()

Returns provenance JSON

REHYDRATE()

Move object Cold → Hot

EMBED()

Compute embedding inline

REST API

Base URL: https://api.percept.dev/v1

POST/v1/searchNatural language or hybrid search

POST/v1/queryExecute SQL with multimodal functions

POST/v1/objectsUpload an object

POST/v1/streamsCreate a streaming source

POST/v1/indexesCreate a vector/keyword/event index

POST/v1/eventsInsert or query events

GET/v1/projects/{id}Project metadata

POST/v1/evidence/{event_id}/exportSigned PDF + clip bundle

CLI reference

percept login
percept org switch miriel-ai
percept project create warehouse-demo
percept project use warehouse-demo

percept bucket create raw-video --tier hot
percept object upload ./dock-cam.mp4 --bucket raw-video \
  --metadata site_id=austin_01,camera_id=dock_4

percept stream create dock-cam-4 --type rtsp \
  --url rtsp://camera.local/stream --tier hot

percept index create delivery-search \
  --source raw-video --modality video \
  --model percept-video-large

percept search "person carrying package" --since 24h --evidence
percept query ./queries/door-left-open.sql
percept pipeline deploy package-delivery-detector.yaml
percept evidence export event_123 --format pdf --include-clips