Cost-aware query client for document storage

Turn filesystems, S3 buckets, Git repos, and external APIs into a structured, queryable interface.
GithubDocs →

When to use piq

  • → Agent workflows that generate and query millions of files
  • → Runtime environments where memory and I/O are expensive
  • → When you want explicit control over resolution cost
  • → Projects where you can design query patterns upfront

When not to use piq

  • × You need writes, updates, or transactions
  • × You need joins at the query layer
  • × You are running ad-hoc analytical queries
  • × You don't want to predesign your access patterns

How it works

collection.ts
import { fileMarkdown } from "@piqit/resolvers";

const posts = fileMarkdown({
  base: "content/posts",
  path: "{year}/{slug}.md",
  frontmatter: z.object({
    title: z.string(),
    status: z.enum(["draft", "published"]),
  }),
  body: { html: true },
});
src/query.ts
import { piq } from "piqit";

// Query: scan → filter → select
const results = await piq
  .from(posts)
  .scan({ year: "2024" })
  .filter({ status: "published" })
  .select("params.slug", "frontmatter.title", "body.html")
  .exec();

// Get first post data
const [{ slug, title, html }] = results;