Overview

jQL (Jeli Query Language) is how jDB performs table operations, calls REST APIs registered with a database, and drives its own environment — all through a single method: db.jQl(query, params).

Every command — insert, select, drop, and so on — is a plugin registered with its own schema: a declared set of fields with names, optional types, defaults and flags. The schema is what makes both syntaxes below, and the object form, resolve to exactly the same thing.

Two syntaxes, one schema

jDB detects which syntax a string query uses automatically — nothing to configure, and the two can be mixed freely across calls.

v1  Positional flags

The original syntax: a command name followed by -value tokens. Non-flag fields are matched by position; boolean fields are matched by typing their name as a bare word anywhere in the query.

insert -{"name":"Ada","role":"admin"} -users -ignoreSync -hard

v2  Named flags

A newer --name=value / bare --name syntax. Fields are matched by name instead of position, so flags can appear in any order. jDB only treats -- as a flag boundary outside quotes/braces and immediately before a letter, so JSON data containing a dash ({"score": -5}) is never misread — that exact ambiguity is why v1 requires care with values containing  -.

insert --data={"name":"Ada","role":"admin"} --table=users --ignoreSync --hard

Object form

Skip string parsing entirely by handing jQl a plain object with a command key. This is the most robust option for code generating queries programmatically.

db.jQl({
    command: 'insert',
    table: 'users',
    data: { name: 'Ada', role: 'admin' },
    ignoreSync: true
});

Field types

Each command's fields table below lists a type badge where the command validates that field. A field with no badge accepts anything it's given (its shape legitimately varies — e.g. insert's data is an object for a single record or an array for a bulk insert).

Response shape

On success, most commands resolve with:

{ state: "insert", status: "success", result: { message: "..." }, code: 200 }

On failure, the promise rejects with:

{ message: "...", status: "error", code: 400 }

select resolves with a result set object exposing getResult() and jDBNumRows() instead of a plain message.

create

create -users -[{"id":{"type":"NUMBER","AUTO_INCREMENT":1},"email":{"type":"VARCHAR"}}]

alter v1 only

When action is a (add), the next argument selects what's being added:

alter -users -a -c -fullName -{"type":"VARCHAR","defaultValue":"Foo Bar"}
alter -users -d -fullName
alter -users -r -people

truncate

truncate -users -yes

truncate-db

Truncates every table in the current database.

drop

drop -t -users -yes
drop -d -myapp -yes -true

insert

insert -[{"name":"Foo Bar","email":"foo@bar.com"},{"name":"Bar Foo","email":"bar@foo.com"}] -users

update

update -users -{"role":"admin"} -age>18

updatemany

updatemany -users -[[{"age":18},{"role":"admin"}]]

delete

delete -users -age>18 -true -rollbackOnError

select

Condition operators inside where(...):

select -* -users -where(role~admin) -limit(10) -orderBy(name)

select --fields=* --table=users --where=role~admin --limit=10

Join clause: join(@table(t2) @clause(INNER) @on(t1.column=t2.column)), with INNER, LEFT, RIGHT or OUTER. All referenced tables must already exist.

batch

batch -[{"type":"insert","table":"users","data":{"name":"Ada"}}] -rollbackOnError

import

Opens a file picker. If the table doesn't exist yet, it's created before the data is inserted.

export

export -users -csv -d -users-export

sync

sync -users -true

schema

schema -export -true
schema -add -{"users":{"type":"create","definition":[{"id":{"type":"NUMBER"}}]}}

env

env -usage

help

help
help -insert

api

Calls a REST endpoint registered with the database through the same jQL pipeline as table commands.

api -/set/access/token -{"token":"abc"}

cls

No fields. Signals a command-line/REPL front end (like the playground) to clear its output. Doesn't touch the database.