# API Reference # Overview The **XINA API** (or **XAPI**) provides programmatic access to a XINA server. > Note that client applications do not connect directly to the server. The [XINA Tunnel](/books/utilities/page/xina-tunnel) utility performs the actual server connection, authentication, and security, and provides a local server for local client to connect. XAPI is built on the **XINA Protocol** (or **XProtocol**), a TCP format used to communicate with the XINA server. It is designed to be simple and easy to implement across many languages and environments, using standard UTF-8 character encoding and JSON data structures. ## Tokens XProtocol is intended to be parsed in-place as a stream is read. This is achieved with variable length **tokens** of the following format: - prefix length: one byte UTF-8 digit indicating length of the prefix in bytes - prefix: UTF-8 digit(s) indicating the length of the content in bytes - content: UTF-8 encoded string or binary data of (prefix count) bytes For example: - `14cake` = `"cake"` - `213big hamburger` = `"big hamburger"` The maximum allowed length of a single token is 2GB. A token may also be empty, which can be denoted with either the prefix `10` or the shorthand prefix `0`. > Note that the content length is specified in *bytes*, not *characters*. Because UTF-8 is a variable length encoding format, it is recommend to first convert string data to bytes before creating a token for an accurate count. ## Packets Tokens are combined together into **packets**, which form all communication between the client and server. ### Client Packets **Client packets** are sent from the client to server. They use the following format: - packet type :: one byte UTF-8 character - header token :: JSON object containing header information (used primarily for system purposes, typically empty) - content token :: UTF-8 encoded JSON object, binary data, or empty depending on token type Client packets use the following packet types:
Type | Code | Description |
---|---|---|
`ACTION` | `A` | contains an API action (most common packet type) |
`BINARY` | `B` | contains binary data (used for transmitting file data) |
`CLOSE` | `X` | closes the connection |
`CONTINUE` | `C` | prompts continuing a data stream from the server |
`END` | `E` | indicates the end of a series of binary packets |
`INIT` | `I` | initializes the connection |
`KEEPALIVE` | `K` | ignored by both server and client, keeps connection open |
`OBJECT` | `O` | indicates the start of a binary object |
Type | Code | Description |
---|---|---|
`KEEPALIVE` | `K` | ignored by both server and client, keeps connection open |
`SERVER` | `S` | primary server packet type, used for all functions |
Code | Description |
---|---|
`1XX` | Success, more data available |
`2XX` | Success, data ended |
`4XX` | Content error |
`5XX` | Server error |
client | server | |
---|---|---|
`ACTION` | `->` | |
`<-` | `SERVER` |
client | server | |
---|---|---|
`ACTION` | `->` | |
`<-` | `SERVER` `1XX` | |
`CONTINUE` | `->` | |
`<-` | `SERVER` `1XX` | |
`CONTINUE` | `->` | |
`<-` | `SERVER` `2XX` |
client | server | notes | |
---|---|---|---|
`OBJECT` | `->` | initializes the object | |
`BINARY` | `->` | contains binary data | |
`...` | `->` | contains additional binary data as needed | |
`END` | `->` | ends the object | |
`<-` | `SERVER` `2XX` | content contains `object_id` |
Property | Value | Req | Default |
---|---|---|---|
action | `"select"` | ✓ | |
select | [select](select-syntax) | ✓ | |
rows | integer | `10,000` | |
use\_strings | boolean | `false` | |
echo | boolean | `false` |
a | b |
---|---|
`0` | `"x"` |
`1` | `"y"` |
`2` | `"z"` |
Property | Value | Req | Default |
---|---|---|---|
action | `"fetch"` | ✓ | |
fetch | `"records"` | ✓ | |
database | [database specifier](specifier-syntax#bkmrk-database) | ✓ | |
records | [records specifier](specifier-syntax#bkmrk-records) | ||
where | [expression](expression-syntax) | ||
order | array of [order terms](select-syntax#bkmrk-order-term) | default database order | |
limit | integer | 1,000 (see below) | |
offset | integer | ||
children | boolean | `true` | |
count | boolean | `false` |
Property | Value | Req | Default |
---|---|---|---|
action | `"fetch"` | ✓ | |
fetch | `"multirecords"` | ✓ | |
databases | [databases specifier](specifier-syntax#bkmrk-databases) | ✓ | |
where | [expression](expression-syntax) | ||
order | array of [order terms](select-syntax#bkmrk-order-term) | default order of first database | |
limit | integer | 1,000 (see below) | |
offset | integer | ||
children | boolean | `true` | |
count | boolean | `false` |
Property | Value | Req | Default |
---|---|---|---|
action | `"fetch"` | ✓ | |
fetch | `"pseudorecords"` | ✓ | |
select | [select](select-syntax) | ✓ | |
where | [expression](expression-syntax) | ||
order | array of [order terms](select-syntax#bkmrk-order-term) | default order of first database | |
limit | integer | ||
offset | integer | ||
count | boolean | `false` |
Property | Value | Req | Default |
---|---|---|---|
action | `"fetch"` | ✓ | |
fetch | `"follows"` | ✓ | |
user | [user specifier](specifier-syntax#bkmrk-user) | current user | |
count | boolean | `false` |
Property | Value | Req | Default |
---|---|---|---|
action | `"fetch"` | ✓ | |
fetch | `"keys"` | ✓ | |
user | [user specifier](specifier-syntax#bkmrk-user) | current user | |
count | boolean | `false` |
Property | Value | Req | Default |
---|---|---|---|
action | `"fetch"` | ✓ | |
fetch | `"keys"` | ✓ | |
user | [user specifier](specifier-syntax#bkmrk-user) | current user | |
type | notification type | ||
seen | boolean |
Property | Value | Req | Default |
---|---|---|---|
fetch | `"posts"` | ✓ | |
wall | [wall specifier](specifier-syntax#bkmrk-wall) | all walls | |
following | boolean | `false` | |
threads | boolean | `false` | |
post | post ID | ||
children | boolean | `false` | |
records | boolean | `false` |
Property | Value | Req | Default |
---|---|---|---|
action | `"fetch"` | ✓ | |
fetch | `"prefs"` | ✓ | |
user | [user specifier](specifier-syntax#bkmrk-user) | current user |
Property | Value | Req | Default |
---|---|---|---|
action | `"fetch"` | ✓ | |
fetch | `"pref_defs"` | ✓ |
Property | Value | Req | Default |
---|---|---|---|
action | `"fetch"` | ✓ | |
fetch | `"user_subscriptions"` | ✓ | |
user | [user specifier](specifier-syntax#bkmrk-user) | current user |
Property | Value | Req | Default |
---|---|---|---|
action | `"fetch"` | ✓ | |
fetch | `"tasks"` | ✓ | |
from | task ID | ||
user | [user specifier](specifier-syntax#bkmrk-user) | ||
text | string | ||
where | [expression](expression-syntax) | ||
order | array of [order terms](select-syntax#bkmrk-order-term) | recent first | |
limit | integer | 1,000 (see below) | |
offset | integer | ||
count | boolean | `false` |
Property | Value | Req | Default |
---|---|---|---|
action | `"fetch"` | ✓ | |
fetch | `"user_subscriptions"` | ✓ | |
team | [team specifier](specifier-syntax#bkmrk-team) | ✓ |
Property | Value | Required | Default |
---|---|---|---|
action | `"fetch"` | ✓ | |
fetch | `"threads"` | ✓ |
Property | Value | Req | Default |
---|---|---|---|
action | `"fetch"` | ✓ | |
fetch | `"users"` | ✓ | |
users | [users specifier](specifier-syntax#bkmrk-users) | all users | |
order | array of [order terms](select-syntax#bkmrk-order-term) | recent first | |
limit | integer | 1,000 (see below) | |
offset | integer |
Property | Value | Req | Default |
---|---|---|---|
action | `"download"` | ✓ | |
download | `"record"` | ✓ | |
database | [database specifier](specifier-syntax#bkmrk-database) | ✓ | |
record | [record specifier](select-syntax#bkmrk-record) | ✓ | |
version | integer | most recent |
Property | Value | Required | Default |
---|---|---|---|
action | `"download"` | ✓ | |
download | `"post"` | ✓ | |
post | post ID | ✓ |
Property | Value | Req | Default |
---|---|---|---|
action | `"insert"` | ✓ | |
database | [database specifier](specifier-syntax#bkmrk-database) | ✓ | |
records | [records data](data-syntax#bkmrk-records) | ✓ | |
on\_duplicate | `"fail"` or `"update"` | `"fail"` | |
fail\_no\_op | `boolean` | `false` |
k | f1 | f2 | f3 | tags |
---|---|---|---|---|
a | 1 | 2 | 3 | t1 |
b | 1 | 2 | 3 | t1 |
k | f1 | f2 | f3 | tags |
---|---|---|---|---|
a | **4** | **null** | 3 | t1, **t2** |
b | 1 | 2 | 3 | t1 |
**c** | **1** | **null** | **null** | **t2** |
Property | Value | Req | Default |
---|---|---|---|
action | `"replace"` | ✓ | |
database | [database specifier](specifier-syntax#bkmrk-database) | ✓ | |
records | [records data](data-syntax#bkmrk-records) | ✓ | |
on\_duplicate | `"update"`, `"delete"`, or `"trash"` (if trash enabled for database) | `"update"` | |
fail\_no\_op | `boolean` | `false` |
k | f1 | f2 | f3 | tags |
---|---|---|---|---|
a | 1 | 2 | 3 | t1 |
b | 1 | 2 | 3 | t1 |
k | f1 | f2 | f3 | tags |
---|---|---|---|---|
a | **4** | **null** | **null** | **t2** |
b | 1 | 2 | 3 | t1 |
**c** | **1** | **null** | **null** | **t2** |
k | f1 | f2 | f3 | tags |
---|---|---|---|---|
b | 1 | 2 | 3 | t1 |
**a** | **4** | **null** | **null** | **t2** |
**c** | **1** | **null** | **null** | **t2** |
k | f1 | f2 | f3 | tags |
---|---|---|---|---|
**a** | **1** | **2** | **3** | **t1** |
Property | Value | Req | Default |
---|---|---|---|
action | `"set"` | ✓ | |
database | [database specifier](specifier-syntax#bkmrk-database) | ✓ | |
records | [records data](data-syntax#bkmrk-records) | ✓ | |
on\_duplicate | `"update"`, `"delete"`, or `"trash"` (if trash enabled for database) | `"update"` | |
on\_remove | `"delete"` or `"trash"` (if trash enabled for database) | `"trash"` if enabled, `"delete"` otherwise | |
fail\_no\_op | boolean | `false` |
k | f1 | f2 | f3 | tags |
---|---|---|---|---|
a | 1 | 2 | 3 | t1 |
b | 1 | 2 | 3 | t1 |
k | f1 | f2 | f3 | tags |
---|---|---|---|---|
a | **4** | **null** | **null** | **t2** |
**c** | **1** | **null** | **null** | **t2** |
k | f1 | f2 | f3 | tags |
---|---|---|---|---|
**a** | **4** | **null** | **null** | **t2** |
**c** | **1** | **null** | **null** | **t2** |
Property | Value | Req | Default |
---|---|---|---|
action | `"update"` | ✓ | |
database | [database specifier](specifier-syntax#bkmrk-database) | ✓ | |
records | [records specifier](api-syntax-data.md#records) | ✓ | |
fields | `jsonobject` map of fields to values to update (see below) | ||
expressions | `jsonobject` map of fields to expressions to update (see below) | ||
file | string object ID of file to update (see below) | ||
fail\_no\_op | boolean | `false` |
Property | Value | Req | Default |
---|---|---|---|
action | `"delete"` | ✓ | |
database | [database](specifier-syntax#bkmrk-database) | ✓ | |
records | [records](specifier-syntax#records) | ✓ | |
fail\_no\_op | boolean | `false` |
Property | Value | Req | Default |
---|---|---|---|
action | `"trash"` | ✓ | |
database | [database](specifier-syntax#bkmrk-database) | ✓ | |
records | [records](specifier-syntax#records) | ✓ | |
fail\_no\_op | boolean | `false` |
Property | Value | Req | Default |
---|---|---|---|
action | `"restore"` | ✓ | |
database | [database](specifier-syntax#bkmrk-database) | ✓ | |
records | [records](specifier-syntax#records) | ✓ | |
fail\_no\_op | boolean | `false` |
Property | Value | Req | Default |
---|---|---|---|
action | `"dispose"` | ✓ | |
database | [database](specifier-syntax#bkmrk-database) | ✓ | |
records | [records](specifier-syntax#records) | ✓ | |
fail\_no\_op | boolean | `false` |
Property | Value | Required | Default |
---|---|---|---|
action | `"schema"` | yes |
Property | Value | Required | Default |
---|---|---|---|
action | `"create"` | yes | |
create | `"group"` | yes | |
group | [group definition](schema-syntax#bkmrk-group) | yes | |
parent | [group specifier](specifier-syntax#bkmrk-group) | no | |
teams | group teams association (see below) | no |
Property | Value | Required | Default |
---|---|---|---|
action | `"create"` | yes | |
create | `"database"` | yes | |
database | [database definition](schema-syntax#bkmrk-database) | yes | |
parent | [group specifier](specifier-syntax#bkmrk-group) | yes | |
teams | database teams association (see below) | no |
Property | Value | Required | Default |
---|---|---|---|
action | `"create"` | yes | |
create | `"team"` | yes | |
team | [team definition](schema-syntax#bkmrk-team) | yes |
Property | Value | Required | Default |
---|---|---|---|
action | `"create"` | yes | |
create | `"user"` | yes | |
user | [user definition](schema-syntax#bkmrk-user) | yes |
Property | Value | Required | Default |
---|---|---|---|
action | `"alter"` | yes | |
alter | `"group"` | yes | |
op | `"set"` | yes | |
group | [group specifier](specifier-syntax#bkmrk-group) | yes | |
set | JSON object map of parameter(s) to value(s) | yes |
Property | Value | Required | Default |
---|---|---|---|
action | `"alter"` | yes | |
alter | `"group"` | yes | |
op | `"objects"` | yes | |
group | [group specifier](specifier-syntax#bkmrk-group) | yes | |
objects | JSON object map of key(s) to object value(s) | yes |
Property | Value | Required | Default |
---|---|---|---|
action | `"alter"` | yes | |
alter | `"group"` | yes | |
op | `"files"` | yes | |
group | [group specifier](specifier-syntax#bkmrk-group) | yes | |
files | JSON object map of key(s) to object ID(s) | yes |
Property | Value | Required | Default |
---|---|---|---|
action | `"alter"` | yes | |
alter | `"database"` | yes | |
op | `"set"` | yes | |
database | [database specifier](specifier-syntax#bkmrk-database) | yes | |
set | JSON object map of parameter(s) to value(s) | yes |
Property | Value | Required | Default |
---|---|---|---|
action | `"alter"` | yes | |
alter | `"database"` | yes | |
op | `"objects"` | yes | |
database | [database specifier](specifier-syntax#bkmrk-database) | yes | |
objects | JSON object map of key(s) to object value(s) | yes |
Property | Value | Required | Default |
---|---|---|---|
action | `"alter"` | yes | |
alter | `"database"` | yes | |
op | `"files"` | yes | |
database | [database specifier](specifier-syntax#bkmrk-database) | yes | |
files | JSON object map of key(s) to object ID(s) | yes |
Property | Value | Required | Default |
---|---|---|---|
action | `"alter"` | yes | |
alter | `"database"` | yes | |
op | `"add_fields"` | yes | |
database | [database specifier](specifier-syntax#bkmrk-database) | yes | |
fields | JSON array of [field definitions](schema-syntax#bkmrk-field) | yes | |
first | `boolean` | no | `false` |
after | [field specifier](specifier-syntax#bkmrk-field) | no |
Property | Value | Required | Default |
---|---|---|---|
action | `"alter"` | yes | |
alter | `"database"` | yes | |
op | `"drop_fields"` | yes | |
database | [database specifier](specifier-syntax#bkmrk-database) | yes | |
fields | [fields specifier](specifier-syntax#bkmrk-fields) | yes |
Property | Value | Required | Default |
---|---|---|---|
action | `"alter"` | yes | |
alter | `"database"` | yes | |
op | `"order_fields"` | yes | |
database | [database specifier](specifier-syntax#bkmrk-database) | yes | |
fields | JSON array of [field specifiers](specifier-syntax#bkmrk-field) | yes | |
after | [field specifier](specifier-syntax#bkmrk-field) | no |
Property | Value | Required | Default |
---|---|---|---|
action | `"alter"` | yes | |
alter | `"database"` | yes | |
op | `"reset_partitions"` | yes | |
database | [database specifier](specifier-syntax#bkmrk-database) | yes | |
partitions | [partitions specifier](specifier-syntax#bkmrk-partitions) | yes |
Property | Value | Required | Default |
---|---|---|---|
action | `"alter"` | yes | |
alter | `"field"` | yes | |
op | `"set"` | yes | |
database | [database specifier](specifier-syntax#bkmrk-database) | yes | |
field | [field specifier](specifier-syntax#bkmrk-field) | yes | |
set | JSON object map of parameter(s) to value(s) | yes |
Property | Value | Required | Default |
---|---|---|---|
action | `"alter"` | yes | |
alter | `"field"` | yes | |
op | `"objects"` | yes | |
database | [database specifier](specifier-syntax#bkmrk-database) | yes | |
field | [field specifier](specifier-syntax#bkmrk-field) | yes | |
objects | JSON object map of key(s) to object value(s) | yes |
Property | Value | Required | Default |
---|---|---|---|
action | `"alter"` | yes | |
alter | `"field"` | yes | |
op | `"files"` | yes | |
database | [database specifier](specifier-syntax#bkmrk-database) | yes | |
field | [field specifier](specifier-syntax#bkmrk-field) | yes | |
files | JSON object map of key(s) to object ID(s) | yes |
Property | Value | Required | Default |
---|---|---|---|
action | `"alter"` | yes | |
alter | `"user"` | yes | |
op | `"set"` | yes | |
user | [user specifier](specifier-syntax#bkmrk-user) | yes | |
set | JSON object map of parameter(s) to value(s) | yes |
Property | Value | Required | Default |
---|---|---|---|
action | `"alter"` | yes | |
alter | `"user"` | yes | |
op | `"objects"` | yes | |
user | [user specifier](specifier-syntax#bkmrk-user) | yes | |
objects | JSON object map of key(s) to object value(s) | yes |
Property | Value | Required | Default |
---|---|---|---|
action | `"alter"` | yes | |
alter | `"user"` | yes | |
op | `"files"` | yes | |
user | [user specifier](specifier-syntax#bkmrk-user) | yes | |
files | JSON object map of key(s) to object ID(s) | yes |
Property | Value | Required | Default |
---|---|---|---|
action | `"drop"` | yes | |
drop | `"group"` | yes | |
group | [group specifier](specifier-syntax#bkmrk-group) | yes | |
children | `boolean` | no | `false` |
Property | Value | Required | Default |
---|---|---|---|
action | `"drop"` | yes | |
drop | `"database"` | yes | |
database | [database specifier](specifier-syntax#bkmrk-database) | yes | |
children | `boolean` | no | `false` |
Property | Value | Required | Default |
---|---|---|---|
action | `"drop"` | yes | |
drop | `"team"` | yes | |
team | [team specifier](specifier-syntax#bkmrk-team) | yes |
Property | Value | Required | Default |
---|---|---|---|
action | `"drop"` | yes | |
drop | `"user"` | yes | |
user | [user specifier](specifier-syntax#bkmrk-user) | yes |
Property | Value | Req | Default |
---|---|---|---|
action | `"struct_buffer_import"` | ✓ | |
model | model group specifier | ✓ | |
origin | origin name | ✓ | |
object\_id | object ID of data file | ✓ | |
format | `string` | ✓ | |
conf | `jsonobject` | ||
strict\_units | `boolean` | `false` |
Property | Value |
---|---|
`action` | `"struct_mn_edit"` |
`database` | mnemonic definition database specifier |
`mn` | mnemonic ID |
`aliases` | `string[]`, name/unit pair alias(es) for mnemonic |
Property | Value | Required |
---|---|---|
`action` | `"struct_mn_edit"` | ✓ |
`database` | mnemonic definition database specifier | ✓ |
`mn` | mnemonic ID | ✓ |
`name` | `string`, new name/unit pair for mnemonic | |
`state` | `string` |
Property | Value | Req | Default |
---|---|---|---|
action | `"struct_create"` | ✓ | |
create | `"project"` | ✓ | |
parent | [group specifier](specifier-syntax#bkmrk-group) | ||
name | `string` | ✓ | |
label | `string` | name | |
desc | `string` | label |
Property | Value | Req | Default |
---|---|---|---|
action | `"struct_create"` | ✓ | |
create | `"category"` | ✓ | |
parent | [group specifier](specifier-syntax#bkmrk-group) | ✓ | |
name | `string` | ✓ | |
label | `string` | name | |
desc | `string` | label |
Property | Value | Req | Default |
---|---|---|---|
action | `"struct_create"` | ✓ | |
create | `"model"` | ✓ | |
parent | [group specifier](specifier-syntax#bkmrk-group) | ✓ | |
name | `string` | ✓ | |
label | `string` | name | |
desc | `string` | label | |
event | `boolean` | `false` | |
eventf | `boolean` | `false` | |
eventfs | `boolean` | `false` | |
group\_teams | team group privilege map | ||
database\_teams | team database privilege map |
Property | Value | Required | Default |
---|---|---|---|
action | `"struct_create"` | ✓ | |
create | `"origin"` | ✓ | |
model | [group specifier](specifier-syntax#bkmrk-group) | ✓ | |
name | `string` | ✓ | |
label | `string` | name | |
desc | `string` | label | |
event | `boolean` | `false` | |
eventf | `boolean` | `false` | |
eventfs | `boolean` | `false` | |
group\_teams | team group privilege map | ||
database\_teams | team database privilege map | ||
partition | `boolean` or `{"from": | `false` |
Property | Value | Req | Default |
---|---|---|---|
action | `"struct_create"` | ✓ | |
create | `"def"` | ✓ | |
parent | [group specifier](specifier-syntax#bkmrk-group) | ✓ |
Property | Value | Req | Default |
---|---|---|---|
action | `"struct_create"` | ✓ | |
create | `"event"` | ✓ | |
group | [group specifier](specifier-syntax#bkmrk-group) | ✓ | |
type | `"none"`, `"file"`, or `"files"` | `"none"` | |
name | string | `"event"`, `"eventf"`, or `"eventfs"` | |
label | string | name | |
desc | string | label | |
singular | string | `"event"` | |
plural | string | singular`s` | |
conf | JSON object | ||
fields | array of [field definitions](schema-syntax#bkmrk-field) | ||
teams | team database privilege map |
Property | Value | Req | Default |
---|---|---|---|
action | `"struct_create"` | ✓ | |
create | `"notebook"` | ✓ | |
parent | [group specifier](specifier-syntax#bkmrk-group) | ✓ | |
name | string | ✓ | |
label | string | name | |
desc | string | label | |
fields | array of [field definitions](schema-syntax#bkmrk-field) | ||
teams | team database privilege map |
Property | Value |
---|---|
`type` | `"all"` |
Property | Value |
---|---|
`type` | `"where"` |
`where` | [expression](api-syntax-ex.md) |
Property | Value |
---|---|
`type` | `"group"` |
`group` | [group specifier](#group) |
Property | Value |
---|---|
`type` | `"database"` |
`database` | [database specifier](#database) |
Property | Value |
---|---|
`type` | `"record"` |
`database` | [database specifier](#database) |
`record` | [record specifier](#record) |
Property | Value |
---|---|
`type` | `"user"` |
`user` | [user specifier](#user) |
Property | Value |
---|---|
field name / label | |
`"file"` |
Property | Value |
---|---|
`type` | `"null"` |
Property | Value |
---|---|
`type` | `"number"` |
`value` | `number` or `string` |
Property | Value |
---|---|
`type` | `"string"` |
`value` | `string` |
Property | Value |
---|---|
`type` | `"datetime"` or `"dt"` |
`value` | `integer` or `string` |
Property | Value |
---|---|
`$dt` | `integer` or `string` |
Property | Value |
---|---|
`type` | `"localdatetime"` or `"ldt"` |
`value` | `string` |
Property | Value |
---|---|
`$ldt` | `string` |
Property | Value |
---|---|
`type` | `"localdate"` or `"ld"` |
`value` | `string` |
Property | Value |
---|---|
`$ld` | `string` |
Property | Value |
---|---|
`type` | `"localtime"` or `"lt"` |
`value` | `string` |
Property | Value |
---|---|
`$lt` | `string` |
Property | Value |
---|---|
`$col` | `string` column |
Property | Value |
---|---|
`type` | `"column"` |
`table` | `string` |
`column` | `string` |
Property | Value |
---|---|
`type` | `"column"` |
`database` | [database specifier](api-syntax-spec.md#database) |
`table` | `string` table name |
`column` | `string` parameter name |
Property | Value |
---|---|
`type` | `"column"` |
`database` | [database specifier](api-syntax-spec.md#database) |
`table` | `string` table name |
`column` | `string` attribute name |
Property | Value |
---|---|
`type` | `"column"` |
`database` | [database specifier](api-syntax-spec.md#database) |
`table` | `string` table name |
`column` | [field specifier](api-syntax-spec.md#field) |
Property | Value |
---|---|
`type` | `"alias"` |
`value` | `string` |
Property | Value |
---|---|
`$alias` | `string` |
Property | Value |
---|---|
`type` | `"between"` |
`e` | [expression](api-syntax-ex.md) |
`min` | [expression](api-syntax-ex.md) |
`max` | [expression](api-syntax-ex.md) |
Property | Value |
---|---|
`$between` | array of three [expressions](api-syntax-ex.md) |
Property | Value |
---|---|
`type` | `"binary"` |
`op` | `string` |
`e1` | [expression](api-syntax-ex.md) |
`e2` | [expression](api-syntax-ex.md) |
Operator | Description |
---|---|
`and` | logical AND |
`or` | logical OR |
`=` | equal |
`!=` | not equal |
`>` | greater |
`>=` | greater or equal |
`<` | less |
`<=` | less or equal |
`is` | test against `NULL` |
`like` | simple pattern matching, see [here](https://dev.mysql.com/doc/refman/8.0/en/string-comparison-functions.html#operator_like) |
`regexp` | advanced pattern matching, see [here](https://dev.mysql.com/doc/refman/8.0/en/regexp.html) |
`+` | addition |
`-` | subtraction |
`*` | multiplication |
`/` | division |
`%` | modulus |
`&` | bit-wise AND |
`⏐` | bit-wise OR |
`<<` | left shift |
`>>` | right shift |
Property | Value |
---|---|
`type` | `"case"` |
`base` | [expression](api-syntax-ex.md) (optional) |
`cases` | `array` of [case options](#case-option) |
`else` | [expression](api-syntax-ex.md) (optional) |
Property | Value |
---|---|
`when` | [expression](api-syntax-ex.md) |
`then` | [expression](api-syntax-ex.md) |
Property | Value |
---|---|
`type` | `"collate"` |
`e` | [expression](api-syntax-ex.md) |
`collation` | `string` |
Property | Value |
---|---|
`type` | `"count_rows"` |
Property | Value |
---|---|
`type` | `"exists"` |
`select` | [select](api-syntax-sel.md) |
Property | Value |
---|---|
`$exists` | [select](api-syntax-sel.md) |
Property | Value |
---|---|
`type` | `"function"` |
`function` | `string` |
`args` | array of [expressions](api-syntax-ex.md) |
Name | Args | Aggregate | Description |
---|---|---|---|
`AVG` | 1 | yes | arithmetic average |
`AVG_DISTINCT` | 1 | yes | arithmetic average of distinct values of argument |
`BIT_AND` | 1 | yes | bit-wise AND |
`BIT_OR` | 1 | yes | bit-wise OR |
`BIT_XOR` | 1 | yes | bit-wise XOR |
`CEIL` | 1 | yes | returns the smallest integer value not less than the argument |
`COUNT` | 1 | yes | returns the number of rows in the which the argument is not `NULL` |
`COUNT_DISTINCT` | `n` | yes | returns the number of distinct value(s) of the arguments |
`FLOOR` | 1 | yes | returns the largest integer value not greater than the argument |
`MAX` | 1 | yes | returns the maximum value of the argument |
`MIN` | 1 | yes | returns the minimum value of the argument |
`POW` | 2 | no | |
`STDDEV_POP` | 1 | yes | returns the population standard deviation of the argument |
`STDDEV_SAMP` | 1 | yes | returns the sample standard deviation of the argument |
`SUM` | 1 | yes | returns the sum of the argument |
`SUM_DISTINCT` | 1 | yes | returns the sum of the distinct values of the argument |
`TRUNCATE` | 2 | no | |
`VAR_POP` | 1 | yes | returns the population variance of the argument |
`VAR_SAMP` | 1 | yes | returns the sample variance of the argument |
Property | Value |
---|---|
`type` | `"in"` |
`e` | [expression](api-syntax-ex.md) |
`values` | array of [expressions](api-syntax-ex.md) |
Property | Value |
---|---|
`$in` | array of one [expression](api-syntax-ex.md), then either an array of expressions or a [select](api-syntax-sel.md) |
Property | Value |
---|---|
`type` | `"in_select"` |
`e` | [expression](api-syntax-ex.md) |
`select` | [select](api-syntax-sel.md) |
Property | Value |
---|---|
`type` | `"select"` |
`select` | [select](api-syntax-sel.md) |
Property | Value |
---|---|
`$select` | [select](api-syntax-sel.md) |
Property | Value |
---|---|
`type` | `"unary"` |
`op` | `string` |
`e` | [expression](api-syntax-ex.md) |
Operator | Description |
---|---|
`not` | logical NOT |
`-` | negate |
`~` | bit invert |
Property | Value |
---|---|
`$` `op` | [expression](api-syntax-ex.md) |
Property | Value | Notes |
---|---|---|
distinct | `boolean`, default `false` | If `true`, only returns unique values |
columns | [result columns](#bkmrk-result-columns) | If empty, returns all columns available from source |
from | [source](#bkmrk-source) | Source being selected from |
where | [expression](expression-syntax) | Condition for rows, where expression returns `true` |
group | `array` of [expressions](expression-syntax) | Used to group rows for aggregation functions |
having | [expression](api-syntax-ex.md) | Like `where`, but can filter aggregation results |
order | `array` of [order terms](#order-term) | Used to sort the results |
limit | [expression](api-syntax-ex.md) | Limit the number of rows returned |
offset | [expression](api-syntax-ex.md) | Offset of the start of the rows |
Property | Value |
---|---|
`type` | `"all"` |
Property | Value |
---|---|
`e` | [expression](api-syntax-ex.md) |
`alias` | `string` (optional) |
Property | Value |
---|---|
`type` | `"table"` |
`table` | `string` table |
`alias` | `string` (optional) |
Property | Value |
---|---|
`type` | `"table_system"` or `"ts"` |
`table` | `string` table name |
`alias` | `string` (optional) |
Property | Value |
---|---|
`type` | `"table_database"` or `"td"` |
`database` | [database specifier](api-syntax-spec.md#database) |
`table` | `string` table name |
`alias` | `string` (optional) |
Property | Value |
---|---|
`type` | `"join"` |
`op` | `"join"`, `"left"`, `"left_outer"`, `"inner"`, or `"cross"` |
`s1` | left join [source](#source) |
`s2` | right join [source](#source) |
Property | Value |
---|---|
`type` | `"select"` |
`select` | [select](api-syntax-sel.md) |
Property | Value |
---|---|
`e` | [expression](api-syntax-ex.md) |
`order` | `"asc"` or `"desc"` (optional, default `"asc"` |
Property | Value |
---|---|
`name` | `string` |
`desc` | `string` |
Property | Value |
---|---|
`name` | `string` |
`label` | `string` (optional) |
`format` | `string` (optional) |
`path` | `string` (optional) |
`desc` | `string` (optional) |
`dynamic` | `boolean` (optional, default `false`) |
`event` | `boolean` (optional, default `false`) |
`file` | `boolean` (optional, default `false`) |
`link` | `boolean` (optional, default `false`) |
`lock` | `boolean` (optional, default `false`) |
`log` | `boolean` (optional, default `false`) |
`notify` | `boolean` (optional, default `false`) |
`subscribe` | `boolean` (optional, default `false`) |
`tag` | `boolean` (optional, default `false`) |
`track` | `boolean` (optional, default `false`) |
`trash` | `boolean` (optional, default `false`) |
`wall` | `boolean` (optional, default `false`) |
`objects` | `object` (optional) |
`files` | `object` (optional) |
`fields` | `array` of [fields](#field) |
`blobs` | `array` of [blobs](#blob) (optional) |
`indexes` | `array` of `string` values (optional) |
`databases` | `array` of [databases](#database) (optional) |