@ -39,7 +39,8 @@ You can use the following meta ops in the REPL:
* `%params`: print all set parameters.
* `%params`: print all set parameters.
* `%run <FILE>`: run the script contained in `<FILE>`.
* `%run <FILE>`: run the script contained in `<FILE>`.
* `%import <FILE OR URL>`: import data in JSON format from the file or URL.
* `%import <FILE OR URL>`: import data in JSON format from the file or URL.
* `%save <FILE>`: the result of the next successful query will be saved in JSON format in a file instead of printed on screen. If `<FILE>` is omitted, then the effect of any previous `%save` command is nullified.
* `%save <FILE>`: the result of the next successful query will be saved in JSON format in a file instead of printed on
screen. If `<FILE>` is omitted, then the effect of any previous `%save` command is nullified.
* `%backup <FILE>`: the current database will be backed up into the file.
* `%backup <FILE>`: the current database will be backed up into the file.
* `%restore <FILE>`: restore the data in the backup to the current database. The current database must be empty.
* `%restore <FILE>`: restore the data in the backup to the current database. The current database must be empty.
@ -48,12 +49,14 @@ You can use the following meta ops in the REPL:
Queries are run by sending HTTP POST requests to the server.
Queries are run by sending HTTP POST requests to the server.
By default, the API endpoint is `http://127.0.0.1:9070/text-query`.
By default, the API endpoint is `http://127.0.0.1:9070/text-query`.
A JSON body of the following form is expected:
A JSON body of the following form is expected:
```json
```json
{
{
"script": "<COZOSCRIPTQUERYSTRING>",
"script": "<COZOSCRIPTQUERYSTRING>",
"params": {}
"params": {}
}
}
```
```
params should be an object of named parameters. For example, if params is `{"num": 1}`,
params should be an object of named parameters. For example, if params is `{"num": 1}`,
then `$num` can be used anywhere in your query string where an expression is expected.
then `$num` can be used anywhere in your query string where an expression is expected.
Always use params instead of concatenating strings when you need parametrized queries.
Always use params instead of concatenating strings when you need parametrized queries.
@ -84,27 +87,20 @@ and a nicely-formatted diagnostic will be in `"display"` if available.
* `POST /text-query`, described above.
* `POST /text-query`, described above.
* `GET /export/{relations: String}`, where `relations` is a comma-separated list of relations to export.
* `GET /export/{relations: String}`, where `relations` is a comma-separated list of relations to export.
* `PUT /import`, import data into the database. Data should be in `application/json` MIME type in the body,
* `PUT /import`, import data into the database. Data should be in `application/json` MIME type in the body,
in the same format as returned in the `data` field in the `/export` API.
in the same format as returned in the `data` field in the `/export` API.
* `POST /backup`, backup database, should supply a JSON body of the form `{"path": <PATH>}`
* `POST /backup`, backup database, should supply a JSON body of the form `{"path": <PATH>}`
* `POST /import-from-backup`, import data into the database from a backup. Should supply a JSON body
* `POST /import-from-backup`, import data into the database from a backup. Should supply a JSON body
of the form `{"path": <PATH>, "relations": <ARRAY OF RELATION NAMES>}`.
of the form `{"path": <PATH>, "relations": <ARRAY OF RELATION NAMES>}`.
* `GET /`, if you open this in your browser and open your developer tools, you will be able to use
* `GET /`, if you open this in your browser and open your developer tools, you will be able to use
a very simple client to query this database.
a very simple client to query this database.
> For `import` and `import-from-backup`, triggers are _not_ run for the relations, if any exists.
> For `import` and `import-from-backup`, triggers are _not_ run for the relations, if any exists.
If you need to activate triggers, use queries with parameters.
> If you need to activate triggers, use queries with parameters.
The following are experimental:
The following are experimental:
* `GET(SSE) /changes/{relation: String}` get changes when mutations are made against a relation, relies on [SSE](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events).
* `GET(SSE) /changes/{relation: String}` get changes when mutations are made against a relation, relies
* `GET(SSE) /rules/{name: String}` register a custom fixed rule and receive requests for computation.
on [SSE](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events).
Query parameter `arity` must also be present.
* `POST /rule-result/{id}` post results of custom fixed rule computation back to the server, used together with the last API.
* `POST /transact` start a multi-statement transaction, the ID returned is used in the following two APIs.
Need to set the `write=true` query parameter if mutations are present.
* `POST /transact/{id}` do queries inside a multi-statement transaction, JSON payload expected is the same as for `/text-query`.
* `PUT /transact/{id}` commit or abort a multi-statement transaction. JSON payload is of the form `{"abort": <bool>}`, pass `false` for commit and `true` for abort. If you forget to do this, a resource leak results, even for read-only transactions.