Querying a CeresDB Instance
CeresDB uses the Antler Query Language (AQL) to interact with the data contained within the database. This language is made up of 9 main actions that can act on 5 different resources:
Collection
Collections act as logical groupings of data with the same schema within a database. They are composed of multiple records.
Note
Details on Schema dictionaries can be found in the Schema Format section
Delete
Deletes a collection from a database
DELETE COLLECTION <name of database>.<name of collection>
Get
Returns the collections contained in a database
GET COLLECTION <name of database>
Post
Creates a new collection
POST COLLECTION <name of database>.<name of collection> <dict of schema>
Put
Update the a collection’s schema
POST COLLECTION <name of database>.<name of collection> <dict of schema>
Database
Databases act as the highest-level grouping of data which can contain multiple collections.
Delete
Deletes a database
DELETE DATABASE <name of database>
Get
Returns the databases contained in the CeresDB instance
GET DATABASE
Post
Creates a new database
POST DATABASE <name of database>
Permit
Permits control access to databases and are made up of records containing usernames within the instance and their roles.
Note
Details on access roles can be found in the Access Roles section
Delete
Deletes a permit
DELETE PERMIT <name of database> <id or list of ids of permit to delete or use '-' to delete ids from piped input>
Get
Returns the permits contained in a CeresDB database
GET PERMIT <name of database> <fields to include in output or use '*' to include all>
Post
Note
To use data piped into the post command, omit the dictionary at the end of the command
Creates a new permit
POST PERMIT <name of database> <dict of permit with format {"username":"<username to add>","role":"<access role to add>"}>
Put
Note
To use data piped into the put command, omit the dictionary at the end of the command
Overwrites a permit with new data
PUT PERMIT <name of database> <id or list of ids to overwrite> <dict or list of dicts of data to update to>
Record
Records are the items of data inserted/retrieved from the collections within a database.
Delete
Deletes a record
DELETE RECORD <name of database>.<name of collection> <id or list of ids of permit to delete or use '-' to delete ids from piped input>
Get
Returns the records within a specific database and collection
GET RECORD <name of database>.<name of collection> <fields to include in output or use '*' to include all>
Post
Note
To use data piped into the post command, omit the dictionary at the end of the command
Creates a new record
POST RECORD <name of database>.<name of collection> <dict or list of dicts of data to insert>
Patch
Note
To use data piped into the patch command, omit the dictionary at the end of the command
Updates a field in multiple records
PATCH RECORD <name of database>.<name of collection> <id or list of ids to update> <dict of fields to update and their new values>
Put
Note
To use data piped into the put command, omit the dictionary at the end of the command
Overwrites a record with new data
PUT RECORD <name of database>.<name of collection> <id or list of ids to overwrite> <dict or list of dicts of data to update to>
User
Users control who can access the database and what their instance-level permissions are.
Note
Details on access roles can be found in the Access Roles section
Delete
Deletes a user
DELETE USER <id or list of ids of permit to delete or use '-' to delete ids from piped input>
Get
Returns the users contained in a CeresDB instance
GET USER <fields to include in output or use '*' to include all>
Post
Note
To use data piped into the post command, omit the dictionary at the end of the command
Creates a new user
POST USER <dict of permit with format {"username":"<username to add>","role":"<access role to add>","password":"<password for the user to authenticate with>"}>
Put
Note
To use data piped into the put command, omit the dictionary at the end of the command
Overwrites a user with new data
PUT USER <id or list of ids to overwrite> <dict or list of dicts of data to update to>
Modifier Actions
While CeresDB uses DELETE, GET, PATCH, POST, and PUT to manipulate
data, the results of these actions can then be piped into others to perform complex
actions. The modifier actions that output can be piped into (in addition to piping the
output into statements which take the - as an argument described above) are:
Count
Returns the number of items returned from the input query in the format
{"count":"<number of items>"}
<Other query> | COUNT
Filter
Note
Filter can only be used on GET queries for records, users, and permits
Allows you to filter out the results of a GET query using logical expressions made
up of <field name> <comparison operator> <value> joined together via logical
operators
<Other query> | FILTER <field name> <comparison operator> <value> <logical operator> ...
JQ
Allows you to process data piped into the command using a JQ string.
<Other query> | JQ '<your JQ string here>'
Note
The JQ string must be wrapped in single quotes
Note
The JQ command can be used to modify data entirely on the server by piping a GET command into a JQ command and then piping that into a PUT command
Note
Do note use the JQ operator to select data (i.e. JQ ‘.[].hello’ on data structured like {“hello”:”…”}) as this will produce an invalid result (all data should be returned as a list of dictionaries, not single type values)
Comparison Operators
>Greater than>=Greater than or equal to=Equal to<Less than<=Less than or equal to!=Not equal to
Logical Operators
ANDAndOROrNOTNotXORExclusive or
Limit
Allows you to reduce the number of results to a specified maximum
<Other query> | LIMIT <maximum desired number of items>
Orderasc
Orders results in ascending order by a specified key
<Other query> | ORDERASC <key to order by>
Orderdsc
Orders results in descending order by a specified key
<Other query> | ORDERDSC <key to order by>