Capabilities Overview

The capability side of LinkedQL is where its identity shifts from a classic query client to SQL for modern applications.

Language Capabilities

LinkedQL extends the SQL language to bring in useful syntax shorthands for relationships, JSON, and other SQL constructs.

Feature	Summary	Docs
DeepRefs	Follow foreign key relationships directly using simple arrow notation.	DeepRefs
JSON Literals	Model JSON objects and arrays using literal JSON syntax.	JSON
UPSERT	Perform the classic INSERT...ON CONFLICT statement in a single step.	UPSERT

Examples

(a) JSON Literals — Structured Projection

Model JSON objects and arrays using literal JSON syntax.

const result = await client.query(`
  SELECT
  id,
  { first: first_name, last: last_name } AS name,
  { email, phone: phone_number } AS contact
  FROM users
`);

console.log(result.rows[0]);
// { id: 1, name: { first: 'Jane', last: 'Dark' }, contact: { email: 'jane@example.com', phone: null } }

(b) DeepRefs — Relationship Traversal

Follow foreign key relationships directly using simple arrow notation.

const posts = await client.query(`
  SELECT title, author ~> { name, email }
  FROM posts
  WHERE published = true;
`);

console.log(posts.rows[0]);
// { title: 'Syntax Shorthands', author: { name: 'John', email: 'john@example.com' } }

(c) UPSERT — Insert or Update

Perform the classic INSERT...ON CONFLICT statement in a single step.

await client.query(`
  UPSERT INTO users (id, name, email)
  VALUES
    (1, 'Jane', 'jane@example.com'),
    (2, 'James', 'j2@example.com');
`);

Runtime Capabilities

LinkedQL extends the query execution layer with reactivity and automatic schema versioning as first-class database features.

Feature	Summary	Docs
Live Queries	Turn on reactivity over any query and get back a live view of your data.	Live Queries
Timeline Engine	Anchor a query to a fixed schema version for stable results over time.	(Coming soon)

Examples

(a) Live Queries and Live Views

Turn on reactivity over any query and get back a live view of your data.

const result = await client.query(`
  SELECT p.title, u.name
  FROM posts AS p LEFT JOIN users AS u ON p.author = u.id
  WHERE p.published = true
  ORDER BY p.created_at DESC
`, { live: true });

setInterval(() => console.log(result.rows), 1000);
// Updates automatically as post or author data changes

(b) Live Queries + DeepRefs

Combine live results with relational traversal and JSON shaping.

const result = await client.query(`
  SELECT
    { title, category } AS post,
    author ~> { name, email } AS author
  FROM posts WHERE published = true
`, { live: true });

(c) Version Binding — Point-in-Time Queries

Anchor a query to a fixed schema version for stable results over time.

const result = await client.query(`
  SELECT name, email
  FROM users@2_3
  WHERE active = true;
`);

Embedding & Integration Capabilities

LinkedQL bundles an embeddable SQL engine, FlashQL, that brings its full capabilities to the local runtime, the edge, and offline world.

Capability	Summary	Docs
Local Database	Run a full SQL engine in memory — same semantics, zero setup.	FlashQL
Federation	Declare foreign namespaces and non-persistent views directly in SQL.	FlashQL
Sync	Materialize and keep remote-backed views aligned with db.sync.	FlashQL

Examples

(a) Local Database — Runs Anywhere

Run a full SQL engine in memory — same semantics, zero setup.

import { FlashQL } from '@linked-db/linked-ql/flashql';
const client = new FlashQL();

await client.query(`CREATE TABLE users (id SERIAL, name TEXT)`);
await client.query(`INSERT INTO users (name) VALUES ('Alice'), ('Bob')`);

const result = await client.query(`SELECT JSON_AGG(name) AS users FROM users`);
console.log(result.rows);
// [{ users: ['Alice', 'Bob'] }]

(b) Federation — Local + Remote

Query local and remote data together in a single SQL surface.

await db.query(`
  CREATE SCHEMA store
  WITH (replication_origin = 'primary')
`);

await db.query(`
  CREATE VIEW store.orders AS
  SELECT * FROM public.orders
`);

const result = await db.query(`
  SELECT u.name, COUNT(o.id) AS total_orders
  FROM users AS u
  LEFT JOIN store.orders AS o ON o.user_id = u.id
  GROUP BY u.id
  ORDER BY total_orders DESC
`);

(c) Sync — Continuous Alignment

Keep local and remote tables automatically synchronized.

await db.query(`
  CREATE SCHEMA store
  WITH (replication_origin = 'primary')
`);

await db.query(`
  CREATE REALTIME VIEW store.orders AS
  SELECT * FROM public.orders
`);

await db.sync.sync({ store: ['orders'] });