Skip to main content

ql

@webda/ql — WebdaQL​

A structured query language (WQL) for filtering and paginating Webda Store results. WQL queries are parsed by an ANTLR4 grammar and translated to native backend queries by each Store implementation (in-memory, MongoDB, PostgreSQL, DynamoDB).

When to use it​

You need WQL when you call store.query() or a relation's .query() method. Every Webda Store accepts a WQL string; no raw SQL, MongoDB filter objects, or DynamoDB conditions needed.

// Query the User repository
const { results } = await User.getRepository().query(
  `email = 'alice@example.com' LIMIT 1`
);

// Query a relation
const { results: posts } = await user.posts.query(
  `status = 'published' ORDER BY createdAt DESC LIMIT 10`
);

Install​

npm install @webda/ql

This package is a dependency of @webda/core — you rarely need to install it directly.

Syntax overview​

expression? orderExpression? limitExpression? offsetExpression?

Filter expressions support:

  • Comparison: field = value, field != value, field > value, field >= value, field < value, field <= value
  • Pattern match: field LIKE "pattern" (_ = single char, % = any chars)
  • Set membership: field IN [value, value, ...]
  • Array contains: field CONTAINS value
  • Null checks: field IS NULL, field IS NOT NULL (missing, undefined or null)
  • Logic: AND, OR, ( ... )

Pagination / ordering:

  • ORDER BY field [ASC|DESC], ...
  • LIMIT <integer>
  • OFFSET "<continuationToken>"

Quick examples​

import * as WebdaQL from "@webda/ql";

// Parse and evaluate against an in-memory object
const validator = new WebdaQL.QueryValidator(
  `status = 'published' AND viewCount >= 100`
);
const post = { status: "published", viewCount: 150 };
console.log(validator.eval(post)); // true

// Prepend a mandatory condition to a user-supplied query
const merged = WebdaQL.PrependCondition(
  `status = 'published' ORDER BY title LIMIT 10`,
  `authorId = 'u-123'`
);
// => 'status = "published" AND authorId = "u-123" ORDER BY title ASC LIMIT 10'

Parameters​

Never concatenate user input into a query. Pass values as parameters instead, with ? and an array or :name and an object:

await Task.query("owner = ? AND status IN ?", [user, ["open", "late"]]);
await Task.query("owner = :owner OR reviewer = :owner", { owner: user });

WebdaQL.bind("priority >= ? LIMIT ?", [2, 10]); // priority >= 2 LIMIT 10

Placeholders are only allowed where a value is expected, values are escaped by type, and = ? / != ? with null become IS NULL / IS NOT NULL. Template literals passed straight to a query method are escaped the same way at compile time by webdac. See Parameters.

API reference​

ExportDescription
QueryValidatorParses a WQL string; eval(obj) evaluates it, toString() normalizes it
bind(query, params)Binds ? / :name placeholders to escaped values
escape(parts, values)Escapes template literal values (used by the compile-time rewrite)
validateSyntax(query)Checks a query against the grammar without evaluating it; placeholders allowed
PrependCondition(query, condition)Merges a condition in front of an existing query, preserving ORDER BY / LIMIT / OFFSET
ExpressionBuilderANTLR visitor that builds the optimized expression AST
AndExpressionLogic AND node
OrExpressionLogic OR node
ComparisonExpressionComparison leaf node
QueryParsed query result: { filter, orderBy?, limit?, continuationToken? }
OrderBy{ field: string; direction: "ASC" | "DESC" }

See also​

Classes​

Interfaces​

Type Aliases​

Variables​

Functions​