rebuildTables

JSON DB "rebuildTables" action rebuilds specified tables

  • "rebuildTables" executes the rebuild on each table in the order they are specified, so if an error occurs, all tables before the table causing the error are rebuilt, and tables following the table causing the error are not.
  • This action is not transactional.
  • As many tables as possible in the list are rebuilt.
  • A failure to rebuild one or more tables does not stop others from being rebuilt.
  • If a table contains many records, the rebuild process may take a while.

 

Request examples

Minimal

{
  "action": "rebuildTables",
  "params": {
    "tableNames": [
      "test1"
    ]
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 
 

Maximal

{
  "api": "db",
  "action": "rebuildTables",
  "params": {
    "databaseName": "ctreeSQL",
    "ownerName": "admin",
    "tableNames": [
      "test1"
    ],
    "transactionId": null
  },
  "responseOptions": {
    "binaryFormat": "hex",
    "dataFormat": "objects",
    "numberFormat": "string"
  },
  "authToken": "replaceWithAuthTokenFromCreateSession",
  "apiVersion": "1.0",
  "requestId": "00000003",
  "debug": "max"
}

 

 
 

 

Response examples

Minimal

{
  "result": {
    "dataFormat": "objects",
    "data": [
      {
        "changeIdField": "changeId",
        "createRecByteIndex": false,
        "databaseName": "ctreeSQL",
        "fieldDelimiterValue": 0,
        "fields": [
          {
            "autoValue": "incrementOnInsert",
            "defaultValue": null,
            "length": null,
            "name": "id",
            "nullable": false,
            "primaryKey": 1,
            "scale": null,
            "type": "bigint"
          },
          {
            "autoValue": "changeId",
            "defaultValue": null,
            "length": null,
            "name": "changeId",
            "nullable": true,
            "primaryKey": 0,
            "scale": null,
            "type": "bigint"
          },
          {
            "autoValue": "none",
            "defaultValue": null,
            "length": 50,
            "name": "name",
            "nullable": true,
            "primaryKey": 0,
            "scale": null,
            "type": "varchar"
          }
        ],
        "folder": ".\\ctreeSQL.dbs",
        "growthExtent": 0,
        "indexFileExtension": ".idx",
        "indexes": [
          {
            "collectStats": false,
            "compression": "off",
            "conditionalExpression": null,
            "databaseName": "ctreeSQL",
            "deferIndexing": false,
            "fields": [
              {
                "caseInsensitive": false,
                "name": "id",
                "reverseCompare": false,
                "sortDescending": false
              }
            ],
            "filename": "admin_test1.idx",
            "immutableKeys": false,
            "indexName": "id_pk",
            "indexNumber": 0,
            "ownerName": "admin",
            "tableName": "test1",
            "unique": true
          }
        ],
        "ownerName": "admin",
        "padValue": 0,
        "path": ".\\ctreeSQL.dbs\\admin_test1.dat",
        "primaryKeyFields": [
          "id"
        ],
        "smallFile": false,
        "tableFileExtension": ".dat",
        "tableName": "test1",
        "totalRecordCount": 0,
        "transactionModel": "logTransactions",
        "uid": 1181
      }
    ]
  },
  "errorCode": 0,
  "errorMessage": "",
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 
 

Maximal

{
  "result": {
    "dataFormat": "objects",
    "data": [
      {
        "changeIdField": "changeId",
        "createRecByteIndex": false,
        "databaseName": "ctreeSQL",
        "fieldDelimiterValue": 0,
        "primaryIndexName": "id_pk",
        "fields": [
          {
            "autoValue": "incrementOnInsert",
            "defaultValue": null,
            "length": null,
            "name": "id",
            "nullable": false,
            "primaryKey": 1,
            "scale": null,
            "type": "bigint"
          },
          {
            "autoValue": "changeId",
            "defaultValue": null,
            "length": null,
            "name": "changeId",
            "nullable": true,
            "primaryKey": 0,
            "scale": null,
            "type": "bigint"
          },
          {
            "autoValue": "none",
            "defaultValue": null,
            "length": 50,
            "name": "name",
            "nullable": true,
            "primaryKey": 0,
            "scale": null,
            "type": "varchar"
          }
        ],
        "folder": ".\\ctreeSQL.dbs",
        "growthExtent": 0,
        "indexFileExtension": ".idx",
        "indexes": [
          {
            "indexName": "id_pk",
            "primaryIndex": "true", 
            "collectStats": false,
            "compression": "off",
            "conditionalExpression": null,
            "databaseName": "ctreeSQL",
            "deferIndexing": false,
            "fields": [
              {
                "caseInsensitive": false,
                "name": "id",
                "reverseCompare": false,
                "sortDescending": false
              }
            ],
            "filename": "admin_test1.idx",
            "immutableKeys": false,
            "indexName": "id_pk",
            "indexNumber": 0,
            "ownerName": "admin",
            "tableName": "test1",
            "unique": true
          }
        ],
        "ownerName": "admin",
        "padValue": 0,
        "path": ".\\ctreeSQL.dbs\\admin_test1.dat",
        "primaryKeyFields": [
          "id"
        ],
        "smallFile": false,
        "tableFileExtension": ".dat",
        "tableName": "test1",
        "totalRecordCount": 0,
        "transactionModel": "logTransactions",
        "uid": 1181
      }
    ]
  },
  "requestId": "2",
  "debugInfo": {
    "request": {
      "api": "db",
      "action": "rebuildTables",
      "params": {
        "databaseName": "ctreeSQL",
        "ownerName": "admin",
        "tableNames": [
          "test1"
        ]
      },
      "apiVersion": "1.0",
      "requestId": "2",
      "responseOptions": {
        "dataFormat": "objects"
      },
      "debug": "max",
      "authToken": "replaceWithAuthTokenFromCreateSession"
    },
    "serverSuppliedValues": {
      "databaseName": "ctreeSQL",
      "ownerName": "admin"
    },
    "errorData": {
      "errorData": null
    },
    "warnings": []
  },
  "errorCode": 0,
  "errorMessage": "",
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 
 

 

Troubleshooting errors

You cannot modify a table while it is in use. When a table has no activity for a default of 2 seconds, it will be closed so you can modify it.

  • When a table is in use, the following actions return an error, such as -8 or 4012:
    • "alterTable"
    • "rebuildTables"
    • "deleteTables"
    • "createIndex"
    • "deleteIndexes"
    • "rebuildIndexes"
    • "runSqlStatements"
  • A table is in use when any account is performing one or more of the following actions with the table:
    • "insertRecords"
    • "updateRecords"
    • "deleteRecords"
    • "truncateRecords"
    • "getRecords..."
    • Has open cursors on the table.
    • Has open transactions on the table (such "createTransaction").
  • Modify the SQL_IDLE_WAKE startup configuration setting to change the number of seconds the server waits before closing a table. A larger number keeps the table open longer for better performance. A smaller number allows you to modify the table sooner.
  • Modify the SQL_IDLE_WAKE startup configuration setting to change the number of tables the server keeps open after they are no longer being actively used. A larger number caches more tables and improves performance. A smaller number allows you to modify tables sooner.

 

Request properties ("params")

Property Description Default Type Limits (inclusive)

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

tableName

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

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

 

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

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. 

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

transactionId

 The "transactionId" property identifies a transaction in which the specified action will be included. Optional with default of "" string 0 to 255 bytes

 

Response properties ("result")

Property Description Type Limits (inclusive)

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"

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

.changeIdField

The "changeIdField" property specifies the name of the field used for the change-tracking functionality.

If the table already has a change-tracking field, this new field is now used instead for change-tracking.

 string 1 to 64 bytes

data

.createRecByteIndex

The "createRecByteIndex" property creates a special index for quickly walking variable-length records backward when set to true. 

Note It is not needed for fixed-length records.

 Boolean

true

false

data

.databaseName

The "databaseName" property specifies the database that contains the tables. 

Note In the API Explorer, "defaultDatabaseName" is set to "ctreeSQL" in the "createSession" action that happens at login.

  • 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.
  • This property's value is case insensitive. 
 string 1 to 64 bytes

data

.fieldDelimiterValue

The "fieldDelimiterValue" property should only be changed for backward compatibility with legacy c-tree files.

Note Do not set this value without first contacting FairCom customer support.

 integer 0 to 255

data

.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,
    "primaryKey": 0, 
    "autoValue": "none"
  }
]
 array

"autoTimestamp"

"autoValue"

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

"primaryKey"

"autoValue"

 

updateRecords and deleteRecords only: 

“bookmark”

data

.fields

.defaultValue

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

data

.fields

.length

 Identifies the length of the field. integer 1 to 65500 

data

.fields

.name

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

The "group" and "name" properties combined uniquely identify each label. 

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

data

.fields

.nullable

 “nullable” identifies whether a field can contain a NULL value. Boolean

true

false

data

.fields

.primaryKey

 When > 0, the "primaryKey" property identifies the ordinal position of the field within the table's primary key. integer 0 to 32

data

.indexes

.fields

.caseInsensitive

The "caseInsensitive" property determines if case comparisons for index key values accounts for case. When false, the server stores index key values in mixed case for comparisons.

When true, case comparisons are case-insensitive, and the server stores index key values in upper case for comparisons.

"fields": [
  {
    "caseInsensitive": true
  }
]
 Boolean

true

false

data

.indexes

.fields

.reverseCompare

The "reverseCompare" property specifies whether the bytes in an index key field are compared starting from the beginning to the end of the key.

When true, bytes in an index key field are compared starting from the end to the beginning of the key. This speeds comparisons when the unique parts of the bytes are at the end of keys.

"fields": [
  {
    "reverseCompare": true
  }
]
 Boolean

true

false

data

.indexes

.fields

.sortDescending

The "sortDescending" property sorts the returned sessions in descending order based on the last time the sessions connected or disconnected, the sessions' "clientName" properties, or the sessions' IP addresses.

"fields": [
  {
    "sortDescending": true
  }
]
 Optional with default of false Boolean

data

.fields

.scale

 If the type is "number" or "money", the "scale" property identifies the number of places to the right of the decimal point,. integer 0 to 32

data

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

data

.folder

The "folder" property defines the file system folder where an item will be stored. 

Important If it is a zero-length string, the server chooses its own folder; otherwise, it uses this folder.

 string 0 to 2,048 bytes

data

.growthExtent

The "growthExtent" property specifies the number of bytes that a server uses to increase a file's size. 

  • A file is extended when adding or updating a record, which requires the file to grow larger.
  • Use a larger number to minimize the number of times a file needs to be extended.
  • Use a smaller number to minimize the amount of unused space in a file.
 integer 0 to 2147483647

data

.indexFileExtension

The "indexFileExtension" property specifies the file system extension to use for a table's index files. If omitted, it defaults to ".idx".

Note If set to a zero-length string, then newly created index files will have no extension.

 string 0 to 64 bytes

data

.indexes

.collectstats

 The “collectStats” property identifies whether usage statistics are being collected and stored. boolean

true

false

data

.indexes

.compression

 The “compression” property identifies whether the index is compressed. string

"on"

"off"

"auto"

data

.indexes

.conditionalExpression

 The “conditionalExpression” property identifies an optional conditional expression that filters which records are included in the index. It is null when there is no conditional expression. string

null

or a string containing a conditional expression.

data

.indexes

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

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.

 string 1 to 64 bytes

data

.indexes

.deferIndexing

 “deferindexing” identifies whether deferred indexing is enabled. A deferred index builds and updates asynchronously. This speeds up inserts, updates, and deletes, with a slight delay due to the changes being included in the index. boolean

true

false

data

.indexes

.filename

The "filename" property contains the name of the index file on the file system. 

  • When creating a file, specify a non-zero-length string to assign the file to a specific location in the file system.
  • The file name may include an absolute or relative path.
  • If the filename is omitted or is a zero-length string, the server defines its own path and name for the file.
  • If "filename" is not specified, the index will be added to the existing index file.
  • The server adds the "indexFileExtension" property to the end of the filename.
 string 0 to 2048 bytes

data

.indexes

.immutableKeys

 "immutableKeys" indicates whether a key's value can be changed. boolean

true

false

data

.indexes

.indexName

 The "indexName" property specifies the name of an index. A zero-length "indexName" is invalid. string 1 to 64 bytes

data

.indexes

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

 string 1 to 64 bytes

data

.indexes

.tableName

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

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

 string 1 to 64 bytes

data

.indexes

.unique

 The "unique" property causes the "createIndex" action to create a unique index, which requires the columns in the index to have a unique value for each record in the table, when set to true.  Boolean

true

false

data

.ownerName

 The "ownerName" property identifies the user who owns an object (see Object owner).  string 0 to 64 bytes

data

.padValue

The "padValue" property is used by the server as a byte value to pad all "char" and "binary" fields in a table when the contents of these fixed-length fields is shorter than the field size.

All fixed-length fields in a table are padded with the same pad value. For more details, see "padValue".

 integer 0 to 255

data

.path

 The "path" property identifies the path of the database folder. For more details, see "path". string 0 to 2,048 bytes

data

.primaryKeyFields

This property specifies the fields of the table’s primary key when multiple fields are combined to form the primary key.

Note The best practice is not to use the "primaryKeyFields" or "primaryKey" properties, so the "createTable" action will automatically create a primary key field named "id" with a unique index named "id_pk".

The order of fields in this property is the order of fields in the primary key index. The "fields" property contains the name and type of each field that is specified in the "primaryKeyFields" array. 

A primary key with multiple fields has an index named "pk". If you specify just one field, the index is named "<fieldname>_pk".

If only one field is used as the primary key, the "primaryKey" property defines the primary key.

Note The "primaryKeyFields" and "primaryKey" properties cannot be used together.

 

Example

"primaryKeyFields": [
  "a",
  "b",
  "c"
],
"fields": [
  {
    "name": "a",
    "type": "tinyint"
  },
  {
    "name": "b",
    "type": "smallint"
  },
  {
    "name": "c",
    "type": "integer"
  }
]
 array an array

data

.smallFile

The "smallFile" causes a table to be optimized for data files that cannot grow larger than 4 GB when set to true.

Note Small data files are faster and more efficient than huge files. They consume less disk space and less memory.

 Boolean

true

false

data

.tableFileExtension

The "tableFileExtension" property specifies the file system extension to use for a table's data files. 

Note If set to a zero-length string, then newly created data files will have no extension.

 string 0 to 64 bytes

data

.tableName

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

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

 string 1 to 64 bytes

data

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

-1 to 99999999999999999999999999999999

data

.transactionModel

The "transactionModel" property defines how the server processes transactions for a table. It is case-insensitive. 

Possible values:
  • "logTransactions"
    • This persists data to data files and writes transaction changes to transaction logs. It supports commit and rollback transactions and data replication. It will not lose data during an unplanned outage. It provides the most durability and the most capabilities, but is slower than the other settings.
  • "ramTransactions"
    • This supports commit and rollback transactions in RAM while persisting data to data files. It does not use a transaction log, which makes it even faster, but an unplanned outage may lose or corrupt unwritten data.
  • "noTransactions"
    • This does not support transactions but still persists data to disk, making it even faster. However, an unplanned outage may lose or corrupt unwritten data
 string

"logTransactions"

"ramTransactions"

"noTransactions"

Was this article helpful?

Give feedback about this article

Related Articles