"insertRecords"
insertRecords inserts one or more records into a table.
The "insertRecords"
action inserts one or more records into a table.
Request examples
Insert into test1
table using objects request example
{ "requestId": "1", "authToken": "replaceWithValidAuthtoken", "api": "db", "action": "insertRecords", "params": { "databaseName": "ctreeSQL", "ownerName": "admin", "tableName": "test1", "dataFormat": "objects", "sourceData": [ { "name": "test name 1" }, { "name": "test name 2" } ] } }
{ "requestId": "2", "authToken": "replaceWithValidAuthtoken", "api": "db", "action": "insertRecords", "params": { "tableName": "test1", "dataFormat": "arrays", "fieldNames": [ "name" ], "sourceData": [ [ "test name 3" ], [ "test name 4" ] ] } }
{ "api": "db", "apiVersion": "1.0", "requestId": "3", "authToken": "replaceWithValidAuthtoken", "action": "insertRecords", "params": { "databaseName": "ctreeSQL", "tableName": "athlete", "dataFormat": "objects", "sourceData": [ { "name": "Michael Jordan", "ranking": 1, "birthDate": "19630217", "playerNumber": 23, "livedPast2000": true, "earnings": 1700000000, "favoriteSaying": "There is no 'i' in team but there is in win." }, { "name": "Babe Ruth", "ranking": 2, "birthDate": "18950206", "playerNumber": 3, "livedPast2000": false, "earnings": 800000, "favoriteSaying": "Every strike brings me closer to the next home run." }, { "name": "Muhammad Ali", "ranking": 3, "birthDate": "19420117", "playerNumber": 1, "livedPast2000": true, "earnings": 60000000, "favoriteSaying": "Float like a butterfly, sting like a bee." }, { "name": "Pele", "ranking": 4, "birthDate": "19401023", "playerNumber": 10, "livedPast2000": true, "earnings": 115000000, "favoriteSaying": "Everything is practice." }, { "name": "Wayne Gretzky", "ranking": 5, "birthDate": "19610126", "playerNumber": 99, "livedPast2000": true, "earnings": 1720000, "favoriteSaying": "You miss 100 percent of the shots you never take." }, { "name": "Michael Schumacher", "ranking": 6, "birthDate": "19690103", "playerNumber": 1, "livedPast2000": true, "earnings": 990000000, "favoriteSaying": "Once something is a passion, the motivation is there." } ] } }
{ "requestId": "4", "authToken": "replaceWithValidAuthtoken", "api": "db", "action": "insertRecords", "params": { "databaseName": "ctreeSQL", "ownerName": "admin", "tableName": "all_types", "dataFormat": "objects", "binaryFormat": "hex", "sourceData": [ { "nested_json_object_or_array": { "hello": "world" }, "boolean_byte": true, "signed_int8": -128, "signed_int16": -32768, "signed_int32": -2147483648, "signed_int64": -9223372036854776000, "iee_base2float32": -0.000001, "iee_base2float64": "-9223372036800000000.0", "signed32digits_base10_left32right0": "-12345678901234567890123456789012", "signed32digits_base10_left0right32": "-0.12345678901234567890123456789012", "signed32digits_base10_left20right12": "-12345678901234567890.123456789012", "signed32digits_base10_left30right2": "-123456789012345678901234567890.12", "signed32digits_base10_left28right4": "-1234567890123456789012345678.9012", "date_yyyymmdd": "2023-04-18", "time_hhmmssfff": "15:43:59.013", "datetime_yyyymmddthhmmssfff": "2023-04-18T15:43:59.013", "fixed_string_10bytes": "_ 3456 _", "variable_string_up_to_max65500bytes": "Variable-length string up to 65,500 bytes.", "variable_string_up_to_2GB": "Variable-length string up to 2GB in length.", "fixed_binary_10bytes": "FF00FF", "variable_binary_up_to_max65500bytes": "FF00FF", "variable_binary_up_to_2GB": "FF00FF" } ] }, "responseOptions": { "binaryFormat": "hex", "dataFormat": "objects", "numberFormat": "string" }, "apiVersion": "1.0", "debug": "max" }
Response examples
{ "authToken": "replaceWithValidAuthtoken", "result": { "dataFormat": "objects", "binaryFormat": "hexadecimal", "fields": [ { "name": "id", "type": "bigint", "length": null, "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": false, "primaryKey": 1 }, { "name": "changeId", "type": "bigint", "length": null, "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": true, "primaryKey": 0 }, { "name": "name", "type": "varchar", "length": 50, "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": true, "primaryKey": 0 } ], "data": [] }, "requestId": "1", "errorCode": 4014, "errorMessage": "field 'BOGUS' does not belong to the table" }
{ "authToken": "replaceWithValidAuthtoken", "result": { "dataFormat": "objects", "binaryFormat": "hex", "fields": [ { "name": "id", "type": "bigint", "length": null, "scale": null, "defaultValue": null, "nullable": false, "primaryKey": 1, "autoValue": "incrementOnInsert" }, { "name": "changeId", "type": "bigint", "length": null, "scale": null, "defaultValue": null, "nullable": true, "primaryKey": 0, "autoValue": "changeId" }, { "name": "name", "type": "varchar", "length": 50, "scale": null, "defaultValue": null, "nullable": true, "primaryKey": 0, "autoValue": "none" } ], "data": [ { "changeId": 1289789, "id": 1, "name": "test name 1" }, { "changeId": 1289789, "id": 2, "name": "test name 2" } ], "primaryKeyFields": [ "id" ], "changeIdField": "changeId" }, "requestId": "1", "errorCode": 0, "errorMessage": "" }
{ "authToken": "replaceWithValidAuthtoken", "result": { "dataFormat": "objects", "binaryFormat": "hex", "fields": [ { "name": "id", "type": "bigint", "length": null, "scale": null, "defaultValue": null, "nullable": false, "primaryKey": 1, "autoValue": "incrementOnInsert" }, { "name": "changeId", "type": "bigint", "length": null, "scale": null, "defaultValue": null, "nullable": true, "primaryKey": 0, "autoValue": "changeId" }, { "name": "nested_json_object_or_array", "type": "json", "length": 65500, "scale": null, "defaultValue": null, "nullable": true, "primaryKey": 0, "autoValue": "none" }, { "name": "boolean_byte", "type": "bit", "length": null, "scale": null, "defaultValue": null, "nullable": true, "primaryKey": 0, "autoValue": "none" }, { "name": "signed_int8", "type": "tinyint", "length": null, "scale": null, "defaultValue": null, "nullable": true, "primaryKey": 0, "autoValue": "none" }, { "name": "signed_int16", "type": "smallint", "length": null, "scale": null, "defaultValue": null, "nullable": true, "primaryKey": 0, "autoValue": "none" }, { "name": "signed_int32", "type": "integer", "length": null, "scale": null, "defaultValue": null, "nullable": true, "primaryKey": 0, "autoValue": "none" }, { "name": "signed_int64", "type": "bigint", "length": null, "scale": null, "defaultValue": null, "nullable": true, "primaryKey": 0, "autoValue": "none" }, { "name": "iee_base2float32", "type": "real", "length": null, "scale": null, "defaultValue": null, "nullable": true, "primaryKey": 0, "autoValue": "none" }, { "name": "iee_base2float64", "type": "float", "length": null, "scale": null, "defaultValue": null, "nullable": true, "primaryKey": 0, "autoValue": "none" }, { "name": "signed32digits_base10_left32right0", "type": "number", "length": 32, "scale": 0, "defaultValue": null, "nullable": true, "primaryKey": 0, "autoValue": "none" }, { "name": "signed32digits_base10_left0right32", "type": "number", "length": 32, "scale": 32, "defaultValue": null, "nullable": true, "primaryKey": 0, "autoValue": "none" }, { "name": "signed32digits_base10_left20right12", "type": "number", "length": 32, "scale": 12, "defaultValue": null, "nullable": true, "primaryKey": 0, "autoValue": "none" }, { "name": "signed32digits_base10_left30right2", "type": "money", "length": 32, "scale": 2, "defaultValue": null, "nullable": true, "primaryKey": 0, "autoValue": "none" }, { "name": "signed32digits_base10_left28right4", "type": "money", "length": 32, "scale": 4, "defaultValue": null, "nullable": true, "primaryKey": 0, "autoValue": "none" }, { "name": "date_yyyymmdd", "type": "date", "length": null, "scale": null, "defaultValue": null, "nullable": true, "primaryKey": 0, "autoValue": "none" }, { "name": "time_hhmmssfff", "type": "time", "length": null, "scale": null, "defaultValue": null, "nullable": true, "primaryKey": 0, "autoValue": "none" }, { "name": "datetime_yyyymmddthhmmssfff", "type": "timestamp", "length": null, "scale": null, "defaultValue": null, "nullable": true, "primaryKey": 0, "autoValue": "none" }, { "name": "fixed_string_10bytes", "type": "char", "length": 10, "scale": null, "defaultValue": null, "nullable": true, "primaryKey": 0, "autoValue": "none" }, { "name": "variable_string_up_to_max65500bytes", "type": "varchar", "length": 65500, "scale": null, "defaultValue": null, "nullable": true, "primaryKey": 0, "autoValue": "none" }, { "name": "variable_string_up_to_2GB", "type": "lvarchar", "length": null, "scale": null, "defaultValue": null, "nullable": true, "primaryKey": 0, "autoValue": "none" }, { "name": "fixed_binary_10bytes", "type": "binary", "length": 10, "scale": null, "defaultValue": null, "nullable": true, "primaryKey": 0, "autoValue": "none" }, { "name": "variable_binary_up_to_max65500bytes", "type": "varbinary", "length": 65500, "scale": null, "defaultValue": null, "nullable": true, "primaryKey": 0, "autoValue": "none" }, { "name": "variable_binary_up_to_2GB", "type": "lvarbinary", "length": null, "scale": null, "defaultValue": null, "nullable": true, "primaryKey": 0, "autoValue": "none" } ], "data": [ { "boolean_byte": true, "changeId": "1293834", "date_yyyymmdd": "2023-04-18", "datetime_yyyymmddthhmmssfff": "2023-04-18T15:43:59.013", "fixed_binary_10bytes": "FF00FF00000000000000", "fixed_string_10bytes": "_ 3456 _", "id": "1", "iee_base2float32": "-1e-06", "iee_base2float64": "-9.22337e+18", "nested_json_object_or_array": { "hello": "world" }, "signed32digits_base10_left0right32": "-0.12345678901234567890123456789012", "signed32digits_base10_left20right12": "-12345678901234567890.123456789012", "signed32digits_base10_left28right4": "-1234567890123456789012345678.9012", "signed32digits_base10_left30right2": "-123456789012345678901234567890.12", "signed32digits_base10_left32right0": "-12345678901234567890123456789012", "signed_int16": "-32768", "signed_int32": "-2147483648", "signed_int64": "-9223372036854775808", "signed_int8": "-128", "time_hhmmssfff": "15:43:59.013", "variable_binary_up_to_2GB": "FF00FF", "variable_binary_up_to_max65500bytes": "FF00FF", "variable_string_up_to_2GB": "Variable-length string up to 2GB in length.", "variable_string_up_to_max65500bytes": "Variable-length string up to 65,500 bytes." } ], "primaryKeyFields": [ "id" ], "changeIdField": "changeId" }, "requestId": "4", "debugInfo": { "request": { "authToken": "replaceWithValidAuthtoken", "api": "db", "action": "insertRecords", "params": { "databaseName": "ctreeSQL", "ownerName": "admin", "tableName": "all_types", "dataFormat": "objects", "binaryFormat": "hex", "sourceData": [ { "nested_json_object_or_array": { "hello": "world" }, "boolean_byte": true, "signed_int8": -128, "signed_int16": -32768, "signed_int32": -2147483648, "signed_int64": -9223372036854776000, "iee_base2float32": -0.000001, "iee_base2float64": "-9223372036800000000.0", "signed32digits_base10_left32right0": "-12345678901234567890123456789012", "signed32digits_base10_left0right32": "-0.12345678901234567890123456789012", "signed32digits_base10_left20right12": "-12345678901234567890.123456789012", "signed32digits_base10_left30right2": "-123456789012345678901234567890.12", "signed32digits_base10_left28right4": "-1234567890123456789012345678.9012", "date_yyyymmdd": "2023-04-18", "time_hhmmssfff": "15:43:59.013", "datetime_yyyymmddthhmmssfff": "2023-04-18T15:43:59.013", "fixed_string_10bytes": "_ 3456 _", "variable_string_up_to_max65500bytes": "Variable-length string up to 65,500 bytes.", "variable_string_up_to_2GB": "Variable-length string up to 2GB in length.", "fixed_binary_10bytes": "FF00FF", "variable_binary_up_to_max65500bytes": "FF00FF", "variable_binary_up_to_2GB": "FF00FF" } ] }, "apiVersion": "1.0", "requestId": "4", "responseOptions": { "binaryFormat": "hex", "dataFormat": "objects", "numberFormat": "string" }, "debug": "max" }, "serverSuppliedValues": { "databaseName": "ctreeSQL", "ownerName": "admin" }, "errorData": { "errorData": null }, "warnings": [] }, "errorCode": 0, "errorMessage": "" }
"params"
The "params"
property is an object that contains an action's parameters. Each action defines its own required and optional properties.
Property summary
"params"
property summariesProperty | Description | Default | Type | Limits (inclusive) | |||
---|---|---|---|---|---|---|---|
determines how binary values are returned |
| string enum |
| ||||
contains the name of a database | Defaults to the | string |
| ||||
specifies the returned results as an array of array, an array of objects, or the default setting defined at login |
| string |
| ||||
specifies the names of fields in a table |
NoteWhen | array |
| ||||
contains the unique name of a schema in a database |
| string |
| ||||
| contains either an array of objects or an array of arrays (depending on the specified |
| array | ||||
contains the name of a table | Required - No default value | string |
|
The "binaryFormat"
property designates how binary values are formatted in the JSON request and JSON response message. The default value is "base64"
.
Note
Typically, response options apply only to the server’s response, but the "binaryFormat"
property applies to both the request and the response.
The
"binaryFormat"
property may occur inside"params"
,"responseOptions"
,"defaultResponseOptions"
, and"result"
.When
"binaryFormat"
occurs in"params"
it specifies how the sender represents binary values.For example, when
"binaryFormat"
is set to"hex"
, the FairCom server expects the binary values of fields and keys to be represented in strings with hexadecimal format.When
"binaryFormat"
occurs in"responseOptions"
or"defaultResponseOptions"
it specifies how the FairCom server should represent binary values in responses.For example, when
"binaryFormat"
is set to"hex"
, the FairCom server represents binary values in strings with hexadecimal format.When
"binaryFormat"
occurs in"result"
it signifies how binary values are represented.For example, when
"binaryFormat"
is set to "base64", the FairCom server represents binary values in the response in base64 format.The following are the possible values for each format.
"base64"
When the server reads and writes from a binary field, it represents the binary value as a base64 string.
This is the default
"base64"
strings contain the following characters:0-9
A-Z
a-z
+
/
=
"hex"
When the server reads and writes from a binary field, it represents the binary value as a hexadecimal string.
Hexadecimal is easier for people to read and convert to binary.
Hexadecimal creates a larger payload than
"base64"
, which makes it less efficient for data transmission.Hexadecimal strings contain the following characters:
0-9
A-F
"byteArray"
When the server reads and writes from a binary field, it represents the binary value as an array of bytes.
An array of bytes is easiest for a program to manipulate.
An array of bytes creates a larger payload than
"base64"
and"hex"
, which makes it less efficient for data transmission.An array of bytes returns a JSON array containing one integer number between 0 and 255 for each byte in the binary value:
"aBinaryField": [ 255, 0, 255 ]
Examples
Create a "binary_test"
table
This example creates a table containing one binary field named "bin"
with a fixed length of 5 bytes.
{ "api": "db", "action": "createTable", "params": { "tableName": "binary_test", "fields": [ { "name": "bin", "type": "binary", "length": 5 } ] }, "authToken": "replaceWithValidAuthtoken" }
Insert a record into the "binary_test"
table using an array of bytes format
This example inserts a record with the ASCII characters "123"
in the "bin"
field. The value of "bin"
is represented as an array of bytes.
{ "api": "db", "action": "insertRecords", "params": { "tableName": "binary_test", "dataFormat": "objects", "binaryFormat": "byteArray", "sourceData": [ { "bin": [49,50,51] } ] }, "authToken": "replaceWithValidAuthtoken" }
Insert a record into the "binary_test"
table using hexadecimal format
This example inserts a record with the ASCII characters "123"
in the "bin"
field. The value of "bin"
is represented as a string in hexadecimal format.
{ "api": "db", "action": "insertRecords", "params": { "tableName": "binary_test", "dataFormat": "objects", "binaryFormat": "hex", "sourceData": [ { "bin": "313233" } ] }, "authToken": "replaceWithValidAuthtoken" }
Insert a record into the "binary_test"
table using base64 format
This example inserts a record with the ASCII characters "123"
in the "bin"
field. The value of "bin"
is represented as a string in base64 format.
{ "api": "db", "action": "insertRecords", "params": { "tableName": "binary_test", "dataFormat": "objects", "binaryFormat": "base64", "sourceData": [ { "bin": "MTIz" } ] }, "authToken": "replaceWithValidAuthtoken" }
Retrieve a record with "binaryFormat"
as an array of bytes
This example requests the first record in the "binary_test" table with the value of "bin"
represented as an array of bytes.
{ "api": "db", "action": "getRecordsByTable", "params": { "tableName": "binary_test", "maxRecords": 1 }, "responseOptions": { "binaryFormat": "byteArray", "dataFormat": "objects", "numberFormat": "number" }, "authToken": "replaceWithValidAuthtoken" }
Response
Note
Our examples insert only 3 bytes into "bin"
. Because the "bin"
field has a fixed-length if 5 bytes, the server pads unused bytes with 0x00
and stores the result. When a record is retrieved, the server returns all 5 bytes.
{ "authToken": "authtokenFromServer", "result": { "dataFormat": "objects", "binaryFormat": "byteArray", "fields": [ { "name": "id", "type": "bigint", "length": null, "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": false, "primaryKey": 1 }, { "name": "changeId", "type": "bigint", "length": null, "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": true, "primaryKey": 0 }, { "name": "bin", "type": "binary", "length": 5, "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": true, "primaryKey": 0 } ], "data": [ { "bin": [49,50,51,0,0], "changeId": 50217, "id": 1 } ], "moreRecords": true, "requestedRecordCount": 1, "returnedRecordCount": 1, "totalRecordCount": 3 }, "errorCode": 0, "errorMessage": "" }
Retrieve a record with "binaryFormat"
as hexadecimal
This example requests the first record in the "binary_test" table with the value of "bin"
represented as a hexadecimal string.
{ "api": "db", "action": "getRecordsByTable", "params": { "tableName": "binary_test", "maxRecords": 1 }, "responseOptions": { "binaryFormat": "hex", "dataFormat": "objects", "numberFormat": "number" }, "authToken": "replaceWithValidAuthtoken" }
Response
{ "authToken": "authtokenFromServer", "result": { "dataFormat": "objects", "binaryFormat": "byteArray", "fields": [ { "name": "id", "type": "bigint", "length": null, "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": false, "primaryKey": 1 }, { "name": "changeId", "type": "bigint", "length": null, "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": true, "primaryKey": 0 }, { "name": "bin", "type": "binary", "length": 5, "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": true, "primaryKey": 0 } ], "data": [ { "bin": "3132330000", "changeId": 50217, "id": 1 } ], "moreRecords": true, "requestedRecordCount": 1, "returnedRecordCount": 1, "totalRecordCount": 3 }, "errorCode": 0, "errorMessage": "" }
Retrieve a record with "binaryFormat"
as base64
This example requests the first record in the "binary_test" table with the value of "bin"
represented as a base64 string.
{ "api": "db", "action": "getRecordsByTable", "params": { "tableName": "binary_test", "maxRecords": 1 }, "responseOptions": { "binaryFormat": "base64", "dataFormat": "objects", "numberFormat": "number" }, "authToken": "replaceWithValidAuthtoken" }
Response
{ "authToken": "authtokenFromServer", "result": { "dataFormat": "objects", "binaryFormat": "byteArray", "fields": [ { "name": "id", "type": "bigint", "length": null, "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": false, "primaryKey": 1 }, { "name": "changeId", "type": "bigint", "length": null, "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": true, "primaryKey": 0 }, { "name": "bin", "type": "binary", "length": 5, "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": true, "primaryKey": 0 } ], "data": [ { "bin": "MTIzAAA=", "changeId": 50217, "id": 1 } ], "moreRecords": true, "requestedRecordCount": 1, "returnedRecordCount": 1, "totalRecordCount": 3 }, "errorCode": 0, "errorMessage": "" }
The "databaseName"
property is an optional string that specifies the database that contains the tables. It defaults to the database name supplied at login.
Note
In the API Explorer, "defaultDatabaseName"
is set to "ctreeSQL"
in the "createSession"
action that happens at login.
A zero-length
"databaseName"
is invalid.Its limits are from 0 to 64 bytes.
If the
"databaseName"
property is omitted or set tonull
, the server will use the default database name specified at login.If no default database is specified during
"createSession"
,"defaultDatabaseName"
will be set to the"defaultDatabaseName"
value that is specified in theservices.json
file.
The "dataFormat"
property is an optional, case-insensitive string enum that defines the format of the response in the "data"
property. The default format is an array of arrays. The alternative is an array of objects. The default for "dataFormat"
can be changed during a "createSession"
action by assigning a different value to the "dataFormat"
property in "defaultResponseOptions"
.
"dataFormat"
property:Two of those versions occur in a request and another occurs in a response. They all indicate how data is formatted.
"dataFormat"
in the request inside"responseOptions"
determines how the"data"
property in the response is formatted.Possible values include:
"arrays"
This is the default and causes the server to return results as an array of arrays, which is the most efficient.
"objects"
This returns results as an array of objects. This is less efficient but is simpler to generate, read, and troubleshoot.
"dataFormat"
in the request in the"params"
object notifies the server how the"sourceData"
property is formatted in the request. This version is rarely used because of the default"autoDetect"
behavior.Possible values include:
"arrays"
This causes the server to return results as an array of arrays, which is the most efficient.
"objects"
This returns results as an array of objects. This is less efficient but is simpler to generate, read, and troubleshoot.
"autoDetect"
This is the default and causes the server to automatically detect the format of the data in the
"sourceData"
property.
"dataFormat"
in the response shows the client how the server formatted the"data"
property.Possible values include:
"arrays"
This is the default and causes the server to return results as an array of arrays, which is the most efficient.
"objects"
This returns results as an array of objects. This is less efficient but is simpler to generate, read, and troubleshoot.
The "fieldNames"
property is an optional, case-sensitive array of strings where each string is the name of a field. It defaults to an empty array.
"fieldNames"
is required in two possible cases:When
"dataFormat"
is set to"arrays"
.When
"dataFormat"
is set to"autoDetect"
and the value in"sourceData"
is an array of arrays.
It is recommended to create tables with all lowercase
"fieldNames"
.
The "ownerName"
property is an optional string from 1 to 64 bytes that specifies the account that owns an object.
The
"ownerName"
property is optional and has a dynamic default value.If the
"ownerName"
property is omitted or set tonull
, the server uses the value of the"defaultOwnerName"
property supplied during the "createSession"
action.If the
"defaultOwnerName"
property is not defined, the server uses the"admin"
as the owner name.The owner of an object has administrative rights over that object.
The
"ownerName"
property is a namespace for an object. You can think of it as a container of objects.The
"ownerName"
allows users to use any name for the objects they create — for example, a QA engineer may copy tables into their owner space to run a set of tests.It is common for a user to create their own copies of objects from other accounts for testing, troubleshooting, and fixing data. The copied objects can retain the same name because the
"ownerName"
distinguishes between them.The fully qualified name of an object is the
"databaseName"
,"ownerName"
, and the object's name, such as"tableName"
meaning a FairCom server may contain many tables with the name"mytable"
as long as each one is in a different database or in a different owner space.For example, an organization often creates different databases for different phases of the development lifecycle, such as dev, test, stage, ua, and prod. Each of these databases contains the same set of objects with the same names. Applications leave the
"databaseName"
out of their JSON actions and use the"defaultDatabaseName"
property to specify the target database.Queries and scripts are often written without specifying
"databaseName"
and/or"ownerName"
, allowing queries and scripts to work properly when run in different databases or in different schemas.
The "tableName"
property is an optional string that contains the name of an integration table or MQTT topic that holds the topic's messages. It defaults to an empty string.
You can use a topic name for an MQTT table because FairCom automatically generates a table name for each topic.
A
"tableName"
cannot begin with a number.It refers to the name of the integration table that stores a topic’s messages and is used to rename that table or assign a new topic to an existing integration table.
MQTT automatically creates an integration table for each new topic it receives. Thus, when a message is sent to a topic, FairCom Edge automatically creates a table to hold it.
As you refine your integration processes, you may want to rename an integration table to better label the data it holds. You can use the
"tableName"
property of the"configureTopic"
action to rename an integration table.The
"alterIntegrationTable"
action can also be used to rename an integration table, but it is less convenient because you must know the original name of the integration table.
"result"
Property summary
"result"
property summariesProperty | Description | Type | Limits (inclusive) | |||
---|---|---|---|---|---|---|
designates how binary values are returned | string enum |
| ||||
| contains an array or object that the server returns, such as records returned by a query NoteIt is an empty array when there are no results available. | array | Its contents are determined by the action | |||
defines the format of the data in the | string |
| ||||
shows an array of objects set by the server where each object is the definition of a field in a table defining the details of each field returned by a query | array |
The "binaryFormat"
property designates how binary values are formatted in the JSON request and JSON response message. The default value is "base64"
.
Note
Typically, response options apply only to the server’s response, but the "binaryFormat"
property applies to both the request and the response.
The
"binaryFormat"
property may occur inside"params"
,"responseOptions"
,"defaultResponseOptions"
, and"result"
.When
"binaryFormat"
occurs in"params"
it specifies how the sender represents binary values.For example, when
"binaryFormat"
is set to"hex"
, the FairCom server expects the binary values of fields and keys to be represented in strings with hexadecimal format.When
"binaryFormat"
occurs in"responseOptions"
or"defaultResponseOptions"
it specifies how the FairCom server should represent binary values in responses.For example, when
"binaryFormat"
is set to"hex"
, the FairCom server represents binary values in strings with hexadecimal format.When
"binaryFormat"
occurs in"result"
it signifies how binary values are represented.For example, when
"binaryFormat"
is set to "base64", the FairCom server represents binary values in the response in base64 format.The following are the possible values for each format.
"base64"
When the server reads and writes from a binary field, it represents the binary value as a base64 string.
This is the default
"base64"
strings contain the following characters:0-9
A-Z
a-z
+
/
=
"hex"
When the server reads and writes from a binary field, it represents the binary value as a hexadecimal string.
Hexadecimal is easier for people to read and convert to binary.
Hexadecimal creates a larger payload than
"base64"
, which makes it less efficient for data transmission.Hexadecimal strings contain the following characters:
0-9
A-F
"byteArray"
When the server reads and writes from a binary field, it represents the binary value as an array of bytes.
An array of bytes is easiest for a program to manipulate.
An array of bytes creates a larger payload than
"base64"
and"hex"
, which makes it less efficient for data transmission.An array of bytes returns a JSON array containing one integer number between 0 and 255 for each byte in the binary value:
"aBinaryField": [ 255, 0, 255 ]
Examples
Create a "binary_test"
table
This example creates a table containing one binary field named "bin"
with a fixed length of 5 bytes.
{ "api": "db", "action": "createTable", "params": { "tableName": "binary_test", "fields": [ { "name": "bin", "type": "binary", "length": 5 } ] }, "authToken": "replaceWithValidAuthtoken" }
Insert a record into the "binary_test"
table using an array of bytes format
This example inserts a record with the ASCII characters "123"
in the "bin"
field. The value of "bin"
is represented as an array of bytes.
{ "api": "db", "action": "insertRecords", "params": { "tableName": "binary_test", "dataFormat": "objects", "binaryFormat": "byteArray", "sourceData": [ { "bin": [49,50,51] } ] }, "authToken": "replaceWithValidAuthtoken" }
Insert a record into the "binary_test"
table using hexadecimal format
This example inserts a record with the ASCII characters "123"
in the "bin"
field. The value of "bin"
is represented as a string in hexadecimal format.
{ "api": "db", "action": "insertRecords", "params": { "tableName": "binary_test", "dataFormat": "objects", "binaryFormat": "hex", "sourceData": [ { "bin": "313233" } ] }, "authToken": "replaceWithValidAuthtoken" }
Insert a record into the "binary_test"
table using base64 format
This example inserts a record with the ASCII characters "123"
in the "bin"
field. The value of "bin"
is represented as a string in base64 format.
{ "api": "db", "action": "insertRecords", "params": { "tableName": "binary_test", "dataFormat": "objects", "binaryFormat": "base64", "sourceData": [ { "bin": "MTIz" } ] }, "authToken": "replaceWithValidAuthtoken" }
Retrieve a record with "binaryFormat"
as an array of bytes
This example requests the first record in the "binary_test" table with the value of "bin"
represented as an array of bytes.
{ "api": "db", "action": "getRecordsByTable", "params": { "tableName": "binary_test", "maxRecords": 1 }, "responseOptions": { "binaryFormat": "byteArray", "dataFormat": "objects", "numberFormat": "number" }, "authToken": "replaceWithValidAuthtoken" }
Response
Note
Our examples insert only 3 bytes into "bin"
. Because the "bin"
field has a fixed-length if 5 bytes, the server pads unused bytes with 0x00
and stores the result. When a record is retrieved, the server returns all 5 bytes.
{ "authToken": "authtokenFromServer", "result": { "dataFormat": "objects", "binaryFormat": "byteArray", "fields": [ { "name": "id", "type": "bigint", "length": null, "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": false, "primaryKey": 1 }, { "name": "changeId", "type": "bigint", "length": null, "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": true, "primaryKey": 0 }, { "name": "bin", "type": "binary", "length": 5, "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": true, "primaryKey": 0 } ], "data": [ { "bin": [49,50,51,0,0], "changeId": 50217, "id": 1 } ], "moreRecords": true, "requestedRecordCount": 1, "returnedRecordCount": 1, "totalRecordCount": 3 }, "errorCode": 0, "errorMessage": "" }
Retrieve a record with "binaryFormat"
as hexadecimal
This example requests the first record in the "binary_test" table with the value of "bin"
represented as a hexadecimal string.
{ "api": "db", "action": "getRecordsByTable", "params": { "tableName": "binary_test", "maxRecords": 1 }, "responseOptions": { "binaryFormat": "hex", "dataFormat": "objects", "numberFormat": "number" }, "authToken": "replaceWithValidAuthtoken" }
Response
{ "authToken": "authtokenFromServer", "result": { "dataFormat": "objects", "binaryFormat": "byteArray", "fields": [ { "name": "id", "type": "bigint", "length": null, "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": false, "primaryKey": 1 }, { "name": "changeId", "type": "bigint", "length": null, "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": true, "primaryKey": 0 }, { "name": "bin", "type": "binary", "length": 5, "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": true, "primaryKey": 0 } ], "data": [ { "bin": "3132330000", "changeId": 50217, "id": 1 } ], "moreRecords": true, "requestedRecordCount": 1, "returnedRecordCount": 1, "totalRecordCount": 3 }, "errorCode": 0, "errorMessage": "" }
Retrieve a record with "binaryFormat"
as base64
This example requests the first record in the "binary_test" table with the value of "bin"
represented as a base64 string.
{ "api": "db", "action": "getRecordsByTable", "params": { "tableName": "binary_test", "maxRecords": 1 }, "responseOptions": { "binaryFormat": "base64", "dataFormat": "objects", "numberFormat": "number" }, "authToken": "replaceWithValidAuthtoken" }
Response
{ "authToken": "authtokenFromServer", "result": { "dataFormat": "objects", "binaryFormat": "byteArray", "fields": [ { "name": "id", "type": "bigint", "length": null, "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": false, "primaryKey": 1 }, { "name": "changeId", "type": "bigint", "length": null, "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": true, "primaryKey": 0 }, { "name": "bin", "type": "binary", "length": 5, "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": true, "primaryKey": 0 } ], "data": [ { "bin": "MTIzAAA=", "changeId": 50217, "id": 1 } ], "moreRecords": true, "requestedRecordCount": 1, "returnedRecordCount": 1, "totalRecordCount": 3 }, "errorCode": 0, "errorMessage": "" }
The "dataFormat"
property is an optional, case-insensitive string enum that defines the format of the response in the "data"
property. The default format is an array of arrays. The alternative is an array of objects. The default for "dataFormat"
can be changed during a "createSession"
action by assigning a different value to the "dataFormat"
property in "defaultResponseOptions"
.
"dataFormat"
property:Two of those versions occur in a request and another occurs in a response. They all indicate how data is formatted.
"dataFormat"
in the request inside"responseOptions"
determines how the"data"
property in the response is formatted.Possible values include:
"arrays"
This is the default and causes the server to return results as an array of arrays, which is the most efficient.
"objects"
This returns results as an array of objects. This is less efficient but is simpler to generate, read, and troubleshoot.
"dataFormat"
in the request in the"params"
object notifies the server how the"sourceData"
property is formatted in the request. This version is rarely used because of the default"autoDetect"
behavior.Possible values include:
"arrays"
This causes the server to return results as an array of arrays, which is the most efficient.
"objects"
This returns results as an array of objects. This is less efficient but is simpler to generate, read, and troubleshoot.
"autoDetect"
This is the default and causes the server to automatically detect the format of the data in the
"sourceData"
property.
"dataFormat"
in the response shows the client how the server formatted the"data"
property.Possible values include:
"arrays"
This is the default and causes the server to return results as an array of arrays, which is the most efficient.
"objects"
This returns results as an array of objects. This is less efficient but is simpler to generate, read, and troubleshoot.
The "fields"
property is a required array of field-type objects. There is one object for each top-level field in the array. Each object identifies the actual data type of the field as stored in the database.
A field-type object is used when creating a table. It contains one object for each field definition returned in the data.
Full request example
"fields": [ { "name": "name", "type": "varchar", "length": 50, "scale": null, "defaultValue": null, "nullable": false, "primaryKey":1 } ]
Full response example
"fields": [ { "name": "id", "type": "bigint", "length": null, "scale": null, "autoValue": "none", "defaultValue": null, "nullable": false, "primaryKey": 1 } ]
Property summary
"fields"
property summariesProperty | Description | Default | Type | Limits (inclusive) | |||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
controls when and how the server automatically sets the field value |
| string |
| ||||||||||||||||||||
| specifies the default value of a field |
| string |
| |||||||||||||||||||
| defines the length of a field's value in a record |
| integer |
| |||||||||||||||||||
| defines a new name of the field | required | string |
| |||||||||||||||||||
| allows a field to contain a NULL value when |
| Boolean |
| |||||||||||||||||||
| adds a field to the specified ordinal position of the table's primary key when > 0 |
| integer |
| |||||||||||||||||||
| defines the number of places to the right of the decimal point |
| integer |
| |||||||||||||||||||
| defines the type of field | required | string |
|
This property controls when and how the server automatically sets the field value.
Specify only one of these values per field.
"none"
indicates the server does not automatically set the field's value."incrementOnInsert"
indicates the server automatically increments a field’s value each time the server inserts a new record. It applies to fields that are of the type of decimal or one of the integer types, such as"bigint"
. Only one field per table can have this attribute. The server returns an error when assigning this attribute to multiple fields. The JSON DB API automatically creates the"id"
field as an"incrementOnInsert"
field. If you apply this attribute to another field, it becomes the only automatically incremented field in the table. If you want that field to be the primary key, assign"primaryKey": 1
to it."timestampOnInsert"
indicates the server automatically sets a field’s value to the current date and time of an insert. It applies only to fields with a type of"timestamp"
."timestampOnUpdate"
indicates the server automatically sets a field’s value to the current date and time of an update. It applies only to timestamp fields."timestampOnUpdateAndInsert"
indicates the server automatically sets a field’s value to the current date and time of an insert and an update. It applies only to fields with a type of"timestamp"
."changeId"
indicates the server uses the field for optimistic locking. The server automatically sets the field's value to the internal transaction number used during the last update of the record. This value changes each time the server updates the record. A table may only have one change tracking field. The field type must be"bigint"
.The JSON DB API automatically creates a
"changeid"
field with change-tracking functionality.Change tracking is optional in the CTDB and ISAM APIs. The application must create a 64-bit integer field and assign change-tracking functionality to it.