Examples — PolyDB Docs

SQL

Relational queries

Run parameterised SQL against any table in your tenant schema with query_sql. DDL (CREATE TABLE, ALTER, DROP) is issued via the backend's query-builder AST rather than as raw SQL strings — the examples below assume the products table already exists.

Query with filter

// Tool: query_sql
{
  "query": "SELECT name, price FROM products WHERE price > ? ORDER BY price DESC",
  "params": [20]
}

Document

NoSQL JSON collections

Store a document

// Tool: store_document
{
  "collection": "users",
  "document": {
    "name": "Alice Nguyen",
    "email": "alice@example.com",
    "role": "admin",
    "created_at": "2024-03-15T09:00:00Z",
    "preferences": { "theme": "dark", "notifications": true }
  }
}

Filter query

// Tool: search_documents
{
  "collection": "users",
  "filter": { "role": { "$eq": "admin" } },
  "limit": 10
}

Range filter

// Tool: search_documents
{
  "collection": "orders",
  "filter": {
    "total": { "$gt": 100 },
    "status": { "$in": ["pending", "processing"] }
  },
  "limit": 25
}

Key-Value

Cache & sessions

Set with TTL

// Tool: set_keyvalue
{
  "key": "session:abc123def456",
  "value": {
    "user_id": "user-789",
    "email": "alice@example.com",
    "roles": ["admin"],
    "login_at": "2024-03-15T10:30:00Z"
  },
  "namespace": "sessions",
  "ttl": 3600
}

Get

// Tool: get_keyvalue
{
  "key": "session:abc123def456",
  "namespace": "sessions"
}

Feature flag

// Tool: set_keyvalue
{
  "key": "feature:dark-mode-v2",
  "value": { "enabled": true, "rollout_pct": 50 },
  "namespace": "flags"
}

Vector

Embeddings & semantic search

Store an embedding

// Tool: store_vector
{
  "collection": "articles",
  "vector": [0.1, 0.5, -0.3, 0.8, 0.02, -0.44, 0.17, 0.93],
  "vector_id": "article-2024-03-001",
  "metadata": {
    "title": "Introduction to PolyDB",
    "author": "eng-team",
    "tags": ["database", "polydb", "tutorial"],
    "published": "2024-03-10"
  }
}

Semantic search (top-5)

// Tool: search_vectors
{
  "collection": "articles",
  "query_vector": [0.11, 0.48, -0.28, 0.82, 0.04, -0.41, 0.19, 0.90],
  "k": 5
}

Graph

Nodes, edges & traversal

Add nodes

// Tool: add_graph_node
{
  "node_id": "alice",
  "node_type": "person",
  "properties": { "name": "Alice Nguyen", "age": 30, "city": "San Francisco" }
}

// Tool: add_graph_node
{
  "node_id": "bob",
  "node_type": "person",
  "properties": { "name": "Bob Chen", "age": 34, "city": "New York" }
}

Add edge

// Tool: add_graph_edge
{
  "from_node": "alice",
  "to_node": "bob",
  "edge_type": "knows",
  "properties": { "since": 2020, "context": "conference" }
}

Query graph (neighbours, traversal, paths)

// Tool: query_graph
{
  "start_node": "alice",
  "pattern": "neighbors",
  "depth": 2
}

Stream

Event streams

Publish event

// Tool: publish_stream
{
  "stream_name": "user-events",
  "event_data": {
    "type": "login",
    "user_id": "alice",
    "ip": "192.168.1.101",
    "user_agent": "Mozilla/5.0",
    "timestamp": "2024-03-15T10:30:00Z"
  }
}

Consume (latest 50)

// Tool: consume_stream
{
  "stream_name": "user-events",
  "limit": 50
}

Consume from cursor (pagination)

// Step 1 — first page (no cursor). Response includes next_cursor.
// Tool: consume_stream
{
  "stream_name": "user-events",
  "limit": 50
}
// Response: { "events": [...], "count": 50, "next_cursor": "eyJpYSI6MTcxMD..." }

// Step 2 — next page. Use the next_cursor returned by Step 1 as the cursor here.
// (Do not copy the placeholder verbatim — substitute the actual base64 cursor string.)
// Tool: consume_stream
{
  "stream_name": "user-events",
  "cursor": "eyJpYSI6MTcxMD...",
  "limit": 50
}
// next_cursor is null when the end of the stream is reached.

Spatial

Geospatial queries

Store a point (WKT)

// Tool: store_spatial
{
  "table_name": "landmarks",
  "geometry": "POINT(-73.9857 40.7484)",
  "attributes": {
    "name": "Empire State Building",
    "category": "landmark",
    "floors": 102
  }
}

Store a polygon (delivery zone)

// Tool: store_spatial
{
  "table_name": "delivery_zones",
  "geometry": "POLYGON((-74.01 40.70, -73.97 40.70, -73.97 40.73, -74.01 40.73, -74.01 40.70))",
  "attributes": { "zone_id": "zone-manhattan-south", "courier": "fleet-A" }
}

Nearby search (1 km radius)

// Tool: search_spatial_nearby
{
  "table_name": "landmarks",
  "longitude": -73.9857,
  "latitude": 40.7484,
  "radius_meters": 1000,
  "limit": 10
}

Time Series

Metrics

Write a metric

// Tool: store_timeseries
{
  "metric": "api_latency_ms",
  "value": 42.5,
  "tags": { "endpoint": "/api/users", "method": "GET", "region": "us-east-1" }
}

Query a time range

// Tool: query_timeseries
{
  "metric": "api_latency_ms",
  "start_time": "2024-03-15T00:00:00Z",
  "end_time": "2024-03-16T00:00:00Z",
  "tags": { "region": "us-east-1" }
}

Aggregate (hourly average)

// Tool: query_timeseries (with aggregation)
{
  "metric": "api_latency_ms",
  "start_time": "2024-03-15T00:00:00Z",
  "end_time": "2024-03-16T00:00:00Z",
  "aggregation": "avg",
  "interval": "1h"
}

Analytics

OLAP cubes

Create a cube

// Tool: create_analytics_cube
{
  "cube_name": "sales",
  "fact_table": "orders",
  "dimensions": ["region", "product_category", "quarter"],
  "measures": ["revenue", "quantity", "discount"]
}

Query cube — revenue by region

// Tool: query_analytics
{
  "cube_name": "sales",
  "dimensions": ["region"],
  "measures": ["revenue"],
  "filters": { "quarter": "Q1-2024" }
}

Drill-down — region + category

// Tool: query_analytics
{
  "cube_name": "sales",
  "dimensions": ["region", "product_category"],
  "measures": ["revenue", "quantity"]
}

Memory & Knowledge

AI agent context

Store a memory (auto-classified)

// Tool: store_memory
{
  "user_input": "What's the weather like in San Francisco today?",
  "llm_response": "It's 72°F and sunny in San Francisco with light winds.",
  "session_id": "sess-user-alice-20240315",
  "metadata": { "intent": "weather_query" }
}

Recall memories for a session

// Tool: recall_memory
{
  "query": "What did Alice ask earlier?",
  "session_id": "sess-user-alice-20240315",
  "max_items": 10
}

Store a knowledge entry

// Tool: store_knowledge
{
  "content": "PolyDB supports 16 data models with a single connection and PostgreSQL-grade ACID for SQL operations.",
  "knowledge_type": "factual",
  "confidence": 0.97,
  "tags": ["polydb", "architecture"]
}

Retrieve high-confidence knowledge

// Tool: search_knowledge
{
  "query": "PolyDB architecture",
  "knowledge_types": ["factual"],
  "min_confidence": 0.9,
  "limit": 20
}

Temporal

Versioned data

Store a versioned entity

// Tool: store_temporal
{
  "entity_id": "config:ui-theme",
  "data": {
    "value": "dark",
    "updated_by": "admin",
    "updated_at": "2024-06-15T09:00:00Z"
  }
}

Query as-of a timestamp (omit or use now for current)

// Tool: query_temporal_at
{
  "entity_id": "config:ui-theme",
  "timestamp": "2024-06-01T12:00:00Z"
}

Full history

// Tool: query_temporal_history
{
  "entity_id": "config:ui-theme",
  "start_time": "2024-01-01T00:00:00Z",
  "end_time": "2024-12-31T23:59:59Z"
}

Full-Text

BM25 search

FTS indices are created implicitly on first write — no separate schema step. Just call index_fulltext to add a document.

Index a document

// Tool: index_fulltext
{
  "index_name": "help_articles",
  "doc_id": "help-001",
  "document": "Getting started with PolyDB Key-Value. The Key-Value provider supports namespaces, TTL expiry, and JSON values. Tags: kv cache tutorial."
}

Search

// Tool: search_fulltext
{
  "index_name": "help_articles",
  "query": "TTL expiry cache",
  "limit": 10
}

Blob

Binary large objects

Store a blob

// Tool: store_blob
{
  "content": "iVBORw0KGgoAAAANSUhEUgAA...",
  "filename": "avatar-user-alice.png",
  "mime_type": "image/png",
  "metadata": {
    "user_id": "alice",
    "width": 256,
    "height": 256,
    "uploaded_at": "2024-03-15T10:00:00Z"
  }
}
// → returns {"blob_id": "blob_a1b2c3d4", ...} — use blob_id for get/delete

Get a blob

// Tool: get_blob
{
  "blob_id": "avatar-user-alice"
}

S3

Object storage

Full bucket lifecycle: create a bucket first, then put, get, and list objects, then clean up. Bucket names are tenant-scoped — no global uniqueness required.

1. Create a bucket

// Tool: create_bucket
{ "bucket": "reports-2024" }
// → {"created": true, "bucket": "reports-2024", "region": "us-east-1"}

2. Put an object

// Tool: put_s3_object
{
  "bucket": "reports-2024",
  "key": "q1/revenue-summary.json",
  "content": "{\"total\": 1240500, \"currency\": \"USD\"}",
  "content_type": "application/json"
}

3. List objects with prefix

// Tool: list_s3_objects
{ "bucket": "reports-2024", "prefix": "q1/" }

4. Get an object

// Tool: get_s3_object
{ "bucket": "reports-2024", "key": "q1/revenue-summary.json" }

5. List all buckets

// Tool: list_buckets
// → {"buckets": [{"name": "reports-2024", "created_at": "..."}], "count": 1}

6. Delete object then bucket

// Tool: delete_s3_object
{ "bucket": "reports-2024", "key": "q1/revenue-summary.json" }
// Tool: delete_bucket  (bucket must be empty first)
{ "bucket": "reports-2024" }
// → {"success": true, "bucket": "reports-2024"}

Iceberg

Apache Iceberg tables

Create a table

// Tool: create_iceberg_table
{
  "table_name": "clickstream",
  "schema": {
    "columns": [
      { "name": "event_id",   "type": "string" },
      { "name": "user_id",    "type": "string" },
      { "name": "page",       "type": "string" },
      { "name": "ts",         "type": "timestamp" },
      { "name": "session_ms", "type": "long" }
    ]
  },
  "partition_by": ["ts"]
}

Insert rows

// Tool: append_iceberg
{
  "table": "clickstream",
  "data_records": [
    { "event_id": "evt-001", "user_id": "alice", "page": "/pricing", "ts": "2024-03-15T10:00:00Z", "session_ms": 1500 },
    { "event_id": "evt-002", "user_id": "alice", "page": "/docs",    "ts": "2024-03-15T10:00:05Z", "session_ms": 1505 }
  ]
}

Time-travel — read a snapshot as-of a timestamp

// Tool: get_iceberg_snapshot_as_of
{
  "table": "clickstream",
  "timestamp": "2024-03-10T00:00:00Z"
}

Coming soon

Cross-model Atomic Transactions

Multi-operation transaction examples are coming soon. The begin_transaction, execute_transactional, commit_transaction, and rollback_transaction tools are under active development. Single-operation SQL transactions via query_sql are GA today.

Advanced Pro / Enterprise

Multi-Provider Workflow — `execute_workflow`

Workflows chain multiple provider calls with $ref to pass outputs between steps. The runner executes them in order; each step can reference any prior step's output using dot-path notation. Available on Pro and Enterprise plans.

Ingest article → embed → store in vector index

// Tool: execute_workflow
{
  "steps": [
    {
      "id": "store_doc",
      "op": "store_document",
      "args": {
        "collection": "articles",
        "document": {
          "title": "PolyDB Multi-Model Architecture",
          "body": "PolyDB unifies 16 data paradigms with one connection...",
          "author": "eng-team",
          "published": "2024-03-15"
        }
      }
    },
    {
      "_comment": "$embed is coming soon — this step is illustrative; not yet executable",
      "id": "embed",
      "op": "$embed",
      "args": {
        "text": "$ref(store_doc.document.body)"
      }
    },
    {
      "id": "store_vector",
      "op": "store_vector",
      "args": {
        "collection": "article_embeddings",
        "vector": "$ref(embed.vector)",
        "vector_id": "$ref(store_doc._id)",
        "metadata": {
          "title": "$ref(store_doc.document.title)",
          "author": "$ref(store_doc.document.author)"
        }
      }
    }
  ]
}

RAG: embed query → search → retrieve documents

// Tool: execute_workflow
{
  "steps": [
    {
      "_comment": "$embed is coming soon — this step is illustrative; not yet executable",
      "id": "embed_query",
      "op": "$embed",
      "args": { "text": "How do I use cross-model transactions?" }
    },
    {
      "id": "vector_search",
      "op": "search_vectors",
      "args": {
        "collection": "article_embeddings",
        "query_vector": "$ref(embed_query.vector)",
        "k": 5
      }
    },
    {
      "id": "fetch_docs",
      "op": "search_documents",
      "args": {
        "collection": "articles",
        "filter": { "_id": { "$in": "$ref(vector_search.ids)" } }
      }
    }
  ]
}

CODEEXAMPLES