queryEntityDefs() — Schema Manager

General Description

The queryEntityDefs operation retrieves a paginated list of entity definitions.

Detailed Description

This operation allows you to fetch multiple entity definitions with pagination support. It's useful for discovering available entity types, building data dictionaries, or creating administrative interfaces that manage entity definitions. The results are paginated to handle large numbers of entity definitions efficiently.

Input Parameters

Parameter	Type	Required	Description
searchTerm	string	Yes	Case-insensitive term matched against definition name, title, and description. Pass an empty string to list everything.
page	number	Yes	Page number, 1-based. Values of zero or less are coerced to 1.
pageSize	number	Yes	Number of items per page. Values of zero or less are coerced to 10.
includeSystem	boolean	No	Whether to include system entity definitions. Default is false.
token	string	No	Authentication token for your request. If not provided, the system will use the default API key from environment variables.
tenantCode	string	No	Tenant code to specify which tenant's data to access. If not provided, the system will extract it from the token or use the default tenant code from environment variables.

Response

Success Response

{
    "success": true,
    "entityDefs": [
        {
            "id": "string",
            "name": "string",
            "title": "string",
            "description": "string",
            "dbTableName": "string",
            "properties": []
        }
    ],
    "totalCount": 0
}

totalCount is the number of definitions matching searchTerm, not the length of entityDefs. Divide it by pageSize to get the page count.

Error Response

{
    "success": false,
    "message": "Error message describing what went wrong"
}

Condition	message
Token missing, expired, or issued for another tenant	Authentication error text from the backend
Caller lacks read permission on entity definitions	Authorization error text from the backend
page or pageSize is not a number	Type error raised before the request is sent
Network or transport failure	The underlying transport error message

The operation does not throw across the tool boundary; every failure is returned in this shape.

Example Usage

Get First Page of Entity Definitions

const result = await queryEntityDefs({
  searchTerm: "",
  page: 1,
  pageSize: 10,
  token: "your-auth-token"
});

if (result.success) {
  console.log(`Found ${result.totalCount} definitions, showing ${result.entityDefs.length}`);
  for (const def of result.entityDefs) {
    console.log(`- ${def.title ?? def.name} (${def.name})`);
  }
} else {
  console.error("Error:", result.message);
}

List the next page from the CLI

gsb call queryEntityDefs --raw --input '{
  "searchTerm": "order",
  "page": 2,
  "pageSize": 25,
  "includeSystem": false
}'

Additional Information

• Pagination is 1-based. Page 1 is the first page; page: 0 is silently treated as page 1.
• When definition caching is enabled the search runs locally against the cached definitions, so results are filtered on name, title, and description only.
• Cached results are projected to name, title, description, dbTableName, id, and properties. Use getEntityDef for the complete definition.
• System definitions are excluded unless includeSystem is true.
• Access permissions are enforced from the token; callers only see definitions they may read.
• For creating or modifying definitions, use createEntityDef and updateEntityDef.