Data Actions

Data actions read from or write to XINA databases.

Read Actions

SELECT

The primary read action in XINA. It closely mirrors the MySQL SELECT query, and returns data as a table of values. The full syntax for the SELECT object is available here.

Property	Value	Required	Default
action	`"select"`	yes
select	select	yes
rows	`integer`	no	`1000`
use_strings	`boolean`	no	`false`
echo	`boolean`	no	`false`

The server response to a SELECT action will start with a header packet, containing a JSON array of JSON object(s) indicating the name of each column as a string and the XINA data type of each column as a string. This will be followed by packet(s) containing the data, as a JSON array of of JSON array(s) of values.

The optional rows property sets the limit of rows per packet. Note that this does not limit the total number of rows returned, this is set by the limit property of the select object.

If the use_strings property is true, all values will be stored as JSON strings instead of their associated JSON type.

If the echo property is true, the generated SQL query will be included in the header object in the "query" property. This is provided to support query debugging; it does not affect the query itself.

Example

Given a table t with two columns, a (int(4)), and b (utf8text), and three rows:

a	b
`0`	`"x"`
`1`	`"y"`
`2`	`"z"`

The following SELECT action:

{
 "action": "select",
 "select": {
  "from": "t"
 },
 "rows": 2
}

Would return three server packets.

First, the header information:

100

[
 {
  "name": "a",
  "type": "int(4)"
 },
 {
  "name": "b",
  "type": "utf8text"
 }
]

Second, the first two rows (limited to two by the rows property):

100

[
 [ 0, "x" ],
 [ 1, "y" ]
]

Third, the last remaining row (with the status code 200 indicating the end of the data):

200

[
 [ 2, "z" ]
]

FETCH

Under Construction

Reads specific types of data in a more structured format than the SELECT action. Although the syntax and response format differs depending on fetch type, all fetch actions share common base properties.

Property	Value	Required	Default
action	`"fetch"`	yes
fetch	fetch type	yes
count	`boolean`	no	`false`
where	expression	no
order	array of order terms	no
limit	`integer`	no
offset	`integer`	no

Records

Fetches records from a database.

Property	Value	Required	Default
action	`"fetch"`	yes
fetch	`"records"`	yes
database	database specifier	yes
records	records specifier
where	expression
order	array of order terms		default database order
limit	`integer`		100,000 (see below)
offset	`integer`
children	`boolean`		`true`
count	`boolean`		`false`

Fetched records are returned as JSON objects. If both records and where are provided, they will be combined with a boolean AND operation.

The default limit for this operation is 100,000. Unlike the SELECT action which streams data directly from the underlying database, FETCH involves additional server overhead processing and formatting the result, so a limit is enforced to maintain system performance. Exceeding the default limit explicitly is permitted but may cause performance issues depending on server configuration.

Multirecords

Fetches records from several databases at once.

Property	Value	Required	Default
fetch	`"multirecords"`	yes
databases	databases specifier	yes
children	`boolean`	no	`true`

Pseudorecords

Fetches data from an arbirary query formatted as though it represents a set of records.

Property	Value	Required	Default
fetch	`"pseudorecords"`	yes
select	select	yes

Follows

Fetches all follows for a single user. This action currently does not reflect the top level fetch properties, except for count.

Property	Value	Required	Default
fetch	`"follows"`	yes
user	user specifier	no	current user

Keys

Fetches all keys for a single user. This action currently does not reflect the top level fetch properties, except for count.

Property	Value	Required	Default
fetch	`"keys"`	yes
user	user specifier	no	current user

Notifications

Fetches notifications for a single user. This action currently does not utilize the top level fetch property "where".

Property	Value	Required	Default
fetch	`"keys"`	yes
user	user specifier	no	current user
type	notification type	no
seen	`boolean`	no

Posts

Fetches wall posts.

Property	Value	Required	Default
fetch	`"posts"`	yes
wall	wall specifier	no	all walls
following	`boolean`	no	`false`
threads	`boolean`	no	`false`
children	`boolean`	no	`false`
records	`boolean`	no	`false`

Prefs

Subscriptions

Tasks

Threads

Users

DOWNLOAD

Under Construction

Write Actions

INSERT

The INSERT action inserts one or more records into a XINA database.

By default, the action will fail if any records being inserted have duplicate key values already in the database. If a different on_duplicate property is set, duplicate records will be updated according to the rules in the table. Only fields explicitly set in the INSERT will be changed. This is analogous to an INSERT ... ON DUPLICATE KEY UPDATE MySQL query.

Property	Value	Required	Default
action	`"insert"`	yes
database	database specifier	yes
records	records data	yes
on_duplicate	`"fail"` or `"update"`	no	`"fail"`
fail_no_op	`boolean`	no	`false`

Examples

Given a starting database containing key field k, fields f1, f2, and f3, with tags enabled, containing the following two records:

k	f1	f2	f3	tags
a	1	2	3	t1
b	1	2	3	t1

And inserting records:

[
 { "k": "a", "f1": 4, "f2": null, "tags": ["t2"] },
 { "k": "c", "f1": 1, "f2": null, "tags": ["t2"] }
]

on_duplicate: "fail"

Action fails due to duplicate key value "a". No change occurs.

on_duplicate: "update"

Record with key value "a" is updated, and record with key value "c" is inserted. Note that field f3 of "a" is unaffected because no inserted records specified an explicit value for f3.

k	f1	f2	f3	tags
a	4	null	3	t1, t2
b	1	2	3	t1
c	1	null	null	t2

REPLACE

The REPLACE action inserts one or more records into a XINA database and overwrites any existing records with duplicate keys.

Property	Value	Required	Default
action	`"replace"`	yes
database	database specifier	yes
records	records data	yes
on_duplicate	`"update"`, `"delete"`, or `"trash"` (if trash enabled for database)	no	`"update"`
fail_no_op	`boolean`	no	`false`

Examples

Given a starting database containing key field k, fields f1, f2, and f3, with tags enabled, containing the following two records:

k	f1	f2	f3	tags
a	1	2	3	t1
b	1	2	3	t1

And replacing records:

[
 { "k": "a", "f1": 4, "f2": null, "tags": ["t2"] },
 { "k": "c", "f1": 1, "f2": null, "tags": ["t2"] }
]

on_duplicate: "update"

Record with key value "a" is updated, and record with key value "c" is inserted. Note that f3 of "a" is now null and t1 is removed because all fields are overridden by the incoming record.

k	f1	f2	f3	tags
a	4	null	null	t2
b	1	2	3	t1
c	1	null	null	t2

on_duplicate: "trash" or "delete"

Existing record with key value "a" is deleted (or trashed), and new records "a" and "c" are inserted.

k	f1	f2	f3	tags
b	1	2	3	t1
a	4	null	null	t2
c	1	null	null	t2

If "trash" is used, the trash table now contains the original "a" record.

k	f1	f2	f3	tags
a	1	2	3	t1

SET

The SET action sets a database to contain the provided, and only the provided, records. Other records already present in the database are removed (either trashed or deleted, depending on the provided configuration).

Property	Value	Required	Default
action	`"set"`	yes
database	database specifier	yes
records	records data	yes
on_duplicate	`"update"`, `"delete"`, or `"trash"` (if trash enabled for database)	no	`"update"`
on_remove	`"delete"` or `"trash"` (if trash enabled for database)	no	`"trash"` if enabled, `"delete"` otherwise
fail_no_op	`boolean`	no	`false`

Examples

Given a starting database containing key field k, fields f1, f2, and f3, with tags enabled, containing the following two records:

k	f1	f2	f3	tags
a	1	2	3	t1
b	1	2	3	t1

And setting records:

[
 { "k": "a", "f1": 4, "f2": null, "tags": ["t2"] },
 { "k": "c", "f1": 1, "f2": null, "tags": ["t2"] }
]

on_duplicate: "update"

Record "a" is updated, record "c" is inserted, and record "b" is deleted (or trashed, depending on on_remove). Note that f3 of "a" is now null and t1 is removed because all fields are overridden by the incoming record.

k	f1	f2	f3	tags
a	4	null	null	t2
c	1	null	null	t2

on_duplicate: "trash" or "delete"

All existing records are deleted (or trashed, depending on on_remove), and new records "a" and "c" are inserted.

k	f1	f2	f3	tags
a	4	null	null	t2
c	1	null	null	t2

UPDATE

The UPDATE action updates the values of one or more fields and/or attached files of one or more records in a single database.

This documentation applies to XINA 9.2 and above.

Property	Value	Required	Default
action	`"update"`	yes
database	database specifier	yes
records	records specifier	yes
fields	`jsonobject` map of fields to values to update (see below)	no
expressions	`jsonobject` map of fields to expressions to update (see below)	no
file	`string` object ID of file to update (see below)	no
fail_no_op	`boolean`	no	`false`

The fields and expressions properties are JSON objects, where each key is interpretted as a field specifier in the context of the current database. For the fields property, each value is interpretted as a literal JSON value for the type of the specified field. For the expressions property, each value is interpretted as an expression, with the evaluated result of the expression stored with the record. These are provided separately because expressions would otherwise not be distinguishable from JSON object value literals.

The file property may be provided for databases with the file feature enabled. When the file is updated, associated file record attributes (file_size, file_type, etc) will be updated automatically from the new file.

If a single field is referenced more than once across the fields and expressions object, the action will fail, as the result would be ambiguous.

By default, if no records are found matching the records specifier, or no values are provided for fields, expressions, and file, the action will complete successfully without any changes occuring. If fail_no_op is true, the action will fail. Note, however, that fail_no_op will only detect these specific no-op conditions; it is possible that no changes will occur if provided update(s) do not actually change any fields of matched record(s).

DELETE

The DELETE action deletes one or more records from a database.

Note that deleted records and all associated data are permanently deleted and cannot be restored.

This action requires the DELETE database privilege.

Property	Value	Required	Default
action	`"delete"`
database	database
records	records
fail_no_op	`boolean`	no	`false`

TRASH

The TRASH action moves one or more records into the trash table of a database. This is only available in databases with the trash feature enabled, otherwise the action will fail.

This action requires the TRASH database privilege.

Property	Value	Required	Default
action	`"trash"`
database	database
records	records
fail_no_op	`boolean`	no	`false`

RESTORE

The RESTORE action moves one or more records from the trash table of a database into the record table. This is only available in databases with the trash feature enabled, otherwise the action will fail.

If any records being restored have duplicate keys as other records currently in the database the action will fail.

This action requires the TRASH database privilege.

Property	Value	Required	Default
action	`"restore"`
database	database
records	records
fail_no_op	`boolean`	no	`false`

DISPOSE

The DISPOSE action deletes one or more records from the trash table of a database. This is only available in databases with the trash feature enabled, otherwise the action will fail.

Note that disposed records and all associated data are permanently deleted and cannot be restored.

This action requires the DELETE database privilege.

Property	Value	Required	Default
action	`"dispose"`
database	database
records	records
fail_no_op	`boolean`	no	`false`