Query Data

Query your stored videos, images, and other data using a type-safe query builder.

Basic Queries

Query videos and images with the built-in convenience methods:

import { createClient } from "zapdos-js";

const client = createClient({
  apiKey: process.env.ZAPDOS_API_KEY,
});

// Get all videos
const videos = await client.videos().fetch();

// Get all images
const images = await client.images().fetch();

// Get background jobs
const jobs = await client.jobs().fetch();

// Get scenes for a specific video
const scenes = await client.scenes("video-object-id").fetch();

Custom Queries

Build custom queries with the query builder:

// Query with filters
const result = await client
  .from("object_storage")
  .select("id", "metadata", "created_at")
  .where("metadata->>'content_type'", "~", "^video/")
  .where("metadata->>'size'", ">", "1000000")
  .limit(10)
  .fetch();

if (result.data) {
  result.data.forEach((item) => {
    console.log(item.id, item.metadata);
  });
}

Query Builder Methods

Chain methods to build complex queries:

const result = await client
  .from("object_storage")
  .select("id", "metadata", "created_at")
  .where("field", "operator", "value")
  .sort("desc") // or "asc"
  .limit(20)
  .cursor("pagination-cursor") // for pagination
  .fetch();

Available Operators

• = — equals
• != — not equals
• > — greater than
• < — less than
• >= — greater than or equal
• <= — less than or equal
• LIKE — SQL LIKE (case-sensitive)
• ILIKE — SQL ILIKE (case-insensitive)
• ~ — regex match
• !~ — regex not match
• IS — for NULL checks only
• IS NOT — for NOT NULL checks only
• @> — array contains (JSON/array fields)

JSON Queries

Query JSON metadata fields:

// Check content type
.where("metadata->>'content_type'", "=", "video/mp4")

// Check numeric values
.where("metadata->>'size'", ">", "5000000")

// Check arrays (parents)
.where("metadata->'parents'", "@>", '["parent-id"]')

Single Results

Get exactly one result:

const video = await client.videos().limit(1).single();

if (video.data) {
  console.log("Found video:", video.data.id);
} else {
  console.log("No video found");
}

Error Handling

All queries return result objects:

const result = await client.videos().fetch();

if (result.error) {
  console.error("Query failed:", result.error.message);
} else {
  console.log("Found videos:", result.data.length);
}