listTables

JSON DB "listTables" action lists tables in the specified database that the logged-in user is allowed to see

All available information about each table is listed.

 

Request examples

Minimal

{
  "action": "listTables",
  "params": {},
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 
 

Filter by partial table name

{
  "api": "db",
  "apiVersion": "1.0",
  "requestId": "2",
  "action": "listTables",
  "params": {
    "databaseName": "ctreeSQL",
    "partialTableName": "a"
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 
 

Filter by list table names

{
  "api": "db",
  "apiVersion": "1.0",
  "requestId": "3",
  "action": "listTables",
  "params": {
    "databaseName": "ctreeSQL",
    "tableNames": [
      "athlete",
      "test1"
    ]
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 
 

Paginate

{
  "api": "db",
  "apiVersion": "1.0",
  "requestId": "4",
  "action": "listTables",
  "params": {
    "databaseName": "ctreeSQL",
    "ownerName": "admin",
    "skipRecords": 1,
    "maxRecords": 3,
    "includeSystemTables": false
  },
  "debug": "max",
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 
 

 

Response examples

Minimal

{
  "result": {
    "dataFormat": "objects",
    "data": [
      {
        "databaseName": "ctreeSQL",
        "ownerName": "admin",
        "path": "./ctreeSQL.dbs",
        "tableName": "all_types",
        "totalRecordCount": -1,
        "uid": 1189
      },
      {
        "databaseName": "ctreeSQL",
        "ownerName": "admin",
        "path": ".\\ctreeSQL.dbs",
        "tableName": "athlete",
        "totalRecordCount": -1,
        "uid": 1185
      },
      {
        "databaseName": "ctreeSQL",
        "ownerName": "admin",
        "path": ".\\ctreeSQL.dbs",
        "tableName": "test1",
        "totalRecordCount": -1,
        "uid": 1181
      }
    ]
  },
  "errorCode": 0,
  "errorMessage": "",
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 
 

Filter by partial table name

{
  "result": {
    "dataFormat": "objects",
    "data": [
      {
        "databaseName": "ctreeSQL",
        "ownerName": "admin",
        "path": "./ctreeSQL.dbs",
        "tableName": "all_types",
        "totalRecordCount": -1,
        "uid": 1189
      },
      {
        "databaseName": "ctreeSQL",
        "ownerName": "admin",
        "path": ".\\ctreeSQL.dbs",
        "tableName": "athlete",
        "totalRecordCount": -1,
        "uid": 1185
      }
    ]
  },
  "requestId": "2",
  "errorCode": 0,
  "errorMessage": "",
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 
 

Filter by list table names

{
  "result": {
    "dataFormat": "objects",
    "data": [
      {
        "databaseName": "ctreeSQL",
        "ownerName": "admin",
        "path": ".\\ctreeSQL.dbs",
        "tableName": "athlete",
        "totalRecordCount": -1,
        "uid": 1185
      },
      {
        "databaseName": "ctreeSQL",
        "ownerName": "admin",
        "path": ".\\ctreeSQL.dbs",
        "tableName": "test1",
        "totalRecordCount": -1,
        "uid": 1181
      }
    ]
  },
  "requestId": "3",
  "errorCode": 0,
  "errorMessage": "",
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 
 

Paginate

{
  "result": {
    "dataFormat": "objects",
    "data": [
      {
        "databaseName": "ctreeSQL",
        "ownerName": "admin",
        "path": ".\\ctreeSQL.dbs",
        "tableName": "athlete",
        "totalRecordCount": -1,
        "uid": 1185
      },
      {
        "databaseName": "ctreeSQL",
        "ownerName": "admin",
        "path": ".\\ctreeSQL.dbs",
        "tableName": "test1",
        "totalRecordCount": -1,
        "uid": 1181
      }
    ]
  },
  "requestId": "4",
  "debugInfo": {
    "request": {
      "api": "db",
      "action": "listTables",
      "params": {
        "databaseName": "ctreeSQL",
        "ownerName": "admin",
        "skipRecords": 1,
        "maxRecords": 3,
        "includeSystemTables": false
      },
      "apiVersion": "1.0",
      "requestId": "4",
      "debug": "max",
      "authToken": "replaceWithAuthTokenFromCreateSession"
    },
    "serverSuppliedValues": {
      "databaseName": "ctreeSQL",
      "ownerName": "admin"
    },
    "errorData": {
      "errorData": null
    },
    "warnings": []
  },
  "errorCode": 0,
  "errorMessage": "",
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 
 

 

Request properties ("params")

Property Description Default Type Limits (inclusive)

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

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

skipRecords

 The "skipRecords" property specifies the number of records to skip over when paginating the results. It is used with "maxRecords" to paginate the results. If the value is not null or omitted, the server returns results from the beginning. If it is > 0, the server skips over the specified number of records and returns results starting from that point up until it returns the maximum number of results as defined by "maxRecords". Optional with default of 0 integer 0 to 9223372036854775807

maxRecords

 The "maxRecords" property specifies the maximum number of records to be returned. It is used with "skipRecords" to paginate the results. If the value is not null or omitted, the server returns the maximum number of results specified by "maxRecords". Optional with default of 20  integer -1 to 65535

includeSystemTables

The "includeSystemTables" property causes the server response to include system tables in the list of tables when set to true.

 

Example

"params": {
  "includeSystemTables": true
}
 Optional with default of false Boolean

true

false

 

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

.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

.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

.path

 The "path" property identifies the path of the database folder. For more details, see "path". string 0 to 2,048 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

Was this article helpful?

Give feedback about this article

Related Articles