updateRecords

JSON DB "updateRecords" action updates records in a database table

The "updateRecords" action updates one or more records in a database table using field values that you specify.

 

Request examples

Update test1 table ignoring change protection

This example ignores change protection by setting "ignoreChangeIdProtection" to true.

{
  "requestId": "1",
  "api": "db",
  "action": "updateRecords",
  "params": {
    "databaseName": "ctreeSQL",
    "ownerName": "admin",
    "tableName": "test1",
    "dataFormat": "objects",
    "ignoreChangeIdProtection": true,
    "fixedLengthCharFormat": "sql",
    "sourceData": [
      {
        "id": 1,
        "name": "new updated value"
      }
    ]
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 
 

Update test1 table using change protection

To successfully run this example, query the record, copy the latest value for "changeId", and update this code to use it. In this example, the changeId was taken from the first successful response example below.

{
  "requestId": "2",
  "api": "db",
  "action": "updateRecords",
  "params": {
    "databaseName": "ctreeSQL",
    "ownerName": "admin",
    "tableName": "test1",
    "dataFormat": "objects",
    "fixedLengthCharFormat": "sql",
    "sourceData": [
      {
        "id": 1,
        "changeId": 1295300,
        "name": "updated"
      }
    ]
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 
 

Update all_types table ignoring change protection

{
  "requestId": "3",
  "api": "db",
  "action": "updateRecords",
  "params": {
    "databaseName": "ctreeSQL",
    "ownerName": "admin",
    "tableName": "all_types",
    "dataFormat": "objects",
    "binaryFormat": "hex",
    "variantFormat": "variantObject",
    "ignoreChangeIdProtection": true,
    "fixedLengthCharFormat": "sql",
    "sourceData": [
      {
        "id": 1,
        "_bookmark_": "00000001",
        "nested_json_object_or_array": {
          "updated": "record"
        },
        "variable_string_up_to_max65500bytes": "updated value"
      }
    ]
  },
  "responseOptions": {
    "binaryFormat": "hex",
    "dataFormat": "objects",
    "numberFormat": "string",
    "variantFormat": "variantObject"
  },
  "apiVersion": "1.0",
  "debug": "max",
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 
 

 

Response examples

Failed update due to mismatched "changeId" values

{
  "errorCode": 1192,
  "errorMessage": "Cannot write the record while updating record with id 2 because the 'changeId' change Id field does not match",
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 
 

Failed update when record with "id": 9999 does not exist

{
  "errorCode": 101,
  "errorMessage": "record not found updating record with 'id' :999",
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 
 

Successfully update test1 table

The "changeId" field returned in the result is important. This value or a more current value must be included in the next update to ensure no other process has changed the record in the interim.

{
  "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": 1295300,
        "id": 1,
        "name": "new updated value"
      }
    ],
    "primaryKeyFields": [
      "id"
    ],
    "changeIdField": "changeId"
  },
  "requestId": "1",
  "errorCode": 0,
  "errorMessage": "",
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 
 

Successfully update 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": "1299331",
        "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": {
          "updated": "record"
        },
        "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": "updated value"
      }
    ],
    "primaryKeyFields": [
      "id"
    ],
    "changeIdField": "changeId"
  },
  "requestId": "3",
  "debugInfo": {
    "request": {
      "api": "db",
      "action": "updateRecords",
      "params": {
        "databaseName": "ctreeSQL",
        "ownerName": "admin",
        "tableName": "all_types",
        "dataFormat": "objects",
        "binaryFormat": "hex",
        "variantFormat": "variantObject",
        "ignoreChangeIdProtection": true,
        "sourceData": [
          {
            "id": 1,
            "nested_json_object_or_array": {
              "updated": "record"
            },
            "variable_string_up_to_max65500bytes": "updated value"
          }
        ]
      },
      "apiVersion": "1.0",
      "requestId": "3",
      "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"
}
 
 

 

Properties

Request properties ("params")

Property Description Default Type Limits (inclusive)

binaryFormat

 The "binaryFormat" property designates the format of binary values embedded in JSON strings. For more details, see "binaryFormat".  Optional with default of "hex" string One of the following: "base64", "hex", or "byteArray".

databaseName

The "databaseName" property specifies the database that contains an object, such as a table or code package. If it is set to null or is omitted, it defaults to the default database of the JSON Action session, see "createSession" and the "defaultDatabaseName" property. 

You specify this property when you want to use a different database instead of the default. Your session's account must have the appropriate privileges to access the code package.

This property is useful because objects, such as tables and code packages, can have the same name in multiple databases. This feature allows you to create multiple environments in the same server and reuse the same JSON actions in each environment. For example, you can create "dev", "test", "stage", and "prod" databases on the same server and use the "defaultDatabaseName" or "databaseName" properties to specify the desired environment.

It is an error to set "databaseName" to the empty string "".

If no default database is specified during "createSession", the server sets the "defaultDatabaseName" to the "defaultDatabaseName" value specified in the services.json file.

 Defaults to the session's "defaultDatabaseName" property string 1 to 64 bytes

dataFormat

The "dataFormat" property 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.
 Optional with default of "arrays" string

"default"

"arrays"

"objects"

fixedLengthCharFormat

The "fixedLengthCharFormat" property controls how the "getRecords" actions return values from fields with the "char" data type (CT_FSTRING), which is FairCom's fixed-length string field. It does not apply to other field types, such as "varchar", "lvarchar", "binary", "varbinary", and "lvarbinary".

 

For more details, see "fixedLengthCharFormat". 

 Optional with default "sql" string

"sql"

"trimTrailingSpaces"

"trimTrailingPadding"

ignoreChangeIdProtection

The "ignoreChangeIdProtection" property causes the server to update the record regardless of the value of "changeId", when "true". 

  • Ignoring the "changeId" field is useful when a process wants to ensure its changes are always applied to a record.
  • However, ignoring the "changeId" field can cause an update to overwrite changes made by other processes. So, setting "ignoreChangeIdProtection" property to true is not recommended when an application reads a record so that a user can update it.
  • It is a best practice to read the record, let the user change values, and update the record using the same "changeId" value that was read.
  • If another process has changed the record in the interim, the server will not update the record and will return error 32602 indicating a missing "changeId" field or return error 1192 because the "changeId" value that was passed in matches the "changeId" value in the record.
 Optional with default of false Boolean

true

false

ownerName

The "ownerName" property specifies the account that owns an object, such as a table or code package. See "createSession" and the "defaultOwnerName" property for more details. 

You specify this property when you want to use a different account instead of the default. Your session's account must have the appropriate privileges to access the code package. 

This property is useful because objects, such as tables and code packages, can have the same name in the same database as long as different accounts own each object. This feature allows you to create duplicate objects for different users on the same server and reuse the same JSON actions on those objects. For example, an administrator can copy objects from a production environment to her account so she can troubleshoot an issue using the same JSON actions, JavaScript, and SQL code.

It is an error to set "ownerName" to the empty string "".

If no default owner is specified during "createSession", the server sets the "defaultOwnerName" to the "defaultOwnerName" value specified in the services.json file.

 Optional with default of the session's "defaultOwnerName" property string 1 to 64 bytes

sourceData

 The "sourceData" property contains source data for an insert or update operation Optional with default of [] array An array of arrays or an array of objects

tableName

The "tableName" property contains the unique, user-defined name of a table.

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

 

"params": {
  "tableName": "ctreeTable"
}
 Required - No default value string 1 to 64 bytes

variantFormat

 The "variantFormat" property tells the server how to interpret the variant data included in a JSON Action request. For more details, see "variantFormat". Optional with default of "json" string

"json"

"binary"

"string"

"variantObject"

 

Response properties ("result")

Property Description Type Limits (inclusive)

binaryFormat

 The "binaryFormat" property designates the format of binary values embedded in JSON strings. See binaryFormat for more details.  string One of the following: "base64", "hex", or "byteArray".

changeIdField

This property's value designates the name of the field used for change-tracking functionality if you are not using the "changeId" field for change tracking.

"createTable" automatically creates the "changeId" field to hold the change tracking number used for optimistic locking. Using the "changeId" field for optimistic locking is a best practice.

However, if you use the name "changeId" for another purpose, you can use the "changeIdField" property to designate a different field as the change tracking number field.

 string 1 to 64 bytes

data

The "data" property contains a response message. Its contents are defined by the action. It is an empty array when no results are available. The following is an example of the data property from a code package action.

  "result": {
    "data": [
      {
        "codeId": 6,
        "databaseName": "faircom",
        "ownerName": "admin",
        "codeName": "convertAndCategorizeTemperature",
        "codeVersion": 1,
        "clonedCodeId": 1,
        "codeStatus": "active",
        "codeLanguage": "javascript",
        "serviceName": "javascript",
        "codeType": "module",
        "description": "optional new description",
        "metadata": {},
        "createdBy": "ADMIN",
        "createdOn": "2025-08-25T21:48:38.109",
        "updatedBy": "ADMIN",
        "updatedOn": "2025-08-25T21:48:38.109",
        "comment": "Cloned from convertTemperature",
        "codeFormat": "utf8"
      },
    ]
 array of objects The action determines its contents.

data

.changeId

 The "changeId" property specifies a unique, server-generated id. When this property is present, the database compares the value of "changeId" to the current transaction number stored in the "changeId" field of the record. This ensures an update does not modify a record that has subsequently been modified by another operation.  integer No limit

data

.id

The "id" property is the unique identifier of an object such as a label or thing. In JSON, you may use an integer number or a string containing an integer number. The server automatically generates the "id" when you create a label and stores it in the label table as an integer. You cannot alter the "id" value. If your application needs to specify a specific numeric identifier for a label, use the "enum" property.

 integer

0 to 2147483647

0 to 9223372036854770000 in the Thing API 

data

.name

The "name" property is the name of a label or field. 

The "group" and "name" properties combined uniquely identify each label. The "createLabel" and "alterLabel" actions return an error if the "group" and "name" properties do not create a unique label name.

The "id" property also uniquely identifies each label so you can rename a label's group and name without breaking "id" references to the label.

 

 string 1 to 64 bytes

dataFormat

The "dataFormat" property (case-insensitive) defines the format of the "data" property. The default for "dataFormat" can be changed during a "createSession" action by assigning a different value to the "dataFormat" property in "defaultResponseOptions".

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

"autoDetect"

"arrays"

"objects"

fields

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

 

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

"autoTimestamp"

"autoValue"

"primaryKey"
"name"
"type"
"length"
"scale"
"defaultValue"
"nullable"

 

updateRecords and deleteRecords only: 

"bookmark"

fields

.autoValue

 The "autoValue" property indicates when and how the server automatically sets the field value. See autoValue for more details.  string

"none"

"incrementOnInsert"

"timestampOnInser"

"timestampOnUpdate"

"timestampOnUpdateAndInsert"

"changeid"

 

Some actions only:

"bookmark"

fields

.defaultValue

 The "defaultValue" property specifies the field's default value. string 0 to 65,500 bytes

fields

.length

 The "length" property identifies the length of the field. integer 1 to 65500 

fields

.name

The "name" property is the name of a label or field. 

The "group" and "name" properties combined uniquely identify each label. The "createLabel" and "alterLabel" actions return an error if the "group" and "name" properties do not create a unique label name.

The "id" property also uniquely identifies each label so you can rename a label's group and name without breaking "id" references to the label.

 string 1 to 64 bytes

fields

.nullable

 The "nullable" property identifies whether a field can contain a NULL value. Boolean

true

false

fields

.primaryKey

The "primaryKey" property identifies a table's primary key. For more details, see "primaryKey".

 integer 0 to 32

fields

.scale

The "scale" property specifies the number of fixed decimal places to the right of the decimal point. Its value must always be less than or equal to the field's length. It is required only for the "number" and "money" data types because they require fixed precision. It is ignored for all other data types. See also Data types. The scale 

The value of "scale" must be an integer from 0 to the number of digits specified by the "length" property. 

A scale of 0 creates an integer number. A scale equal to the length creates a number that can only have a fractional value.

The "money" field type must have a scale of 2 or 4. The default is 4.

You may optionally use the "length" property to specify fewer than 32 total digits to limit the total number of digits available to the number. A length limit reduces the maximum size of the scale. For example, a length of 3 allows the scale of a "number" to be 0, 1, 2, or 3. 

Example numbers allowed in "number" and "money" field types with a length of 4 and a scale from 0 to 4.

 

Request Example

Create a table that contains all field types that use the "scale" property.

"fields": [
  {
    "name": "j",
    "type": "number",
    "scale": 32
  },
  {
    "name": "k",
    "type": "number",
    "scale": 4
  }


],
 integer 0 to 32

fields

.type

The "type" property specifies the field's data type. See Data types for the limits, valid values, and whether "length" and "scale" are required.

 

Request example

"fields": [
  {
    "name": "j",
    "type": "number"
  }
]
 string

"json"

"bit"

"tinyint"

"smallint"

"integer"

"bigint"

"real"

"float"

"number"

"money"

"date"

"time"

"timestamp"

"char"

"varchar"

"lvarchar"

"binary"

"varbinary"

"lvarbinary"

primaryKeyFields

 The "primaryKeyFields" property specifies the fields to use for the table’s primary key. For more details, see "primaryKeyFields". array of strings ["field1", …,"fieldN"]

Was this article helpful?

Give feedback about this article

Related Articles