`"getRecordsByIds"` (JSON Action)

JSON DB `"getRecordsByIds"` action retrieves records from a database table using their IDs

The "getRecordsByIds" action retrieves one or more records from a database table using their IDs. The response message contains one record for each ID specified in the "id" array.

Essential information

A table must have a primary key or ID to retrieve records.
Tables created by the "createTable" action, automatically have an auto increment "id" field indexed as a primary key.
Tables created by other APIs may not have an "id" field; instead, they may have a primary key index that includes one or more fields in the table.
The "getRecordsByIds" action provides an optional "primaryKeys" property that can retrieve records using any primary key index.
The "primaryKeys" property:
- can be used to retrieve one or more records from a database table using primary key identifiers
- is required if "id" is omitted
- is "null" if using "ids"
The "id" property:
- is required if "primaryKeys" is omitted and supplied by the client to uniquely identify each request
- is "null" if using the "primaryKeys" property
- is the client's message identifier and should be a string containing a value that is unique to the client
- may also be a number, array, or object (this is discouraged)
In asynchronous protocols, such as MQTT, "getRecordsByIds" enables the client to associate response messages with the original request messages since the server adds this property (with the client's value) to each response message.
JSON DB API sends a response message with an error if "id" is missing or null. Although jsonAction allows the "id" to be null or omitted, JSON DB API does not.
The server includes the "id" in reply messages using the exact value and data type that the client supplied in the request. If the client sends a string, the server replies with the identical string. If it sends a number, the server replies with the identical number. This behavior is required by jsonAction. A string is preferred because it is the fastest and easiest for the server to return the identical value. If a number is used, it should be an integer to avoid differences in binary rounding behavior between the client and the server.
The "id" should be unique from the client's perspective. From the server's perspective, the true unique "id" of a request-response message pair is the combination of the client id plus the server’s auth id for that client. The "id" will likely not be unique from the server's perspective since different clients can use the same "id" values).

Usage scenarios:

Retrieving one record by its ID
Loading a previously saved set of IDs to quickly retrieve a set of records
Using foreign key IDs to look up records

Performance considerations:

The fastest way to retrieve a specific record is to look it up by its ID.
Results start to return more slowly as more records are requested.

Request examples

Arrays

{
  "api": "db",
  "action": "getRecordsByIds",
  "requestId": "1",
  "params": {
    "tableName": "athlete",
    "ids": [
      3
    ]
  },
  "responseOptions": {
    "dataFormat": "arrays"
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

`"primaryKeys"`

{
  "api": "db",
  "action": "getRecordsByIds",
  "requestId": "2",
  "params": {
    "databaseName": "ctreeSQL",
    "tableName": "athlete",
    "primaryKeys": [
      [
        {
          "fieldName": "id",
          "value": 3
        }
      ]
    ]
  },
  "responseOptions": {
    "dataFormat": "objects"
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

Return objects

{
  "api": "db",
  "apiVersion": "1.0",
  "requestId": "3",
  "action": "getRecordsByIds",
  "params": {
    "databaseName": "ctreeSQL",
    "ownerName": "admin",
    "tableName": "athlete",
    "ids": [
      6,
      2,
      4
    ]
  },
  "responseOptions": {
    "binaryFormat": "hex",
    "dataFormat": "objects",
    "numberFormat": "string",
    "includeFields": [],
    "excludeFields": []
  },
  "debug": "max",
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

Maximal

{
  "api": "db",
  "action": "getRecordsByIds",
  "requestId": "1",
  "params": {
    "databaseName": "ctreeSQL",
    "ownerName": "admin",
    "tableName": "athlete",
    "ids": [
      3
    ]
  },
  "responseOptions": {
    "dataFormat": "objects",
    "binaryFormat": "hex",
    "numberFormat": "string",
    "variantFormat": "variantObject",
    "includeFields": [
      "name",
      "ranking"
    ],
    "excludeFields": []
  },
  "debug": "max",
  "requestId": "3",
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

Response examples

Arrays

{
  "result": {
    "dataFormat": "arrays",
    "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": 30,
        "scale": null,
        "defaultValue": null,
        "nullable": true,
        "primaryKey": 0,
        "autoValue": "none"
      },
      {
        "name": "ranking",
        "type": "smallint",
        "length": null,
        "scale": null,
        "defaultValue": null,
        "nullable": false,
        "primaryKey": 0,
        "autoValue": "none"
      },
      {
        "name": "birthDate",
        "type": "date",
        "length": null,
        "scale": null,
        "defaultValue": null,
        "nullable": true,
        "primaryKey": 0,
        "autoValue": "none"
      },
      {
        "name": "playerNumber",
        "type": "number",
        "length": 32,
        "scale": 6,
        "defaultValue": null,
        "nullable": true,
        "primaryKey": 0,
        "autoValue": "none"
      },
      {
        "name": "livedPast2000",
        "type": "bit",
        "length": null,
        "scale": null,
        "defaultValue": null,
        "nullable": true,
        "primaryKey": 0,
        "autoValue": "none"
      },
      {
        "name": "earnings",
        "type": "money",
        "length": 32,
        "scale": 4,
        "defaultValue": null,
        "nullable": true,
        "primaryKey": 0,
        "autoValue": "none"
      },
      {
        "name": "favoriteSaying",
        "type": "varchar",
        "length": 500,
        "scale": null,
        "defaultValue": null,
        "nullable": true,
        "primaryKey": 0,
        "autoValue": "none"
      }
    ],
    "data": [
      [
        3,
        1291366,
        "Muhammad Ali",
        3,
        "1942-01-17",
        1,
        true,
        60000000,
        "Float like a butterfly, sting like a bee."
      ]
    ],
    "primaryKeyFields": [
      "id"
    ],
    "changeIdField": "changeId",
    "moreRecords": false,
    "requestedRecordCount": 0,
    "returnedRecordCount": 1,
    "totalRecordCount": 1
  },
  "requestId": "3",
  "debugInfo": {
    "request": {
      "api": "db",
      "action": "getRecordsByIds",
      "params": {
        "databaseName": "ctreeSQL",
        "tableName": "athlete",
        "primaryKeys": [
          [
            {
              "fieldName": "id",
              "value": 3
            }
          ]
        ]
      },
      "requestId": "2",
      "responseOptions": {
        "dataFormat": "arrays"
      },
      "debug": "max",
      "authToken": "replaceWithAuthTokenFromCreateSession"
    },
    "serverSuppliedValues": {
      "databaseName": "ctreeSQL",
      "ownerName": "admin"
    },
    "errorData": {
      "errorData": null
    },
    "warnings": []
  },
  "errorCode": 0,
  "errorMessage": "",
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

Objects

{
  "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": 30,
        "scale": null,
        "defaultValue": null,
        "nullable": true,
        "primaryKey": 0,
        "autoValue": "none"
      },
      {
        "name": "ranking",
        "type": "smallint",
        "length": null,
        "scale": null,
        "defaultValue": null,
        "nullable": false,
        "primaryKey": 0,
        "autoValue": "none"
      },
      {
        "name": "birthDate",
        "type": "date",
        "length": null,
        "scale": null,
        "defaultValue": null,
        "nullable": true,
        "primaryKey": 0,
        "autoValue": "none"
      },
      {
        "name": "playerNumber",
        "type": "number",
        "length": 32,
        "scale": 6,
        "defaultValue": null,
        "nullable": true,
        "primaryKey": 0,
        "autoValue": "none"
      },
      {
        "name": "livedPast2000",
        "type": "bit",
        "length": null,
        "scale": null,
        "defaultValue": null,
        "nullable": true,
        "primaryKey": 0,
        "autoValue": "none"
      },
      {
        "name": "earnings",
        "type": "money",
        "length": 32,
        "scale": 4,
        "defaultValue": null,
        "nullable": true,
        "primaryKey": 0,
        "autoValue": "none"
      },
      {
        "name": "favoriteSaying",
        "type": "varchar",
        "length": 500,
        "scale": null,
        "defaultValue": null,
        "nullable": true,
        "primaryKey": 0,
        "autoValue": "none"
      }
    ],
    "data": [
      {
        "birthDate": "1969-01-03",
        "changeId": "1291366",
        "earnings": "990000000",
        "favoriteSaying": "Once something is a passion, the motivation is there.",
        "id": "6",
        "livedPast2000": true,
        "name": "Michael Schumacher",
        "playerNumber": "1",
        "ranking": "6"
      },
      {
        "birthDate": "1895-02-06",
        "changeId": "1291366",
        "earnings": "800000",
        "favoriteSaying": "Every strike brings me closer to the next home run.",
        "id": "2",
        "livedPast2000": false,
        "name": "Babe Ruth",
        "playerNumber": "3",
        "ranking": "2"
      },
      {
        "birthDate": "1940-10-23",
        "changeId": "1291366",
        "earnings": "115000000",
        "favoriteSaying": "Everything is practice.",
        "id": "4",
        "livedPast2000": true,
        "name": "Pele",
        "playerNumber": "10",
        "ranking": "4"
      }
    ],
    "primaryKeyFields": [
      "id"
    ],
    "changeIdField": "changeId",
    "moreRecords": false,
    "requestedRecordCount": 3,
    "returnedRecordCount": 3,
    "totalRecordCount": 3
  },
  "requestId": "3",
  "debugInfo": {
    "request": {
      "api": "db",
      "action": "getRecordsByIds",
      "params": {
        "databaseName": "ctreeSQL",
        "ownerName": "admin",
        "tableName": "athlete",
        "ids": [
          6,
          2,
          4
        ]
      },
      "apiVersion": "1.0",
      "requestId": "3",
      "responseOptions": {
        "binaryFormat": "hex",
        "dataFormat": "objects",
        "numberFormat": "string",
        "includeFields": [],
        "excludeFields": []
      },
      "debug": "max",
      "authToken": "replaceWithAuthTokenFromCreateSession"
    },
    "serverSuppliedValues": {
      "databaseName": "ctreeSQL",
      "ownerName": "admin"
    },
    "errorData": {
      "errorData": null
    },
    "warnings": []
  },
  "errorCode": 0,
  "errorMessage": "",
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

Use the getRecordsByIds JSON API action to retrieve records from a database table using their IDs

API actionsJSON DB APIJSON Actionquery actionsget records by idsgetRecordsByIds

`"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)
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
ids	(optional) specifies a unique identifier for a row in a table. It is mutually exclusive with `"primaryKeys"`. Mutually exclusive with `primaryKeys`	`"null"` Required when `primaryKeys` is omitted.	array
ownerName	(optional) specifies the unique name of a schema in a database.	`""`	string	1 to 64 bytes
primaryKeys	(conditional) specifies values of the fields used to form a multi-field primary key. It is mutually exclusive with `"ids"`.	`"null"` Required when `ids` is omitted.	array of arrays
tableName	specifies the name of a table	Required - No default value	string	1 to 64 bytes
transformCodeName	(optional) specifies the name of a `"getRecordsTransform"` code package to transform the output of the `"getRecords..."` action	Optional name of a code package	string	The string must contain the name of an existing code package with a `"codeType"` of `"getRecordsTransform"`

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

`"ids"`

The "ids" property is an array. Each identifier in the array uniquely specifies a table row, indicating which records the action affects. Its default value is "null" but it is required if the "primaryKeys" property is "null" or not specified.

The "ids" property is mutually exclusive with the "primaryKeys" property meaning it is required when "primaryKeys" is omitted or an error is returned if both have values.
It is typically an array of integers ("ids": [1,3,5]).
It can be an array of an array of strings ("ids": ["9555444333222111","9555444333222112", "9555444333222113"]).
- A string "id" supports numbers larger than 9,007,199,254,740,991.
- This is the largest number supported by many programming languages and JSON parser implementations that use IEEE double-precision floats to hold numbers.
It can be the primary key value of another field in the table making it useful when your table is created by another API, such as SQL, that allows any field in the table to be the primary key.
If your table does not have an "id" field but uses a "vin" field as the primary key, you can use vin values to look up records ("ids": [ "4Y1SL65848Z411439", "1HGBH41JXMN109186" ]).
If your table uses more than one field as the primary key, you must use the "primaryKeys" property to look up records.
Tip
The "getRecordsByIds'' action uses a primary key index to look up records. A primary key index must be a unique, non-null index without conditional filtering. For best performance and maximum simplicity, create tables using the JSON DB API because it automatically creates an auto increment "id" field that is indexed as a primary key.

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

`"primaryKeys"`

The "primaryKeys" property is an array of arrays containing key-value pairs. The default value is ""null" ,but it is required if the "ids" property is omitted. It is used to specify search criteria and to show the results found.

"primaryKeys" is best used if tables were created with primary keys composed of multiple fields. If primary keys are composed of a single field, it is best to use "ids".
Note
Tables created using JSON DB API actions cannot create primary keys composed of multiple fields.
A table must have a primary key defined in order to use "primaryKeys"
The "primaryKeys" property is mutually exclusive with the "ids" property, meaning it is required when "ids" is omitted, or an error is returned if both have values.
The "primaryKeys" property is an array of arrays
- The outer array contains one or more primary key definitions, enabling the server to retrieve multiple records simultaneously.
- Each inner array is a primary key definition that specifies the values the server needs to retrieve one matching record.
- A primary key definition consists of one or more objects where each object is a field-value pair that uses the following structure ({ "fieldName": "someField","value": "someValue" }).

Example

If your table uses the "first_name" and "last_name" fields as the primary key, the following "primaryKeys" property will retrieve two records.

Note

If your table does not have a primary key, its records cannot be retrieved, updated or deleted using the "getRecordsByIds", "updateRecords" and "deleteRecords" actions. Other getRecords actions can query its records.

   "primaryKeys": 
    [ 
      [
        { "fieldName": "first_name", "value": "Sam" },
        { "fieldName": "last_name",  "value": "I-am" }
      ],
      [
        { "fieldName": "first_name", "value": "The Cat" },
        { "fieldName": "last_name",  "value": "in the Hat" }
      ]
    ]

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

`"transformCodeName"`

The "transformCodeName" property is an optional string that specifies the name of an existing code package with a "codeType" of "getRecordsTransform".

When this property is present in a "getRecords..." transform, the server passes the query results to the code package as an array of objects. The code transforms the records and returns a valid JSON value. The server places the value in the "data" property of the response to the "getRecords..." action.

`"responseOptions"`

The "responseOptions" property is an optional object that configures the server to return a customized response.

None of these properties are required, but some are mutually exclusive:
- "includeFields" and "excludeFields" are mutually exclusive.
  Use "includeFields" or "excludeFields" to control which record fields are present in the data.
- "includePaths" and "excludePaths" are mutually exclusive.
  Use "includePaths" or "excludePaths" to control which JSON properties are included in the data.
A JSON path includes the JSON field name plus the path of the property within the JSON field.
Use "omit" to remove a property from a response, such as omitting "errorMessage".
Use "dataFormat" to control whether data comes back as an array of arrays or an array of objects.
Use "numberFormat" to control whether JSON numbers are rendered as digits or digits embedded in a string.
Use "variantFormat" to control how the server formats the values of variant fields in its response.

    "responseOptions": 
    { 
     "omit": ["error", "fieldDefs" ]
     "dataFormat": "arrays", 
     "numberFormat": "number",
     "includeFields": [ "name", "email" ],
     "excludeFields": [],
     "includePaths": [],
     "excludePaths": [ "email.domain" ],
     "binaryFormat": "base64",
     "variantFormat": "json"
    }

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

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

The "binaryFormat" property designates the formatof binary values embedded in JSON strings. The default value for "binaryFormat" is the "defaultBinaryFormat" defined in the "createSession" or "alterSession" actions. If it is omitted there, it defaults to the value of the "defaultBinaryFormat" property in the <faircom>/config/services.json file. If it is not there, the FairCom server defaults it to "hex". Prior to version 13.0.4, the server defaulted it to "base64".

Note

Typically, response options apply only to the server’s response, but the "binaryFormat" property applies to both the request and the response.

The "binaryFormat" property may occur inside "params", "responseOptions", "defaultResponseOptions" , "result", and "mapOfPropertiesToFields".
- It occurs in "params" when actions create or change values.
- It occurs in "responseOptions" when actions return values.
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.
When "binaryFormat" occurs in "mapOfPropertiesToFields", it tells the server how to encode or decode the binary value in a JSON property.
For example, including "binaryFormat" in a "tableFieldsToJson" transform step controls how the server takes a raw binary field value and encodes it as a JSON property.
For example, including "binaryFormat" in a "jsonToTableFields" or "jsonToDifferentTableFields" transform step controls how the server decodes a binary value in a JSON property so it can store the raw binary value in a field.
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 ]

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

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

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

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

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

Note

Our examples insert only 3 bytes into "bin". Because the "bin" field has a fixed length of 5 bytes, the server pads unused bytes with 0x00 and stores the result. When a record is retrieved, the server returns all 5 bytes.

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

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

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

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

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

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

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

`"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 server applies the "variantFormat" property to all variant fields affected by a JSON action, such as all variant fields inserted by the "insertRecord" action or all variant fields returned by the "getRecordsByIndex" action. If you want more control, set the "variantFormat" property to "variantObject" and you can use variant objects to independently set the variant type and encoding of each variant field in a JSON action.

A variant field is a flexible, strongly-typed field. It is flexible because each variant field in each record can store any type of data. It is strongly typed because each variant field in each record stores the type of value it contains.

A variant field's type can currently be set to "binary", "json", "string", and "boolean" values. In the future, you will be able to set it to other values, such as "jpeg", "xml", and user-defined types.

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

"variantFormat": "binary"

Use the "variantFormat": "binary" setting to store and return variant field values as binary values embedded in JSON strings.
The "binary" variant type ensures maximum compatibility and performance across all FairCom APIs, including JSON DB, SQL, CTDB, and ISAM.
When "variantFormat" is "binary", the server sets the variant's type to "binary" and stores raw bytes in the variant field.
The binary value can be any sequence of bytes.
The server does not validate the binary value.
The "binaryFormat" property specifies how the client and server format binary value. For example, the "hex" value embeds hexadecimal numbers in a JSON string.

"variantFormat": "json"

Use the "variantFormat": "json" setting to store and return variant field values as JSON values.
The "json" variant type provides maximum convenience in FairCom's JSON APIs.
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.
- 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 containing embedded numbers. All languages and JSON parsers work well with strings containing embedded numbers – even extremely large and small numbers.
When "variantFormat" is "json", the server sets the variant's type to "json" and stores a JSON value in the variant field.
- 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.
- 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.
- 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.
- The server stores a JSON true and false in the variant field as is. It stores and returns the ASCII characters true or false.
- The server stores a JSON object and array as is. When it validates the JSON, it minimizes whitespace while preserving the ASCII characters representing the actual object or array. For example, the server stores the array [1,2,3] as the ASCII characters [1,2,3].

"variantFormat": "variantObject"

Use the "variantFormat": "variantObject" setting to store and return variant field values as a variant object.
The variant object defines everything the server and client need to know about a variant, including its type, value, value encoding, and storage encoding.
The "variantObject" variant type provides maximum flexibility across all FairCom APIs and programming languages.
A variant object is a JSON object containing the following properties: "schema", "value", "valueEncoding", and "type". The "schema" property must have the value "jsonaction.org/schemas/variantObject".
When "variantFormat" is "variantObject", the server parses the variant object and uses its properties to determine how to store the variant value.
- The "value" property contains the variant field's value .
- The "valueEncoding" property specifies how the value is encoded so the server and client can decode the value. For example, assigning "hex" to "valueEncoding" indicates the "value" property contains a binary value embedded in a string as hexadecimal characters. The server decodes the value before storing it in the variant field. In FairCom's JSON APIs, the "binaryFormat" property in the "responseOptions" object specifies how the server encodes the binary value before returning it.
- The "type" property specifies the variant's type, such as "json", "binary", and "string". In the future, the FairCom server will support additional types, such as "jpeg", "xml", and user-defined types.
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".

Add "binaryFormat": "base64" to "responseOptions" to tell the server to encode the variant value as Base64.

{
  "schema": "jsonaction.org/schemas/variantObject",
  "value": "ewogICJrZXkiOiAidmFsdWUiCn0=",
  "valueEncoding": ["base64"],
  "type": "binary"
}

Add "numberFormat": "string" to "responseOptions" to tell the server to embed the number in a string.

{
  "schema": "jsonaction.org/schemas/variantObject",
  "value": "123.45",
  "valueEncoding": ["string"],
  "type": "number"
}

Add "numberFormat": "number" to "responseOptions" to tell the server to encode the number as a JSON number.

{
  "schema": "jsonaction.org/schemas/variantObject",
  "value": 123.45,
  "type": "number"
}

{
  "schema": "jsonaction.org/schemas/variantObject",
  "value": true,
  "type": "boolean"
}

{
  "schema": "jsonaction.org/schemas/variantObject",
  "value": "A JSON string with embedded \" double quote.",
  "type": "string"
}

{
  "schema": "jsonaction.org/schemas/variantObject",
  "value": [1,"2",{"key": "value"}],
  "type": "json"
}

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

when no results are available, it is an empty array

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

fields

.autoValue

identifies when and how the server automatically sets the field value.

string

"none"

"incrementOnInsert"

"timestampOnInsert"

"timestampOnUpdate"

"timestampOnUpdateAndInsert"

"changeid"

fields

.defaultValue

(optional) identifies the default value of the field.

string

0 to 65,500 bytes

fields

.length

(optional) specifies the length of a field's value in a record.

integer

1 to 65500

fields

.name

identifies the name of the field.

string

0 to 64 bytes

fields

.nullable

(optional) identifies whether a field can contain a NULL value.

Boolean

true

false

fields

.primarykey

(optional) when > 0, identifies the ordinal position of the field within the table's primary key.

integer

0 to 32

fields

.scale

(conditional)specifies the number of places to the right of the decimal point.

integer

0 to 32

fields

.type

identifies the type of the field. See Data types.

string

"bit"

"tinyint"

"smallint"

"integer"

"bigint"

"real"

"float"

"number"

"money"

"date"

"time"

"timestamp"

"char"

"varchar"

"lvarchar"

"binary"

"varbinary"

"lvarbinary"

"json"

primaryKey

represents the order of the primary keys in the index

when primaryKey is 0, it means a field is not part of a primary key

integer

0 to 255

requestedRecordCount

details how many records were requested in the "getRecordsFromCursor" action to determine if fewer records were returned than were requested

integer

0 to 2147483647

returnedRecordCount

details how many records were returned from the "getRecordsFromCursor" action to determine if fewer records were returned than were requested

integer

0 to 2147483647

totalRecordCount

specifies an integer, the server sets its value to the number of records returned by a query

integer

-1 to 99999999999999999999999999999999

`"autoValue"`

This optional property indicates when and how the server automatically sets the field value.

Only one of these values is allowed per field.

"none" indicates that the server does not automatically set the field's value.
"incrementOnInsert" indicates that the server automatically increments a field’s value each time the server inserts a new record. It applies to fields that are of the type of decimal or one of the integer types, such as "bigint". Only one field per table can have this attribute. The server returns an error when assigning this attribute to multiple fields. The JSON DB API automatically creates the "id" field as an "incrementOnInsert" field. If you apply this attribute to another field, it becomes the only automatically incremented field in the table. If you want that field to be the primary key, assign "primaryKey": 1 to it.
"timestampOnInsert" indicates that the server automatically sets a field’s value to the current date and time of an insert. It applies only to fields with a type of "timestamp".
Note
If you attempt to insert a record and specify a timestamp for a field that has "autoValue" set to "timestampOnInsert", the timestamp you specified is ignored, and the current date and time are assigned to the field.
"timestampOnUpdate" indicates that the server automatically sets a field’s value to the current date and time of an update. This setting applies only to timestamp fields.
"timestampOnUpdateAndInsert" indicates that the server automatically sets a field’s value to the current date and time of an insert and an update. It applies only to fields with a type of "timestamp".
"changeId" indicates the server uses the field for optimistic locking. The server automatically sets the field's value to the internal transaction number used during the last update of the record. This value changes each time the server updates the record. A table may only have one change tracking field. The field type must be "bigint".
The JSON DB API automatically creates a "changeid" field with change-tracking functionality.
Change tracking is optional in the CTDB and ISAM APIs. The application must create a 64-bit integer field and assign change-tracking functionality to it.

Request Example

"fields": [
  {
    "name": "signed_int32",
    "type": "integer",
    "autoValue": "incrementOnInsert"
  }
]

Response Example

{
  "result": {
    "dataFormat": "objects",
    "data": [
      {
        "changeIdField": "changeId",
        "createRecByteIndex": false,
        "databaseName": "ctreeSQL",
        "fieldDelimiterValue": 0,
        "fields": [
          {
            "autoValue": "incrementOnInsert",
            "defaultValue": null,
            "length": null,
            "name": "signed_int32",
            "nullable": true,
            "primaryKey": 0,
            "scale": null,
            "type": "integer"
          }
        ]
      }
    ]
  },
  "errorCode": 0,
  "errorMessage": "",
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

`"binaryFormat"`

Note

Typically, response options apply only to the server’s response, but the "binaryFormat" property applies to both the request and the response.

The "binaryFormat" property may occur inside "params", "responseOptions", "defaultResponseOptions" , "result", and "mapOfPropertiesToFields".
- It occurs in "params" when actions create or change values.
- It occurs in "responseOptions" when actions return values.
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.
When "binaryFormat" occurs in "mapOfPropertiesToFields", it tells the server how to encode or decode the binary value in a JSON property.
For example, including "binaryFormat" in a "tableFieldsToJson" transform step controls how the server takes a raw binary field value and encodes it as a JSON property.
For example, including "binaryFormat" in a "jsonToTableFields" or "jsonToDifferentTableFields" transform step controls how the server decodes a binary value in a JSON property so it can store the raw binary value in a field.
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 ]

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

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

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

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

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

Note

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

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

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

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

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

`"dataFormat"`

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

`"requestedRecordCount"`

The "requestedRecordCount" property is a signed, 32-bit integer set by the server in response to the "getRecordsFromCursor" method.

It makes it easy to know how many records were requested in the last call to "getRecordsFromCursor".
An application can use "requestedRecordCount" in conjunction with "returnedRecordCount" to determine if fewer records were returned than requested, which occurs when the cursor reaches the end of the recordset.

`"returnedRecordCount"`

The "returnedRecordCount" is a 32-bit integer set by the server in response to the "getRecordsFromCursor" method.

It makes it easy to know how many records were returned from the last call to "getRecordsFromCursor".
An application can use "returnedRecordCount" in conjunction with "requestedRecordCount" to determine if fewer records were returned than requested, which occurs when the cursor reaches the end of the recordset.

`totalRecordCount`

The "totalRecordCount" property contains the total available number of records that can be returned from a query.

The "totalRecordCount" is set to -1, when the server does not know the total record count.
A very fast way to get the total number of records in a table is to call the "getRecordsByTable" method without applying a "tableFilter". This immediately returns the count without reading and counting records.
For most methods, the server does not calculate "totalRecordCount" because calculating it requires walking all records in the query, which may take a significant amount of time.
When the result is returned as a cursor, "totalRecordCount" is the total number of records that the cursor can traverse.
Note
This does not apply to cursor responses.
When the result returns records directly, "totalRecordCount" is the total number of records that can be retrieved – not necessarily the number of records returned.

"getRecordsByIds" (JSON Action)

JSON DB "getRecordsByIds" action retrieves records from a database table using their IDs

Essential information

Request examples

Arrays

"primaryKeys"

Return objects

Maximal

Response examples

Arrays

Objects

Use the getRecordsByIds JSON API action to retrieve records from a database table using their IDs

"params"

"databaseName"

Note

"ids"

Tip

"ownerName"

"primaryKeys"

Note

Example

Note

"tableName"

"transformCodeName"

"responseOptions"

"binaryFormat"

Note

Note

"dataFormat"

"numberFormat"

"variantFormat"

"result"

"autoValue"

Note

"binaryFormat"

Note

Note

"dataFormat"

"fields"

Example

"requestedRecordCount"

"returnedRecordCount"

totalRecordCount

Note

`"getRecordsByIds"` (JSON Action)

JSON DB `"getRecordsByIds"` action retrieves records from a database table using their IDs

`"primaryKeys"`

`"params"`

`"databaseName"`

`"ids"`

`"ownerName"`

`"primaryKeys"`

`"tableName"`

`"transformCodeName"`

`"responseOptions"`

`"binaryFormat"`

`"dataFormat"`

`"numberFormat"`

`"variantFormat"`

`"result"`

`"autoValue"`

`"binaryFormat"`

`"dataFormat"`

`"fields"`

`"requestedRecordCount"`

`"returnedRecordCount"`

`totalRecordCount`