Skip to main content

FairCom database engine: JSON DB API

The JSON DB API manages the FairCom database. It provides actions to manage databases, tables, indexes, and records. It is based on the jsonAction protocol, which sends JSON requests to a server and returns JSON responses.

This section is a topical listing of all actions in the API and defines the JSON payloads that can be sent to the FairCom server over HTTPS or WebSocket using the endpoint /api — such as, https://localhost:8443/api.

Sessions

Services

Databases

Action

Description

"createDatabase"

"createDatabase" creates a database.

"deleteDatabase"

"deleteDatabase" deletes a database unless archived, deleting a database and its containing folder and all its files . It removes all data and metadata in the database.

"listDatabases"

"listDatabses" lists databases the logged-in user is allowed to see.

Tables

Action

Description

"alterTable"

"alterTable" modifies a table.

"createTable"

"createTable" creates a table in a database.

"deleteTables"

"deleteTables" deletes one or more tables in a single transaction.

"describeTables"

"describeTables" returns a complete set of metadata about one or more specified tables.

"listTables"

"listTables" lists tables in the specified database that the logged-in user is allowed to see.

"rebuildTables"

"rebuildTables" rebuilds specified tables.

Indexes

Action

Description

"createIndex"

"createIndex" creates an index on one or more fields in a table.

"deleteIndexes"

"deleteIndexes" deletes an index.

"listIndexes"

"listIndexes" lists indexes in the specified database table that the logged-in user is allowed to see.

"rebuildIndexes"

"rebuildIndexes" rebuilds all indexes or specified indexes.

Modify data

Action

Description

"deleteRecords"

"deleteRecords" deletes one or more records from a database table using one or more IDs.

"insertRecords"

"insertRecords" inserts one or more records into a database table - one record for each item in the "data" array.

"truncateRecords"

"truncateRecords" deletes all records from a database table very quickly by deleting and recreating the data file.

"updateRecords"

"updateRecords" updates one or more records in a database table.

Get data

Action

Description

"closeCursor"

"closeCursor" closes a previously opened cursor.

"getRecordsByIds"

"getRecordsByIds" retrieves one or more records from a database using their IDs. This action is useful for using the database as a simple key-value store.

"getRecordsByIndex"

"getRecordsByIndex" can return a cursor that quickly retrieves records forward and backward in index order. The cursor can efficiently retrieve thousands of records at a time. The cursor can fetch records forward and backward and skip past records.

"getRecordsByPartialKeyRange"

"getRecordsByPartialKeyRange" retrieves records from a database table that match a partial key in the specified index. It is particularly useful for typeahead queries.

"getRecordsByTable"

"getRecordsByTable" retrieves records from a database table in table order. It can return a cursor that quickly and efficiently paginates through records in the table. It can also immediately return all records in a table.

"getRecordsFromCursor"

"getRecordsFromCursor" retrieves records from a cursor returned from another "getRecords..." action. A cursor can efficiently retrieve thousands of records at a time. Most cursors can fetch records forward and backward and skip past records.

"getRecordsInKeyRange"

"getRecordsInKeyRange" retrieves records from a database table within a specified range of keys in an index. It matches index keys against partial or complete key values. The upper or lower bounds of the key range can be specified or omitted. This action is the fastest way to retrieve a bounded set of records in index order.

"getRecordsStartingAtKey"

"getRecordsStartingAtKey" retrieves records from a database table starting with the record that most closely matches the specified key in the specified index. It is the fastest way to walk records in index order starting at a specific key. It is typically used to look up records that are near a key. It can also be used to retrieve a span of records before and after a key value.

"getRecordsUsingSQL"

"getRecordsUsingSQL" uses SQL to retrieve records. It can return a cursor that retrieves records forward and backward in SQL query order. The cursor can efficiently retrieve thousands of records at a time. The cursor can fetch records forward and backward and skip past records.

SQL

Action

Description

"getRecordsUsingSQL"

"getRecordsUsingSQL" uses SQL to retrieve a set of records.

"runSqlStatements"

"runSqlStatements" runs one or more SQL statements, such as drop, create, alter, call, insert, update, and delete statements.

Transactions

Action

Description

"commitTransaction"

This closes a transaction and makes its changes durable and visible to other transactions. You can include the "transactionSavepointId" property to commit changes in the transaction up to the savepoint. "commitTransaction" always closes a transaction. Once a transaction is closed, you can no longer use its "transactionId".

"createTransaction"

This returns a "transactionId" property that you can add to other actions to put them under control of this transaction. Until you run "commitTransaction", changes made inside the transaction are invisible outside the transaction and are not durably persisted; thus, if the server fails before the transaction commits, all actions in the transaction are automatically rolled back.

"createTransactionSavePoint"

This bookmarks the current point in the transaction process. You can create multiple savepoints and use "revertTransactionToSavepoint" to undo changes made after the savepoint.

"listTransactions"

This returns a list of all active transactions that the logged-in account is authorized to see.

"rollbackTransaction"

This closes a transaction and discards all changes made under the control of the transaction. Once a transaction is closed, you can no longer use its "transactionId".

"revertTransactionToSavepoint"

This undoes a transaction's changes back to a savepoint previously created by "createTransactionSavepoint" . It keeps the transaction open so you can continue to do more actions under transaction control.