102 lines
5.1 KiB
Protocol Buffer
102 lines
5.1 KiB
Protocol Buffer
// common/proto/table_script.proto
|
|
syntax = "proto3";
|
|
package komp_ac.table_script;
|
|
|
|
// Manages column-computation scripts for user-defined tables.
|
|
// Each script belongs to a single table (table_definition_id) and populates
|
|
// exactly one target column in that table. The server:
|
|
// - Validates script syntax (non-empty, balanced parentheses, starts with '(')
|
|
// - Validates the target column (exists, not a system column, allowed type)
|
|
// - Validates column/type usage inside math expressions
|
|
// - Validates referenced tables/columns against the schema
|
|
// - Enforces link constraints for structured access (see notes below)
|
|
// - Analyzes dependencies and prevents cycles across the schema
|
|
// - Transforms the script to decimal-safe math (steel_decimal)
|
|
// - Upserts into table_scripts and records dependencies in script_dependencies
|
|
// The whole operation is transactional.
|
|
service TableScript {
|
|
// Create or update a script for a specific table and target column.
|
|
//
|
|
// Behavior:
|
|
// - Fetches the table by table_definition_id (must exist)
|
|
// - Validates "script" (syntax), "target_column" (exists and type rules),
|
|
// and all referenced tables/columns (must exist in same schema)
|
|
// - Validates math operations: prohibits using certain data types in math
|
|
// - Enforces link constraints for structured table access:
|
|
// • Allowed always: self-references (same table)
|
|
// • Structured access via steel_get_column / steel_get_column_with_index
|
|
// requires an explicit link in table_definition_links
|
|
// • Raw SQL access via steel_query_sql is permitted (still validated)
|
|
// - Detects and rejects circular dependencies across all scripts in the schema
|
|
// (self-references are allowed and not treated as cycles)
|
|
// - Transforms the script to decimal-safe operations (steel_decimal)
|
|
// - UPSERTS into table_scripts on (table_definitions_id, target_column)
|
|
// and saves a normalized dependency list into script_dependencies
|
|
rpc PostTableScript(PostTableScriptRequest) returns (TableScriptResponse);
|
|
}
|
|
|
|
// Request to create or update a script bound to a specific table and column.
|
|
message PostTableScriptRequest {
|
|
// Required. The metadata ID from table_definitions.id that identifies the
|
|
// table this script belongs to. The table must exist; its schema determines
|
|
// where referenced tables/columns are validated and where dependencies are stored.
|
|
int64 table_definition_id = 1;
|
|
|
|
// Required. The target column in the target table that this script computes.
|
|
// Must be an existing user-defined column in that table (not a system column).
|
|
// System columns are reserved: "id", "deleted", "created_at".
|
|
// The column's data type must NOT be one of the prohibited target types:
|
|
// BIGINT, DATE, TIMESTAMPTZ
|
|
// Note: BOOLEAN targets are allowed (values are converted to Steel #true/#false).
|
|
string target_column = 2;
|
|
|
|
// Required. The script in the Steel DSL (S-expression style).
|
|
// Syntax requirements:
|
|
// - Non-empty, must start with '('
|
|
// - Balanced parentheses
|
|
//
|
|
// Referencing data:
|
|
// - Structured table/column access (enforces link constraints):
|
|
// (steel_get_column "table_name" "column_name")
|
|
// (steel_get_column_with_index "table_name" index "column_name")
|
|
// • index must be a non-negative integer literal
|
|
// • self-references are allowed without links
|
|
// • other tables require an explicit link from the source table
|
|
// (table_definition_links) or the request fails
|
|
// - Raw SQL access (no link required, but still validated):
|
|
// (steel_query_sql "SELECT ...")
|
|
// • Basic checks disallow operations that imply prohibited types,
|
|
// e.g., EXTRACT(…), DATE_PART(…), ::DATE, ::TIMESTAMPTZ, ::BIGINT, CAST(…)
|
|
// - Self variable access in transformed scripts:
|
|
// (get-var "column_name") is treated as referencing the current table
|
|
//
|
|
// Math operations:
|
|
// - The script is transformed by steel_decimal; supported math forms include:
|
|
// +, -, *, /, ^, **, pow, sqrt, >, <, =, >=, <=, min, max, abs, round,
|
|
// ln, log, log10, exp, sin, cos, tan
|
|
// - Columns of the following types CANNOT be used inside math expressions:
|
|
// BIGINT, TEXT, BOOLEAN, DATE, TIMESTAMPTZ
|
|
//
|
|
// Dependency tracking and cycles:
|
|
// - Dependencies are extracted from steel_get_column(_with_index), get-var,
|
|
// and steel_query_sql and stored in script_dependencies with context
|
|
// - Cycles across tables are rejected (self-dependency is allowed)
|
|
string script = 3;
|
|
|
|
// Optional. Free-text description stored alongside the script (no functional effect).
|
|
string description = 4;
|
|
}
|
|
|
|
// Response after creating or updating a script.
|
|
message TableScriptResponse {
|
|
// The ID of the script record in table_scripts (new or existing on upsert).
|
|
int64 id = 1;
|
|
|
|
// Human-readable warnings concatenated into a single string. Possible messages:
|
|
// - Warning if the script references itself (may affect first population)
|
|
// - Count of raw SQL queries present
|
|
// - Info about number of structured linked-table accesses
|
|
// - Warning if many dependencies may affect performance
|
|
string warnings = 2;
|
|
}
|