DATA MODEL
PROVIDERS

The SQL provider exposes a full relational interface: schema creation, DML, and parameterised queries. It sits directly on top of the backend's native SQL engine, so you get dialect-correct DDL and full JOIN support. Use it whenever your data has a clear schema and you need the expressiveness of SQL — aggregations, window functions, complex predicates.

The Document provider stores arbitrary JSON documents in named collections, with MongoDB-compatible filter operators ($eq, $gt, $lt, $in, $regex). Documents are indexed by a generated _id and stored in the backend's native JSONB column, so filter queries are backend-accelerated. No schema declaration is needed — just insert and query.

The Key-Value provider offers a Redis-style set/get/delete/exists interface with optional namespacing and per-key TTL expiry. Keys are arbitrary strings; values are JSON-serialisable objects. Expired keys are lazily purged on access. Use it for caching computed results, storing session tokens, feature flags, or any data with a natural lifetime.

The Vector provider stores high-dimensional embedding vectors in a FAISS index backed by the configured storage engine. It supports cosine and L2 similarity search, metadata filtering, and batch upsert. Vectors are identified by a vector_id string and carry a JSON metadata payload. Designed for RAG pipelines, semantic search, recommendation engines, and any workflow that involves embedding models.

The Graph provider exposes a property-graph model powered by NetworkX. Nodes carry typed properties; edges carry directional relationships with their own properties. Traversal operations support BFS/DFS, shortest-path, neighbour enumeration, and subgraph extraction. Graph state is persisted to the backing store between sessions.

The Stream provider implements an append-only event log with named streams. Producers publish JSON event payloads; consumers read from a stream with a configurable limit and optional offset cursor. Events carry monotonically increasing sequence numbers and wall-clock timestamps. Use it for activity feeds, audit logs, change data capture, and lightweight pub/sub within a single PolyDB instance.

The Spatial provider stores geometric shapes as WKT or GeoJSON with arbitrary attribute payloads. Queries include bounding-box intersection, radius/nearby search (metres), and contains/intersects predicates. Geometry operations are handled by Shapely for correctness; results are returned with the original WKT and all attributes. Suitable for store locators, delivery zones, asset tracking, and environmental datasets.

The Time Series provider stores named numeric metrics with ISO 8601 timestamps and free-form tag dictionaries. Range queries return raw data points or aggregated series (avg, sum, min, max, count) with optional downsampling intervals. Tags enable multi-dimensional filtering — for example, querying CPU usage by host and region simultaneously.

The Analytics provider builds OLAP-style cubes over fact tables with named dimensions and measures. Cube definitions declare the fact source and how dimensions map to columns; query operations slice and dice using one or more dimensions and aggregate measures with SUM, AVG, COUNT, MIN, or MAX. Results are returned as tabular JSON ready for charting libraries.

The S3 provider exposes a bucket/key object storage API, mirroring the AWS S3 interface. Start by creating a bucket with create_bucket, then write objects with put_s3_object. Objects are stored with arbitrary metadata and MIME type. Operations cover bucket lifecycle (create, delete, list) plus object put, get, delete, and list with prefix filtering.

The Memory provider implements a structured memory store for LLM agents, automatically classifying each interaction into episodic (specific events), semantic (general facts), or procedural (how-to knowledge) memory types. It tracks session context, supports semantic recall via embedding similarity, and provides recency-weighted retrieval so agents can surface the most relevant context for a given query.

The Temporal provider stores every write as a new immutable version rather than overwriting in place. Any past state can be retrieved with an as-of timestamp query. The complete version history for any entity is available as an ordered list. This enables full audit trails, configuration rollback, and compliance with data retention requirements — without any application-level versioning logic.

The Full-Text provider builds inverted indexes using FTS5 (SQLite) or tsvector (PostgreSQL/CockroachDB) and ranks results with BM25 relevance scoring. Documents are indexed with an ID and one or more text fields. Queries support phrase matching, boolean operators, and prefix search. Highlights with match snippets are optionally returned alongside results.

The Blob provider stores arbitrary binary data alongside a structured metadata envelope (MIME type, size, checksums, custom tags). Unlike the S3 provider, Blob is optimised for smaller objects that need queryable metadata — find all images tagged with a given label, or list all PDFs uploaded by a user. Binary content is base64-encoded in transit and stored as BYTEA or BLOB natively.

The Iceberg provider exposes Apache Iceberg table semantics: schema evolution, snapshot-based time-travel, partition pruning, and metadata-layer management. Tables accumulate snapshots on each write; any previous snapshot can be queried as a read-only view. Schema changes (add/drop/rename column) are tracked in the metadata layer without rewriting data files, making it suitable for long-lived analytical tables in a data lake architecture.

Cross-model ACID transactions — wrapping operations from SQL, Document, Key-Value, Vector, and other providers in a single commit-or-rollback boundary — are under active development. Single-operation SQL transactions are available today via query_sql. Full multi-provider transaction MCP tools will ship in an upcoming release.