Skip to main content

"insertRecords" (JSON Action)

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

{
  "requestId": "1",
  "api": "db",
  "action": "insertRecords",
  "params": {
    "databaseName": "ctreeSQL",
    "ownerName": "admin",
    "tableName": "test1",
    "dataFormat": "objects",
    "sourceData": [
      {
        "name": "test name 1"
      },
      {
        "name": "test name 2"
      }
    ]
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

Insert into test1 table using an array of arrays

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

Insert into athlete table

{
  "api": "db",
  "apiVersion": "1.0",
  "requestId": "3",
  "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."
      }
    ]
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

Insert into all_types table

{
  "requestId": "4",
  "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",
    "variantFormat": "variantObject"
  },
  "apiVersion": "1.0",
  "debug": "max",
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

Response examples

Insert into test1 table because of an incorrect field name failure

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

Successfully inserted into test1 table

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

Insert into all_types table

{
  "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": {
      "api": "db",
      "action": "insertRecords",
      "params": {
        "databaseName": "ctreeSQL",
        "ownerName": "admin",
        "tableName": "all_types",
        "dataFormat": "objects",
        "binaryFormat": "hex",
        "variantFormat": "variantObject",
        "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",
        "variantFormat": "variantObject"
      },
      "debug": "max",
      "authToken": "replaceWithAuthTokenFromCreateSession"
    },
    "serverSuppliedValues": {
      "databaseName": "ctreeSQL",
      "ownerName": "admin"
    },
    "errorData": {
      "errorData": null
    },
    "warnings": []
  },
  "errorCode": 0,
  "errorMessage": "",
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

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

API actionsJSON DB APIJSON Actioninsert recordsinsertRecords

"params"

The "params" property is an object that contains an action's request parameters as defined by a set of properties. Each action defines its own required and optional properties. See System limits for a comprehensive overview of property requirements and limitations.

Table 1. "params" property summaries

Property

Description

Default

Type

Limits (inclusive)

binaryFormat

(optional) specifies how binary values are returned

"hex"

string

One of the following: "base64", "hex", or "byteArray".

databaseName

(optional) 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

(optional) 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

(optional) 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

(optional) specifies the unique name of a schema in a database.

""

string

1 to 64 bytes

sourceData

(optional) 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

variantFormat

(optional) tells the server how to interpret the variant-type data included in the request

"json"

string

"json"
"binary"
"string"
"variantObject"


"binaryFormat"

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

  • A zero-length "databaseName" is invalid.

  • Its length limit is 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", "databaseName" will be set to the "defaultDatabaseName" value that is specified in the services.json file.

"params": {
  "databaseName": "mainDatabase"
  }

"dataFormat"

The "dataFormat" property is a case-insensitive string enum that defines the format of 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 in "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 the server automatically detects 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.

Example response

{
  "result": {
    "dataFormat": "objects"
  }
}

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

  • "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 identifies the user who owns an object (see Object owner). If it is omitted or set to "" or null, the server uses the default owner name supplied during the "createSession" action or uses the account's "username" as the owner name.

"params": {
  "ownerName": "SuperUser"
}

"tableName"

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

See table name in System limits for the table naming requirements and limitations.

Example request

"params": {
  "tableName": "ctreeTable"
}

"variantFormat"

The "variantFormat" property tells the server how to format the values of variant fields in its response to your request.

The "variantFormat" property has one of the following values: "binary", "json", "string", and "variantObject". It tells the server how to store and return values stored in variant fields. The default value is "json".

Things to know

  • The server applies the "variantFormat" property to all variant fields affected by a JSON action.

  • If you want to control the variant format of each field, set the "variantFormat" property to "variantObject" and use variant objects to set the variant type and encoding of each variant field.

The following sections describe each value of the "variantFormat" property.

"variantFormat": "binary"

  • Use the "variantFormat": "binary" setting to encode a variant field's value as a JSON string.

  • The "binaryFormat" property specifies how to encode the binary value.

    • The "binaryFormat": "hex" setting uses hexadecimal to encode a binary value in a JSON string.

    • The "binaryFormat": "base64" setting uses Base64 to encode a binary value in a JSON string.

    • The "binaryFormat": "byteArray" setting uses an array of integer numbers to encode each byte in the binary value.

  • When "variantFormat" is "binary", the server sets the variant's type to "binary" and stores raw bytes in the variant field.

  • The "binary" variant type ensures maximum compatibility and performance across all FairCom APIs, including JSON DB, SQL, CTDB, and ISAM.

  • The server does not validate the binary value, which can be any sequence of bytes.

"variantFormat": "json"

  • Use the "variantFormat": "json" setting to encode a variant field's value as a JSON value.

    • A JSON value can be an object, array, string, number, true, false, or null.

    • A binary field value is returned in a JSON string.

    • The "binaryFormat" property specifies the format of a binary variant value embedded in a JSON string.

    • The "numberFormat" property causes the server to return numbers as JSON numbers or JSON strings.

  • When "variantFormat" is "json", the server sets the variant's type to "json" and stores a JSON value in the variant field.

    • The server validates JSON before it assigns it to a variant field.

    • The server converts a variant field to valid JSON before it returns the value of a variant field.

  • When "variantFormat" is set to "json" in "responseOptions" and the "type" of variant object is "binary", the JSON API returns the binary variant value embedded in a string or as a byte array depending on the "binaryFormat" property in "responseOptions". In other words, when "variantFormat" is set to "json" in "responseOptions", the API returns a JSON value. All variant values can be returned as native JSON values except for binary values because JSON cannot represent them. Thus, when a variant has a binary value and the response option is JSON, the API embeds the binary value in a JSON string according to the value of "binaryFormat".

  • The server converts variant values to and from JSON as follows:

    • JSON null: The server does not store a JSON null; instead it marks the variant field as NULL. If the field is not nullable, the API returns an error.

    • JSON string: The server stores a JSON string in the variant field as is. It includes the double quotes before and after the string's value and stores escaped characters without decoding them. For example, the server stores the JSON string, "my // string",  as "my // string". The server returns a JSON string exactly as it stores it.

    • JSON number: The server stores a JSON number in the variant field as is. A number consists of the following ASCII characters 1234567890+-.eE. For example, the server stores the JSON number -123.45  as the ASCII characters -123.45. The server returns a JSON string exactly as it stores it.

    • JSON true & false: The server stores a JSON true and false in the variant field as is. It stores and returns the ASCII characters true or false.

    • JSON object & array: The server stores a JSON object and array as is. When it validates the JSON, it minimizes whitespace while preserving the UTF-8 characters representing the actual object or array. For example, the server stores the array [1,2,3]  as the UTF-8 characters [1,2,3].

"variantFormat": "variantObject"

  • Use the "variantFormat": "variantObject" setting to encode a variant field's value as a variant object.

  • When the "insertRecords" and "updateRecords" actions have "variantFormat": "variantObject" in "params", you must assign a variant object to each variant field.

  • A JSON action returns a variant object for a variant field value when you put "variantFormat": "variantObject" in "responseOptions".

"variantFormat": "string"

  • Use the "variantFormat": "string" setting to encode a variant field's value as a JSON string.

  • This setting in the "responseOptions" property causes all "getRecords..." actions to return string values from variant fields.

    • Binary values are returned as a JSON string containing an embedded binary value. The "binaryFormat" property specifies how to encode the binary value.

    • Number values are returned as a JSON number embedded in a string, such as "123.45". The server ignores the "numberFormat" property in the "responseOptions" object.

    • Boolean values are returned as a "true" or "false" string.

    • String values are returned as a JSON string, which may contain JSON escaped characters.

    • JSON values are returned embedded in a string.

      • A JSON object is escaped, encoded, and embedded in a string, such as "{\"key\": \"value\"}".

      • A JSON array is escaped, encoded, and embedded in a string, such as "[1, \"my string\", true ]".

      • A JSON string is returned as a JSON string.

      • A JSON number is embedded in a JSON string, such as "-123.456".

      • A JSON true is returned as "true".

      • A JSON false is returned as "false".

      • A JSON null is returned as "null".

  • This setting in the "params" property for "insertRecords" and "updateRecords" actions requires a string value to be assigned to each variant field.

    • FairCom does not recommend this setting because it can only store strings in variant fields. Consider using the other "variantFormat" options to store many more types of data, such as binary, JSON objects, JSON arrays, numbers, etc.

"responseOptions"

Table 2. "responseOptions" property summaries

Property

Description

Default

Type

Limits (inclusive)

binaryFormat

specifies how binary values are returned

"hex"

string

One of the following: "base64", "hex", or "byteArray".

dataFormat

specifies what format the results will be returned in

"arrays"

string

"default"
"arrays"
"objects"

excludeFields

(optional) specifies which fields are excluded in the response message

[]

When the array is empty or the property is not specified, the includeFields behavior applies

array

excludePaths

specifies which paths are excluded in the response message

[]

When the array is empty or the property is not specified, the includePaths behavior applies

array

includeFields

(optional) specifies which fields are returned in the response message

[]

When the array is empty or the property is not specified, all fields are returned

array

includePaths

specifies which paths are included in the response message

[]

When the array is empty or the property is not specified, all paths are returned

array

numberFormat

specifies how numbers are formatted in the JSON response message

"number"

string

"number"
"string"

omit

specifies which properties are excluded in the response message

{}

object

stringFormat

specifies the format in which string field values are returned

"json"

string

"json"
"hex"

variantFormat

(optional) specifies how the server will represent the values of variant fields in its response to your request

"json"

string

"json"
"binary"
"string"
"variantObject"


"binaryFormat"

"dataFormat"

"numberFormat"

The "numberFormat" property is an optional, case-insensitive string enum. It defines the format of JSON numbers. The default value for "numberFormat" is the "defaultNumberFormat" defined in the "createSession" or "alterSession" actions. If it is omitted there, it defaults to the value of the "defaultNumberFormat" property in the <faircom>/config/services.json file.

When "numberFormat" occurs in "mapOfPropertiesToFields", it tells the server how to encode or decode a number assigned to a JSON property.

For example, including "numberFormat" in a "tableFieldsToJson" transform step controls if the server encodes a number in a JSON property as a number or a number embedded in a string.

Possible values:

  • "number"

    This causes the server to return numeric values as JSON numbers, such as -18446744073709551616.000144722494 .

    This is most efficient.

    JSON represents numbers are base-ten numbers that may have any number of digits.

    Large numbers, such as 18446744073709551616.000144722494 are known to cause problems with JSON parsers and some programming languages, such as JavaScript, which are limited to the smaller range and binary rounding errors of IEEE floating point numbers.

  • "string"

    This returns the server to embed numeric values in JSON strings, such as "18446744073709551616.000144722494" .

    This is slightly less efficient because it includes two extra double quote characters

    Returning numbers embedded in strings ensures JSON parsers and programming languages will not automatically convert the number to a numeric representation that loses precision, introduces rounding errors, truncates values, or generates errors. This allows your application to control how numbers are processed.

  • Omitted or set to null

    This defaults to "number".

Example request

{
  "action": "someAction",
  "responseOptions":
  {
    "numberFormat": "string"
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

"stringFormat"

The "stringFormat" property in "responseOptions" changes how "char", "varchar", "lvarchar", and "variant" string field values are returned.

This property applies to all "getRecords..." actions, except for "getRecordsUsingSql" because SQL controls the format of strings it returns.

Options

"json" (default)

  • Returns "char", "varchar", "lvarchar", and "variant" string values as hexadecimal numbers embedded as JSON strings, such as "6d7920737472696e67".

  • Returns the raw binary value stored in the field, encoded as a hexadecimal.

  • Always twice the length of the original string.

  • Useful for returning legacy values that are incompatible with UTF-8 so they can be fixed.

  • When the "stringFormat" property is "hex", the API ignores the setting of "fixedLengthCharFormat" because it returns the field's raw value.  It includes pad characters in the hex dump. For example, "value     " in a char(10) field returns "76616c75652020202020".

  • When "variantFormat" is "string" or "json", a variant field returns binary values embedded in a string, such as "6d7920737472696e67". It also returns normal string values stored in a variant as a string, such as "my string". The application cannot reliably determine when a string is normal or contains embedded hexadecimal characters.

    • This setting forces all variant string values to be encoded as hexadecimal, making decoding string values predictable.

    • It overrides "binaryFormat" and always encodes variant strings as hexadecimal.

    • It removes the need to encode strings with JSON escape characters, such as \\ and \n.

      • For example, this setting causes a variant value stored as "my string" to be returned as "6D7920737472696E67".

Example

{
  "api": "db",
  "action": "getRecordsByTable",
  "params": {
    "tableName": "athlete"
  },
  "responseOptions": {
    "stringFormat": "hex",
    "binaryFormat": "hex",
    "dataFormat": "objects",
    "numberFormat": "string",
    "variantFormat": "variantObject"
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

Implementation steps

  • Add the "stringFormat" property to the "responseOptions" property for all "getRecords…" actions except for "getRecordsUsingSql".

  • Add the "stringFormat" property to the "defaultResponseOptions" property in the "createSession" and "alterSession" actions.

    • It defines the default value for the "stringFormat" property for "getRecords…" actions.

  • Add the "stringFormat" property to services.json under the "jsonActionApiDefaults"."defaultResponseOptions" properties.

    • It defines the default value for the "stringFormat" property for all sessions.

"variantFormat"

The "variantFormat" property tells the server how to format the values of variant fields in its response to your request.

"result"

Table 3. "result" properties summary

Property

Description

Type

Limits (inclusive)

binaryFormat

specifies how binary values are returned

string

One of the following: "base64", "hex", or "byteArray".

data

is an array of objects or arrays. Each item in the array describes a record. The array is empty if no results are available.

array

The action determines its contents.

dataFormat

identifies the format of the data in the "data" property.

string

"autoDetect"
"arrays"
"objects"

fields

is an array of objects, one for each field. Each object contains the field's characteristics.

array



"binaryFormat"

"dataFormat"

The "dataFormat" property is a case-insensitive string enum that defines the format of 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 in "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 the server automatically detects 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.

Example response

{
  "result": {
    "dataFormat": "objects"
  }
}

"fields"

The "fields" property is an array of objects. It is required when creating a table. Each object in the array defines a field by specifying its properties.

Example

"fields": [
  {
    "autoValue": "none",
    "name": "name",
    "type": "varchar",
    "length": 50,
    "scale": null,
    "defaultValue": null,
    "nullable": false
  }
]

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.