Data Tables and Views

Data Tables and Views let you store, query, and manage structured data directly on the platform—without relying on external databases. Use Data Tables to persist custom data for your AI Agents and apps, and Table Views to create virtual datasets by joining one or more tables.

The platform offers two capabilities:

• Data Definition: Create tables and views, control access, and define apps for secure API access.
• Data Manipulation: Perform CRUD operations on tables and views using Service Nodes or public APIs.

---

Data Tables

A Data Table stores structured data in rows and columns. Tables can be shared with AI Agents, apps, and process assistants.

Create a Data Table

1. Go to Data > Data Tables and select Create Data Table.

   

   Alternatively, select New Table.

   

2. Enter the following details and select Create.

   

Field	Description
Name	Name for the data table
Description	Purpose of the table
Columns	Columns to include
Indexes	Indexes for faster search
Bot Assignments	AI Agents that can access this table
App Assignments	Apps that can access this table
Process Assignments	Process apps that can access this table

---

Columns

Define the columns for your table.

Field	Description
Name	Column name (see Reserved Words)
Type	Data type: string, date, or number
Required	Marks the column as mandatory
Encrypted	Secures the data in this column
Reference Column	Foreign key constraint linking to another table’s column
Max Length	Maximum character length for the column value
Default Value	Value used when none is provided

The platform automatically adds these system columns to every table:

Column	Description
sys_Id	Unique identifier for each row
Created_On	Timestamp when the row was created
Updated_On	Timestamp when the row was last updated
Created_By	User ID of the creator
Updated_By	User ID of the last editor

---

Indexes

Add indexes to improve search and retrieval performance.

Field	Description
Index Name	Label for the index
Is Unique	Enforces unique values in the index
Column & Sort Order	Columns in the index and their sort direction (ascending or descending)

---

Assignments

Control which apps, AI Agents, and process apps can access the table.

• AI Agent assignments: Grant Read, Write, and Delete permissions. Assigned AI Agents can access table data through Service Nodes in Dialog Tasks.
• App assignments: Grant Read, Write, and Delete permissions. Only assigned apps can use the CRUD APIs for this table.
• Process app assignments: Grant Read, Write, and Delete permissions to process apps.

---

Import and Export

Export and import Data Table definitions as JSON files to transfer them between environments.

Export a Data Table:

1. Hover over the table and select the ellipsis (…) icon.

2. Select Export Definition.

3. A JSON file is generated and downloaded.

   

Import a Data Table:

1. Select the down arrow next to New Table and choose Import Table Definition.

2. Enter a Table Name and select the JSON file.

3. Select Import.

   

Sample JSON definition:

{
  "name": "customertable",
  "description": "Table containing customer details",
  "indexes": [],
  "schemaDef": [
    {"name": "CustEmail", "type": "string", "isRequired": false, "isEncrypted": false, "reference": {}, "maxLength": "", "default": ""},
    {"name": "CustType", "type": "string", "isRequired": false, "isEncrypted": false, "reference": {}, "maxLength": "", "default": "Preferred"},
    {"name": "CustName", "type": "string", "isRequired": true, "isEncrypted": false, "reference": {}, "maxLength": "", "default": ""},
    {"name": "CustId", "type": "number", "isRequired": true, "isEncrypted": true, "reference": {}, "maxLength": "5", "default": ""}
  ]
}

---

Change Table Owner

The table owner or an account administrator can transfer ownership to another user. When ownership changes, all related tables and views are also transferred, and all app assignments for those tables are lost.

1. Hover over the table and select the ellipsis (…) icon.

2. Select Change Owner.

   

3. Select the new owner and select Proceed.

   

4. A confirmation message appears. Review any related tables and views that are also affected.

Ownership cascade example:

Scenario	What transfers
Change owner on Table A (used in View 1 with Table B, and View 2 with Table C; Table F references Table A)	Table B, Table C, Table F, View 1, View 2
Change owner on Table F (references Table A)	Table A, Table B, Table C, View 1, View 2

---

Share Data Tables

Assign a Data Table to AI Agents, process apps, or apps to share it. Users with shared access can view the table definition but cannot edit or update it.

In the Shared Tables tab, you see only the tables shared with users who have view permission.

Developers can view shared table definitions through a Service Node using the Get Data action to access metadata, or Add Data and Update Data actions to see column names.

---

Table Views

A Table View creates a virtual dataset by querying one or more Data Tables. It supports filters, grouping, sorting, and joins.

Create a Table View

1. Go to Data > Table Views and select Create Table View or New View.

   

2. Enter the view details:

   • Name — Name for the table view.
   • Description — Up to 100 characters.
   • Assignment — Bots and apps that can access this view.
   

3. Choose Single Table or Multiple Tables.

   

4. Configure the view definition:

   

Setting	Description
Table	Select the source table(s)
Columns	Select columns to include; supports aggregation functions (sum, avg, min, max, count) — for example, count(<table_name>.<column_name>)
Filter Criteria	Filter results using column name, comparison operator (=, !=, <, >), and value; multiple criteria connected by AND/OR
Group By	Group identical data using <table_name>.<column_name>
Sort By	Order results using <table_name>.<column_name> asc/desc

5. For Multiple Tables, also configure join rules:

   

Join Setting	Description
Table	Table to join
Join Type	Inner, Right Outer, or Left Outer
Join Columns	Columns used for the join
Join Criteria	Operator: =, !=, >, or <

You can add up to 4 join rules per view.

---

Import and Export

Export and import Table View definitions as JSON files.

Export a Table View:

1. Hover over the table view and select the ellipsis (…) icon.

2. Select Export View.

   

3. Select Confirm on the dialog. A JSON file is downloaded.

   

Import a Table View:

1. Select the down arrow next to New View and choose Import View.

   

2. Enter a View Name and select the JSON file.

3. Select Import.

   

4. In the import dialog, select the table view and the columns to map.

---

Change View Owner

The view owner or an account administrator can transfer ownership to another user.

1. Hover over the table view and select the ellipsis (…) icon.

2. Select Change Owner.

   

3. Select the new owner and select Proceed.

   

4. A confirmation message appears. Review any related views that are also affected.

---

Share Table Views

Assign a Table View to bots, process apps, or apps to share it. Users with shared access can view the view definition but cannot edit or update it.

In the Shared Views tab, you see only the views shared with users who have view permission.

Developers can access shared view definitions through a Service Node.

---

App Definition

Create an app to securely access Data Tables and Table Views through public APIs. Apps are used for:

• Querying data tables and views via API.
• Importing and exporting table and view definitions.

To create an app:

1. Enter an App Name.

2. Optionally enforce JTI/JWE as required by your security policy.

   

---

Data as a Service

Use a Service Node in a Dialog Task to read and write data in tables and views from within your AI Agent.

Service Call — Table

Configure a Service Node to perform CRUD operations on a Data Table.

Steps:

1. Open the app and the Dialog Task where you want to access data.

2. Add a Service Node at the appropriate point in the flow.

3. In the Component Properties, configure General Settings:

   

   Field	Value
   Service Type	Data Service
   Type	Table

4. Select Define Request and configure the request:

   
   • Choose a Data Table — Select from the tables assigned to this app.
   • Action — Select the operation: Add Data, Get Data, Update Data, or Delete Data.

5. Select Test to validate (note: context references will not resolve until runtime).

6. Select Save.

Access the returned data using: {{context.<service_node_name>.response.body.queryResult[<index>].<column_name>}}

---

Add Data

Provide a value for each column. Values can be static or reference a context object, for example {{context.entities.<entity-name>}}.

Sample response:

{
  "CustId": 1,
  "Type": "Preferred",
  "Address": "New York",
  "CustomerName": "John Smith",
  "sys_Id": "sys-5c46e351-ee51-5c27-80cf-c6c1e8f8f066"
}

---

Get Data

Filter and fetch rows from the table.

Setting	Description
Filter Criteria	Column name, operator, and value (supports AND/OR); omit to return all rows
Limit	Maximum records to return (default: 10)
Offset	Number of records to skip from the result

Sample response:

{
  "hasMore": true,
  "total": 4,
  "queryResult": [
    {"CustId": 1, "CustomerName": "John Smith", "Address": "New York"},
    {"CustId": 2, "CustomerName": "Jane Doe", "Address": "Chicago"}
  ]
}

---

Update Data

Modify existing rows by specifying column values and filter criteria.

• Check a column to update its value. If you check a column and leave the value blank, that column is set to empty.
• Unchecked columns retain their original values.
• Use filter criteria to target specific rows.

Sample response:

{"records": []}

---

Delete Data

Delete rows by specifying filter criteria (column name, operator, and value). Multiple criteria can be connected with AND/OR.

Sample response:

{"nDeleted": 1}

---

Service Call — View

Configure a Service Node to query data from a Table View.

Steps:

1. Open the app and the Dialog Task.

2. Add a Service Node and configure General Settings:

   Field	Value
   Service Type	Data Service
   Type	View

3. Select Define Request and configure:

   • Choose a Table View — Select from views assigned to this app.
   • Filter Criteria — Column, operator, and value (supports AND/OR); omit to return all rows.
   • Limit — Maximum records to return.
   • Offset — Records to skip.

4. Select Test, then Save.

Access returned data using: {{context.<service_node_name>.response.body.queryResult[<index>].<column_name>}}

Sample response:

{
  "hasMore": true,
  "total": 4,
  "queryResult": [
    {"type": "Gold", "address": "New York"},
    {"type": "Gold", "address": "Chicago"}
  ]
}

---

Admin Console Management

As an administrator, you can view all Data Tables and Table Views in your workspace and change their ownership.

Manage Data Tables

1. Log in to the Admin Console.

2. Navigate to Data Tables & View > Data Tables.

   

3. View all tables you own and shared tables in the workspace.

4. To change ownership, select the ellipsis (…) icon next to a table and choose Change Owner.

   

5. Select the new owner and select Proceed.

   

6. All related tables and views are transferred to the new owner. All app assignments for the table are lost.

---

Manage Table Views

1. Log in to the Admin Console.

2. Navigate to Data Tables & View > Table Views.

   

3. View all table views you own and shared views in the workspace.

4. To change ownership, select the ellipsis (…) icon next to a view and choose Change Owner.

   

5. Select the new owner and select Proceed.

   

6. All related views are transferred to the new owner. All app assignments for the view are lost.

---

Guidelines and Best Practices

Data Tables are designed for low-volume, conversation-relevant data. They are not a general-purpose database.

Recommended Limits

Scope	Limit
Rows per table	10,000
Columns per table	20
Row size	100 KB
Table size	100 MB
Total data per workspace	500 MB

Best Practices

• Store only data that directly supports AI Agent conversations — user preferences, lookup tables, conversation context.
• Use clear, consistent naming conventions for tables and columns.
• Do not store JSON objects in Data Tables.
• Regularly remove outdated or unnecessary rows.
• Avoid bulk operations; they can impact AI Agent performance.
• Ensure data type mappings are accurate for all columns.
• Back up important data regularly.

When to Use Alternatives

For large datasets or complex operations, use:

• Relational databases
• NoSQL databases
• Data warehouses
• Cloud storage solutions

Compliance

The platform monitors Data Table usage. Misuse may result in restricted or revoked access to this feature.

---

Data Manipulation APIs

Use these APIs to read and write data programmatically:

API	Purpose
Data Insert API	Insert rows into a table
Data Update API	Update existing rows
Data Delete API	Delete rows
Query Table Data API	Retrieve data from a table
Query View Data API	Retrieve data from a view

---

Reference

Glossary

Term	Definition
Data Definition	Defining how data is stored — tables, columns, views, and access rules
Data Manipulation	CRUD operations (Create, Read, Update, Delete) on data
Data Table	Storage structure for tabular data with named rows and columns
Column	An individual field in a table
Reference Column	A foreign key constraint that links a column’s values to another table’s column
Index	A pointer to table data used to speed up retrieval
Table View	A virtual table created from one or more Data Tables using joins and filters
Filter Criteria	Conditions that determine which rows appear in a view
Group By	Groups identical data together in a view result
Sort By	Orders rows in a view result by specified columns
Join	Combines data from two or more tables into a single result set
Inner Join	Returns only matched rows from both tables
Right Outer Join	Returns matched rows plus all unmatched rows from the right table (with nulls for the left)
Left Outer Join	Returns matched rows plus all unmatched rows from the left table (with nulls for the right)

---

Reserved Words

These words cannot be used as column names:

ACCESS, ADD, ALL, ALTER, AND, ANY, AS, ASC, AUDIT, BETWEEN, BY, CHAR, CHECK, CLUSTER, COLUMN, COMMENT, COMPRESS, CONNECT, CREATE, CURRENT, DATE, DECIMAL, DEFAULT, DELETE, DESC, DISTINCT, DROP, ELSE, EXCLUSIVE, EXISTS, FILE, FLOAT, FOR, FROM, GRANT, GROUP, HAVING, IDENTIFIED, IMMEDIATE, IN, INCREMENT, INDEX, INITIAL, INSERT, INTEGER, INTERSECT, INTO, IS, LEVEL, LIKE, LOCK, LONG, MAXEXTENTS, MINUS, MLSLABEL, MODE, MODIFY, NOAUDIT, NOCOMPRESS, NOT, NOWAIT, NULL, NUMBER, OF, ON, ONLINE, OFFLINE, OPTION, ORDER, PCTFREE, PRIOR, PRIVILEGES, PUBLIC, RAW, RENAME, RESOURCE, REVOKE, ROW, ROWID, ROWNUM, ROWS, SELECT, SESSION, SET, SHARE, SIZE, SMALLINT, START, SUCCESSFUL, SYNONYM, SYSDATE, TABLE, THEN, TO, TRIGGER, UID, UNION, UNIQUE, UPDATE, USER, VALIDATE, VALUES, VARCHAR, VARCHAR2, VIEW, WHENEVER, WHERE, WITH

---