Tables Data Model

Reference for Tables entities, resolver strings, dependencies, cells, and score configuration.

Use this page when you copy, transform, or automate Tables programmatically. It describes the shapes agents and API clients rely on when reading or writing sheet data.

The REST API uses the smart-tables tag and lowercase column type values such as text and prompt_template. The PromptLayer MCP server uses uppercase backend enum values such as TEXT and PROMPT_TEMPLATE for the same column types. See Column Types for the full UI and backend type catalog.

Entity hierarchy

A Table is the top-level workspace. Each Table contains one or more sheets. Each sheet has columns, rows, and cells at every row-column intersection.

Entity	ID format	Key fields
Table	UUID	title, workspace_id, folder_id
Sheet	UUID	table_id, title, index, row_count, version_count
Column	UUID	sheet_id, title, type, config, position_rank, is_output_column
Cell	UUID or virtual ID	sheet_id, column_id, row_index, status, value, display_value, last_computed_version

version_count on a sheet increments when sheet data, layout, score configuration, imports, or execution output changes. Many mutation endpoints return version, the current version_count after the change.

Column types

Kind	API type	Behavior
Input	text	Stores editable row data. Cells are written directly and do not run computation.
Computed	prompt_template, llm, code, score, comparison, composition, and other non-text backend types	Runs per-row work from config and declared dependencies. Cells track execution status and can become stale when upstream values change.

Text columns are the only columns whose cells you can edit with Update Cell. Computed cells are produced by recalculation operations.

Resolver format

Column configurations reference source columns with a resolver string:

{table_id}.{sheet_id}.{column_id}

Each segment is a UUID. The three-part form uniquely identifies a column, including columns in other sheets or tables (for example, composition columns).

Resolver strings appear in column config fields that wire inputs to sources:

Config field	Use
source	Single source column for checks, extraction, assertions, and similar column types.
sources	Multiple source columns, such as comparison inputs or helper transforms.
prompt_template_variable_mappings	Maps a prompt template input variable to a source column.
variable_mappings	Maps template variables in assertions, loops, or other configurable text to source columns.
Other *_variable_mappings fields	Same mapping pattern for type-specific configuration keys.

Examples

Map a prompt variable to an input text column in the same sheet:

{
  "prompt_template_variable_mappings": {
    "question": "a1b2c3d4-e5f6-7890-abcd-ef1234567890.b2c3d4e5-f6a7-8901-bcde-f12345678901.c3d4e5f6-a7b8-9012-cdef-123456789012"
  }
}

Point a composition column at a column in another sheet:

{
  "source": "d4e5f6a7-b8c9-0123-def0-234567890123.e5f6a7b8-c9d0-1234-ef01-345678901234.f6a7b8c9-d0e1-2345-f012-456789012345"
}

Map assertion variables to prior computed columns:

{
  "variable_mappings": {
    "response": "a1b2c3d4-e5f6-7890-abcd-ef1234567890.b2c3d4e5-f6a7-8901-bcde-f12345678901.d4e5f6a7-b8c9-0123-def0-234567890123",
    "expected": "a1b2c3d4-e5f6-7890-abcd-ef1234567890.b2c3d4e5-f6a7-8901-bcde-f12345678901.e5f6a7b8-c9d0-1234-ef01-345678901234"
  }
}

When all referenced columns live in the current sheet, you can often omit table_id and sheet_id in UI-driven workflows. For API and MCP automation—especially when copying tables or referencing other sheets—use the full three-part resolver.

Dependency graph

Computed columns form a directed acyclic graph (DAG). Declare edges with the dependencies array on Create Column and Update Column. PromptLayer rejects cycles with a 400 response.

Each dependency object describes how a source column feeds the computed column:

Field	Required	Description
column_id	Yes	UUID of the source column.
reference_type	No	How the dependency is consumed. Defaults to value (the cell output).
config_key	No	Config field this dependency feeds, such as a variable name or source key.
config_meta	No	Extra metadata for the mapping. Shape depends on the column type.
source_resolver	No	Full {table_id}.{sheet_id}.{column_id} string for the source. Present on read payloads and useful when copying column definitions between sheets.
source_label	No	Human-readable label for the source column, such as the column title. Present on read payloads.

Write example

{
  "title": "Quality check",
  "type": "prompt_template",
  "config": {
    "template": { "name": "qa_grader" },
    "prompt_template_variable_mappings": {
      "answer": "a1b2c3d4-e5f6-7890-abcd-ef1234567890.b2c3d4e5-f6a7-8901-bcde-f12345678901.c3d4e5f6-a7b8-9012-cdef-123456789012",
      "question": "a1b2c3d4-e5f6-7890-abcd-ef1234567890.b2c3d4e5-f6a7-8901-bcde-f12345678901.b2c3d4e5-f6a7-8901-bcde-f123456789012"
    }
  },
  "dependencies": [
    {
      "column_id": "b2c3d4e5-f6a7-8901-bcde-f123456789012",
      "reference_type": "value",
      "config_key": "question"
    },
    {
      "column_id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
      "reference_type": "value",
      "config_key": "answer"
    }
  ]
}

When a source cell value, resolver mapping, or upstream column config changes, dependent computed cells become STALE. See Cells and Runs for rerun scopes.

Cell shape

Each cell stores a structured value, an optional display_value string for the grid, and execution metadata for computed columns.

Read response fields

Field	Input (text) cell	Computed cell
id	Cell UUID	Cell UUID, or a virtual cell ID for not-yet-computed output cells
status	Usually COMPLETED	STALE, QUEUED, DISPATCHED, RUNNING, COMPLETED, or FAILED
value	Stored input (string, number, object, etc.)	Structured output from the column type
display_value	Rendered text shown in the grid	Rendered text shown in the grid
last_computed_version	null	Sheet version_count when the cell last completed computation; null until the first successful run
input_hash	null	Hash of inputs used for cache invalidation
execution_id	null	Execution ID for the current or most recent computed value
request_metrics	null	Price, latency, and token usage for prompt-template cells

Some internal responses use lowercase statuses (completed, stale, running, queued, error, cancelled). Public table endpoints return uppercase statuses in the TableCell schema.

Structured value shapes

The value field is type-specific:

• Text columns: Often a plain string or JSON-compatible scalar. Some clients wrap values as { "value": "..." }.
• Computed columns: Structured output from the column runner—plain text, JSON, booleans, numbers, or nested objects depending on the column type.

Check display_value for the grid-friendly rendering. Use value when you need the full structured result in code.

Write shapes

Update text cells with Update Cell:

{
  "display_value": "What is the refund policy?",
  "value": "What is the refund policy?"
}

Set initial text values when adding rows via Add Rows:

{
  "count": 1,
  "values": [
    {
      "b2c3d4e5-f6a7-8901-bcde-f123456789012": "What is the refund policy?"
    }
  ]
}

Each key in values is a column_id UUID. Do not write computed cells directly—queue recalculation instead.

Distinguish input vs computed cells

Signal	Input cell	Computed cell
Parent column type	text	Any non-text type
last_computed_version	null	Set after a successful run
status	COMPLETED after write	Tracks queue, run, completion, failure, or staleness
Writable via PATCH	Yes	No—recalculate instead

Score configuration

Sheet scoring is configured per sheet and returned on Get Score and Configure Score.

Configure request

Field	Description
score_type	auto, boolean, numeric, or custom. Required when you pass score_config.
score_config	Explicit scoring configuration object. Shape depends on score_type.
column_ids	Column UUIDs to include in scoring.
column_names	Column titles to include. Titles must be unique in the sheet.
code / code_language	Custom scorer source (PYTHON or JAVASCRIPT) for custom mode.
true_values / false_values	Token lists for boolean scoring.
assertion_aggregation	all, any, or mean for assertion-style boolean scoring.

Score configuration object

Stored and returned as:

{
  "score_type": "boolean",
  "score_config": {
    "column_ids": ["c3d4e5f6-a7b8-9012-cdef-123456789012"],
    "true_values": ["pass", "true", "yes"],
    "false_values": ["fail", "false", "no"],
    "assertion_aggregation": "mean"
  }
}

Custom scorers must return a deterministic object with a numeric score key. Optional keys include sub_scores and score_matrix. See Scoring for UI modes and examples.

Score response highlights

Get Score returns aggregate results plus per-column breakdowns:

Field	Description
scoring_type / score_type	Active scoring mode
score_configuration	Current score_type and score_config
aggregate_score / overall_score	Sheet-level score
columns	Per-column scores with included_count and excluded_count
score_matrix	Optional matrix display for custom scoring
status	queued, running, completed, or failed while recalculating

Changing score configuration creates a new sheet version and sets requires_recalculation: true. Call Recalculate Score to queue calculation.

Related

• Tables overview
• Columns
• Cells and Runs
• Scoring
• Migrate from Evaluations and Datasets
• Tables REST API
• PromptLayer MCP — Smart Tables tools