Skip to main content

"insertRecords"

JSON DB "insertRecords" action inserts records into a table

The "insertRecords" action inserts one or more records into a table.

Request examples

Insert into test1 table using objects request

{
  "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"
      }
    ]
  }
}

Insert into test1 table using an array of arrays request

{
  "requestId": "2",
  "authToken": "replaceWithValidAuthtoken",
  "api": "db",
  "action": "insertRecords",
  "params": {
    "tableName": "test1",
    "dataFormat": "arrays",
    "fieldNames": [
      "name"
    ],
    "sourceData": [
      [
        "test name 3"
      ],
      [
        "test name 4"
      ]
    ]
  }
}

Insert into athlete table request

{
  "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."
      }
    ]
  }
}

Insert into all_types table request

{
  "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,
        "ieee_base2float32": -0.000001,
        "ieee_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

Insert into test1 table because of an incorrect field name failure response

{
  "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"
}

Insert into test1 table successful response

{
  "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": ""
}

Insert into all_types table response

{
  "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": "ieee_base2float32",
        "type": "real",
        "length": null,
        "scale": null,
        "defaultValue": null,
        "nullable": true,
        "primaryKey": 0,
        "autoValue": "none"
      },
      {
        "name": "ieee_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",
        "ieee_base2float32": "-1e-06",
        "ieee_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,
            "ieee_base2float32": -0.000001,
            "ieee_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": ""
}

Use the insertRecords JSON API action to insert records into a table

API actionsJSON DB APIjsonActioninsert recordsinsertRecords

"params"

The "params" property is an object that contains an action's parameters. Each action defines its own required and optional properties.

Property summary

Table 1. "params" property summaries

Property

Description

Default

Type

Limits (inclusive)

binaryFormat

specifies how binary values are returned

"base64"

string enum

"base64"
"hex"

databaseName

specifies the name of a database

Defaults to the "defaultDatabaseName" value that is set during "createSession". If no default is set during "createSession", then "faircom" is used.

string

1 to 64 bytes

dataFormat

specifies the returned results as an array of array, an array of objects, or the default setting defined at login

"arrays"

string

"default"
"arrays"
"objects"

fieldNames

specifies the names of fields in a table

[]

When "sourceData" is an array of arrays, it is required and has no default value.

array

1 to 64 bytes

ownerName

specifies the unique name of a schema in a database

""

string

1 to 64 bytes

sourceData

contains either an array of objects or an array of arrays (depending on the specified "dataFormat") in each object or nested array is the source data for an insert or update operation

[]

array

tableName

specifies the name of a table

Required - No default value

string

1 to 64 bytes



"binaryFormat"

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.

Essential information

  • 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.

      • Base64 is harder for people to read and convert to binary.

      • Base64 creates the smallest payload for the most efficient data transmission in JSON.

      • "base64" strings contain the characters 0 - 9 , A - Z, a - z, +, /, and =.

    • "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 30% larger payload than "base64", which makes it less efficient for data transmission.

      • Hexadecimal strings contain the characters 0 - 9 and 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": ""
}

"databaseName"

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.

Essential information

  • A zero-length "databaseName" is invalid.

  • Its limits are from 0 to 64 bytes.

  • If the "databaseName" property is omitted or set to null, 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 the services.json file.

"dataFormat"

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".

There are three different (but similar) versions of the "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.

"fieldNames"

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.

Essential information

  • "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".

"ownerName"

The "ownerName" property is an optional string from 1 to 64 bytes that specifies the account that owns an object.

"tableName"

The "tableName" property is a string containing the name of a table.

Essential information

  • A table name may contain up to 64 ASCII characters and must not start with a number.

"result"

Properties summary

Table 2. "result" properties summary

Property

Description

Type

Limits (inclusive)

binaryFormat

specifies how binary values are returned

string enum

"base64"
"hex"

data

specifies an array or object that the server returns, such as records returned by a query. It is an empty array when no results are available.

array

Its contents are determined by the action

dataFormat

specifies the format of the data in the "data" property

string

"autoDetect"
"arrays"
"objects"

fields

specifies 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



"binaryFormat"

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.

Essential information

  • 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.

      • Base64 is harder for people to read and convert to binary.

      • Base64 creates the smallest payload for the most efficient data transmission in JSON.

      • "base64" strings contain the characters 0 - 9 , A - Z, a - z, +, /, and =.

    • "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 30% larger payload than "base64", which makes it less efficient for data transmission.

      • Hexadecimal strings contain the characters 0 - 9 and 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": ""
}

"dataFormat"

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".

There are three different (but similar) versions of the "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.

"fields"

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
  }
]

A database is a set of data that is managed by a database server. A database contains data that is organized into tables, records, and fields. A database is a huge composite data type that represents a group of interconnected objects. A database allows records to be joined together for querying, searching, and processing by users, applications, and services.

A database is a security container that controls which accounts have permissions to access specific data.